部署 AI 编程代理 SDD 实战指南：从单机 Claude Code 到多智能体规范驱动开发

部署 AI 编程代理 SDD 实战指南：从单机 Claude Code 到多智能体规范驱动开发

发布日期：2026-07-03 | 分类：AI 开发方法论 | 难度：进阶

简介

2025-2026 年，AI 编程代理（AI Coding Agent）已经从「单打独斗」进化到「多智能体协作」阶段。Claude Code、Codex CLI、Cursor 等工具让开发者能快速生成代码，但当项目规模变大、需求变复杂时，单纯靠对话式编程（Vibe Coding）会出现三个致命问题：

1. 意图漂移：聊着聊着，AI 不知道你要做什么了
2. 上下文溢出：代码量大到 AI 记不住前因后果
3. 缺乏规范：改了什么、为什么改，全靠聊天记录

规范驱动开发（Spec-Driven Development, SDD）正是解决这些问题的方案。而本文将更进一步——讲解如何部署和管理一个由 SDD 驱动的多机 AI 编程代理集群，让不同机器上的不同 Agent 按照统一规范协同工作。

你将学到

• 🖥️ 如何搭建多机 AI 编程代理基础设施（Hermes Agent + Claude Code + Codex）
• 📋 如何在团队中落地 SDD 工作流（OpenSpec 框架）
• 🔄 如何让多个 Agent 按统一规范并行工作
• 🛠️ 实际生产环境的部署和运维经验
• 🚨 常见坑和解决方案

适用读者

• 已经使用过 Claude Code 或 Codex，想提升协作效率的开发者
• 管理多台开发机（Linux/Mac/Windows），想统一调度 AI Agent 的技术负责人
• 对 SDD 有基本了解，想在生产环境落地的人

---

前置要求

资源	说明
一台 Linux 服务器	作为中央调度器（建议 Ubuntu 22.04+/Debian 12+）
至少一台远程开发机	Mac（macOS 14+）和/或 Windows（10/11 22H2+）
Hermes Agent	安装在中央调度机上
Claude Code	安装在远程开发机上（npm install -g @anthropic-ai/claude-code）
OpenSpec CLI	可选，但推荐安装
SSH 密钥	中央调度机免密登录到所有远程开发机
基本的命令行和容器知识	—

---

一、架构总览

1.1 为什么需要多机部署？

单机 Claude Code 已经很强，但实际开发中常常遇到：

场景 A：数据库应用开发
  - Windows DBView 项目 → 需要在 Windows 上调试
  - 但 CI/CD、博客部署在 Linux → 需要多机

场景 B：并行开发
  - 前端修 Bug + 后端加功能 → 两个 Agent 同时工作
  - 同一台机器上下文打架 → 分开部署更干净

场景 C：资源隔离
  - 生产环境不能随便装开发依赖
  - 但开发机要跑各种实验

多机部署不是炫技，而是真实需求驱动的架构选择。

1.2 推荐架构

                         ┌──────────────────────┐
                         │    Hermes Agent       │
                         │   (中央调度器/Linux)    │
                         │                       │
                         │  Skills / Cron / MCP   │
                         │  OpenSpec 规范管理     │
                         └──────┬───────┬────────┘
                                │       │
                    SSH/tmux   │       │  SSH/psmux
                                │       │
                    ┌───────────▼┐    ┌─▼───────────┐
                    │  Mac 开发机  │    │ Windows 开发机 │
                    │             │    │               │
                    │ Claude Code │    │   Claude Code │
                    │ tmux 会话   │    │   psmux 会话   │
                    │ nvm 18.18  │    │   PowerShell  │
                    └─────────────┘    └───────────────┘

核心原则：

• 中央调度器不写代码——它只负责任务分发、规范管理、进度监控
• 远程代理写代码——Claude Code 在各自的机器上执行
• 规范驱动一切——没有 spec，不动一行代码

---

二、部署中央调度器

2.1 安装 Hermes Agent

在 Linux 服务器上安装 Hermes Agent：

# 使用安装脚本（推荐）
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# 或者用 pip
pip install hermes-agent

验证安装：

