OP CLI 指令

当前章节列出了可用于通过 OP CLI 构建插件的指令。

备注

OP CLI 会作为项目依赖安装在插件工程中。

请尽可能升级到OP CLI的最高版本，以便使用我们提供的最新功能及修复的问题。

开发者需要通过 npx 调用 CLI 的指令：npx op [command] [arguments] [options]

概览

指令名称	指令描述
init	初始化项目设置。
add	为插件工程添加「前端插槽」或「开放能力」。
packup	构建插件工程并在工程根目录下生成 `.opk` 文件，提供版本控制
login	将用于在特定环境中获取用户凭证的参数存储到 `config/local.yaml` 中。
pickteam	获取团队列表并使用团队列表中的团队信息更新配置文件，以进行本地调试或持续集成。
invoke	在本地启动插件项目并调用插件的一个或多个生命周期。
upgrade	升级 `@ones/cli-plugin` 及相关依赖到当前大版本的最新版本
scan	扫描插件工程中使用到的接口url

init

初始化项目设置。

它会在安装 npm 依赖项后自动执行，开发人员可以查看 packages.json 上的 scripts 字段以了解更多详细信息。

npx op init

add

为插件工程添加「前端插槽」或「开放能力」。

npx op add <target-type>

示例

为插件工程添加「前端插槽」或「子前端插槽」

npx op add module
npx op add sub-module

为插件工程添加「开放能力」

npx op add ability

参数

参数名称	参数描述
`target-type`	指定需要添加的内容类型，支持的类型有： `module` `sub-module` `ability`

packup

构建插件工程并在工程根目录下生成 .opk 文件，提供版本控制。

npx op packup [filename]

参数

参数名称	参数描述
`filename`	指定 `.opk` 文件的名称，默认为项目名称。

选项

选项名称	要求	选项描述
`--bump <mode>`	`@ones/cli-plugin` `v1.14.0+`	打包时提供更新插件版本号的选项，`no-modify`: 不变更版本号, `major`: 更新主版本号, `minor`: 更新次版本号, `patch`: 更新补丁号
`--release`	`@ones/cli-plugin` `v1.22.0+`	构建用于生产环境的`.opk`文件。如果不指定该选项，打包出来的`.opk`文件则只能用于开发环境

将用于在特定环境中获取用户凭证的参数存储到 config/local.yaml 中。

参数 baseURL 是协议敏感的，不同的协议类型将被视为不同的 scope。

登录成功后，CLI 会将作用域参数存储到 ~/.ones/cli-plugin.yaml 中，并被用于本地调试。

同时，如果当前项目之前从未选择过「团队信息」，此命令将尝试自动运行 npx op pickteam local。

npx op login [options] [baseURL]

参数

参数名称	参数描述
`baseURL`	指定登录的环境 URL

选项

选项名称	选项别名	选项描述
`--host-url [url]`	`-h [url]`	可选，指定用于本地调试的 host URL。在最新版本的ONES中这个可以不需要指定。
`--username <username>`	`-u <username>`	用作用户名的电子邮件地址或电话号码。
`--password <password>`	`-p <password>`	密码
`--scope [url]`	`-s [url]`	使用特定 `scope` 参数登录，默认为当前环境 URL，该选项与 `-u`、`-p` 选项互斥。

关于 `--scope` 选项

为了方便插件开发者在不同工程中使用相同或者不同环境配置的需要，在每次使用 login 指令登录成功后，CLI 会尝试在用户目录下记录登录过程中所使用的用户凭证信息。

备注

在不同的操作系统中，凭证信息存储的路径会有所区别。

Linux/macOS: ~/.ones/cli-plugin.yaml
Windows: C:\Users\YOUR_USERNAME\.ones\cli-plugin.yaml

scopes:
  https://foo.example.com:
    baseURL: https://foo.example.com
    username: foo
    password: fooPass
  https://bar.example.com:
    baseURL: https://bar.example.com
    username: bar
    password: barPass

需要注意的是，当执行 login 指令并使用 scope 选项时：

会与 -u -p 选项互斥。
如果所选择的 scope 的凭证失效，则进入交互式问答中输入新的用户凭证信息（效果等同于执行 npx op login）。

示例

进入交互式问答流程，输入登录参数。

npx op login

指定登录环境为 https://dev.ones.com 并进入交互式问答流程输入剩余的参数：hostURL, username, password。

npx op login https://dev.ones.com

