# Agent-Manager (= Heicode Agnet 平台) 对接需求文档

**版本**: v1.1
**生效日期**: 2026-05-07
**目标读者**: agent-manager 服务的开发团队
**对接方**: mcp-server（Heicode Manager）
**依据**:
- Heicode 主线：`heicode.md` / `plan.md`
- 接口契约：`integration/agnet-platform-request-contract.md`
- 运行时设计：`heicode-runtime-auth-newapi-secret-design.md`

**v1.1 修订**（2026-05-07，按 Heicode 团队 4 路径架构修订）:
- §1.1 架构图：反映双模型网关（NewAPI + LiteLLM）并存
- §3.1 payload 校验：新增 `billing_context.provider` enum 约束（`newapi` | `litellm`）
- §4.1 Pod 启动：按 provider 注入不同 token（`HEICODE_NEWAPI_USER_TOKEN` 或 `LITELLM_USER_KEY`）
- §3a（**新增**）：子 Agent 模型网关路由说明

**配套文档**:
- 调用关系全景：[`Heicode-完整调用流程图.md`](./Heicode-完整调用流程图.md)
- mcp-server 已上线接口：[`Heicode-接口契约文档.md`](./Heicode-接口契约文档.md)
- 整体进度与待办：[`Heicode-对接进度与待办.md`](./Heicode-对接进度与待办.md)

---

## 0. TL;DR

agent-manager 在 Heicode 架构里担任 **Agnet 平台**角色——**执行层**，运行子 Agent、回传日志/事件/审计。

需要做三件事：

1. **新增 12 个 HTTP 接口**（`/api/agnet/*`），接收 mcp-server 的部署请求并回传状态
2. **改 Pod 启动方式**：子 Agent Pod 启动时只接收 `AGENT.md` + `resource_context` + `permission_manifest`，**不再接收长期密钥**
3. **接入 AKS Workload Identity**：子 Agent Pod 通过 ServiceAccount 拿身份，按需从 Vault 拉短期凭据

⚠️ **现有 agent-manager 接口不动**（taiji 业务还在用），**全部增量**。

---

## 1. 背景与边界

### 1.1 Heicode 全栈架构（v1.1 修订：4 路径模型调用）

```
┌─────────────────────────────────────────────────────────────────┐
│ 入口层                                                          │
│  cc-haha 桌面客户端                heicode web 前端              │
│  (Tauri + Bun)                    (React + Rsbuild)              │
└─────────────────────────────────────────────────────────────────┘
                  │                                   │
                  │   登录 4 接口                      │
                  └───────────┬───────────────────────┘
                              ▼
              ┌──────────────────────────────────┐
              │  Heicode Manager (mcp-server)    │
              │  ✅ 登录 IdP                     │
              │  ✅ ResourceBinding/Grant        │
              │  ❌ /api/agnet/* (12 接口)       │
              │  ❌ /api/user/heicode/* (4 透传) │
              └──────┬───────────┬───────────┬───┘
                     │           │           │
        部署请求      │           │ NewAPI 元数据查询
                     │           │ (service token)
                     ▼           ▼
        ┌────────────────────────────────────────┐
        │  ★ 你要做的：agent-manager (Agnet 平台)│
        │   - 12 个新接口                         │
        │   - 创建 K8s Deployment                 │
        │   - 按 billing_context.provider 路由    │
        └──────────────┬───────────────────────┬──┘
                       │                       │
        provider=newapi│      provider=litellm │
                       ▼                       ▼
        ┌──────────────────────┐  ┌──────────────────────┐
        │  子 Agent Pod        │  │  子 Agent Pod        │
        │  (Heicode 用户的)    │  │  (taijiagent 用户的) │
        │  ENV:                │  │  ENV:                │
        │  HEICODE_NEWAPI_     │  │  LITELLM_USER_KEY    │
        │    USER_TOKEN        │  │  LITELLM_BASE_URL    │
        └──────────┬───────────┘  └──────────┬───────────┘
                   │ /v1/chat/completions    │ /v1/chat/completions
                   ▼                         ▼
        ┌──────────────────────┐  ┌──────────────────────┐
        │  Heicode NewAPI      │  │  taijiagent LiteLLM  │
        │  code.xinghanlab.com │  │  (mcp-server 内置)    │
        └──────────────────────┘  └──────────────────────┘
                   │                         │
                   └────────────┬────────────┘
                                ▼
                  40+ AI 提供商（OpenAI、Claude、Gemini...）
```

