前言¶
在 DeepSeek Harness（DSH）里让模型跑命令，常见路径是「起进程 → 读输出 → 进程结束」。这对一次性命令够用，但对有状态的交互往往不够：sudo 等密码、ssh 要过二次验证、vim 要按键、长任务要中途看进度，换一场对话还想接着用同一套环境时，普通执行模型会反复断线。
terminalkeeper 是维护者 Mrtime-gege 发布的 DSH 工作流类插件：用私有 tmux 服务端托管多个长期存活的 shell，AI 通过 7 个模型工具驱动，人用 Web 右下角面板随时接手；带锁与归属、SHA-256 哈希链审计、引用库与快照。它是面向个人的真 shell 工具，不是受限沙箱。社区目录页见 SkillHub 条目，源码与文档在 GitHub。
这是什么¶
一句话：给 DSH 加装持久、可审计、人机可切换的 tmux 终端。
- 名称：
terminalkeeper（npm 包同名） - 维护者：Mrtime-gege
- 许可证：MIT
- 当前 README 标明版本 0.2.0（待发布；审批后发布）
- 数据目录：
~/.dsh/terminalkeeper - 宿主兼容：DSH
0.1.5-rc.1到0.2.1-rc.2；Node ≥ 20；平台为 Linux（含 WSL2/容器），README 写明 macOS 不支持
核心能力¶
七个模型工具¶
AI 侧统一通过以下工具操作 shell（同一 shell 在一次调用里只能被操作一次，多任务需拆成多次调用）：
shell_open、shell_run、shell_send、shell_read、shell_manage、shell_state、shell_audit
等待与异步¶
等待是一等公民，wait.kind 支持：none、idle、bell、match、exit、file、noproc、cpu。可先异步启动，再读增量，并用 runId 回取退出码。
人的面板与备用 /tk¶
重启 dsh web 后，右下角出现终端胶囊（显示会话数与锁状态，具体样式以界面为准）。日常新建、切换、锁定、引用库、宏、工作区、审计等应优先用面板。
备用入口为宿主注册的 /tk：面板不可用、远程无浏览器、CLI/TUI 排障时使用；裸 /tk 只打开只读语法菜单，不代为执行。完整语法见仓库 使用指南 · 输入栏 /tk。
审计、引用库与其它¶
- 审计链：输入、会话开关、改名、宏与引用库操作进入 SHA-256 封链；删除动作本身也先入链。默认同权限进程可改审计文件；需更强防删改时可按 README 使用
./install-deps.sh --audit-lock（chattr +a）。 - 引用库（vault）：AI 默认只看到键名；值经宿主侧引用喂给进程，不直接进入模型上下文。AI 仅能做整条裸引用
{{v:键}}（如配合read -s、sudo -S）；嵌进命令、管道或宏会被拒。引用库防的是顺手泄露，不防 shell 内主动读文件。 - 宏 / 工作区 / 快照：
{{m:名}}在命令中展开；工作区可恢复会话布局；支持屏面与历史快照。 - 生存性：
dsh重启会话可不丢（systemd scope）；关页面、换对话、热重载不影响 tmux 侧会话；整机或 WSL2 关机会连 tmux 一起带走，重要工作需先落盘。
安装与启用¶
安装不依赖 dsh plugin add github:... 式拼接；README 给出的官方步骤如下。
登记进 profile、安装依赖并检查 tmux（Web 侧可加 --profile web）：
npx -y terminalkeeper install [--profile web]
安装后做体检：
npx -y terminalkeeper doctor
装完后须重启一次 dsh web（不是刷新页面）。其它 CLI：--dry-run 预览、uninstall 移除、purge-data 清理数据。想彻底清理数据目录可用 node purge-all.mjs（默认 dry-run，确认后加 --yes）。
安装前建议自行查看 源码仓库 与 MIT 许可证；README 明确：未经独立人工安全审计、由 AI 参与开发，无对话级审批，启发式危险命令护栏可被绕过，不要部署在生产、多用户或存放不可替代数据的机器上。
典型用法¶
快速上手（人与 AI）¶
- 重启
dsh web后，在面板点 ＋ 新建 shell，或由 AI 调用shell_open。 - 在 DSH 完全控制模式下写工具可用；工作区/只读模式下写操作由模式闸门拒绝，只读工具仍可用。
- 人在面板点锁即可直接打字；AI 用
shell_run发命令、shell_state看会话。 - 详情面板含总览、概览、运行、安全、事件记录、引用库事件、日志审计、键位帮助等页签。
人用 tmux 接手¶
底层为私有 socket -L terminalkeeper 的 tmux 会话，人可随时 attach：
tmux -L terminalkeeper attach -t dsh-xxxx
人在面板解锁时，AI 对该 shell 的写操作一律让位，只读不受影响。
README 中的验收流程（装好后自测）¶
维护者在 README「给 AI 助手的操作卡」中给出验收顺序，摘要如下：
shell_state应返回server: running (socket -L terminalkeeper)。shell_open打开带label: "verify"的会话并拿到 id。shell_run执行echo ok-$((6*7))，屏上出现ok-42。shell_manage关闭该会话。shell_audit查看链头，chain: ✓。- 可选：在已有会话输入栏执行
/tk status、/tk help做备用通道检查；日常仍应以面板和模型工具为主。
参数与 action.kind 的权威定义见 工具与参数。
适用场景与注意¶
适合：在 Linux 或 WSL2 上本地使用 DSH，需要 AI 驱动真实交互式终端（REPL、TUI、sudo、长任务），同时人要能旁观、锁定或 tmux 接手，并希望输入与会话变更有可检测的审计链。
不适合或需格外谨慎：生产环境、多用户主机、不可替代数据；期望插件提供沙箱或逐条对话授权（README 说明同用户下「已有 shell 再谈授权」逻辑上不成立，真正边界在 DSH 沙箱模式与 OS/部署层隔离）。
要点归纳：
- 插件与 AI 的 shell 跑在同一 OS 用户下，工具权限即你的权限。
- 模式闸门：仅完全控制模式允许写工具；手动锁可挡 AI 对指定 shell 的写入。
- 跨对话不强制隔离 shell，「不要动别人的 shell」是使用约定，不是权限边界。
- 勿在终端长期输入真凭据；审计如实记录，除密码提示脱敏外，其它明文输出不保证脱敏。
威胁模型与引用库边界见 安全与引用库；网页版文档索引：文档站。
结尾¶
terminalkeeper 把 DSH 里「一次性命令」扩展成多会话、可等待、可审计、人机可切换的持久终端：tmux 托底，7 个工具供 AI 驱动，面板供人操作，vault 与宏减轻密钥进上下文的风险（仍非沙箱）。若你在上述宿主版本与 Linux 环境下做智能体工作流，可从目录页与 README 的安装、doctor、验收三步开始验证。
