CLI 与发布前检查

从创建项目到验证归档，明确每个命令做什么、不做什么，以及成功标准。

API 参考

按章节查看契约、签名、字段与示例；未注明的默认值不作推断。

本页内容

01脚手架选项

先完成插件入门指南的本地包准备，在 extension-work 中执行并保留 AMBLELOFT_PACKS。CLI 不自动安装依赖。

代码示例

npx --no-install amble-extension init my-app --name my-app --template expense
cd my-app
npm install --save-dev "$AMBLELOFT_PACKS/ambleloft-extension-sdk-0.1.0-alpha.9.tgz" "$AMBLELOFT_PACKS/ambleloft-extension-core-0.1.0-alpha.9.tgz" "$AMBLELOFT_PACKS/ambleloft-extension-cli-0.1.0-alpha.9.tgz"
npm run build
npm run validate
npm run pack

02validate / pack

从本地已安装 CLI 执行。validate 不执行扩展代码；pack 输入为准备好的目录，输出必须在其外部，后缀 .amble-extension。默认不覆盖已有输出；--force 显式覆盖。

代码示例

npx amble-extension validate dist/package --json
npx amble-extension pack dist/package dist/my-app.amble-extension --json
npx amble-extension validate dist/my-app.amble-extension --json

字段 / API	说明
Exit 0 / 1 / 2	成功 / 校验或执行失败 / 命令语法错误。
--json	validate、pack、doctor 的结构化输出。
--	分隔选项与以 - 开头的路径。

03doctor 是源码检查

--host 指向宿主源码目录，不是运行中应用。检查能力基线不等于实际运行成功；runtimeStatus: not-tested 不能写成已通过宿主测试。

代码示例

npx amble-extension doctor --host ../Ambleloft \
  --require operations,declarativeForms,localMessages --json

字段 / API	说明
Available capability IDs	operations、configuration、localMessages、declarativeForms、mcpApps、messageActions、extensionAuthentication。 agentHooks, conversationTurns, backgroundJobs (M2 source preview).
Unavailable	formResumeApi；没有 extensionIcons capability ID。

04发布验收矩阵

CLI 不负责安装、信任、登录或发布到市场。发布前保留宿主版本、SDK/CLI 版本、归档校验输出和人工验收记录。

字段 / API	说明
Package	图标、Skill、YAML、页面和许可证都在包内；归档验证通过。
Interaction	中文/英文、深浅主题、键盘操作、空输入和边界值。
Business writes	取消、超时、已写入丢响应、查询恢复与幂等。
Messages	重复/乱序事件、断线重连、撤回、偏好与操作结果。

05alpha.9 Hooks 校验

Schema 和 CLI 检查 Hooks 事件、权限、入口与 handler 冲突。doctor 检查源码能力，不代替真实宿主授权、模型作业和重启验收。

代码示例

npx --no-install amble-extension doctor --host /path/to/agent --require agentHooks,conversationTurns,backgroundJobs --json

SDK / CLI 0.1.0-alpha.9 · 接口基线兼容性与预览说明 · 案例源码