文档资产组织三部曲：归类、合并与索引

从散件到资产

业务需求生成跑完，doc/business/ 目录里躺着几十份文档，一页一份，文件名是页面名。这份家当离「资产」还差三步：没有模块结构，查一个功能要凭记忆猜文件；单页文档颗粒太碎，没人愿意通读；更重要的是没有对账——哪些模块有文档、哪些没有，没人说得清。

三个 skill 接力完成这个转变：业务模块归类（skill6，business-config）给每份文档找到模块归属；模块合并（skill7，module-merge）把同模块文档合并成带目录的模块清单；模块索引（skill4，module-index）生成全局索引并做完整性对账。执行顺序 skill6 -> skill7 -> skill4，每步读上一步的产物，也是整条流水线的收尾段。

三部曲的中枢是一份配置文件 doc/business/business.json：模块清单从它来，归类结果记回它，合并按它分组，索引对账也拿它当基准。一份文件贯穿三步，状态逐步丰满。

归类：读内容，不读文件名

归类的产物是每份文档旁边一个小小的 .模块.txt，三行内容：模块名、建议分类、分类理由。

规则的关键词是「内容分析而非文件名」。文件名说的是页面，内容说的才是业务：一份叫 pageList 的文档，打开看全是发票查验、认证、抵扣，就该归进税务管理模块，而不是按字面归到什么列表页。分类理由强制写出来，是给人工复核留的依据——理由讲不通的分类，一眼就能推翻。

模块清单本身从哪来，分两条路。项目用 RuoYi 这类带基础底座的框架时，输入框架表数量上限，按表名前缀批量生成模块骨架：sys_ 开头进系统管理，gen_ 进代码生成，qrtz_ 进定时任务，剩下的按业务表前缀归业务模块，一键完成。框架自带的模块没必要人工起名，前缀就是现成的语义。没有框架底座的项目走手动输入，逐个登记模块名和说明。

配置文件还有一个刻意的设计：只有用户明确同意，才把新出现的文档自动加进配置。归类 skill 发现新文件时先提示，等人确认。禁止静默修改配置——模块结构是三步共用的基准，基准悄悄变了，后面的对账就失去了参照。

状态跟踪：配置文件长出账本

归类完成后，business.json 里的每个模块多出一组状态字段：

这组字段让配置文件从静态清单变成了动态账本。合并 skill 每处理完一份文档就更新对应模块的已处理数，流水线中断后重启，从账本上直接读出断点在哪，已完成的模块不再重跑。整套「可断点续跑」机制，靠的就是这层状态设计，它在编排协议设计一篇里有完整展开。

合并：原文摘录原则

合并把同模块的多份文档拼成一份 {系统名称}-功能资产总清单.md。听起来是体力活，规则却最凶——核心原则四个字：原文摘录。禁止简化，禁止合并，禁止省略。

模板把层级映射规定死：原始文档的 ## 功能模块、### 功能、##### 详细说明，分别对应输出文档的 ### 功能节、功能点清单表、##### 详细说明节。每个功能点带固定三段式：输入参数表、输出结果、业务规则，外加一行「对应文档」链接指回原始文件。链接不是装饰，是溯源通道：合并文档里的任何内容存疑，一键跳回单页原文对质。

禁止出现的内容被列成了表：

这四条禁令针对的全是大模型在长文档任务里的本能倾向：写到后面开始偷懒概括。原文摘录原则的立场是，合并这一步不创造任何新信息，只做搬运和组织——理解性的工作已经在上游做完，搬运也不许夹带私货。

无内容的功能点也有规矩：输入参数表写「无」，不许省略整个小节。省略和「没有」在下游是两回事，前者丢失信息，后者是明确的陈述。

人机分工：LLM 表达，脚本判定

合并是流水线里人机分工最清晰的一步：LLM 负责按模板生成，验证脚本 merge_verify.py 负责判定质量，LLM 必须调用脚本，不许自评通过。

脚本解析原始文档和输出文档的结构，按三个数字判定：

判定标准能写成脚本，靠的是结构性锚点：数标题就是数功能点，查表格存在性就是查参数完整性（这套「质量指标可量化」的方法论见输出质量控制）。数字定成三档也有讲究：输入参数表是字段级事实，错一个就丢一个，必须 100%；功能点和业务规则允许小幅损耗，90% 的线内可以放行，警报照样记录。

flowchart TD
    A[按 business.json 分组] --> B[LLM 按模板生成合并文档]
    B --> C[调用 merge_verify.py]
    C -->|质量验证通过| D[临时文件移入最终位置]
    C -->|门禁未通过| E[重新生成或修正]
    E -->|不超过 3 次| B
    E -->|3 次仍失败| F[标记需人工审核 继续其他文档]
    D --> G[更新 business.json 状态字段]

质量通过后临时文件才移到最终位置，这个顺序保证目录里出现的永远是过检文档，失败的中间产物不污染正式位置。

失败处理与超长输入

重试上限 3 次，3 次不过标记「需人工审核」，继续处理其他文档。单点失败不阻塞整批，最后人工只处理带标记的少数模块，这是全流水线统一的降级策略。

超长模块是合并特有的难题：单模块文档加起来超过十万字，一次性读入必被截断。技能文档给的执行方案是全程分批：分批 Read，每次三百行左右；临时文件记录处理进度；分批写入目标文档；写入被截断时用局部编辑补齐，补完复查节号连续性——功能点应从 1.1 顺排到 1.N，跳号即截断铁证。一套组合拳下来，十万字模块也能稳定走完。

索引：A/B/C 对账法

最后一步生成全局索引 00_索引.md，方法是从两个方向数同一批东西。

方向一：读合并文档，提取模块清单和每个模块的功能清单。方向二：读 business.json，拿到规划中的全部模块定义。两个方向交叉对账，每个模块落进三类之一：A 类，有模块定义也有业务文档，正常；B 类，有文档但没有模块定义，说明出现了规划外的功能，是需求侧的意外收获；C 类，有模块定义但没有业务文档，说明这个模块在系统里存在却没人逆向过，是覆盖的缺口。

索引文档里因此有四张表：统计总表、A 类正常清单、B 类规划外发现、C 类缺口清单。分类标注在合并文档里就已埋下——模板规定 B 类功能带「来自 doc/business/，模块.txt 未列出」的加粗标注，C 类带「模块.txt 定义，暂无业务文档」的警示标注，索引只是把散在各模块的标记汇成全局视图。

这套对账最有价值的地方在 C 类清单。它回答了一个之前没人能回答的问题：逆向工程的覆盖完整吗？没有索引对账，缺一个模块没人知道；有了对账，缺口自动浮出水面，补不补、什么时候补，成了显式的管理决策。

合并即审计

回头看三部曲，它名义上做的是文档整理，实际完成的是一次需求完整性审计：归类发现了散文档的模块归属，合并验证了搬运过程零损耗，索引对出了规划与实现的差集。文档工程和质量审计在这里合成了同一件事。

这也是文档资产化的最后一步。到索引生成为止，代码库的全部业务语义被组织成五层可下钻结构：索引 -> 模块清单 -> 功能清单 -> 功能点详情 -> 原始文档链接。新人从索引进入，五次点击内能到达任何一个功能的字段级描述。

文档资产齐了，还剩数据库那半边：数据库数据字典：DDL 解析与业务语境反哺——表结构早就有了，业务含义从哪来。