Zsh Tool

🚀 zsh-tool

zsh-tool 是一款專為 Claude Code 設計的 Zsh 執行工具，具備與 Bash 完全兼容的特性。它採用基於 yield 的監督機制、PTY 模式、NEVERHANG 斷路器以及 A.L.A.N. 短期學習功能，有效解決了使用 Claude Code 時在 zsh 環境下的諸多問題。

🚀 快速開始

如果你使用 zsh，Claude Code 的 Bash 工具會導致引號不匹配和 shell 混亂，每次調試循環都會消耗大量令牌。而 zsh-tool 能立即且永久地消除這些問題。避免一次調試循環，就能節省 30 多秒時間和數百個令牌。

✨ 主要特性

基於 Yield 的執行

命令在運行 yield_after 秒後，如果仍在執行，會返回部分輸出：

• 不再出現命令掛起的情況，你始終能重新獲得控制權。
• 支持增量輸出，可使用 zsh_poll 進行收集。
• 支持交互式輸入，可使用 zsh_send 發送。
• 提供任務管理功能，可使用 zsh_kill 和 zsh_tasks。

PTY 模式

為交互式程序提供完整的偽終端仿真：

# 啟用 pty 模式
zsh(command="pass insert mypass", pty=true)
# 查看提示信息，使用 zsh_send 發送輸入

• 能正確處理交互式提示。
• 支持需要 TTY 的程序。
• 支持彩色輸出和終端轉義序列。
• 實現標準輸入、標準輸出和標準錯誤的完全合併。

NEVERHANG 斷路器

防止掛起的命令阻塞會話：

• 跟蹤每個命令哈希的超時模式。
• 在滾動的 1 小時窗口內出現 3 次超時後，打開斷路器。
• 5 分鐘後自動恢復。
• 狀態包括：CLOSED（正常）→ OPEN（阻塞）→ HALF_OPEN（測試）。

A.L.A.N. 2.0（按需學習系統）

智能短期學習系統：

• 重試檢測：當你重複執行失敗的命令時發出警告。
• 連勝追蹤：慶祝成功連勝，在失敗連勝時發出警告。
• 模糊匹配：例如 git push origin feature-1 可匹配 git push origin *。
• 主動洞察：在你運行命令之前提供上下文反饋。
• 會話記憶：15 分鐘滾動窗口跟蹤最近的活動。
• 時間衰減：指數衰減（半衰期 24 小時），自動清理。
• SSH 智能：將主機連接性與遠程命令成功情況分開記錄。
• 管道段跟蹤：當 cat foo | grep -badopts | sort 失敗時，A.L.A.N. 能知道哪個段失敗。

智能輪詢

zsh_poll 在返回之前執行 2 秒的監聽窗口。如果在 2 秒內有輸出到達，則立即返回。否則，輪詢元數據會告知代理當前的情況：

建議僅作參考，最終決策由代理決定。例如 2 分鐘的 pip install 操作，不會再產生 40 次空往返。

支持終止檢測的 A.L.A.N.

當代理終止命令時，A.L.A.N. 會將其記錄為 KILLED 結果，並對原因進行分類：

終止分類通過比較 kill_elapsed / median_duration 來區分是用戶的不耐煩還是真正的掛起。

manopt — 失敗時顯示手冊頁選項

當命令多次失敗時，A.L.A.N. 會顯示其可用選項：

• 首次失敗：正常反饋，不顯示 manopt。
• 第二次失敗：觸發後臺異步 manopt 查找（超時 2 秒）。
• 第三次及以後失敗：在 A.L.A.N. 洞察中顯示緩存的選項表。

選項從本地手冊頁解析，緩存在 SQLite 中，默認啟用（ALAN_MANOPT_ENABLED=1）。

SSH 跟蹤

A.L.A.N. 對 SSH 命令進行特殊處理，記錄兩個獨立的觀察結果：

退出碼分類：

• 0 — 成功（連接成功且命令執行成功）
• 255 — 連接失敗（SSH 無法連接）
• 1 - 254 — 命令失敗（連接成功，但遠程命令執行失敗）

