我把同一份 Agent 配置写了 4 遍: JSON、TOML、YAML 与配置文件的语法和选择

Object、Array 与逗号#

Object 用花括号，成员写成 "key": value。Array 用方括号，元素按顺序排列。成员或元素之间放逗号，最后一个后面不能放逗号:

1
{
2
  "tools": ["read", "write"]
3
}

下面不是标准 JSON:

1
{
2
  "tools": ["read", "write"],
3
}

我用 Python 3.13 的 json 模块解析一份带注释和尾逗号的文本，得到的是:

1
JSONDecodeError: Expecting property name enclosed in double quotes

这两个限制常让手写配置变得烦，但也让生成器和不同语言的 Parser 更容易达成一致。

Key 和 String 必须使用双引号#

标准 JSON 的 Object Key 是 String，所以必须加双引号。String 本身也只能使用双引号:

1
{"model": "reasoning-large"}

下面 3 种都不是标准 JSON:

1
{model: "reasoning-large"}   // 裸 key
2
{'model': 'reasoning-large'} // 单引号
3
{"model": undefined}        // JSON 没有 undefined

它们可能是合法 JavaScript，却不是合法 JSON。JSON 源自 JavaScript 对象字面量，但今天二者不是同一种语言。

转义: 反斜杠会再收一次税#

JSON String 中常用转义包括:

Windows 路径和正则表达式最容易暴露双层解析:

1
{
2
  "workspace": "C:\\Users\\me\\project",
3
  "pattern": "^src\\/.*\\.ts$"
4
}

文件里写 \\，Parser 读出来才是一个 \。如果这段字符串随后还要进入正则 Parser，它又会解释一遍。每套 Parser 都像机场安检，再过一层就再开一次箱。

Number 没有 int64 这回事#

JSON Grammar 允许负数、小数和指数形式:

1
{
2
  "retries": 3,
3
  "temperature": 0.2,
4
  "threshold": 1e-6
5
}

但 JSON 只定义 Number 的文本语法，不承诺宿主语言使用哪种数值类型。JavaScript 通常把它读成 IEEE 754 双精度 Number，因此超过安全整数范围的 ID 可能丢精度:

1
{
2
  "job_id": 9007199254740993
3
}

跨语言传递大整数、雪花 ID 或精确 Decimal 时，我会写成字符串，再由应用按明确类型解析:

1
{
2
  "job_id": "9007199254740993"
3
}

null、缺失与空字符串不同#

这 3 份配置表达不同状态:

1
{}

1
{"proxy": null}

1
{"proxy": ""}

它们通常分别表示未提供、显式置空、提供了空字符串。具体工具可能赋予别的语义，但格式本身没有把三者合并。配置合并时这一区别尤其重要: null 有时会删除继承值，有时会覆盖成空值，有时直接不合法。只能查工具文档或 Schema，不能靠气氛判断。

重复 Key 和成员顺序#

RFC 8259 说 Object 中的名称应该唯一，因为重复时不同实现可能保留第一个、保留最后一个、全部保留或报错:

1
{
2
  "network": false,
3
  "network": true
4
}

人类可能从上往下读成 “最后一次覆盖”，安全审计却不该建立在 “可能” 上。不要写重复 Key。

JSON Object 在数据模型上是无序映射。Parser 经常保留源码顺序，但业务逻辑不应该依赖顺序。需要顺序时使用 Array。

JSON 为什么没有注释#

标准 JSON 没有注释。对机器生成、API 交换和锁文件来说，这是优点；对手写的长期配置来说，这很痛苦。常见解决方案有 3 种:

1. 工具明确支持 JSONC，也就是带 // 或 /* ... */ 注释的 JSON 方言。
2. 用 $comment、description 之类的普通字段，前提是 Schema 允许未知字段。
3. 攬弃 JSON，改用工具支持的 TOML 或 YAML。

JSONC 也不是 JSON5。JSON5 还可能允许单引号、裸 Key、Infinity 等更多 JavaScript 风格语法。方言名称看起来只差一个字符，能力边界却不同。

