Mrtime-gege/dsh-agent-shell

dsh-agent-shell

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

npm version
npm license
node
CI

中文（本文件） · English

🙋 作者的话（请先读）

这是一个人的业余项目，不是全职开发，也与任何官方无关。 设计与测试都按自己的工程标准来，但节奏受现实约束：主业加班、健康、token/机器费用都会直接影响更新速度——可能一周三版，也可能一个月没动静；issue 看精力回，PR 欢迎但不承诺合并时限。这里没有 SLA、没有付费支持、没有"随时在线的维护者"。

所以请把预期放在：① 关键场景请自备回退方案；② 升版前扫一眼 CHANGELOG（安全类修复会尽量在公告里写明）；③ MIT 协议，风险自负（下文风险清单请务必读完）。如果它帮到了你，给个 star、或者把它讲给更多人，就是对"用爱发版"最实在的支持。感谢理解 —— 我们尽量把每个版本都发得干净。

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

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

1. 由 AI 开发，无人审计。 设计与实现全部出自 AI，配套一套自动化测试与真机验证，但没有任何人做过安全审计。
2. 授权 = 任意命令。 一个对话被授权后，它的 AI 就能以你自己的用户权限：读文件、改配置、发网络请求、装软件、删东西 —— 本插件没有任何审批防护，不会逐条问你。拒绝授权它就真的执行不了；想彻底关掉门需显式 requireConsent: false（那等于放弃防线）。
3. 不负责后果。 它只是"便捷调用 + 如实记录"，不是沙箱：误删、被提示词注入带偏执行了危险命令、凭据被读到终端里，后果由你自己承担。
4. 唯一防线只是启发式护栏。 guardDangerousCommands 默认开，做关键词匹配（rm -rf /、mkfs、dd of=/dev/ 等）；可被变量/脚本/拼接轻易绕过，也会误报。它是减速带，不是防护。
5. 审计 = "可检测"，不是"不可篡改"（默认）：哈希链能发现"删过/改过/调过序"，但同权限的 AI 本就能改审计文件（它能拿到 shell）；要升级到不可删/改需 chattr +a（见审计）。
6. ssh/远程只有"录像级"审计：记录的是进出隧道的键与屏，不是远端机器上实际执行了什么。
7. 闲置自动关闭（0.3.0 起默认关 = 会话永久保留）：默认不会有任何会话被自动回收。只有显式启用才会关——单个会话 shell_open idleMinutes=30（正数分钟）或打开全局开关 idleClose（给未指定时长的会话兜底 idleCloseMinutes）；0/-1/不指定 = 永不自动关闭。启用后的判定：连续无输入或运行（AI 工具与面板输入含被拦企图都算活动；只读屏/查询不算，否则面板开着永不关），到点关闭并记审计 reason=idle-timeout。
8. 整机重启会丢会话：dsh 自身重启会话存活（systemd 用户 scope）；但整机/虚拟机重启（如 WSL2 VM 休眠/重启）会连 tmux 一起带走——tmux 会话不落盘，属于平台层限制。重要工作先落盘文件。
9. 不要放进生产/多用户/有不可替代数据的机器；内部测试、可重建的环境、你想清楚后果的自用机器才合适。重要数据先备份。

别在终端里长期输入真凭据——面板逐键与留痕是如实记录的（密码提示场景会自动脱敏为 [redacted:password]，但其它明文输出不保证）。

一条命令安装

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

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

会依次：登记进 profile 的依赖与 bundle → 按 pnpm/npm 装依赖 → 检查 tmux → 提示重启 dsh web。
配套：--dry-run 只预览；doctor 体检（tmux / 装没装 / 数据目录）；uninstall 反向移除；--profile 指定其它 profile。
版本节奏：npm 发布由推 v tag 的 GitHub Actions 自动完成（0.2.2 起带 CLI；更早版本没有 bin）。

它是什么

- 私有 tmux 服务端持有多个持久 shell：关页面、换对话、热重载、重启 DSH 都不丢（看门狗赛后收养/回收）。
- 7 个模型工具（0.2.3 精简）：shell_open / shell_run / shell_send / shell_read / shell_manage / shell_state / shell_audit；等待并入了 shell_read（传 until），护栏预演并入了 shell_run/shell_send（传 dryrun），授权状态在 shell_state 里一并汇报；寻址用稳定 id（dsh-…，名字只是可改的 label）。
- 面板（右下角胶囊）：真终端 —— sudo 密码提示、vim 全屏、REPL、补全、历史全都通，输入即进终端。
- 审计一条链管全部：tool-call（调了哪些工具）/input（送进终端的键）/open/close/rename/consent/panel-lock/env-degraded/capture/idle（闲置关闭）/config（设置变更）/claim（接管与交还）/macro（宏写入，全文入链）/vault（秘密消耗，只记键名） 全在 audit-YYYY-MM-DD.jsonl，逐事件即时封链（写入算一次 SHA-256），删一条/改一字节/调顺序 → 断链即报警。