指定登录环境为 https://dev.ones.com 并将 hostURL 设置为 tcp://dev.ones.com:30002，同时指定用户凭证信息，这将直接执行登录操作。

注意

关于端口：如果是docker部署的环境，端口为9006；如果是k3s|k8s部署环境，其端口为30002。

npx op login https://dev.ones.com -h tcp://dev.ones.com:30002 -u test@ones.com -p password

指定登录环境为 https://partnerdev.ones.com，但使用 https://dev.ones.com scope 下保存的用户凭证。

npx op login https://partnerdev.ones.com -h tcp://dev.ones.com:30002 -s https://dev.ones.com

pickteam

使用存储在配置文件中的用户凭证(config/local.yaml 或 config/ci-deploy.yaml)获取团队列表，并使用团队列表中的团队信息更新配置文件以用于本地调试或持续集成。

在选择团队信息之前，需要先执行 npx op login 或 npx op ci 完成登录操作。

npx op pickteam [target] [options]

参数

参数名称	参数描述
`target`	指定需要更新团队信息的目标类型配置，目标类型只能是 `local` 或 `ci`。

选项

选项名称	选项别名	选项描述
`--branch-name <branch>`	`-b <branch>`	为持续集成配置指定部署的分支名称。
`--team-uuid <uuid>`		匹配团队列表中指定的团队 UUID。
`--team-name <name>`		匹配团队列表中指定的团队名称。

备注

-b --branch-name <branch> 选项只在 target 为 ci 时生效，留空或不指定值将进入交互式问答补充分支名。

备注

当同时指定 --team-uuid 和 --team-name 参数时，只有 --team-uuid 参数会生效。

示例

1.使用存储在 config/local.yaml 中的用户凭证获取团队列表，在这之前需要先执行 npx op login 指令。

npx op pickteam local

进入交互式问答选择持续集成分支，并使用存储在 config/ci-deploy.yaml 中的分支信息中的用户凭证获取团队列表，在这之前需要先执行 npx op ci 指令

npx op pickteam ci

使用存储在 config/ci-deploy.yaml 中的 next 分支信息中的用户凭证获取团队列表，请注意分支名称区分大小写，分支名称必须与config/ci-deploy.yaml中的分支名称相同，如果没有匹配的分支名称，CLI 将抛出错误。

npx op pickteam ci -b next

使用存储在 config/local.yaml 中的用户凭证获取团队列表，获取团队列表后，CLI 将尝试选择团队 UUID 为 “T7YB134K” 的团队信息，如果没有成功匹配团队 UUID，CLI 将抛出错误。

npx op pickteam local --team-uuid T7YB134K

使用存储在 config/ci-deploy.yaml 中的 next 分支信息中的用户凭证获取团队列表，获取团队列表后，CLI 将尝试选择团队名称为 TestTeamName 的团队信息，如果没有成功匹配团队名称，CLI 将抛出错误。

npx op pickteam ci -b next --team-name TestTeamName

invoke

在本地启动插件项目并调用插件的一个或多个「生命周期」。

「流程」和「生命周期」之间的区别在于「流程」将包含多个「生命周期」。

npx op invoke [options] <target>

参数

参数名称	参数描述
`target`	指定您要调用的「流程」或「生命周期」。

可调用的「生命周期」名称

install
enable
disable
uninstall

关于生命周期，开发者可在「入门指引 - 插件生命周期」一节中了解详情。

可调用的「流程」名称

流程	包含的生命周期
`run`	`install` `enable`
`clear`	`disable` `uninstall`

选项

选项名称	选项别名	选项描述
`--mode`		调试模式，支持的类型有 `all` `backend` `frontend` 默认模式为 `all`。
`--webpack-stats-preset <level>`		指定 Webpack 日志级别，支持级别有: `errors-only` `errors-warnings` `minimal` `none` `normal` `verbose` `detailed` `summary` 默认日志级别为 `info`。
`--reinstall-plugin`		当目标环境中已安装的插件 `appid` 与当前插件工程冲突时，会尝试卸载目标环境中的插件并安装本地工程中的插件内容。
`--self-tunnel <endpoint>`		自定义的插件服务后端地址，这个地址需要能够保证ONES实例能够通过http访问你的本地插件。当CLI工具采用默认的localtunnel开源工具帮你创建的地址无法被ONES实例访问时，你可以选择自己选择稳定的隧道工具或者找你你所在公司的网络管理员以提供帮助。

