Zsh Tool

zsh工具

  

用于Claude Code的Zsh执行工具，具有完整的Bash奇偶校验、基于产量的监督、PTY模式、NEVERHANG断路器和A.L.A.N.短期学习。

状态： 贝塔系数（v0.7.2）

作者 克劳德+梅尔德雷

许可证： 麻省理工学院

组织机构： ArkTechNWA

______________________________________________________________________

*对可靠性的执着关注。*

______________________________________________________________________

为什么？

#1原因： 如果你使用zsh，Claude Code的Bash工具会导致引号不匹配和shell混淆。每个调试循环都需要消耗令牌。zsh工具立即永久消除了这种情况。

令牌数学： 避免了一次调试螺旋=节省了30多秒，保留了数百个令牌。

zsh工具是 智能shell执行:

这就是“运行命令”和“智能shell集成”之间的区别

______________________________________________________________________

特性

基于收益的执行

命令返回后 yield_after 如果仍在运行，则显示部分输出的秒数：

• 不再悬挂 --你总是能重新获得控制权
• 增量输出 --收集与 zsh_poll
• 交互式输入 --发送与 zsh_send
• 任务管理 — zsh_kill 和 zsh_tasks

PTY模式

交互式程序的完整伪终端仿真：

# Enable with pty: true
zsh(command="pass insert mypass", pty=true)
# See prompts, send input with zsh_send

• 正确处理交互式提示
• 需要TTY的程序
• 颜色输出和端子转义序列
• 完整的stdin/stdout/stderr合并

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.知道失败了 *哪个* 分段失败

带行号的增量输出（v0.6.3）

zsh_poll 仅返回 自上次投票以来的新输出，前缀为全局行号。不再每次投票都会丢弃800条线路。

801: Installing package foo...
802: Compiling module bar...
803: Done.

第一次轮询返回第1行的所有输出。后续的轮询从上次停止的地方继续。完成的任务返回最终的增量，然后在重新轮询时为空。

智能投票

zsh_poll 执行a 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 后台查找（超时2秒）
• 第三次+失败 --在A.L.A.N.insight中显示缓存的选项表

从本地手册页解析。缓存在SQLite中。默认情况下打开(ALAN_MANOPT_ENABLED=1).

SSH跟踪

A.L.A.N.专门处理SSH命令，记录了两个单独的观察结果：

出口代码分类：

• 0 --成功（连接AND命令成功）
• 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 如果没有明确提供。

要求： 防锈工具链(cargo)以及 zsh 必须安装。

______________________________________________________________________

建筑

zsh-tool/
├── .claude-plugin/
│   ├── plugin.json
│   └── CLAUDE.md
├── .mcp.json
├── zsh-tool-rs/
│   ├── Cargo.toml
│   └── src/
│       ├── main.rs          # CLI entry point
│       ├── lib.rs           # Module exports
│       ├── executor.rs      # Pipe/PTY command execution
│       ├── config.rs        # User config (~/.config/zsh-tool/)
│       ├── circuit.rs       # NEVERHANG circuit breaker
│       ├── meta.rs          # Task metadata (exit code, pipestatus)
│       ├── alan/            # A.L.A.N. 2.0 learning engine
│       │   ├── mod.rs       #   Recording + insights
│       │   ├── hash.rs      #   Fuzzy command hashing
│       │   ├── insights.rs  #   Proactive feedback
│       │   ├── manopt.rs    #   Man-page option parsing
│       │   ├── ssh.rs       #   SSH host/command tracking
│       │   ├── streak.rs    #   Success/failure streaks
│       │   ├── pipeline.rs  #   Pipeline segment tracking
│       │   ├── prune.rs     #   Temporal decay + pruning
│       │   └── stats.rs     #   Database statistics
│       └── serve/           # MCP JSON-RPC server
│           ├── mod.rs       #   Request dispatch + tool handlers
│           ├── format.rs    #   Rich output formatting
│           ├── protocol.rs  #   JSON-RPC framing
│           └── tools.rs     #   Tool schema definitions
├── scripts/
│   └── run-mcp.sh           # Build + launch wrapper
├── data/
│   └── alan.db              # A.L.A.N. SQLite database
└── 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.7.2

用户可见输出 — *告诉模型展示它的工作*

• 修复： 在Claude Code中，用户无法看到MCP工具的结果（平台限制）。工具描述现在指示模型在其响应文本中逐字传递命令输出。
• 这是Claude Code不向用户呈现MCP工具结果块的一种解决方法。

0.7.1

陈旧的二进制修复 — *实际交付新格式*

• 修复： run-mcp.sh 现在运行 cargo clean -p 在源代码更改时进行重建之前，防止Cargo的增量构建提供过时的二进制文件
• 修复： 重建触发器现在也在关注 Cargo.toml （旧版本的凸起是看不见的 find -newer 检查）

0.7.0

丰富的输出格式 — *不再有JSON转储*

