组合插件转正施工记录

August 21, 2026 · View on GitHub

从需求到发布轨的完整施工记录（2026-08-21）。

需求来源

桌面计划文件《DSH-Windows-bash插件开发计划.txt》：Windows 上 DSH 默认 pwsh，LLM 训练语料 bash 占比高，agent 执行 POSIX 命令错误率高。目标：默认 bash、无 bash 回落 pwsh、配置可切换。

调研结论

  • disabled 默认值来源：@deepseek-ai/dsh-base bundle 的 cordis.patch.yml（!!js process.platform === 'win32'），bundles 层而非 preset 层
  • 官方 tool-bash 依赖 ctx.shell（bash-local/bash-sandbox 提供），Windows 上 bash-sandbox 也 disabled——光启用 tool-bash 不够，需自带执行器
  • 官方 bash-local 直接 spawn bash（依赖 PATH），无 pwsh 那样的路径探测（resolve.ts）——本机 git-bash 不在 PATH，需显式路径
  • 插件配置面板机制：settings.plugin.item slot + settings namespace；但 apiproxy 有 allowlist，插件自行注册的 namespace 不被 serve（官方 deferred work）

设计决策

  1. 组合插件自带 bash 工具（不依赖官方 tool-bash）：subprocess 通道执行 git-bash，动态注册/注销
  2. 提示词裁剪替代工具注销：官方 pwsh 工具在 preset 层无法运行时注销，用 system-prompt/assemble 过滤隐藏
  3. 卡片读写走插件自己的 host API：绕开 apiproxy settings allowlist，host 端仍经 settings 服务持久化
  4. 折叠卡片 + 终端卡片：与官方 PluginCard / TerminalBlock 同构，体验一致

迭代记录

  1. v0.0.1 首版：bash 探测 + 配置面板卡片（初版非折叠）+ 动态工具注册 + 提示词裁剪 + status API。注入验证：bash 工具注册、git-bash 执行、配置切换链路全部通过
  2. 卡片折叠化：用户要求与官方卡片一致——重写为折叠式（头部 button + chevron + 展开 body + staged 保存）
  3. 终端卡片：用户发现 bash 工具行不能像 pwsh 点击查看命令——补 presentCall/presentResult（card:'terminal'），exit 标记对齐官方格式（末尾、exit 0 不报）
  4. 发布轨：README 徽章 + About 卡片 + LICENSE + GitHub 仓库 + Release v0.0.1
  5. 发布补齐：cordis.patch.yml（bundle patch 正式装配）+ package.json 元数据 + README.en + CHANGELOG + docs + 截图 + lib 提交 + Release ZIP

实测验证

  • 注入即生效（host+UI），status API：bashFound=true, effective=bash（C:\Program Files\Git\bin\bash.exe）
  • 配置面板：选 pwsh 保存 → effective 立即变 pwsh（bash 工具注销）；选 auto → 恢复 bash
  • git-bash 执行：echo / 管道 / ls 正常（exit 0）
  • 工具面：agent 视图 tools 里 pwsh 被过滤，只剩 bash（git-bash 描述）
  • 终端卡片：对话页点击展开显示命令/cwd/输出/exit 状态
  • 卸载即净：dev_uninject_plugin 一键还原

规划

  • P1 run_in_background 支持：bash 工具后台执行（jobs 通道），与官方 tool-bash 对齐
  • P2 bashPath 面板配置：卡片内显示/编辑显式 bash 路径（当前仅 settings.yaml 手动配置）
  • P3 非 Windows 平台适配：Linux/macOS 上自动跳过（当前仅 Windows 语义）