我什么时候选 JSON#

我会把 JSON 用在这些地方:

• 工具或 API 强制要求 JSON。
• 文件主要由程序生成，而不是长期手写。
• 需要成熟的 JSON Schema、编辑器补全和跨语言互操作。
• 希望语法保持很小，不接受隐式类型或复杂别名。

对于一份需要大量解释的 Agent 权限配置，纯 JSON 不是我最喜欢的手写格式。对一份 MCP 进程注册表或机器生成的状态文件，它通常很合适。

Key/Value Pair#

TOML 最基本的语句是:

1
key = value

等号左右的空格不影响含义。Bare Key 只能包含 ASCII 字母、数字、下划线和连字符:

1
model = "reasoning-large"
2
max_tokens = 8192
3
sandbox-mode = "workspace-write"

特殊 Key 要加引号:

1
"server name" = "docs"
2
"127.0.0.1" = "local"

TOML 区分大小写，所以 model 和 Model 是两个 Key。为了少给自己制造一种区别，我通常统一使用 snake_case。

注释#

# 到行尾是注释，String 内部的 # 仍然是普通字符:

1
model = "reasoning-large" # 用于代码任务
2
color = "#ff8800"

注释是 TOML 很适合手写 Agent 配置的原因。权限字段旁边可以解释为什么关闭，而不是期待 6 个月后的自己心灵感应。

4 种 String#

TOML 有 Basic、Literal 以及它们各自的多行形式。

Basic String 使用双引号并处理转义:

1
message = "first line\nsecond line"
2
path = "C:\\Users\\me\\project"

Literal String 使用单引号，不处理反斜杠转义，很适合 Windows 路径和正则:

1
path = 'C:\Users\me\project'
2
pattern = '^src/.*\.ts$'

单引号不是 Shell 的单引号，只是 TOML Literal String 的定界符。

Multiline Basic String 使用 3 个双引号:

1
instructions = """
2
Read the repository rules first.
3
Run the narrowest relevant check.
4
Do not print secrets.
5
"""

Multiline Literal String 使用 3 个单引号，内容中的反斜杠仍然保持原样:

1
windows_example = '''
2
C:\Users\me\project
3
'''

多行 String 的首个紧邻换行会被裁掉，结尾换行是否保留要看定界符位置和具体写法。放长 Prompt 时，我会用一个实际 Parser 打印 repr()，不靠目测数换行。

Integer、Float 与可读分隔符#

TOML 区分 Integer 和 Float，并允许下划线分组数字:

1
max_tokens = 128_000
2
ratio = 0.25
3
threshold = 1e-6
4
hex_mask = 0xFF_A0

布尔值只能小写:

1
enabled = true
2
dry_run = false

True、FALSE 都不合法。严格其实挺好，少一种写法就少一种会议议题。

日期与时间是原生类型#

TOML 比 JSON 多出 Offset Date-Time、Local Date-Time、Local Date 和 Local Time:

1
expires_at = 2026-09-13T08:30:00Z
2
maintenance_date = 2026-09-13
3
quiet_time = 08:30:00

我用 Python 3.13 标准库 tomllib 解析后，3 个值分别变成:

1
expires_at       datetime  2026-09-13 08:30:00+00:00
2
maintenance_date date      2026-09-13
3
quiet_time       time      08:30:00

这不是字符串格式化糖。Parser 确实产生了不同宿主类型。需要原样保留时间文本时应该加引号。

Array 与 Inline Table#

普通 Array:

1
include = ["src/**/*.ts", "tests/**/*.ts"]
2
ports = [3000, 3001, 3002]

TOML 1.0 Array 允许混合不同类型，但配置中的同类列表通常更容易验证和消费。Array 可以跨行，并允许最后一个元素后带逗号:

1
allowed_tools = [
2
  "read",
3
  "search",
4
  "browser",
5
]

Inline Table 适合很小的对象:

1
limits = { requests = 10, timeout_seconds = 30 }