• 结构化输出 --命令头、分隔部分、带图标的状态页脚
• 视觉状态图标 — ✔ / ✘ 替换 [COMPLETED / [FAILED 括号
• 进度巩固 --连续的进度线（例如。， 10%, 20%, 30%)折叠后仅显示最新版本，防止下载/构建过程中出现屏幕垃圾邮件
• 命令回显 — $ command header显示运行的内容，截断为120个字符
• 彩色出口代码 --绿色=0，红色=非零，黄色=信号（129+）
• 更丰富的通知 --后台任务完成使用 ┌ notify: 带有故障着色
• ALAN洞察图标 — ⚠ 对于警告， ℹ 供参考
• 新 format.rs 模块 --从mod.rs中提取的所有格式转换为独立的、可测试的模块
• 35项新测试 （共121个）涵盖所有格式化功能

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

完全锈蚀重写 — *再见Python，你好速度*

• 用Rust完全重写 --MCP服务器、执行器、A.L.A.N.、NEVERHANG、所有本地
• 79锈蚀试验 --单元测试+完整的MCP集成测试（JSON-RPC往返）
• CI管道已重写 — cargo test + cargo clippy 替换pytest+ruff
• Python已删除 --7600多行Python被删除，零Python依赖
• CI速度提高约2倍 --冷造97s→ 缓存48秒（与Python的60-120秒相比）
• 保留所有功能：yield/poll/send/kill、PTY模式、A.L.A.N.2.0、NEVERHANG、manopt、SSH跟踪、管道段

0.5.0

A.L.A.N.v2升级 — *智能投票、杀戮意识、操纵*

• 智能轮询：2s监听窗口 zsh_poll 减少空车往返；具有持续时间估计和自适应建议的民意调查元数据
• 有杀戮意识的A.L.A.N。: KILLED 带有经过跟踪的结果类型；对早期杀死（不耐烦）、晚期杀死（真正的挂起）和模式问题（错误的方法）进行分类
• manopt集成：在重复命令失败时异步分析手册页选项；缓存在SQLite中；同一命令模板在第三次以上失败时出现
• 新 outcome_type 和 kill_elapsed_ms 观察专栏
• 新 manopt_cache 持久手册页选项存储表
• ENV变体： ALAN_MANOPT_ENABLED, ALAN_MANOPT_TIMEOUT, ALAN_MANOPT_FAIL_TRIGGER, ALAN_MANOPT_FAIL_PRESENT

0.4.90

反馈改进 — *更好的信号，更少的噪音*

• ALAN见解现在被归类为信息/警告元组
• 命令感知：grep退出1=“不匹配”（信息），退出127=“找不到命令”（警告）
• 执行后洞察：静默检测、管道屏蔽警告、SIGPIPE排除
• 元数据行上的ANSI颜色（绿色=成功，红色=失败，青色=正在运行，黄色=超时）
• 基于退出代码的完成/失败状态字
• 原始管道清单替换格式化 [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

管道状态标记泄漏修复 — *数据完整性*

• 固定比赛条件 ___ZSH_PIPESTATUS_MARKER___ 可能泄漏到输出中
• 标记现在已剥离 _build_task_response() 在返回给来电者之前
• 防止在执行过程中捕获输出时损坏文件内容
• CI:Runner切换为docker executor，添加了PEP 668合规性

0.4.80

每段退出代码 — *确切地知道哪个命令失败了*

• 现在显示退出代码 [cmd1:0,cmd2:1,cmd3:0] 格式而不是单个整数
• 每个管道段与其从zsh的实际出口状态配对 $pipestatus
• A.L.A.N.学习获得准确的每个命令结果
• 用于人类和人工智能分析的自记录输出
• 修复了所有命令都报告的错误 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 失败，你知道的 *全局正则表达式打印* 是问题所在吗
• 支持引用/转义的管道解析可以正确处理复杂的命令
• 向后兼容：完整管道仍与分段一起记录
• 248条新测试线，涵盖分段跟踪和边缘情况

0.4.6

配置和波兰语 — *用户可配置默认值，覆盖率91%*

• 用户配置文件(~/.config/zsh-tool/config.yaml)对于自定义yield_after
• 测试覆盖率提高：303次测试，覆盖率91%
• 修复了任务清理中的空检查错误
• 整合并修复徽标文件

0.4.5

捆绑插件 — *零摩擦市场安装*

• 自动安装包装器(scripts/run-mcp.sh)首次运行时创建venv
• 便携的 .mcp.json 使用 ${CLAUDE_PLUGIN_ROOT}
• ArkTechNWA市场支持
• 无需手动安装pip

0.4.0

测试套件和CI — *290次测试，覆盖率89%*

• 涵盖所有模块的全面测试套件
• 带测试和棉绒阶段的CI管道
• 动态管道和覆盖徽章
• 温和的测试跑步者(run_tests.sh)在文件之间睡个好觉
• 修复了弃用警告和lint错误
• 添加了pytest-asyncio以支持异步测试

0.3.1

SSH智能 — *将主机连接与远程命令成功分离*

• SSH命令现在记录双重观察（主机+远程命令）
• 退出代码分类：0=成功，255=连接失败，1-254=命令失败
• 新 ssh_observations SSH特定跟踪表
• get_ssh_host_stats() --每台主机连接/命令成功率
• get_ssh_command_stats() --所有主机上的每个命令统计数据
• SSH特定见解：不稳定的主机、可靠的主机、失败的命令
• SSH跟踪的31个新测试

0.3.0

A.L.A.N.2.0 — *“也许你搞砸了，也许你做得对。”*

• 重试检测：重复失败命令时发出警告
• 条纹追踪：庆祝成功，警告失败
• 模糊模板匹配：相似命令分组
• 主动洞察：执行前的情境反馈
• 会话记忆：15分钟滚动窗口
• 新数据库表： recent_commands, streaks

0.2.0

• 基于收益的执行，实时监督
• PTY模式用于全终端仿真
• 通过以下方式提供交互式输入支持 zsh_send
• 任务管理： zsh_poll, zsh_kill, zsh_tasks
• 修复了子进程的stdin阻塞问题。管道

0.1.0

• 初始版本
• 切勿挂断断路器
• A.L.A.N.学习数据库

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证 了解详情。

______________________________________________________________________

For Johnny5. For us.

ArkTechNWA