GSD 工作流校验策略全解：从 content-heuristic 到 human-review 的四级自动化门控

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

在 GSD（GitHub 加速计划 gs / gsd-2）的 spec-driven workflow 体系中，verify字段是每个步骤产出质量的自动化守门员：它定义了引擎如何验证步骤输出是否达标。本文围绕 verification-policies.md 展开，完整讲解content-heuristic、shell-command、prompt-verify、human-review四种策略的配置语法、适用场景、校验规则与底层实现，并给出真实模板中可直接复用的 YAML 示例。读完本文，你将能根据步骤性质为工作流挑选合适的校验策略，编写通过定义加载校验的合法verify配置。

verify字段的定位：步骤输出的验证契约

在 V1 工作流定义中，每个步骤（step）由id、name、prompt三个必填字段构成，并可选携带requires/depends_on、produces、context_from、iterate与verify（参见 yaml-schema-v1.md）。其中verify是专门描述"如何验证该步骤输出"的字段，它必须是一个包含policy字段的对象，policy只能是以下四个枚举值之一：

• content-heuristic：对产物内容做轻量启发式检查；
• shell-command：执行 shell 命令，以退出码判定通过/失败；
• prompt-verify：将验证提示词交给 LLM 进行质量评判；
• human-review：暂停执行，等待人工审批。

从源码看，四种策略在 definition-loader.ts 中被建模为一个联合类型：

| { policy: "content-heuristic"; minSize?: number; pattern?: string } | { policy: "shell-command"; command: string } | { policy: "prompt-verify"; prompt: string } | { policy: "human-review" };

这直观地揭示了每种策略各自的附加字段约束：content-heuristic的minSize、pattern可选；shell-command必须携带command；prompt-verify必须携带prompt；human-review不需要任何附加字段。实际运行时，四种策略在 custom-verification.ts 中分别被映射为三种执行结果（continue/retry/pause），本文将逐一展开。

策略一：content-heuristic— 轻量级内容启发式检查

content-heuristic针对产物文件执行尺寸与文本模式两项检查，所有子字段均可选，用于对"步骤确实产出了实质性内容"做快速健康检查。

配置语法

verify: policy: content-heuristic minSize: 500 # optional — minimum byte size of the artifact pattern: "## Summary" # optional — string pattern that must appear in the artifact

字段说明：

适用场景

当你不希望为每个步骤都编写完整的外部校验脚本时，用它做"步骤是否有实质输出"的轻量 sanity check，例如检查研究笔记是否达到一定长度、草稿是否包含## Summary标题。该策略在官方模板中应用最广：blog-post-pipeline.yaml的三个步骤全部采用该策略（见下文），release-checklist.yaml的 changelog 步骤与code-audit.yaml的 inventory 步骤也用它兜底。

底层实现细节

src/resources/extensions/gsd/custom-verification.ts 中的处理流程可以概括为三步：

1. 产物存在性：首先检查produces声明的产物文件是否存在，缺失即判定验证失败；
2. minSize字节数检查：若设置了minSize，通过stat.size比较实际文件大小，小于阈值即失败；
3. pattern正则匹配：若设置了pattern，用new RegExp(verify.pattern)对文件内容做测试，不匹配即失败；若该模式本身不是合法正则，引擎会记录 warning 并按失败处理。

值得注意：虽然文档中pattern表述为"string pattern"，但其底层实际以 JavaScript 正则表达式执行匹配，因此你可以传入类似^- .+\.ts$这样的正则模式，而不只是字面字符串。此外，三种失败原因（文件缺失、低于 minSize、模式不匹配）都会在日志中具体输出，便于定位问题。

策略二：shell-command— 程序化命令校验

shell-command通过执行一条 shell 命令来验证步骤输出，判定标准是命令的退出码：退出码为 0 表示验证通过，非 0 表示失败。这是四者中表达能力最强、最贴近 CI/CD 习惯的策略，文件存在性检查、测试套件执行、lint、编译等都适用。

配置语法

verify: policy: shell-command command: "test -f output/report.md && wc -l output/report.md | awk '{print ($1 > 10)}'"

字段说明：

适用场景

当验证逻辑需要程序化判定——例如产物文件是否存在、测试套件是否通过、代码是否通过 lint、项目能否编译——优先使用本策略。官方模板中有两个典型用法：

release-checklist.yaml用grep校验版本号格式：

verify: policy: shell-command command: "grep -E '^[0-9]+\\.[0-9]+\\.[0-9]+$' version.txt"

code-audit.yaml用test -f校验审计结果文件是否生成：

verify: policy: shell-command command: "test -f audit-results.md"

底层实现与安全边界

src/resources/extensions/gsd/custom-verification.ts 揭示了三个关键实现细节：

