| 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/ 子目录，而不是直接删除。
具体动作：
- 将文档移到对应主题域下的
archive/ 子目录（如 knowledge/permission/archive/xxx.md）。子目录不存在时新建
- 在文档顶部一级标题之下增加过时声明（blockquote 引用），格式参考已有归档文档：
- 方案被替代：
> ⚠️ 已过时 — 本文档描述的是 X 方案，已被 Y 替代。当前方案见 \knowledge/.../新文档.md`。保留供回查历史问题。`
- 能力已下线：
> ⚠️ 已过时 — 本文档描述的能力已下线，保留供历史回查。
knowledge/README.md 同步：
- 从主索引表「知识目录」中移除该条目
- 在「已过时文档（Archive）」表中追加条目，「替代文档」列填新文档路径或
—（无替代时）
不直接删除的理由：归档保留了历史决策的可追溯性。当未来读者疑惑"为什么之前是这样设计"或排查老 bug 时，archive 里的文档是唯一一手来源；删掉后这些上下文只能靠翻 git history 还原，成本高得多。
命名与目录约定
- 文件名统一使用 kebab-case（如
biz-token-expired-callback.md）
- 目录名同样使用 kebab-case
| 类型 | 目录 |
|---|
| 组件/功能 | knowledge/[模块名]/ |
| 架构设计 | knowledge/architecture/ |
| 开发指南 | knowledge/guides/ |
注意事项
- 优先更新已有知识文档，再考虑新增
- 增量修改，不重写整个文档
- 大范围更新前先征求用户确认
