heicode-win/docs/integration/agnet-platform-api-design.md

Agnet 平台 ↔ Heicode 集成接口设计（草案）

本文描述 Agnet 平台应向 Heicode（Manager / 客户端 / 自动化服务） 暴露的 控制面、数据面隔离、权限模型与可视化/事件接口。
路径、字段名为 设计意图；落地时可等价映射为 gRPC 或 GraphQL，但语义与隔离边界应保持一致。

关联里程碑：[../milestones/](../milestones/README.md) 中 M3～M5。

---

1. 设计目标

目标	说明
权界清晰	调用方身份可解析为「谁、属于哪一租户、具备何种角色」
租户默认隔离	无显式授权则不可读他租户资源
有状态可观测	执行单元生命周期与运行态可通过 API + 事件流呈现
可演进	资源带 api_version / schema 版本；破坏性变更走新版本路径

1.1 Agnet 可视化：Heicode Manager 与 Heicode 客户端的职责划分

使用方：团队与个人都会使用 Heicode；下列划分依据的是 信息类型与界面载体，不是「只有某类用户才用某一端」。

载体	主要职责	典型内容
Heicode Manager	呈现 Agnet 平台回传的运行态与性能类字段：编队/实例是否在跑、阶段（phase）、健康度、资源占用、队列与心跳、项目级聚合指标与近期错误摘要等。	控制台、Dashboard、与平台 SLA/运维相关的观测面。
Heicode（客户端）	在 编码与工作会话过程中，实时或准实时展示 Agnet 平台内子 agent 产出的内容（流式文本/结构化片段/工具结果等），与编辑、会话上下文同屏。	会话内输出面板、流式增量、与当前任务绑定的子 agent 交付物。

边界：Manager 侧重 平台契约下的状态与指标；Heicode 侧重 工作流中的执行输出。二者可调用同源底层 API，但 不得把「平台大盘」与「子代理会话输出」混为同一套 UI 假设——后者通常带更强会话/项目上下文与更细粒度流式协议。

---

2. 身份与调用方式

2.1 服务间（推荐生产）

• Heicode Manager 使用 服务账号 调用 Agnet：Authorization: Bearer <m2m_jwt>。
• JWT 声明至少包含：sub（服务主体）、tenant_id（若适用）、scope（见 §3）、exp。
• Agnet 校验Issuer（Manager 签发的委托令牌 或 Agnet 签发的服务令牌，二选一应文档化）。

2.2 用户委派（可选）

• 终端用户经 Heicode OAuth 后，Manager 代发 用户委派令牌 访问 Agnet 只读/受限写接口；Claims 含 user_id、org_id、roles。

2.3 必需传递的上下文头（建议）

Header	必填	说明
Authorization	是	Bearer Token
X-Request-Id	强建议	全链路追踪
X-Tenant-Id	多租户时必填	顶层隔离键；与 Token 声明互相校验，不一致则 401
X-Org-Id	视模型	组织内子划分
X-Project-Id	编排相关 API 建议	资源挂载点
X-Environment	可选	dev / staging / prod
X-Heicode-Correlation-Id	强建议	与 Manager 审计日志关联

---

3. 权限模型（RBAC 概要）

3.1 角色（示例命名，可映射贵司 IAM）

角色	典型 scope	说明
agnet:platform_admin	全租户元数据、调试接口	极少人数
agnet:org_admin	本租户内项目、编队、凭据绑定
agnet:project_editor	指定项目下部署/停止/读状态
agnet:operator_readonly	读状态、读事件、读审计
agnet:auditor	仅审计与导出

3.2 权限分离原则

• 控制面（部署/改策略）与 观测面（读指标）可分角色授予。
• 凭据类写操作（绑定 Git Token、云 SA）单独 scope：agnet:credential:write。
• SK 正文写入：仅允许经 Heicode 客户端身份或专用 **heicode:sk:write**（示例名）路径；Agnet / Manager 控制台接口不得授予 SK 正文写权限（与 §5.0「SK 仅在 Heicode 编辑」一致）。
• 拒绝隐式升级：只读 Token 不得通过查询参数绕过 body 校验升格为写操作。

---

4. 多租户与数据隔离

4.1 隔离键层级

Tenant（租户）
 └── Organization（可选）
      └── Project（项目）
           └── Deployment（一次编队部署）
                └── AgentInstance（执行单元实例）

• 所有持久化资源 必须带 tenant_id；API 默认按 Token + Header 解析租户并 强制过滤。
• 跨租户引用：禁止在 URL 中使用「全局唯一但不带租户前缀」的裸 ID；推荐 tenant_scoped_id 或 (tenant_id, local_id) 复合。

4.2 数据面实现选项（择一或组合）

