感叹号 Shell Mooling0602/dsh-hint-shell

dsh-hint-shell

一个 DeepSeek Harness 插件，让 ! 在输入框里成为 shell 前缀。

- 输入框为空 —— 在自带占位符后面追加 ，输入 ! 执行 shell 命令，整句变成 发消息或创建任务, / 调用指令, @ 文件或对话，输入 ! 执行 shell 命令。
- 输入 ! 之后 —— 在 ! 后面紧跟一行灰色提示 输入 shell 命令…。
- 提交时 —— 像 !ls 这样的一行会在会话的工作目录里作为真正的 shell 命令执行。输出会以工具调用和结果的形式记入会话，所以下一次真正的请求已经能看到它。! 这一行本身不会发起任何模型请求。

其他一切不变：不加新按钮，不替换组件，不改键盘行为。

! 遵循与 / 相同的约定

Harness 只有在触发符号后面跟着内容时，才把它当作触发器：parseCommand 要求 / 后面至少有一个名称字符，输入框的 matchEnter 在 token 为空时直接放弃。所以单独一个 / 是普通文本，不是命令。

! 的行为相同。单独一个 ! 是普通文字，和其他消息一样发给模型；只有 ! 后面跟着命令，才算 shell 意图。!ls 和 ! ls 都表示 ls。

工作原理

输入框的 effect 复用了自带输入框已有的机制。

空闲提示 —— 空输入框的占位符来自对 conversation/placeholder.default 的 locale 查询。LocaleRuntime.prototype.translate 是原型方法，所以插件把它包一层，只给这个 key 追加一句（以及 placeholder.hero，即同一个输入框在空会话布局下的 key）。其他所有命名空间和 key 原样透传。

待命提示 —— 自带样式表已经能画出这类消息：

.input p:last-child::after {
content: var(--dsh-composer-hint);
color: var(--dsw-alias-label-caption);
}

上游只会在原生命令声明时填充这个属性，而 ! 前缀产生不了这种声明。自定义属性会继承，所以在输入框卡片上设置 --dsh-composer-hint 就够了：自带规则随后会在输入的 ! 后面立刻画出文字，用的是自带说明文字颜色。插件不添加 DOM，不做测量，也不做定位。

草稿本身来自 [data-composer-input]，即输入框已经暴露的可编辑区域，所以这个插件没有配套插件，也不依赖内部触发器实现。

文案

文案放在插件自己的 dsh-hint-shell locale 命名空间里，注册永远不会冲突。locale 服务的 register 是只追加的，遇到重复的 (namespace, locale) 组合会抛错，所以插件无法覆盖 conversation 命名空间。

| | zh | en |
| 空闲子句 | ，输入 ! 执行 shell 命令 | , type ! for shell commands |
| 待命提示 | 输入 shell 命令… | Enter a shell command… |

改 src/copy.ts 即可修改。

执行

宿主侧挂接 agent/pre-step，这是循环派发请求前的最后一个点，它的 reject 决策会中止该请求。因此一行 ! 不消耗任何 token。

记录结果需要一整轮工具交换，而不是单个事件。模型可见的界面带有 tool/result，却没有 tool/call；而一条工具结果前面没有 assistant 的 tool-call 块，就成了一条消息在回应从未发出的调用——服务商会拒绝这种消息。记录按智能体循环写自身记录的方式写入，并采用会话重新打开时 format v4 读取器校验的形状：

1. step/start —— agent/pre-step 在循环开启自己的 step 之前 运行，而 v4 要求每条界面消息都属于一个已开启的 step。插件为这对消息开启一个 step。
2. 内容为空的 system/message —— 仅在界面仍为空时写入。V4 把第一条 system 消息保护为界面头部，没有它就无法追加后续的 system/message。一行 ! 可能是会话做的第一件事，所以要预留这个头部；空内容不会派生任何模型消息，也不渲染任何记录行。
3. assistant/message，携带 tool-call 块（界面事件，带标识的消息）
4. tool/call（仅日志，供 UI 和重放使用）
5. tool/result（界面事件：一条带标识的 tool 角色消息，其 source.callId 与 toolCallId 匹配，并把 tool/call 的 seq 作为来源事件引用）
6. step/end —— 关闭这个合成 step，让循环的 turn/end 保持合法

