SQUADS

验证指南

确保您的小队在发布到市场前满足质量标准。

为什么要验证？

小队在用户环境中执行代码。验证可确保质量、安全性和结构完整性，防止问题传递给其他开发者。

检查内容

验证工具在 6 个加权类别中分析您的小队：

类别权重验证内容
清单 (squad.yaml)25%name、version、description、aiox.minVersion、components
结构15%目录、预期文件、文件扩展名
智能体20%必填字段、archetype、persona_profile、whenToUse
任务15%输入/输出合约、responsavel、atomic_layer
工作流10%agent_sequence、transitions、success_indicators
交叉引用15%引用的智能体存在，无循环依赖

评分系统

每个小队根据上述加权类别获得 0 到 100 的分数。

SAFE分数 >= 80，无错误 — 可以发布
WARNING有警告但无阻断性错误
CRITICAL有错误或分数低于阈值 — 必须在发布前修复

如何验证

a) CLI（推荐）

发布前在本地验证小队的最快方式：

squads validate ./my-squad           # 完整验证
squads validate ./my-squad --json    # JSON 输出
squads publish ./my-squad --dry-run  # 模拟发布

validationDocs.aiosMethodTitle

validationDocs.aiosMethodDescription

/SQUADS:nsc:squad-validator

*validate-squad my-squad

*extend-squad my-squad --add task --name missing-task

c) Claude Code（无需 Squad）

指示 Claude Code 使用 CLI 验证您的小队：

npx squads validate ./squads/my-squad

d) 网页（提交页面）

提交页面会在粘贴 GitHub URL 时自动运行验证。提交前请修复所有问题。

常见错误与修复

错误原因修复
description 被解析为对象多行 YAML（| 或 >）使用引号内的内联字符串
智能体缺少必填字段缺少 whenToUse、archetype 等在 frontmatter 中添加字段
Task responsavel 未找到智能体名称不匹配使用精确的 agent.name 值
工作流中的智能体不在序列中agent_sequence 中的 ID 无效使用 agent.id（kebab-case）
组件不匹配squad.yaml 中列出的文件不存在将 components 与实际文件同步

发布前检查清单

squad.yaml 有效，包含 name、version、description
无 .env 文件或硬编码凭据
无 node_modules/ 或 .git/ 目录
README.md 存在且包含安装说明
所有智能体包含必填字段（archetype、whenToUse、persona_profile）
所有任务包含输入/输出合约
交叉引用有效（智能体存在，无循环依赖）

Squad 质量关卡

对于 Squad Core 用户，框架在小队生成过程中提供内置质量关卡：

  • ▸第 6 阶段：小队生成质量关卡 — 22 项针对结构、字段和交叉引用的阻断性检查。
  • ▸第 9 阶段：发布前检查清单 — 16 项针对市场发布就绪度的阻断性检查。

使用 *validate-squad 和 *extend-squad 命令进行迭代验证和修复：

*validate-squad my-squad
*extend-squad my-squad --add agent --name new-agent

更多详情请参阅 CLI 参考

验证指南 — SQUADS