cgraphx 1.4.3 → 2.0.1

package/dist/.claude-template/skills/knowledge-migrate/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: knowledge-migrate
+disable-model-invocation: true
+description: 将存量知识库(docs/knowledge/)批量迁移到新分类体系,两阶段各自独立提交——阶段一 frontmatter 换血:逐篇读内容,按内容主题判定新 document_type / source_type / 业务域(不按旧值机械映射),服务模块移入 tags,仅改写 frontmatter 四个字段(保留正文与其余全部字段;owners 现为必填,缺失时补填默认负责人),dry-run 报告 → 用户确认 → 执行 → 逐篇 docs validate(失败回滚该条)→ 剔除归档 → 索引重建提议 → 抽检;阶段二 文件名迁移(仅当存在不合规文件名,典型为早期全英文 kebab-case):按现行命名规则拟新 slug,改名并同步改写全库引用,悬空校验不过整批回滚。Use when 迁移知识库/分类迁移/类型迁移/frontmatter 迁移/知识库换血/英文文件名迁移/文件改名/migrate knowledge/taxonomy migration.
+---
+
+# 知识库迁移 (Knowledge Migrate)
+
+## 定位
+
+- **存量一次性换血,无双轨期**:分类体系换成 document_type 7 值 / source_type 5 值、domains 语义转向业务域;本 skill 是存量迁移的唯一执行载体。
+- **两阶段,各自独立提交**:阶段一改 frontmatter(报告 → 确认 → 执行 → 校验 → 剔除 → 索引 → 抽检),完成并提交后才进阶段二;阶段二改文件名(仅当存在不合规文件名,典型为早期全英文 kebab-case 知识库),改名必同步改写全库引用。阶段可单独触发:文件名已合规的库只做阶段一。
+- **按内容主题判定,不按旧值机械映射**:值合法 ≠ 归属准确;同名保留值同样逐篇复核。
+- **用户确认是唯一人工闸门**:每阶段先出 dry-run 报告,不改任何文件;未确认不得执行写入。
+
+## 新分类枚举表(迁移目标)
+
+### document_type(7 值)
+
+| 值 | 含义 |
+|---|---|
+| business-entity | 业务实体 |
+| business-flow | 业务流程 |
+| mechanism | 技术机制(含架构) |
+| decision | 决策 |
+| rule | 规则 |
+| lesson | 教训 |
+| guide | 指南(含运维手册/教程/安装/FAQ/API 文档) |
+
+### source_type(5 值)
+
+| 值 | 含义 |
+|---|---|
+| work_context | 工作上下文 |
+| batch_exploration | 批量探索 |
+| review | 评审 |
+| debugging | 调查排障 |
+| manual | 手工 |
+
+## 旧值 → 新值映射表(判定依据)
+
+### document_type
+
+| 旧值 | 新值 / 判定方式 |
+|---|---|
+| concept | → business-entity |
+| exploration / finding / analysis | 按内容主题判定:讲业务流程 → business-flow;讲技术机制/架构 → mechanism;讲业务实体 → business-entity |
+| architecture | → mechanism |
+| warning | 约束类 → rule;复盘类 → lesson |
+| tutorial / runbook / installation / api / faq | → guide |
+| conversation / note | 按主题判定;确无主题 → 剔除入库(记入剔除清单) |
+
+### source_type
+
+| 旧值 | 新值 |
+|---|---|
+| ai_session | → work_context |
+| architecture_review / code_review | → review |
+| debugging | → debugging(同名保留,按新语义复核) |
+| manual / human_note / external_summary | → manual |
+
+### domains
+
+- **服务模块值迁 tags**:domains 中的服务模块值移入 tags(在原 tags 基础上追加,不覆盖)。
+- **按内容填业务域**:迁移后 domains ≥1 项(**不得留空**)。
+- **非空边界**:服务模块值迁出 domains 后,若文档无明确业务域归属,必须按内容填入合适的业务域——不得迁出空 domains。
+
+### owners(新必填,缺失补填)
+
+- owners 现为必填字段:缺失或空列表 → `docs validate` 判 `missing_required_field`,该条迁移会被校验回滚。
+- **已有 owners 一律原样保留**,不改写、不追加。
+- **缺失或为空 → 补填默认负责人**:取 `git config user.name`(取不到则请用户给定),作为该文档 owners 的唯一值。
+- 补填是批量默认、不逐篇追问:在 dry-run 报告表「owners 补填」列示出,随第 3 步用户确认一并通过;用户对某条负责人有意见,在该步逐条修订。
+
+### 同名保留值复核
+
+decision / rule / lesson / guide(document_type)与 debugging / manual(source_type)是同名保留值——**值合法 ≠ 归属准确**,必须按新语义逐篇复核,不得以「值没变」为由跳过。
+
+### 判定纪律
+
+**按内容主题判定,不按旧值机械映射**:逐篇读文档内容(至少读 Summary 与标题/正文要点)再判定;判定依据浓缩为一句话记入报告表,供抽检可审。
+
+## 阶段一:frontmatter 迁移
+
+1. **定范围**:目标项目知识库(`docs/knowledge/` 全量)或用户指定文件集;域外文件不碰。
+2. **dry-run**(不改任何文件):逐篇读内容,按上面的「旧值 → 新值映射表」判定,生成**迁移报告表**(格式见下节)——每行含判定依据(一句话);主题不明者标剔除建议。
+3. **用户确认(硬检查点)**:报告交用户确认——**未确认不得执行写入**;用户对单条的修改意见直接采纳,修订报告后以确认版为执行依据。
+4. **执行**:按确认版报告批量改写 frontmatter——**仅改 document_type / source_type / domains / tags 四个字段**,并对 owners 缺失/为空的条目按确认版报告补填默认负责人(见「owners(新必填,缺失补填)」);保留正文与其他全部 frontmatter 字段(未知字段原样保留,见「字段改写纪律」)。
+5. **逐篇校验**:`cgraphx docs validate <file>`(或 `node dist/cli/index.js docs validate <file>`);不过的条目**回滚该条**(恢复迁移前 frontmatter)并列入失败清单。
+6. **剔除执行**:主题不明的剔除项**移出索引目录**(默认 `docs/knowledge/` → `docs/knowledge-archive/`,归档目录可在第 3 步用户确认环节改)——留在 `docs/knowledge/` 带旧值会导致重索引 skip,违反「重建索引无 skip」验收;剔除动作同样在用户确认后执行。
+7. **提议重建索引**:`cgraphx docs index`(**用户确认后**执行,全量覆盖式、事务性:失败回滚,不坏旧索引);不得自动执行。
+8. **输出**:① 抽检建议——随机抽 N 篇供人工核对(含判定依据;默认 10% 且 ≥3 篇);② 剔除清单(含归档去向);③ 失败清单(validate 不过被回滚的条目)。
+9. **独立提交**:阶段一改动单独提交,提交后再进阶段二。
+
+## 阶段二:文件名迁移
+
+仅当库内存在不合规文件名时执行(典型:早期知识库文件名全英文 kebab-case,如 `architecture-overview.md`);文件名已合规则跳过本阶段。改的是阶段一 survivors(仍在 `docs/knowledge/` 的文件)。
+
+1. **dry-run(不改文件)**:逐篇按「文件命名规则」拟新 slug;扫全库 `related_documents` 与正文中的 `.md` 路径引用,列出每个改名的受影响引用方;生成**文件名迁移报告表**(格式见下节)。
+2. **用户确认(硬检查点)**:未确认不得改名;确认一并涵盖本阶段重建索引授权(不再设第二暂停)。
+3. **执行(原子批)**:由确认版报告建立 old→new 全量映射,然后 `git mv` 改名(保历史)+ 同步改写全库引用——`related_documents` 与正文中按路径引用处,保留原前缀形态(`./x.md` / `docs/knowledge/x.md`)仅换基名。正文语义一字不动(路径替换除外)。
+4. **悬空校验**:扫所有 `related_documents` 目标与正文 `.md` 引用,须全部落地到现存文件;出悬空 → **整批回滚**(`git mv` 可逆 + old→new 反向映射还原引用)并列失败清单,不做半回滚。
+5. **重建索引**:`cgraphx docs index`(路径已变,必须重建;授权已折叠入第 2 步确认);验收同阶段一,索引报告 0 skipped。
+6. **独立提交**:与阶段一分开提交。
+7. **输出**:① 抽检——随机抽改名篇目输出改名 + 引用改写 diff;② 失败清单(悬空回滚的批次)。
+
+## 迁移报告表格式
+
+列定义(dry-run 产出,提交用户确认):
+
+| 列 | 填法 |
+|---|---|
+| 文件 | 相对项目根的路径 |
+| 旧 document_type → 新 | 旧值 → 新值;同名保留值标「已复核」 |
+| 旧 source_type → 新 | 同上 |
+| 旧 domains → 新业务域 | 迁出服务模块后保留/补填的业务域值 |
+| 移入 tags 的服务模块 | 从 domains 移入 tags 的具体值;无则 — |
+| owners 补填 | 缺失/为空 → 填默认负责人(git user);已有 owners → — |
+| 判定依据 | 一句话(为什么判为该新值),抽检可审 |
+| 剔除建议 | 主题不明者填「剔除」+ 理由;其余 — |
+
+## 文件命名规则(阶段二)
+
+slug 跟项目实际叫法(沿用 knowledge-write「命名与语言」):中文概念用项目语言,代码标识符/协议/产品名保留真实形式(markdown / redis / CodeGraph 不翻);取 title/主题的词,不二次翻译;逐篇判定,依据入报告表。例:
+
+| 旧文件名 | 新文件名 | 依据 |
+|---|---|---|
+| architecture-overview.md | 架构总览.md | title「CodeGraph 架构总览」,产品名 CodeGraph 不入 slug |
+| markdown-knowledge-base.md | markdown知识库.md | markdown 为标识符保留英文,「知识库」用项目语言 |
+
+## 文件名迁移报告表格式
+
+列定义(dry-run 产出,提交用户确认):
+
+| 列 | 填法 |
+|---|---|
+| 旧文件名 → 新文件名 | 相对 `docs/knowledge/` 的基名变更 |
+| 命名依据 | 一句话(新 slug 怎么来的),抽检可审 |
+| 受影响引用方 | 全库内经 `related_documents` 或正文路径引用该文件、需同步改写的文件清单;无则 — |
+
+## 字段改写纪律
+
+仅改四个字段(owners 缺失/为空时另按「owners(新必填,缺失补填)」补填默认负责人),其余一律保留。改写结果形态(值取自确认版报告):
+
+```yaml
+document_type: <新 document_type>   # 枚举表 7 值之一
+source_type: <新 source_type>       # 枚举表 5 值之一
+domains:                            # 业务域,≥1 项,不得为空
+  - <按内容判定的业务域>
+tags:                               # 原 tags 保留 + 追加从 domains 移入的服务模块
+  - <原 tags…>
+  - <移入的服务模块>
+# 其余 frontmatter 字段(title / concepts / aliases / status /
+# related_code / related_documents / created / updated 及任何未知字段):原样保留
+# owners:已有则原样保留;缺失/为空则补填默认负责人(见「owners(新必填,缺失补填)」)
+# 正文:一字不动
+```
+
+## 红线
+
+- **阶段一不改正文**:只改写 frontmatter 的 document_type / source_type / domains / tags 四个字段(owners 缺失/为空时按规则补填默认负责人,不改写已有 owners)。
+- **未知字段保留**:除四个目标字段(及 owners 缺失补填)外的全部 frontmatter 字段原样保留,不删不改。
+- **owners 只补不改**:已有 owners 一律保留;仅缺失/为空时补填默认负责人,不覆盖、不追加。
+- **validate 不过即回滚该条**:`docs validate` 失败的条目恢复迁移前 frontmatter,列入失败清单,不带病入库。
+- **不自动跑 docs index**:索引重建仅在用户确认后执行。
+- **剔除必先经用户确认且给出归档去向**:剔除项必须移出索引目录(默认 `docs/knowledge-archive/`),禁止留在 `docs/knowledge/` 带旧值(重索引会 skip)。
+- **域外文件不碰**:只动 `docs/knowledge/` 或用户指定文件集。
+- **迁移后 domains ≥1 项**:服务模块迁出后必须按内容补填业务域,不得迁出空 domains。
+- **阶段二改名必同步改引用**:`git mv` 改名必须同步改写全库 `related_documents` 与正文中对该文件的路径引用(保留 `./x.md` / `docs/knowledge/x.md` 前缀形态,仅换基名);禁止只改名不改引用,留悬空引用。
+- **阶段二不改正文语义**:仅替换路径引用,正文其余内容一字不动。
+- **阶段二悬空即整批回滚**:悬空校验不过 → 整批回滚(`git mv` 可逆 + old→new 反向还原引用),列失败清单,不做半回滚。
+- **两阶段独立提交**:阶段一(frontmatter)与阶段二(文件名)分开提交;阶段一提交后才进阶段二。
+- **文件名已合规不强改**:阶段二仅处理不合规文件名(典型早期全英文 kebab-case);已合规则跳过,不为统一而统一。

