---
name: update-project-knowledge
description: "检查已完成的项目工作，并仅在产生已确认、长期有效的信息时更新现有项目知识库。仅在用户显式调用 $update-project-knowledge 进行任务结束或每日收尾检查时使用。"
---

# 更新项目知识库

检查本次任务或当天工作，并按需同步到项目已有的结构化知识文档。

## 定位项目

1. 如果用户指定了项目路径，优先使用该路径。
2. 否则从当前目录识别 Git 仓库根目录。
3. 如果当前目录不是 Git 仓库，在工作区内浅层查找：
   - 只有一个仓库时，使用该仓库；
   - 存在多个仓库时，让用户选择；
   - 没有仓库时，将当前项目目录作为目标。
4. 记录目标项目的绝对路径，后续检查只针对该项目。
5. 读取该项目适用的 `AGENTS.md`。

不要根据文件夹名称猜测项目位置。

## 定位知识库

按照以下顺序确定知识库位置：

1. 优先使用用户明确指定的目录。
2. 检查 `AGENTS.md` 是否声明了知识库路径。
3. 检查项目中的 `docs/INDEX.md`、`docs/index.md` 或其他文档索引。
4. 如果存在多个可能的知识库，先让用户选择。
5. 如果不存在知识库或文档结构无法确认，停止执行并说明需要先建立知识库。

本 Skill 只更新已有知识库，不擅自创建新的知识库结构。

## 检查当前状态

执行前记录项目和知识文档已有的未提交变更，不覆盖或回退用户原有修改。

以只读方式检查：

- 当前对话中已经完成的工作；
- 当前项目的 `git status --short`；
- 与本次任务相关的 `git diff`；
- 本次任务修改过的文件；
- 已执行的编译、测试或验证结果；
- 必要时检查与本次任务相关的最近提交。

如果项目不是 Git 仓库，则根据当前对话、文件修改和验证结果判断。

不要默认扫描整个项目或整个知识库。

## 判断是否需要更新

只记录已经确认、以后仍然有用的信息，例如：

- 项目目标、业务场景或主要工作流程变化；
- 模块职责、依赖关系、调用关系或数据流变化；
- 接口、协议、数据结构、单位、坐标系或输入输出变化；
- 已经确认的技术决策及其限制；
- 已定位并验证的问题、原因和解决方案；
- 实际完成进度、当前阻塞项和下一步变化。

如果没有产生长期有效的信息，不修改任何文档，并报告“本次无需更新知识库”。

## 选择文档

优先读取知识库索引，根据索引确定需要修改的文档。

如果项目采用以下常见文档，可以参考对应关系：

- `overview.md`：项目背景、目标、场景和整体流程；
- `architecture.md`：目录结构、模块职责、依赖、调用关系和数据流；
- `interfaces.md`：接口、协议、数据结构、单位和输入输出；
- `decisions.md`：技术决策、原因、替代方案和限制；
- `problems.md`：问题现象、根因、解决方法和验证结果；
- `progress.md`：已完成、进行中、阻塞项和下一步；
- `INDEX.md`：知识库导航和文档职责。

这些文件名不是强制要求。项目已有其他结构时，遵循现有索引和文档约定。

只读取并修改与本次变化直接相关的文档，不要默认读取整个知识库。

## 记录原则

- 只记录能够从代码、配置、测试结果、Git 变更或用户确认中得到支持的信息。
- 重要结论尽量标注相关文件路径、模块、类名或方法名。
- 无法确认的信息标记为“待确认”，不得自行补全。
- 区分“已经实施”和“计划采用”。
- 区分“已解决”和“待解决”。
- 只修改相关章节，不重写整个文档。
- 避免在多个文档中重复保存相同内容。
- 进度文档只保存当前状态，不积累成长篇开发日志。
- 保留文档原有语言、结构和写作风格。

## 不应记录

不要记录：

- 普通聊天和临时想法；
- 尚未验证的猜测；
- 没有长期参考价值的失败尝试；
- 冗长终端输出、编译日志和完整代码；
- 可以直接从代码中轻易查到的低价值细节；
- 密钥、密码、令牌、私有地址和个人路径。

## 安全限制

- 只允许修改已经确认的知识库目录。
- 不修改业务代码、配置文件、测试和构建脚本。
- 不修改任何 `AGENTS.md`。
- 不删除、移动或重命名现有文件。
- 不覆盖或回退执行前已经存在的用户改动。
- 不扫描 `.git`、日志、缓存、编译产物和第三方依赖。
- 不读取或修改目标项目之外的其他项目，除非用户明确要求。
- 发现知识文档与当前代码存在明显冲突时，说明冲突并保留依据，不直接覆盖原结论。

## 完成检查

完成后检查本次产生的文件差异，并报告：

1. 本次是否需要更新知识库；
2. 修改了哪些知识文档；
3. 新增或修正了哪些长期信息；
4. 哪些信息仍然待确认；
5. 本次 Skill 是否只修改了知识库目录；
6. 工作区中是否存在执行前就已经存在的其他改动。