這意味著當 ssh host3 'git pull' 以退出碼 255 失敗時，A.L.A.N. 知道是主機不可達，而不是 git pull 命令本身有問題。

工具列表

📦 安裝指南

從市場安裝（推薦）

將 ArkTechNWA 市場添加到 Claude Code：

ArkTechNWA/claude-plugins

然後安裝：/plugin install arktechnwa/zsh-tool

插件會在首次運行時自動安裝依賴項。

手動安裝

git clone https://github.com/ArkTechNWA/zsh-tool.git ~/.claude/plugins/zsh-tool

在 ~/.claude/settings.json 中啟用：

{
  "enabledPlugins": {
    "zsh-tool": true
  }
}

捆綁的 scripts/run-mcp.sh 腳本會在首次運行時構建 Rust 二進制文件並啟動 MCP 服務器。

本地開發

對於本地開發/測試，包裝腳本會自動檢測 CLAUDE_PLUGIN_ROOT 是否未展開，並使用計算出的插件根目錄代替，無需更改配置。

或者，創建一個 .mcp.local.json 文件，使用絕對路徑：

{
  "mcpServers": {
    "zsh-tool": {
      "type": "stdio",
      "command": "/path/to/zsh-tool/scripts/run-mcp.sh",
      "env": {
        "NEVERHANG_TIMEOUT_DEFAULT": "120",
        "NEVERHANG_TIMEOUT_MAX": "600"
      }
    }
  }
}

如果未明確提供，ALAN_DB_PATH 將自動設置為 {plugin_root}/data/alan.db。

要求：必須安裝 Rust 工具鏈（cargo）和 zsh。

📚 詳細文檔

架構

zsh-tool/
├── .claude-plugin/
│   ├── plugin.json
│   └── CLAUDE.md
├── .mcp.json
├── zsh-tool-rs/
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs          # CLI 入口點
│       ├── lib.rs           # 模塊導出
│       ├── executor.rs      # 管道/PTY 命令執行
│       ├── config.rs        # 用戶配置 (~/.config/zsh-tool/)
│       ├── circuit.rs       # NEVERHANG 斷路器
│       ├── meta.rs          # 任務元數據 (退出碼, pipestatus)
│       ├── alan/            # A.L.A.N. 2.0 學習引擎
│       │   ├── mod.rs       #   記錄 + 洞察
│       │   ├── hash.rs      #   模糊命令哈希
│       │   ├── insights.rs  #   主動反饋
│       │   ├── manopt.rs    #   手冊頁選項解析
│       │   ├── ssh.rs       #   SSH 主機/命令跟蹤
│       │   ├── streak.rs    #   成功/失敗連勝
│       │   ├── pipeline.rs  #   管道段跟蹤
│       │   ├── prune.rs     #   時間衰減 + 清理
│       │   └── stats.rs     #   數據庫統計信息
│       └── serve/           # MCP JSON-RPC 服務器
│           ├── mod.rs       #   請求分發 + 工具處理程序
│           ├── protocol.rs  #   JSON-RPC 框架
│           └── tools.rs     #   工具模式定義
├── scripts/
│   └── run-mcp.sh           # 構建 + 啟動包裝器
├── data/
│   └── alan.db              # A.L.A.N. SQLite 數據庫
└── README.md

配置

環境變量（在 .mcp.json 中設置）：

• ALAN_DB_PATH — A.L.A.N. 數據庫位置
• NEVERHANG_TIMEOUT_DEFAULT — 默認超時時間（120 秒）
• NEVERHANG_TIMEOUT_MAX — 最大超時時間（600 秒）
• ALAN_MANOPT_ENABLED — 啟用失敗時的手冊頁選項提示（默認：1）
• ALAN_MANOPT_TIMEOUT — 等待 manopt 解析的最大秒數（默認：2.0）
• ALAN_MANOPT_FAIL_TRIGGER — 觸發異步查找的失敗次數（默認：2）
• ALAN_MANOPT_FAIL_PRESENT — 顯示緩存選項的失敗次數（默認：3）

禁用 Bash（可選）

