modelstudioai__cli/docs/agents/config-add.md

配置项扩展

触发条件

• 新增 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 不显示新字段,用户改了无法回查