heicode/docs/integration/heicode-desktop-sub-agile-api.md

Heicode 桌面客户端 sub 敏捷流程 API 对接文档

更新时间：2026-06-01 适用范围：Heicode Desktop / 本地服务对接 Heicode Manager，跑通普通 sub 模式敏捷开发流程。 Manager 生产地址：https://code.xinghanlab.com

0. 当前生产联调结论

截至 2026-05-31，普通 sub 敏捷链路已按生产地址完成端到端联调，并已用 Heicode Manager 生产入口复核 Runtime 新镜像修复后的真实生成链路：

项目	状态	生产验证
Manager 创建 deployment	已通过	POST /api/swarms 返回 Manager deployment 并写入 Runtime 映射
Agent Manager Runtime 执行	已通过	Runtime 返回 completed，backend Agent 返回 completed
模型调用	已通过	gpt-5.4 通过生产 NewAPI 调用成功，Runtime 回传 newapi_request_id
用量回传	已通过	Runtime metrics 返回 tokens_used=2682，日志包含 prompt/completion/total tokens
Callback / timeline	已通过	Manager 可查询 Runtime timeline、task.completed、sk_tool.completed、artifact.created 和状态
Artifact 列表	已通过	GET /artifacts 返回业务交付 artifact
Artifact 完整内容下载	已通过	GET /artifacts/{artifact_id}/content 返回 HTTP 200 和完整文本内容

本次真实生产烟测记录：

字段	值
deployment_id	dep_1d6d66896cc6
runtime_swarm_id	swm_03995f7c7a27
model	gpt-5.4
runtime_state	completed
tokens_used	2682
newapi_request_id	chatcmpl-DlbZce3VZnsv5DptBILFoiRYy5ZHN
artifact_id	art_swm_03995f7c7a27_backend_1
artifact_type	code_patch
artifact content	HTTP 200，text/plain; charset=utf-8，约 7.8 KB，内容为多文件 Python CLI 项目交付物

补充生产验证：

字段	值
runtime_swarm_id	swm_b60c8181bc79
objective	生成可运行的 Node.js Express REST API 小项目
artifact_id	art_swm_b60c8181bc79_backend_1
artifact_type	code_patch
tokens_used	2571
artifact content	HTTP 200，text/plain; charset=utf-8，约 8.2 KB，包含 package.json、src/index.js、README.md、test/smoke.test.js 的 markdown 多文件代码内容

重要修正：

1. 桌面客户端不要再使用 agent-model-builder、agent-model-reviewer、agent-model-product 这类占位模型名。生产 NewAPI 没有这些模型，会返回 No available channel for model ...。
2. 普通 sub 当前优先建议使用生产已复核通过的 gpt-5.4。claude-sonnet-4-6 仍可作为 NewAPI 模型存在，但当前普通 sub Runtime 若按普通 /v1/chat/completions 方式调用 Claude Code 类模型，可能返回上游 400；客户端不要把该错误误判为加密或 Manager 创建失败。
3. orchestration_plan.metadata.correlation_id 是创建 deployment 的必填字段，必须放在 orchestration_plan 内，不是顶层 metadata。
4. 成功态不能只看 status=completed。客户端还应确认 runtime_state=completed、artifacts.length > 0、artifact 不是失败摘要、tokens_used > 0，并优先展示可下载的业务交付物。
5. Runtime 日志已支持回传 newapi_request_id 和 model_usage。客户端应把这些字段展示在调试信息或错误详情中，便于定位模型调用问题。
6. artifact_type=code_patch 不一定代表已经拿到 zip/git 工程包；当前 Runtime 可能返回 .txt markdown 多文件代码。客户端必须按 content 内容继续分类展示，不要把 artifact 原文整段刷到聊天区。

1. 对接目标

桌面客户端负责用户主体验：输入想法、回答追问、持续推进任务、查看子环节反馈、处理高危审批、接收交付结果。

Manager 负责辅助控制面：任务草稿桥接、资源/权限、Agent deployment、状态/timeline/artifact/SK 查询、审批记录和短期凭证 lease。

本文只描述普通 sub 敏捷流程，不包含蜂群 task graph、claim、heartbeat、handoff 等蜂群模式能力。

2. 认证与公共约定

2.1 API 分组

