Agentswarm/CLIENT_GUIDE.md

# 客户端接入指南（Client Guide）

本文说明**客户端如何与 Agent Swarm 运行时交互**。系统总览见 [README.md](README.md)；接口契约见 [docs/integration/runtime-contract.md](docs/integration/runtime-contract.md)；事件结构见 [docs/integration/event-schema.md](docs/integration/event-schema.md)。

> 架构说明：生产链路中，终端用户通过 **Heicode Manager / 桌面客户端** 提交需求，由 Manager 调用本 Swarm 运行时（见 `heicode-swarm-deferred` 裁定）。「客户端」在本文指**调用 Swarm 运行时 REST API 的一方**（Manager、联调脚本或开发者）。Swarm 不在对话回路，通过**带签名回调**回报状态。

---

## 1. 两个交互面

1. **REST API（客户端 → Swarm）**：创建部署、查询状态/任务/日志/事件/指标、审批、停止。
2. **回调事件流（Swarm → 客户端/Manager）**：生命周期事件经带 HMAC 签名的回调推送（见 §6）。

WebSocket `/ws/{agent_id}` 仅供 **Agent 执行单元** 接入，**不是客户端接口**。

---

## 2. 鉴权

- 客户端调用带 `Authorization: Bearer <token>`，Swarm 校验 `AGENT_RUNTIME_SERVICE_TOKEN`（兼容 `AGNET_RUNTIME_SERVICE_TOKEN`）。
- 未配置令牌时为**非安全开发模式**（不校验，仅本地）。
- 常用请求头：`X-Correlation-ID`（贯穿追踪）、`X-Idempotency-Key`（创建幂等）。
- 响应信封：成功 `{ "success": true, "data": {...} }`；失败 `{ "success": false, "error": {code,message,request_id} }`。

---

## 3. 生命周期：创建 → 观察 → （审批）→ 停止

### 3.1 创建部署
`POST /api/swarms`（别名 `/api/agent/swarm/deployments`、`/api/agnet/deployments`）

```bash
curl -s -X POST http://<host>:8000/api/swarms \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Correlation-ID: corr-123" \
  -H "X-Idempotency-Key: idem-123" \
  -d '{
        "mode": "swarm",
        "requirement": { "objective": "实现 add(a,b) 并补充测试与说明" },
        "callback": { "url": "https://your-manager/api/agent/callbacks/runtime-events", "subscribed_events": [] },
        "metadata": { "manager_deployment_id": "dep-1" }
      }'
```
必填：`requirement.objective`（或 `orchestration_plan.objective`）、`callback.url`、`metadata.manager_deployment_id`。

响应 `data`：`deployment_id`、`runtime_deployment_id`、`swarm_id`(=workflow_id)、`manager_deployment_id`、`mode`、`status`、`created`。**请保存 `deployment_id`** 用于后续查询。

### 3.2 观察
| 接口 | 用途 |
|---|---|
| `GET /api/swarms/{deployment_id}` | 部署状态概要 |
| `GET /api/swarms/{deployment_id}/workflow` | 工作流/阶段视图（phases、agents、tokens、tools、artifacts、summary） |
| `GET /api/swarms/{deployment_id}/tasks` | 任务 DAG（task_id、agent_role、status、depends_on…） |
| `GET /api/swarms/{deployment_id}/logs`（`/events`） | 事件流，分页 `?limit=&cursor=`（断线后用 cursor 回补） |
| `GET /api/swarms/{deployment_id}/metrics` | 任务/Agent/预算指标 |
| `GET /api/swarms/{deployment_id}/diagnostics` | 失败、回调尝试、审批诊断 |

状态机：`waiting_approval → running → (blocked ⇄ running) → completed | failed | stopped`。

### 3.3 审批（高危操作）
当部署进入 `waiting_approval` 并推送 `approval.requested` 时，客户端经 Manager 审批后回执：
```bash
curl -s -X POST http://<host>:8000/api/swarms/<deployment_id>/approvals/<approval_id> \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "decision": "approved" }'   # 或 "rejected"，可带 credential_ref / reason
```

### 3.4 停止
```bash
curl -s -X POST http://<host>:8000/api/swarms/<deployment_id>/stop \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "reason": "client requested stop" }'
```

---

## 4. 健康检查

- `GET /` → `{status, service}`；`GET /health` → 含 Redis 与连接数；`GET /metrics` → Prometheus。

---

## 5. 工作流（去中心化蜂群 —— 唯一行为，无开关）

