TARE-Learn/deliverables/客户AI工程Skill交付包/skills/project-knowledge-builder/SKILL_zh.md

name, description

name	description
project-knowledge-builder	当用户要求“项目知识库”“看项目”“整理项目”，或需要深度检查软件项目、构建/刷新项目知识库、创建入门文档、架构图、领域词汇表、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。

最小有用集合：

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：

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

Windows PowerShell：

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

常用选项：

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 报告变更文件。

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