BytePlan Dev CLI

BytePlan Dev CLI 是面向 BytePlan 平台低代码开发的命令行工具，提供登录鉴权、多环境切换、模型/字段管理、预算表单 AI 设计、页面发布、数据字典、LOV、业务流脚本、任务、SQL 查询、知识库只读检索、日志查询以及 Codex/Claude Code skills 安装能力。

CLI 默认输出 JSON，适合人工操作，也适合在自动化脚本或 AI Agent 工作流中调用。

安装

需要 Node.js 22.5 或更高版本（认证元数据使用内置 SQLite）。

npm install -g byteplan-dev-cli

本仓库提供三个等价命令入口：

byteplan-dev-cli -h
bp-dev -h
bpd -h

本地开发时可直接运行：

node src/cli.js -h

快速开始

首次使用可以用账号密码登录：

bp-dev login -u 18256485741 -p '<password>'
# 更安全：密码从 stdin 读取，不出现在命令参数中
printf '%s\n' '<password>' | bp-dev login -u 18256485741 --password-stdin
# 工号登录：tenantCode 会作为 /base/login 的 query 参数发送
bp-dev login --tenant-code refond -u bp_10001 -p '<password>'

也可以不提供账号密码，使用设备码登录：

bp-dev login

CLI 会输出验证地址和用户码。请在浏览器中确认授权，CLI 随后自动完成登录。

登录后查看配置：

bp-dev config

常用查询：

bp-dev account list
bp-dev user info
bp-dev app
bp-dev app switch <appCodeOrId>
bp-dev model list -n "订单"
bp-dev model columns -m <modelId>
bp-dev page list
bp-dev form -h

执行任何不熟悉的命令前，建议先看帮助：

bp-dev model -h
bp-dev model create -h
bp-dev page publish -h

登录与环境

CLI 会把 access token 和 refresh token 存入 SQLite 的 byteplan_tokens 表；环境、用户、当前账号、token 索引和过期时间统一保存在同一数据库的 byteplan_environments、byteplan_accounts 与 byteplan_settings 表中。应用内会通过 BYTEPLAN_DATABASE_PATH 自动传入服务端数据库路径；独立运行 CLI 时默认使用 ~/.byteplan/byteplan-client.db。

登录到指定环境：

bp-dev login -e dev
bp-dev login -e uat
bp-dev login -e test

内置 test 环境使用 https://testapp.byteplan.com。其他自定义环境需要提供 baseurl：

bp-dev login -e custom --baseurl https://custom.example.com

设备码登录流程：

1. CLI 调用 /oauth2/device_authorization 申请设备码；线上网关返回 404 时自动回退到 /base/oauth2/device_authorization。
2. CLI 输出 verificationUriComplete 和 userCode，等待用户在浏览器中确认。
3. CLI 按服务端返回的 interval 无 Token 轮询 /device/authorization 或 /base/device/authorization；状态变为 verified 后，再调用配套的 /login 换取 token。
4. access/refresh token 写入 SQLite 的 byteplan_tokens 表；若部署没有状态接口，则兼容回退到 RFC 8628 的直接 token 轮询。
5. access token 到期时，CLI 会使用 refresh token 自动换取新 token，并更新 SQLite；只有 refresh token 失效或刷新失败时才需要重新登录。

账号密码登录流程：

1. bp-dev login -u <phone> -p <password> 使用 grant_type=password 调用 /base/login。
2. CLI 默认先调用 /base/util/getEnvironmentInfo，根据 encryptPasswordFlag 决定是否获取 /base/util/get/publicKey 并使用 RSA PKCS#1 加密密码。
3. 可以用 --encrypt-login 或 --no-encrypt-login 覆盖服务端返回的加密策略。
4. 密码只用于本次登录请求，不会写入 SQLite、.env 文件或 CLI 输出；成功后的 access/refresh token 与设备码登录使用相同的 SQLite 存储。

