@amaster.ai/cli

amaster 提供两类能力，amaster-cli 作为兼容命令保留：

1. 模板检查
2. Addon Marketplace

Registry

• 默认 registry：helige -> https://www.helige.cn
• 内置别名：helige-int -> https://www.helige-int.cn
• 默认 registry 可通过环境变量 AMASTER_CLI_REGISTRY 覆盖
• 临时切换其他环境时使用 --registry

认证

export AMASTER_CLI_REGISTRY=amaster.local

amaster login
amaster login --registry helige-int --browser
amaster login --registry helige-int
amaster login --registry https://demo.example.com --email [email protected] --password password
amaster whoami
amaster logout

登录流程：

1. --browser：打开 /login?redirect=/api/oauth/authorize...，通过本地 http://127.0.0.1:18147/oauth/callback 接收授权码
2. 默认密码模式：先登录 /api/auth/login
3. 再用 amaster-cli 这个 public PKCE OAuth client 兑换 Addon 写接口可用的 Bearer Token
4. 本地 session 按 registry 隔离保存到 ~/.amaster/cli/config.json

Addon 命令

amaster addon search crm
amaster addon search crm --target /path/to/app
amaster addon view crm-pages
amaster addon view [email protected]
amaster addon versions crm-pages
amaster addon members [email protected]
amaster addon content [email protected] lead-summary

amaster addon publish .
amaster addon publish ./dist/addon.tgz --scope official
amaster addon activate crm-pages
amaster addon deactivate crm-pages
amaster addon delete crm-pages

amaster addon install [email protected]
amaster addon install crm-pages --registry helige-int
amaster addon upgrade crm-pages
amaster addon list

Addon 可把市场展示主图和截图放在源码包内，例如：

marketplace/cover.png
marketplace/screenshots/preview.png

并在 addon.json 中声明：

{
  "display": {
    "image": "marketplace/cover.png",
    "screenshots": ["marketplace/screenshots/preview.png"]
  }
}

这些 marketplace/ 文件只用于发布到 Addon Marketplace，不会被 addon install 安装到应用工程。需要随 Addon 安装到应用工程并被代码引用的运行素材，应声明为 assets member。

addon search 在未显式传 --application-type 时，会从 --target 指定目录或当前目录向上查找最近的 package.json，读取同级 app.settings.yml 的 type，并自动按 web 或 mini 过滤。addon search --target 只用于推断应用类型，不会修改目标应用。 addon search --json 返回面向 MCP/AI 的轻量结果，只包含 name、version、installSpecifier、标题、描述、类目、适用类型、阶段、成员类型和主图地址。

常用参数：

• --registry <alias-or-url>
• --organization-code <code>
• --json
• --set key=value：安装参数
• --application-type web|mini
• --target <path>：显式指定应用根目录；不传时从当前目录向上查找最近的 package.json

安装规则

设计态安装成员类型：

• component
• page
• theme
• workflow
• bpmn
• entity
• datasource
• assets
• settings

skill member 可以发布到 Marketplace，供 Agent 通过 Server API 下载并安装到自己的 skill cache；普通设计态 addon install 不会把 skill 写入应用工程。Skill member 的 source.path 必须指向一个目录，目录内必须包含带 name 和 description frontmatter 的 SKILL.md，可选包含 references/、assets/ 和 scripts/。如果存在 scripts/，必须提供 scripts/scripts.json 声明可执行入口的名称、路径、用途和确认策略；脚本依赖的辅助文件可放在 scripts/ 下，不需要逐个声明为入口。

安装结果会写入：

• src/addons/<addon-name>/meta.json
• settings 成员会深合并到应用根目录 app.settings.yml
• assets 成员会复制到 src/assets/<addon-name>；组件或页面可用 @/assets/<addon-name>/... 静态导入这些图片、JSON、字体或其他前端运行素材

Addon 可在 addon.json 中声明安装后的运行配置要求：

{
  "install": {
    "npm": {
      "dependencies": {
        "@tanstack/react-query": "^5.66.0"
      }
    },
    "requirements": {
      "envs": [
        {
          "key": "OAUTH_CLIENT_ID",
          "required": true,
          "category": "OAuth",
          "label": "OAuth Client ID",
          "description": "OAuth client id",
          "defaultValue": "demo-client"
        }
      ],
      "secrets": [
        {
          "key": "OAUTH_CLIENT_SECRET",
          "required": true,
          "description": "OAuth client secret"
        }
      ]
    }
  }
}

