omp-worker-mcp 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +430 -263
- package/README.zh-CN.md +428 -260
- package/bin/omp-worker-mcp.mjs +2 -10
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/runner.js +43 -13
- package/dist/runner.js.map +1 -1
- package/dist/security.js +66 -0
- package/dist/security.js.map +1 -0
- package/dist/version.js +19 -0
- package/dist/version.js.map +1 -0
- package/package.json +11 -3
- package/server.json +39 -0
package/README.zh-CN.md
CHANGED
|
@@ -1,260 +1,428 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
# omp-worker-mcp
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
[ Worker。**
|
|
6
|
+
|
|
7
|
+
一个 MCP 服务器：让 ChatGPT、Codex、Claude Code、Cursor 等 MCP 客户端当“主控”，<br />
|
|
8
|
+
让你电脑上的 Oh My Pi（OMP）当它在后台干活的“执行者”。
|
|
9
|
+
|
|
10
|
+
[](https://www.npmjs.com/package/omp-worker-mcp)
|
|
11
|
+
[](https://github.com/divenire990/omp-worker-mcp/actions/workflows/ci.yml)
|
|
12
|
+
[](package.json)
|
|
13
|
+
[](server.json)
|
|
14
|
+
[](LICENSE)
|
|
15
|
+
|
|
16
|
+
[English](README.md) · 简体中文 · [文档中心](docs/README.zh-CN.md)
|
|
17
|
+
|
|
18
|
+
<br />
|
|
19
|
+
|
|
20
|
+
<img src="assets/how-it-works.zh-CN.svg" alt="主控 Agent 通过 omp-worker-mcp 把任务委派给后台 OMP Worker，Worker 返回结构化结果供主控审查" width="860" />
|
|
21
|
+
|
|
22
|
+
[快速开始](#快速开始) · [使用示例](#使用示例) · [工具一览](#工具一览) · [配置](#配置) · [安全模型](#安全模型) · [常见问题](#常见问题)
|
|
23
|
+
|
|
24
|
+
</div>
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 它解决什么问题
|
|
29
|
+
|
|
30
|
+
大多数编程 Agent 什么都自己干：读代码、做计划、改文件、跑测试、修 bug，全挤在同一个对话、同一个模型的额度里。`omp-worker-mcp` 把这件事拆成两个角色：
|
|
31
|
+
|
|
32
|
+
| 角色 | 由谁担任 | 负责什么 |
|
|
33
|
+
| :--- | :--- | :--- |
|
|
34
|
+
| **主控（Supervisor）** | 你正在对话的 Agent：ChatGPT、Codex、Claude Code、Cursor… | 理解需求、拆分任务、写验收标准、审查结果 |
|
|
35
|
+
| **执行者（Worker）** | 你本机的 OMP CLI，使用你在 `omp setup` 里选的模型 | 读文件、改代码、跑命令和测试、汇报结果 |
|
|
36
|
+
|
|
37
|
+
`omp-worker-mcp` 就是两者之间的桥：它给主控提供一组 MCP 工具，在后台启动 OMP，把每个任务记录在磁盘上，最后交回一份简短的结构化报告，而不是一大段日志。
|
|
38
|
+
|
|
39
|
+
**主要特点**
|
|
40
|
+
|
|
41
|
+
- **单个任务或整套计划都行**：`omp_run_compact` 委派单个任务；`omp_run_batch_compact` 把最多 50 个任务按依赖关系（DAG）调度，最多 10 个同时跑。
|
|
42
|
+
- **声明式写入范围校验**：批量并行的写任务必须声明自己负责的路径，声明范围重叠或依赖成环会在任何 Worker 启动前被拒绝（属于调度前检查与提示词约束，而非系统级文件锁）。
|
|
43
|
+
- **结果可审查**：每个 Worker 都以 `OMP_WORKER_RESULT` 收尾：状态、摘要、改了哪些文件、验证证据、遗留事项。
|
|
44
|
+
- **返工不用从头来**：`omp_continue` 把反馈发回**同一个** OMP 会话，Worker 保留之前的上下文。
|
|
45
|
+
- **任务记录持久化**：任务元数据、日志和结果都存在磁盘上，MCP 服务器重启后依然可以查询。
|
|
46
|
+
- **网页版 ChatGPT 也能用**：通过 OpenAI Secure MCP Tunnel 连接，本机不开放入站端口，并可通过 `OMP_WORKER_ALLOWED_ROOTS` 限制任务只能在指定目录中运行（自 `0.2.0` 起提供；历史版本 npm `0.1.1` 不具备该特性）。
|
|
47
|
+
|
|
48
|
+
## 适合什么场景
|
|
49
|
+
|
|
50
|
+
**适合：**
|
|
51
|
+
|
|
52
|
+
- 想让强模型做决策，让更快或更便宜的模型去写代码；
|
|
53
|
+
- 任务够大、值得委派：一个功能、带测试的 bug 修复、跨模块重构、较长的只读调研；
|
|
54
|
+
- 想让仓库里不同部分并行推进，又不想多个 Agent 互相覆盖；
|
|
55
|
+
- 习惯用 ChatGPT 思考，希望它能直接操作你电脑上的文件。
|
|
56
|
+
|
|
57
|
+
**不太值得：**
|
|
58
|
+
|
|
59
|
+
- 只改一行或者问个小问题——主控自己动手更快；
|
|
60
|
+
- 你需要真正的系统级沙箱。本项目控制的是任务**在哪里启动**、**被告知能碰什么**，而不是 OMP 在技术上能做什么（见[安全模型](#安全模型)）。
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## 快速开始
|
|
65
|
+
|
|
66
|
+
**前置条件：** Node.js ≥ 22 · 已安装 [Oh My Pi](https://github.com/can1357/oh-my-pi) · 一个 MCP 客户端（Codex、Claude Code、Cursor、ChatGPT 等）。
|
|
67
|
+
|
|
68
|
+
### 1. 安装并配置 OMP
|
|
69
|
+
|
|
70
|
+
按 [OMP 官方说明](https://github.com/can1357/oh-my-pi) 安装，然后执行：
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
omp --version # 确认命令在 PATH 中
|
|
74
|
+
omp setup # 登录并选择默认模型
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
这里选的默认模型，就是所有 Worker 干活时使用的模型。（进阶：也可以在 `~/.omp/agent/config.yml` 中设置 `modelRoles.default: <provider>/<model>`。）
|
|
78
|
+
|
|
79
|
+
> 如果 `omp` 不在 `PATH` 中，请在下面的 MCP 配置里把 `OMP_WORKER_OMP_COMMAND` 设为可执行文件的完整路径。
|
|
80
|
+
|
|
81
|
+
### 2. 在客户端中注册 MCP 服务器
|
|
82
|
+
|
|
83
|
+
不需要全局安装——客户端会用 `npx -y omp-worker-mcp` 直接运行已发布的 npm 包。选择你的客户端：
|
|
84
|
+
|
|
85
|
+
<details open>
|
|
86
|
+
<summary><b>Codex</b>（作者日常使用的配置）</summary>
|
|
87
|
+
|
|
88
|
+
编辑 `~/.codex/config.toml`（Windows：`C:\Users\<你>\.codex\config.toml`）：
|
|
89
|
+
|
|
90
|
+
```toml
|
|
91
|
+
[mcp_servers.omp-worker]
|
|
92
|
+
command = "npx"
|
|
93
|
+
args = ["-y", "omp-worker-mcp"]
|
|
94
|
+
|
|
95
|
+
[mcp_servers.omp-worker.env]
|
|
96
|
+
OMP_WORKER_OMP_COMMAND = "omp"
|
|
97
|
+
|
|
98
|
+
# 可选（仅用于 Codex Code Mode）：让 Codex 直接调用 omp-worker 工具而不经过 code-mode 包装。
|
|
99
|
+
# 按当前官方 Codex 配置参考，请合并进已有的 [features.code_mode] 表（切勿重复声明同名表头），
|
|
100
|
+
# 并将 "mcp__omp_worker" 追加到列表中（保留你已有的其他条目，避免覆盖）：
|
|
101
|
+
[features.code_mode]
|
|
102
|
+
direct_only_tool_namespaces = ["mcp__omp_worker"]
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
*（如果 `config.toml` 中已有 `[features.code_mode]` 表，请直接合并进该表并在 `direct_only_tool_namespaces` 列表中追加 `"mcp__omp_worker"`，避免产生重复表头或覆盖已有列表项。旧版 Codex 曾使用写在所有 `[表头]` 之前的顶层键 `direct_only_tool_namespaces = ["mcp__omp_worker"]`。无论新旧写法均为可选偏好，并非注册 MCP 服务所必需；详见 [Codex 专属直接命名空间配置](docs/author-workflow.zh-CN.md#codex-专属直接命名空间配置) 与 [Codex 官方配置参考](https://learn.chatgpt.com/docs/config-file/config-reference)。）*
|
|
106
|
+
|
|
107
|
+
</details>
|
|
108
|
+
|
|
109
|
+
<details>
|
|
110
|
+
<summary><b>ChatGPT（网页版）</b>：通过 Secure MCP Tunnel</summary>
|
|
111
|
+
|
|
112
|
+
> **版本要求（`>= 0.2.0`）：** `OMP_WORKER_ALLOWED_ROOTS` 自 `omp-worker-mcp` `0.2.0` 起提供（历史版本 npm `0.1.1` 不具备该特性，不会执行 `OMP_WORKER_ALLOWED_ROOTS` 目录白名单检查）。远程暴露本机执行能力前，请确认 `npx -y omp-worker-mcp@latest --version` 返回 `0.2.0` 或更高版本。
|
|
113
|
+
|
|
114
|
+
在本机通过 OpenAI 的 `tunnel-client` 运行服务器，你的电脑只发起出站连接。
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
export OMP_WORKER_OMP_COMMAND=omp
|
|
118
|
+
export OMP_WORKER_ALLOWED_ROOTS='["/Users/you/Projects"]' # 远程访问时强烈建议设置（自 0.2.0 起提供；0.1.1 不具备该特性）
|
|
119
|
+
export CONTROL_PLANE_API_KEY='<runtime-api-key>'
|
|
120
|
+
|
|
121
|
+
tunnel-client init \
|
|
122
|
+
--sample sample_mcp_stdio_local \
|
|
123
|
+
--profile omp-worker \
|
|
124
|
+
--tunnel-id <your-tunnel-id> \
|
|
125
|
+
--mcp-command "npx -y omp-worker-mcp"
|
|
126
|
+
|
|
127
|
+
tunnel-client doctor --profile omp-worker --explain
|
|
128
|
+
tunnel-client run --profile omp-worker
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Windows PowerShell 写法、`0.1.1` 升级与本地构建说明、`tunnel-client runtimes connect` 托管模式、权限要求和完整信任边界见 [ChatGPT Secure MCP Tunnel 指南](docs/chatgpt-secure-tunnel.zh-CN.md)。
|
|
132
|
+
</details>
|
|
133
|
+
|
|
134
|
+
<details>
|
|
135
|
+
<summary><b>Claude Code</b></summary>
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
claude mcp add omp-worker --scope user --env OMP_WORKER_OMP_COMMAND=omp -- npx -y omp-worker-mcp
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
只想在当前项目使用，就把 `--scope user` 换成 `--scope project`。Windows `cmd.exe` 下如果 `npx` 找不到，改用 `cmd /c npx`。
|
|
142
|
+
|
|
143
|
+
</details>
|
|
144
|
+
|
|
145
|
+
<details>
|
|
146
|
+
<summary><b>Cursor · VS Code / Copilot · Windsurf · Continue · 其他 JSON 配置的客户端</b></summary>
|
|
147
|
+
|
|
148
|
+
```json
|
|
149
|
+
{
|
|
150
|
+
"mcpServers": {
|
|
151
|
+
"omp-worker": {
|
|
152
|
+
"command": "npx",
|
|
153
|
+
"args": ["-y", "omp-worker-mcp"],
|
|
154
|
+
"env": {
|
|
155
|
+
"OMP_WORKER_OMP_COMMAND": "omp"
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
各客户端的配置文件位置和注意事项见 [客户端接入与配置指南](docs/client-configurations.zh-CN.md)。
|
|
163
|
+
|
|
164
|
+
</details>
|
|
165
|
+
|
|
166
|
+
改完配置后重启客户端。
|
|
167
|
+
|
|
168
|
+
### 3. 告诉 Agent 什么时候该委派
|
|
169
|
+
|
|
170
|
+
注册服务器只是让工具**可用**，并不代表 Agent 会**主动选用**。在项目的指令文件里加一段简短规则——`AGENTS.md`（Codex）、`CLAUDE.md`（Claude Code）、`.cursorrules` / `.github/copilot-instructions.md`（其他客户端）——或者写进 ChatGPT 项目的说明里：
|
|
171
|
+
|
|
172
|
+
```markdown
|
|
173
|
+
## 委派规则（omp-worker-mcp）
|
|
174
|
+
- 简单问答、单文件小改、方案讨论：自己做。
|
|
175
|
+
- 有分量的单个任务（新功能、修 bug、重构、较长的调研）：先简单看一下代码，
|
|
176
|
+
再用 `omp_run_compact` 委派，写清楚 `goal` 和 `acceptance`。
|
|
177
|
+
- 多个部分的工作：用 `omp_run_batch_compact`。并行写任务的 `ownership` 不能重叠；
|
|
178
|
+
会改到同一批文件的任务要用 `depends_on` 排先后。
|
|
179
|
+
- 每个结果都要审查；没达到验收标准，就用 `omp_continue` 给出具体反馈。
|
|
180
|
+
- `git push`、发布、部署、修改密钥等操作不要委派，必须先和用户确认。
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
更完整的模板：[作者工作流 → 策略模板内容](docs/author-workflow.zh-CN.md#策略模板内容)。
|
|
184
|
+
|
|
185
|
+
### 4. 跑第一个任务
|
|
186
|
+
|
|
187
|
+
先从只读任务开始：
|
|
188
|
+
|
|
189
|
+
```text
|
|
190
|
+
请使用 omp-worker-mcp 对当前工作区做一次只读检查，总结项目结构和依赖情况。不要修改任何文件。
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
**正常情况下你会看到：** Agent 调用 `omp_run_compact`，OMP 在后台工作，然后返回一段简短总结，没有任何文件被修改。如果任务运行时间超过等待窗口（默认 60 秒），调用会先返回 `job_id` 和 `running` 状态，Agent 接着用 `omp_wait` 等待——这是正常现象。
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## 使用示例
|
|
198
|
+
|
|
199
|
+
配好委派规则后，你只要描述想要的结果即可。下面展示的是主控在背后实际发送的内容。
|
|
200
|
+
|
|
201
|
+
### 单个任务
|
|
202
|
+
|
|
203
|
+
> “给 `src/net/` 里的 HTTP 客户端加上指数退避重试，写单元测试，并确保 `npm test` 通过。”
|
|
204
|
+
|
|
205
|
+
```jsonc
|
|
206
|
+
// omp_run_compact
|
|
207
|
+
{
|
|
208
|
+
"cwd": "/path/to/repo",
|
|
209
|
+
"goal": "Add exponential backoff (max 5 retries) to src/net/client.ts for 5xx and network errors.",
|
|
210
|
+
"acceptance": [
|
|
211
|
+
"Unit tests cover the retry and give-up paths",
|
|
212
|
+
"npm test passes"
|
|
213
|
+
],
|
|
214
|
+
"timeout_minutes": 30
|
|
215
|
+
}
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
返回结果是精简过的（示例，有删减）：
|
|
219
|
+
|
|
220
|
+
```jsonc
|
|
221
|
+
{
|
|
222
|
+
"job_id": "job-…",
|
|
223
|
+
"status": "completed",
|
|
224
|
+
"attempt": 1,
|
|
225
|
+
"max_attempts": 3,
|
|
226
|
+
"session_id": "sess-…",
|
|
227
|
+
"summary": "Added retry with exponential backoff to the HTTP client.",
|
|
228
|
+
"artifacts": [
|
|
229
|
+
{ "path": "src/net/client.ts", "description": "retry loop + backoff helper" },
|
|
230
|
+
{ "path": "test/net/client.test.ts", "description": "retry / give-up tests" }
|
|
231
|
+
],
|
|
232
|
+
"verification": ["npm test: all tests passed"],
|
|
233
|
+
"remaining": [],
|
|
234
|
+
"details_path": "…/jobs/job-…/job.json"
|
|
235
|
+
}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
### 多个任务组成 DAG
|
|
239
|
+
|
|
240
|
+
> “并行给 API 加一个 `/health` 接口、给前端加一个状态徽标，完成后再写一个覆盖两者的集成测试。”
|
|
241
|
+
|
|
242
|
+
```mermaid
|
|
243
|
+
graph LR
|
|
244
|
+
api["api · 写 src/api/"] --> tests["tests · 写 tests/"]
|
|
245
|
+
ui["ui · 写 src/ui/"] --> tests
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
```jsonc
|
|
249
|
+
// omp_run_batch_compact
|
|
250
|
+
{
|
|
251
|
+
"cwd": "/path/to/repo",
|
|
252
|
+
"max_parallel": 2,
|
|
253
|
+
"tasks": [
|
|
254
|
+
{ "id": "api", "goal": "Add GET /health returning build info.", "access": "write", "ownership": ["src/api/"] },
|
|
255
|
+
{ "id": "ui", "goal": "Show a status badge fed by /health.", "access": "write", "ownership": ["src/ui/"] },
|
|
256
|
+
{ "id": "tests", "goal": "Add an integration test for /health and the badge.",
|
|
257
|
+
"depends_on": ["api", "ui"], "access": "write", "ownership": ["tests/"],
|
|
258
|
+
"acceptance": ["npm test passes"] }
|
|
259
|
+
]
|
|
260
|
+
}
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
需要记住的几条规则：
|
|
264
|
+
|
|
265
|
+
- `write` 任务必须在 `ownership` 中列出自己负责的路径（相对于 `cwd`）；`read_only` 任务不需要。
|
|
266
|
+
- 可能同时运行的两个任务不能负责重叠的路径——改用 `depends_on` 让它们先后执行。
|
|
267
|
+
- `max_parallel` 取值 1–10（默认 4）；整个任务组有总时限（`group_timeout_minutes`，默认 60 分钟）。
|
|
268
|
+
- 等待窗口结束时任务组还没跑完，会返回 `group_id`，用 `omp_wait_group` 继续等待。
|
|
269
|
+
|
|
270
|
+
### 监督任务
|
|
271
|
+
|
|
272
|
+
| 情况 | 使用的工具 |
|
|
273
|
+
| :--- | :--- |
|
|
274
|
+
| 还在运行 | `omp_wait` / `omp_wait_group` |
|
|
275
|
+
| 需要日志、每次尝试的记录或完整的最终回复 | `omp_result` |
|
|
276
|
+
| 结果没达到验收标准 | `omp_continue`，附上具体反馈（计入 `max_attempts`，默认 3 次） |
|
|
277
|
+
| 方向错了，要停下 | `omp_cancel` / `omp_cancel_group` |
|
|
278
|
+
|
|
279
|
+
---
|
|
280
|
+
|
|
281
|
+
## 工具一览
|
|
282
|
+
|
|
283
|
+
| 工具 | 类型 | 作用 |
|
|
284
|
+
| :--- | :--- | :--- |
|
|
285
|
+
| `omp_run_compact` | **推荐** | 启动单个任务，最多等待 `wait_seconds`（≤ 60）后返回精简结果 |
|
|
286
|
+
| `omp_run_batch_compact` | **推荐** | 校验并运行最多 50 个任务组成的 DAG，最多等待 `wait_seconds`（≤ 240） |
|
|
287
|
+
| `omp_delegate` | 底层 | 启动单个任务，立即返回 `job_id` |
|
|
288
|
+
| `omp_wait` | 底层 | 等待单个任务结束 |
|
|
289
|
+
| `omp_wait_group` | 底层 | 等待任务组结束 |
|
|
290
|
+
| `omp_result` | 查看 | 完整状态、尝试记录、`attempt-NN.stdout.jsonl` / `attempt-NN.stderr.log` 路径、最终回复 |
|
|
291
|
+
| `omp_continue` | 监督 | 向同一个 OMP 会话发送反馈，再尝试一次 |
|
|
292
|
+
| `omp_cancel` | 控制 | 停止任务及其进程树 |
|
|
293
|
+
| `omp_cancel_group` | 控制 | 停止任务组中所有排队和运行中的任务 |
|
|
294
|
+
|
|
295
|
+
完整参数与限制见 [工具参考](docs/tool-reference.zh-CN.md)。
|
|
296
|
+
|
|
297
|
+
---
|
|
298
|
+
|
|
299
|
+
## 配置
|
|
300
|
+
|
|
301
|
+
所有配置都通过环境变量完成：写在客户端 MCP 配置的 `env` 里，或者在启动服务器的 shell 中设置。
|
|
302
|
+
|
|
303
|
+
| 变量 | 默认值 | 用途 |
|
|
304
|
+
| :--- | :--- | :--- |
|
|
305
|
+
| `OMP_WORKER_OMP_COMMAND` | `omp` | OMP 可执行文件名或完整路径 |
|
|
306
|
+
| `OMP_WORKER_ALLOWED_ROOTS` | *（不设置 = 不限制）* | 绝对路径组成的 JSON 数组，任务只能在这些目录内运行。**任何远程使用都应设置。** *（自 `0.2.0` 起提供；npm `0.1.1` 不具备该特性。）* |
|
|
307
|
+
| `OMP_WORKER_STATE_DIR` | `~/.codex/state/omp-worker` | 任务状态、提示词和日志的存放位置（即使不用 Codex 也默认放在这里） |
|
|
308
|
+
| `OMP_WORKER_RETENTION_TTL_SECONDS` | *（不设置 = 永久保留）* | 删除超过 N 秒的已结束记录 |
|
|
309
|
+
| `OMP_WORKER_RETENTION_MAX_BYTES` | *（不设置 = 不限制）* | 存储超过 N 字节时，从最旧的已结束记录开始删除 |
|
|
310
|
+
|
|
311
|
+
完整变量表、磁盘目录结构和重启行为见 [运维与状态生命周期](docs/operations.zh-CN.md) · [`.env.example`](.env.example)。
|
|
312
|
+
|
|
313
|
+
---
|
|
314
|
+
|
|
315
|
+
## 安全模型
|
|
316
|
+
|
|
317
|
+
**`omp-worker-mcp` 会强制执行的：**
|
|
318
|
+
|
|
319
|
+
- 设置了 `OMP_WORKER_ALLOWED_ROOTS` 时*（自 `0.2.0` 起提供；npm `0.1.1` 不具备该特性）*，任务的 `cwd` 经 `realpath` 解析后必须位于某个允许的根目录内。同名前缀绕过、符号链接 / junction 逃逸都会在 OMP 启动前被拒绝；变量存在但内容无效时直接拒绝执行（fail closed）。
|
|
320
|
+
- 批量任务中，并行的 `write` 任务 `ownership` 必须互不重叠，依赖图不能有环——这些都在启动任何 Worker 之前检查。
|
|
321
|
+
- 写入范围和只读要求会作为明确约束传给每个 Worker。
|
|
322
|
+
|
|
323
|
+
**它不负责的：**
|
|
324
|
+
|
|
325
|
+
- 它**不是沙箱**。OMP 及其运行的一切，权限与启动服务器的系统账户完全相同。`ownership` 是调度时的检查加上对 Worker 的指令，不是文件系统锁。
|
|
326
|
+
- 它不替你判断什么操作安全。`git push`、发布、部署、修改密钥，应由你和主控亲自确认。
|
|
327
|
+
|
|
328
|
+
远程访问时（例如通过 Secure MCP Tunnel 让 ChatGPT 调用），务必设置 `OMP_WORKER_ALLOWED_ROOTS`，并考虑使用专用低权限账户、容器或虚拟机。报告安全漏洞请见 [SECURITY.md](SECURITY.md)。
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
## 平台支持
|
|
333
|
+
|
|
334
|
+
| 平台 | 状态 |
|
|
335
|
+
| :--- | :--- |
|
|
336
|
+
| Windows | ✅ 已用真实 OMP CLI 端到端验证，并在 CI（`windows-latest`）运行完整测试 |
|
|
337
|
+
| macOS | 🟡 CI（`macos-latest`）中运行完整测试（使用模拟 OMP），尚未用真实 OMP CLI 端到端验证 |
|
|
338
|
+
| Linux | 🟡 CI（`ubuntu-latest`）中运行完整测试（使用模拟 OMP），尚未用真实 OMP CLI 端到端验证 |
|
|
339
|
+
|
|
340
|
+
| 客户端 | 状态 |
|
|
341
|
+
| :--- | :--- |
|
|
342
|
+
| Codex | ✅ 作者日常使用 |
|
|
343
|
+
| ChatGPT 网页版（Secure MCP Tunnel） | 📄 提供完整配置与接入文档，见[指南](docs/chatgpt-secure-tunnel.zh-CN.md) |
|
|
344
|
+
| Claude Code、Cursor、VS Code / Copilot、Windsurf、Continue | 📄 提供配置文档，未在 CI 中做集成测试 |
|
|
345
|
+
| 云端 / 远程 Agent 环境 | ⚠️ 需要提供 Node.js ≥ 22、`PATH` 中的 OMP、可写工作区和启动子进程的权限 |
|
|
346
|
+
|
|
347
|
+
欢迎提交 Linux 实测反馈和你验证过的客户端配置，见 [贡献指南](CONTRIBUTING.zh-CN.md)。
|
|
348
|
+
|
|
349
|
+
---
|
|
350
|
+
|
|
351
|
+
## 常见问题
|
|
352
|
+
|
|
353
|
+
<details>
|
|
354
|
+
<summary><b>Agent 不调用这些工具，什么都自己做。</b></summary>
|
|
355
|
+
|
|
356
|
+
工具可用不等于会被选用。加上[第 3 步](#3-告诉-agent-什么时候该委派)的委派规则，或者在提示词里直接点名（“用 omp-worker-mcp 来……”）。启用了 Code Mode 的 Codex 用户还可以按需配置 `features.code_mode.direct_only_tool_namespaces`。
|
|
357
|
+
</details>
|
|
358
|
+
|
|
359
|
+
<details>
|
|
360
|
+
<summary><b>任务一启动就报 “command not found” 或 <code>ENOENT</code>。</b></summary>
|
|
361
|
+
|
|
362
|
+
MCP 服务器找不到 OMP。把 `OMP_WORKER_OMP_COMMAND` 设成可执行文件的完整路径——图形界面客户端的 `PATH` 往往比终端里的短。
|
|
363
|
+
</details>
|
|
364
|
+
|
|
365
|
+
<details>
|
|
366
|
+
<summary><b>返回的是 <code>job_id</code> 和 <code>running</code>，没有结果。</b></summary>
|
|
367
|
+
|
|
368
|
+
较长的任务都会这样：调用最多只等 `wait_seconds`，任务仍在后台继续运行。调用 `omp_wait`（或 `omp_wait_group`）继续等即可。
|
|
369
|
+
</details>
|
|
370
|
+
|
|
371
|
+
<details>
|
|
372
|
+
<summary><b>Worker 用的是哪个模型？</b></summary>
|
|
373
|
+
|
|
374
|
+
OMP 的默认模型，也就是 `omp setup` 里选的那个（或 `~/.omp/agent/config.yml` 中的 `modelRoles.default`）。主控用的是你客户端的模型——两者可以不同，这正是本项目的用意。
|
|
375
|
+
</details>
|
|
376
|
+
|
|
377
|
+
<details>
|
|
378
|
+
<summary><b>报错 “outside OMP_WORKER_ALLOWED_ROOTS”。</b></summary>
|
|
379
|
+
|
|
380
|
+
任务的 `cwd` 不在任何允许的根目录内，说明白名单在正常工作。如果这个目录本该允许，把它加进 `OMP_WORKER_ALLOWED_ROOTS`（注意：`OMP_WORKER_ALLOWED_ROOTS` 自 `0.2.0` 起提供；npm `0.1.1` 不具备该特性）。
|
|
381
|
+
</details>
|
|
382
|
+
|
|
383
|
+
<details>
|
|
384
|
+
<summary><b>报错 “Concurrent write ownership conflict”。</b></summary>
|
|
385
|
+
|
|
386
|
+
两个可能同时运行的任务负责的路径重叠了。把它们的 `ownership` 分开，或者加上 `depends_on` 让其中一个排在后面。
|
|
387
|
+
</details>
|
|
388
|
+
|
|
389
|
+
<details>
|
|
390
|
+
<summary><b>和客户端自带的子 Agent 有什么区别？</b></summary>
|
|
391
|
+
|
|
392
|
+
Worker 是独立的 Agent（OMP），可以用不同的模型和服务商；它在后台跨对话轮次运行，状态保存在磁盘上，任何 MCP 客户端都能驱动——包括网页版 ChatGPT。批量模式在此基础上还提供依赖排序和写入范围检查。
|
|
393
|
+
</details>
|
|
394
|
+
|
|
395
|
+
---
|
|
396
|
+
|
|
397
|
+
## 文档
|
|
398
|
+
|
|
399
|
+
| 文档 | 什么时候看 |
|
|
400
|
+
| :--- | :--- |
|
|
401
|
+
| [作者工作流](docs/author-workflow.zh-CN.md) | 配置委派规则，理解“委派 → 审查 → 返工”的监督闭环 |
|
|
402
|
+
| [客户端接入与配置](docs/client-configurations.zh-CN.md) | 配置 Codex、Claude Code、Cursor、VS Code、Windsurf、Continue |
|
|
403
|
+
| [ChatGPT Secure MCP Tunnel](docs/chatgpt-secure-tunnel.zh-CN.md) | 用网页版 ChatGPT 驱动本机 OMP |
|
|
404
|
+
| [工具参考](docs/tool-reference.zh-CN.md) | 查看所有工具、参数和结果信封 |
|
|
405
|
+
| [运维与状态生命周期](docs/operations.zh-CN.md) | 调整环境变量、存储、清理与重启行为 |
|
|
406
|
+
| [基准测试协议](benchmarks/README.zh-CN.md) | 对比直接执行与主控–Worker 委派 |
|
|
407
|
+
| [Registry 发布指南](docs/registry-publishing.zh-CN.md) | 发布到 npm 和官方 MCP Registry（维护者用） |
|
|
408
|
+
|
|
409
|
+
[COMPATIBILITY.md](COMPATIBILITY.md) 定义了公共契约与版本策略；[CHANGELOG.md](CHANGELOG.md) 记录各版本变化。
|
|
410
|
+
|
|
411
|
+
## 参与贡献
|
|
412
|
+
|
|
413
|
+
欢迎提 Issue 和 PR，尤其是 Linux 实测和验证过的客户端配置。请先阅读 [贡献指南](CONTRIBUTING.zh-CN.md)。从源码构建：
|
|
414
|
+
|
|
415
|
+
```bash
|
|
416
|
+
git clone https://github.com/divenire990/omp-worker-mcp.git
|
|
417
|
+
cd omp-worker-mcp
|
|
418
|
+
npm ci
|
|
419
|
+
npm test # 先构建，再用模拟 OMP 跑测试
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
## 致谢
|
|
423
|
+
|
|
424
|
+
基于 [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) 构建，围绕 [Oh My Pi](https://github.com/can1357/oh-my-pi)（MIT）设计。OMP 不随本包分发，需要单独安装。本项目为独立项目，与 OMP、OpenAI、Anthropic 均无隶属关系。
|
|
425
|
+
|
|
426
|
+
## 许可证
|
|
427
|
+
|
|
428
|
+
[MIT](LICENSE)
|