工号登录在上述流程基础上增加 --tenant-code <tenantCode>；例如 bp-dev login --tenant-code refond -u bp_10001 -p '<password>' 会请求 /base/login?tenantCode=refond&t=...。也可以通过 BP_TENANT_CODE 环境变量提供 tenantCode。

环境管理：

bp-dev env list
bp-dev env switch dev
bp-dev env current

查看当前环境已授权的账号：

bp-dev account list
bp-dev -e dev account list

命令只从 SQLite 读取当前环境、当前账号以及账号列表；-e 只对本次查询生效，不会切换持久化的活动环境，也不会回退读取 ~/.byteplan/.env*。

也可以在单条命令上临时指定环境：

bp-dev -e uat model list

支持的环境变量：

| 变量 | 说明 | |---|---| | BP_USER | 可选，账号/手机号；与 BP_PASSWORD 同时存在时可作为一次性账号密码登录输入 | | BP_PASSWORD | 可选，账号密码；仅用于登录请求，不写入 SQLite、.env 或 CLI 输出 | | BP_TENANT_CODE | 可选，工号登录时的 tenantCode；与 BP_USER、BP_PASSWORD 一起使用 | | BP_ENV | 环境名，默认 uat | | BP_BASE_URL | 当前环境自定义服务地址 | | ACCESS_TOKEN | 可选，由外部安全凭证提供方注入的 access token | | BP_DEVICE_CLIENT_ID / BP_DEVICE_CLIENT_SECRET / BP_DEVICE_SCOPE | 可选，覆盖设备客户端配置 | | BP_PASSWORD_CLIENT_ID / BP_PASSWORD_CLIENT_SECRET / BP_PASSWORD_SCOPE | 可选，覆盖账号密码登录客户端配置 |

命令总览

| 命令 | 说明 | |---|---| | config | 查看当前登录配置、环境、token 状态 | | login | 通过账号密码或设备码登录 BytePlan，并安全保存 token | | account | 列出当前环境已授权账号并标记当前账号 | | env | 多环境列表、切换、当前环境查询 | | user / tenant | 当前用户、租户列表与租户切换 | | app | 查询可用应用 | | model | 模型、字段、视图模型、模型事件流管理 | | form | 预算表单 AI 创建、配置、保存、目录查询和表单搜索 | | physical-scheme / table | 查询物理方案文件夹、创建物理表方案 | | page | 页面创建、授权、源码保存、tag 版本管理 | | datasource | 数据源查询 | | sql | SQL 查询配置创建与执行 | | dict | 数据字典创建、查询、加值 | | lov | LOV 创建、更新、字段列配置 | | coding | 编码规则列表和明细查询 | | task | 脚本任务创建、参数、运行、实例查询 | | hierarchy | 维度、层级和值查询，以及维度/维值创建与更新 | | issue | 分阶段查询本地知识库（只读） | | logs | Grafana Loki 日志查询 | | component | 本地扫描 byte-builder PC 组件元信息、属性、事件、方法 | | skill | 安装、查看、卸载随包提供的 skills |

知识库检索

知识库为全局共享清单，不分环境、租户或应用。CLI 只提供读取命令，不会自动新增知识：

# 先用命令、错误码或症状关键词检索候选摘要
bpd -e uat issue search --query "Token Expired"

# 没有命中时，让 AI 分页查看标题目录
bpd -e uat issue list --page 1 --size 20

# 选定一个候选后才读取完整内容
bpd -e uat issue get --id <issueId>

search 和 list 不返回完整内容；只有 get 返回所选知识详情，避免把整个知识库放入 AI 上下文。

数据分析

