team-wiki-codebase

name team-wiki-codebase description 让 AI 真正理解大型代码库。针对多仓库、多微服务、迭代多年的项目，通过架构逆向 + Graph RAG 图谱 + CLI 多语言 AST， 将海量代码压缩为结构化知识库——每条结论可回溯代码行，每条关系有置信度标注。 适用场景：项目有 10+ 仓库或微服务，AI 直接读代码无法全局理解、回答不准确、token 开销大。 产出：组件设计文档 × N + 架构总览 + 桥梁文档 + Graph RAG 图谱(G1~G9) + _manifest.json + team-wiki 编译产物。 Trigger: team-wiki-codebase, code-to-knowledge, 代码知识库, 架构分析, 架构逆向 Prerequisites: 可访问的源码目录（支持多仓库）；本 skill 目录下 `references/` 与 `scripts/` team-wiki-codebase — 大型代码库 AI 认知工程 方法论与脚本位于本 skill 的 references/ 、 scripts/ （ team-wiki upgrade 后出现在 .cursor/skills/team-wiki-codebase/ 或 .codebuddy/skills/team-wiki-codebase/ ）。人类可读概览见 README.md 。 图谱 CLI 能力见 GRAPH-CAPABILITIES.md 。 解决什么问题 ：大型项目（10+ 仓库、数十微服务、迭代多年）让 AI 无法全局理解——上下文窗口装不下所有代码，组件关系散落各处，业务规则隐藏在深层调用链中。直接让 AI 读代码，既慢（海量 token）又不准（缺乏全局视角）。 怎么解决 ：通过架构逆向工程，将海量代码系统化压缩为 结构化、可验证、AI-Native 的深度知识库——每个结论可回溯到代码行，每条关系有置信度标注，每次更新有增量校验。AI 读知识库而非读源码，用约 1/50 的 token 获得全局架构认知。 使用方式 /team-wiki-codebase # 默认：Standard（单 session 核心路径） /team-wiki-codebase --deep # Deep：完整 K1~K4 + G1~G9 /team-wiki-codebase --update # 增量更新已有 knowledge/ /team-wiki-codebase continue # 从 _review/progress.json 断点继续 Agent 架构 Agent 文件 启动时机 知识库文档生成 Agent references/agents/kb-doc-generator.md Phase K2 每批组件 Graph RAG Agent references/agents/graph-rag-agent.md Phase K3 主 Agent 职责 ：流程编排、确认点管理、progress.json 维护、质量报告汇总。 入口判断 每次激活时必须先执行此判断。 IF 用户输入包含 "--update" 或 "增量更新": → Update 模式 ELSE IF 用户输入包含 "continue" 或 "继续": → Continue 模式 ELSE: → 检查用户指定目录下是否有 _review/progress.json IF 存在 → 告知状态，等待"继续上次"或"重新开始" ELSE → Phase 0 Continue 模式 Step 1：定位 progress.json Step 2：读取解析，展示恢复摘要 Step 3：根据 current_phase 跳转： "phase0_done" → Phase K1 "phasek1_waiting_confirm" → 展示 k1-architecture-map.md，等待确认① "phasek1_confirmed" → Phase K2 "phasek2_batch_N" → Phase K2 第 N 批继续（跳过已完成） "phasek2_waiting_confirm" → 等待确认② "phasek2_confirmed" → Phase K3 "phasek3_done" → Phase K4 "phasek4_done"/"completed" → 告知完成，询问是否 --update 或重跑某组件 Update 模式（增量更新） 触发 ： /team-wiki-codebase --update 或「增量更新」。 前提 ：已有 completed 状态的 progress.json。 Step 1：读取 progress.json，获取 file_hash_cache Step 2：扫描 project_root，计算各文件当前 SHA256 Step 3：对比 hash，分类：新增 / 修改 / 删除 Step 4：展示变更摘要，等待用户确认： ┌────────────────────────────────────┐ │ 变更摘要 │ │ 新增: N 个文件 │ │ 修改: N 个文件（含 Aurora.py 等） │ │ 删除: N 个文件 │ │ 受影响组件: [列表] │ │ 受影响图谱文档: G1/G2/G6/G7 │ └────────────────────────────────────┘ Step 5：仅重跑受影响范围： - Phase K2：重新生成受影响组件的 Type-4 文档（覆盖写入） - Phase K3 局部：更新涉及变更组件的图谱文档（G1/G2/G6/G7） - Phase K4：重新运行 validate_kb.py Step 6：更新 file_hash_cache + metadata.json commit SHA Step 7：组件级 diff（处理新增/删除仓库或组件） IF repos 列表与上次不同： 新增的仓库 → 对新仓库执行完整 K1 扫描，补充到组件清单，生成 Type-4 文档 删除的仓库 → 对应组件文档顶部加 `⚠️ [DEPRECATED] 此组件对应仓库已移除` → 更新 k1-architecture-map.md 的组件清单 → 更新 G1 矩阵（移除已删除组件的行列，新增新组件行列） progress.json 规范 路径 ： <output_dir>/../_review/progress.json { "version" : "5" , "repos" : [ { "name" : "repo-a" , "path" : "/absolute/path/to/repo-a" , "language" : "go" } , { "name" : "repo-b" , "path" : "/absolute/path/to/repo-b" , "language" : "python" } ] , "output_dir" : "/absolute/path/to/knowledge" , "primary_language" : "go" , "project_name" : "ProjectName" , "scan_time" : "2026-01-01T10:00:00Z" , "current_phase" : "phasek2_batch_2" , "confirmed_phases" : [ "phase0" , "phasek1" ] , "service_map" : { "描述" : "Phase K1 Step 3 构建的服务名→仓库映射表" , "ServiceA" : { "repo" : "repo-a" , "entry" : "cmd/serviceA/main.go" } , "ServiceB" : { "repo" : "repo-b" , "entry" : "app/main.py" } } , "kb_progress" : { "component_total" : 12 , "components_done" : [ "Aurora" , "Frame" ] , "components_pending" : [ "CCDB" , "Dispatcher" ] , "type1_done" : false , "type2_done" : false , "type3_done" : false , "bridge_docs_done" : false , "graph_rag_done" : false } , "accuracy_stats" : { "total_claims" : 0 , "verified" : 0 , "unverified" : 0 , "ambiguous_relations" : 0 } , "interface_coverage" : { "描述" : "接口数量对账结果，由 Phase K2 自校验填充" , "ComponentA" : { "type" : "HTTP" , "scanned" : 13 , "documented" : 0 , "gap" : 13 } , "ComponentB" : { "type" : "MQ" , "scanned" : 5 , "documented" : 0 , "gap" : 5 } } , "consistency_check" : { "描述" : "Phase K3 Step 3 跨文档一致性校验结果" , "contradictions" : 0 , "missing_refs" : 0 , "g1_deviations" : 0 , "consistency_rate" : 0.0 } , "e2e_validation" : { "描述" : "Phase K4 Step 4 AI 端到端验证结果" , "total_questions" : 0 , "correct" : 0 , "partial" : 0 , "incorrect" : 0 , "boundary_ok" : 0 , "boundary_fail" : 0 , "accuracy_rate" : 0.0 } , "file_hash_cache" : { "relative/path/to/file.go" : "sha256_hex" } } accuracy_stats 在每批 Phase K2 完成后累加，是知识库可信度的全局指标。 核心原则（准确性优先） 代码为唯一事实来源 ：每个结论必须有代码文件:行号 作为证据，无法验证的标 [UNVERIFIED] 置信度三态强制 ：图谱中每条关系标 EXTRACTED(1.0) / INFERRED(0.6~0.9) / AMBIGUOUS(0.1~0.3) ；禁止凭空发明，禁止用 0.5 默认值 两级准确性验证 ：Phase K2 每份文档生成后立即自校验；Phase K4 全库质量检验 人在回路两次确认 ：架构理解（K①）和组件文档质量（K②）必须人工确认，防止系统性错误扩散 并行生成 + 断点续传 ：Type-4 组件文档并行分发（同一消息发出所有 Agent calls）；每批持久化 progress.json Token 精简 ： Glob → Grep → Read 三步法，禁止全量目录扫描 诚实审计 ： [UNVERIFIED] 不得隐藏；质量数字完整展示；不确定用 AMBIGUOUS 不删除 认知边界声明 ：知识库 README 必须明确声明覆盖范围和不覆盖范围，让 AI 知道何时应该说"不确定" 跨文档一致性 ：Phase K3 强制交叉比对组件间关系描述，矛盾项必须修复后才计入"一致" 端到端可验证 ：Phase K4 用标准化问题测试知识库实际回答能力，E2E 准确率目标 ≥ 80% Phase 0：初始化 一次性向用户询问以下信息（ 同一条消息，不分步骤 ）： 项目所有代码仓库路径 （用户把整个项目涉及的所有仓库地址列出来）： 格式：每行一个绝对路径，或逗号分隔 示例： /path/to/api-gateway /path/to/order-service /path/to/user-service /path/to/common-lib 说明：这是最关键的一步。大型项目的代码散布在多个仓库中，必须 全部提供 才能构建完整的架构认知。遗漏仓库 = 知识库盲区。 项目名称 （用于文档命名，如 "CVM"、"电商平台"） 产品文档来源 （可选，提供则生成 Type-5/6 桥梁文档）： API 文档目录路径 使用限制 / FAQ 文档路径 输出路径 （默认：第一个仓库的父目录下的 knowledge/ ） Step 0A：仓库清单整理 收到用户提供的仓库列表后，构建仓库清单： FOR 每个用户提供的路径: 1. 验证路径存在且可访问 2. 检测是否为 git 仓库（是否有 .git 目录） 3. 检测主要语言（按文件扩展名分布） 4. 统计代码规模（文件数 + 估算行数） 5. 记录 git commit SHA + tag 结果写入 _review/repo-manifest.json： { "repos": [ { "path": "/absolute/path/to/repo-a", "name": "repo-a", "language": "go", "files": 320, "lines_estimate": 45000, "commit": "abc123", "tag": "v1.2.0", "accessible": true }, ... ], "total_repos": N, "inaccessible": ["path/to/repo-x（权限不足）"] } 展示给用户确认： 已识别 {N} 个仓库： ✅ repo-a (Go, ~45K 行) ✅ repo-b (Python, ~12K 行) ✅ repo-c (Go, ~28K 行) ❌ repo-x (路径不存在或无法访问) 总计: ~{N}K 行代码，{N} 个仓库 确认无误后回复"继续"，或补充遗漏的仓库。 Step 0B：自动检测主要语言 （按仓库列表汇总，不阻断流程）： 检测方法：汇总所有仓库的文件扩展名分布 .go 文件占比最高 → language: "go" .py 文件占比最高 → language: "python" .java 文件占比最高 → language: "java" .ts/.js 文件占比最高 → language: "typescript" .rs 文件占比最高 → language: "rust" 多语言混合（无明显主导） → language: "mixed" 备注：language 字段用于接口扫描时选择 grep 模式（详见 Phase K1 Step 5） Step 0C：记录基准版本 ： # 对每个仓库分别记录 FOR repo in repos: git -C <repo.path> rev-parse HEAD 2>/dev/null git -C <repo.path> describe --tags --always 2>/dev/null 写入 _review/metadata.json ： { "project_name" : "CVM" , "scan_time" : "<ISO8601>" , "repos" : [ { "name" : "repo-a" , "commit" : "<sha>" , "tag" : "<tag>" } , { "name" : "repo-b" , "commit" : "<sha>" , "tag" : "<tag>" } ] } Step 0D：CLI 结构基线（每个代码仓库，推荐） 在 K1 深读之前，用 Team Wiki CLI 生成可证据化的 import/call 结构边（Python/Go/TS 等， code-ast ）并与 regex 基线合并（ code-heuristic ）： # 对每个 repo（<wiki_root> 通常为项目下的 .teamwiki 或 .wiki） team-wiki compile code <repo_abs_path> <wiki_root> \ --project <project_slug> \ --extract ast,heuristic \ --write # 预览 AST 统计（不写盘） team-wiki compile code <repo> <wiki> --extract ast --dry-run 输出： code/<project>/ 下 index/component/relation 等页； graph/<project>-graph-index.json （结构边草案）。 K1/K2/K3 写 _manifest.json 的 edges[] 时： 优先引用 compile 的 code-ast 边 + evidenceRefs （ path:line ），Agent 推断标 INFERRED / AMBIGUOUS 。 K3 完成后写入 wiki 图： team-wiki compile code <output_dir> <wiki_root> --extract ast,heuristic --write （有 _manifest.json 时走 manifest 快路径 merge graph-index.json ）。 写入初始 progress.json（current_phase: "phase0_done"），进入 Phase K1 。 Phase K1：架构逆向与源材料采集 方法论 ： references/methodology/phase0-collection.md + references/methodology/phase1-reverse-engineering.md Step 1：可选运行扫描脚本（推荐） python3 scripts/scan_repo.py <project_root> --depth 2 --top 10 输出：文件统计 + 关键文件发现报告 + 语言分布。 Step 2：关键文件提取 按优先级扫描（详见 phase0-collection.md）： P0 必须 ：入口文件、路由/Handler、流程编排配置、Proto/IDL P1 重要 ：数据库 Schema（DDL）、常量/错误码定义 P2 增强 ：配置文件、测试文件（理解预期行为） Step 3：架构逆向（详见 phase1-reverse-engineering.md） 自底向上分层：叶子节点(DB/MQ) → 中间节点(编排/调度) → 根节点(API入口) 三层穿透追踪：对核心 API ≥5 条完成 API入口→编排层→服务执行层 全链路追踪 构建 N×N 组件关系矩阵（标注通信方式：RPC/MQ/DB） Step 4：生成架构分析报告 写入 _review/k1-architecture-map.md ： ## 架构分层（≥4层） | 层级 | 组件列表 | 核心职责 | 代码仓库 | ## 组件清单 | 组件名 | 架构层级 | **所属仓库** | 语言 | 核心度(P0/P1/P2) | 入口文件 | **接口校验类型** | 接口校验类型取值（在确认点①请用户核对此列）： - `HTTP` → API 接入层，有 HTTP/gRPC 路由注册，需做接口数对账 - `MQ` → 消息处理层，有 MQ Consumer/Exchange 声明，以 Topic 数做基准 - `RPC` → 内部服务层，有 .proto / .thrift / IDL 文件，以 Method 数做基准 - `NONE` → 调度/执行/数据层，无对外接口，不做接口数校验 ## N×N 组件通信矩阵 （值：RPC/MQ/DB/—，标注置信度 [E]EXTRACTED/[I]INFERRED/[A]AMBIGUOUS） ## 核心调用链路（≥5条） （格式：API(file:line) → 编排层(config:line) → 服务层(handler:line) → DB(table)） ## 术语表 | 内部术语 | 外部/产品术语 | 说明 | ## 不确定项（供人工确认） （标注 [A] 的关系和推断，说明不确定原因） （接口校验类型不确定的组件，标注 [?] 等用户在确认点①明确） Step 5：接口清单扫描（按校验类型分别执行） 仅对 k1-architecture-map.md 中接口校验类型 ≠ NONE 的组件执行 ： FOR 每个 接口校验类型 = HTTP 的组件: 执行 grep 扫描： Go: grep -rn "\.GET\|\.POST\|\.PUT\|\.DELETE\|router\.Handle\|@handler" <component_dir> Python: grep -rn "@app\.route\|@router\.\|APIRouter\|include_router" <component_dir> 记录：组件名 → HTTP接口数 N（SCAN_CONFIDENCE: HIGH/MEDIUM） FOR 每个 接口校验类型 = MQ 的组件: 执行 grep 扫描：