工程工作流 datit309/supergraph

面向 AI 编程智能体的 Supergraph

Tiếng Việt · 安装指南 · 工作流示例 · 团队配置

把 AI 编程智能体从代码生成器，变成有纪律的工程工作流系统。

Supergraph 用强制工作流、图智能和 LSP 驱动的代码分析，在 Claude Code、OpenAI Codex CLI、Google Antigravity、OpenCode 和 DeepSeek Harness（DSH）上强制执行规划、TDD、验证、评审和架构感知决策。

Supergraph 做什么

每个非平凡改动都走严格的工程生命周期：

scan → analyze → plan → TDD → execute → fix → verify → review

- 知识图谱与代码智能：由 Codebase Memory MCP（>= 0.10.8,<0.11.0）驱动。通过 index_repository 把仓库状态在本地索引到 .codebase-memory/graph.db.zst（缓存位于 ~/.cache/codebase-memory-mcp），提供数学化的爆炸半径、调用层级、依赖环和测试缺口。Serena 提供 LSP 级符号导航与诊断。
- 7 个子代理的专用架构：自主分离关注点——plan-writer（规划）、plan-reviewer（规格检查）、executor（TDD 执行）、qa-tester（E2E 浏览器/API 测试）、security-auditor（OWASP/Vibesec 应用安全）、diagnostician（根因调试）、code-reviewer（独立合并裁决）。
- 自主人类浏览器智能体与 QA（browser-agent）：原生 Rust CDP（agent-browser，零 Playwright）。用紧凑的无障碍树快照（@ref），借真实用户配置档绕过反爬墙，生成 5 维 ISTQB 测试矩阵（UI + API + DB 故障注入），并导出结构化缺陷报告。
- 多智能体编排（supergraph-team）：波次 DAG 任务调度，隔离 Git worktree，实时仪表盘（:3333）。

Windows 钩子行为

在 Windows 上，hooks/run-hook.cmd 会在标准路径和用户级路径中动态查找 Git Bash。找不到 Git Bash 时，钩子跳过并给出警告，平台执行不被阻塞。

支持的平台

| 平台 | 配置 | 指令文件 |
| Claude Code | Marketplace / 插件 | CLAUDE.md |
| OpenAI Codex CLI | Marketplace / 本地安装器 | AGENTS.md |
| Google Antigravity | 本地安装器 | AGENTS.md |
| OpenCode | 本地安装器（/skills） | OPENCODE.md |
| DeepSeek Harness (DSH) | 原生 Cordis Bundle（cordis.patch.yml） | AGENTS.md |

快速安装（一条命令）

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 安全提示：把远程代码通过管道交给 shell 执行之前，先检查安装脚本。

安装到指定平台：
curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform [claude|codex|antigravity|opencode|dsh|all]

自动更新提醒

Supergraph 在 SessionStart 检查新版本（最多每 24 小时一次）。更新命令： Claude Code: /plugin marketplace update supergraph Codex: codex plugin marketplace upgrade supergraph Antigravity: curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform antigravity OpenCode: curl -fsSL https://raw.githubusercontent.com/datit309/supergraph/master/install.sh | sh -s -- --platform opencode DSH: dsh plugin --profile web update supergraph 设置 SUPERGRAPH_UPDATE_CHECK=false 可关闭检查。注意：OpenCode 目前没有提供 SessionStart 钩子。

👉 手动克隆和各平台的详细步骤，见 docs/INSTALLATION.md。

MCP 配置

1. Codebase Memory MCP (Required)
pip install 'codebase-memory-mcp>=0.10.8,<0.11.0'
codebase-memory-mcp cli index_repository --repo-path "$(pwd)" --name supergraph --mode moderate

2. Serena MCP (Optional, LSP symbol navigation)
uv tool install -p 3.13 serena-agent

3. Supergraph Team MCP & Browser Agent (Built-in)
Automatically bundled across all platforms with live dashboard (:3333).

快速开始

