前言¶
用 DeepSeek Harness（DSH）的 Web GUI 做智能体开发时，常见流程是：在 composer 里描述需求，让模型改代码、跑脚本。若只想查版本、列目录、执行一条本地 shell，仍走模型对话会多一轮上下文，也更容易把无关输出写进会话。
dsh-cli-mode 在输入框首字符使用 ！ 或 ! 时，整行作为真实命令在当前会话工作目录执行，不发送给模型、不产生对话轮次。下面介绍它的能力、安装方式与安全边界。
这是什么¶
dsh-cli-mode 是维护者 Shadoso-w 发布的 DSH bundle 插件，分类为客户端：Host 半注册 /cli-mode/* 路由并通过 ctx.shell 执行命令；浏览器半监听 composer 草稿、切换命令行模式样式，并在输入区下方展示结果卡。
一句话定位：Web UI composer 中以 ！ 或 ! 开头的行，在会话 sandbox 工作目录里当作 shell 命令运行，结果以卡片形式反馈，命令与 stdout 不进入模型上下文。
核心功能¶
进入与交互¶
| 操作 | 行为 |
|---|---|
| 输入 | 首字符为 ！ 或 !（可带前导空格，例如 ! npm --version）即进入命令行模式 |
| 视觉 | 命令行模式激活时，输入区文字变为红色（#e5484d） |
| 执行 | Enter 执行；Shift+Enter 换行；Esc 清除该行并退出命令行模式 |
反馈与历史¶
- 成功：提示「命令已执行」，展示
`cmd` 命令已执行、标准输出与当前cwd。 - 失败：系统报错原文，并附带 「下一步建议」 编号清单（由
suggest.js按报错指纹生成，覆盖命令不存在、权限、路径、npm/ Git、沙箱拒绝、超时等常见情况）。 - 结果卡显示在输入区下方，可点「清除」；命令历史按会话持久化，路径为
${DSH_HOME:-~/.dsh}/cli-mode/history/<session>.json，最多 200 条。
Host API（浏览器通过同源 fetch 调用）¶
| 路由 | 请求体 | 响应要点 |
|---|---|---|
POST /cli-mode/exec |
{ command, sessionId, timeoutMs? } |
{ ok, kind, command?, stdout?, stderr?, truncated?, workdir, message, suggestions? } |
POST /cli-mode/workdir |
{ sessionId } |
{ workdir } |
POST /cli-mode/history |
读：{ sessionId }；写：{ sessionId, entries } |
{ entries } |
可调常量（无 settings schema，需改源码顶部常量）¶
| 常量 | 文件 | 默认值 | 含义 |
|---|---|---|---|
DEFAULT_TIMEOUT_MS |
lib/index.js |
120000 |
单条命令默认超时 |
MAX_TIMEOUT_MS |
lib/index.js |
600000 |
请求超时的硬上限 |
STDOUT_MAX_BYTES |
lib/index.js |
120000 |
单流捕获字节上限 |
CFG.timeoutMs |
lib/client.js |
120000 |
浏览器侧请求超时 |
CFG.outputLimit |
lib/client.js |
4000 |
结果卡展示的 stdout 字符数 |
当前 package 版本为 1.3.0，许可证 MIT，要求 Node >= 20。
安装与启用¶
市场/可发布安装与官方 README 一致，在指定 profile 下执行（将 <package-or-tarball-or-git-url> 换为实际包名、 tarball 或 Git URL）：
dsh plugin --profile web add <package-or-tarball-or-git-url>
dsh plugin add 会在 profile 目录运行 pnpm，并根据已安装包声明的 dsh.bundle 自动 reconcile dsh.profile.bundles。
本地开发可将包链到 profile 的 node_modules，并在 <DSH_HOME>/profiles/<profile>/package.json 中增加 dependencies 与 dsh.profile.bundles，然后重启 profile：
dsh web
安装前建议阅读 GitHub 仓库 源码与 MIT 许可证；插件命令以当前 DSH 进程权限、经会话 sandbox 策略执行，等同于在 harness 会话环境里开 shell。
典型用法¶
- 启动 Web：
dsh web，在浏览器打开对应会话。 - 在 composer 输入框首字符输入
!或！，确认输入区变红。 - 输入命令，例如
! npm --version或! ls，按Enter执行。 - 在输入区下方的结果卡查看 stdout、
cwd或失败时的「下一步建议」；不需要时点击「清除」。
排查鉴权与 Origin 门闩时，可在已登录页面的控制台调用只读探测接口（不执行任何命令）：
await (await fetch('/cli-mode/probe', { method: 'POST' })).json()
返回字段包括 authenticated、gateShape、cookiePresent、loopback 等，用于区分「未带会话 cookie」与「connection 门闩解析异常」。
适用场景与注意¶
适合：已在 DSH Web 里维护会话工作区，需要频繁执行短命令（版本检查、目录列表、单次构建/测试）且不希望污染模型上下文的开发者。
安全与部署（README 明确的三道门，须全部通过才会执行）：
- 浏览器会话：插件路由复用 deployment
connection服务的requestRejection/isAuthenticated（运行时探测实际存在的门）；无会话返回 401。 - Origin 围栏：默认同 host 的 loopback 场景；跨站
sec-fetch-site: cross-site拒绝 403；LAN 部署需自行放宽。 - 文件沙箱：经
ctx.shell与会话 sandbox 策略；写被拒时返回沙箱失败及加宽模式建议。
命令在服务端以 DSH Host 身份运行，不是浏览器沙箱里的 JavaScript。安装前请自行审计 lib/index.js 与路由逻辑；社区目录 SkillHub 插件页 与 GitHub 无 DeepSeek / 幻方官方从属关系，仅为 DSH 生态中的第三方插件条目。
结尾¶
dsh-cli-mode 把 composer 首字符 ! / ！ 变成会话工作区内的真实 shell 入口：不占用模型轮次，失败时有结构化「下一步建议」，历史按会话落盘。需要安装或 issue 时，见 SkillHub 目录 与 GitHub：Shadoso-w/dsh-cli-mode。
