mirror of
https://github.com/modelstudioai/cli.git
synced 2026-09-14 19:49:23 +08:00
85 lines
2.8 KiB
Markdown
85 lines
2.8 KiB
Markdown
|
# 配置项扩展
|
||
|
|
|
||
|
|
## 触发条件
|
||
|
|
|
||
|
|
- 新增 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
|
||
|
|
- [ ] 校验失败抛错(非法值)
|
||
|
|
- [ ] 默认值正确
|
||
|
|
|
||
|
|
## 完成后自查
|
||
|
|
|
||
|
|
```sh
|
||
|
|
# 三个来源都试一遍
|
||
|
|
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` 不显示新字段,用户改了无法回查
|