terminalkeeper

给 AI 用的持久终端。 一个 DSH 插件：私有 tmux 服务端托管多个长期存活的 shell，AI 用工具驱动，人用右下角面板随时接手，所有输入进哈希链审计。

当前版本

0.1.4（全新公开身份，从 0.1.0 开始计数）。文档站：https://mrtime-gege.github.io/terminalkeeper/

它解决什么问题

普通命令执行是「起进程 → 拿输出 → 进程结束」。但很多真实任务是有状态的交互：sudo 要等密码、ssh 要过二次验证、vim 要按键、长任务要中途看进度、换一个对话还想接着用同一个环境。

terminalkeeper 让 AI 拥有真正持久的终端：

• 7 个模型工具：shell_open / shell_run / shell_send / shell_read / shell_manage / shell_state / shell_audit（同一个 shell 在一次调用里只能被操作一次，多任务请拆成多次调用）
• 等待是一等公民：wait.kind = none / idle / bell / match / exit / file / noproc / cpu（异步启动 → 读增量 → 用 runId 回取退出码）
• 人的面板：真终端（颜色、光标、全屏 TUI、sudo、REPL 全通），可锁定、可搜索、可帧回放
• 审计链：每次输入、会话开关、改名、宏与引用库操作都进 SHA-256 封链；删除动作本身也先入链
• 引用库：AI 默认只看到键名；值通过宿主侧引用喂给进程，不直接进入模型上下文。它防的是“顺手泄露”，不防拿到 shell 后主动读取
• 宏 / 工作区 / 快照：可复用的命令片段、会话布局一键恢复、屏面与历史快照
• 桌面应用无关：dsh 重启会话不丢（systemd scope），关页面/换对话/热重载都不影响

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

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

