Files

T

gongzhiyong f466c40545 docs: update desktop sub agile integration flow

2026-05-27 17:53:04 +08:00

27 KiB

Raw Blame History

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

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

1. 对接目标

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

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

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

2. 认证与公共约定

2.1 API 分组

API 前缀	用途	认证
`/api/heicode-auth/api/user/tasks/*`	HeicodeTask 任务编排代理，创建任务、追问、查询任务	`Authorization: Bearer <heicode_access_token>`
`/api/agnet/user/*`	Manager 用户态 Agnet 控制面，deployment、timeline、artifact、审批	Manager 登录 session cookie + `New-Api-User: <user_id>`
`/api/user/self`	查询当前 Manager 用户	Manager 登录 session cookie

2.2 Manager 用户态 Header

调用 /api/agnet/user/* 时必须带：

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

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

2.3 统一响应 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/agnet/user/tasks/{task_id}/deployment-draft
5. 创建 Manager deployment：POST /api/agnet/user/deployments
6. 轮询 deployment detail / events / timeline
7. 展示 artifacts / sk-snapshots / logs / metrics
8. 如出现 approval，桌面端展示审批并调用 approve/reject
9. 完成后继续迭代或停止 deployment

3.1 2026-05-27 生产验证结果

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

生产环境：

项	值
Manager	`https://code.xinghanlab.com`
Manager 版本	`1.4.6`
Agent Manager Runtime	`http://20.212.121.126`
Runtime health	`healthy`

已验证成功的链路：

Manager 登录
-> /api/user/self
-> /api/agnet/runtime/health
-> /api/agnet/user/tasks/{task_id}/deployment-draft
-> /api/agnet/user/deployments
-> /api/agnet/user/deployments/{deployment_id}
-> 直查 Agent Manager runtime deployment
-> /api/agnet/user/deployments/{deployment_id}/metrics
-> /api/agnet/user/deployments/{deployment_id}/events
-> /api/agnet/user/deployments/{deployment_id}/logs
-> /api/agnet/user/deployments/{deployment_id}/artifacts
-> /api/agnet/user/deployments/{deployment_id}/sk-snapshots
-> /api/agnet/user/deployments/{deployment_id}/timeline
-> /api/agnet/user/deployments/{deployment_id}/stop
-> 直查 Agent Manager runtime deployment 状态为 stopped

本次生产烟测 ID：

对象	ID / 结果
task snapshot	`task-client-sim-1779875397`
Manager deployment	`dep_40730ad87435`
Runtime deployment	`dep_6747d5eeb54c`
create 结果	200，Manager 成功保存 runtime deployment id
stop 结果	200，Manager 和 Agent Manager 均为 `stopped`

本次未由 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 / detail / metrics / stop 已真实有效；events / logs / artifacts / sk-snapshots / timeline 查询接口均 200，但本次 Runtime 没有产生真实回调数据，所以列表为空。

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/agnet/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. 从任务生成 Agnet Deployment Draft

`POST /api/agnet/user/tasks/{task_id}/deployment-draft`

把 HeicodeTask 快照转换成 Manager 可创建的 Agnet 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": "agnet-model-builder",
  "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": "smoke-model",
  "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	否	子 Agnet 默认运行模型
`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": "agnet",
        "agents": [
          {
            "role": "backend",
            "model_ref": "agnet-model-builder",
            "instance_count": 1
          }
        ]
      },
      "agents": [
        {
          "role_template": "backend",
          "goal": "Execute the Heicode task as backend within the approved resource scope.",
          "default_model_id": "agnet-model-builder",
          "resource_grants": []
        }
      ],
      "constraints": {
        "allowed_model_ids": []
      },
      "metadata": {
        "correlation_id": "task-task_abc123-xxxxxxxx"
      }
    }
  }
}

7. 创建 Manager Deployment

`POST /api/agnet/user/deployments`

使用上一步 orchestration_plan 创建 Manager deployment。

请求：

{
  "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": "agnet",
      "agents": [
        {
          "role": "backend",
          "model_ref": "agnet-model-builder",
          "instance_count": 1
        }
      ]
    },
    "agents": [
      {
        "role_template": "backend",
        "goal": "Execute the Heicode task as backend within the approved resource scope.",
        "default_model_id": "agnet-model-builder",
        "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 仍可创建，但不会进入真实执行。

8. 查询 Deployment

8.1 列表

`GET /api/agnet/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/agnet/user/deployments/{deployment_id}`

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

8.3 停止

`POST /api/agnet/user/deployments/{deployment_id}/stop`

请求：

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

响应：

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

9. 执行反馈查询

9.1 Events

`GET /api/agnet/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/agnet/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/agnet/user/deployments/{deployment_id}/metrics`

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

响应：

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

9.4 Artifacts

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

查询中间交付物和最终交付物摘要。

响应：

{
  "success": true,
  "data": {
    "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",
        "created_at": 1779850000000
      }
    ],
    "items": [],
    "total": 1
  }
}

9.5 SK Snapshots

`GET /api/agnet/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/agnet/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/agnet/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": "agnet-runtime",
        "request_reason": "需要写入功能分支",
        "ttl_seconds": 900,
        "expires_at": 1779850900000,
        "created_at": 1779850000000
      }
    ]
  }
}

10.2 同意审批

`POST /api/agnet/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://agnet/lease_xxx",
      "status": "active",
      "expires_at": 1779850900000
    }
  }
}

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

10.3 拒绝审批

`POST /api/agnet/approvals/{approval_id}/reject`

请求：

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

响应：

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

10.4 查询 lease

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

响应：

{
  "success": true,
  "data": {
    "items": [
      {
        "lease_id": "lease_xxx",
        "credential_ref": "lease://agnet/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/agnet/credential-leases/{lease_id}/revoke`

请求：

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

响应：

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

11. 角色模板

`GET /api/agnet/role-templates`

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

响应：

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

12. 状态枚举

HeicodeTask.status

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

Agnet Deployment.status

状态	说明
`accepted`	Manager 已接受并落本地记录
`running`	Runtime 已开始执行
`stopped`	已停止
`failed`	失败

Agnet Deployment.runtime_state

状态	说明
`queued`	Manager 本地队列/占位，尚未同步真实 Runtime
`runtime_syncing`	正在同步 Runtime
`runtime_accepted`	Runtime 接受
`runtime_sync_failed`	Runtime 同步失败
`not_configured`	生产 Runtime 未配置

普通 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. 桌面端最小伪代码

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

const task = await mcp.post('/api/heicode-auth/api/user/tasks/intent', {
  intent: userInput,
}, {
  headers: {
    Authorization: `Bearer ${heicodeAccessToken}`,
  },
})

let current = task.data
while (current.status === 'configuring') {
  const followup = findNextFollowup(current)
  const answer = await askUser(followup)
  current = await mcp.post(
    `/api/heicode-auth/api/user/tasks/${current.id}/answer`,
    {
      question_id: followup.id,
      option_id: answer.id,
    }
  ).then((r) => r.data)
}

const draft = await manager.post(
  `/api/agnet/user/tasks/${current.id}/deployment-draft`,
  {
    task: current,
    sub_mode: 'agile',
    binding_scope: `task-${current.id}`,
    role_templates: ['backend', 'frontend', 'reviewer'],
    default_model_id: 'agnet-model-builder',
  },
  { headers: { 'New-Api-User': String(userId) } }
)

const deployment = await manager.post(
  '/api/agnet/user/deployments',
  { orchestration_plan: draft.data.orchestration_plan },
  { headers: { 'New-Api-User': String(userId) } }
)

const deploymentId = deployment.data.deployment_id

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

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

15. 当前生产注意事项

https://code.xinghanlab.com 的 Manager 用户态接口已上线。
Manager 本地控制面可创建 sub_mode=agile/waterfall deployment。
生产 Manager 已配置 Agent Manager Runtime，当前直接走 http://20.212.121.126；域名和 HTTPS 后续单独处理，不作为客户端当前接入阻塞项。
deployment-draft -> create -> detail -> stop 已在生产验证通过，客户端可按本文参数形状接入。
events/logs/artifacts/sk-snapshots/timeline 查询接口已验证不报错；真实阶段事件、产物、SK 调用结果需要 Agent Manager 执行任务并回调后才会出现。
POST /api/heicode-auth/api/user/tasks/intent 需要桌面客户端提供 heicode_access_token；没有该 token 会返回 401。

27 KiB Raw Blame History Unescape Escape

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

1. 对接目标

2. 认证与公共约定

2.1 API 分组

2.2 Manager 用户态 Header

2.3 统一响应 Envelope

3. 推荐完整流程

3.1 2026-05-27 生产验证结果

4. 当前用户信息

GET /api/user/self

5. HeicodeTask 任务编排

5.1 创建任务

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

5.2 查询任务列表

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

5.3 查询任务详情

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

5.4 回答追问

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

6. 从任务生成 Agnet Deployment Draft

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

7. 创建 Manager Deployment

POST /api/agnet/user/deployments

8. 查询 Deployment

8.1 列表

GET /api/agnet/user/deployments

8.2 详情

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

8.3 停止

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

9. 执行反馈查询

9.1 Events

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

9.2 Logs

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

9.3 Metrics

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

9.4 Artifacts

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

9.5 SK Snapshots

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

9.6 Timeline

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

10. 审批与短期凭证

10.1 查询待审批

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

10.2 同意审批

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

10.3 拒绝审批

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

10.4 查询 lease

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

10.5 撤销 lease

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

11. 角色模板

GET /api/agnet/role-templates

12. 状态枚举

HeicodeTask.status

Agnet Deployment.status

Agnet Deployment.runtime_state

普通 sub 子环节建议值

13. 错误码

14. 桌面端最小伪代码

15. 当前生产注意事项

27 KiB

Raw Blame History

`GET /api/user/self`

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

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

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

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

`POST /api/agnet/user/tasks/{task_id}/deployment-draft`

`POST /api/agnet/user/deployments`

`GET /api/agnet/user/deployments`

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

`POST /api/agnet/user/deployments/{deployment_id}/stop`

`GET /api/agnet/user/deployments/{deployment_id}/events`

`GET /api/agnet/user/deployments/{deployment_id}/logs`

`GET /api/agnet/user/deployments/{deployment_id}/metrics`

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

`GET /api/agnet/user/deployments/{deployment_id}/sk-snapshots`

`GET /api/agnet/user/deployments/{deployment_id}/timeline`

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

`POST /api/agnet/approvals/{approval_id}/approve`

`POST /api/agnet/approvals/{approval_id}/reject`

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

`POST /api/agnet/credential-leases/{lease_id}/revoke`

`GET /api/agnet/role-templates`