taijibaga/heicode-mananger
9
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

docs(integration): retire artifact download model; final product lives only on git

Browse Source 
Per the locked-in model: sub mode requires git binding; the final deliverable
exists ONLY in the user's own git repo (clone/pull). During a run HM streams
ONLY run-info (logs, status, work-view). There is no product download —
project_folder / manifest / files / archive(zip) / local-edits-revision are all
retired across both docs.

- spec: header note, sequence diagram, §2 contract table (code product = git_ref),
  §3.0 step13, §3.1 (mandatory git), §3.5/§3.6 (git-only view), §3.7 (git is the
  iterate baseline, no local-edits), §6.4 (deliverable check on git_ref, not files),
  §7 / §8#8 / §10 TODO aligned. HM "artifact" demoted to a delivery/run-info record.
- unified-api: §3 parity note + legacy error codes marked retired (prior commit
  already reworked §5/§6).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
chenchen
2026-06-03 11:54:54 +08:00
co-authored by Claude Opus 4.8
parent 9b1f74265c
commit 233f99fd22
2 changed files with 50 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/integration/heicode-desktop-unified-api.md
+3 -3
View File
@@ -89,7 +89,7 @@ signature = base64( ed25519_sign(device_priv, sha256(canonical)) )
## 3. 统一任务接口 ## 3. 统一任务接口
两套前缀，按模式选择：`/api/heicode/sub-agile/*`（→ agent_management）、`/api/heicode/swarm/*`（→ HeiCode-Swarm）。**下表以 sub-agile 为例，swarm 路径把前缀 `sub-agile` 换成 `swarm` 后完全同形（含 artifacts/files/archive/revisions/local-edits/approvals/deployments 全部子接口，gap P1-4）**——两组路由由同一注册函数生成，不存在「只实现了 sub-agile」的情况。 两套前缀，按模式选择：`/api/heicode/sub-agile/*`（→ agent_management）、`/api/heicode/swarm/*`（→ HeiCode-Swarm）。**下表以 sub-agile 为例，swarm 路径把前缀 `sub-agile` 换成 `swarm` 后完全同形（approvals/deployments/workflow 等子接口）**——两组路由由同一注册函数生成，不存在「只实现了 sub-agile」的情况。（注：`files/archive/revisions/local-edits` 这些遗留子接口两侧也都还在，但已不作为代码交付路径，见 §5/§6。）
| 方法 | 路径 | 说明 | | 方法 | 路径 | 说明 |
|---|---|---| |---|---|---|
@@ -322,8 +322,8 @@ Schema 查询：`GET /api/agent/callbacks/runtime-events/schema`。
| code | 场景 | retryable | | code | 场景 | retryable |
|---|---|---| |---|---|---|
| `ARTIFACT_REVISION_CONFLICT` | 本地修改基于旧版本（`data.current_project_revision` 给出最新版本） | false | | ~~`ARTIFACT_REVISION_CONFLICT`~~ | **遗留**（local-edits revision，已退役，见 §6） | false |
| `ARTIFACT_ARCHIVE_NOT_READY` | zip 产物尚未就绪（无文件），稍后重试 | true | | ~~`ARTIFACT_ARCHIVE_NOT_READY`~~ | **遗留**（archive zip 下载，已退役，见 §5.3） | true |
| `ARTIFACT_ARCHIVE_FAILED` | 打包失败 | false | | `ARTIFACT_ARCHIVE_FAILED` | 打包失败 | false |
| `RESOURCE_BINDING_INVALID` | resource_binding_id 不存在或非本人 | false | | `RESOURCE_BINDING_INVALID` | resource_binding_id 不存在或非本人 | false |
| `DEPLOY_TARGET_DISABLED` | 云目标未启用 | false | | `DEPLOY_TARGET_DISABLED` | 云目标未启用 | false |
docs/integration/heicode-sub-mode-flow-spec.md
+47 -39
View File
@@ -1,6 +1,12 @@
# Heicode Sub 模式 端到端流程与三端规范（v0.1 草案） # Heicode Sub 模式 端到端流程与三端规范（v0.1 草案）
> 更新时间：2026-06-02 > **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 仓库、产物合并、修改/重做、部署。 > 范围：**Sub（普通子代理协作）模式**——桌面客户端（一个像 Claude Code 的智能体程序）把一个**多 agent 重活外包到云端 agent_management**：客户端发起 → 经 Heicode Manager（模型网关 + 控制面）→ agent_management 多 agent 并行执行 → 流式回客户端展示的**完整闭环**，含资源绑定、git 仓库、产物合并、修改/重做、部署。
> 前提认知（**务必先读 §0**）：客户端本身能本地跑 agent；**sub 模式是把大任务派到云端,不是客户端唯一的干活方式**；**模型统一由 HM 的 `/v1/*` 提供给客户端和 AM 两边**。 > 前提认知（**务必先读 §0**）：客户端本身能本地跑 agent；**sub 模式是把大任务派到云端,不是客户端唯一的干活方式**；**模型统一由 HM 的 `/v1/*` 提供给客户端和 AM 两边**。
> 目的：**统筹三端（桌面客户端 / Heicode Manager / agent_management）的颗粒度与理解**，作为三方共同对齐的权威流程文档与契约规范。 > 目的：**统筹三端（桌面客户端 / Heicode Manager / agent_management）的颗粒度与理解**，作为三方共同对齐的权威流程文档与契约规范。
@@ -75,16 +81,16 @@
│ │ │ _plan + 注入资源授权 │ HMAC │ 分配角色/模型 │ │ │ │ _plan + 注入资源授权 │ HMAC │ 分配角色/模型 │
│ │ │ │ │ 5 各 agent 干活： │ │ │ │ │ │ 5 各 agent 干活： │
│ │ │ │ ◄──────┤ 流式回调状态/日志/ │ │ │ │ │ ◄──────┤ 流式回调状态/日志/ │
│ 7 轮询/订阅 ◄──┼────────┤ 6 收敛三层状态+产物 │ callback│ work/产物 + git 入库 │ │ 7 轮询/订阅 ◄──┼────────┤ 6 收敛三层状态+运行信息 │ callback│ 状态/日志/work + │
│ 展示 work │ │ 裁决 display_status │ │ 8 各 agent 代码→分支 │ │ 展示 work(只有 │ │ 裁决 display_status │ │ git 入库 + push │
│ │ │ │ │ 9 合并→完整产物 │ │ 日志/状态/work)│ │ (只转发运行信息) │ │ 8 各 agent 代码→分支 │
│ 10 看产物 ─────┼───────►│ manifest/files/archive │ ◄──────┤ (git/blob) │ │ │ │ │ │ 9 合并→交付分支(git) │
│ (经 git 或 │ │ │ │ │ │ 10 看产物 ─────┼──git──► (直接 git clone/pull 用户 │ ◄──────┤ push 用户仓库 + │
│ 经 HM) │ │ │ │ │ │ 只走 git │ 自己的仓库; 不经 HM) │ git_ref │ 回调 git_ref 通知 HM │
│ 11 不满意 ─────┼───────►│ /messages | /execute ├──────► │ 12 修改/重做 │ │ 11 不满意 ─────┼───────►│ /messages | /execute ├──────► │ 12 修改/重做(git) │
│ │ │ (带 active_revision) │ │ │ │ │ │ │ │ │
│ 13 本地 git │ ◄──────┤ (用户自己仓库直接 pull) │ │ │ │ 13 本地 git │ ◄─git── (pull/改/push, 不经 HM) │ │ │
│ 14 部署 VM ────┼───────►│ 取凭据(加密) → 执行 │ │ │ │ 14 部署 VM ────┼───────►│ 取凭据(加密) → 客户端执行│ │ │
└────────────────┘ └──────────────────────────┘ └──────────────────────┘ └────────────────┘ └──────────────────────────┘ └──────────────────────┘
``` ```
@@ -98,10 +104,10 @@
|---|---|---|---|---| |---|---|---|---|---|
| 建任务 | 需求包（objective/context/约束/验收/模型选择/角色） | orchestration_plan + 资源授权 grants | deployment_id/swarm_id | deployment_id(=task_id) + display_status | | 建任务 | 需求包（objective/context/约束/验收/模型选择/角色） | orchestration_plan + 资源授权 grants | deployment_id/swarm_id | deployment_id(=task_id) + display_status |
| 运行状态 | — | — | `status`+`runtime_execution_status`+`phase` | **`display_status`**（裁决后） | | 运行状态 | — | — | `status`+`runtime_execution_status`+`phase` | **`display_status`**（裁决后） |
| 日志/work | — | — | 事件流（task./agent./phase./handoff./artifact.） | `user_logs`+`debug_logs` / work 视图 | | 日志/work | — | — | 事件流（task./agent./phase./handoff./artifact.） | `user_logs`+`debug_logs` / work 视图（**只有运行信息**） |
| 每 agent 指标 | — | — | 🔴 per-agent tokens/tools/elapsed | workflow.agents[].* | | 每 agent 指标 | — | — | 🔴 per-agent tokens/tools/elapsed | workflow.agents[].* |
| 产物 | — | — | artifact（type/uri/**source_agent_role**/files） | project_folder：manifest/files/archive | | 代码产物 | — | — | **git push + 回调 `git_ref`**（commit/分支/改了哪些文件 + `source_agent_role`，仅元数据） | **git_ref（让客户端去 git pull）**——HM 不提供产物文件下载 |
| 修改/重做 | message / execute（带 revision） | 续跑/重做指令 | 新 artifact + 状态 | 新 display_status + 新产物 | | 修改/重做 | message / execute | 续跑/重做指令 | 新 commit + git_ref + 状态 | 新 display_status + 新 git_ref |
| 凭据 | 只传 `resource_binding_id` | 注入 `secret_ref`（azkv://） | — | 只回 secret_ref（打码） | | 凭据 | 只传 `resource_binding_id` | 注入 `secret_ref`（azkv://） | — | 只回 secret_ref（打码） |
> ⚠️ **上表只画了「任务控制面」。还有一条独立的并行通道——模型调用：** > ⚠️ **上表只画了「任务控制面」。还有一条独立的并行通道——模型调用：**
@@ -138,7 +144,7 @@
**E. 合并与产物** **E. 合并与产物**
12. **AM** 阶段结束 → 把各 agent 分支**合并**成一个交付分支（`delivery/<task_id>` 或 PR）→ push 到用户仓库 → 回调通知 **HM** 产物就绪（带 `git_ref` + artifact）。 12. **AM** 阶段结束 → 把各 agent 分支**合并**成一个交付分支（`delivery/<task_id>` 或 PR）→ push 到用户仓库 → 回调通知 **HM** 产物就绪（带 `git_ref` + artifact）。
13. **客户端**看产物两条路：(a) 直接 `git clone/pull` 用户自己的仓库；(b) 经 **HM** 的 `manifest/files/archive`。 13. **客户端**看产物：直接 `git clone/pull` 用户自己的仓库（完整工程 + 历史 + diff）。**只此一条路**——产物在 git，HM 不托管/不打包/不提供产物文件下载；HM 给的只是 `git_ref`（告诉客户端去哪个仓库/分支/commit pull）。
**F. 不满意 → 改 / 重做** **F. 不满意 → 改 / 重做**
14. **客户端** → `POST .../messages`（追加要求）或 `.../execute`（重跑）→ **HM** 取最新 accepted 基线转给 **AM** → **AM** 在原产物上改/重做 → 回到第 9 步。 14. **客户端** → `POST .../messages`（追加要求）或 `.../execute`（重跑）→ **HM** 取最新 accepted 基线转给 **AM** → **AM** 在原产物上改/重做 → 回到第 9 步。
@@ -156,9 +162,7 @@
🟢 客户端选 `mode=sub_agile`（区别于 `swarm`）。 🟢 客户端选 `mode=sub_agile`（区别于 `swarm`）。
✅ **决策（2026-06-02）**：**git 仓库 = 用户绑定自己的仓库**（gitea / github，用户提供 URL）。**没有 Heicode 托管仓库**。 ✅ **决策（2026-06-02）**：**git 仓库 = 用户绑定自己的仓库**（gitea / github，用户提供 URL）。**没有 Heicode 托管仓库**。
- **git 流程**（agent 入库/合并、客户端 git pull 看产物）需要先绑定仓库 → 见 §4.1。 ✅ **决策（2026-06-03）**：**sub 模式强制绑定 git**——未绑仓库则**不能进 sub**（UI 上禁用 sub，引导用户先绑 git 或改用客户端本地模式）。**不再有"未绑仓库走仅产物轻量路径"这种东西**（`project_folder`/manifest/files/archive 已退役）。代码产物的唯一归宿就是用户绑定的 git 仓库（§4.1）：agent 在此入库/合并，客户端 `git clone/pull` 看产物。
- **未绑仓库时**：走「仅产物」轻量路径——HM 把 AM 产物以 `project_folder`（manifest/files/archive）形式给客户端，**无 git、无增量 diff、无分支历史**。
- ❓ 待定（小）：sub 模式是否**强制**绑 git？建议——**全 git 流程需绑仓库；不绑则只能用轻量产物路径**，由产品决定是否在 UI 上「未绑仓库则禁用 sub」。
### 3.2 客户端 → HM（加密 + 鉴权 + 建任务） ### 3.2 客户端 → HM（加密 + 鉴权 + 建任务）
@@ -197,26 +201,27 @@
- 谁负责合并？（agent_management 合并后给一个最终分支/commit；HM 不碰 git 操作，只记录引用） - 谁负责合并？（agent_management 合并后给一个最终分支/commit；HM 不碰 git 操作，只记录引用）
- 合并策略？（按目录隔离自然无冲突：backend/ + frontend/ 并列；同文件冲突由一个「集成 agent」或规则解决） - 合并策略？（按目录隔离自然无冲突：backend/ + frontend/ 并列；同文件冲突由一个「集成 agent」或规则解决）
🟡 **现状**：sub 模式 AM 产物是 **blob/文本 artifact**（每角色一个 project_folder，多角色=多 artifact，见实测）；**尚未真正 git 入库 + 合并**。当前「合并成完整产物」靠客户端把多个 artifact 的 manifest 拼起来展示。git 化是目标态。 🟡 **现状**：sub 模式 AM 当前还是把产物当 blob/文本 artifact 回传（每角色一个，多角色=多个），**尚未真正 git 入库 + 合并**——这是**待迁移的旧实现**，不是目标态。目标态（本节）是 AM 全程在用户 git 仓库里 commit/合并，产物只在 git。客户端不再"拼 manifest 展示产物"。
### 3.6 产物查看（两条路） ### 3.6 产物查看（只走 git）
🟢 **经 HM**（不绑 git 也能看）：`/artifacts`（列表，主产物归一化 `project_folder`）→ `/manifest`（文件树）→ `/files?path=`（单文件）→ `/archive`（整包 zip）。 🔴 **唯一路径 = git**：sub 完成后客户端直接 `git clone/pull` 用户自己绑定的仓库，看完整工程 + 提交历史 + diff。HM 给的只是 `git_ref`（repo/branch/commit），告诉客户端去哪 pull。
🔴 **经 git**（绑了仓库）：客户端直接 `git clone/pull` 用户自己的仓库,看完整工程 + 历史 + diff。这是用户「通过 git 了解产物」的路径。
> **退役**：旧的「经 HM 看产物」（`/artifacts`→`/manifest`→`/files?path=`→`/archive`）是无 git 流程的残留，**sub 强制 git 后不再使用**。HM 在运行期只向客户端流式推**运行信息**（日志/状态/work，见 §5），**不提供产物文件的浏览或下载**。HM 的 `/artifacts` 接口若保留，只列**非代码的运行信息记录**（如 `test_report` 测试报告、摘要），供 work 视图展示，**不是可下载交付物**。
### 3.7 不满意 → 修改 / 重做（**两条路：云端改 或 本地改**） ### 3.7 不满意 → 修改 / 重做（**两条路：云端改 或 本地改**）
> 因为客户端本身是智能体程序（像 Claude Code），迭代有**两条等价路径**,用户按场景选： > 因为客户端本身是智能体程序（像 Claude Code），迭代有**两条等价路径**,用户按场景选：
> **基线就是 git**：两条路都以**用户仓库的最新提交**为唯一基线，不存在 HM 侧的 `local-edits`/revision 回传机制（已退役）。本地改完 `git push`，云端续跑前 `git pull`，冲突/历史/diff 全交给 git。
**路径 A — 回云端 AM 改（继续 sub）** **路径 A — 回云端 AM 改（继续 sub）**
- 🟡 **修改（续跑）**：`POST .../tasks/{id}/messages`（追加要求）→ HM 取**最新 accepted revision** 作基线 → AM 在原产物上改。（HM 侧 revision 机制已实现；AM 真正「中途续跑」🔴待支持） - 🟡 **修改（续跑）**：`POST .../tasks/{id}/messages`（追加要求）→ HM 转给 AM → AM 先 `git pull` 取用户仓库最新提交作基线 → 在其上改 → 再 push。（AM 真正「中途续跑」🔴待支持）
- 🔴 **重做**：`POST .../tasks/{id}/execute`（或新增 `/redo`）→ AM 丢弃旧产物重新生成。需 AM 支持「redo」语义。 - 🔴 **重做**：`POST .../tasks/{id}/execute`（或新增 `/redo`）→ AM 在新分支上重新生成（旧交付分支保留可对比）。需 AM 支持「redo」语义。
**路径 B — 拉到本地用客户端自己的 agent 改（回到本地模式）** **路径 B — 拉到本地用客户端自己的 agent 改（回到本地模式）**
- 🟢/🔴 客户端 `git pull` 用户仓库 → 用**客户端本地 agent**（像 Claude Code，模型仍走 HM `/v1/*`）在本地改 → `git push` 回仓库。**不必每次回云端**,适合小修小补。 - 🟢/🔴 客户端 `git pull` 用户仓库 → 用**客户端本地 agent**（像 Claude Code，模型仍走 HM `/v1/*`）在本地改 → `git push` 回仓库。**不必每次回云端**，适合小修小补。
- 改完若想让云端继续接力,把本地改动作为新基线（`local-edits` 或直接 push 后 `/messages`）。 - 改完想让云端接力：直接 push 后再 `/messages`，AM `git pull` 自然拿到本地改动——**无需任何 HM 回传接口**。
🟢 **本地修改回传（衔接两条路）**：用户/客户端本地改了产物 → `POST .../local-edits` 存为新 revision（accepted），后续云端续跑/重做以它为基线（避免云端覆盖本地改动）。
### 3.8 部署（✅ 必须客户端执行 + 必须用户确认） ### 3.8 部署（✅ 必须客户端执行 + 必须用户确认）
@@ -274,7 +279,7 @@
| 阶段 | 协议 | 状态 | | 阶段 | 协议 | 状态 |
|---|---|---| |---|---|---|
| 现状 | 客户端轮询 `GET .../workflow`（运行中 3–5s、终态 15–30s） | 🟢 | | 现状 | 客户端轮询 `GET .../workflow`（运行中 3–5s、终态 15–30s） | 🟢 |
| 目标 | `GET .../tasks/{id}/events/stream`（SSE）：HM 把 AM 回调实时转发；事件含 `agent.action / tool.call / artifact.created / phase.changed / log.line` | 🔴 | | 目标 | `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 }`。 - SSE event 统一信封：`{ event_type, deployment_id, agent_id?, phase?, occurred_at, payload }`。
@@ -327,10 +332,13 @@
否则 if 有 artifacts 但全是总结/兜底 → display_status = "needs_codegen" 否则 if 有 artifacts 但全是总结/兜底 → display_status = "needs_codegen"
否则 (一个 artifact 都没有) → display_status = "completed_without_deliverable" 否则 (一个 artifact 都没有) → display_status = "completed_without_deliverable"
``` ```
**"真实交付物"的判定**(逐条排除"假产物"):一个 artifact 满足以下**才算真实**—— **"真实交付物"的判定**(逐条排除"假产物"):AM 回报的交付记录满足以下**才算真实**——
- `metadata.synthesized != true`(不是 AM 的兜底占位产物),**且** - **目标态(git)**:回调带 **`git_ref`**(repo/branch/commit_sha)且有**真实提交**(commit 数 > 0 / 改了 N 个文件) → 真交付。HM 据此判"有没有真东西",**不下载、不读代码内容**。
- 不是纯总结类(标题/正文不含 "runtime execution summary"、"without per-agent artifacts" 等兜底标记;`artifact_type` 不是 `document`/`summary`),**且** - `metadata.synthesized != true`(不是 AM 的兜底占位记录),**且**
- 属于交付类型(`code_patch`/`code_bundle`/`diff`/`test_report`/`deployment_manifest` 等)或带有"改了 N 个文件"的结构化信号。 - 不是纯总结类(标题/正文不含 "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`。客户端据此就能准确区分成败,不会被假成功骗到。** > 一句话:**`completed` 必须"AM 说完成 + 真的有代码产物"两个条件都满足;只有总结没代码 = `needs_codegen`;啥都没有 = `completed_without_deliverable`。客户端据此就能准确区分成败,不会被假成功骗到。**
@@ -374,7 +382,7 @@
| 提交身份 | agent 提交用一个明确的 **bot 身份**（如 `heicode-agent <bot@heicode>`）+ commit message 带任务/agent/角色标注,便于用户在 git 历史里分辨人/机改动。 | | 提交身份 | agent 提交用一个明确的 **bot 身份**（如 `heicode-agent <bot@heicode>`）+ commit message 带任务/agent/角色标注,便于用户在 git 历史里分辨人/机改动。 |
| 合并冲突 | 目录隔离（backend/、frontend/ 并列）天然无冲突；同文件冲突由「集成 agent」或规则化合并解决，无法自动解则上报 `needs_codegen` 让用户介入/再跑一轮。 | | 合并冲突 | 目录隔离（backend/、frontend/ 并列）天然无冲突；同文件冲突由「集成 agent」或规则化合并解决，无法自动解则上报 `needs_codegen` 让用户介入/再跑一轮。 |
| 写入方式 | ❓建议：agent **不直接 push 到用户的 `main`**,而是 push 到 `delivery/<task_id>` 或开 **PR**,由用户在自己 git 上 review/merge → 既安全又复用用户的 PR/CI 工作流。是否强制 PR 模式待定。 | | 写入方式 | ❓建议：agent **不直接 push 到用户的 `main`**,而是 push 到 `delivery/<task_id>` 或开 **PR**,由用户在自己 git 上 review/merge → 既安全又复用用户的 PR/CI 工作流。是否强制 PR 模式待定。 |
| 客户端看产物 | 直接对用户自己的仓库 `git clone/pull`；或经 HM `/archive`（不想本地 git 时）。 | | 客户端看产物 | **只走 git**：直接对用户自己的仓库 `git clone/pull`。HM 不提供 `/archive` 等产物下载（已退役）。 |
--- ---
@@ -389,7 +397,7 @@
| 5 | 工单/里程碑 | 可选增强,默认关 —— ❓ 是否纳入 v1? | | 5 | 工单/里程碑 | 可选增强,默认关 —— ❓ 是否纳入 v1? |
| 6 | 流式 | v1 先轮询 work、SSE 放 v1.1 —— ❓ 接受? | | 6 | 流式 | v1 先轮询 work、SSE 放 v1.1 —— ❓ 接受? |
| 7 | 写入方式 | ❓ agent 是 push 到 `delivery/<task_id>` 分支 / 开 PR,还是直接进 main? 建议 PR/分支模式 | | 7 | 写入方式 | ❓ agent 是 push 到 `delivery/<task_id>` 分支 / 开 PR,还是直接进 main? 建议 PR/分支模式 |
| 8 | 未绑仓库 | ❓ 是否「未绑 git 则禁用 sub」,还是允许「仅产物」轻量路径? | | 8 | 未绑仓库 | ✅ **未绑 git 则禁用 sub**(强制绑 git)。不再有"仅产物"轻量路径;产物只在 git,无 project_folder/manifest/archive/local-edits |
--- ---
@@ -468,11 +476,11 @@
- 🔴 中途续跑 / redo 语义 - 🔴 中途续跑 / redo 语义
**桌面客户端**（本身是 Claude-Code 式智能体程序） **桌面客户端**（本身是 Claude-Code 式智能体程序）
- 🟡 模式选择：本地模式（本地跑 agent）vs sub 模式（派云端 AM） - 🟡 模式选择：本地模式（本地跑 agent）vs sub 模式（派云端 AM）；**未绑 git 时禁用 sub 入口**
- 🟡 work 视图（先轮询 workflow，SSE 后接） - 🟡 work 视图（先轮询 workflow，SSE 后接）——**只展示运行信息**（日志/状态/work），不做产物下载
- 🔴 多 artifact 合并展示（多角色产物拼成一棵完整项目树） - 🔴 **看产物 = git**：`git clone/pull` 用户仓库展示工程/历史/diff（不再拼 artifact 项目树）
- 🔴 迭代路径 B：`git pull` → 本地 agent 改 → push（复用本地能力，不必每次回云端） - 🔴 迭代路径 B：`git pull` → 本地 agent 改 → push（复用本地能力，不必每次回云端）
- 🔴 经 git 看产物 / 本地 git / 经 HM 取凭据 + 用户确认后本地执行部署 - 🔴 部署：经 HM 取短期凭据 + 用户确认后本地执行
--- ---