Skip to content

auth-change.md

Latest commit

 

History

History
143 lines (111 loc) · 6.75 KB

auth-change.md

File metadata and controls

143 lines (111 loc) · 6.75 KB
Raw

鉴权扩展

触发条件

  • 增加新的鉴权域或 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
                                    └─ resolveOpenApi(sources)    → OpenAPI 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
  • openapi — 阿里云 OpenAPI 签名域,用 AccessKey ID/Secret 调用 Token Plan 等 OpenAPI
  • none — 本地命令、登录/配置类命令、无需 credential 的命令

多凭证并存

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

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

解析分工:

  • 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 > 默认
  • resolveOpenApi() — auth: "openapi" 命令;优先级 --access-key-id/--access-key-secret > ALIBABA_CLOUD_ACCESS_KEY_ID/ALIBABA_CLOUD_ACCESS_KEY_SECRET > config access_key_*。兼容读取旧字段 openapi_access_key_*,新写入只写短字段
  • 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 / kscli 硬编码;当前遗留的 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 / openapi 鉴权状态,并 mask token
  • packages/commands/src/commands/auth/logout.ts:
    • 清理范围与双凭证并存规则一致
  • 新的业务命令设置正确 auth:
    • 模型域请求 → auth: "apiKey"
    • Console Gateway → auth: "console"
    • 阿里云 OpenAPI 请求 → auth: "openapi"
    • 本地/登录/配置 → 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 ALIBABA_CLOUD_ACCESS_KEY_ID ALIBABA_CLOUD_ACCESS_KEY_SECRET
HOME=/tmp/empty pnpm -F bailian-cli exec tsx src/main.ts auth status

# flag 注入(凭证域 flag 只在对应业务命令可见,auth status 不接收)
pnpm -F bailian-cli exec tsx src/main.ts text chat --message hi --api-key sk-xxx --dry-run
pnpm -F bailian-cli exec tsx src/main.ts token-plan list-seats --access-key-id ak-xxx --access-key-secret sec-xxx --dry-run
pnpm -F bailian-cli exec tsx src/main.ts auth login --open-api --access-key-id ak-xxx --access-key-secret sec-xxx --dry-run

# env 注入
DASHSCOPE_API_KEY=sk-xxx pnpm -F bailian-cli exec tsx src/main.ts auth status
ALIBABA_CLOUD_ACCESS_KEY_ID=ak-xxx ALIBABA_CLOUD_ACCESS_KEY_SECRET=sec-xxx pnpm -F bailian-cli exec tsx src/main.ts auth status

Console 登录/网关相关改动:

pnpm -F bailian-cli exec tsx src/main.ts auth login --console
pnpm -F bailian-cli exec tsx 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 时写死产品命令,导致 kscli 等入口提示错误