Update Heicode integration docs

2026-05-29 21:30:00 +08:00
parent bef6f71bb2
commit d0f74542ce
3 changed files with 2389 additions and 0 deletions
@@ -0,0 +1,493 @@
+# Heicode 对接需求实现情况报告
+
+**生成日期**: 2026-05-12  
+**最近同步**: 2026-05-29  
+**对比文档**: `plans/Agent-Manager-Heicode对接需求文档(2).md`  
+**当前分支**: `feature/code-ai-agent-test`  
+**部署版本**: `heicode-v2-20260529120632`
+
+> 2026-05-29 补充：本文最初记录 Phase 1-5 实现状态。最新普通 sub 敏捷模式联调更新请优先阅读 `docs/HEICODE_V2_1_4_UPDATE_SUMMARY.md` 和 `docs/HEICODE_API_INTEGRATION.md`。下方保留原阶段性报告结构，并同步标注 v2.1.6 已补齐的能力。
+
+---
+
+## 📊 总体实现进度
+
+| 类别 | 需求数量 | 已实现 | 部分实现 | 未实现 | 完成度 |
+|------|---------|--------|---------|--------|--------|
+| **核心 API 接口** | 12 | 11 | 0 | 1 | 92% |
+| **认证和安全** | 5 | 5 | 0 | 0 | 100% |
+| **数据模型** | 8 | 8 | 0 | 0 | 100% |
+| **K8s 集成** | 6 | 4 | 2 | 0 | 67% |
+| **Vault 集成** | 4 | 2 | 2 | 0 | 50% |
+| **模型网关路由** | 3 | 3 | 0 | 0 | 100% |
+| **总计** | 38 | 33 | 4 | 1 | **87%** |
+
+### v2.1.6 新增完成项
+
+| 能力 | 状态 | 说明 |
+|------|------|------|
+| `/api/swarms` Runtime 兼容入口 | ✅ 完成 | 支持创建、详情、状态、停止、日志、事件、指标和审批 decision |
+| Runtime 主动 callback | ✅ 完成 | 支持 status、phase、timeline、agent、tool、artifact、approval、budget 事件 |
+| 普通 sub artifact 回调 | ✅ 完成 | 普通 sub agent 真实执行完成后会生成 `artifact.created`，用户态 artifacts 不再固定为 0 |
+| 普通 sub task 终态 | ✅ 完成 | 新增 `task.completed` / `task.failed` / `task.blocked` 回调 |
+| deployment/agent 状态一致性 | ✅ 完成 | deployment 完成或失败时，agents 会同步进入终态 |
+| `/api/swarms/{id}/logs` 兜底日志 | ✅ 完成 | 返回 Runtime 聚合日志摘要，而不是固定占位文本 |
+| Callback HMAC/幂等接收 | ✅ 完成 | 支持 v2.1 HMAC，兼容旧 service token |
+| artifact 查询 | ✅ 完成 | `GET /api/agnet/user/deployments/{deployment_id}/artifacts` |
+| timeline 查询 | ✅ 完成 | `GET /api/agnet/user/deployments/{deployment_id}/timeline` |
+| SK snapshot 查询投影 | ✅ 完成 | `GET /api/agnet/user/deployments/{deployment_id}/sk-snapshots` |
+| 审批 decision | ✅ 完成 | 支持 `/api/swarms/.../approvals/...` 与 `/api/agnet/deployments/.../approvals/...` |
+
+---
+
+## ✅ 已完成功能（33项）
+
+### 1. 核心 API 接口（11/12）
+
+#### ✅ 已实现的接口
+
+| 接口 | 路径 | 状态 | 文件位置 |
+|------|------|------|----------|
+| 1️⃣ 健康检查 | `GET /api/agnet/health` | ✅ 完成 | `api/agnet/router.py:20` |
+| 2️⃣ 创建部署 | `POST /api/agnet/deployments` | ✅ 完成 | `api/agnet/deployments.py:123` |
+| 3️⃣ 列出部署 | `GET /api/agnet/deployments` | ✅ 完成 | `api/agnet/deployments.py:346` |
+| 4️⃣ 获取部署详情 | `GET /api/agnet/deployments/{id}` | ✅ 完成 | `api/agnet/deployments.py:408` |
+| 5️⃣ 停止部署 | `POST /api/agnet/deployments/{id}/stop` | ✅ 完成 | `api/agnet/deployments.py:469` |
+| 6️⃣ 获取日志 | `GET /api/agnet/deployments/{id}/logs` | ✅ 完成 | `api/agnet/deployments.py:596` |
+| 7️⃣ 获取事件 | `GET /api/agnet/deployments/{id}/events` | ✅ 完成 | `api/agnet/deployments.py:679` |
+| 8️⃣ 获取指标 | `GET /api/agnet/deployments/{id}/metrics` | ✅ 完成 | `api/agnet/deployments.py:731` |
+| 9️⃣ Runtime 兼容入口 | `POST /api/swarms` | ✅ 完成 | `api/swarm/router.py` |
+| 🔟 Callback 接收 | `POST /api/agnet/callbacks/swarm-events` | ✅ 完成 | `api/agnet/callbacks.py` |
+| 1️⃣1️⃣ 用户态观测 | `/api/agnet/user/deployments/{id}/{artifacts,timeline,sk-snapshots}` | ✅ 完成 | `api/agnet/callbacks.py` |
+
+**实现亮点**:
+- ✅ 完整的请求/响应模型定义
+- ✅ 幂等性支持（Idempotency-Key）
+- ✅ 分页支持（cursor-based）
+- ✅ 日志脱敏机制
+- ✅ 审计日志记录
+- ✅ 错误码标准化
+
+### 2. 认证和安全（5/5）
+
+| 功能 | 状态 | 实现位置 |
+|------|------|----------|
+| Service Token 认证 | ✅ 完成 | `api/agnet/auth.py:verify_service_token` |
+| Header 提取和验证 | ✅ 完成 | `api/agnet/auth.py:extract_headers` |
+| 敏感字段检测 | ✅ 完成 | `api/agnet/validators.py:validate_no_sensitive_fields` |
+| Vault 引用验证 | ✅ 完成 | `api/agnet/validators.py:validate_vault_references` |
+| 审计日志记录 | ✅ 完成 | `api/agnet/deployments.py:create_audit_log` |
+
+**实现细节**:
+```python
+# 认证中间件
+@router.post("/deployments")
+async def create_deployment(
+    token: str = Depends(verify_service_token)  # ✅ Token 验证
+):
+    headers = extract_headers(request)  # ✅ Header 提取
+    validate_no_sensitive_fields(payload)  # ✅ 敏感字段检测
+    validate_vault_references(payload)  # ✅ Vault 引用验证
+```
+
+### 3. 数据模型（8/8）
+
+| 模型 | 状态 | 文件位置 |
+|------|------|----------|
+| CreateDeploymentRequest | ✅ 完成 | `api/agnet/models.py` |
+| DeploymentStatus 枚举 | ✅ 完成 | `database.py` |
+| RiskLevel 枚举 | ✅ 完成 | `database.py` |
+| BillingProvider 枚举 | ✅ 完成 | `database.py` |
+| AgentInstance 模型 | ✅ 完成 | `database.py` |
+| Event 模型 | ✅ 完成 | `database.py` |
+| AuditLog 模型 | ✅ 完成 | `database.py` |
+| 响应模型（8个） | ✅ 完成 | `api/agnet/models.py` |
+
+### 4. K8s 集成（4/6）
+
+| 功能 | 状态 | 实现位置 |
+|------|------|----------|
+| Namespace 创建 | ✅ 完成 | `api/agnet/k8s_manager.py:create_namespace` |
+| Pod 创建 | ✅ 完成 | `api/agnet/k8s_manager.py:create_pod` |
+| ConfigMap 创建 | ✅ 完成 | `api/agnet/k8s_manager.py:create_configmap` |
+| Pod 日志获取 | ✅ 完成 | `api/agnet/k8s_manager.py:get_pod_logs` |
+| Pod 状态查询 | ⚠️ 部分 | `api/agnet/k8s_manager.py:get_pod_status` |
+| ServiceAccount 管理 | ⚠️ 部分 | 需要增强 |
+
+### 5. Vault 集成（2/4）
+
+| 功能 | 状态 | 实现位置 |
+|------|------|----------|
+| Vault 客户端初始化 | ✅ 完成 | `api/agnet/vault_client.py` |
+| 密钥获取接口 | ✅ 完成 | `api/agnet/vault_client.py:get_secret` |
+| Kubernetes Auth | ⚠️ 部分 | 需要配置 |
+| Workload Identity | ⚠️ 部分 | 需要 AKS 配置 |
+
+### 6. 模型网关路由（3/3）
+
+| 功能 | 状态 | 实现说明 |
+|------|------|----------|
+| Provider 字段验证 | ✅ 完成 | 支持 `newapi` 和 `litellm` |
+| NewAPI Token 注入 | ✅ 完成 | 环境变量 `HEICODE_NEWAPI_USER_TOKEN` |
+| LiteLLM Token 注入 | ✅ 完成 | 环境变量 `LITELLM_USER_KEY` |
+
+**实现代码**:
+```python
+# 按 provider 路由模型网关
+configmap_data = {
+    "MODEL_GATEWAY_URL": (
+        settings.HEICODE_NEWAPI_BASE_URL 
+        if request.billing_context.provider.value == "newapi" 
+        else settings.LITELLM_BASE_URL
+    ),
+}
+```
+
+---
+
+## ⚠️ 部分实现功能（4项）
+
+### 1. ServiceAccount 自动创建和绑定
+
+**当前状态**: 基础实现，需要增强
+
+**已实现**:
+- ✅ 基础 ServiceAccount 创建
+
+**待完善**:
+- ⚠️ 按 `role-{user_id}` 命名规则
+- ⚠️ Vault Kubernetes Auth Role 绑定
+- ⚠️ Workload Identity 注解
+
+**需要补充**:
+```python
+def create_service_account(self, namespace: str, role: str, user_id: str):
+    sa_name = f"sa-{role}-{hashlib.sha256(user_id.encode()).hexdigest()[:6]}"
+    sa = client.V1ServiceAccount(
+        metadata=client.V1ObjectMeta(
+            name=sa_name,
+            annotations={
+                "azure.workload.identity/client-id": "<managed-identity-id>",
+                "vault.hashicorp.com/role": f"heicode-{user_id}"
+            }
+        )
+    )
+    self.v1.create_namespaced_service_account(namespace, sa)
+```
+
+### 2. ConfigMap 三文件格式
+
+**当前状态**: 基础实现，需要完善格式
+
+**已实现**:
+- ✅ ConfigMap 创建
+- ✅ 基础配置注入
+
+**待完善**:
+- ⚠️ AGENT.md 格式化
+- ⚠️ resource_context.json 结构
+- ⚠️ permission_manifest.json 结构
+
+### 3. Vault Kubernetes Auth
+
+**当前状态**: 客户端已实现，需要配置
+
+**已实现**:
+- ✅ Vault 客户端封装
+- ✅ 密钥获取接口
+
+**待配置**:
+- ⚠️ Vault 服务器地址
+- ⚠️ Kubernetes Auth 路径
+- ⚠️ Policy 配置
+
+### 4. Pod 日志脱敏
+
+**当前状态**: 基础实现，需要增强
+
+**已实现**:
+- ✅ 日志获取
+- ✅ 基础脱敏标记
+
+**待增强**:
+- ⚠️ 正则匹配敏感信息
+- ⚠️ 自动掩码处理
+- ⚠️ 脱敏规则配置
+
+---
+
+## ❌ 未实现 / 后续增强功能（1项 + 2项增强）
+
+### 1. SSE 实时日志流
+
+**接口**: `GET /api/agnet/deployments/{id}/logs/stream`
+
+**状态**: ❌ 未实现
+
+**优先级**: 低（标记为可选）
+
+**实现建议**:
+```python
+from fastapi.responses import StreamingResponse
+
+@router.get("/deployments/{deployment_id}/logs/stream")
+async def stream_logs(deployment_id: str):
+    async def log_generator():
+        while True:
+            logs = await get_new_logs(deployment_id)
+            for log in logs:
+                yield f"data: {json.dumps(log)}\n\n"
+            await asyncio.sleep(1)
+    
+    return StreamingResponse(
+        log_generator(),
+        media_type="text/event-stream"
+    )
+```
+
+### 2. 资源作用域监控快照
+
+**接口**: `GET /api/agnet/projects/{binding_scope}/dashboard-snapshot`
+
+**状态**: ⚠️ 后续增强
+
+**优先级**: 中
+
+**需要返回**:
+- active_instances
+- phase_distribution
+- failure_rate_1h
+- avg_task_duration
+- budget (tokens/cost/duration)
+- resource_usage (cpu/mem/network)
+
+### 3. SK 快照解析
+
+**接口**: `POST /api/agnet/sk-snapshots/resolve`
+
+**状态**: ⚠️ 后续增强
+
+**优先级**: 中
+
+**功能说明**: 拉取 git/upload 资源，生成只读快照。v2.1.4 已支持从 Runtime callback payload 投影查询 SK snapshot，独立解析接口仍待补齐。
+
+### 4. SK 快照查询
+
+**接口**: `GET /api/agnet/user/deployments/{id}/sk-snapshots`
+
+**状态**: ✅ 已实现（v2.1.4）
+
+**优先级**: 已完成
+
+**功能说明**: 从 `sk_tool.called`、`sk_tool.completed`、`sk_tool.failed` 和携带 `sk_snapshot` 的 artifact callback payload 投影返回快照列表。独立快照解析与物化存储可在后续增强。
+
+---
+
+## 📁 代码结构
+
+```
+api/agnet/
+├── __init__.py              # 模块初始化
+├── router.py                # 主路由（38 行）
+├── auth.py                  # 认证中间件（1,512 字节）
+├── models.py                # 数据模型（7,691 字节）
+├── deployments.py           # 部署管理接口（27,888 字节）⭐ 核心
+├── validators.py            # 请求验证（4,097 字节）
+├── idempotency.py           # 幂等性缓存（2,096 字节）
+├── k8s_manager.py           # K8s 操作封装（7,608 字节）
+└── vault_client.py          # Vault 客户端（5,361 字节）
+
+总计: ~1,756 行代码
+```
+
+---
+
+## 🔍 关键实现细节
+
+### 1. 创建部署流程
+
+```python
+# api/agnet/deployments.py:123
+@router.post("/deployments")
+async def create_deployment(...):
+    # 1. 幂等性检查
+    if idempotency_key:
+        cached = idempotency_cache.get(idempotency_key)
+        if cached:
+            return cached
+    
+    # 2. 请求验证
+    validate_deployment_request(request, headers)
+    
+    # 3. 创建数据库记录
+    deployment = Deployment(...)
+    db.add(deployment)
+    
+    # 4. 创建 K8s 资源
+    k8s_manager.create_namespace(namespace)
+    k8s_manager.create_configmap(namespace, configmap_name, data)
+    k8s_manager.create_pod(namespace, pod_name, image, env_vars)
+    
+    # 5. 创建审计日志
+    create_audit_log(db, actor, action, resource_id, result)
+    
+    # 6. 返回响应
+    return CreateDeploymentResponse(...)
+```
+
+### 2. 模型网关路由
+
+```python
+# 根据 billing_context.provider 决定模型网关
+if request.billing_context.provider.value == "newapi":
+    # Heicode NewAPI
+    model_gateway_url = settings.HEICODE_NEWAPI_BASE_URL
+    token_env_name = "HEICODE_NEWAPI_USER_TOKEN"
+else:
+    # taijiagent LiteLLM
+    model_gateway_url = settings.LITELLM_BASE_URL
+    token_env_name = "LITELLM_USER_KEY"
+
+# 从 Vault 获取 token
+model_gateway_secret = await vault_client.get_secret(
+    request.billing_context.secret_ref
+)
+
+# 注入 Pod 环境变量
+env_vars[token_env_name] = model_gateway_secret
+```
+
+### 3. 日志脱敏
+
+```python
+# api/agnet/deployments.py:596
+@router.get("/deployments/{deployment_id}/logs")
+async def get_deployment_logs(...):
+    # 获取 Pod 日志
+    pod_logs = k8s_manager.get_pod_logs(namespace, pod_name)
+    
+    # 解析并脱敏
+    for line in pod_logs.split('\n'):
+        logs.append(LogEntry(
+            message=line,  # TODO: 需要增强脱敏逻辑
+            redacted=True if contains_sensitive(line) else False
+        ))
+    
+    return GetLogsResponse(logs=logs)
+```
+
+---
+
+## 🎯 下一步工作建议
+
+### Phase 1: 完善核心功能（1-2 天）
+
+**优先级: 高**
+
+1. ✅ 增强 ServiceAccount 创建逻辑
+   - 实现 `sa-{role}-{user_hash}` 命名
+   - 添加 Vault 和 Workload Identity 注解
+
+2. ✅ 完善 ConfigMap 三文件格式
+   - AGENT.md 模板化
+   - resource_context.json 结构化
+   - permission_manifest.json 标准化
+
+3. ✅ 增强日志脱敏
+   - 正则匹配敏感信息
+   - 自动掩码处理
+
+### Phase 2: 实现缺失接口（2-3 天）
+
+**优先级: 中**
+
+1. ⚪ 实现资源作用域监控快照
+   - `GET /api/agnet/projects/{binding_scope}/dashboard-snapshot`
+
+2. ⚪ 实现 SK 快照功能
+   - `POST /api/agnet/sk-snapshots/resolve`
+   - `GET /api/agnet/deployments/{id}/sk-snapshots`
+
+### Phase 3: 基础设施配置（3-5 天）
+
+**优先级: 中**
+
+1. ⚪ 配置 Vault Kubernetes Auth
+   - 部署 Vault 服务器
+   - 配置 Auth 路径和 Policy
+
+2. ⚪ 配置 AKS Workload Identity
+   - 启用 OIDC Issuer
+   - 配置 Federated Identity
+
+### Phase 4: 可选功能（1-2 天）
+
+**优先级: 低**
+
+1. ⚪ 实现 SSE 实时日志流
+   - `GET /api/agnet/deployments/{id}/logs/stream`
+
+---
+
+## 📊 与需求文档对比
+
+| 需求章节 | 完成度 | 说明 |
+|---------|--------|------|
+| §2 - 12 个新接口 | 92% | 11/12 已实现，SSE 日志流待补齐 |
+| §3 - 接口详情 | 80% | 核心逻辑完成，细节待完善 |
+| §3a - 模型网关路由 | 100% | ✅ 完全实现 |
+| §4 - Pod 启动改造 | 70% | 基础完成，SA 和 ConfigMap 待增强 |
+| §5 - AKS 基础设施 | 40% | 需要基础设施团队配合 |
+| §6 - 向后兼容 | 100% | ✅ 老接口完全不受影响 |
+
+---
+
+## ✅ 结论
+
+### 当前状态
+
+**总体完成度: 87%**
+
+- ✅ **核心功能已实现**: 11/12 API 接口完成
+- ✅ **认证和安全完善**: 100% 完成
+- ✅ **模型网关路由**: 100% 完成
+- ⚠️ **部分功能待完善**: ServiceAccount、ConfigMap、日志脱敏
+- ❌ **1 个接口待实现**: SSE 日志流
+- ⚠️ **2 个后续增强项**: 资源作用域监控快照、SK 快照解析/物化存储
+
+### AKS 部署版本
+
+**当前 AKS 上的版本是 `heicode-v2-20260529120632`**，包含：
+- ✅ 完整的 Heicode Agent API (`/api/agnet/*`)
+- ✅ `/api/swarms` Runtime 兼容入口
+- ✅ Runtime 主动 callback、artifact、timeline、SK snapshot 查询
+- ✅ 普通 sub 真实执行后的 `artifact.created` 与 `task.*` 终态回调
+- ✅ deployment 与 agents 终态一致性修复
+- ✅ `/api/swarms/{id}/logs` Runtime 聚合日志摘要
+- ✅ 审批 decision 接收路径
+- ✅ 部署管理、日志、事件、指标功能
+- ✅ 模型网关路由（NewAPI/LiteLLM）
+- ✅ Vault 集成基础
+- ✅ 审计日志和事件追踪
+
+### 可以开始对接
+
+**是的，当前代码已经可以开始对接！**
+
+核心 API 和普通 sub 联调能力已经实现，可以支持：
+1. ✅ 创建和管理部署
+2. ✅ 查询部署状态和详情
+3. ✅ 获取日志和事件
+4. ✅ 监控资源指标
+5. ✅ 模型网关路由
+6. ✅ Runtime callback 回写 timeline / artifact / SK snapshot
+7. ✅ 高风险动作审批流
+
+剩余的 SSE 日志流、监控快照和 SK 快照解析/物化存储可以在后续迭代中补充。
+
+---
+
+**文档版本**: v1.1  
+**生成时间**: 2026-05-12  
+**最近同步**: 2026-05-29  
+**维护者**: Agent Manager Team
@@ -0,0 +1,252 @@
+# 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` |