bp-dev analysis list
bp-dev analysis list -q "库存"
bp-dev analysis list --model-code ABD_INVENTORY_B -t cross --scope private
bp-dev analysis create --name "供应链库存分析" --model-code ABD_INVENTORY_B
bp-dev analysis get --report-id 2091868638562930690 --tenant-id 1598132771284447234
bp-dev analysis update --report-id 2091868638562930690 --x-axis product_id --y-axis warehouse_id --indicators on_hand_qty,available_qty,allocated_qty,in_transit_qty --chart-type column-1-0
bp-dev analysis update --report-id 2091868638562930690 --x-axis product_id --y-axis warehouse_id --indicators on_hand_qty --date-precision snapshot_date=yearMonthDay
bp-dev analysis get --report-id 2091868638562930690
bp-dev analysis get -i 2091868638562930690 --tenant-id 1598132771284447234

-q/--query 会搜索分析名称、编码以及模型名称、编码，结果支持 --page、--size 分页。

analysis get 返回指定分析的完整配置，包括模型字段、坐标轴、指标、数据源和图表配置。--tenant-id 可用于校验返回详情属于当前租户。

analysis create 固定创建当前租户的私有基础分析；文件夹和模型名称可自动解析，成功返回 created: true、reportId 和可编辑详情页 previewUrl。随后必须用 analysis get 查询 dimInfos，再执行 analysis update 配置轴。

analysis update 的 --x-axis 行维和 --indicators 指标为必填，--y-axis 列维与 --name 可选。轴参数使用字段编码，多个字段用逗号分隔，也可传 JSON 字符串数组。表格图会把字段写入 chartSetting.axisInfo；柱状图、折线图等图片图表会把主横轴和主指标写入 chartSetting.chartAttr.xAxis/yAxis，--y-axis 作为分面列维保存在 facetAxis，避免网页端出现空的横轴/纵轴配置。--chart-type 只支持当前租户已开放的网页端图表键（如 column-1-0、pie-0-2、line-0-1）和基础类型别名，未开放的图表键会被拒绝，并将预览键写入 chartSettingSave.biMiniConfig。日期字段可以用 --date-precision field=yearMonthDay 和 --date-format field=dataFormatByTl 修改网页端写入 biAxisConfigData 的日期配置。命令会校验 DIM/INDICATOR 类型、日期字段类型和值、保留未指定图表配置，并重新读取服务端详情；只有名称、轴、图表类型和日期配置真实落盘时才返回 verified: true。

完整新建流程为：analysis create → analysis get → analysis update → analysis get。基础创建后任何步骤失败都应保留并复用已有 reportId，不要重复创建。

模型与字段

bp-dev model list
bp-dev model list -n "待办"
bp-dev model list -c ABD_TODO
bp-dev model multidim-list -c BGTT_DEMO1 -n "DEMO1" -p 0 -s 10
bp-dev model columns -m <modelId>
bp-dev model field-config

创建模型或新增字段：

bp-dev model create -f ./model.json
bp-dev model create-multidim -c BGTT_DEMO1 -n "DEMO1" --fields '[{"columnName":"name","dimHierarchyCode":"HIER_ACCOUNT_01"}]'
bp-dev model multidim-fields -m <modelId> -d <definitionId>
bp-dev model multidim-fields-save -m <modelId> -d <definitionId> --fields '[{"columnName":"name","columnDesc":"名称","dimCode":"ACCOUNT"}]'
bp-dev model column-add -m <modelId> -c <fieldCode> -n "字段描述" -t TEXT
bp-dev model column-update -m <modelId> -c <fieldCode> -n "新字段描述"
bp-dev model column-add -m <modelId> -c file -n "附件" -t EXT_FILE
bp-dev model column-add -m <modelId> -c clac1 -n "计算字段1" -t EXT_CALCULATE --cal-sql "select t.amount_type"

model create 返回值会包含 previewUrl，格式为 https://dev.byteplan.com/#/data/dbm_ms_model_bb/data_physical_model_setting/{modelId}（实际域名跟随当前 CLI 环境）。

创建多维模型：