方案	适用	Agnet 侧责任
逻辑隔离	快速迭代	每张业务表 tenant_id + RLS 或统一拦截器
Schema 分库	强合规	每租户独立 schema / database
命名空间隔离（K8s）	执行单元运行时	编排器按租户分配 NS 与网络策略

4.3 负例测试（验收必备）

• 使用 Tenant A 的凭证访问 Tenant B 的 deployment_id → 403 或 404（对外不区分）。
• 列表接口默认 不得返回其他租户资源，即使 ID 被猜到。

---

5. 编排与控制面 API（M3）

下列 REST 仅为示意；实际路径前缀可为 /api/v1 或 /agnet/v1。

5.0 Heicode Manager：一键部署 Agnet 团队与 SK 边界（产品契约）

下列条款为 Heicode 与 Agnet 联合落地时必须写清 的契约；API 形状可与 **POST /deployments** 合一或拆为 **POST /teams/deployments** 等聚合端点，但 语义不得缩水。

契约项	要求
一键部署	在 Heicode Manager 控制台提供 单次操作（按钮或向导终点）完成：在 Agnet 上 部署一支 Agnet 团队/编队，并得到可追踪的 deployment_id、团队视图入口与后续观测衔接（见 §1.1、§6）。不得依赖用户在 Agnet 原生控制台重复手工编排才能跑通 Heicode 叙事。
团队成员	部署配置须 显式包含团队成员（至少：user_id、组织内角色、是否纳入该 Agnet 团队）。成员关系由 Manager/Agnet 持久化，供 RBAC、配额与审计；团队管理员经 Manager 控制面维护名单（增删改须审计）。
成员所用模型	须能声明 各成员默认使用的模型/路由（如 default_model_id、provider_profile_id 或与 Manager 模型策略对齐的引用）。支持「团队缺省 + 成员覆盖」；未授权模型 不得在执行路径上静默生效。
子 agent（Agnet 平台内）与 SK	本文所称 子 Agnet / 子 agent 均指 Agnet 平台内部的子智能体/子执行单元（由 Agnet 编排与实例化），非 Heicode 自研运行时。部署配置须支持为 指定子 agent 绑定 SK 输入源；运行态下该子 agent 只读白名单内的 SK 内容。
SK 与 Git / 上传 MD	SK 正文资产以 Git 仓库为统一事实源（用户指定的远端/连接与分支、路径规则由集成约定）。同时允许用户 上传 Markdown 等文件 作为 补充 SK 源（租户内对象存储/制品 ID）。Agnet 执行前将两类来源 解析为不可变快照（commit SHA / upload version），再注入子 agent 上下文。
SK 文件仅在 Heicode 中编辑	Git 侧 SK 的 创建、修改、删除 经 Heicode 客户端提交到仓库（或 Heicode 发起变更后再同步）；上传类 SK 的 新增/替换 仅通过 Heicode 提供的入口（Manager 可做登记与透传，不提供 SK 正文在线编辑器）。Agnet 平台与子 agent 对 SK 均只读；若 Agnet 控制台出现可直接改 SK 正文的 API/UI，视为 违背产品边界。

部署请求体扩展（示意，可与 §5.1 合并）

{
  "project_id": "prj_xxx",
  "template": "agnet_team_default",
  "correlation_id": "mgr_cor_abc",
  "members": [
    {
      "user_id": "usr_alice",
      "role_in_team": "lead",
      "default_model_id": "mdl_claude_sonnet",
      "provider_profile_id": "pp_org_default"
    },
    {
      "user_id": "usr_bob",
      "role_in_team": "member",
      "default_model_id": "mdl_claude_haiku"
    }
  ],
  "sub_agents": [
    {
      "role_template": "sub_reviewer",
      "sk_file_refs": ["sk_review_policy.md", "sk_api_bar.yaml"]
    }
  ],
  "parameters": { "unit_overrides": {} }
}

• **sk_sources（推荐显式建模）**：替代或细化纯路径数组 sk_file_refs; 每个元素标明来源类型，便于 Agnet 实现拉取与快照。

部署请求体中 SK 绑定扩展示意

"sub_agents": [
  {
    "role_template": "sub_reviewer",
    "sk_sources": [
      {
        "type": "git",
        "repo_ref": { "connection_id": "gitconn_1", "repo_url": "https://example.com/org/sk-repo.git", "ref": "main", "paths": ["policy/review.md"] }
      },
      {
        "type": "upload",
        "artifact_id": "sk_upl_9f3a",
        "mime": "text/markdown"
      }
    ]
  }
]

5.0.1 对 Agnet 平台的接口与语义要求（含 SK）

下列为 Agnet 应向 Heicode/Manager 提供或可观测 的最小要求；路径可为等价 gRPC。

