sanguo_moziplus_v2/docs/research/research-batch1-squad-superset-opencode.md

# 调研报告：Claude Squad / Superset / OpenCode 对 moziplus v2.0 的启发

**版本**: v1.0  
**作者**: 庞统（副军师）🐦  
**日期**: 2026-05-16  
**项目**: moziplus v2.0 AI Native DevOps 平台设计参考  

---

## 项目一：Claude Squad (smtg-ai/claude-squad)

### 1.1 一句话定位

基于 tmux + git worktree 的轻量级多 AI Agent 终端会话管理器，让用户在一个 TUI 中同时监督多个独立运行的编码 Agent。

### 1.2 核心设计理念

1. **tmux 即运行时隔离**：每个 Agent 运行在独立的 tmux session 中，进程级隔离，天然支持暂停/恢复/崩溃不影响其他 Agent
2. **git worktree 即文件隔离**：每个 Agent 在独立的 worktree（独立分支）中工作，文件系统级隔离，零合并冲突风险
3. **Instance 状态机驱动**：`Instance` struct 作为每个 Agent 会话的中心编排器，管理状态转移（idle → running → paused → done），协调 tmux 和 git 子系统
4. **TUI 旁观者模式**：统一 TUI 界面让人类以旁观者身份监控所有 Agent，但 Agent 之间无直接通信通道
5. **Agent 无感知编排**：Agent 本身不知道自己被编排，只是普通的 CLI 交互（Claude Code / Codex / OpenCode 等）

### 1.3 与 moziplus v2.0 AI Native 相关的关键洞察

| 洞察 | 关联 |
|------|------|
| **进程级隔离 vs 协作** | Claude Squad 的隔离是"各自干活互不干扰"，moziplus v2.0 的黑板架构是"有组织的协作"——方向相反但互补。Agent 的文件操作隔离（worktree 思路）值得借鉴 |
| **状态机管理** | Instance 的状态转移模型（idle/running/paused/done/error）可以直接映射到 moziplus v2.0 的节点状态管理 |
| **旁观者模式** | TUI Dashboard 监控所有 Agent 的做法与 moziplus v2.0 的 Dashboard 双入口设计理念一致 |
| **Agent 无感知** | Agent 不需要知道编排系统的存在，这与 moziplus v2.0 的"Agent 只做产出"原则高度吻合 |

### 1.4 可直接借鉴的具体做法

**1) 状态机模型**（参考 Instance struct）

```go
// Claude Squad 的 Instance 状态
type Instance struct {
    Name      string
    Program   string  // claude/codex/opencode
    Branch    string
    Worktree  string
    State     InstanceState  // Idle, Running, Paused, Stopped, Error
}
```

moziplus v2.0 可以借鉴这种结构化的 Agent 实例管理，在黑板中为每个 Agent 维护类似的状态记录。

**2) Worktree 隔离方案**

```bash
# Claude Squad 的 worktree 创建模式
git worktree add -b agent/<name> .claude-squad/worktrees/<name>
```

对于 moziplus v2.0 中需要文件操作的并行任务（如代码生成），可以采用类似的工作目录隔离策略，每个 Agent 任务分配独立的工作目录。

**3) TmuxSession 封装**

将底层进程管理抽象为统一的 Session 接口，moziplus v2.0 的 Daemon 层可以类似地封装 OpenClaw Agent 的生命周期管理。

### 1.5 不值得借鉴的地方

| 做法 | 原因 |
|------|------|
| **Agent 间无通信** | moziplus v2.0 需要结构化协作（黑板架构），Agent 之间通过黑板间接通信是核心设计，不能走"完全隔离"路线 |
| **依赖 tmux** | tmux 是 Unix-only 的终端复用器，moziplus v2.0 的 Daemon 是事件驱动的服务进程，不应依赖终端工具 |
| **人工串行 Review** | Claude Squad 需要人工逐个检查 Agent 产出，moziplus v2.0 的审查流水线 + 挑战体系可以自动化这个过程 |
| **缺乏任务分解** | 只有人工分配任务给 Agent，没有自动任务分解能力，moziplus v2.0 需要内置 DAG 分解 |

