Camil-H/cli-agent-lint

# cli-agent-lint 审计 CLI 工具的 AI 代理就绪性。在 5 个类别中运行 34 项检查，并生成一个字母等级评分卡，告诉你 CLI 与自主代理的配合程度。 ## 演示 **Google Workspace CLI**  **GitHub CLI**  ## 安装 **Homebrew**（macOS） ``` brew install Camil-H/tap/cli-agent-lint ``` **Debian / Ubuntu**（来自 GitHub Releases 的 .deb 包） ``` curl -LO https://github.com/Camil-H/cli-agent-lint/releases/latest/download/cli-agent-lint_linux_amd64.deb sudo dpkg -i cli-agent-lint_linux_amd64.deb ``` **Go** ``` go install github.com/Camil-H/cli-agent-lint@latest ``` **二进制文件** — 从 [GitHub Releases](https://github.com/Camil-H/cli-agent-lint/releases) 下载。 ## 快速开始 ``` # 审核 CLI 工具 cli-agent-lint check ./my-tool # JSON 输出 cli-agent-lint check --output json ./my-tool # 仅被动模式 — 解析帮助文本，不执行目标 cli-agent-lint check --no-probe ./my-tool # 列出所有检查 cli-agent-lint checks # 描述特定检查 cli-agent-lint checks TE-1 ``` ## 检查内容 每一项检查都针对 AI 代理以非交互方式驱动 CLI 时所关心的特定属性。检查分为五个类别，分别对应实践中代理可能遇到的不同失败模式。 | 类别 | ID | 摘要 | 重要性 | |---|---|---|---| | **流程安全** | `FS-*` | 这会阻塞我的代理吗？ | 如果代理卡在交互式提示、无法认证或无法区分成功与失败，就会成为“死”代理。这些检查确保你的 CLI 不会阻塞自主循环——无 TTY 提示、非交互式认证路径、清晰的 stderr/stdout 分离，以及可靠的退出码。 | | **令牌效率** | `TE-*` | 这会耗尽我的上下文窗口吗？ | CLI 输出的每一字节都会占用代理的上下文窗口。冗长的输出会迅速填满窗口，降低代理遵循指令和理解结果的能力。这些检查确保你的 CLI 支持 JSON 输出、`--quiet`/`--no-color` 模式、分页列表命令以及字段过滤——让代理获得信号而非噪声。 | | **自描述性** | `SD-*` | 我的代理能仅从 `--help` 学习这个 CLI 吗？ | 代理通过阅读 `--help` 来学习 CLI。如果帮助文本缺少示例、错误信息晦涩难懂，或无法发现命令模式，代理就会退回到试错——浪费令牌并中断流程。这些检查确保你的 CLI 在第一次尝试时就教会代理如何正确使用它。 | | **自动化安全** | `SA-*` | 我的代理能安全地使用这个 CLI 而不造成破坏吗？ | 代理会重试失败命令、传递不可信输入，且无法阅读“确定吗？”类提示。这些检查确保你的 CLI 在破坏性命令上提供 `--yes`/`--force` 标志，拒绝路径遍历和控制字符，并支持 `--dry-run` 以便代理在提交前预览。 | | **可预测性** | `PV-*` | 我的代理能信任输出吗？ | 无法信任工具输出的代理会对每一步都产生怀疑。这些检查确保你的 CLI 产生确定性输出、为不同错误类别记录明确的退出码、支持 `--timeout` 以实现有时间限制的执行，并暴露重试/速率限制信息。 | ### 检查方法 - **被动** — 仅分析 `--help` 文本；始终安全，零副作用。 - **主动** — 使用精心构造的输入执行目标 CLI。可以通过 `--no-probe` 禁用。 ### 安全提示 主动检查会以子进程方式执行目标 CLI。该工具会清理敏感环境变量并实施资源限制，但目标 CLI 仍可能发起网络请求、读取本地文件或在探测时表现不同。**在审计不可信 CLI 时请使用 `--no-probe`。如需完全隔离，请在容器中运行。** ## 评分 | 等级 | 分数 | 含义 | |:---:|:---:|---| | **A** | ≥ 90% | 代理就绪 | | **B** | ≥ 70% | 基本可用，存在部分差距 | | **C** | ≥ 50% | 存在显著差距 | | **D** | ≥ 30% | 需要大量工作 | | **F** | < 30% | 不适合代理 | ## 参数 | 参数 | 描述 | 默认值 | |---|---|---| | `--output, -o` | 输出格式：`text`、`json` | `text` | | `--no-color` | 禁用彩色输出 | | | `--quiet, -q` | 抑制信息输出 | | | `--no-probe` | 仅执行被动检查 | | | `--severity` | 最低严重级别：`info`、`warn`、`fail` | `info` | | `--category` | 仅运行某一类别的检查 | | | `--skip` | 跳过特定检查 ID（可重复） | | | `--timeout` | 探测命令超时时间 | `5s` | ## 退出码 | 代码 | 含义 | |:---:|---| | `0` | 所有检查通过 | | `1` | 存在一个或多个失败的严重性检查 | | `2` | 使用错误或运行时错误 | ## 从源码构建 ``` go build -o cli-agent-lint . go test ./... go vet ./... ``` ## 许可证 MIT — 参见 [LICENSE](LICENSE)。

标签：Agent 友好, AI 代理, AI 工具链, CLI, CLI 工具, Debian Ubuntu, EVTX分析, GitHub Releases, Go 安装, Homebrew 安装, JSON 输出, LLM 工具, SEO: AI agent CLI, SEO: automated CLI checks, SEO: cli-agent-lint, SEO: CLI readiness, WiFi技术, 上下文窗口, 二进制发布, 二进制发布, 交互式阻塞, 令牌效率, 威胁情报, 对称加密, 工具审计, 帮助文本解析, 开发者工具, 开源工具, 开源工具, 无 TTY 提示, 日志审计, 标准输出分离, 标准错误分离, 流控安全, 自动化审计, 自动化检查, 被动模式, 退出码可靠性, 非交互式认证