# Heicode v2.1.6 更新说明

**生成日期**: 2026-05-29  
**适用版本**: `heicode-v2-20260529120632`  
**主文档**: `docs/HEICODE_API_INTEGRATION.md`  
**联调 Base URL**: `http://20.212.121.126`

---

## 1. 更新概览

本次更新面向 Heicode 普通 sub 敏捷模式联调，重点补齐 Agent Manager 作为 Runtime 适配层时需要的创建、查询、回调、审批和观测能力。

核心变化：

- `/api/swarms` 新增 Runtime 兼容入口，可接收 Heicode Manager 的结构化 `orchestration_plan`。
- `/api/agnet/deployments` 支持普通 sub 结构化计划，并会主动发出 Runtime 生命周期 callback。
- 修复普通 sub 真实执行后缺失 `artifact.created` 的问题，并补齐用户态 artifacts 可见性。
- 新增 `task.completed` / `task.failed` / `task.blocked` 事件，用于补齐普通 sub 子任务终态。
- 修复 deployment 已完成但 `agents[].status` 仍为 `running` 的状态不一致问题。
- `/api/swarms/{swarm_id}/logs` 不再返回 Phase 2 固定占位文本，而是输出 Runtime 聚合日志摘要。
- Callback 协议升级到 v2.1 形态，支持 HMAC 签名、幂等事件、`payload.*` 格式和旧 token 过渡兼容。
- 新增 artifact、timeline、SK snapshot 用户态查询接口，数据由 Runtime callback event 投影生成。
- 新增审批 decision 接收路径，覆盖 `/api/swarms` 和 `/api/agnet/deployments` 两种运行入口。
- K8s/Docker 部署配置补充 Heicode、Vault、Redis、模型网关相关环境变量和代码目录。

---

## 2. API 变更

### 2.1 `/api/swarms` Runtime 兼容入口

新增或补齐以下接口：

| 方法 | 路径 | 用途 |
|------|------|------|
| `POST` | `/api/swarms` | 创建 Runtime run，映射到底层 swarm 执行记录 |
| `GET` | `/api/swarms/{swarm_id}` | 查询 run 详情 |
| `GET` | `/api/swarms/{swarm_id}/status` | 查询状态、阶段、进度、Agent 和 artifact 摘要 |
| `POST` | `/api/swarms/{swarm_id}/stop` | 幂等停止 run |
| `GET` | `/api/swarms/{swarm_id}/logs` | 查询 Runtime/Agent 日志聚合兜底 |
| `GET` | `/api/swarms/{swarm_id}/events` | 查询 Runtime message/event 兜底 |
| `GET` | `/api/swarms/{swarm_id}/metrics` | 查询基础用量、耗时和产物数量 |
| `POST` | `/api/swarms/{swarm_id}/approvals/{approval_id}` | 接收 Manager 审批 decision |

创建校验规则：

- `dry_run: true` 会返回 `422`，不会创建真实 run。
- `orchestration_plan` 必须是对象。
- `orchestration_plan.sub_mode` 必须是 `agile` 或 `waterfall`。
- `orchestration_plan.user_context.user_id` 必填。
- `callback.url` 必填。
- 同一个 `X-Idempotency-Key` 会返回已有 run，避免重复创建。

响应兼容：

- `deployment_id` 与 `swarm_id` 同时返回；当前两者同值。
- `/api/agnet/deployments/{deployment_id}` 可查询 `/api/swarms` 创建出的 run。
- `/api/agnet/deployments/{deployment_id}/stop` 可停止 `/api/swarms` 创建出的 run。

### 2.2 `/api/agnet/deployments` 普通 sub 兼容

创建部署现在可以直接接收结构化 `orchestration_plan`，并将字段提升到旧版模型：

- `agents`
- `risk_level`
- `budget`
- `billing_context`
- `resource_grants`
- `metadata`
- `agile_context`
- `sub_mode`
- `callback`

兼容字段：

