FastheiandClaude Opus 4.8
f9df550ac9
修 #75:蜂群单任务铺不到多 agent。两层根因 + 对应修复(均经本地 k8s 端到端验证):
1) 真实 agent 执行器从未实现 #7「自主分解提案」(autonomous-task-generation.md §4 标为
「后续」;此前只有 stub_agent 演示)。编排器侧 handle_task_proposal 早已就绪,缺 agent 侧出口。
- agent/main.py: 新增 propose_task()(发 WS task_proposal,字段对齐 handle_task_proposal);
execute_task 传入 proposal_callback;control_messages 接受 task_proposal_ack。
- agent/task_executor.py: 新增 _maybe_propose_subtasks() —— 执行顶层种子时用 _parse_task 拆分,
把每个子任务经 proposal_callback 提案入池(由编排器 review→create_task→其他 agent 自选)。
仅顶层种子提案(parent 为空、source 非 agent_proposed/dynamic_handoff),子任务不再递归提案,无环。
env ENABLE_AUTONOMOUS_PROPOSALS(默认 on)可关。
2) _parse_task 又脆又静默退化为单任务(原 max_tokens=2000 截断 + 严格 json.loads + except 兜底):
- max_tokens 可配 AGENT_PLAN_MAX_TOKENS(默认 65536;注:qwen3.7-max 网关上限即 65536,>之 400);
- 新增 _coerce_subtasks 宽容解析(裸数组 / ``` 围栏 / {"subtasks":[...]} / 从文本抠 [...]);
- 解析失败重试 1 次再退化;成功打 INFO "Decomposed into N",退化打明确 WARNING(可观测)。
派发:提案子任务 required_capabilities 置空(像种子,任意空闲 agent 可自选)。否则 LLM 给的具体能力
不是固定能力池子集 → can_agent_run_task 永远拒 → 子任务卡 PENDING(本地实测到的死锁)。能力提示保留在
agent_role(不门控派发);能力感知路由(把子任务能力映射到能力池)作为后续增强,见 #75。
本地验证(Docker Desktop k8s,qwen3.7-max,池16):两次 run 复现「种子→拆 6/8 子任务→派给 6/8 个不同
agent 并行执行」,此前恒为单 agent。
测试(本地全过):test-runtime-contract / test-contract-freeze / test-merge-smoke / test-workflow-e2e /
test-autonomous-tasks / test-agent-launcher / test-convergence。
影响:仅 agent/(执行单元);不动 Manager↔Swarm 冻结契约 / 计费 / 审计 / 编排器接口。
Refs #75
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Agent 执行器（Agent Runtime）
Agent 是蜂群系统中的执行单元（worker）。每个 Agent 作为独立进程运行（在 Kubernetes 中通常是一个 Pod），通过 WebSocket 连接到 Orchestrator，领取任务、调用大模型完成编码工作，并把结果写回 Git 分支。
职责概览
- 通过 WebSocket 连接 Orchestrator，并以自身**能力（capabilities）**注册，例如
python、testing、technical-writing。 - 接收 Orchestrator 下发的任务，使用 OpenAI 兼容的大模型完成子任务。
- 在隔离的「按任务工作目录」中生成/修改文件，并提交到独立的结果分支。
- 支持与其它 Agent 协作（peer collaboration）与移交（handoff）。
- 持续上报心跳、状态与执行结果，并暴露 Prometheus 指标。
目录结构
agent/
├── main.py # Agent 主循环：连接、注册、心跳、消息处理、并发与重连
├── task_executor.py # 任务执行引擎：调用 OpenAI 兼容模型，应用文件改动
├── handoff_logic.py # 移交决策逻辑（复杂度 / 能力 / 预估时长）
├── git_operations.py # Git 克隆、建分支、提交、推送
└── requirements.txt # Python 依赖
核心模块
主循环（main.py）
- 连接与重连：断线后按指数退避自动重连并重新注册。
- 有界并发：通过信号量限制同时执行的任务数（
MAX_CONCURRENT_TASKS），并在注册/心跳中上报剩余容量available_slots。 - 任务受理：对每个分配先做校验，重复任务返回
task_accepted(status=duplicate)，超出容量返回task_rejected，由 Orchestrator 重新入队。 - 执行保护：单任务超时（
TASK_TIMEOUT_SECONDS）与任务取消（cancel_task）。 - 心跳：每 15 秒上报一次存活与容量信息。
- 优雅退出：收到 SIGINT/SIGTERM 时停止接单并清理在执行的任务。
任务执行器（task_executor.py）
- 使用 OpenAI 兼容 API（可指向自定义
base_url）完成子任务。 - 根据上下文中的**依赖产物（dependency_artifacts）与专家角色（specialist_role）**对齐输出：测试与文档以实现产物的行为/异常语义为准。
- 将模型返回的文件改动安全地写入工作目录（带路径越界校验）。
- 记录用量并附带计费/审计归属（
usage与X-Agent/X-Agnet模型归属头），供 Orchestrator 上报。
移交逻辑（handoff_logic.py）
当子任务满足以下条件时建议移交给更合适的 Agent：
- 复杂度为
high； - 需要当前 Agent 不具备的专业能力；
- 预估耗时超过 60 分钟。
Git 操作（git_operations.py）
- 自动识别仓库根目录（
repo_root），使按任务子目录也能在父级 Git 仓库中正确执行。 - 为每个任务创建结果分支（形如
agent/{agent-id}/{task}-{timestamp}），提交并推送。
配置（环境变量）
凭据通过同目录的 .env（已被 .gitignore 忽略）加载，亦可由部署环境/secret_ref 注入。请勿将密钥写入代码或提交记录。
# 模型（OpenAI 兼容）
OPENAI_API_KEY=... # 或 MODEL_API_KEY
OPENAI_API_BASE=https://api.openai.com/v1 # 或 MODEL_API_BASE，可指向自定义端点
OPENAI_MODEL=gpt-4o-mini # 或 MODEL_NAME / MODEL_ID
# 连接与身份
ORCHESTRATOR_URL=ws://localhost:8000 # Orchestrator 的 WebSocket 地址
AGENT_ID=worker-1 # 不填则自动生成
AGENT_CAPABILITIES=python,testing # 逗号分隔的能力列表
WORKSPACE_DIR=/workspace # 工作目录
# 可选
GIT_REPO_URL=https://... # 需在仓库内工作时设置
GIT_USERNAME / GIT_PASSWORD / GIT_TOKEN# 推送凭据
GIT_BASE_BRANCH=main # 结果分支的基线
MAX_CONCURRENT_TASKS=4 # 最大并发任务数
TASK_TIMEOUT_SECONDS=60 # 单任务超时
METRICS_PORT=9000 # 设置后暴露 Prometheus 指标
ENABLE_SUBTASK_HANDOFF=false # 是否启用动态子任务移交
本地运行
pip install -r agent/requirements.txt
# 准备 .env（含 OPENAI_API_KEY 等），然后从仓库根目录运行：
set "ORCHESTRATOR_URL=ws://localhost:8000"
set "AGENT_ID=worker-1"
set "AGENT_CAPABILITIES=python,code_generation,testing,pytest,technical-writing,general"
set "WORKSPACE_DIR=...\tmp-workspace\worker-1"
python -m agent.main
任务执行流程
- 注册：连接 Orchestrator 并上报能力与可用容量。
- 心跳：每 15 秒上报存活与剩余容量。
- 受理：校验分配，必要时拒绝（容量不足）或忽略（重复）。
- 执行：在独立的按任务工作目录中调用模型完成子任务；如启用，可向同伴 Agent 咨询或移交。
- 提交：若为 Git 工作区，提交并推送到结果分支。
- 回报：将结果（含用量）发送回 Orchestrator，并将状态置为空闲。
协作（Peer Collaboration）
当上下文提供了 peer_agents 时，测试/文档等角色可向实现角色发起咨询；被咨询方会回复自己最近一次完成任务的摘要，帮助各专家在重叠领域保持一致。
监控
Agent 暴露的 Prometheus 指标包括：已执行/失败任务数、任务时长、移交次数、重连次数、被拒/重复任务数、当前活跃任务数与 Agent 状态。