信息

在ONES版本>= v3.14.150+，>= v6.1.78，>= v6.2.5+的情况下需要指定tunnel。通常你不需要刻意使用self-tunnel，只有当默认提供的tunnel网络不稳定时，你才需要使用self-tunnel来提供稳定的网络环境。

当你指定了自定义的tunnel或者默认的localtunnel地址时，你可以使用https://{tunnel地址}/healthz来检查你的插件服务是否正常。

upgrade

要求

@ones/cli-plugin
v1.14.0+

概述

升级 @ones/cli-plugin 及相关依赖到当前大版本的最新版本

npx op upgrade

scan

扫描插件工程中使用到的接口url

npx op scan [target]

要求

@ones/cli-plugin
v1.19.0+

参数

参数名称	参数描述
`target`	扫描的目标类型，支持的类型有： `api`: 插件代码中的api声明 `trigger`: 使用到的Trigger插槽

当不传入target参数时，默认同时扫描api和trigger。

选项

选项名称	选项别名	选项描述
--output	-o	扫描结果的输出文件路径，如果不指定，则仅在控制台打印扫描结果。扫描结果文件是yaml格式的

扫描与匹配规则

api

op工具会扫描插件源码中的字符串、字符串模板和字符串拼接表达式。当扫描到的字符串字面量中包含字符/时，扫描程序会认为这是一个url，并将其转换为一个由前置正则片段，url正则片段，占位正则片段和后置正则片段组成的正则表达式。

对于扫描工具漏判的情况，你可以通过@ones-api注释手动指定API：

import APIs from 'apis'

import { request } from './utils'

// @ones-api: /api/project/users/me
request(APIs.getUsers())

对于扫描工具误判的情况，你可以通过@ones-api-ignore注释手动排除API：

const Routes = () => {
  return (
    <Switch>
      {/* @ones-api-ignore */}
      <Route path="/login" component={Login} />
      {/* @ones-api-ignore */}
      <Route path="/register" component={Register} />
    </Switch>
  )
}

或者通过@ones-api-ignore-file注释手动排除整个文件的扫描：

// @ones-api-ignore-file

const Routes = () => {
  return (
    <Switch>
      <Route path="/login" component={Login} />
      <Route path="/register" component={Register} />
    </Switch>
  )
}

trigger

op工具会扫描plugin.yaml中的Trigger插槽，收集Action对应的API，并将其转化为url正则表达式

扫描完成后，op工具会将收集到的url正则表达式与扫描配置中的API集合进行正则匹配，输出匹配到的API

扫描配置

你可以通过配置文件op.config.mjs中的scan配置项来定制扫描的行为。

扫描配置结构如下：

interface ScanConfigSchema {
  roots?: string[]
  exclude?: (string | RegExp)[]
  apis?: string[]
  output?: {
    level?: 'matched' | 'all'
  }
  patternFragment?: {
    pre?: string
    placeholder?: string
    post?: string
  }
  checkIsPathLikeString?: (value: string) => boolean
}

字段名称	字段类型	默认值	描述
`roots`	`string[]`	`["web","backend"]`	要扫描的代码根目录
`exclude`	`(string｜RegExp)[]`	`[/node_modules/]`	不扫描的路径
`apis`	`string[]`	`[]`	要匹配的API集合
`output.level`	`"matched"｜"all"`	`"all"`	扫描结果的输出级别： matched: 仅输出匹配到API的扫描结果 all: 输出所有扫描结果
`patternFragment.pre`	`string`	`"(?:[^\n]*)"`	url正则表达式的前置正则片段
`patternFragment.placeholder`	`string`	`"(?:[^\n/]*)"`	url正则表达式的占位正则片段
`patternFragment.post`	`string`	`"(?:[^\n]*)"`	url正则表达式的后置正则片段
`checkIsPathLikeString`	`(value: string) => boolean`	`(value) => value.includes("/")`	判断一个字符串字面量是否是url的函数

概览​

init​

add​

示例​

参数​

packup​

参数​

选项​

login​

参数​

选项​

关于 --scope 选项​

示例​

pickteam​

参数​

选项​

示例​

invoke​

参数​

可调用的「生命周期」名称​

可调用的「流程」名称​

选项​

upgrade​

要求​

概述​

scan​

要求​

参数​

选项​

扫描与匹配规则​

api​

trigger​

扫描配置​

概览