---
name: project-knowledge-builder
description: 当用户要求“项目知识库”“看项目”“整理项目”，或需要深度检查软件项目、构建/刷新项目知识库、创建入门文档、架构图、领域词汇表、ADR、API/配置/数据库生成索引或 RAG 友好仓库文档时使用。
---

# 项目知识库构建

## 概览

构建一个有源码依据的项目知识库，帮助人和 AI 理解、扩展、排障和索引代码库。把知识库视为持续维护的系统资产，而不是 README 改写。

## 快速使用

用户不需要记住命令、脚本路径或 `$project-knowledge-builder`。

最短触发语即可：

- `项目知识库`

除非用户另有说明，将当前仓库作为目标，输出到 `docs/project-knowledge/`。由你运行 bundled inventory 脚本并写文档。只有用户明确要求命令行用法时，才展示手工命令。

## 语言和受众默认值

如果用户使用中文或要求中文，人类阅读的叙述文档默认使用中文：README、上下文、架构、运行、后端、前端、数据、认证/权限、扩展、排障、RAG 指南和 ADR。源码路径、类名、命令、API 路径、配置键、表名、权限码、元数据枚举值保持原样。

把新维护者作为主要受众。一个有用的知识库应该让新人无需额外辅导就能回答四个问题：

1. 这个项目是什么，主要模块在哪里？
2. 如何本地运行，或如何识别当前运行模式？
3. 如何找到某个功能对应的后端接口、前端页面、数据库表和权限码？
4. 新增普通功能时通常需要修改什么，尤其是菜单/按钮权限？

生成索引不要为了友好而牺牲精确性。生成文件要便于机器刷新；叙述文档要便于人阅读。

## 核心规则

每个结论都必须能追溯到仓库，或明确标记为推断。优先使用源码路径、命令、生成索引和未解决问题清单，而不是自信散文。

## 工作流

1. **设定范围。** 确认或默认输出位置为 `docs/project-knowledge/`。如果用户提到 RAG、飞书/Lark、Dify、Notion、入门、架构 Review 或 API 文档，调整输出契约。
2. **优先读取本地说明。** 检查根文档，以及 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`.codex/`、`.agents/`、包管理文件、构建文件、env 示例、Docker 文件和模块 README。
3. **生成 inventory。** 对目标仓库运行本 Skill 的 `scripts/project_inventory.py`。用输出作为事实基础，再人工检查关键文件。
4. **映射上下文。** 识别限界上下文、运行模式、主要模块、路径暗示的 owner、外部系统和数据存储。使用 `CONTEXT.md` 和 `CONTEXT-MAP.md` 风格文档。
5. **提取生成索引。** 尽可能产出可机器刷新的文档：接口、前端路由/视图、配置键、环境变量、数据库表、权限码、定时任务、队列、扩展点。
6. **编写人类指南。** 产出入门、架构、本地运行/部署、数据模型、认证/权限、扩展、排障和术语表文档。按用户语言书写；中文用户使用 `已观察来源`、`核心事实`、`操作影响`、`未知与风险` 等标题。
7. **为真实决策创建 ADR。** 记录当前代码已经体现的重要架构决策。不要发明未来决策，除非标为 proposed。
8. **添加 RAG 元数据指南。** 包括切块、source-path metadata、过期策略和排除规则。
9. **验证。** 重新运行 inventory，扫描占位符、坏链接、过期路径和无依据结论。报告已验证内容和仍不确定内容。

## 输出契约

创建或升级完整知识库时读取 `references/output-contract_zh.md`。

最小有用集合：

```text
docs/project-knowledge/
├── README.md
├── CONTEXT.md
├── CONTEXT-MAP.md
├── 01-architecture.md
├── 02-runtime.md
├── 03-backend.md
├── 04-frontend.md
├── 05-data-and-migrations.md
├── 06-auth-permissions.md
├── 07-extension-guide.md
├── 08-troubleshooting.md
├── 09-rag-indexing.md
├── adr/
│   └── 0001-current-runtime-architecture.md
└── generated/
    ├── project-inventory.md
    ├── backend-endpoints.md
    ├── frontend-routes.md
    ├── config-reference.md
    ├── database-dictionary.md
    └── permission-codes.md
```

只有仓库较小或用户要求轻量产物时，才缩小范围。

## 来源依据标准

- 非显然结论必须内联引用来源路径。
- 区分 **已观察**、**推断** 和 **未知**。
- 不要凭记忆总结生成代码、依赖或配置，必须读取。
- 如果不稳定事实需要外部文档，浏览一手来源并附链接。
- 保留项目专用约定。如果仓库要求追踪注释、ADR 格式或 issue ID，记录并遵守。

## 跨平台兼容

当用户询问 macOS、Windows、Linux、CI、可移植性或跨机器安装/运行时，读取 `references/compatibility_zh.md`。bundled inventory 脚本面向 Python 3.9+，只使用标准库。

## Inventory 脚本

仅在手工刷新或用户询问命令时展示。请在目标仓库运行：

macOS/Linux：

```sh
python3 /path/to/skill/scripts/project_inventory.py --root . --out docs/project-knowledge/generated
```

Windows PowerShell：

```powershell
py -3 C:\path\to\skill\scripts\project_inventory.py --root . --out docs\project-knowledge\generated
```

常用选项：

```sh
python3 /path/to/skill/scripts/project_inventory.py --root . --out ./kb-inventory --json
python3 /path/to/skill/scripts/project_inventory.py --root . --out docs/project-knowledge/generated --max-files 20000
```

脚本只是起点，不能替代阅读核心文件。编写叙述文档前，必须检查代表性文件。

## 质量门禁

最终回复前：

- 用适合平台的命令列出生成文档，例如 macOS/Linux 使用 `find docs/project-knowledge -type f | sort`，PowerShell 使用 `Get-ChildItem docs/project-knowledge -Recurse -File`。
- 执行 `rg -n "TODO|TBD|待补|unknown|your/path|foo|bar" docs/project-knowledge`。
- 编辑后重新运行 inventory 脚本。
- 检查顶层 README 链接是否可解析。
- 如果用户是中文用户，扫描叙述文档中是否仍有英文结构标题，例如 `Observed Sources`、`Core Facts`、`Operational Implications`、`Unknowns/Risks`、`Architecture`、`Runtime`、`Backend`、`Frontend`、`Troubleshooting`，除代码、元数据或生成输出外应翻译。
- 检查新人可用性：README 给出阅读顺序；运行文档说明本地/Docker/云端模式；权限文档说明菜单/按钮权限流；扩展文档说明后端 CRUD、前端页面和权限变更。
- 使用 `git status --short` 报告变更文件。

如果用户要求“深度”或“落地”，不要停在单页概览。必须交付生成索引和人类指南。