Skip to content

config-add.md

Latest commit

 

History

History
84 lines (61 loc) · 3.01 KB

config-add.md

File metadata and controls

84 lines (61 loc) · 3.01 KB
Raw

配置项扩展

触发条件

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

配置三层来源

flag (--xxx)   ─┐
                ├─ buildSources() + buildSettings() ─→ Settings(命令读取面)
env (XXX=yyy)  ─┤
                │
config 文件     ─┘
~/.bailian/config.json

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

必查清单

A. 类型定义

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

B. 加载逻辑

  • packages/core/src/config/loader.ts:
    • buildSources() 如需新增来源,把 flag/file/env 纳入 sources
    • buildSettings() 加新字段的合并逻辑(flags.x ?? process.env.XXX ?? file.x ?? default)
    • 校验(数值范围、枚举合法性等)
    • 校验失败抛 BailianError(USAGE)

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

  • packages/core/src/types/command.ts:GLOBAL_FLAGS
  • packages/runtime/src/registry.ts 会自动从 GLOBAL_FLAGS 生成 root help;tools/generate-reference.ts 会生成 reference/index.md 的全局 flag 段
  • flag 的 type 标注(switch / boolean / number / array / string),让 packages/runtime/src/args.ts 正确解析
  • 改完全局 flag 后跑 pnpm --filter bailian-cli run generate:reference

D. 命令使用方

  • 用到新字段的命令文件直接读 ctx.settings.xxx,不要重复解析 env/config
  • 配置展示 / 修改命令同步:
    • packages/commands/src/commands/config/show.ts 显示新字段
    • packages/commands/src/commands/config/set.ts 的 VALID_KEYS / KEY_ALIASES / description 允许 set

E. 文档

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

F. 测试

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

完成后自查

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

# 写到文件(会改用户 HOME,必要时先用临时 HOME)
pnpm -F bailian-cli exec tsx src/main.ts config set --key <key> --value <value>
cat ~/.bailian/config.json

常见漏点

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