dsh-plugin-subagent-bridge 0.14.2 → 0.15.1
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 +200 -258
- package/index.js +30 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,271 +5,220 @@
|
|
|
5
5
|
<!-- M8ven ownership proof — keep this line in place; it verifies the publisher. -->
|
|
6
6
|
[](https://m8ven.ai/mcp/dogtiti-dsh-plugin-subagent-bridge-8a3t8k?s=readme)
|
|
7
7
|
|
|
8
|
-
在 DeepSeek Harness 宿主内部提供**本机回环 MCP
|
|
8
|
+
在 DeepSeek Harness 宿主内部提供**本机回环 MCP 端点**，让另一个智能体把任务派给 DSH 会话并取回结果；反过来，DSH 里的 agent 也能把任务派给 Codex 或 Claude Code。
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
两个方向共用同一个插件，各自遵守对方产品的 `maxDepth: 1`：**能派活，不能再派回来**。
|
|
11
11
|
|
|
12
12
|
---
|
|
13
13
|
|
|
14
|
-
##
|
|
14
|
+
## 能力一览
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
|
23
|
-
| --- | --- |
|
|
24
|
-
| `prompt` | 必填，任务正文 |
|
|
25
|
-
| `cwd` | 工作目录；默认用当前会话目录 |
|
|
26
|
-
| `resume` | Claude Code 的 session id，续接同一段对话 |
|
|
27
|
-
| `model` | 模型别名或 id；不传则用配置，再退回 Claude 自己的设置 |
|
|
28
|
-
|
|
29
|
-
返回 `{ ok, text, sessionId, durationMs }`，`sessionId` 就是下次 `resume` 用的那个。
|
|
30
|
-
|
|
31
|
-
和 `codex_dispatch` 的差别只在底层：Claude Code 的 `-p` 模式**一次输出一个 JSON 对象**（`{type:"result", result, session_id, is_error}`），不像 Codex 是事件流。所以解析器只看 stdout 的 JSON，**stderr 的警告不算失败**——比如模型名带 `[1M]` 后缀时 CLI 会警告，但仍然正常返回。
|
|
32
|
-
|
|
33
|
-
配置项：`claudeBin`（默认 `claude`）、`claudeModel`（默认空，即用 CLI 自己的设置）、`claudeTimeoutMs`（默认 300 秒，上限 240 秒夹取）。
|
|
34
|
-
|
|
35
|
-
## 创建项目（workspace）
|
|
36
|
-
|
|
37
|
-
DSH 的侧边栏分组是"项目（workspace）"，和会话的工作目录是两回事：新建会话默认落在「未分组」，除非它所在的目录已经是一个项目。
|
|
16
|
+
| 方向 | 入口 | 一次调用做什么 |
|
|
17
|
+
| --- | --- | --- |
|
|
18
|
+
| Codex / 任意 MCP 客户端 → DSH | `dsh_task` | 开会话、投递、阻塞到这一轮结束，只回最终答案 |
|
|
19
|
+
| 同上，并行 | `dsh_spawn` + `dsh_wait` | 立刻返回句柄，多个 worker 同时跑，再批量等 |
|
|
20
|
+
| 同上，续派 | `dsh_followup` | 复用 worker 的上下文再派一轮 |
|
|
21
|
+
| DSH → Codex | `codex_dispatch` | 跑一次 `codex exec`，回最终回答与可续接的线程 id |
|
|
22
|
+
| DSH → Claude Code | `claude_dispatch` | 跑一次 `claude -p`，回最终回答与可续接的 session id |
|
|
38
23
|
|
|
39
|
-
|
|
24
|
+
插件运行在宿主进程内，直接用公开服务（`sessionController`、`sessions`、`workspaceRegistry`、`userQuestions`），不需要读凭据文件，也不需要伪造 cookie。
|
|
40
25
|
|
|
41
|
-
|
|
42
|
-
// 目录不是项目 → 用它创建项目（标题取目录名），会话直接归到项目下
|
|
43
|
-
dsh_task({ prompt: "…", cwd: "/repo/clawer", workspace: true })
|
|
26
|
+
---
|
|
44
27
|
|
|
45
|
-
|
|
46
|
-
dsh_spawn({ task_name: "w1", message: "…", cwd: "/repo/clawer", workspace: "Clawer" })
|
|
28
|
+
## 安装
|
|
47
29
|
|
|
48
|
-
|
|
49
|
-
|
|
30
|
+
```bash
|
|
31
|
+
git clone https://github.com/Dogtiti/dsh-plugin-subagent-bridge
|
|
50
32
|
```
|
|
51
33
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
- 目录不存在时先递归创建，再做项目登记（登记要求目录已存在）；
|
|
55
|
-
- 目录已经是项目 → **直接复用，不改标题**（底层 `create` 对同一路径返回已有记录）；
|
|
56
|
-
- 返回结果里带上 `workspace: { id, title, path }`，方便确认落在哪个项目；
|
|
57
|
-
- 项目操作失败不影响派发本身（分组是外观，不因此让任务失败）。
|
|
58
|
-
|
|
59
|
-
## 回答 worker 的问题（`dsh_answer`）
|
|
60
|
-
|
|
61
|
-
worker 需要用户拍板时会调用 `ask_user_question`，然后**卡在那里等**。如果人不在，任务就停住了。
|
|
34
|
+
Plugins → 添加 → 选该目录。
|
|
62
35
|
|
|
63
|
-
|
|
36
|
+
启动后在 `127.0.0.1:47821` 监听，并把端点写到 `~/.dsh/bridge/endpoint.json`（目录 0700、文件 0600）：
|
|
64
37
|
|
|
65
|
-
```
|
|
66
|
-
// dsh_wait 的返回
|
|
38
|
+
```json
|
|
67
39
|
{
|
|
68
|
-
"
|
|
69
|
-
"
|
|
70
|
-
"
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
{
|
|
74
|
-
"id": "mode",
|
|
75
|
-
"question": "用哪种模式？",
|
|
76
|
-
"header": "Choose Mode",
|
|
77
|
-
"options": [{ "label": "快速", "description": "只跑单测" }, { "label": "完整" }]
|
|
78
|
-
}
|
|
79
|
-
]
|
|
80
|
-
},
|
|
81
|
-
"next": "blocked on a question: answer it with dsh_answer, or call dsh_wait again"
|
|
40
|
+
"url": "http://127.0.0.1:47821/mcp/<token>",
|
|
41
|
+
"port": 47821,
|
|
42
|
+
"token": "<token>",
|
|
43
|
+
"pid": 12345,
|
|
44
|
+
"startedAt": "2026-10-22T12:30:00.000Z"
|
|
82
45
|
}
|
|
83
46
|
```
|
|
84
47
|
|
|
85
|
-
|
|
48
|
+
## 接到 Codex
|
|
86
49
|
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
})
|
|
50
|
+
```bash
|
|
51
|
+
codex mcp add dsh-bridge --url "$(node -p "require(process.env.HOME+'/.dsh/bridge/endpoint.json').url")"
|
|
52
|
+
codex mcp list # 验证
|
|
53
|
+
codex mcp remove dsh-bridge # 移除
|
|
92
54
|
```
|
|
93
55
|
|
|
94
|
-
|
|
56
|
+
桌面 App 与 CLI 共用 `~/.codex/config.toml`，两端都会看到这条。
|
|
95
57
|
|
|
96
|
-
|
|
97
|
-
- `selected` 是选项 label 数组，多选时给多个；跳过一个问题就给空数组；
|
|
98
|
-
- 回答是插进正在等待的那个回合的（底层用 `steer`），worker 立刻继续；
|
|
99
|
-
- 只有真卡在 `ask_user_question` 上才算「等待中」——工具一旦返回结果就不再报。
|
|
58
|
+
> token 放在 URL 路径里（能力 URL），所以 Codex 侧不需要配环境变量——桌面 App 从 Finder 启动时拿不到自定义环境变量。也支持 `Authorization: Bearer <token>`，需要时可用 `--bearer-token-env-var`。
|
|
100
59
|
|
|
101
|
-
|
|
60
|
+
Claude Code 同理：
|
|
102
61
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
| `mode` | DSH 里的名字 | 行为 |
|
|
106
|
-
| --- | --- | --- |
|
|
107
|
-
| `queue`（默认） | 排队发送 | 等当前回合跑完，再作为一个新回合处理 |
|
|
108
|
-
| `steer` | 插话发送 | 并入当前回合，模型在下一步就能看到 |
|
|
109
|
-
|
|
110
|
-
`dsh_task`、`dsh_spawn`、`dsh_followup` 都支持：
|
|
111
|
-
|
|
112
|
-
```js
|
|
113
|
-
dsh_followup({ worker: "w1", message: "接下来只改 src 下的文件", mode: "steer" })
|
|
114
|
-
dsh_task({ sessionId: "session-…", prompt: "停一下，改成只跑单测", mode: "steer" })
|
|
62
|
+
```bash
|
|
63
|
+
claude mcp add --transport http dsh-bridge "<上面那个 url>" --scope user
|
|
115
64
|
```
|
|
116
65
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
1. **`steer` 不打断正在执行的工具**。实测 worker 正在跑 `sleep 90`，`steer` 的消息投递进去了，但要等那次工具调用返回、模型走到下一步才被看到——整整 70 秒。真想立刻停，是 DSH 界面上另一个动作（取消），不是投递模式。
|
|
120
|
-
2. **`steer` 不新开回合**（turn 编号不变），所以等待条件必须是「当前回合结束」。早期实现等的是「下一个回合」，答案都回来了、调用还在等，最后 120 秒超时。
|
|
121
|
-
|
|
122
|
-
`dsh_task` 对正在运行的会话默认会拒绝，错误信息里会提示改用 `steer`。
|
|
66
|
+
---
|
|
123
67
|
|
|
124
|
-
|
|
68
|
+
## 正向：Codex → DSH
|
|
125
69
|
|
|
126
|
-
|
|
70
|
+
### 工具
|
|
127
71
|
|
|
128
|
-
|
|
72
|
+
| 工具 | 作用 |
|
|
73
|
+
| --- | --- |
|
|
74
|
+
| `dsh_task` | **同步**派活：开会话、投递、阻塞到这一轮结束，只返回**最终回答** |
|
|
75
|
+
| `dsh_spawn` | **异步**派活：立刻返回 `task_name` + `sessionId`，可并行开多个 |
|
|
76
|
+
| `dsh_followup` | 给已有 worker 再派一轮（复用上下文） |
|
|
77
|
+
| `dsh_wait` | 一次等多批 worker，任一到达终态即返回 |
|
|
78
|
+
| `dsh_close` | 关闭 worker，释放并发名额（不删除会话） |
|
|
79
|
+
| `dsh_answer` | 代用户回答 worker 提出的问题（见「问题上报」） |
|
|
80
|
+
| `dsh_list_workers` | 列出本桥开的 worker 及实时状态 |
|
|
81
|
+
| `dsh_dispatch` | 向指定会话投递一条用户消息并开始一轮；返回 `requestId` 与 `seqAtDispatch` |
|
|
82
|
+
| `dsh_read_result` | **长轮询**读该会话在 `seqAtDispatch` 之后的全部助手文本（看过程用；要结果用 `dsh_wait`） |
|
|
83
|
+
| `dsh_list_sessions` | 列出会话**元数据**（id、标题、工作目录、是否运行、最后活动时间） |
|
|
129
84
|
|
|
130
|
-
|
|
85
|
+
### 基本用法
|
|
131
86
|
|
|
132
87
|
```js
|
|
133
|
-
//
|
|
134
|
-
dsh_task({ prompt: "
|
|
88
|
+
// 同步：等它跑完，直接拿最终答案
|
|
89
|
+
dsh_task({ prompt: "审一下 src/bridge.ts 的错误处理", cwd: "/repo", timeoutSeconds: 300 })
|
|
135
90
|
|
|
136
|
-
//
|
|
137
|
-
dsh_spawn({ task_name: "
|
|
91
|
+
// 并行：先拿句柄，再批量等
|
|
92
|
+
dsh_spawn({ task_name: "audit_api", message: "…", cwd: "/repo" })
|
|
93
|
+
dsh_spawn({ task_name: "audit_ui", message: "…", cwd: "/repo" })
|
|
94
|
+
dsh_wait({ targets: ["audit_api", "audit_ui"], timeoutMs: 240000 })
|
|
138
95
|
|
|
139
|
-
//
|
|
140
|
-
|
|
96
|
+
// 续派：复用 worker 的上下文
|
|
97
|
+
dsh_followup({ worker: "audit_api", message: "把第 3 条展开，给出补丁" })
|
|
141
98
|
```
|
|
142
99
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
- 目录不存在时先递归创建，再做项目登记（登记要求目录已存在）；
|
|
146
|
-
- 目录已经是项目 → **直接复用，不改标题**（底层 `create` 对同一路径返回已有记录）；
|
|
147
|
-
- 返回结果里带上 `workspace: { id, title, path }`，方便确认落在哪个项目；
|
|
148
|
-
- 项目操作失败不影响派发本身（分组是外观，不因此让任务失败）。
|
|
149
|
-
|
|
150
|
-
## 排队还是立刻打断（`mode`）
|
|
100
|
+
边界：
|
|
151
101
|
|
|
152
|
-
|
|
102
|
+
- `dsh_list_sessions` **只返回元数据**，不含任何消息内容；
|
|
103
|
+
- `dsh_read_result` 只对**本桥派发过**的会话生效，从未派发过的会话一律拒绝。
|
|
153
104
|
|
|
154
|
-
|
|
155
|
-
| --- | --- |
|
|
156
|
-
| `queue`（默认） | 等当前回合跑完再处理这条消息 |
|
|
157
|
-
| `steer` | 把消息**插进当前回合**（当前那一步仍会跑完） |
|
|
158
|
-
| `interrupt` | **先取消当前回合**，再发送，真正立刻停下 |
|
|
105
|
+
### 指定模型
|
|
159
106
|
|
|
160
|
-
`dsh_task`、`dsh_spawn`、`dsh_followup`
|
|
107
|
+
`dsh_task`、`dsh_spawn`、`dsh_followup` 都可以带 `model`：
|
|
161
108
|
|
|
162
109
|
```js
|
|
163
|
-
|
|
164
|
-
|
|
110
|
+
dsh_task({ prompt: "…", model: "zai-coding-cn/glm-5.3", reasoningEffort: "max" })
|
|
111
|
+
dsh_spawn({ task_name: "review", message: "…", model: "opencode-go/deepseek-v4.1-flash" })
|
|
165
112
|
```
|
|
166
113
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
114
|
+
- 写法是 `provider/model`；只写模型名时沿用当前默认 provider；
|
|
115
|
+
- `reasoningEffort` 可选，取值随模型；
|
|
116
|
+
- 不传就完全不动会话；
|
|
117
|
+
- 实测：请求确实切到指定模型，且**不会改写 profile 的默认模型**。
|
|
170
118
|
|
|
171
|
-
|
|
172
|
-
2. **`steer` 不新开回合**，所以等待条件不能是"下一个回合结束"。早期实现那样写，答案已经回来了、调用还在等，最后 120 秒超时。现在 steer 等的是「当前回合结束」。
|
|
119
|
+
实现上是在建好会话、发第一个 prompt **之前**调一次 `selectModel`，所以 worker 第一轮就在新模型上跑。
|
|
173
120
|
|
|
174
|
-
|
|
121
|
+
### 项目归属（`workspace`）
|
|
175
122
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
## 指定模型
|
|
179
|
-
|
|
180
|
-
`dsh_task`、`dsh_spawn`、`dsh_followup` 都可以带 `model`，让 worker 跑在指定模型上：
|
|
123
|
+
DSH 的侧边栏分组（项目 / workspace）和工作目录是两回事：新建会话默认落在「未分组」，除非所在目录已经是项目。
|
|
181
124
|
|
|
182
125
|
```js
|
|
183
|
-
dsh_task({ prompt: "…",
|
|
184
|
-
dsh_spawn({ task_name: "
|
|
185
|
-
|
|
126
|
+
dsh_task({ prompt: "…", cwd: "/repo/clawer", workspace: true }) // 用目录名建项目
|
|
127
|
+
dsh_spawn({ task_name: "w1", message: "…", cwd: "/repo/clawer", workspace: "Clawer" })
|
|
128
|
+
dsh_task({ prompt: "…", cwd: "/repo/clawer" }) // 只复用，不创建
|
|
186
129
|
```
|
|
187
130
|
|
|
188
|
-
-
|
|
189
|
-
-
|
|
190
|
-
-
|
|
191
|
-
-
|
|
192
|
-
|
|
193
|
-
实现上就是在建好会话、发第一个 prompt **之前**调一次 `selectModel`，所以 worker 的第一轮就已经在新模型上跑。
|
|
194
|
-
|
|
195
|
-
## 工具
|
|
196
|
-
|
|
197
|
-
| 工具 | 作用 |
|
|
198
|
-
| --- | --- |
|
|
199
|
-
| `dsh_task` | **同步**派活：开会话、投递、阻塞到这一轮结束，只返回**最终回答**（最后一条 assistant 消息） |
|
|
200
|
-
| `dsh_spawn` | **异步**派活：立刻返回 `task_name` + `sessionId`，可同时开多个 worker 并行跑 |
|
|
201
|
-
| `dsh_followup` | 给已有 worker 再派一轮（复用它的上下文） |
|
|
202
|
-
| `dsh_close` | 关闭 worker，释放并发名额（不删除会话） |
|
|
203
|
-
| `dsh_list_workers` | 列出本桥开的 worker 及其实时状态 |
|
|
204
|
-
| `dsh_wait` | 一次等多批 worker：`targets` + `timeoutMs`，任一到达终态即返回 `{completed}` / `{errored}` / `"running"` / `"not_found"` |
|
|
205
|
-
| `dsh_dispatch` | 向指定会话投递一条用户消息并开始一轮；返回 `requestId` 与 `seqAtDispatch` |
|
|
206
|
-
| `dsh_read_result` | **长轮询**读进度：返回该会话在 `seqAtDispatch` 之后的**全部**助手文本（用于看过程；要结果用 `dsh_wait`） |
|
|
207
|
-
| `dsh_list_sessions` | 列出会话**元数据**（id、标题、工作目录、是否运行、最后活动时间） |
|
|
131
|
+
- 目录不存在时先递归创建，再做项目登记（登记要求目录已存在）；
|
|
132
|
+
- 目录已经是项目 → **复用，不改标题**；
|
|
133
|
+
- 返回里带 `workspace: { id, title, path }`；
|
|
134
|
+
- 项目操作失败不影响派发本身。
|
|
208
135
|
|
|
209
|
-
|
|
136
|
+
### 排队还是插话（`mode`）
|
|
210
137
|
|
|
211
|
-
|
|
138
|
+
DSH 的「繁忙时的发送行为」只有两种，桥原样交给调用方：
|
|
212
139
|
|
|
213
|
-
|
|
|
140
|
+
| `mode` | DSH 里的名字 | 行为 |
|
|
214
141
|
| --- | --- | --- |
|
|
215
|
-
| `
|
|
142
|
+
| `queue`（默认） | 排队发送 | 等当前回合跑完，作为新回合处理 |
|
|
143
|
+
| `steer` | 插话发送 | 并入当前回合，模型下一步就能看到 |
|
|
216
144
|
|
|
217
|
-
|
|
145
|
+
```js
|
|
146
|
+
dsh_followup({ worker: "w1", message: "接下来只改 src 下的文件", mode: "steer" })
|
|
147
|
+
```
|
|
218
148
|
|
|
219
|
-
|
|
149
|
+
两个实测结论：
|
|
220
150
|
|
|
221
|
-
|
|
151
|
+
1. **`steer` 不打断正在执行的工具**——worker 若正卡在 `sleep 90` 这类调用里，消息要等它返回才被看到（实测 70 秒）。真想立刻停下是界面上的「取消」，不是投递模式。
|
|
152
|
+
2. **`steer` 不新开回合**（turn 编号不变），所以桥等的是「当前回合结束」；等「下一回合」会一直等到超时。
|
|
222
153
|
|
|
223
|
-
|
|
224
|
-
- `dsh_read_result` 只对**本桥派发过**的会话生效；从未派发过的会话一律拒绝。
|
|
154
|
+
`dsh_task` 对正在运行的会话默认拒绝，错误信息会提示改用 `steer`。插话的回复和原任务在同一回合里，桥会定位到**自己那条 user/message** 之后再取回答，避免混进原任务后续步骤的输出。
|
|
225
155
|
|
|
226
|
-
|
|
156
|
+
### 无人值守（`assumeDefaults`）
|
|
227
157
|
|
|
228
|
-
|
|
158
|
+
worker 卡在 `ask_user_question` 上时需要有人在界面上点一下，但调用方是另一个 agent 时那个人往往不在。因此桥在派发时**自动追加一条常驻指令**：
|
|
229
159
|
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
|
|
160
|
+
```
|
|
161
|
+
（如果缺少必要信息或需要在多个方案里选择，直接采用最合理的默认做法继续做完，
|
|
162
|
+
不要把选择权抛回给用户、不要调用 ask_user_question 等回答；
|
|
163
|
+
在结果里用一行说明你假设了什么。）
|
|
233
164
|
```
|
|
234
165
|
|
|
235
|
-
|
|
166
|
+
- 默认开启，`assumeDefaults: false` 可关；
|
|
167
|
+
- `dsh_task`、`dsh_spawn`、`dsh_followup` 三条路径都会加；
|
|
168
|
+
- prompt 里本来就提到 `ask_user_question` 时不追加。
|
|
236
169
|
|
|
237
|
-
|
|
170
|
+
效果：worker 不会停下来等人，而是选一个合理默认做法做完并交代假设，调用方据此复核。
|
|
238
171
|
|
|
239
|
-
|
|
172
|
+
### 问题上报（`pendingQuestion`）
|
|
173
|
+
|
|
174
|
+
worker 真的问了问题时，`dsh_wait` 会把问题原样带出来：
|
|
175
|
+
|
|
176
|
+
```jsonc
|
|
240
177
|
{
|
|
241
|
-
"
|
|
242
|
-
"
|
|
243
|
-
"
|
|
244
|
-
|
|
245
|
-
|
|
178
|
+
"status": { "w1": "running" },
|
|
179
|
+
"timedOut": true,
|
|
180
|
+
"pendingQuestion": {
|
|
181
|
+
"callId": "call_abc",
|
|
182
|
+
"questions": [{
|
|
183
|
+
"id": "mode",
|
|
184
|
+
"question": "用哪种模式？",
|
|
185
|
+
"header": "Choose Mode",
|
|
186
|
+
"options": [{ "label": "快速", "description": "只跑单测" }, { "label": "完整" }]
|
|
187
|
+
}]
|
|
188
|
+
},
|
|
189
|
+
"next": "blocked on a question: answer it with dsh_answer, or call dsh_wait again"
|
|
246
190
|
}
|
|
247
191
|
```
|
|
248
192
|
|
|
249
|
-
|
|
193
|
+
`dsh_answer({ worker, answers: [{ id, selected: [...] }] })` 用来代答。**已知限制**：DSH 的 `userQuestions.answer()` 只接受已经超时、进入 `continued` 状态的问题；还阻塞在工具调用里的问题是 Web UI 的 answerer 接管的，桥答不了（实测返回 `answered: false`）。所以实际使用中更该依赖上面的 `assumeDefaults`，而不是等 worker 提问。
|
|
250
194
|
|
|
251
|
-
|
|
195
|
+
---
|
|
252
196
|
|
|
253
|
-
|
|
254
|
-
codex mcp add dsh-bridge --url "$(node -p "require(process.env.HOME+'/.dsh/bridge/endpoint.json').url")"
|
|
255
|
-
```
|
|
197
|
+
## 反向：DSH → Codex / Claude Code
|
|
256
198
|
|
|
257
|
-
|
|
199
|
+
两个工具都会给本部署的 Agent 注册，参数形状一致，差别只在底层 CLI。
|
|
258
200
|
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
201
|
+
### `codex_dispatch`
|
|
202
|
+
|
|
203
|
+
| 参数 | 说明 |
|
|
204
|
+
| --- | --- |
|
|
205
|
+
| `prompt` | 必填，任务正文 |
|
|
206
|
+
| `cwd` | 工作目录，默认当前会话目录 |
|
|
207
|
+
| `resume` | Codex 线程 id，续接同一线程 |
|
|
208
|
+
| `sandbox` | `read-only` / `workspace-write` / `danger-full-access` |
|
|
263
209
|
|
|
264
|
-
|
|
210
|
+
返回 `{ ok, text, threadId, exitCode, durationMs }`。执行 `codex exec [resume <id>] --json -o <临时文件>`，从事件流取 `thread.started`、从 `-o` 取最终消息。**`resume` 时 `sandbox` 与 `cwd` 不生效**——`codex exec resume` 不接受 `-s` / `-C`。
|
|
265
211
|
|
|
266
|
-
|
|
212
|
+
### `claude_dispatch`
|
|
267
213
|
|
|
268
|
-
|
|
214
|
+
| 参数 | 说明 |
|
|
215
|
+
| --- | --- |
|
|
216
|
+
| `prompt` | 必填，任务正文 |
|
|
217
|
+
| `cwd` | 工作目录 |
|
|
218
|
+
| `resume` | Claude Code 的 session id |
|
|
219
|
+
| `model` | 模型别名或 id；不传则用配置，再退回 CLI 自己的设置 |
|
|
269
220
|
|
|
270
|
-
|
|
271
|
-
codex mcp remove dsh-bridge
|
|
272
|
-
```
|
|
221
|
+
返回 `{ ok, text, sessionId, durationMs }`。执行 `claude -p --output-format json`，只读 stdout 的单个 JSON 对象；**stderr 的警告不算失败**（模型名带 `[1M]` 后缀时 CLI 会警告，但结果正常）。
|
|
273
222
|
|
|
274
223
|
---
|
|
275
224
|
|
|
@@ -286,81 +235,76 @@ codex mcp remove dsh-bridge
|
|
|
286
235
|
| 键 | 默认 | 说明 |
|
|
287
236
|
| --- | --- | --- |
|
|
288
237
|
| `enabled` | `true` | 总开关；关闭后不监听、不写端点文件 |
|
|
289
|
-
| `port` | `47821` |
|
|
290
|
-
| `endpointFile` | `~/.dsh/bridge/endpoint.json` |
|
|
291
|
-
| `maxResultChars` | `20000` |
|
|
292
|
-
| `taskTimeoutSeconds` | `300` | `dsh_task`
|
|
293
|
-
| `
|
|
294
|
-
| `
|
|
295
|
-
| `
|
|
238
|
+
| `port` | `47821` | 回环端口；固定端口让客户端那条 URL 重启后依然有效 |
|
|
239
|
+
| `endpointFile` | `~/.dsh/bridge/endpoint.json` | 端点与令牌落盘位置 |
|
|
240
|
+
| `maxResultChars` | `20000` | 单次结果返回的最大字符数（超出保留尾部） |
|
|
241
|
+
| `taskTimeoutSeconds` | `300` | `dsh_task` 等待上限（客户端可覆盖，最大 240） |
|
|
242
|
+
| `assumeDefaults` | `true` | 派发时追加「自行决策」的常驻指令 |
|
|
243
|
+
| `workersFile` | `~/.dsh/bridge/workers.json` | worker 注册表（0600） |
|
|
244
|
+
| `maxHops` | `1` | 跨工具委派层数上限 |
|
|
245
|
+
| `dispatchPerMinute` | `10` | 滚动窗口内的派发次数 |
|
|
296
246
|
| `dispatchWindowMs` | `60000` | 上述窗口长度 |
|
|
297
|
-
| `maxWorkersPerRoot` | `4` | **每个工作目录**的 worker
|
|
298
|
-
| `maxWorkers` | `12` |
|
|
299
|
-
| `workerTtlMs` | `86400000` |
|
|
300
|
-
| `waitTimeoutMs` | `240000` | `dsh_wait`
|
|
301
|
-
| `readWaitSeconds` | `25` | `dsh_read_result`
|
|
302
|
-
| `codexBin` | `codex` | Codex 可执行文件；含 `/`
|
|
303
|
-
| `codexSandbox` | `workspace-write` | `codex_dispatch`
|
|
304
|
-
| `codexTimeoutMs` | `300000` | 单次 `codex_dispatch`
|
|
305
|
-
|
|
306
|
-
|
|
247
|
+
| `maxWorkersPerRoot` | `4` | **每个工作目录**的 worker 上限 |
|
|
248
|
+
| `maxWorkers` | `12` | 全局上限 |
|
|
249
|
+
| `workerTtlMs` | `86400000` | 记录过期后不再占名额 |
|
|
250
|
+
| `waitTimeoutMs` | `240000` | `dsh_wait` 默认超时 |
|
|
251
|
+
| `readWaitSeconds` | `25` | `dsh_read_result` 默认长轮询时长 |
|
|
252
|
+
| `codexBin` | `codex` | Codex 可执行文件；含 `/` 时严格按路径解析 |
|
|
253
|
+
| `codexSandbox` | `workspace-write` | `codex_dispatch` 默认 sandbox |
|
|
254
|
+
| `codexTimeoutMs` | `300000` | 单次 `codex_dispatch` 超时 |
|
|
255
|
+
| `claudeBin` | `claude` | Claude Code 可执行文件 |
|
|
256
|
+
| `claudeModel` | 空 | 默认让 Claude CLI 用自己的设置 |
|
|
257
|
+
| `claudeTimeoutMs` | `300000` | 单次 `claude_dispatch` 超时 |
|
|
258
|
+
|
|
259
|
+
端口被占用时不会静默换端口：端点文件里写入 `error` 字段，宿主日志打印 `subagent-bridge: could not start on port …`。
|
|
307
260
|
|
|
308
261
|
---
|
|
309
262
|
|
|
310
|
-
##
|
|
311
|
-
|
|
312
|
-
两个 agent 都接了同一个桥时，存在真实的环路：DSH worker → `codex_dispatch` → 那次 Codex 运行也能看到 `dsh-bridge` → 又 `dsh_spawn` → …。两边**各自进程内**的深度规则都管不到这条链（Codex 的 `agent_max_depth` 只数自己的 `spawn_agent`，DSH 的 `maxDepth` 只看 `delegationDepth`，而桥建的 worker 是顶层会话，深度恒为 0）。
|
|
263
|
+
## 护栏与限制
|
|
313
264
|
|
|
314
|
-
|
|
265
|
+
### 防环
|
|
315
266
|
|
|
316
|
-
|
|
267
|
+
两个 agent 都接了同一个桥时存在真实环路：DSH worker → `codex_dispatch` → 那次 Codex 也能看到 `dsh-bridge` → 又 `dsh_spawn` → …。双方进程内的深度规则都管不到这条链（桥建的 worker 是顶层会话，深度恒为 0）。
|
|
317
268
|
|
|
318
|
-
|
|
319
|
-
- 调用方是桥建的 worker 时按其深度 1 起算；
|
|
320
|
-
- `codex_dispatch` 运行期间会把链路标记为"在飞"，嵌套回来的调用继承该深度；
|
|
321
|
-
- 超限直接报错，措辞可执行：
|
|
322
|
-
`codex_dispatch would create delegation depth 2, but maxHops is 1. Carry the work out directly instead of delegating again.`
|
|
269
|
+
**① 深度（`maxHops`，默认 1）**：每次派发都计算 `max(在飞链路深度, 调用方深度) + 1`，超限直接报错：
|
|
323
270
|
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
271
|
+
```
|
|
272
|
+
codex_dispatch would create delegation depth 2, but maxHops is 1.
|
|
273
|
+
Carry the work out directly instead of delegating again.
|
|
274
|
+
```
|
|
327
275
|
|
|
328
|
-
|
|
276
|
+
**② 速率（`dispatchPerMinute`，默认 10）**：拦截广度型失控与紧循环重试：
|
|
329
277
|
|
|
330
278
|
```
|
|
331
279
|
rate limit: 10 dispatches per 60s reached; retry in 23s
|
|
332
280
|
```
|
|
333
281
|
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
worker 名额**按工作目录分桶**，调用方不用传任何 owner：
|
|
282
|
+
### 名额
|
|
337
283
|
|
|
338
|
-
- 每个 `cwd` 默认 **4 个**（`maxWorkersPerRoot`）；
|
|
339
|
-
-
|
|
340
|
-
-
|
|
341
|
-
- 记录 **24 小时**没更新就自动不再占名额（`workerTtlMs`），不需要手动清理；
|
|
284
|
+
- 每个 `cwd` 默认 **4 个**（`maxWorkersPerRoot`），全局 **12 个**（`maxWorkers`）；
|
|
285
|
+
- **完成但没 `dsh_close` 的仍占名额**；
|
|
286
|
+
- 记录 **24 小时**没更新自动释放；
|
|
342
287
|
- 阻塞式 `dsh_task` 不计入名额，只登记。
|
|
343
288
|
|
|
344
|
-
|
|
289
|
+
按 `cwd` 分桶而不是按会话，是因为 MCP 端点共享、请求里没有会话身份；`cwd` 是唯一由调用方稳定提供、且语义上对应「一个项目」的维度。
|
|
345
290
|
|
|
346
|
-
|
|
291
|
+
### 跨重启
|
|
347
292
|
|
|
348
|
-
worker
|
|
293
|
+
worker 注册表和每轮的时间基线落在 `~/.dsh/bridge/workers.json`：
|
|
349
294
|
|
|
350
|
-
-
|
|
351
|
-
-
|
|
352
|
-
-
|
|
353
|
-
-
|
|
354
|
-
-
|
|
355
|
-
- 文件最多保留 200 条，超出时先淘汰最旧的 **已关闭** worker。
|
|
295
|
+
- 重启后 `dsh_list_workers` 仍能看到之前的 worker；
|
|
296
|
+
- 已结束的 worker，`dsh_wait` 直接返回缓存里的最终回答；
|
|
297
|
+
- 重启时还在跑的，会话未打开时状态为 `offline`；
|
|
298
|
+
- `dsh_followup` 会开新一轮并清掉旧回答；
|
|
299
|
+
- 最多保留 200 条，超出先淘汰最旧的已关闭 worker。
|
|
356
300
|
|
|
357
|
-
|
|
301
|
+
### 安全模型
|
|
358
302
|
|
|
359
|
-
- 只监听 `127.0.0.1
|
|
360
|
-
-
|
|
361
|
-
-
|
|
362
|
-
-
|
|
363
|
-
- DSH
|
|
303
|
+
- 只监听 `127.0.0.1`；
|
|
304
|
+
- 请求必须带令牌：路径 `/mcp/<token>` 或 `Authorization: Bearer <token>`，定长时间比较；
|
|
305
|
+
- 令牌首次启动生成并持久化，能力 URL 稳定；
|
|
306
|
+
- 能力等价于「向指定会话投递消息」：能读到端点文件的进程就能派活，文件 0600、目录 0700；
|
|
307
|
+
- DSH 侧的权限策略不受影响，派进去的消息仍按会话自身的 sandbox / 审批策略执行。
|
|
364
308
|
|
|
365
309
|
---
|
|
366
310
|
|
|
@@ -373,22 +317,22 @@ Codex / 任意 MCP 客户端
|
|
|
373
317
|
dsh-plugin-subagent-bridge（宿主进程内）
|
|
374
318
|
· node:http 监听 127.0.0.1:47821
|
|
375
319
|
· initialize / tools/list / tools/call / ping
|
|
376
|
-
· sessionController.prompt({sessionId, requestId, mode, content})
|
|
320
|
+
· sessionController.prompt({ sessionId, requestId, mode, content })
|
|
377
321
|
· sessions.get(id).snapshotEvents() 读回助手文本
|
|
378
322
|
```
|
|
379
323
|
|
|
380
|
-
|
|
324
|
+
协议是 **streamable HTTP 的无状态子集**：每个 POST 返回一段 `application/json`，不做服务端推送，因此取结果用**长轮询**——`dsh_read_result` 在服务端等，客户端一次调用即可拿到答案；客户端断开时服务端立即停止等待。
|
|
381
325
|
|
|
382
326
|
---
|
|
383
327
|
|
|
384
328
|
## 配套 skill
|
|
385
329
|
|
|
386
|
-
`skills/` 下有两份可直接安装的 skill
|
|
330
|
+
`skills/` 下有两份可直接安装的 skill，把「什么时候该派活、怎么派、怎么收尾」写成模型能读的规则：
|
|
387
331
|
|
|
388
332
|
| Skill | 装给谁 | 作用 |
|
|
389
333
|
| --- | --- | --- |
|
|
390
334
|
| `deepseek-worker` | Codex | 让 Codex 把任务当 subagent 派给 DSH（`dsh_task`），一次调用等结果 |
|
|
391
|
-
| `delegate-to-external-agent` | DSH | 让 DSH 的 agent
|
|
335
|
+
| `delegate-to-external-agent` | DSH | 让 DSH 的 agent 在需要独立视角/复核时派给 Codex 或 Claude Code，含两者差别与续接方式 |
|
|
392
336
|
|
|
393
337
|
```bash
|
|
394
338
|
# Codex 侧
|
|
@@ -398,17 +342,15 @@ mkdir -p ~/.codex/skills && cp -R skills/deepseek-worker ~/.codex/skills/
|
|
|
398
342
|
mkdir -p ~/.dsh/skills && cp -R skills/delegate-to-external-agent ~/.dsh/skills/
|
|
399
343
|
```
|
|
400
344
|
|
|
401
|
-
两份都是标准 `SKILL.md`：YAML frontmatter（`name` + `description`）+ 正文。**触发靠 description
|
|
345
|
+
两份都是标准 `SKILL.md`：YAML frontmatter（`name` + `description`）+ 正文。**触发靠 description**——模型平时只看到名字和描述，判断相关了才读正文，所以描述里写满了中英触发语和「不要用」的边界。改完立刻生效，不用重启。
|
|
402
346
|
|
|
403
347
|
---
|
|
404
348
|
|
|
405
349
|
## 兼容性
|
|
406
350
|
|
|
407
|
-
- DSH `^0.2.1-0`（`engines.dsh
|
|
408
|
-
- MCP 协议版本：`2025-06-18`、`2025-03-26`、`2024-11-05
|
|
409
|
-
- 依赖宿主公开服务 `sessionController
|
|
410
|
-
|
|
411
|
-
---
|
|
351
|
+
- DSH `^0.2.1-0`（`engines.dsh`）；
|
|
352
|
+
- MCP 协议版本：`2025-06-18`、`2025-03-26`、`2024-11-05`（按客户端请求回显，未知版本回落到最新）；
|
|
353
|
+
- 依赖宿主公开服务 `sessionController`、`sessions`、`workspaceRegistry`、`userQuestions`；不可用时工具返回明确错误。
|
|
412
354
|
|
|
413
355
|
## 开发
|
|
414
356
|
|
|
@@ -416,8 +358,9 @@ mkdir -p ~/.dsh/skills && cp -R skills/delegate-to-external-agent ~/.dsh/skills/
|
|
|
416
358
|
node --test "test/*.test.mjs"
|
|
417
359
|
```
|
|
418
360
|
|
|
419
|
-
|
|
420
|
-
|
|
361
|
+
83 项，覆盖握手与版本协商、工具清单与参数校验、派发调用形状、结果读取的时间基线、长轮询、真实 HTTP 往返（含 404/405/202 与 bearer 分支）、`codex exec` 事件解析与二进制解析、成功/失败/超时三种运行结果、resume 的参数分叉、只回最终回答、`dsh_wait` 的四种终态、并发上限与释放、followup 重基线、注册表落盘与重启复原、`maxHops` 与速率限制、按 `cwd` 分桶的预算、工作区归属、`workspace` 创建与复用、`queue` / `steer` 的投递与等待、插话回答的定位、`claude` 输出解析与 resume 参数、`assumeDefaults` 指令注入、`pendingQuestion` 与 `dsh_answer`。
|
|
362
|
+
|
|
363
|
+
`test/persistence.test.mjs` 单独覆盖持久化：文件权限、缺失/损坏记录、并发写、冷会话缓存与 `offline`。
|
|
421
364
|
|
|
422
365
|
---
|
|
423
366
|
|
|
@@ -425,12 +368,11 @@ node --test "test/*.test.mjs"
|
|
|
425
368
|
|
|
426
369
|
| 插件 | 说明 |
|
|
427
370
|
| --- | --- |
|
|
371
|
+
| **dsh-plugin-subagent-bridge**（本仓库） | 让 Codex 通过本机 MCP 把 DSH 当 subagent 用，反向也能派给 Codex / Claude Code |
|
|
428
372
|
| [dsh-plugin-composer-predict](https://github.com/Dogtiti/dsh-plugin-composer-predict) | 预测下一条指令并显示为占位文字，`Tab` 采纳 |
|
|
429
373
|
| [dsh-plugin-composer-history](https://github.com/Dogtiti/dsh-plugin-composer-history) | 输入框中按 `↑` / `↓` 回填历史消息 |
|
|
430
|
-
|
|
|
431
|
-
| [dsh-plugin-
|
|
432
|
-
| [dsh-plugin-provider-icons](https://github.com/Dogtiti/dsh-plugin-provider-icons) | 在模型名旁显示供应商品牌 logo（24 个厂商，支持前缀匹配） |
|
|
433
|
-
|
|
374
|
+
| [dsh-plugin-usage-panel](https://github.com/Dogtiti/dsh-plugin-usage-panel) | 在模型选择器旁显示供应商套餐额度余量 |
|
|
375
|
+
| [dsh-plugin-provider-icons](https://github.com/Dogtiti/dsh-plugin-provider-icons) | 在模型名旁显示供应商品牌 logo |
|
|
434
376
|
|
|
435
377
|
## 许可
|
|
436
378
|
|
package/index.js
CHANGED
|
@@ -75,6 +75,7 @@ const DEFAULTS = {
|
|
|
75
75
|
codexBin: 'codex',
|
|
76
76
|
codexSandbox: 'workspace-write',
|
|
77
77
|
codexTimeoutMs: 300000,
|
|
78
|
+
assumeDefaults: true,
|
|
78
79
|
claudeBin: 'claude',
|
|
79
80
|
claudeModel: '',
|
|
80
81
|
claudeTimeoutMs: 300000,
|
|
@@ -309,6 +310,28 @@ const TOOLS = [
|
|
|
309
310
|
},
|
|
310
311
|
]
|
|
311
312
|
|
|
313
|
+
/**
|
|
314
|
+
* Standing instruction appended to a delegated task.
|
|
315
|
+
*
|
|
316
|
+
* A worker that stops to ask a question needs somebody at the UI; when the caller is
|
|
317
|
+
* another agent, nobody is. The caller would rather have a reasonable assumption and a
|
|
318
|
+
* finished result, so the worker is told to make one and report it.
|
|
319
|
+
*/
|
|
320
|
+
const ASSUMPTION_POLICY =
|
|
321
|
+
'如果缺少必要信息或需要在多个方案里选择，直接采用最合理的默认做法继续做完，不要把选择权抛回给用户、不要调用 ask_user_question 等回答；在结果里用一行说明你假设了什么。'
|
|
322
|
+
|
|
323
|
+
/**
|
|
324
|
+
* Attach the standing instruction when the deployment wants it.
|
|
325
|
+
* @param settings - resolved settings.
|
|
326
|
+
* @param message - caller-supplied text.
|
|
327
|
+
* @returns the text to deliver.
|
|
328
|
+
*/
|
|
329
|
+
function withAssumptionPolicy(settings, message) {
|
|
330
|
+
if (settings.assumeDefaults !== true) return message
|
|
331
|
+
if (message.includes('ask_user_question')) return message
|
|
332
|
+
return `${message}\n\n（${ASSUMPTION_POLICY}）`
|
|
333
|
+
}
|
|
334
|
+
|
|
312
335
|
/**
|
|
313
336
|
* Take over the questions a worker asks, so the calling agent can answer them.
|
|
314
337
|
*
|
|
@@ -965,7 +988,7 @@ export function createApi(ctx, state, settings) {
|
|
|
965
988
|
const before = Number(sessions()?.get?.(sessionId)?.seq ?? 0)
|
|
966
989
|
const requestId = randomUUID()
|
|
967
990
|
const accepted = await service.prompt(
|
|
968
|
-
{ sessionId, requestId, mode: mode === 'steer' ? 'steer' : 'queue', content: [{ type: 'text', text: message }] },
|
|
991
|
+
{ sessionId, requestId, mode: mode === 'steer' ? 'steer' : 'queue', content: [{ type: 'text', text: withAssumptionPolicy(settings, message) }] },
|
|
969
992
|
AbortSignal.timeout(30000),
|
|
970
993
|
)
|
|
971
994
|
state.dispatched.add(sessionId)
|
|
@@ -1000,7 +1023,7 @@ export function createApi(ctx, state, settings) {
|
|
|
1000
1023
|
const before = Number(sessions()?.get?.(target.sessionId)?.seq ?? 0)
|
|
1001
1024
|
const requestId = randomUUID()
|
|
1002
1025
|
const accepted = await service.prompt(
|
|
1003
|
-
{ sessionId: target.sessionId, requestId, mode: mode === 'steer' ? 'steer' : 'queue', content: [{ type: 'text', text: message }] },
|
|
1026
|
+
{ sessionId: target.sessionId, requestId, mode: mode === 'steer' ? 'steer' : 'queue', content: [{ type: 'text', text: withAssumptionPolicy(settings, message) }] },
|
|
1004
1027
|
AbortSignal.timeout(30000),
|
|
1005
1028
|
)
|
|
1006
1029
|
state.baseline.set(target.sessionId, before)
|
|
@@ -1079,7 +1102,7 @@ export function createApi(ctx, state, settings) {
|
|
|
1079
1102
|
const finished = waitForTurnEnd(ctx, targetId, waitAfter, seconds * 1000)
|
|
1080
1103
|
const requestId = randomUUID()
|
|
1081
1104
|
const accepted = await service.prompt(
|
|
1082
|
-
{ sessionId: targetId, requestId, mode: deliveryMode, content: [{ type: 'text', text: prompt }] },
|
|
1105
|
+
{ sessionId: targetId, requestId, mode: deliveryMode, content: [{ type: 'text', text: withAssumptionPolicy(settings, prompt) }] },
|
|
1083
1106
|
AbortSignal.timeout(30000),
|
|
1084
1107
|
)
|
|
1085
1108
|
state.dispatched.add(targetId)
|
|
@@ -2309,6 +2332,10 @@ function resolveSettings(config) {
|
|
|
2309
2332
|
}
|
|
2310
2333
|
if (key === 'codexBin' && typeof value === 'string' && value !== '') merged.codexBin = value
|
|
2311
2334
|
if (key === 'codexSandbox' && typeof value === 'string' && value !== '') merged.codexSandbox = value
|
|
2335
|
+
if (key === 'assumeDefaults') {
|
|
2336
|
+
merged.assumeDefaults = value === true || value === 'true'
|
|
2337
|
+
continue
|
|
2338
|
+
}
|
|
2312
2339
|
if (key === 'claudeBin' && typeof value === 'string' && value !== '') merged.claudeBin = value
|
|
2313
2340
|
if (key === 'claudeModel' && typeof value === 'string') merged.claudeModel = value
|
|
2314
2341
|
if (key === 'workersFile' && typeof value === 'string' && value !== '') merged.workersFile = expandHome(value)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-plugin-subagent-bridge",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.15.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Subagent bridge: lets Codex delegate a task to DeepSeek Harness the way it would spawn a subagent (one call, waits for the answer), plus a codex_dispatch tool for the reverse direction.",
|
|
6
6
|
"keywords": [
|