1. 执行方式：命令通过sh -c执行，cwd设为运行目录，stdio为 pipe，并设置了30 秒超时；超时或被信号终止同样视为失败（retry）。
2. 退出码语义：result.status === 0返回continue（放行），否则返回retry（重试）。验证失败后的重试行为由引擎统一处理，custom-verification.ts顶部注释说明"exit 0 → continue, else retry"。
3. 注入防护：实现内置了危险模式正则/\$\(||;\s*(rm|curl|wget|nc|bash|sh|eval)\b/，一旦命令包含命令替换、反引号或与删除/下载/反弹 shell 相关的拼接模式，校验器会跳过执行并返回pause`（暂停）而非直接放行。

需要强调的信任边界：命令字符串来源于 workflow 定义时冻结的 DEFINITION.yaml，命令以 GSD 进程同等权限运行，因此只应对信任的工作流定义使用shell-command——这一安全提示同样明确写在该文件的注释中。编写命令时注意 YAML 中\与$的转义（如上面grep示例中正则里的\\）。

策略三：prompt-verify— 交给 LLM 的智能评判

prompt-verify将一段验证提示词发送给 LLM，由模型对步骤输出进行评估。它适用于无法用 shell 命令表达的判断型验证：质量评估、完整性审查、风格符合度检查等。

配置语法

verify: policy: prompt-verify prompt: "Review the generated API documentation. Does it cover all endpoints with request/response examples? Answer PASS or FAIL with reasoning."

字段说明：

适用场景

当验证需要超出命令表达能力的"判断力"时使用。官方code-audit.yaml的最终 report 步骤即采用此策略，验证报告是否覆盖所有被审计文件并按严重级别分组：

verify: policy: prompt-verify prompt: "Does the report cover all audited files and group findings by severity? Answer PASS or FAIL."

编写prompt时建议像示例一样给出明确判定规则（"Answer PASS or FAIL"），并补充可核对的具体标准（如"是否覆盖所有端点、是否包含请求/响应示例"），以提高评判的一致性与可追溯性。

运行时行为

在 custom-verification.ts 中，prompt-verify与human-review一样总是返回pause——即引擎暂停该步骤的自动化放行，将验证交还给上层 Agent 驱动 LLM 完成评判。这是设计中"确定性与智能性"的分工：确定性校验（两种启发式策略）由引擎直接判定，而需要理解力的验证则回到 Agent 的循环中，由模型结合提示词产出 PASS/FAIL 结论后再决定是否继续。

策略四：human-review— 人工审批门控

human-review暂停执行流程，等待人类对步骤输出做出批准或拒绝。它不包含任何附加字段，是最简单也最"重"的校验策略。

配置语法

verify: policy: human-review

字段说明：

适用场景

当步骤产出需要人类判断力时使用，例如：涉及设计决策的产出、面向公众的内容、安全敏感变更。release-checklist.yaml的最终 publish 步骤就是典型代表——发布动作不可逆，交给人工把关：

verify: policy: human-review

从实现看，该策略与prompt-verify一样返回pause（等待人工检查），意味着引擎不会自动放行，工作流停留在该步骤等待用户确认。

定义加载期的校验规则

引擎在**定义加载时（definition-load time）**就会对verify对象做静态校验，而不是等到运行期才暴露问题。从 definition-loader.ts 可确认以下规则：

• policy必须是"content-heuristic"、"shell-command"、"prompt-verify"、"human-review"四个字符串之一，任何其他取值都会被拒绝；
• shell-command必须携带非空command字段，缺失或为空字符串会被拒绝（错误信息形如Step "<id>" verify policy "shell-command" requires a non-empty "command" field）；
• prompt-verify必须携带非空prompt字段，缺失或为空会被拒绝；
• content-heuristic与human-review除policy外没有必填子字段。

这套校验意味着：一个非法policy或缺少必要子字段的verify会在/gsd workflow validate阶段直接被拦截，便于在写入.gsd/workflows/后立即发现错误。相关规则同时被 definition-loader.test.ts 与 custom-verification.test.ts 中的测试用例覆盖，是经过回归保障的契约行为。

组合实战：从官方模板看策略选型

理解四种策略后，关键在于"在正确的位置用正确的策略"。官方模板集中展示了三种典型组合模式：

1. 线性链 +content-heuristic全程兜底（templates/blog-post-pipeline.yaml）

params: topic: "AI" audience: "developers" steps: - id: research name: Research the topic prompt: >- Research the topic "{{ topic }}" for an audience of {{ audience }}. Write detailed findings including key trends, important facts, and relevant examples. Save the results to research.md. requires: [] produces: - research.md verify: policy: content-heuristic minSize: 200 - id: outline name: Create an outline prompt: >- Using the research findings, create a structured blog post outline targeting {{ audience }}. Include section headings, key points for each section, and a logical flow. Save to outline.md. requires: - research context_from: - research produces: - outline.md verify: policy: content-heuristic - id: draft name: Write the draft prompt: >- Write a complete blog post draft following the outline. The post should be engaging for {{ audience }}, cover all outlined sections, and include a compelling introduction and conclusion. Save to draft.md. requires: - outline context_from: - outline produces: - draft.md verify: policy: content-heuristic minSize: 500

2. 迭代扇形展开 + 命令校验 + LLM 评判（templates/code-audit.yaml）：inventory用content-heuristic确保文件清单非空；audit-file用iterate按^- (.+\.ts)$模式逐个审计文件，并以shell-command的test -f audit-results.md确认每个子执行都写入了结果；最终report步骤用prompt-verify检查报告完整性。

3. 菱形依赖 + 人工审批收口（templates/release-checklist.yaml）：changelog用content-heuristic；version-bump用shell-command的grep校验 semver 格式；test-suite用test -f确认测试结果文件存在；publish作为汇聚点用human-review把最终发布交给人工把关。

这三种模式覆盖了日常绝大多数工作流形态，可作为自建工作流的起点。空白脚手架见 templates/workflow-definition.yaml，其中四种verify策略均已注释形式给出，可直接复制反注释使用；更完整的字段说明可查阅 references/yaml-schema-v1.md，context_from、iterate、params的进阶用法见 references/feature-patterns.md。

选型速查与验证闭环

将工作流定义写入.gsd/workflows/<name>.yaml（项目级，建议入库）或~/.gsd/workflows/<name>.yaml（全局，加--global）之后，先运行/gsd workflow validate <name>触发上文所述的加载期校验，再运行/gsd workflow <name>执行。校验失败时，shell-command会得到retry重试机会，prompt-verify与human-review会得到pause等待上层决策，而content-heuristic的具体失败原因（文件缺失/尺寸不足/模式不匹配）会写入日志——理解这些运行时行为，能让你在定位工作流卡点时快速判断"是该修产物，还是该换策略"。

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用