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）：面板输入当刻回显（<100ms）、没变不推、断线自动退回轮询；回放成品屏逐帧带时刻（去重/8MiB/同一条脱敏路），会话关了帧还在，close 审计带回文件名与帧数。
• tmux 原生能力接入：remain-on-exit 死壳定格 2 分钟（⚰ 退出码可读、屏面保留供回看，到点回收）；monitor-bell 响铃旗标（面板 🔔、steps expect:"bell"——旗标粘滞只做灭→亮沿变，已亮如实拒绝不装万能）；window_activity 最后输出时刻随行带出；启动时自动回收 control 重连攒下的 tmux 幻影会话（详情里如实报告数量，不再混进会话列表）。
• 工作区（workspace-save/list/restore/delete）：一组壳的现场（label/cwd/尺寸/闲置策略）存成命名场景，整机/WSL 重启丢壳后一条命令整批重建。
• 宏历史与还原（macro-history/restore + CLI）：宏文本就全量入封链——按 at 一键还原任意历史版本，提示词注入偷改宏后可见可逆。
• 启动让路：就绪链（4 次子进程）推迟到 startupDeferMs（默认 2s）或真实使用秒唤醒；审计链头 O(1) 读回、整链校验挪后台趟；systemd 探针缓存 24h。banner 关键路径本就仅 ~50ms（冷导入+注册），没动它。
• 面板体验：ⓘ 详情新增「运行参数」卡（生效值直读）+「启动」段（阶段流程图：注册→延迟门→就绪链→就绪）；授权按钮补按下态样式；「官方审批」提示可×收起（本机 localStorage 记住）；插件未就绪时屏幕显示「(插件启动中…)」而非「(无输出)」；/list 在启动期间快速返回（不挂面板首帧）。
• shell_state 瘦身 97% + lines 描述纠偏 +《工具参数手册》+ HTTP 路由 22→25 + 提示词安全双保险（schema 禁 {{ + 宿主消毒）+ 系统控制客户端幻影清理。
• 全量验证收尾（本批最后三轮）：① control 捕获路径三连修复——capture-pane -S -N 锚点在共享 control + 并发流下不可靠（返回旧屏 → 假 ✅ exit 0），改「全量捕获 + 取底部 max(lines, 屏高) 行」确定性切片；子壳命令（( )/&+sleep）误判空闲时「只认回显行之后的 exit 标记」并轮询等标记（parseFreshExit 纯函数）；control 客户端 teardown 后置空引用（不再复用死句柄）。顺带 close/reap/面板关闭的审计记录改为落盘后才返回；/list 启动期快速返回与全量载荷同构。② ⓘ 详情重排为 6 张主题卡（会话/服务端/运行参数/运行状态/安全与审批/关于），信息一行不减、默认只展开高频两张。③ 本机环境修复：Kali+WSL2 上 ~/.bashrc source nvm 时自动 nvm use 拖慢每壳启动 3~9 秒（注入回车排队"看似失效"），已加 --no-use 恢复 0.35s（备份 ~/.bashrc.bak-20260921-205038，删掉 --no-use 可还原）。全套件绿：pure 248 / client 426 / edge / smoke / env / watchdog / longrun（连续多遍稳定）。

0.3.2（2026-09-19）— 稳健补丁批

vault/宏库损坏显式报 + 面板×烧键并发锁 + oneShot 并发闸 + 键 TTL + 审计 /chain /vault-history 与 close 见证 + redactSecrets 跨行修复 + 授权面板重排 + 长任务套件。更早版本见 docs/CHANGELOG.md 与 docs/更新记录.md。

详细文档

文档	内容
docs/使用细节.md	人机双接管完全指南、面板/工具用法、配置项、HTTP API、工作原理
docs/工具参数手册.md	每个工具的每个参数：承诺语义、坑、实测核验结论（56 参数全典）
docs/SECURITY.md	安全模型、审计边界、已知限制（随包发布）
CHANGELOG / 更新记录 / 升级注意-0.2到0.3	版本变化 / 完整改动根因 / 跨大版本迁移
设计与实现 / CONTRIBUTING / PUBLISHING / archive/	内部结构 / 贡献 / 发布 / 已兑现设计稿归档

给 AI 助手的操作卡

写给正在读这份 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）。