docs(integration): professional accuracy pass on client + AM contract

- 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 <noreply@anthropic.com>

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":"<HEICODE_AGENT_ID>","access_token":"<X-Agent-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":"<HEICODE_AGENT_ID>","access_token":"<X-Agent-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` 生效。

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 → 直连用**。部署/管理主要在网页台完成(客户端也可调同一接口)。