diff --git a/docs/integration/heicode-sub-mode-flow-spec.md b/docs/integration/heicode-sub-mode-flow-spec.md new file mode 100644 index 0000000..1ff7c04 --- /dev/null +++ b/docs/integration/heicode-sub-mode-flow-spec.md @@ -0,0 +1,260 @@ +# Heicode Sub 模式 端到端流程与三端规范（v0.1 草案） + +> 更新时间：2026-06-02 +> 范围：**Sub（普通子代理协作）模式**从桌面客户端发起、经 Heicode Manager、到 agent_management 执行、再流式回到客户端展示的**完整闭环**，含资源绑定、git 仓库、产物合并、修改/重做、部署。 +> 目的：**统筹三端（桌面客户端 / Heicode Manager / agent_management）的颗粒度与理解**，作为三方共同对齐的权威流程文档与契约规范。 +> 性质：本文是**目标设计** + **现状标注**。每节用标记区分： +> - 🟢 **已实现**（当前代码/线上已具备） +> - 🟡 **部分实现**（有基础，缺字段/流式/打通） +> - 🔴 **待建**（目标态，尚未实现） +> - ❓ **待决策**（需产品/三端确认的设计点，附我的建议） + +相关文档：客户端对接接口见 [`heicode-desktop-unified-api.md`](./heicode-desktop-unified-api.md)；runtime 契约见 agent_management《Sub Mode Runtime 对接指南》。 + +--- + +## 0. 三端角色与边界 + +| 端 | 角色 | 负责 | 不负责 | +|---|---|---|---| +| **桌面客户端**（cc-haha / Desktop） | 用户入口 + 本地操作 | 选模式、填需求、展示 work/日志/产物、本地 git、发起部署 | 不直连 agent_management；不自行判定成功；不存明文凭据 | +| **Heicode Manager**（heicode/） | 网关 + 控制面 + **唯一状态裁判** | 解密验签、鉴权、建任务、分发 runtime、收敛状态/产物、资源绑定与凭据托管、对客户端统一出口 | 不执行 agent；不直接写业务代码；不在日志/库里留明文凭据 | +| **agent_management**（Sub Mode Runtime） | 执行面 | 把需求拆成多 agent、调度执行、产代码、git 入库、流式上报状态/日志/产物、合并 | 不面向用户；不输出最终 `display_status`；不做最终裁决 | + +**铁律**： +1. 客户端**只调 Manager**（`/api/heicode/*`、`/api/agent/*`），禁止直连 runtime/NewAPI/Runtime artifact。 +2. Manager 是**唯一状态裁判**，客户端只消费 `display_status`。 +3. 凭据只进 **Azure Key Vault**，全链路只传/存 `secret_ref`，明文绝不落库/日志/回调。 + +--- + +## 1. 端到端总体流程（时序） + +```text +┌── 桌面客户端 ──┐ ┌──── 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 或 │ │ │ │ │ +│ 经 Manager) │ │ │ │ │ +│ 11 不满意 ─────┼───────►│ /messages | /execute ├──────► │ 12 修改/重做 │ +│ │ │ (带 active_revision) │ │ │ +│ 13 本地 git │ ◄──────┤ (用户自己仓库直接 pull) │ │ │ +│ 14 部署 VM ────┼───────►│ 取凭据(加密) → 执行 │ │ │ +└────────────────┘ └──────────────────────────┘ └──────────────────────┘ +``` + +--- + +## 2. 三端颗粒度契约（一图看清谁给谁什么） + +| 数据/动作 | 客户端 → Manager | Manager → runtime | runtime → Manager（回调） | Manager → 客户端 | +|---|---|---|---|---| +| 建任务 | 需求包（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.1 选择 sub + 准备（资源绑定前置） + +🟢 客户端选 `mode=sub_agile`（区别于 `swarm`）。 +❓ **是否必须先绑 git 才能用 sub？** → 见 §4.1。**建议：不强制**——默认走 **Heicode 托管仓库**（零配置即用），绑自己的 git 是高级选项。 + +### 3.2 客户端 → Manager（加密 + 鉴权 + 建任务） + +🟢 **加密链路**：与模型调用完全一致。 +- 写请求（POST/PUT/DELETE）：`Content-Encoding: heicode-aead-v1`，X25519-ECDH + HKDF + ChaCha20-Poly1305 加密 body，Ed25519 设备签名（`X-Heicode-*`）。 +- GET：无 body 设备签名（同 canonical，body 哈希为空串哈希）。 +- Manager 中间件 `UserOrV2DeviceAuth` 解密 + 验签 + 从设备绑定 token 解析用户身份。 + +🟢 **鉴权/配额**：解析 user_id、绑定 scope、计费上下文。 +🟢 **建任务**：`POST /api/heicode/sub-agile/tasks`，body = **需求包**（见客户端接口文档 §3.1），Manager 译成 `orchestration_plan` 并落库，返回 `deployment_id`（= task_id）。 + +### 3.3 Manager → 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，不含明文）**。 +🟡 **回调竞态**：runtime 回调可能早于 Manager 存 runtime_id → Manager 用「读时收敛」(`reconcileDeploymentFromRuntime`) 兜底（已实现）。 + +### 3.4 多 agent 执行 + 流式回传（work 视图，参考 Claude Code） + +🟡 **现状**：runtime 通过回调上报 `deployment.status_changed / task.* / handoff.* / artifact.created / phase.changed` 等事件；Manager 聚合成 timeline/events/logs；客户端**轮询**展示。 +🔴 **目标（work 视图）**：像 Claude Code 的 work 面板那样**实时流式**展示「每个 agent 正在做什么、跑了哪些工具、产了哪些文件、各阶段进度」。需要补： + +1. 🔴 **流式协议**：Manager 提供 `GET .../tasks/{id}/events/stream`（SSE）或 WS，把 runtime 回调实时转发给客户端。**现状无 SSE**，客户端轮询 `/workflow`（3–5s）兜底（见 §5）。 +2. 🔴 **per-agent 富字段**：runtime 在状态/回调里上报每个 agent 的 `tokens / tools(工具调用数) / elapsed_seconds / 当前动作描述 / artifact_ids`。Manager 的 `/workflow` 已预留这些字段（缺值时为 0/空），等 runtime 填。 +3. 🔴 **artifact 来源角色**：runtime 给 artifact 打 `source_agent_role`，Manager 才能把产物准确归到对应 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；Manager 不碰 git 操作，只记录引用） +- 合并策略？（按目录隔离自然无冲突：backend/ + frontend/ 并列；同文件冲突由一个「集成 agent」或规则解决） + +🟡 **现状**：sub 模式 runtime 产物是 **blob/文本 artifact**（每角色一个 project_folder，多角色=多 artifact，见实测）；**尚未真正 git 入库 + 合并**。当前「合并成完整产物」靠客户端把多个 artifact 的 manifest 拼起来展示。git 化是目标态。 + +### 3.6 产物查看（两条路） + +🟢 **经 Manager**（不绑 git 也能看）：`/artifacts`（列表，主产物归一化 `project_folder`）→ `/manifest`（文件树）→ `/files?path=`（单文件）→ `/archive`（整包 zip）。 +🔴 **经 git**（绑了仓库）：客户端直接 `git clone/pull` 用户自己的仓库,看完整工程 + 历史 + diff。这是用户「通过 git 了解产物」的路径。 + +### 3.7 不满意 → 修改 / 重做 + +🟡 **修改（续跑）**：`POST .../tasks/{id}/messages`（追加要求）→ Manager 取**最新 accepted 本地修改 revision** 作基线 → runtime 在原产物上改。（Manager 侧 revision 机制已实现；runtime 真正「中途续跑」🔴待支持） +🔴 **重做**：`POST .../tasks/{id}/execute`（或新增 `/redo`）→ runtime 丢弃旧产物重新生成。需 runtime 支持「redo」语义。 +🟢 **本地修改回传**：用户在本地改了产物 → `POST .../local-edits` 存为新 revision（accepted），后续续跑/重做以它为基线。 + +### 3.8 部署（客户端经 Manager 加密接口取凭据 → 执行） + +🔴 **目标**： +- 客户端要部署到 VM/连数据库时，**不直接拿明文凭据**；通过 Manager 的**加密密钥接口**换取**短期凭据租约**（secret 从 KV 解出，经 V2 加密通道回客户端，或由 Manager 代理执行）。 +- 两种执行位：(a) **客户端执行**（Manager 发短期租约，客户端 git→VM、跑部署）；(b) **Manager/runtime 执行**（客户端只下指令，凭据不出 Manager）。建议高危操作走 (b) + 审批。 +🟡 **现状**：有云部署控制面占位（`/deployments`，返回 `executor:pending_worker`），真实执行待 Deploy 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`** 给任务；Manager 内部解析为凭据注入 runtime。 +- 客户端**禁止 inline** secret_ref / AccessKey / 连接串。 +- 凭据录入**一次性**：客户端经 V2 加密通道把凭据传给 Manager → Manager 写 KV → 库里只留 `azkv://`。 + +### 4.1 Git 仓库绑定 ❓ + +**用途**：agent 在此仓库读写代码、git 入库、合并；客户端 clone/pull 看产物；后续 git 到 VM 部署。 + +| 决策点 | 我的建议 | +|---|---| +| **是否必须绑 git 才能用 sub** | **否，不强制**。默认 **Heicode 托管仓库**（每个 sub 任务自动开一个托管 repo，用户零配置即用）；绑自己的 git 是**高级选项**（能用自己的工作流/工单/CI）。这样降低门槛又保留高级能力。 | +| **绑定鉴权方式（SSH 还是？）** | **首选 HTTPS + 细粒度 token**：GitHub → **GitHub App**（最小权限、可按仓库授权、可吊销、有 rate limit 优势）或 fine-grained PAT；Gitea/GitLab → 范围化 PAT。**SSH deploy key** 作为备选（适合纯 push/pull、不需要 API 的场景）。凭据进 KV。**不建议**用账号密码。 | +| **绑定粒度** | 单仓库级（一个 binding = 一个 repo + 一个分支基线 + 允许路径）。permission_scope：`repo:read` / `repo:write`。 | +| **能否用 git 的工单/里程碑** | **可选增强**，不影响主流程：若绑的是 GitHub/Gitea 且授了 issues 权限，可把 sub 任务的**子任务映射为 issues**、**阶段映射为 milestone**、**handoff/审批映射为 issue 评论**。默认关闭，用户显式开启。这能让用户在自己的 git 看板里跟踪 agent 进度。 | +| **分支模型** | 见 §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（Manager 写）→ 只存 secret_ref。 +- 使用 → 任务/部署时 Manager 从 KV 解出注入 runtime，或发**短期租约**（TTL + 可吊销）给客户端。 +- 审计 → 谁在什么 scope 用了哪条绑定、发了哪些租约、何时吊销（只记 secret_ref + 打码摘要）。 + +--- + +## 5. 流式协议规范（work 视图） + +| 阶段 | 协议 | 状态 | +|---|---|---| +| 现状 | 客户端轮询 `GET .../workflow`（运行中 3–5s、终态 15–30s） | 🟢 | +| 目标 | `GET .../tasks/{id}/events/stream`（SSE）：Manager 把 runtime 回调实时转发；事件含 `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`（基于 Manager 的事件游标）。 +- **降级**：SSE 不可用时自动回落轮询，UI 行为一致（只是延迟）。 +- 客户端**不要**订阅不存在的流（未上线前 `/events/stream` 返回未实现，别硬连）。 + +--- + +## 6. 状态模型（唯一裁判 = Manager） + +🟢 三层 + 裁决（见客户端接口文档 §4）： +- `cloud_deployment_status`（Manager 控制面）/ `runtime_execution_status`（runtime 事实）/ **`display_status`（客户端只看这个）**。 +- 裁决：runtime `completed` + 有真实交付物（非 `metadata.synthesized`、非纯总结）→ `completed`；否则降级 `needs_codegen`（只有方案/总结）/ `completed_without_deliverable`（无产物）。 +- `waiting_approval` 透传（高风险/需审批时）。 + +--- + +## 7. Git 仓库与分支 / 合并模型 ❓ + +**目标流程**： +```text +任务开始 → 建/选仓库 → 拉基线分支 base +每个 agent → 自己分支 agent/ → 多次 commit（流式可见 diff） +阶段结束 → 集成：合并各 agent 分支 → 交付分支 delivery/（或 main） +完成 → 交付分支即「完整产物」；客户端 clone/pull 看；不满意 → 在交付分支上续跑/重做 +``` + +**决策点**： +| 点 | 建议 | +|---|---| +| 仓库归属 | 托管仓库（Heicode 名下，任务级）或用户绑定仓库（用户名下，复用其工作流）。两者都支持，绑定优先。 | +| 谁执行 git | **agent_management 执行**所有 git 操作（commit/merge）；Manager 只**记录引用**（repo/branch/commit_sha）并在 artifact metadata 里带 `git_ref`。Manager 不做 git。 | +| 合并冲突 | 目录隔离（backend/、frontend/ 并列）天然无冲突；同文件冲突由「集成 agent」或规则化合并解决，冲突无法自动解则上报 `needs_codegen` 让用户/再跑一轮。 | +| 客户端看产物 | 绑定仓库 → 直接 git；托管仓库 → 经 Manager `/archive` 或给只读 clone 凭据（短期租约）。 | + +--- + +## 8. 开放决策点汇总（需你拍板） + +1. **git 前置**：默认托管仓库 + 可选绑自己的 git（我建议如此）—— 确认？ +2. **git 鉴权**：GitHub App / 细粒度 PAT 为主，SSH deploy key 备选 —— 确认？ +3. **工单/里程碑**：作为可选增强（子任务→issue、阶段→milestone）默认关 —— 要不要纳入 v1？ +4. **流式**：v1 先轮询 work 视图，SSE 作为 v1.1 —— 接受？ +5. **git 执行方**：agent_management 执行 git、Manager 只记引用 —— 确认？ +6. **部署执行位**：高危走「Manager/runtime 执行 + 审批」，低危可发短期租约让客户端执行 —— 确认？ +7. **托管仓库技术选型**：用哪套 git 服务承载托管仓库（自建 Gitea / GitHub org / Azure Repos）？ + +--- + +## 9. 与现状的差距清单（三端 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 富字段（已预留，等 runtime 填） +- 🔴 资源绑定 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 / 经 Manager 取凭据部署 + +--- + +*本文为 v0.1 草案，决策点（§8）确认后转 v1。三端以本文对齐颗粒度与职责边界。*