TOML 1.0 的 Inline Table 要放在一行内，而且最后一项后不能有尾逗号。对象一旦开始增长，我就把它改成正式 Table。

Table 与 Dotted Key#

Table Header 建立嵌套对象:

1
[permissions]
2
read = true
3
write = false

它等价于:

1
{
2
  "permissions": {
3
    "read": true,
4
    "write": false
5
  }
6
}

Dotted Key 可以写同一结构:

1
permissions.read = true
2
permissions.write = false

再深一层也可以:

1
mcp.docs.command = "node"
2
mcp.docs.enabled = true

但不要同时用多种写法重复定义同一个 Key。TOML 禁止重复 Key，我实际把下面文本交给 tomllib:

1
key = 1
2
key = 2

结果是:

1
TOMLDecodeError: Cannot overwrite a value (at line 2, column 8)

这比 JSON 的 “各 Parser 自行发挥” 更安全。

Array of Tables: MCP Server 的关键语法#

[[mcp_servers]] 每出现一次，就向 mcp_servers Array 追加一个 Table:

1
[[mcp_servers]]
2
name = "docs"
3
command = "node"
4
args = ["server.js", "--stdio"]
5

6
[[mcp_servers]]
7
name = "repo"
8
command = "python"
9
args = ["repo.py"]

它对应 JSON 的:

1
{
2
  "mcp_servers": [
3
    {
4
      "name": "docs",
5
      "command": "node",
6
      "args": ["server.js", "--stdio"]
7
    },
8
    {
9
      "name": "repo",
10
      "command": "python",
11
      "args": ["repo.py"]
12
    }
13
  ]
14
}

一个方括号 [x] 是 Table，两个方括号 [[x]] 是 Array of Tables。少写一层方括号，不是少了一点装饰，而是换了数据类型。

Table 之后的归属陷阱#

TOML 依赖 Header 改变后续 Key 的归属:

1
model = "reasoning-large"
2

3
[permissions]
4
read = true
5
write = false

model 在根 Table，read 和 write 在 permissions。如果把 model 放到 Header 后面:

1
[permissions]
2
read = true
3
model = "reasoning-large"

那么 model 也属于 permissions，不是回到根节点。缩进不改变归属，最近的 Table Header 才改变。TOML 看起来平坦，但 Parser 记得自己当前站在哪个房间。

TOML 没有 null#

TOML 没有通用 Null。可选字段通常直接省略，或者由应用定义一个明确的哨兵字符串。不要擅自写:

1
proxy = null

它不合法。省略和显式清除必须由工具的合并协议另行设计，这也是 TOML 在多层覆盖场景中的一个真实限制。

我什么时候选 TOML#

如果工具允许我自己选择格式，我通常把 TOML 用于:

• 人类长期维护的应用或 Agent 设置。
• 结构以 Key/Value 和中等深度 Table 为主。
• 需要注释、明确类型和严格重复键检查。
• 包含日期时间、路径、正则或多行 Prompt。

当嵌套非常深、对象数组很多时，TOML 的 Header 会让我在文件里频繁确认当前位置。这时 YAML 或 JSON 可能更直观。

Mapping、Sequence 与缩进#

Mapping 是 key: value:

1
model: reasoning-large
2
dry_run: false

Sequence 的每项以 - 开头:

1
tools:
2
  - read
3
  - search
4
  - browser

Sequence Item 也可以是 Mapping:

1
servers:
2
  - name: docs
3
    command: node
4
  - name: repo
5
    command: python

缩进表示父子关系。YAML 规范要求缩进使用空格，不能用 Tab:

1
permissions:
2
  read: true
3
  write: false

read 和 write 比 permissions 多缩进 2 个空格，所以属于它。2 个空格不是 YAML 的强制宽度，只是一种最常见约定；同一级必须保持一致。

下面的视觉差异很小，数据结构却不同:

1
# 一个对象，里面有两个字段
2
permissions:
3
  read: true
4
  write: false

1
# 两个对象组成的数组
2
permissions:
3
  - read: true
