From 708d4103d158ac316106715151842d12f40eeb63 Mon Sep 17 00:00:00 2001
From: yibo <bboonnee@gmail.com>
Date: Tue, 25 Aug 2026 19:07:50 +0800
Subject: [PATCH] docs(open-api): 手册补全局 Agent invoke 端点

---
 docs/done/open-api-manual.md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/docs/done/open-api-manual.md b/docs/done/open-api-manual.md
index a3fe7f2..a402d22 100644
--- a/docs/done/open-api-manual.md
+++ b/docs/done/open-api-manual.md
@@ -30,8 +30,16 @@ OPEN_API_KEYS=sk-test-key-001,sk-prod-key-...
 
 ### 接口 ①：指派任务并获取 JobId (Invoke)
 
-**🔹 端点**：`POST /api/open/companies/:companyId/agents/:agentId/invoke`
-**🔹 作用**：唤起指定公司和指定名称的 Agent 执行任务。
+两个变体，选哪个只看这个 Agent 挂不挂在某家公司名下：
+
+- **公司级 Agent**：`POST /api/open/companies/:companyId/agents/:agentId/invoke`
+  这家公司必须已经雇过这个 Agent（`company_agents` 里有登记），没雇过一律 404。
+- **全局 Agent**：`POST /api/open/agents/:agentId/invoke`
+  面向不挂任何公司的系统级 specialist（比如 `master`、`agent-creator`、`h3-video-prompt`
+  这类），不查雇佣关系，只查这个 Agent 本体存不存在。`agentId` 里不能带 `companyId:role`
+  这种冒号前缀——那是公司级 Agent 的地址形态，传了会直接 400，提示改走上面那条。
+
+两者的请求体、返回值、轮询方式完全一样，下面统一说明。
 
 #### 请求参数 (Body)
 
@@ -42,6 +50,8 @@ OPEN_API_KEYS=sk-test-key-001,sk-prod-key-...
 | `webhookUrl` | String | 选填 | 回调地址。当任务完结时主动推送结果至该URL。| `"https://your-app/webhook"`|
 
 #### 代码示例 (cURL)
+
+公司级 Agent：
 ```bash
 curl -X POST http://YOUR_SERVER_IP:3010/api/open/companies/test/agents/claude-youtube-skills/invoke \
   -H "Authorization: Bearer sk-test-key-001" \
@@ -57,6 +67,16 @@ curl -X POST http://YOUR_SERVER_IP:3010/api/open/companies/test/agents/claude-yo
   }'
 ```
 
+全局 Agent（不带 companyId）：
+```bash
+curl -X POST https://lemonboss.wudaima.com/api/open/agents/h3-video-prompt/invoke \
+  -H "Authorization: Bearer sk-test-key-001" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "task": "帮我写一条 5 秒产品特写的 H3 视频提示词，主体是一杯冒着热气的咖啡"
+  }'
+```
+
 #### 返回值
 接口会光速返回 HTTP 202 的响应该结果：
 ```json
--
libgit2 0.21.4