类别	要求
部署与编队	实现 **POST /deployments（或 **POST /teams/deployments）可接收 成员、成员模型、子 agent 模板及 sk_sources；返回 **deployment_id**、实例/子 agent 标识，供 Callback 与观测关联。
SK 快照只读	对每个 deployment_id / sub_agent_id，Agnet 须能记录 已解析的 SK 快照（Git：commit_sha + 路径哈希；Upload：artifact_id + 版本）。运行注入 仅此快照，不得在执行中「瞒报版本」拉未授权路径。
Git 拉取	Agnet 须支持 按租户注册 Git 凭据/连接（connection_id 或等价），由用户在 Heicode/Manager 流程中授权；Agnet 不提供 Git 写接口用于改 SK——写操作发生在 Git 远端或经 Heicode 提交后，Agnet 仅 fetch + checkout 指定 ref。
上传制品	若支持 type: "upload"：Agnet（或与 Manager 分工）须提供 **artifact_id** 的只读获取（如 GET /sk-artifacts/{artifact_id}/content 或预签名 URL），无 PUT 修改正文于 Agnet 控制台；上传入口 仅 Heicode 侧发起、Agnet 存只读副本。
刷新策略	约定 何时重新解析 SK（如新 commit、用户触发刷新、部署新版本）；须可通过 API 或事件暴露 **sk_snapshot_refreshed**，便于 Heicode 提示「已用新版本 SK」。
禁止项	不得提供面向 SK 正文的 通用写 API（与 §3.2 一致）；子 agent 只读绑定列表内的快照。

• **sk_file_refs**（若保留简化字段）：视为 相对某默认 Git 根或 由 Manager 展开为 sk_sources 前的简写；联合 RFC 须声明展开规则。
• 验收：部署完成后，Manager 可展示「团队成员—模型—Agnet 子 agent—SK 源（Git ref / 上传件）—快照版本」；Git 更新或 Heicode 重新上传后，按刷新策略在后续运行使用新快照。

5.1 部署编队

POST /deployments

请求体（示意）

{
  "project_id": "prj_xxx",
  "template": "agile_min",
  "correlation_id": "mgr_cor_abc",
  "members": [],
  "sub_agents": [],
  "parameters": {
    "unit_overrides": {}
  }
}

响应

{
  "deployment_id": "dep_yyy",
  "status": "accepted",
  "agent_instances": [
    { "instance_id": "agi_1", "role": "AG-PO", "phase": "pending" }
  ]
}

5.2 查询部署

• GET /deployments/{deployment_id} —— 含租户校验。
• POST /deployments/{deployment_id}:stop —— 优雅停止。

5.3 Webhook / 回调（Agnet → Heicode）

• Manager 注册 URL：POST /integration/heicode/callback-config（或由 Agnet 控制台配置）。
• 负载含：deployment_id、instance_id、event_type、payload、occurred_at、signature。

签名：HMAC-SHA256（共享密钥或 JWKS）；拒绝无签名请求。

---

6. 运行态与可视化 API（M5）

与产品分工的对应关系：本章 §6.1～§6.3 主要支撑 Heicode Manager 上的平台运行态与聚合视图；§6.4 支撑 Heicode 客户端在编码过程中展示 子 Agnet 输出。总则见 §1.1。

6.1 实例快照

GET /agent-instances/{instance_id}

响应字段（示意）

{
  "instance_id": "agi_1",
  "deployment_id": "dep_yyy",
  "tenant_id": "ten_1",
  "role": "AG-PO",
  "phase": "running",
  "health": "ok",
  "last_heartbeat_at": "2026-04-30T12:00:00Z",
  "queue_depth": 2,
  "current_task": { "id": "task_7", "summary": "Review API draft" },
  "resource": { "cpu_pct": 12, "mem_mb": 512 },
  "errors_recent": [{ "at": "...", "code": "UPSTREAM_TIMEOUT", "message": "..." }]
}

6.2 项目级聚合

GET /projects/{project_id}/dashboard-snapshot

返回：活跃实例数、按 phase 分布、近 1h 失败率、平均任务耗时等 JSON 聚合（供 Heicode 控制台图表）。

6.3 指标导出（可选）

• GET /metrics —— Prometheus 文本；或
• GET /projects/{project_id}/metrics.json —— 简化 JSON。

6.4 子 Agnet 输出流（Heicode 编码侧）

面向 Heicode 客户端在会话内展示 Agnet 平台子 agent 的产出（与 §6.1 的「实例心跳/资源占用」互补：此处强调 内容增量，而非仅状态字段）。

设计意图（路径可等价映射）：

• GET /sessions/{session_id}/sub-agents/{sub_agent_id}/stream —— SSE，或
• WS /sessions/{session_id}/stream —— 多路复用主题：sub_agent.output、sub_agent.tool_result 等。

data 示例（输出增量）

