smart
67837df8d0
- 新增全套考试卷、评估卷、参考答案与考试培训包模板 - 修正slidev培训课件：调整模块标题、链路图缩放，替换工单示例为通用业务对象 - 修正课堂红线表述为证据红线，将小组作业调整为个人作业要求 - 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块 - 整理AI工程技能交付包，迁移旧资产至客户专属交付包并统一术语 - 新增考试输出模板与TRAE使用记录文档
134 lines
6.7 KiB
Markdown
134 lines
6.7 KiB
Markdown
---
|
||
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` 报告变更文件。
|
||
|
||
如果用户要求“深度”或“落地”，不要停在单页概览。必须交付生成索引和人类指南。
|