bp-dev model create-multidim -c BGTT_DEMO1 -n "DEMO1" --fields '[{"columnName":"name","dimHierarchyCode":"HIER_ACCOUNT_01"},{"columnName":"account","columnDesc":"科目","dimCode":"ACCOUNT"}]'

该命令需要 modelCode、modelName 和 fields；appCode=grid、modelType=2、tableCreateType=MANUAL 由 CLI 固定提交。fields 是新增字段数组，每项需要 columnName，并在 dimCode、dimHierarchyCode 中二选一；columnDesc 可选，默认使用 columnName。传 dimHierarchyCode 时，CLI 会自动查出 dimHierarchyId、dimHierarchyName 和对应维度的 dimCode；传 dimCode 时只提交维度编码，不传层级字段。模型创建接口会自动生成 id、version_number、created_date、created_by、last_updated_date、last_updated_by、amount、data_id、duplicate_id、order_number 这十个内置字段，创建命令的 --fields 中不要重复传入；CLI 创建流程只批量提交新增字段，提交成功后自动同步模型结构。

所有新增字段的 columnType 固定为 VARCHAR，columnTypeLength 固定为 200，命令不提供修改参数。--fields 也可以传 @/path/to/fields.json。查询已有多维模型字段：

bp-dev model multidim-fields -m <modelId> -d <definitionId>

查询命令固定使用 modelType=2、page=1、size=200，并调用 /data/api/modelSetting/query。

独立创建或更新多维模型字段：

bp-dev model multidim-fields-save -m <modelId> -d <definitionId> --fields '[{"columnName":"name","columnDesc":"名称","dimCode":"ACCOUNT"},{"columnName":"department","columnDesc":"部门","dimHierarchyCode":"HIER_ALLOC_01"}]'
bp-dev model multidim-fields-save -m <modelId> -d <definitionId> --fields @./fields.json

该命令先查询当前字段，再按 columnName 匹配：已存在的自定义字段会更新，不存在的字段会创建；新建字段必须传 dimCode 或 dimHierarchyCode，更新已有字段可以只传 columnName 和 columnDesc。层级编码会自动解析为维度和层级元数据，传 dimCode 更新时会清除层级绑定。新建字段的类型和长度始终固定为 VARCHAR、200。批量提交成功后自动调用 /data/api/modelSetting/structure/sync。

分页查询多维模型列表：

bp-dev model multidim-list
bp-dev model multidim-list -c BGTT_DEMO1 -n "DEMO1" -p 0 -s 10

该命令调用 /data/api/model/query，appCode=grid 固定不变，支持 modelCode、modelName、page（0-based）和 size 参数。

DECIMAL/AMOUNT 字段的 --precision 会同时写入 fieldProps.precision 和顶层 decimalLength。

附件字段使用 EXT_FILE 类型；CLI 会按平台约定自动提交 checkType=FILE、checkObject=default、isTableField=N。

计算字段 EXT_CALCULATE 使用 SQL 子查询，当前模型表别名固定为 t，只能用 t 引用当前表字段，可关联其它表；CLI 会把明文 SQL 自动 base64 编码到 fieldProps.calSql，并按平台约定提交 checkType=CALCULATE、isTableField=N。

创建模型关联关系（类似外键）：

bp-dev model relations -m <modelId>
bp-dev model children -c <modelCode>

bp-dev model relation-add -m <detailModelId> \
  --main-model <headerModelId> --main-name "主模型名称" \
  --main-column id --ref-column header_id

model relations 查询模型父子关系及关联字段，对应接口 /data/api/physical/model/pk/info/query。 model children 查询指定父模型下的子模型；默认输出摘要，追加 --full 可输出完整子模型定义。 其中 -m 是当前/引用字段所在模型，对应接口 modelId；--ref-column 是当前模型里的引用字段，对应 refColumn；--main-model、--main-name、--main-column 对应被引用主模型的 mainModelId、mainModelName、mainRefColumn。--ref-model 默认等于 -m，删除策略 --delete-type 支持 CASCADE 级联删除、NOT 不能删除、DIRECT 直接删除，默认 NOT。

