8.7 KiB
Agnet 用户部署流程
Deprecated: 本文是早期用户流程草案。2026-05-02 之后，资源绑定、凭证托管、NewAPI 解耦和 Agnet AKS 运行身份以
../saas-manager-agnet-architecture-plan.md为准。本文如与新架构计划冲突，以新架构计划为准。
本文记录 Heicode Manager 中用户从绑定仓库、授权云资源，到部署子 Agnet 的目标流程。它描述产品语义和交互顺序，具体 API 字段以 agnet-platform-api-design.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[]：
{
"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 表单：
- 绑定 Git 来源：选择代码仓库、SK 仓库或二合一仓库，并选择 ref/path。
- 绑定云权限：选择 AWS/Azure/GCP 或单项资源权限，生成可引用的 principal/profile/network policy。
- 定义子 Agnet：为每个角色配置目标、模型、启动
AGENT.md、Git 范围和云权限。 - 配置 SK 策略：选择允许/禁止的 SK，确认继承规则。
- 部署前确认：展示每个子 Agnet 的最终权限摘要。
- 部署后观测：展示快照锚点、运行时绑定、事件和审计。
最低可用版本可以继续使用 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_urlJSON。 - 仓库用途建模：前端需要区分项目仓库、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_planpayload。 - 在最后一步展示只读确认摘要。
第二阶段接入真实平台能力：
- Git 连接真正完成 OAuth/token/SSH key 授权与轮换。
- 云权限真正绑定 AWS/Azure/GCP 身份与单项资源。
- Agnet 平台返回已物化的 Git 快照、运行时绑定与 SK 生效策略。
- Manager 展示平台返回的有效策略，而不是只展示用户提交的原始计划。