Litho Doc

Litho Document 技能（纯 代理 版）

本 技能 是 Litho（deepwiki-rs）的纯 代理 平行实现。不依赖任何外部二进制，完全通过 代理 的工具调用能力自主完成四阶段文档生成流水线。

目标产出：

1.概述.md — C4 上下文 图 + 项目概述 + 业务价值 2.架构.md — C4 ContAIner/组件 图 + 架构模式 + 模块职责 3.工作流.md — 时序图 + 流程图 + 并发模型 + 错误处理 4.Deep-Exploration/ — 每个领域模块的深度研究文档 5.边界接口.md — 命令行工具/API/配置等对外接口清单 6.数据库概览.md — ER 图 + 表结构（条件触发） 四阶段流水线总览 预处理 → 研究 → 编排 → 输出 ↓ ↓ ↓ ↓ 结构洞察 C1-C4 Markdown 文件持久化

每个阶段的详细执行指南在 references/ 中，代理 按需加载。下面只给出决策级指导。

阶段一：预处理 → 了解项目

决策要点：

根据项目规模选择扫描策略（见下方快速路径） 建立预处理报告：项目名、语言、框架、核心模块列表、README摘要 预处理报告是后续所有阶段的基础上下文，务必准确

快速路径（按项目规模）：

规模 判断标准 扫描策略 小 <100 源文件 列出_files 递归 + read_file 全部核心文件 中 100-500 源文件 列出_files 仅一级目录 + read_file 入口+配置+README + codebase_搜索 语义搜索 大 >500 源文件 仅读 README + 主配置 + 入口文件 + view_file_outline 核心模块 + grep_搜索 精确搜索

详细步骤见 references/phase1-preprocessing.md

阶段二：研究 → C4 多层级分析

决策要点：

执行顺序：C1 → C2 → [C3 并行]（与 deepwiki-rs 一致） 领域模块必须全覆盖：src/ 下每个子目录都识别为候选模块，用 DDD 分组（核心域/支撑域/通用域），不得遗漏 渐进式深度控制：按 导入ance 评分分级分析 研究产出写入 .litho-代理/ 临时目录持久化（见下方中间产物策略）

并发搜索：Step 2.3(架构) + 2.4(工作流) + 2.6(边界) 的搜索可并发调用，Step 2.5(模块深度) 必须在 2.2(领域模块) 之后

渐进式深度：

导入ance 分析深度 读取文件数 MermAId 图 ≥7（核心域） 深度分析 5+ 完整 flow图表 + 交互表格 4-6（支撑域） 标准分析 3 精简流程图 ≤3（通用域） 简要描述 1-2 无图

详细步骤见 references/phase2-re搜索.md

阶段三：编排 → 生成 Markdown 文档

决策要点：

生成顺序：边界接口 → 概述 → 模块深度(逐个) → 架构 → 工作流 → 数据库（依赖少的先写入） 分章节写入大型文档：架构和工作流分 2-3 次写入（框架 → 补充章节） 逐模块独立写入：每个 Deep-Exploration 文档独立 write_to_file，写完即释放上下文 代码引用密度：每模块 ≥3 文件路径、≥2 类型名、组件表每行有路径列

⚠️ 叙述性写作风格（P0 关键！）：

生成的文档必须面向人类阅读友好，而不是冷冰冰的 PPT 式结构化文字。核心要求：

每个章节开头必须有叙述性 summary：用 2-4 句话先解释"这个章节在说什么、为什么重要"，不要直接甩出表格或列表 表格和列表前后必须有解读段落：不要只给结构化数据，要解释"这意味着什么、为什么这样设计" 设计决策必须讲"为什么"：不只说"选了什么"，还要说"放弃了什么、为什么这样选" 用类比和比喻建立理解桥梁：比如把 Memory 比作"快递站"、把 代理 比作"工人"、把 流水线 比作"生产线" 避免冷冰冰的标题堆叠：章节标题应该自然引出叙述，而不是 ### 2.1 核心目标 → 直接跳到列表

详细写作风格指南和模板见 references/phase3-composition.md

阶段四：输出 → 验证与交付

决策要点：

MermAId 图表语法验证（节点 ID 仅字母数字、标签用双引号、换行用
） 每份文档末尾标注置信度评分（1-10） 生成执行摘要报告（文档清单、模块覆盖数、置信度表、需人工审查项）

数据库文档触发（满足任一即触发，否则写极简声明文件）：

.sql/.sqlproj 文件 | 迁移s//sql//db//database/ 目录 | ORM 依赖 | DB 配置文件

详细验证清单见 references/phase4-输出.md

⚠️ 中间产物持久化策略（核心！） 问题

代理 单次对话上下文窗口有限。随着分析深入，早期的研究结果可能因上下文压力被「遗忘」。

解决方案

每完成一个研究步骤，将关键发现持久化到 .litho-代理/ 临时目录，而非仅依赖对话上下文：

.litho-代理/ ├── preprocessing.md ← 预处理报告（阶段一产出） ├── c1-系统-上下文.md ← 系统上下文报告 ├── c2-domAIn-模块s.md ← 领域模块报告 ├── architecture.md ← 架构研究报告 ├── 工作流.md ← 工作流研究报告 ├── boundary.md ← 边界接口报告 ├── database.md ← 数据库报告（条件） └── 模块s/ ← 各模块深度报告 ├── llm.md ├── 缓存.md └── ...

操作方法：

每完成一个研究 Step → write_to_file 写入 .litho-代理/ 对应文件 编排阶段需要某报告 → read_file 从 .litho-代理/ 读取 最终输出完成后 → 删除 .litho-代理/ 临时目录（可选保留供复查）

关键优势：

上下文压力时可以释放早期研究数据，需要时再读取 研究结果不丢失，即使对话很长也能保证编排阶段的数据完整性 与 deepwiki-rs 的 Memory 作用域机制等效 工具使用优先级 codebase_搜索 — 语义搜索（找「做什么事」的代码） grep_搜索 — 精确搜索（找特定符号/类名/函数名） view_file_outline — 快速获取文件结构（不读全量） read_file — 深读关键文件（入口、核心模块） 列出_files — 扫描目录结构 参考文档（按需加载） references/phase1-preprocessing.md — 预处理详细步骤 + 搜索策略 references/phase2-re搜索.md — 研究各 代理 详细指南 + 输出格式 references/phase3-composition.md — 文档模板 + 分章节策略 + 代码引用规范 references/phase4-输出.md — MermAId 验证清单 + 置信度评分模板 references/doc-templates.md — MermAId 图表语法速查 + 类型选择指南