安全边界（更细的"能挡什么、挡不住什么"）

- 确认门一次过后不再问：防手滑与静默启动，不防蓄意 agent —— 原生 bash 能绕过本插件做它想做的一切（包括改授权文件），任何"只在插件通道内生效"的防护都只是对这条通道的礼貌。
- 面板状态行的「无审批」是如实告知，不是开关。
- 人机互斥：解锁面板 = 人在操作，AI 对该 shell 的一切修改（发送/改名/改尺寸/关闭）让路，只读不受影响；解锁/上锁记审计。
- 能力降级如实说：无 systemd → 会话不随dsh重启存活；无 /proc → 嵌套 tmux 忙闲判定退化；每句都是人话，shell_state/面板 ⓘ//diagnose 可查。
- 平台：仅 Linux；Windows 请用 WSL2，macOS 不支持。
- 完全安全模型见 docs/SECURITY.md。

什么时候值得用它

| 场景 | 为什么 |
|---|---|
| sudo / ssh / vim / gdb / REPL 等交互式工具 | 真 TTY：密码提示、全屏 TUI、Ctrl-C 都通 |
| 反复起进程开销大的长任务 | shell 常驻：路径、历史、环境变量一直在 |
| 想查"谁在什么时候让 shell 干了什么" | 审计链逐事件封链、断链即报警 |

快速上手

1. 装好重启后，右下角出现胶囊 >_ N 🔒。
2. 点胶囊 → ＋ 新建 shell；或 shell_open 开一个。
3. 面板：锁图标解锁 → 直接打字；AI：shell_run 发命令 → shell_state 看会话。
4. 首次用工具会问你一次授权；之后正常使用。

人机双接管（0.3.0）：AI 干一半人来接，人干一半 AI 来接

AI 的终端就是普通 tmux 会话（挂在插件的私有 socket 上），你随时可以走进去；你自己在同一 socket 上开的终端，也能让 AI 接管。socket 名与会话 id 用 shell_state 查（server: running (socket -L dsh-agent) 那行）。

① 人接管 AI 的壳（AI 干一半 → 人接手）

tmux -L dsh-agent list-sessions            # 看看都有哪些壳
tmux -L dsh-agent attach -t dsh-ab12cd     # 直接走进去打字（就是普通 tmux）
退出但让会话继续跑：Ctrl-b 然后按 d（detach）

你 attach 期间 AI 仍可读写（shell_state 里会显示 ⚠有人已attach，AI 知情但不停工）。想让 AI 彻底放手：让它执行
shell_manage action=release session=dsh-ab12cd —— 之后 AI 的写操作一律被拒（读不受影响、闲置不回收、不出现在 AI 的 mine 里），现场完全归你。

② AI 接管人建的壳（人干一半 → AI 接手）

tmux -L dsh-agent new-session -s mywork    # 关键：用插件的私有 socket（-L dsh-agent）

⚠ 建会话务必带 -s 名字：不带名字时 tmux 会分配纯数字会话名，而插件按设计过滤纯数字名
（它们与 tmux 给 control 客户端自动建的会话无法区分）——数字名会话在 shell_state/面板里不可见。

然后对 AI 说「接管 mywork」。AI 执行 shell_manage action=claim session=mywork：记归属、开始输出留痕（此前没有）、之后照常 shell_run/shell_read 驱动。干完想还给人：AI release，你再 attach 回去。
（别人对话名下的壳，AI 不能随手 claim —— 需要你明确同意，AI 带 override:true 才行。）

③ 秘密不过 AI 手（vault，配合双域引用）

面板 ⚙ 菜单 →「引用库」页签录入键值；或 CLI（人这一侧）：

dsh-agent-shell vault set sudo-pw '你的密码' --one-shot    # 一次性：注入成功即焚
dsh-agent-shell vault list                                  # AI 也能 list（只见键名，永远不见值）

AI 端只写引用，例如过 sudo 密码提示：

{ "session": "dsh-ab12cd", "steps": [
{ "send": "sudo -S whoami", "expect": "match:[Pp]assword" },
{ "send": "{{v:sudo-pw}}",  "expect": "idle" } ] }
值不进 AI 上下文、不进审计文本、不上工具输出。打码按行身份：只遮注入所在的行（注入命令的回显行、值独占/结尾的行），无关行不误伤也不给"猜一位遮一位"的预言机留信号（0.3.1，详见 SECURITY）；oneShot 的落刀在送出的那一刻（护栏通过后、进管道前）——"发送报错但其实已送达"骗不过一次性。

