heicode-mananger/docs/integration/heicode-sub-mode-flow-spec.md

Heicode Sub 模式 端到端流程与三端规范（v0.1 草案）

2026-06-03 产物模型钉死（最重要的认知）：

• sub 模式强制绑定 git 才能用（未绑 git 只能走客户端本地模式，进不了 sub）。
• 最终产物只存在于用户自己的 git 仓库。没有"下载产物"这回事——不存在 project_folder / manifest / files / archive zip / local-edits 回传这一整套（已全部退役）。要代码就 git clone/pull。
• 运行期间 HM 流式给客户端的，只有"运行信息"：日志（user_logs/debug_logs）、状态（display_status + 三层状态）、work 视图杂项（每个 agent 在做什么、跑了什么工具、改了哪些文件、阶段进度、测试输出等）。这些是给人看的过程信息，不是可下载交付物。
• HM 眼里的 "artifact" 退化成交付/完成记录（带 git_ref、改了哪些文件、source_agent_role 等元数据），仅用于 ① display_status 的"有无真交付"防空壳核对、② 在 work 视图里展示；客户端不从 HM 下载任何产物文件。

更新时间：2026-06-03（产物模型对齐）/ 2026-06-02（初稿） 范围：Sub（普通子代理协作）模式——桌面客户端（一个像 Claude Code 的智能体程序）把一个多 agent 重活外包到云端 agent_management：客户端发起 → 经 Heicode Manager（模型网关 + 控制面）→ agent_management 多 agent 并行执行 → 流式回客户端展示的完整闭环，含资源绑定、git 仓库、产物合并、修改/重做、部署。 前提认知（务必先读 §0）：客户端本身能本地跑 agent；sub 模式是把大任务派到云端,不是客户端唯一的干活方式；模型统一由 HM 的 /v1/* 提供给客户端和 AM 两边。 目的：统筹三端（桌面客户端 / Heicode Manager / agent_management）的颗粒度与理解，作为三方共同对齐的权威流程文档与契约规范。 性质：本文是目标设计 + 现状标注。每节用标记区分：

• 🟢 已实现（当前代码/线上已具备）
• 🟡 部分实现（有基础，缺字段/流式/打通）
• 🔴 待建（目标态，尚未实现）
• ❓ 待决策（需产品/三端确认的设计点，附我的建议）

相关文档：客户端对接接口见 heicode-desktop-unified-api.md；runtime 契约见 agent_management《Sub Mode Runtime 对接指南》。

---

0. 术语与三端角色（先把名字钉死，避免歧义）

⚠️ 名字钉死：本文用 HM = Heicode Manager（那个 Go 网关），用 AM = agent_management（就是你口中的「Agent Manager / Sub Mode Runtime」）。两者完全是两个不同的服务，本文不再用模糊的「Manager」一词。三方按下表对号入座。

简称	全名	是什么	栈
客户端	桌面客户端 cc-haha / Desktop	像 Claude Code 那样的智能体编程程序:本地自己能跑 agent、写代码、执行命令。用模型时调 HM 的模型接口	TS（Tauri+React/CLI）
HM	Heicode Manager	① 模型调用网关（new-api）——给「客户端」和「AM」两边都提供模型调用接口 /v1/*（鉴权/计费/路由都在这）；② 控制面 / 状态裁判 / 凭据中介。HM 自己不跑 agent、不执行命令、不连 VM	Go(Gin/GORM)
AM	agent_management（= 你说的 Agent Manager / Sub Mode Runtime,在 20.212.121.126）	云端多 agent 运行时:把任务拆成多 agent 并行干活、写代码、git 入库；这些 agent 也是调 HM 的模型接口 /v1/* 来用模型	独立服务

「AI」从哪来：AI = 模型。模型统一由 HM 的 /v1/* 提供。智能体执行（跑 agent）发生在两处：本地（桌面客户端,像 Claude Code）和云端（AM,sub 模式多 agent）。两边都通过 HM 调模型。HM 是大家共用的模型网关,自己不当 agent。

0.1 关键能力边界（谁跑 agent / 谁提供模型 / 谁执行命令）

能力	客户端	HM	AM
智能体程序 / 跑 agent	✅ 本地跑（像 Claude Code）	❌ 不跑 agent	✅ 云端跑多 agent
提供模型调用接口 /v1/*	❌（是调用方）	✅ 是模型网关,给客户端和 AM 都提供	❌（是调用方）
调模型	✅ 调 HM /v1/*	—（被调方）	✅ 调 HM /v1/*
本地执行命令 / 部署 / 看 VM 日志	✅ 在用户机器上执行（像 Claude Code）	❌ 从不执行、不连 VM	❌（AM 在自己沙箱产代码,不部署用户 VM）
解密验签 / 鉴权 / 计费	❌	✅	❌
裁决 display_status	❌	✅ 唯一裁判	❌（只报执行事实）
托管凭据（KV）/ 发短期凭据	❌	✅	❌

澄清几个之前易错的点：

• HM 不部署、不执行命令、不连 VM、不看 VM 日志——它是模型网关 + 控制面,不是执行器。
• 部署到用户 VM + 在 VM 看日志 = 客户端自己在用户机器上干（像 Claude Code 本地执行；用户确认后 HM 只把短期凭据加密发给客户端）。
• sub 模式 = 把多 agent 任务派到云端 AM 跑（区别于客户端本地自己跑一个小任务）；AM 的 agent 调 HM 用模型,流式回 HM,HM 裁决后回客户端。

0.2 sub 模式是什么、什么时候用（既然客户端本地就能跑 agent）

关键澄清：客户端本身能在本地跑智能体（像 Claude Code）完成小/快任务。那为什么还要 sub？

• 本地模式（客户端自己）：在用户机器上跑单个/轻量 agent，适合小改动、即时、交互式。计算在用户机器上。
• sub 模式（本文主题）：客户端把一个**更大的、需要多 agent 并行协作、或希望云端异步跑（关掉电脑也继续）**的任务，派发到云端 AM 执行。计算在云端 AM，多 agent 并行（backend/frontend/reviewer 同时干）。
• 两种模式的模型都走 HM /v1/*，鉴权 + 计费统一在 HM。
• sub 模式下客户端的角色 = 发起任务 + 实时看 work + 本地看/改产物 + 本地执行部署；真正的 codegen 多 agent 在云端 AM。客户端不在 sub 模式里本地跑 codegen agent（那是本地模式）。

一句话：sub = 把多 agent 重活外包到云端 AM；客户端当指挥台 + 取货 + 本地部署。本地模式 = 客户端自己干小活。模型两边都问 HM 要。

0.3 三端铁律

1. 客户端任务/控制走 HM（/api/heicode/*、/api/agent/*），模型走 HM（/v1/*），禁止直连 AM / Runtime artifact。
2. HM 是唯一状态裁判，客户端只消费 display_status（定义见 §6）。
3. 凭据只进 Azure Key Vault，全链路只传/存 secret_ref，明文绝不落库/日志/回调。
4. HM 不执行任何命令、不部署、不连 VM、不跑 agent；agent 执行在云端 AM（sub 任务期）或客户端本地（本地模式 / 部署期）。模型由 HM 提供给两边。

---

1. 端到端总体流程（时序）

┌── 桌面客户端 ──┐        ┌──── Heicode Manager ────┐        ┌── agent_management ──┐
│                │        │                          │        │                      │
│ 0 选 sub 模式  │        │                          │        │                      │
│ 0.5 (可选)绑 git/vm/db ─┼─► 资源绑定→Key Vault     │        │                      │
│                │  V2加密 │  存 secret_ref           │        │                      │
│ 1 填需求包 ────┼───────►│ 2 解密+验签+鉴权+配额    │        │                      │
│                │        │ 3 需求包→orchestration   ├──────► │ 4 拆分多 agent       │
│                │        │   _plan + 注入资源授权    │  HMAC  │   分配角色/模型       │
│                │        │                          │        │ 5 各 agent 干活：     │
│                │        │                          │ ◄──────┤   流式回调状态/日志/  │
│ 7 轮询/订阅 ◄──┼────────┤ 6 收敛三层状态+运行信息  │ callback│  状态/日志/work +     │
│  展示 work(只有 │        │   裁决 display_status     │        │  git 入库 + push     │
│  日志/状态/work)│        │   (只转发运行信息)        │        │ 8 各 agent 代码→分支  │
│                │        │                          │        │ 9 合并→交付分支(git)  │
│ 10 看产物 ─────┼──git──► (直接 git clone/pull 用户  │ ◄──────┤  push 用户仓库 +      │
│   只走 git      │         自己的仓库; 不经 HM)      │ git_ref │  回调 git_ref 通知 HM │
│ 11 不满意 ─────┼───────►│ /messages | /execute     ├──────► │ 12 修改/重做(git)     │
│                │        │                          │        │                      │
│ 13 本地 git    │ ◄─git──  (pull/改/push, 不经 HM)  │        │                      │
│ 14 部署 VM ────┼───────►│ 取凭据(加密) → 客户端执行│        │                      │
└────────────────┘        └──────────────────────────┘        └──────────────────────┘

---

2. 三端颗粒度契约（一图看清谁给谁什么）

表头里 HM = Heicode Manager，AM = agent_management。

数据/动作	客户端 → HM	HM → AM	AM → HM（回调）	HM → 客户端
建任务	需求包（objective/context/约束/验收/模型选择/角色）	orchestration_plan + 资源授权 grants	deployment_id/swarm_id	deployment_id(=task_id) + display_status
运行状态	—	—	status+runtime_execution_status+phase	display_status（裁决后）
日志/work	—	—	事件流（task./agent./phase./handoff./artifact.）	user_logs+debug_logs / work 视图（只有运行信息）
每 agent 指标	—	—	🔴 per-agent tokens/tools/elapsed	workflow.agents[].*
代码产物	—	—	git push + 回调 git_ref（commit/分支/改了哪些文件 + source_agent_role，仅元数据）	git_ref（让客户端去 git pull）——HM 不提供产物文件下载
修改/重做	message / execute	续跑/重做指令	新 commit + git_ref + 状态	新 display_status + 新 git_ref
凭据	只传 resource_binding_id	注入 secret_ref（azkv://）	—	只回 secret_ref（打码）

⚠️ 上表只画了「任务控制面」。还有一条独立的并行通道——模型调用：

• 客户端 → HM /v1/*（客户端本地 agent 用模型）
• AM → HM /v1/*（AM 的 agent 用模型） 两边用同一套模型接口,HM 统一做鉴权 + 计费 + 路由。模型调用与上面的任务控制面是两条不同的通道,别混在一起。

---

3. 阶段详解

3.0 完整执行流程（逐步，明确每一步谁做什么）

全程三个主体：客户端（像 Claude Code 的智能体程序）、HM（模型网关 + 控制面，不跑 agent、不执行命令）、AM（云端多 agent 运行时）。客户端和 AM 的 agent 用模型时都调 HM 的 /v1/*。

A. 准备（一次性）

1. 用户在客户端绑定自己的 git 仓库（github/gitea URL + 一个 PAT）。客户端经 V2 加密把 PAT 发给 HM → HM 把 PAT 写进 Key Vault，库里只留 secret_ref，返回一个 resource_binding_id。
2. （需要部署时）同样绑定 VM（host + ssh key）、数据库、blob，凭据进 KV，各得一个 resource_binding_id。

B. 发起任务 3. 用户在客户端选 sub 模式、填需求包（目标/约束/验收/角色/模型/要用哪条 resource_binding_id）。 4. 客户端 → POST /api/heicode/sub-agile/tasks（V2 加密 body + 设备签名）。 5. HM：解密 → 验签 → 鉴权 → 查配额 → 把需求包译成 orchestration_plan，从 KV 取出 git 凭据注入（短期 token），落库，返回 deployment_id（= task_id）。HM 不写代码、不跑 agent。

C. 执行（AM 干活，HM 中转） 6. HM → POST /api/agent/sub-agile/deployments（给 AM），带：需求、角色/模型、回调地址、HMAC 签名密钥、git 仓库 + 短期凭据。 7. AM：把需求拆成多个 agent（如 backend / frontend / reviewer），各自分配模型，开始干活。每个 agent 用模型时调 HM 的 /v1/*（和桌面客户端用同一套模型接口）。 8. AM 的每个 agent：clone 用户仓库 → 在自己分支（agent/<role>）写代码、跑工具/测试（调 HM /v1/* 用模型）→ commit & push 到用户仓库（用第 5/6 步注入的短期 PAT）。 9. AM 持续把「每个 agent 在做什么 / 跑了什么工具 / 改了哪些文件 / 当前阶段 / 产物」流式回调给 HM（HMAC 签名）：POST /api/agent/callbacks/runtime-events。 10. HM 收回调 → 聚合事件 + 裁决 display_status（见 §6）+ 持久化。

D. 客户端看 work 11. 客户端轮询 GET .../tasks/{id}/workflow（运行中 3–5s；将来 SSE）→ 拿 display_status + 各 agent 状态/动作 + 阶段 + 产物列表，渲染成「work 视图」（参考 Claude Code）。

E. 合并与产物 12. AM 阶段结束 → 把各 agent 分支合并成一个交付分支（delivery/<task_id> 或 PR）→ push 到用户仓库 → 回调通知 HM 产物就绪（带 git_ref + artifact）。 13. 客户端看产物：直接 git clone/pull 用户自己的仓库（完整工程 + 历史 + diff）。只此一条路——产物在 git，HM 不托管/不打包/不提供产物文件下载；HM 给的只是 git_ref（告诉客户端去哪个仓库/分支/commit pull）。

F. 不满意 → 改 / 重做 14. 客户端 → POST .../messages（追加要求）或 .../execute（重跑）→ HM 取最新 accepted 基线转给 AM → AM 在原产物上改/重做 → 回到第 9 步。

G. 部署（客户端执行 + 用户确认；HM 只发凭据） 15. 客户端发起部署 → 弹窗让用户确认（目标 VM / 环境 / 用哪条 binding / 影响）。 16. 用户确认 → 客户端向 HM 换短期凭据租约（HM 从 KV 解出 VM ssh key，经 V2 加密发回客户端，带 TTL）。 17. 客户端在用户自己机器上执行部署：git pull 用户仓库 → ssh 到 VM → 跑部署命令 → 在 VM 上看日志。HM 全程不碰 VM、不执行命令、不看日志；HM 只记审计（谁、哪条 binding、何时、TTL）。

一句话区分执行位:写代码 = AM 沙箱里执行;部署到用户 VM + 看 VM 日志 = 客户端在用户机器上执行;HM 永远只做网关/裁判/凭据中介,不执行任何东西。

---

3.1 选择 sub + 准备（资源绑定前置）

🟢 客户端选 mode=sub_agile（区别于 swarm）。 ✅ 决策（2026-06-02）：git 仓库 = 用户绑定自己的仓库（gitea / github，用户提供 URL）。没有 Heicode 托管仓库。 ✅ 决策（2026-06-03）：sub 模式强制绑定 git——未绑仓库则不能进 sub（UI 上禁用 sub，引导用户先绑 git 或改用客户端本地模式）。不再有"未绑仓库走仅产物轻量路径"这种东西（project_folder/manifest/files/archive 已退役）。代码产物的唯一归宿就是用户绑定的 git 仓库（§4.1）：agent 在此入库/合并，客户端 git clone/pull 看产物。

3.2 客户端 → HM（加密 + 鉴权 + 建任务）

🟢 加密链路：与模型调用完全一致。

• 写请求（POST/PUT/DELETE）：Content-Encoding: heicode-aead-v1，X25519-ECDH + HKDF + ChaCha20-Poly1305 加密 body，Ed25519 设备签名（X-Heicode-*）。
• GET：无 body 设备签名（同 canonical，body 哈希为空串哈希）。
• HM 中间件 UserOrV2DeviceAuth 解密 + 验签 + 从设备绑定 token 解析用户身份。

🟢 鉴权/配额：解析 user_id、绑定 scope、计费上下文。 🟢 建任务：POST /api/heicode/sub-agile/tasks，body = 需求包（见客户端接口文档 §3.1），HM 译成 orchestration_plan 并落库，返回 deployment_id（= task_id）。

3.3 HM → agent_management（分发）

🟢 POST /api/agent/sub-agile/deployments（env 当前指向 http://20.212.121.126），Bearer service token。 🟢 注入：callback URL（/api/agent/callbacks/runtime-events）+ HMAC 签名密钥引用 + metadata.manager_deployment_id + 角色/模型 + 资源授权 grants（secret_ref，不含明文）。 🟡 回调竞态：AM 回调可能早于 HM 存 runtime_id → HM 用「读时收敛」(reconcileDeploymentFromRuntime) 兜底（已实现）。

3.4 多 agent 执行 + 流式回传（work 视图，参考 Claude Code）

🟡 现状：AM 通过回调上报 deployment.status_changed / task.* / handoff.* / artifact.created / phase.changed 等事件；HM 聚合成 timeline/events/logs；客户端轮询展示。 🔴 目标（work 视图）：像 Claude Code 的 work 面板那样实时流式展示「每个 agent 正在做什么、跑了哪些工具、产了哪些文件、各阶段进度」。需要补：

1. 🔴 流式协议：HM 提供 GET .../tasks/{id}/events/stream（SSE）或 WS，把 AM 回调实时转发给客户端。现状无 SSE，客户端轮询 /workflow（3–5s）兜底（见 §5）。
2. 🔴 per-agent 富字段：AM 在状态/回调里上报每个 agent 的 tokens / tools(工具调用数) / elapsed_seconds / 当前动作描述 / artifact_ids。HM 的 /workflow 已预留这些字段（缺值时为 0/空），等 AM 填。
3. 🔴 artifact 来源角色：AM 给 artifact 打 source_agent_role，HM 才能把产物准确归到对应 agent。
4. 🔴 阶段细分：runtime 上报 phases[]（每阶段 status/agents），而非单个 phase 字符串。

work 视图的最小可用版（不等 SSE）：客户端轮询 /workflow 拿 agents[] + phases[] + metrics，3–5s 刷新即可先跑起来；SSE 是体验升级项。

3.5 代码入 git + 多 agent 产物合并

🔴 目标：每个 agent 把自己产的代码 commit 到 git 仓库的独立分支（如 agent/backend、agent/frontend），最后 合并成一个完整产物（merge 到 main 或一个交付分支）。

❓ 关键决策（§7 详述）：

• 仓库在哪？（Heicode 托管 vs 用户绑定的 git）
• 谁负责合并？（agent_management 合并后给一个最终分支/commit；HM 不碰 git 操作，只记录引用）
• 合并策略？（按目录隔离自然无冲突：backend/ + frontend/ 并列；同文件冲突由一个「集成 agent」或规则解决）

🟡 现状：sub 模式 AM 当前还是把产物当 blob/文本 artifact 回传（每角色一个，多角色=多个），尚未真正 git 入库 + 合并——这是待迁移的旧实现，不是目标态。目标态（本节）是 AM 全程在用户 git 仓库里 commit/合并，产物只在 git。客户端不再"拼 manifest 展示产物"。

3.6 产物查看（只走 git）

🔴 唯一路径 = git：sub 完成后客户端直接 git clone/pull 用户自己绑定的仓库，看完整工程 + 提交历史 + diff。HM 给的只是 git_ref（repo/branch/commit），告诉客户端去哪 pull。

退役：旧的「经 HM 看产物」（/artifacts→/manifest→/files?path=→/archive）是无 git 流程的残留，sub 强制 git 后不再使用。HM 在运行期只向客户端流式推运行信息（日志/状态/work，见 §5），不提供产物文件的浏览或下载。HM 的 /artifacts 接口若保留，只列非代码的运行信息记录（如 test_report 测试报告、摘要），供 work 视图展示，不是可下载交付物。

3.7 不满意 → 修改 / 重做（两条路：云端改 或 本地改）

因为客户端本身是智能体程序（像 Claude Code），迭代有两条等价路径,用户按场景选：

基线就是 git：两条路都以用户仓库的最新提交为唯一基线，不存在 HM 侧的 local-edits/revision 回传机制（已退役）。本地改完 git push，云端续跑前 git pull，冲突/历史/diff 全交给 git。

路径 A — 回云端 AM 改（继续 sub）

• 🟡 修改（续跑）：POST .../tasks/{id}/messages（追加要求）→ HM 转给 AM → AM 先 git pull 取用户仓库最新提交作基线 → 在其上改 → 再 push。（AM 真正「中途续跑」🔴待支持）
• 🔴 重做：POST .../tasks/{id}/execute（或新增 /redo）→ AM 在新分支上重新生成（旧交付分支保留可对比）。需 AM 支持「redo」语义。

路径 B — 拉到本地用客户端自己的 agent 改（回到本地模式）

• 🟢/🔴 客户端 git pull 用户仓库 → 用客户端本地 agent（像 Claude Code，模型仍走 HM /v1/*）在本地改 → git push 回仓库。不必每次回云端，适合小修小补。
• 改完想让云端接力：直接 push 后再 /messages，AM git pull 自然拿到本地改动——无需任何 HM 回传接口。

3.8 部署（✅ 必须客户端执行 + 必须用户确认）

✅ 决策（2026-06-02）：部署绝对走客户端,且必须用户显式确认才执行。HM 不自动部署、AM 不自动部署。

• 流程：客户端发起部署 → 弹用户确认(目标/环境/影响) → 用户确认 → 客户端向 HM 的加密密钥接口换取短期凭据租约(VM SSH key / git PAT 等从 KV 解出,经 V2 加密通道回客户端,带 TTL) → 客户端本地执行(git pull 用户仓库 → push/部署到 VM,或连库迁移)。
• HM 角色:只发短期凭据 + 记审计(谁、哪条 binding、何时、TTL),不代执行。
• 凭据租约:短 TTL、可吊销、用完即弃;高危目标(如生产)可叠加审批门(waiting_approval)后再发租约。 🟡 现状:有云部署控制面占位(/deployments,返回 executor:pending_worker);凭据租约模型(approval→lease)有骨架。🔴 待建:客户端取凭据的加密接口 + 客户端本地执行器。

---

4. 资源绑定规范（git / vm / database / blob → Key Vault）

🔴 前置硬卡点：Azure Key Vault 当前托管身份取 token 400、不可达。资源绑定的核心是「凭据进 KV、只存 secret_ref」，KV 不通则整个功能不可用。必须先由运维给 VM 托管身份在目标 KV 授 Key Vault Secrets Officer 角色（Phase 0）。

4.0 通用模型

每个资源绑定 = { resource_binding_id, type, name, metadata(非敏感), secret_ref(azkv://…), permission_scope, binding_scope(租户/工作区), status }。

• 客户端只传 resource_binding_id 给任务；HM 内部解析为凭据注入 AM。
• 客户端禁止 inline secret_ref / AccessKey / 连接串。
• 凭据录入一次性：客户端经 V2 加密通道把凭据传给 HM → HM 写 KV → 库里只留 azkv://。

4.1 Git 仓库绑定 ✅（已定方向）

模型：用户绑定自己的仓库（gitea / github，用户提供 URL）。agent 在此仓库读写代码、git 入库、合并；客户端 clone/pull 看产物；后续从此仓库 git 到 VM 部署。

项	方案（已定 / 建议）
仓库归属	✅ 用户自己的仓库。用户提供 repo_url（github.com/... 或自建 gitea URL）。无 Heicode 托管仓库。
绑定鉴权（用户输入密钥）	✅ HTTPS + 细粒度 PAT（个人访问令牌）为主——github 与 gitea 通用、用户只需粘贴一个 token、可按仓库范围授权、可随时吊销、不暴露账号密码。流程：用户在自己 git 生成范围化 PAT（建议 repo 读写）→ 客户端经 V2 加密通道把 PAT 传 HM → HM 写 KV，库里只留 secret_ref。备选：SSH deploy key（用户把 HM 出示的公钥加到仓库 Deploy keys；适合不愿发 PAT 的场景）。
provider 识别	由 repo_url 推断（github.com → github API；其他 → gitea，需带 api_base）。metadata：provider / repo_url / default_branch / api_base?。
绑定粒度	单仓库级（一个 binding = 一个 repo + 默认分支 + 允许路径 allowed_paths）。permission_scope：repo:read / repo:write。
凭据有效性/过期	PAT 会过期/被吊销 → HM 在用前预检（一次 GET repo），失效则标记 binding status=invalid 并提示用户重新绑定，不静默失败。
工单 / 里程碑	可选增强（默认关，用户显式开）：把 sub 子任务映射为 issues、阶段映射为 milestone、handoff/审批映射为 issue 评论，让用户在自己 git 看板跟踪 agent 进度。需要 PAT 额外授 issues 权限。
分支模型 / 合并	见 §7。

4.2 VM 连接绑定 🔴

type=vm，metadata：host/port/user/连接方式（ssh key / 密码）；secret 进 KV。用于部署/运维。高危,建议绑定时声明用途 + 部署需审批。

4.3 数据库绑定 🔴

type=database，metadata：引擎/host/port/db 名；连接串/密码进 KV。用于 agent 生成需要连库的代码或迁移。

4.4 Blob 存储绑定 🔴

type=blob，metadata：账号/容器；key/SAS 进 KV。用于大产物/数据集存取。

4.5 凭据生命周期

• 录入 → KV（HM 写）→ 只存 secret_ref。
• 使用 → 任务/部署时 HM 从 KV 解出注入 AM，或发短期租约（TTL + 可吊销）给客户端。
• 审计 → 谁在什么 scope 用了哪条绑定、发了哪些租约、何时吊销（只记 secret_ref + 打码摘要）。

---

5. 流式协议规范（work 视图）

阶段	协议	状态
现状	客户端轮询 GET .../workflow（运行中 3–5s、终态 15–30s）	🟢
目标	GET .../tasks/{id}/events/stream（SSE）：HM 把 AM 回调实时转发；事件含 agent.action / tool.call / phase.changed / log.line / delivery.pushed（产物就绪=带 git_ref 的通知，不是文件）	🔴

规范：

• SSE event 统一信封：{ event_type, deployment_id, agent_id?, phase?, occurred_at, payload }。
• 客户端断线重连用 Last-Event-ID（基于 HM 的事件游标）。
• 降级：SSE 不可用时自动回落轮询，UI 行为一致（只是延迟）。
• 客户端不要订阅不存在的流（未上线前 /events/stream 返回未实现，别硬连）。

---

6. 状态模型与 display_status 裁决（完整定义，给三方）

🟢 已实现。这是全文最关键的概念之一,三方必须一致理解。

6.1 HM 只做"事实透传 + 防空壳",不判断代码对错

• AM 只上报执行事实(completed 只代表"我跑完了")。
• HM 没 AI、不读代码、不跑代码、不编译、不测试。 所以 HM 不判断"代码对不对、有没有效"——那不是 HM 能做、也不该做的事。
• HM 的 display_status 只做两件事:① 忠实透传 AM 的执行状态;② 防"空壳/兜底假成功"——AM 说 completed 时,HM 顺手核对一下"到底有没有产物"(这是事实层面的核对:有/无、是不是兜底占位,不是质量判断)。
• 真正"对不对、有没有效"由客户端 + 用户判断(见 §6.6):客户端是 Claude-Code 式程序,能把产物/git 拉下来自己跑、自己测、看 diff,用户 review 拍板。
• 客户端只看 display_status 决定**"这轮跑完了没、是不是空交付";"代码好不好"客户端自己看产物。**

6.2 三层状态（GET .../tasks/{id}/workflow 同时返回）

字段	含义	谁产生
cloud_deployment_status	HM 控制面状态（accepted/running/stopped…）	HM
runtime_execution_status	AM 上报的原始执行状态（AM 说它自己到哪了）	AM
display_status	HM 裁决后、给用户展示的唯一状态	HM

6.3 display_status 的全部取值（枚举）

值	含义	客户端该怎么展示
accepted	已受理,排队中	进行中（灰/黄）
running	正在执行	进行中（蓝，转圈）
waiting_approval	等用户审批高风险操作	黄，弹审批
completed	完成,且有真实可交付的代码产物	绿,成功
needs_codegen	AM 说完成了,但只产了方案/总结、没有真实代码 → 需继续生成	黄,提示"需补充代码/继续"
completed_without_deliverable	AM 说完成了,但完全没有产物	红/橙,视为没成功
failed	执行失败	红,失败
stopped	被用户/系统停止	灰,已停止

6.4 裁决算法（HM 收到 AM 状态后怎么算 display_status）

输入: AM 的 runtime_status, 该任务的 artifacts 列表
规则:
  if runtime_status 不是 "completed":
        display_status = runtime_status 原样透传
        (running / waiting_approval / failed / stopped / accepted ...)
  else  # AM 说 completed,进入"是否真有交付物"的裁决
        遍历该任务的 artifacts:
          只要存在 1 个"真实交付物"        → display_status = "completed"   ✅
        否则 if 有 artifacts 但全是总结/兜底  → display_status = "needs_codegen"
        否则 (一个 artifact 都没有)          → display_status = "completed_without_deliverable"

"真实交付物"的判定(逐条排除"假产物"):AM 回报的交付记录满足以下才算真实——

• 目标态(git):回调带 git_ref(repo/branch/commit_sha)且有真实提交(commit 数 > 0 / 改了 N 个文件) → 真交付。HM 据此判"有没有真东西",不下载、不读代码内容。
• metadata.synthesized != true(不是 AM 的兜底占位记录),且
• 不是纯总结类(标题/正文不含 "runtime execution summary"、"without per-agent artifacts" 等兜底标记;不是 document/summary 类)。
• 兼容旧实现:在 AM 尚未 git 化前,带"改了 N 个文件"结构化信号的 code_patch/diff 记录也按真交付算(过渡期)。

注意:HM 判的是**"有没有真提交"这个事实**(防空壳),不是判代码对不对(§6.6)。git_ref 是元数据,不是可下载产物。

一句话:completed 必须"AM 说完成 + 真的有代码产物"两个条件都满足;只有总结没代码 = needs_codegen;啥都没有 = completed_without_deliverable。客户端据此就能准确区分成败,不会被假成功骗到。

6.5 成功判据（客户端用）

display_status == "completed" 且 artifacts 非空 = 真成功;其余都不是成功(各有不同处理)。

6.6 ⚠️ "对不对/有没有效"归谁判 —— 客户端 + 用户,不是 HM（三方必读）

谁	判什么	怎么判
HM	只判事实:这轮跑完没?有没有产物?是不是空壳/兜底?	看 AM 状态 + artifact 有无（不读代码、不编译、不测试、不判对错）
客户端（Claude-Code 式）	判代码对不对、能不能跑、是不是要的	把产物/git 拉到本地,自己跑、自己测、看 diff;有问题就本地改或回云端改
用户	终裁:满不满意、收不收货	在客户端 review 产物,满意才算真完;不满意 → 改/重做（§3.7）

直接回答你的问题:

• HM 不需要、也不该编译/测试/判断代码真伪——那不合理。HM 是网关,没 AI。
• 完成后是对是错,客户端当然知道:它是智能体程序,把代码拉下来一跑一测就清楚,用户也会 review。这才是判"有效"的地方。
• HM 的 display_status 顶多帮客户端省一步:告诉它"这轮跑完了 / 是不是空交付",避免把一个空壳当成功;但**"代码好不好"绝不由 HM 判**。

关于测试/编译(纠正我之前的错误说法):

• 跑测试/编译是 AM 在自己沙箱里做(任务执行的一部分),或客户端在本地做。
• 若 AM 跑了测试,测试结果就是一个产物(test_report artifact)给客户端看——不是回传给 HM 去"裁决"。HM 不参与对错判断。

---

7. Git 仓库与分支 / 合并模型 ❓

目标流程：

任务开始 → 建/选仓库 → 拉基线分支 base
每个 agent → 自己分支 agent/<role> → 多次 commit（流式可见 diff）
阶段结束 → 集成：合并各 agent 分支 → 交付分支 delivery/<task_id>（或 main）
完成 → 交付分支即「完整产物」；客户端 clone/pull 看；不满意 → 在交付分支上续跑/重做

决策点：

点	方案（已定 / 建议）
仓库归属	✅ 用户绑定的仓库（github/gitea，用户给 URL）。无托管仓库。
谁执行 git	✅ agent_management 执行所有 git 操作（clone 用户仓库、各 agent commit 到分支、合并到交付分支、push）——用 HM 注入的短期 PAT（从 KV 解出，最小权限）。HM 只记录引用（repo_url/branch/commit_sha）并在 artifact metadata 带 git_ref，不做 git。
提交身份	agent 提交用一个明确的 bot 身份（如 heicode-agent <bot@heicode>）+ commit message 带任务/agent/角色标注,便于用户在 git 历史里分辨人/机改动。
合并冲突	目录隔离（backend/、frontend/ 并列）天然无冲突；同文件冲突由「集成 agent」或规则化合并解决，无法自动解则上报 needs_codegen 让用户介入/再跑一轮。
写入方式	❓建议：agent 不直接 push 到用户的 main,而是 push 到 delivery/<task_id> 或开 PR,由用户在自己 git 上 review/merge → 既安全又复用用户的 PR/CI 工作流。是否强制 PR 模式待定。
客户端看产物	只走 git：直接对用户自己的仓库 git clone/pull。HM 不提供 /archive 等产物下载（已退役）。

---

8. 决策点（部分已定，2026-06-02）

#	决策	结论
1	git 归属	✅ 用户绑自己的仓库(github/gitea,给 URL),无托管仓库
2	git 鉴权	✅ HTTPS + 细粒度 PAT 为主(github/gitea 通用、用户粘贴 token)、SSH deploy key 备选
3	部署	✅ 必须客户端执行 + 必须用户确认;HM 只发短期凭据 + 记审计
4	git 执行方	✅ agent_management 执行 git(用注入的短期 PAT),HM 只记引用
5	工单/里程碑	可选增强,默认关 —— ❓ 是否纳入 v1?
6	流式	v1 先轮询 work、SSE 放 v1.1 —— ❓ 接受?
7	写入方式	❓ agent 是 push 到 delivery/<task_id> 分支 / 开 PR,还是直接进 main? 建议 PR/分支模式
8	未绑仓库	✅ 未绑 git 则禁用 sub(强制绑 git)。不再有"仅产物"轻量路径;产物只在 git,无 project_folder/manifest/archive/local-edits

---

9. 更多需要考虑的细节（我补充的，超出已提问题）

这些是我认为必须在 v1 前定清的边界/细节,大多附我的建议,标 ❓ 的需你拍板。

9.1 仓库与代码库状态

• 空仓库 vs 已有代码：agent 是在已有代码库上增量改,还是绿地新建? 建议 binding 时声明 mode: greenfield | existing;existing 时 agent 先读现有结构再改,且只动 allowed_paths 内的文件。
• 多仓库任务：一个任务是否可能跨多个仓库(前端仓 + 后端仓)? 建议 v1 单仓库,多仓库 v2。
• monorepo / 子目录：用 allowed_paths 限定 agent 工作目录,避免动到无关代码。
• 大文件 / LFS：是否支持 git-lfs? v1 可不支持,但要拒绝把大二进制/数据集塞进 git(走 blob 绑定)。
• .gitignore + 防止误提交密钥：agent 绝不能把任何凭据/secret_ref/.env 提交进仓库;runtime 侧需有 secret 扫描,提交前拦截。

9.2 凭据与安全

• PAT 最小权限 + 短时效：注入 AM 的 PAT 应尽量是短期/单仓库范围;若用户给的是长期 PAT,HM 至少做范围校验并提醒。
• 凭据只在内存：AM 用完 PAT 不落盘、不进日志;HM 注入走加密。
• scope 隔离：一条 binding 的凭据只能被该用户(binding_scope)的任务使用,跨用户禁用。
• 审计：每次「解 KV、注入 AM、发客户端租约」都留审计(user / binding / 用途 / 时间 / TTL),明文不入审计。
• 吊销：用户删 binding 或吊销租约后,进行中的任务该如何? 建议:已注入的短期凭据自然过期,新操作立即失效。

9.3 任务执行与失败

• 预算/配额：每任务 token/时长/成本上限;跑超预算时如何? 建议:到上限暂停 + 标 needs_codegen/budget_exceeded,让用户决定续不续,不静默烧钱。
• 中途停止(stop)：停止时已 commit 的代码保留在分支(不回滚),任务标 stopped;用户可在该分支续跑或丢弃。
• agent 崩溃 / 部分失败：多 agent 里某个失败 → 整体 completed_without_deliverable/部分交付? 建议:HM 裁决时若有 agent 失败但有有效产物,仍可 completed 但带 warning;全失败则 failed。
• 幂等：同一需求重复提交(网络重试)用 X-Idempotency-Key 去重,避免建重复任务/重复 git 分支。
• 超时：AM 长时间无回调 → HM 标 stale/超时,客户端可见。

9.4 产物与验收

• 验收标准如何验证：需求包里的 acceptance_criteria 谁来验? 建议:AM 跑测试(若有)并把测试结果作为 test_report 产物给客户端;客户端 + 用户据此判对错(不经 HM 裁决,§6.6)。
• 产物版本/标签：每次交付打 tag(delivery-<task>-rev<N>)或记 commit_sha,便于回溯 + 部署指定版本。
• 修改 vs 重做的边界：/messages(在现有产物上改)与 /redo(重新生成)语义要清晰;redo 是否丢弃旧分支? 建议:redo 开新分支,旧的保留可对比。

9.5 协作与团队

• 谁能看/操作一个任务：binding_scope = 租户/工作区;同 scope 内成员可见,跨 scope 禁。
• 并发任务同仓库：两个任务同时改一个 repo → 用不同 delivery/<task_id> 分支隔离,合并到 main 时各自 PR,冲突由用户处理。

9.6 git provider 细节

• rate limit：github/gitea API 有限流,频繁 commit/查询要退避,避免触发封禁。
• 私有 / 公开仓库：都支持;私有仓库凭 PAT 访问。
• 网络可达：runtime 要能访问用户的 git(公网 github 没问题;自建 gitea 若在内网,需用户提供可达地址或白名单)。
• webhook 回写(可选)：若用户在自己仓库手动改了代码,是否要 webhook 通知 HM 同步基线? v2 考虑。

9.7 部署细节(客户端执行 + 用户确认)

• 确认内容：弹窗要清楚展示部署目标、环境(prod/staging)、用哪条 binding、影响范围,用户确认后才发凭据。
• 目标多样性：v1 先支持 VM(SSH);k8s/serverless v2。
• 回滚：部署失败/效果不好 → 客户端能回滚到上一个交付 tag。
• 租约最小化：发给客户端的凭据是单目标、短 TTL;用完吊销。

9.8 体验(参考 Claude Code work)

• work 视图最小信息:每个 agent 的「当前在做什么(一句话)+ 正在改哪个文件 + 跑了什么命令/工具 + 产出」,实时滚动。
• 可中断:用户能在 work 视图里随时停/插话(/messages)。
• 可读日志分层:普通用户看 user_logs(友好),调试面板看 debug_logs(原始)。

---

10. 与现状的差距清单（三端 TODO）

Phase 0（运维，硬卡点）

• 🔴 打通 Key Vault 托管身份（VM identity 授 KV Secrets Officer）——不通则资源绑定/凭据全链路不可用。

Heicode Manager

• 🟡→🟢 资源绑定 API（git/vm/db/blob CRUD + 凭据写 KV + secret_ref；KV 通后启用）
• 🔴 SSE 事件流转发（/events/stream）
• 🔴 给 agent/客户端的「绑定读取 + 短期租约」接口（部署取凭据用）
• 🟡 workflow per-agent 富字段（已预留，等 AM 填）
• 🔴 资源绑定 UI（重做干净版）

agent_management（runtime）

• 🔴 真正 git 入库 + 多 agent 分支 + 合并成交付分支
• 🔴 跑测试/编译并把结果作为 test_report 产物给客户端看（不是给 HM 裁决；对错由客户端+用户判，§6.6）
• 🔴 对照 acceptance_criteria 自检，结果同样作为产物给客户端
• 🔴 per-agent 指标上报（tokens/tools/elapsed/当前动作）
• 🔴 artifact 带 source_agent_role + git_ref
• 🔴 phases[] 阶段细分上报
• 🔴 中途续跑 / redo 语义

桌面客户端（本身是 Claude-Code 式智能体程序）

• 🟡 模式选择：本地模式（本地跑 agent）vs sub 模式（派云端 AM）；未绑 git 时禁用 sub 入口
• 🟡 work 视图（先轮询 workflow，SSE 后接）——只展示运行信息（日志/状态/work），不做产物下载
• 🔴 看产物 = git：git clone/pull 用户仓库展示工程/历史/diff（不再拼 artifact 项目树）
• 🔴 迭代路径 B：git pull → 本地 agent 改 → push（复用本地能力，不必每次回云端）
• 🔴 部署：经 HM 取短期凭据 + 用户确认后本地执行

---

本文为 v0.1 草案，决策点（§8）确认后转 v1。三端以本文对齐颗粒度与职责边界。