agent-zw 中文说明

agent-zw 是一个跨平台 AI Agent 稳定性增强工具包，主要解决 OpenCode、Claude Code、Codex CLI 等 Agent 在执行长命令时的卡死、假死、超大输出撑爆上下文等问题。

核心命令是：

agent-run <超时秒数> <命令> [参数...]

例如：

agent-run 120 npm install
agent-run 300 cargo build --release
agent-run 180 pytest tests/
agent-run 60 python train.py

为什么需要它

AI 编程 Agent 经常会遇到这些问题：

1. npm install、pip install、cargo build 等命令长时间不返回，Agent 卡住。
2. 测试或构建输出太大，撑爆上下文窗口。
3. macOS / Linux / Windows 的 shell 行为不同，Agent 很容易误用交互式命令。
4. OpenCode、Claude Code、Codex CLI 本身都没有统一的命令超时层。

agent-zw 提供一个很薄的外挂式保护层，不改任何 Agent 内核，只在命令执行层加保护。

安装

npm install -g agent-zw

要求：

• Node.js >= 18
• 支持 macOS / Linux / Windows

安装后会提供：

agent-run

macOS / Linux 上还会尝试安装兼容命令：

opencode-run

快速开始

包安装

agent-run 120 npm install
agent-run 120 pip install -r requirements.txt
agent-run 120 pnpm install

编译构建

agent-run 300 cargo build --release
agent-run 300 go build ./...
agent-run 300 npm run build

测试

agent-run 180 pytest
agent-run 180 npm test
agent-run 180 cargo test

普通脚本

agent-run 60 python script.py

超时建议

| 命令类型 | 建议超时 | 示例 | |---|---:|---| | 包安装 | 120 秒 | agent-run 120 npm install | | 编译构建 | 300 秒 | agent-run 300 cargo build | | 测试套件 | 180 秒 | agent-run 180 pytest | | 普通命令 | 60 秒 | agent-run 60 python script.py |

输出截断

默认最大输出：102400 字节。

如果命令输出超过限制，agent-run 会自动截断，避免 Agent 上下文被大日志撑爆。

你可以通过环境变量调整：

export AGENT_MAX_OUTPUT_BYTES=204800

各系统行为

macOS / Linux

安装时会把 agent-run 安装到：

~/.local/bin/agent-run

如果可能，还会创建：

~/.local/bin/opencode-run

如命令不可用，把 ~/.local/bin 加入 PATH：

export PATH="$HOME/.local/bin:$PATH"

Windows

安装时会准备 Windows 版脚本：

%LOCALAPPDATA%\agent-zw\bin\agent-run.ps1
%LOCALAPPDATA%\agent-zw\bin\agent-run.cmd

如果 agent-run 不在 PATH 中，添加用户 PATH：

[Environment]::SetEnvironmentVariable('Path', $env:Path + ';' + $env:LOCALAPPDATA + '\agent-zw\bin', 'User')

然后重启终端。

Agent 集成

OpenCode

OpenCode 里执行长命令时使用：

agent-run 120 npm install

或兼容旧名：

opencode-run 120 npm install

Claude Code

建议在 CLAUDE.md 中加入：

执行长时间命令时，必须使用 agent-run：
agent-run 120 npm install
agent-run 300 cargo build

Codex CLI

建议在 ~/.codex/setup.md 中加入：

所有可能长时间运行的命令都使用 agent-run 包装。

常见问题

1. agent-run: command not found

macOS / Linux：

export PATH="$HOME/.local/bin:$PATH"

Windows：

$env:Path += ';' + $env:LOCALAPPDATA + '\agent-zw\bin'

2. 命令被超时杀掉了怎么办？

说明命令超过了你设置的时间。可以：

agent-run 300 npm install

或者先检查网络、依赖源、构建步骤是否卡住。

3. 输出被截断了怎么办？

使用分页或过滤：

agent-run 60 npm test | tail -100
agent-run 60 cat build.log | head -200

4. npm 发布需要 OTP 怎么办？

维护者发布新版本时，如果 npm 要求二步验证：

npm publish --otp=123456

把 123456 换成认证器里的 6 位验证码。

限制

• agent-zw 不修改 OpenCode、Claude Code、Codex CLI 的内部逻辑。
• npm 安装不会自动执行 sudo / 管理员级系统调优。
• Windows Service / launchd / watchdog 属于高级能力，需要单独安装脚本支持。

许可证

MIT