4
  - write: false

第 2 份通常不是权限配置想要的结构。横杠不是 Bullet 的装饰，它创建了 Array Item。

Block Style 与 Flow Style#

YAML 也支持类似 JSON 的 Flow Style:

1
include: [src/**/*.ts, tests/**/*.ts]
2
permissions: {read: true, write: false, network: false}

这和 Block Style 表达同类数据。我的规则很简单:

• 小型标量数组可以用 Flow Style。
• 嵌套对象和对象数组使用 Block Style。
• 不为了省 2 行把整份 YAML 压成括号迷宫。

YAML 1.2 的目标之一是让 JSON 成为它的严格子集。因此，一份标准 JSON 文本通常也是合法 YAML 1.2 文本。不过，工具实际使用的 YAML Parser、Schema 和扩展版本仍可能不同，不能由这个包含关系推断所有实现行为一致。

Plain、单引号与双引号 Scalar#

不加引号的是 Plain Scalar:

1
model: reasoning-large
2
workspace: /work/demo

单引号主要按字面保留内容，内部单引号写两次:

1
pattern: '^src/.*\.ts$'
2
message: 'It''s ready'

双引号会处理 \n、\t、\uXXXX 等转义:

1
message: "first line\nsecond line"
2
path: "C:\\Users\\me\\project"

YAML 的 Plain Scalar 方便，但某些开头字符和 : 、 # 组合具有结构意义。遇到 URL、时间、通配符、正则、冒号后空格或看起来像布尔值和数字的文本，我倾向于加引号:

1
url: "https://example.com/api"
2
pattern: "*.ts"
3
answer: "null"
4
version: "1.0"

这里的引号不是为了让文件看起来正式，而是为了固定类型和边界。

隐式类型: YAML 最著名的脚趾捕捉器#

YAML 会根据 Schema 解析 Plain Scalar。YAML 1.1 中 yes、no、on、off 经常被解析成 Boolean；YAML 1.2 Core Schema 把 Boolean 收窄为大小写组合的 true 和 false。问题是现实工具不一定使用同一规范版本或同一 Schema。

我用 yq 4.53.2 实际解析了 6 个值:

这组结果描述的是本次 yq 实验，不是宇宙中所有 YAML Parser 的共同誓言。比如某些 Parser 会把日期构造成 Date 对象，旧版 YAML 1.1 Parser 可能把 on 读成 true。

跨工具配置里，我会遵循 3 条保守规则:

1. Boolean 只写 true 和 false。
2. Null 只写 null，需要字符串时写 "null"。
3. 版本号、ID、端口前导零、日期和类似科学计数法的文本都加引号。

Null 有很多写法，但不要炫技#

YAML Core Schema 可以识别 null、Null、NULL 和 ~。空 Value 也可能解析为空节点:

1
proxy: null
2
cache: ~
3
optional:

它们是否在应用合并时表示 “删除继承值”，仍由应用定义。我只写小写 null，因为清楚比展示语言掌握程度重要。

多行文本: | 与 >#

Agent 配置经常包含 Prompt 或 Instructions，YAML 的 Block Scalar 很方便。

Literal Style | 保留换行:

1
instructions: |
2
  Read repository rules first.
3
  Run the narrowest relevant check.
4
  Do not print secrets.

解析结果近似:

1
Read repository rules first.\nRun the narrowest relevant check.\nDo not print secrets.\n

Folded Style > 会把多数普通换行折叠为空格:

1
instructions: >
2
  Read repository rules first.
3
  Run the narrowest relevant check.
4
  Do not print secrets.

解析结果近似:

1
Read repository rules first. Run the narrowest relevant check. Do not print secrets.\n

末尾 Chomping Indicator 控制结尾换行:

Prompt 对空格和换行敏感时，| 和 > 不是排版选择，而是数据选择。我通常用 |- 表示 “保留内部行，不额外添加末尾换行”。

Anchor 与 Alias#

YAML 可以用 Anchor &name 标记节点，再用 Alias *name 引用同一节点:

1
safe_permissions: &safe
2
  read: true
3
  write: false
4
  network: false
5

6
agents:
7
  reviewer:
8
    permissions: *safe
9
  researcher:
10
    permissions: *safe

这能减少重复，但也增加了追踪成本。更微妙的是，常见的 Merge Key << 并不属于 YAML 1.2 Core Schema 的普通能力，很多工具把它作为额外约定支持:

1
researcher:
2
  <<: *defaults
3
  network: true

除非目标工具明确支持，我不会在可移植 Agent 配置里依赖 Merge Key。几十行重复配置可能不优雅，但一次静默忽略的权限覆盖更不优雅。

Alias 还可能让反序列化后的数据成为共享引用，而不是两个完全独立的副本。应用若修改其中一个节点，另一个是否跟着变化取决于加载器和后续转换。配置只是静态输入时影响不大，直接在内存中变更解析结果时要留意。

Tag 与反序列化安全#

YAML 支持显式 Tag，用来说明节点类型:

1
port: !!int "4321"
2
label: !!str 4321

某些语言生态还支持构造本地对象的自定义 Tag。历史上，不安全加载任意 YAML 可能触发对象构造甚至代码执行。处理不可信 YAML 时，要使用目标库的 Safe Loader，并限制 Alias 数量、文档大小和嵌套深度。

这不是 YAML 独有的问题。任何支持扩展类型、引用或对象构造的反序列化格式都需要资源与类型边界。只是 YAML 的友好外观很容易让人忘记 Parser 后面可能站着一台对象工厂。

多文档 Stream#

YAML 可以在一个 Stream 中放多份 Document:

1
---
2
name: reviewer
3
permissions:
4
  write: false
5
---
6
name: implementer
7
permissions:
8
  write: true
9
...

--- 开始新 Document，... 显式结束 Document。很多 Kubernetes 文件使用这种能力，但不是所有 Agent 配置 Loader 都接受多文档。工具只期待一个 Mapping 时，不要因为 YAML 能写就写。

重复 Key#

YAML Mapping 的 Key 必须唯一，但现实 Parser 对重复 Key 的处理并不统一。有的报错，有的保留最后值:

1
permissions:
2
  network: false
3
  network: true

这在权限配置里尤其危险。Lint 应当把重复 Key 当错误，而不是把它当覆盖机制。

我什么时候选 YAML#

我会用 YAML 处理:

• 人类频繁编辑、嵌套层次明显的配置。
• CI Pipeline、部署清单等生态已经统一使用 YAML 的地方。
• 需要大量多行文本或对象数组。
• 目标工具提供严格 Schema、编辑器支持和明确 Parser 版本。

如果配置涉及安全权限、隐式类型很多，且没有 Schema 或 Lint，我反而更偏向 TOML 或 JSON。YAML 的简洁来自上下文，机器和人都必须把上下文读对。

值通常都是 String#

Python 3.13 的 ConfigParser 读取上面的值后:

1
temperature -> '0.2'  type: str
2
dry_run     -> 'false' type: str

getfloat() 和 getboolean() 可以显式转换，但文件格式本身没有给每个值统一定型。尤其不要这样写:

1
bool(config["agent"]["dry_run"])

因为 bool("false") 仍然是 True。应该使用 Parser 提供的布尔转换 API，或者自己定义严格词汇表。

Section、Key 大小写和重复项依赖实现#

以 Python ConfigParser 默认行为为例:

• Section 名称区分大小写。
• Section 内的 Key 不区分大小写，并会规范成小写。
• # 和 ; 可以开始整行注释。
• = 和 : 都能分隔 Key 与 Value。
• 读取多份文件时，后读文件的冲突值优先。

换一个 INI Parser，这些细节可能改变。INI 的核心优势是简单，核心风险也是没有足够统一的边界。

嵌套与 Array 都是应用协议#

下面 3 种都有人使用:

1
[permissions]
2
read = true

1
permissions.read = true

1
[agent.permissions]
2
read = true