---

## 项目二：Superset (superset-sh/superset)

> **注**：原任务中的 nihaals/superset-terminal 实际上是 superset-sh/superset 的旧名或相关项目。superset-sh/superset 是当前活跃的正式版本。

### 2.1 一句话定位

专为多 AI 编码 Agent 并行编排设计的终端 IDE，通过 git worktree 隔离 + 内置审查/合并工作流，让 10+ 个 Agent 同时在同一代码库上工作。

### 2.2 核心设计理念

1. **Worktree 原生**：每个 Agent 任务自动创建独立 worktree + 分支，共享 Git 对象存储（省空间），变更互不可见直到显式合并
2. **任务即 Agent**：`superset agent spawn --name <name> --task <description> --branch <branch>` ——每个任务直接映射为一个 Agent 实例
3. **批量 PR 审查**：多个 Agent 的产出可以并行审查和合并，内置 diff 查看和编辑器跳转
4. **本地执行 & 隐私**：所有操作在本地机器上运行，不代理 API 调用
5. **IDE 无关**：支持 VS Code、Cursor、Xcode、JetBrains 等任何编辑器打开 worktree

### 2.3 与 moziplus v2.0 AI Native 相关的关键洞察

| 洞察 | 关联 |
|------|------|
| **任务-Worktree-Branch 三位一体** | 一个任务 = 一个工作目录 = 一个分支，这个映射关系简洁且有效。moziplus v2.0 的每个节点任务可以采用类似的工作目录分配策略 |
| **并行审查工作流** | 多个 Agent 完成后并行 Review → Merge 的流程，与 moziplus v2.0 的审查流水线（分级审查 + 挑战）异曲同工 |
| **Agent 作为执行器，人作为审查者** | 这个分工模式与 moziplus v2.0 的"Agent 做产出，审查流水线做质量把关"一致 |
| **共享对象存储** | Git worktree 共享 .git 目录的做法节省空间，moziplus v2.0 在 NAS 上可以类似地共享数据存储 |

### 2.4 可直接借鉴的具体做法

**1) 任务分配 DSL**

```bash
# Superset 的 Agent 启动方式
superset agent spawn \
  --name "update-types" \
  --task "Add TypeScript types to auth module" \
  --branch "feat/types"

superset agent spawn \
  --name "fix-lint" \
  --task "Fix all ESLint errors" \
  --branch "fix/lint"
```

moziplus v2.0 的任务创建 CLI 可以借鉴这种声明式的任务分配语法：`cli.py create --title "xxx" --assignee zhangfei --description "..."`

**2) Workspace 预设**

```bash
superset workspace create refactor-auth
# 预定义一组 Agent 和任务模板
```

moziplus v2.0 可以预定义任务模板（如"回测流程模板"、"数据验证模板"），一键生成 DAG。

**3) Review + Merge 工作流**

Superset 的"Agent 在独立分支完成 → 人工 Review diff → Merge 回主分支"流程，可以映射为 moziplus v2.0 的"Agent 完成 output.md → 审查流水线检查 → Daemon 合并结果"。

### 2.5 不值得借鉴的地方

| 做法 | 原因 |
|------|------|
| **纯人工审查** | moziplus v2.0 有 AI 驱动的审查流水线，不需要人工逐个 Review |
| **无 Agent 间协作** | Superset 的 Agent 各干各的，没有结构化协作机制，moziplus v2.0 需要黑板驱动的协作 |
| **单机架构** | 只跑在一台机器上，moziplus v2.0 需要支持多节点（NAS + Windows Node 等） |
| **缺乏 DAG 感知** | 任务之间没有依赖关系管理，moziplus v2.0 的核心就是 DAG 编排 |

---

## 项目三：OpenCode (opencode-ai/opencode)

### 3.1 一句话定位

开源的多 Provider AI 编码 Agent，核心是一个 provider-agnostic 的抽象层 + TUI 界面 + 可扩展的 MCP 工具系统。

### 3.2 核心设计理念