package/dist/.claude-template/skills/knowledge-recall/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: knowledge-recall
-description: 从项目 markdown 知识库召回业务概念 — 当用户聊业务/遇到不懂的术语/需要对齐项目黑话/提到一个名词想确认项目里有没有沉淀过时,强制派子 agent 在隔离上下文里加载全量 concept 列表做语义匹配,主 agent 只拿命中的概念(名+文档路径+一行说明),不直接看到全量表。Use when 聊业务/不懂这个术语/这个词什么意思/对齐黑话/项目黑话/业务概念/行业术语/这个名词/沉淀过/之前记录过/有没有相关文档/这个业务词.
+description: 从项目 markdown 知识库召回业务概念 — 当用户聊业务/遇到不懂的术语/需要对齐项目黑话/提到一个名词想确认项目里有没有沉淀过时,强制派子 agent 在隔离上下文里加载全量 concept 列表做语义匹配,主 agent 只拿命中的概念(名+文档路径+一行说明),不直接看到全量表。Use when 聊业务/不懂这个术语/这个词什么意思/对齐黑话/项目黑话/业务概念/行业术语/这个名词/沉淀过/之前记录过/有没有相关文档/这个业务词/X是什么/这个概念什么意思.
 ---
 
 ## 这个 skill 解决什么
