dsh-agent-shell
适用于 DeepSeek Harness (DSH) 的持久化、与对话解耦的多 Shell 终端面板：真实 tmux TTY、7 个模型工具、可拖拽浮动面板
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:Mrtime-gege/dsh-agent-shell#a8276ad550c591de68619faccfa6c80cde87d0d9Agent Shell 以 dsh-agent-shell 发布，当前版本为 0.3.2。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
给 DeepSeek Harness 的持久化多 shell 终端：7 个模型工具 + 右下角一个可拖动、可直接打字的悬浮面板。
中文（本文件） · English
这是一个人的业余项目，不是全职开发，也与任何官方无关。 设计与测试都按自己的工程标准来，但节奏受现实约束：主业加班、健康、token/机器费用都会直接影响更新速度——可能一周三版，也可能一个月没动静；issue 看精力回，PR 欢迎但不承诺合并时限。这里没有 SLA、没有付费支持、没有"随时在线的维护者"。
所以请把预期放在：① 关键场景请自备回退方案；② 升版前扫一眼 CHANGELOG（安全类修复会尽量在公告里写明）；③ MIT 协议，风险自负（下文风险清单请务必读完）。如果它帮到了你，给个 star、或者把它讲给更多人，就是对"用爱发版"最实在的支持。感谢理解 —— 我们尽量把每个版本都发得干净。
这工具能把你的机器交给 AI。 它不是玩具，也不是"受限执行环境"。
requireConsent: false（那等于放弃防线）。guardDangerousCommands 默认开，做关键词匹配（rm -rf /、mkfs、dd of=/dev/* 等）；可被变量/脚本/拼接轻易绕过，也会误报。它是减速带，不是防护。chattr +a（见审计）。shell_open idleMinutes=30（正数分钟）或打开全局开关 idleClose（给未指定时长的会话兜底 idleCloseMinutes）；0/-1/不指定 = 永不自动关闭。启用后的判定：连续无输入或运行（AI 工具与面板输入含被拦企图都算活动；只读屏/查询不算，否则面板开着永不关），到点关闭并记审计 reason=idle-timeout。dsh 自身重启会话存活（systemd 用户 scope）；但整机/虚拟机重启（如 WSL2 VM 休眠/重启）会连 tmux 一起带走——tmux 会话不落盘，属于平台层限制。重要工作先落盘文件。别在终端里长期输入真凭据——面板逐键与留痕是如实记录的（密码提示场景会自动脱敏为
[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）。
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），删一条/改一字节/调顺序 → 断链即报警。dsh重启存活；无 /proc → 嵌套 tmux 忙闲判定退化；每句都是人话，shell_state/面板 ⓘ//diagnose 可查。| 场景 | 为什么 |
|---|---|
sudo / ssh / vim / gdb / REPL 等交互式工具 | 真 TTY：密码提示、全屏 TUI、Ctrl-C 都通 |
| 反复起进程开销大的长任务 | shell 常驻：路径、历史、环境变量一直在 |
| 想查"谁在什么时候让 shell 干了什么" | 审计链逐事件封链、断链即报警 |
>_ N 🔒。shell_open 开一个。shell_run 发命令 → shell_state 看会话。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 <<<再裸注入）。要防的就是那个不可信的 AI 本身，就别把重要凭据放进它能引用到的会话——这是这类工具的统一边界，不是 vault 的实现缺陷。
④ 宏（可复用命令片段，人和 AI 都能写）
dsh-agent-shell macros set deploy 'cd /srv/app && git pull && make restart' # CLI
或在面板「引用库」里写，或让 AI shell_manage action=macro-set。之后任何一方发 {{m:deploy}} 即展开执行；宏内容可嵌 {{v:键}}（发送时才展开，值不落脚本）。所有宏写入全量进审计封链——防止提示词注入把持久化命令偷渡进你的环境。
~/.dsh/agent-shell/audit-YYYY-MM-DD.jsonl（按天，保留期自动清理）；output/ 是终端录像（原始字节，链上 open 记录带它的路径）。./install-deps.sh --audit-lock（chattr +a，需一次性 root；加锁后无法自动清理、需人工归档）。ttlDays 三入口（CLI/面板/HTTP），N 天未用自动焚（10 分钟粒度，expire 入账，缺时间戳永不误伤）。GET /vault-history（键使用史聚合，只有键名与引用原文）+ GET /chain（新鲜复验）；close 记录带留痕 transcriptSha256+bytes（删改留痕可证）；过滤视图头部不再陈旧计数。password: 形状规则原会跨行吞掉提示下一行的真实输出（ssh 排障实锤"假失败"）；收紧为同行空白，HTTP 折叠头仍由 Bearer 规则兜住。file: 等待支持 ~ 展开（waitFor/steps 一致）。scripts/test-longrun.mjs（可复用固定流程）：5 路并行/300 步流式/工具链 17 项/vim+REPL 交互/sudo+ssh 凭据自适应（缺凭据自动 SKIP，CI 可跑）/oneShot 并发竞态/close 见证/链复验/临时密钥目录自毁。教训钉进脚本：pane 环境无 USER/LOGNAME，取用户名必须 $(id -un)。本 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 | 发布流程 |
这一段写给正在读这份 README 的 AI：用户让你安装/验证本插件，或问"这是干什么的"，照下面执行。
npx -y dsh-agent-shell install # 登记进当前 profile（--profile <名> 可指定）
npx -y dsh-agent-shell doctor # 三行都应 ✓：tmux / profile「x」已安装 / 数据目录
然后提醒用户重启宿主（dsh web 重启，不是刷新页面；宿主代码在启动时加载）。重启后你这侧的会话会在新进程里继续。
shell_state —— 返回里应有 settings:、capability:、server: running (socket -L dsh-agent) 三族信息；找不到该工具 = 没挂载（回 A 查 profile / 是否重启）。shell_open {name:"verify"} → 应返回 session dsh-xxxxxx …；对返回的 id shell_run {command:"echo ok-$((6*7))"} → 屏上必须出现 ok-42（这条打通 send-keys→tty→渲染→capture 全链路）；shell_manage {action:"close", session:<id>} 收尾。shell_audit {days:1, lines:5} 头部有 chain: ✓；要更强保证让用户跑 dsh-agent-shell verify-audit（退出码 0 = 链完整）。>_ N 悬浮胶囊，点开能看到刚才的会话；没有就请用户刷新页面（面板资源随宿主加载）。capability 行会显示降级方式（如 tmux 直启），属正常，功能不缺失。一句话：它给 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）。