cli-creator

CLI 创建器

创建一个真正的 CLI，让后续的 Codex 会话能在任意工作目录中通过命令名称运行它。

此技能适用于持久工具，而非一次性脚本。如果在当前仓库中写个短脚本就能解决任务，请改为直接在那里编写脚本。

开始

说明目标工具、其来源，以及它应完成的首批实际任务：

• 来源：API 文档、OpenAPI JSON、SDK 文档、curl 示例、浏览器应用、现有内部脚本、文章或可用的 Shell 历史记录。
• 任务：明确的读取或写入操作，例如 列出草稿、下载失败作业的日志、搜索消息、上传媒体、读取队列计划。
• 安装名称：简短的二进制名称，例如 ci-logs、slack-cli、sentry-cli 或 buildkite-logs。

如果用户想要个人工具且未指定仓库，优先在 ~/code/clis/<tool-name> 下新建文件夹。

开始搭建前，检查拟定的命令是否已存在：

command -v <tool-name> || true

如果已存在，请选一个更清晰的安装名称，或询问用户。

选择运行时

选择之前，检查用户的机器和源材料：

command -v cargo rustc node pnpm npm python3 uv || true

然后选择最不令人意外的工具链：

• 对于 Codex 应能在任何仓库中运行的持久 CLI，默认使用 Rust：它能生成一个快速的二进制文件，参数解析能力强，JSON 处理良好，也易于复制或安装到 ~/.local/bin。
• 当官方 SDK、身份验证辅助工具、浏览器自动化库或现有仓库工具能让 CLI 更实用时，使用 TypeScript/Node。
• 当来源涉及数据科学、本地文件转换、笔记本、SQLite/CSV/JSON 分析，或仍可安装为持久命令的 Python 密集型管理工具时，使用 Python。

除非能显著改进 CLI，否则不要选择会增加配置负担的语言。如果未安装最佳选择所需的语言，要么征得用户同意后安装缺失的工具链，要么选择次优且已安装的选项。

开始搭建前，用一句话说明选择及其原因，并说明你发现已安装的工具链。

命令约定

编码前，先在聊天中勾勒命令界面。包括二进制名称、发现命令、解析或 ID 查询命令、读取命令、写入命令、原始接口、身份验证/配置选择，以及 PATH/安装命令。

设计命令界面时，请阅读 references/agent-cli-patterns.md，了解预期的可组合 CLI 形式。

围绕以下命令界面进行构建：

• tool-name --help 显示所有主要功能。
• tool-name --json doctor 验证配置、身份验证、版本、端点可达性及缺失的设置。
• tool-name init ... 在仅用环境变量进行身份验证不便时，保存本地配置。
• 发现命令用于查找账户、项目、工作区、团队、队列、频道、仓库、仪表板或其他顶层容器。
• 解析命令将名称、URL、slug、永久链接、客户输入或构建链接转换为稳定 ID，避免后续命令重复进行广泛搜索。
• 读取命令用于获取精确对象以及列出/搜索集合。分页列表应支持有界的 --limit、游标、偏移量，或明确记录的默认值。
• 写入命令每个只执行一种明确操作：创建、更新、删除、上传、安排、重试、评论、起草。它们接受最精确且稳定的资源 ID；在服务允许时，应优先支持 --dry-run、draft 或 preview，并且不得将写入操作隐藏在 fix、debug 或 auto 等宽泛命令中。
• --json 返回稳定的机器可读输出。
• 提供原始接口：request、tool-call、api 或最贴切且准确的名称。

不要只提供通用的 request 命令。应提供高层动词，让 Codex 能执行重复性任务。

在 CLI README 或同等文档中说明 JSON 规范：API 透传还是 CLI 封装、成功响应格式、错误响应格式，以及每类命令各一个示例。在 --json 模式下，错误必须为机器可读格式，且不得包含凭据。

身份验证与配置

优先支持常规路径，并按以下顺序处理：

1. 使用服务标准名称的环境变量，例如 GITHUB_TOKEN。
2. 用户配置文件，位于 ~/.<tool-name>/config.toml 或其他简单且有文档说明的路径。
3. 仅在明确进行一次性测试时使用 --api-key 或工具专用的令牌标志。日常使用优先选择环境变量或配置文件，因为标志可能泄露到 Shell 历史记录或进程列表中。

绝不输出完整令牌。doctor --json 应说明令牌是否可用、身份验证来源类别（flag、env、config、provider default 或 missing），以及缺少哪项设置步骤。

如果 CLI 无需网络或身份验证也能运行，应在 doctor --json 中明确说明：报告是否处于 fixture/offline 模式、是否找到了 fixture 数据，以及该模式是否不需要身份验证。

对于通过 DevTools 的 curl 获取信息的内部 Web 应用，请在实现前创建经过脱敏的端点说明：资源名称、方法/路径、必需的请求头、身份验证机制、CSRF 行为、请求正文、响应 ID 字段、分页方式、错误以及一份经过脱敏的响应示例。绝不要提交复制来的 Cookie、Bearer 令牌、客户机密信息或完整的生产环境载荷。

使用截图推断工作流、UI 术语、字段和确认步骤。除非截图附有网络请求、导出文件、文档页面或 fixture，否则不要将截图视为 API 证据。

