chenchen/heicode-win
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: remove obsolete agnet plans

Browse Source
This commit is contained in:
gongzhiyong
2026-05-02 22:11:19 +08:00
parent f585d26fe7
commit 72d0e095a4
18 changed files with 25 additions and 1173 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/integration/README.md
+9 -59
View File
@@ -1,64 +1,14 @@
# 集成与平台接口（阅读地图）
# 集成契约入口
> 受众：实现 Agnet 平台侧、与 Heicode 对接编排或事件流的工程师；以及 Heicode Manager / 客户端中负责对外契约的同学。
本目录只保留当前仍贴近实现的登录与客户端认证契约。Agnet / NewAPI / Secret Store 的新边界和实施计划统一放在 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md)。
本目录回答三个问题：
## 保留文档
1. Heicode 与 Agnet **谁负责什么**（产品分工与边界）
2. 二者之间走 **什么协议、什么字段**（API 契约）
3. 这些能力 **何时落地**（与里程碑对齐）
| 文档 | 用途 |
|------|------|
| [`Heicode-登录接口对接文档.md`](./Heicode-登录接口对接文档.md) | 已上线账号密码登录接口契约 |
| [`heicode-oauth-flow.md`](./heicode-oauth-flow.md) | Heicode 客户端通过浏览器登录 Manager 的流程 |
## 当前主线
## 已清理内容
2026-05-02 之后，Manager / NewAPI / Agnet / Secret Store 的主边界以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 为准。
本目录中的旧接口草案可作为历史参考；如果出现冲突，优先采用新架构计划。
## 推荐阅读顺序
| 步骤 | 文档 | 你将得到 |
| --- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| 1 | `[../saas-manager-agnet-architecture-plan.md](../saas-manager-agnet-architecture-plan.md)` | 新主线：SaaS Manager、NewAPI、Agnet、Secret Store 的职责边界 |
| 2 | `[../glossary.md](../glossary.md)` | 统一术语：Heicode / Manager / 客户端 / 子 agent / SK / 标识符等 |
| 3 | `[../architecture.md](../architecture.md)` | 整体架构与数据流（mermaid） |
| 4 | `[../sk-lifecycle.md](../sk-lifecycle.md)` | SK 来源、快照、写权边界（**单点真相**） |
| 5 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` | 历史 API 草案：需按新主线重写后才能作为实现契约 |
| 6 | `[./agnet-user-deployment-flow.md](./agnet-user-deployment-flow.md)` | 历史用户流程草案：Git 来源和云权限应升级为统一资源绑定 |
| 7 | `[./orchestration-plan-contract.md](./orchestration-plan-contract.md)` | 历史编排提案草案：需补齐 Resource Grant、Secret Broker 与平台代理 |
| 8 | `[./Heicode-登录接口对接文档.md](./Heicode-登录接口对接文档.md)` | 已上线认证接口契约（login / me / refresh / logout） |
| 9 | `[./heicode-oauth-flow.md](./heicode-oauth-flow.md)` | 客户端浏览器登录到 Manager 的完整流程 |
| 10 | `[./acceptance-matrix.md](./acceptance-matrix.md)` | 集成验收最小测试矩阵，后续需要按新主线更新 |
## 边界速览
| 主题 | Heicode Manager | Heicode 客户端 | Agnet 平台 |
| -------------- | --------------- | ----------- | ---------------------- |
| 一键部署 Agnet 团队 | 入口与编排请求 | 不参与 | 接收 `POST /deployments` |
| 模型策略与计费 | 路由 / RBAC / 计费 | 调用 Manager | 不参与 |
| 子 agent 输出展示 | 平台运行态汇总 | 会话内增量展示 | 提供 SSE/WS 流 |
| SK 正文写入 | **不允许** | 唯一编辑入口 | **不允许**（仅只读快照） |
| 凭据（Git/云 SA）写入 | 通过 Secret Broker 托管、轮换、撤销 | 发起授权 | 运行时按 Resource Grant 和 K8s 身份受控使用 |
## 与里程碑的关系
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
旧的 Agnet API 草案、编排提案、验收矩阵和 M1-M5 计划已经删除。后续需要按新主线重新生成正式契约，而不是沿用旧文档。
docs/integration/acceptance-matrix.md
-54
View File
@@ -1,54 +0,0 @@
# Agnet 集成验收矩阵
本文用于把集成设计从“建议”变成“可执行验收项”。
## 1. 验收范围
- 编排控制面（部署/停止/查询）
- 租户隔离与权限
- SK 快照只读边界
- 事件流（运行态 + 子 agent 输出）
- 回调签名与重试
## 2. 用例矩阵（最小集）
| ID | 类别 | 场景 | 前置条件 | 期望结果 |
|----|------|------|----------|----------|
| A01 | Happy path | `agile_min` 一键部署成功 | 模板可用、成员与模型已授权 | 返回 `deployment_id`，实例进入 `pending→running` |
| A02 | Happy path | `waterfall_min` 一键部署成功 | 同 A01 | 返回 `deployment_id`，角色实例齐全 |
| A03 | 授权 | 成员指定未授权模型 | 组织模型白名单不包含该模型 | 拒绝，`MODEL_NOT_ALLOWED` |
| A04 | 多租户 | Tenant A 访问 Tenant B 部署 | 两租户均有数据 | 返回 `403` 或 `404`（不泄漏存在性） |
| A05 | SK 边界 | 子 agent 绑定越权路径 | `sk_sources` 路径超白名单 | 拒绝，`SK_SOURCE_UNRESOLVABLE` 或 `FORBIDDEN_CROSS_TENANT` |
| A06 | 预算 | 模型提案预算超限 | 策略设定 max budget | 拒绝，`BUDGET_EXCEEDED` |
| A07 | 幂等 | 同 `intent_id` 重复提交 | 首次已 accepted | 第二次返回冲突或幂等复用，`DEPLOYMENT_CONFLICT` |
| A08 | 回调安全 | callback 签名错误 | 模拟篡改签名 | 拒绝处理并记审计 |
| A09 | 事件流 | SSE 断线后续传 | 已产生事件、支持 `Last-Event-ID` | 重连后补齐丢失窗口事件 |
| A10 | 子输出流 | 会话订阅 `sub_agent.output` | 会话内子 agent 正在运行 | 客户端收到 `output_delta` 流式事件 |
| A11 | 运行时绑定 | 部署携带非法 `runtime_execution` 引用 | principal 不属于租户或未授权 | 拒绝，`RUNTIME_BINDING_INVALID` |
| A12 | SK 策略 | `sk_access_policy` 与租户策略冲突 | 显式拒绝覆盖必需快照路径 | 拒绝，`SK_POLICY_REJECTED` |
## 3. 验收字段（每条事件必须）
- `event_id`
- `schema_version`
- `tenant_id`
- `project_id`
- `deployment_id`
- `correlation_id`
- `occurred_at`
## 4. 验收结论模板
| 项目 | 结果 | 备注 |
|------|------|------|
| 通过数 / 总数 | | |
| 阻断问题 | | |
| 风险接受项 | | |
| 下一轮回归时间 | | |
## 5. 执行建议
- 每次版本上线前至少执行 A01/A02/A04/A05/A08/A09
- 每次策略变更后追加 A03/A06 回归
- 验收输出应关联 `request_id` 与 `correlation_id`，便于排障
docs/integration/agnet-platform-api-design.md
-492
View File
@@ -1,492 +0,0 @@
# Agnet 平台 ↔ Heicode 集成接口设计（草案）
> Deprecated: 本文是早期接口草案。2026-05-02 之后，Manager / NewAPI / Agnet / Secret Store 的主边界以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 为准。本文如与新架构计划冲突，以新架构计划为准。
本文描述 **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`** 等聚合端点，但 **语义不得缩水**。
**启动参数与权限归属（与 Manager 的边界）**
- **Agnet 在拉起编队 / 子 agent 运行时**（进程或等价隔离单元）须获得完整部署参数：`sk_sources`、`runtime_execution`、`sk_access_policy`、成员与模型声明等；**不得在缺少参数时静默放宽为越权默认**。
- **权限与策略的可执行副本落在 Agnet**：Git 连接、`cloud_principal_refs`、SK 允许/拒绝边界由 Agnet 控制面 **落账并在运行时强制执行**；Heicode Manager **只负责发起部署请求并展示 Agnet 回传的快照锚点与观测字段**，**不是**运行时的权限裁决引擎。
| 契约项 | 要求 |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **一键部署** | 在 **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 内容。 |
| **云上 / 运行时权限（须随部署传参）** | 用户在 **Heicode Manager** 中为子 agent 配置的 **执行环境绑定**（例如专用虚拟机池、云 identity / 服务账号引用、网络或资源配额策略 ID）**必须**出现在 **部署请求体**（或等价的平台编排参数）中，由 **Agnet 调度与强制执行**；不得假设「仅在控制台勾选、不传平台即可生效」。缺省值与继承规则（编队级 → 子 agent 覆盖）须在联合 RFC 中写死。 |
| **SK 访问策略（允许 / 禁止，须随部署传参）** | 除 **`sk_sources` 解析出的快照正文**外，须支持显式声明 **SK 工具/技能命名空间或路径的允许集与拒绝集**（或引用租户级策略模板 ID）。部署完成后，平台将 **物化**各子 agent 的 **有效 SK 策略**：快照内容 ∩ 允许规则 − 拒绝规则；子 agent 运行时 **不得**调用策略外的 SK 工具入口（与 §12 校验一致）。 |
| **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 合并）**
```json
{
"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"],
"runtime_execution": {
"profile_id": "exec_profile_vm_dedicated",
"cloud_principal_refs": ["cp_az_mi_ci_readonly"],
"network_policy_ref": "net_tenant_isolated"
},
"sk_access_policy": {
"policy_ref": "tenant_sk_policy_default",
"deny_skill_ids": ["sk_admin_dest_env"],
"inherit_deployment_defaults": true
}
}
],
"parameters": { "unit_overrides": {} }
}
```
- `**runtime_execution`（推荐）**：承载 **子 agent 云上执行绑定**（VM/池、云 SA/MI、网络策略等）；字段名可映射为 Agnet 内部模型，但 **语义不得省略**——Manager 收集的配置必须可达 Agnet。
- `**sk_access_policy`（推荐）**：与 **`sk_sources` 快照**配合，声明 **允许/拒绝** 的技能 ID、路径前缀或租户策略引用；平台在部署落账时计算 **effective policy** 并下发给运行时。
- `**sk_sources`（推荐显式建模）**：替代或细化纯路径数组 `sk_file_refs`; 每个元素标明来源类型，便于 Agnet 实现拉取与快照。
**部署请求体中 SK 绑定扩展示意**
```json
"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`、`runtime_execution`、`sk_access_policy`**（字段名可等价映射）；返回 `**deployment_id**`、实例/子 agent 标识，供 Callback 与观测关联。 |
| **SK 快照只读** | 对每个 `deployment_id` / `sub_agent_id`，Agnet 须能记录 **已解析的 SK 快照**（Git：`commit_sha` + 路径哈希；Upload：`artifact_id` + 版本）。运行注入 **仅此快照**，不得在执行中「瞒报版本」拉未授权路径。 |
| **运行时绑定落账** | 部署请求中的 **`runtime_execution`（或等价字段）** 必须持久化，并在 **实例化子 agent** 时绑定到实际执行环境（VM、identity、网络隔离等）；观测 API 能回答「该实例使用了哪套运行时绑定」。 |
| **SK 策略物化** | 部署接受后，Agnet 必须能输出 **每个子 agent 的生效 SK 策略**（快照哈希 + `sk_access_policy` 解析结果），供 Manager **Git 来源 / 审计**页展示「允许 / 禁止 SK」结论与追溯。 |
| **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 / 上传件）—快照版本—**运行时绑定**—**生效 SK 策略**」；Git 更新或 Heicode 重新上传后，按刷新策略在后续运行使用新快照。
### 5.1 部署编队
`POST /deployments`
**请求体（示意）**
```json
{
"project_id": "prj_xxx",
"template": "agile_min",
"correlation_id": "mgr_cor_abc",
"members": [],
"sub_agents": [],
"parameters": {
"unit_overrides": {}
}
}
```
**响应**
```json
{
"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}`
**响应字段（示意）**
```json
{
"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 示例（输出增量）**
```json
{
"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 示例**
```json
{
"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：
```json
{ "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）未超策略阈值
6. 若请求包含 **`runtime_execution`**：`profile_id` / `cloud_principal_refs` 等引用 **属于本租户且已授权**，否则 **拒绝部署**（错误码建议 `RUNTIME_BINDING_INVALID`）。
7. 若请求包含 **`sk_access_policy`**：须与租户默认策略合并并 **物化为可执行的生效边界**；非法组合（例如引用禁止的技能 ID、与快照路径冲突）返回 **403** / `SK_POLICY_REJECTED`。
---
## 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 源不可解析或不可读 |
| `RUNTIME_BINDING_INVALID` | 云上 / 运行时绑定引用无效或未授权 |
| `SK_POLICY_REJECTED` | SK 允许 / 拒绝策略与快照或租户策略冲突 |
| `BUDGET_EXCEEDED` | 超预算 |
| `FORBIDDEN_CROSS_TENANT` | 跨租户访问拒绝 |
| `DEPLOYMENT_CONFLICT` | 幂等或状态冲突 |
| `CALLBACK_SIGNATURE_INVALID` | 回调签名校验失败 |
验收用例集合见：`[./acceptance-matrix.md](./acceptance-matrix.md)`。
---
*本文档随里程碑评审更新；实现细节以 Agnet 与 Heicode 联合 RFC 为准。*
docs/integration/agnet-user-deployment-flow.md
-160
View File
@@ -1,160 +0,0 @@
# Agnet 用户部署流程
> Deprecated: 本文是早期用户流程草案。2026-05-02 之后，资源绑定、凭证托管、NewAPI 解耦和 Agnet AKS 运行身份以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 为准。本文如与新架构计划冲突，以新架构计划为准。
本文记录 Heicode Manager 中用户从绑定仓库、授权云资源，到部署子 Agnet 的目标流程。它描述产品语义和交互顺序，具体 API 字段以 [`agnet-platform-api-design.md`](./agnet-platform-api-design.md) 与 [`orchestration-plan-contract.md`](./orchestration-plan-contract.md) 为准。
## 一、绑定代码与 SK 仓库
用户进入 Manager 后，首先绑定 Git 来源。Git 来源可以是任意 GitHub 仓库、企业 GitHub、GitLab、Gitea、Gitee，或其他自建代码库，只要平台能通过连接凭据读取指定 ref 与路径即可。
一个 Git 来源可以承担以下几类用途：
- 项目代码仓库：存放当前要开发、修改、构建或发布的业务项目。
- SK 技能仓库：存放子 Agnet 启动和运行时需要读取的 SK/技能定义。
- 二合一仓库：项目代码与 SK 技能放在同一个仓库中，通过不同路径区分。
绑定时至少需要记录：
- `connection_id`：该 Git 连接在租户内的引用 ID。
- `repo_url`：代码库地址。
- `ref`：分支、tag 或 commit。
- `paths`：允许读取的项目路径、SK 路径或 `AGENT.md` 路径。
Manager 不直接编辑 SK 正文，也不在部署后临时扩大仓库读取范围。部署时传给 Agnet 的应是明确的 `sk_sources` 与可解析的 Git ref/path 边界。
## 二、绑定云服务权限
部署子 Agnet 前，用户还需要绑定可供子 Agnet 使用的云服务权限。云服务可以是 AWS、Azure、GCP 等完整云账号/项目，也可以是单项资源权限，例如某台虚拟机、某个数据库、某个对象存储桶、某个托管身份或服务账号。
绑定结果不应把明文密钥暴露给前端部署表单，而应形成可引用的租户内权限对象，例如：
- `cloud_principal_refs`：云身份、托管身份、服务账号或角色引用。
- `profile_id`：执行环境档案，例如 VM 池、容器执行环境、区域、配额、镜像或运行约束。
- `network_policy_ref`：网络访问策略，例如只能访问指定 VPC、数据库或内网域名。
这些引用必须属于当前租户，并在部署前由 Manager/Agnet 校验可用性。部署请求中只传引用，不传明文凭据。
## 三、定义子 Agnet 编队
用户准备部署前，需要为每个子 Agnet 明确角色与边界。每个子 Agnet 至少要确定：
- 角色：例如架构师、实现者、测试者、审查者、发布者等。
- 目标：本次部署中该角色要完成的任务。
- 默认模型：该子 Agnet 优先使用的模型或模型策略。
- 启动 `AGENT.md`：该子 Agnet 启动时读取的固定指令文件，可来自项目仓库或 SK 仓库。
- 可用 Git 权限：该子 Agnet 能读取或写入哪些仓库、ref、路径。
- 可用云权限：该子 Agnet 能使用哪些 `cloud_principal_refs`、执行环境和网络策略。
- SK 访问策略：允许使用哪些 SK，禁止使用哪些 SK，是否继承租户或部署级默认策略。
这些信息应合并成部署计划中的 `agents[]`：
```json
{
"role_template": "implementation_agent",
"goal": "Implement the selected feature in the project repository.",
"default_model_id": "mdl_claude_sonnet",
"sk_sources": [
{
"type": "git",
"repo_ref": {
"connection_id": "git_main",
"repo_url": "https://github.com/org/project.git",
"ref": "main",
"paths": ["AGENT.md", "skills/implementation.md"]
}
}
],
"runtime_execution": {
"profile_id": "rt_azure_vm_pool_build",
"cloud_principal_refs": ["cp_azure_mi_build"],
"network_policy_ref": "net_project_private"
},
"sk_access_policy": {
"policy_ref": "sk_policy_project_default",
"deny_skill_ids": ["prod-db-write"],
"inherit_deployment_defaults": true
}
}
```
## 四、部署前确认
Manager 在发送部署请求前，应向用户展示一份可审阅的部署摘要：
- 本次部署使用的项目仓库与 SK 仓库。
- 每个子 Agnet 的角色、目标和启动 `AGENT.md`。
- 每个子 Agnet 的 Git 读取/写入范围。
- 每个子 Agnet 的云权限、执行环境和网络边界。
- 每个子 Agnet 的 SK 允许/拒绝策略。
- 预算、时长、模型允许列表、租户和项目 ID。
用户确认后，Manager 将部署计划发送给 Agnet 平台。Agnet 平台负责解析 Git 快照、物化有效 SK 策略、绑定云运行时权限，并返回 `deployment_id`。
## 五、部署后观测
部署完成后，Manager 需要展示 Agnet 回传的结果，而不是重新推断运行时权限：
- `deployment_id` 与当前状态。
- 每个子 Agnet 的角色、模型、目标。
- Git/SK 快照锚点，例如 commit sha、路径哈希、artifact ID。
- 生效的云运行时绑定。
- 生效的 SK 访问策略。
- 事件、审计与失败原因。
如果 Agnet 拒绝部署，Manager 应保留并展示拒绝原因，例如 Git 来源不可解析、云 principal 不属于租户、网络策略不可用，或 SK 策略冲突。
## 六、前端承载建议
该流程在前端上更适合做成分步向导，而不是单个 JSON 表单：
1. 绑定 Git 来源：选择代码仓库、SK 仓库或二合一仓库，并选择 ref/path。
2. 绑定云权限：选择 AWS/Azure/GCP 或单项资源权限，生成可引用的 principal/profile/network policy。
3. 定义子 Agnet：为每个角色配置目标、模型、启动 `AGENT.md`、Git 范围和云权限。
4. 配置 SK 策略：选择允许/禁止的 SK，确认继承规则。
5. 部署前确认：展示每个子 Agnet 的最终权限摘要。
6. 部署后观测：展示快照锚点、运行时绑定、事件和审计。
最低可用版本可以继续使用 JSON 高级表单，但面向普通用户的主路径应提供结构化选择器与摘要确认页。
## 七、与当前前端的差距
当前 Manager 前端已经有 Agnet 部署入口，也能在高级表单中提交 `sk_sources`、`runtime_execution` 与 `sk_access_policy`。这说明底层部署 payload 的方向是对的，但还没有完整覆盖上述用户路径。
已经体现的部分：
- 部署表单支持为每个 agent 填写 `role_template`、`goal` 与默认模型。
- 部署表单支持通过 JSON 填写 Git 型 `sk_sources`。
- 部署表单支持填写执行 profile、云 principal 与网络策略引用。
- 部署表单支持填写 SK 策略引用、禁止技能与继承默认策略。
- Git 来源页已经用文案表达「绑定代码/SK 仓库 -> 分配云权限 -> 部署 -> 查看快照锚点」。
- Agents 页面能从部署计划中展示每个子 Agnet 的运行时绑定与 SK 策略。
仍需补齐的部分：
- Git 连接管理：用户应能绑定 GitHub、企业 GitHub、GitLab、Gitea、Gitee 或自建 Git，而不是手写 `repo_url` JSON。
- 仓库用途建模：前端需要区分项目仓库、SK 仓库、二合一仓库，并允许为同一仓库选择不同 path/ref。
- 云权限绑定：前端需要提供 AWS、Azure、GCP 或单项资源权限的绑定页，并把结果保存为可引用的 principal/profile/network policy。
- `AGENT.md` 选择：每个子 Agnet 应能显式选择启动 `AGENT.md`，并展示它来自哪个仓库、ref 与路径。
- 权限摘要：部署前需要按子 Agnet 汇总 Git 范围、云权限、SK 允许/禁止规则，供用户确认。
- 策略校验反馈：当 Agnet 拒绝部署时，前端需要把 `SK_SOURCE_UNRESOLVABLE`、`RUNTIME_BINDING_INVALID`、`SK_POLICY_REJECTED` 等错误映射成人能理解的提示。
因此，当前前端更像「高级部署表单 + 观测页」，目标形态应升级为「连接绑定 -> 权限授权 -> 子 Agnet 编队 -> 部署确认 -> 观测审计」的主流程。
## 八、最小落地版本
为了尽快把用户路径跑通，可以分两阶段实现：
第一阶段保留现有部署接口，只补齐结构化前端：
- 新增 Git 来源管理页，保存 `connection_id`、`repo_url`、`ref` 与允许路径。
- 新增云权限引用管理页，保存 `cloud_principal_refs`、`profile_id` 与 `network_policy_ref`。
- 将新建部署 Sheet 改为分步表单，仍然生成当前 `orchestration_plan` payload。
- 在最后一步展示只读确认摘要。
第二阶段接入真实平台能力：
- Git 连接真正完成 OAuth/token/SSH key 授权与轮换。
- 云权限真正绑定 AWS/Azure/GCP 身份与单项资源。
- Agnet 平台返回已物化的 Git 快照、运行时绑定与 SK 生效策略。
- Manager 展示平台返回的有效策略，而不是只展示用户提交的原始计划。
docs/integration/heicode-oauth-flow.md
+1 -2
View File
@@ -127,7 +127,7 @@ sequenceDiagram
## 六、与 Agnet API 设计的衔接
- 这里的 Token 用于 Heicode 客户端调 Manager；Manager 调 Agnet 时使用 `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §2.1 / §2.2 中的 M2M JWT 或用户委派令牌
- 这里的 Token 用于 Heicode 客户端调 Manager；Manager 调 Agnet 时应使用服务间令牌或受控委托令牌，具体以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 为准
- 跨链路追踪建议在 Manager 调 Agnet 时附带 `X-Heicode-Correlation-Id` 与本登录会话关联
## 七、安全注意事项
@@ -147,4 +147,3 @@ sequenceDiagram
![Heicode login flow screenshot 04](../images/wecom-screenshot-04.jpg)
![Heicode login flow screenshot 05](../images/wecom-screenshot-05.jpg)
![Heicode login flow screenshot 06](../images/wecom-screenshot-06.jpg)
docs/integration/orchestration-plan-contract.md
-122
View File
@@ -1,122 +0,0 @@
# 编排提案契约（`orchestration_plan`）
> Deprecated: 本文是早期编排提案草案。2026-05-02 之后，正式计划需要补齐 Resource Grant、Secret Broker、Secret Store、AKS 运行身份和平台代理语义；主参考见 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md)。
本文定义「模型提案、平台裁决」模式下的最小编排对象，供 Heicode / Manager / Agnet 三方对齐。
## 1. 决策边界
- **模型（经 SK 引导）**：产出编排提案 `orchestration_plan`
- **Agnet 平台**：执行策略裁决（权限、预算、模型授权、租户隔离），并决定是否执行
- **Heicode Manager**：承载入口与状态展示，透传提案并记录 `correlation_id`
## 2. 最小对象
```json
{
"intent_id": "intent_20260430_001",
"template_hint": "agile_min",
"objective": "实现并验证用户登录链路",
"risk_level": "medium",
"budget": {
"max_tokens": 120000,
"max_cost_usd": 8.0,
"max_duration_sec": 3600
},
"agents": [
{
"role_template": "AG-PO",
"goal": "拆解验收标准并输出任务分配",
"default_model_id": "mdl_claude_sonnet",
"sk_sources": [
{
"type": "git",
"repo_ref": {
"connection_id": "gitconn_1",
"repo_url": "https://example.com/org/sk-repo.git",
"ref": "main",
"paths": ["agile/po-guideline.md"]
}
}
]
},
{
"role_template": "AG-DEV",
"goal": "按拆解清单完成实现与自测",
"default_model_id": "mdl_claude_sonnet",
"sk_sources": [],
"runtime_execution": {
"profile_id": "exec_profile_vm_pool_ci",
"cloud_principal_refs": ["cp_az_mi_build"],
"network_policy_ref": "net_project_default"
},
"sk_access_policy": {
"policy_ref": "tenant_sk_policy_default",
"deny_skill_ids": ["sk_cross_env_admin"],
"inherit_deployment_defaults": true
}
}
],
"constraints": {
"allowed_model_ids": ["mdl_claude_sonnet", "mdl_claude_haiku"],
"forbidden_actions": ["cross_tenant_read", "credential_write"]
},
"metadata": {
"tenant_id": "ten_001",
"project_id": "prj_auth",
"correlation_id": "mgr_cor_abc"
}
}
```
## 3. 字段说明（最小集）
| 字段 | 必填 | 说明 |
|------|------|------|
| `intent_id` | 是 | 业务意图 ID，幂等与审计用 |
| `template_hint` | 是 | 期望模板（如 `agile_min` / `waterfall_min`） |
| `objective` | 是 | 任务目标摘要 |
| `risk_level` | 是 | `low` / `medium` / `high` |
| `budget.*` | 是 | token、成本、时长预算上限 |
| `agents[]` | 是 | 子 agent 提案列表 |
| `agents[].role_template` | 是 | 角色模板 |
| `agents[].goal` | 是 | 该角色目标 |
| `agents[].default_model_id` | 否 | 建议模型；最终由平台策略裁决 |
| `agents[].sk_sources` | 否 | SK 来源列表 |
| `agents[].runtime_execution` | 否 | **须在转为部署请求时保留**：子 agent 云上执行绑定（VM/池、云 principal、网络策略等），与 [`agnet-platform-api-design.md`](./agnet-platform-api-design.md) §5.0 一致 |
| `agents[].sk_access_policy` | 否 | **须在转为部署请求时保留**：SK 允许 / 禁止规则（引用或内联），与快照合并后由平台物化为生效策略 |
| `constraints.allowed_model_ids` | 否 | 允许模型白名单 |
| `metadata.tenant_id` | 是 | 顶层隔离键 |
| `metadata.project_id` | 是 | 项目标识 |
| `metadata.correlation_id` | 是 | 全链路追踪键 |
## 4. 裁决规则（平台侧）
Agnet 在执行前必须做下列校验：
1. 租户与项目一致性：`tenant_id` / `project_id` 与令牌声明匹配
2. 权限校验：调用主体具备部署与读取权限
3. 模型授权：`default_model_id` 在组织与项目策略允许范围内
4. SK 边界：`sk_sources` 可解析、可读、无越权路径
5. 预算约束：`max_tokens` / `max_cost_usd` / `max_duration_sec` 不超策略上限
6. 运行时边界：若存在 `runtime_execution`，其引用须为本租户已授权的执行档案 / 云 principal（否则 `RUNTIME_BINDING_INVALID`）
7. SK 策略：若存在 `sk_access_policy`，合并后须一致且可执行（否则 `SK_POLICY_REJECTED`）
## 5. 典型拒绝码
| code | 含义 |
|------|------|
| `POLICY_REJECTED` | 平台策略拒绝执行 |
| `MODEL_NOT_ALLOWED` | 模型未授权 |
| `SK_SOURCE_UNRESOLVABLE` | SK 源无法解析或无权限读取 |
| `RUNTIME_BINDING_INVALID` | 云上 / 运行时绑定无效或未授权 |
| `SK_POLICY_REJECTED` | SK 允许 / 拒绝策略冲突 |
| `BUDGET_EXCEEDED` | 预算超限 |
| `FORBIDDEN_CROSS_TENANT` | 跨租户访问拒绝 |
| `DEPLOYMENT_CONFLICT` | 幂等冲突或状态冲突 |
## 6. 对接建议
- `orchestration_plan` 建议由 Manager **无损映射**为 Agnet `POST /deployments` 标准 payload；**`runtime_execution` / `sk_access_policy` 不得在进入部署链路时丢弃**，否则子 agent 无法获得用户在 Manager 配置的权限与 SK 边界
- 拒绝时应返回 `error.code` + `request_id` + `correlation_id`
- 接受后返回 `deployment_id`，并通过事件流持续反馈执行状态