# 集成与平台接口（阅读地图）

> 受众：实现 Agnet 平台侧、与 Heicode 对接编排或事件流的工程师；以及 Heicode Manager / 客户端中负责对外契约的同学。

本目录回答三个问题：

1. Heicode 与 Agnet **谁负责什么**（产品分工与边界）
2. 二者之间走 **什么协议、什么字段**（API 契约）
3. 这些能力 **何时落地**（与里程碑对齐）

## 推荐阅读顺序


| 步骤  | 文档                                                                                                          | 你将得到                                               |
| --- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| 1   | `[../glossary.md](../glossary.md)`                                                                          | 统一术语：Heicode / Manager / 客户端 / 子 agent / SK / 标识符等 |
| 2   | `[../architecture.md](../architecture.md)`                                                                  | 整体架构与数据流（mermaid）                                  |
| 3   | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §1.1                                     | Manager 与客户端在 Agnet 可视化中的职责划分                      |
| 4   | `[../sk-lifecycle.md](../sk-lifecycle.md)`                                                                  | SK 来源、快照、写权边界（**单点真相**）                            |
| 5   | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §2–§3                                    | 身份、调用方式、RBAC                                       |
| 6   | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §4                                       | 多租户与隔离                                             |
| 7   | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §5                                       | 一键部署、SK 绑定、控制面 API                                 |
| 8   | `[./orchestration-plan-contract.md](./orchestration-plan-contract.md)`                                      | 模型提案对象与平台裁决规则                                      |
| 9   | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §6–§7                                    | 运行态、聚合视图、事件流（双轨）                                   |
| 10  | `[./Heicode-登录接口对接文档.md](./Heicode-登录接口对接文档.md)`                                                    | 已上线认证接口契约（login / me / refresh / logout）          |
| 11  | `[./heicode-oauth-flow.md](./heicode-oauth-flow.md)`                                                        | 客户端浏览器登录到 Manager 的完整流程                            |
| 12  | `[./acceptance-matrix.md](./acceptance-matrix.md)`                                                          | 集成验收最小测试矩阵                                         |
| 13  | `[../milestones/README.md](../milestones/README.md)` + `[../milestones/STATUS.md](../milestones/STATUS.md)` | 落地节奏与现状                                            |


## 边界速览


| 主题             | Heicode Manager | Heicode 客户端 | Agnet 平台               |
| -------------- | --------------- | ----------- | ---------------------- |
| 一键部署 Agnet 团队  | 入口与编排请求         | 不参与         | 接收 `POST /deployments` |
| 模型策略与计费        | 路由 / RBAC / 计费  | 调用 Manager  | 不参与                    |
| 子 agent 输出展示   | 平台运行态汇总         | 会话内增量展示     | 提供 SSE/WS 流            |
| SK 正文写入        | **不允许**         | 唯一编辑入口      | **不允许**（仅只读快照）         |
| 凭据（Git/云 SA）写入 | 持久化与轮换          | 发起授权        | 按租户使用                  |


## 与里程碑的关系

API 设计中的章节与里程碑的对应：


| API 设计章节        | 主对应里程碑                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------- |
| §2 身份 / §3 RBAC | [M1](../milestones/M1-contract-identity.md)、[M4](../milestones/M4-tenant-rbac-isolation.md)             |
| §4 多租户隔离        | [M4](../milestones/M4-tenant-rbac-isolation.md)                                                         |
| §5 编排控制面        | [M3](../milestones/M3-agnet-orchestration-bridge.md)                                                    |
| §6 / §7 运行态、事件流 | [M5](../milestones/M5-observability-visualization.md)                                                   |
| §8 审计           | [M4](../milestones/M4-tenant-rbac-isolation.md) / [M5](../milestones/M5-observability-visualization.md) |


## 集成方常见疑问

- **「Agnet 控制台为什么不能改 SK？」** 见 `[../sk-lifecycle.md](../sk-lifecycle.md)` §二 / §六
- **「子 agent 输出走 §6 还是 §7？」** 两节互补：`§6.4` 强调内容增量，`§7` 强调订阅与重连；事件 `type` 必须可区分
- **「跨租户负例怎么测？」** 见 `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §4.3
- **「破坏性变更怎么走？」** 见 `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §10