BytePlan Code CLI

BytePlan Code CLI 是面向 BytePlan 平台查询和分析的命令行工具。数据查询统一通过 sql 管理和执行只读 SQL；平台写入仅保留洞察画布 report save 和保存 SQL 查询管理，认证、上下文切换及本地文件操作仍可使用。

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

完整命令、参数和示例见 CLI 命令文档。

安装

需要 Node.js 22.5 或更高版本。

npm install -g byteplan-code-cli

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

byteplan-code-cli -h
bp-code -h
bpc -h

本地开发时可直接运行：

node src/cli.js -h

快速开始

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

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

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

bp-code login

CLI 会优先使用 verificationUriComplete 授权地址自动打开系统默认浏览器，并同时输出授权地址和用户码作为手动入口。请在网页中确认授权，CLI 随后自动完成登录。

登录后查看配置：

bp-code config

常用查询：

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

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

bp-code model -h
bp-code sql exec -h
bp-code report save -h

登录与环境

CLI 将环境、用户、当前账号、token 索引和过期时间等非敏感元数据保存在当前 CLI 自己的 JSON 配置中，默认路径为 ~/.byteplan/config.json。可以用 BYTEPLAN_CONFIG_PATH 指定配置文件，或用 BYTEPLAN_CONFIG_DIR 指定配置目录。认证链路不会读取或写入项目外部的 SQLite 数据库，也不会读取旧的 .env/envs.json 元数据。

凭证目录可以通过 BYTEPLAN_CREDENTIALS_DIR 覆盖。默认位置为：macOS ~/Library/Application Support/byteplan-cli，Linux $XDG_DATA_HOME/byteplan-cli 或 ~/.local/share/byteplan-cli，Windows %LOCALAPPDATA%/BytePlan/byteplan-cli。macOS 优先把主密钥保存在系统钥匙串（Service=byteplan-cli、Account=master.key），钥匙串不可用时回退到凭证目录中的 master.key.file；凭证文件本身使用 AES-256-GCM 加密。

登录到指定环境：

bp-code login -e dev
bp-code login -e uat
bp-code login -e test
bp-code login -e prod

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

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

设备码登录流程：

1. CLI 调用 /oauth2/device_authorization 申请设备码；线上网关返回 404 时自动回退到 /base/oauth2/device_authorization。
2. CLI 优先使用 verificationUriComplete（缺失时使用 verificationUri）自动打开系统默认浏览器，同时输出授权地址和 userCode，等待用户在网页中确认；若浏览器未自动打开，可复制输出的地址手动访问。
3. CLI 按服务端返回的 interval 无 Token 轮询 /device/authorization 或 /base/device/authorization；状态变为 verified 后，再调用配套的 /login 换取 token。
4. access/refresh token 写入独立的加密凭证存储；若部署没有状态接口，则兼容回退到 RFC 8628 的直接 token 轮询。
5. access token 到期时，CLI 会使用 refresh token 自动换取新 token，并更新加密凭证；只有 refresh token 失效或刷新失败时才需要重新登录。

账号密码登录流程：

1. bp-code 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. 密码只用于本次登录请求，不会写入 JSON、SQLite、.env 文件或 CLI 输出；成功后的 access/refresh token 与设备码登录使用相同的加密凭证存储。

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

环境管理：

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

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

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

命令从 CLI JSON 配置读取当前环境、当前账号以及账号列表，并从加密凭证存储检查 token 状态；-e 只对本次查询生效，不会切换持久化的活动环境，也不会回退读取 ~/.byteplan/.env*。

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

bp-code -e uat model list

支持的环境变量：

| 变量 | 说明 | |---|---| | BP_USER | 可选，账号/手机号；与 BP_PASSWORD 同时存在时可作为一次性账号密码登录输入 | | BP_PASSWORD | 可选，账号密码；仅用于登录请求，不写入 JSON、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 | 查询模型、字段和关系 | | page | 查询页面、版本和远程源码；可生成本地页面项目 | | datasource | 数据源查询 | | sql | 保存 SQL 查询管理与只读 SQL 执行 | | dict | 查询数据字典及字典项 | | lov | 查询 LOV、运行时值和字段列 | | hierarchy | 层级和值查询 | | component | 本地扫描 byte-builder PC 组件元信息、属性、事件、方法 | | report | 新建或更新洞察画布报告，自动编码 configData | | skill | 安装、查看、卸载随包提供的 skills |

平台安全策略：公开 CLI 默认只读，例外是 report save 和保存 SQL 查询的 sql create/update。sql exec 与 sql update 在请求平台前仅允许 SELECT/WITH；其他平台创建、更新、发布、运行或触发类命令仍不注册。本地 project、pull、skill install/remove 只影响本地文件或 CLI 配置，不写入 BytePlan 业务数据。

数据查询（SQL）

sql 命令提供保存查询、表字段元数据和动态查询能力。sql exec 会验证 SQL，并且只接受 SELECT 或 WITH 开头的查询；分页由平台注入，SQL 中不要自行添加 LIMIT。

bp-code sql list --code <queryCode>
bp-code sql get --id <regulationId>
bp-code sql tables --datasource-id <dataSourceId>
bp-code sql columns --table <tableName>
bp-code sql create -c <queryCode> --desc "查询说明"
bp-code sql update --id <regulationId> -c <queryCode> -s "SELECT * FROM <tableName>"
bp-code sql exec -d <datasourceName> -s "SELECT * FROM <tableName>" --size 20
bp-code sql exec -d <datasourceName> -s "SELECT period, SUM(stock) AS stock_sum FROM <tableName> GROUP BY period" --size 100