模型事件流：

bp-dev model events -m <modelId>
bp-dev model event-detail -e <eventId>
bp-dev model event-project -m <modelId> -E <eventId>
bp-dev model event-pull
bp-dev model event-create ...
bp-dev model event-scripts -e <eventId>
bp-dev model event-update ...
bp-dev model event-execute ...

视图模型：

bp-dev view create ...
bp-dev view sql ...
bp-dev view columns ...
bp-dev view col ...
bp-dev view sort-add ...

具体参数以 bp-dev view <subcommand> -h 为准。

维度、层级和值

查询维度和层级：

bp-dev hierarchy dims
bp-dev hierarchy list
bp-dev hierarchy dim-values -d <dimId>
bp-dev hierarchy values -c <dimHierarchyCode>

创建维度时只需传编码和名称，CLI 会自动补上 公共_ 前缀，并固定提交其他维度字段：

bp-dev hierarchy create -c bbb -n bbb

也可以在同一条 CLI 命令中创建维度和多个维值。维度创建成功后，CLI 会使用返回或回查得到的 dimId 调用维值创建接口：

bp-dev hierarchy create \
  -c bbb -n bbb \
  --value-code aaa --value-name aaaa \
  --value-code ccc --value-name cccc

--value-code 和 --value-name 必须成对传入；如果维度编码已存在，CLI 会复用该维度并继续创建维值。

维度和维值创建完成后，可以在该维度下创建层级定义：

bp-dev hierarchy hierarchy-create -d bbb -n "产品层级"
bp-dev hierarchy hierarchy-create -d bbb -n "产品层级" -c HIER_bbb_01
bp-dev hierarchy hierarchy-value-add -d bbb -i <dimHierarchyId> -c aaa
bp-dev hierarchy hierarchy-create-with-values -d bbb -n "产品层级" \\
  --values '[{"code":"1","name":"产品"},{"code":"1-1","name":"配件","parentCode":"1"}]'

该命令会按维度编码解析 dimId、dimName，默认层级编码为 HIER_<dimCode>_01，并固定提交层级排序、层级类型、版本控制和层级数等页面默认值。层级创建后，可用 hierarchy-value-add 把当前维度下的维值挂到层级；不传 --parent-value-id 时添加根节点，传入父维值 ID 时添加子节点，nodeLevel 默认分别为 1 和 2。CLI 会按维值编码自动解析维值 ID、名称和租户 ID。每次添加或更新层级值都会自动执行“进入编辑状态（mdmDimHierarchyController/lock）→挂载→发布（cof）→完成锁定（unLock）”，不需要单独执行锁定命令。

hierarchy-create-with-values 将“准备维度/维值、创建层级、挂载层级值”合并为一个命令。--values 接收 JSON 数组，支持扁平的 parentCode/parentValueCode，也支持嵌套 children；已存在的维度和维值会复用，缺失的维度值会自动创建。维度不存在时需额外传 --dim-name。批量挂载只执行一次“进入编辑状态→全部挂载→发布→完成锁定”流程。

单独创建或更新内置目标维度下的维值时，只需传维值编码和名称：

bp-dev hierarchy dim-value-create -c aaa -n aaaa
bp-dev hierarchy dim-value-update -c aaa -n aaaa

也可以用 --dim-id 指定其他维度。更新命令会先按维值编码查询真实的 dimValueId、版本号和当前记录字段，不再固定某一条维值记录。创建和更新维值时，CLI 会自动完成 L（进入编辑）→ 业务请求 → C（发布），不需要单独执行编辑状态命令。

物理方案

物理方案命令直接封装物理表定义接口。命令会使用当前 CLI 环境、租户和登录凭证；不需要也不应传浏览器里的 cookie、Bearer token 或页面追踪头。