每条消息都带一个新的 UUID id 和一个由生产者拥有的 source.kind，这正是 v4 读取器在重新打开时检查的内容。省略其中任何一项都不是表面问题：实时追加会成功，随后持久化编码器拒绝该行，缓冲的批次永远到不了日志，本轮以格式错误失败，例如 format v4 tool/result at seq 8 requires a first-class message with a string id。

由于这些是对持久日志的追加，且该 step 已被拒绝，命令的输出会留在历史里，供下一个请求使用，而无需为它专门发起请求。

命令通过 /bin/sh -c 运行，所以引号、管道和通配符的行为与终端一致，而不是重新实现一套。输出上限为 30 000 个字符，非零退出或信号会作为工具错误上报。

subprocess 是可选读取，而不是在 inject 中声明：硬依赖会导致没有服务商组合时 Cordis 拒绝挂载整个插件，连带把 composer 提示也拖下水。没有服务商时提示仍可用，一行 ! 会记录一条工具错误，指明缺失的服务。

开发

源码是 TypeScript；两个发布的 JavaScript 文件都是生成的。

npm install # typescript + esbuild + @types/node
npm run typecheck # tsc --noEmit
npm run build # src/ -> client.js, host.ts -> index.js
npm test # composer, shell-line, and installed-Harness format tests

test/dsh-format.test.ts 针对已安装的 Harness 驱动宿主钩子：它通过一个真实的 Session，然后通过真实的 format v4 reader 编码、接纳并恢复日志。这样一来，线上应用能接受、却无法重新打开的记录形态，会让测试套件失败。它从宿主安装位置（DSH_MODULES，或全局 npm root -g）解析 harness 包；一个都没装时报告跳过。

client.js 必须保持为单个自包含文件：Client 模块加载器的 require 只解析宿主包，无法解析相对导入，所以构建时打包 src/，而不是直接发布它。index.js 是构建产物，不直接发布 .ts，这样宿主就不必依赖运行时开启 TypeScript stripping。

目录结构

| 路径 | 用途 |
| host.ts | Host 半边：! 前置步骤钩子（源码）。 |
| index.js | 生成的 Host 模块。不要编辑。 |
| client.js | 生成的 Client 包。不要编辑。 |
| src/copy.ts | 两条字符串，双语。 |
| src/index.ts | 两个 composer 效果：占位符子句与提示绘制。 |
| src/exec.ts | Shell 行解析、执行与输出格式化。 |
| src/types.ts | 所用 Client 服务的结构化类型。 |
| src/host-types.ts | 所用 Host 服务的结构化类型。 |
| test/run.test.ts | Composer 集成测试（假 DOM + 假 locale）。 |
| test/host.test.ts | Shell 行与前置步骤钩子测试。 |
| test/dsh-format.test.ts | 已安装 Harness 测试：通过真实 Session 追加，再通过真实 v4 reader 重新打开日志。 |
| cordis.patch.yml | 配置档 bundle 行。 |

行为说明

- 仅当草稿就是裸 ! 时才显示提示；输入命令后提示消失。! 后不需要空格。
- 空 composer 上从不显示提示（这种情况由占位符覆盖），句子中间也不显示（hello !world 是普通文本）。
- 提示跟随当前 locale；切换语言会重新渲染。
- 卸载会恢复原来的 translate。

为什么用到 MutationObserver

可编辑区域属于 Lexical，它会在自己的更新阶段把输入的文本提交到自己的段落节点。这个阶段不保证在浏览器派发 input 之前完成，所以同步读取 [data-composer-input] 可能仍描述上一个字符。只在 input 时读取，会让裸 ! 晚一个按键出现——它要等到后面那个空格输入后才显示，之后草稿删回 ! 时又像是「卡住」了。

因此插件在 Lexical 实际产生的 mutation 上重绘，那才是文本已进入 DOM 的权威信号。input 上的延迟读取保留作为兜底。两条路径都只安排一次绘制，所以多画一次代价很低，而且幂等。