从一次真实配置检查开始

复制部署文档后，配置文件看起来完整，程序却在加载阶段失败，未必是模型服务、网络或权限问题。今天检查一个多智能体示例项目时，我遇到的原因更简单：一条角色说明中的双引号提前结束了 YAML 字符串。

本文只讨论配置语法，不涉及真实候选人信息，也没有运行面试或做人员评估。

现象与验证边界

我从《AI 面试天团 — 快速部署指南.md》的 6.2 节复制完整 YAML 配置，保存为独立文件，交给本机已有的 YAML 解析器检查。原示例的技术角色 persona 所在行报错：

Unexpected scalar at node end at line 38, column 117

这里的行号属于复制出来的代码块，不是整个 Markdown 文件的行号。验证没有调用云 API 或大模型：只解析文档中的文本。随后仅调整该条 persona 的标量写法，其余内容保持原样，整份配置就能成功解析，目标团队节点也仍然存在。这个对照把问题范围缩到了字符串表示。

把问题缩成一行

下例是自写的最小示例，不是整段复制原项目文案：

persona: "请区分"掌握概念"与"实际实践"。"

外层双引号已经开始一个字符串，内容里的第一个未转义双引号又把它结束。后面的文字不能按原意继续作为同一字符串解析。报错指向后半句时，排查起点应向前看，检查字符串边界，不要只盯着光标附近的汉字。

三种可选的修正方式

短文本可以保留双引号，并把内部双引号转义：

persona: "请区分\"掌握概念\"与\"实际实践\"。"

也可以用单引号包裹包含双引号的文字：

persona: '请区分"掌握概念"与"实际实践"。'

单引号内容里如果还需要单引号，YAML 使用两个连续单引号表示，不要把两种引号风格的转义习惯混在一起。

对于持续修改的长文案，我更倾向把它写成块标量：

persona: >-
  请区分"掌握概念"与"实际实践"。
  回答应明确说明证据和边界。

大于号采用折叠风格；上面这种同等缩进、连续的普通文本行会折叠到一段文字中。减号用于去掉末尾换行。若正文的换行本身有意义，例如命令或格式模板，应考虑字面风格的竖线，而不是机械地将所有多行内容都换成大于号。具体边界按 YAML 1.2.2 第 7.3 和 8.1 节理解。

修复后还要检查什么

我采用的顺序是：先检查文件是否能被解析，再确认目标映射节点和成员还在，最后才交给应用做配置校验。

语法通过不代表应用一定能启动：模型字段、技能名称、文件路径和权限仍可能不符合应用要求。反过来，如果文本连语法解析都没通过，就不应该先修改模型地址或密钥来试运气。

把文档里的整段可复制配置也纳入检查很有价值。单独看一个正确片段，无法证明读者实际复制的整段配置正确；解析整段后再检查关键节点，可以尽早发现缩进或标量边界错误。

本次实际结果与来源

本次结果是：原代码块解析失败；仅将一条 persona 改成折叠块标量后，原配置整体解析成功。我已向原项目提交 Issue #166，附上位置、错误信息和最小修正建议。这里不把语法验证扩大成对整个应用运行状态的结论。

参考规范：YAML 1.2.2，7.3 Flow Scalar Styles、8.1 Block Scalar Styles。

https://yaml.org/spec/1.2.2/

问题记录与原始文档入口：

https://gitcode.com/agent-best-practices/ai-interview-swarm/issues/166