Codex 友好型 CLI 命令面设计基于 agent-cli-patterns 的可组合命令模式指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills导读本文是仓库内 cli-creator 技能包中核心参考文档 agent-cli-patterns.md 的完整解读与工程化扩展。它回答一个关键问题当你要为一个服务、应用、API、日志源或数据库设计一个可以被 CodexAI Agent反复、可靠地调用执行的命令行工具时命令面command surface应该长什么样读完本文你将掌握可组合原语的拆分原则、名词 动词的命令形状规范、JSON 稳定输出的契约、退出码约定、分页与广度控制、raw 逃生舱设计以及配套 companion skill 的写作范式——这些能力可直接用于搭建ci-logs、slack-cli、sentry-cli这类持久化 CLI。心智模型CLI 是 Codex 的命令层agent-cli-patterns.md开篇就给出了全文的底层心智模型The CLI is Codexs command layer. It should turn a service, app, API, log source, or database into shell commands Codex can run repeatedly from any repo.这句话包含两层含义CLI 是命令层它不是一次性脚本而是把远程或本地的业务能力服务、应用、API、日志源、数据库转化为 shell 里可反复执行的命令。Codex 是消费者CLI 是它触达世界的手。必须可从任何仓库运行这正是 SKILL.md 中Create a real CLI that future Codex threads can run by command name from any working directory的要求——CLI 要安装到 PATH 上而不是只能在源码目录里用cargo run或包管理器包装器运行。可组合原语优于万能大命令文档强调的核心设计取向Good CLIs for Codex expose composable primitives. Avoid a single command that tries to do the whole investigation when smaller discover, read, resolve, download, inspect, draft, and upload commands would compose better.即避免设计一个试图完成整个调查流程的巨型命令而应该把流程拆成更小的可组合原语——discover发现、read读取、resolve解析、download下载、inspect检查、draft草稿、upload上传。每个原语只做一件事Codex 可以像搭积木一样把它们串成任意工作流而不是被一个全自动命令锁死。这一原则在 SKILL.md 的 Command Contract 一节得到呼应写命令要do one named action each并且do not hide writes inside broad commands such asfix,debug, orauto。Help 即接口为未来的 Codex 线程写帮助文本CLI 的--help是 Codex 认识这个工具的第一入口。文档的设定是未来某个 Codex 线程手里只有一个二进制文件和一个模糊的任务描述没有 README、没有上下文。因此--help必须自足、自解释每个命令都要有简短描述flag 名称要使用产品/API 中原生的字面词汇不要发明抽象别名。一个合格的一级帮助top-level help应当能回答以下问题问题对应能力我可以发现哪些容器containersdiscovery 命令如accounts list、projects list我可以精确读取哪些对象read 命令如issues get、messages context我可以解析哪些稳定 IDresolve 命令如channels resolve我可以下载/上传哪些文件download/upload 命令如logs download、media upload存在哪些写操作write 命令如drafts create原始逃生舱raw escape hatch是什么request get之类的兜底命令命令形状规范名词在前动词在后文档给出了首选命令形状preferred command shapetool-name --json doctor tool-name --json accounts list tool-name --json projects list tool-name --json channels resolve --name codex tool-name --json messages search exact phrase tool-name --json messages context message-id --before 3 --after 3 tool-name --json logs download build-url --failed --out ./logs tool-name --json media upload --file ./image.png tool-name --json drafts create --body-file draft.json规律非常清晰先写产品名词product nouns再写动词verbs。accounts、projects、channels、messages、logs、media、drafts是名词资源list、resolve、search、context、download、upload、create是动作。这让命令读起来像一句完整的话在 messages 中搜索……、下载 logs……。当某个 API 的原生名词已经足够强时直接动词也是允许的tool-name --json social-sets tool-name --json drafts list --social-set id tool-name --json request get /v2/me但文档强调的铁律是一致性consistency除非产品词汇表强制要求否则不要混用多种风格。SKILL.md 的 Build Workflow 第 2 步也要求Sketch the command list in chat. Keep names short and shell-friendly即命名要短、要 shell 友好。为什么是--json全局可用注意上述示例里几乎每个命令都带了--json。这正是文档后续 Support--jsoneverywhere Codex will parse or pipe results 的体现Codex 的核心工作方式是解析输出、管道传递结果因此 JSON 是全局一等公民而不是某个命令的专属选项。借鉴成熟 CLI 的有用形状文档反对过于聪明的 Agent 专属抽象而是推荐从成熟 CLI 中借鉴被验证过的模式# 字段选择的结构化输出让常见读取可脚本化 tool-name issues list --json number,title,url,state tool-name issues list --json number,title --jq .[] | select(.state open) # 默认给人读的文本请求时才输出完整 API 对象 tool-name pods get name tool-name pods get name -o json # 产品级工作流命令而不只是 REST 名词 tool-name logs tail tool-name webhooks listen --forward-to localhost:4242/webhooks tool-name webhooks trigger checkout.completed这三个模式分别对应三个设计取向字段选择field selection--json number,title,url,state让 Codex 只取需要的字段与--jq组合可以做服务端过滤的补充如只筛state open的条目避免为了取一个字段而拉全量对象。默认文本、按需 JSONpods get name默认输出人类可读的文本-o json时才给出完整 API 对象。这与Support human text by default if it helps呼应——人读的时候别堆 JSON机器解析的时候别省 JSON。产品工作流命令logs tail、webhooks listen、webhooks trigger是产品语义层面的动作而不是对 REST 名词的机械映射。文档还给出了一条务实的边界Only implement filtering or templating if the user will actually need it. Stable JSON plus narrow read commands are the baseline.即过滤和模板化功能只有当用户确实需要时才实现稳定的 JSON 窄粒度的读取命令才是基线。第一遍命令设计顺序Discover → Resolve → Read → Context文档把首轮命令设计定义为四个阶段顺序非常讲究Discover发现先发现宽泛的容器——workspaces、accounts、social sets、repos、projects、channels、queues。这是 Codex 面对陌生服务时的第一步用来摸清这里有什么。Resolve解析把人类输入解析成稳定 ID——用户名、频道名、永久链接permalink、PR URL、build URL、客户 slug。目的是把模糊的、易变的输入转成后续命令可以直接使用的稳定标识。Read读取读取精确对象——issue、event、thread、draft、customer、job、run、media item。Context上下文在锚点对象周围获取上下文——附近的消息、父线程、周边日志、审计历史如messages context message-id --before 3 --after 3。核心原则是文档这句警告Do not force Codex to repeatedly search when it already has a stable ID.即一旦 Codex 拿到了稳定 ID就不要再强迫它反复搜索。这一顺序也直接映射到 SKILL.md 的 Command ContractResolve commands turn names, URLs, slugs, permalinks, customer input, or build links into stable IDs so future commands do not repeat broad searches——解析命令的存在意义就是避免未来的命令重复做宽泛搜索。输出契约文本、JSON、文件与退出码JSON 输出的硬性约定文档对--json给出了四条铁律只向 stdout 输出 JSON进度和诊断信息发送到 stderr这样管道和解析不会污染数据流保持成功与错误形状的文档化success and error shapes 要有文档可查脱敏redacttoken、cookie、客户机密、私有 header 和无关 payload 一律不得出现在输出中。这与 SKILL.md 的 JSON 政策要求完全一致Under--json, errors must be machine-readable and must not contain credentials。并且注意--json命令面下还要区分 API pass-through透传 API 响应与 CLI envelopeCLI 自封装外壳两种模式文档中需给出成功形状、错误形状和每个命令族的示例。下载与导出对下载和导出类命令尽量把文件写到用户提供的--out路径下如logs download build-url --failed --out ./logsJSON 输出中应返回文件路径、字节数如果廉价可得、源 URL 或 ID以及后续跟进命令follow-up command。返回下一步该跑什么是帮助 Agent 连续行动的关键细节。退出码语义退出码是 Agent 判断命令成败的唯一机器信号文档定义如下成功含空结果退出码为 0注意空结果也是成功——查不到数据不是错误非零退出码对应认证失败、非法输入、网络失败、解析失败、API 错误、上传/下载不完整doctor --json在缺少认证时也必须可用它应当报告缺少认证而不是崩溃。这正是 SKILL.md 中doctor命令定位的延伸——tool-name --json doctorverifies config, auth, version, endpoint reachability, and missing setup并把认证来源分类报告为flag、env、config、provider default 或 missing。分页与广度控制默认浅显式加宽文档推荐默认浅层shallow获取把广度交给显式旋钮控制tool-name --json messages search topic --limit 10 tool-name --json messages search topic --limit 50 --all-pages --max-pages 3 tool-name --json drafts list --limit 20 --offset 40三个示例展示了三种控制维度--limit限制单次返回条数默认浅--all-pages --max-pages N在显式要求时才翻页并且限制最大页数防止 Agent 意外拉爆整个数据集--offset 40提供基于偏移量的经典分页。返回结果时应回传提供方真实支持的游标字段next_cursor、next_url、offset、page_count等——whatever is real for the provider。不要捏造提供方不存在的分页机制。SKILL.md 同样要求Paginated lists support a bounded--limit, cursor, offset, or clearly documented default。Raw 逃生舱是维修舱不是主界面CLI 不可能预知所有未来需求因此需要保留一个 raw 逃生舱escape hatch。文档给出两条定位原则它是维修舱而非主界面a repair hatch, not the main interface——绝大多数场景应走高层命令好的 raw 命令依然复用全部基础设施配置的认证、base URL、JSON 解析、脱敏、状态/错误处理、--json。也就是说raw 不等于裸奔它只是把 HTTP 层暴露出来安全治理层不拆。读取类逃生舱应该容易使用tool-name --json request get /v2/me关于写操作文档给出非常明确的红线Treat raw writes as live writes. Do not hide POST/PUT/PATCH/DELETE behind a debug command.raw 写就是真实写绝不要把 POST/PUT/PATCH/DELETE 藏在名为debug的命令后面来暗示它是安全的。这呼应了 SKILL.md 的两处要求raw 逃生舱support read-only calls first. Do not run raw non-GET/HEAD requests against a live service unless the user asked for that specific write且逃生舱要有一个诚实的名字——request、tool-call、api或最贴近实际的名字。同时 SKILL.md 也警告不要只暴露一个通用的request命令因为 Codex 需要的是针对重复任务的高层动词。Companion Skill 模式教 Codex 怎么走通工具CLI 建好之后还需要一个配套的 companion skill在 SKILL.md 中称为小的 companion skill。文档给出的原则是The companion skill should be smaller than the CLI README. It should teach the path through the tool.companion skill 应该比 CLI README 更小它的职责不是罗列所有功能而是教 Codex 走通工具的路径the path through the tool——先跑什么、再跑什么、哪些事不能做。文档给出的骨架模板Start with: tool-name --json doctor tool-name --json accounts list For [common job]: tool-name --json ... tool-name --json ... Rules: - Prefer installed tool-name on PATH. - Use --json when analyzing output. - Create drafts by default. - Do not publish/delete/retry/submit unless the user asked. - Use request get ... only when high-level commands are missing.这个模板蕴含了 companion skill 的标准结构Start with给出入口命令通常是doctor 第一个 discovery 命令先验证环境再摸清资源For [common job]为每个常见任务给出推荐命令序列Rules安全规则清单——优先用 PATH 上已安装的tool-name、分析输出时用--json、默认只建草稿、未经用户明确要求不得 publish/delete/retry/submit、只有高层命令缺失时才用request get。文档最后补充Include JSON shape notes only when Codex needs them to choose the next command——JSON 形状说明只在 Codex 需要据此选择下一个命令时才写入 skill避免让 skill 变成 API 文档的复制品。这一节与 SKILL.md 的 Companion Skill 章节互相印证后者要求 skill 按未来 Codex 线程应使用的顺序来写先验证命令存在、先跑哪个命令、认证如何配置、哪个 discovery 命令找常见 ID、安全读路径、草稿/写路径、raw 逃生舱、未经批准不做什么、三个可复制粘贴的命令示例并明确Keep API reference details in the CLI docs or a skill reference file——API 参考细节应留在 CLI 文档或 skill 的 reference 文件中skill 本体只负责排序、安全与示例。在 cli-creator 工作流中的落点这份 patterns 参考文档不是孤立存在的它在整个 cli-creator 技能中处于命令面设计规范的位置SKILL.md 的 Command Contract 环节明确要求When designing the command surface, read references/agent-cli-patterns.md for the expected composable CLI shape并据此列出应构建的命令面--help、doctor、init、discovery、resolve、read、写命令、--json、raw 逃生舱技能入口 agents/openai.yaml 给出的默认提示词是Create a composable CLI from this source material, install it on PATH, test it from outside the source folder, and create a companion skill that teaches Codex when to use it——其中composable CLI正是本文命令面规范要交付的形态整个技能包按 README.md 的说明属于 curated 技能可通过$skill-installer cli-creator安装使用。因此当你在 cli-creator 工作流中为某个新服务设计命令面时本文就是那份设计核对清单检查命令是否遵循名词动词、是否按 Discover→Resolve→Read→Context 排序、--json是否全局可用、退出码语义是否正确、分页是否默认浅、raw 逃生舱是否诚实命名、companion skill 是否教了路径而非罗列功能。快速自查清单最后把整份 patterns 提炼成一张可直接对照的清单CLI 是命令层能从任意仓库反复运行而非源码目录内的一次性脚本命令可组合拆分为 discover / resolve / read / download / inspect / draft / upload 等小原语拒绝全自动大命令--help自足只有二进制 模糊任务时也能看懂flag 使用产品/API 原生词汇命令形状统一名词 动词channels resolve、messages search风格保持一致首轮命令按 Discover → Resolve → Read → Context 排序已有稳定 ID 时不再强制搜索--json全局可用JSON 只进 stdout进度/诊断进 stderr成功与错误形状有文档输出脱敏下载类命令支持--outJSON 返回路径、字节数、源 URL/ID 和跟进命令退出码成功含空结果为 0认证/输入/网络/解析/API/传输失败为非零无认证时doctor --json不崩溃分页默认浅--limit/--all-pages/--max-pages/--offset显式控制广度回传提供方真实游标字段raw 逃生舱复用认证与脱敏基础设施raw 写即真实写不藏在debug后面companion skill 比 README 小只教路径Start with / common jobs / Rules含安全红线默认草稿、未经批准不 publish/delete【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考