前言¶
在 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、驗收三步開始驗證。
