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/README.md
+6 -10
View File
@@ -1,6 +1,6 @@
# Heicode 文档入口
本目录是 Heicode 仓库的**文档主索引**。整体内容按受众分两条阅读路径，再共享一组通用骨架。
本目录是 Heicode 仓库的**文档主索引**。2026-05-02 之后，文档以 [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) 为主线；偏离该主线的旧 Agnet API 草案和 M1-M5 计划已清理。
## 共用骨架（建议都先读）
@@ -19,23 +19,19 @@
1. [`onboarding/README.md`](./onboarding/README.md)：阅读顺序
2. [`onboarding/local-dev.md`](./onboarding/local-dev.md)：本地联调步骤与排错
3. [`onboarding/env-variables.md`](./onboarding/env-variables.md)：环境变量手册
4. 回到共用骨架：[`architecture.md`](./architecture.md) → [`glossary.md`](./glossary.md)
5. 计划与现状：[`milestones/README.md`](./milestones/README.md)、[`milestones/STATUS.md`](./milestones/STATUS.md)
4. 回到共用骨架：[`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) → [`architecture.md`](./architecture.md) → [`glossary.md`](./glossary.md)
## 路径 B · Agnet / 平台集成方
适合实现 Agnet 平台侧、与 Heicode 对接编排或事件流的工程师。
1. [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) → [`glossary.md`](./glossary.md) → [`architecture.md`](./architecture.md)
2. [`integration/README.md`](./integration/README.md)：集成方阅读地图
3. [`sk-lifecycle.md`](./sk-lifecycle.md)：SK 边界（Heicode 端写、Agnet 只读快照）
4. [`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md)：历史 API 草案，若与新架构计划冲突，以新架构计划为准
5. [`integration/agnet-user-deployment-flow.md`](./integration/agnet-user-deployment-flow.md)：历史用户流程草案，若与新架构计划冲突，以新架构计划为准
6. [`integration/heicode-oauth-flow.md`](./integration/heicode-oauth-flow.md)：HeiCode 客户端 ↔ Manager 浏览器登录流程
7. 落地节奏：[`milestones/README.md`](./milestones/README.md)（M3–M5）+ [`milestones/STATUS.md`](./milestones/STATUS.md)
2. [`sk-lifecycle.md`](./sk-lifecycle.md)：SK 边界（Heicode 端写、Agnet 只读快照）
3. [`integration/README.md`](./integration/README.md)：当前仍保留的集成契约入口
4. [`integration/heicode-oauth-flow.md`](./integration/heicode-oauth-flow.md)：Heicode 客户端 ↔ Manager 浏览器登录流程
## 关于版本与更新
- 本目录下的文档以 **设计意图与契约语义** 为准；实现细节以仓库代码为准。
- 任一文档与代码出现冲突时，请在 PR 里同步更新文档与 [`milestones/STATUS.md`](./milestones/STATUS.md)。
- 任一文档与今晚主线出现冲突时，优先更新或删除冲突文档，不再保留多套计划并行。
- 受众边界：`docs/` 内不做产品营销文案，营销内容归 `website/`。
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`，并通过事件流持续反馈执行状态
docs/milestones/M1-contract-identity.md
-31
View File
@@ -1,31 +0,0 @@
# M1 · 契约与身份对齐
## 目标
在**不绑定具体云厂商**的前提下，冻结 **Heicode Manager** 与 **Heicode 客户端** 之间的最小身份与 API 语义，使后续 Agnet 集成可通过同一身份体系挂载授权。
## 完成定义（DoD）
- [ ] **登录与会话**：浏览器 OAuth / loopback 回调语义文档化；`session` 与 `token` 字段含义与过期策略书面一致。
- [ ] **模型发现**：`GET /v1/models`（或等价路径）的请求头、错误码与分页/过滤约定写入契约草案。
- [ ] **用户上下文**：客户端携带的租户/组织标识（若有）与 Manager 侧解析规则一致，避免 silent ignore。
- [ ] **版本协商**：客户端 `User-Agent` / `X-Heicode-Client-Version` 与 Manager 最低兼容矩阵写明。
## 依赖
- 无前置里程碑；为本目录后续里程碑的**共同前置**。
## 与 Agnet 的衔接（预备）
M1 **不要求** Agnet 已接入；但契约中预留：
- `X-Tenant-Id` / `X-Org-Id`（可选）传播约定，便于 M4 多租户对齐。
## 验收建议
- 自动化契约测试或 Postman/Newman 集合跑通最小路径。
- 产品侧评审：登录失败、令牌过期、权限不足三类错误对用户可见且可诊断。
## 风险
- 契约频繁变动会导致 M3 编排回调身份映射返工——M1 冻结后应通过**版本号**约束变更。
docs/milestones/M2-local-e2e.md
-29
View File
@@ -1,29 +0,0 @@
# M2 · 本地端到端闭环（单环境）
## 目标
在**单机或本地 Docker 网络**内跑通：**官网/文档 → Manager → Heicode 客户端 → 一次「写仓库 / 触发流水线」的示意闭环**（不要求生产级 SLA）。
## 完成定义（DoD）
- [ ] 本地可启动 Manager 与 Heicode 客户端（CLI 或 Desktop 至少其一）。
- [ ] 用户完成登录后，可拉取模型列表并成功发起**至少一类**对话或任务请求。
- [ ] **可追溯锚点**：产生一条可与 Git 提交或 CI Run ID 关联的记录（哪怕是脚本化演示）。
- [ ] 文档：开发者可在 30 分钟内按 README 复现上述路径。
## 依赖
- [M1](./M1-contract-identity.md) 契约可用。
## 与 Agnet 的衔接
- 本里程碑可用 **模拟编排**（静态 JSON / Mock Server）代替真实 Agnet；接口形状应对齐 [`agnet-platform-api-design.md`](../integration/agnet-platform-api-design.md) 中的 **Dry-run / Mock** 一节（若已定义）。
## 验收建议
- 录制简短屏幕录像或自动化 E2E（可选）。
- 清单式回归：**登录 → 模型 → 对话 → 追溯记录存在**。
## 风险
- 若跳过可追溯锚点，后续 M4/M5 审计字段难以回补。
docs/milestones/M3-agnet-orchestration-bridge.md
-32
View File
@@ -1,32 +0,0 @@
# M3 · Agnet 编排桥接（执行单元生命周期）
## 目标
**Agnet 平台**按约定 API 向 Heicode 暴露：**编队部署、执行单元状态、任务回写** 能力；Heicode Manager / 客户端可将编排动作纳入同一身份与审计链路。
## 完成定义（DoD）
- [ ] Agnet 侧实现集成文档中 **编排控制面** 最小集（部署/伸缩/停止编队或等价操作）；与 **Heicode Manager 一键部署 Agnet 团队** 能力对齐（**§5.0**：成员、成员模型、子 Agnet 绑定 `sk_file_refs`）。
- [ ] **SK 边界**：子 Agnet 仅按绑定 **只读** SK；SK 正文编辑 **仅** 经 Heicode，Manager/Agnet 无写入口（集成文档 **§5.0**、**§3.2**）。
- [ ] **回调/Webhook**：执行单元状态变更可推送到 Heicode 可订阅地址（或 Manager 注册 webhook URL）。
- [ ] **幂等与关联 ID**：每次部署生成全局唯一的 `deployment_id`，与 Heicode 侧 `correlation_id` 可互查。
- [ ] **失败语义**：超时、部分就绪、不可调度等状态码与可重试策略文档化。
- [ ] 联调环境：至少一套非生产 Agnet 与 Heicode **对打成功**（见集成文档验收用例）。
## 依赖
- [M1](./M1-contract-identity.md)
- [M2](./M2-local-e2e.md)（可用 Mock 缩短并行时间，但上线前需真实联调）
- 阅读 [`../integration/agnet-platform-api-design.md`](../integration/agnet-platform-api-design.md) 第 3～6 节（含 **§5.0**）
## 与 Agnet 的衔接
- 本里程碑直接消费 **部署类 API**、**Agent 实例 CRUD 语义**、**事件订阅**（见集成文档）。
## 验收建议
- 表格化测试用例：部署成功、部署失败回滚、并发部署隔离（与 M4 交叉验证）。
## 风险
- Agnet 若尚未稳定 **deployment_id → 实例列表** 映射，会导致 Heicode 客户端「状态面板」空洞（转入 M5）。
docs/milestones/M4-tenant-rbac-isolation.md
-31
View File
@@ -1,31 +0,0 @@
# M4 · 租户模型、RBAC 与数据隔离
## 目标
在 Agnet 与 Heicode 联合语境下，落实 **权限分离** 与 **多租户数据隔离**，使「平台管理员 / 组织管理员 / 项目成员 / 只读审计」可分工，且任意 API **默认不可跨租户泄漏**。
## 完成定义（DoD）
- [ ] **租户模型**：`tenant`（或 `org`）为顶层隔离边界；`project` / `environment` 为常用次级边界；标识符在请求头或路径中明确（见集成文档）。
- [ ] **RBAC**：至少四类角色行为矩阵落地（创建编队、查看密钥类操作、只读观测、平台运维）；拒绝默认「幂等全局读」。
- [ ] **数据面隔离**：存储层按租户分区（逻辑 schema / 物理库 / 命名空间之一），查询默认带 `tenant_id` 谓词；集成测试含 **跨租户负例**（必须 403/404）。
- [ ] **密钥与凭据**：连接 Git/云的凭据 **从不**在跨租户 API 响应中回显；轮换与审计字段可查。
- [ ] **审计日志**：敏感操作（部署、凭据绑定、策略变更）写入 **追加式审计流**，含操作者主体与 `correlation_id`。
## 依赖
- [M1](./M1-contract-identity.md)
- [M3](./M3-agnet-orchestration-bridge.md)（编排 API 已存在才可测隔离）
## 与 Agnet 的衔接
- 对齐集成文档 **§3 认证与授权**、**§5 多租户与数据隔离**。
## 验收建议
- 自动化 **租户穿越测试**（Tenant A 的 token 访问 Tenant B 资源必须失败）。
- 数据团队/安全团队走查 RBAC 矩阵与审计字段。
## 风险
- 「软隔离」（仅应用层过滤）在复杂查询下易遗漏——需在评审中明确 **查询路径全覆盖**。
docs/milestones/M5-observability-visualization.md
-37
View File
@@ -1,37 +0,0 @@
# M5 · 可观测性与可视化（运行态对外）
## 目标
为 **有状态执行单元** 提供 **可视化与可观测接口**，并与产品分工对齐（详见 [`../integration/agnet-platform-api-design.md`](../integration/agnet-platform-api-design.md) **§1.1**）：
- **Heicode Manager**：展示 Agnet 平台回传的 **运行态与性能类字段**（是否在跑、阶段、健康、资源占用、聚合指标、近期错误摘要等），支撑控制台与运维信任。
- **Heicode 客户端**：在编码与工作会话中 **实时展示子 Agnet 输出内容**（流式增量等），与会话上下文同屏，降低「黑盒」带来的协作摩擦。
团队与个人均可使用上述能力；差异在 **信息类型**（平台状态 vs 会话内子代理产出），不在用户类别。
## 完成定义（DoD）
- [ ] **快照 API**：按 `agent_id` / `deployment_id` 返回结构化状态（阶段、版本、最近心跳、队列深度等字段见集成文档 **§6.1**）—— 主要支撑 **Manager** 侧平台运行态。
- [ ] **子 Agnet 输出流**：会话内子执行单元产出可通过 SSE/WS 或等价协议增量下发（集成文档 **§6.4**），Heicode 客户端可订阅并与编码界面联动。
- [ ] **事件流**：支持 SSE 或 WebSocket **订阅**单实例或项目级 **生命周期/运行态** 事件；含断线重连与 `Last-Event-ID` 语义（集成文档 **§7**）；与「输出增量」事件类型可区分。
- [ ] **聚合视图**：项目级 Dashboard 所需指标（活跃单元数、失败率、平均耗时）可由 Agnet 聚合端点提供，或约定由 Heicode Manager 拉取后缓存（二选一须文档化）。
- [ ] **与权限联动**：只读角色仅能访问允许范围内的实例；事件流不得泄漏其他租户 ID。
- [ ] **SLI 约定**：可选暴露 RED/USE 类指标端点（Prometheus 或 JSON），便于接入现有监控。
## 依赖
- [M3](./M3-agnet-orchestration-bridge.md)（实例存在）
- [M4](./M4-tenant-rbac-isolation.md)（否则可视化接口本身成为数据泄漏面）
## 与 Agnet 的衔接
- 对齐集成文档 **§1.1**（职责划分）、**§6**（含 **§6.4** 子代理输出）、**§7**（事件流）。
## 验收建议
- 业务方 UAT：非技术成员能否从 UI 判断「卡在哪一步」。
- 负载测试：事件流在 **N 并发订阅** 下仍满足延迟上限（自定阈值）。
## 风险
- 若事件 schema 不版本化，客户端与平台升级易出现「半屏空白」——需 **schema 版本** 字段。
docs/milestones/README.md
-29
View File
@@ -1,29 +0,0 @@
# Heicode 交付里程碑（索引）
> 导航：[`../README.md`](../README.md) · [`../glossary.md`](../glossary.md) · [`../architecture.md`](../architecture.md) · [`./STATUS.md`](./STATUS.md)
本目录保存早期 M1-M5 里程碑草案。2026-05-02 之后，SaaS Manager、NewAPI、Agnet 和 Secret Store 的落地节奏以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 第十节为准。
本目录可作为历史参考；后续需要把 M1-M5 重写为 P0-P5 后再作为正式交付计划使用。
## 推荐阅读顺序
| 顺序 | 文档 | 摘要 |
|------|------|------|
| 0 | [SaaS Manager 与 Agnet 平台架构计划](../saas-manager-agnet-architecture-plan.md) | 当前主计划：P0-P5 |
| 1 | [M1-契约与身份对齐](./M1-contract-identity.md) | Heicode Manager ↔ 客户端最小契约；登录与令牌语义 |
| 2 | [M2-本地端到端闭环](./M2-local-e2e.md) | 单环境跑通：登录、模型发现、对话、一次发布链路（示意） |
| 3 | [M3-Agnet-编排集成](./M3-agnet-orchestration-bridge.md) | 拉起编队、执行单元生命周期与回调 Heicode |
| 4 | [M4-租户隔离与权限](./M4-tenant-rbac-isolation.md) | 多租户数据面隔离、RBAC、审计字段落地 |
| 5 | [M5-可观测与可视化](./M5-observability-visualization.md) | 运行态可视、指标与事件流对接 Heicode 客户端/控制台 |
## 与集成设计文档的关系
Agnet 平台应对外暴露的 **HTTP/gRPC 契约、事件流与隔离模型** 详述见：
**[`../integration/agnet-platform-api-design.md`](../integration/agnet-platform-api-design.md)**
早期里程碑 **M3～M5** 曾对应集成文档中的「编排 API」「安全与隔离」「观测与可视化 API」。这些内容需要按新的 Manager 资源绑定、Secret Broker、AKS 运行身份和 NewAPI 解耦方案重写。
---
*新增里程碑时请在本表追加一行，并在文档内标明前置依赖。*
docs/milestones/STATUS.md
-76
View File
@@ -1,76 +0,0 @@
# 里程碑现状对齐
本文以仓库当前代码为依据，对早期 M1-M5 的 DoD 项做粗粒度盘点，便于例会与评审快速对齐。2026-05-02 之后，正式计划以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 第十节 P0-P5 为准；本文保留为历史现状参考。
> 状态图例：
> - `done`：代码已落地并经过基本验证
> - `partial`：部分项可用，关键缺口已知
> - `todo`：尚未开始或仅有占位
> - `docs-only`：仅文档定义，待实现承接
>
> 来源依据：`cc-haha/src/server/api/heicode-auth.ts`、`cc-haha/src/server/services/providerService.ts`、`heicode/controller/heicode_oauth.go`、`heicode/router/heicode-router.go`、本仓库 `docs/`。
## M1 · 契约与身份对齐
| DoD | 状态 | 备注 |
|-----|------|------|
| 登录与会话语义文档化 | `done` | 详见 [`../integration/heicode-oauth-flow.md`](../integration/heicode-oauth-flow.md) |
| `/v1/models` 模型发现契约 | `partial` | 客户端 `providerService.fetchProviderModels` 已支持探活与多种返回结构；分页/过滤约定尚未文档化 |
| 用户上下文 `tenant_id` / `org_id` 传播 | `todo` | Heicode 客户端尚未在请求中显式注入；预留位置在请求头层 |
| 版本协商 `User-Agent` / `X-Heicode-Client-Version` | `todo` | 未在客户端统一植入 |
| `X-Tenant-Id` 预留约定 | `docs-only` | 见 API 设计 §2.3 |
## M2 · 本地端到端闭环
| DoD | 状态 | 备注 |
|-----|------|------|
| 本地可启动 Manager 与客户端 | `done` | 步骤见 [`../onboarding/local-dev.md`](../onboarding/local-dev.md) |
| 登录 → 模型 → 至少一类任务调用 | `partial` | API Key 路径完整；浏览器登录可达；端到端任务回归未自动化 |
| 可追溯锚点（Git commit / CI Run） | `todo` | 客户端尚未把会话与 Git/CI 关联 |
| 文档：30 分钟内复现 | `done` | 根 README + `onboarding/` 已覆盖 |
## M3 · Agnet 编排桥接
| DoD | 状态 | 备注 |
|-----|------|------|
| Agnet 控制面最小集（部署/伸缩/停止） | `docs-only` | 设计完整，本仓库不含实现 |
| Heicode Manager「一键部署 Agnet 团队」 | `todo` | 尚未在 `heicode` 中提供 |
| SK 边界（写权仅 Heicode、子 agent 只读） | `partial` | 文档单点真相已就绪（[`../sk-lifecycle.md`](../sk-lifecycle.md)）；客户端 SK 编辑入口待落地 |
| Webhook / 回调（Agnet → Heicode） | `todo` | Manager 未提供回调注册端点 |
| 幂等与 `deployment_id` / `correlation_id` | `docs-only` | 字段约定见 API 设计 §5.1、§2.3 |
| 失败语义（超时 / 部分就绪 / 不可调度） | `docs-only` | 待与 Agnet 联合评审落地 |
| 联调环境对打成功 | `todo` | 需要真实 Agnet 接入 |
## M4 · 租户、RBAC 与隔离
| DoD | 状态 | 备注 |
|-----|------|------|
| 租户模型（`tenant` 顶层） | `partial` | `heicode` 自身有用户/组/Token 体系；Heicode 维度未与 Agnet 集成 |
| RBAC 角色矩阵 | `partial` | `heicode` 控制台已有基础角色；与 Agnet 设计（`agnet:*` 角色）未对齐 |
| 数据面隔离与跨租户负例 | `todo` | 待联合 Agnet 落地后补测 |
| 凭据写入隔离（Git Token / 云 SA） | `docs-only` | 见 API 设计 §3.2 |
| 审计日志（追加式） | `partial` | `heicode` 自带操作日志；统一 `correlation_id` 字段未规范化 |
## M5 · 可观测性与可视化
| DoD | 状态 | 备注 |
|-----|------|------|
| 实例快照 API | `docs-only` | 字段定义见 API 设计 §6.1 |
| 子 Agnet 输出流（SSE/WS） | `todo` | 客户端 UI 尚未实现订阅 |
| 项目级聚合 / Dashboard | `partial` | `heicode` 控制台具备模型/Token 指标基础 |
| 事件流（含 `Last-Event-ID` 重连） | `docs-only` | 见 API 设计 §7 |
| 与 RBAC 联动 | `todo` | 需在 M4 落地后回填 |
| SLI 指标导出 | `todo` | Prometheus / JSON 端点未配置 |
## 风险与建议
1. **SK 边界要尽早写到自动化校验**：避免后续在 Agnet 控制台或 Manager 误开 SK 写 API
2. **`correlation_id` 与 `tenant_id` 在客户端先注入**：即便 Agnet 还没接，也方便后续审计回看
3. **Webhook 与回调签名先做规范**：联调时再补会引入兼容包袱
4. **客户端订阅子 agent 输出的协议** 在 UI 还没动前就该确定多路 `type` 命名
## 维护约定
- 每次 PR 涉及 M1–M5 任一 DoD 变化时，在本文相应行更新状态并简述
- 状态从 `docs-only` 升到 `partial` / `done` 时，标注 PR 链接或代码入口
- 本文不写时间表，避免与里程碑原文重复
docs/onboarding/README.md
+2 -2
View File
@@ -7,7 +7,7 @@
1. [`local-dev.md`](./local-dev.md)：把 `cc-haha`（客户端）、`heicode`（Manager）、`website`（站点）跑起来；含常见错误与排查
2. [`env-variables.md`](./env-variables.md)：客户端识别的环境变量（base URL、OAuth 配置）
3. 共用骨架：[`../architecture.md`](../architecture.md)、[`../glossary.md`](../glossary.md)、[`../sk-lifecycle.md`](../sk-lifecycle.md)
4. 现状对齐：[`../milestones/STATUS.md`](../milestones/STATUS.md)
4. 主计划对齐：[`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md)
5. 子项目细则：
- 客户端约定：[`../../cc-haha/AGENTS.md`](../../cc-haha/AGENTS.md)
- 网关约定：[`../../heicode/CLAUDE.md`](../../heicode/CLAUDE.md)
@@ -24,7 +24,7 @@
## 你不需要做的事
- **不要** 在 Heicode 客户端里实现计费 / 订阅；这部分归 Manager 与平台
- **不要** 在 Heicode 客户端里实现计费 / 订阅；这部分由 Manager 展示，底层能力来自 NewAPI
- **不要** 给 Agnet 平台或 Manager 增加可写 SK 正文的 API（违反 SK 边界，详见 [`../sk-lifecycle.md`](../sk-lifecycle.md)）
- **不要** 引入「客户端 → 模型供应商直连」的捷径；所有模型调用应经 Manager 路由
docs/onboarding/local-dev.md
+1 -1
View File
@@ -104,4 +104,4 @@ docker compose up -d --build heicode-www
2. 拉取模型列表（应来自 Provider API，不是硬编码）
3. 发起一次对话或 Anthropic Messages 请求
详见 [`../milestones/M2-local-e2e.md`](../milestones/M2-local-e2e.md)。
后续端到端闭环以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 的 P0-P5 为准。
docs/sk-lifecycle.md
+3 -3
View File
@@ -2,7 +2,7 @@
本文是 Heicode 仓库内 **关于 SK 的唯一权威说明**。其它文档涉及 SK 时请相对链接到本文件，避免规则在多处重复。
> 上游契约出处：[`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) §3.2 / §5.0 / §5.0.1。
> 架构边界出处：[`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md)。
> 名称定义：[`glossary.md#sk（skill-资产）`](./glossary.md)。
---
@@ -107,7 +107,7 @@ Agnet 不需要、也不应该提供针对 SK 正文的 `PUT` / `PATCH`：写操
| 读 SK 快照 | 允许（用于展示） | 允许（运营/审计） | 允许（运行时注入） |
| 列出 SK 绑定关系 | 允许 | 允许 | 允许 |
权限模型在 [`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) §3 中给出 RBAC 角色：
权限模型以后续 P1-P3 的 Resource Grant、Secret Broker 和 Agnet AKS 运行身份实现为准：
- `agnet:credential:write`：用于绑定 Git Token / 云 SA
- `heicode:sk:write`（示例命名）：仅授予 Heicode 客户端身份
@@ -115,7 +115,7 @@ Agnet 不需要、也不应该提供针对 SK 正文的 `PUT` / `PATCH`：写操
## 七、与一键部署的关系
[`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) §5.0 要求 Heicode Manager 提供「一键部署 Agnet 团队」单次操作，部署请求体须显式包含：
Heicode Manager 提供「部署 Agnet 团队」操作时，部署请求或等价 permission manifest 须显式包含：
- 团队成员列表与组织内角色
- 各成员所用模型 / `provider_profile_id`
docs/vision-heicode-full-stack-agentic-dev.md
+3 -3
View File
@@ -6,7 +6,7 @@
| 称谓 | 含义 |
|------|------|
| **Heicode Manager** | 账户、模型与路由策略、计费与渠道等能力的网关及管理控制台。 |
| **Heicode Manager** | SaaS 用户控制台与编排中枢，负责用户、租户、项目、资源绑定、权限分配、Agnet 部署、审计，以及面向普通用户展示模型、余额和调用日志。 |
| **Heicode** | 终端与桌面侧人机编程客户端及本地服务（与 Manager 区分时亦称「Heicode 客户端」）。 |
| **Orchard** | 子智能体编排与团队模板所在平台（概念名）。 |
| **执行单元** | 在编排侧按角色模板实例化的智能体实例。 |
@@ -42,7 +42,7 @@ Heicode 的关切点是：**在多人、多环境、多迭代的条件下，如
### 4.1 身份与策略一元化
使人机在统一身份与组织策略下工作：谁能访问何种模型与渠道、何种环境、何种仓库与密钥——应有清晰归属与审计预期，而不是散落在若干控制台口径不一致。
使人机在统一身份与组织策略下工作：谁能访问何种模型、何种环境、何种仓库与密钥引用——应由 Manager 统一资源与权限语义，并通过 NewAPI、Agnet 与 Secret Store 各自的服务边界执行，而不是散落在若干控制台口径不一致。
### 4.2 编排与角色范式
@@ -72,7 +72,7 @@ Heicode Manager ←→ Heicode 客户端
**边界**：编排平台内部实现细节不属于愿景正文；Heicode 关心的是 **契约、体验与安全边界** 是否说得清、守得住。
**与编排侧（如 Agnet）的可观测分工（方向性）**：平台回传的 **运行态与性能类信息**（是否在跑、健康与资源等）宜在 **Heicode Manager** 上呈现；**子执行单元在会话中的产出内容**宜在 **Heicode** 编码与工作过程中 **实时展示**。团队与个人均可使用两端；划分依据是 **信息类型与载体**，详见 [`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) **§1.1**。
**与编排侧（如 Agnet）的可观测分工（方向性）**：平台回传的 **运行态与性能类信息**（是否在跑、健康与资源等）宜在 **Heicode Manager** 上呈现；**子执行单元在会话中的产出内容**宜在 **Heicode** 编码与工作过程中 **实时展示**。团队与个人均可使用两端；划分依据是 **信息类型与载体**。具体边界以 [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) 为准。
---