opencode-poorguy-shellkeeper

English

opencode 插件：把 Hermes Agent 的"持久 shell"理念带进 opencode——跨 AI 调用保留 cwd、环境变量、别名；外加一个固定在 TUI 底部的双栏 dock 面板，实时盯进程。

功能一览

• shell 工具（server 插件）：默认复用按 session::name 隔离的持久 powershell.exe，跨调用保留 cwd / 环境变量 / 别名。命令经 base64 + UTF-8 包裹投入，规避 PS 5.1 GBK 输入问题。
• dock 面板（TUI 插件，可选，推荐装）：输入框下方双栏固定面板：
  • 左栏：当前选中 shell 的实时历史（可滚动，包含 ≤8000 字符完整输出；进程存活状态 / PID / cwd）
  • 右栏：shell 标签列表（当前高亮）+ 直接输命令的输入框
• /shells 命令：把光标聚焦到面板右侧输入框
• 进程内 inbox 通道：面板输入 → inbox/<sessionID>__<name>.jsonl → server 插件 500ms 轮询执行 → 状态文件回写 → 面板 1s 轮询刷新（跨进程零依赖）

安装

1. 在 ~/.config/opencode/opencode.jsonc 的 plugin 数组加入：

// ~/.config/opencode/opencode.jsonc
{
  "plugin": ["@thd3178/opencode-poorguy-shellkeeper"]
}

2. （可选但强烈推荐）在 ~/.config/opencode/tui.json 的 plugin 数组加入同名包，启用 dock：

{
  "plugin": ["@thd3178/opencode-poorguy-shellkeeper"]
}

只有 opencode.jsonc 注册是工具；面板完全来自 tui.json，两者独立，缺面板不影响工具。

用法

AI 侧：shell 工具

| 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | command | string | （必填） | PowerShell 命令，支持多行；禁止 exit（会杀掉会话） | | timeout | number | 120000 | 超时毫秒；超时自动杀掉并恢复 cwd 重建 | | name | string | main | 命名会话，不同 name 完全独立 | | reset | boolean | false | 先杀掉该 name 的会话再执行（环境变量清空，cwd 回到项目目录） |

AI 每次调用的返回末尾都会跟一行 [ocps] shell=<name> ok=<bool> code=<n> cwd=<路径> 元信息。落盘的状态文件格式稳定，直接喂面板的。

规则（已写进工具描述，AI 会守）：

1. 长驻服务（web 服务、springboot 等）必须 Start-Process / Start-Job 后台化，禁止前台占住会话
2. 要并行干两件事就 name="scratch" 开新会话
3. 会话卡死或想要干净环境就 reset=true

用户侧：面板

• 左栏：当前选中 shell 的完整滚动历史，滚轮/键盘翻看
• 右栏：shell 列表 + 输入框，直接输 PowerShell 命令回车执行
• 输入框里也有自己的"命令"：
  • /new <名字> 开新 shell 并切换
  • /select <名字> 切到已有 shell
  • （即：在面板里输入的命令不会进 AI 聊天，只进面板 shell）

禁用持久化

OPENCODE_PERSISTENT_SHELL=0（或 false）时，工具退化为每次调用独立子进程（一次性 shell，跑完即销毁）。此模式不写状态文件、面板空白。

状态文件

正常模式下每次执行写 %LOCALAPPDATA%\opencode\persistent-shell\<sessionID>.json。目录可用 OPENCODE_PS_STATE_DIR 覆盖（测试隔离用）。

已知限制（设计使然）

• 非交互式：面板输入的命令只走 stdin pipe，不支持 npm login、redis-cli 裸进入 REPL 这类的 prompts——这类需求请回 opencode 主输入框或让它走非交互变体（redis-cli GET key、ssh user@host "cmd"、…）
• 原生 GBK 回退：原生命令（cmd 系）写 GBK 字节时按行回退到 GBK 解码，PS 原生路径不受影响（已是 UTF-8）。历史旧数据（编码出问题的）不会被回填
• 超时 / reset 重建：cwd 会恢复，环境变量丢（进程物理属性）
• stderr 与 stdout 不保证交错：stderr 整段尾随，带 [stderr] 前缀
• TUI 仅限终端：opencode 桌面/网页端不加载 @opencode-ai/plugin/tui，面板不可用（工具不受影响）
• 延迟：面板 1s 轮询刚刚发生的执行——历史最多滞后 1 秒

开发

bun install
bun run build          # 产出 dist/index.js（server）+ dist/tui.js（TUI），含 .d.ts
bun run typecheck      # tsc --noEmit
bun test               # 24 个集成测试（真实 powershell.exe）

bun test 用真实 powershell.exe 集成测试，包括编码回退、超时重建、命名会话隔离、inbox 通道、状态文件原子写。调试构建产物可直接看 dist/index.js（单文件无映射）。

License

MIT © 2026 tanghongdong