内容
# AI Agent Hub
AI Agent Hub 是一个运行在 Windows 上的轻量级 MCP 调度服务。它让 Claude Code、Codex
等主 Agent 通过统一工具调用本地 CLI Coding Agent。
V1 已完成稳定、安全、可审计的 CLI Agent 调用链路；V2-M1 已交付确定性工程门禁，
V2-M2 已交付 Worktree 隔离，V2-M3 已交付 Review 与集成门禁。当前进入 V2-M4
“安全并行调度”。
项目当前里程碑、验收证据和下一步统一记录在 [docs/PROJECT-STATUS.md](docs/PROJECT-STATUS.md)。
## 当前能力
- Java 17 + Maven
- 官方 MCP Java SDK 2.0.0
- stdio MCP Server
- `list_agents`、`get_task`、`list_tasks`、`submit_agent_task`、`cancel_task`、`run_agent`、`run_review` 与 `cleanup_worktree`
- Codex CLI Adapter
- Qoder CLI Adapter（`qodercli -p` 非交互模式）
- Generic CLI Adapter
- Windows 原生进程启动，不拼接 Shell 命令字符串
- stdin UTF-8 任务传输
- 超时、进程树终止、stdout/stderr 捕获和输出上限
- 工作目录白名单、Agent 命令白名单、环境变量白名单
- Git 仓库和干净工作区校验
- JSONL 审计日志及 stdout/stderr 独立日志
- 跨 Hub 进程的工作区文件锁
- `scope.include` / `scope.exclude` 文件范围强制校验
- 服务端白名单 Verification Profile 和自动质量门禁
- Agent 与验证命令的独立输出日志
- Git Worktree 隔离执行、唯一任务分支、跨进程生命周期锁与幂等清理
- retained Worktree 上的独立只读 Reviewer 与 `run_review` MCP 工具
- JSON Schema 约束、独立最终响应文件和严格 Review JSON 解析
- 内容 SHA-256 指纹与 Git HEAD/分支/索引状态双重不可变性检查
- Worker、Review、集成验证组合的确定性 `ready_for_integration` / `changes_requested` 门禁
- `.tasks/<runId>.json` 原子任务快照、严格状态迁移和 Hub 重启后 Review 恢复
- 服务端持久化队列、确定性 Worker Dispatcher、Scope 冲突门禁和跨进程全局/仓库/Agent 配额槽位
- `get_task` 与可按状态、Agent、仓库过滤的稳定排序 `list_tasks`
- 立即返回持久化 `queued` 快照、后台复用同一 Dispatcher 的 `submit_agent_task`
- 排队任务以及本 Hub 自有 Worker/Verification 进程树的幂等 `cancel_task`
## 架构
```text
Claude Code / Codex
|
| MCP tools
v
AI Agent Hub (Java)
|
+-- AgentRegistry
+-- AgentAdapter
+-- ProcessRunner
+-- GitVerifier / ScopeVerifier
+-- WorkspaceLockManager
+-- WorktreeManager
+-- ReviewService / ReviewOutputParser
+-- WorkspaceFingerprinter
+-- TaskStore / TaskRecord
+-- ScopeConflictDetector / SchedulingCapacityManager
+-- SchedulingDispatcher / TaskQuery
+-- VerificationRunner
+-- AuditLogger
|
v
Codex CLI / Generic CLI
|
v
Allowed Git workspace
```
## 环境要求
- Windows 10/11
- JDK 17 或更高版本
- Maven 3.9+
- Git
- 至少一个已安装并登录的 CLI Agent
本机默认 Java 仍可能是 Java 8。构建前请显式设置 JDK 17：
```powershell
$env:JAVA_HOME = "D:\App\JDK\JDK17"
$env:Path = "$env:JAVA_HOME\bin;$env:Path"
java -version
```
## 构建与测试
```powershell
mvn clean package
```
生成的可执行文件：
```text
target\ai-agent-hub.jar
```
仅运行常规测试：
```powershell
mvn test
```
显式运行真实 MCP + Codex E2E：
```powershell
mvn -Dtest=McpV2E2eTest -DaiAgentHub.e2e=true test
```
该 E2E 会真实调用 Codex CLI，默认构建会跳过；仅在里程碑验收或显式回归时运行。
## 配置
编辑 `config/agents.yml`：
```yaml
allowedWorkspaceRoots:
- "D:/Study/MY_PROJECT"
logsDirectory: "logs"
worktreesDirectory: "worktrees"
worktreeBranchPrefix: "ai-agent-hub/task"
requireCleanWorkspace: true
maxOutputBytes: 1048576
scheduling:
maxConcurrentTasks: 4
maxConcurrentPerRepository: 2
defaultMaxConcurrentPerAgent: 1
agentLimits:
codex: 1
qoder: 1
queueCapacity: 100
heartbeatIntervalSeconds: 5
staleAfterSeconds: 30
verificationProfiles:
maven-test:
displayName: Maven tests
command: [mvn.cmd, test]
timeoutSeconds: 600
agents:
codex:
adapter: codex
command: codex.cmd
enabled: true
capabilities: [code, review, test]
timeoutSeconds: 1800
qoder:
adapter: qodercli
command: qodercli.exe
enabled: true
capabilities: [code, review, test]
timeoutSeconds: 1800
```
安全规则：
- `workspace` 必须位于 `allowedWorkspaceRoots` 之下。
- 默认要求 Git 工作区干净，避免把旧修改误认为本次结果。
- MCP 参数不能传入任意命令；Agent 和验证命令只能来自配置白名单。
- `in_place` 模式下同一工作区不能并发执行；Worktree 创建阶段使用短时基准仓库锁。
- Worktree 根目录必须位于目标仓库之外，任务分支必须位于配置的分支前缀下。
- Worktree 成功或失败后默认保留；脏 Worktree 只有显式 `force: true` 才能清理。
- `scope` 使用工作区相对路径，支持 `*`、`**` 和 `?`。
- Agent 越界修改不会被视为成功，返回状态为 `scope_violation`。
- Codex Worker 固定使用 `workspace-write`；Reviewer 固定使用 `read-only`、JSON Schema 和独立
最终响应文件，不会添加绕过审批和沙箱的危险参数。
- Reviewer 前后同时核对内容指纹与 Git 状态；任何内容、HEAD、分支、索引或未跟踪状态漂移
都会阻止集成。
## 启动
```powershell
$env:AI_AGENT_HUB_JAVA_HOME = "D:\App\JDK\JDK17"
.\scripts\run-hub.cmd
```
stdio 模式下，stdout 只能用于 MCP JSON-RPC。服务日志写入 stderr 或 `logs/`。
## 接入 Claude Code
Claude Code 在 Windows 上需要找到 Git Bash：
```powershell
$env:CLAUDE_CODE_GIT_BASH_PATH = "D:\App\Git\Git\bin\bash.exe"
```
构建 JAR 后注册项目级 MCP Server：
```powershell
claude mcp add --scope project -e AI_AGENT_HUB_JAVA_HOME=D:\App\JDK\JDK17 ai-agent-hub -- D:\Study\MY_PROJECT\AI-Agent-Hub\scripts\run-hub.cmd
```
检查配置：
```powershell
claude mcp get ai-agent-hub
claude mcp list
```
然后重新启动 Claude Code，并通过 `/mcp` 确认能看到：
- `list_agents`
- `get_task`
- `list_tasks`
- `submit_agent_task`
- `cancel_task`
- `run_agent`
- `run_review`
- `cleanup_worktree`
## MCP 请求示例
```json
{
"agentId": "codex",
"workspace": "D:/Study/MY_PROJECT/demo-project",
"timeoutSeconds": 900,
"task": {
"title": "实现 Todo 删除功能",
"goal": "增加删除接口并补充测试",
"files": ["TodoService", "TodoController"],
"constraints": ["不要修改数据库结构"],
"acceptanceCriteria": ["测试通过", "只修改 Todo 模块"]
},
"scope": {
"include": ["src/main/java/**/todo/**", "src/test/java/**/todo/**"],
"exclude": ["src/main/java/**/migration/**"]
},
"verificationProfile": "maven-test",
"isolation": {
"mode": "worktree",
"baseRef": "HEAD",
"retention": "retain"
}
}
```
`scope` 省略时不限制文件；`verificationProfile` 省略时不执行额外验证。验证命令不能由 MCP
请求临时指定，只能选择 `config/agents.yml` 中已有的 Profile。`isolation` 省略时保持兼容，
继续使用 `in_place`；指定 `mode: worktree` 后，Agent、Git 快照和验证命令都在独立 Worktree
中运行。
`run_agent` 会同步等待排队和执行。需要立即返回时，使用相同请求结构调用
`submit_agent_task`；它会在安全预检后返回 `queued` 快照，后台继续执行。返回的 `runId`
同时是持久化 `taskId`。可随时读取最新任务快照：
```json
{
"taskId": "run-20260715-001"
}
```
任务可以用 `cancel_task` 和同一个 `taskId` 幂等取消。`queued` 会原子迁移为 `cancelled`；
由当前 Hub 通过 `submit_agent_task` 启动且处于 `starting`、`running` 或 `verifying` 的任务，
会先迁移为 `cancel_requested`，受控终止 Worker/Verification 进程树，并仅在确认退出后写入
`cancelled`。跨 Hub 实例、同步调用和 `reviewing` 尚无可验证句柄时会明确失败关闭，不会伪造
已取消状态；取消不会删除 Worktree、分支、日志或审计证据。
也可以用 `list_tasks` 稳定排序查询；所有字段均可省略，`limit` 默认为 100、最大为 1000：
```json
{
"state": "worker_succeeded",
"agentId": "codex",
"workspace": "D:/Study/MY_PROJECT/demo-project",
"limit": 50
}
```
Worktree 结果的 `execution` 会返回 `mode`、`baseWorkspace`、`workspace`、`baseRef`、
`baseCommit`、`branch`、`headCommit` 和 `retained`。Review 时必须把完整 `execution`
和原 Worker `runId` 传给 `run_review`：
```json
{
"reviewerAgentId": "codex",
"workerRunId": "run-20260715-001",
"execution": {
"mode": "worktree",
"baseWorkspace": "D:/Study/MY_PROJECT/demo-project",
"workspace": "D:/Study/MY_PROJECT/ai-agent-hub-worktrees/demo-project-run-20260715-001",
"baseRef": "HEAD",
"baseCommit": "0123456789abcdef",
"branch": "ai-agent-hub/task/run-20260715-001",
"headCommit": "0123456789abcdef",
"retained": true
},
"focus": ["correctness", "security", "tests"],
"standards": ["No public API regression"],
"integrationVerificationProfile": "maven-test"
}
```
Review 只返回结构化 Finding 和确定性的 `gateStatus`，不会自动合并或清理。结果为
`ready_for_integration` 后仍需由后续流程显式集成；`changes_requested` 或其他失败状态会
保留现场。清理时把 `execution` 传给 `cleanup_worktree`；存在未提交修改时必须显式设置
`force: true`，清理接口可重复调用。
Worker 结果状态包括 `success`、`failed`、`timeout`、`scope_violation`、
`verification_failed` 和 `workspace_busy`。
将任务交给 Qoder 时，只需把 MCP 请求中的 `agentId` 改为 `qoder`：
```json
{
"agentId": "qoder",
"workspace": "D:/Study/MY_PROJECT/demo-project",
"task": {
"title": "实现 Todo 删除功能",
"goal": "增加删除接口并补充相关测试"
}
}
```
## V2 当前进度
V2-M1“确定性工程门禁”已完成，交付提交为 `35e27d1`；16 项常规测试和 1 项真实
MCP + Codex E2E 均已通过。
V2-M2“Git Worktree 与任务分支生命周期”已完成，交付提交为 `cc04d72`：`run_agent`
支持隔离执行，结果和审计返回完整执行上下文，双任务可以并行运行，`cleanup_worktree`
支持安全幂等清理。
V2-M3“Review 与集成门禁”已完成，交付提交为 `c62418b`：新增只读 Reviewer、结构化
Finding、内容指纹与 Git 状态双重不可变性、集成验证和确定性“可集成/需返工”门禁。
当前里程碑为 V2-M4“安全并行调度”。持久化任务注册表、调度配置、保守 Scope 冲突判定、
跨进程配额槽位和确定性 Worker Dispatcher 已经落地；同步 `run_agent` 与异步
`submit_agent_task` 复用同一执行链路，`get_task` / `list_tasks` 可跨重启查询任务，
`cancel_task` 已覆盖排队任务及本 Hub 自有的 Worker/Verification 进程树。当前继续实现
持久化运行所有权、心跳和孤儿对账。
详细任务、验收条件、证据和风险以
[`docs/PROJECT-STATUS.md`](docs/PROJECT-STATUS.md) 为准；Worktree 边界见
[`docs/V2-WORKTREE-DESIGN.md`](docs/V2-WORKTREE-DESIGN.md)；Review 设计见
[`docs/V2-REVIEW-DESIGN.md`](docs/V2-REVIEW-DESIGN.md)；并行调度契约见
[`docs/V2-PARALLEL-SCHEDULING-DESIGN.md`](docs/V2-PARALLEL-SCHEDULING-DESIGN.md)。
## 测试范围
自动测试覆盖：
- YAML 配置加载
- Codex 命令构建和危险参数检查
- UTF-8 stdin/stdout
- 非零退出码和 stderr
- 超时与进程终止
- 输出截断
- Git 仓库、干净状态和变更文件识别
- Generic Adapter 到日志和 Git 结果的服务级链路
- 跨实例工作区锁竞争和释放
- 文件范围匹配、排除与路径逃逸检查
- 验证 Profile 加载、执行、跳过和审计日志
- 空字符分隔的 Git 路径、空格文件名和重命名识别
- Worktree 创建、查询、残留对账、生命周期锁、脏目录保护与幂等清理
- `run_agent` 隔离执行、结构化执行结果、审计字段与双任务安全并行
- Review JSON Schema、严格字段/枚举/路径/结论一致性解析
- 工作区内容指纹、Git HEAD/分支/索引状态漂移检测
- 只读 Reviewer、Worker 门禁短路、Finding、集成验证、审计和确定性 Gate 状态
- Reviewer 与清理之间的 retained Worktree 生命周期互斥
- 任务快照原子替换、严格字段/状态机校验、并发终态写入和跨 Hub 实例 Review 恢复
- 调度数值约束、未知字段拒绝、静态路径前缀冲突和跨实例配额获取/释放
此外，项目已经在 Windows 上完成真实链路验证：
```text
MCP initialize
-> tools/list 发现 run_agent / submit_agent_task / get_task / list_tasks / cancel_task / run_review / cleanup_worktree
-> run_agent(codex, isolation=worktree)
-> Hub 创建任务分支与独立 Worktree
-> Codex Worker 与 Verification 在 Worktree 内运行
-> Hub 返回 changedFiles 与完整 execution
-> run_review(codex, retained execution)
-> Codex Reviewer 在 read-only 沙箱输出符合 Schema 的独立 JSON
-> Hub 核对内容指纹和 Git 状态，执行集成 Verification
-> gateStatus=ready_for_integration
-> cleanup_worktree(force=true)
-> 第二次清理返回 alreadyAbsent
```
更完整的设计背景参见 `docs/Windows-AI-Agent-Hub-Architecture-Whitepaper-V2.md`。
