多 AI 智能体协作开发的桌面工作台
把并发的 AI 团队管理得像发 IM 一样自然
Main Hall ──── Orchestrator ────┬──── DM ──── Agent A (worktree-a)
├──── DM ──── Agent B (worktree-b)
└──── Room ── Agent A + Agent B
(conflict auto-created)
演示视频: https://drive.google.com/file/d/1kV23W_YMLg6L06ruz783HEphB7JZ0eeU/view?usp=sharing
| 快速导航 | ||
|---|---|---|
| ✨ 是什么 | 🚀 快速开始 | 🏗️ 项目结构 |
| ⚙️ 功能特性 | 🧠 开发方法论 | 📊 项目状态 |
| 🛠️ 开发指南 | 🧪 测试 | 📦 构建与打包 |
AgentHub 是一个 Electron 桌面工作台，专门用于驱动和管理多个 AI 编程 Agent 协同开发。它解决了多智能体系统中最核心的两个工程问题：
🔭 可见性 — 用熟悉的 IM 三层会话结构（主厅 / 私聊 / 会议室），随时知道"我在跟哪个 Agent 说话、每个 Agent 在干什么"。
🛡️ 安全性 — 每个 Agent 在独立 Git worktree 中工作，产出以 diff Artifact 渲染，用户逐一 Apply / Discard，改动永远不会自动落入主工作区。
AgentHub 本身也是"用 AI Agent 协作开发"的实验性产物——全部代码由 AI Agent 跨数十个里程碑增量构建，并形成了一套可复用的 Agent 协作开发方法论。
前置要求： Node.js 20+，Git 2.28+，Windows / macOS / Linux
# 1. 克隆仓库
git clone https://github.com/giansha/AgentsHub
cd AgentsHub
# 2. 安装依赖
npm install
# 3. 启动开发模式（自动重建 native bindings）
npm run dev
⚠️ Windows PowerShell 用户： 若npm.ps1被执行策略阻止，请用npm.cmd替代npm。
⚠️ VSCode 集成终端： VSCode 会注入ELECTRON_RUN_AS_NODE=1导致白屏。请改用外部终端，或先执行Remove-Item Env:ELECTRON_RUN_AS_NODE。
每个特性按「问题 → 常规做法 → 我们的方案 → 验证」结构说明。 🔬 标注的验证步骤为待复现占位（暂无已知触发事故，仅供功能验证）。
| ❌ 问题 | 多智能体系统运行起来后，用户很难知道"我现在在跟哪个 Agent 说话""每个 Agent 各自在干什么"。状态一旦不可见，用户就失去了对并发团队的掌控。 |
| 🔧 方案 | 把会话组织成三层线程，每层在后端都对应真实的线程模型、参与者模型与独立 Git 分支。 |
| 层级 | 图标 | 角色 | 适用场景 |
|---|---|---|---|
| Main Hall（主厅） | 🏛️ | 用户与长时编排器的主对话 | 派活、汇报、提合并 |
| DM（私聊） | 💬 | 用户或编排器与单个 subagent 的一对一通道 | 调试、查看单 Agent 进度 |
| Room（会议室） | 🚪 | 多个 Agent 的群聊，按 @-mention 寻址 |
协作议题、冲突自动协调 |
配套功能：@-mention 寻址 · 角色徽章 · 叙述者状态条 · 推理通道
🔬 验证 派发 2 个 subagent → 确认侧栏出现 Main Hall + 两个 DM，且
git worktree list显示独立分支。 负向：向未绑定 runtime 的 DM 发消息应报错/空操作，而非静默丢弃。
| ❌ 问题 | 多个 subagent 同时完成时，朴素实现会让编排器被并发重复唤醒，多个唤醒共享同一上下文、互相打架。 |
| 🔧 方案 | 用按 session 合并的调用队列 OrchestratorInvocationQueue，把并发唤醒合并成一个 follow-up，当前轮跑完再 drain。 |
关键设计：
- ⏸️ 同一 session 正在运行时，新的"重新评估"请求合并成待执行的 follow-up
- 🛑 用户按 Stop 时，连合并的 follow-up 一并丢弃，避免"刚中止又自启"
- 📢 调用失败显式上报（
onError），不静默吞掉 - 🎛️
max_concurrent_subagents限流 + Fleet 面板实时展示活动 / 成本 / 分支 / 角色
🐛 真实案例： 一个被
catch {}吞掉的迁移列错误曾把编排器变成无法诊断的"假死"。队列因此被明确设计为"失败必上报、但不影响后续 drain"。
| ❌ 问题 | Room 里允许 Agent 之间自由 @-mention 时，两个 Agent 互相 @ 可以无限对话下去，烧光预算且无人叫停。 |
| 🔧 方案 | 区分级联"深度"与广播"宽度"，只对深度设限。 |
广播（无 @）：A 说 → B 说 → C 说 ← depth=1，永不触发暂停 ✅
辩论（有 @）：@A → @B → @A → @B ← depth=4，自动暂停 ⛔
用户发新消息 → 重新激活 ✅
深度上限 DEBATE_ROUND_DEPTH_CAP = 4，逻辑见 room-coordinator.ts。
🔬 验证 在含 ≥2 个 Agent 的 Room 中引导互相 @，观察第 4 跳后 Room 状态变
paused，出现 "Debate round complete" 提示。 对照组：发无 @ 的消息，全员各回一次但不触发暂停。
| ❌ 问题 | 多个 subagent 并发开发，可能在合并时才暴露文件冲突。 |
| 🔧 方案 | 把冲突检测前置到调度路径，一旦两个 subagent 改了同一批文件，自动创建 Conflict Room 让它们协调。 |
容错设计： 兄弟分支可能已被合并清理，git diff base...branch 会抛 "unknown revision"。此时只记 CONFLICT_CHECK_SKIPPED 警告并跳过，绝不让检测失败中断整个派发流程（见 conflict-detector.ts）。
| ❌ 问题 | 让外部 Agent 直接编辑主工作树有两个风险——并发会话互相覆盖，以及改动难以单独 diff 与回滚。 |
| 🔧 方案 | 每个外部 Agent 对话拥有一棵独立的 Git worktree，改动以 diff Artifact 渲染成带 Apply/Discard 的可交互卡片。 |
外部 Agent 对话
│
├── contact/claude-code-abc123/ ← 独立 worktree，懒创建幂等
│ └── 改动快照 → diff Artifact
│ │
│ ┌──────┴──────┐
│ ▼ ▼
│ git apply git reset
│ --3way (✅) --hard (🗑️)
└──────────────────────────────────►
编排器 worktree（主工作区）
🔬 验证 让外部联系人改文件 →
git worktree list应见contact/<handle>-<id>worktree，聊天流出现带 Apply/Discard 的 ArtifactCard。 负向：无改动时点 Apply/Discard，应得到"无待处理改动"提示，而非报错。
| ❌ 问题 | Agent 工具生态快速变化，把工作台锁死到单一后端意味着每接入一个新工具都要改一遍核心管线。 |
| 🔧 方案 | 定义统一接缝 AgentBackend，所有后端实现相同接口，核心管线无需改动。 |
interface AgentBackend {
probe(): Promise<ProbeResult> // 绝不抛错，工具不可用是常态
openSession(ctx): AsyncIterable<NormalizedAgentEvent>
}当前支持的后端：
| 后端 | 状态 | 说明 |
|---|---|---|
FakeBackend |
✅ | 确定性可脚本化，用于开发/测试（AGENTHUB_FAKE_BACKENDS=1） |
ClaudeCodeBackend |
✅ | @anthropic-ai/claude-agent-sdk，支持 DeepSeek 兼容接入 |
OpenCodeBackend |
✅ | opencode serve + @opencode-ai/sdk，支持 OpenAI 兼容接入 |
🔬 验证
AGENTHUB_FAKE_BACKENDS=1启动 → "新建会话"中选到 FakeBackend 联系人 → 对话在线程/活动/成本/Artifact 各面板均有输出。
| ❌ 问题 | Agent 在后台自主执行时，用户看不到它"在想什么、在做什么"，出问题无法定位是哪一步、花了多少钱。 |
| 🔧 方案 | 四个维度的全程可见性。 |
| 维度 | 实现 | 效果 |
|---|---|---|
| 🧠 思考可见 | 推理通道 + 实时叙述者（live narrator） | 实时看到 Agent 的思考与动作 |
| 🔍 步骤可钻取 | TraceTimeline 时间线 | 对单个 subagent 逐步钻取 |
| 🔐 权限可升级 | grant / deny 升级请求，持久化记录 | 撞到未授权工具时弹窗而非失败 |
| 💰 成本可归账 | Fleet 成本面板，逐 runtime 独立归账 | 每个 Agent 的 token / 费用清晰可见 |
🔬 验证 限制 Profile 某工具权限后派活 → 弹出 grant/deny 升级请求，重启后仍在
permission-escalation表。 负向：deny 后该工具保持禁用，而非静默放行。
| ❌ 问题 | 这些工具默认每次写文件都要交互式索权，在 AgentHub 无人值守的后台执行下，会卡成一个用户看不见的审批死循环。 |
| 🔧 方案 | 识别到审批关卡放错了位置——唯一的人类把关应在"是否采纳改动"，而非"每次写文件"。 |
具体做法：
- 🔓 让工具在沙箱 worktree 里放手改（关闭逐次索权）
- 🛡️ 屏蔽开发者本机的全局配置，避免私人设置污染所有用户
- 📨 通过系统提示告知工具"改动最终会交给用户审查"
- 🔌 通过环境变量注入连接信息，可将工具接到 DeepSeek 等协议兼容模型
🐛 复现验证（回归原审批死循环）： 用会写文件的任务驱动 Claude Code 后端 → 对话应顺畅产出改动并停在用户侧的 Apply，不在工具内部卡住等待逐次写文件授权。
| ❌ 问题 | Apply 是一个直接改动代码库、且会被用户反复点击的按钮。中途打补丁失败会留下改了一半的工作区；重复点击则在同一文件上反复叠加。 |
| 🔧 方案 | 四层防护，确保 Apply 原子化、幂等、可降级。 |
Apply 流程
│
├─ 1. 拍快照（原子化保证）
├─ 2. 暂存全部变更（含新增/二进制/删除/改名）
├─ 3. 检查是否已存在？─── 已存在 ──► 返回成功（幂等）
│
├─ 4. 空跑预演
├─ 5a. 直接 git apply ──► 成功 ──► ✅
└─ 5b. 失败 → 三方合并（降级）──► 成功 ──► ✅
└─ 失败 → 回滚快照 ──► ❌ 干净报错
🐛 真实案例： 测试中曾出现打补丁半途失败，把 Git 冲突标记（
<<<<<<<）直接写进package.json，用户每点一次 Apply 就再叠一层。上述四层修复直接针对该事故（worktree-patch.ts）。
| ❌ 问题 | 主厅一条消息里同时 @claude-code 写后端、@opencode 写前端，若整段话原样发给两边，两个 AI 会各自把对方的活也干一遍。 |
| 🔧 方案 | 按 @-handle 出现位置切段 + 否定句守卫双重保障。 |
用户输入：
"请大家注意安全。@claude-code 写后端接口，@opencode 写前端页面"
│
按 @ 位置切段
│
┌────────────┴────────────┐
▼ ▼
claude-code 收到： opencode 收到：
"请大家注意安全。 "请大家注意安全。
写后端接口" 写前端页面"
否定句守卫匹配 don't delete / 不要删除 / 别归档 等，避免"千万别删掉这个助手"被误读成"删掉这个助手"。
🐛 真实案例： 联合测试中 "@A 写后端、@B 写前端" 被整段发给两边，B 把 A 的文件也建了，导致 A 的改动被采纳后 B 那份因撞车而失败。按 @ 切段后消除。
| ❌ 问题 | 每个外部 AI 在隔离 worktree 里干活，但采纳改动时都落到同一主工作区。后开工的 AI 若从过时起点出发，会把已采纳的成果重建或覆盖。 |
| 🔧 方案 | 每个 AI 开工前，先把 worktree 单向同步到主工作区最新状态；但只同步干净的 worktree，绝不覆盖进行中的工作。 |
等待迟到写入： 某些工具（如 OpenCode）在声称"已答完"后文件仍在异步落盘，因此采用"看一眼 → 稍等 → 再看一眼"，以后一次为准。
🔬 验证 AI-A 新建
foo.ts并 Apply → AI-B 开始新一轮 → 验证 B 的 worktree 已含foo.ts，不会重建或覆盖。 负向：B 的 worktree 有未完成改动时，应跳过同步。
| ❌ 问题 | 线性"一步接一步"计划无法表达"几件事可以并行、某些事必须等前置完成"的真实依赖结构。 |
| 🔧 方案 | 新增 DAG 工作流引擎，在原有线性计划之外提供并行调度能力。 |
DAG 示例：A → C，B → C
[任务A] ──┐
├──► [任务C]（等 A 和 B 都完成）
[任务B] ──┘
A、B 并行放出；C 等两者的产出均被用户批准后才解锁。
设计取舍：
| 原则 | 说明 |
|---|---|
| ➕ 只做加法 | 原线性计划路径原封不动，DAG 是额外选项 |
| 👤 人类把关推进 | 下游节点等上游产出被用户批准后才解锁，非 AI 自动推进 |
| 📋 同 Agent 排队 | 单个 Agent 无法同时干两件事，多个待办依序执行 |
| ❌ 失败明确可见 | 角色绑定失败则整条工作流标为失败，主厅留可见提示 |
状态： 🟡 早期——核心 schema + state + WorkflowRunRepo + 迁移已落地，编排 UI 待后续迭代。
🔬 验证 构造
A → C、B → C的图 → 验证 A、B 并行放出，C 等两者完成后才开始；任一节点失败则工作流整体失败。 负向：同一 Agent 绑定两个无依赖节点，应排队执行而非并行。
AgentHub 全部代码由 AI Agent 跨数十个里程碑增量构建。让一批"会遗忘上下文、会幻觉、会各自为政"的 AI 长期协作产出，本质是一个软件工程治理问题。
| 层 | 目录 | 角色 | 更新规则 |
|---|---|---|---|
| 📍 当前真相 | docs/feature-map/ |
每个子系统的可用状态 + QA 步骤 + 核验时间 | 每次触碰功能必须同步，状态标签靠读代码挣得 |
| 📜 历史 | docs/reports/（38 篇） |
里程碑交付范围、修正、决策、遗留项 | 只追加，不回改；后续 Agent 的交接契约 |
| 💡 设计意图 | docs/superpowers/ |
阶段规格与逐任务实现计划 | 落地后冻结；与当前真相对照即可看出偏差 |
问题：AI 没有跨会话记忆。如果只给它一个任务就开干，它会重新踩上一个 Agent 已经解决的坑，或破坏只在报告里写过原因的不变量；干完也不留交接，下一个 Agent 又从零开始。
常规做法：靠 commit message 和代码本身做隐式交接——但 commit 记录"改了什么"，不记录"为什么这么改、当时还有什么没解决"。
我们的方案：CLAUDE.md 把里程碑前后的动作写成显式契约，分两个钩子：
开工前（"When Starting Work On A Milestone"）：
- 先读上一里程碑报告（
docs/reports/）——报告携带代码与计划都没有的东西：执行中的修正、tag 后发现的 bug、热修、刻意的行为决策。 - 再读本里程碑的 plan（
docs/superpowers/plans/）——每个 plan 含自包含任务、确切命令与测试。 - 用 superpowers 的
executing-plans/subagent-driven-development执行。
收工后：
4. 在 docs/reports/ 写新报告：交付范围、修正、关键问题与修法、tag 后 bug、已知"非 bug 行为"、遗留项。
5. 更新 CLAUDE.md 的"Project File Structure"（增删文件、刷新 Last updated）。
6. 为每个动过的功能更新 docs/feature-map/：调状态、写 QA、把 Last verified 顶到当前 commit + 日期——禁止留着旧核验时间不动。
还有一条"完工询问"约束：实现完成（测试 / typecheck / build 全过）后，必须先问用户是否要写验收 / 交接报告，而不能擅自写。把"是否留档"的决定权交还用户，同时保证流程不会被省略。
效果：交接不再依赖某个 Agent 的自觉，而是流程的固定环节；"读上一份报告"成了开工的第一步。
开工前 收工后
│ │
├─ 1. 读上一里程碑报告 ├─ 4. 写新报告（事故/决策/遗留）
├─ 2. 读本里程碑计划 ├─ 5. 更新文件结构（CLAUDE.md）
└─ 3. 执行 └─ 6. 更新 docs/feature-map/ 所有动过的功能
每次会话自动加载、优先级高于模型默认行为。核心内容：
Build Gotchas（历次真实事故固化为永久约束）
| 陷阱 | 现象 | 约束 |
|---|---|---|
| 迁移前缀碰撞 | 新库侥幸通过，历史库静默损坏 | migration-guards.test.ts 常绿 |
| 表重建漏拷列 | 静默丢数据，被 catch {} 吞掉，表现为运行时假死 |
必须拷贝全部列 |
zustand v5 内联 ?? [] |
每帧新引用 → 无限重渲染 → 白屏 | 必须用模块级稳定常量兜底 |
| ESM 强转 CJS | Electron require("electron") 返回路径字符串而非运行时 API |
绝不加 format: 'cjs' |
AI Anchor Tags（让"为什么"可 grep、可守护、可被前置成门禁）
基本规则：类型表达 what、注释表达 why，且 why 用一组结构化前缀标注——[Business-Rule]（业务约束）/ [Why]（为何选这个实现而非显而易见的替代）/ [Context]（隐式外部依赖或 PR/issue 链接）/ [Invariant]（调用方必须维持的前置条件）/ [Hack/Warning]（绕过外部 bug 的 workaround）。配套重构铁律：未经显式指令不得删改这些标签注释；改动若使某条 [Why]/[Business-Rule] 失效，必须连注释一起更新。
设计意图——为什么单独为"why"立一套规范：
- "what"可再生，"why"不可再生。 类型、签名、控制流都能被后来的 Agent 通过读代码重新推断出来；唯独"当初为什么这么做、还有什么别的写法被否决了、依赖了哪个外部前提"是一旦不写下来就永久丢失的信息。把注释预算集中花在这类不可再生信息上，而不是复述代码已经说清的事。
- 拦截 AI 最典型的破坏动作。 AI 重构时有一种"好心"倾向：把它看不出理由的代码"简化"掉、把绕路的写法"改回"直觉写法、把它不理解的注释顺手删掉。而这些代码恰恰常常是为某个外部约束故意写成那样的。标签把"这里有不可省略的理由"这件事，正好放在 Agent 即将下手的那一行旁边，在编辑发生的那一刻拦住它。
- 每个标签编码一份"对未来读者的动作契约"，不只是分类：
[Business-Rule]说"这是产品/外部约束，别当成可优化掉的实现细节"；[Why]说"显而易见的替代方案已被考虑并否决，别好心改回去"；[Invariant]说"破坏它会波及所有调用方，先评估爆炸半径"；[Hack/Warning]说"这是对外部 bug 的绕行，没有明确指令不得移除"。读到标签 = 读到一条该如何对待这段代码的指令。
发挥作用的原理——它凭什么对 AI 真的有效：
- 可枚举，所以能写成门禁。 自由散文里的"注意事项"只能指望 Agent 碰巧读到；而带固定前缀的标签是可
grep的机器地址。于是"重构某段代码前，先列出该范围内所有[Business-Rule]/[Invariant]/[Hack/Warning]并逐条读"这条规则可以被机械执行——Agent 能主动检索它们，而不是被动撞见。把"理解约束"从概率事件变成确定步骤。 - 就近共置 → 抗上下文截断。 AI 的失忆主要来自上下文被压缩 / 换会话。标签与它解释的代码写在同一处，因此只要那段代码进入上下文，它的"why"必然同时在场（locality of reference）——不依赖 Agent 还记得几十轮之前读过的某份设计文档。
- 它是与"过去的决策者"通信的异步信道。 AI 无法回头问当初写代码的人。标签就是那个人留给所有未来 Agent 的留言，把一次性的决策固化成可被反复读取的上下文。
- 自愈，所以长期可信。 注释会随代码漂移而腐化，腐化的锚点比没有锚点更危险。规范因此规定：调试时把每条注释当假设而非真理去验证（与代码冲突时信代码）；一旦确认某条
[Business-Rule]/[Why]/[Invariant]已过时，修正它是本次改动的一部分——一条误导性注释本身就是 bug。这条规则让锚点在演化中保持可信，而不是慢慢变成噪声。
净效果：散落的注释被升级为一类受保护、可检索、自带处理契约、并随代码自愈的工程知识——它把"为什么"从"希望有人注意到"变成"流程必须经过的检查项"。
| 标签 | 含义 | 对后续 Agent 的动作契约 |
|---|---|---|
[Business-Rule] |
产品/外部约束 | 别当成可优化掉的实现细节 |
[Why] |
为何选此实现 | 显而易见的替代方案已被否决，别好心改回去 |
[Invariant] |
必须维持的前置条件 | 破坏它会波及所有调用方，先评估爆炸半径 |
[Hack/Warning] |
对外部 bug 的绕行 | 没有明确指令不得移除 |
把方法论拆成按意图触发、按需加载的 Skill：
| Skill 组 | 触发场景 |
|---|---|
feature-completeness-map |
构建/维护功能状态文档；"这个功能做完了吗" |
gitnexus 套件（6 个子 Skill） |
代码探索 / 影响分析 / 调试 / 重构 / 向导 / CLI |
superpowers 过程套件 |
对齐需求 → 写计划 → 执行 → TDD → 系统调试 → 验证完成 |
问题：方法论若写成一篇长文档，要么没人每次都读（失效），要么全塞进上下文（挤占 token、稀释注意力）。而且"建议"对 AI 没有约束力——它会"合理化"地跳过自己觉得多余的步骤。
考量：把方法论拆成按意图触发、按需加载的 Skill（渐进式披露）——平时只占一行描述，命中某类任务时才把完整方法展开进上下文；并把关键步骤写成强制门禁而非建议。项目里有三组 Skill：
(1) feature-completeness-map —— 对抗"功能完成度"的真相漂移。
- 问题：项目变大后无人能准确回答"这个功能做完了吗"。报告说 "done" 只是假设；"每块都存在"不等于"每块连通"——最危险的 bug 藏在接缝里（UI 调到一个存在但逻辑错误的 IPC handler；producer 造了对象却从不调用 consumer；查找键与写入键不匹配）。
- 做法：定义一套靠读代码挣来的状态标签（✅ 全链路打通 / 🟡 有已确认缺口 / 🔵 单边实现 / ⚪ 仅设计 / ❓ 未核验），强制"连通性优于存在性"——必须追踪一个具体值穿过每个边界才能给 ✅，并区分"代码追踪过"与"实际运行过"两档可信度。招牌规则 Deferred-vs-Bug 双向生效：把缺失标 bug 前要查它是否被计划 / 报告 / spec 有意推迟；但报告说"已完成"同样只是假设，一个可达却静默忽略输入的路径（真实例子：
default_agent_profile_id被 Plan 路径无视、硬编码回退到default-coder），即便报告称 shipped 也是实打实的 bug。
(2) gitnexus 套件 —— 用代码知识图谱给"理解与改动"上门禁。
-
问题：Agent 改一个函数时不知道谁在调它、会牵连哪些执行流；盲改即制造回归；用查找替换重命名会漏改或误改。
-
结构：套件按开发动作拆成 6 个子 Skill，按用户意图路由加载，而非一股脑塞进上下文：
子 Skill 触发意图 gitnexus-exploring"X 是怎么工作的 / 谁调用了它" gitnexus-impact-analysis"改 X 会破坏什么 / 安全吗" gitnexus-debugging"为什么 X 失败了 / 这个错误从哪来" gitnexus-refactoring重命名 / 抽取 / 拆分 / 移动 gitnexus-guideGitNexus 工具、图 schema、资源参考 gitnexus-cli索引 / 重分析 / 生成 wiki / 查状态 -
强制纪律（写在 CLAUDE.md 的 Always/Never Do）：改任何符号前先跑
gitnexus_impact上报爆炸半径（d=1 直接调用方会坏、必须更新；d=2/d=3 递进风险）；HIGH/CRITICAL 风险须先警告用户；重命名用懂调用图的gitnexus_rename（先dry_run）而非查找替换；提交前用gitnexus_detect_changes核对改动范围与预期一致。 -
新鲜度治理：代码一提交，知识图谱就过期。约定 commit / merge 后跑
npx gitnexus analyze --skip-agents-md刷新（Claude Code 侧用 PostToolUse hook 自动触发），并提示用--embeddings保住已生成的向量。
(3) superpowers 过程套件 —— 规定"怎么推进一项工作"。
brainstorming（动手前先把需求与设计对齐，且未经批准不进入实现）、writing-plans（把规格拆成逐任务计划）、executing-plans/subagent-driven-development（执行）、test-driven-development、systematic-debugging、verification-before-completion（声称"完成 / 修好"前必须先跑验证命令、用输出说话）。这组 Skill 规定的是流程骨架——先对齐再实现、先写测试再写码、先验证再宣称完成——与上面两组"领域门禁"互补。
整体取舍：三组 Skill + 三层文档 + 生命周期契约共同构成一条规则——关键判断（功能是否真完成、改动是否安全、工作是否对齐需求）都不靠 Agent 的自觉，而是被前置成必须经过的门。这正是让一群无长期记忆的 AI 能跨数十个里程碑稳定协作的根本原因。
AgentHub/
├── 📁 electron/main/ # Node/Electron 主进程
│ ├── agent/ # AgentRunner、权限层、叙述者
│ ├── backends/ # 外部 Agent 后端适配层（FakeBackend / ClaudeCode / OpenCode）
│ ├── db/ # SQLite 抽象、迁移、keychain
│ ├── git/ # GitService、worktree 生命周期、原子补丁
│ ├── llm/ # Provider 工厂、模型目录、定价
│ ├── repositories/ # DB 访问层（每表一文件）
│ └── services/ # 业务逻辑（编排器、Room、冲突检测、工件服务……）
│
├── 📁 src/ # React 渲染进程（Vite）
│ ├── components/chat/ # ChatView、ArtifactCard、ThreadTree
│ ├── components/fleet/ # Fleet 面板、权限升级弹窗
│ ├── components/settings/ # 设置、插件集成
│ └── stores/ # Zustand 状态管理
│
├── 📁 shared/ # 两进程共用类型 + IPC 契约
├── 📁 tests/ # 815 个测试（单测 + 冒烟）
└── 📁 docs/
├── feature-map/ # 📍 当前真相层（12 个子系统）
├── reports/ # 📜 历史层（里程碑报告）
└── superpowers/ # 💡 设计意图层（规格 + 计划）
npm run dev # 开发模式（热重载，自动重建 native bindings）
npm run typecheck # 仅类型检查
npm run rebuild:electron # 重建 Electron 原生绑定（切换运行时后需要）
npm run rebuild:node # 重建 Node 原生绑定（运行测试前需要）npm test # 全部 815 个测试（自动重建 Node 绑定）
npm run test:watch # 监视模式
# 可选：真实 CLI/模型冒烟测试（需本地安装对应工具）
npx vitest run tests/smoke/claude-code-real-smoke.test.ts
npx vitest run tests/smoke/opencode-real-smoke.test.ts测试覆盖： 服务层单测 · Store 单测 · 渲染器组件测试 · 后端适配器测试 · IPC 契约测试 · 迁移守卫
npm run build # 生产构建
npm run package # 打包（当前平台）
npm run package:win # Windows NSIS 安装包
npm run package:mac # macOS DMG + ZIP
npm run package:linux # Linux AppImage| 阶段 | 状态 | 关键特性 |
|---|---|---|
| Phase 0 | ✅ | Electron 壳、SQLite、AgentRunner（10 工具）、Plan/Orchestrator 模式、跨平台打包 |
| Phase 1 | ✅ | 三层 IM 线程、长时编排器（6 信号工具）、subagent 生命周期、冲突检测、合并流程、叙述者 |
| Phase 2 | ✅ | ActivityHub 可观测性、多角色 Profile、权限墙升级、并发调度 + 限流、Fleet 成本归集 |
| Phase 3 P0 | ✅ | AgentBackend 适配层、FakeBackend、持久联系人模型、外部 DM 路由 |
| Phase 3 Track-0 | ✅ | Per-conversation worktrees、实时 diff Artifact、原子 + 幂等 Apply/Discard |
| Phase 3 P1 | ✅ | 真实 ClaudeCodeBackend（@anthropic-ai/claude-agent-sdk）、DeepSeek 兼容 |
| Phase 3 P2 | ✅ | 真实 OpenCodeBackend（opencode serve + @opencode-ai/sdk） |
| 有界辩论 | ✅ | Room peer-@ 链深度上限 + 重激活守卫 |
| DAG 工作流引擎 | 🟡 | Schema + state + Repo 落地，编排 UI 待后续迭代 |
已知延期项
- 富插件健康检查（超出 CLI 可用性/版本检测的范围）
- 全功能 propose/confirm-merge UI 含冲突解决（M3-b）
- token 级别外部后端文本流式传输
- 重复 Stop-note 节流
- 打包/更新器手动发布流程
本项目由 AI Agent 跨数十个里程碑增量构建
详见 docs/reports/ — 每一篇报告都是下一个 Agent 的交接契约