hermes --version

2.2 配置远程开发机连接

Mac 开发机

# 在 Mac 上开启远程登录
sudo systemsetup -setremotelogin on

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 配置 nvm（如果是 M 系列芯片）
# 编辑 ~/.zshrc，确保 nvm 初始化
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

在中央调度机上配置 SSH 免密登录：

# 生成本机 SSH 密钥（如已有则跳过）
ssh-keygen -t ed25519 -C "hermes-agent"

# 拷贝到 Mac
ssh-copy-id user@mac-ip

# 测试连接
ssh user@mac-ip "claude --version"

Windows 开发机

Windows 推荐使用 OpenSSH Server + PowerShell：

# 在 Windows 上安装 OpenSSH Server（管理员 PowerShell）
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
Start-Service sshd
Set-Service -Name sshd -StartupType 'Automatic'

# 验证
ssh localhost "claude --version"

中央调度机测试连接：

ssh user@windows-ip "claude --version"

⚠️ Windows 注意事项：Claude Code 在 Windows 上默认用 CMD，但中文支持不如 PowerShell。建议在项目配置中指定 "shell": "powershell"。

2.3 配置项目清单

Hermes Agent 通过 ~/.hermes/projects.json 管理所有项目。一个典型配置：

{
  "dbview": {
    "device": "win",
    "host": "192.168.31.200",
    "user": "developer",
    "tool": "claude-code",
    "mode": "psmux",
    "workdir": "C:\\Projects\\dbview"
  },
  "valin-salary": {
    "device": "mac",
    "host": "100.110.128.83",
    "user": "developer",
    "tool": "claude-code",
    "mode": "tmux",
    "workdir": "/Users/developer/projects/valin-salary"
  }
}

这样配置后，只需说「在 dbview 项目中执行：xxx」，Hermes 就会自动 SSH 到 Windows、启动或复用 psmux 会话、把命令发给 Claude Code。

---

三、SDD 规范体系搭建

3.1 选择 SDD 框架

目前主流的 SDD 框架对比如下：

框架	特点	适用场景	社区活跃度
OpenSpec	轻量级、文件结构清晰、OPSX 命令	已有代码库 + 增量开发	⭐⭐⭐⭐⭐
Spec Kit (GitHub)	GitHub 深度集成、Issue/Spec 联动	GitHub 原生团队	⭐⭐⭐⭐
BMAD	面向大型项目、含架构决策记录	企业级复杂项目	⭐⭐⭐
cc-sdd	Claude Code 原生、最小化适配	单项目快速上手	⭐⭐⭐

本文以 OpenSpec 为例，因为它最轻量、工具链最成熟，且与 Claude Code 配合最好。

3.2 初始化项目

在远程项目目录中初始化 OpenSpec：

# SSH 到远程开发机
ssh user@mac-ip "cd /path/to/project && npx openspec init"

这会生成：

project/
├── openspec/
│   ├── project.md        ← 项目元数据（技术栈、架构约定）
│   └── changes/          ← 所有变更记录
│       └── archive/      ← 已完成的变更归档
└── .gitignore

3.3 配置 CLAUDE.md

为了让 Claude Code 自动遵循 SDD 工作流，在项目根目录创建 CLAUDE.md：

# 项目规范

## 开发流程
1. 所有新功能或重构必须先创建 OpenSpec 变更
2. 第一步在 openspec/changes/ 下创建版本计划
3. 人类审核 spec 后才能开始编码
4. 编码完成后，更新 spec 状态并归档

## 技术栈
- 前端：React 18 + TypeScript + Tailwind CSS
- 后端：Node.js + Express + Prisma ORM
- 数据库：PostgreSQL
- 测试：Vitest + Playwright

## 代码规范
- 使用 ESLint + Prettier
- 提交信息遵循 Conventional Commits
- 每个 PR 必须包含测试

配置了这个文件后，Claude Code 每次启动都会自动加载它，从而内化 SDD 工作流。

---

四、SDD 驱动的多 Agent 工作流

这是本文的核心——如何通过中央调度器，让多个 AI Agent 按照统一规范并行工作。

4.1 整体流程

