dsh-agent-shell

dsh-agent-shell

给 DeepSeek Harness 的持久化多 shell 终端：7 个模型工具 + 右下角一个可拖动、可直接打字的悬浮面板。

中文（本文件） · English（冻结于 0.3.1，中文唯一权威）

🙋 作者的话

一个人的业余项目，与任何官方无关。 节奏受现实约束（主业/健康/费用），没有 SLA、没有付费支持。所以：① 关键场景自备回退；② 升版前扫一眼 CHANGELOG；③ MIT，风险自负（下面风险清单务必读完）。帮到你了的话，一个 star 就是最实在的支持。

⚠️ 风险，先读清楚再决定装不装

这工具能把你的机器交给 AI。 它不是玩具，也不是"受限执行环境"。

1. 由 AI 开发，无人审计——自动化测试 + 真机验证有，人工安全审计没有。
2. 授权 = 任意命令——一个对话被授权后，它的 AI 以你自己的用户权限读写一切；本插件没有任何审批防护，不会逐条问你。彻底关审批需显式 requireConsent:false（等于放弃防线）。
3. 不负责后果——误删、提示词注入带偏、凭据被读到终端里，后果自负。
4. 唯一防线只是启发式护栏——guardDangerousCommands 关键词匹配（rm -rf /、mkfs、dd of=/dev/* 等）；可被变量/脚本/拼接轻易绕过，也会误报。它是减速带，不是防护。
5. 审计 =「可检测篡改」不是「不可篡改」（默认）——哈希链能发现删/改/调序，但同权限的 AI 本就能改审计文件；要内核级防删改跑 ./install-deps.sh --audit-lock（chattr +a）。
6. ssh/远程只有「录像级」审计——记的是进出隧道的键与屏，不是远端实际执行了什么。
7. 闲置回收默认关（0.3.0 起 = 会话永久保留）——只在显式启用 idleClose 或单会话 idleMinutes 后才到点关闭并记审计；只读屏/查询不算活动。
8. 整机重启会丢会话——dsh 自身重启存活（systemd scope），但整机/WSL2 虚机关机连 tmux 一起带走。重要工作先落盘。
9. 不要放进生产/多用户/有不可替代数据的机器；平台仅 Linux（Windows 用 WSL2，macOS 不支持）。

别在终端里长期输入真凭据——留痕是如实记录的（密码提示会自动脱敏，但其它明文输出不保证）。

一条命令安装

先决条件：Linux（含 WSL2/容器）、Node ≥ 20、运行的 DSH（0.1.5+）。

npx -y dsh-agent-shell install [--profile web]     # 当前 0.3.3

依次：登记进 profile → 装依赖 → 检查 tmux → 提示重启 dsh web。配套：--dry-run 预览；doctor 体检；uninstall 反向移除。

它是什么

• 私有 tmux 服务端持有多个持久 shell：关页面、换对话、热重载、重启 DSH 都不丢。
• 7 个模型工具：shell_open / shell_run / shell_send / shell_read / shell_manage / shell_state / shell_audit；等待并入 shell_read（until），护栏预演并入 dryrun，寻址用稳定 id（名字只是可改的 label）。
• 面板（右下角胶囊）= 真终端：sudo 提示、vim 全屏、REPL、补全、历史全都通。0.3.3 起抓屏走 SSE 推送（输入当刻回显，断线退回轮询）、🎬 帧回放（replayCapture 默认关，逐帧回看"刚才实际发生了什么"）。
• 审计一条链管全部：工具调用/输入键/开关改名/授权/锁定/接管/宏与秘密操作/闲置/设置变更……全部事件在 audit-YYYY-MM-DD.jsonl 逐条封链（SHA-256 串接），删一条/改一字节/调顺序 → 断链即报警（事件全表见 SECURITY）。

什么时候值得用它

交互式程序（sudo/ssh/vim/gdb/REPL——真 TTY 全通）· 长任务（shell 常驻，路径/历史/环境一直在，不用反复起进程）· 要查账（谁在什么时候让 shell 干了什么：审计链封链 + 🎬 帧回放，断链即报警）。

快速上手

装好重启 → 右下角出现胶囊 >_ N 🔒；点 ＋ 新建 shell（或让 AI shell_open）。面板点锁即直接打字；AI 用 shell_run 发命令、shell_state 看会话。每个对话首次用工具会请你授权一次，之后正常用。

人机双接管（一句话版）

AI 的终端就是普通 tmux 会话（私有 socket -L dsh-agent）：你 tmux -L dsh-agent attach -t dsh-xxxx 随时进去接手，想让 AI 彻底放手就说「release」；你在同一 socket 建的壳（务必 -s 带名字），AI shell_manage action=claim 就能接手。秘密（vault）值不过 AI 之手——AI 只能写 {{v:键}} 裸引用喂 stdin 提示；宏（{{m:名}}）沉淀重复命令、写入全量入链。完整操作与规则见 docs/使用细节.md「人机双接管完全指南」。

安全边界（能挡什么、挡不住什么）

• 确认门一次过后不再问：防手滑与静默启动，不防蓄意 agent——原生 bash 能绕过本插件做它想做的一切，任何"只在插件通道内生效"的防护都只是对这条通道的礼貌。
• 人机互斥：面板解锁 = 人在操作，AI 对该 shell 的修改一律让路（只读不受影响）；解锁/上锁记审计。
• 能力降级如实说：无 systemd → 会话不随 dsh 重启存活；无 /proc → 嵌套 tmux 忙闲判定退化——每句人话，shell_state/面板 ⓘ//diagnose 可查。
• 完整安全模型以 docs/SECURITY.md 为准（随包发布）。

宿主版本现状（dsh，明确说明）

本插件的宿主是 DeepSeek Harness（dsh），两者版本需放在一起看：

• 当前部署：@deepseek-ai/dsh@0.1.5-rc.1（npm 全局安装于 ~/.nvm/versions/node/*/lib/node_modules/@deepseek-ai/dsh），本插件全部功能与测试都基于这一版。
• 上游已有新版本：npm latest 已推到 0.1.5-rc.2（2026-09-22 发布）；另有 next: 0.1.5-rc.3、alpha: 0.1.7-alpha.2 在同轨道上继续前进。
• 核对结论：0.1.5-rc.1 → rc.2 的官方发布记录只有 Improvements / 其他变更 类条目（界面与内部打磨），没有破坏性/不兼容更新（无 breaking、无配置或 API 破坏项）。
• 决策：暂不升级、暂不在新版本上做适配测试。理由：
  1. 当前部署稳定：本插件全套测试（pure / client / edge / smoke / longrun）在 0.1.5-rc.1 上全绿，没有"必须跟着上游走"的修复需求；
  2. 升级收益低风险不可忽略：UI 类更新也会改面板挂载点/客户端 bundle 的哈希与渲染路径，任何本地适配漂移都要重新验证整套面板与工具链；
  3. 等上游更成熟的 stable（或出现本插件需要跟随的修复）再评估，评估时以重跑全套测试 + 面板实机回归为准。