1. **Provider-Agnostic 抽象**：编码 Agent 接口与 AI 模型 Provider 解耦，支持 Claude、GPT、Gemini、本地模型，随时切换不锁厂商
2. **TUI Thin Client**：TUI 是"瘦客户端"，所有业务逻辑委托给后端 server，前端只负责渲染和交互
3. **MCP 工具扩展**：通过 Model Context Protocol 添加外部工具（本地/远程 MCP Server），Agent 能力可按需扩展
4. **权限控制体系**：工具级权限配置（如 edit 工具需要审批、bash 工具受限），可精细控制 Agent 能做什么
5. **Context Compaction**：上下文压缩机制，长对话中自动精简历史，控制 token 使用

### 3.3 与 moziplus v2.0 AI Native 相关的关键洞察

| 洞察 | 关联 |
|------|------|
| **Provider-Agnostic = Agent-Agnostic** | OpenCode 解耦了 AI Provider，moziplus v2.0 可以进一步解耦 Agent 本身——黑板架构不关心 Agent 是谁，只关心产出 |
| **TUI Thin Client** | moziplus v2.0 的 Dashboard 也应该是 Thin Client，所有编排逻辑在 Daemon 层 |
| **MCP 工具扩展** | moziplus v2.0 的 Skill 系统与 MCP 的理念类似——按需给 Agent 注入能力，但 moziplus 的 Skill 是任务级注入而非全局可用 |
| **权限控制** | 工具级权限对应 moziplus v2.0 的"节点只关注自己的产出"——Agent 只能做被允许的操作 |
| **Context Compaction** | 对应 moziplus v2.0 的 L0-L3 四层上下文架构——不是所有上下文都注入，按层级精简 |

### 3.4 可直接借鉴的具体做法

**1) Provider 抽象层**

```go
// OpenCode 的 Provider 接口抽象
type Provider interface {
    Complete(ctx context.Context, messages []Message) (Response, error)
    Stream(ctx context.Context, messages []Message) (<-chan Chunk, error)
}
```

moziplus v2.0 可以定义类似的 Agent 抽象接口，让不同类型的 Agent（OpenClaw Agent / 外部 CLI / HTTP API）统一接入黑板：

```python
# moziplus v2.0 可能的 Agent 接口
class AgentAdapter(ABC):
    @abstractmethod
    async def execute(self, task: NodeTask, context: BlackboardSnapshot) -> NodeOutput:
        pass
    
    @abstractmethod
    async def status(self) -> AgentStatus:
        pass
```

**2) 权限配置文件**

```json
// OpenCode 的 opencode.json 权限配置
{
  "permissions": {
    "tools": {
      "edit": "allow",      // 自动允许文件编辑
      "bash": "require-approval"  // bash 命令需要审批
    }
  }
}
```

moziplus v2.0 可以借鉴这种声明式的 Agent 权限配置，在节点模板中定义每个角色允许的操作。

**3) MCP 工具注册**

```json
{
  "mcp": {
    "servers": {
      "github": {
        "command": "mcp-github",
        "args": ["--repo", "owner/repo"]
      }
    }
  }
}
```

moziplus v2.0 的 Skill 注入可以采用类似的注册机制，但基于任务上下文动态注入而非全局注册。

### 3.5 不值得借鉴的地方

| 做法 | 原因 |
|------|------|
| **单 Agent 架构** | OpenCode 本质是单 Agent 工具，没有多 Agent 协作能力，moziplus v2.0 的核心是多 Agent 编排 |
| **对话式交互** | OpenCode 的主要交互是对话（chat），moziplus v2.0 是任务驱动（DAG），交互模式根本不同 |
| **无任务编排** | 没有任务分解、DAG 管理、依赖解析等编排能力，这是 moziplus v2.0 的核心价值 |
| **无经验沉淀** | 没有 Memory → Skill → Rule 的经验闭环机制 |

---

## 综合结论：对 moziplus v2.0 的设计启发

### 启发一：隔离粒度要恰到好处

三个项目都采用了某种形式的隔离：
- Claude Squad：tmux 进程隔离 + git worktree 文件隔离
- Superset：git worktree + 独立分支
- OpenCode：Provider 抽象层 + 权限控制