- `agents[].role_template` 或 `agents[].target_role` 会规范化为 `role`。
- `billing_context.default_model_id` 为空时默认填充为 `default`。
- `billing_context.allowed_model_ids` 为空时默认使用 `default_model_id`。
- `budget.max_usd` 与 `budget.max_cost_usd` 双向兼容。
- `resource_grants` 同时兼容 `type/ref/permissions` 和 `resource_type/secret_ref/permission_scope`。

安全规则：

- `callback.url` 必须使用 `https://`。
- `callback.signing_secret_ref` 必须使用 `azkv://`。
- `billing_context.secret_ref` 必须使用 `azkv://`。
- `resource_grants` 只能传 secret reference，不能传明文凭据。
- 请求体、callback payload、artifact metadata 等仍会执行敏感字段扫描。

---

## 3. Callback 与观测

### 3.1 Runtime 主动回调

`/api/agnet/deployments` 和 `/api/swarms` 创建的任务会根据 `callback.subscribed_events` 主动推送事件。

默认事件集：

- `deployment.status_changed`
- `phase.changed`
- `timeline.updated`
- `agent.started`
- `agent.completed`
- `agent.crashed`
- `task.completed`
- `task.failed`
- `task.blocked`
- `sk_tool.called`
- `sk_tool.completed`
- `sk_tool.failed`
- `approval.requested`
- `budget.alert`
- `artifact.created`

当前 callback 发送端会：

- 使用 `X-Agnet-Event-Id` 做事件幂等标识。
- 使用 `X-Agnet-Timestamp` 和 `X-Agnet-Signature` 做 HMAC 校验。
- 优先从 `callback.signing_secret_ref` 对应环境变量或 Azure Key Vault 解析签名密钥。
- 发送失败时记录 warning，不阻塞 Runtime 执行。

### 3.2 Manager callback 接收端

新增接收接口：

```http
POST /api/agnet/callbacks/swarm-events
```

支持能力：

- v2.1 HMAC callback。
- 旧版 `X-Agnet-Service-Token` 或 `Authorization: Bearer <HEICODE_SERVICE_TOKEN>` 过渡兼容。
- `X-Agnet-Event-Id` 或 body `event_id` 幂等去重。
- `payload.*` 标准载荷格式。
- 旧版顶层 `artifact` 自动合并到 `payload`。
- `swarm_id`、`occurred_at`、`agent_instance_id` 会持久化到事件投影。
- `approval.requested` 会写入审计标记。

联调 schema 接口：

```http
GET /api/agnet/callbacks/swarm-events/schema
```

该接口只返回事件类型、分类、必填字段、阶段枚举和 artifact 类型，不返回 token 或明文密钥。

### 3.3 用户态观测接口

新增或补齐：

| 方法 | 路径 | 数据来源 |
|------|------|----------|
| `GET` | `/api/agnet/user/deployments/{deployment_id}/artifacts` | `artifact.created` callback payload |
| `GET` | `/api/agnet/user/deployments/{deployment_id}/timeline` | timeline、phase、agent、approval、budget、artifact、SK tool 事件合并 |
| `GET` | `/api/agnet/user/deployments/{deployment_id}/sk-snapshots` | `sk_tool.*` 与携带 `sk_snapshot` 的 artifact 事件 |

注意：当前 artifact/timeline/SK snapshot 不是独立表字段化存储，而是由 callback event payload 投影生成。

---

## 4. 审批与预算

审批路径：

| 场景 | 接口 |
|------|------|
| `/api/swarms` run | `POST /api/swarms/{swarm_id}/approvals/{approval_id}` |
| 普通 deployment | `POST /api/agnet/deployments/{deployment_id}/approvals/{approval_id}` |

decision 只接受：

- `approved`
- `rejected`

预算与用量：

- `budget.alert` payload 会包含 `model_id`、token 计数、成本、运行时长、资源秒、`billing_source` 和预算摘要。
- `/api/swarms/{swarm_id}/metrics` 当前返回本地基础聚合，后续可接入真实 Pod 指标与日志后端。

---

## 5. 部署与配置

Docker 镜像：