{
  "schema_version": 1,
  "type": "output_delta",
  "sub_agent_id": "sub_agi_1",
  "parent_turn_id": "turn_42",
  "content": { "mime": "text/markdown", "delta": "..." },
  "finished": false
}

• 鉴权与租户隔离与 §2～§4 一致；仅授权用户可读本会话下的子代理流。
• 若实际实现将子代理输出 嵌套在既有对话/Messages 协议中，须在联合 RFC 中声明字段映射，语义与本节一致即可。

---

7. 事件流（SSE / WebSocket）

两类订阅（勿混淆）：

1. 平台/实例生命周期与运行态（与 §6.1、§6.2 对照）：阶段变更、健康、任务摘要等 —— 主要支撑 Heicode Manager 与状态面板。
2. 会话内子代理输出与工具结果（与 §6.4 对照）—— 主要支撑 Heicode 客户端编码界面；实现上可与下述端点合并为多路事件，但 事件 type 必须可区分。

7.1 SSE（推荐易调试）

GET /agent-instances/{instance_id}/events

• Headers：Accept: text/event-stream
• 事件：id、event、data（JSON）

data 示例

{
  "schema_version": 1,
  "type": "phase_changed",
  "from": "pending",
  "to": "running",
  "at": "2026-04-30T12:00:01Z"
}

7.2 WebSocket（高吞吐）

WS /projects/{project_id}/stream

• 首帧 鉴权（query token 或子协议）；订阅主题：deployment.、instance.。

7.3 重连与顺序

• 支持 Last-Event-ID；服务端保留短期 环形缓冲（如 15 分钟）以便断线续传。

---

8. 审计与合规（跨 M4/M5）

• GET /audit-logs?tenant_id=&from=&to= —— 仅 auditor / org_admin。
• 每条：actor、action、resource、tenant_id、request_id、correlation_id、result。

---

9. 错误模型

HTTP	含义	客户端行为
400	参数错误	展示校验细节
401	未认证	刷新令牌
403	权限不足	引导申请角色
404	不存在或无权（对外统一）	不泄漏存在性
409	状态冲突（重复部署）	幂等重试策略
429	限流	退避
503	编排背压	重试 + 降级文案

响应体统一 envelope：

{ "error": { "code": "FORBIDDEN_CROSS_TENANT", "message": "...", "request_id": "..." } }

---

10. 版本与演进

• URL 前缀：/api/v1；破坏性变更引入 /api/v2。
• 事件 schema_version 递增；客户端忽略未知字段。

---

11. OpenAPI / 交付物建议

• Agnet 侧维护 OpenAPI 3.1 与 异步 API（SSE/WS）说明；
• 提供 Postman Collection + 租户穿越测试集合。

---

12. 编排决策权模型（新增约束）

为避免“模型直接执行导致越权/失控”，本项目明确采用：

• 模型提案：模型基于 SK 产出 orchestration_plan
• 平台裁决：Agnet 对提案执行权限、租户、预算、模型授权校验后决定执行
• Manager 入口：Heicode Manager 仅作为调用入口与状态展示，不绕过裁决链路

详见：[./orchestration-plan-contract.md](./orchestration-plan-contract.md)。

最低校验项（平台必须执行）：

1. tenant_id / project_id 与令牌一致
2. 成员与角色具备部署权限
3. default_model_id 在组织策略允许范围
4. sk_sources 可解析且无越权路径
5. 预算上限（tokens / cost / duration）未超策略阈值

---

13. 事件字典（建议最小集）

建议固定以下事件名，避免前后端各自命名造成协议漂移：

event	用途
deployment.accepted	部署请求被接受，进入编排队列
deployment.rejected	部署被策略拒绝
instance.phase_changed	执行单元阶段变化
instance.health_changed	执行单元健康状态变化
sub_agent.output_delta	子 agent 流式输出增量
sk_snapshot_refreshed	SK 快照刷新完成

每个事件最小字段建议：

• event_id
• schema_version
• tenant_id
• project_id
• deployment_id
• correlation_id
• occurred_at

---

14. 业务错误码字典（补充）

除 HTTP 状态码外，建议统一错误码最小集合：

code	说明
POLICY_REJECTED	平台策略拒绝执行提案
MODEL_NOT_ALLOWED	模型未授权
SK_SOURCE_UNRESOLVABLE	SK 源不可解析或不可读
BUDGET_EXCEEDED	超预算
FORBIDDEN_CROSS_TENANT	跨租户访问拒绝
DEPLOYMENT_CONFLICT	幂等或状态冲突
CALLBACK_SIGNATURE_INVALID	回调签名校验失败

验收用例集合见：[./acceptance-matrix.md](./acceptance-matrix.md)。

---

本文档随里程碑评审更新；实现细节以 Agnet 与 Heicode 联合 RFC 为准。