该技能用于为 B2C CLI(基于 oclif)开发新的 CLI 命令和主题。
用途:当需要新增命令、创建主题、添加旗标或参数、实现表格输出或复用 SDK 客户端时使用。
命令组织:命令位于 packages/b2c-cli/src/commands/,目录结构直接映射命令名,例如 code/deploy.ts 对应 b2c code deploy,mrt/env/var/set.ts 对应 b2c mrt env var set。
基类选择:根据需求继承合适基类。BaseCommand 提供日志、JSON 输出与错误处理;OAuthCommand 提供 OAuth 鉴权;InstanceCommand 提供 B2C 实例(主机名、代码版本),其下含 CartridgeCommand、JobCommand、WebDavCommand;MrtCommand 对应 Managed Runtime API;OdsCommand 对应 On-Demand Sandbox API。均从 @salesforce/b2c-tooling-sdk/cli 导入。
命令模板要点:使用静态 description、examples、args、flags,并设置 static enableJsonFlag = true 支持 JSON 输出;在 run() 中调用 require* 方法校验,通过 this.args / this.flags 取值,用 this.instance.ocapi 等客户端调用 API,出错时用 getApiErrorMessage 生成清晰错误。
新增主题:在 packages/b2c-cli/package.json 的 oclif.topics 下注册主题及子主题,并附描述。
旗标模式:支持带短别名与环境变量回退的字符串、带默认值的整数、可 --no-* 的布尔、逗号分隔多值、枚举选项以及 dependsOn 条件旗标。
表格输出:使用 createTable / TableRenderer 与 ColumnDef 定义列,结合 --extended 与 --columns 旗标控制显示。
国际化:所有面向用户的字符串用 t() 函数,键遵循 commands.<topic>.<command>.<key> 模式,缺失时回退默认字符串。
验证与客户端:OAuthCommand 提供 requireOAuthCredentials;InstanceCommand 提供 requireServer、requireCodeVersion、requireWebDavCredentials;MrtCommand 提供 requireMrtCredentials。客户端按需懒加载,如 instance.ocapi、instance.webdav、odsClient、mrtClient。
错误处理:this.error 会以退出码 1 退出并支持 suggestions;this.warn 仅警告继续。调用 API 时务必同时解构 error 与 response,以便 getApiErrorMessage 处理 ODS、OCAPI、SCAPI 错误及非 JSON 响应。
限制与排查:创建文件后命令未找到需确认目录正确并运行 pnpm --filter @salesforce/b2c-cli run build 重新生成 manifest;旗标名用 kebab-case,单字符别名仅一个字符,dependsOn 引用需存在;require* 不可用时应检查基类是否正确;缺少 i18n 键不会崩溃但应保持路径一致。构建与测试命令:pnpm run build && pnpm --filter @salesforce/b2c-cli run test。