bsteam

bsteam 统一命令行入口（单入口 + 插件化）。

架构

• 核心（本包，npm 包名 @oncoding/bsteam，终端命令名 bsteam）：BaseCommand / 配置加载（cosmiconfig + profiles）/ 本地凭证存储 / Platform API client / envelope 与 table 格式化 / 共享 init 与 prerun hooks。暴露用户态 auth / context / kb / token / reimbursement / api / config / version 命令。
• 运维插件 @bsteam/cli-ops：db / seed / dev / sync 命令组，仅在 monorepo workspace 内自动加载。
• 系统命令（后续）：各业务域可继续按插件拆分；公开分发包不应携带 DB reset、seed clear、真实 sync 等运维后门。

@bsteam/cli-ops 在 monorepo 开发环境内通过 workspace sibling 自动挂载；公网安装 @oncoding/bsteam 时由于该插件不发布，CLI 会跳过插件加载，普通用户看不到运维命令。

Agent 友好原则

本 CLI 参考飞书 CLI 的三层模型，但按 bsteam 当前边界收敛：

• Shortcut / Domain 命令：用户态平台对象命令放在核心包，例如 kb list、token list、reimbursement list；本地开发验收命令如 db status、seed list 由 ops 插件提供。
• Auth 命令：auth login/status/check/scopes/list/logout 是核心能力，面向人类和 Agent 共享。
• Context 命令：context list/current/switch/rename 只管理本机 ~/.bsteam/config.json 的 context，用于在 local / staging / prod 之间命名和切换；不联网、不验证权限。
• Raw API 命令：api <METHOD> <PATH> 提供兜底访问；GET/HEAD 可直接跑，写操作必须 --dry-run 或 --yes，否则 exit 10。

所有 Agent 场景优先使用 --json，失败时读取 envelope 的 ok/error.code/error.hint，不要解析 human 输出。

开发者使用

在 monorepo 内运行：

pnpm bsteam --help
pnpm bsteam token -h
pnpm bsteam db status        # 由 @bsteam/cli-ops 提供
pnpm bsteam seed list        # 由 @bsteam/cli-ops 提供
pnpm bsteam --context staging auth status
pnpm bsteam context list
pnpm bsteam context switch staging
pnpm bsteam context rename xteam staging
pnpm bsteam config show
pnpm bsteam version
pnpm bsteam completion --shell zsh

Shell 自动补全

completion 从当前 oclif 命令表生成候选项。monorepo 内运行时会包含 workspace-only 的 ops 命令；公网安装 @oncoding/bsteam 后只包含用户态命令。

查看配置步骤：

bsteam completion
bsteam completion install --shell zsh

临时启用：

source <(bsteam completion script --shell zsh)

持久启用：

mkdir -p ~/.bsteam/completions
bsteam completion script --shell zsh > ~/.bsteam/completions/_bsteam
printf '\n# bsteam completion\nsource ~/.bsteam/completions/_bsteam\n' >> ~/.zshrc
exec zsh

支持 zsh / bash / fish。补全不会请求 Platform API；--context 从本机 ~/.bsteam/config.json 读取，--profile 使用内置 dev / staging / prod。

Auth 快速开始

CLI 采用类似 kubectl 的 context config：一个配置文件同时保存环境、用户、token 和当前 context。默认路径：

~/.bsteam/config.json

个人中心「安全与 CLI Token」先生成个人访问令牌（PAT），再复制 CLI 登录命令。也可以手动把 PAT 从 stdin 写入指定 context：

printf '%s' "$BSTEAM_PLATFORM_TOKEN" \
  | bsteam auth login --context staging --api-url https://api.example.com --domain baisui-innovation --token-stdin

bsteam --context staging auth status
bsteam --context staging auth check foundation:members:read

Context 与 Domain 边界

context 是本机环境别名，回答“这条命令连哪个 bsteam 环境”。典型值是 local、xteam、staging、prod。domain 是平台安全域，回答“登录后默认在哪个业务安全边界内操作”。典型值是 baisui-innovation 或服务端 UUID。

个人中心「安全与 CLI Token」复制出的 bsteam auth login 命令必须遵守：

• --context 默认使用部署环境名：优先取前端 build env VITE_BSTEAM_ENV_NAME，未配置时从前端/API 域名安全推导。
• --domain 才使用当前安全域 code/ID；不要把 domain code 或 UUID 拼进 context。
• context rename 只改本机别名，不改 cluster、user、token 或默认 domain。

登录多个环境后，可以用 context 命令管理本机默认目标，不需要重新输入 token：

bsteam context list
bsteam context current
bsteam context switch staging
bsteam context switch --context staging
bsteam auth status

context switch 只修改本机 currentContext，不会请求 Platform API。切换后用 auth status 实时确认该 token、API 和权限仍然有效。一次性覆盖仍然使用全局 --context <name>，不会改变默认 context。

