baa-conductor

commit

0cdbd8a

parent

1786c1e

author

im_wower

date

2026-03-22 18:07:55 +0800 CST

docs(api): add business and control describe guides

 1@@ -14,10 +14,24 @@
 2 ## 先读什么
 3 
 4 1. [`DESIGN.md`](./DESIGN.md)
 5-2. [`docs/api/README.md`](./docs/api/README.md)
 6-3. [`docs/runtime/README.md`](./docs/runtime/README.md)
 7-4. [`docs/ops/README.md`](./docs/ops/README.md)
 8-5. [`coordination/TASK_OVERVIEW.md`](./coordination/TASK_OVERVIEW.md)
 9+2. [`docs/api/business-interfaces.md`](./docs/api/business-interfaces.md)
10+3. [`docs/api/control-interfaces.md`](./docs/api/control-interfaces.md)
11+4. [`docs/api/README.md`](./docs/api/README.md)
12+5. [`docs/runtime/README.md`](./docs/runtime/README.md)
13+6. [`docs/ops/README.md`](./docs/ops/README.md)
14+7. [`coordination/TASK_OVERVIEW.md`](./coordination/TASK_OVERVIEW.md)
15+
16+## 面向 AI 的推荐阅读顺序
17+
18+如果是网页版 AI、CLI AI 或手机网页 AI，推荐按这个顺序：
19+
20+1. 先读 [`docs/api/business-interfaces.md`](./docs/api/business-interfaces.md)
21+2. 再读 [`docs/api/control-interfaces.md`](./docs/api/control-interfaces.md)
22+3. 然后按用途调：
23+   - `GET /describe/business`
24+   - 或 `GET /describe/control`
25+4. 如有需要，再调 `GET /v1/capabilities`
26+5. 完成能力感知后，再执行业务查询或控制动作
27 
28 ## 当前目录结构
29 

  1@@ -0,0 +1,127 @@
  2+# 业务类接口
  3+
  4+这份文档给网页版 AI、CLI AI 和自动化脚本使用。
  5+
  6+目标不是让调用方“猜接口”，而是让调用方先完成能力感知，再决定下一步动作。
  7+
  8+推荐顺序：
  9+
 10+1. 先读本文件
 11+2. 再请求 `GET /describe/business`
 12+3. 如有需要，再请求 `GET /v1/capabilities`
 13+4. 确认当前可用能力后，再调用具体业务接口
 14+
 15+控制类接口单独见：
 16+
 17+- [`control-interfaces.md`](./control-interfaces.md)
 18+
 19+## 当前推荐入口
 20+
 21+当前项目是 `mini` 单节点模式。
 22+
 23+推荐优先级：
 24+
 25+1. 内网真相源：`http://100.71.210.78:4317`
 26+2. 公网入口：`https://conductor.makefile.so`
 27+
 28+说明：
 29+
 30+- 本地 `4317` 是当前主真相源
 31+- `conductor.makefile.so` 是公网访问入口
 32+- 历史兼容面的 `control-api.makefile.so` 不再是业务接口的主入口
 33+
 34+## 给 AI 的最小使用规则
 35+
 36+在 CLI、网页版 AI 或手机端 AI 里，推荐固定遵守这套顺序：
 37+
 38+1. 先读本文件
 39+2. 再调 `GET /describe/business`
 40+3. 再调 `GET /v1/capabilities`
 41+4. 只使用 `capabilities` 明确声明存在的接口
 42+5. 不要假设 `/v1/exec`、`/v1/files/read`、`/v1/files/write`、`POST /v1/tasks` 一定已经上线
 43+
 44+## 当前已经可用的业务类接口
 45+
 46+### 发现与说明
 47+
 48+| 方法 | 路径 | 作用 |
 49+| --- | --- | --- |
 50+| `GET` | `/describe/business` | 返回业务类自描述、当前模式、示例和注意事项 |
 51+| `GET` | `/v1/capabilities` | 返回当前已启用的读/写/诊断能力摘要 |
 52+
 53+### 只读业务查询
 54+
 55+| 方法 | 路径 | 作用 |
 56+| --- | --- | --- |
 57+| `GET` | `/v1/controllers?limit=20` | 查看当前 controller 摘要 |
 58+| `GET` | `/v1/tasks?status=queued&limit=20` | 查看任务列表，可按 `status` 过滤 |
 59+| `GET` | `/v1/tasks/:task_id` | 查看单个任务详情 |
 60+| `GET` | `/v1/tasks/:task_id/logs?limit=200` | 查看单个任务日志，可按 `run_id` 过滤 |
 61+| `GET` | `/v1/runs?limit=20` | 查看运行列表 |
 62+| `GET` | `/v1/runs/:run_id` | 查看单个运行详情 |
 63+
 64+## 当前不要假设已经可用的业务写接口
 65+
 66+这些能力已经有迁移方向，但当前不要让网页版 AI、CLI AI 在没有再次确认 `/describe/business` 和 `/v1/capabilities` 的情况下直接调用：
 67+
 68+| 方法 | 路径 | 当前状态 |
 69+| --- | --- | --- |
 70+| `POST` | `/v1/exec` | 迁移中，不要默认假设已上线 |
 71+| `POST` | `/v1/files/read` | 迁移中，不要默认假设已上线 |
 72+| `POST` | `/v1/files/write` | 迁移中，不要默认假设已上线 |
 73+| `POST` | `/v1/tasks` | 迁移中，不要默认假设已上线 |
 74+
 75+如果未来这些接口上线，应以 `/describe` 和 `/v1/capabilities` 的实际返回为准。
 76+
 77+## 推荐给 AI 的调用顺序
 78+
 79+### 先做能力感知
 80+
 81+```bash
 82+BASE_URL="http://100.71.210.78:4317"
 83+curl "${BASE_URL}/describe/business"
 84+```
 85+
 86+```bash
 87+BASE_URL="http://100.71.210.78:4317"
 88+curl "${BASE_URL}/v1/capabilities"
 89+```
 90+
 91+### 再做业务查询
 92+
 93+```bash
 94+BASE_URL="http://100.71.210.78:4317"
 95+curl "${BASE_URL}/v1/tasks?limit=5"
 96+```
 97+
 98+```bash
 99+BASE_URL="http://100.71.210.78:4317"
100+curl "${BASE_URL}/v1/runs?limit=5"
101+```
102+
103+```bash
104+BASE_URL="http://100.71.210.78:4317"
105+TASK_ID="example-task-id"
106+curl "${BASE_URL}/v1/tasks/${TASK_ID}"
107+```
108+
109+```bash
110+BASE_URL="http://100.71.210.78:4317"
111+TASK_ID="example-task-id"
112+curl "${BASE_URL}/v1/tasks/${TASK_ID}/logs?limit=50"
113+```
114+
115+## CLI / 网页版 AI 推荐提示
116+
117+启动 CLI、网页版 AI 或手机网页 AI 时，建议先让它遵守下面这条规则：
118+
119+```text
120+先阅读业务类接口文档，再请求 /describe/business 和 /v1/capabilities。
121+只有在确认接口存在后，才调用具体业务接口；不要假设写接口已经上线。
122+```
123+
124+## 当前边界
125+
126+- 业务类接口当前以“只读查询”为主
127+- 控制动作例如 `pause` / `resume` / `drain` 不在本文件讨论范围内
128+- 控制类接口见 [`control-interfaces.md`](./control-interfaces.md)

  1@@ -0,0 +1,128 @@
  2+# 控制类接口
  3+
  4+这份文档给网页版 AI、CLI AI 和人工运维使用。
  5+
  6+目标是：
  7+
  8+- 先完成能力感知
  9+- 再读取当前状态
 10+- 最后才执行控制动作
 11+
 12+业务类接口单独见：
 13+
 14+- [`business-interfaces.md`](./business-interfaces.md)
 15+
 16+## 当前推荐入口
 17+
 18+当前项目使用 `mini` 单节点模式。
 19+
 20+推荐优先级：
 21+
 22+1. 内网真相源：`http://100.71.210.78:4317`
 23+2. 公网入口：`https://conductor.makefile.so`
 24+
 25+## 给 AI 的控制顺序
 26+
 27+建议严格按这个顺序：
 28+
 29+1. 先读本文件
 30+2. 调 `GET /describe/control`
 31+3. 如有需要，再调 `GET /v1/capabilities`
 32+4. 调 `GET /v1/system/state`
 33+5. 确认当前模式和动作目标后，再执行 `pause` / `resume` / `drain`
 34+
 35+不要在未读状态前直接写入控制动作。
 36+
 37+## 当前可用控制类接口
 38+
 39+### 发现与诊断
 40+
 41+| 方法 | 路径 | 作用 |
 42+| --- | --- | --- |
 43+| `GET` | `/describe/control` | 返回控制类自描述和推荐使用顺序 |
 44+| `GET` | `/health` | 返回服务健康摘要 |
 45+| `GET` | `/version` | 返回服务版本摘要 |
 46+| `GET` | `/v1/capabilities` | 返回当前启用能力、读写分类和注意事项 |
 47+
 48+### 当前状态
 49+
 50+| 方法 | 路径 | 作用 |
 51+| --- | --- | --- |
 52+| `GET` | `/v1/system/state` | 返回当前 automation mode、leader、queue、active runs |
 53+
 54+### 控制动作
 55+
 56+| 方法 | 路径 | 作用 |
 57+| --- | --- | --- |
 58+| `POST` | `/v1/system/pause` | 切到 `paused` |
 59+| `POST` | `/v1/system/resume` | 切到 `running` |
 60+| `POST` | `/v1/system/drain` | 切到 `draining` |
 61+
 62+### 低层诊断
 63+
 64+| 方法 | 路径 | 作用 |
 65+| --- | --- | --- |
 66+| `GET` | `/healthz` | 最小健康探针 |
 67+| `GET` | `/readyz` | readiness 探针 |
 68+| `GET` | `/rolez` | 当前角色视图 |
 69+| `GET` | `/v1/runtime` | 本地运行时快照 |
 70+
 71+## 推荐给 AI 的调用顺序
 72+
 73+### 先看 describe
 74+
 75+```bash
 76+BASE_URL="http://100.71.210.78:4317"
 77+curl "${BASE_URL}/describe/control"
 78+```
 79+
 80+### 再看 capabilities
 81+
 82+```bash
 83+BASE_URL="http://100.71.210.78:4317"
 84+curl "${BASE_URL}/v1/capabilities"
 85+```
 86+
 87+### 再看当前 system state
 88+
 89+```bash
 90+BASE_URL="http://100.71.210.78:4317"
 91+curl "${BASE_URL}/v1/system/state"
 92+```
 93+
 94+### 最后再执行控制动作
 95+
 96+```bash
 97+BASE_URL="http://100.71.210.78:4317"
 98+curl -X POST "${BASE_URL}/v1/system/pause" \
 99+  -H 'Content-Type: application/json' \
100+  -d '{"requested_by":"web_ai","reason":"manual_pause"}'
101+```
102+
103+```bash
104+BASE_URL="http://100.71.210.78:4317"
105+curl -X POST "${BASE_URL}/v1/system/resume" \
106+  -H 'Content-Type: application/json' \
107+  -d '{"requested_by":"web_ai","reason":"manual_resume"}'
108+```
109+
110+```bash
111+BASE_URL="http://100.71.210.78:4317"
112+curl -X POST "${BASE_URL}/v1/system/drain" \
113+  -H 'Content-Type: application/json' \
114+  -d '{"requested_by":"web_ai","reason":"manual_drain"}'
115+```
116+
117+## 给 CLI / 网页版 AI 的推荐提示
118+
119+```text
120+先阅读控制类接口文档，再请求 /describe/control、/v1/capabilities、/v1/system/state。
121+只有在确认当前状态后，才执行 pause / resume / drain。
122+```
123+
124+## 当前边界
125+
126+- 当前控制面是单节点 `mini`
127+- 控制动作默认作用于当前唯一活动节点
128+- 业务查询和未来的本机能力接口不在本文件内讨论
129+- 业务类接口见 [`business-interfaces.md`](./business-interfaces.md)