install.npm 会写入应用根目录 package.json。如果目标应用已声明同名包，CLI 会按 semver 判断是否可保留现有版本：版本范围相交，或现有版本下限高于 Addon 请求下限时，保留应用现有版本；旧版本或无法按 semver 判断的差异会停止并返回 package_dependency_conflict。 通过 registry 执行 addon install / addon upgrade 时，如果 package.json 有变更，CLI 会按当前应用自动执行 bun install、pnpm install、npm install 或 yarn install。

install.requirements 会写入 meta.json，并在安装/升级结果中返回 requirements 和 missingRequirements。requirements.envs 和 requirements.secrets 会合并到应用根目录 app.settings.yml 的 envMetadata；env 字段生成 type: input / storage: env，secret 字段生成 type: password / storage: secret / sensitive: true。defaultValue 仅支持 env，会写为 default；secret 不保存密钥值。

环境变量和 Secret requirement 是应用级共享依赖，不归某一个 Addon 独占。多个 Addon 声明同名且存储类型兼容的 requirement 时会复用同一份 envMetadata；展示名称和说明保留应用中已有值，required 按逻辑或合并。若同一个 key 被分别声明成 env 和 secret，或核心存储属性不一致，安装会以 setting_value_conflict 停止。

settings 成员中的 rbac.permissions 按权限字符串去重追加，rbac.roles 按 role.code 合并；同一角色的 permissions 会增量合并，应用已有的角色名称和说明不会被后安装的 Addon 覆盖。升级 Addon 时只移除该 Addon 已不再声明的权限贡献，不影响应用原有配置或其他 Addon 的贡献。其他数组仍按普通设置整体替换，避免把未知数组误判成可组合资源。

页面接入方式：

• CLI 只复制页面文件并写入 src/addons/{addonName}/meta.json
• CLI 不自动修改 src/routes.tsx 或 src/app.config.ts
• 安装/升级结果会返回 llmGuidance，由大模型按当前应用结构接入 web routes、mini pages 和 tabBar
• addon install/upgrade --json 只返回精简消费视图，不返回完整安装元数据、文件 hash、发布物料或数据库 id

显式接入指导：

• Addon 包根目录可以放 PROMPT.md
• PROMPT.md 不会进入发布安装包；发布时会作为版本提示词元数据保存。安装/升级后会写入 src/addons/<addon-name>/PROMPT.md，并在 src/addons/<addon-name>/meta.json 中记录 guidance.prompt.path 和 contentHash
• 安装/升级结果的 llmGuidance.prompt 会返回提示词内容；后续 addon list --json 也会读取已安装 Addon 目录中的 PROMPT.md 并返回 guidance.prompt.content
• 如果 Addon 本身就是一个 skill 资源，应在 addon.json.members 中显式声明 type: "skill"；普通 Addon 的根 PROMPT.md 只作为模型指导

升级策略：

• 先读取已安装 meta.json
• 如果受管文件被本地修改，升级会停止
• 冲突会先汇总后返回，不会写入半成品
• 普通输出会打印冲突摘要；--json 会输出 MCP/AI 可消费的结构化冲突信息

冲突 JSON 示例：

{
  "success": false,
  "code": "ADDON_INSTALL_CONFLICT",
  "message": "Addon install has 1 conflict(s)",
  "operation": "install",
  "addon": {
    "name": "approval-addon",
    "version": "1.0.0",
    "applicationType": "web"
  },
  "targetDir": "/path/to/app",
  "conflicts": [
    {
      "kind": "target_exists",
      "path": "src/pages/approval/index.tsx",
      "sourcePath": "pages/approval/index.tsx",
      "memberName": "approval-page",
      "memberType": "page",
      "message": "src/pages/approval/index.tsx already exists in target application"
    }
  ]
}

MCP 接入时可按 conflicts[].path 读取应用里的当前文件，并按 memberName / sourcePath 获取 Addon 原始内容，再交给 AI 或人工合并处理。

模板检查

命令：

amaster check route [--cwd <path>] [--routes-file <path>]
amaster check ast --stack react-vite [--cwd <path>]
amaster check type --stack <react-vite|taro> [--cwd <path>]
amaster check build --stack <react-vite|taro> [--cwd <path>]
amaster check all --stack <react-vite|taro> [--cwd <path>]