用途
本约定适用于 Squad CLI 工具(create-squad)的全部开发工作。Squad 是一个零依赖的 Node.js 包,用于为任意项目添加 AI 智能体团队。在修改任何 Squad 源代码之前,理解这些模式是必要的。
主要能力与约定
零依赖
Squad 没有任何运行时依赖,全部使用 Node.js 内置模块(fs、path、os、child_process)。不要在 package.json 的 dependencies 中添加任何包。这是硬性约束,而非偏好。
Node.js 内置测试运行器
测试使用 node:test 和 node:assert/strict,不使用任何测试框架。通过 npm test 运行,测试文件位于 test/ 目录,测试命令为 node --test test/。
错误处理 —— fatal() 模式
所有面向用户的错误都通过 fatal(msg) 函数处理,该函数打印带红色 ✗ 前缀的消息并以退出码 1 结束。绝不抛出未处理的异常或打印原始堆栈跟踪。全局 uncaughtException 处理器会调用 fatal() 作为安全网。
ANSI 颜色常量
颜色在 index.js 顶部定义为常量:GREEN、RED、DIM、BOLD、RESET。使用这些常量,不要内联 ANSI 转义码。
文件结构
- .squad/ —— 团队状态(用户所有,升级时绝不覆盖)
- .squad/templates/ —— 从 templates/ 复制的模板文件(Squad 所有,升级时覆盖)
- .github/agents/squad.agent.md —— 协调者提示词(Squad 所有,升级时覆盖)
- templates/ —— npm 包随附的源模板
- .squad/skills/ —— SKILL.md 格式的团队技能(用户所有)
- .squad/decisions/inbox/ —— 用于并行决策写入的投递箱
Windows 兼容性
文件路径始终使用 path.join(),绝不硬编码 / 或 \ 分隔符。Squad 必须能在 Windows、macOS 和 Linux 上运行,所有测试必须在所有平台上通过。
Init 幂等性
init 流程采用“存在即跳过”模式:如果文件或目录已存在,则跳过并报告“already exists”。init 期间绝不覆盖用户状态。upgrade 流程只覆盖 Squad 所有的文件。
复制模式
copyRecursive(src, target) 同时处理文件和目录。它使用 { recursive: true } 创建父目录,并对文件使用 fs.copyFileSync。
使用方式示例
错误处理:
function fatal(msg) {
console.error(`${RED}✗${RESET} ${msg}`);
process.exit(1);
}
文件路径构造(Windows 安全):
const agentDest = path.join(dest, '.github', 'agents', 'squad.agent.md');
存在即跳过模式:
if (!fs.existsSync(ceremoniesDest)) {
fs.copyFileSync(ceremoniesSrc, ceremoniesDest);
console.log(`${GREEN}✓${RESET} .squad/ceremonies.md`);
} else {
console.log(`${DIM}ceremonies.md already exists — skipping${RESET}`);
}
反模式
- 添加 npm 依赖 —— Squad 是零依赖的,只使用 Node.js 内置模块。
- 硬编码路径分隔符 —— 绝不直接使用 / 或 \,始终使用 path.join()。
- init 时覆盖用户状态 —— init 跳过已存在的文件,只有 upgrade 才覆盖 Squad 所有的文件。
- 原始堆栈跟踪 —— 所有错误都经过 fatal(),用户看到的是干净的消息而非堆栈跟踪。
- 内联 ANSI 码 —— 使用颜色常量(GREEN、RED、DIM、BOLD、RESET)。
适用场景
适用于参与 Squad CLI 工具(create-squad)源码开发、维护或审查的开发者,尤其是需要遵循项目既有约定、保持跨平台兼容与零依赖约束的场景。
限制
资料未提供该技能的具体安装命令、版本要求、收费信息或平台支持范围等细节,暂未提供。