日常工作知识库

Appearance

ATM (Agent Task Manager) AI 任务调度系统架构与本地在行 Agent (Antigravity / SpecFlow / arkcli) 适配实战 ​

在多 Agent 协同研发的实际场景中，开发团队往往需要在本地宿主机运行多种不同的 AI Agent CLI（如 Antigravity、SpecFlow SDD、Claude Code、arkcli 等）。为了解决任务下发受阻、缺少实时终端流输出、并发冲突以及无法响应交互质询的问题，ATM (Agent Task Manager) 搭建了 "Cloudflare Hub (云端大脑) + 本地守护进程 (Local Daemon)" 的混合云拓扑。

本文系统性归纳 ATM 的架构实现细节、关键攻坚突破以及针对本地在行 Agent 的专项适配方案。

🗺️ 一、 架构拓扑与全景通信流程 ​

🛠️ 二、 核心功能增强与攻坚突破 ​

1. 真实物理进程生命周期控制 (SIGTERM / SIGKILL / SIGSTOP / SIGCONT) ​

  • 根因：原先调用 /cancel 仅修改内存与数据库中的状态字段，未强杀底层 childProcess 句柄，易造成宿主机后台僵尸进程与 CPU 泄漏。
  • 解决：在 [MultiToolAdapter](file:///Users/jinqicheng/Desktop/58work/79team/atm-monorepo/apps/atm-daemon/src/adapters/multi-tool.adapter.ts) 中建立 taskId ➔ ChildProcess 映射表。
    • killTask(taskId)：优先发送 SIGTERM 优雅终止；若 1 秒内未退出，强制发送 SIGKILL 彻底强杀。
    • pauseTask(taskId) / resumeTask(taskId)：利用 POSIX 信号发送 SIGSTOP / SIGCONT，实现任务的真正的挂起与恢复。

2. 双向 stdin 交互流管道注入 (SEND_INPUT) ​

  • 场景：Agent CLI 运行中经常出现需要用户确认（y/n）、选择编号或应答 SpecFlow 的 Grill-Me 质询。
  • 解决：
    • REST 端点：POST /api/local/tasks/:id/stdin（接收 JSON { input: "y" }）。
    • WebSocket 帧：SEND_INPUT 信令帧直接写入 childProcess.stdin。
    • 前端界面：在 Console 终端底部增加带有 Prompt 提示的 stdin 指令注入条与发送按钮。

3. 本地优先级并发队列管理器 (LocalQueueManager) ​

  • 场景：防止离线或并发连续派单时冲垮宿主机资源。
  • 解决：
    • 优先级权重排序：urgent (权重4) > high (3) > normal (2) > low (1)。
    • 并发数受控：设置 maxConcurrentTasks（默认 2），超额任务在内存队列中排队。
    • 超时熔断：支持 timeoutSeconds，超时自动强杀子进程并挂载 TaskStatus.FAILED。

4. 任务交割产物 (Artifacts) 与 Git Diff 捕获 ​

  • 解决：任务退出时，适配器自动在执行工作区探查：
    • 执行 git diff --stat 捕获修改的代码切面与行数。
    • 自动汇总 Markdown 产物（如 SpecFlow 的 .specify/<reqName>/ 契约文档或 Antigravity 的 .agents/skills/ 技能文件），写入 TaskResult.gitDiffSummary 与 artifacts 数组。

🤖 三、 适配本地在行 Agent 的专项方案 ​

在 79team 的开发环境中，针对 3 类在行 Agent 实现了专门的适配器分流逻辑：

1. 🛸 Antigravity Adapter (antigravity.adapter.ts) ​

  • 目标：适配 Google DeepMind Antigravity AI Pair-programming Agent。
  • 逻辑：自动解析 Antigravity 执行指令，探查工作区下由对话生成的产物，并将关联修改的 Patch 总结在 TaskResult 中。

2. 📐 SpecFlow SDD Adapter (specflow.adapter.ts) ​

  • 目标：适配 58 业财 SDD 工具链 (specflow sddx, specflow specify, specflow plan, specflow task, specflow review)。
  • 逻辑：
    • 自动在指令追加 --non-interactive 标志防止盲目挂起。
    • 自动抓取并格式化 .specify/<reqName>/ 目录下的规格与 metrics.json 审计评分报告。

3. 🌋 火山引擎 arkcli Adapter (arkcli.adapter.ts) ​

  • 目标：适配火山引擎 arkcli 命令（支持 volc-codingplan 与 volc-agentplan）。
  • 逻辑：自动绑定 Profile 凭证切面，处理 Responses API 的流式吐出。

🎯 四、 验证结果 ​

经全套单元测试与工程构建验证：

  1. pnpm -r build：TypeScript 编译 100% 通过。
  2. pnpm -r test：apps/atm-worker（2 个测试）与 apps/atm-daemon（7 个测试，包含 queue-and-adapters.test.ts）共 9 个测试用例全部通过。

💡 附：关于图形能力扩展 (Archify 生图技能) 的建议 ​

针对您提出的 “基于 Archify 沉淀 79team 私有生图技能，或丰富到 /knowledge-base 让生成的文章具备图形能力” 的设想，给出如下落地建议：

  1. VitePress 原生渲染 (最轻量建议)：
    • 当前 /knowledge-base 基于 VitePress 构建，系统已原生支持 Mermaid 语法（如本文开头的 sequenceDiagram）。VitePress 会将其在前端直接渲染为矢量 SVG 图表，无额外生图脚本依赖。
  2. 沉淀 79team-archify 专属生图技能 (推荐扩展)：
    • 可以在 .agents/skills/archify-diagrams/ 或 ~/.gemini/config/skills/ 中集成基于 Archify / Puppeteer / CLI 的架构图生成 Skill。
    • 当 Agent 在编写知识库文章或设计 SpecFlow 架构时，可通过 Skill 输入 Markdown / 代码结构，自动导出高保真 png/svg 图片并存入 site/public/ 供文章引用。