CLI开发工具【免费下载链接】autocompleteIDE-style autocomplete for your existing terminal shell项目地址https://gitcode.com/GitHub_Trending/au/autocomplete点击查看免费下载本仓库withfig/autocomplete现已并入 Amazon Q Developer CLI 的开源生态是 Fig 时代沉淀下来的海量 CLI 补全规范集合。本文将围绕 README 中“completion specs 是什么、如何在 3 分钟内贡献第一个 spec、如何用 pnpm 脚本开发与校验”这条主线结合仓库内数百个 TypeScript 补全规范的真实实现完整讲解 spec 的数据结构、Generator 机制与贡献流程帮助读者理解并亲手写出可运行的 CLI 智能补全。一、背景当终端遇上 IDE 式补全Amazon Q Developer CLI前身是开源项目 Fig为git、npm、docker、aws等数百个常用 CLI 提供“IDE 风格”的补全体验用户开始输入命令时它会根据当前上下文实时填充相关的子命令subcommand、选项option与参数argument。这套能力之所以能覆盖这么多工具靠的正是本仓库维护的一批声明式补全规范completion specs。仓库当前版本号为2.692.3见 package.json在src/目录下按命令名组织着 800 个 TypeScript 文件例如git.ts9812 行、npm.ts1610 行、curl.ts914 行以及aws/、az/、gcloud/等大型云厂商 CLI 的独立子目录构成了一个规模可观的补全规范生态。二、什么是 Completion SpecREADME 给出了精确定义A completion spec is adeclarativeschema that specifies thesubcommands,optionsandargsfor a CLI tool. Amazon Q uses these schemas to generate suggestions.也就是说一个 completion spec 是一份声明式declarativeschema它描述某个 CLI 工具的三类核心信息subcommands该命令支持哪些子命令options该命令支持哪些选项短选项-x、长选项--xxx、以及二者的组合别名args每个子命令/选项后跟的参数是什么类型、是否可选、是否可重复。Amazon Q 读取这些 schema 后在你敲击键盘时实时生成补全建议。在仓库源码中一个最小 spec 长这样以 create-completion-spec.ts 为例const completionSpec: Fig.Spec { name: create-completion-spec, description: Setup fig folder and create spec with the given name, subcommands: [ { name: help, description: Display help for command, priority: 49, args: { name: command, isOptional: true }, }, ], options: [ { name: --here, description: Set if the spec should be created in the current folder, }, { name: [-h, --help], description: Display help for command, priority: 49, }, ], args: { name: name }, }; export default completionSpec;每个 spec 文件以export default completionSpec;结尾导出name字段命令名用于在终端中触发对应补全。三、安装 Amazon Q Developer CLImacOSDMG 安装从 AWS 官方文档下载安装包Homebrew 安装brew install amazon-qNOTE: 下载完成后需要启动 Amazon Q 应用来完成命令行环境配置之后才能在终端中生效。Linux / Windows官方目前仅在 macOS 提供安装包Linux 与 Windows 的支持正在推进中相关讨论见 AWS 的 q-command-line-discussions 社区Linux 讨论 #14、Windows 讨论 #15。远程机器SSH若需要在 SSH 会话中获得补全能力可查阅官方文档中 “Autocomplete in SSH” 一节。支持的终端根据 README 的 FAQAmazon Q 支持以下终端环境原生 macOS Terminal、iTerm、Tabby、Hyper、Kitty、WezTerm、AlacrittyVSCode、JetBrains IDE、Android Studio、Nova 的集成终端。四、3 分钟内贡献第一个 Spec前置条件已安装 Amazon Q for command line已安装 Node 与 Pnpm仓库package.json声明engines要求node 20、pnpm 9packageManager固定为pnpm9.1.0。操作步骤安装 pnpm按官方指引安装这是本仓库使用的包管理器。Fork 仓库Forkwithfig/autocomplete。克隆并创建示例 spec# 将 YOUR_GITHUB_USERNAME 替换为你的 GitHub 用户名 git clone https://github.com/YOUR_GITHUB_USERNAME/autocomplete.git autocomplete cd autocomplete # 添加上游仓库为 remote git remote add upstream https://github.com/withfig/autocomplete.git # 安装依赖 pnpm install # 创建一个名为 abc 的示例 spec pnpm create-spec abc # 开启 dev mode pnpm dev验证效果在终端中输入abc[空格]你的示例 spec 就会出现在补全建议中。开发模式下的文件流转README 补充了三条关键机制也可从 package.json 的 scripts 中得到印证spec 以TypeScript编写放在src/目录下保存时 spec 会被编译到build/目录pnpm build对应npx withfig/autocomplete-tools compiledev mode下Amazon Q 从build/目录读取 spec并且generators 会在每次按键时重新执行从而实现动态补全。create-spec命令由npx withfig/autocomplete-tools create-spec提供见 package.json它会在src/下生成一个带名字的空白 spec 骨架。若想在当前目录就地创建可参考create-completion-spec.ts中展示的--here选项语义。五、Spec 数据结构详解结合源码理解 spec 的字段是编写高质量补全的前提。下面结合仓库真实文件逐个拆解。5.1 顶层结构Fig.Spec一个 spec 文件通常包含name、description、subcommands、options、args五个核心字段。以 aliases.ts 为例const completionSpec: Fig.Spec { name: aliases, description: Bash aliases on steroids, dynamic alias functions for bash, subcommands: [ /* ... */ ], options: [ /* ... */ ], args: [ /* ... */ ], };name命令名必填决定触发范围description展示在补全列表里的说明文字面向用户subcommands数组每项是一个Fig.Subcommand结构与顶层类似可嵌套options数组每项是一个Fig.Optionargs数组或单个对象描述命令位置的参数。5.2 选项Options的多种写法选项是补全中最常见的对象。以 curl.ts 为例可以看到几种典型形态短选项与长选项合并{ name: [-a, --append], description: Append to target file when uploading, },带参数文件模板{ name: [-K, --config], description: Read config from a file, args: { name: file, template: filepaths }, },参数带模板与自定义查询分隔符{ name: [-E, --cert], description: Client certificate file and password, args: { name: certificate[:password], generators: { getQueryTerm: : }, }, },可重复选项与光标定位insertValue{ name: [-d, --data], description: HTTP POST data, insertValue: -d {cursor}, args: { name: data }, isRepeatable: true, },这里isRepeatable: true表示-d可多次出现insertValue支持{cursor}占位符插入后光标自动定位到引号内极大提升输入体验。5.3 参数Args的语义example/git_push.ts 是官方保留的教学示例直接演示了如何从git push --help的 SYNOPSIS 翻译成 spec其中两个概念最关键isOptional参数是否可省略。例如git push的[repository [refspec...]]语义是“repository 可选但如果输入了 repository就必须输入 refspec”翻译为args: [ { name: repository, isOptional: true }, { name: refspec, isOptional: true, isVariadic: true }, ],isVariadic参数是否可变长可跟多个值refspec后面的...即对应此字段。该文件头部注释还点明了两个 Fig 尚未支持的语法在写 spec 时需要注意方括号表示的可选选项Fig 暂无“可选 option”语法|表示互斥选项组Fig 不支持互斥声明需要把每个选项单独列出。5.4 优先级与图标补全建议支持排序与视觉修饰。git.ts 中分支补全的postProcess展示了priority与icon的用法return { name, description: Branch, icon: fig://icon?typegit, priority: 75, };当前分支则被标记为return { name: branch.replace(*, ).trim(), description: Current branch, priority: 100, icon: ⭐️, };优先级越高越靠前展示icon既可以是 emoji也可以是fig://icon?type...协议引用仓库 icons 目录提供git.png、docker.png、aws.png等素材供 spec 引用。六、Generator让补全“活”起来静态枚举子命令和选项只是第一步。当参数需要动态生成如列出分支、搜索 npm 包、列出远程文件时就要用到generators。README 在贡献指引中专门提到 Generators 是社区最需要的贡献方向之一。6.1 Generator 的四个钩子example/trigger.ts 是一个官方示例完整展示了 generator 的四个关键回调script —— 每次按键执行的 shell 脚本script: (tokens) { var baseLsCommand [ls, -1ApL]; var whatHasUserTyped tokens[tokens.length - 1]; // 根据用户已输入内容解析目录路径拼出 ls 命令 return [...baseLsCommand, folderPath]; },postProcess —— 把脚本 stdout 转成建议列表postProcess: (out) { // 解析 ls 输出区分文件/文件夹 final_array.push({ type: outputType, // file 或 folder name: item, insertValue: item, }); return final_array; },trigger —— 决定何时重新执行生成器而不是简单过滤trigger: (newToken, oldToken) { // 用户敲到新的 / 时重新生成目录列表 if (newToken.lastIndexOf(/) ! oldToken.lastIndexOf(/)) { return true; } return false; },getQueryTerm —— 决定用用户输入中的哪一段去过滤建议getQueryTerm: (token) { return token.slice(token.lastIndexOf(/) 1); },这个示例还演示了为补全添加自定义前缀file://的处理技巧当用户输入尚未包含前缀时script返回[echo, file://]引导用户先补出前缀。6.2 真实世界的 Generatornpm 包搜索npm.ts 展示了更高阶的用法——generator 可以异步调用外部 API。其核心逻辑createNpmSearchHandler会根据用户当前 token 决定查询哪个接口若 token 以结尾或已包含第二个说明用户想选版本则请求https://registry.npmjs.org/pkg解析dist-tags与versions生成建议否则视为包名搜索请求 npms.io 的搜索接口返回包名与描述。const shouldGetVersion searchTerm.startsWith() ? atsInStr(searchTerm) 1 : searchTerm.includes();可以看到spec 不仅能枚举静态内容还能通过与真实 CLI/API 交互实现“每敲一个字符都在重新思考”的动态补全。6.3 处理脚本报错git.ts 的filterMessages与分支解析函数示范了健壮性处理const output filterMessages(out); if (output.startsWith(fatal:)) { return []; }当git输出fatal:等错误信息时返回空数组而非把报错当建议展示postProcessBranches还处理了 detached HEAD、前缀其他 worktree 检出的分支、remotes/前缀去重等边界情况。七、其他 package.json 命令README 列出了仓库常用的三条命令对应 package.json 中的 scripts# 对 src/ 下所有 spec 做类型检查tsc --noEmit通过后提示可提交 pnpm test # 把 src/ 中的 TypeScript spec 编译到 build/ 目录 pnpm build # 用 ESLint 与 Prettier 自动修复代码风格问题 pnpm lint:fix此外还有pnpm devnpx withfig/autocomplete-tools dev监视src/变化并实时编译供本地调试pnpm create-spec name创建新的 spec 骨架pnpm lint只检查不修复ESLint Prettier check。仓库还通过huskyprepare脚本lint-staged在提交前对*.ts自动执行eslint --fix保证合入代码风格统一。八、如何参与贡献README 明确列出了社区最欢迎的贡献方向新增 completion specs为尚未覆盖的 CLI 编写规范修正既有 spec 的错误遗漏的子命令、选项或参数为参数建议编写 Generators让参数补全更智能更好的描述、图标等细节主题Themes相关贡献。对新手而言最简单的切入点是从pnpm create-spec生成一个真实使用的小命令 spec 开始如 README 示例中的abc然后逐步为它的子命令、选项和参数补充generators。九、FAQ 与常见问题9.1 Amazon Q 支持哪些终端支持 macOS 原生 Terminal、iTerm、Tabby、Hyper、Kitty、WezTerm、Alacritty以及 VSCode、JetBrains IDE、Android Studio、Nova 的集成终端。若希望支持更多终端可在 AWS 的 q-command-line-discussions 社区提出诉求。9.2 Amazon Q 是如何工作的根据 READMEAmazon Q for command line 通过macOS Accessibility API定位补全窗口并与 shell 集成来读取用户已经输入的内容从而在正确的光标位置弹出补全。9.3 支持 Windows / Linux 吗目前仅支持 macOS。Windows讨论 #15与 Linux讨论 #14的支持正在推进中。9.4 如何下载 Amazon Q运行brew install amazon-q或从 AWS 官网下载应用安装后记得启动 Amazon Q 应用完成初始化。9.5 如何提交 PR参考官方 “How to Contribute” 指南。仓库有 400 贡献者的历史沉淀许多人的第一个开源贡献正是贡献了一个 completion spec。9.6 安装后不生效怎么办运行诊断命令q doctor该命令会自动排查安装问题若仍无法解决可在 q-command-line-discussions 社区发帖求助。十、结语从 README 的“3 分钟上手”到仓库源码中的完整实现可以看到 completion spec 这套声明式方案的精妙用一份 TypeScript schema 描述 CLI 的语法树再用 Generators 注入动态能力从而以极低的成本把 IDE 级补全带到终端世界。本仓库既是 Amazon Q Developer CLI 的补全数据源也是学习如何系统化描述任意 CLI 接口的绝佳样本——无论你是想为下一个常用工具补上补全还是想深入理解声明式补全引擎的运作方式都可以从src/下找一个你熟悉的命令如git.ts、curl.ts开始研读。赞分享CLI开发工具【免费下载链接】autocompleteIDE-style autocomplete for your existing terminal shell项目地址https://gitcode.com/GitHub_Trending/au/autocomplete点击查看免费下载相关推荐Amazon Q Developer CLI文件系统inode操作技巧Amazon Q Developer CLI文件系统inode操作技巧 引言为什么inode操作对开发者如此重要 在日常开发工作中文件系统操作是不可避免CVAT部署从零到交付标注数据的完整流水线五步走CVAT部署从零到交付标注数据的完整流水线五步走 假设你手里有 5000 张街景图需要在一周内交付一份 COCO 格式的目标检测数据集。这篇文章带你完成 C数据标注计算机视觉数据集AI 应用后端前端Amazon Q Developer CLI合规性安全标准符合Amazon Q Developer CLI合规性安全标准符合 引言 在当今数字化时代开发工具的安全性已成为企业级应用的核心关注点。Amazon Q Dev上一篇Homemade Machine Learning音乐生成创意AI应用终极指南下一篇Zotero Style 插件开发指南从架构到实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考