INI 本身没有告诉我们哪一种代表嵌套对象。逗号分隔也无法无歧义表达参数本身包含逗号的 Array:

1
args = --message, hello, world

这是 3 个参数，还是 --message 加上 hello, world 一个参数？只有应用知道。结构复杂到需要发明转义规则时，INI 已经不再简单，换 TOML、YAML 或 JSON 更省事。

我什么时候选 INI#

INI 适合:

• 兼容已有工具或 Windows 风格配置。
• 配置本质上是少量分组后的 String Key/Value。
• 不需要深层嵌套、复杂 Array 或严格跨语言类型。

它不适合作为我从零设计的复杂 Agent 编排格式。两个 MCP Server 尚且能靠 Section 命名约定表达，等到 Server 还有环境变量、超时、权限和传输方式时，这套约定很快会长成一门没有规范的新语言。

不要把 .env 变成小型 YAML#

我不会这样塞复杂数据:

1
AGENT_PERMISSIONS={"read":true,"write":false}
2
AGENT_TOOLS=read,search,browser

第一项变成嵌套 JSON，第二项发明逗号数组。现在一次配置要经过 Dotenv Parser、环境变量传递，再经过 JSON 或 CSV Parser。可以工作，但边界和错误信息都变差。

更清楚的分工是:

1
# config.toml, 可以提交
2
model = "reasoning-large"
3
api_key_env = "AGENT_API_KEY"
4

5
[permissions]
6
read = true
7
write = false

1
# .env.local, 不提交
2
AGENT_API_KEY=actual-secret-value

结构、默认值和权限放版本控制中的配置文件；密钥从环境、操作系统 Keychain 或 Secret Manager 注入。配置保存密钥的名字，不保存密钥本身。

JSONC#

JSONC 通常表示允许 JavaScript 风格注释的 JSON:

1
{
2
  // 禁止 Agent 修改文件
3
  "write": false,
4
  "network": false
5
}

是否允许尾逗号仍由 Parser 选项决定。微软的 jsonc-parser 就把 allowTrailingComma 做成独立选项，所以 “支持注释” 不能推出 “支持尾逗号”。

JSON5#

JSON5 通常进一步允许单引号、裸 Key、尾逗号、十六进制数等:

1
{
2
  model: 'reasoning-large',
3
  tools: ['read', 'search'],
4
}

它更适合人手写，但标准 JSON Parser 不会接受。

JavaScript 或 TypeScript 配置#

可执行配置甚至可以计算值:

1
export default {
2
  model: process.env.AGENT_MODEL ?? "reasoning-large",
3
  timeout: 10 * 1000,
4
  include: ["src", ...(process.env.CI ? ["tests"] : [])],
5
};

优点是组合、条件、变量和类型系统都现成。代价也非常具体:

• 加载配置等于执行代码。
• 静态分析与跨语言消费更困难。
• 配置结果依赖环境和执行时机。
• 不可信仓库中的配置可能直接成为代码执行入口。

当工具明确设计成加载代码配置时，我会用它的能力；当数据文件已经够用时，我不会为了少写 4 行复制而引入一台 JavaScript VM。

additionalProperties 要不要关#

把 additionalProperties 设为 false 可以抓住拼写错误:

1
permisions: # 少写了一个 s
2
  write: false

否则错误 Key 可能被静默忽略，用户以为权限已关闭，Agent 则按默认值运行。这对安全字段很危险。

代价是向前兼容性降低。旧 Validator 遇到新字段会拒绝配置。我会对安全敏感、内部控制的配置使用严格 Schema；对需要插件扩展的区域，则明确留出 extensions 或命名空间，而不是允许任意 Key 混在根节点。

Scalar 覆盖容易，Mapping 与 Array 合并困难#

假设用户配置是:

1
permissions:
2
  read: true
3
  write: false
4
tools:
5
  - read
6
  - search

项目配置是:

1
permissions:
2
  write: true
3
tools:
4
  - browser

至少存在 4 种合理策略:

1. 浅覆盖: 整个 permissions 被项目对象替换，read 消失。
2. 深合并: 只把 write 改成 true，保留 read。
3. Array 替换: tools 最后只有 browser。
4. Array 追加: tools 变成 read、search、browser。

格式没有规定答案。YAML Anchor、TOML Dotted Key 和 JSON Merge Patch 是不同机制，也不能自动代表工具的加载策略。

我在修改 Agent 配置前会先找 4 个信息:

• 文件搜索路径。
• 来源优先级。
• Object 是替换还是深合并。
• Array 是替换、追加还是按 ID 合并。

找不到官方说明时，我会做一个无害实验: 在低优先级配置中放唯一值，在高优先级配置中只覆盖一个兄弟字段，然后运行工具的 config show、诊断命令或最小启动路径观察最终值。不要拿网络和写权限当实验字段。

1. Unexpected token 或 Expected comma#

这通常是 JSON 的引号、逗号或括号错误。先让 Parser 报准确行列:

1
jq empty config.json

不要从文件开头人工数括号。格式化器和 Parser 专门干这个。

2. TOML Key 跑进错误 Table#

检查它前面最近的 [table] 或 [[array_of_tables]]。缩进不会把 Key 拉回根节点。可以用 Python 标准库打印解析结果:

1
python -c 'import pathlib,tomllib,pprint; pprint.pp(tomllib.loads(pathlib.Path("config.toml").read_text()))'

3. YAML mapping values are not allowed here#

优先检查:

• 缩进层级是否一致。
• 是否混入 Tab。
• Plain Scalar 中是否出现 : 。
• 上一行是否漏了 - 或 :。
• 多行 Block 是否缩进不足。

用 Parser 看结构，而不是只看语法高亮:

1
yq -o=json config.yaml

4. 值看起来对，类型却错#

打印 Value 及其类型。典型错误包括:

• JSON 中把 false 写成 "false"。
• YAML 中把版本号解析成 Number。
• TOML 日期没加引号，变成 Date。
• INI 中把所有 String 当成自动带类型。

5. 配置合法但完全没生效#

这通常不是格式问题。检查:

• 文件名和路径。
• 当前工作目录。
• 项目是否被工具标记为可信。
• Profile 是否真的选中。
• 更高优先级来源是否覆盖。
• 字段是否已弃用或只在特定版本支持。

6. Agent 启动后才报 MCP Server 失败#

配置语法只证明 command 是 String、args 是 Array。还要检查:

• Executable 是否存在。
• 工作目录是否正确。
• 参数是否被拆成独立 Array Item。
• 环境变量是否传入。
• Transport 是 stdio、HTTP 还是其他方式。
• Server 是否向 stdout 打了破坏协议的日志。

这是语义验证，不是 Parser 能提前推断的内容。

JSON#

• 所有 Key 与 String 使用双引号。
• 不写注释和尾逗号，除非工具明确声明 JSONC 方言。
• 不写重复 Key，不依赖 Object 顺序。
• 大整数 ID 写成 String。
• 区分缺失、null 和空 String。

TOML#

• Key 使用统一的 snake_case。
• 根 Key 放在第一个 Table Header 之前。
• 用 [table] 表示对象，用 [[table]] 表示对象数组。
• 路径和正则优先考虑 Literal String。
• 不重复定义 Key，不用不存在的 null。

YAML#

• 每层 2 个空格，禁止 Tab。
• Boolean 只写 true 和 false。
• 日期、版本、ID、通配符和可疑 Scalar 加引号。
• 多行 Prompt 明确选择 |、> 和 Chomping Indicator。
• 避免 Merge Key、自定义 Tag 和复杂 Anchor，除非目标工具明确支持。
• 用 Linter 拒绝重复 Key。

INI 与 .env#

• 假设所有 Value 都是 String，再显式转换。
• 不发明深层对象和复杂 Array 协议。
• 查清注释、引号、展开与覆盖行为属于哪个实现。
• Secret 不提交，示例文件只提交变量名称和安全占位值。