SuperAPI AI 工具集

software-devtools

编程与开发

查看项目

更新于 10-16 04:26

技能介绍

用途

本技能用于构建面向开发者的工具(Developer Tools)与 SDK 工程,涵盖开发者体验(DX)与 SDK 设计的完整链路。适用场景包括:构建 CLI 工具(参数解析、子命令、交互式提示)、设计与实现 API 的 SDK 或客户端库、从 OpenAPI/GraphQL/Protobuf 模式生成代码、构建 VS Code 扩展或 JetBrains 插件或语言服务器协议(LSP)实现、向包仓库(npm、PyPI、crates.io、NuGet、Maven Central)发布包、度量并改进开发者体验指标、构建 codemod 或基于 AST 的代码转换工具。

不适用场景:面向用户的 Web 或移动应用(转 software-frontend、software-mobile)、API 设计原则本身(转 dev-api-design)、后端服务实现(转 software-backend)、CI/CD 流水线与平台工程(转 ops-devops-platform)、智能体与技能开发(转 agents-skills、agents-mcp)、依赖审计与升级策略(转 dev-dependency-management)。

主要能力

工作流:先对工具面分类(CLI、SDK、代码生成器、编辑器扩展或 codemod),再按决策树选择实现模式并明确输出契约,最后应用打包、DX、代码生成或编辑器集成的相应指引。

CLI 框架选型:Node.js 使用 Commander.js、oclif、Ink(用于 CLI 的 React);Go 使用 Cobra + Viper;Rust 使用 clap + dialoguer;Python 使用 Click / Typer。

SDK 设计原则:保持 API 面尽量小;渐进式披露(简单默认零配置可用,高级选项按需提供);复杂配置使用 builder / fluent 模式(如 new ClientBuilder().withAuth(token).withRetries(3).build()),避免 20 个字段的深层选项对象;错误信息需说明出错原因与修复方式;返回强类型对象而非原始 JSON;遵循语义化版本并为每个大版本提供迁移路径;核心尽量零运行时依赖;按语言习惯编写(Python SDK 要有 Python 风格)。

CLI 开发模式:自动化契约——退出码、stdout、stderr 与机器可读输出视为公共 API;人类进度信息输出到 stderr,请求数据输出到 stdout,--json 必须保持可解析且无横幅与颜色。退出码约定:0 为完全成功,1 为执行失败(含校验失败、依赖瞬时失败与部分完成),2 为调用无效;具体错误码、可重试性与完成/失败清单放入 JSON。参数解析使用 tool <command> [args] [--flags] 通用模式,子命令层级最多两级。交互提示需对破坏性操作明确确认、提供可选输入;非交互模式下缺少必填值以退出码 2 失败而非弹出提示。进度指示器:不确定时使用 spinner,已知长度使用进度条,始终提供 --quiet / --silent。颜色遵循 NO_COLOR 环境变量与 --no-color。配置文件发现支持 ~/.config/toolname/config.yaml、.toolnamerc、toolname.config.js 层级并在本地覆盖。支持 bash、zsh、fish 的 shell 补全。安装器与自更新需用带外固定的密钥验证签名,保留旧二进制直到新版本通过自检。

面向智能体的 CLI 模式:智能体已成为与人类并列的主要 CLI 消费者。非交互优先——所有输入都可通过 flag 传入;渐进式 --help 发现——不要一次性倾倒全部文档;每个 --help 至少包含两个使用示例;支持 --stdin 与结构化 --output 以便管道串联;缺参数时立即失败并给出可操作错误与“是否为”提示;命令幂等(重复 deploy 返回“已部署,无操作”);破坏性操作支持 --dry-run 预览;区分 --yes(批准既定计划)与 --force(可能改变覆盖策略),二者均不得禁用凭证检查、签名验证或授权;命令结构可预测(如 resource + verb);成功时返回部署 ID、URL 与耗时等可解析数据。

代码生成:在存在模式时采用模式驱动(OpenAPI/GraphQL/Protobuf),代码转换使用 AST 而非脆弱正则,生成输出经过项目格式化器,添加清晰的生成文件标记与 linguist-generated=true,支持安全的 --dry-run 与部分重新生成。可用工具包括 OpenAPI Generator(自托管)、Stainless/Fern/Speakeasy(托管)、GraphQL Codegen、Protobuf/Connect、自定义 AST 转换。

IDE 扩展开发:保持 activate() 轻量,多编辑器语言特性优先用 LSP,控制 webview 包体积,在协议层测试 LSP 服务器,面向分叉用户时同时发布到 VS Code Marketplace 与 Open VSX。

包发布:遵循语义化版本;使用约定式提交(feat:、fix:,破坏性变更用 ! 或 BREAKING CHANGE: 页脚)并自动生成变更日志;优先使用仓库 OIDC 受信发布而非静态发布令牌,自动溯源需满足资格条件并验证生成的证明;Node.js 模块格式方面,require(esm) 在 Node v20.19 / v22.12 / v23+ 已默认启用,若支持的 Node 下限为 ^20.19 || >=22.12 可仅发布 ESM 并声明 engines,避免双包风险,仅在有旧运行时或工具需求时才提供 CJS/ESM 双包并测试两个入口;仅在导入无必需副作用时声明 sideEffects: false;使用 npm deprecate 等弃用旧版本并提供迁移指南。

DX 指标:度量本地反馈回路时间、首次 API 调用时间、各步骤的引导流失率、最新大版本采用率、按方法的错误率、支持工单聚类与开发者满意度。

使用方式

按工作流分类工具面,依据决策树(交互式终端工具、供他人导入的库、编辑器集成、从模式生成代码、转换现有代码、开发者文档门户)选择实现模式,从对应参考文件获取细节:references/sdk-and-cli-checklist.md(SDK 运行时契约、CLI 分发、codemod 工具与编辑器集成清单)、references/publishing-and-support.md(发布、包签名、文档、支持与弃用流程)、references/dx-scenarios-and-antipatterns.md(Do/Avoid 清单、反模式与 S1–S5 配方,含 changesets 的 SDK 发布、智能体可消费 CLI、OpenAPI 转 SDK 流水线、自定义 DSL 的 LSP、IDE 扩展认证与令牌刷新)、references/mcp-server-development.md(何时以及如何将开发者工具暴露为 MCP 服务器)。

选择代码生成器前,需在 data/sources.json 所链接的厂商文档中核对支持的 schema 特性与语言;发布前,需核对仓库身份/溯源要求,并按 publishing-and-support.md 测试 CLI 的目标操作系统与运行时安装矩阵;编辑器集成需核对宿主 API 与 LSP 能力支持,并在发布配置中保留已测试版本。

适用场景与限制

适用场景为构建 CLI、SDK、代码生成器、IDE 扩展、LSP 实现、codemod 与包发布流程。限制包括:API 设计原则、后端服务、前端/移动应用、CI/CD 平台工程、依赖审计与升级策略均不属于本技能范围,需转向相邻技能。已知陷阱包括:让公共 SDK 或 CLI 面泄漏内部传输细节、不稳定 ID 或后端特定的重试语义;把代码生成当作一次性脚手架而非具有可读性、兼容性与重生成保证的产品面;仅从源码树而非消费者实际安装的打包产物验证包;在 IDE 扩展激活路径中做繁重启动工作;只提供人类友好输出而缺少稳定的机器可读契约。

暂未提供

本技能的收费、价格、平台支持矩阵、具体性能数据等事实在资料中暂未提供。