查询当前租户可见的物理方案文件夹：

bp-dev physical-scheme folder-list
bp-dev physical-scheme folder-list --title "数据"
# 等价别名
bp-dev table folders

不传 --title 时调用文件夹树接口；传入 --title 时调用搜索接口，返回匹配的文件夹和物理方案。搜索结果数组中的 type 可能是 folder、table 或 virtualView，完整对象分别位于 folder 或 table 字段中。

创建物理表方案：

bp-dev physical-scheme create -f ./physical-scheme.json

physical-scheme.json 使用接口字段名：

{
  "folderId": "1647865501068759042",
  "appCode": "appbuild",
  "tableName": "mstest_demo1",
  "tableDesc": "demo",
  "tableAliasCode": "t",
  "dsId": "1476488572560576514",
  "generationType": "AUTO_INCREMENT",
  "defSql": "",
  "ptmTableColumns": [
    {
      "defDetailId": 1,
      "columnName": "id",
      "hcfColumnType": "HCF-NUMBER",
      "columnDesc": "主键id",
      "pkColumn": "Y",
      "nullAble": "N",
      "columnSort": 1,
      "autoIncrement": true
    }
  ]
}

也可以使用 --json 传入同一 JSON，或用 --folder-id、--app、--table-name、--table-desc、--table-alias、--datasource-id、--generation-type、--def-sql 和 --columns 覆盖配置。defType 固定为 table，enabledFlag 固定为 Y。

PC 组件属性查看