@@ -19,6 +19,7 @@ description: 从项目 markdown 知识库召回业务概念 — 当用户聊业
 2. **直接采纳** 子 agent 返回的命中概念列表 —— 不要再自己调 `cgraphx docs concepts/find` 重新查(那是浪费,且会把全量表拉进主上下文)
 3. 拿到命中概念后,主 agent 决定下一步:
    - 概念够清晰,直接回答用户
-   - 需要细节 → `Read` 子 agent 返回的文档 path
-   - 需要精确查某个概念的其他文档 → 调 `code-impact-api` skill
-   - 子 agent 说"没有命中"→ 告诉用户项目里没沉淀这个概念,问要不要记录
+   - **命中里有标"实体主条目"的** → 优先 `Read` 它:那是概念的枢纽(定义 / 黑话 / 关键约束 / 代码入口)。要"该实体参与了哪些业务"的全景,再 `cgraphx docs find --concept=<实体>` 反查引用它的流程条目(这是实体参与业务的派生视图,不是重复查询)
+   - 需要流程细节 → `Read` 子 agent 返回的流程文档 path,再从条目的代码入口进代码
+   - 需要精确查某个概念的其他文档 → 调 `knowledge-api` skill
+   - 子 agent 说"没有命中"→ 告诉用户项目里没沉淀这个概念,问要不要记录;是业务实体(名词、有属性和生命周期)就走 `knowledge-write` 的实体主条目(`business-entity`)

