docs(agnet): capture user deployment flow
This commit is contained in:
gongzhiyong
+3
-2
@@ -29,8 +29,9 @@
|
||||
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/heicode-oauth-flow.md`](./integration/heicode-oauth-flow.md)：HeiCode 客户端 ↔ Manager 浏览器登录流程
|
||||
6. 落地节奏：[`milestones/README.md`](./milestones/README.md)（M3–M5）+ [`milestones/STATUS.md`](./milestones/STATUS.md)
|
||||
5. [`integration/agnet-user-deployment-flow.md`](./integration/agnet-user-deployment-flow.md)：用户绑定 Git / 云权限到部署子 Agnet 的产品流程
|
||||
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)
|
||||
|
||||
## 关于版本与更新
|
||||
|
||||
|
||||
@@ -20,12 +20,13 @@
|
||||
| 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_sources`、**运行时绑定**、**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)` | 落地节奏与现状 |
|
||||
| 8 | `[./agnet-user-deployment-flow.md](./agnet-user-deployment-flow.md)` | 用户从绑定 Git / 云权限到部署子 Agnet 的产品流程 |
|
||||
| 9 | `[./orchestration-plan-contract.md](./orchestration-plan-contract.md)` | 模型提案对象与平台裁决规则 |
|
||||
| 10 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §6–§7 | 运行态、聚合视图、事件流（双轨） |
|
||||
| 11 | `[./Heicode-登录接口对接文档.md](./Heicode-登录接口对接文档.md)` | 已上线认证接口契约（login / me / refresh / logout） |
|
||||
| 12 | `[./heicode-oauth-flow.md](./heicode-oauth-flow.md)` | 客户端浏览器登录到 Manager 的完整流程 |
|
||||
| 13 | `[./acceptance-matrix.md](./acceptance-matrix.md)` | 集成验收最小测试矩阵 |
|
||||
| 14 | `[../milestones/README.md](../milestones/README.md)` + `[../milestones/STATUS.md](../milestones/STATUS.md)` | 落地节奏与现状 |
|
||||
|
||||
|
||||
## 边界速览
|
||||
@@ -59,4 +60,4 @@ API 设计中的章节与里程碑的对应：
|
||||
- **「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-platform-api-design.md](./agnet-platform-api-design.md)` §10
|
||||
|
||||
@@ -0,0 +1,158 @@
|
||||
# Agnet 用户部署流程
|
||||
|
||||
本文记录 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 展示平台返回的有效策略，而不是只展示用户提交的原始计划。
|
||||
Reference in New Issue
Block a user