- 当前部署镜像更新为 `agnettaiji.azurecr.io/ai-agents/agent-manager:heicode-v2-20260529120632`。
- 当前 AKS 线上运行 digest 为 `sha256:8aebf04ff6a4f398d6a9a75583199db2b62f2a29c2aad2390e7225ac59ef52dd`。
- `Dockerfile` 已复制 `config/`、`api/`、`models/`，确保 Heicode 对接模块进入镜像。

新增运行时配置项：

- `HEICODE_SERVICE_TOKEN`
- `REDIS_URL`
- `HEICODE_NEWAPI_BASE_URL`
- `LITELLM_BASE_URL`
- `NAMESPACE_PREFIX`
- `MAX_CONCURRENT_DEPLOYMENTS_PER_USER`
- `MAX_CONCURRENT_DEPLOYMENTS_PER_SCOPE`
- `VAULT_URL`
- `VAULT_TOKEN`

安全提醒：

- K8s Secret 清单在提交或对外分发前应只保留占位符，不应包含真实 Azure、Vault、Gitee 或 Heicode token。
- `azkv://` 是密钥引用，不是明文密钥；Runtime 不应把它展开写入日志、callback、timeline 或 artifact metadata。

---

## 6. 已知限制

- Callback 发送失败当前只记录 warning，不阻塞任务执行；尚未实现完整重试队列、死信队列和人工 replay。
- `/api/swarms/{id}/logs`、`events`、`metrics` 目前是 Runtime/Swarm 本地聚合与轮询兜底，未接入完整日志和指标后端。
- credential lease 的真实凭证兑换仍由 Manager / Vault 链路负责，Runtime 只消费 `credential_ref`。
- artifact/timeline/SK snapshot 当前由 event payload 投影生成，后续如需强查询能力可拆为独立表。
- SSE 实时日志流仍是后续增强项。

---

## 7. 建议联调清单

1. 调用 `GET /api/agnet/health` 确认服务可用。
2. 调用 `GET /api/agnet/callbacks/swarm-events/schema` 确认 callback schema 与事件类型。
3. 使用 `POST /api/swarms` 创建普通 sub 敏捷 run，并传入 `X-Idempotency-Key`。
4. 重复第 3 步确认幂等返回已有 run。
5. 使用缺失 `callback.url`、缺失 `user_context.user_id`、`dry_run:true` 的 payload 验证 `422`。
6. 查询 `/api/swarms/{swarm_id}` 和 `/api/swarms/{swarm_id}/status` 验证 `deployment_id` / `swarm_id` 兼容。
7. 验证普通 sub 实际执行后会收到 `task.completed` / `task.failed` 回调。
8. 验证 Runtime 主动 callback 是否写入 `/api/agnet/user/deployments/{deployment_id}/timeline`。
9. 验证普通 sub 实际执行后会收到 `artifact.created`，并查询 artifacts 不再为 0。
10. 发送 `sk_tool.completed` 或带 `sk_snapshot` 的 artifact callback 后查询 SK snapshots。
11. 触发或模拟 `approval.requested` 后调用 approval decision 接口验证 `approved` / `rejected`。

---

## 8. 相关代码位置

| 模块 | 文件 |
|------|------|
| Heicode API router | `api/agnet/router.py` |
| 部署创建、停止、审批 | `api/agnet/deployments.py` |
| Callback 接收与用户态观测 | `api/agnet/callbacks.py` |
| Heicode 请求/响应模型 | `api/agnet/models.py` |
| Runtime callback 发送端 | `api/swarm/callback_client.py` |
| `/api/swarms` 兼容入口 | `api/swarm/router.py` |
| Swarm callback 触发点 | `api/swarm/orchestrator.py` |
| 数据模型 | `database.py` |
| 配置项 | `config/settings.py` |
| 错误码 | `config/error_codes.py` |
| K8s 配置 | `k8s/agent-manager-configmap.yaml`、`k8s/agent-manager-deployment.yaml`、`k8s/agent-manager-secret.yaml` |