diff --git a/docs/integration/heicode-desktop-unified-api.md b/docs/integration/heicode-desktop-unified-api.md
index 8f628e2..bbd9af4 100644
--- a/docs/integration/heicode-desktop-unified-api.md
+++ b/docs/integration/heicode-desktop-unified-api.md
@@ -7,6 +7,15 @@ Manager 生产地址：`https://code.xinghanlab.com`
 
 > 本文取代旧的 `heicode-desktop-sub-agile-api.md`（其 `/api/agnet/*` 路由已废弃）。新客户端一律使用本文的 `/api/heicode/*` 与 `/api/agent/*` 接口。
 
+> **2026-06-02 更新（已对照客户端 gap-analysis 闭环 P0/P1 并在运行时实跑验证）**：
+> - GET 全程无 cookie 的「无 body 设备签名」（§1，P0-1）；
+> - 审批列表 `GET .../approvals?status=`（§3.2，P0-2）；
+> - 产物列表归一化 `display_artifact_type=project_folder` + `is_project`（§5，P0-3）；
+> - `/archive` 下载契约（zip 头 + `ARTIFACT_ARCHIVE_NOT_READY`，§5，P0-4）；
+> - 单文件改 `?path=` 编码（§5，P1-1）；
+> - revision `accepted`/`applied` 语义 + `/messages`·`/execute` 自动用最新 accepted（§6，P1-2/P1-3）；
+> - Swarm 全量同形显式声明（§3，P1-4）。
+
 ## 0. 命名与总原则
 
 - **命名统一**：`agnet` 是历史拼写错误，已全量改为 `agent`。所有新接口为 `/api/agent/*`、`/api/heicode/*`；旧 `/api/agnet/*` 已下线（404）。
@@ -344,15 +353,18 @@ Schema 查询：`GET /api/agent/callbacks/runtime-events/schema`。
 - 生产包禁用 mock 任务/审批/产物。
 - 只消费 Manager 的 `display_status` / manifest / diagnostics。
 - 普通用户文案不出现 `newapi`、上游厂商、模型网关字眼。
-- 任务接口认证用 deviceToken / Manager session；base_url 来自 preset。
+- 任务接口认证：写请求用 V2 加密 body + 设备签名，GET 用 V2 无 body 设备签名（见 §1），均复用模型调用同一套实现；base_url 来自 preset。
 
 ## 10. 错误码（新增）
 
-| code | 场景 |
-|---|---|
-| `ARTIFACT_REVISION_CONFLICT` | 本地修改基于旧版本 |
-| `RESOURCE_BINDING_INVALID` | resource_binding_id 不存在或非本人 |
-| `DEPLOY_TARGET_DISABLED` | 云目标未启用 |
-| `FILE_NOT_FOUND` | 项目文件不存在 |
+| code | 场景 | retryable |
+|---|---|---|
+| `ARTIFACT_REVISION_CONFLICT` | 本地修改基于旧版本（`data.current_project_revision` 给出最新版本） | false |
+| `ARTIFACT_ARCHIVE_NOT_READY` | zip 产物尚未就绪（无文件），稍后重试 | true |
+| `ARTIFACT_ARCHIVE_FAILED` | 打包失败 | false |
+| `RESOURCE_BINDING_INVALID` | resource_binding_id 不存在或非本人 | false |
+| `DEPLOY_TARGET_DISABLED` | 云目标未启用 | false |
+| `FILE_NOT_FOUND` | 项目文件不存在 | false |
+| `FILE_PATH_REQUIRED` | 取单文件未带 `?path=` | false |
 
-其余错误码沿用旧文档 §13。
+其余错误码沿用旧文档 §13。所有错误统一形如 `{"success":false,"error":{"code","message","retryable"}}`，可读 `error.retryable` 决定是否重试。