异构双 Agent 协同：构建无人值守的长任务自动化研发流水线

1. 背景与工程痛点

在面对大规模存量代码治理（例如将老旧医疗系统数十个页面的空值判断标准化、批量补齐 TypeScript 类型声明或全量清除非规范 API）时，依赖单会话单 Agent 的交互模式通常会暴露三项关键工程缺陷：

半自动化的"伪连续性"
通用 Agent 为保证操作安全，默认倾向于在完成单步文件编辑后暂停等待人类用户的交互确认（Confirmation Loop）。在面对包含数十个步骤的长链路任务时，开发者往往被迫退化为"人工继续按钮点击器"，开发注意力被严重切碎。
长会话的上下文膨胀与漂移
随着多轮交互的积累，上下文窗口（Context Window）急剧膨胀，不仅导致单次请求响应延迟上升，还极易引发指令遵循度下降（Attention Degradation），导致后半程修改偏离既定规则。
推理成本与任务性质不匹配
对全仓 50 个文件进行结构固定的语法替换与规范调整，本质属于高吞吐、低创意的"确定性实现"工作。若全程依赖顶层高级推理模型反复携带全量历史上下文，会造成高昂且不必要的 Token 消耗。

为解决上述问题，我们需要将系统架构设计、任务状态机调度、具体代码落地与质量门禁进行分层解耦。

2. 系统架构设计：分层协作模型

本方案引入类似经典分布式系统中的"主控节点（Master）- 工作节点（Worker）- 仲裁门禁（Arbiter）"拓扑结构：

复制代码

                ┌──────────────────────────────────────────────┐
                │        架构规划与监管层 (Supervisor)           │
                │        Google Antigravity (反重力)           │
                │  - 深度业务需求理解与依赖拓扑分析           │
                │  - 任务原子化拆解与标准化指令定义           │
                │  - 对齐团队架构规范 (CLAUDE.md / DATA-08 等) │
                └──────────────────────┬───────────────────────┘
                                       │ 1. 结构化任务入队
                                       ▼
                ┌──────────────────────────────────────────────┐
                │          任务状态机队列 (Task Queue)         │
                │          .agents/tasks/queue.json            │
                │  - 状态流转: PENDING ➔ RUNNING ➔ COMPLETED   │
                │  - 持久化元数据、重试计数与断点恢复         │
                └──────────────────────┬───────────────────────┘
                                       │ 2. 调度执行
                                       ▼
                ┌──────────────────────────────────────────────┐
                │          批量执行计算层 (Headless Worker)    │
                │              本地 ZCode CLI                  │
                │  - 无头静默执行代码编写与文件落地 (--mode yolo)│
                │  - 吞吐批处理任务，利用独立配额资源          │
                └──────────────────────┬───────────────────────┘
                                       │ 3. 产出变更 (Git Diff)
                                       ▼
                ┌──────────────────────────────────────────────┐
                │          自动化质量门禁 (Quality Gatekeeper)  │
                │  - 静态代码检查 (yarn lint-gate)             │
                │  - 单元测试与语法构建验证                   │
                │  - ✅ 门禁通过 ➔ 状态标记 COMPLETED ➔ 推进下一项│
                │  - ❌ 门禁失败 ➔ 捕获终端报错 ➔ 注入下一轮自愈  │
                └──────────────────────────────────────────────┘

角色职责划分

分层	承担主体	核心职责
决策与监管层 (Supervisor)	Google Antigravity	1. 业务上下文理解与技术方案定型； 2. 任务队列生成与边界约束规范； 3. 复杂异常场景下的架构级介入与仲裁。
状态调度层 (State Machine)	Queue Engine	1. 任务进度持久化，提供断点续传（Checkpoint Recovery）； 2. 维持原子任务的依赖流转，防止竞态冲突。
无头执行层 (Worker)	ZCode CLI	1. 接收标准化提示词，以非交互式方式快速修改源码； 2. 承载大吞吐、高 Token 消耗的代码生成体力活。
质量门禁层 (Gatekeeper)	Automated Pipeline	1. 严格阻断未通过 ESLint、类型检查与编译的代码合入； 2. 为有界自动纠偏重试（Bounded Self-Healing）提供即时反馈源。

3. 本地环境打通与全双工 CLI 集成

为了支撑该架构在真实 Windows 生产设备上稳定运行，必须解决两个本地 AI 实例之间的跨进程调用与无头执行通道。

3.1 ZCode CLI 环境集成与无头参数

ZCode 在其客户端分发包内部自带了完整的 Node.js CLI 工具链（D:\Programs\ZCode\resources\glm\zcode.cjs）。在实际集成时，需解决两项底层约束：

Provider 依赖路径修复 ：CLI 进程默认从当前工作路径寻址配置，需通过 Windows 目录联结（Junction）将其软链映射至核心配置源：
powershell 复制代码
```
cmd /c mklink /J "D:\Programs\ZCode\resources\glm\provider" "D:\Programs\ZCode\resources\config\provider"
```
全局别名封装与静默模式激活 ：
在系统 PATH 目录下建立包装器 zcode.cmd，并利用 --mode yolo 激活无头全权限静默执行模式：
powershell 复制代码
```
# 验证执行连通性
zcode -p "请输出测试状态" --cwd "d:\Documents\web_toproemr" --mode yolo
```