**boundary**:
- Manager (mcp-server) = **用户控制台 + 编排中枢**，不直接动 K8s
- Agnet 平台 (agent-manager) = **执行层**，唯一接触 K8s deployment 的服务
- Manager 通过 HTTP 调 Agnet 平台，**不**直接调 K8s API
- **★ 重要**：模型调用是 4 路径（cc-haha + heicode 前端 → NewAPI；子 Agent → NewAPI 或 LiteLLM 看 provider；mcp-server 内部 → LiteLLM），详见 [`Heicode-完整调用流程图.md §2.5`](./Heicode-完整调用流程图.md)

### 1.2 不要做什么

| 不要做 | 为什么 |
|---|---|
| ❌ 在 agent-manager 里再发起高危操作审批 | 审批只在客户端做，agent-manager 只**校验** approval_id 是否有效 |
| ❌ 直接信任 mcp-server 传来的 role 提升 | 高权限角色由 Vault policy / K8s RBAC 强制，不靠应用层声明 |
| ❌ 把长期密钥（Git PAT、云 access key）注入 Pod env | Pod 只能拿短期、最小权限凭证；长期密钥放 Vault |
| ❌ 让 Pod 直连 mcp-server 拿用户上下文 | 上下文应在创建 Deployment 时一次性写入 K8s Secret/ConfigMap |
| ❌ 替换或破坏现有 agent-manager 老接口 | taiji 业务（channel admin → 创建 Agent → 部署）正在用，必须向后兼容 |

---

## 2. 12 个新接口（必须实现）

