dsh-plugin-subagent-bridge 0.0.0-stage → 0.5.0

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Subagent Bridge",
+    "description": "Loopback MCP endpoint that lets another agent hand work to DeepSeek Harness sessions, with metadata-only session listing and result reads limited to dispatched sessions."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "\u5b50\u667a\u80fd\u4f53\u6865",
+    "description": "\u5728\u672c\u673a\u56de\u73af\u5730\u5740\u63d0\u4f9b MCP \u7aef\u70b9\uff0c\u8ba9\u5176\u4ed6\u667a\u80fd\u4f53\uff08\u5982 Codex\uff09\u628a\u4efb\u52a1\u6d3e\u7ed9 DeepSeek Harness \u4f1a\u8bdd\uff1b\u4f1a\u8bdd\u5217\u8868\u53ea\u8fd4\u56de\u5143\u6570\u636e\uff0c\u7ed3\u679c\u8bfb\u53d6\u4ec5\u9650\u672c\u6865\u6d3e\u53d1\u8fc7\u7684\u4f1a\u8bdd\u3002"
+  }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "dsh-plugin-subagent-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "type": "module",
+  "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.",
+  "keywords": [
+    "dsh-plugin",
+    "deepseek",
+    "harness",
+    "mcp",
+    "bridge",
+    "codex"
+  ],
+  "author": "Dogtiti",
+  "license": "MIT",
+  "homepage": "https://github.com/Dogtiti/dsh-plugin-subagent-bridge#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Dogtiti/dsh-plugin-subagent-bridge"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "skills/*/SKILL.md"
+  ],
+  "engines": {
+    "dsh": "^0.2.1-0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/skills/deepseek-worker/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: deepseek-worker
+description: 交给 DSH / 开个 worker 时使用；把自足任务当 subagent 派给 DeepSeek Harness：dsh_task 一次调用开会话、等这一轮干完、拿回结论。不用于几行改动或 DSH 未启动。
+---
+
+# 把任务交给 DSH（subagent 用法）
+
+DSH 是通过 `dsh-bridge` MCP 接上来的另一个编码代理。用法和"给自己开一个 subagent"一样：**一次调用，给它一个自足的任务，等它把这一轮干完并返回结论。**
+
+## 先确认工具在
+
+工具列表里应当有 `dsh_task`、`dsh_dispatch`、`dsh_read_result`、`dsh_list_sessions`。
+
+- 没有 `dsh_task` → DSH 没启动或 MCP 未接入。直接告诉用户"需要先启动 DeepSeek Harness"，**不要假装调用成功**。
+- 调用报连接错误 → 报错误原文，然后自己把这件事做掉，不要反复重试。
+
+## 默认动作：`dsh_task`
+
+```jsonc
+dsh_task({
+  "prompt": "自足的任务描述 + 验收标准",
+  "cwd": "/Users/.../当前仓库"          // 当前项目根目录
+})
+```
+
+返回：
+
+```jsonc
+{
+  "sessionId": "session-…",   // 续做时用它
+  "created": true,
+  "status": "completed",       // completed | turn-<reason> | timeout
+  "text": "worker 的最终回答",
+  "turns": 3,
+  "durationMs": 42000
+}
+```
+
+`dsh_task` **阻塞到 DSH 那一轮结束**再返回，不需要轮询。默认最多等 300 秒，更重的任务传 `timeoutSeconds`（上限 600）。
+
+## 怎么写 prompt
+
+worker **看不到你这段对话**，它只有 `prompt` 和 `cwd`。写成可以独立开工的工单：
+
+1. **背景一句话**：什么项目、要解决什么。
+2. **具体改动**：文件/模块/行为，能给路径就给。
+3. **验收标准**：跑什么命令、期望什么结果（例如 `pnpm vitest` 全绿）。
+4. **边界**：不要动哪些文件、不要改哪些接口、不要提交或推送。
+5. **输出要求**：结尾几行说明"改了什么、怎么验证、还有什么风险"。
+
+不要写"按上面的讨论去做"——worker 没有你的上下文。
+
+## prompt 的红线
+
+worker 收到的是**一条普通用户消息**，它看不到你这边有没有技能、叫什么名字。所以：
+
+- ❌ 不要把技能名、工具名写进 prompt：`用户明确要求使用 deepseek-worker 写…`、`请用 dsh_task 执行…`、`你是 deepseek-worker 子代理…`
+- ❌ 不要给它派角色或交代你们的协作机制：`你现在是一个 subagent，完成后回调…`
+- ❌ 不要复述用户的元指令：`用户说了要 DeepSeek 来做，所以…`
+- ✅ 只写**任务本身**：目标、位置、验收标准、边界。
+
+用户如果说「用 deepseek-worker 写个冒泡」，你派出去的那句话应该只是：
+
+```
+用 Python 实现 bubble_sort(nums)：原地升序、相邻比较交换、无交换提前结束；
+附调用示例；覆盖空列表/单元素/重复值/负数/已排序/逆序；不读写文件、不执行命令。
+```
+
+一旦 prompt 里出现 `deepseek-worker`，worker 会以为那是它自己的技能或工具，白费一轮去确认「本会话没有这个技能」。
+
+## 拿到结果之后
+
+- `completed` → 读 `text`，判断是否真的达成交付；需要复核就自己跑一遍验证命令。
+- `turn-…`（如 `turn-aborted`、`turn-error`）→ 那一轮没正常结束，把 `text` 里的信息转述给用户，必要时自己接手。
+- `timeout` → 工作**没有丢**，DSH 那边还在跑。用同一个 `sessionId` 再调一次问进度，或先用低阶工具看一眼。
+
+## 同一个 worker 继续干
+
+```jsonc
+dsh_task({ "sessionId": "session-…", "prompt": "再把失败的那个用例补上" })
+```
+
+适合"先改、看了再补"的往返。目标会话正在跑时会被拒绝（提示改用 `dsh_dispatch`），这是有意的。
+
+## 低阶工具（一般不用）
+
+只有"给一个已在用的 DSH 会话留言"才用：`dsh_dispatch` 投递、`dsh_read_result` 长轮询取回。日常派活一律 `dsh_task`。
+
+## 回报给用户
+
+三句话以内：派给了谁（新 worker / 某 session）、结果如何（`status` + 核心结论）、下一步建议。**不要把 worker 的长文整段贴回来**。
+
+## 不要做
+
+- 不要把密钥、私有凭据写进 `prompt`——它会进入 DSH 的会话日志。
+- 不要让 worker 操作你的本地环境（它有自己的权限与目录）。
+- 不要把三件不相关的事塞进一次调用；拆开更可控。
+- 不要在 DSH 未启动时假装委派成功。

package/skills/delegate-to-codex/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: delegate-to-codex
+description: 让 Codex 审一下 / review / 用另一个模型验证 / 要第二意见 / 交叉验证 / 交给 Codex 实现 时使用。用 codex_dispatch 把任务派给 Codex，一次调用阻塞到它退出拿到回答，可用 resume 续同一线程。不用于几行改动，也不用于 Codex 未安装或未登录时。
+---
+
+# 把任务交给 Codex
+
+Codex 是同一台机器上的另一个编码代理。`codex_dispatch` 会跑一次 `codex exec`，**阻塞到它退出**，返回它的最终回答和线程 id。
+
+## 先确认可用
+
+- 工具列表里有 `codex_dispatch` 才能用。没有 → 说明这个部署没装 `dsh-plugin-subagent-bridge`，或者 Codex 二进制没找到。
+- 调用返回 `codex executable not found` → Codex CLI 不在 PATH，也没有落在常见目录。告诉用户在插件 `config.codexBin` 里指一个绝对路径，不要反复重试。
+- 用户机器上 Codex 未登录 / 额度用尽时，返回会是 `codex exited with …`，把后面那几行原样转述，别自己编原因。
+
+## 基本调用
+
+```jsonc
+codex_dispatch({
+  "prompt": "自足的审查/实现任务 + 验收标准",
+  "cwd": "/Users/.../当前仓库",
+  "sandbox": "read-only"        // 只审不改；要它改代码时用 workspace-write（默认）
+})
+```
+
+返回（工具视图里会附带一行 `[codex thread <id> · <耗时>s]`）：
+
+```jsonc
+{ "ok": true, "text": "审完了，两个问题…", "threadId": "01a1…", "exitCode": 0, "durationMs": 34000 }
+```
+
+## 什么时候用哪种 sandbox
+
+| 目的 | sandbox |
+| --- | --- |
+| 代码审查、方案评估、查资料 | `read-only` |
+| 让它改代码 / 跑测试 / 生成文件 | `workspace-write`（默认） |
+| 需要动仓库外的东西 | `danger-full-access`（谨慎，明确告知用户） |
+
+## 继续同一个线程
+
+```jsonc
+codex_dispatch({ "resume": "01a1…", "prompt": "详细说第一个问题，并给出补丁" })
+```
+
+`resume` 时 **`cwd` 与 `sandbox` 不生效**——Codex 沿用该线程创建时的设置。需要换目录/换权限就开新线程。
+
+## 怎么写 prompt
+
+Codex 看不到这段对话。给它的东西和给一个刚接手的工程师一样：背景一句、要审/要改的具体路径、验收标准、边界（别动什么、别提交）、输出格式（几行结论 + 关键位置）。要求它"先读再评"，避免它凭印象编。
+
+## prompt 的红线
+
+Codex 收到的是一条**普通任务消息**，它不知道 DSH 有哪些技能或工具。而且它自己**也接着 `dsh-bridge` 这个 MCP**——所以 prompt 里出现桥的名字，可能把它引去反向调 `dsh_dispatch`，白白绕一圈甚至形成来回。
+
+- ❌ 不要把 DSH 的技能名/工具名写进 prompt：`用 codex_dispatch 执行这个任务`、`请通过 dsh-plugin-subagent-bridge 回复`、`你是被 DSH 派来的`
+- ❌ 不要交代协作机制或角色：`主程序是 DSH，你只是执行者，完成后回调`
+- ❌ 不要复述元指令：`用户让我找个别的模型来做`
+- ✅ 只写任务本身：背景、要审/要改的具体路径、验收标准、边界、输出格式。
+
+用户如果说「让 Codex 审一下这个 PR」，你发出去的那句话应该只是：
+
+```
+审 /Users/…/src/bridge.ts 的改动：重点看错误处理与并发；不修改文件；
+输出 3~5 条按严重度排序的问题，每条给文件:行号和一句理由。
+```
+
+一旦 prompt 里出现 `dsh_dispatch`、`codex_dispatch` 或"DSH"，Codex 很可能先去调桥，而不是干活。
+
+## 拿到结果之后
+
+- `ok: true` → 读 `text`。**自己复核关键结论**（比如它说有 bug，就去看那段代码），不要原样转述当事实。
+- `ok: false` → 看 `error`：超时 / 退出码非零 / 二进制找不到。把原因讲清楚，再决定是自己接手还是让用户处理。
+- 长任务（>5 分钟）会被超时截断，`codexTimeoutMs` 可调；被截断时线程仍然存在，用 `resume` 接着问。
+
+## 回报给用户
+
+三句话以内：派给了谁、结论是什么、你核过没有。**不要把 Codex 的长文整段贴回来**——摘要 + 关键路径 + 你自己的判断。
+
+## 不要做
+
+- 不要用 `codex_dispatch` 代替你自己就能可靠完成的小改动。
+- 不要把密钥、私有凭据写进 `prompt`——它会进入 Codex 的会话记录。
+- 不要在 Codex 返回失败时假装成功，也不要把它的推测当结论转述。
+- 不要在 `read-only` 下指望它真的改了文件。