3.2 Antigravity CLI (`agy.exe`) 的反向接入

为实现双向全双工调用，系统探查并打通了位于用户 AppData 下的官方 CLI 驱动 agy.exe：

-p / --print：提供非交互式结果打印；
--dangerously-skip-permissions：授权 CLI 自动审批合规工具调用，避免弹窗中断。

双向调度矩阵：

Antigravity ➔ ZCode ：zcode -p "<prompt>" --cwd <repo> --mode yolo，用于下派批量改动；
ZCode ➔ Antigravity ：agy -p "<complex-task>" --dangerously-skip-permissions，用于在 Worker 遇到死锁或复杂架构决策时反向请求高级推理参谋。

4. 核心组件实现：任务状态机与自动化看门狗

长任务流水线能否可靠运行，取决于状态持久化 与故障自愈能力。

4.1 任务队列契约设计 (`queue.json`)

队列采用原子化 JSON 格式持久化在 .agents/tasks/queue.json 中：

json 复制代码

{
  "jobId": "job_1792761052471",
  "title": "病区表单空值与 0 值判定规范化改造",
  "defaultWorker": "zcode",
  "tasks": [
    {
      "id": "T1",
      "title": "检查 adviceExcuteToal 模块空值判定",
      "prompt": "严格遵循 DATA-08 规则，检查 assets/apps/inpNurse/pages/adviceExcuteToal 目录，禁止使用 !val，必须显式区分 0 与 null/undefined...",
      "status": "pending",
      "worker": "zcode",
      "retryCount": 0,
      "maxRetries": 2,
      "verifyCommand": "yarn lint-gate"
    }
  ]
}

4.2 自动化看门狗流水线 (`scripts/task-runner.cjs`)

执行器脚本作为主进程，负责管理子任务的生命周期、状态转移以及质量门禁判决：

javascript 复制代码

// 核心状态调度与门禁仲裁逻辑简化实现
function runQueue(options = {}) {
  const queue = loadQueue(DEFAULT_QUEUE_FILE);

  for (const task of queue.tasks) {
    if (task.status === 'completed') continue;

    task.status = 'in_progress';
    saveQueue(queue);

    let passed = false;
    let errorFeedback = '';

    while (!passed && task.retryCount < task.maxRetries) {
      // 1. 调用 Worker (ZCode) 执行无头改动
      const workerRes = executeWorker(task.worker, task.prompt, errorFeedback);

      // 2. 执行后置质量门禁校验
      const verifyRes = verifyResult(task.verifyCommand);

      if (verifyRes.passed) {
        passed = true;
        task.status = 'completed';
        task.completedAt = new Date().toISOString();
        saveQueue(queue);
      } else {
        // 3. 门禁失败：捕获报错反哺给下一次 Prompt 进行精准修复
        task.retryCount++;
        errorFeedback = verifyRes.output;
        saveQueue(queue);
      }
    }

    if (!passed) {
      task.status = 'failed';
      saveQueue(queue);
      console.error(`[task-runner] 任务 ${task.id} 阻断流水线，等待人工决策。`);
      break;
    }
  }
}

5. 工程收益与指标评估

与传统的单 Agent 对话式改造相比，该异构双 Agent 架构在长任务场景下表现出显著的技术与经济优势：

5.1 Token 消耗与成本优化

模式	上下文管理方式	主模型单轮 Token 消耗	综合成本模型
单 Agent 全量交互	多轮累加，长上下文持续膨胀	30k ~ 100k+ / 每轮	随任务复杂度呈超线性增长
双 Agent 分层协同	Supervisor 下发精炼指令，上下文立即释放	300 ~ 800 / 每轮	低且恒定；繁重生成的计算量转移给本地/专项配额（如 1024 程序员节福利套餐）

5.2 交付确定性与工程规范保障

绝对门禁准入 ：每一个原子改动必须通过实际项目的 yarn lint-gate 增量检查与编译验证。代码质量依赖确定性的工程工具链（ESLint、TypeScript Compiler），而非大模型的概率性自查。
零中断断点恢复 ：无论任务执行中途因断网、超时还是进程退出中断，执行器均依据 queue.json 维持的状态快照在数秒内原地重启，彻底消除重构遗漏。

6. 结语

在现代大模型辅助研发范式中，单个全能 Agent 的性能边界往往受限于上下文容量与高昂的决策成本。

通过将系统解构为 "高推理监督者（Supervisor）+ 高吞吐执行者（Worker）+ 确定性质量门禁（Quality Gate）"，我们得以将异构 AI 工具链深度融合到真实的软件工程生命周期中。这种兼具架构严谨性与资源经济性的工作流，为应对超大规模存量代码重构与无人值守持续治理，提供了一种兼具可行性与工程美感的工业级解法。