From f542017ebc24345cb8e24d9f16ea46c0967382a4 Mon Sep 17 00:00:00 2001
From: qinhao <qinghao@qq.com>
Date: Mon, 1 Jun 2026 09:44:20 +0000
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=202026-06-01=5Fheicode?=
 =?UTF-8?q?=E5=AE=A2=E6=88=B7=E7=AB=AF=E7=9B=B8=E5=85=B3=E5=AE=9A=E4=B9=89?=
 =?UTF-8?q?.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 2026-06-01_heicode客户端相关定义.md | 2807 +++++++++++++++++++++++++++
 2026-06-01_计划分工.md              |  338 ----
 2 files changed, 2807 insertions(+), 338 deletions(-)
 create mode 100644 2026-06-01_heicode客户端相关定义.md
 delete mode 100644 2026-06-01_计划分工.md

diff --git a/2026-06-01_heicode客户端相关定义.md b/2026-06-01_heicode客户端相关定义.md
new file mode 100644
index 0000000..9129a73
--- /dev/null
+++ b/2026-06-01_heicode客户端相关定义.md
@@ -0,0 +1,2807 @@
+# Heicode 客户端与 Agent Runtime 统一调用方案
+
+> 版本：v0.1  
+> 日期：2026-06-01  
+> 范围：Heicode 客户端、heicode-mananger、agent_management、HeiCode-Swarm  
+> 基准：以 Heicode 客户端体验为基准，统一接口归口、模式路由、状态、日志、产物、回调和调试规范。
+
+## 1. 背景与目标
+
+当前 Heicode 体系中存在几个历史问题：
+
+1. `agnet` 是拼写错误，后续标准命名应统一为 `agent`。
+2. `/api/swarms` 被同时用于普通 Sub Agile 和真正 Swarm，造成语义混乱。
+3. Runtime、Manager、客户端各自判断任务完成、产物有效性和状态，导致结论不一致。
+4. 客户端既要支持 Sub Agile，又要支持 Swarm，但两种模式的执行层、模型策略和展示方式不同。
+5. 所有接口需要归口到 Manager，客户端不应直接调用 Runtime。
+
+本方案目标：
+
+- 客户端明确区分 `Sub Agile` 和 `Swarm` 两种模式。
+- 所有客户端接口统一归口到 `heicode-mananger`。
+- 所有 Sub Agile 模式统一走 `agent_management`。
+- 所有 Swarm 模式统一走 `HeiCode-Swarm`。
+- 新接口统一使用 `agent`，不再使用错误拼写 `agnet`。
+- 拆分原 `/api/swarms` 路由，分别定义 Sub Agile 和 Swarm 路由。
+- Manager 成为唯一状态裁判，Runtime 只上报结构化事实。
+- 产物、日志、回调、调试信息全部经 Manager 归一化后提供给客户端。
+
+## 2. 总体原则
+
+```text
+客户端负责：提需求、选模式、选模型、持续对话、展示结果
+
+Manager 负责：统一接口、模型校验、Runtime 路由、状态裁决、产物归档、审计
+
+agent_management 负责：执行所有 Sub Agile / 普通 sub 模式
+
+HeiCode-Swarm 负责：执行所有 Swarm / 蜂群模式
+```
+
+客户端永远只调用 Manager：
+
+```text
+Heicode 客户端 -> heicode-mananger -> agent_management
+Heicode 客户端 -> heicode-mananger -> HeiCode-Swarm
+```
+
+客户端禁止直接调用：
+
+```text
+agent_management
+HeiCode-Swarm
+NewAPI
+模型网关
+Runtime artifact content 接口
+```
+
+## 3. 术语统一
+
+### 3.1 拼写统一
+
+历史错误命名：
+
+```text
+agnet
+Agnet
+```
+
+新标准命名：
+
+```text
+agent
+Agent
+```
+
+新接口、字段、文档统一使用 `agent`。
+
+兼容期可以保留旧接口，但旧接口只做转发，不再作为主文档和新客户端调用路径。
+
+### 3.2 模式定义
+
+| 模式 | 用户可见名称 | Runtime | 定位 | 模型策略 |
+|---|---|---|---|---|
+| `sub_agile` | Sub Agile | agent_management | 普通子代理协作，按角色/阶段推进 | 用户可自选模型，可按角色选择 |
+| `swarm` | Swarm | HeiCode-Swarm | 蜂群编排，多 Agent 动态协作 | 用户选择主模型，由 Swarm Runtime 控制子模型调用 |
+
+注意：
+
+- `Sub Agent` 在用户界面仍统一称为 `Sub Agile`。
+- `/api/swarms` 不再作为模式判断依据。
+- `agent_management` 中历史存在的 `/api/swarms` 只能视为旧兼容入口，不代表 Swarm 模式。
+
+## 4. 系统分工
+
+### 4.1 Heicode 客户端
+
+客户端是主 Agent 和用户入口。
+
+职责：
+
+1. 提出需求。
+2. 选择模式：`Sub Agile` 或 `Swarm`。
+3. Sub Agile 模式支持选择模型。
+4. Swarm 模式支持选择主模型。
+5. 维护持续会话。
+6. 展示 Manager 返回的状态、日志、时间线、审批、用量和产物。
+7. 支持查看和下载产物。
+8. 支持调试详情展示。
+
+客户端本地任务会话建议保存：
+
+```ts
+type HeicodeTaskMode = "sub_agile" | "swarm";
+
+interface HeicodeTaskSession {
+  taskId: string;
+  conversationId: string;
+  deploymentId?: string;
+  mode: HeicodeTaskMode;
+  status: string;
+  selectedModel?: string;
+  primaryModel?: string;
+  roleModels?: Record<string, string>;
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+客户端不做：
+
+- 不直接调用 Runtime。
+- 不自行判断 Runtime 是否真正完成。
+- 不用正则判断产物是否有效。
+- 不展示 Runtime 原始部署草稿给普通用户。
+- 不展示 `newapi`、上游厂商、内部模型网关等字眼。
+
+### 4.2 heicode-mananger
+
+Manager 是所有接口的统一入口、Runtime 路由器和唯一状态裁判。
+
+职责：
+
+1. 接收客户端需求包。
+2. 根据模式路由 Runtime。
+3. 校验模型、套餐、预算、权限和资源绑定。
+4. 生成 Runtime 执行计划。
+5. 接收 Runtime 回调。
+6. 保存任务、会话、部署、事件、日志、产物和审计。
+7. 根据结构化事实裁决最终状态。
+8. 向客户端提供统一状态、日志、产物、调试接口。
+
+Runtime 路由规则：
+
+```text
+mode=sub_agile -> agent_management
+mode=swarm     -> HeiCode-Swarm
+```
+
+### 4.3 agent_management
+
+agent_management 是所有 Sub Agile / 普通 sub 模式的 Runtime。
+
+职责：
+
+1. 接收 Manager 下发的 Sub Agile plan。
+2. 按角色执行任务。
+3. 支持 Manager 下发的用户自选模型。
+4. 生成真实 artifact。
+5. 向 Manager 回调阶段、日志、状态、产物、用量和审批事件。
+6. 上报结构化执行事实。
+
+Sub Agile 角色示例：
+
+```text
+product
+architect
+frontend
+backend
+reviewer
+ops
+```
+
+### 4.4 HeiCode-Swarm
+
+HeiCode-Swarm 是所有 Swarm / 蜂群模式的 Runtime。
+
+职责：
+
+1. 接收 Manager 下发的 Swarm plan。
+2. 使用主模型进行编排和决策。
+3. 负责任务图、Agent claim、heartbeat、handoff、retry、blocked 等蜂群能力。
+4. 生成统一 artifact。
+5. 向 Manager 回调 Swarm 执行事件、状态、产物、用量和调试数据。
+
+Swarm 不作为 Sub Agile Runtime 使用。
+
+## 5. 路由设计
+
+### 5.1 客户端到 Manager 路由
+
+建议拆分客户端语义路由：
+
+```text
+GET  /api/heicode/capabilities
+
+POST /api/heicode/sub-agile/tasks
+GET  /api/heicode/sub-agile/tasks
+GET  /api/heicode/sub-agile/tasks/{task_id}
+POST /api/heicode/sub-agile/tasks/{task_id}/messages
+POST /api/heicode/sub-agile/tasks/{task_id}/execute
+POST /api/heicode/sub-agile/tasks/{task_id}/stop
+DELETE /api/heicode/sub-agile/tasks/{task_id}
+GET  /api/heicode/sub-agile/tasks/{task_id}/timeline
+GET  /api/heicode/sub-agile/tasks/{task_id}/logs
+GET  /api/heicode/sub-agile/tasks/{task_id}/events
+GET  /api/heicode/sub-agile/tasks/{task_id}/artifacts
+GET  /api/heicode/sub-agile/tasks/{task_id}/artifacts/{artifact_id}/content
+GET  /api/heicode/sub-agile/tasks/{task_id}/diagnostics
+
+POST /api/heicode/swarm/tasks
+GET  /api/heicode/swarm/tasks
+GET  /api/heicode/swarm/tasks/{task_id}
+POST /api/heicode/swarm/tasks/{task_id}/messages
+POST /api/heicode/swarm/tasks/{task_id}/execute
+POST /api/heicode/swarm/tasks/{task_id}/stop
+DELETE /api/heicode/swarm/tasks/{task_id}
+GET  /api/heicode/swarm/tasks/{task_id}/timeline
+GET  /api/heicode/swarm/tasks/{task_id}/logs
+GET  /api/heicode/swarm/tasks/{task_id}/events
+GET  /api/heicode/swarm/tasks/{task_id}/artifacts
+GET  /api/heicode/swarm/tasks/{task_id}/artifacts/{artifact_id}/content
+GET  /api/heicode/swarm/tasks/{task_id}/diagnostics
+```
+
+如果后端希望减少路由，也可以保留统一任务接口：
+
+```text
+/api/heicode/tasks
+```
+
+但请求体必须包含：
+
+```json
+{
+  "mode": "sub_agile"
+}
+```
+
+或：
+
+```json
+{
+  "mode": "swarm"
+}
+```
+
+### 5.2 Manager 到 Runtime 路由
+
+新标准路由应拆分为：
+
+```text
+Sub Agile Runtime:
+POST /api/agent/sub-agile/deployments
+GET  /api/agent/sub-agile/deployments/{deployment_id}
+POST /api/agent/sub-agile/deployments/{deployment_id}/stop
+POST /api/agent/sub-agile/deployments/{deployment_id}/approvals/{approval_id}
+
+Swarm Runtime:
+POST /api/agent/swarm/deployments
+GET  /api/agent/swarm/deployments/{deployment_id}
+POST /api/agent/swarm/deployments/{deployment_id}/stop
+POST /api/agent/swarm/deployments/{deployment_id}/approvals/{approval_id}
+```
+
+映射关系：
+
+```text
+/api/agent/sub-agile/* -> agent_management
+/api/agent/swarm/*     -> HeiCode-Swarm
+```
+
+### 5.3 Runtime 到 Manager 回调路由
+
+新标准回调：
+
+```text
+POST /api/agent/callbacks/runtime-events
+```
+
+旧接口兼容：
+
+```text
+POST /api/agnet/callbacks/swarm-events
+```
+
+旧接口只做兼容转发，新文档和新客户端以 `/api/agent/callbacks/runtime-events` 为准。
+
+## 6. 能力发现接口
+
+客户端启动时从 Manager 拉取模式和模型能力。
+
+```text
+GET /api/heicode/capabilities
+```
+
+示例响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "modes": [
+      {
+        "id": "sub_agile",
+        "name": "Sub Agile",
+        "runtime_kind": "agent_management",
+        "model_selection": "per_role",
+        "supports_roles": true,
+        "supports_task_graph": false,
+        "supports_artifacts": true,
+        "supports_continue_chat": true
+      },
+      {
+        "id": "swarm",
+        "name": "Swarm",
+        "runtime_kind": "heicode_swarm",
+        "model_selection": "primary",
+        "supports_roles": false,
+        "supports_task_graph": true,
+        "supports_artifacts": true,
+        "supports_continue_chat": true
+      }
+    ],
+    "models": [
+      {
+        "id": "gpt-5.4",
+        "name": "gpt-5.4",
+        "available": true
+      }
+    ]
+  },
+  "error": null
+}
+```
+
+## 7. 客户端工作模式参考
+
+参考图片目录：
+
+```text
+C:\Users\Administrator\Desktop\heicode\doc\picture
+```
+
+图片体现的目标工作模式是：
+
+```text
+聊天区 = 主 Agent 对用户的简洁叙述、关键动作、最终结果
+右侧任务面板 = 后台 Workflow / Phases / Agents / Tokens / Tools / Time / Artifacts
+后台任务 = 可异步运行，完成后可回到会话继续处理
+```
+
+这套体验可以作为 Heicode 客户端的模式基准。
+
+### 7.1 工作区布局
+
+客户端建议采用三层信息密度：
+
+1. 聊天主区
+2. 后台任务面板
+3. 调试详情面板
+
+```text
+┌───────────────────────────────┬──────────────────────────────┐
+│ 聊天主区                       │ Background Tasks / 我的任务   │
+│                               │                              │
+│ 用户需求                       │ Workflow: oracle-site        │
+│ 主 Agent 说明                  │ Status: Running              │
+│ 关键工具动作                   │ 4 Agents · 75.3k Tokens      │
+│ 最终摘要                       │                              │
+│ 产物入口                       │ Phases                       │
+│                               │ - Content                    │
+│ 输入框                         │   - backend                  │
+│                               │   - frontend                 │
+│                               │ - Review                     │
+└───────────────────────────────┴──────────────────────────────┘
+```
+
+### 7.2 聊天主区展示原则
+
+聊天主区只展示用户需要理解的内容：
+
+```text
+我会用 Sub Agile 并行执行 backend/frontend 两个角色，然后合并产物。
+已启动后台任务 oracle-site。
+子代理已完成执行，已生成 2 个产物。
+产物：Backend API 方案、Frontend 页面方案。
+```
+
+聊天区不展示：
+
+```text
+完整部署草稿 JSON
+Runtime 原始 callback
+大量重复 artifact 正文
+内部 routing payload
+内部 service name
+newapi / API 原厂 / 上游供应商字眼
+```
+
+### 7.3 后台任务面板
+
+右侧任务面板用于承载 Workflow 细节。
+
+通用字段：
+
+```json
+{
+  "workflow_id": "wf_xxx",
+  "task_id": "task_xxx",
+  "title": "oracle-site",
+  "mode": "sub_agile",
+  "status": "running",
+  "summary": "Generate Oracle cloud agency website with frontend/backend separation",
+  "agent_count": 4,
+  "tokens": 75300,
+  "tools": 12,
+  "elapsed_seconds": 90,
+  "phases": []
+}
+```
+
+面板展示：
+
+```text
+Workflow 名称
+模式：Sub Agile / Swarm
+状态：Running / Completed / Failed
+耗时
+Agent 数量
+Tokens
+Tools
+简短目标描述
+Phases 折叠列表
+Artifacts 入口
+Debug 入口
+```
+
+### 7.4 Phase 展示
+
+Phase 是右侧任务面板的主组织方式。
+
+Sub Agile 推荐 Phase：
+
+```text
+Plan
+Design
+Develop
+Review
+Deliver
+```
+
+Swarm 推荐 Phase：
+
+```text
+Plan
+Dispatch
+Execute
+Handoff
+Review
+Deliver
+```
+
+Phase 数据结构：
+
+```json
+{
+  "phase_id": "phase_content",
+  "name": "Content",
+  "status": "completed",
+  "agents": [
+    {
+      "agent_id": "agent_history",
+      "name": "content:history",
+      "role": "content",
+      "status": "completed",
+      "tokens": 19400,
+      "tools": 1,
+      "elapsed_seconds": 20
+    }
+  ]
+}
+```
+
+### 7.5 Agent 展示
+
+每个 Agent 行展示：
+
+```text
+Agent 名称
+角色
+状态
+Tokens
+Tools
+耗时
+产物数量
+```
+
+示例：
+
+```text
+Content
+  content:history      19.4k tokens · 1 tool · 20s
+  content:technology   19.2k tokens · 1 tool · 19s
+  content:future       19.4k tokens · 1 tool · 21s
+
+Hero
+  hero                 17.3k tokens · 1 tool · 09s
+```
+
+### 7.6 异步后台任务
+
+图片中有明显的后台 workflow 语义：
+
+```text
+Ran workflow ai-intro-website
+Used ScheduleWakeup
+Background tasks
+Finished
+```
+
+Heicode 可对齐为：
+
+1. 用户发送任务。
+2. 客户端立即显示“已启动后台任务”。
+3. Manager 创建 deployment。
+4. Runtime 异步执行。
+5. 客户端通过轮询或推送刷新右侧任务面板。
+6. 任务完成后，聊天区追加一条简洁总结。
+7. 用户可进入产物详情或继续对话。
+
+状态流：
+
+```text
+submitted -> accepted -> running -> completed
+submitted -> accepted -> running -> waiting_approval -> running -> completed
+submitted -> accepted -> running -> failed
+submitted -> accepted -> running -> stopped
+```
+
+### 7.7 Workflow 与模式映射
+
+客户端可以统一使用 `Workflow` 作为用户可见工作单元。
+
+```text
+Sub Agile = role-based workflow
+Swarm = graph-based workflow
+```
+
+Sub Agile 右侧面板：
+
+```text
+Workflow
+Status
+Roles / Agents
+Phases
+Tokens
+Tools
+Artifacts
+```
+
+Swarm 右侧面板：
+
+```text
+Workflow
+Status
+Task Graph
+Agents
+Handoffs
+Heartbeats
+Retries
+Artifacts
+```
+
+### 7.8 聊天区与右侧面板的职责边界
+
+| 内容 | 聊天区 | 右侧任务面板 | 调试面板 |
+|---|---|---|---|
+| 用户需求 | 展示 | 摘要 | 原始请求 |
+| 任务启动 | 展示简短信息 | 展示 workflow 状态 | Runtime create response |
+| Phase 进度 | 少量关键节点 | 完整展示 | 原始 callback |
+| Agent 明细 | 不展开 | 展示 tokens/tools/time | 原始日志 |
+| Artifact 摘要 | 展示入口 | 展示列表 | URI/hash/download_path |
+| Artifact 正文 | 点击查看 | 点击查看 | 原始 content 响应 |
+| 错误 | 用户友好文案 | 失败节点 | HTTP/status/request_id |
+
+### 7.9 对 Manager 的新增需求
+
+为了支撑该工作模式，Manager 需要提供 workflow-oriented 查询结果。
+
+建议新增或在现有接口中返回：
+
+```text
+GET /api/heicode/sub-agile/tasks/{task_id}/workflow
+GET /api/heicode/swarm/tasks/{task_id}/workflow
+```
+
+返回结构：
+
+```json
+{
+  "success": true,
+  "data": {
+    "workflow_id": "wf_xxx",
+    "task_id": "task_xxx",
+    "mode": "sub_agile",
+    "title": "oracle-site",
+    "status": "completed",
+    "summary": "Generate Oracle cloud agency website",
+    "agent_count": 4,
+    "tokens": 75300,
+    "tools": 12,
+    "elapsed_seconds": 90,
+    "phases": [
+      {
+        "name": "Develop",
+        "status": "completed",
+        "agents": [
+          {
+            "name": "backend",
+            "role": "backend",
+            "status": "completed",
+            "tokens": 30100,
+            "tools": 4,
+            "elapsed_seconds": 40,
+            "artifact_ids": ["art_backend"]
+          }
+        ]
+      }
+    ],
+    "artifacts": [
+      {
+        "artifact_id": "art_backend",
+        "title": "Backend delivery",
+        "artifact_type": "code_patch"
+      }
+    ]
+  },
+  "error": null
+}
+```
+
+### 7.10 客户端交互细节
+
+建议交互：
+
+```text
+右侧任务面板默认显示最近一个运行中 Workflow
+已完成任务收起到 Finished
+每个 Workflow 可展开 Phase
+每个 Phase 可展开 Agent
+Agent 行点击进入日志/产物
+Artifact 点击查看详情
+下载按钮从 Manager content 接口保存到本地
+失败节点显示用户友好错误，调试按钮显示 request_id
+```
+
+与图片保持一致的展示文案：
+
+```text
+Ran workflow oracle-site
+工作流已在后台启动，正在并行执行 backend/frontend。
+工作流已完成，已生成 2 个产物。
+Workflow 执行情况
+```
+
+但 Heicode 里用户模式名称仍保持：
+
+```text
+Sub Agile
+Swarm
+```
+
+## 8. 需求包定义
+
+客户端向 Manager 提交需求包，而不是提交 Runtime 原始参数。
+
+### 7.1 Sub Agile 需求包
+
+```json
+{
+  "mode": "sub_agile",
+  "client_role": "main_agent",
+  "conversation_id": "conv_xxx",
+  "requirement": {
+    "objective": "做一个 Oracle 云代理商网站，前后端分离",
+    "context": [],
+    "attachments": [],
+    "constraints": [],
+    "acceptance_criteria": []
+  },
+  "model_selection": {
+    "type": "per_role",
+    "default_model": "gpt-5.4",
+    "roles": {
+      "backend": "gpt-5.4",
+      "frontend": "gpt-5.4",
+      "reviewer": "gpt-5.3-codex"
+    }
+  },
+  "roles": ["backend", "frontend"]
+}
+```
+
+### 7.2 Swarm 需求包
+
+```json
+{
+  "mode": "swarm",
+  "client_role": "main_agent",
+  "conversation_id": "conv_xxx",
+  "requirement": {
+    "objective": "做一个复杂系统，自动拆分并协作完成",
+    "context": [],
+    "attachments": [],
+    "constraints": [],
+    "acceptance_criteria": []
+  },
+  "model_selection": {
+    "type": "primary",
+    "primary_model": "gpt-5.4"
+  }
+}
+```
+
+## 9. 模型策略
+
+### 8.1 Sub Agile 模型策略
+
+Sub Agile 支持用户自选模型。
+
+支持两种方式：
+
+1. 全局模型：
+
+```json
+{
+  "type": "default",
+  "default_model": "gpt-5.4"
+}
+```
+
+2. 按角色模型：
+
+```json
+{
+  "type": "per_role",
+  "default_model": "gpt-5.4",
+  "roles": {
+    "backend": "gpt-5.4",
+    "frontend": "gpt-5.4",
+    "reviewer": "gpt-5.3-codex"
+  }
+}
+```
+
+Manager 负责校验：
+
+```text
+模型是否存在
+用户套餐是否允许
+角色是否允许
+预算是否允许
+Runtime 是否支持
+```
+
+Manager 转给 agent_management：
+
+```json
+{
+  "agents": [
+    {
+      "role_template": "backend",
+      "default_model_id": "gpt-5.4"
+    },
+    {
+      "role_template": "frontend",
+      "default_model_id": "gpt-5.4"
+    }
+  ],
+  "billing_context": {
+    "provider": "newapi",
+    "default_model_id": "gpt-5.4",
+    "allowed_model_ids": ["gpt-5.4", "gpt-5.3-codex"],
+    "secret_ref": "azkv://..."
+  }
+}
+```
+
+### 8.2 Swarm 模型策略
+
+Swarm 模式只暴露主模型选择。
+
+客户端提交：
+
+```json
+{
+  "type": "primary",
+  "primary_model": "gpt-5.4"
+}
+```
+
+Manager 转给 HeiCode-Swarm：
+
+```json
+{
+  "primary_model": "gpt-5.4",
+  "model_policy": {
+    "strategy": "primary_model_controls_sub_agents",
+    "allowed_model_ids": ["gpt-5.4"],
+    "fallback_model_id": "gpt-5.4"
+  }
+}
+```
+
+含义：
+
+```text
+主模型负责 Swarm 编排和决策
+子 Agent 模型调用由 Swarm Runtime 按 model_policy 控制
+客户端不直接为每个 Swarm 子 Agent 选择模型
+```
+
+## 10. 状态标准
+
+### 10.1 云上云下交互状态约定
+
+Heicode 状态需要拆成三层：
+
+```text
+client_task_status
+= 客户端本地会话/交互状态
+
+cloud_deployment_status
+= Manager 侧云端部署状态
+
+runtime_execution_status
+= Runtime 实际执行状态
+```
+
+最终给用户展示的状态由 Manager 裁决：
+
+```text
+display_status
+= Manager 根据 client_task_status、cloud_deployment_status、runtime_execution_status 和结构化产物事实裁决后的展示状态
+```
+
+职责边界：
+
+```text
+客户端记录云下交互状态
+Runtime 上报云上执行事实
+Manager 维护云端部署状态并输出最终 display_status
+客户端只展示 Manager 返回的 display_status
+```
+
+### 10.2 三层状态关系
+
+```json
+{
+  "task_id": "task_xxx",
+  "conversation_id": "conv_xxx",
+  "mode": "sub_agile",
+  "client_task_status": "running",
+  "cloud_deployment_status": "running",
+  "runtime_execution_status": "completed",
+  "display_status": "needs_codegen",
+  "last_synced_at": "2026-06-01T10:00:00Z"
+}
+```
+
+说明：
+
+- `client_task_status` 只描述客户端本地交互状态。
+- `cloud_deployment_status` 描述 Manager 控制面的部署状态。
+- `runtime_execution_status` 描述 Runtime 实际执行状态。
+- `display_status` 是唯一展示给用户的最终状态。
+
+### 10.3 客户端任务状态
+
+```text
+drafting
+submitted
+syncing
+running
+waiting_input
+waiting_approval
+completed
+completed_without_deliverable
+needs_codegen
+failed
+stopped
+offline_pending
+```
+
+含义：
+
+| 状态 | 含义 |
+|---|---|
+| `drafting` | 用户正在输入，任务尚未提交 |
+| `submitted` | 需求已提交到 Manager |
+| `syncing` | 客户端正在同步 Manager 状态 |
+| `running` | 云端正在执行 |
+| `waiting_input` | 等待用户继续补充输入 |
+| `waiting_approval` | 等待用户审批 |
+| `completed` | Manager 判定有效完成 |
+| `completed_without_deliverable` | Manager 判定完成但无有效产物 |
+| `needs_codegen` | 只有方案/总结，需要继续生成代码 |
+| `failed` | 任务失败 |
+| `stopped` | 用户停止 |
+| `offline_pending` | 本地离线，等待恢复后同步 |
+
+客户端本地至少保存：
+
+```json
+{
+  "task_id": "task_xxx",
+  "conversation_id": "conv_xxx",
+  "deployment_id": "dep_xxx",
+  "mode": "sub_agile",
+  "client_task_status": "running",
+  "last_synced_at": "2026-06-01T10:00:00Z",
+  "pending_messages": []
+}
+```
+
+### 10.4 云端部署状态
+
+```text
+accepted
+queued
+runtime_syncing
+runtime_accepted
+running
+waiting_approval
+waiting_input
+completed
+completed_without_deliverable
+needs_codegen
+failed
+stopped
+```
+
+含义：
+
+| 状态 | 含义 |
+|---|---|
+| `accepted` | Manager 已接收任务 |
+| `queued` | 等待 Runtime 创建 |
+| `runtime_syncing` | 正在创建/同步 Runtime |
+| `runtime_accepted` | Runtime 已接受任务 |
+| `running` | Runtime 正在执行 |
+| `waiting_approval` | 等待审批 |
+| `waiting_input` | 等待用户补充输入 |
+| `completed` | Manager 判定有效完成 |
+| `completed_without_deliverable` | Runtime 完成但无有效产物 |
+| `needs_codegen` | 只有方案/总结，需要继续生成代码 |
+| `failed` | 执行失败 |
+| `stopped` | 已停止 |
+
+### 10.5 Runtime 执行状态
+
+Runtime 只报告执行事实，不做最终用户态裁决。
+
+```text
+initializing
+accepted
+running
+waiting_approval
+blocked
+completed
+failed
+stopped
+```
+
+Runtime 回调示例：
+
+```json
+{
+  "event_type": "deployment.status_changed",
+  "mode": "sub_agile",
+  "runtime_kind": "agent_management",
+  "deployment_id": "dep_xxx",
+  "runtime_deployment_id": "run_xxx",
+  "payload": {
+    "runtime_execution_status": "completed",
+    "phase": "development",
+    "deliverable": {
+      "has_deliverable": true,
+      "summary_only": false,
+      "artifact_ids": ["art_xxx"],
+      "files_modified": [],
+      "has_diff": false,
+      "commit_sha": ""
+    }
+  }
+}
+```
+
+### 10.6 状态裁决原则
+
+Runtime 只上报结构化事实：
+
+```json
+{
+  "runtime_status": "completed",
+  "deliverable": {
+    "has_deliverable": true,
+    "summary_only": false,
+    "artifact_ids": ["art_xxx"],
+    "files_modified": ["src/app.ts"],
+    "has_diff": true,
+    "commit_sha": ""
+  }
+}
+```
+
+Manager 负责最终裁决：
+
+```text
+有有效产物 -> completed
+只有总结 -> completed_without_deliverable 或 needs_codegen
+Runtime 失败 -> failed
+用户停止 -> stopped
+等待审批 -> waiting_approval
+```
+
+客户端只展示 Manager 裁决结果。
+
+裁决规则：
+
+| Runtime 状态/事实 | Manager display_status |
+|---|---|
+| `running` | `running` |
+| `waiting_approval` | `waiting_approval` |
+| `completed` + `has_deliverable=true` + `summary_only=false` | `completed` |
+| `completed` + `summary_only=true` | `completed_without_deliverable` 或 `needs_codegen` |
+| `completed` + 无 artifact | `completed_without_deliverable` 或 `needs_codegen` |
+| `failed` | `failed` |
+| `stopped` | `stopped` |
+
+### 10.7 云下到云上的同步流程
+
+客户端提交：
+
+```text
+drafting -> submitted -> syncing
+```
+
+Manager 接收：
+
+```text
+accepted -> queued -> runtime_syncing -> runtime_accepted -> running
+```
+
+Runtime 回调：
+
+```text
+running -> completed / failed / waiting_approval / blocked
+```
+
+Manager 裁决后客户端同步：
+
+```text
+syncing/running -> completed / failed / waiting_approval / needs_codegen
+```
+
+### 10.8 断网与重启恢复
+
+客户端本地必须保留：
+
+```text
+task_id
+conversation_id
+deployment_id
+mode
+last_synced_at
+pending_messages
+```
+
+客户端重新打开时：
+
+```text
+1. 读取本地最近任务。
+2. 对每个未终态任务调用 Manager 状态接口。
+3. Manager 返回 display_status 和 workflow。
+4. 客户端恢复聊天区和右侧 Workflow 面板。
+```
+
+如果本地存在未发送消息：
+
+```text
+client_task_status = offline_pending
+恢复网络后继续 POST /messages
+```
+
+## 11. 回调事件标准
+
+### 10.1 统一回调 Envelope
+
+```json
+{
+  "event_id": "evt_xxx",
+  "event_type": "artifact.created",
+  "mode": "sub_agile",
+  "runtime_kind": "agent_management",
+  "deployment_id": "dep_xxx",
+  "runtime_deployment_id": "run_xxx",
+  "task_id": "task_xxx",
+  "conversation_id": "conv_xxx",
+  "agent_instance_id": "agent_backend_1",
+  "agent_role": "backend",
+  "correlation_id": "corr_xxx",
+  "occurred_at": "2026-06-01T10:00:00Z",
+  "payload": {}
+}
+```
+
+### 10.2 Sub Agile 事件
+
+```text
+deployment.status_changed
+phase.changed
+timeline.updated
+agent.started
+agent.completed
+agent.failed
+task.completed
+task.failed
+task.blocked
+artifact.created
+budget.alert
+approval.requested
+approval.granted
+approval.rejected
+```
+
+### 10.3 Swarm 事件
+
+Swarm 在 Sub Agile 基础事件上增加：
+
+```text
+task.created
+task.claimed
+task.running
+task.heartbeat
+task.retried
+task.released
+handoff.requested
+handoff.completed
+handoff.failed
+```
+
+## 12. 产物标准
+
+### 12.0 产物落地形态：项目文件夹
+
+Heicode 的最终产物不应只以单个文本 artifact 呈现，而应以一个完整项目文件夹形式落地。
+
+标准产物形态：
+
+```text
+artifact_project
+= 一个可查看、可下载、可继续编辑、可再次上传同步的项目文件夹
+```
+
+示例：
+
+```text
+oracle-cloud-agency-site/
+├─ frontend/
+│  ├─ package.json
+│  ├─ src/
+│  │  ├─ App.tsx
+│  │  └─ main.tsx
+│  └─ README.md
+├─ backend/
+│  ├─ package.json
+│  ├─ src/
+│  │  ├─ main.ts
+│  │  └─ modules/
+│  └─ README.md
+├─ docs/
+│  ├─ architecture.md
+│  ├─ api.md
+│  └─ deploy.md
+├─ docker-compose.yml
+├─ .env.example
+└─ README.md
+```
+
+因此 Artifact 不再只表示“一个文件”，而应分为两级：
+
+```text
+Project Artifact
+  └─ File Artifacts / Directory Entries
+```
+
+用户在客户端看到的是项目文件夹，而不是一串重复的长文本。
+
+### 12.1 Artifact Schema
+
+```json
+{
+  "artifact_id": "art_xxx",
+  "artifact_type": "project_folder",
+  "title": "Oracle Cloud Agency Site",
+  "summary": "Oracle 云代理商网站项目，包含 frontend、backend、docs 和部署文件。",
+  "uri": "manager://tasks/task_xxx/artifacts/art_xxx",
+  "mime_type": "application/vnd.heicode.project+json",
+  "size_bytes": 123456,
+  "stage": "development",
+  "checkpoint": "artifact_ready",
+  "agent_role": "backend",
+  "created_at": "2026-06-01T10:00:00Z",
+  "metadata": {
+    "runtime_deployment_id": "run_xxx",
+    "content_hash": "sha256:xxx",
+    "download_path": "/api/heicode/sub-agile/tasks/task_xxx/artifacts/art_xxx/archive",
+    "manifest_path": "/api/heicode/sub-agile/tasks/task_xxx/artifacts/art_xxx/manifest",
+    "root_dir": "oracle-cloud-agency-site"
+  }
+}
+```
+
+### 12.2 Artifact Type
+
+```text
+project_folder
+project_archive
+code_patch
+code_bundle
+document
+test_report
+deployment_manifest
+log_bundle
+summary_only
+other
+```
+
+推荐规则：
+
+| 类型 | 含义 | 用途 |
+|---|---|---|
+| `project_folder` | 项目文件夹产物 | 默认最终交付形式 |
+| `project_archive` | 项目压缩包 | 下载整个项目 |
+| `code_patch` | 代码补丁 | 审查/增量更新 |
+| `code_bundle` | 代码包 | 较旧兼容形式 |
+| `document` | 文档 | PRD/架构/API 文档 |
+| `test_report` | 测试报告 | 验收 |
+| `deployment_manifest` | 部署清单 | 部署配置 |
+| `log_bundle` | 日志包 | 排障 |
+| `summary_only` | 仅总结 | 不应被视为完整交付 |
+
+### 12.3 项目产物 Manifest
+
+项目文件夹必须有 manifest，用于描述目录树、文件 hash、来源角色和下载信息。
+
+```json
+{
+  "artifact_id": "art_project_xxx",
+  "artifact_type": "project_folder",
+  "project_name": "oracle-cloud-agency-site",
+  "root_dir": "oracle-cloud-agency-site",
+  "revision": 1,
+  "content_hash": "sha256:project-tree-hash",
+  "entries": [
+    {
+      "path": "frontend/package.json",
+      "type": "file",
+      "mime_type": "application/json",
+      "size_bytes": 890,
+      "content_hash": "sha256:file1",
+      "source_agent_role": "frontend",
+      "content_path": "/api/heicode/sub-agile/tasks/task_xxx/artifacts/art_project_xxx/files/frontend/package.json"
+    },
+    {
+      "path": "backend/src/main.ts",
+      "type": "file",
+      "mime_type": "text/typescript",
+      "size_bytes": 2400,
+      "content_hash": "sha256:file2",
+      "source_agent_role": "backend",
+      "content_path": "/api/heicode/sub-agile/tasks/task_xxx/artifacts/art_project_xxx/files/backend/src/main.ts"
+    },
+    {
+      "path": "docs/architecture.md",
+      "type": "file",
+      "mime_type": "text/markdown",
+      "size_bytes": 6200,
+      "content_hash": "sha256:file3",
+      "source_agent_role": "architect",
+      "content_path": "/api/heicode/sub-agile/tasks/task_xxx/artifacts/art_project_xxx/files/docs/architecture.md"
+    }
+  ],
+  "archive": {
+    "format": "zip",
+    "download_path": "/api/heicode/sub-agile/tasks/task_xxx/artifacts/art_project_xxx/archive",
+    "size_bytes": 456789,
+    "content_hash": "sha256:ziphash"
+  }
+}
+```
+
+目录项字段：
+
+| 字段 | 含义 |
+|---|---|
+| `path` | 相对项目根目录路径 |
+| `type` | `file` 或 `directory` |
+| `mime_type` | 文件 MIME |
+| `size_bytes` | 文件大小 |
+| `content_hash` | 文件 hash |
+| `source_agent_role` | 产出该文件的角色 |
+| `content_path` | 文件内容读取接口 |
+
+### 12.4 项目产物读取
+
+客户端统一调用 Manager：
+
+```text
+GET /api/heicode/sub-agile/tasks/{task_id}/artifacts
+GET /api/heicode/sub-agile/tasks/{task_id}/artifacts/{artifact_id}/manifest
+GET /api/heicode/sub-agile/tasks/{task_id}/artifacts/{artifact_id}/files/{path}
+GET /api/heicode/sub-agile/tasks/{task_id}/artifacts/{artifact_id}/archive
+
+GET /api/heicode/swarm/tasks/{task_id}/artifacts
+GET /api/heicode/swarm/tasks/{task_id}/artifacts/{artifact_id}/manifest
+GET /api/heicode/swarm/tasks/{task_id}/artifacts/{artifact_id}/files/{path}
+GET /api/heicode/swarm/tasks/{task_id}/artifacts/{artifact_id}/archive
+```
+
+客户端能力：
+
+```text
+查看项目文件树
+点击文件查看内容
+下载单个文件
+下载整个项目 zip
+打开本地项目文件夹
+提交本地修改
+```
+
+### 12.5 产物读取兼容
+
+客户端统一调用 Manager：
+
+```text
+GET /api/heicode/sub-agile/tasks/{task_id}/artifacts
+GET /api/heicode/sub-agile/tasks/{task_id}/artifacts/{artifact_id}/content
+
+GET /api/heicode/swarm/tasks/{task_id}/artifacts
+GET /api/heicode/swarm/tasks/{task_id}/artifacts/{artifact_id}/content
+```
+
+客户端不要从 callback 或聊天气泡里读取完整产物。
+
+callback 的 `summary` 只用于摘要展示。
+
+完整内容以 content 接口返回为准。
+
+### 12.6 Runtime 产物回传要求
+
+Runtime 回传产物时，应优先回传项目 manifest，而不是只回传长文本 summary。
+
+`artifact.created` payload 示例：
+
+```json
+{
+  "artifact_id": "art_project_xxx",
+  "artifact_type": "project_folder",
+  "title": "Oracle Cloud Agency Site",
+  "summary": "包含 frontend、backend、docs 和部署配置的完整项目。",
+  "uri": "runtime://run_xxx/artifacts/art_project_xxx",
+  "mime_type": "application/vnd.heicode.project+json",
+  "size_bytes": 456789,
+  "stage": "development",
+  "checkpoint": "artifact_ready",
+  "metadata": {
+    "root_dir": "oracle-cloud-agency-site",
+    "manifest_uri": "runtime://run_xxx/artifacts/art_project_xxx/manifest",
+    "archive_uri": "runtime://run_xxx/artifacts/art_project_xxx/archive.zip",
+    "content_hash": "sha256:project-tree-hash",
+    "file_count": 42,
+    "directory_count": 8,
+    "source": "agent_management"
+  }
+}
+```
+
+对于 Sub Agile：
+
+```text
+frontend role 产出 frontend/
+backend role 产出 backend/
+architect/product/reviewer 产出 docs/
+ops 产出部署配置
+Manager 负责汇总为一个 project_folder artifact
+```
+
+对于 Swarm：
+
+```text
+Swarm Runtime 根据 task graph 汇总多个 task 产物
+最终仍归档成一个 project_folder artifact
+```
+
+### 12.7 本地产物修改与云端同步协议
+
+客户端用户可能会下载或打开产物后在本地修改。该修改不能默认被云端感知。
+
+必须明确：
+
+```text
+Runtime 生成产物 -> Manager 归档 -> 客户端查看/下载
+```
+
+这条链路是标准产物下发链路。
+
+但：
+
+```text
+用户本地修改产物 -> 云端自动读取 -> Runtime 自动回调
+```
+
+这条链路默认不存在。
+
+如果需要云端读取用户修改后的产物，客户端必须显式上传本地修改。
+
+#### 12.7.1 客户端上传本地修改
+
+Sub Agile：
+
+```text
+POST /api/heicode/sub-agile/tasks/{task_id}/artifacts/{artifact_id}/local-edits
+```
+
+Swarm：
+
+```text
+POST /api/heicode/swarm/tasks/{task_id}/artifacts/{artifact_id}/local-edits
+```
+
+请求体：
+
+```json
+{
+  "edit_id": "edit_xxx",
+  "base_artifact_id": "art_xxx",
+  "base_project_revision": 1,
+  "base_revision": 1,
+  "base_content_hash": "sha256:old",
+  "content_hash": "sha256:new",
+  "mime_type": "text/html",
+  "path": "frontend/src/App.tsx",
+  "filename": "App.tsx",
+  "content": "<html>...</html>",
+  "change_summary": "用户修改了首页标题和 CTA 文案",
+  "client_edited_at": "2026-06-01T18:00:00Z"
+}
+```
+
+大文件不建议直接传 `content`，应使用上传 URL 或文件上传接口：
+
+```text
+POST /api/heicode/sub-agile/tasks/{task_id}/artifacts/{artifact_id}/local-edits/upload-url
+POST /api/heicode/swarm/tasks/{task_id}/artifacts/{artifact_id}/local-edits/upload-url
+```
+
+如果用户修改了多个文件，客户端应提交 batch：
+
+```text
+POST /api/heicode/sub-agile/tasks/{task_id}/artifacts/{artifact_id}/local-edits/batch
+POST /api/heicode/swarm/tasks/{task_id}/artifacts/{artifact_id}/local-edits/batch
+```
+
+请求体：
+
+```json
+{
+  "edit_id": "edit_batch_xxx",
+  "base_artifact_id": "art_project_xxx",
+  "base_project_revision": 1,
+  "changes": [
+    {
+      "op": "update",
+      "path": "frontend/src/App.tsx",
+      "base_content_hash": "sha256:old1",
+      "content_hash": "sha256:new1",
+      "content": "..."
+    },
+    {
+      "op": "create",
+      "path": "frontend/src/components/Hero.tsx",
+      "content_hash": "sha256:new2",
+      "content": "..."
+    },
+    {
+      "op": "delete",
+      "path": "docs/old.md",
+      "base_content_hash": "sha256:old3"
+    }
+  ],
+  "change_summary": "用户本地调整前端首页结构"
+}
+```
+
+#### 12.7.2 Manager 保存 Artifact Revision
+
+Manager 收到本地修改后必须：
+
+1. 校验用户权限。
+2. 校验任务归属。
+3. 校验 `base_artifact_id`。
+4. 校验 `base_project_revision` 是否匹配当前项目基线版本。
+5. 校验每个文件的 `base_content_hash` 是否匹配当前基线版本。
+6. 保存为新的 project artifact revision。
+7. 标记来源为 `client_local_edit`。
+8. 重算项目 tree hash。
+9. 将该 revision 纳入后续执行基线。
+
+Revision 示例：
+
+```json
+{
+  "artifact_id": "art_xxx",
+  "revision": 2,
+  "project_revision": 2,
+  "source": "client_local_edit",
+  "base_artifact_id": "art_xxx",
+  "base_revision": 1,
+  "base_content_hash": "sha256:old",
+  "content_hash": "sha256:new",
+  "created_by": "user",
+  "created_at": "2026-06-01T18:00:00Z",
+  "change_summary": "用户修改了首页标题和 CTA 文案",
+  "status": "received"
+}
+```
+
+#### 12.7.3 冲突处理
+
+如果 `base_content_hash` 与云端最新 revision 不一致，说明用户基于旧版本修改。
+
+Manager 返回：
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "ARTIFACT_REVISION_CONFLICT",
+    "message": "本地产物基于旧版本修改，请先同步最新版本后再提交。",
+    "retryable": false
+  },
+  "data": {
+    "current_project_revision": 3,
+    "conflicts": [
+      {
+        "path": "frontend/src/App.tsx",
+        "client_base_hash": "sha256:old",
+        "current_content_hash": "sha256:latest"
+      }
+    ]
+  }
+}
+```
+
+客户端处理：
+
+```text
+提示用户存在版本冲突
+提供查看最新版本
+提供另存为新产物
+必要时提供重新合并
+```
+
+#### 12.7.4 Manager 转发 Runtime
+
+Manager 保存本地修改后，可以根据任务状态决定是否通知 Runtime。
+
+通知 Sub Agile Runtime：
+
+```text
+POST /api/agent/sub-agile/deployments/{deployment_id}/artifact-edits
+```
+
+通知 Swarm Runtime：
+
+```text
+POST /api/agent/swarm/deployments/{deployment_id}/artifact-edits
+```
+
+请求体：
+
+```json
+{
+  "event_type": "artifact.local_edit_received",
+  "task_id": "task_xxx",
+  "deployment_id": "dep_xxx",
+  "runtime_deployment_id": "run_xxx",
+  "artifact_id": "art_xxx",
+  "revision": 2,
+  "project_revision": 2,
+  "source": "client_local_edit",
+  "manifest_uri": "manager://tasks/task_xxx/artifacts/art_xxx/revisions/2/manifest",
+  "archive_uri": "manager://tasks/task_xxx/artifacts/art_xxx/revisions/2/archive",
+  "content_hash": "sha256:new",
+  "change_summary": "用户修改了首页标题和 CTA 文案",
+  "client_edited_at": "2026-06-01T18:00:00Z"
+}
+```
+
+Runtime 不应直接读取客户端本地文件。Runtime 只能通过 Manager 提供的 `manifest_uri`、`archive_uri` 或文件 content 代理接口读取新 revision。
+
+#### 12.7.5 Runtime 处理策略
+
+Runtime 收到本地修改后可以返回三种处理结果：
+
+| 策略 | 含义 |
+|---|---|
+| `accept` | 接受用户修改，作为新的执行基线 |
+| `review` | 让 Agent 审查用户修改 |
+| `continue` | 基于用户修改继续生成下一轮产物 |
+
+Runtime 回调 Manager：
+
+```json
+{
+  "event_id": "evt_xxx",
+  "event_type": "artifact.local_edit_applied",
+  "mode": "sub_agile",
+  "runtime_kind": "agent_management",
+  "deployment_id": "dep_xxx",
+  "runtime_deployment_id": "run_xxx",
+  "task_id": "task_xxx",
+  "payload": {
+    "artifact_id": "art_xxx",
+    "revision": 2,
+    "project_revision": 2,
+    "status": "accepted",
+    "strategy": "accept",
+    "content_hash": "sha256:new"
+  }
+}
+```
+
+如果 Runtime 审查后发现问题：
+
+```json
+{
+  "event_type": "artifact.local_edit_reviewed",
+  "payload": {
+    "artifact_id": "art_xxx",
+    "revision": 2,
+    "status": "needs_user_action",
+    "summary": "本地修改缺少必要配置项，请补充环境变量说明。"
+  }
+}
+```
+
+#### 12.7.6 新增事件类型
+
+本地产物修改相关事件：
+
+```text
+artifact.local_edit_received
+artifact.local_edit_stored
+artifact.local_edit_applied
+artifact.local_edit_reviewed
+artifact.local_edit_rejected
+artifact.revision_conflict
+```
+
+事件职责：
+
+| 事件 | 发送方 | 接收方 | 含义 |
+|---|---|---|---|
+| `artifact.local_edit_received` | Manager | Runtime | Manager 收到并保存用户本地修改 |
+| `artifact.local_edit_stored` | Manager | 客户端 | 本地修改已保存为新 revision |
+| `artifact.local_edit_applied` | Runtime | Manager | Runtime 已接受该 revision |
+| `artifact.local_edit_reviewed` | Runtime | Manager | Runtime 已审查该 revision |
+| `artifact.local_edit_rejected` | Runtime | Manager | Runtime 拒绝使用该 revision |
+| `artifact.revision_conflict` | Manager | 客户端 | 本地修改基于旧版本，存在冲突 |
+
+#### 12.7.7 客户端展示
+
+产物详情需要支持项目文件树和版本列表：
+
+```text
+oracle-cloud-agency-site/
+├─ frontend/
+├─ backend/
+├─ docs/
+└─ README.md
+
+版本 1：Runtime 生成项目文件夹
+版本 2：用户本地修改 frontend/src/App.tsx
+版本 3：Agent 基于用户修改继续生成
+```
+
+Revision 展示字段：
+
+```json
+{
+  "artifact_id": "art_xxx",
+  "revision": 2,
+  "project_revision": 2,
+  "source": "client_local_edit",
+  "content_hash": "sha256:new",
+  "created_at": "2026-06-01T18:00:00Z",
+  "created_by": "user",
+  "status": "accepted"
+}
+```
+
+客户端可提供：
+
+```text
+查看版本
+下载版本
+下载整个项目
+打开项目文件夹
+设为继续执行基线
+提交本地修改
+查看冲突
+另存为新产物
+```
+
+#### 12.7.8 后续执行基线
+
+Manager 必须维护每个 artifact 的当前有效 revision：
+
+```json
+{
+  "artifact_id": "art_xxx",
+  "current_revision": 2,
+  "current_project_revision": 2,
+  "current_content_hash": "sha256:new",
+  "current_source": "client_local_edit",
+  "accepted_by_runtime": true
+}
+```
+
+后续继续对话或继续执行时，Manager 生成 Runtime plan 必须引用最新 accepted revision：
+
+```json
+{
+  "artifact_context": [
+    {
+      "artifact_id": "art_xxx",
+      "revision": 2,
+      "project_revision": 2,
+      "manifest_uri": "manager://tasks/task_xxx/artifacts/art_xxx/revisions/2/manifest",
+      "archive_uri": "manager://tasks/task_xxx/artifacts/art_xxx/revisions/2/archive",
+      "content_hash": "sha256:new"
+    }
+  ]
+}
+```
+
+#### 12.7.9 最终原则
+
+```text
+产物落地以项目文件夹为准。
+用户本地修改项目文件夹不等于云端产物更新。
+客户端必须显式上传 local edit。
+Manager 保存 project artifact revision。
+Runtime 通过 Manager 读取 manifest/archive/file content。
+后续执行必须以最新 accepted project revision 为基线。
+```
+
+## 13. 日志标准
+
+所有服务统一日志字段：
+
+```json
+{
+  "timestamp": "2026-06-01T10:00:00Z",
+  "level": "info",
+  "mode": "sub_agile",
+  "task_id": "task_xxx",
+  "conversation_id": "conv_xxx",
+  "deployment_id": "dep_xxx",
+  "runtime_deployment_id": "run_xxx",
+  "runtime_kind": "agent_management",
+  "agent_role": "backend",
+  "event_type": "agent.completed",
+  "message": "Agent task completed",
+  "request_id": "model_request_xxx",
+  "correlation_id": "corr_xxx"
+}
+```
+
+Manager 给客户端返回两层日志：
+
+```json
+{
+  "user_logs": [
+    {
+      "time": "2026-06-01T10:00:00Z",
+      "level": "info",
+      "message": "子代理已开始执行"
+    }
+  ],
+  "debug_logs": [
+    {
+      "event_id": "evt_xxx",
+      "event_type": "agent.started",
+      "runtime_kind": "agent_management",
+      "runtime_deployment_id": "run_xxx",
+      "raw_payload": {}
+    }
+  ]
+}
+```
+
+普通用户默认只看 `user_logs`。
+
+开发者调试模式显示 `debug_logs`。
+
+## 14. 返回标准
+
+### 13.1 成功返回
+
+```json
+{
+  "success": true,
+  "data": {},
+  "error": null,
+  "trace": {
+    "task_id": "task_xxx",
+    "conversation_id": "conv_xxx",
+    "deployment_id": "dep_xxx",
+    "correlation_id": "corr_xxx"
+  }
+}
+```
+
+### 13.2 失败返回
+
+```json
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "MODEL_TIMEOUT",
+    "message": "模型服务响应超时，请稍后重试",
+    "retryable": true
+  },
+  "trace": {
+    "task_id": "task_xxx",
+    "conversation_id": "conv_xxx",
+    "deployment_id": "dep_xxx",
+    "correlation_id": "corr_xxx"
+  }
+}
+```
+
+错误提示原则：
+
+- 面向用户不展示 `newapi`、`API 原厂`、`上游供应商` 等内部字眼。
+- 调试信息放入 diagnostics，不直接展示给普通用户。
+
+## 15. 调试标准
+
+### 14.1 客户端调试面板
+
+建议展示：
+
+```text
+任务 ID
+会话 ID
+模式
+Manager Deployment ID
+Runtime 类型
+Runtime Deployment ID
+当前状态
+当前阶段
+最后事件
+最后错误
+模型
+模型 request_id
+产物数量
+回调数量
+```
+
+### 14.2 Manager 诊断接口
+
+```text
+GET /api/heicode/sub-agile/tasks/{task_id}/diagnostics
+GET /api/heicode/swarm/tasks/{task_id}/diagnostics
+```
+
+示例响应：
+
+```json
+{
+  "task_id": "task_xxx",
+  "conversation_id": "conv_xxx",
+  "mode": "sub_agile",
+  "runtime_kind": "agent_management",
+  "deployment_id": "dep_xxx",
+  "runtime_deployment_id": "run_xxx",
+  "status": "failed",
+  "phase": "development",
+  "last_error": {
+    "code": "MODEL_TIMEOUT",
+    "message": "模型服务响应超时",
+    "http_status": 504,
+    "model_request_id": "xxx",
+    "retryable": true
+  },
+  "counts": {
+    "events": 18,
+    "logs": 19,
+    "artifacts": 2,
+    "callbacks": 18
+  }
+}
+```
+
+### 14.3 Swarm 专属诊断
+
+Swarm 诊断额外包含：
+
+```json
+{
+  "graph": {
+    "total_tasks": 8,
+    "completed_tasks": 6,
+    "failed_tasks": 1,
+    "blocked_tasks": 1
+  },
+  "agents": [
+    {
+      "agent_id": "agent_backend_1",
+      "status": "running",
+      "current_task": "task_backend_api",
+      "last_heartbeat_at": "2026-06-01T10:00:00Z"
+    }
+  ],
+  "handoffs": [],
+  "retries": []
+}
+```
+
+## 16. 安全与审计
+
+Manager 统一负责：
+
+```text
+用户身份校验
+套餐校验
+模型权限校验
+预算校验
+资源绑定校验
+高危审批 gate
+secret_ref 格式校验
+审计落库
+```
+
+安全要求：
+
+1. 所有 secret 只能以 `azkv://` 等引用形式传递。
+2. 禁止明文 token、API key、私钥进入请求、日志、回调、artifact metadata。
+3. 高危操作必须先审批再下发 Runtime。
+4. Runtime 不应自行绕过 Manager 执行高危操作。
+5. 审计字段至少包含：
+
+```text
+who
+agent
+resource
+action
+time
+approval
+result
+correlation_id
+```
+
+## 17. 客户端生产约束与上线阻断项
+
+本节用于约束 Heicode 客户端生产行为，避免客户端侧 mock、旁路调用、假审批或错误认证导致云端能力看似可用但实际不可控。
+
+### 17.1 审批闭环必须调用 Manager
+
+客户端只负责展示审批请求，不能在本地直接判定审批成功。
+
+禁止行为：
+
+```text
+ApprovalDialog approve/reject 只修改本地状态
+installApprovalMock 在生产包启用
+Slice/mock 审批数据伪装成真实审批
+```
+
+标准流程：
+
+```text
+Runtime 请求审批
+  -> Manager 保存 approval request
+  -> 客户端展示审批弹窗
+  -> 用户点击批准/拒绝
+  -> 客户端 POST Manager 审批接口
+  -> Manager 校验权限/归属/requester!=approver
+  -> Manager 转发 Runtime
+  -> Runtime 回调审批结果
+  -> Manager 更新 display_status
+  -> 客户端刷新 UI
+```
+
+客户端接口建议：
+
+```text
+POST /api/heicode/sub-agile/tasks/{task_id}/approvals/{approval_id}/approve
+POST /api/heicode/sub-agile/tasks/{task_id}/approvals/{approval_id}/reject
+
+POST /api/heicode/swarm/tasks/{task_id}/approvals/{approval_id}/approve
+POST /api/heicode/swarm/tasks/{task_id}/approvals/{approval_id}/reject
+```
+
+Manager 必须校验：
+
+```text
+approval_id 属于当前用户可见任务
+deployment_id 属于当前用户
+requester != approver
+审批未过期
+审批目标资源属于该任务/用户/绑定范围
+```
+
+客户端只有在 Manager 返回成功后，才能将审批 UI 更新为已批准或已拒绝。
+
+### 17.2 生产包禁止 Mock 冒充 Live
+
+生产包禁止：
+
+```text
+installApprovalMock
+seeded fake tasks
+mock approvals
+mock Runtime events
+mock artifacts 冒充真实产物
+```
+
+开发环境允许 mock，但必须在 UI 明示：
+
+```text
+Mock Mode
+Seeded Data
+Local Demo
+```
+
+Live 环境必须满足：
+
+```text
+所有审批来自 Manager
+所有任务状态来自 Manager
+所有产物来自 Manager artifact/project 接口
+所有日志/事件来自 Manager 聚合接口
+```
+
+### 17.3 任务事件流必须归口 Manager
+
+客户端需要实时刷新任务、审批、日志和产物状态，但事件流必须由 Manager 提供。
+
+标准事件流：
+
+```text
+GET /api/heicode/sub-agile/tasks/{task_id}/events/stream
+GET /api/heicode/swarm/tasks/{task_id}/events/stream
+```
+
+事件流至少覆盖：
+
+```text
+display_status.changed
+workflow.updated
+phase.changed
+agent.started
+agent.completed
+agent.failed
+approval.requested
+approval.resolved
+artifact.created
+artifact.revision.created
+log.appended
+diagnostic.updated
+```
+
+客户端不应订阅：
+
+```text
+Runtime legacy SSE
+Runtime WebSocket
+/tasks
+/agents
+/handoffs
+/ws/{agent_id}
+```
+
+如果 Manager 暂未提供 SSE，客户端可以轮询 Manager：
+
+```text
+GET /api/heicode/sub-agile/tasks/{task_id}/workflow
+GET /api/heicode/swarm/tasks/{task_id}/workflow
+```
+
+但不能订阅不存在的事件流路由，也不能直接连 Runtime 绕过 Manager。
+
+### 17.4 认证与 Manager Base URL
+
+客户端任务接口认证必须与登录/设备配对体系一致。
+
+标准要求：
+
+```text
+任务接口使用 deviceToken 或 Manager 明确定义的会话 token
+Manager base URL 必须来自 preset / profile 配置
+禁止继续读取已清空或废弃的 mcpAuth.accessToken
+禁止硬编码 code.xinghanlab.com 作为任务默认上游
+```
+
+客户端每个任务请求建议携带：
+
+```text
+Authorization
+X-Heicode-Device-Id
+X-Heicode-Client-Version
+X-Heicode-Request-Id
+```
+
+Manager 返回认证失败时，客户端展示用户友好文案：
+
+```text
+登录状态已失效，请重新登录后继续。
+```
+
+客户端调试面板可显示：
+
+```text
+http_status
+request_id
+manager_base_url
+auth_source=deviceToken
+```
+
+但普通用户错误提示中不展示内部 token 名称。
+
+### 17.5 客户端禁止直连 Runtime
+
+生产客户端禁止直连：
+
+```text
+agent_management
+HeiCode-Swarm
+Swarm orchestrator
+Runtime /tasks
+Runtime /agents
+Runtime /handoffs
+Runtime /ws
+```
+
+所有任务、审批、日志、产物、调试信息必须走 Manager。
+
+允许的唯一调用方向：
+
+```text
+Heicode 客户端 -> heicode-mananger
+```
+
+禁止链路：
+
+```text
+Heicode 客户端 -> agent_management
+Heicode 客户端 -> HeiCode-Swarm
+Heicode 客户端 -> Swarm orchestrator /tasks
+Heicode 客户端 -> Runtime WebSocket
+```
+
+### 17.6 客户端禁止 inline secret_ref
+
+客户端不得直接提交任意 `secret_ref`、Key Vault 路径、API Key 或连接串。
+
+禁止请求：
+
+```json
+{
+  "resource_grants": [
+    {
+      "secret_ref": "azkv://some-vault/secrets/platform-key"
+    }
+  ]
+}
+```
+
+客户端只能提交资源绑定引用：
+
+```json
+{
+  "resource_bindings": [
+    {
+      "resource_binding_id": "rb_xxx",
+      "purpose": "deploy"
+    }
+  ]
+}
+```
+
+Manager 负责：
+
+```text
+根据 user_id 查询资源绑定
+校验 binding_scope
+生成 Runtime resource manifest
+注入合法 secret_ref
+审计资源授权
+```
+
+客户端只展示资源名称和授权状态，不展示 secret 路径。
+
+### 17.7 客户端状态只消费 Manager display_status
+
+客户端不得根据 Runtime 原始字段自行裁决完成状态。
+
+禁止：
+
+```text
+Runtime 返回 completed 后客户端直接显示已完成
+客户端用中文/英文正则判断是否代码产物
+客户端根据 artifact summary 判断是否有效交付
+```
+
+标准：
+
+```text
+客户端只展示 Manager 返回的 display_status
+客户端只展示 Manager 返回的 artifact/project manifest
+客户端只展示 Manager 返回的 diagnostics
+```
+
+### 17.8 上线阻断检查清单
+
+生产上线前客户端必须满足：
+
+| 检查项 | 要求 |
+|---|---|
+| 审批 | approve/reject 必须调用 Manager |
+| Mock | 生产包禁用 approval/task/artifact mock |
+| 事件流 | SSE 或轮询必须来自 Manager |
+| 认证 | 任务接口使用有效 deviceToken / Manager session |
+| Base URL | Manager 地址来自 preset/profile |
+| Runtime | 客户端不得直连 Runtime |
+| secret_ref | 客户端不得 inline secret_ref |
+| 状态 | 客户端只展示 Manager display_status |
+| 产物 | 客户端只通过 Manager artifact/project 接口读取 |
+| 调试 | 普通用户不展示内部供应商/网关字眼 |
+
+## 18. 云部署目标与部署生命周期协议
+
+本节用于提前定义项目产物部署到云端的扩展协议，适用于 Azure、阿里云、AWS 等云厂商。
+
+云部署是 `project_folder` 产物之后的下一阶段生命周期。
+
+```text
+project_folder artifact
+  -> 用户选择部署目标
+  -> Manager 校验权限/审批/凭证/预算
+  -> Deploy Worker 或 Runtime 执行部署
+  -> 回传部署状态、日志、URL、资源清单
+  -> Manager 归档 deployment_manifest
+  -> 客户端展示部署结果
+```
+
+客户端仍然只调用 Manager，不直接调用云厂商 API。
+
+### 18.1 部署目标能力发现
+
+Manager 提供部署目标能力接口：
+
+```text
+GET /api/heicode/deployment-targets
+```
+
+响应：
+
+```json
+{
+  "success": true,
+  "data": {
+    "targets": [
+      {
+        "id": "azure",
+        "name": "Azure",
+        "enabled": true,
+        "supports_preview": true,
+        "supports_production": true,
+        "requires_approval": true,
+        "credential_binding_required": true,
+        "regions": ["eastasia", "southeastasia", "westus"]
+      },
+      {
+        "id": "aliyun",
+        "name": "阿里云",
+        "enabled": false,
+        "supports_preview": true,
+        "supports_production": true,
+        "requires_approval": true,
+        "credential_binding_required": true
+      },
+      {
+        "id": "aws",
+        "name": "AWS",
+        "enabled": false,
+        "supports_preview": true,
+        "supports_production": true,
+        "requires_approval": true,
+        "credential_binding_required": true
+      }
+    ]
+  },
+  "error": null
+}
+```
+
+客户端据此展示：
+
+```text
+部署到 Azure
+部署到阿里云
+部署到 AWS
+暂不部署
+```
+
+### 18.2 项目产物部署 Manifest
+
+结构性代码项目需要预留部署目录：
+
+```text
+project-name/
+├─ frontend/
+├─ backend/
+├─ docs/
+├─ deploy/
+│  ├─ azure/
+│  │  ├─ bicep/
+│  │  └─ README.md
+│  ├─ aliyun/
+│  └─ aws/
+├─ docker-compose.yml
+├─ .env.example
+└─ heicode-artifact.json
+```
+
+`heicode-artifact.json` 中增加部署信息：
+
+```json
+{
+  "deployment": {
+    "deployable": true,
+    "targets": ["azure", "aliyun", "aws"],
+    "default_target": "azure",
+    "environments": ["preview", "production"],
+    "required_secrets": [
+      {
+        "key": "DATABASE_URL",
+        "required": true,
+        "description": "数据库连接字符串"
+      }
+    ],
+    "entrypoints": {
+      "frontend": "frontend",
+      "backend": "backend"
+    },
+    "commands": {
+      "build": "docker compose build",
+      "start": "docker compose up -d",
+      "test": "npm test"
+    }
+  }
+}
+```
+
+Manager 判断项目是否可部署时，应以该 manifest 和项目文件树为准。
+
+### 18.3 客户端发起部署
+
+Sub Agile：
+
+```text
+POST /api/heicode/sub-agile/tasks/{task_id}/deployments
+```
+
+Swarm：
+
+```text
+POST /api/heicode/swarm/tasks/{task_id}/deployments
+```
+
+请求：
+
+```json
+{
+  "artifact_id": "art_project_xxx",
+  "artifact_revision": 3,
+  "target": "azure",
+  "environment": "preview",
+  "region": "eastasia",
+  "deployment_mode": "managed",
+  "resource_binding_id": "rb_azure_xxx",
+  "options": {
+    "frontend": true,
+    "backend": true,
+    "database": "managed"
+  }
+}
+```
+
+客户端只传：
+
+```text
+artifact_id
+artifact_revision
+target
+environment
+region
+deployment_mode
+resource_binding_id
+options
+```
+
+客户端禁止传：
+
+```text
+云厂商 AccessKey
+云厂商 Secret
+subscription secret
+service principal secret
+连接串明文
+secret_ref
+```
+
+### 18.4 Manager 部署前校验
+
+Manager 必须校验：
+
+```text
+artifact 属于当前用户
+artifact_revision 是 latest accepted revision 或用户明确选择的 accepted revision
+artifact_type = project_folder
+manifest.deployment.deployable = true
+target 已启用
+environment 合法
+用户套餐允许云部署
+resource_binding_id 属于当前用户
+resource_binding_id 允许该 target/environment
+预算足够
+生产部署是否需要审批
+```
+
+如果是生产部署或高风险部署：
+
+```text
+display_status = waiting_approval
+```
+
+审批通过后才允许下发 Deploy Worker 或 Runtime。
+
+### 18.5 云凭证与资源绑定
+
+云凭证统一由 Manager 管理，客户端只引用资源绑定。
+
+资源绑定示例：
+
+```json
+{
+  "resource_binding_id": "rb_azure_xxx",
+  "provider": "azure",
+  "display_name": "Azure 测试订阅",
+  "scope": "subscription",
+  "allowed_environments": ["preview"],
+  "requires_approval_for": ["production"]
+}
+```
+
+Manager 内部映射：
+
+```text
+resource_binding_id -> secret_ref -> azkv://...
+```
+
+客户端永远不看到 `secret_ref`。
+
+### 18.6 部署状态
+
+新增部署生命周期状态：
+
+```text
+deployment_requested
+deployment_validating
+waiting_approval
+provisioning
+building
+deploying
+verifying
+deployed
+deployment_failed
+deployment_stopped
+rollback_requested
+rolling_back
+rolled_back
+rollback_failed
+```
+
+客户端展示文案：
+
+| 状态 | 用户文案 |
+|---|---|
+| `deployment_requested` | 已提交部署请求 |
+| `deployment_validating` | 正在校验部署配置 |
+| `waiting_approval` | 等待审批 |
+| `provisioning` | 正在创建云资源 |
+| `building` | 正在构建项目 |
+| `deploying` | 正在部署 |
+| `verifying` | 正在验证访问 |
+| `deployed` | 部署成功 |
+| `deployment_failed` | 部署失败 |
+| `deployment_stopped` | 部署已停止 |
+| `rolling_back` | 正在回滚 |
+| `rolled_back` | 已回滚 |
+| `rollback_failed` | 回滚失败 |
+
+### 18.7 部署事件
+
+部署事件通过统一 Runtime callback 或 Deploy Worker callback 回传 Manager：
+
+```text
+deployment.target.validated
+deployment.approval.required
+deployment.provisioning.started
+deployment.build.started
+deployment.deploy.started
+deployment.verify.started
+deployment.deployed
+deployment.failed
+deployment.rollback.started
+deployment.rollback.completed
+deployment.rollback.failed
+```
+
+`deployment.deployed` 示例：
+
+```json
+{
+  "event_id": "evt_deploy_xxx",
+  "event_type": "deployment.deployed",
+  "mode": "sub_agile",
+  "deployment_id": "dep_xxx",
+  "task_id": "task_xxx",
+  "payload": {
+    "target": "azure",
+    "environment": "preview",
+    "region": "eastasia",
+    "url": "https://oracle-site-preview.azurewebsites.net",
+    "artifact_id": "art_project_xxx",
+    "artifact_revision": 3,
+    "resources": [
+      {
+        "type": "app_service",
+        "name": "oracle-site-api",
+        "provider_resource_id": "/subscriptions/xxx/resourceGroups/..."
+      }
+    ],
+    "cost_estimate": {
+      "monthly_usd": 18.5
+    }
+  }
+}
+```
+
+### 18.8 部署结果产物
+
+部署成功后，Manager 生成新的 `deployment_manifest` artifact：
+
+```json
+{
+  "artifact_id": "art_deploy_xxx",
+  "artifact_type": "deployment_manifest",
+  "title": "Azure Preview Deployment",
+  "summary": "Oracle 云代理商网站已部署到 Azure preview 环境。",
+  "metadata": {
+    "target": "azure",
+    "environment": "preview",
+    "region": "eastasia",
+    "url": "https://oracle-site-preview.azurewebsites.net",
+    "resource_count": 5,
+    "cost_estimate_monthly_usd": 18.5,
+    "source_project_artifact_id": "art_project_xxx",
+    "source_project_revision": 3
+  }
+}
+```
+
+项目 artifact revision 记录部署信息：
+
+```json
+{
+  "artifact_id": "art_project_xxx",
+  "revision": 3,
+  "deployments": [
+    {
+      "deployment_run_id": "deploy_xxx",
+      "target": "azure",
+      "environment": "preview",
+      "status": "deployed",
+      "url": "https://oracle-site-preview.azurewebsites.net"
+    }
+  ]
+}
+```
+
+### 18.9 Provider Adapter 预留
+
+云厂商差异由 Provider Adapter 吸收。
+
+```text
+Deployment Provider Adapter
+├─ azure
+├─ aliyun
+├─ aws
+├─ tencent-cloud
+└─ custom
+```
+
+统一能力：
+
+```text
+validate()
+plan()
+provision()
+build()
+deploy()
+verify()
+rollback()
+destroy()
+```
+
+不同云厂商只实现 adapter，不改变客户端和 Manager 外部协议。
+
+### 18.10 客户端部署 UI
+
+客户端在项目产物详情中提供：
+
+```text
+部署
+选择云厂商
+选择环境 preview/production
+选择区域
+选择资源绑定
+查看费用预估
+提交审批
+查看部署日志
+打开部署地址
+回滚
+停止部署
+```
+
+客户端普通用户只看到：
+
+```text
+部署目标
+部署状态
+部署 URL
+费用预估
+部署日志摘要
+回滚入口
+```
+
+调试面板显示：
+
+```text
+deployment_run_id
+provider
+region
+resource_binding_id
+provider_resource_id
+callback_event_id
+request_id
+```
+
+### 18.11 云部署原则
+
+```text
+云部署必须基于 project_folder artifact 的 accepted revision。
+客户端只选择 target/environment/resource_binding_id。
+Manager 负责校验、审批、凭证解析、预算和审计。
+Runtime 或 Deploy Worker 负责执行 provider adapter。
+部署结果以 deployment_manifest artifact 和 deployment events 回传。
+生产部署必须支持审批和回滚。
+```
+
+## 19. 兼容策略
+
+旧接口保留一段时间：
+
+```text
+/api/agnet/*
+/api/swarms
+/api/agnet/callbacks/swarm-events
+```
+
+新接口：
+
+```text
+/api/agent/*
+/api/agent/sub-agile/*
+/api/agent/swarm/*
+/api/agent/callbacks/runtime-events
+```
+
+兼容期规则：
+
+1. 旧接口只做转发。
+2. 新文档只写新接口。
+3. 新客户端只调用新接口。
+4. Manager 内部保存时统一使用 `agent` 命名。
+5. 日志里可以记录 legacy route，但不展示给普通用户。
+
+## 20. 落地顺序
+
+### 阶段 1：接口与命名统一
+
+- 新增 `/api/agent/*`。
+- 新增 `/api/heicode/sub-agile/*`。
+- 新增 `/api/heicode/swarm/*`。
+- 旧 `/api/agnet/*` 和 `/api/swarms` 做兼容转发。
+
+### 阶段 2：模式路由统一
+
+- Manager 根据 `mode` 路由。
+- `sub_agile` 只走 agent_management。
+- `swarm` 只走 HeiCode-Swarm。
+
+### 阶段 3：模型策略统一
+
+- Sub Agile 支持用户自选模型和按角色模型。
+- Swarm 支持主模型。
+- Manager 统一校验模型权限、套餐和预算。
+
+### 阶段 4：状态与产物裁决统一
+
+- Runtime 上报结构化事实。
+- Manager 统一裁决最终状态。
+- 客户端只展示 Manager 结论。
+
+### 阶段 5：日志、回调、调试统一
+
+- Runtime callback 统一到 `/api/agent/callbacks/runtime-events`。
+- Manager 聚合 user logs 和 debug logs。
+- 客户端增加诊断面板。
+
+## 21. 最终链路
+
+### 21.1 Sub Agile
+
+```text
+Heicode 客户端
+  -> /api/heicode/sub-agile/tasks
+  -> heicode-mananger
+  -> /api/agent/sub-agile/deployments
+  -> agent_management
+  -> /api/agent/callbacks/runtime-events
+  -> heicode-mananger
+  -> 客户端查询状态/日志/产物
+```
+
+### 21.2 Swarm
+
+```text
+Heicode 客户端
+  -> /api/heicode/swarm/tasks
+  -> heicode-mananger
+  -> /api/agent/swarm/deployments
+  -> HeiCode-Swarm
+  -> /api/agent/callbacks/runtime-events
+  -> heicode-mananger
+  -> 客户端查询状态/日志/产物
+```
+
+## 22. 一句话总结
+
+```text
+Heicode 客户端只负责提需求和展示结果；
+heicode-mananger 统一接口、模型、路由、状态、产物和审计；
+agent_management 专门执行 Sub Agile；
+HeiCode-Swarm 专门执行 Swarm；
+新协议统一使用 agent，拆分 Sub Agile 和 Swarm 路由，不再复用 /api/swarms 表达两种模式。
+```
diff --git a/2026-06-01_计划分工.md b/2026-06-01_计划分工.md
deleted file mode 100644
index 1ec2e26..0000000
--- a/2026-06-01_计划分工.md
+++ /dev/null
@@ -1,338 +0,0 @@
-**一、系统分工**
-
-```text
-Heicode 客户端
-= 主 Agent / 用户交互层
-只负责发起任务、持续会话、展示状态、查看/下载产物
-
-heicode-mananger
-= 控制面 / 路由器 / 唯一裁判
-负责用户权限、任务记录、Runtime 路由、状态裁决、产物归档、审计
-
-agent_management
-= Sub Agile Runtime
-所有 Sub / Sub Agile / 普通 sub 模式都走这里
-
-HeiCode-Swarm
-= Swarm Runtime
-所有 Swarm / 蜂群模式都走这里
-```
-
-最重要的边界：
-
-```text
-客户端永远只调用 heicode-mananger
-客户端不直连 agent_management
-客户端不直连 HeiCode-Swarm
-```
-
-**二、模式路由**
-
-Manager 不能再根据 `/api/swarms` 判断是不是 Swarm，因为 `agent_management` 里 `/api/swarms` 只是普通 sub 的 Runtime 兼容入口。
-
-应该按任务模式路由：
-
-```text
-mode = sub_agile / sub / agile
-  -> agent_management
-
-mode = swarm
-  -> HeiCode-Swarm
-```
-
-建议 Manager 配置：
-
-```env
-SUB_RUNTIME_BASE_URL=http://agent-management
-SUB_RUNTIME_CREATE_PATH=/api/swarms
-
-SWARM_RUNTIME_BASE_URL=http://heicode-swarm
-SWARM_RUNTIME_CREATE_PATH=/api/swarms
-```
-
-也就是说，两个 Runtime 都可以有 `/api/swarms`，但 Manager 必须用 `mode` 决定请求哪个服务。
-
-**三、统一请求结构**
-
-客户端发给 Manager 时，必须明确模式和主 Agent 身份。
-
-Sub Agile：
-
-```json
-{
-  "mode": "sub_agile",
-  "sub_mode": "agile",
-  "client_role": "main_agent",
-  "task_id": "task_xxx",
-  "conversation_id": "conv_xxx"
-}
-```
-
-Swarm：
-
-```json
-{
-  "mode": "swarm",
-  "client_role": "main_agent",
-  "task_id": "task_xxx",
-  "conversation_id": "conv_xxx"
-}
-```
-
-Manager 转发 Runtime 时，补齐：
-
-```json
-{
-  "orchestration_plan": {
-    "objective": "用户任务",
-    "sub_mode": "agile",
-    "user_context": {},
-    "billing_context": {},
-    "agent_runtime": {},
-    "agents": [],
-    "metadata": {
-      "mode": "sub_agile",
-      "client_role": "main_agent",
-      "manager_deployment_id": "dep_xxx",
-      "correlation_id": "task_xxx_xxx"
-    }
-  },
-  "callback": {
-    "url": "https://code.xinghanlab.com/api/agnet/callbacks/swarm-events",
-    "signing_secret_ref": "azkv://..."
-  }
-}
-```
-
-**四、统一状态裁决**
-
-`heicodedebug` 里反复强调：Runtime 只输出“结构化真相”，Manager 才是唯一裁判。
-
-Runtime 不应该说“我 completed 所以就是完成”。它应该上报：
-
-```json
-{
-  "runtime_status": "completed",
-  "deliverable": {
-    "artifact_type": "code_patch",
-    "has_deliverable": true,
-    "summary_only": false,
-    "files_modified": ["src/app.ts"],
-    "has_diff": true,
-    "commit_sha": "",
-    "artifact_ids": ["art_xxx"]
-  },
-  "usage": {
-    "model_tokens": 2470,
-    "model_cost_usd": 0.03
-  }
-}
-```
-
-Manager 再判断最终用户看到的状态：
-
-```text
-有有效产物 -> completed
-只有总结，没有实际产物 -> completed_without_deliverable / needs_codegen
-Runtime 失败 -> failed
-用户停止 -> stopped
-等待审批 -> waiting_approval
-```
-
-这样客户端就不会再自己用正则判断“这是不是产物”。
-
-**五、统一产物协议**
-
-无论 Sub Agile 还是 Swarm，都统一走 Manager 的产物接口：
-
-```text
-GET /api/agnet/user/deployments/{deployment_id}/artifacts
-GET /api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content
-```
-
-Runtime 回调 `artifact.created` 只传摘要和 URI，不把完整内容塞进对话框。
-
-Artifact 标准字段：
-
-```json
-{
-  "artifact_id": "art_xxx",
-  "artifact_type": "code_patch",
-  "title": "Backend task delivery",
-  "summary": "摘要",
-  "uri": "runtime://swm_xxx/artifacts/art_xxx",
-  "mime_type": "text/plain",
-  "size_bytes": 12345,
-  "stage": "development",
-  "checkpoint": "artifact_ready",
-  "metadata": {
-    "runtime_deployment_id": "swm_xxx",
-    "agent_role": "backend",
-    "content_hash": "sha256:xxx",
-    "download_path": "/api/swarms/swm_xxx/artifacts/art_xxx/content"
-  }
-}
-```
-
-客户端只展示：
-- 产物列表
-- 查看详情
-- 下载
-
-不要再把完整产物重复塞进聊天气泡和侧边栏。
-
-**六、事件回调统一**
-
-统一回调入口可以继续用现有的：
-
-```text
-POST /api/agnet/callbacks/swarm-events
-```
-
-虽然名字里有 `swarm-events`，但它可以作为 Runtime 统一事件入口。后续可以加别名：
-
-```text
-POST /api/agnet/callbacks/runtime-events
-```
-
-标准事件分两层。
-
-Sub Agile 必须支持：
-
-```text
-deployment.status_changed
-phase.changed
-timeline.updated
-agent.started
-agent.completed
-agent.failed
-task.completed
-task.failed
-task.blocked
-artifact.created
-budget.alert
-approval.requested
-```
-
-Swarm 在此基础上增加：
-
-```text
-task.created
-task.claimed
-task.running
-task.heartbeat
-task.retried
-task.released
-handoff.requested
-handoff.completed
-```
-
-**七、客户端展示规则**
-
-客户端只按 `mode` 展示不同 UI：
-
-Sub Agile：
-
-```text
-阶段
-角色
-时间线
-产物
-审批
-用量
-```
-
-Swarm：
-
-```text
-阶段
-任务图
-Agent 节点
-handoff
-heartbeat
-blocked/retry
-产物
-审批
-用量
-```
-
-客户端不要展示：
-- 部署草稿 JSON
-- Runtime 内部 payload
-- `swarm_id` / `runtime_deployment_id`
-- callback 原始内容
-- Runtime 内部诊断给普通用户
-
-这些可以放到开发者诊断模式。
-
-**八、各项目需要做什么**
-
-`heicode-mananger`：
-
-```text
-1. 按 mode 路由 Runtime
-2. 成为唯一状态裁判
-3. 统一 artifact schema
-4. 统一 completed 判定
-5. 保存 deployment_id / runtime_deployment_id / runtime_kind
-6. 提供统一 artifacts/content 接口
-7. 不再依赖文本正则判断产物有效性
-```
-
-`agent_management`：
-
-```text
-1. 作为所有 Sub Agile 的 Runtime
-2. 接收 Manager 的普通 sub plan
-3. 生成 artifact.created
-4. 上报结构化 deliverable 字段
-5. 支持 content 下载路径
-6. 不把 summary-only 当成完整代码交付
-```
-
-`HeiCode-Swarm`：
-
-```text
-1. 只负责真正 Swarm 模式
-2. 提供 task graph / handoff / heartbeat / retry
-3. 也遵守统一 artifact / callback / usage schema
-4. 禁止绕过 Manager 的旁路调用成为生产主链路
-```
-
-`heicode-winos-release / heicode-macos-release`：
-
-```text
-1. 只调用 Manager
-2. 最近任务保存 mode / task_id / deployment_id / conversation_id
-3. Sub Agile 和 Swarm 显示分开
-4. 产物只从 Manager artifact content 接口查看和下载
-5. 不再本地裁决 completed 是否真实完成
-```
-
-**九、推荐落地顺序**
-
-```text
-第一步：定 mode 路由
-Sub Agile -> agent_management
-Swarm -> HeiCode-Swarm
-
-第二步：定状态机
-completed / failed / stopped / waiting_approval / completed_without_deliverable / needs_codegen
-
-第三步：定 artifact schema
-所有 Runtime 都按同一结构回调
-
-第四步：Manager 做唯一裁判
-Runtime 上报事实，Manager 输出结论
-
-第五步：客户端只消费 Manager 结论
-不再本地正则判断产物和完成状态
-```
-
-最终一句话方案：
-
-```text
-Sub Agile 和 Swarm 不合并 Runtime，只统一 Manager 对外协议；
-agent_management 是 Sub Agile 执行层，HeiCode-Swarm 是 Swarm 执行层；
-Manager 是唯一裁判，客户端是主 Agent 和展示层。
-```
\ No newline at end of file