本段只是如实记录当前部署决策与依据；若日后升级 dsh，记得同步核对本插件的面板挂载与『参数设置』入口，并重新跑全套测试。

最近更新

0.3.3（2026-09-22）— 面板推送化 + 启动让路 + 帧回放 + tmux 原生三件套 + 全量验证收尾

• 🎬 帧回放（replayCapture 默认关）+ 抓屏 SSE（/stream）：面板输入当刻回显（ 写给正在读这份 README 的 AI：用户让你装/验收本插件，或问"这是干什么的"，照下面执行。

A. 安装（装前把上方风险清单要点给用户看一眼）：npx -y dsh-agent-shell install → npx -y dsh-agent-shell doctor（三行都 ✓）→ 提醒用户重启 dsh web（不是刷新页面）。

B. 验收（按序，全过才算装好）：① shell_state 返回 server: running (socket -L …)；找不到工具 = 没挂载；② shell_open {name:"verify"} → 对返回 id shell_run {command:"echo ok-$((6*7))"} → 屏上必须出现 ok-42 → shell_manage action=close 收尾；③ shell_audit {days:1,lines:5} 头部 chain: ✓；④ 让用户看右下角悬浮胶囊，没有就刷新页面；⑤ 无 systemd 环境（如 WSL2 旧版）capability 行显示降级属正常。

C. 答疑口径：它给 DSH 加装真实、持久、可审计的终端——AI 用 7 个 shell_* 工具驱动多个后台 tmux 会话（长任务、vim/ssh、跨对话接管），人用右下角面板随时旁观或上手打字，可互相接管/交还；每次输入进哈希链审计，vault 让密码值不过 AI 之手。必须同时讲清：① 这是把真 shell 交给 AI，护栏是减速带不是沙箱；② 不是受限执行环境、不弹审批；③ 默认"可检测篡改"，内核级防删改需 --audit-lock。排障细节见 docs/使用细节.md；安全边界以 docs/SECURITY.md 为准。

许可证

MIT（见 LICENSE）。