SuperAPI AI 工具集

squad-conventions

编程与开发

查看项目

更新于 10-16 06:55

技能介绍

用途

本约定适用于 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)源码开发、维护或审查的开发者,尤其是需要遵循项目既有约定、保持跨平台兼容与零依赖约束的场景。

限制

资料未提供该技能的具体安装命令、版本要求、收费信息或平台支持范围等细节,暂未提供。