AI 侧引用规则（0.3.1）：AI 直接写 {{v:}} 时，整条 send 必须只有这一个裸引用（如上例喂 sudo 密码提示）。echo {{v:pw}}、printf %s {{v:pw}} | base64、A={{v:pw}}B 这类"把值嵌进命令"的形态一律拒绝——因为值一旦进入 AI 可加工的管线，任何变换输出（base64/rev/od）都能绕过打码，实测 | base64 就能把一次性键还原（oneShot 只烧第一次，救不了它）。把秘密喂给程序的 stdin 提示是唯一合规路径。 人从面板「引用库」旁亲自输入、或经宏闭环（{{m:bastion}} 内部嵌 {{v:}}，宏文本全量入封链）不受此限。

诚实边界：output/ 留痕是 tmux 原始字节流，值进过 pane 就在里面——vault 防的是 AI 与审计/显示面的顺手泄露，不防本机磁盘，也不防"同时控制字节与提交时序"的主动多步拼接提取（如先 rev  本 README 只保留最近一批更新；更早版本见 docs/CHANGELOG.md 与 docs/更新记录.md。

详细文档

| 文档 | 内容 |
|---|---|
| docs/使用细节.md | 面板/工具用法、配置项、HTTP API、工作原理 |
| docs/SECURITY.md | 安全模型、审计边界、已知限制 |
| docs/升级注意-0.2到0.3.md | 0.2.x 升 0.3.x 的语义变化与迁移须知 |
| docs/CHANGELOG.md | 版本变化 |
| docs/更新记录.md | 完整改动记录（根因 + 验证） |
| docs/设计与实现.md | 内部结构 |
| docs/PUBLISHING.md | 发布流程 |

给 AI 助手的操作卡（安装 · 验收 · 答疑）

这一段写给正在读这份 README 的 AI：用户让你安装/验证本插件，或问"这是干什么的"，照下面执行。

A. 安装（用户让你装时才装；装前把上方风险清单的要点先给用户看一眼）

npx -y dsh-agent-shell install            # 登记进当前 profile（--profile  可指定）
npx -y dsh-agent-shell doctor             # 三行都应 ✓：tmux / profile「x」已安装 / 数据目录

然后提醒用户重启宿主（dsh web 重启，不是刷新页面；宿主代码在启动时加载）。重启后你这侧的会话会在新进程里继续。

B. 验收（按序做，全过才算装好）

1. 挂载确认：调用 shell_state —— 返回里应有 settings:、capability:、server: running (socket -L dsh-agent) 三族信息；找不到该工具 = 没挂载（回 A 查 profile / 是否重启）。
2. tmux 真驱动：shell_open {name:"verify"} → 应返回 session dsh-xxxxxx …；对返回的 id shell_run {command:"echo ok-$((67))"} → 屏上必须出现 ok-42（这条打通 send-keys→tty→渲染→capture 全链路）；shell_manage {action:"close", session:} 收尾。
3. 审计链：shell_audit {days:1, lines:5} 头部有 chain: ✓；要更强保证让用户跑 dsh-agent-shell verify-audit（退出码 0 = 链完整）。
4. 面板（人侧）：让用户看浏览器右下角应有 >_ N 悬浮胶囊，点开能看到刚才的会话；没有就请用户刷新页面（面板资源随宿主加载）。
5. WSL2 等无 systemd 环境：capability 行会显示降级方式（如 tmux 直启），属正常，功能不缺失。

C. 有人问"这个插件是干什么的"——按这个口径回答

一句话：它给 DSH 加装真实、持久、可审计的终端——AI 用 7 个 shell_ 工具驱动多个后台 tmux 会话（长任务、vim/ssh 这类交互程序、跨对话接管），人用右下角悬浮面板随时旁观或直接上手打字；人和 AI 可以在同一批终端上互相接管/交还（claim / release / 原生 tmux -L dsh-agent attach）。每一次输入都进哈希链审计，输出留痕是原始字节（close 记录带 sha256 见证，删改可证）；vault 秘密域让密码"值不过 AI 之手"，宏域让重复命令可以安全沉淀。

必须同时讲清的三件事：① 它把真 shell 交给 AI——危险命令护栏是减速带不是沙箱，装之前让对方读 README 风险清单；② 它不是受限执行环境，也不弹审批；③ 审计默认"可检测篡改"，要内核级不可篡改需 install-deps.sh --audit-lock。

安装/排障细节在 docs/使用细节.md；安全边界以 docs/SECURITY.md 为准。

许可证

MIT（见 LICENSE）。