@stars-w/dsh-shell-callback

Warning

本仓库已停止维护（Deprecated / Stopped Maintenance）

DSH 0.1.2-rc.1 已原生提供 bash run_in_background + tool-jobs：后台执行、完成通知、job_output / job_kill / 有界等待均已内置。本插件的独特价值（完成通知直接携带完整输出、后台超时杀进程）已不足以支撑继续适配新版本，因此不再继续开发、不再适配新版本、不再发布新功能。

已安装用户建议改用原生 bash run_in_background + job_output / job_kill；本仓库仅保留历史实现与说明归档，新安装不推荐。

命令执行回调桥：bash_cb 工具以回调方式返回命令结果，DSH 会话不再阻塞等待命令执行。

要解决的问题

内置 bash 工具的前台路径会 await ctx.shell.run(...) 阻塞整个回合直到命令退出（或超时被杀）；后台路径虽然立即返回 job id，但完成通知不带输出，模型还要再 job_output 轮询/按设定时间 wait。本插件把命令执行对接上 bash/shell 后台执行已有的结算回调机制（ctx.jobs.onJobDone），会话不再"按设定时间傻等"。

安装

包已发布到 npm（public），推荐直接通过 dsh 插件命令安装：

dsh plugin --profile web add @stars-w/dsh-shell-callback

安装后会自动追加到 profile 的 dsh.profile.bundles，作为标准 bundle 加载。

本地开发 / 构建

git clone https://gitcode.com/wy_stars/dsh-shell-callback.git
cd dsh-shell-callback
bash scripts/build.sh   # junction 运行期依赖 + 语法门禁

本地注入器工具：dev_build_plugin → dev_inject_plugin → dev_reload_package dsh-shell-callback → dev_uninject_plugin dsh-shell-callback。

工作原理

模型调用 bash_cb：命令经 ctx.shell.start 注册为无主 background job，工具立即返回 job id，回合不阻塞。
命令结束时 jobs-local 结算 → onJobDone 回调把完整输出（stdout/stderr/退出码/超时标记）构造成会话消息：会话空闲则 agent.followup 直接唤醒，忙碌则 agent.inject 排队进下一步。
job_output / job_kill / job_list 对返回的 job id 全部可用（无主 job 对 owner 会话开放访问）；可选 timeout_ms 到点杀进程树，回调仍投递已收集的部分输出。

为什么是无主 job（关键设计）

agent 预设内的 tool-jobs 完成通知监听器对无主 job 直接 return（owner === void 0），因此本插件（注册在宿主组合 global 层）的回调是唯一通知者，不会出现双通知。global 层 attachController 使无主 job 的 start 通过 servesOwner 前置检查。

工具面

参数	说明
`command`	要执行的 bash 命令
`description`	5–10 词的主动语态描述（显示在 UI）
`workdir`	可选；默认会话工作区，相对路径按会话 cwd 解析
`timeout_ms`	可选；最长运行时间（毫秒），超时杀进程树并回调部分输出

构建

纯 ESM JS，无 TypeScript 编译步骤；构建门禁只做运行期依赖 junction + 语法校验：

bash scripts/build.sh          # junction @deepseek-ai/dsh-tools、dsh-llm + node --check

运行期依赖解析：lib/index.js 的 @deepseek-ai/* 导入经本目录 node_modules 的 junction 指向 DSH 部署目录的已编译包（默认 /usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules，可用 DSH_DEPLOY_MODULES 覆盖）；其嵌套依赖由部署目录自身解析。

已验证行为

bash_cb 立即返回 job id，回合不阻塞；回调消息携带完整输出送达会话
timeout_ms 准点杀进程树，回调投递部分输出 + 超时标记
job_kill 取消后结算为 killed，无重复回调
热重载/卸载时所有注册经 ctx.effect 自动清理（工具无重名冲突）

已知取舍

无唤醒预算（tool-jobs 有 3 次上限）：每次回调都携带完整结果、job 只结算一次，通知风暴自限；若模型连续起 N 个 job 后空闲，会收到 N 次各携结果的唤醒，这是预期行为。
若模型在 job 运行中多次 job_output，结算回调只携带增量（与 job_output 的单游标语义一致）。
卸载插件时运行中的 job 不受影响（jobs 注册表与 shell 执行器独立存活），但结算回调消失——残留 job 仍可 job_output/job_kill，或随会话/服务回收。