@bluefocus-ai/btp-cli

BTP 绩效平台命令行工具：在终端完成登录、目标规划、目标共识与绩效评估，不依赖浏览器。

安装与运行

无需克隆仓库，直接用 npx 运行：

npx -y @bluefocus-ai/btp-cli --help

也可以全局安装后使用 btp 命令：

npm install -g @bluefocus-ai/btp-cli
btp --help

本地开发时在 cli/ 目录使用 pnpm：

pnpm install
pnpm build
node dist/cli.js --help

pnpm test           # 单元测试（全部打桩到本地 mock server）
pnpm typecheck      # 类型检查
pnpm check:pack     # 校验 npm tarball 必需资产且不包含源码/测试

命令

BTP="npx -y @bluefocus-ai/btp-cli"

$BTP login                 # 手机号 + 短信验证码登录（交互输入）
$BTP login --phone <手机号> --code <验证码>   # 非交互
$BTP logout                # 清除本地登录凭据
$BTP whoami                # 显示当前身份与凭据有效期

$BTP cycles                # 列出可见的绩效周期
$BTP me                    # 显示本人绩效信息
$BTP review list [--cycle <perfId>] [--json]
$BTP review fill <targetId> --text "自评内容" --score 90
$BTP review fill --from ./reviews.yaml

$BTP plan list [--cycle <perfId>] [--json]                            # 目标规划（录入）
$BTP plan add --type <key_indicators|top_tasks> --dimension "维度" --description "描述" --weight 30
$BTP plan edit <flowId> [--weight 40] [--description "..."]
$BTP plan rm <inputTargetId> [--yes]
$BTP plan history <flowId> [--json]

$BTP consensus show [--cycle <perfId>] [--json]     # 目标共识
$BTP consensus submit [--yes]                       # 冻结当前草稿为新组合
$BTP consensus agree [--yes]
$BTP consensus reject [--yes]

$BTP result [--cycle <perfId>] [--json]             # 绩效结果（只读）

$BTP skill path            # 输出随包分发的 skill 目录绝对路径

cycles / me / review list / plan list / consensus show / plan history / result 默认输出人类可读表格，加 --json 输出单个 JSON 文档（stdout 只放数据，提示与错误走 stderr）。

cycles 分别标识哪些周期当前「可用于录入」与「可用于自评」。只读查询默认取最新可见周期（不套写入窗口）；写入命令在满足阶段窗口的周期里取最新，多周期时建议先 cycles 再显式 --cycle。plan list 同时输出目标标识 flowId（跨版本不变，供 plan edit / plan history）与版本标识 inputTargetId（指向当前版本，供 plan rm）。

写入校验与阶段窗口

• 自评：内容非空且不超过 1000 字，自评分 0-100 且不可清空；提交前会校验目标属于本次要写的周期。
• 目标规划：新建只允许 key_indicators / top_tasks；维度 ≤512 字、描述 ≤1000 字、权重为 5 的倍数且 ≤100；core_values 目标只能改描述、不可删除。
• 目标共识：提交组合要求目标非空、权重齐全、合计正好 100%、core_values 恰好 1 条且权重 10%、单条权重为 5 的倍数。agree / reject 针对最近一次已提交组合，不做草稿权重校验。
• 阶段窗口：自评 [PERFORMANCE_STARTED, PERFORMANCE_LOCK_STAFF)；目标新建/删除 [PERFORMANCE_STARTED, PERFORMANCE_SUBMITTED)；目标修改、组合提交与表态 [PERFORMANCE_STARTED, PERFORMANCE_LAST_CHECK)。越窗或阶段不可识别时 CLI 本地拒绝，不发起请求。

包内容与 skill

npm pack 产物只包含运行所需资产：dist/、skills/、README.md 与 CHANGELOG.md（package.json、LICENSE 等由 npm 约定保证的文件除外），不含 src/、tests/ 与 tsconfig.json。

配套的 agent skill 与 CLI 同包、同版本分发，来源位置是 cli/skills/btp-cli/；全局安装后可执行 btp skill path 取得它的绝对路径。

要让 agent 自动发现 skill，可安装 Skills Market 私有技能：

npx blueai-skills@latest add cmmsyj3m30000awfa62safkc1/btp-cli

批量填写文件格式

reviews:
  - targetId: "361129863970419595"
    text: |
      多行自评内容
    score: 95

校验规则：自评内容不能为空且不能超过 1000 字、自评分必须是 0-100 的数字、目标标识不能重复、reviews 不能为空。任何一条校验不通过都会整批拒绝，不会进入提交流程。提交按顺序逐条进行，任一条失败立即停止并报告已成功与失败的条目。

退出码

• 0：成功
• 1：参数/业务校验失败，或一般运行失败（网络错误、服务端错误、响应结构异常、文件解析失败等）
• 2：鉴权失效且自动刷新失败，需要重新执行 btp login

两个必须知道的平台约束

1. 同一账号只有一个会话（单会话）。

任何一次新登录都会立即吊销该账号此前全部会话，access 与 refresh 一起失效。因此：

• CLI 登录会把你在浏览器上的会话顶下线，反之亦然；本工具不支持与浏览器会话并存。
• btp login 会在登录前给出提示；遇到会话被吊销时 CLI 会提示重新登录并以退出码 2 结束。
• btp logout 只清除本地凭据，不会吊销服务端会话。

2. refresh_token 是一次性的。

刷新会轮换出新的 token 对，旧值立即失效。因此 CLI 做了两层串行：进程内复用同一次刷新、跨进程用文件锁互斥；拿不到锁时会重新读取磁盘凭据，而不是重复消费 refresh token。请避免在多个终端同时高频调用本工具。

凭据与卸载

• 凭据文件：~/.blueai/secrets.json，目录 0700、文件 0600，原子写入。会话存放在其中的独立字段 blueai-btp-cli.session，不覆盖同文件里其他工具（如 blueai-skills-cli）写入的键；btp logout 也只会移除本工具这个字段。
• token 不会出现在命令输出或日志中。
• 卸载：先执行 btp logout（未全局安装时用 npx -y @bluefocus-ai/btp-cli logout）清掉会话字段，再执行 npm uninstall -g @bluefocus-ai/btp-cli；确认 ~/.blueai/ 下没有其他工具在使用时，才连同目录一起删除。
• 服务地址默认指向 prac 环境；可用环境变量 BTP_BASE_URL 覆盖。凭据与签发它的服务地址绑定，切换地址后必须重新 btp login，旧地址的凭据不会被发送到新地址。

本期不做

飞书授权登录、周报素材集成、团队/上级视角（批量代表态、上级评分）、本人绩效结果表态、GitHub Actions 自动发版与 provenance。