API 前缀	用途	认证
/api/heicode-auth/api/user/tasks/*	HeicodeTask 任务编排代理，创建任务、追问、查询任务	V2 加密 body + Authorization: Bearer <heicode_access_token>
/api/agent/user/*	Manager 用户态 Agent 控制面，deployment、timeline、artifact、审批	V2 加密 body；未加密 Web 控制台请求继续使用 Manager session + New-Api-User
/api/swarms	蜂群模式创建入口 / Runtime adapter 入口	V2 加密 body；未加密 Web 控制台请求继续使用 Manager session + New-Api-User
/api/user/self	查询当前 Manager 用户	Manager 登录 session cookie

2.2 桌面端请求 body 加密

桌面客户端调用 Manager 的 sub / 蜂群入口时，应使用与模型调用一致的 V2 加密请求协议。普通 sub 用户态接口在生产 Manager 1.4.7+ 已支持；POST /api/swarms 蜂群入口在本次 Manager 代码中补齐同一套 V2 body 加密鉴权，需随下一次生产部署生效。

适用接口：

API 前缀	V2 加密 body	说明
/api/agent/user/*	支持	Manager 解密并校验设备签名后，按当前设备对应用户执行
/api/swarms	支持	Manager 解密并校验设备签名后，按当前设备对应用户创建蜂群/Runtime adapter deployment
/api/heicode-auth/*	支持	Manager 解密并校验设备签名后，把明文 body 代理给上游 HeicodeTask 服务；仍需携带 heicode_access_token
浏览器后台普通页面请求	兼容未加密 JSON	不影响现有 Manager Web 控制台

V2 请求头与模型调用一致：

Content-Encoding: heicode-aead-v1
X-Heicode-Device-Id: <device_id>
X-Heicode-Timestamp: <unix_ms>
X-Heicode-Nonce: <nonce_hex>
X-Heicode-Fingerprint: <device_fingerprint>
X-Heicode-Eph-Pubkey: <base64_x25519_ephemeral_pubkey>
X-Heicode-Signature: <base64_ed25519_signature>
X-Heicode-Client-Version: <desktop_version>
Content-Type: application/json
Accept: application/json

加密和签名协议沿用模型调用：

body = nonce || ChaCha20-Poly1305(plaintext_json, aad)
aad = device_id + "|" + timestamp + "|" + nonce + "|" + method + "|" + path_with_query

canonical = method + "\n"
          + path_with_query + "\n"
          + timestamp_ms + "\n"
          + nonce_hex + "\n"
          + device_fingerprint + "\n"
          + ephemeral_pubkey_b64 + "\n"
          + sha256_hex(plaintext_body)

signature = base64(ed25519_sign(device_private_key, sha256(canonical)))

/api/heicode-auth/* 额外要求：

Authorization: Bearer <heicode_access_token>

原因：该 token 是上游 HeicodeTask 服务认证用；V2 设备签名只证明请求来自已配对的 Manager 桌面设备。

客户端实现要求：

1. sub 流程调用不要新增一套加密协议，直接复用模型调用的 encryptedFetch / V2 设备签名实现。
2. aad 和 canonical 中的 path_with_query 必须是 Manager 实际收到的 path，例如 /api/agent/user/tasks/task-1/deployment-draft，不能把 origin 写进去。
3. 加密前的 plaintext 必须是最终 JSON body；签名里的 sha256_hex(plaintext_body) 必须和该 JSON 字节完全一致。
4. 每次请求必须使用新的 X-Heicode-Nonce 和新的 X25519 ephemeral key。
5. V2 请求失败时优先读取 X-Heicode-Auth-Error 和 X-Heicode-Server-Time，用于提示设备未配对、时间漂移、nonce 重放、签名错误或解密失败。

2.3 Manager 用户态 Header

未加密 Web 控制台请求调用 /api/agent/user/* 或 /api/swarms 时必须带：

Cookie: session=<manager-session>
New-Api-User: <manager_user_id>
Content-Type: application/json
Accept: application/json

New-Api-User 必须等于当前登录用户 ID，否则会返回未授权。

使用 V2 加密 body 时，/api/agent/user/* 和 /api/swarms 不依赖浏览器 session cookie，也不需要 New-Api-User；Manager 会从设备绑定 token 中解析用户身份。为兼容当前 Web 控制台，未加密请求仍按 session cookie + New-Api-User 处理。

2.4 蜂群入口加密边界

蜂群模式的业务流程与普通 sub 敏捷流程分开对接，但客户端到 Manager 的请求加密规则一致。

接口	所属模式	加密要求
POST /api/agent/user/tasks/{task_id}/deployment-draft	普通 sub 敏捷	V2 body 加密
POST /api/agent/user/deployments	普通 sub 敏捷	V2 body 加密
POST /api/swarms	蜂群模式	V2 body 加密

注意：本文后续章节仍只描述普通 sub 敏捷主流程；蜂群 task graph、claim、heartbeat、handoff、approval decision 等字段以单独蜂群对接文档为准。

2.5 统一响应 Envelope

成功：

{
  "success": true,
  "message": "",
  "data": {}
}

失败：

{
  "success": false,
  "message": "human readable message",
  "error": {
    "code": "ERROR_CODE",
    "message": "human readable message"
  }
}

3. 推荐完整流程

1. 桌面端确认 Manager 登录态，获取 /api/user/self
2. 创建 HeicodeTask：POST /api/heicode-auth/api/user/tasks/intent
3. 如果 status=configuring，回答追问：POST /api/heicode-auth/api/user/tasks/{task_id}/answer
4. 当任务卡生成后，创建 deployment draft：POST /api/agent/user/tasks/{task_id}/deployment-draft
5. 创建 Manager deployment：POST /api/agent/user/deployments
6. 轮询 deployment detail / events / timeline
7. 查询 runtime-diagnostics，区分 callback 已到、Runtime 状态、失败 Agent 和兜底摘要 artifact
8. 查询 artifacts 列表；如果需要完整文件，调用 artifact content 代理接口下载
9. 展示 sk-snapshots / logs / metrics
10. 如出现 approval，桌面端展示审批并调用 approve/reject
11. 完成后继续迭代或停止 deployment

3.1 Runtime 诊断接口

客户端展示普通 sub 结果时，不能只看 deployment status=completed。Manager 已提供只读诊断接口，用来识别 Runtime 是否真的完成、是否有 failed agent、是否只返回兜底摘要 artifact。

GET /api/agent/user/deployments/{deployment_id}/runtime-diagnostics

返回核心字段：

字段	说明
runtime_mode	agent 表示普通 sub Runtime；swarm 表示蜂群 Runtime
runtime_swarm_id / runtime_deployment_id	Manager 保存的 Runtime 映射
data_source	当前诊断来源，正常为 runtime_status
status / phase	Runtime 直接返回的状态和阶段
agents	Runtime 返回的 Agent 状态列表
artifacts	Runtime status 里的产物摘要
metrics	Runtime status 里的 usage/耗时等指标
warnings	Manager 根据 Runtime status 识别出的异常

常见 warnings：

warning	客户端展示含义
runtime_agent_failed	存在失败 Agent，不能把任务说成完整交付
runtime_completed_with_failed_agents	Runtime 总状态 completed，但内部 Agent 有失败，需要提示“执行异常完成”
runtime_summary_artifact_only	只有 Runtime execution summary 兜底摘要，不是最终业务交付物
runtime_zero_model_usage	Runtime 回传模型 token 为 0，说明 Agent 可能没有真实调用模型
runtime_status_query_failed	Manager 无法查询 Runtime status，只能展示已落库 callback

客户端建议：

1. deployment detail / timeline / artifacts 仍按原接口展示。
2. 若 warnings 包含 runtime_summary_artifact_only，需要提示“当前没有最终交付产物，请查看运行日志/等待 Runtime 修复”。
3. 若 runtime_mode=agent，按普通 sub 敏捷展示；若 runtime_mode=swarm，按蜂群模式展示任务图/Agent 编队，不能混用两套文案。
4. 该接口只读，失败时不应中断已有 timeline/artifact 展示。

3.2 Artifact 完整内容下载

普通 sub 的 artifact.created callback 只保存摘要、URI、大小、hash 和 metadata。客户端或 Manager 页面需要完整产物正文时，先查列表，再走 Manager 用户态 content 代理接口，不要直接暴露 Blob 凭据、SAS URL 或 Runtime 内网地址。

列表：

GET /api/agent/user/deployments/{deployment_id}/artifacts

下载：

GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content

Manager 行为：

1. 校验当前用户拥有该 deployment_id。
2. 校验 artifact_id 属于该 deployment。
3. 使用 deployment 里保存的 runtime_swarm_id / runtime_deployment_id 请求 Runtime： GET /api/swarms/{swarm_id}/artifacts/{artifact_id}/content。
4. 透传 Runtime 返回的文件内容、Content-Type、Content-Disposition 等安全响应头。
5. 如果 Runtime 未配置、artifact 不存在或 Runtime 返回错误，返回业务错误，不伪造内容。

页面说明：

• Manager Web 任务总览中的 artifact 卡片会显示“下载产物”。
• 如果 artifact 是 Runtime execution summary 兜底摘要，页面会明确提示它不是最终业务交付物。

3.3 Artifact 展示和有效性判断

桌面客户端不要把 artifact content 原文直接追加到聊天流里。聊天区只展示简短结论，完整产物放在右侧“交付产物”区域或独立详情页中。

推荐聊天区文案：

Sub Agile 执行完成，已生成 2 个交付产物：

- 前端交付物
- 后端交付物

请在右侧“交付产物”中查看、下载或应用到工作区。

artifact 展示规则：

情况	客户端展示	是否算代码交付
artifact_type=code_bundle，content 是 zip/tar 或 metadata 有 git branch / commit	显示“工程包”，提供下载 / 解压 / 应用到工作区	是
artifact_type=code_patch，content 是 diff/patch	显示“代码补丁”，提供查看 diff / 应用补丁	是
artifact_type=code_patch，content 是 markdown 多文件代码块，包含 package.json、src/...、启动命令	显示“代码文档”，提供拆分文件 / 复制 / 保存到工作区	部分算，不能当作完整工程包
artifact_type=document	显示“方案文档”	否
content 以“以下是作为 Frontend 角色”“交付物总结”“交付物摘要”等开头，且只有方案描述	显示“方案总结，不是代码交付物”	否
title 为 Runtime execution failed 或 Runtime execution summary	显示失败或兜底摘要	否

客户端分类建议：

function classifyArtifact(item: Artifact, content: string, contentType?: string) {
  const lowerType = (item.artifact_type || '').toLowerCase()
  const isZip = contentType?.includes('application/zip')
  const hasGitRef = /https?:\/\/\S+\.git|git@|branch|commit/i.test(content)
  const hasPatch = /^diff --git /m.test(content) || /^--- a\//m.test(content)
  const hasCodeProject =
    content.includes('package.json') &&
    /src\/[\w./-]+\.(js|ts|tsx|jsx|go|py)/.test(content)
  const summaryOnly =
    /以下是作为.*角色|交付物总结|交付物摘要|实现规划|目录建议/.test(content) &&
    !hasPatch &&
    !hasCodeProject

  if (isZip || lowerType === 'code_bundle' || hasGitRef) return 'code_bundle'
  if (hasPatch) return 'code_patch'
  if (hasCodeProject) return 'code_document'
  if (summaryOnly) return 'summary_only'
  if (lowerType === 'document') return 'document'
  return 'unknown'
}

展示要求：

1. summary 只作为卡片摘要，不要整段写进聊天。
2. uri / metadata.download_path 只作为下载依据，不直接暴露给用户；客户端通过 Manager content 代理获取正文。
3. 对用户要求“写代码 / 做网站 / 做前后端分离项目”的任务，只有 code_bundle、code_patch、code_document 可视为代码产出；summary_only 需要提示“Runtime 只返回了方案总结，需要继续生成代码”。
4. 如果 content 是 markdown 多文件代码，客户端可提供“保存到工作区”能力：按标题 ## package.json、## src/index.js 等拆分文件；拆分前必须让用户确认目标目录，避免覆盖本地文件。
5. 如果 content 是 zip/git branch/patch，优先提供下载 / 应用按钮，而不是直接展示全部正文。

3.4 2026-05-28 生产验证结果

本节记录已经按“桌面客户端应调用的顺序”在生产环境跑过的结果，客户端可按同一顺序和参数形状对接。

生产环境：

项	值
Manager	https://code.xinghanlab.com
Manager 版本	1.4.19
Agent Manager Runtime	http://20.212.121.126
Runtime health	healthy
Manager callback	https://code.xinghanlab.com/api/agent/callbacks/swarm-events

已验证成功的链路：

Manager 登录
-> /api/user/self
-> /api/agent/runtime/health
-> /api/agent/user/tasks/{task_id}/deployment-draft
-> /api/agent/user/deployments
-> Manager 调 Agent Manager Runtime create
-> Runtime 自动 callback 到 Manager
-> /api/agent/user/deployments/{deployment_id}
-> /api/agent/user/deployments/{deployment_id}/metrics
-> /api/agent/user/deployments/{deployment_id}/events
-> /api/agent/user/deployments/{deployment_id}/logs
-> /api/agent/user/deployments/{deployment_id}/artifacts
-> /api/agent/user/deployments/{deployment_id}/sk-snapshots
-> /api/agent/user/deployments/{deployment_id}/timeline
-> /api/agent/user/deployments/{deployment_id}/stop

最新生产烟测 ID：

对象	ID / 结果
Manager deployment	dep_1d6d66896cc6
Runtime swarm	swm_03995f7c7a27
detail status	completed
detail phase	deploy
runtime_state	completed
agent state	completed
model	gpt-5.4
tokens_used	2682
newapi_request_id	chatcmpl-DlbZce3VZnsv5DptBILFoiRYy5ZHN
artifact	art_swm_03995f7c7a27_backend_1，code_patch

已确认事实：

• Manager 端普通 sub 控制面已经可创建 deployment、调用 Runtime、接收 callback、反写 deployment 状态、聚合 events/timeline。
• Manager 端 callback 支持 HMAC 和旧 token 两种校验；生产当前 HMAC fallback 和 legacy token 均使用同一个值，由运维私下提供给 Agent Manager，不写入本文。
• Agent Manager / Runtime 新镜像已完成真实业务 artifact、非零 usage、newapi_request_id 和 Runtime 日志回传的生产复核。高危审批闭环仍需按真实高危任务单独验收。

本次未由 Codex 直接跑通的步骤：

步骤	结果	原因	客户端要求
POST /api/heicode-auth/api/user/tasks/intent	401	Codex 没有桌面客户端持有的 heicode_access_token	客户端必须带 Authorization: Bearer <heicode_access_token>

说明：

• 如果客户端已经有 HeicodeTask snapshot，可以直接从 deployment-draft 开始跑，生产已验证可通。
• 如果客户端需要从自然语言创建任务，必须先完成 Heicode 登录并拿到 heicode_access_token。
• 当前 create / callback / detail / metrics / events / timeline / artifacts / artifact content 已真实有效；SK snapshots 需要 Runtime 在真实任务中回写 sk_tool.* 或 snapshot 字段后才会有数据。

3.5 桌面客户端联调结论

普通 sub 模式可以开始桌面客户端联调。建议先按 Windows 最新客户端跑通，因为生产已有 Windows 设备绑定记录；macOS 端必须先确认客户端版本和 Keychain 凭据。

项	当前结论	客户端动作
Windows 设备绑定	生产已有 windows 设备绑定记录	可直接按本文流程联调
macOS 设备绑定	生产库当前没有 darwin/macOS 设备绑定记录	升级到最新 macOS 包，清理 Keychain 中旧 Heicode 凭据后重新登录
用户模型列表	Manager 端真实 token 请求 /v1/models 正常	���果桌面端 401，优先排查本地 token / device pair，不要先改模型配置
普通 sub POST 请求	Manager 支持 V2 body 加密	复用模型调用的 encryptedFetch
普通 sub GET 查询	当前仍建议使用 session + New-Api-User 兼容路径	后续如需完全无 cookie，再补无 body 签名 GET 协议

4. 当前用户信息

GET /api/user/self

获取当前 Manager 登录用户，用于拿 id 并设置 New-Api-User。

响应关键字段：

{
  "success": true,
  "data": {
    "id": 22,
    "username": "chenchen",
    "email": "",
    "group": "default",
    "role": 1,
    "status": 1
  }
}

客户端处理：

• 保存 data.id。
• 后续 /api/agent/user/* 请求带 New-Api-User: <id>。

5. HeicodeTask 任务编排

这些接口通过 Manager 同源代理访问 mcp-server：

Base: /api/heicode-auth

5.1 创建任务

POST /api/heicode-auth/api/user/tasks/intent

描述用户想做什么，创建 HeicodeTask。

请求头必须包含桌面客户端登录后持有的 Heicode access token：

Authorization: Bearer <heicode_access_token>
Content-Type: application/json
Accept: application/json

请求：

{
  "intent": "做一个客户工单管理系统，支持登录、工单列表、状态流转和后台统计",
  "name": "客户工单管理系统"
}

字段：

字段	类型	必需	说明
intent	string	是	用户自然语言目标
name	string	否	任务名称，不传则由服务端生成

响应：

{
  "success": true,
  "data": {
    "id": "task_abc123",
    "user_id": "22",
    "name": "客户工单管理系统",
    "status": "configuring",
    "status_caption": "需要补充几个问题",
    "intent": "做一个客户工单管理系统...",
    "thread": [
      {
        "kind": "user",
        "text": "做一个客户工单管理系统...",
        "at": 1779850000000
      },
      {
        "kind": "heicode",
        "text": "请选择第一版范围",
        "at": 1779850001000,
        "followups": [
          {
            "id": "scope",
            "question": "第一版优先做什么？",
            "options": [
              { "id": "mvp", "label": "MVP 基础功能" }
            ]
          }
        ]
      }
    ],
    "card": null,
    "created_at": 1779850000000,
    "updated_at": 1779850001000
  }
}

5.2 查询任务列表

GET /api/heicode-auth/api/user/tasks?status=running&limit=20&offset=0

查询当前用户任务。

查询参数：

参数	类型	必需	说明
status	string	否	draft/configuring/running/awaiting_approval/completed/failed/paused
limit	number	否	默认由服务端决定
offset	number	否	分页偏移

响应：

{
  "success": true,
  "data": {
    "items": [],
    "total": 0,
    "offset": 0,
    "limit": 20
  }
}

5.3 查询任务详情

GET /api/heicode-auth/api/user/tasks/{task_id}

响应同 HeicodeTask。

5.4 回答追问

POST /api/heicode-auth/api/user/tasks/{task_id}/answer

同样必须携带：

Authorization: Bearer <heicode_access_token>

请求：

{
  "question_id": "scope",
  "option_id": "mvp"
}

响应：

{
  "success": true,
  "data": {
    "id": "task_abc123",
    "status": "running",
    "card": {
      "goal": "客户工单管理系统第一版",
      "scope": ["登录", "工单列表", "状态流转"],
      "generated_artifacts": ["产品说明", "接口草案", "开发任务"],
      "manager_actions": [
        {
          "label": "绑定 Git",
          "deeplink": "/sk-sources"
        }
      ]
    }
  }
}

客户端处理：

• status=configuring：继续展示 thread[].followups。
• status=running 且 card 存在：允许用户创建 Manager deployment。
• status=awaiting_approval：轮询审批接口。
• status=completed/failed/paused：停止高频轮询。

6. 从任务生成 Agent Deployment Draft

POST /api/agent/user/tasks/{task_id}/deployment-draft

把 HeicodeTask 快照转换成 Manager 可创建的 Agent orchestration plan。

生产已验证：客户端只要能提供 task snapshot，就可以不依赖 Manager 再去拉 task，直接调用本接口生成 draft。

请求：

{
  "task": {
    "id": "task_abc123",
    "name": "客户工单管理系统",
    "intent": "做一个客户工单管理系统...",
    "status": "running",
    "card": {
      "goal": "客户工单管理系统第一版",
      "scope": ["登录", "工单列表", "状态流转"],
      "generated_artifacts": ["产品说明", "接口草案", "开发任务"]
    }
  },
  "sub_mode": "agile",
  "binding_scope": "task-task_abc123",
  "role_templates": ["backend", "frontend", "reviewer"],
  "default_model_id": "claude-sonnet-4-6",
  "budget": {
    "max_tokens": 120000,
    "max_cost_usd": 8,
    "max_duration_sec": 3600
  },
  "resource_grants": []
}

生产烟测可用的最小请求形状：

{
  "task": {
    "id": "task-client-sim-1779875397",
    "name": "客户端模拟普通 sub 敏捷流程",
    "intent": "做一个轻量待办系统，包含任务列表、状态流转、基础测试和上线说明",
    "status": "running",
    "card": {
      "goal": "交付轻量待办系统 MVP",
      "scope": "普通 sub 敏捷流程接口联调",
      "generated_artifacts": []
    }
  },
  "sub_mode": "agile",
  "risk_level": "low",
  "budget": {
    "max_tokens": 20000,
    "max_cost_usd": 1,
    "max_duration_sec": 600
  },
  "binding_scope": "task-client-sim",
  "role_templates": ["backend"],
  "default_model_id": "claude-sonnet-4-6",
  "resource_grants": [
    {
      "grant_id": "grant-client-sim-git",
      "resource_id": "git-client-sim",
      "resource_type": "git",
      "binding_scope": "task-client-sim",
      "target_role": "backend",
      "target_agent_ref": "agent-backend-1",
      "permission_scope": ["repo:read"],
      "metadata": {
        "repo_url": "https://example.invalid/heicode/client-sim.git"
      },
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/client-sim-git",
      "status": "active"
    }
  ]
}

字段：

字段	类型	必需	说明
task.id	string	是	必须和 URL {task_id} 一致
task.name	string	否	任务名称
task.intent	string	否	用户原始目标
task.card.goal	string	否	优先作为 objective
sub_mode	string	是	agile 或 waterfall，桌面客户端默认传 agile
binding_scope	string	否	建议 task-<task_id>
role_templates	string[]	否	默认 ["backend"]
default_model_id	string	否	子 Agent 默认运行模型；生产默认建议 claude-sonnet-4-6
budget	object	否	不传使用默认预算
resource_grants	array	否	不传时 Manager 生成只读 task context grant

响应：

{
  "success": true,
  "data": {
    "task_id": "task_abc123",
    "orchestration_plan": {
      "intent_id": "task_abc123",
      "template_hint": "heicode-task",
      "objective": "客户工单管理系统第一版",
      "sub_mode": "agile",
      "risk_level": "low",
      "budget": {
        "max_tokens": 120000,
        "max_cost_usd": 8,
        "max_duration_sec": 3600
      },
      "user_context": {
        "user_id": "22",
        "role": "user",
        "channel_id": "default"
      },
      "billing_context": {
        "provider": "newapi",
        "newapi_group": "default"
      },
      "agent_runtime": {
        "platform": "agent",
        "agents": [
          {
            "role": "backend",
            "model_ref": "claude-sonnet-4-6",
            "instance_count": 1
          }
        ]
      },
      "agents": [
        {
          "role_template": "backend",
          "goal": "Execute the Heicode task as backend within the approved resource scope.",
          "default_model_id": "claude-sonnet-4-6",
          "resource_grants": []
        }
      ],
      "constraints": {
        "allowed_model_ids": []
      },
      "metadata": {
        "correlation_id": "task-task_abc123-xxxxxxxx"
      }
    }
  }
}

7. 创建 Manager Deployment

POST /api/agent/user/deployments

使用上一步 orchestration_plan 创建 Manager deployment。

必填注意：

• metadata.correlation_id 必须在 orchestration_plan.metadata 内。
• 如果客户端绕过 draft 接口直接创建 deployment，也必须自行生成该字段，例如 task-<task_id>-<timestamp>。
• 不要把 metadata 放在请求顶层；顶层 metadata 不会满足创建校验。
• billing_context.default_model_id、agents[].default_model_id、constraints.allowed_model_ids 必须使用生产 NewAPI 已存在模型。

请求：

{
  "orchestration_plan": {
    "intent_id": "task_abc123",
    "template_hint": "heicode-task",
    "objective": "客户工单管理系统第一版",
    "sub_mode": "agile",
    "risk_level": "low",
    "budget": {
      "max_tokens": 120000,
      "max_cost_usd": 8,
      "max_duration_sec": 3600
    },
    "user_context": {
      "user_id": "22",
      "role": "user",
      "channel_id": "default"
    },
    "billing_context": {
      "provider": "newapi",
      "newapi_group": "default"
    },
    "agent_runtime": {
      "platform": "agent",
      "agents": [
        {
          "role": "backend",
          "model_ref": "claude-sonnet-4-6",
          "instance_count": 1
        }
      ]
    },
    "agents": [
      {
        "role_template": "backend",
        "goal": "Execute the Heicode task as backend within the approved resource scope.",
        "default_model_id": "claude-sonnet-4-6",
        "resource_grants": []
      }
    ],
    "constraints": {
      "allowed_model_ids": []
    },
    "metadata": {
      "correlation_id": "task-task_abc123-xxxxxxxx"
    }
  }
}

响应：

{
  "success": true,
  "data": {
    "deployment_id": "dep_464a08b7b751",
    "sub_mode": "agile",
    "status": "accepted",
    "phase": "pending",
    "runtime_state": "queued",
    "runtime_deployment_id": "",
    "runtime_swarm_id": "",
    "failure_reason": "",
    "agent_instances": [
      {
        "instance_id": "agi_1fddac9cded5",
        "role": "backend",
        "phase": "pending",
        "runtime_state": "queued",
        "failure_reason": ""
      }
    ],
    "permission_manifest": {
      "user_id": "22",
      "binding_scope": "task-task_abc123",
      "agent_role": "backend",
      "target_agent_ref": "agent-backend-1",
      "resource_grants": []
    }
  }
}

客户端处理：

• 保存 deployment_id。
• runtime_state=queued 表示 Manager 已建立本地控制面记录。
• 如果生产 Runtime 未配置，deployment 仍可创建，但不会进入真实执行。

直接创建的最小可用生产示例：

{
  "orchestration_plan": {
    "intent_id": "task-prod-smoke",
    "template_hint": "heicode-task",
    "objective": "生成一个极简 hello world 网站。必须返回真实代码文件内容，不接受只有方案总结。",
    "sub_mode": "agile",
    "risk_level": "low",
    "budget": {
      "max_tokens": 20000,
      "max_cost_usd": 0.5,
      "max_duration_sec": 900
    },
    "user_context": {
      "user_id": "22",
      "channel_id": "heicode",
      "binding_scope": "task-prod-smoke"
    },
    "billing_context": {
      "provider": "newapi",
      "default_model_id": "gpt-5.4",
      "allowed_model_ids": ["gpt-5.4"],
      "secret_ref": "azkv://heicode-kv.vault.azure.net/secrets/model-gateway-key"
    },
    "agile_context": {
      "stage": "development",
      "checkpoint": "artifact_required",
      "acceptance_criteria": [
        "artifact content must include real source files",
        "package.json or equivalent entry file must be present for code tasks",
        "README must include run or smoke test commands",
        "do not return only a delivery summary document"
      ],
      "next_action": "submit_artifact",
      "requires_user_approval": false
    },
    "agents": [
      {
        "role_template": "fullstack",
        "goal": "生成 hello world 网站真实代码 artifact，必须包含文件路径、源码内容、启动命令和冒烟说明，不要只写交付总结。",
        "default_model_id": "gpt-5.4",
        "resource_grants": []
      }
    ],
    "constraints": {
      "allowed_model_ids": ["gpt-5.4"]
    },
    "metadata": {
      "correlation_id": "prod-smoke-<timestamp>"
    }
  }
}

8. 查询 Deployment

8.1 列表

GET /api/agent/user/deployments

响应：

{
  "success": true,
  "data": {
    "items": [
      {
        "deployment_id": "dep_464a08b7b751",
        "sub_mode": "agile",
        "status": "accepted",
        "phase": "pending",
        "runtime_state": "queued",
        "failure_reason": "",
        "created_at": "2026-05-27T11:44:30+08:00",
        "updated_at": "2026-05-27T11:44:30+08:00",
        "permission_manifest": {},
        "orchestration_plan": {}
      }
    ]
  }
}

8.2 详情

GET /api/agent/user/deployments/{deployment_id}

响应字段同列表单项，包含完整 orchestration_plan。

8.3 停止

POST /api/agent/user/deployments/{deployment_id}/stop

请求：

{
  "reason": "用户停止本轮 sub 敏捷任务"
}

响应：

{
  "success": true,
  "data": {
    "deployment_id": "dep_464a08b7b751",
    "status": "stopped",
    "phase": "stopped"
  }
}

9. 执行反馈查询

9.1 Events

GET /api/agent/user/deployments/{deployment_id}/events

用于展示 deployment 事件流。

响应：

{
  "success": true,
  "data": {
    "items": [
      {
        "event_id": "evt_xxx",
        "event": "deployment.accepted",
        "deployment_id": "dep_464a08b7b751",
        "occurred_at": "2026-05-27T11:44:30+08:00",
        "result": "ok"
      }
    ]
  }
}

9.2 Logs

GET /api/agent/user/deployments/{deployment_id}/logs

用于展示最近日志。当前 Manager 未接真实 Runtime 时主要是审计日志。

响应：

{
  "success": true,
  "data": {
    "items": [
      {
        "timestamp": "2026-05-27T11:44:30+08:00",
        "level": "info",
        "message": "deployment accepted",
        "source": "manager-audit"
      }
    ]
  }
}

9.3 Metrics

GET /api/agent/user/deployments/{deployment_id}/metrics

用于展示成本、耗时、token、资源指标。真实 Runtime 未接入时可能为空或为本地占位。

响应：

{
  "success": true,
  "data": {
    "deployment_id": "dep_464a08b7b751",
    "runtime_state": "queued",
    "metrics": {}
  }
}

9.4 Artifacts

GET /api/agent/user/deployments/{deployment_id}/artifacts

查询中间交付物和最终交付物摘要。注意：列表接口只返回摘要和引用，不能证明代码内容有效；客户端需要按需调用 content 接口并按“Artifact 展示和有效性判断”继续分类。

响应：

{
  "success": true,
  "data": {
    "deployment_id": "dep_464a08b7b751",
    "artifacts": [
      {
        "artifact_id": "art_swm_b60c8181bc79_backend_1",
        "artifact_type": "code_patch",
        "title": "backend task delivery",
        "summary": "下面给出一个可直接落地的 Node.js Express REST API 小项目交付物，包含真实代码文件内容...",
        "uri": "azblob://heicode-artifacts/runtime-artifacts/swm_b60c8181bc79/art_swm_b60c8181bc79_backend_1.txt",
        "metadata": {
          "download_path": "/api/swarms/swm_b60c8181bc79/artifacts/art_swm_b60c8181bc79_backend_1/content",
          "content_hash": "sha256:224cc3559cdfa6e607808a286cfa05a795c4331f61e776e58078471eb8ae45e1"
        },
        "created_at": 1779850000000
      }
    ],
    "items": [],
    "total": 1
  }
}

GET /api/agent/user/deployments/{deployment_id}/artifacts/{artifact_id}/content

读取完整产物正文。客户端必须通过该接口判断产物是否真的是代码，而不是只看 artifact_type。

真实代码文档示例片段：

## 1) package.json

```json
{
  "name": "express-rest-api-demo",
  "scripts": {
    "start": "node src/index.js",
    "test": "node --test"
  },
  "dependencies": {
    "express": "^4.19.2"
  }
}
```

## 2) src/index.js

```js
const express = require('express');
const app = express();
app.get('/health', (req, res) => res.json({ success: true, message: 'OK' }));
```

summary-only 示例片段：

以下是作为 **Frontend 角色**，针对“Oracle 云代理商网站”可提交给 Heicode Manager artifacts 的具体交付物总结。

# 交付物总结：Oracle 云代理商网站（前端）

第二种只能显示为“方案总结 / 文档”，不能显示为代码生成完成。

9.5 SK Snapshots

GET /api/agent/user/deployments/{deployment_id}/sk-snapshots

查询本轮任务使用的 SK 快照。

响应：

{
  "success": true,
  "data": {
    "deployment_id": "dep_464a08b7b751",
    "sk_snapshots": [
      {
        "snapshot_id": "sks_task_abc123_backend_001",
        "deployment_id": "dep_464a08b7b751",
        "agent_role": "backend",
        "source_type": "git",
        "source_ref": "git:https://example.com/tools.git#main:backend",
        "content_hash": "sha256:abc123",
        "tool_name": "repo_write",
        "created_at": "2026-05-27T11:45:00+08:00",
        "metadata": {
          "redacted": true
        }
      }
    ],
    "items": [],
    "total": 1
  }
}

9.6 Timeline

GET /api/agent/user/deployments/{deployment_id}/timeline

聚合审计事件、Runtime callback、artifact、SK snapshot。桌面客户端推荐优先使用这个接口渲染“当前子环节进度”。

响应：

{
  "success": true,
  "data": {
    "deployment_id": "dep_464a08b7b751",
    "deployment": {
      "deployment_id": "dep_464a08b7b751",
      "sub_mode": "agile",
      "status": "accepted",
      "phase": "pending",
      "runtime_state": "queued"
    },
    "events": [],
    "callbacks": [],
    "artifacts": [],
    "sk_snapshots": [],
    "timeline": [
      {
        "kind": "audit",
        "at": 1779850000000,
        "event": "deployment.accepted"
      },
      {
        "kind": "callback",
        "at": "2026-05-27T11:45:00+08:00",
        "event": "phase.changed",
        "event_id": "evt_phase_001",
        "event_type": "phase.changed"
      },
      {
        "kind": "artifact",
        "at": 1779850060000,
        "event": "test_report",
        "artifact_id": "art_test_report_001"
      }
    ]
  }
}

客户端建议：

• 轮询间隔：运行中 3-5 秒；终态 15-30 秒或停止。
• 优先展示 timeline[]。
• 如果存在 artifact，提供“查看交付物”入口。
• 如果存在 callback.event_type=approval.requested 或任务状态 awaiting_approval，拉取审批接口。

10. 审批与短期凭证

高危操作审批必须由桌面客户端作为主体验展示。Manager 只提供记录、approve/reject 和 lease。

10.1 查询待审批

GET /api/agent/approvals?status=pending&deployment_id={deployment_id}

查询参数：

参数	类型	必需	说明
status	string	否	pending/approved/rejected/expired
deployment_id	string	否	按 deployment 过滤

响应：

{
  "success": true,
  "data": {
    "items": [
      {
        "approval_id": "appr_xxx",
        "user_id": 22,
        "deployment_id": "dep_464a08b7b751",
        "binding_scope": "task-task_abc123",
        "operation": "git.write",
        "resource_id": "res_git_main",
        "resource_type": "git",
        "resource_scope": "feature/*",
        "target_role": "backend",
        "risk_level": "high",
        "requires_credential": true,
        "credential_lease_id": "",
        "status": "pending",
        "requested_by": "agent-runtime",
        "request_reason": "需要写入功能分支",
        "ttl_seconds": 900,
        "expires_at": 1779850900000,
        "created_at": 1779850000000
      }
    ]
  }
}

10.2 同意审批

POST /api/agent/approvals/{approval_id}/approve

请求：

{
  "reason": "用户确认允许本轮任务写入功能分支"
}

响应：

{
  "success": true,
  "data": {
    "approval_id": "appr_xxx",
    "status": "approved",
    "credential_lease_id": "lease_xxx",
    "credential_lease": {
      "lease_id": "lease_xxx",
      "credential_ref": "lease://agent/lease_xxx",
      "status": "active",
      "expires_at": 1779850900000
    }
  }
}

注意：响应只会返回 lease://... 引用，不返回明文凭证。

10.3 拒绝审批

POST /api/agent/approvals/{approval_id}/reject

请求：

{
  "reason": "用户拒绝生产环境写入"
}

响应：

{
  "success": true,
  "data": {
    "approval_id": "appr_xxx",
    "status": "rejected",
    "decision_reason": "用户拒绝生产环境写入"
  }
}

10.4 查询 lease

GET /api/agent/credential-leases?status=active&deployment_id={deployment_id}

响应：

{
  "success": true,
  "data": {
    "items": [
      {
        "lease_id": "lease_xxx",
        "credential_ref": "lease://agent/lease_xxx",
        "approval_id": "appr_xxx",
        "deployment_id": "dep_464a08b7b751",
        "resource_id": "res_git_main",
        "resource_type": "git",
        "target_role": "backend",
        "status": "active",
        "expires_at": 1779850900000
      }
    ]
  }
}

10.5 撤销 lease

POST /api/agent/credential-leases/{lease_id}/revoke

请求：

{
  "reason": "用户停止任务"
}

响应：

{
  "success": true,
  "data": {
    "lease_id": "lease_xxx",
    "status": "revoked"
  }
}

11. 角色模板

GET /api/agent/role-templates

获取推荐子 Agent 角色，桌面端可用于角色选择页。

响应：

{
  "success": true,
  "data": {
    "items": [
      {
        "key": "backend",
        "display_name": "Backend Agent",
        "summary": "实现后端接口、数据模型和服务逻辑",
        "default_model": "gpt-5.4",
        "default_permissions": ["repo:read", "repo:write"],
        "risk_level": "medium"
      }
    ]
  }
}

default_model 由 Manager 单一来源 defaultAgentModelID() 提供（环境变量 AGENT_DEFAULT_MODEL_ID，默认生产已验证的 gpt-5.4）。Manager 不再回退 agent-model-<role> 占位名；客户端如不指定 default_model_id，draft/runtime agent 会自动采用该单一默认值。

12. 状态枚举

HeicodeTask.status

状态	说明	客户端动作
draft	草稿	可继续编辑
configuring	等待回答追问	展示 followups
running	可推进/运行中	创建 deployment 或展示 timeline
awaiting_approval	等待审批	拉取 /api/agent/approvals
completed	完成	展示交付物
failed	失败	展示失败原因
paused	暂停	允许继续或停止

Agent Deployment.status

状态	说明
accepted	Manager 已接受并落本地记录
running	Runtime 已开始执行
completed	Runtime 回调 deployment.status_changed: completed 后的成功终态（真实终态，客户端状态机必须覆盖；注意需结合 §15.1 成功四要素判断是否为有效交付，completed 本身不代表有业务产物）
stopped	已停止
failed	失败

注意：status 由 Manager 接收 Runtime deployment.status_changed 后镜像写入。除上述规范值外，Runtime 若回传其他自定义状态字符串，Manager 会透传保存，客户端应对未知值做兜底（按非终态处理或显示原值）。

Agent Deployment.runtime_state

状态	说明
queued	Manager 本地队列/占位，尚未同步真实 Runtime
runtime_syncing	正在同步 Runtime
runtime_accepted	Runtime 接受
runtime_sync_failed	Runtime 同步失败
not_configured	生产 Runtime 未配置
running / completed / failed / stopped	Runtime 回调后 runtime_state 会镜像 Runtime 上报的状态值；phase.changed 还会把 checkpoint 写入此字段。客户端不要假设其取值封闭，应做兜底

普通 sub 子环节建议值

Runtime callback / timeline 中可使用：

阶段	说明
requirements	需求
design	设计
backend	后端
frontend	前端
review	检查
test	测试
deploy	部署

13. 错误码

错误码	场景	客户端处理
TASK_NOT_FOUND	任务不存在或 task snapshot 缺失	重新拉取任务
TASK_CONFLICT	URL task_id 与 body task.id 不一致	修正请求
POLICY_REJECTED	参数不符合策略	展示错误并阻止继续
MODEL_NOT_ALLOWED	模型不在允许列表	让用户换模型或联系管理员
BUDGET_EXCEEDED	预算超过平台策略	调低预算
RESOURCE_GRANT_INVALID	Resource Grant 字段缺失或角色不匹配	重新选择资源权限
RESOURCE_GRANT_SECRET_REF_REQUIRED	凭据型资源缺少 secret_ref	引导用户绑定资源/密钥
SECRET_REF_INVALID	secret_ref 不是 azkv://...	禁止继续
RESOURCE_GRANT_SECRET_REJECTED	metadata/constraints/audit 疑似包含明文密钥	禁止继续并提示脱敏
CALLBACK_SECRET_REJECTED	Runtime 回调含明文密钥	展示安全错误

14. 桌面端最小伪代码

type Json = Record<string, unknown>

// 复用模型调用已经使用的 V2 加密 fetch：
// - 自动拉取 /api/server-pubkey
// - 每次请求生成 nonce + X25519 ephemeral key
// - 用 ChaCha20-Poly1305 加密 body
// - 用设备 Ed25519 私钥签名 canonical
// - 设置 Content-Encoding: heicode-aead-v1 和所有 X-Heicode-* 头
async function encryptedManagerRequest<T>(
  method: 'POST',
  path: string,
  body?: Json,
  extraHeaders: Record<string, string> = {}
): Promise<T> {
  return encryptedFetch<T>(`${managerBaseUrl}${path}`, {
    method,
    plaintextJson: body,
    headers: {
      Accept: 'application/json',
      ...extraHeaders,
    },
  })
}

const self = await manager.get('/api/user/self')
const userId = self.data.id

const task = await encryptedManagerRequest<Envelope<TaskSnapshot>>(
  'POST',
  '/api/heicode-auth/api/user/tasks/intent',
  { intent: userInput },
  {
    Authorization: `Bearer ${heicodeAccessToken}`,
  }
)

let current = task.data
while (current.status === 'configuring') {
  const followup = findNextFollowup(current)
  const answer = await askUser(followup)
  current = await encryptedManagerRequest<Envelope<TaskSnapshot>>(
    'POST',
    `/api/heicode-auth/api/user/tasks/${current.id}/answer`,
    {
      question_id: followup.id,
      option_id: answer.id,
    },
    {
      Authorization: `Bearer ${heicodeAccessToken}`,
    }
  ).then((r) => r.data)
}

const draft = await encryptedManagerRequest<Envelope<DeploymentDraft>>(
  'POST',
  `/api/agent/user/tasks/${current.id}/deployment-draft`,
  {
    task: current,
    sub_mode: 'agile',
    binding_scope: `task-${current.id}`,
    role_templates: ['backend', 'frontend', 'reviewer'],
    default_model_id: 'claude-sonnet-4-6',
  }
)

const deployment = await encryptedManagerRequest<Envelope<Deployment>>(
  'POST',
  '/api/agent/user/deployments',
  { orchestration_plan: draft.data.orchestration_plan }
)

const deploymentId = deployment.data.deployment_id

setInterval(async () => {
  const timeline = await manager.get<Envelope<DeploymentTimeline>>(
    `/api/agent/user/deployments/${deploymentId}/timeline`,
    { headers: { 'New-Api-User': String(userId) } }
  )
  renderTimeline(timeline.data.timeline)

  const approvals = await manager.get<Envelope<ApprovalList>>(
    `/api/agent/approvals?status=pending&deployment_id=${deploymentId}`,
    { headers: { 'New-Api-User': String(userId) } }
  )
  renderApprovals(approvals.data.items)
}, 5000)

async function refreshSubDelivery(deploymentId: string) {
  const diagnostics = await manager.get<Envelope<RuntimeDiagnostics>>(
    `/api/agent/user/deployments/${deploymentId}/runtime-diagnostics`,
    { headers: { 'New-Api-User': String(userId) } }
  )
  renderRuntimeDiagnostics(diagnostics.data)

  const artifacts = await manager.get<Envelope<ArtifactList>>(
    `/api/agent/user/deployments/${deploymentId}/artifacts`,
    { headers: { 'New-Api-User': String(userId) } }
  )
  renderArtifacts(artifacts.data.artifacts)

  const firstDeliverable = artifacts.data.artifacts.find(
    (item) => item.artifact_type !== 'log_bundle'
  )
  if (firstDeliverable) {
    const content = await manager.get<string>(
      `/api/agent/user/deployments/${deploymentId}/artifacts/${firstDeliverable.artifact_id}/content`,
      {
        headers: { 'New-Api-User': String(userId) },
        responseType: 'text',
      }
    )
    renderArtifactContent(content.data)
  }
}

兼容说明：

• 桌面客户端对 POST 等有 body 的 sub 请求走 V2 加密时，/api/agent/user/* 不需要 New-Api-User，也不依赖浏览器 cookie。
• GET 查询接口本身没有请求 body，当前生产兼容路径仍使用 Manager session cookie + New-Api-User。如果桌面本地服务后续要完全脱离 session cookie 查询 timeline / artifact / approval，需要再补“无 body 的 V2 设备签名 GET”协议。
• /api/heicode-auth/* 仍必须带 Authorization: Bearer <heicode_access_token>，该 token 只用于上游 HeicodeTask 认证。
• 如果客户端临时还没有接入 V2 加密，只能作为调试兼容路径使用 Manager session + New-Api-User 调 /api/agent/user/*；正式桌面流程不要依赖该路径。

15. 当前生产注意事项

1. https://code.xinghanlab.com 的 Manager 用户态接口已上线；当前生产版本为 1.4.19。
2. Manager 本地控制面可创建 sub_mode=agile/waterfall deployment。
3. 生产 Manager 已配置 Agent Manager Runtime，当前直接走 http://20.212.121.126；域名和 HTTPS 后续单独处理，不作为客户端当前接入阻塞项。
4. V2 加密 deployment-draft 已在生产验证通过：真实构造 Content-Encoding: heicode-aead-v1 请求返回 200，sub_mode=agile，user_id=22。
5. deployment-draft -> create -> Runtime callback -> detail -> events/timeline -> artifacts -> artifact content 已在生产验证通过，客户端可按本文参数形状接入。
6. events/logs/artifacts/timeline 查询接口已验证不报错；真实 artifact、tokens_used、newapi_request_id 已可从 Runtime / Manager 查询到。SK snapshots 仍取决于 Runtime 是否回写 snapshot 字段。
7. POST /api/heicode-auth/api/user/tasks/intent 需要桌面客户端提供 heicode_access_token；没有该 token 会返回 401。
8. malformed V2 请求已在生产验证会返回 X-Heicode-Auth-Error，客户端应把该头转成可读错误提示。
9. 当前 GET 查询接口没有请求 body，仍按 session + New-Api-User 验证；这不影响 body 加密要求，但客户端若要全链路无 cookie，需要后续补无 body 签名 GET。
10. macOS 联调前必须确认客户端已完成设备绑定；若 Manager 设备页没有 macOS 设备，模型列表 401 应优先处理客户端本地凭据和 Keychain，而不是改 Manager 模型配置。

15.1 成功和失败判断

客户端展示普通 sub 结果时建议使用以下判断：

判断项	成功标准
deployment	status=completed 且 runtime_state=completed
Runtime	runtime_swarm_id 非空，Runtime status 为 completed
Agent	至少一个目标 Agent 为 completed，没有 failed agent
usage	tokens_used > 0，日志中可见 newapi_request_id 或 model_usage
artifact	artifacts.length > 0，且业务产物 artifact_type 为 code_patch、code_bundle、document、test_report、deployment_manifest 等
artifact content	GET /artifacts/{artifact_id}/content 返回 200，内容不是 Runtime execution failed / Runtime execution summary 兜底摘要
代码任务	若用户要求写代码，content 必须能分类为 code_bundle、code_patch 或 code_document，不能是 summary_only

失败场景示例：

场景	客户端提示
artifact_type=other 且标题为 Runtime execution failed	Runtime Agent 执行失败，当前 artifact 只是失败摘要，不是业务交付物
tokens_used=0	模型调用未成功或 Runtime 未回传用量，需查看 logs / newapi_request_id
Runtime 日志出现 504 Gateway Time-out	Agent 调模型超时，通常不是客户端发参或加密问题
Runtime 日志出现上游 400 Bad Request	Agent 模型调用参数/模型适配问题，需由 Runtime / Agent Manager 处理
artifact content 是“以下是作为 Frontend 角色...”这类角色口吻总结	Runtime 只返回了方案总结，客户端应提示“未获得真实代码交付物”，并允许用户继续要求生成代码