package/dist/.claude-template/skills/knowledge-write/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: knowledge-write
+description: 维护可供 cgraphx docs 索引的 Markdown 知识文件(docs/knowledge/)。用于创建、编辑、规范化或提取元数据,将对话、代码探索结果、教程、指南、运维手册、安装说明、决策、经验教训、业务实体概念或面向 AI 的项目知识保存为可被 cgraphx docs 检索的 .md 文件。
+---
+
+# 知识沉淀 (Knowledge Write)
+
+## 定位
+
+- **知识库 = 业务概念与代码的索引,不是百科**:条目只存代码给不了的东西(概念定位、黑话映射、跨文件才看得出的关系、代码入口指针),行为细节让 agent 从代码入口进去读。代码是事实来源,条目是指北针。不存细节,所以没有东西可腐烂。
+- **重构幸存测试**(该不该进库的判据):代码重构之后这条还成立吗?概念名 / 文件级入口 / 跨文件关系成立;行号 / 步骤时序 / 实现逻辑不成立——后者一律不写。
+- **双层结构**:实体层(`business-entity` 条目,一个业务实体一个文档)+ 流程层(business-flow(流程主条目)/ mechanism(技术机制)等,一个业务流程一个文档),靠概念引用连接——召回精度的根基。
+
+## 流程
+
+1. **定目标路径**(`docs/knowledge/` 下,一个文档一个主题;目录不存在则创建;知识文件不存到别处)。
+2. **命名新概念前先查已有词汇**(见 CLI):含义相同 → 复用规范名;替代名称走 `aliases`,不造重复 concept。
+3. **更新已有文件 → 先读取并保留其 frontmatter**(见「维护」)。
+4. **写 frontmatter**(见「Frontmatter 规范」)+ 正文必含 `## Summary`——唯一进索引的章节。
+5. **Write 后立刻 `cgraphx docs validate <file>`**:非法 → 修 frontmatter 再 Write 再校验,直到合法才告知用户已保存(非法文件 index 时整个跳过,校验前置不是可选)。
+6. **合并检查**:三条件全满足才提示用户(见「维护」)。
+7. **询问是否触发扫描**;未经确认不跑 `cgraphx docs index`(全量覆盖式重建,事务性:失败回滚,不坏旧索引)。
+
+## 双层结构:实体条目与流程条目
+
+- **实体主条目**(`document_type: business-entity`):业务实体 = 能用名词指代、有属性和生命周期、被多个流程引用(商品 / 礼包 / 订单)。按 [template-concept.md](template-concept.md) 写——只做定位与指引(定义 / 黑话 / 跨文件约束 / 代码入口),行为细节留给代码。
+- **流程条目的正向引用**:必须在 `concepts:` 声明所涉实体(规范实体名);漏标 → 该流程从实体视图消失。
+- **反查 = 派生的"参与业务"视图**:`find --concept=<实体>` 返回所有引用该实体的文档。**任何条目里都不手动维护全量清单**——手动维护必陈旧,反查永远最新。
+- **同名严格性**:流程条目里的实体名与实体条目的规范 concept 名逐字一致;建条目前先 `docs concepts` 查名,错一个名反查就断。
+- **不是所有概念都配主条目**:机制概念(Scene 分发机制、准三层)、动作概念(礼包续订)留作 tag;只有业务实体升级。
+- **沉淀时机**:功能交付完成时最佳(理解最新鲜);implementation/subagent-implement 收尾会提示识别实体;只从一两个流程抽出的条目用 `status: draft` + Open Questions 标记未补全。
+
+## Frontmatter 规范
+
+```yaml
+---
+title: 礼包
+document_type: business-entity
+domains:
+  - 商品
+concepts:
+  - 礼包
+aliases:
+  - package
+  - Pkg
+  - 销售包
+tags:
+  - entity
+  - so-service
+status: active
+source_type: manual
+owners:
+  - platform
+related_code:
+  - so-service/so-busi/src/main/java/.../PkgContinueAtom.java
+related_documents:
+  - docs/knowledge/礼包新装流程.md
+created: 2026-04-28
+updated: 2026-04-28
+---
+```
+
+- **必填 8 项**:title / document_type / domains / concepts / status / source_type / updated / owners。
+- **时间**:`YYYY-MM-DD`;`created` 可选推荐。
+- **`related_code`**:仅作元数据保存(不建反向链接,不校验路径存在);用文件级路径或全限定类名,不写行号。
+- **`document_type` 枚举(7)**:business-entity 业务实体(业务对象主条目)· business-flow 业务流程 · mechanism 技术机制(含架构)· decision 决策 · rule 规则 · lesson 教训 · guide 指南(含运维手册/教程/安装/FAQ/API 文档)。
+- **`source_type` 枚举(5)**:work_context 工作上下文(需求/任务流中沉淀)· batch_exploration 批量探索(knowledge-init 式项目探索)· review 评审(代码/架构评审中发现)· debugging 调查排障(问题调查中发现)· manual 手工(人工主动整理)。
+- **`status` 枚举(4)**:draft · active · superseded · deprecated。
+
+## Summary 章节(唯一进索引)
+
+- 只有 `## Summary`(中文别名 `## 摘要`)进索引;**标题大小写敏感,必须正好两个 # + 一个空格**。其他章节留在文件里,AI 想看就 Read。
+- 章节按 `document_type` 选模板——模板是写作指南,不是索引契约:
+
+| document_type | 模板 |
+|---|---|
+| business-entity | [template-concept.md](template-concept.md) |
+| business-flow | [template-flow.md](template-flow.md) |
+| mechanism / decision / rule / lesson | [template-memory.md](template-memory.md) |
+| guide | [template-guide.md](template-guide.md) |
+
+## 命名与语言
+
+- **concept**:一个概念一个规范名,优先复用已索引名(`docs concepts` 查);不造翻译重复项(Redis / redis server / Redis Installation 算重复);替代名(译名 + 同义词 + 缩写)进 `aliases`。
+- **命名由检索机制决定**:`find --q` 是整串 LIKE,**只匹配 title + Summary**(concept 名不参与)→ 黑话/口语变体要在 Summary 出现一次才可被 `--q` 命中;`find --concept` 是精确过滤、召回子 agent 用 concept 名做语义匹配 → 规范名用项目实际用词;aliases 只归一,不参与搜索。
+- **语言**:中文概念不硬翻英文——代码标识符/协议/产品名保留真实形式(Redis / SqliteStore / FTS5),业务/流程概念用项目语言(本地开发环境、任务办理流程);正文用中文,术语/标识符/路径保留英文;Summary 标题保留英文。
+- **domain**:语义为**业务域**——项目的业务领域(合约 / 商品 / 礼包 / 宽带 / 订单),稳定有界;**自由词表,程序不校验枚举**,靠填写引导与召回反馈收敛。服务/模块信息(so-service / order-service)放 **tags** 不放 domains。示例:✗ `domains: [so-service]` → ✓ `domains: [商品]` + `tags: [so-service]`。**tags**:松散分组,不替代 concepts/domains。
+- **文件名**:主题 slug 跟项目实际叫法(常说"流程"就用"流程",常说 redis 就用 redis),不二次翻译;不进索引、不参与检索,中文名不影响命中。
+
+## CLI
+
+- **查已有词汇**:`cgraphx docs concepts`(concept + 关联文档数 + domain)/ `docs domains` / `docs tags`;查特定:`find --q=<词>`(整串 LIKE,title+Summary)/ `find --concept=<名>`(精确过滤,也是实体反查入口)。索引未建 → `grep -rl "concepts:" docs/knowledge/ --include="*.md"`。
+- **校验**:`docs validate <file>`(exit 0 合法 / 2 非法;`--json` 出 {valid, skipReason, detail})。规则与 index 扫描一致(单一事实源 `src/core/markdown/validator.ts`):title 非空 · document_type 属 7 枚举 · domains/concepts/owners ≥1 项 · status 属 4 枚举 · source_type 属 5 枚举 · updated 为 YYYY-MM-DD。
+- **扫描**:`docs index`——全量覆盖式重建,事务性(任一步失败回滚,旧索引不坏)。
+
+## 质量规则
+
+- **应记录**(满足任一):非显而易见的业务逻辑 · 决策原因(尤其有替代方案时)· 跨系统的执行流程与运维操作 · 陷阱与隐式约束 · 跨系统依赖 · 历史背景(事故/变通/遗留约束)。
+- **不记录**:代码/配置已记录的 · 通用编程知识 · 已应用的一次性修复 · 逐字对话记录(提取结论,不提取过程)· 工具使用说明 · 可从文件结构推导的 · **行号与符号偏移**(只写文件级路径)· **步骤时序与代码逻辑复述**(条目给代码入口,写步骤就种下腐烂)。
+- **通用**:持久知识优于对话日志;保留证据(文件级路径/符号名/命令输出)使他 AI 可信任;不确定性用 Open Questions 或 `status: draft`;约束类陷阱用 `rule`,复盘类用 `lesson`;被替代用 `superseded` + `related_documents` 链替代者;教程/指南尽量含 Validation / Troubleshooting。
+
+## 维护
+
+### 更新已有文件
+
+提取现有 frontmatter;保留未知字段(明显有误除外);列表字段规范化;补缺失必填项;**未查已有用法前不重命名 concepts/domains**;保留有用标题;优先追加带日期新发现,而非重写历史结论(除非已过时)。
+
+### 合并检查
+
+仅三条件**同时满足**才提示:① document_type 匹配或兼容(memory 模板族:mechanism/decision/rule/lesson 互兼容;**business-entity 与 business-flow 永不互合**——实体新发现追加进实体条目);② 核心概念高度重叠(至少一个核心 concept 出现在对方 `concepts:` 中,边缘重叠不算);③ 范围相似(覆盖同一知识领域,不只是提到相同概念)。
+
+查候选:`find --concept=<核心概念>` / `find --q=<标题关键词>`(无索引则 grep)。合并时:读全文 → 带日期标题下追加 → 更新 `updated` + 合并 concepts/aliases/tags/related_code/related_documents → 删除新文件 → 保留已有 `title`(除非用户给了更好的)。
+
+### 拆分
+
+一个文档覆盖多个不相关概念 → 拆:每文档聚焦一个核心概念;章节不共享 concepts/domains/type → 分文件;相关但目的不同且概念显著重叠 → 可同文档;按主题命名,`related_documents` 互链。
+
+## 红线(绝对不能做)
+
+1. ❌ **知识文件不出 `docs/knowledge/`**。
+2. ❌ **不跳过校验 Write**——修到 validate 合法才告知已保存。
+3. ❌ **未经用户确认不跑 `docs index`**。
+4. ❌ **不造重复 concept**——先查词汇,替代名走 aliases。
+5. ❌ **不写行号 / 步骤时序 / 代码复述**——索引层只存定位与指针。
+6. ❌ **不手动维护"参与业务"全量清单**——`find --concept` 反查派生。
+7. ❌ **不硬翻中文概念为英文**——用项目实际话语。

