terminalkeeper

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

当前版本

0.2.0（待发布；审批后发布）。变化见 CHANGELOG 的 0.2.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 在一次调用里只能被操作一次，多任务请拆成多次调用）
• 备用命令行 /tk：面板不可用或需要恢复/排障时的纯文本入口；官方菜单只提示语法，不执行；日常操作请优先使用面板
• 等待是一等公民：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. 日常操作优先用面板：新建/切换/锁/批量操作、引用库、宏、工作区、审计都在面板；只有面板不可用或排障时才用输入栏 /tk（见下）。
6. 想彻底清理：node purge-all.mjs（默认 dry-run，确认后加 --yes）。

输入栏 /tk（备用入口，不推荐日常使用）

日常操作请优先使用右下角面板和设置页。/tk 是备用通道，不建议作为主要操作方式；不要把“能用命令”理解成“推荐用命令”。

/tk 是插件注册的唯一宿主命令（ctx.commands），Web 输入栏、CLI/TUI 共用；命令和结果都走会话文本流，不打开面板或其它 Web 结果页面。它存在的意义是：面板打不开、远程/无浏览器、CLI/TUI、排障与恢复时，仍有一个纯文本入口。它不是面板的等价替代，功能和安全性都更弱。

为什么只建议备用：

1. 不会替你操作：输入裸 /tk 打开的是只读语法菜单。选中一项只在输入栏上方显示完整语法，不执行、不填草稿；裸 /tk 会被清掉，仍需自己手输完整命令。
2. 新会话草稿不执行：/tk 是会话命令，必须在已有会话的输入栏执行；全新草稿页只能看菜单提示，先发一条消息建立会话。
3. 命令会进入模型上下文：命令参数、文件路径、键名、备注和结果都可能被 AI 看到。不要为了“让 AI 知道”把敏感信息写进命令。
4. 秘密只能走文件：没有交互式口令输入；--value-file / --passphrase-file / --text-file 必须指向 0600 文件，且文件路径会进入上下文。key get 默认只返回元数据，导出值只写文件、不打印。
5. 功能是面板的子集：列表筛选、批量操作、锁与接管、快照预览、引用库编辑/解锁、宏与工作区管理、审计详情、设置页等，仍以面板为主；命令只覆盖其中一部分运维动作。
6. 没有审批，也没有更强隔离：--yes 只是防误触，不是授权；危险命令护栏是启发式减速带，能绕、会误报；同用户、同机器的边界不变。
7. 不适合长任务和交互：长输出、TUI、实时进度、并发操作请用面板或模型工具；纯文本结果在会话里也不便于回看和筛选。

适合用 /tk 的场景：面板无法打开、无浏览器/远程环境、CLI/TUI、恢复与排障、把状态或审计结果落到文本流。

备用场景常用：/tk status、/tk shell list、/tk vault group list、/tk audit chain、/tk workspace list；完整语法用 /tk help。

完整命令表、菜单行为和安全约束见使用指南 · 输入栏 /tk。

人机双接管

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 里主动读文件、调本机接口或把值交给会回显的程序。
• 输入栏 /tk（备用）：日常优先面板；命令文本和结果进入会话记录；秘密值不得写在命令行，只能通过 0600 文件传入。菜单只做语法提示，不执行。
• 跨对话：插件不强制隔离不同对话的 shell；“不要动别人的 shell”是使用约定，不是权限边界。

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

兼容性

• 宿主：DeepSeek Harness（dsh）0.1.5-rc.1 到 0.2.1-rc.2。
• /tk 文本命令要求宿主提供 ctx.commands；官方只读菜单要求客户端提供 ctx.commandUi。缺少对应服务时该入口不启用，其余功能不受影响。
• 数据目录：~/.dsh/terminalkeeper。

文档

文档	内容
文档站	全部文档的网页版（目录即索引）
使用指南	安装、配置、面板、备用输入栏 /tk、工具、引用库、宏、审计、键位
工具与参数	五块模型、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: ✓。
6. 可选（备用入口）：请用户在已有会话里执行 /tk status，应返回 terminalkeeper=on、sessions=、audit= 等文本；执行 /tk help 应看到完整语法。日常验收仍以面板和模型工具为主。

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

许可证

MIT（见 LICENSE）。