鉴权扩展

触发条件

增加新的鉴权域或 token 来源(env / config / flag / 文件)
调整 API Key / Console token 解析优先级
改 bl auth login / auth status / auth logout 流程
改 runtime 对 command auth 的 gating 或 credential 注入

鉴权链路

argv flags ─┐
env var   ──┼─ buildSources(flags) ─┐
config    ──┘                       │
                                    ├─ buildSettings(sources) → ctx.settings
                                    │
                                    ├─ resolveApiKey(sources)     → model-domain Client
                                    └─ resolveConsole(sources)    → console-domain Client

defineCommand({ auth }) → runtime/authStage → ctx.client → command.run(ctx)

当前 command 鉴权域(AuthRequirement):

apiKey — DashScope / OpenAI-compatible 模型域,用 API key 与 model base URL
console — Bailian Console Gateway,用 console access token + region/site/switchAgent/workspace
none — 本地命令、登录/配置类命令、无需 credential 的命令

双凭证并存（API Key + Console）

~/.bailian/config.json 可同时保存 api_key 与 access_token。登录任一种方式不得删除另一种:

bl auth login --api-key ... 只更新 api_key / base_url
bl auth login --console 只更新 access_token 以及回调携带的 console 作用域字段
bl auth logout --console 只清 access_token
bl auth logout 清 api_key + access_token

解析分工:

resolveApiKey() — auth: "apiKey" 命令;优先级 --api-key > DASHSCOPE_API_KEY > config api_key
resolveModelBaseUrl() — model base URL;优先级 --base-url > DASHSCOPE_BASE_URL > config base_url > REGIONS.cn
resolveConsole() — auth: "console" 命令;当前 token 来自 config access_token,region/site/switchAgent 来自 flag > config > 默认
describeAuthState() — auth status / banner / telemetry 使用的只读快照

命令不要直接解析 token、env 或 config。业务请求统一走 ctx.client;登录/配置命令通过 ctx.authStore() / ctx.configStore() 的窄接口操作落盘。

必查清单

A. core 层(类型 + 解析)

packages/core/src/types/command.ts:
- 如新增鉴权域,扩展 AuthRequirement
- 更新 credentialFlagDefs() 暴露该域可见的 flag
- 必要时新增 *_AUTH_FLAGS
packages/core/src/auth/types.ts:
- 新增 credential 类型 / source / scope 字段
packages/core/src/auth/resolver.ts:
- 新增或调整 resolver,保持优先级注释清晰
- 新增/调整 resolver hint 时保持产品无关,不要新增 bl / rag 硬编码;当前遗留的 bl auth login hint 如被触碰,迁到 runtime enhanceHint
packages/core/src/auth/store.ts:
- 如果新方式需要持久化,扩展 AuthStore / AuthPersistPatch
packages/core/src/config/schema.ts:
- ConfigFile 加 disk 字段(snake_case)
- Settings 加运行时字段(如果命令需要读取)
packages/core/src/config/loader.ts:
- buildSources() / buildSettings() 把 flag/env/file 读到正确层

B. runtime 层

packages/runtime/src/create-cli.ts:
- parse flags 时纳入新的全局/凭证域 flag
- globalFlags 与 ownFlags 分流正确
packages/runtime/src/middleware.ts:authStage:
- 根据 command.auth 解析 credential 并注入 ctx.client
- settings.dryRun 下是否允许缺 credential 的策略明确
packages/runtime/src/error-handler.ts:
- AUTH hint 增强使用 binName,不要硬编码 bl
- URL 从 packages/runtime/src/urls.ts import

C. command 层

packages/commands/src/commands/auth/login.ts:
- 新增/调整登录 flag 与流程
- 持久化只走 ctx.authStore().login(...)
packages/commands/src/commands/auth/status.ts:
- 分别显示 model / console 鉴权状态,并 mask token
packages/commands/src/commands/auth/logout.ts:
- 清理范围与双凭证并存规则一致
新的业务命令设置正确 auth:
- 模型域请求 → auth: "apiKey"
- Console Gateway → auth: "console"
- 本地/登录/配置 → auth: "none"

D. 用户面文档

README.md / README.zh.md "Authentication" 段落
skills/bailian-cli/reference/ 通过 pnpm run sync:skill-assets 重建

E. 测试

packages/cli/tests/e2e/auth.e2e.test.ts 增加新方式的 happy / failure 路径
mask token 的输出格式不变(避免泄漏)
如调整 resolver 优先级,补 core/runtime 单测覆盖 flag > env > file

完成后自查

# 各种凭证组合
unset DASHSCOPE_API_KEY DASHSCOPE_ACCESS_TOKEN
HOME=/tmp/empty node packages/cli/src/main.ts auth status

# flag 注入
node packages/cli/src/main.ts auth status --api-key sk-xxx

# env 注入
DASHSCOPE_API_KEY=sk-xxx node packages/cli/src/main.ts auth status

Console 登录/网关相关改动:

node packages/cli/src/main.ts auth login --console
node packages/cli/src/main.ts usage stats --dry-run --output json

常见漏点

✗ 加了新 token 来源但忘了改 resolver 优先级,实际不生效
✗ ConfigFile / Settings 加字段但 parseConfigFile 或 buildSettings 没读
✗ auth login 写成功但 auth status 不识别(两边走的 storage path 不一致)
✗ token mask 显示完整 token,日志泄漏
✗ auth: "console" 命令误用 apiKey 域,config 只有 API key 时会把 sk-... 发到网关
✗ 新增 core resolver hint 时写死产品命令,导致 rag 等入口提示错误

5.5 KiB Raw Blame History Unescape Escape