┌──────────────────────────────────────────────────────┐
│                    人类开发者                          │
│                   (提出需求)                           │
└─────────────────────┬────────────────────────────────┘
                      │
                      ▼
┌──────────────────────────────────────────────────────┐
│              Hermes Agent（中央调度器）                 │
│                                                      │
│  Step 1: 接收需求 → 生成 OpenSpec proposal            │
│  Step 2: 人类审核 proposal                            │
│  Step 3: 分拆任务 → 分配 Agent                        │
│  Step 4: 监控进度 → 收集结果                           │
│  Step 5: 合并审查 → 归档变更                           │
└──────────────────────────────────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        │             │             │
        ▼             ▼             ▼
   ┌─────────┐  ┌─────────┐  ┌─────────┐
   │Agent A  │  │Agent B  │  │Agent C  │
   │(Mac)    │  │(Linux)  │  │(Win)    │
   │前端任务  │  │后端 API  │  │数据库脚本 │
   └─────────┘  └─────────┘  └─────────┘

4.2 Step 1：创建 OpenSpec 变更

在中央调度器上，通过 Hermes 创建 OpenSpec 变更计划：

# 发送任务到远程开发机
hermes run dbview "请在 openspec/changes/ 下创建 v3 版本计划：
├── .openspec.yaml
├── proposal.md
├── design.md
├── tasks.md
└── specs/
    ├── 数据导出功能/spec.md
    ├── 查询性能优化/spec.md
    └── 连接池重构/spec.md

每个 spec.md 包含：描述、影响、方案、接口、文件、工时估算"

远程的 Claude Code 会生成所有规范文件。Hermes 自动监控进度并在完成后通知。之后人类审核这些规范文件，确认后再进入实现阶段。

4.3 Step 2：批量审批文件创建

Claude Code 在创建多个文件时会逐个询问，正确的处理方式是：

# 在远程开发机上向 tmux 发送选型指令
# 第一个文件创建询问出现时，选择 "Yes, allow all edits"
# 这样后续所有文件都会自动创建

在 Hermes 中，这可以通过 cron 脚本自动处理。

4.4 Step 3：分拆任务并行执行

OpenSpec 的 tasks.md 按优先级和依赖关系排列任务。Hermes 可以将其拆分为独立任务，分发给不同机器：

tasks.md 示例：
├── P1-1: 数据导出功能 (3h) → 发给 Mac Agent A
├── P1-2: 查询性能优化 (2h) → 发给 Mac Agent A（串行）
├── P2-1: 连接池重构 (4h)  → 发给 Windows Agent B（可并行）

在 Hermes 中执行：

# Agent A 处理核心功能
hermes run dbview "按 OpenSpec 计划，开始实施 P1-1 数据导出功能"

# Agent B 并行处理独立任务
hermes run dbview "开始实施 P2-1 连接池重构"

4.5 Step 4：监控执行进度

AI 编程代理可能需要长时间运行（几十分钟到几小时）。使用 Hermes Cron 进行自动监控：

# 创建监控任务，每 5 分钟检查一次进度
hermes cron create \
  --schedule "every 5m" \
  --repeat 12 \
  --script /home/hermes/scripts/monitor-dbview.sh

监控脚本示例：

#!/bin/bash
# ~/.hermes/scripts/monitor-dbview.sh

SESSION="dbview"
HOST="user@192.168.31.200"

OUTPUT=$(ssh $HOST "tmux capture-pane -t $SESSION -p 2>/dev/null | tail -5")

if echo "$OUTPUT" | grep -qi "error\|failed\|fatal"; then
    echo "⚠️ 任务执行遇到错误，请检查"
    exit 1
fi

if echo "$OUTPUT" | grep -qi "committed\|已完成\|all done"; then
    echo "✅ 任务已完成！"
fi

4.6 Step 5：审查、提交与归档

任务完成后：

# 1. 检查 git 状态
ssh user@windows-ip "cd C:\\Projects\\dbview && git status"

# 2. 提交代码
ssh user@windows-ip "cd C:\\Projects\\dbview && git add -A && git commit -m 'feat: 数据导出功能实现'"

