modiqo/cliare

What it solves

CLIARE（CLI Agent Readiness Evaluation）解决了“CLI 漂移”问题，即命令行界面的实际运行行为与文档或帮助文本不一致。这种漂移会导致 AI 代理通过反复试错猜测命令和标志而浪费 token 和延迟。它还帮助安全审查员识别未文档化的副作用（如在看似安全的发现命令中意外写文件）。

How it works

CLIARE 将 CLI 二进制视为黑盒，在受限的控制下对其进行探测。它不依赖静态文档，而是在各种上下文（干净、已认证或基于 fixture）中运行二进制，记录实际存在的命令、哪些标志是安全的，以及输出是否可机器解析（JSON/YAML）。随后生成命令索引和一套报告（评分卡、问题账本和角色专属包），映射出 CLI 的真实表面。

Who it’s for

• CLI Maintainers：识别帮助覆盖、诊断信息和输出契约的缺口，使其工具更适合代理使用。
• Security Reviewers：在将二进制暴露给自主代理之前，检测未文档化的运行时行为和持久副作用。
• Agent Harness Builders：获取有证据支持的命令索引，使代理能够直接路由到正确的命令，而无需通过试错重新发现语法。

Highlights

• Evidence-Based Mapping：基于运行时证据生成 command-index.json，而非手写文档。
• Black-Box Probing：在隔离或特定主机环境中测量二进制，以检测副作用。
• Agent-Ready Artifacts：生成 AGENT_SKILL.md 和角色报告，指导代理行为。
• Surface Querying：提供工具让 harness 查询意图到命令的路由答案。
• CI Integration：包含 GitHub Action，自动化就绪审计并创建发布门槛。