BytePlan Code CLI

使用 BytePlan Code CLI 查询 BytePlan 平台数据、管理登录上下文、生成本地项目或安装随 CLI 发布的 skills。CLI 默认输出 JSON；不熟悉参数时，先运行 byteplan-code-cli <command> -h。

每次任务前：先查看远端有哪些技能（必做）

每次执行新的 BytePlan 任务前，先查看当前用户在当前环境下有哪些远端 skill：

byteplan-code-cli skill list --remote

拿到列表后：

对照本次任务的诉求，判断列表里是否存在能直接完成该任务的远端 skill（看 name 和 description）。

有匹配项时，先读取它的详细内容，再按该 skill 的说明执行任务：

byteplan-code-cli skill detail --id <skillId>
# 或
byteplan-code-cli skill detail --code <skillCode>

没有匹配项，再按下面的通用流程处理。

不要跳过这一步：远端 skill 由用户在平台上维护，随时可能新增或更新，不要凭记忆假设有哪些技能。若命令报错或列表为空，如实说明后再继续。

每次任务前：检查并自动升级 CLI（必做）

每次执行新的 BytePlan 任务前，必须先检查 CLI 是否有新版本：

byteplan-code-cli --version
npm view byteplan-code-cli version

两者一致：直接继续任务。
npm 上的版本更高：立即自动升级，无需向用户确认：
```
npm i -g byteplan-code-cli@latest
byteplan-code-cli --version
byteplan-code-cli skill install --force
```
升级后必须用 skill install --force 同步内置 skills（这是升级流程的一部分，视为已获用户授权），然后继续任务。

支持的功能

登录与上下文：login、config、account、env、user、tenant、app、browser-url。
模型与元数据：model、view、datasource、dict、lov、hierarchy。
数据与报告：通过 sql tables/columns 查看数据结构，用 sql exec 执行只读 SELECT/WITH 查询；通过 report docs 查看格式，并用 report save 新建或更新洞察画布报告。
页面：查询页面、版本和源码，生成本地页面项目。
开发辅助：component 查看 PC 组件元信息。
Skill 管理：skill list、skill install、skill remove。

平台命令默认只读，明确的平台写入例外是 report save 和 sql create/update 的保存查询管理。登录、环境或租户切换以及本地项目、skill 文件操作仍可使用。以 byteplan-code-cli -h 和各级 -h 的实时输出为准。

安装 CLI 和 Skills

只有在用户要求安装 CLI，或完成当前 BytePlan 任务确实需要 CLI 且本机尚未安装时，执行下面的安装流程。

检查 Node.js 和 npm：
```
command -v node
node --version
command -v npm
npm --version
```
byteplan-code-cli 要求 Node.js >=22.5.0。如果没有 npm、没有 Node.js，或 Node.js 版本过低，先通过当前系统已有的 Node 版本管理器或 Node.js 官方安装包安装/升级 Node.js；npm 会随 Node.js 一起安装。安装后重新运行以上四条命令。不要在 Node.js 缺失时尝试单独用 npm 安装 npm。
安装最新版 CLI，并仅在命令成功退出后继续：
```
npm i -g byteplan-code-cli@latest
```
如果出现全局目录权限或 PATH 错误，停止并报告具体错误；优先修正 Node 版本管理器或 npm 全局目录配置，不要擅自使用 sudo。
验证 CLI，然后安装包内全部 skills：
```
byteplan-code-cli --version
byteplan-code-cli skill install
```
子命令是单数 skill，不是 skills；可执行命令是 byteplan-code-cli，不是 byeplan-code-cli。bp-code 和 bpc 是等价的短别名。
安装完成后显示 skill 状态和 CLI 版本：
```
byteplan-code-cli skill list
byteplan-code-cli --version
```
向用户汇报 skill list 中状态为 copy 或 link 的已安装 skills，以及最终版本号。如果安装输出含 skipped 或后续列表含 missing，不要宣称全部安装成功，应说明未安装项和原因。

默认 skill 目标目录是 ~/.claude/skills。如果使用方不是 Claude Code，安装时显式指定其实际 skills 目录，例如 Codex：

byteplan-code-cli skill install --target "${CODEX_HOME:-$HOME/.codex}/skills"
byteplan-code-cli skill list --target "${CODEX_HOME:-$HOME/.codex}/skills"

仅安装指定 skill 时，把名称追加到 skill install 后；需要覆盖目标目录中的同名 skill 时，必须先确认覆盖符合用户意图，再使用 --force。