package/dist/.claude-template/skills/knowledge-write/template-concept.md

@@ -0,0 +1,95 @@
+# 实体概念主条目模板
+
+适用的 `document_type` 值：
+
+```text
+business-entity
+```
+
+实体主条目是知识库**索引层的枢纽**：一个业务实体（能用名词指代、有属性和生命周期、被多个流程引用，如"商品"、"礼包"、"订单"）独占一个文档。条目只做**定位与指引**——定义、黑话、跨文件才看得出的约束、代码入口；行为细节永远由 agent 去代码里读，不写进条目（不存细节，所以不会腐烂）。
+
+## 完整模板
+
+```markdown
+---
+title: 礼包
+document_type: business-entity
+domains:
+  - product
+concepts:
+  - 礼包                  # 规范实体名：必须与流程条目 concepts 里的引用名严格一致（反查锚点）
+aliases:
+  - package
+  - Pkg
+  - 销售包                 # 黑话/别名：同时写进 Summary 一句话，才能被 find --q 命中
+tags:
+  - entity
+status: active             # 只从一两个流程抽出来、尚未补全时用 draft
+source_type: manual
+owners:
+  - platform
+related_code:
+  - so-service/so-busi/src/main/java/.../PkgContinueAtom.java   # 文件级入口，不写行号
+related_documents:
+  - docs/knowledge/礼包新装流程.md
+  - docs/schema-knowledge/xw-so/ddl/pkg_inst.sql
+created: 2026-07-26
+updated: 2026-07-26
+---
+
+# 礼包
+
+## Summary
+
+一句话定义 + 系统定位。黑话别名在此各出现一次（如"又称销售包/package"）。
+与邻近概念的边界一句话说清（如"礼包是商品的打包形态，成员为商品实例"）。
+不写行为细节、不写流程步骤。
+
+## 命名与边界
+
+规范名、英文标识符、黑话变体；与易混概念的区分（商品 vs SKU vs SPU 这类）。
+
+## 关键约束与陷阱
+
+只写**跨文件才看得出的**业务规则、隐式约束、历史地雷。
+示例：礼包内商品禁止单独退订；准三层续包对礼包成员的校验顺序。
+
+## 代码入口
+
+实体核心类、关键服务/Atom/Scene —— 文件级路径，agent 从这里进去读真实逻辑。
+不写行号（重构即失效）、不复述代码逻辑。
+
+## 相关表
+
+链 docs/schema-knowledge/<工程>/ddl/<表>.sql 的 DDL 快照；没有快照就列核心表名。
+
+## 关联流程
+
+只列 2-3 个核心流程条目供人读。完整"参与业务"清单不在此维护——
+`cgraphx docs find --concept=礼包` 反查所有引用该实体的文档，是唯一权威视图。
+
+## Open Questions
+
+尚未确认的语义、边界未清的相邻概念。用 status: draft 配合此章节。
+```
+
+## 各章节填写要点
+
+| 章节 | 用途 | 注意事项 |
+|------|------|----------|
+| Summary | 定义 + 黑话 + 定位 | 唯一进索引的章节；黑话要在此出现才能被关键词搜到；不写行为细节 |
+| 命名与边界 | 规范名与易混概念区分 | 防止"商品/Goods/SKU"各建一个条目的碎片化 |
+| 关键约束与陷阱 | 跨文件关系与隐式规则 | 单个文件能读出的东西不写（代码是事实来源） |
+| 代码入口 | agent 读代码的起点 | 文件级路径；**绝不写行号**；不解释代码做了什么 |
+| 相关表 | DDL 快照链接 | 走 docs/schema-knowledge/，不抄表结构 |
+| 关联流程 | 人读的 2-3 个核心流程 | 不维护全量清单，全量由 concept 反查派生 |
+
+## 不应写入实体条目的内容
+
+| 不写 | 理由 |
+|------|------|
+| 流程步骤、时序 | 属于流程条目与代码，写进来必然腐烂 |
+| 代码逻辑复述 | 代码是事实来源，agent 应从代码入口去读 |
+| 行号（`Foo.java:372`） | 一次重构全部失效 |
+| "参与业务"全量清单 | 由 `find --concept=<实体>` 反查派生，手动维护必陈旧 |
+| 可从 DDL/代码直接读出的属性列表 | 索引层只给指针，不抄内容 |

