# 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` 注入。**请勿将密钥写入代码或提交记录。**

```bash
# 模型（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           # 是否启用动态子任务移交
```

## 本地运行

```bash
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
```

## 任务执行流程

1. **注册**：连接 Orchestrator 并上报能力与可用容量。
2. **心跳**：每 15 秒上报存活与剩余容量。
3. **受理**：校验分配，必要时拒绝（容量不足）或忽略（重复）。
4. **执行**：在独立的按任务工作目录中调用模型完成子任务；如启用，可向同伴 Agent 咨询或移交。
5. **提交**：若为 Git 工作区，提交并推送到结果分支。
6. **回报**：将结果（含用量）发送回 Orchestrator，并将状态置为空闲。

## 协作（Peer Collaboration）

当上下文提供了 `peer_agents` 时，测试/文档等角色可向实现角色发起咨询；被咨询方会回复自己最近一次完成任务的摘要，帮助各专家在重叠领域保持一致。

## 监控

Agent 暴露的 Prometheus 指标包括：已执行/失败任务数、任务时长、移交次数、重连次数、被拒/重复任务数、当前活跃任务数与 Agent 状态。