如果登录后想把环境别名改成本机习惯用法，可以只重命名 context，不重写 cluster、user 或 token：

bsteam context rename xteam staging

也可以手写 config，适合 CI、Agent 沙箱和一次性 staging 验收：

{
  "apiVersion": "bsteam.io/v1",
  "kind": "Config",
  "currentContext": "staging",
  "clusters": {
    "staging": {
      "server": "https://api.example.com"
    }
  },
  "users": {
    "alice": {
      "token": "bst_pat_xxx"
    }
  },
  "contexts": {
    "staging": {
      "cluster": "staging",
      "user": "alice",
      "domain": "baisui-innovation"
    }
  }
}

访问解析优先级：

1. --api-url / --token / --domain / --as-user-id
2. BSTEAM_PLATFORM_API_URL / BSTEAM_PLATFORM_TOKEN / BSTEAM_ACTIVE_DOMAIN_ID / BSTEAM_IMPERSONATE_USER_ID
3. --config / BSTEAM_CONFIG + --context / BSTEAM_CONTEXT 指向的 context config；未显式指定 context 时使用 currentContext
4. 旧版 ~/.bsteam/credentials.json（兼容读取）
5. 本地 profile 默认值，例如 http://localhost:13001

--domain 可传安全域 UUID 或更适合人和 Agent 使用的 domain_code，例如 baisui-innovation。配置文件以 0600 权限写入；CLI 输出只展示脱敏 token，config show 也不会打印明文 token、用户资料或本地权限快照。身份和权限以 auth status 实时查询服务端为准。PAT 明文只在创建时显示一次，服务端只保存 hash、prefix、last4、过期、吊销和最近使用时间。当前 MVP 暂未接 OS keychain，后续如要面向公网分发，应再补 keychain provider。

管理员测试权限时，不要获取目标用户的 CLI Token。复用管理后台同一套“切换身份”机制：先查目标用户的稳定 id，再给任意平台命令加 --as-user-id <platform_user_id>。服务端只允许 platform_super_admin 使用该 header，并继续走正式权限和审计链路：

bsteam --context staging auth users --search "张三"
bsteam --context staging --as-user-id <platform_user_id> auth status --json
bsteam --context staging --as-user-id <platform_user_id> token list --domain baisui-innovation

如果某个 context 的日常操作都在同一个安全域，可以把默认安全域写进 context，之后不用每条命令都传 --domain：

bsteam --context staging auth domain list
bsteam --context staging auth domain switch baisui-innovation
bsteam --context staging auth users --search "张三"

常用命令：

bsteam auth login --context staging --api-url https://api.example.com --token-stdin
bsteam auth token create --name "MacBook CLI" --expires-in-days 30
bsteam auth token list
bsteam auth token revoke <token-id> --yes
bsteam auth ssh-key add
bsteam auth ssh-key list
bsteam context list
bsteam context switch staging
bsteam context current
bsteam context rename xteam staging
bsteam --context staging auth domain list
bsteam --context staging auth domain switch baisui-innovation
bsteam auth users --search "张三"
bsteam auth list
bsteam --context staging auth status
bsteam --config ./bsteam.config.json --context prod api GET /api/v1/auth/session
bsteam auth logout --context staging

知识库

知识库命令全部走 Platform HTTP API，适合公网 npm 安装后的普通用户和 Agent 使用，不依赖本地仓库或 DB：

bsteam kb list
bsteam kb get product-handbook
bsteam kb create --slug product-handbook --name "Product Handbook" --visibility members_only --dry-run
bsteam kb update product-handbook --description "团队产品手册" --dry-run
bsteam kb tree product-handbook
bsteam kb file product-handbook README.md
bsteam kb git product-handbook
bsteam kb acl grant product-handbook --principal-type user --principal-id user_123 --permission write --path "docs/*" --dry-run
bsteam kb acl list product-handbook
bsteam kb share create product-handbook --path "docs/intro.md" --expires-in-hours 24 --dry-run
bsteam kb delete product-handbook --yes

kb file 默认读取渲染/元数据接口；需要原始内容时传 --raw。二进制文件应使用 --output <path>，避免把不可读内容写入终端。知识库 Git 使用当前账号的 SSH 公钥鉴权；如果 git clone 返回 Permission denied (publickey)，先执行 bsteam auth ssh-key add 上传本机 .pub 公钥。

我的 Token 与报销

token 对应 AI Token Vault 的“我的 Token”，默认列表只展示脱敏值。创建或更新密钥时优先从 stdin 或 --data-file 输入，避免明文进入 shell history：

printf '%s' "$OPENAI_API_KEY" \
  | bsteam token create --api-key-stdin --platform-code openai --platform-name OpenAI --models gpt-4.1,gpt-4.1-mini