# 3. 归档 OpenSpec 变更
# Claude Code 会自动运行 /opsx:archive 将当前变更移入 archive 目录

# 4. 推送到远端
ssh user@windows-ip "cd C:\\Projects\\dbview && git push"

---

五、远程会话管理

5.1 Mac 开发机（tmux）

# 新建会话
ssh user@mac-ip "tmux new-session -d -s project-name 'cd /path && claude'"

# 发送命令
ssh user@mac-ip "tmux send-keys -t project-name '按OpenSpec计划开始实施' Enter"

# 查看输出
ssh user@mac-ip "tmux capture-pane -t project-name -p"

# 复用现有会话（推荐）
ssh user@mac-ip "tmux send-keys -t project-name '新任务' Enter"

重要原则： 始终优先复用已有会话，而不是每次都新建。同一项目只应该有一个 Claude Code 会话。Hermes Agent 的项目配置已经内置了会话复用逻辑。

5.2 Windows 开发机（psmux）

Windows 上推荐使用 psmux（PowerShell 版的 tmux 替代）：

# 新建会话
New-PSSession -Name dbview

# 发送命令（通过 Hermes 自动处理）
# psmux 默认用 PowerShell，中文兼容性比 CMD 好

5.3 远程会话最佳实践

实践	说明
会话命名规范	用项目名命名：dbview、valin-salary
避免多会话并行	同一项目不同任务不要开两个 Claude Code 会话——上下文会互相污染。串行执行或改用独立分支
定时检查可用性	跨天任务可能导致远程会话丢失。启动新任务前先检查会话状态
输出清空	长时间运行的 Claude Code 会累积大量输出，定期 capture 最新内容即可

---

六、自动化与运维

6.1 项目执行自动化

通过 Hermes 的项目配置，将「项目 + 设备 + 工具」绑定，只需一句话就能调度：

{
  "dbview": {
    "device": "win",
    "host": "192.168.31.200",
    "user": "developer",
    "tool": "claude-code",
    "mode": "psmux",
    "workdir": "C:\\Projects\\dbview",
    "shell": "powershell"
  }
}

使用方式：

在 Hermes 对话中：
"在 dbview 项目中执行：用 OpenSpec 创建 v3 版本计划"

# Hermes 自动：
# 1. SSH 到 Windows
# 2. 复用或新建 psmux 会话
# 3. 将命令发给 Claude Code
# 4. 创建监控任务跟踪进度
# 5. 完成时自动清理监控

6.2 定时任务与自愈

Hermes Cron 可以设置任务完成后的自删除，避免监控脚本堆积：

# 一次性监控任务（执行 12 次后自动删除）
hermes cron create \
  --from-prompt "每5分钟检查 dbview 项目远程会话进度，检测到完成则推送消息" \
  --schedule "every 5m" \
  --repeat 12

监控脚本的 self-destruct 模式：

#!/bin/bash
# 检测到完成时自动删除自身
if [ "$(ssh win "cd /proj && git status --porcelain | wc -l")" -eq 0 ]; then
    hermes cron remove dbview-monitor
    echo "✅ dbview 任务已完成，监控已清理"
fi

6.3 子代理模式（Subagent Delegation）

Hermes Agent 支持子代理模式（delegate_task），适合将大型 OpenSpec 计划拆分为多个子任务并行执行：

父 Agent（Hermes）
├── 创建 OpenSpec 变更结构
├── 人类审核
├── 子代理 A：实施 P1-1（Mac）
├── 子代理 B：实施 P2-1（Windows，可并行）
└── 审查结果 → 提交 → 归档

子代理各自运行在独立的上下文中，互不干扰，最终结果合并回父会话。

---

七、常见问题

Q1：Claude Code 在远程会话中卡住不动了怎么办？

现象： 发送命令后长时间无响应（显示 "Shimmying..." 或 "Germinating..."）

原因： LLM 在思考或等待工具执行。这通常是正常行为，不是卡死。

处理：

1. 检查输出：tmux capture-pane -t session -p | tail -10
2. 如果显示的任务最后一行有更新时间，说明还在工作
3. 超过 20 分钟无更新，再考虑重启

