Files

T

qinhao f542017ebc 更新 2026-06-01_heicode客户端相关定义.md

2026-06-01 09:44:20 +00:00

62 KiB

Raw Permalink Blame History

Heicode 客户端与 Agent Runtime 统一调用方案

版本：v0.1
日期：2026-06-01
范围：Heicode 客户端、heicode-mananger、agent_management、HeiCode-Swarm
基准：以 Heicode 客户端体验为基准，统一接口归口、模式路由、状态、日志、产物、回调和调试规范。

1. 背景与目标

当前 Heicode 体系中存在几个历史问题：

agnet 是拼写错误，后续标准命名应统一为 agent。
/api/swarms 被同时用于普通 Sub Agile 和真正 Swarm，造成语义混乱。
Runtime、Manager、客户端各自判断任务完成、产物有效性和状态，导致结论不一致。
客户端既要支持 Sub Agile，又要支持 Swarm，但两种模式的执行层、模型策略和展示方式不同。
所有接口需要归口到 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. 总体原则

客户端负责：提需求、选模式、选模型、持续对话、展示结果

Manager 负责：统一接口、模型校验、Runtime 路由、状态裁决、产物归档、审计

agent_management 负责：执行所有 Sub Agile / 普通 sub 模式

HeiCode-Swarm 负责：执行所有 Swarm / 蜂群模式

客户端永远只调用 Manager：

Heicode 客户端 -> heicode-mananger -> agent_management
Heicode 客户端 -> heicode-mananger -> HeiCode-Swarm

客户端禁止直接调用：

agent_management
HeiCode-Swarm
NewAPI
模型网关
Runtime artifact content 接口

3. 术语统一

3.1 拼写统一

历史错误命名：

agnet
Agnet

新标准命名：

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 和用户入口。

职责：

提出需求。
选择模式：Sub Agile 或 Swarm。
Sub Agile 模式支持选择模型。
Swarm 模式支持选择主模型。
维护持续会话。
展示 Manager 返回的状态、日志、时间线、审批、用量和产物。
支持查看和下载产物。
支持调试详情展示。

客户端本地任务会话建议保存：

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 路由器和唯一状态裁判。

职责：

接收客户端需求包。
根据模式路由 Runtime。
校验模型、套餐、预算、权限和资源绑定。
生成 Runtime 执行计划。
接收 Runtime 回调。
保存任务、会话、部署、事件、日志、产物和审计。
根据结构化事实裁决最终状态。
向客户端提供统一状态、日志、产物、调试接口。

Runtime 路由规则：

mode=sub_agile -> agent_management
mode=swarm     -> HeiCode-Swarm

4.3 agent_management

agent_management 是所有 Sub Agile / 普通 sub 模式的 Runtime。

职责：

接收 Manager 下发的 Sub Agile plan。
按角色执行任务。
支持 Manager 下发的用户自选模型。
生成真实 artifact。
向 Manager 回调阶段、日志、状态、产物、用量和审批事件。
上报结构化执行事实。

Sub Agile 角色示例：

product
architect
frontend
backend
reviewer
ops

4.4 HeiCode-Swarm

HeiCode-Swarm 是所有 Swarm / 蜂群模式的 Runtime。

职责：

接收 Manager 下发的 Swarm plan。
使用主模型进行编排和决策。
负责任务图、Agent claim、heartbeat、handoff、retry、blocked 等蜂群能力。
生成统一 artifact。
向 Manager 回调 Swarm 执行事件、状态、产物、用量和调试数据。

Swarm 不作为 Sub Agile Runtime 使用。

5. 路由设计

5.1 客户端到 Manager 路由

建议拆分客户端语义路由：

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

如果后端希望减少路由，也可以保留统一任务接口：

/api/heicode/tasks

但请求体必须包含：

{
  "mode": "sub_agile"
}

或：

{
  "mode": "swarm"
}

5.2 Manager 到 Runtime 路由

新标准路由应拆分为：

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}

映射关系：

