知识图谱批量生成器
📌 版本历史
| 版本 | 日期 | 变更内容 |
|---|---|---|
| 2.2.0 | 2026-09-02 | 沉淀大规模项目全量升级实战：① 骨架卡升级策略——用户反馈"待补充太多/规则过简"时触发全量升级，按领域并行派子代理 + 主代理监控产出（grep 剩余待补充数），代理停滞即接管补齐；② mermaid 节点 label 禁嵌套圆括号（渲染失败头号原因）与批量正则修复脚本；③ 子代理跨模块相对路径易错（../.. 层级），终检必须跑双链校验；④ 更新升级后的统计回写与 README |
| 2.1.0 | 2026-09-01 | 修复 Obsidian wiki 链接路径规范（重要）：Obsidian 的 [[...]] wiki 链接不支持 ../ 相对路径（../ 会被当作笔记名导致无法点击），全部改为从知识库根出发的完整路径（[[领域/模块/功能.md|别名]]）；同步修正 templates.md 中的链接规范表与 mermaid 节点语法（mermaid 内禁止 [[...]]，用纯文本节点）；补充实战经验：L2 领域索引引用跨领域模块链接深度、子代理 429 限流降级、质检脚本跳过代码块、L3 功能数差异由第五批回写 |
| 2.0.0 | 2026-08-24 | 修复 Obsidian 双链兼容性：第五批质检新增"无点号语法 + 逐链接相对路径解析校验"，生成的知识库在 Obsidian 中可正常跳转 |
| 1.0.0 | 初始版本 | 5 批批量生成策略（L1+L2 骨架 → L3 模块索引 → 核心功能卡片 → 其余功能骨架 → 全局质检）基础能力 |
Overview
面向大规模项目的知识工程。当项目已有完整代码/文档、功能节点超过 50 个、需要一次性生成数百个节点的完整知识库时，按批次策略高效生成，避免单次输出过载。所有文件内容必须遵循 business-knowledge-graph-generator skill 中定义的模板规范（references/templates.md）。
何时使用
- 功能数量超过 50 个的大规模项目
- 已有完整的项目代码目录结构 + 核心代码文件内容（可分批提供）
- 需要一次性生成数百个节点的完整知识库
输入要求：提供完整的项目代码目录结构 + 核心代码文件内容（可分批提供）。
批量处理策略
当功能数量超过 50 个时，按以下顺序分 5 批处理：
第一批：L1 + L2 骨架（全局结构）—— 预计输出 6~20 个文件
- 生成
knowledge/_index.md（L1 全景图） - 为每个领域生成
<领域>/_index.md（L2 领域图） - 质量检查：确认所有领域和模块已覆盖，无遗漏
第二批：L3 模块索引（功能清单）—— 预计输出 20~50 个文件
- 为每个模块生成
<领域>/<模块>/_index.md（L3 模块图） - 质量检查：确认每个模块的功能清单完整，所有功能已命名
第三批：高优先级功能卡片（核心流程）—— 预计输出 20~30 个文件
- 识别系统的核心功能（用户最常用的 20% 功能，如登录、下单、支付）
- 为这些功能生成完整的 L4 卡片（含流程、规则、事件、依赖、代码位置）
- 质量检查：核心流程包含异常分支，代码位置精确到行号
第四批：其余功能骨架卡片 —— 预计输出 50~200+ 个文件
- 为剩余功能生成最小化卡片（至少包含 Frontmatter + 功能描述 + 基础规则）
- 标注
状态: 待补充，供后续人工完善 - 质量检查：所有功能都有对应的 .md 文件，无功能遗漏
第五批：全局质量检查与索引更新
- 验证所有双链均为 Obsidian 兼容相对路径（
[[../模块/功能.md|别名]]），无[[领域.模块.功能]]点号语法 - 遍历校验：每个链接相对当前文件解析后，目标 .md 文件必须存在
- 标注所有悬空链接，生成待修复清单
- 更新各层级
_index.md中的统计数字（模块数量、功能数量） - 生成
knowledge/README.md使用说明
优先级判定规则
| 优先级 | 判定标准 | 示例功能 |
|---|---|---|
| 核心 | 用户日常使用 > 80% 的场景、资金安全相关 | 登录、下单、支付、退款 |
| 重要 | 用户日常使用 30%~80% 的场景、数据管理相关 | 订单查询、物流追踪、修改信息 |
| 一般 | 管理后台功能、低频操作、配置类 | 商品分类管理、日志查询、报表生成 |
输出要求
- 按批次输出，每批完成后报告进度，并等待用户确认后再继续下一批
- 每批输出时，列出本批生成的文件清单
- 第三批（核心功能）生成完成后，暂停，等待用户指定下一批重点领域
- 所有文件内容必须遵循
business-knowledge-graph-generator中references/templates.md定义的模板规范
批次汇报格式
## 第 X 批完成 ✅
**生成文件数**：XX 个
**涉及领域**：领域A、领域B
**文件清单**：
- knowledge/领域A/_index.md
- knowledge/领域A/模块A/_index.md
- ...
**下一批计划**：生成 XXX 领域的核心功能卡片
请确认是否继续？
注意事项
- 分批交付：如果项目超过 100 个功能，先完成 L1 和 L2 骨架，再逐步下钻到 L3，最后批量生成 L4
- 代码读取限制：如果代码文件太多，让用户先提供核心模块的 5~10 个关键文件，其他按目录结构描述即可
- 人工补充：Skill 生成 80% 的内容（结构、流程、规则框架），但具体的历史踩坑记录和负责人信息需提示用户手动补充
实战经验（2026-09-01 jetlinks 项目沉淀）
- Obsidian 链接必须用库根路径 + 不带
.md后缀（最关键）：Obsidian 的 wiki 链接 不支持../相对路径（../会被当作笔记名），也 不支持.md后缀（[[Note.md]]会被当作名为 "Note.md" 的笔记而非 "Note"，导致无法点击）。所有链接统一写[[领域/模块/功能\|别名]]（从 knowledge/ 根出发，不写 .md），mermaid 图中用纯文本节点（A[功能] --> B[功能]），禁止[[...]]语法。 - 子代理 429 限流降级：大规模探索/生成时子代理可能触发频率限制（429），此时降级为主会话直接生成：先用 Glob/Grep 定位所有 Controller 的
@RequestMapping与 HTTP 方法注解（可精确到行号），再逐文件写入。 - 质检脚本须跳过代码块：L4 卡片内"链接规范"示例常写在反引号代码块中，质检正则需先剔除
`...`与mermaid块内容，否则会把示例误报为悬空链接。 - 功能数回写机制：L2 索引中的模块功能数是预估的，L3 生成后以实际为准，第五批用脚本自动回写 L2 统计列与 L1 规模统计。
- 批量生成用脚本：第四批骨架卡片（100+ 文件）用 Python 脚本从 L3 索引表格正则提取功能名/类型/描述并批量写入，保证命名与链接一致，比逐文件手写高效且不易出错。
实战经验（2026-09-02 大规模项目全量升级沉淀）
- 骨架卡升级全量触发，不等点名：用户对"待补充/规则过简"不满即触发全量升级，按领域分批，全部升级到完整卡详细度（见 business skill 的"L4 卡片详细度标准"）。
- 并行子代理按领域分派 + 主代理监控：每个领域派一个子代理（prompt 内置模板样例 + mermaid 铁律 + 代码勘察要求）；主代理用
grep -rl "状态: 待补充" <领域> | wc -l定期检查剩余量，代理停滞（一段时间无新文件产出）时直接接管补齐，不干等。 - mermaid 节点 label 禁嵌套圆括号（渲染失败头号原因）：flowchart 节点
[..]/{..}内出现()（如A[Foo(x)]）会报 "Expecting SQE, DOUBLECIRCLEEND..." 解析错误；函数签名参数删除或空格分隔。批量修复：正则仅扫 mermaid 块，把[label(args)]替换为[label args]（去括号、逗号变空格）。 - 子代理跨模块相对路径易错：子代理写跨模块链接时
../..层级算错是高频失误（例如交易管理/交易日志/指向行情数据/自选股管理/应为../../行情数据/自选股管理/_index.md而非../自选股管理/）；终检必须跑双链校验脚本，列出断链清单逐一修复。 - 终检三合一：升级完成后跑 ① 双链完整性脚本（遍历全部 md 解析
[[...]]相对路径并校验目标存在）② mermaid 括号扫描 ③ 待补充残留计数（grep -rl "状态: 待补充" | wc -l应为 0）；更新 README 统计后交付。
批量升级骨架卡操作指南
当 knowledge/ 已存在大量骨架卡需升级时：
1. 统计剩余：grep -rl "状态: 待补充" knowledge/*/ | wc -l （按领域细分）
2. 按领域并行派子代理（每个 prompt 需包含：模板样例绝对路径、mermaid 铁律、
代码勘察要求"至少 1-2 个真实函数名+行号，找不到标待定位不编造"、输出报告格式）
3. 主代理定期检查：find 最近 mtime 文件 / grep 剩余待补充数；停滞即接管
4. 终检：双链校验脚本 + mermaid 括号扫描 + 待补充计数归零
5. 更新 README 统计与各层 _index 统计数字
Resources
business-knowledge-graph-generator/references/templates.md：L1~L4 模板规范（必须遵循）