docs(integration): self-sufficient unified API doc for desktop client
以客户端开发视角通读后补齐缺口,使客户端可仅凭本文对接: - §0.1 推荐完整流程(capabilities->create->poll workflow->artifacts->manifest/files/archive) - §3.1 创建响应(deployment_id=task_id 来源)+ 列表响应 - §5 artifacts 列表响应 - §6 local-edit 单/批量请求 + 成功 + 冲突响应示例 - §7 云部署请求/响应示例 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -14,6 +14,25 @@ Manager 生产地址：`https://code.xinghanlab.com`
|
||||
- **Manager 是唯一状态裁判**：客户端只消费 `display_status`，不自行用正则判断产物是否有效。
|
||||
- **task_id ≡ deployment_id**：统一任务接口里 `{task_id}` 即 Manager 的 `deployment_id`。
|
||||
|
||||
## 0.1 推荐完整流程
|
||||
|
||||
```text
|
||||
1. GET /api/heicode/capabilities 取模式/模型，渲染模式与模型选择
|
||||
2. POST /api/heicode/sub-agile/tasks (需求包) 创建任务 -> 响应里拿 deployment_id(=task_id)
|
||||
3. (可选) POST .../tasks/{id}/execute 若需"先建后跑"或重试派发
|
||||
4. 轮询 GET .../tasks/{id}/workflow (运行中 3-5s) 读 display_status + 三层状态 + agents
|
||||
5. 出现 approval 时: GET .../approvals?status=pending -> approve/reject
|
||||
6. display_status=completed 后:
|
||||
GET .../tasks/{id}/artifacts 拿 artifact_id
|
||||
GET .../artifacts/{artifact_id}/manifest 项目文件树
|
||||
GET .../artifacts/{artifact_id}/files/{path} 单文件正文
|
||||
GET .../artifacts/{artifact_id}/archive 整包 zip
|
||||
7. (可选) 用户本地改后: POST .../artifacts/{id}/local-edits
|
||||
8. (可选) 部署: GET /api/heicode/deployment-targets -> POST .../tasks/{id}/deployments
|
||||
```
|
||||
|
||||
> 成功判据：`display_status=completed`（不是 `needs_codegen` / `completed_without_deliverable`）且 artifacts 非空。
|
||||
|
||||
## 1. 认证与加密（重要）
|
||||
|
||||
桌面客户端调用本文所有 `/api/heicode/*` 接口，**body 加密与签名和模型调用（`/v1/*`）完全一致**——直接复用同一套 `encryptedFetch` / V2 设备签名实现，无需新增协议。
|
||||
@@ -100,6 +119,25 @@ Manager 生产地址：`https://code.xinghanlab.com`
|
||||
`/messages` body：`{"message":"继续把测试补上","role":"user"}`。
|
||||
`/execute` body 可空；用于"创建后再触发"或重试派发。
|
||||
|
||||
**创建响应**（`deployment_id` 即后续所有 `{task_id}`）：
|
||||
|
||||
```json
|
||||
{ "success": true, "message": "", "data": {
|
||||
"deployment_id": "dep_b5fab27e9255",
|
||||
"sub_mode": "agile",
|
||||
"status": "accepted",
|
||||
"display_status": "accepted",
|
||||
"runtime_state": "runtime_syncing",
|
||||
"runtime_swarm_id": "",
|
||||
"agent_instances": [
|
||||
{"instance_id":"agi_xxx","role":"backend","phase":"pending","runtime_state":"queued","failure_reason":""}
|
||||
],
|
||||
"permission_manifest": {"user_id":"22","binding_scope":"","resource_grants":[]}
|
||||
}}
|
||||
```
|
||||
|
||||
**任务详情** `GET .../tasks/{task_id}` 返回同形 + 完整 `orchestration_plan`；**任务列表** `GET .../tasks` 返回 `{"items":[ ...同上... ],"total":N}`。客户端按 `display_status` 渲染，详情/列表读取时 Manager 会自动从 Runtime 收敛终态。
|
||||
|
||||
## 4. 状态模型（display_status）
|
||||
|
||||
客户端只展示 `display_status`（Manager 裁决结果）：
|
||||
@@ -148,7 +186,21 @@ Manager 生产地址：`https://code.xinghanlab.com`
|
||||
|
||||
## 5. 产物：项目文件夹
|
||||
|
||||
Runtime 返回单个文本/markdown 多文件 artifact；Manager 解析成项目文件树后提供：
|
||||
Runtime 返回单个文本/markdown 多文件 artifact；Manager 解析成项目文件树后提供。
|
||||
|
||||
**产物列表** `GET .../tasks/{task_id}/artifacts`：
|
||||
|
||||
```json
|
||||
{ "success": true, "data": {
|
||||
"deployment_id":"dep_xxx","total":1,
|
||||
"artifacts":[
|
||||
{"artifact_id":"art_swm_xxx_backend_1","artifact_type":"code_patch","title":"backend task delivery",
|
||||
"summary":"...","uri":"azblob://...","metadata":{"content_hash":"sha256:...","summary_only":false}}
|
||||
]
|
||||
}}
|
||||
```
|
||||
|
||||
判断是否真实交付：`display_status=completed` 且 artifact 的 `metadata.synthesized != true`（Manager 已裁决，客户端无需自判）。
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|---|---|---|
|
||||
@@ -181,8 +233,18 @@ manifest 示例：
|
||||
| POST | `.../artifacts/{artifact_id}/local-edits` | 上传单文件修改 |
|
||||
| POST | `.../artifacts/{artifact_id}/local-edits/batch` | 上传多文件修改（`changes[]`，op=update/create/delete） |
|
||||
|
||||
请求体核心：`base_revision`（基线版本）、`path`/`content` 或 `changes[]`、`change_summary`。
|
||||
冲突：若 `base_revision` 不等于当前最新，返回 `ARTIFACT_REVISION_CONFLICT` + `data.current_project_revision`，客户端提示用户先同步。
|
||||
单文件上传请求：
|
||||
|
||||
```json
|
||||
{ "base_artifact_id":"art_xxx","base_revision":1,"path":"frontend/src/App.tsx",
|
||||
"content":"<html>...</html>","content_hash":"sha256:new","change_summary":"改了首页标题" }
|
||||
```
|
||||
|
||||
批量请求：`{ "base_revision":1, "changes":[ {"op":"update","path":"a.py","content":"..."},{"op":"create","path":"b.py","content":"..."},{"op":"delete","path":"c.py"} ], "change_summary":"..." }`
|
||||
|
||||
成功响应：`{ "success":true,"data":{ "artifact_id":"art_xxx","revision":2,"project_revision":2,"source":"client_local_edit","status":"received","content_hash":"sha256:new" } }`
|
||||
|
||||
冲突：若 `base_revision` 不等于当前最新，返回 `{ "success":false,"error":{"code":"ARTIFACT_REVISION_CONFLICT",...},"data":{"current_project_revision":3} }`，客户端提示用户先同步再提交。
|
||||
|
||||
## 7. 云部署（控制面，执行待 Deploy Worker）
|
||||
|
||||
@@ -192,8 +254,17 @@ manifest 示例：
|
||||
| POST | `/api/heicode/sub-agile/tasks/{task_id}/deployments` | 发起部署（body: artifact_id/target/environment/region/resource_binding_id/options） |
|
||||
| GET | `/api/heicode/sub-agile/tasks/{task_id}/deployments` | 部署列表 |
|
||||
|
||||
发起部署请求：
|
||||
|
||||
```json
|
||||
{ "artifact_id":"art_xxx","artifact_revision":1,"target":"azure","environment":"preview",
|
||||
"region":"eastasia","deployment_mode":"managed","resource_binding_id":123 }
|
||||
```
|
||||
|
||||
响应：`{ "success":true,"data":{ "deployment_run_id":"deploy_xxx","deployment_id":"dep_xxx","target":"azure","environment":"preview","status":"deployment_requested","executor":"pending_worker" } }`
|
||||
|
||||
客户端**禁止**传云厂商 AccessKey/Secret/连接串/secret_ref，只传 `resource_binding_id`（Manager 内部解析为凭据）。
|
||||
`environment=production` 进入 `waiting_approval`；当前响应带 `executor: "pending_worker"`（真实云执行待 Deploy Worker 接入）。
|
||||
`environment=production` → `status=waiting_approval`（需审批）；`executor: "pending_worker"` 表示真实云执行待 Deploy Worker 接入（当前部署不会真正起资源）。
|
||||
|
||||
## 8. Runtime 回调（仅 Runtime 用，客户端无需关心）
|
||||
|
||||
|
||||
Reference in New Issue
Block a user