smart
67837df8d0
- 新增全套考试卷、评估卷、参考答案与考试培训包模板 - 修正slidev培训课件：调整模块标题、链路图缩放，替换工单示例为通用业务对象 - 修正课堂红线表述为证据红线，将小组作业调整为个人作业要求 - 新增权限、状态流转、审计日志、看板指标四类可复用业务规则块 - 整理AI工程技能交付包，迁移旧资产至客户专属交付包并统一术语 - 新增考试输出模板与TRAE使用记录文档
134 lines
7.4 KiB
Markdown
134 lines
7.4 KiB
Markdown
---
|
|
name: project-knowledge-builder
|
|
description: Use when a user asks “项目知识库”, “看项目”, “整理项目”, or otherwise wants to inspect a software project deeply, build/refresh a project knowledge base, create onboarding docs, architecture maps, domain glossaries, ADRs, generated API/config/database indexes, or RAG-ready repository documentation.
|
|
---
|
|
|
|
# Project Knowledge Builder
|
|
|
|
## Overview
|
|
|
|
Build a source-grounded project knowledge base that helps humans and AI agents understand, extend, troubleshoot, and index a codebase. Treat the knowledge base as a maintained system artifact, not a README rewrite.
|
|
|
|
## Quick Use
|
|
|
|
Users should not need to remember commands, script paths, or `$project-knowledge-builder`.
|
|
|
|
The shortest trigger is enough:
|
|
|
|
- `项目知识库`
|
|
|
|
Treat the current repository as the target and `docs/project-knowledge/` as the output path unless the user says otherwise. Run the bundled inventory script yourself and write the docs. Only show manual commands when the user explicitly asks for command-line usage.
|
|
|
|
## Language And Audience Defaults
|
|
|
|
If the user writes in Chinese or asks for Chinese, write human-facing narrative docs in Chinese by default: README, context, architecture, runtime, backend, frontend, data, auth/permissions, extension, troubleshooting, RAG guidance and ADRs. Keep source paths, class names, commands, API paths, config keys, table names, permission codes and metadata enum values unchanged.
|
|
|
|
Treat beginners as a primary audience. A useful knowledge base should let a new maintainer answer four questions without extra coaching:
|
|
|
|
1. What is this project and where are the main modules?
|
|
2. How do I run it locally or identify the active runtime mode?
|
|
3. How do I find the backend endpoint, frontend page, database table and permission code for a feature?
|
|
4. What must change when adding a normal feature, especially menu/button permissions?
|
|
|
|
Do not make generated indexes overly friendly at the cost of precision. Keep generated files machine-refreshable; make narrative docs readable.
|
|
|
|
## Core Rule
|
|
|
|
Every claim must be traceable to the repository or to an explicitly marked inference. Prefer source paths, commands, generated inventories, and unresolved-question lists over confident prose.
|
|
|
|
## Workflow
|
|
|
|
1. **Set scope.** Confirm or assume the output location. Default to `docs/project-knowledge/`. If the user mentions RAG, Feishu/Lark, Dify, Notion, onboarding, architecture review, or API docs, tailor the output contract.
|
|
2. **Read local instructions first.** Check root docs plus `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.codex/`, `.agents/`, package manifests, build files, env examples, Docker files, and module READMEs.
|
|
3. **Generate an inventory.** Run `scripts/project_inventory.py` from this skill against the repo. Use its output as a factual base, then inspect important files manually.
|
|
4. **Map contexts.** Identify bounded contexts, runtime modes, major modules, owners implied by paths, external systems, and data stores. Use `CONTEXT.md` and `CONTEXT-MAP.md` style docs.
|
|
5. **Extract generated indexes.** Produce machine-refreshable docs where possible: endpoints, frontend routes/views, config keys, env variables, database tables, permission codes, scheduled jobs, queues, and extension points.
|
|
6. **Write human guides.** Produce onboarding, architecture, local run/deploy, data model, auth/permission, extension, troubleshooting, and glossary docs. Match the user's language for narrative docs; for Chinese users, use Chinese section titles such as `已观察来源`, `核心事实`, `操作影响`, and `未知与风险`.
|
|
7. **Create ADRs for real decisions.** Record important architecture decisions already embodied in the code. Do not invent future decisions unless marked as proposed.
|
|
8. **Add RAG metadata guidance.** Include chunking, source-path metadata, stale-data policy, and exclusion rules.
|
|
9. **Verify.** Re-run the inventory, scan docs for placeholders, broken relative links, stale paths, and unsupported claims. Report what was verified and what remains uncertain.
|
|
|
|
## Output Contract
|
|
|
|
Read `references/output-contract.md` when creating or upgrading a full knowledge base.
|
|
|
|
Minimum useful set:
|
|
|
|
```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
|
|
```
|
|
|
|
Scale down only if the repo is small or the user requests a lighter artifact.
|
|
|
|
## Source-Grounding Standards
|
|
|
|
- Cite source paths inline for non-obvious claims.
|
|
- Distinguish **Observed** from **Inferred** and **Unknown**.
|
|
- Do not summarize generated code, dependencies, or configs from memory. Read them.
|
|
- If external docs are needed for unstable facts, browse primary sources and link them.
|
|
- Preserve project-specific conventions. If a repo requires trace comments, ADR format, or issue IDs, document and follow that.
|
|
|
|
## Cross-Platform Compatibility
|
|
|
|
Read `references/compatibility.md` when the user asks about macOS, Windows, Linux, CI, portability, or installing/running the skill across machines. The bundled inventory script is intended to run on Python 3.9+ with only the standard library.
|
|
|
|
## Inventory Script
|
|
|
|
Use this only for manual refreshes or when the user asks for the command. Run from the target repo:
|
|
|
|
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
|
|
```
|
|
|
|
Useful options:
|
|
|
|
```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
|
|
```
|
|
|
|
The script is a starting point, not a replacement for reading core files. Inspect representative files before writing narrative docs.
|
|
|
|
## Quality Gates
|
|
|
|
Before final response:
|
|
|
|
- List generated docs with a platform-appropriate command, such as `find docs/project-knowledge -type f | sort` on macOS/Linux or `Get-ChildItem docs/project-knowledge -Recurse -File` on PowerShell.
|
|
- `rg -n "TODO|TBD|待补|unknown|your/path|foo|bar" docs/project-knowledge`
|
|
- Re-run the inventory script after edits.
|
|
- Check that top-level README links resolve.
|
|
- If the user is Chinese, scan narrative docs for English-only structural headings such as `Observed Sources`, `Core Facts`, `Operational Implications`, `Unknowns/Risks`, `Architecture`, `Runtime`, `Backend`, `Frontend`, `Troubleshooting`, and translate them unless they are code, metadata, or generated output.
|
|
- Check newcomer usefulness: README gives a reading order; runtime doc names local/Docker/cloud modes; auth doc explains menu/button permission flow; extension doc explains backend CRUD, frontend page and permission changes.
|
|
- `git status --short` to report changed files.
|
|
|
|
If the user asked for “deep” or “落地”, do not stop at a single overview. Deliver generated indexes plus human guides.
|