taiji-AI-PAD/Docs/Agent-Manager-Heicode对接需求文档.md

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
• mcp-server 已上线接口：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

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。

下表是必须实现的 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，不传用户凭据：

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 通用响应包裹

成功：

{ "success": true, "data": { ... } }

失败（结构化必填）：

{
  "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. 返回：

   {
     "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 的字符串。

字段：

{
  "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），整个生态有两套并存的产品级模型网关：

网关	服务对象	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：

{
  "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（自然语言上下文）：

# 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（结构化资源元数据，无密钥）：

{
  "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（结构化权限清单，给系统强制执行用）：

{
  "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 标注：

  metadata:
    annotations:
      azure.workload.identity/client-id: <managed-identity-client-id>
  

• 给 SA 配 Federated Identity Credential 关联到 Azure AD

5.2 Vault Kubernetes Auth 配置

# 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 同步更新。