前言¶
DeepSeek Harness（DSH）这类 AI 编码代理通常以「生成代码」为主，缺乏对工程流程的约束和检查。在复杂项目中，这种模式容易导致测试不足、代码审查缺失、变更影响范围不清晰，最终增加维护成本。
Supergraph 插件为 DSH 提供了一套工程化工作流，通过强制执行的流程、代码库图智能和 LSP 级别的代码分析，让 AI 编码代理在执行任务时遵循规范的开发步骤。
插件定位与维护¶
Supergraph 是一个面向 AI 编码代理的工程化工作流系统，由维护者 datit309 开发，在 GitHub 上获得 22 个星标，目前版本为 2.3.0。它支持 Claude Code、OpenAI Codex CLI、Google Antigravity、OpenCode 以及 DeepSeek Harness（DSH）等多个平台。
插件的核心目标是将 AI 编码代理从单纯的代码生成器转变为具备工程纪律的协作伙伴，通过强制规划、测试驱动开发（TDD）、验证、审查和架构感知决策，提升代码质量和项目可维护性。
核心能力¶
工程生命周期流程¶
Supergraph 将非平凡变更强制纳入严格的工程生命周期：
scan → analyze → plan → TDD → execute → fix → verify → review
每个环节都有明确的职责和产出，确保变更在进入下一阶段前满足前置条件。
知识图谱与代码智能¶
插件依赖 Codebase Memory MCP（版本 >= 0.10.8,< 0.11.0）在本地索引仓库状态，生成 .codebase-memory/graph.db.zst 文件（缓存位于 ~/.cache/codebase-memory-mcp）。通过 index_repository 命令，插件能够提供数学上的变更影响范围（blast radius）、调用层级、依赖循环和测试覆盖缺口。Serena MCP 提供 LSP 级别的符号导航和诊断能力。
7 个专业子代理架构¶
Supergraph 采用 7 个单职责子代理，实现关注点分离：
plan-writer：分析代码图并制定计划（不编写代码）plan-reviewer：独立审查计划是否符合规范和完整性executor：在隔离的 Git 工作树中执行任务，遵循 TDDqa-tester：生成 ISTQB 测试矩阵，运行自动化的 E2E 浏览器和 API 测试security-auditor：对照 OWASP Top 10、IDOR、SQL 注入等规则审查变更diagnostician：隔离最小可复现案例，科学诊断根本原因code-reviewer：独立评估变更是否符合需求，给出合并意见
浏览器自动化与 QA¶
插件内置基于 Rust CDP 的 browser-agent，使用紧凑的无障碍树快照（@ref）绕过反爬虫检测，生成 5 维 ISTQB 测试矩阵（UI + API + DB 故障注入），并导出结构化的缺陷报告。
多代理编排¶
supergraph-team 提供基于 DAG（有向无环图）的任务调度，支持并发隔离的 Git 工作树，并提供实时仪表板（端口 3333）供监控和调试。
安装与启用¶
通用一键安装¶
macOS、Linux 或 WSL（默认覆盖所有平台）：
curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh
Windows PowerShell 5.1+：
irm https://raw.githubusercontent.com/datit309/supergraph/master/install.ps1 | iex
指定平台安装¶
curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform [claude|codex|antigravity|opencode|dsh|all]
DSH 平台更新¶
DSH 用户可通过以下命令更新插件：
dsh plugin --profile web update supergraph
MCP 依赖安装¶
插件依赖 Codebase Memory MCP：
pip install 'codebase-memory-mcp>=0.10.8,<0.11.0'
codebase-memory-mcp cli index_repository --repo-path "$(pwd)" --name supergraph --mode moderate
可选依赖 Serena MCP：
uv tool install -p 3.13 serena-agent
典型用法¶
完整工作流示例¶
- 扫描项目结构，构建图上下文
/supergraph:scan
- 分析问题与变更影响范围
/supergraph:analyze
- 创建实现计划
/supergraph:plan
- 执行任务（带 TDD 和隔离工作树）
/supergraph:execute
- 自动修复循环
/supergraph:fix
- E2E 浏览器和 API 验证（Rust CDP agent-browser）
/supergraph:browser-agent
- 验证证据与最终审查
/supergraph:verify
/supergraph:review
常用技能清单¶
| 技能 | 用途 | 使用时机 |
|---|---|---|
/supergraph:scan |
扫描项目结构，构建/验证图 | 每次会话开始 |
/supergraph:explore |
代码库探索与架构发现 | 复杂研究且不修改代码 |
/supergraph:analyze |
图风险分析、影响范围、方案选择 | 范围不明确、存在枢纽/桥接节点 |
/supergraph:sdd |
带架构图的软件设计文档 | 正式架构规范 |
/supergraph:plan |
嵌入契约的实现计划 | 任何非平凡变更前 |
/supergraph:tdd |
严格测试驱动开发（RED → GREEN） | 实现功能或修复 Bug |
/supergraph:execute |
多工作器 Wave DAG 执行 | 执行已保存的计划 |
/supergraph:fix |
基于计划的自动修复循环 | 代码变更完成后 |
/supergraph:integration |
集成、契约、DB 测试 | 单元测试通过后 |
/supergraph:browser-agent |
ISTQB QA 测试与浏览器仿真 | E2E Web/API 测试、反爬虫场景 |
/supergraph:video-demo |
叙述式演示视频与 Retina 截图 | 营销视频、功能演示、视觉复现 |
/supergraph:vibesec |
安全审计（OWASP Top 10、IDOR、SQLi） | 安全审查与敏感接口 |
/supergraph:verify |
新的验证证据门 | 宣布完成或提交前 |
/supergraph:review |
独立代码审查与合并意见 | 合并前 |
/supergraph:diagnose |
6 阶段科学调试循环 | 原因不明的 Bug |
/supergraph:serena |
LSP 符号导航与安全重构 | 跨文件复杂重构 |
/supergraph:zoom-out |
领域词汇模块地图 | 在不熟悉的代码中迷失时 |
/supergraph:architecture |
自包含的 HTML 架构报告 | 重构前或新成员入职 |
/supergraph:handoff |
会话上下文压缩 | 会话结束或切换上下文 |
/supergraph:caveman |
Token 压缩模式（约 75% 减少） | 长会话与 Token 效率优化 |
适用场景与注意事项¶
Supergraph 适合需要严格工程流程的大型项目、团队协作场景，以及对测试覆盖率、安全审计和代码审查有较高要求的场景。它特别适用于需要 AI 代理承担更工程化职责的开发工作流。
注意事项：
- 插件以当前 DSH 进程的权限运行，安装前应检查源码与许可证。
- 需要安装 Codebase Memory MCP 依赖（版本范围 >= 0.10.8,< 0.11.0）。
- 插件会定期检查更新（会话启动时，最多每 24 小时一次），可通过设置
SUPERGRAPH_UPDATE_CHECK=false禁用。
价值总结¶
Supergraph 通过流程强制、代码库图智能和多代理编排，将 AI 编码代理从代码生成器转变为具备工程纪律的协作伙伴。它帮助开发者在 AI 辅助编程的同时，保持代码质量、测试覆盖和安全标准。
更多详情与完整示例，可参考官方文档：
- GitHub：https://github.com/datit309/supergraph
- 安装指南：https://github.com/datit309/supergraph/blob/master/docs/INSTALLATION.md
- 工作流示例：https://github.com/datit309/supergraph/blob/master/docs/EXAMPLES.md
- 目录页：https://www.skillhub.cn/plugins/datit309/supergraph