**对 moziplus v2.0 的启发**：黑板架构的隔离应该是"逻辑隔离"而非"物理隔离"。Agent 之间共享黑板数据（状态、上下文），但在执行层面保持工作目录和权限的隔离。隔离粒度 = 任务节点级别，每个节点的产出写入独立目录，但通过黑板共享元信息。

### 启发二：Agent 应该是无感知的执行器

三个项目的一个共同点：Agent 不需要知道编排系统的存在。Claude Squad 和 Superset 的 Agent 只是普通的 CLI 工具，OpenCode 的 Agent 不知道上层有没有编排器。

**对 moziplus v2.0 的启发**：强化"Agent 只做产出"的设计。Agent 收到的是明确的节点任务（input），产出的是结构化的结果（output.md + 结论 JSON）。Agent 不关心 DAG 怎么流转、不关心其他 Agent 在做什么。这让系统可以自由替换 Agent 实现（OpenClaw Agent / CLI 工具 / 外部 API）。

### 启发三：状态管理是编排的基石

Claude Squad 的 Instance 状态机（idle/running/paused/done/error）和 Superset 的 Agent 任务状态管理，都说明了状态管理在多 Agent 编排中的核心地位。

**对 moziplus v2.0 的启发**：黑板中的节点状态管理要更加丰富，支持：
- 基础状态：pending → running → done/failed
- 审查状态：done → reviewing → challenged → revised → approved
- 挂起/恢复：paused → resumed
- 状态变更要有事件通知机制（Daemon 事件驱动）

### 启发四：审查工作流需要结构化

Superset 的 Review + Merge 流程和 OpenCode 的权限审批机制，都指向同一个需求：Agent 产出需要质量把关。

**对 moziplus v2.0 的启发**：moziplus v2.0 的审查流水线比这些项目更进一步：
- 分级审查（自动检查 → 同行审查 → 专家审查）
- 挑战权（被挑战者可以反驳）
- 自动化检查（格式校验、数据验证）
- 但可以借鉴 Superset 的"可视化 diff"思路，让 Dashboard 展示审查对比

### 启发五：扩展性通过抽象层实现

OpenCode 的 Provider 抽象层和 MCP 工具系统是最好的例证——通过定义清晰的接口边界，系统可以无限扩展而不改核心。

**对 moziplus v2.0 的启发**：
1. **Agent 适配器抽象**：定义统一的 `AgentAdapter` 接口，任何 Agent 实现只要满足接口就能接入黑板
2. **Skill 动态注入**：类似 MCP 的按需工具注册，但基于任务上下文动态注入
3. **黑板数据模型版本化**：黑板的结构可以演进，通过版本号保证向后兼容

### 总结矩阵

| 维度 | Claude Squad | Superset | OpenCode | moziplus v2.0 借鉴 |
|------|-------------|----------|----------|-------------------|
| 隔离方式 | tmux + worktree | worktree + branch | 权限控制 | 逻辑隔离（黑板）+ 工作目录隔离 |
| Agent 通信 | 无 | 无 | 无 | 黑板间接通信 ✅ |
| 状态管理 | Instance 状态机 | Agent 状态 | Provider 状态 | 节点状态 + 审查状态 ✅ |
| 审查机制 | 人工 Review | 人工 Review | 权限审批 | 自动化审查流水线 ✅ |
| 扩展性 | 固定 Agent 类型 | CLI Agent | MCP 工具 | Agent 适配器 + Skill 注入 ✅ |
| 任务编排 | 无（手动分配） | 简单分配 | 无 | DAG 编排 ✅ |

**核心结论**：这三个项目代表了 2025-2026 年多 Agent 编排的"第一代"实践——解决的是"如何让多个 Agent 同时跑起来"的问题。moziplus v2.0 要解决的是更深层的"如何让多个 Agent 有组织地协作"的问题。从它们身上借鉴的是工程层面的具体做法（状态管理、隔离策略、扩展接口），而不是架构层面的设计（因为它们都没有真正的协作编排架构）。