config.yaml支持锚点复用与base→env→override三级合并策略，通过&定义资源锚点、*引用复用，并按优先级覆盖字段，避免硬编码冗余和环境误覆盖。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用Qoder时发现配置参数未按预期生效、环境切换异常或同一字段在不同场景下表现不一致，则可能是由于config.yaml与JSON配置文件中语法规范、类型约束或加载优先级未被准确理解。以下是针对Qoder核心配置文件config.yaml与JSON环境设置的参数详解：
一、config.yaml中锚点复用与层级合并机制
Qoder解析器遵循YAML 1.2标准，支持锚点(&)与别名(*)实现跨段落配置复用，并结合base→env→override三级合并策略控制字段覆盖行为，避免硬编码冗余与环境误覆盖。
1、在config.yaml顶部定义通用资源配置锚点：resources: &default_limits memory: "512Mi" cpu: "200m"。
2、在服务模块中通过api_service: 。
3、确保base.yml仅含基础字段（如log_level、max_retries），env/prod.yml仅覆盖必要项（如database.url: "${DB_URL}"）。
4、override.local.yml用于临时调试，其字段将最终覆盖前两级配置，但不会写入版本控制。
二、JSON配置中键名拼写与数据类型强制校验
Qoder在加载JSON配置时执行严格schema匹配：任意键名错位、布尔值大小写错误或数值型字段加引号，均导致整块配置被跳过，而非静默降级。
1、所有布尔字段必须使用小写true/false，禁止使用"true"、True或1。
2、数值型字段不可包裹双引号，"timeout": "30"必须修正为"timeout": 30。
3、嵌套对象末尾禁止多余逗号，多行JSON中最后一项后不得出现逗号。
4、路径类字段统一使用正斜杠且不以/结尾，"model_dir": "models/qwen"为合法，"models/qwen/"为非法。
三、环境变量注入与安全兜底机制
Qoder支持${VAR_NAME}语法注入系统级环境变量，使敏感信息脱离配置文件；若变量未定义，默认保留原始占位符字符串而非报错，需主动校验有效性。
1、操作系统中导出变量须全大写并仅含字母与下划线：export QODER_API_KEY="sk-xxx"。
2、YAML或JSON中对应位置使用占位符：auth: { api_key: "${QODER_API_KEY}" }。
3、小写变量名（如qoder_api_key）或含短横线（QODER-API-KEY）将无法被识别。
4、启动前执行qoder-cli doctor --env-check可批量验证所有${}引用变量是否存在。
四、混合加载时JSON与YAML字段映射一致性保障
当Qoder同时加载JSON主配置与YAML扩展配置时，同语义字段（如http_timeout、log_level）必须键名完全一致、单位统一，否则以最后加载文件为准，易引发隐式覆盖。
1、将核心参数（max_retries、log_level、http_timeout）在JSON中定义为基准版本，YAML中仅通过相同键名覆盖。
2、确认两文件中时间单位统一为毫秒，禁止JSON中用"3000"而YAML中用"3s"。
3、数组类字段默认采用追加策略，非替换；若需清空重置，须在base.json中显式设为[]。
4、字段缺失时，Qoder不自动填充默认值，必须在base层完整声明所有必需字段。
五、安全模式下危险标签与注释处理规则
Qoder启用安全模式后禁用JSON注释（//或/* */）及YAML中潜在危险标签（如!include、!env），防止配置注入攻击；所有注释内容将被忽略，不参与解析。
1、JSON中删除所有行内或块状注释，仅保留纯JSON结构。
2、YAML中禁用自定义标签，!include /path/to/file.yml将被拒绝加载。
3、注释后若紧邻有效键名，可能导致该键被识别为注释内容，"#启用调试 debug: true"中debug不会被识别。
4、启用安全模式时，Qoder日志中将输出WARNING：[SECURITY] Skipped unsafe tag "!env" at line 42。
