From f128f4d03f80f8dc7854de957ad5fdd1d2bdad43 Mon Sep 17 00:00:00 2001 From: chenchen Date: Thu, 4 Jun 2026 22:42:55 +0800 Subject: [PATCH] docs(integration): professional accuracy pass on client + AM contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AM contract: fix stale lifecycle path defaults in the env-override table (/agents/{agent_id}, /agents/{agent_id}/stop — matches code, not the old /api/agent/... values); correct the self-check create line to POST /agents; align the verify-endpoint example to the real production response shape (user_id is a string, agent_id included, miss returns {valid:false}). - Client API: §0 overview now states HM mints the per-agent access_token (AM no longer "returns" it). Co-Authored-By: Claude Opus 4.8 --- docs/integration/heicode-am-contract.md | 11 +++++++---- docs/integration/heicode-desktop-client-api.md | 4 ++-- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/integration/heicode-am-contract.md b/docs/integration/heicode-am-contract.md index 0e00709d..1187c1e8 100644 --- a/docs/integration/heicode-am-contract.md +++ b/docs/integration/heicode-am-contract.md @@ -124,7 +124,10 @@ HM 把用户绑定的资源按**资源类型 + provider**解成固定 env 名( - 比较 `请求头 X-Agent-Access-Token == 自己 env 里的 AGENT_ACCESS_TOKEN`(常量时间比较,建议 `hmac.compare`/`secrets.compare_digest`)。两者是 HM 启动时注入的同一把密钥,**相等即放行,不等返回 401/403**。 - **不用回 HM、零额外依赖、零网络往返**。这是双方约定的正式接入方式。 - 缺失或为空(老 agent / 未注入)时如何处理由 AM 决定(建议:env 里有 `AGENT_ACCESS_TOKEN` 就强制校验,没有则放行以兼容)。 -- **可选兜底:HM 权威校验端点**(AM 不需要、默认不用;仅当 AM 想让 HM 当权威、或想顺带拿 `user_id` 时):`POST {HM}/api/heicode/agent-access/verify`,body `{"agent_id":"","access_token":""}` → `{"success":true,"data":{"valid":true,"user_id":22,"template_id":"..."}}`;不符只回 `{"valid":false}`。公开端点、常量时间比较。 +- **可选兜底:HM 权威校验端点**(AM 不需要、默认不用;仅当 AM 想让 HM 当权威、或想顺带拿 `user_id` 时)。公开端点、常量时间比较、生产实测可用: + - 请求:`POST {HM}/api/heicode/agent-access/verify`,`Content-Type: application/json`,body `{"agent_id":"","access_token":""}` + - 命中:`{"success":true,"data":{"valid":true,"agent_id":"dep_xxx","user_id":"22","template_id":"architect"}}`(`user_id` 为字符串) + - 不命中(令牌错 / agent 不存在 / 空令牌):`{"success":true,"data":{"valid":false}}`(不泄露任何用户信息) - **只有部署该 agent 的用户拿到令牌 ⇒ 只有他能调** = 「这个 agent 这个用户能调」。 - **通道加密 = TLS**:agent 子域名请走 **HTTPS**,令牌与对话内容由 TLS 加密;HM 不在回路,无需 HM 中转解密。 @@ -167,8 +170,8 @@ HM 这些路径都可用环境变量覆盖(默认值见 §1),AM 若用别的路 | `AGENT_RUNTIME_BASE_URL` | — | AM 基址(必须配,HTTPS/私网) | | `AGENT_RUNTIME_SERVICE_TOKEN` | — | HM 调 AM 的 Bearer | | `AGENT_RUNTIME_AGENT_START_PATH` | `/agents` | 启动(你们的 create) | -| `AGENT_RUNTIME_AGENT_PATH` | `/api/agent/agents/{agent_id}` | 取状态(GET)/删除(DELETE) | -| `AGENT_RUNTIME_AGENT_STOP_PATH` | `/api/agent/agents/{agent_id}/stop` | 停止 | +| `AGENT_RUNTIME_AGENT_PATH` | `/agents/{agent_id}` | 取状态(GET)/删除(DELETE) | +| `AGENT_RUNTIME_AGENT_STOP_PATH` | `/agents/{agent_id}/stop` | 停止 | | `AGENT_RUNTIME_START_TIMEOUT_SECONDS` | `60` | 启动超时 | > 字段名若需调整(如 `subdomain`→别的),只改 `heicode/controller/agent_template_runtime.go` 中 `amStartTemplateAgent`/`amGetAgentStatus` 的解析键一处即可,其余 HM 代码不动。 @@ -177,7 +180,7 @@ HM 这些路径都可用环境变量覆盖(默认值见 §1),AM 若用别的路 ## 7. 联调自检清单 -- [ ] `POST /agents/start` 收到 `agent_definition`+`env`+`callback_url`,起 agent、注入 env、返回 `{runtime_id, subdomain, access_token, status}`。 +- [ ] `POST /agents` 收到 `config`+`env`(含 `AGENT_INSTRUCTION_TEXT`/`AGENT_ROLE_NAME`/`AGENT_ACCESS_TOKEN`),起 agent、注入 env、返回 `{namespace 或 runtime_id, access_info.domain 或 subdomain, status}`。 - [ ] agent 用模型打到 HM `/v1/*`(带用户身份),计费正常。 - [ ] agent 子域名按 §3.1 ① **本地比对** `X-Agent-Access-Token == env AGENT_ACCESS_TOKEN`(常量时间);不符返回 401/403,非该 agent 所有者的调用被拒。 - [ ] `GET /agents/{id}` 返回真实 status;`stop`/`delete` 生效。 diff --git a/docs/integration/heicode-desktop-client-api.md b/docs/integration/heicode-desktop-client-api.md index cd6f104b..c92080be 100644 --- a/docs/integration/heicode-desktop-client-api.md +++ b/docs/integration/heicode-desktop-client-api.md @@ -16,8 +16,8 @@ 新模型很简单: 1. 用户在 **HM 网页控制台**绑定资源(git/vm/数据库/对象存储)、选「资源 + 模板」**部署一个常驻 agent**。 -2. HM 把所选资源解出后注入 agent 的 `.env`,交给 **AM** 启动;AM 返回**唯一子域名 + 访问 token**。 -3. **桌面客户端**从 HM 读 agent 列表 → 拿到**子域名 + token** → **直连 agent 子域名(SSE)对话使用**。**HM 不在对话回路里。** +2. HM 把所选资源解出后注入 agent 的 `.env`(并**现签一把 per-agent 访问令牌**一起注入),交给 **AM** 启动;AM 返回**唯一子域名**。 +3. **桌面客户端**从 HM 读 agent 列表 → 拿到**子域名 + 访问令牌**(HM 现签的 `access_token`)→ **直连 agent 子域名(SSE)对话使用**。**HM 不在对话回路里。** 4. **模型调用**:客户端自己用模型、以及 agent 用模型,**都走 HM `/v1/*`**(鉴权 + 计费)。 > 客户端在新模型里的核心动作 = **列出我的 agent → 直连用**。部署/管理主要在网页台完成(客户端也可调同一接口)。