本仓**即蜂群运行时**，模式选择（single/chain/sub/swarm）在仓外；**没有「启用 swarm」开关**。下述流程**无条件生效**（cutover 已完成）：编排器**播种**单一目标种子任务 → Agent 感知共享池**自选**（信息素 τ + 能力/负载/预算）→ 经 `task_proposal` **自底向上自主分解**（#7）→ 经 `task_bid`/`yield`/`takeover` **竞争/接管**（#8）→ **同伴交叉评审**（≥2 评审者，#11）→ **收敛**（产出 `termination_reason`，#12），最后 `master_agent.synthesize` 汇总。**已删除**：Master/planner 自顶向下分解兜底、单 critic 主控评审环及其 `ENABLE_PLANNER_FALLBACK` / `ENABLE_REVIEW_LOOP` 等开关。

- `MAX_REVIEW_CYCLES`（默认 2）：交叉评审/重做的轮次预算（保留）。
- `MAX_AGENTS_PER_USER`（默认 10）：每用户并发连接的 Agent 上限（见 security-boundary §6）。
- 仅剩的能力开关：`ENABLE_QUALITY_EVAL` + `HEICODE_SANDBOX_ISOLATED`（代码沙箱评分，见 security-boundary §8.1）、`ENABLE_SUBTASK_HANDOFF`（agent 侧子任务移交）。
- 模型走 HM 模型网关（OpenAI 兼容 `/v1`）：`OPENAI_API_KEY` = **HM 为该用户现签的 per-user `sk-`**（NewAPI token），`OPENAI_API_BASE` = **HM `/v1`**，`OPENAI_MODEL` 为所选模型。由 Agent 平台在拉起 agent 时注入其进程 env（server→server，**不入 create 请求 / 回调 / 日志**）。模型调用**扣发起用户 `user.Quota`**、按 token 名归集计量；详见 [usage-billing-schema.md §2](docs/integration/usage-billing-schema.md)。

---

## 6. 回调事件流（Swarm → 客户端/Manager）

Swarm 向 `callback.url` POST 事件，**带 HMAC 签名**（客户端须验签）：
- 头：`X-Agent-Timestamp`(ms)、`X-Agent-Signature`、`X-Agent-Event-Id`、`X-Correlation-ID`（+ `X-Agnet-` 兼容别名）。
- 签名：`sha256=hex(HMAC_SHA256(secret, "{timestamp}.{event_id}.{raw_body}"))`，secret = `AGENT_CALLBACK_SIGNING_SECRET`，时间容差 300s。
- 幂等：按 `X-Agent-Event-Id` → body `event_id` → `idempotency_key` 去重。
- 事件类型与必填字段：见 [event-schema.md](docs/integration/event-schema.md)（`deployment.status_changed`、`task.*`、`handoff.*`、`approval.requested`、`artifact.created`、`timeline.updated`、`budget.alert`…）。

客户端可只消费 REST（轮询 `/workflow`+`/logs?cursor=`），或同时接收回调。

---

## 7. 本地联调（无需密钥）

```bash
# 1) 编排器（内存存储；蜂群流程无条件生效，无需开关）
set "REDIS_FAKE=1" & set "MAX_REVIEW_CYCLES=2"
python -m uvicorn orchestrator.main:app --host 0.0.0.0 --port 8000
# 2) 无密钥桩 Agent（联调用）
set "ORCHESTRATOR_URL=ws://localhost:8000" & set "AGENT_ID=stub-1" & set "AGENT_CAPABILITIES=python,code_generation,testing,pytest,technical-writing,general"
python scripts/stub_agent.py
# 3) 用 §3.1 的 curl 提交需求，再用 §3.2 观察
```

---

## 8. 说明与边界

- **桌面/前端 UI**：当前桌面客户端为单 Agent A2A 直连模型；**蜂群图 / 协作时间线**的前端事件 API 尚未冻结（见 [frontend-event-api.md](docs/integration/frontend-event-api.md)）。
- **不得在请求/回调/日志中出现明文密钥**；凭据一律 `secret_ref`（`azkv://`）。见 [security-boundary.md](docs/integration/security-boundary.md)。
- **计费主线**：Agent 模型调用走 HM `/v1`，用 **HM 为该用户现签的 per-user `sk-`** 作 `OPENAI_API_KEY`，**扣发起用户 `user.Quota`**；NewAPI 是账本、按请求计量，**Swarm 不是账本、仅上报用量**（随模型请求带 `X-Agent-*` 归因头）。归因主轴 = `user.id`/`channelId`，不引入 tenant。见 [usage-billing-schema.md §1/§2](docs/integration/usage-billing-schema.md)。