完整参数以 bp-code sql <subcommand> -h 为准。

洞察画布报告

report save 对齐 Web 端 /ai/api/report-center/saveReport 请求。参数文件中的 configData 保持普通 JSON 对象，CLI 会自动按 UTF-8 转为 Base64；更新已有报告时如果不传版本号，CLI 会先查询最新的 versionNumber。

{
  "title": "经营分析洞察",
  "configData": {
    "addedDashboards": [
      { "id": "chapter-1", "title": "经营概览", "children": [] }
    ]
  }
}

CLI 按真实查询接口结构只保存 configData.addedDashboards。图表的 type/config/data/report 等字段位于 addedDashboards[].children；对话会话、上传文件、分析参数及其他运行态字段都会在请求前移除。

完整字段和 12 种图表配置见 addedDashboards 数据结构。

# 新建
bp-code report save -f report.json

# 更新；自动查询最新 versionNumber
bp-code report save -i <reportId> -t "更新后的标题" -f report.json

保存成功后输出 reportId、当前环境对应的 previewUrl、操作类型和接口原始响应。例如 dev 环境：

{
  "reportId": "2091927997226807297",
  "previewUrl": "https://dev.byteplan.com/#/ai/ai_report/ai_report?path=report_detail&reportId=2091927997226807297",
  "operation": "create",
  "result": "2091927997226807297"
}

模型与字段

bp-code model list
bp-code model list -n "待办"
bp-code model list -c ABD_TODO
bp-code model columns -m <modelId>
bp-code model field-config

查询模型关联关系：

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

model relations 查询模型父子关系及关联字段，对应接口 /data/api/physical/model/pk/info/query。 model children 查询指定父模型下的子模型；默认输出摘要，追加 --full 可输出完整子模型定义。

视图模型：

bp-code view sql -m <viewModelId>
bp-code view columns -m <viewModelId>

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

PC 组件属性查看

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

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

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

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

更新内置快照：

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

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

页面与前端 Widget

页面查询与本地项目生成：

bp-code page list
bp-code page list -a <appCodeOrId>
bp-code page list --app-id <appId> -m <modelCode> -n "页面名" --usage PC --size 10
bp-code page templates
bp-code page templates --id default
bp-code page templates --id list-page
bp-code page project --template default --params '{"app":"sup","model":"ABD_ORDER","name":"订单页面"}'
bp-code page project --template list-page --params '{"app":"sup","model":"ABD_ORDER","name":"订单列表"}'
bp-code page project --template detail-page --params '{"app":"sup","model":"ABD_ORDER","name":"订单详情"}'
bp-code page project --template ./my-page-template --params @page-params.json
bp-code page project --template ./my-page-template --param title=概览 --param pageSize=20

page templates 返回内置模板声明的参数、路径和生成命令。page project 的 --template 可以是内置模板 ID，也可以是自定义模板目录。每个模板通过 template.json 声明参数，通过 generator.js 实现生成逻辑；CLI 只解析通用的 --params、可重复的 --param key=value 和输出目录选项。生成结果固定在当前工作目录的 pages/ 下，不会创建、上传或发布线上页面。

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

{
  "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-code page tag-info -t <tagId>
bp-code page source -p <pageCode>
bp-code page source -p <pageCode> --tag 1.0.1
bp-code page source -p <pageCode> --raw > widget.js   # 源码页
bp-code page source -p <pageCode> --raw > dsl.json    # 低代码页

字典与 LOV

数据字典：

bp-code dict list
bp-code dict items -i <dictId>
bp-code dict count

LOV：

bp-code lov list -a <appCode>
bp-code lov get -i <lovId>
bp-code lov values -c <lovCode>
bp-code lov cols -i <lovId>

Skills

仓库内置多个按任务拆分的 BytePlan Skill，可复制安装到 Claude Code skills 目录：

bp-code skill list
bp-code skill list --remote
bp-code skill detail --code <skillCode>
bp-code skill detail --id <skillId>
bp-code skill install
bp-code skill install bp-analytics-delivery
bp-code skill remove bp-analytics-delivery

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

skill list 默认列出本地 bundled skill；加 --remote 会调用 GET /ai/api/skill/list 查询当前用户的远端 skill。skill detail 调用 GET /ai/api/skill/detail，支持 --id 或 --code，需要先登录。

以 bp-code skill list 的实时结果为准。常用 Skill：

| Skill | 说明 | |---|---| | bp-analytics-delivery | 查询现有模型数据并保存洞察画布报告 | | bp-page-creation | 生成、修改和构建本地页面项目，不远端发布 |

Skill 与公开 CLI 使用同一安全边界：数据查询统一使用 sql，SQL 仅允许 SELECT/WITH， 保存查询和执行前都会调用平台验证。需要已移除的远端 创建、更新、运行或发布能力时，Skill 只能交付本地规格或项目并明确外部协调项。

开发

安装依赖：

npm install

查看 CLI：

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

运行测试脚本：

npm test

测试覆盖 API、命令帮助、只读命令策略和 Skill 命令策略。

项目结构

.
├── src/
│   ├── cli.js              # CLI 入口与全局选项
│   ├── api/                # BytePlan API 封装
│   └── commands/           # commander 命令注册
├── skills/                 # 按任务拆分的 Skill 与共享参考资源
├── templates/              # CLI 运行时项目模板（不依赖 skill 目录）
├── package.json
└── README.md

注意事项

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