component 命令不需要登录。CLI 包内默认带一份组件参数快照，直接运行即可查询； 如果你传了 --builder-root 或设置 BP_BUILDER_ROOT，则会实时扫描 byte-builder 前端项目里的 src/pages/byte-builder/component/pc/*/export.js 和对应 setter，查看组件 type、默认属性、 可拖放父子关系、事件、方法以及能识别到的属性项。

bp-dev component list
bp-dev component info table
bp-dev component props tabs-pane
bp-dev component list --builder-root /path/to/byte-builder-front
bp-dev component info table --builder-root /path/to/byte-builder-front
bp-dev component props tabs-pane --builder-root /path/to/byte-builder-front

也可以用环境变量指定项目根目录：

export BP_BUILDER_ROOT=/path/to/byte-builder-front
bp-dev component list
bp-dev component props table

更新内置快照：

node scripts/update-component-manifest.js /path/to/byte-builder-front

说明：简单数组式 setter 提取较准；复杂 React setter 会尽量提取 Form.Item name，输出里会标注来源。输出中的 dataSource 会标明当前结果来自内置快照还是实时扫描。

页面与前端 Widget

页面查询与创建：

bp-dev page list
bp-dev page list -a <appCodeOrId>
bp-dev page list --app-id <appId> -m <modelCode> -n "页面名" --usage PC --size 10
bp-dev page auth-pages -m <modelCode>
bp-dev page detail -p <pageId>
bp-dev page assign-function -p <pageId> -f <functionId>
bp-dev page templates
bp-dev page templates --id default
bp-dev page templates --id list-page
bp-dev page lowcode validate --config-file dsl.json
bp-dev page lowcode create -a <appCode> -m <modelCode> -n "低代码页面" --config-file dsl.json
bp-dev page project --template default --params '{"app":"sup","model":"ABD_ORDER","name":"订单页面"}'
bp-dev page project --template list-page --params '{"app":"sup","model":"ABD_ORDER","name":"订单列表"}'
bp-dev page project --template detail-page --params '{"app":"sup","model":"ABD_ORDER","name":"订单详情"}'
bp-dev page project --template ./my-page-template --params @page-params.json
bp-dev page project --template ./my-page-template --param title=概览 --param pageSize=20
bp-dev page create-source -a <appCode> -m <modelCode> -n "页面名" --source-dir .
bp-dev page publish -p <pageId> -m <modelCode> --app-code <appCode>

page auth-pages 根据模型编码查询运行时 GET 接口被分配到的页面 ID。CLI 会先按模型编码查询模型并解析应用编码，再拼接 authCode。模型编码会转为小写：

{appCode}-get-/api/online/{modelCode lowercase}/get

例如 caba + LOWCODETEST_CABA_PROJECT_VIEW 会请求 authCode=caba-get-/api/online/lowcodetest_caba_project_view/get，输出 pageIds 数组。

page templates 返回内置模板声明的参数、路径和生成命令。page project 的 --template 可以是内置模板 ID，也可以是自定义模板目录。每个模板通过 template.json 声明参数，通过 generator.js 实现生成逻辑；CLI 只解析通用的 --params、可重复的 --param key=value 和输出目录选项，不包含模板专属参数或历史兼容参数。生成结果固定在当前工作目录的 pages/ 下，不会自动创建、上传或发布线上页面。page create-source 会校验项目根目录和构建产物，再上传 <source-dir>/dist/widget.umd.js。

新建页面支持 sourceCode 项目流程和 PC 低代码 DSL 流程。page lowcode validate 是本地校验命令，不访问远程；page lowcode create 从经过校验的 DSL 创建新页面；page lowcode list/detail/master-detail 根据模型元数据生成标准页面。历史兼容命令 page create-lowcode、page create-list 不再注册。

低代码组件参考源码和静态组件清单随 bp-lowcode-dsl skill 发布。需要刷新源码快照时，在仓库根目录执行 node packages/byteplan-code-cli/scripts/update-lowcode-reference.js <byte-builder 项目根目录>。

自定义模板最小清单示例：

{
  "id": "dashboard",
  "name": "Dashboard",
  "generator": "./generator.js",
  "parameters": {
    "title": { "type": "string", "required": true },
    "pageSize": { "type": "number", "default": 20 },
    "showChart": { "type": "boolean", "default": true }
  }
}

参数类型支持 string、number、boolean、array、object。生成器导出 generatePageProject(context) 或默认函数；context 提供已校验的 params、模板信息、输出选项、BytePlan 查询服务以及受 pages/ 目录约束的项目生成辅助方法。

源码与版本：

bp-dev page tag-info -t <tagId>
bp-dev page source -p <pageCode>
bp-dev page source -p <pageCode> --tag 1.0.1
bp-dev page source -p <pageCode> --raw > widget.js   # 源码页
bp-dev page source -p <pageCode> --raw > dsl.json    # 低代码页
bp-dev page tag-create -p <pageId> -m <modelCode> --source-dir . --tag 1.0.1
bp-dev page tag-publish -p <pageId> -t <tagId>

严格 tag 模式：

• 不允许直接覆盖已有 tag
• 改源码或 lowcode DSL 都必须创建新 tag
• 同一个版本号不能保存两次

lowcode 页面建议工作流：

# 新页面：先生成或编辑普通 JSON DSL，再本地校验
bp-dev page lowcode validate --config-file dsl.json
bp-dev page lowcode create -a <appCode> -m <modelCode> -n "页面名" --config-file dsl.json

# 已有页面：读取线上 DSL，修改后创建新 tag
bp-dev page source -p <pageCode> --raw > dsl.json
# 编辑 dsl.json
bp-dev page lowcode validate --config-file dsl.json
bp-dev page tag-create -p <pageId> -m <modelCode> --config-file dsl.json --tag 1.0.1

page tag-create --source-dir 会继承当前线上版本配置后替换源码产物，避免模型配置丢失；如果当前版本配置已异常，可用 --base-tag <tag> 指定正常旧版本作为底稿。page tag-create --config-file 会优先读取配置里的 pageKind 和 curModelCode/modelCodes[0]；必要时也可以显式传 --page-kind lowcode -m <modelCode>。

如果页面是列表页下的详情页，page create-source 支持通过 --function-id <主页面functionId> 指定父页面。

字典与 LOV

数据字典：

bp-dev dict list
bp-dev dict create -a <appCode> -c <dictCode> -n "字典名"
bp-dev dict create -a <appCode> -c <dictCode> -n "字典名" --items '[{"value":"1","name":"启用"},{"value":"0","name":"停用"}]'
bp-dev dict items -i <dictId>
bp-dev dict item-add -i <dictId> -v <value> -n "选项名"

LOV：

bp-dev lov list -a <appCode>
bp-dev lov create -a <appCode> -c <lovCode> -n "LOV名" --sql "select id, code, name from ..."
bp-dev lov cols -i <lovId>
bp-dev lov col-update -i <lovId> --field name --display "名称"
bp-dev lov update -i <lovId> -n "新名称"

编码规则：

bp-dev coding rules -c SYS_DEPARTMENT -n "部门编码" --type-id 1625695801874407426
bp-dev coding details -i 1631218900132057090

任务、SQL 和日志

任务：

bp-dev task list
bp-dev task create ...
bp-dev task project -i <taskId>
bp-dev task pull -d ./task-project
bp-dev task push -d ./task-project
bp-dev task params -i <taskId>
bp-dev task param-add ...
bp-dev task run -i <taskId>
bp-dev task instances -i <taskId>
bp-dev task instances --trace-id <traceId>

SQL 查询：

bp-dev sql list --code <queryCode>
bp-dev sql get --id <regulationId>
bp-dev sql exec -s "select * from <tableName>" --size 20

日志查询：

bp-dev logs -s 1h -g "DEBUG_MARKER"
bp-dev logs trace <traceId> -s 30m
bp-dev logs trace <traceId> -s 30m -f "dual"

日志平台凭证使用应用“环境变量”页面中的 LOG_PLATFORM_ACCOUNT 和 LOG_PLATFORM_PASSWORD；账号和密码均从应用环境变量表读取，也可通过同名进程环境变量临时覆盖。

Skills

仓库内置一个统一的 BytePlan playbook，可复制安装到 Claude Code skills 目录：

bp-dev skill list
bp-dev skill install
bp-dev skill install bp-playbook
bp-dev skill remove bp-playbook

默认安装目标是 ~/.claude/skills，可用 --target 或 CLAUDE_SKILLS_DIR 覆盖。

当前内置 skill：

| Skill | 说明 | |---|---| | bp-playbook | BytePlan CLI、建模、页面、脚本、迁移、调试与项目交付的统一入口 | | bp-lowcode-dsl | 参考 byte-builder PC 组件源码生成、校验和创建低代码 DSL 页面 |

bp-playbook/SKILL.md 只负责识别任务和路由；具体知识按主题放在 references/，可执行工具放在 scripts/，模板和示例放在 assets/。 执行任务时只加载相关主题，避免把整套平台文档一次性塞入上下文。

开发

安装依赖：

npm install

查看 CLI：

node src/cli.js -h
node src/cli.js skill list --src skills --target /tmp/bp-skills-test

运行测试脚本：

npm test

当前 npm test 是占位脚本，只输出 No tests yet。

项目结构

.
├── src/
│   ├── cli.js              # CLI 入口与全局选项
│   ├── api/                # BytePlan API 封装
│   └── commands/           # commander 命令注册
├── skills/bp-playbook/     # 统一入口、主题知识、脚本与示例资产
├── templates/              # CLI 运行时项目模板（不依赖 skill 目录）
├── package.json
└── README.md

注意事项

• CLI 输出统一为 JSON；失败时通常返回 { "error": true, "message": "..." }。
• 绝大多数业务命令需要先登录；skill 命令是本地文件操作，不需要登录 BytePlan。
• 写操作确认机制在代码中保留，但当前处于关闭状态，写命令会直接执行。
• 命令参数以 bp-dev <command> -h 和 bp-dev <command> <subcommand> -h 输出为准。