gongzhiyongandClaude Opus 4.8
b53e32be78
- jina 工具砍到 allowlist(默认 search_web,read_url),21→2;其余工具不暴露, 减少 prompt 膨胀与误用(env JINA_TOOL_ALLOWLIST 可调)。 - prompt 加 workspace/tool 边界:本地 base_commit 代码是唯一真源,本地读改; web 搜索/read_url 仅用于外部知识(库文档/语言特性/报错查证),严禁取本仓源码 (web 版本≠本地 base_commit,会污染 patch);read_url 不接受 file:// 本地路径。 搜索作为模型验证/补能手段保留,仅约束调用边界。 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 状态。