squad-version-check

本技能为关于 Squad CLI 内部机制的可复用知识，置信度为 medium，来源方式为仓库调查，日期 2026-05-26，验证于 bradygaster/squad 的 Issue #1173 侦察。

一、用途本技能覆盖 @bradygaster/squad-cli 如何将版本号写入 squad.agent.md、squad upgrade 的工作方式（保留什么、覆盖什么），以及如何从 coordinator 提示中探测 npm registry 以获取最新版本。

二、包与注册表事实

包名：@bradygaster/squad-cli
注册表：npm（公共）
CLI 可执行文件：squad（通过 package.json#bin.squad 注册）
Node 版本要求：Node ≥22.5.0（ESM-only 代码库）

三、版本标记机制源文件：dist/cli/core/version.js，包含三个函数：

getPackageVersion()：从编译后的 JS 文件向上查找 package.json，返回 pkg.version。可从 dist/cli/core/version.js 或打包后的根 cli.js 工作。未找到时返回回退值 '0.0.0'。
stampVersion(filePath, version)：在 squad.agent.md 中修改三处：HTML 注释 （必须紧跟在 frontmatter --- 之后的下一行）；身份行 - Version: {version}；问候语指令中的反引号 Squad v{version}。由 init 与 upgrade 在将模板复制到目标位置后调用。
readInstalledVersion(filePath)：从 squad.agent.md 读回已标记版本。先尝试 HTML 注释格式正则 //，回退到旧的 frontmatter 格式 /^version:\s*"([^"]+)"/m，任何错误返回 '0.0.0'。

四、squad upgrade 行为源文件：dist/cli/core/upgrade.js。被覆盖的内容：squad.agent.md（从模板全量覆盖后调用 stampVersion()）；TEMPLATE_MANIFEST 中 overwriteOnUpgrade: true 的文件，包括 casting JSON 文件、模板 .md 文件、copilot-instructions.md（在启用 @copilot 时）；GitHub Actions 工作流（来自 templates/workflows/，非 npm 项目会获得类型感知的桩文件）。文件复制后运行 runMigrations()。被保留的内容：team.md、routing.md、decisions.md、ceremonies.md（用户所有）；agents/*/history.md（单个 agent 记忆）；.squad/config.json（从不触碰，stateBackend 完整保留）；不在 TEMPLATE_MANIFEST 中的用户新增文件。自升级路径 selfUpgradeCli()：通过 npm_execpath 与 npm_config_user_agent 检测 npm/pnpm/yarn，分别运行 npm install -g @bradygaster/squad-cli@latest、pnpm add -g @bradygaster/squad-cli@latest、yarn global add @bradygaster/squad-cli@latest；insider 构建使用 @insider 标签。 compareSemver(a, b) 工具函数（位于 upgrade.js）：返回 -1/0/1。处理预发布版本时先剥离预发布进行基础比较，再将预发布视为小于正式版（例如 0.9.5-insider.1 < 0.9.5）。如需在提示逻辑中直接使用可移植。

五、.squad/config.json 内容默认结构为 {"version": 1, "stateBackend": "worktree"}。coordinator 在运行时可能添加的可选字段：defaultModel（所有 agent spawn 的全局模型覆盖）、agentModelOverrides.{agentName}（按 agent 的模型覆盖）。从升级路径的角度该文件为只读，仅 coordinator 会写入（用于模型偏好）。

六、版本检查探测（npm Registry）在 coordinator 提示中可用一行命令获取 dist-tags：npm view @bradygaster/squad-cli dist-tags --json。超时 5 秒；若 5 秒内无响应则放弃并显示正常问候语。成功时提取 dist-tags[channel]（例如 dist-tags["insider"]）。任何错误（网络失败、注册表不可达、解析错误）均显示正常问候语。

七、上游按操作系统区分的缓存 CLI（self-update.ts）将最新版本信息写入操作系统特定路径，TTL 为 24 小时。读取上游缓存的一行命令： node -e "const p=require('path'),o=require('os');const b=process.env.APPDATA||(process.platform==='darwin'?p.join(o.homedir(),'Library','Application Support'):p.join(o.homedir(),'.config'));const f=p.join(b,'squad-cli','update-check.json');try{const d=JSON.parse(require('fs').readFileSync(f,'utf8'));const age=Date.now()-d.checkedAt;if(age<86400000)console.log(JSON.stringify(d));else console.log('STALE')}catch{console.log('MISS')}" 输出语义：有效 JSON {"latestVersion":"X.Y.Z","checkedAt":N} 表示缓存命中，使用 latestVersion；STALE 表示缓存已过期（超过 24 小时），视为无数据；MISS 表示缓存缺失或损坏，视为无数据。操作系统缓存路径：Windows 为 %APPDATA%\squad-cli\update-check.json；Linux 为 ~/.config/squad-cli/update-check.json；macOS 为 ~/Library/Application Support/squad-cli/update-check.json。仓库本地缓存约定：.squad/.cache/version-check.json，供 coordinator 用于 insider/preview 渠道（上游缓存仅存储 latest）。Schema 为 {"checkedAt": "2026-05-26T14:13:28.492Z", "currentVersion": "0.9.6-insider.2", "channel": "insider", "channelVersion": "0.9.7-insider.1"}。TTL 为自 checkedAt 起 24 小时。.squad/.cache/ 已列入 .gitignore，缓存文件不会被提交。

八、关键文件路径（已安装的 CLI）

版本工具：dist/cli/core/version.js
升级逻辑：dist/cli/core/upgrade.js
初始化逻辑：dist/cli/core/init.js
模板清单：dist/cli/core/templates.js
Copilot 安装辅助：dist/cli/copilot-install.js
squad.agent.md 模板：templates/squad.agent.md.template
会话初始化参考：templates/session-init-reference.md
所有模板：templates/

九、适用场景与限制适用于需要理解或复用 Squad CLI 的版本标记、升级覆盖与保留规则、npm registry 版本探测以及版本检查缓存读取逻辑的场景。资料未提供该技能的安装方式、收费模式、独立平台支持与效果数据，暂未提供。

技能介绍