knowledge-manager

name	knowledge-manager
description	项目知识库（知识文档）的更新与沉淀。在代码变更后或对话中产生有价值的业务知识时，应使用此 skill 沉淀知识。以下场景应主动考虑提醒触发：用户提到业务背景或设计决策等代码外知识、用户明确要求记录信息或沉淀文档、完成较大功能开发后。

知识库管理

管理 knowledge/ 目录下的项目知识文档。

知识更新流程

0. 初始化知识库（仅首次使用）

knowledge/README.md 不存在时执行 references/initialization.md，完成后继续第 1 步；存在则跳过本步。

1. 获取变更信息

git diff --name-only
git diff --cached --name-only

从当前会话提取：新增/修改的功能、涉及的核心文件、关键设计决策。

2. 检测已有知识是否需要更新

使用 code-explorer subAgent 搜索 knowledge/ 目录，避免文档内容进入主上下文。

3. 判断是否有新知识需要沉淀

• 需要沉淀：复杂业务逻辑、重要设计决策、易踩坑的注意事项
• 不需要沉淀：简单 bug 修复、纯重构、临时调试代码

4. 输出结果

列出需要更新/新增的知识文档及原因，征求用户确认后再执行。无需处理时不输出提示。

5. 撰写/修改知识文档

执行前读取 references/writing-guidelines.md 获取沉淀原则与写作规范。

若项目为前后端分离场景且沉淀内容涉及后台字段 / 接口 / 后台行为，额外读取 references/frontend-backend-collection.md 获取对应的采集模板。

6. 更新知识索引（闭环）

新增/更新知识文档后，必须同步更新 knowledge/README.md 中的知识索引表。

知识归档流程

与「知识更新流程」并列、独立触发。当一份文档不再代表当前事实时（方案被替代 / 能力下线 / 业务逻辑废弃）走此流程。移动到同主题域下的 archive/ 子目录，而不是直接删除。

具体动作：

1. 将文档移到对应主题域下的 archive/ 子目录（如 knowledge/permission/archive/xxx.md）。子目录不存在时新建
2. 在文档顶部一级标题之下增加过时声明（blockquote 引用），格式参考已有归档文档：
   • 方案被替代：> ⚠️ 已过时 — 本文档描述的是 X 方案，已被 Y 替代。当前方案见 \knowledge/.../新文档.md`。保留供回查历史问题。`
   • 能力已下线：> ⚠️ 已过时 — 本文档描述的能力已下线，保留供历史回查。
3. knowledge/README.md 同步：
   • 从主索引表「知识目录」中移除该条目
   • 在「已过时文档（Archive）」表中追加条目，「替代文档」列填新文档路径或 —（无替代时）

不直接删除的理由：归档保留了历史决策的可追溯性。当未来读者疑惑"为什么之前是这样设计"或排查老 bug 时，archive 里的文档是唯一一手来源；删掉后这些上下文只能靠翻 git history 还原，成本高得多。

命名与目录约定

• 文件名统一使用 kebab-case（如 biz-token-expired-callback.md）
• 目录名同样使用 kebab-case

类型	目录
组件/功能	knowledge/[模块名]/
架构设计	knowledge/architecture/
开发指南	knowledge/guides/

注意事项

1. 优先更新已有知识文档，再考虑新增
2. 增量修改，不重写整个文档
3. 大范围更新前先征求用户确认