YassineZAIBI/ground-truth

# Ground Truth — 一款 Claude Code 插件 ## 功能介绍 在漫长的智能体开发会话之后，你的代码库、`CLAUDE.md` 和 README 彼此之间会开始产生信息漂移。Ground Truth 会将它们协调并整合为三份产出物： - **`BUSINESS_MIRROR.md`** — 面向非技术干系人。“12 项功能中有 9 项已生效。这是最紧急的事项。” - **`GROUND_TRUTH.md``** — 面向工程师。包含引用文件的表格、漂移报告、风险清单和关键路径。 - **`.ground-truth/dashboard.html`** — 单个自包含的交互式页面，包含三个选项卡：**Business / Technical / API tree**，可缩放的 Mermaid 架构图，高风险面板，以及针对各项能力的屏幕截图嵌入功能。 ## 安装 在任意 Claude Code 会话中： ``` /plugin marketplace add YassineZAIBI/ground-truth /plugin install ground-truth ``` ## 使用 ``` /ground-truth # auto-detects: first run if no data, else incremental /ground-truth --auto # skip vocabulary confirmation (CI-friendly) /ground-truth --rebuild # full re-run, ignore cache /ground-truth --since HEAD~10 # incremental from a specific git ref /ground-truth --no-screenshots # skip visual asset scanning /ground-truth --no-endpoints # skip API tree (for non-HTTP projects) /ground-truth --cheap # skip the most expensive LLM stages (Tech window only) ``` 首次运行需要 30-90 秒；随后的增量运行通常在 10-20 秒内完成。 在每次运行结束时，协调器会打印一个可直接点击的 `file://` 链接以访问你的控制面板。**Mac 上按住 Cmd 键点击，Windows 上按住 Ctrl 键点击** 即可直接在浏览器中将其打开。 ## 验证你的控制面板是否为官方版本 如果你的控制面板没有三个选项卡 (Business / Technical / API tree)，或者缺少 Mermaid 图表，则说明有某个智能体绕过了官方渲染器。请运行： ``` python3 .claude/plugins/ground-truth/skills/ground-truth/scripts/verify.py ``` 如果控制面板不是官方模板，该命令将以非零状态退出并列出缺失的部分。要重新生成： ``` python3 .claude/plugins/ground-truth/skills/ground-truth/scripts/render.py ``` 或者直接运行 `/ground-truth --rebuild`。 ## 写入内容 ``` your-project/ ├── GROUND_TRUTH.md ← commit this ├── BUSINESS_MIRROR.md ← share this └── .ground-truth/ ← gitignored ├── data.json shared state across runs ├── voice.yaml project vocabulary (edit by hand) ├── dashboard.html open in any browser ├── drift-report.md deep dive on drift └── history/.json archived runs ``` ## 处理管道 (8 个阶段，尽可能并行) 1. **voice-harvester** (LLM，仅首次运行，会询问用户) — 挖掘项目词汇表 2. **cartographer** (确定性) — 文件清单 + 依赖图 3. **endpoint-cartographer** (确定性) — 提取所有 HTTP endpoint 4. **archaeologist + drift-detector + business-translator** (LLM，**通过 subagent 并行**) 5. **triage-medic** (确定性) — 分配 live/unverified/half-built/broken/dead 状态 6. **risk-analyst** (混合) — 计算关键路径 + 排名前 5 的风险 7. **screenshot-scanner** (确定性) — 嵌入可选的可视化资产 8. **renderer** (确定性) — 使用锁定的模板生成所有产出物 ## 添加屏幕截图 将 PNG/JPG 文件放入以下任一位置，并以抽象概念名称命名： - `docs/screenshots/.png` - `public/screenshots/.png` - `.ground-truth/screenshots/.png` 渲染器会将它们以 base64 格式嵌入到 `dashboard.html` 中，使其保持为一个独立的单文件。 ## 编辑项目的表达风格 首次运行后，`.ground-truth/voice.yaml` 文件将被创建。编辑其中的任意字段，保存后运行 `/ground-truth --rebuild`。此后，两个视图中都会使用你设定的名词术语。 ## 支持的框架 (endpoint 发现) - Next.js App Router (`app/**/route.ts`) - Next.js Pages Router (`pages/api/**`) - FastAPI (`@app.get`, `@router.post`, 等) - Flask (`@app.route`, `@bp.route`) - Express (`app.get`, `router.post`) 要添加新框架，请编辑 `skills/ground-truth/scripts/endpoints.py` — 每个框架对应一个正则表达式。 ## Token 经济学 该处理管道专为低成本的每周运行而设计： - **确定性阶段从不调用 LLM。** Cartographer、Endpoint Cartographer、Triage、Risk 评分、Screenshot 扫描器和 Renderer 全部都是 Python 脚本。 - **LLM 阶段仅针对脏数据。** 在增量运行中，只会重新评估自上次提交以来发生更改的抽象和文档。缓存记录将被原样复用。 - **并行的 subagent。** 漂移检测器和业务翻译器通过 Task 工具并发运行，因为它们共享输入但产生互不交叉的输出。 - **`--cheap` 标志** 会跳过漂移检测器和业务结果，以实现超快运行（成本约为首次完整运行的 5-10%）。 ## 限制 - **仅支持静态分析。** 分诊检查仅涉及导入 + 测试 + TODO 密度。它不会运行你的代码。 - **Mermaid 布局存在限制。** 当抽象超过约 20 个时，自动布局会变得十分拥挤。该 skill 在设计上上限为 15 个。 - **漂移检测的效果取决于你的文档质量。** 空的 README 意味着没有可以检测漂移的参考基准。skill 会在 `unknowns[]` 中记录这一缺失。 ## 许可证 MIT。尽情 Fork、修改并发布吧。 ## 贡献 欢迎提交 Bug 和功能请求。该处理管道有意设计为模块化：每个阶段都是一个独立的 SKILL.md 提示词 +（可选的）一个 Python 脚本。

标签：AI编程助手, API管理, Claude, CVE检测, HTML看板, Markdown, Mermaid, 云安全监控, 云资产清单, 代码分析, 代码审查, 代码库管理, 代码维护, 凭证管理, 多模态安全, 威胁情报, 开发者工具, 技术文档, 插件, 数据管道, 文档漂移, 文档生成, 架构图, 网络调试, 自动化, 软件工程, 软件开发, 逆向工具, 逆向工程, 静态分析, 项目文档, 风险检测