若要僅使用 zsh 作為 shell，可在 ~/.claude/settings.json 中添加：

{
  "permissions": {
    "deny": ["Bash"]
  }
}

變更日誌

0.6.1

協議修復 — 支持 Claude Code v2.1+ 的裸 JSON-RPC

• 修復：MCP 服務器現在能自動檢測裸換行分隔的 JSON（Claude Code v2.1.42+）與 Content-Length 框架。
• 調試日誌：stderr 診斷信息，用於協議協商、請求/響應生命週期和關閉。
• 日誌文件：run-mcp.sh 將 stderr 重定向到 /tmp/zsh-tool-mcp.log，用於 MCP 調試。

0.6.0

完全用 Rust 重寫 — 告別 Python，迎接速度提升

• 用 Rust 完全重寫：MCP 服務器、執行器、A.L.A.N.、NEVERHANG 等全部採用原生實現。
• 79 個 Rust 測試：單元測試 + 完整的 MCP 集成測試（JSON-RPC 往返）。
• CI 管道重寫：cargo test + cargo clippy 取代 pytest + ruff。
• 移除 Python：刪除 7600 多行 Python 代碼，零 Python 依賴。
• CI 速度提升約 2 倍：冷構建從 97 秒降至 48 秒（緩存後），而 Python 版本為 60 - 120 秒。
• 保留所有功能：yield/輪詢/發送/終止、PTY 模式、A.L.A.N. 2.0、NEVERHANG、manopt、SSH 跟蹤、管道段。

0.5.0

A.L.A.N. v2 升級 — 智能輪詢、支持終止檢測、manopt 功能

• 智能輪詢：zsh_poll 中的 2 秒監聽窗口減少了空往返；輪詢元數據包含持續時間估計和自適應建議。
• 支持終止檢測的 A.L.A.N.：新增 KILLED 結果類型並跟蹤執行時間；對過早終止（用戶不耐煩）、過晚終止（真正的掛起）和模式問題（錯誤的方法）進行分類。
• manopt 集成：在命令多次失敗時異步解析手冊頁選項；緩存在 SQLite 中；在同一命令模板第三次及以後失敗時顯示。
• 觀察結果表新增 outcome_type 和 kill_elapsed_ms 列。
• 新增 manopt_cache 表用於持久存儲手冊頁選項。
• 環境變量：ALAN_MANOPT_ENABLED、ALAN_MANOPT_TIMEOUT、ALAN_MANOPT_FAIL_TRIGGER、ALAN_MANOPT_FAIL_PRESENT。

0.4.90

反饋改進 — 更好的信號，更少的噪音

• ALAN 洞察現在分類為信息/警告元組。
• 命令感知：grep 退出碼 1 表示 "無匹配"（信息），退出碼 127 表示 "命令未找到"（警告）。
• 執行後洞察：靜默檢測、管道屏蔽警告、排除 SIGPIPE。
• 元數據行使用 ANSI 顏色（綠色 = 成功，紅色 = 失敗，青色 = 運行中，黃色 = 超時）。
• 根據退出碼顯示 COMPLETED/FAILED 狀態字。
• 原始 pipestatus 列表取代格式化的 [cmd:code] 字符串。
• 分組顯示洞察信息：[info: A.L.A.N.: ...] 和 [warning: A.L.A.N.: ...]。

0.4.83

支持 Python 3.14 — 面向未來的兼容性

• 添加 Python 3.14 分類器和徽章。
• 移除已棄用的 asyncio.DefaultEventLoopPolicy 夾具（計劃在 3.16 中移除）。
• 所有 331 個測試在 Python 3.14.2 上通過。

0.4.81

修復 Pipestatus 標記洩漏問題 — 數據完整性保障

• 修復了 ___ZSH_PIPESTATUS_MARKER___ 可能洩漏到輸出中的競態條件。
• 在 _build_task_response() 中將標記從返回給調用者的結果中移除。
• 防止在執行過程中捕獲輸出時文件內容損壞。
• CI：運行器切換到 Docker 執行器，添加 PEP 668 合規性。

0.4.80

