---
name: init-project-knowledge
description: "首次分析现有项目，创建或完善 AGENTS.md 和结构化项目知识库，并根据真实代码和资料进行初步填充。仅在用户显式调用 $init-project-knowledge 建立项目知识库时使用，不用于日常更新。"
---

# 初始化项目知识库

分析当前项目，建立一套轻量、结构化、可版本管理并适合 Codex 长期使用的项目知识库。

## 定位项目

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

不要根据文件夹名称猜测项目位置、技术栈或用途。

## 检查现有知识库

检查项目是否已经存在：

- `AGENTS.md`；
- `docs/INDEX.md` 或其他文档索引；
- 项目概览、架构、接口、决策、问题和进度文档；
- 其他具有相同用途的知识文档。

如果已经存在完整知识库，不重复初始化，并建议使用 `$update-project-knowledge`。

如果知识库只完成了一部分，保留已有内容，只创建缺失文件并补充必要信息。

## 确定知识库位置

按照以下顺序选择知识库目录：

1. 用户明确指定的目录；
2. 现有 `AGENTS.md` 声明的知识库目录；
3. 已经存在并承担项目文档用途的 `docs/`；
4. 默认使用项目根目录下的 `docs/`。

如果现有 `docs/` 已经用于其他用途，并且直接加入知识库可能造成混乱，先向用户确认是否使用：

```text
docs/project-knowledge/
```