# 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 表达两种模式。
```