支持每段退出碼 — 精確知道哪個命令失敗

• 退出碼現在顯示為 [cmd1:0,cmd2:1,cmd3:0] 格式，而不是單個整數。
• 每個管道段與其從 zsh $pipestatus 獲得的實際退出狀態配對。
• A.L.A.N. 學習接收到準確的每個命令的結果。
• 輸出具有自解釋性，便於人類和 AI 分析。
• 修復了所有命令無論實際狀態如何都報告 exit=0 的錯誤。

0.4.79

服務器模塊化重構 — 更清晰的架構

• 將 MCP 服務器提取到 zsh_tool/server.py 模塊中。
• 在 zsh_tool/config.py 中集中配置。
• 修復了 plugin.json 版本與包版本的同步問題。

0.4.75

管道智能 — 知道管道的哪個段失敗

• A.L.A.N. 現在捕獲每個管道的 zsh $pipestatus 數組。
• 每個段作為獨立的觀察結果記錄，有自己的退出碼。
• 當 cat foo | grep -badopts | sort 失敗時，你知道是 grep 出了問題。
• 支持引號/轉義的管道解析能正確處理複雜命令。
• 向後兼容：完整的管道仍與段一起記錄。
• 新增 248 行測試用例，覆蓋段跟蹤和邊緣情況。

0.4.6

配置與優化 — 用戶可配置默認值，測試覆蓋率達 91%

• 用戶配置文件 (~/.config/zsh-tool/config.yaml) 用於自定義 yield_after。
• 測試覆蓋率提高：303 個測試，91% 覆蓋率。
• 修復任務清理中的空檢查錯誤。
• 合併並修復徽標文件。

0.4.5

捆綁插件 — 零摩擦的市場安裝

• 自動安裝包裝器 (scripts/run-mcp.sh) 在首次運行時創建虛擬環境。
• 可移植的 .mcp.json 使用 ${CLAUDE_PLUGIN_ROOT}。
• 支持 ArkTechNWA 市場。
• 無需手動執行 pip install。

0.4.0

測試套件與 CI — 290 個測試，89% 覆蓋率

• 全面的測試套件覆蓋所有模塊。
• 包含測試和 lint 階段的 CI 管道。
• 動態管道和覆蓋率徽章。
• 溫和的測試運行器 (run_tests.sh) 在文件之間使用 nice 和 sleep。
• 修復棄用警告和 lint 錯誤。
• 添加 pytest-asyncio 以支持異步測試。

0.3.1

SSH 智能 — 區分主機連接性和遠程命令成功情況

• SSH 命令現在記錄雙重觀察結果（主機 + 遠程命令）。
• 退出碼分類：0 = 成功，255 = 連接失敗，1 - 254 = 命令失敗。
• 新增 ssh_observations 表用於 SSH 特定跟蹤。
• get_ssh_host_stats() — 每臺主機的連接/命令成功率。
• get_ssh_command_stats() — 所有主機上每個命令的統計信息。
• SSH 特定洞察：不穩定的主機、可靠的主機、失敗的命令。
• 新增 31 個 SSH 跟蹤測試用例。

0.3.0

A.L.A.N. 2.0 — “也許你搞砸了，也許你做對了。”

• 重試檢測：當重複執行失敗的命令時發出警告。
• 連勝追蹤：慶祝成功，在失敗時發出警告。
• 模糊模板匹配：將類似的命令分組。
• 主動洞察：在執行前提供上下文反饋。
• 會話記憶：15 分鐘滾動窗口。
• 新增數據庫表：recent_commands、streaks。

0.2.0

• 基於 yield 的執行，即時監督。
• 支持 PTY 模式，實現完整的終端仿真。
• 通過 zsh_send 支持交互式輸入。
• 任務管理：zsh_poll、zsh_kill、zsh_tasks。
• 修復了子進程使用 PIPE 時標準輸入阻塞的問題。

0.1.0

• 初始版本發佈。
• 包含 NEVERHANG 斷路器。
• 具備 A.L.A.N. 學習數據庫。

📄 許可證

本項目採用 MIT 許可證，詳情請見 LICENSE。