在调用 Meticulous 相关技能前检查并更新 CLI…

每次开始任何 Meticulous 工作流前，先确认 meticulous CLI 已安装且为最新版本、已完成认证并选好项目，同时更新已安装的 Meticulous 技能。

适用场景

解决思路

1. 每个对话只需运行一次本流程；如果本次对话中已经运行过，直接跳过，不必每次调用 Meticulous 技能都重新检查版本或更新。
2. 如果使用的是托管的 Meticulous MCP 服务器而非 CLI，跳过步骤 1-4（CLI 安装/更新与本地认证不适用），直接执行步骤 5；因为技能文档集与 CLI/MCP 工具本身是两回事，无论用哪种方式调用工具，技能都需要保持最新。
3. 把安装/更新命令（步骤 1、3、5）当作尽力而为且非阻塞的操作：命令若在白名单内会静默执行，否则会弹出权限提示，两种结果都可以接受。
4. 如果命令需要你没有的权限（出现提示或用户拒绝），就改为建议而非强制：告诉用户建议执行某命令（例如“建议运行 `npm install --global @alwaysmeticulous/cli@latest` 来更新 Meticulous CLI”），然后继续；被拒绝不算失败，只是“稍后再做”。
5. 如果用户现在不想运行，继续执行后续步骤并返回调用方技能；唯一硬性要求是 `meticulous` 命令存在（步骤 1），如果确实未安装且用户拒绝安装，则停止，因为没有 CLI 任何 Meticulous 技能都无法运行。
6. 只读检查（`meticulous --version`、`npm view …`、`meticulous auth whoami`）可以直接运行。
7. 步骤 1：运行 `meticulous --version` 检查已安装版本；如果命令未找到，说明 CLI 未安装，执行 `npm install --global @alwaysmeticulous/cli@latest` 全局安装（尽力而为）。
8. 如果安装不在白名单内，建议用户自行运行该命令；由于没有 CLI 任何 Meticulous 技能都无法运行，这是唯一需要停下等待的情况；安装后重新运行 `meticulous --version` 确认已在 `PATH` 中，然后跳到步骤 4。
9. 步骤 2：运行 `npm view @alwaysmeticulous/cli version` 检查最新发布版本。
10. 步骤 3：如果已安装版本与最新版本一致，跳到步骤 4；否则按安装方式更新（尽力而为，若不在白名单内则建议用户运行相应命令并继续）。
11. 全局安装时（典型情况，`which meticulous` 解析到当前项目之外的路径）：运行 `npm install --global @alwaysmeticulous/cli@latest`。
12. 项目内本地安装时（`@alwaysmeticulous/cli` 出现在项目 `package.json` 中且 `which meticulous` 解析到 `node_modules/.bin` 内）：运行 `npm install --save-dev @alwaysmeticulous/cli@latest`；若项目使用 pnpm 则运行 `pnpm add --save-dev @alwaysmeticulous/cli@latest`；若使用 yarn 则运行 `yarn add --dev @alwaysmeticulous/cli@latest`。
13. 如果执行了更新，重新运行 `meticulous --version` 并确认与最新版本一致后再继续。
14. 步骤 4：运行 `meticulous auth whoami` 验证用户已认证并已选择项目；如需结构化输出可加 `--json`，它会打印 `authenticatedVia` 和 `selectedProject`。
15. 情况 (a) 通过 OAuth 登录且已选项目：无需操作，继续步骤 5。
16. 情况 (b) 通过 API token 或注入凭据认证：这些凭据限定于单个项目且项目已固定，无需选择，不要运行 `meticulous auth set-project`（API token 会报错，注入凭据也无从选择），继续步骤 5。
17. 情况 (c) “Not logged in”：登录是浏览器 SSO，必须由人在浏览器完成；在用户自己的机器上（浏览器能访问本机 localhost）运行 `meticulous auth login --non-interactive`，它会打印登录 URL 并等待本地回调服务器，因此放到后台运行，把 URL 展示给用户请其打开并完成登录，完成后命令结束并存储 token，即可继续；也可以让用户自己运行 `meticulous auth login`（在其终端会直接打开浏览器）。
18. 在远程或沙箱机器上（云 agent、SSH 会话、容器），其他设备的浏览器无法访问本机 localhost 时，运行 `meticulous auth login --device`，它使用 OAuth 设备流，打印 URL 和短代码而非等待本地回调；放到后台运行，把 URL 和代码展示给用户，请其在任意设备打开 URL 并输入代码，确认后命令结束并存储 token。
19. 两种登录形式都会跳过交互式项目选择器，因此已知项目时可加 `--project "Organization/Project"` 一步完成登录并固定项目；不加 `--project` 时，拥有多个项目的账号会落入情况 (d)，登录完成后重新运行 `meticulous auth whoami` 并按报告的情况处理，再继续步骤 5。
20. 在完全没有人的 CI 类环境中，替代方案是使用 API token：设置 `METICULOUS_API_TOKEN`（或传 `--apiToken`）而不是登录。
21. 情况 (d) 通过 OAuth 登录但没有默认项目：`whoami` 成功但 stderr 提示未设置默认项目，此时项目级命令无法解析项目；运行 `meticulous auth list-projects` 列出选项（每行一个 “organization/project” slug），再运行 `meticulous auth set-project --project "Organization/Project"` 固定一个。
22. 除非项目明确无歧义（例如只列出一个项目，或仓库明显对应其中之一），否则询问用户使用哪个；也可以让用户自己运行 `meticulous auth set-project`（不带 `--project` 会显示交互式选择器）。
23. 项目选择保存在账号而非机器上，因此也适用于 MCP 服务器和用户的其他机器；`meticulous auth get-project` 可单独打印当前解析的项目。
24. 步骤 5：更新已安装的 Meticulous 技能（技能本身也在活跃开发中），方式取决于安装方式（尽力而为）。
25. 若用 `npx skills` 安装（默认方式，技能文件位于 `.claude/skills/`、`.cursor/skills/` 或对应 agent 目录，并带有 `skills-lock.json`）：运行 `npx skills add alwaysmeticulous/skills --skill "*" --agent claude-code --agent codex --agent cursor -y` 为指定 agent 安装或更新所有技能；只有在项目中看到 `skills-lock.json`（或技能文件本身）后才运行，否则会在插件安装之外再装一份副本。
26. 若作为 Claude Code 插件安装（技能以 `/meticulous:<skill-name>` 命名空间出现，`claude plugin list` 列出 `meticulous@meticulous`）：`npx skills` 不会触及这些，应运行 `claude plugin update meticulous@meticulous` 更新插件；告诉用户更新需重启 Claude Code 后才生效（也可自行从 `/plugin` 菜单操作）；例外：如果 `claude plugin list` 报告插件 scope 为 `managed`，说明它由组织的托管设置固定，不要尝试更新，只需告知用户。
27. 若从 Cursor 插件市场安装：没有命令可运行，建议用户从 Cursor 的 Customize → Plugins 更新。
28. 如果相应命令不在白名单内，建议用户自行运行；无论命令是否执行或用户拒绝，都继续执行调用方技能。

适用边界 · 注意事项

• 本次对话中已经运行过本流程时，不要重复检查版本或重复更新。
• 使用托管的 Meticulous MCP 服务器时，不要执行步骤 1-4（CLI 安装/更新与本地认证不适用）。
• 当凭据是 API token 或注入凭据时，不要运行 `meticulous auth set-project`（API token 会报错，注入凭据也无从选择）。