1. Start session — scan graph context /supergraph:scan

2. Analyze problem & blast radius
/supergraph:analyze

3. Create implementation plan
/supergraph:plan

4. Execute with isolated git worktrees & TDD
/supergraph:execute

5. Auto-fix loop
/supergraph:fix

6. E2E Browser & API verification (Rust CDP agent-browser)
/supergraph:browser-agent

7. Verification evidence & review
/supergraph:verify
/supergraph:review

👉 完整操作演示，见 docs/EXAMPLES.md。

技能目录

| 技能 | 用途 | 何时使用 |
| /supergraph:scan | 扫描项目结构，构建并校验图谱 | 每次会话开始时 |
| /supergraph:explore | 代码库探索与架构发现 | 需要深入研究、但不改动代码时 |
| /supergraph:analyze | 图谱风险分析、影响范围、可选方案 | 范围不明确，或涉及枢纽/桥接节点 |
| /supergraph:sdd | 带 schema 的软件设计文档 | 需要正式架构规格时 |
| /supergraph:plan | 内嵌契约的实施计划 | 任何非平凡改动之前 |
| /supergraph:tdd | 严格测试驱动开发（RED → GREEN） | 实现任何功能或修复缺陷时 |
| /supergraph:execute | 多 worker Wave DAG 执行（Worktrees） | 执行已保存的计划 |
| /supergraph:fix | 感知计划的自动修复循环（测试、lint、格式化） | 代码改动完成后 |
| /supergraph:integration| 集成测试、契约测试与数据库测试 | 单元测试通过后 |
| /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 部署 7 个专用子代理，每个只负责一件事：

1. plan-writer： 分析代码图谱并撰写计划（从不写代码）。
2. plan-reviewer： 独立评审计划，检查是否符合规格、是否完整。
3. executor： 在隔离的 git worktree 内执行任务，严格遵循 TDD。
4. qa-tester： 生成 ISTQB 测试矩阵，自主运行 E2E 浏览器与 API 测试。
5. security-auditor： 按 OWASP Top 10、IDOR、注入与密钥泄露审计 diff。
6. diagnostician： 隔离最小复现，科学诊断根因。
7. code-reviewer： 独立终审，对照需求评估 diff。

团队配置与多智能体协作

Supergraph Team 协调多智能体 DAG 执行，文件零冲突：
- Worktree 隔离： 并发任务在隔离的 worktree 中运行（.supergraph/worktrees/）。
- 实时监控面板： 在 http://127.0.0.1:3333 实时可视化 DAG。

👉 完整的团队上手流程与分支策略，见 plugins/supergraph/docs/TEAM-SETUP.md。

硬性规则

1. 没有获批的计划，绝不写代码。
2. 没有已验证的失败 RED 测试，绝不动手实现。
3. 未经用户批准，绝不修改枢纽节点。
4. 绝不跳过自动修复循环。
5. 测试失败或评审有 CRITICAL 问题时，绝不提交。
6. 假设任何关系之前，先查图谱工具（search_graph、trace_path）。
7. 浏览器/API 功能一律用 browser-agent 验证（Rust CDP，零 Playwright）。

项目结构

supergraph/
├── plugins/supergraph/
│ ├── skills/ # 41 engineering skills
│ ├── agents/ # 7 specialized subagents
│ ├── hooks/ # Smart lifecycle hooks
│ └── docs/TEAM-SETUP.md # 团队协作指南 ├── docs/ │ ├── INSTALLATION.md # 各平台详细安装说明 │ └── EXAMPLES.md # 端到端工作流实操演示 ├── AGENTS.md # 面向 Codex、Antigravity、DSH 的工作流 ├── CLAUDE.md # 面向 Claude Code 的工作流 └── settings.json # 自动放行权限

许可与隐私

- 本地优先，保护隐私： 代码库图谱和浏览器配置档严格保留在你本机。不会向外部服务器传输任何代码。
- 许可： MIT License。© 2026 datit309。