bsteam token list
bsteam token list --owner-name "张明"
bsteam token get <token-id>
bsteam token operations
bsteam token precheck --rows-file ./tokens.import.json
bsteam token reveal <token-id> --yes
bsteam token delete <token-id> --yes
bsteam token permissions list
bsteam token permissions replace --policies-file ./token-policies.json --dry-run

token get 只返回脱敏详情和行级权限，不会打印明文。token reveal 是唯一会显式打印 AI Token 明文的命令，必须传 --yes。dry-run 和错误预览会自动脱敏 api_key / token / secret 等字段。

Token 报销命令同样只走服务端权限和审计链路：

bsteam reimbursement list
bsteam reimbursement create --payment-date 2026-06-23 --category team-ai-lab --platform-code openai --amount 120.50 --status submitted --invoice-file ./invoice.pdf --voucher-file ./payment.png --dry-run
bsteam reimbursement update <id> --status approved --invoice-file ./invoice.pdf --dry-run
bsteam reimbursement delete <id> --yes
bsteam reimbursement permissions list
bsteam reimbursement permissions replace --policies-file ./reimbursement-policies.json --dry-run

--category 支持已登记类别或新增类别；--invoice-file / --voucher-file 可重复传入或用逗号分隔。旧版 --invoice-required 仅保留为兼容参数，不作为主要使用方式展示。

Raw API

bsteam api GET /api/v1/auth/session
bsteam api GET /api/v1/platform/authz/capabilities --json
bsteam api POST /api/v1/account/preferences --data '{"density":"compact"}' --dry-run
bsteam api POST /api/v1/account/preferences --data '{"density":"compact"}' --yes

写操作没有 --dry-run 或 --yes 时返回 exit code 10，供 Agent/HITL 拦截。

对外 API（供插件作者）

插件仅通过包顶层入口 import：

import {
  BaseCommand,
  ExitCodes,
  loadConfig,
  getProfile,
  formatTable,
  createEnvelope,
  platformApiGet,
  resolvePlatformApiOptions,
  getCredential,
  getContextCredential,
} from '@oncoding/bsteam';

完整公共 API 见 src/index.ts。

高风险门禁

由 prerun hook 检查命令 description 是否含「高风险」字样，结合当前 --profile 的 dangerousOpsAllowed 拦截。具体门禁参数（如 db reset 的三道门禁）由各命令自行实现。

被拒绝时返回 exit code 10（ExitCodes.DANGEROUS_REFUSED）。

Exit Codes

| Code | 含义 | |------|------| | 0 | 成功 | | 1 | 一般错误 | | 2 | 参数错误 | | 3 | 配置错误 | | 4 | 网络错误 | | 5 | 依赖缺失 | | 6 | 未认证 / token 无效 | | 10 | 高风险操作被拒绝 | | 130 | 用户中断（Ctrl+C） |

包结构

src/
├── base-command.ts        # BaseCommand 抽象类
├── config/
│   ├── exit-codes.ts      # ExitCodes 枚举
│   ├── config-loader.ts   # cosmiconfig 5 层合并
│   └── profiles.ts        # dev / staging / prod
├── auth/
│   ├── context-config.ts   # ~/.bsteam/config.json contexts/users/clusters 存取与脱敏
│   └── credential-store.ts # 旧版 ~/.bsteam/credentials.json 兼容读取
├── http/
│   └── platform-api.ts    # Platform API client + auth resolution
├── formatters/
│   ├── envelope.ts        # JSON envelope 协议
│   └── table.ts           # 终端表格
├── hooks/
│   ├── init.ts            # TTY 检测、env 默认值
│   └── prerun.ts          # 高风险门禁
├── commands/
│   ├── api.ts
│   ├── auth/
│   │   ├── login.ts
│   │   ├── status.ts
│   │   ├── check.ts
│   │   ├── scopes.ts
│   │   ├── users.ts
│   │   ├── domain/
│   │   ├── ssh-key/
│   │   ├── list.ts
│   │   ├── logout.ts
│   │   └── token/
│   ├── kb/
│   │   ├── acl/
│   │   └── share/
│   ├── token/
│   │   └── permissions/
│   ├── reimbursement/
│   │   └── permissions/
│   ├── completion/
│   ├── version.ts
│   └── config/show.ts
└── index.ts               # 唯一公共导出
bin/
├── argv.js                 # 前置全局 flags 归一化（支持 bsteam --config x --context y auth status）
├── run.js                 # 生产入口
└── dev.js                 # ts-node 开发入口

验证

(cd backend && pnpm --filter @oncoding/bsteam build)
(cd backend && pnpm --filter @oncoding/bsteam test)
(cd backend && pnpm --filter @oncoding/bsteam pack:check)
node bin/run.js --help
node bin/run.js --version