docs: clarify desktop sub artifact handling

Document how the desktop client should classify and display sub-mode artifacts, including summary-only outputs and markdown code documents. Constraint: Keep interface paths stable; update display and validation rules only Confidence: high Scope-risk: narrow Not-tested: Documentation-only change; git diff --check passed
2026-06-01 01:48:27 +08:00
parent 1d5bc81b38
commit be5b9996d9
1 changed files with 146 additions and 16 deletions
@@ -1,6 +1,6 @@
 # Heicode 桌面客户端 sub 敏捷流程 API 对接文档

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

@@ -32,6 +32,17 @@ Manager 生产地址：`https://code.xinghanlab.com`
 | `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. 桌面客户端不要再使用 `agnet-model-builder`、`agnet-model-reviewer`、`agnet-model-product` 这类占位模型名。生产 NewAPI 没有这些模型，会返回 `No available channel for model ...`。
@@ -39,6 +50,7 @@ Manager 生产地址：`https://code.xinghanlab.com`
 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. 对接目标

@@ -256,7 +268,66 @@ Manager 行为：
 - Manager Web 任务总览中的 artifact 卡片会显示“下载产物”。
 - 如果 artifact 是 `Runtime execution summary` 兜底摘要，页面会明确提示它不是最终业务交付物。

-### 3.3 2026-05-28 生产验证结果
+### 3.3 Artifact 展示和有效性判断
+
+桌面客户端不要把 artifact content 原文直接追加到聊天流里。聊天区只展示简短结论，完整产物放在右侧“交付产物”区域或独立详情页中。
+
+推荐聊天区文案：
+
+```text
+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` | 显示失败或兜底摘要 | 否 |
+
+客户端分类建议：
+
+```ts
+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 生产验证结果

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

@@ -323,7 +394,7 @@ Manager 登录
 - 如果客户端需要从自然语言创建任务，必须先完成 Heicode 登录并拿到 `heicode_access_token`。
 - 当前 create / callback / detail / metrics / events / timeline / artifacts / artifact content 已真实有效；SK snapshots 需要 Runtime 在真实任务中回写 `sk_tool.*` 或 snapshot 字段后才会有数据。

-### 3.4 桌面客户端联调结论
+### 3.5 桌面客户端联调结论

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

@@ -786,7 +857,7 @@ Authorization: Bearer <heicode_access_token>
  "orchestration_plan": {
    "intent_id": "task-prod-smoke",
    "template_hint": "heicode-task",
-    "objective": "生成一个极简 hello world 网站交付说明，返回 artifact。",
+    "objective": "生成一个极简 hello world 网站。必须返回真实代码文件内容，不接受只有方案总结。",
    "sub_mode": "agile",
    "risk_level": "low",
    "budget": {
@@ -801,20 +872,32 @@ Authorization: Bearer <heicode_access_token>
    },
    "billing_context": {
      "provider": "newapi",
-      "default_model_id": "claude-sonnet-4-6",
-      "allowed_model_ids": ["claude-sonnet-4-6"],
+      "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": "claude-sonnet-4-6",
+        "goal": "生成 hello world 网站真实代码 artifact，必须包含文件路径、源码内容、启动命令和冒烟说明，不要只写交付总结。",
+        "default_model_id": "gpt-5.4",
        "resource_grants": []
      }
    ],
    "constraints": {
-      "allowed_model_ids": ["claude-sonnet-4-6"]
+      "allowed_model_ids": ["gpt-5.4"]
    },
    "metadata": {
      "correlation_id": "prod-smoke-<timestamp>"
@@ -958,7 +1041,7 @@ Authorization: Bearer <heicode_access_token>

 #### `GET /api/agnet/user/deployments/{deployment_id}/artifacts`

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

 响应：

@@ -969,11 +1052,15 @@ Authorization: Bearer <heicode_access_token>
    "deployment_id": "dep_464a08b7b751",
    "artifacts": [
      {
-        "artifact_id": "art_test_report_001",
-        "artifact_type": "test_report",
-        "title": "测试报告",
-        "summary": "本轮后端接口测试通过",
-        "uri": "artifact://task_abc123/test-report/art_test_report_001",
+        "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
      }
    ],
@@ -983,6 +1070,47 @@ Authorization: Bearer <heicode_access_token>
 }
 ```

+#### `GET /api/agnet/user/deployments/{deployment_id}/artifacts/{artifact_id}/content`
+
+读取完整产物正文。客户端必须通过该接口判断产物是否真的是代码，而不是只看 `artifact_type`。
+
+真实代码文档示例片段：
+
+````text
+## 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 示例片段：
+
+```text
+以下是作为 **Frontend 角色**，针对“Oracle 云代理商网站”可提交给 Heicode Manager artifacts 的具体交付物总结。
+
+# 交付物总结：Oracle 云代理商网站（前端）
+```
+
+第二种只能显示为“方案总结 / 文档”，不能显示为代码生成完成。
+
 ### 9.5 SK Snapshots

 #### `GET /api/agnet/user/deployments/{deployment_id}/sk-snapshots`
@@ -1465,8 +1593,9 @@ async function refreshSubDelivery(deploymentId: string) {
 | 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`、`document`、`test_report`、`deployment_manifest` 等 |
+| 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` |

 失败场景示例：

@@ -1476,3 +1605,4 @@ async function refreshSubDelivery(deploymentId: string) {
 | `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 只返回了方案总结，客户端应提示“未获得真实代码交付物”，并允许用户继续要求生成代码 |