mcpField
C
cli-for-agents

cli-for-agents

github.com/poteto开发13252 次安装21 周前更新
代码仓库

关于 cli-for-agents

用于设计或审查可由 Agent 非交互操作的命令行界面的技能，侧重命令易发现、输入可组合及输出便于机器处理。

主要功能

  1. 01基于标志的非交互操作
  2. 02分层命令帮助与示例
  3. 03支持标准输入和管道
  4. 04可操作的错误与幂等性
  5. 05试运行与跳过确认
  6. 06一致的命令结构和实用输出

适用场景

  1. 01设计供 Agent 使用的命令行工具
  2. 02审查现有命令行为
  3. 03让脚本组合多个命令
  4. 04支持预览有破坏性的操作

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/poteto/plugins --skill cli-for-agents

安装后在 Claude Code 中输入/cli-for-agents确认已加载。

详细介绍

面向 Agent 的 CLI

面向人类的 CLI 往往会阻碍 Agent：交互式提示、冗长的前置文档，以及没有可复制粘贴示例的帮助文本。优先采用适用于无头环境且可在管道中组合的模式。

优先采用非交互模式

  • 每项输入都应能通过标志或标志值传入。不要要求使用方向键、菜单或限时提示。
  • 如果缺少标志，再回退到交互模式，而不是反过来。

不佳： mycli deploy → ? Which environment? (use arrow keys)
良好： mycli deploy --env staging

提高可发现性，避免倾倒上下文

  • Agent 会逐步发现子命令：mycli，然后是 mycli deploy --help。不要每次运行都输出整本手册。
  • 让每个子命令各自管理文档，避免未使用的命令占用上下文。

让 --help 真正实用

  • 每个子命令都应支持 --help。
  • 每个 --help 都应包含示例，并提供真实的调用方式。与文字说明相比，示例更有助于匹配模式。
Options:
  --env     Target environment (staging, production)
  --tag     Image tag (default: latest)
  --force   Skip confirmation

Examples:
  mycli deploy --env staging
  mycli deploy --env production --tag v1.2.3
  mycli deploy --env staging --force

标准输入、标志和管道

  • 在适用的情况下接受标准输入（例如 cat config.json | mycli config import --stdin）。
  • 避免不合理的位置参数顺序，也不要在缺少值时回退到交互式提示。
  • 支持命令串联：mycli deploy --env staging --tag $(mycli build --output tag-only)。

快速失败并提供可执行的错误提示

  • 缺少必需标志时，应立即退出并显示清晰的消息和正确的调用示例，而不是卡住。
Error: No image tag specified.
  mycli deploy --env staging --tag <image-tag>
  Available tags: mycli build list --output tags

幂等性

  • Agent 经常重试。同一条成功的命令重复运行时应安全（无操作，或明确提示“已完成”），而不应重复产生副作用。

破坏性操作

  • 添加 --dry-run（或等效选项），让 Agent 在提交前预览计划。
  • 提供 --yes / --force 以跳过确认，同时为人类用户保留安全的默认行为。

结构可预测

  • 全程采用一致的模式，例如 resource + verb：如果存在 mycli service list，那么 mycli deploy list 和 mycli config list 也应遵循相同的形式。

成功输出

  • 成功时返回便于机器使用的数据：ID、URL、时长。纯文本即可；不要只依赖装饰性输出。
deployed v1.2.3 to staging
url: https://staging.myapp.com
deploy_id: dep_abc123
duration: 34s

审查现有 CLI 时

  • 检查：非交互路径、分层帮助、--help 中的示例、标准输入／管道支持、包含调用示例的错误消息、幂等性、试运行、跳过确认的标志、一致的命令结构，以及结构化的成功输出。

评论

支持 Markdown