package/dist/.claude-template/skills/knowledge-write/template-flow.md

@@ -0,0 +1,100 @@
+# 业务流程主条目模板
+
+适用的 `document_type` 值：
+
+```text
+business-flow
+```
+
+流程主条目记录一个**业务流程**（礼包新装、订单退款、准三层续订）：触发、参与者、主干状态流转、异常分支与跨文件约束。与实体主条目（business-entity）互补——实体给定位，流程给链路；两者靠 `concepts` 引用连接。同样只存代码给不了的东西：跨文件才看得出的规则、状态迁移的边界、文件级代码入口。逐步时序与代码复述一律不写（重构幸存测试：重构后仍成立的才写）。
+
+## 完整模板
+
+```markdown
+---
+title: 礼包新装流程
+document_type: business-flow
+domains:
+  - 商品
+concepts:
+  - 礼包                  # 所涉实体：必须与实体条目 concepts 里的规范名严格一致（反查锚点）
+  - 订单
+aliases:
+  - 新装
+  - 礼包开通               # 黑话/别名：同时写进 Summary 一句话，才能被 find --q 命中
+tags:
+  - so-service             # 服务/模块信息放 tags，不放 domains
+status: active             # 只从一两个视角抽出、尚未补全时用 draft
+source_type: work_context
+owners:
+  - platform
+related_code:
+  - so-service/so-busi/src/main/java/.../PkgInstallScene.java   # 文件级入口，不写行号
+related_documents:
+  - docs/knowledge/礼包.md
+created: 2026-07-31
+updated: 2026-07-31
+---
+
+# 礼包新装流程
+
+## Summary
+
+一句话定义 + 系统定位。黑话别名在此各出现一次（如"又称新装/礼包开通"）。
+与邻近流程的边界一句话说清（如"新装止于首单生效，续订归礼包续订流程"）。
+不写逐步时序、不复述代码。
+
+## 触发与前置
+
+触发事件（用户下单 / 上游回调 / 定时任务）与前置条件（已存在的实体与状态）。
+
+## 参与者与系统
+
+涉及的角色、系统、服务——文件级列举，不展开实现。
+
+## 主链路与状态流转
+
+主干步骤与关键状态迁移（如 待支付 → 生效 → 完成）。
+只给状态名与文件级入口指针，不写行号、不复述每一步的代码逻辑。
+
+## 异常分支
+
+失败 / 回滚 / 补偿路径：什么情况触发、回到哪个状态。
+
+## 关键约束与陷阱
+
+只写**跨文件才看得出的**业务规则、隐式约束、历史地雷。
+示例：新装校验先于库存扣减；准三层对礼包成员的校验顺序。
+
+## 代码入口
+
+流程入口类、关键 Scene/Atom/Handler —— 文件级路径，agent 从这里进去读真实逻辑。
+不写行号（重构即失效）、不复述代码逻辑。
+
+## Open Questions
+
+尚未确认的分支、边界未清的相邻流程。用 status: draft 配合此章节。
+```
+
+## 各章节填写要点
+
+| 章节 | 用途 | 注意事项 |
+|------|------|----------|
+| Summary | 定义 + 黑话 + 边界 | 唯一进索引的章节（标题必须正好 `## Summary`，两个 # 一个空格）；黑话要在此出现才能被关键词搜到；不写逐步时序 |
+| 触发与前置 | 触发事件与前置条件 | 写清由什么启动、依赖哪些已存在的实体/状态 |
+| 参与者与系统 | 角色/系统/服务 | 文件级列举，不展开实现细节 |
+| 主链路与状态流转 | 主干步骤与状态迁移 | 给状态名与文件级入口；**绝不写行号、不复述每步代码** |
+| 异常分支 | 失败/回滚/补偿 | 写触发条件与回到的状态，不复述异常处理代码 |
+| 关键约束与陷阱 | 跨文件规则与隐式约束 | 单个文件能读出的东西不写（代码是事实来源） |
+| 代码入口 | agent 读代码的起点 | 文件级路径；**绝不写行号**；不解释代码做了什么 |
+| Open Questions | 未确认分支 | 与已确认内容分开跟踪；配合 status: draft |
+
+## 不应写入流程条目的内容
+
+| 不写 | 理由 |
+|------|------|
+| 行号（`Foo.java:372`） | 一次重构全部失效 |
+| 逐步代码逻辑复述 | 代码是事实来源，agent 应从代码入口去读 |
+| 全量分支 / 全量状态清单 | 只写主干与关键分支，全量让 agent 读代码 |
+| "参与业务"全量清单 | 由 `find --concept=<实体>` 反查派生，手动维护必陈旧 |
+| 可从代码直接读出的字段/参数 | 索引层只给指针，不抄内容 |