构建工作流

1. 阅读源信息，仅需了解资源、身份验证、分页、ID、媒体/文件流程、速率限制和危险的写入操作。如果文档提供 OpenAPI，请先下载或检查，再命名命令。
2. 在聊天中列出命令清单。名称应简短且便于在 Shell 中使用。
3. 为 CLI 搭建脚手架，并提供 README 或等效的仓库说明文档。
4. 实现 doctor、发现、解析、读取命令，以及用户要求时的一条范围有限的草稿或 dry-run 写入路径，并提供原始操作逃生口。
5. 将 CLI 安装到 PATH 中，确保无需进入源文件夹即可运行 tool-name ...。
6. 在其他仓库或 /tmp 中进行冒烟测试，而不只是运行 cargo run 或包管理器包装命令。运行 command -v <tool-name>、<tool-name> --help 和 <tool-name> --json doctor。
7. 运行格式检查、类型检查/构建、请求构造器的单元测试、分页/请求正文构造器的测试、无身份验证情况下的 doctor 测试、帮助输出测试，以及至少一次 fixture、dry-run 或实时只读 API 调用。

如果为了验证而需要进行实时写入，请先询问，并确保操作可撤销或仅创建草稿。

如果源信息来自现有脚本或 Shell 历史记录，请将可用的调用拆分为实际阶段：设置、发现、下载/导出、转换/索引、草拟、上传、轮询、实时写入。保留用户已经依赖的标志、路径和环境变量，然后为可重复的阶段添加稳定 ID、有界 JSON 和文件输出。

对于原始操作逃生口，优先支持只读调用。除非用户明确要求执行特定写入操作，否则不要对实时服务运行原始的非 GET/HEAD 请求。

对于媒体、制品或预签名上传流程，请分别测试每个阶段：创建上传、传输字节、轮询/读取处理状态，然后附加或引用生成的 ID。

对于由 fixture 支持的原型，请将 fixture 放在可预测的项目路径中，并确保 CLI 安装后仍能找到它们。从 /tmp 执行冒烟测试，以发现只能在源文件夹内运行的二进制文件。

对于面向日志的 CLI，请将确定性的片段提取与模型解读分开。优先使用可输出文件名、行号或字节范围、匹配规则及简短摘录的命令。

Rust 默认项

使用 Rust 构建时，请使用成熟的 crate，而不是自定义解析器：

• 命令和帮助信息使用 clap
• HTTP 使用 reqwest
• 载荷使用 serde / serde_json
• 小型配置文件使用 toml
• CLI 风格的错误上下文使用 anyhow

添加类似 make install-local 的 Makefile 目标，用于构建 release 并将二进制文件安装到 ~/.local/bin。

TypeScript/Node 默认设置

使用 TypeScript/Node 构建时，请确保 CLI 可以像普通命令一样安装：

• 使用 commander 或 cac 处理命令和帮助信息
• 使用原生 fetch、官方 SDK 或用户现有的 HTTP 辅助工具调用 API
• 仅在外部载荷验证确实能避免故障时使用 zod
• 在 package.json 中为已安装的命令配置 bin 条目
• 使用仓库现有约定中的 tsup、tsx 或 tsc

添加安装流程，例如 pnpm install、pnpm build 和 pnpm link --global，或者添加一个 Makefile 目标，将小型包装脚本安装到 ~/.local/bin。

Python 默认设置

使用 Python 构建时，除非工作流有更多需求，否则优先使用朴素的标准库组件：

• 使用 argparse 处理命令和帮助信息；如果子命令会变得杂乱，则使用 typer
• 使用 urllib.request / urllib.parse、requests 或 httpx 处理 HTTP，并与附近已安装或已使用的工具保持一致
• 使用 json、csv、sqlite3、pathlib 和 subprocess 处理本地文件、导出、数据库和现有脚本
• 使用 pyproject.toml 控制台脚本，或使用小型可执行包装脚本来安装命令
• 仅在确实需要依赖时使用 uv 或虚拟环境

添加一个 Makefile 目标，例如 make install-local，用于将命令安装到 PATH，并说明它依赖 uv、虚拟环境，还是仅依赖系统 Python。

配套技能

CLI 可用后，为其创建或更新一个小型技能。如果可以使用 $skill-creator，请使用它。除非用户指定仓库本地的 .codex/skills/... 路径或其他技能仓库，否则个人配套技能请放在 $CODEX_HOME/skills/<tool-name>/SKILL.md。

编写配套技能时，请按未来的 Codex 线程使用 CLI 的顺序组织内容，而不是逐一介绍所有功能。说明：

• 如何验证已安装的命令是否存在。
• 首先应运行哪个命令。
• 如何配置身份验证。
• 哪个发现命令可以找到常用 ID。
• 安全的读取路径。
• 预期的草稿/写入路径。
• 原始操作的应急入口。
• 未经用户明确批准时，不要执行哪些操作。
• 三个可直接复制粘贴的命令示例。

将 API 参考详情放在 CLI 文档或技能参考文件中。技能应聚焦于顺序、安全性，以及未来的 Codex 线程实际应运行的示例。