完整字段定义见 [`integration/agnet-platform-request-contract.md`](http://gitee.ath.cx:3000/xiaohei/heicode/src/branch/main/docs/integration/agnet-platform-request-contract.md)。

下表是必须实现的 11 个接口 + 1 个可选 SSE：

| 序号 | 接口 | 用途 | mcp-server 何时调 |
|---|---|---|---|
| 1 | `POST /api/agnet/deployments` | 创建子 Agent 部署 | 用户在 Manager 点"部署" |
| 2 | `GET /api/agnet/deployments` | 列表 | Manager 显示"我的部署"页 |
| 3 | `GET /api/agnet/deployments/{id}` | 详情 | Manager 显示部署详情页 |
| 4 | `POST /api/agnet/deployments/{id}/stop` | 停止 | 用户点"停止"或预算超 |
| 5 | `GET /api/agnet/deployments/{id}/logs` | 日志（脱敏） | 用户看子 Agent 输出 |
| 6 | `GET /api/agnet/deployments/{id}/logs/stream` | SSE 实时日志 | （可选）实时控制台 |
| 7 | `GET /api/agnet/projects/{binding_scope}/dashboard-snapshot` | 资源作用域监控快照 | Manager 总览页 |
| 8 | `GET /api/agnet/deployments/{id}/metrics` | 单部署指标序列 | Manager 详情页"性能"tab |
| 9 | `GET /api/agnet/deployments/{id}/events` | 事件流 | Manager 详情页"事件"tab |
| 10 | `GET /api/agnet/audit-logs` | 审计日志 | Manager 审计页 |
| 11 | `POST /api/agnet/sk-snapshots/resolve` | 触发 SK 快照解析 | Manager 拉取/刷新 SK |
| 12 | `GET /api/agnet/deployments/{id}/sk-snapshots` | 查询 SK 快照 | Manager 部署详情 |

### 2.1 mcp-server 调用 agent-manager 的认证模型

mcp-server 用**服务身份令牌**（service token）调 agent-manager，**不传**用户凭据：

```http
POST /api/agnet/deployments
Authorization: Bearer <manager-service-token>
Content-Type: application/json
X-Correlation-Id: <uuid>
X-User-Id: <end-user-id>
X-Binding-Scope: <binding_scope>
Idempotency-Key: <uuid>   # 创建类接口建议
```

| Header | 必填 | 说明 |
|---|---|---|
| `Authorization: Bearer <token>` | 是 | manager 的服务令牌；agent-manager 校验签名/有效期 |
| `X-Correlation-Id` | 是 | mcp-server 生成；全链路追踪 ID |
| `X-User-Id` | 建议 | 实际终端用户 ID；冗余于 body `user_context.user_id` |
| `X-Binding-Scope` | 建议 | 当前操作的资源作用域；冗余于 body `resource_grants[].binding_scope` |
| `Idempotency-Key` | 创建类建议 | mcp-server 生成；agent-manager 缓存幂等结果 |

**待决策**：服务令牌怎么发？三种方案：

| 方案 | 说明 |
|---|---|
| (A) Pre-shared bearer | mcp-server 配 env `AGENT_MANAGER_SERVICE_TOKEN`；agent-manager 配等值校验。最简单 |
| (B) JWT 签发 | 共享 secret 签发短期 JWT；agent-manager 校验签名 |
| (C) AKS Workload Identity | mcp-server pod 用 SA 拿 token；agent-manager 校验 OIDC issuer。最规范 |

mcp-server 团队建议: **(A) 先做，后期升 (C)**。请告知你们偏好。

### 2.2 通用响应包裹

成功：
```json
{ "success": true, "data": { ... } }
```

失败（**结构化必填**）：
```json
{
  "success": false,
  "error": {
    "code": "POLICY_REJECTED",
    "message": "human readable",
    "request_id": "req_xxx"
  }
}
```

mcp-server 会按 business `code` 路由处理。建议 code 集合：

| code | 场景 | mcp-server 行为 |
|---|---|---|
| `POLICY_REJECTED` | 缺必填、风险等级非法 | 显示校验错误，不重试 |
| `BUDGET_EXCEEDED` | 超 token/金额/时长预算 | 显示预算告警 |
| `MODEL_NOT_ALLOWED` | 模型不在 allowed_model_ids 内 | 显示模型未授权 |
| `FORBIDDEN_SCOPE` | header 与 body 用户/资源作用域不一致 | 阻断 + 写审计 |
| `RESOURCE_GRANT_INVALID` | resource_grants 字段缺失 / 跨用户 / 角色不匹配 | 拒绝部署 |
| `RESOURCE_GRANT_SECRET_REJECTED` | 请求中出现明文密钥字段 | 让 mcp-server 重新生成 payload |
| `SK_SOURCE_UNRESOLVABLE` | SK 来源不可解析 | 重试或提示 |
| `DEPLOYMENT_CONFLICT` | 部署不存在 / 状态冲突 / 重复提交 | 用 Idempotency-Key 查既有结果 |
| `NOT_FOUND` | 资源不存在 | 返回空态 |
| `CURSOR_EXPIRED` | 分页游标过期 | 弃 cursor，重新拉 |
| `RATE_LIMITED` | 限流 | 按 `Retry-After` 退避 |
| `INTERNAL_ERROR` | 内部错误 | 退避重试 + 人工排查 |

---

## 3. 接口详情速览（agent-manager 视角）

> 完整 payload 字段见 heicode 仓库的 `agnet-platform-request-contract.md`，本节只给你们 server 端实现要点。

### 3.1 POST /api/agnet/deployments — 创建部署

**收到 payload 后必须做的事**：

1. **服务令牌校验** —— 401 否则
2. **Idempotency-Key 查重** —— 若同 key 已处理，返回原结果（不重复创建 K8s deployment）
3. **payload 字段校验**：
   - `orchestration_plan.intent_id` / `template_hint` / `objective` / `risk_level` / `budget` / `metadata.correlation_id` / `agents[]` 必填
   - `risk_level=high` 时 `agents[].resource_grants[].constraints.approval_id` 必须存在
   - `agents[].default_model_id` 若设置，必须 ∈ `constraints.allowed_model_ids`
   - `resource_grants[]`：`grant_id` / `resource_id` / `resource_type` / `user_id` / `binding_scope` / `target_role` / `target_agent_ref` / `permission_scope` / `status` 必填
   - 凭据型资源（git/sk/cloud_account/cloud_resource）：`secret_ref` 必填；`project_doc` 可空
   - **`billing_context.provider`**（Heicode 2026-05-07 修订）：枚举 = `newapi` | `litellm`
     - `newapi` → 子 Agent Pod 调模型走 Heicode NewAPI（`code.xinghanlab.com`）
     - `litellm` → 子 Agent Pod 调模型走 taijiagent LiteLLM
     - agent-manager 据此决定 Pod env 注入哪个 token：`HEICODE_NEWAPI_USER_TOKEN` 或 `LITELLM_USER_KEY`
     - **agent-manager 不需要做产品决策，仅按 mcp-server 传来的值路由**
4. **敏感字段拒绝**：递归扫 `metadata` / `constraints` / `audit`，key 含 `password|token|secret|private_key|access_key|credential` → `RESOURCE_GRANT_SECRET_REJECTED`
5. **审批校验**（仅 risk_level=high）：
   - `approval_id` 在 `constraints` 或 `audit` 中
   - 审批主体 ∈ `user_context.user_id` / `resource_grants[].user_id`
   - 审批未过期（含 TTL / window）
   - 范围覆盖 `binding_scope` + `permission_scope` + 目标环境 + 资源 ID
6. **创建 K8s Deployment**：
   - 命名空间：建议 `agnet-{user_id 短哈希}` 或现有规则
   - ServiceAccount：按 `agents[].role_template` + user_id 派生（见 §4）
   - Pod 启动配置：把 AGENT.md + resource_context + permission_manifest 写入 ConfigMap，挂到 Pod
   - **不写明文密钥**到 env / configmap
7. **返回**：
   ```json
   {
     "success": true,
     "data": {
       "deployment_id": "dep_xxx",
       "status": "accepted",
       "agent_instances": [
         { "instance_id": "agi_xxx", "role": "builder", "phase": "pending" }
       ]
     }
   }
   ```

### 3.2 POST /api/agnet/deployments/{id}/stop — 停止

- 已停止 → 200 + `status=stopped`（幂等）
- 进入终态（如 `completed`）且无运行实例 → 409 `DEPLOYMENT_CONFLICT`
- 高风险停止缺审批 → 422 `POLICY_REJECTED`

### 3.3 GET /api/agnet/deployments/{id}/logs — 日志（**强制脱敏**）

**返回前必须做**：扫描 `message` 字段，删/掩盖任何疑似密码、token、私钥、连接串、access key 的字符串。

字段：
```json
{
  "log_id": "log_xxx",
  "deployment_id": "dep_xxx",
  "agent_instance_id": "agi_xxx",
  "stream": "stdout|stderr|system|audit",
  "level": "info|warn|error",
  "message": "task started",
  "redacted": true,
  "occurred_at": "ISO 8601"
}
```

支持 query：`agent_instance_id`、`stream`、`since`、`limit`（默认 200，建议 max 1000）、`cursor`。

### 3.4 GET /api/agnet/deployments/{id}/events — 事件

至少实现这些事件名：
- `deployment.accepted` — 平台接受请求
- `instance.phase_changed` — 子 Agent phase 变化
- `sk_snapshot_refreshed` — SK 快照刷新
- `resource_grant.attached` / `resource_grant.revoked` — 授权绑定/撤销
- `budget.threshold_reached` — 预算触发
- `deployment.failed` — 部署失败

字段：`event_id` / `event` / `schema_version` / `user_id` / `channel_id` / `binding_scope` / `deployment_id` / `correlation_id` / `occurred_at`。

### 3.5 GET /api/agnet/projects/{binding_scope}/dashboard-snapshot — 监控快照

> 注意路径里写 `projects/{binding_scope}` 是契约保留旧名；参数值是 `binding_scope` 不是 project_id。

返回：active_instances、phase_distribution、failure_rate_1h、avg_task_duration、budget（tokens/cost/duration）、resource_usage（cpu/mem/network）、updated_at。

### 3.6 GET /api/agnet/deployments/{id}/metrics — 单部署指标（建议）

返回时间序列：
- `tokens_used` (count)
- `cost_usd` (number)
- `duration_sec` (count)
- `cpu_millicores` (millicore)
- `memory_mb` (mb)
- `restart_count` / `tool_call_count` / `error_count` / `queue_latency_ms`

支持 `window=15m&step=60s` 等参数。

### 3.7 GET /api/agnet/audit-logs — 审计日志

字段：`audit_id` / `actor` / `action` / `resource` / `user_id` / `channel_id` / `binding_scope` / `request_id` / `correlation_id` / `result` / `occurred_at`。

支持 query：`user_id`、`binding_scope`、`actor`、`action`、`since`、`limit`、`cursor`。

### 3.8 POST /api/agnet/sk-snapshots/resolve — SK 快照解析

请求：`{"deployment_id": "dep_xxx"}`

服务端动作：把 deployment 的 `agents[].sk_sources[]` 里的 git/upload 资源拉取下来，生成只读快照（**不带凭据**），生成 `snapshot_id` + `artifact_ref` + `checksum`。

### 3.9 GET /api/agnet/deployments/{id}/sk-snapshots — SK 快照查询

返回 snapshots 列表，含 `source_ref`（如 `main:skills/heicode/**@sha_xxx`）、`resolved_at`、`status: ready/resolving/failed`。

---

## 3a. 子 Agent 模型网关路由（v1.1 新增 — 必须实现）

### 3a.1 背景：为什么有这个章节

按 Heicode 团队 2026-05-07 的修订（详见 [`Heicode-完整调用流程图.md §2.5`](./Heicode-完整调用流程图.md)），整个生态有**两套并存的产品级模型网关**：

| 网关 | 服务对象 | provider 字段值 |
|---|---|---|
| **Heicode NewAPI** (`code.xinghanlab.com`) | cc-haha 桌面端用户、Heicode 用户部署的子 Agent | `"newapi"` |
| **taijiagent LiteLLM** | 原生 taijiagent 用户、taijiagent 用户部署的子 Agent | `"litellm"` |

mcp-server 创建 deployment 时会在 `billing_context.provider` 字段告诉 agent-manager："这个子 Agent 调模型走哪条网关"。

**agent-manager 不需要做产品决策**，只按 provider 字段路由。

### 3a.2 校验规则（agent-manager 在 §3.1 step 3 校验）

| 字段 | 取值 | 行为 |
|---|---|---|
| `billing_context.provider` | `"newapi"` | 走 Heicode NewAPI |
| `billing_context.provider` | `"litellm"` | 走 taijiagent LiteLLM |
| 缺失 / 其他值 | — | 返回 422 `POLICY_REJECTED`，message 提示有效取值 |

### 3a.3 token 来源约定

mcp-server 在 `resource_grants[]` 里会传 `secret_ref` 指向用户的模型调用 token：

```json
{
  "billing_context": {
    "provider": "newapi",
    "newapi_user_ref": "newapi_user_123",
    "newapi_group": "development",
    "quota_ref": "newapi_token_or_group_quota_ref"
  },
  "agents": [{
    "resource_grants": [
      {
        "resource_type": "model_gateway_token",
        "secret_ref": "vault://secret/users/{user_id}/heicode/newapi_user_token",
        ...
      }
    ]
  }]
}
```

agent-manager 实现时：
- 拿到 deployment 后，按 provider 找出对应的 `secret_ref`
- 通过 Vault Kubernetes Auth 拿真实 token
- 注入 Pod env（详见 §4.1 步骤 4）

### 3a.4 联调阶段简化（Phase 2-3 可接受）

Phase 2-3 联调时如果 Vault 还没就位，**允许临时用预共享 token**（agent-manager pod env 配一个测试用 token）作为 fallback，但必须：
- 标注 `Deployment.metadata.annotations["heicode.io/token-source"] = "fallback-shared"`
- Phase 5 (Vault 接入) 完成后立即删除 fallback 路径
- 测试用 token 限额低（例如 $1/day）

### 3a.5 模型调用路径汇总

```
子 Agent Pod (provider=newapi):
  POST /v1/chat/completions
  Authorization: Bearer ${HEICODE_NEWAPI_USER_TOKEN}
       ↓
  https://code.xinghanlab.com (Heicode NewAPI)
       ↓
  转发到 OpenAI / Claude / Gemini / ...

子 Agent Pod (provider=litellm):
  POST /v1/chat/completions
  Authorization: Bearer ${LITELLM_USER_KEY}
       ↓
  ${LITELLM_BASE_URL} (taijiagent LiteLLM)
       ↓
  转发到 OpenAI / Claude / Gemini / ...
```

两条路径**互不替代**，由 provider 字段一次性决定。

---

## 4. Pod 启动行为改造（必须）

依据 `heicode.md §七 AKS 上的 Agnet 凭证访问`。

### 4.1 推荐流程

```
mcp-server POST /api/agnet/deployments (含 user_id, role, resource_grants, secret_refs,
                                        billing_context.provider)
         ↓
agent-manager:
  1. 在 AKS 创建 ServiceAccount（命名规则：sa-{role}-{user_id 短哈希}）
  2. 给 SA 绑定 Vault Kubernetes Auth role（pol 路径包含 user_id + binding_scope）
  3. 创建 ConfigMap：AGENT.md + resource_context.json + permission_manifest.json
  4. ★ 按 billing_context.provider 路由模型网关 token：
     - provider=newapi  → 从 secret_ref 拿 Heicode NewAPI user token
                         注入 Pod env：
                           HEICODE_NEWAPI_BASE_URL=https://code.xinghanlab.com
                           HEICODE_NEWAPI_USER_TOKEN=<从 Vault/secret_ref 取>
     - provider=litellm → 从 secret_ref 拿 LiteLLM user key
                         注入 Pod env：
                           LITELLM_BASE_URL=<内网 LiteLLM 地址>
                           LITELLM_USER_KEY=<从 Vault/secret_ref 取>
  5. 创建 Deployment，spec:
     - serviceAccountName: <上面那个 SA>
     - volumeMounts: ConfigMap 挂到 /etc/agent/
     - env (Vault 部分):
        VAULT_ADDR: 内网 Vault 地址
        VAULT_AUTH_PATH: /auth/kubernetes/login
        VAULT_ROLE: <上面 SA 绑定的 role>
     - env (模型网关部分): 见步骤 4 按 provider 决定
     - **不**写任何 GIT_TOKEN、AZURE_KEY 等业务凭据明文 env
         ↓
Pod 启动：
  - 读 ConfigMap 里的 AGENT.md / resource_context / permission_manifest
  - 调模型时用 HEICODE_NEWAPI_USER_TOKEN 或 LITELLM_USER_KEY
  - 调外部业务凭据（如 git clone）时，用 SA token 调 Vault 拿短期凭证，用完即弃
```

> **关于模型 token 注入的安全权衡**（v1.1 补充）：
> NewAPI/LiteLLM user token 是"模型调用费用归属凭据"，不是"业务最高权限凭据"。把它作为 env 一次性注入是 Heicode 团队认可的妥协方案（避免每次调模型都过 Vault）。Token 必须满足：
> - 由 Heicode/taijiagent 平台**按 user 分发**（不是 admin token）
> - **TTL 短**（建议 24h）或可被快速撤销
> - **额度受限**（不超过用户 budget）
> - agent-manager 在 Deployment annotation 里记 `secret_ref` 引用，便于审计/吊销追溯
> - Pod 销毁时 token 也跟 Pod env 一起消失

### 4.2 ConfigMap 三个文件的格式建议

**AGENT.md**（自然语言上下文）：
```markdown
# Role: backend builder
# Goal: 在 services/api/** 路径下完成实现并提交代码
# Resources you can use:
- Git: <repo_url> (ref: main, paths: services/api/**, actions: read/write)
- Models: gpt-5.4-mini (max_tokens: 100000)
# Forbidden:
- 修改 services/api/** 之外的文件
- 创建新分支
```

**resource_context.json**（结构化资源元数据，**无密钥**）：
```json
{
  "agent_role": "backend",
  "deployment_id": "dep_xxx",
  "resources": [
    {
      "resource_id": "res_git_001",
      "type": "git",
      "external_ref": "https://example.com/org/repo.git",
      "constraints": { "ref": "main", "allowed_paths": "services/api/**" },
      "secret_ref": "vault://secret/users/{user_id}/bindings/repo_default/resources/res_git_001"
    }
  ]
}
```

**permission_manifest.json**（结构化权限清单，**给系统强制执行用**）：
```json
{
  "user_id": "user_123",
  "binding_scope": "repo_default",
  "agent_role": "backend",
  "resource_grants": [
    {
      "grant_id": "grant_xxx",
      "resource_type": "git",
      "allowed_actions": ["repo:read"],
      "constraints": { "ref": "main", "allowed_paths": "services/api/**" },
      "secret_ref": "vault://..."
    }
  ]
}
```

### 4.3 强制规定

| 项 | 必须 | 不得 |
|---|---|---|
| Pod env | 仅 VAULT_ADDR / VAULT_ROLE / 公开配置 | 任何长期凭据、连接串、token、密码 |
| ConfigMap 内容 | 元数据 + secret_ref 引用 | 凭据原文 |
| Pod 日志 | 脱敏后输出 | 凭据片段、env dump |
| Pod 镜像 | 公共 base + 启动 script | 凭据嵌入到镜像 |
| Vault 访问 | 通过 SA + Kubernetes Auth | Pod 直接拿 root token |

---

## 5. AKS 基础设施对齐（与基础设施团队协作）

### 5.1 Workload Identity 启用

- AKS 集群启用 OIDC issuer + Workload Identity addon
- 命名空间级 ServiceAccount 标注：
  ```yaml
  metadata:
    annotations:
      azure.workload.identity/client-id: <managed-identity-client-id>
  ```
- 给 SA 配 Federated Identity Credential 关联到 Azure AD

### 5.2 Vault Kubernetes Auth 配置

```hcl
# Vault policy: per (user_id, binding_scope) 派生
path "secret/users/${user_id}/bindings/${binding_scope}/resources/*" {
  capabilities = ["read"]
}

# Kubernetes Auth role: 绑定 SA → policy
{
  "bound_service_account_names": ["sa-backend-${user_id_hash}"],
  "bound_service_account_namespaces": ["agnet-${user_id_hash}"],
  "policies": ["heicode-${user_id}-${binding_scope}"],
  "ttl": "1h"
}
```

### 5.3 网络策略

- agent-manager → Vault：内网；Vault 不暴露公网
- Pod → Vault：通过 K8s service 或 private endpoint
- Pod → Git/Cloud：按 `network_policy_ref` 限制出站

---

## 6. 当前业务影响（保证现有 taiji 业务不挂）

agent-manager 当前接口（核实自 mcp-server 老代码 `app/agent_manager_client.py`，2026-05-05）：

| 方法 | 路径 | mcp-server 调用方 |
|---|---|---|
| GET | `/templates` | 列模板 |
| GET | `/templates/platform` | 平台模板 |
| GET | `/templates/custom` | 自定义模板 |
| GET | `/templates/{template_name}` | 单模板详情 |
| POST | `/agents` | 创建 Agent（payload: AgentConfig） |
| GET | `/agents` | 列 Agent |
| GET | `/agents/{name}/status` | Agent 状态 |
| GET | `/agents/{name}/metrics` | Agent 指标 |
| GET | `/agents/{name}/logs` | Agent 日志 |
| DELETE | `/agents/{name}` | 删除 Agent |
| POST | `/agents/{name}/restart` | 重启 |
| PATCH | `/agents/{name}` (scale) | 扩缩容 |
| POST | `/external-tools/{tool_id}` 等 | 外部工具生成/更新/删除 |
| POST | `/external-tools/agents/create-with-tools` | 用工具集创建 Agent |
| GET | `/resources/stats` | 资源统计 |
| GET | `/resources/user/{id}` | 用户资源 |
| GET | `/resources/channel/{id}` | 渠道资源 |
| GET | `/health` | 健康检查 |

**前缀对比**：
- 老 API：根路径下 `/templates/*`、`/agents/*`、`/external-tools/*`、`/resources/*`、`/health`
- 新 Heicode 契约：`/api/agnet/*`

**纪律（已经核实无冲突）**：
- ✅ 前缀完全不重叠 → 老接口和新接口可以**并存**
- ✅ 路径冲突 = 0
- ❌ 不改老接口路径、字段、响应形态
- ❌ 不改老的 K8s namespace 命名规则（taiji 老 Agent 还在跑）

**纪律**：
- ✅ 全部新增 12 个接口在 `/api/agnet/*` 前缀下
- ❌ 不改老接口路径、字段、响应形态
- ❌ 不改老的 K8s namespace 命名规则（taiji 老 Agent 还在跑）
- ✅ 新建用 `agnet-*` namespace，与老 namespace 隔离

---

## 7. 联调计划

### Phase 1: 服务令牌打通（半天）
1. mcp-server 配置环境变量 `AGENT_MANAGER_SERVICE_TOKEN`
2. agent-manager 实现 token 校验中间件
3. mcp-server 写一个 dummy 调用，确认 401/200 通畅

### Phase 2: POST /api/agnet/deployments 通跑（2-3 天）
1. agent-manager 实现接口（不要求真起 Pod，先打日志返回 mock deployment_id）
2. mcp-server 写出站客户端
3. 联调 payload 校验、错误码、Idempotency-Key

### Phase 3: 状态/日志/事件/审计（3-5 天）
- agent-manager 实现 GET 类接口
- 至少能返回 mock 数据或真实 K8s 数据

### Phase 4: 真实 Pod 部署（5-7 天）
- 接入 K8s API 真起 Deployment
- ConfigMap 写 AGENT.md / resource_context / permission_manifest
- Pod 启动后能读到这些文件

### Phase 5: AKS Workload Identity + Vault（1-2 周）
- 基础设施部署 Vault
- ServiceAccount + Workload Identity 联通
- Pod 通过 SA 调 Vault 拿短期凭据

---

## 8. mcp-server 这边能给的支持

mcp-server（Heicode Manager）已经准备好的：

| 项 | 状态 |
|---|---|
| ResourceBinding/Grant 数据模型 + 9 个 CRUD 接口 | ✅ 已上线 |
| 登录联邦（heicode 调 mcp-server `/me` `/refresh`）| ✅ 已上线 |
| 从 mcp-server 出站调 agent-manager 的客户端代码 | ⏳ 等 agent-manager 接口 ready 后做（~3-5 天） |
| 本地 stub `/api/agnet/*` 给前端联调用 | ⏳ 1-2 天可交付 |

**请 agent-manager 团队尽快确认**：
- ❓ 你们偏好哪种服务令牌方案（A pre-shared / B JWT / C Workload Identity）？
- ❓ 你们的开发节奏？（按 §7 phase 排，预计 3-4 周完整闭环）
- ❓ 联调环境地址：staging 用什么 base URL？mcp-server 这边怎么配？
- ❓ 现有 agent-manager 老接口的契约文档在哪？mcp-server 老代码还在调，避免迁移时踩坑

---

## 9. 快速导航

| 我想了解… | 看哪 |
|---|---|
| Heicode 整体边界 | `heicode.md`（heicode 仓库 docs/） |
| 12 接口完整 payload | `integration/agnet-platform-request-contract.md` |
| Pod 启动安全约束 | `heicode.md §七` + `heicode-runtime-auth-newapi-secret-design.md §三` |
| mcp-server 已上线接口 | `Docs/Heicode-接口契约文档.md`（mcp-server 仓库） |
| 整体进度与待办 | `Docs/Heicode-对接进度与待办.md`（mcp-server 仓库） |
| 部署安全清单 | `deployment/azure-production-deploy-guardrails.md`（heicode 仓库） |

---

## 10. 联系

mcp-server 这边联系点：
- 出站客户端代码改动：mcp-server 后端
- 接口契约对齐：见 §2.2 错误码表与 §3 各接口
- 测试账号、APIM 路由、CORS 等：mcp-server 后端

如发现本文档与 heicode 主线文档冲突，**以 heicode 主线为准**，并请回函通知 mcp-server 同步更新。