package/dist/.claude-template/skills/knowledge-write/template-guide.md

@@ -0,0 +1,77 @@
+# 指南或教程类文档模板
+
+适用的 `document_type` 值：
+
+```text
+guide
+```
+
+`guide` 是统一指南类型，按内容分子类（不另设 document_type）：**教程**（tutorial）/ **安装说明**（installation）/ **API 文档**（api）/ **常见问题**（faq）/ **运维手册**（runbook）。子类信息写进 `tags`（如 `tags: [runbook]`）便于筛选。
+
+## 完整模板
+
+```markdown
+# Redis Local Installation Guide
+
+## Summary
+
+说明本指南的目标。
+
+## Context
+
+说明本指南的适用场景。
+
+## Prerequisites
+
+列出所需的操作系统、工具、权限和前提假设。
+
+## Steps
+
+提供有序的操作步骤。
+
+## Configuration
+
+记录重要的文件、选项、环境变量或默认值。
+
+## Examples
+
+提供命令或使用示例。
+
+## Validation
+
+说明如何验证结果。
+
+## Troubleshooting
+
+记录常见故障和修复方法。
+
+## References
+
+链接源材料或相关的本地文档。
+```
+
+## 各章节填写要点
+
+| 章节 | 用途 | 注意事项 |
+|------|------|----------|
+| Summary | 指南目标 | 一句话说清读完本文能达成什么 |
+| Context | 适用场景 | 说明前置条件、目标读者、与其他指南的关系 |
+| Prerequisites | 前提条件 | 列出 OS、工具版本、权限、网络要求等 |
+| Steps | 操作步骤 | 有序编号，每步一个明确动作，附预期输出 |
+| Configuration | 配置说明 | 记录需要修改的文件、环境变量、默认值及推荐值 |
+| Examples | 使用示例 | 提供可直接复制运行的命令或代码片段 |
+| Validation | 验证方法 | 说明如何确认操作成功，附验证命令或检查点 |
+| Troubleshooting | 故障排除 | 按症状→原因→修复的格式记录常见问题 |
+| References | 参考资料 | 链接官方文档、相关本地文档或相关代码文件 |
+
+## runbook 子类：运维手册类 guide
+
+运维手册（runbook）是 guide 的子类（用 `tags: [runbook]` 标记），在通用骨架上**必含三要素**：
+
+| 要素 | 对应章节 | 要求 |
+|------|----------|------|
+| 操作步骤 | Steps / Procedure | 有序编号，每步一个明确动作，附预期输出 |
+| 回滚方案 | Rollback | 操作失败或结果异常时如何恢复到操作前状态 |
+| 检查点 | Validation / Verification | 操作前确认前置、操作后确认生效，各给检查命令与判断标准 |
+
+可视场景补充：触发信号（Symptoms——告警/日志特征/监控指标异常）、诊断方法（Diagnosis——确认问题的检查命令与判断标准）、升级路径（Escalation——何时停止自行处理并联系谁）。

