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

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

更新时间：2026-06-02 范围：Sub（普通子代理协作）模式从桌面客户端发起、经 Heicode Manager、到 agent_management 执行、再流式回到客户端展示的完整闭环，含资源绑定、git 仓库、产物合并、修改/重做、部署。 目的：统筹三端（桌面客户端 / 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 三端铁律

1. 客户端只调 HM（/api/heicode/*、/api/agent/*），禁止直连 AM / NewAPI / Runtime artifact。
2. HM 是唯一状态裁判，客户端只消费 display_status（定义见 §6）。
3. 凭据只进 Azure Key Vault，全链路只传/存 secret_ref，明文绝不落库/日志/回调。
4. HM 不执行任何命令、不部署、不连 VM；执行靠 AM（任务期）或客户端（部署期）。

---

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/产物 + git 入库 │
│   展示 work    │        │   裁决 display_status     │        │ 8 各 agent 代码→分支  │
│                │        │                          │        │ 9 合并→完整产物       │
│ 10 看产物 ─────┼───────►│  manifest/files/archive  │ ◄──────┤   (git/blob)          │
│   (经 git 或    │        │                          │        │                      │
│    经 HM)  │        │                          │        │                      │
│ 11 不满意 ─────┼───────►│ /messages | /execute     ├──────► │ 12 修改/重做          │
│                │        │   (带 active_revision)    │        │                      │
│ 13 本地 git    │ ◄──────┤  (用户自己仓库直接 pull) │        │                      │
│ 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[].*
产物	—	—	artifact（type/uri/source_agent_role/files）	project_folder：manifest/files/archive
修改/重做	message / execute（带 revision）	续跑/重做指令	新 artifact + 状态	新 display_status + 新产物
凭据	只传 resource_binding_id	注入 secret_ref（azkv://）	—	只回 secret_ref（打码）

---

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. 客户端看产物两条路：(a) 直接 git clone/pull 用户自己的仓库；(b) 经 HM 的 manifest/files/archive。

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 托管仓库。

• git 流程（agent 入库/合并、客户端 git pull 看产物）需要先绑定仓库 → 见 §4.1。
• 未绑仓库时：走「仅产物」轻量路径——HM 把 AM 产物以 project_folder（manifest/files/archive）形式给客户端，无 git、无增量 diff、无分支历史。
• ❓ 待定（小）：sub 模式是否强制绑 git？建议——全 git 流程需绑仓库；不绑则只能用轻量产物路径，由产品决定是否在 UI 上「未绑仓库则禁用 sub」。

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（每角色一个 project_folder，多角色=多 artifact，见实测）；尚未真正 git 入库 + 合并。当前「合并成完整产物」靠客户端把多个 artifact 的 manifest 拼起来展示。git 化是目标态。

3.6 产物查看（两条路）

🟢 经 HM（不绑 git 也能看）：/artifacts（列表，主产物归一化 project_folder）→ /manifest（文件树）→ /files?path=（单文件）→ /archive（整包 zip）。 🔴 经 git（绑了仓库）：客户端直接 git clone/pull 用户自己的仓库,看完整工程 + 历史 + diff。这是用户「通过 git 了解产物」的路径。

3.7 不满意 → 修改 / 重做

🟡 修改（续跑）：POST .../tasks/{id}/messages（追加要求）→ HM 取最新 accepted 本地修改 revision 作基线 → AM 在原产物上改。（HM 侧 revision 机制已实现；AM 真正「中途续跑」🔴待支持） 🔴 重做：POST .../tasks/{id}/execute（或新增 /redo）→ runtime 丢弃旧产物重新生成。需 runtime 支持「redo」语义。 🟢 本地修改回传：用户在本地改了产物 → POST .../local-edits 存为新 revision（accepted），后续续跑/重做以它为基线。

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 / artifact.created / phase.changed / log.line	🔴

规范：

• 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 为什么要"裁决"

AM（agent_management）只会上报"执行事实"(它说 completed 只代表"我跑完了"),但"跑完了"不等于"交付成功"——可能跑完了却没产出真实代码(只产了一段总结/兜底)。如果直接把 AM 的 completed 给用户,会出现"显示成功、实际没东西"的假成功。 所以由 HM 做唯一裁判:综合 AM 的状态 + 实际产物,算出一个给用户看的最终状态 display_status。客户端只看 display_status,不看 AM 的原始状态。

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"

"真实交付物"的判定(逐条排除"假产物"):一个 artifact 满足以下才算真实——

• metadata.synthesized != true(不是 AM 的兜底占位产物),且
• 不是纯总结类(标题/正文不含 "runtime execution summary"、"without per-agent artifacts" 等兜底标记;artifact_type 不是 document/summary),且
• 属于交付类型(code_patch/code_bundle/diff/test_report/deployment_manifest 等)或带有"改了 N 个文件"的结构化信号。

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

6.5 成功判据（客户端用）

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

---

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 clone/pull；或经 HM /archive（不想本地 git 时）。

---

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」,还是允许「仅产物」轻量路径?

---

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 跑测试(若有)并把测试结果作为 artifact 回传;HM 把「测试通过」纳入 completed 裁决参考。
• 产物版本/标签：每次交付打 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 分支 + 合并成交付分支
• 🔴 per-agent 指标上报（tokens/tools/elapsed/当前动作）
• 🔴 artifact 带 source_agent_role + git_ref
• 🔴 phases[] 阶段细分上报
• 🔴 中途续跑 / redo 语义

桌面客户端

• 🟡 work 视图（先轮询 workflow，SSE 后接）
• 🔴 多 artifact 合并展示（多角色产物拼成一棵完整项目树）
• 🔴 经 git 看产物 / 本地 git / 经 HM 取凭据部署

---

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