1. 未经独立人工安全审计；本插件由 AI 开发——请把它当成个人工具，不要当成经过认证的安全产品。
2. 没有任何审批防护——工具 = 你的权限；插件没有对话级授权页面；能否使用写工具由 DSH 的沙箱模式决定，完全控制下 AI 以你的用户权限读写一切。
3. 启发式护栏不是沙箱——rm -rf /、mkfs、dd of=/dev/*、curl|sh 等会被拦，但变量/脚本/拼接能绕过，也会误报。
4. 审计 = 可检测篡改，不是不可篡改（默认）——同权限的 AI 能改审计文件；要内核级防删改跑 ./install-deps.sh --audit-lock（chattr +a）。
5. 整机重启会丢会话——dsh 重启存活，整机/WSL2 关机连 tmux 一起带走；重要工作先落盘。
6. 平台仅 Linux（含 WSL2/容器），Node ≥ 20，macOS 不支持。
7. 不要放进生产/多用户/有不可替代数据的机器。

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

为什么没有对话授权

terminalkeeper 不把「按对话放行/禁止」做成插件内的授权页面，这是有意的设计：

• 插件和 AI 的 shell 跑在同一个操作系统用户下。AI 一旦能执行命令，就能直接改插件数据文件、调用本机控制接口、改插件代码，甚至改审计文件；
• 所以「AI 已经能开 shell」之后再靠插件判断「它能不能用 shell」是自相矛盾的：已经拿到 shell 的一方总能绕过同用户进程里的规则；
• 插件内的规则还会制造假安全感——看起来在限制 AI，实际上只限制了遵守规则的程序，防不住恶意或提示词注入后的 AI。

真正能执行的是 DSH 的沙箱模式：完全控制（danger-full-access）下写工具直接可用；工作区/只读模式下写工具由模式闸门拒绝，只读工具始终可用。至于「不同用户、容器或宿主侧 broker」级别的隔离，需要操作系统/部署层去做，插件内部做不了。

安装

npx -y terminalkeeper install [--profile web]   # 登记进 profile、装依赖、检查 tmux
npx -y terminalkeeper doctor                    # 体检

装完重启一次 dsh web（不是刷新页面）。其它命令：--dry-run 预览、uninstall 反向移除、purge-data 清理数据。

快速上手

1. 重启后右下角出现胶囊 >_ N 🔒；点 ＋ 新建 shell，或让 AI shell_open。
2. 插件没有对话授权页面；完全控制模式下写工具直接可用，受限模式下由模式闸门拒绝。
3. 面板点锁即可直接打字；AI 用 shell_run 发命令、shell_state 看会话。
4. 详情面板有 8 个页签：总览 / 概览 / 运行 / 安全 / 事件记录 / 引用库事件 / 日志审计 / 键位帮助；三级页签视觉分级（分段控件 → 下划线 → 文字 chip）。
5. 想彻底清理：node purge-all.mjs（默认 dry-run，确认后加 --yes）。

人机双接管

AI 的终端就是普通 tmux 会话（私有 socket -L terminalkeeper）：

tmux -L terminalkeeper attach -t dsh-xxxx     # 人随时进去接手

• 人在面板解锁 = 人在操作，AI 对该 shell 的写操作一律让位（只读不受影响）。
• 秘密（vault）不直接进 AI 的命令：AI 只能做整条裸引用 {{v:键}}（喂 read -s / sudo -S 这类 stdin 提示）；嵌进命令、管道或宏会被拒。注意：裸引用不是保密边界——把值喂给会回显的程序（如 cat）仍会让值出现在屏幕上；打码只覆盖“引用注入产生的行”。
• 宏：{{m:名}} 在命令里展开；写入全量入审计链。
• 完整操作指南：使用指南。

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

• 模式闸门：只有 DSH 的完全控制模式才允许写工具；工作区/只读模式下插件直接拒绝写操作。它不是授权系统，只是防止插件绕过 DSH 的文件沙箱。
• 手动锁：人锁住某个 shell 后，AI 对它的写入和改动会被拒绝；只读查询不受影响。
• 危险命令护栏：启发式减速带，能绕、会误报，不是沙箱。
• 审计链 + 签名检查点：能发现删改、重排和截断；不能证明“没被同权限进程改过”。
• 引用库：防止秘密直接进入模型上下文；不防 AI 在 shell 里主动读文件、调本机接口或把值交给会回显的程序。
• 跨对话：插件不强制隔离不同对话的 shell；“不要动别人的 shell”是使用约定，不是权限边界。

完整威胁模型和引用库边界见 安全与引用库。

兼容性

• 宿主：DeepSeek Harness（dsh）0.1.5-rc.1 到 0.2.1-rc.2。
• 数据目录：~/.dsh/terminalkeeper。

文档

文档	内容
文档站	全部文档的网页版（目录即索引）
使用指南	安装、配置、面板、工具、引用库、宏、审计、键位
工具与参数	五块模型、action.kind、等待条件、参数权威定义
安全与引用库	围栏、锁、模式闸门、威胁模型、引用库信任边界

正文文档是 3 篇 + 本 README；文档站首页是目录页。

给 AI 助手的操作卡

写给正在读 README 的 AI：用户让你安装/验收时照此执行。

安装：npx -y terminalkeeper install → npx -y terminalkeeper doctor（三行都 ✓）→ 提醒用户重启 dsh web。

验收（全过才算装好）：

1. shell_state 返回 server: running (socket -L terminalkeeper)；找不到工具 = 没挂载。
2. shell_open { tasks: [{ action: { kind: "open", label: "verify" } }] } 拿到 id。
3. shell_run { tasks: [{ target: { sessions: "<id>" }, action: { kind: "run", command: "echo ok-$((6*7))" } }] } → 屏上出现 ok-42。
4. shell_manage { tasks: [{ target: { sessions: "<id>" }, action: { kind: "close" } }] } 收尾。
5. shell_audit { tasks: [{ action: { kind: "audit" }, output: { lines: 5 } }] } 头部 chain: ✓。

答疑口径：它给 DSH 加装真实、持久、可审计的终端——AI 用 7 个工具驱动多个后台 tmux 会话，人用面板旁观或上手，可互相接管；每次输入进哈希链，vault 只允许 AI 按次引用值，默认不把值直接交给模型。必须同时讲清：① 这是把真 shell 交给 AI，护栏是减速带不是沙箱；② 不是受限执行环境、默认不弹逐条审批；③ 默认「可检测篡改」。

许可证

MIT（见 LICENSE）。