package/dist/.claude-template/skills/knowledge-write/template-memory.md

@@ -0,0 +1,61 @@
+# 记忆类文档模板
+
+适用的 `document_type` 值：
+
+```text
+mechanism
+decision
+rule
+lesson
+```
+
+## 完整模板
+
+```markdown
+# DefaultOrderService Exploration Findings
+
+## Summary
+
+陈述持久性结论。
+
+## Context
+
+解释为何进行此探索以及检查了什么范围。
+
+## Findings
+
+记录具体观察结果，而非推测。
+
+## Evidence
+
+引用文件、符号、命令、API 结果或相关代码片段。
+
+## Impact For Future Changes
+
+说明未来 AI/代码变更在编辑前应考虑什么。
+
+## Reuse Guidance
+
+说明另一个 AI 应在何时使用此文档。
+
+## Follow-ups
+
+列出后续工作。
+
+## Open Questions
+
+将未解决的问题与已确认的发现分开跟踪。
+```
+
+## 各章节填写要点
+
+| 章节 | 用途 | 注意事项 |
+|------|------|----------|
+| Summary | 持久性结论 | 写结论而非过程；未来 AI 读到此处即可判断相关性 |
+| Context | 探索原因和范围 | 说明为什么需要探索、检查了哪些文件或模块 |
+| Findings | 具体观察 | 只记录确认的事实，推测放入 Open Questions |
+| Evidence | 证据引用 | 附上文件路径、符号名、命令输出等可验证的信息 |
+| Impact For Future Changes | 未来影响 | 说明修改相关代码前需要考虑什么 |
+| Reuse Guidance | 复用指引 | 说明另一个 AI 在什么场景下应参考此文档 |
+| Follow-ups | 后续工作 | 列出待完成的任务或待验证的假设 |
+| Open Questions | 未解决问题 | 与已确认的 Findings 分开，避免混淆 |