/api/agent/sub-agile/* -> agent_management
/api/agent/swarm/*     -> HeiCode-Swarm

5.3 Runtime 到 Manager 回调路由

新标准回调：

POST /api/agent/callbacks/runtime-events

旧接口兼容：

POST /api/agnet/callbacks/swarm-events

旧接口只做兼容转发，新文档和新客户端以 /api/agent/callbacks/runtime-events 为准。

6. 能力发现接口

客户端启动时从 Manager 拉取模式和模型能力。

GET /api/heicode/capabilities

示例响应：

{
  "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. 客户端工作模式参考

参考图片目录：

C:\Users\Administrator\Desktop\heicode\doc\picture

图片体现的目标工作模式是：

聊天区 = 主 Agent 对用户的简洁叙述、关键动作、最终结果
右侧任务面板 = 后台 Workflow / Phases / Agents / Tokens / Tools / Time / Artifacts
后台任务 = 可异步运行，完成后可回到会话继续处理

这套体验可以作为 Heicode 客户端的模式基准。

7.1 工作区布局

客户端建议采用三层信息密度：

聊天主区
后台任务面板
调试详情面板

┌───────────────────────────────┬──────────────────────────────┐
│ 聊天主区                       │ Background Tasks / 我的任务   │
│                               │                              │
│ 用户需求                       │ Workflow: oracle-site        │
│ 主 Agent 说明                  │ Status: Running              │
│ 关键工具动作                   │ 4 Agents · 75.3k Tokens      │
│ 最终摘要                       │                              │
│ 产物入口                       │ Phases                       │
│                               │ - Content                    │
│ 输入框                         │   - backend                  │
│                               │   - frontend                 │
│                               │ - Review                     │
└───────────────────────────────┴──────────────────────────────┘

7.2 聊天主区展示原则

聊天主区只展示用户需要理解的内容：

我会用 Sub Agile 并行执行 backend/frontend 两个角色，然后合并产物。
已启动后台任务 oracle-site。
子代理已完成执行，已生成 2 个产物。
产物：Backend API 方案、Frontend 页面方案。

聊天区不展示：

完整部署草稿 JSON
Runtime 原始 callback
大量重复 artifact 正文
内部 routing payload
内部 service name
newapi / API 原厂 / 上游供应商字眼

7.3 后台任务面板

右侧任务面板用于承载 Workflow 细节。

通用字段：

{
  "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": []
}

面板展示：

Workflow 名称
模式：Sub Agile / Swarm
状态：Running / Completed / Failed
耗时
Agent 数量
Tokens
Tools
简短目标描述
Phases 折叠列表
Artifacts 入口
Debug 入口

7.4 Phase 展示

Phase 是右侧任务面板的主组织方式。

Sub Agile 推荐 Phase：

Plan
Design
Develop
Review
Deliver

Swarm 推荐 Phase：

Plan
Dispatch
Execute
Handoff
Review
Deliver

Phase 数据结构：

{
  "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 行展示：

Agent 名称
角色
状态
Tokens
Tools
耗时
产物数量

示例：

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 语义：

Ran workflow ai-intro-website
Used ScheduleWakeup
Background tasks
Finished

Heicode 可对齐为：

用户发送任务。
客户端立即显示“已启动后台任务”。
Manager 创建 deployment。
Runtime 异步执行。
客户端通过轮询或推送刷新右侧任务面板。
任务完成后，聊天区追加一条简洁总结。
用户可进入产物详情或继续对话。

状态流：

submitted -> accepted -> running -> completed
submitted -> accepted -> running -> waiting_approval -> running -> completed
submitted -> accepted -> running -> failed
submitted -> accepted -> running -> stopped

7.7 Workflow 与模式映射

客户端可以统一使用 Workflow 作为用户可见工作单元。

Sub Agile = role-based workflow
Swarm = graph-based workflow

Sub Agile 右侧面板：

Workflow
Status
Roles / Agents
Phases
Tokens
Tools
Artifacts

Swarm 右侧面板：

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 查询结果。

建议新增或在现有接口中返回：

GET /api/heicode/sub-agile/tasks/{task_id}/workflow
GET /api/heicode/swarm/tasks/{task_id}/workflow

返回结构：

{
  "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 客户端交互细节

建议交互：

右侧任务面板默认显示最近一个运行中 Workflow
已完成任务收起到 Finished
每个 Workflow 可展开 Phase
每个 Phase 可展开 Agent
Agent 行点击进入日志/产物
Artifact 点击查看详情
下载按钮从 Manager content 接口保存到本地
失败节点显示用户友好错误，调试按钮显示 request_id

与图片保持一致的展示文案：

Ran workflow oracle-site
工作流已在后台启动，正在并行执行 backend/frontend。
工作流已完成，已生成 2 个产物。
Workflow 执行情况

但 Heicode 里用户模式名称仍保持：

Sub Agile
Swarm

8. 需求包定义

客户端向 Manager 提交需求包，而不是提交 Runtime 原始参数。

7.1 Sub Agile 需求包

{
  "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 需求包

{
  "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 支持用户自选模型。

支持两种方式：

全局模型：

{
  "type": "default",
  "default_model": "gpt-5.4"
}

按角色模型：

{
  "type": "per_role",
  "default_model": "gpt-5.4",
  "roles": {
    "backend": "gpt-5.4",
    "frontend": "gpt-5.4",
    "reviewer": "gpt-5.3-codex"
  }
}

Manager 负责校验：

模型是否存在
用户套餐是否允许
角色是否允许
预算是否允许
Runtime 是否支持

Manager 转给 agent_management：

{
  "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 模式只暴露主模型选择。

客户端提交：

{
  "type": "primary",
  "primary_model": "gpt-5.4"
}

Manager 转给 HeiCode-Swarm：

{
  "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"
  }
}

含义：

主模型负责 Swarm 编排和决策
子 Agent 模型调用由 Swarm Runtime 按 model_policy 控制
客户端不直接为每个 Swarm 子 Agent 选择模型

10. 状态标准

10.1 云上云下交互状态约定

Heicode 状态需要拆成三层：

client_task_status
= 客户端本地会话/交互状态

cloud_deployment_status
= Manager 侧云端部署状态

runtime_execution_status
= Runtime 实际执行状态

最终给用户展示的状态由 Manager 裁决：

display_status
= Manager 根据 client_task_status、cloud_deployment_status、runtime_execution_status 和结构化产物事实裁决后的展示状态

职责边界：

客户端记录云下交互状态
Runtime 上报云上执行事实
Manager 维护云端部署状态并输出最终 display_status
客户端只展示 Manager 返回的 display_status

10.2 三层状态关系

{
  "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 客户端任务状态

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`	本地离线，等待恢复后同步

客户端本地至少保存：

{
  "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 云端部署状态

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 只报告执行事实，不做最终用户态裁决。

initializing
accepted
running
waiting_approval
blocked
completed
failed
stopped

Runtime 回调示例：

{
  "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 只上报结构化事实：

{
  "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 负责最终裁决：

有有效产物 -> 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 云下到云上的同步流程

客户端提交：

drafting -> submitted -> syncing

Manager 接收：

accepted -> queued -> runtime_syncing -> runtime_accepted -> running

Runtime 回调：

running -> completed / failed / waiting_approval / blocked

Manager 裁决后客户端同步：

syncing/running -> completed / failed / waiting_approval / needs_codegen

10.8 断网与重启恢复

客户端本地必须保留：

task_id
conversation_id
deployment_id
mode
last_synced_at
pending_messages

客户端重新打开时：

1. 读取本地最近任务。
2. 对每个未终态任务调用 Manager 状态接口。
3. Manager 返回 display_status 和 workflow。
4. 客户端恢复聊天区和右侧 Workflow 面板。

如果本地存在未发送消息：

client_task_status = offline_pending
恢复网络后继续 POST /messages

11. 回调事件标准

10.1 统一回调 Envelope

{
  "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 事件

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 基础事件上增加：

task.created
task.claimed
task.running
task.heartbeat
task.retried
task.released
handoff.requested
handoff.completed
handoff.failed

12. 产物标准

12.0 产物落地形态：项目文件夹

Heicode 的最终产物不应只以单个文本 artifact 呈现，而应以一个完整项目文件夹形式落地。

标准产物形态：

artifact_project
= 一个可查看、可下载、可继续编辑、可再次上传同步的项目文件夹

示例：

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 不再只表示“一个文件”，而应分为两级：

Project Artifact
  └─ File Artifacts / Directory Entries

用户在客户端看到的是项目文件夹，而不是一串重复的长文本。

12.1 Artifact Schema

{
  "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

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、来源角色和下载信息。

{
  "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：

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

客户端能力：

查看项目文件树
点击文件查看内容
下载单个文件
下载整个项目 zip
打开本地项目文件夹
提交本地修改

12.5 产物读取兼容

客户端统一调用 Manager：

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 示例：

{
  "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：

frontend role 产出 frontend/
backend role 产出 backend/
architect/product/reviewer 产出 docs/
ops 产出部署配置
Manager 负责汇总为一个 project_folder artifact

对于 Swarm：

Swarm Runtime 根据 task graph 汇总多个 task 产物
最终仍归档成一个 project_folder artifact

12.7 本地产物修改与云端同步协议

客户端用户可能会下载或打开产物后在本地修改。该修改不能默认被云端感知。

必须明确：

Runtime 生成产物 -> Manager 归档 -> 客户端查看/下载

这条链路是标准产物下发链路。

但：

用户本地修改产物 -> 云端自动读取 -> Runtime 自动回调

这条链路默认不存在。

如果需要云端读取用户修改后的产物，客户端必须显式上传本地修改。

12.7.1 客户端上传本地修改

Sub Agile：

POST /api/heicode/sub-agile/tasks/{task_id}/artifacts/{artifact_id}/local-edits

Swarm：

POST /api/heicode/swarm/tasks/{task_id}/artifacts/{artifact_id}/local-edits

请求体：

{
  "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 或文件上传接口：

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：

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

请求体：

{
  "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 收到本地修改后必须：

校验用户权限。
校验任务归属。
校验 base_artifact_id。
校验 base_project_revision 是否匹配当前项目基线版本。
校验每个文件的 base_content_hash 是否匹配当前基线版本。
保存为新的 project artifact revision。
标记来源为 client_local_edit。
重算项目 tree hash。
将该 revision 纳入后续执行基线。

Revision 示例：

{
  "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 返回：

{
  "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"
      }
    ]
  }
}

客户端处理：

提示用户存在版本冲突
提供查看最新版本
提供另存为新产物
必要时提供重新合并

12.7.4 Manager 转发 Runtime

Manager 保存本地修改后，可以根据任务状态决定是否通知 Runtime。

通知 Sub Agile Runtime：

POST /api/agent/sub-agile/deployments/{deployment_id}/artifact-edits

通知 Swarm Runtime：

POST /api/agent/swarm/deployments/{deployment_id}/artifact-edits

请求体：

{
  "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：

{
  "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 审查后发现问题：

{
  "event_type": "artifact.local_edit_reviewed",
  "payload": {
    "artifact_id": "art_xxx",
    "revision": 2,
    "status": "needs_user_action",
    "summary": "本地修改缺少必要配置项，请补充环境变量说明。"
  }
}

12.7.6 新增事件类型

本地产物修改相关事件：

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 客户端展示

产物详情需要支持项目文件树和版本列表：

oracle-cloud-agency-site/
├─ frontend/
├─ backend/
├─ docs/
└─ README.md

版本 1：Runtime 生成项目文件夹
版本 2：用户本地修改 frontend/src/App.tsx
版本 3：Agent 基于用户修改继续生成

Revision 展示字段：

{
  "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"
}

客户端可提供：

查看版本
下载版本
下载整个项目
打开项目文件夹
设为继续执行基线
提交本地修改
查看冲突
另存为新产物

12.7.8 后续执行基线

Manager 必须维护每个 artifact 的当前有效 revision：

{
  "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：

{
  "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 最终原则

产物落地以项目文件夹为准。
用户本地修改项目文件夹不等于云端产物更新。
客户端必须显式上传 local edit。
Manager 保存 project artifact revision。
Runtime 通过 Manager 读取 manifest/archive/file content。
后续执行必须以最新 accepted project revision 为基线。

13. 日志标准

所有服务统一日志字段：

{
  "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 给客户端返回两层日志：

{
  "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 成功返回

{
  "success": true,
  "data": {},
  "error": null,
  "trace": {
    "task_id": "task_xxx",
    "conversation_id": "conv_xxx",
    "deployment_id": "dep_xxx",
    "correlation_id": "corr_xxx"
  }
}

13.2 失败返回

{
  "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 客户端调试面板

建议展示：

任务 ID
会话 ID
模式
Manager Deployment ID
Runtime 类型
Runtime Deployment ID
当前状态
当前阶段
最后事件
最后错误
模型
模型 request_id
产物数量
回调数量

14.2 Manager 诊断接口

GET /api/heicode/sub-agile/tasks/{task_id}/diagnostics
GET /api/heicode/swarm/tasks/{task_id}/diagnostics

示例响应：

{
  "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 诊断额外包含：

{
  "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 统一负责：

用户身份校验
套餐校验
模型权限校验
预算校验
资源绑定校验
高危审批 gate
secret_ref 格式校验
审计落库

安全要求：

所有 secret 只能以 azkv:// 等引用形式传递。
禁止明文 token、API key、私钥进入请求、日志、回调、artifact metadata。
高危操作必须先审批再下发 Runtime。
Runtime 不应自行绕过 Manager 执行高危操作。
审计字段至少包含：

who
agent
resource
action
time
approval
result
correlation_id

17. 客户端生产约束与上线阻断项

本节用于约束 Heicode 客户端生产行为，避免客户端侧 mock、旁路调用、假审批或错误认证导致云端能力看似可用但实际不可控。

17.1 审批闭环必须调用 Manager

客户端只负责展示审批请求，不能在本地直接判定审批成功。

禁止行为：

ApprovalDialog approve/reject 只修改本地状态
installApprovalMock 在生产包启用
Slice/mock 审批数据伪装成真实审批

标准流程：

Runtime 请求审批
  -> Manager 保存 approval request
  -> 客户端展示审批弹窗
  -> 用户点击批准/拒绝
  -> 客户端 POST Manager 审批接口
  -> Manager 校验权限/归属/requester!=approver
  -> Manager 转发 Runtime
  -> Runtime 回调审批结果
  -> Manager 更新 display_status
  -> 客户端刷新 UI

客户端接口建议：

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 必须校验：

approval_id 属于当前用户可见任务
deployment_id 属于当前用户
requester != approver
审批未过期
审批目标资源属于该任务/用户/绑定范围

客户端只有在 Manager 返回成功后，才能将审批 UI 更新为已批准或已拒绝。

17.2 生产包禁止 Mock 冒充 Live

生产包禁止：

installApprovalMock
seeded fake tasks
mock approvals
mock Runtime events
mock artifacts 冒充真实产物

开发环境允许 mock，但必须在 UI 明示：

Mock Mode
Seeded Data
Local Demo

Live 环境必须满足：

所有审批来自 Manager
所有任务状态来自 Manager
所有产物来自 Manager artifact/project 接口
所有日志/事件来自 Manager 聚合接口

17.3 任务事件流必须归口 Manager

客户端需要实时刷新任务、审批、日志和产物状态，但事件流必须由 Manager 提供。

标准事件流：

GET /api/heicode/sub-agile/tasks/{task_id}/events/stream
GET /api/heicode/swarm/tasks/{task_id}/events/stream

事件流至少覆盖：

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

客户端不应订阅：

Runtime legacy SSE
Runtime WebSocket
/tasks
/agents
/handoffs
/ws/{agent_id}

如果 Manager 暂未提供 SSE，客户端可以轮询 Manager：

GET /api/heicode/sub-agile/tasks/{task_id}/workflow
GET /api/heicode/swarm/tasks/{task_id}/workflow

但不能订阅不存在的事件流路由，也不能直接连 Runtime 绕过 Manager。

17.4 认证与 Manager Base URL

客户端任务接口认证必须与登录/设备配对体系一致。

标准要求：

任务接口使用 deviceToken 或 Manager 明确定义的会话 token
Manager base URL 必须来自 preset / profile 配置
禁止继续读取已清空或废弃的 mcpAuth.accessToken
禁止硬编码 code.xinghanlab.com 作为任务默认上游

客户端每个任务请求建议携带：

Authorization
X-Heicode-Device-Id
X-Heicode-Client-Version
X-Heicode-Request-Id

Manager 返回认证失败时，客户端展示用户友好文案：

登录状态已失效，请重新登录后继续。

客户端调试面板可显示：

http_status
request_id
manager_base_url
auth_source=deviceToken

但普通用户错误提示中不展示内部 token 名称。

17.5 客户端禁止直连 Runtime

生产客户端禁止直连：

agent_management
HeiCode-Swarm
Swarm orchestrator
Runtime /tasks
Runtime /agents
Runtime /handoffs
Runtime /ws

所有任务、审批、日志、产物、调试信息必须走 Manager。

允许的唯一调用方向：

Heicode 客户端 -> heicode-mananger

禁止链路：

Heicode 客户端 -> agent_management
Heicode 客户端 -> HeiCode-Swarm
Heicode 客户端 -> Swarm orchestrator /tasks
Heicode 客户端 -> Runtime WebSocket

17.6 客户端禁止 inline secret_ref

客户端不得直接提交任意 secret_ref、Key Vault 路径、API Key 或连接串。

禁止请求：

{
  "resource_grants": [
    {
      "secret_ref": "azkv://some-vault/secrets/platform-key"
    }
  ]
}

客户端只能提交资源绑定引用：

{
  "resource_bindings": [
    {
      "resource_binding_id": "rb_xxx",
      "purpose": "deploy"
    }
  ]
}

Manager 负责：

根据 user_id 查询资源绑定
校验 binding_scope
生成 Runtime resource manifest
注入合法 secret_ref
审计资源授权

客户端只展示资源名称和授权状态，不展示 secret 路径。

17.7 客户端状态只消费 Manager display_status

客户端不得根据 Runtime 原始字段自行裁决完成状态。

禁止：

Runtime 返回 completed 后客户端直接显示已完成
客户端用中文/英文正则判断是否代码产物
客户端根据 artifact summary 判断是否有效交付

标准：

客户端只展示 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 产物之后的下一阶段生命周期。

project_folder artifact
  -> 用户选择部署目标
  -> Manager 校验权限/审批/凭证/预算
  -> Deploy Worker 或 Runtime 执行部署
  -> 回传部署状态、日志、URL、资源清单
  -> Manager 归档 deployment_manifest
  -> 客户端展示部署结果

客户端仍然只调用 Manager，不直接调用云厂商 API。

18.1 部署目标能力发现

Manager 提供部署目标能力接口：

GET /api/heicode/deployment-targets

响应：

{
  "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
}

客户端据此展示：

部署到 Azure
部署到阿里云
部署到 AWS
暂不部署

18.2 项目产物部署 Manifest

结构性代码项目需要预留部署目录：

project-name/
├─ frontend/
├─ backend/
├─ docs/
├─ deploy/
│  ├─ azure/
│  │  ├─ bicep/
│  │  └─ README.md
│  ├─ aliyun/
│  └─ aws/
├─ docker-compose.yml
├─ .env.example
└─ heicode-artifact.json

heicode-artifact.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：

POST /api/heicode/sub-agile/tasks/{task_id}/deployments

Swarm：

POST /api/heicode/swarm/tasks/{task_id}/deployments

请求：

{
  "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"
  }
}

客户端只传：

artifact_id
artifact_revision
target
environment
region
deployment_mode
resource_binding_id
options

客户端禁止传：

云厂商 AccessKey
云厂商 Secret
subscription secret
service principal secret
连接串明文
secret_ref

18.4 Manager 部署前校验

Manager 必须校验：

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
预算足够
生产部署是否需要审批

如果是生产部署或高风险部署：

display_status = waiting_approval

审批通过后才允许下发 Deploy Worker 或 Runtime。

18.5 云凭证与资源绑定

云凭证统一由 Manager 管理，客户端只引用资源绑定。

资源绑定示例：

{
  "resource_binding_id": "rb_azure_xxx",
  "provider": "azure",
  "display_name": "Azure 测试订阅",
  "scope": "subscription",
  "allowed_environments": ["preview"],
  "requires_approval_for": ["production"]
}

Manager 内部映射：

resource_binding_id -> secret_ref -> azkv://...

客户端永远不看到 secret_ref。

18.6 部署状态

新增部署生命周期状态：

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：

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 示例：

{
  "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：

{
  "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 记录部署信息：

{
  "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 吸收。

Deployment Provider Adapter
├─ azure
├─ aliyun
├─ aws
├─ tencent-cloud
└─ custom

统一能力：

validate()
plan()
provision()
build()
deploy()
verify()
rollback()
destroy()

不同云厂商只实现 adapter，不改变客户端和 Manager 外部协议。

18.10 客户端部署 UI

客户端在项目产物详情中提供：

部署
选择云厂商
选择环境 preview/production
选择区域
选择资源绑定
查看费用预估
提交审批
查看部署日志
打开部署地址
回滚
停止部署

客户端普通用户只看到：

部署目标
部署状态
部署 URL
费用预估
部署日志摘要
回滚入口

调试面板显示：

deployment_run_id
provider
region
resource_binding_id
provider_resource_id
callback_event_id
request_id

18.11 云部署原则

云部署必须基于 project_folder artifact 的 accepted revision。
客户端只选择 target/environment/resource_binding_id。
Manager 负责校验、审批、凭证解析、预算和审计。
Runtime 或 Deploy Worker 负责执行 provider adapter。
部署结果以 deployment_manifest artifact 和 deployment events 回传。
生产部署必须支持审批和回滚。

19. 兼容策略

旧接口保留一段时间：

/api/agnet/*
/api/swarms
/api/agnet/callbacks/swarm-events

新接口：

/api/agent/*
/api/agent/sub-agile/*
/api/agent/swarm/*
/api/agent/callbacks/runtime-events

兼容期规则：

旧接口只做转发。
新文档只写新接口。
新客户端只调用新接口。
Manager 内部保存时统一使用 agent 命名。
日志里可以记录 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

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

Heicode 客户端
  -> /api/heicode/swarm/tasks
  -> heicode-mananger
  -> /api/agent/swarm/deployments
  -> HeiCode-Swarm
  -> /api/agent/callbacks/runtime-events
  -> heicode-mananger
  -> 客户端查询状态/日志/产物

22. 一句话总结

Heicode 客户端只负责提需求和展示结果；
heicode-mananger 统一接口、模型、路由、状态、产物和审计；
agent_management 专门执行 Sub Agile；
HeiCode-Swarm 专门执行 Swarm；
新协议统一使用 agent，拆分 Sub Agile 和 Swarm 路由，不再复用 /api/swarms 表达两种模式。

62 KiB Raw Permalink Blame History Unescape Escape

Heicode 客户端与 Agent Runtime 统一调用方案

1. 背景与目标

2. 总体原则

3. 术语统一

3.1 拼写统一

3.2 模式定义

4. 系统分工

4.1 Heicode 客户端

4.2 heicode-mananger

4.3 agent_management

4.4 HeiCode-Swarm

5. 路由设计

5.1 客户端到 Manager 路由

5.2 Manager 到 Runtime 路由

5.3 Runtime 到 Manager 回调路由

6. 能力发现接口

7. 客户端工作模式参考

7.1 工作区布局

7.2 聊天主区展示原则

7.3 后台任务面板

7.4 Phase 展示

7.5 Agent 展示

7.6 异步后台任务

7.7 Workflow 与模式映射

7.8 聊天区与右侧面板的职责边界

7.9 对 Manager 的新增需求

7.10 客户端交互细节

8. 需求包定义

7.1 Sub Agile 需求包

7.2 Swarm 需求包

9. 模型策略

8.1 Sub Agile 模型策略

8.2 Swarm 模型策略

10. 状态标准

10.1 云上云下交互状态约定

10.2 三层状态关系

10.3 客户端任务状态

10.4 云端部署状态

10.5 Runtime 执行状态

10.6 状态裁决原则

10.7 云下到云上的同步流程

10.8 断网与重启恢复

11. 回调事件标准

10.1 统一回调 Envelope

10.2 Sub Agile 事件

10.3 Swarm 事件

12. 产物标准

12.0 产物落地形态：项目文件夹

12.1 Artifact Schema

12.2 Artifact Type

12.3 项目产物 Manifest

12.4 项目产物读取

12.5 产物读取兼容

12.6 Runtime 产物回传要求

12.7 本地产物修改与云端同步协议

12.7.1 客户端上传本地修改

12.7.2 Manager 保存 Artifact Revision

12.7.3 冲突处理

12.7.4 Manager 转发 Runtime

12.7.5 Runtime 处理策略

12.7.6 新增事件类型

12.7.7 客户端展示

12.7.8 后续执行基线

12.7.9 最终原则

13. 日志标准

14. 返回标准

13.1 成功返回

13.2 失败返回

15. 调试标准

14.1 客户端调试面板

14.2 Manager 诊断接口

14.3 Swarm 专属诊断

16. 安全与审计

17. 客户端生产约束与上线阻断项

17.1 审批闭环必须调用 Manager

17.2 生产包禁止 Mock 冒充 Live

17.3 任务事件流必须归口 Manager

17.4 认证与 Manager Base URL

17.5 客户端禁止直连 Runtime

62 KiB

Raw Permalink Blame History