Q2：多机并行开发如何处理代码冲突？

方案一：Git Worktree 隔离 每个 Agent 在独立的 worktree 中工作，各自有独立的工作区和分支。

git worktree add ../dbview-agent-a feature/export
git worktree add ../dbview-agent-b feature/perf

方案二：按模块分拆 利用 OpenSpec 的 tasks.md 天然按功能模块分拆，Agent A 改前端、Agent B 改后端，几乎没有冲突。

Q3：Claude Code 批量创建文件时一直询问确认？

在远程 tmux 会话中：

Claude Code: "Do you want to create file X?"
  1. Yes
  2. Yes, allow all edits during this session
  3. No

解决方案：在第一个文件询问时自动选择选项 2：

tmux send-keys -t project-name "2" Enter

这个操作可以通过 cron 监控脚本自动化：检测到 "allow all edits" 关键词时自动发 2。

Q4：Claude Code 提示"Context window full"怎么办？

这是 Claude Code 的常见限制。解决方案：

1. 减短执行窗口：将 OpenSpec tasks.md 的任务拆分得更细，单次实现 2-3 个任务
2. 使用 /compact 命令：Claude Code 内置的上下文压缩功能
3. 重启会话：提交代码后，重启 Claude Code 会话清空上下文

Q5：Windows 上 Claude Code 中文乱码？

确保在项目配置中指定使用 PowerShell 而不是 CMD：

{
  "dbview": {
    "shell": "powershell"
  }
}

同时在远程开发机上检查：

# 确认 PowerShell 的编码
[System.Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Console]::OutputEncoding

Q6：远程 SSH 连接经常断开怎么办？

# 在中央调度机的 ~/.ssh/config 中配置
Host *
    ServerAliveInterval 60
    ServerAliveCountMax 10
    TCPKeepAlive yes

Q7：Hermes Cron 监控任务执行成功但没收到通知？

检查两个地方：

# 1. 验证 cron 任务状态
hermes cron list

# 2. 查看脚本输出
cat ~/.hermes/cron/output/<job-id>.log

常见原因：微信/QQ 等平台接口限流导致的送达失败。如果是这种情况，手动检查任务状态即可。

Q8：多个 Agent 同时写同一个文件怎么办？

永远不要让两个 Agent 同时写同一个文件。 这是黄金法则。如果 OpenSpec 的 tasks.md 显示两个任务有重叠文件，必须串行执行或重新分拆：

❌ 错误：Agent A 改 userService.ts，Agent B 也在改 userService.ts
✅ 正确：Agent A 改 userService.ts（完成后提交），Agent B 改 orderService.ts

---

八、进阶阅读

• OpenSpec 基础概念与 OPSX 工作流 — SDD 入门必读
• OpenSpec 实战指南：从规范到代码的完整工作流 — OPSX 实操案例
• Hermes Agent 多机编排实战 — 多机代理调度
• tmux AI 编程会话管理高级实战 — 远程会话管理
• Claude Code Skills 使用教程 — AI Agent 技能定制
• Spec-Driven Development in 2026 — SDD 2026 全景

---

总结

本文从实战出发，完整讲解了如何部署一个由 SDD 规范驱动的多机 AI 编程代理集群：

阶段	关键操作	工具
基础设施	安装 Hermes Agent、配置 SSH、设置远程项目	SSH、tmux、psmux
规范体系	初始化 OpenSpec、配置 CLAUDE.md	OpenSpec CLI
执行流程	创建 proposal → 审核 → 拆任务 → 分配 Agent	OPSX 命令
监控运维	Cron 监控、批处理审批、自动清理	Hermes Cron
归档总结	提交代码、更新 spec、归档变更	Git、OPSX archive

核心思想只有一句话：先写规范，再写代码；中央调度，多机执行。 在 AI 编程代理越来越普及的今天，这不是一个「是否要做」的问题，而是「什么时候做」的问题。

---

本文基于 Hermes Agent + OpenSpec 的实际生产部署经验编写。 部署日期：2026-07-03 | 环境：Ubuntu 24.04 + macOS + Windows 11