Skip to content

config-add.md

Latest commit

 

History

History
84 lines (61 loc) · 2.76 KB

config-add.md

File metadata and controls

84 lines (61 loc) · 2.76 KB

配置项扩展

触发条件

  • 新增 env var(如 DASHSCOPE_* / BAILIAN_* / NO_COLOR)
  • 给 ~/.bailian/config.json 加字段
  • 给全局 flag 加新选项(--xxx)
  • 改 config 字段优先级

配置三层来源

flag (--xxx)   ─┐
                ├─ loadConfig() 合并 ─→ Config(运行时单一对象)
env (XXX=yyy)  ─┤
                │
config 文件     ─┘
~/.bailian/config.json

优先级一般是 flag > env > config 文件 > 默认值,具体见 core/config/loader.ts。

必查清单

A. 类型定义

  • packages/core/src/config/schema.ts:
    • Config(运行时形状)加新字段
    • ConfigFile(disk 形状,snake_case)加新字段(如果允许写文件)
    • parseConfigFile() 解析新字段
    • 如果是 enum 字段,加校验

B. 加载逻辑

  • packages/core/src/config/loader.ts:loadConfig():
    • 加新字段的合并逻辑(flags.x ?? process.env.XXX ?? file.x ?? default)
    • 校验(数值范围、枚举合法性等)
    • 校验失败抛 BailianError(USAGE)

C. 全局 flag(如果加的是 flag)

  • packages/core/src/types/command.ts:GLOBAL_OPTIONS 数组
  • registry.ts 的 buildGlobalFlagLines 会自动从 GLOBAL_OPTIONS 生成 bl --help 与 reference/index.md 的全局 flag 段,无需手写
  • flag 的 type 标注(boolean / number / array),让 args.ts 正确解析
  • 改完全局 flag 后跑 pnpm --filter bailian-cli run generate:reference

D. 命令使用方

  • 用到新字段的命令文件直接读 config.xxx,不要重复解析
  • 配置展示 / 修改命令同步:
    • packages/cli/src/commands/config/show.ts 显示新字段
    • packages/cli/src/commands/config/set.ts 允许 set
    • packages/cli/src/commands/config/export-schema.ts 在 schema 输出里

E. 文档

  • README.md / README_CN.md 的 env var 表格

F. 测试

  • 单测覆盖优先级:flag > env > file
  • 校验失败抛错(非法值)
  • 默认值正确

完成后自查

# 三个来源都试一遍
node packages/cli/src/main.ts config show --output json | grep <new-field>
XXX=value node packages/cli/src/main.ts config show --output json | grep <new-field>
node packages/cli/src/main.ts config show --xxx value --output json | grep <new-field>

# 写到文件
node packages/cli/src/main.ts config set --key <key> --value <value>
cat ~/.bailian/config.json

常见漏点

  • ✗ Config 接口加字段但 loadConfig 没填,运行时永远 undefined
  • ✗ ConfigFile 用 camelCase 字段名(disk schema 应该是 snake_case)
  • ✗ 全局 flag 没标 type: "boolean",被当成需要值的 --xxx <value>
  • ✗ 加了 env var 但 README 表格没更新,用户不知道有这条
  • ✗ config show 不显示新字段,用户改了无法回查