im_wower
·
2026-04-02
business-interfaces.md
1# 业务类接口
2
3这份文档给网页版 AI、CLI AI 和自动化脚本使用。
4
5目标不是让调用方“猜接口”，而是让调用方先完成能力感知，再决定下一步动作。
6
7推荐顺序：
8
91. 先读本文件
102. 再请求 `GET /describe/business`
113. 如有需要，再请求 `GET /v1/capabilities`
124. 确认当前可用能力后，再调用具体业务接口
13
14控制类接口单独见：
15
16- [`control-interfaces.md`](./control-interfaces.md)
17
18## 当前推荐入口
19
20当前项目是 `mini` 单节点模式。
21
22推荐优先级：
23
241. 内网真相源：`http://100.71.210.78:4317`
252. 公网入口：`https://conductor.makefile.so`
26
27说明：
28
29- 本地 `4317` 是当前主真相源
30- `conductor.makefile.so` 是公网访问入口
31- 如果文档或旧配置还提到单独 `control-api` 域名，也只按 legacy 兼容 / 残留依赖盘点理解，不再作为业务接口主入口
32
33## 给 AI 的最小使用规则
34
35在 CLI、网页版 AI 或手机端 AI 里，推荐固定遵守这套顺序：
36
371. 先读本文件
382. 再调 `GET /describe/business`
393. 再调 `GET /v1/capabilities`
404. 只使用 `capabilities` 明确声明存在的接口
415. 如果目的是本机 shell 或文件操作，切到 [`control-interfaces.md`](./control-interfaces.md) 和 `GET /describe/control`
42
43## 当前已经可用的业务类接口
44
45### 发现与说明
46
47| 方法 | 路径 | 作用 |
48| --- | --- | --- |
49| `GET` | `/describe/business` | 返回业务类自描述、当前模式、示例和注意事项 |
50| `GET` | `/v1/capabilities` | 返回当前已启用的读/写/诊断能力摘要 |
51
52### 只读业务查询
53
54| 方法 | 路径 | 作用 |
55| --- | --- | --- |
56| `GET` | `/v1/browser` | 查看浏览器登录态元数据、持久化记录、插件在线状态，以及供 Firefox 浮层同步的 `automation_conversations` 快照 |
57| `GET` | `/v1/browser/claude/current` | 查看当前 Claude 代理回读结果；这是 legacy Claude 辅助读接口，不是浏览器桥接主模型 |
58| `GET` | `/v1/renewal/conversations?platform=chatgpt&status=paused` | 查看续命对话自动化状态，可按 `platform` / `status` 过滤 |
59| `GET` | `/v1/renewal/conversations/:local_conversation_id` | 查看单个本地续命对话、当前自动化状态和 active link |
60| `GET` | `/v1/renewal/links?platform=chatgpt&remote_conversation_id=conv_xxx` | 查看平台对话到本地对话、页面路由和代理目标的关联 |
61| `GET` | `/v1/renewal/jobs?status=pending&local_conversation_id=lc_xxx` | 查看续命任务列表，可按 `status` / `local_conversation_id` / `message_id` 过滤 |
62| `GET` | `/v1/renewal/jobs/:job_id` | 查看单个续命任务的 payload、目标快照、重试和最终状态 |
63| `GET` | `/v1/controllers?limit=20` | 查看当前 controller 摘要 |
64| `GET` | `/v1/tasks?status=queued&limit=20` | 查看任务列表，可按 `status` 过滤 |
65| `GET` | `/v1/tasks/:task_id` | 查看单个任务详情 |
66| `GET` | `/v1/tasks/:task_id/logs?limit=200` | 查看单个任务日志，可按 `run_id` 过滤 |
67
68### 通用浏览器请求接口
69
70| 方法 | 路径 | 作用 |
71| --- | --- | --- |
72| `POST` | `/v1/browser/request` | 通过 `conductor -> /ws/browser -> 插件页面内 HTTP 代理` 发起通用 browser request；当前正式支持 Claude 的 prompt/raw buffered / SSE 请求，以及 ChatGPT 的 path-based buffered / SSE 请求 |
73| `POST` | `/v1/browser/request/cancel` | 取消 request 或流；会向对应 browser client 下发正式 `request_cancel` |
74| `POST` | `/v1/browser/claude/send` | legacy 包装：等价映射到 `POST /v1/browser/request` |
75
76说明：
77
78- `GET /v1/browser` 是当前正式浏览器桥接读面；支持按 `platform`、`account`、`client_id`、`host`、`status` 过滤
79- 这个读面只返回 `account`、凭证指纹、端点元数据和时间戳状态；不会暴露原始 `cookie`、`token` 或 header 值
80- `GET /v1/browser` 现在会额外返回 `automation_conversations`，按 `platform + remote_conversation_id` 暴露当前对话的 `automation_status`、`pause_reason` 和 active link，供 Firefox / Safari 浮层和调试读面同步统一自动化状态
81- `records[].view` 会区分活跃连接与仅持久化记录，`status` 会暴露 `fresh`、`stale`、`lost`
82- 当前浏览器代发面正式支持 `claude`、`chatgpt` 和 `gemini`
83- `POST /v1/browser/request` 要求 `platform`；若 `platform=claude` 且省略 `path`，可用 `prompt` 走 Claude completion 兼容模式；`platform=chatgpt` / `platform=gemini` 当前都必须显式带 `path`
84- `POST /v1/browser/request` 支持 `responseMode=buffered` 和 `responseMode=sse`
85- `responseMode=sse` 会返回 `text/event-stream`，事件名固定为 `stream_open`、`stream_event`、`stream_end`、`stream_error`
86- `stream_event` 都带递增 `seq`；失败、超时或取消时会带着已收到的 partial 状态落到 `stream_error`
87- `GET /v1/browser` 会返回当前浏览器风控默认值和运行中 target/platform 状态摘要，便于观察限流、退避和熔断
88- `GET /v1/browser` 的 `policy.defaults.stale_lease` 会暴露后台清扫阈值；`policy.targets[]` 会补 `last_activity_*`、`stale_sweep_count`、`last_stale_sweep_*`，便于判断 slot 是否曾被后台自愈回收
89- `GET /v1/browser` 的 `policy` 关键运行态现在会从 `artifact.db` 恢复限流窗口、退避和熔断状态；`in_flight` / `waiting` 仍然只是当前进程内视图
90- `send` / `current` 不是 DOM 自动化，而是通过插件已有的页面内 HTTP 代理完成
91- renewal 读面当前分成三层：
92 - `conversations` 看自动化状态和 active link
93 - `links` 看平台对话到本地对话、页面和 tab 目标的映射
94 - `jobs` 看续命 dispatcher 的 `pending / running / done / failed`、重试次数、错误和目标快照
95- `renewal.conversations.read` 现在会额外返回：
96 - `pause_reason` / `last_error`
97 - `execution_state`
98 - `consecutive_failure_count`
99 - `repeated_message_count`
100 - `repeated_renewal_count`
101- `conductor` 启动时会自动释放异常退出遗留的 `execution_state`，并把 `status=running` 的 renewal job 安全回排为 `pending`
102- ChatGPT / Gemini raw relay 仍依赖浏览器里真实捕获到的登录态 / header；建议先看 `GET /v1/browser?platform=chatgpt&status=fresh`、`GET /v1/browser?platform=gemini&status=fresh`
103- 如果没有活跃 browser bridge client，会返回 `503`
104- 如果 client 还没有 Claude 凭证快照，会返回 `409`
105- 打开、聚焦、重载标签页等 browser/plugin 管理动作已经移到 [`control-interfaces.md`](./control-interfaces.md) 和 `GET /describe/control`
106
107### Codex 会话查询与写入
108
109| 方法 | 路径 | 作用 |
110| --- | --- | --- |
111| `GET` | `/v1/codex` | 查看当前 `conductor -> codexd` 代理状态 |
112| `GET` | `/v1/codex/sessions` | 查看当前 Codex sessions |
113| `GET` | `/v1/codex/sessions/:session_id` | 查看单个 Codex session |
114| `POST` | `/v1/codex/sessions` | 创建或恢复一个 Codex session |
115| `POST` | `/v1/codex/turn` | 向已有 session 提交一轮 turn |
116
117说明：
118
119- 这些 `/v1/codex/*` 路由固定代理到独立 `codexd`
120- `conductor-daemon` 不自己持有 Codex session 真相
121- turn 的回读统一通过 `GET /v1/codex/sessions/:session_id` 里的 `lastTurn*` 和 `recentEvents`
122- 正式能力只保留 session / turn / status
123
124## 当前不在业务面讨论的写接口
125
126下面这些能力里，`/v1/exec`、`/v1/files/read`、`/v1/files/write` 已经在本地 control / host-ops 面可用，但它们不属于“业务查询”接口：
127
128| 方法 | 路径 | 当前状态 |
129| --- | --- | --- |
130| `POST` | `/v1/exec` | 已可用；请改读 `control-interfaces.md` 和 `/describe/control` |
131| `POST` | `/v1/files/read` | 已可用；请改读 `control-interfaces.md` 和 `/describe/control` |
132| `POST` | `/v1/files/write` | 已可用；请改读 `control-interfaces.md` 和 `/describe/control` |
133| `POST` | `/v1/tasks` | 迁移中，不要默认假设已上线 |
134
135是否真的应该调用，仍然以 `/describe` 和 `/v1/capabilities` 的实际返回为准。
136
137## 推荐给 AI 的调用顺序
138
139### 先做能力感知
140
141```bash
142BASE_URL="http://100.71.210.78:4317"
143curl "${BASE_URL}/describe/business"
144```
145
146```bash
147BASE_URL="http://100.71.210.78:4317"
148curl "${BASE_URL}/v1/capabilities"
149```
150
151### 再做业务查询
152
153```bash
154BASE_URL="http://100.71.210.78:4317"
155curl "${BASE_URL}/v1/tasks?limit=5"
156```
157
158```bash
159BASE_URL="http://100.71.210.78:4317"
160curl "${BASE_URL}/v1/codex"
161```
162
163```bash
164BASE_URL="http://100.71.210.78:4317"
165curl "${BASE_URL}/v1/browser?platform=claude&status=fresh"
166```
167
168```bash
169BASE_URL="http://100.71.210.78:4317"
170curl -X POST "${BASE_URL}/v1/browser/request" \
171 -H 'Content-Type: application/json' \
172 -d '{"platform":"claude","prompt":"Summarize the current repository status."}'
173```
174
175```bash
176BASE_URL="http://100.71.210.78:4317"
177curl -X POST "${BASE_URL}/v1/browser/request" \
178 -H 'Content-Type: application/json' \
179 -d '{"platform":"chatgpt","method":"GET","path":"/backend-api/models"}'
180```
181
182```bash
183BASE_URL="http://100.71.210.78:4317"
184curl -X POST "${BASE_URL}/v1/browser/request/cancel" \
185 -H 'Content-Type: application/json' \
186 -d '{"platform":"claude","requestId":"browser-request-demo"}'
187```
188
189```bash
190BASE_URL="http://100.71.210.78:4317"
191curl "${BASE_URL}/v1/browser/claude/current"
192```
193
194```bash
195BASE_URL="http://100.71.210.78:4317"
196curl -X POST "${BASE_URL}/v1/codex/sessions" \
197 -H 'Content-Type: application/json' \
198 -d '{"cwd":"/Users/george/code/baa-conductor","purpose":"duplex"}'
199```
200
201```bash
202BASE_URL="http://100.71.210.78:4317"
203SESSION_ID="session-example"
204curl "${BASE_URL}/v1/codex/sessions/${SESSION_ID}"
205```
206
207```bash
208BASE_URL="http://100.71.210.78:4317"
209SESSION_ID="session-example"
210curl -X POST "${BASE_URL}/v1/codex/turn" \
211 -H 'Content-Type: application/json' \
212 -d "{\"sessionId\":\"${SESSION_ID}\",\"input\":\"Summarize pending work.\"}"
213```
214
215```bash
216BASE_URL="http://100.71.210.78:4317"
217TASK_ID="example-task-id"
218curl "${BASE_URL}/v1/tasks/${TASK_ID}"
219```
220
221```bash
222BASE_URL="http://100.71.210.78:4317"
223TASK_ID="example-task-id"
224curl "${BASE_URL}/v1/tasks/${TASK_ID}/logs?limit=50"
225```
226
227## CLI / 网页版 AI 推荐提示
228
229启动 CLI、网页版 AI 或手机网页 AI 时，建议先让它遵守下面这条规则：
230
231```text
232先阅读业务类接口文档，再请求 /describe/business 和 /v1/capabilities。
233只有在确认接口存在后，才调用具体业务接口；如果要做本机 shell 或文件操作，改读 /describe/control。
234```
235
236## 当前边界
237
238- 业务类接口当前以“只读查询”为主
239- 浏览器业务面当前以“登录态元数据读面 + 通用 browser request 合同”收口，不把页面对话 UI 当成正式能力
240- 浏览器 relay 当前正式支持 Claude 和 ChatGPT；其中 ChatGPT 仅支持显式 `path` 的 raw relay，且依赖本地 Firefox bridge 已连接和有效登录态
241- `/v1/browser/request/cancel` 已正式接到 Firefox bridge；`responseMode=sse` 会返回真实 `text/event-stream`
242- `/v1/codex/*` 是少数已经正式开放的业务写接口，但后端固定代理到独立 `codexd`
243- 控制动作例如 `pause` / `resume` / `drain` 不在本文件讨论范围内
244- 本机能力接口 `/v1/exec`、`/v1/files/read`、`/v1/files/write` 也不在本文件讨论范围内
245- 控制类接口见 [`control-interfaces.md`](./control-interfaces.md)