meticulous-cli-update

安装或更新 Meticulous CLI

@alwaysmeticulous/cli 软件包正在积极开发中，并频繁发布更改和改进。其他 Meticulous 技能都假设 meticulous 命令位于 PATH 中且为最新版本，因此请在每次 Meticulous 工作流开始时运行此技能。

每次对话只需运行一次。如果你已在本次对话中运行过，请跳过——无需在每次调用 Meticulous 技能时重新检查或更新版本。

使用 MCP 服务而非 CLI？ 步骤 1-4 涉及安装/更新 meticulous CLI 二进制文件及其本地身份验证——通过托管的 Meticulous MCP 服务调用工具时，这些都不适用。该服务已是最新版本，并通过 MCP 连接本身进行身份验证，而非使用 meticulous auth login。请直接跳到步骤 5：已安装的技能（本文档集）与 CLI/MCP 工具本身是两回事，无论你通过哪种方式调用工具，都仍需保持技能为最新版本。关于 MCP 登录，有一点值得注意：如果 Claude Code 因“授权响应中的 Issuer 不匹配（RFC 9207）”而无法登录，它复用了过期的授权服务器 URL 缓存——请告知用户在 /mcp 中为 Meticulous 服务选择清除身份验证（而非重新进行身份验证），然后再次进行身份验证。

完整的设置说明——安装 CLI、连接 MCP 服务和安装这些技能——请参阅 app.meticulous.ai/docs/agents/setup。

如何处理安装/更新命令

此技能通常作为另一个 Meticulous 技能的子步骤运行。以下安装/更新命令（步骤 1、3 和 5）涉及安全敏感操作——它们会安装软件包并访问网络——因此请将它们视为尽力而为且非阻塞的操作：

• 通常无法提前判断某条命令是否在白名单中。如果在白名单中，命令会静默运行；如果不在白名单中，尝试运行时会出现权限提示。无论哪种结果都没关系——根据提示判断即可。
• 如果某条命令需要你没有的权限（出现权限提示，或用户拒绝授权），请将此视为应该_建议而非强行执行_的信号。告诉用户建议执行某项操作，例如：“建议运行 npm install --global @alwaysmeticulous/cli@latest 来更新 Meticulous CLI”，然后继续后续操作。用户拒绝授权不代表失败，只意味着“以后再做”。
• 如果用户现在不想运行，请继续操作。 不要停止工作流；继续完成剩余步骤，然后返回调用此技能的技能。唯一的硬性要求是 meticulous 命令必须存在（步骤 1）——如果确实未安装，且用户拒绝安装，则无法继续任何 Meticulous 技能，因此请在此处停止。

只读检查（meticulous --version、npm view …、meticulous auth whoami）可以直接运行。

步骤 1 — 检查已安装的版本

meticulous --version

如果找不到该命令，则表示尚未安装 CLI。请全局安装（尽力而为，参见上方说明）：

npm install --global @alwaysmeticulous/cli@latest

如果安装操作不在白名单中，请建议用户自行运行该命令。由于没有 CLI 就无法运行任何 Meticulous 技能，如果用户拒绝安装，这是唯一需要停止并等待的情况——后续没有可继续的操作。安装完成后，重新运行 meticulous --version 以确认它位于 PATH 中，然后跳到步骤 4。

步骤 2 — 检查最新发布的版本

npm view @alwaysmeticulous/cli version

步骤 3 — 如果 CLI 已过时，请更新

如果已安装的版本与最新版本一致，请跳到步骤 4。

否则，请根据 CLI 的安装方式进行更新（尽力而为，参见上方说明 — 如果更新不在允许范围内，建议用户运行相应命令，然后无论如何继续）：

• 全局安装（通常如此 — which meticulous 解析到当前项目之外的路径）：

  npm install --global @alwaysmeticulous/cli@latest
  

• 在项目中本地安装（项目的 package.json 中包含 @alwaysmeticulous/cli，且 which meticulous 解析到 node_modules/.bin 中）：

  npm install --save-dev @alwaysmeticulous/cli@latest
  # or, if the project uses pnpm:
  pnpm add --save-dev @alwaysmeticulous/cli@latest
  # or yarn:
  yarn add --dev @alwaysmeticulous/cli@latest
  

如果已运行更新，请重新运行 meticulous --version，并在继续之前确认其与最新版本一致。

步骤 4 — 检查身份验证和项目选择

确认用户已通过 Meticulous 身份验证，并已选择项目：

meticulous auth whoami

如果希望根据结构化输出进行分支判断，可以添加 --json — 它会输出 authenticatedVia 和 selectedProject。

共有四种情况：

(a) 已通过 OAuth 登录，且已选择项目

Authenticated via: OAuth
Logged in as: Jane Smith ([email protected])
Organizations: acme-corp (member)
Selected project: acme-corp/Web App

无需操作 — 继续步骤 5。

(b) 通过 API 令牌或注入的凭据完成身份验证

Authenticated via: project API token (METICULOUS_API_TOKEN environment variable)
Pinned project: acme-corp/Web App

也可能显示为 project API token (~/.meticulous/config.json)、test-run API token 或 credentials injected at request time（会将 bearer 凭据附加到发往 app.meticulous.ai 的请求中的 Agent 平台）。这些凭据限定于单个项目，该项目已固定，因此无需选择 — 不要运行 meticulous auth set-project：使用 API 令牌时会报错（令牌绑定到一个项目），使用注入的凭据时也没有可供选择的项目。继续步骤 5。

(c) “未登录”

命令会退出，并显示：

未登录。请运行 meticulous auth login，或设置 METICULOUS_API_TOKEN。在没有浏览器的终端中，请使用 meticulous auth login --non-interactive。

登录采用浏览器 SSO，因此始终需要由真人在浏览器中完成；应使用哪条登录命令取决于运行环境：

• 在用户自己的计算机上（该计算机上的浏览器可以访问此计算机的 localhost）：

  meticulous auth login --non-interactive
  

  此命令会输出登录 URL，然后等待本地回调服务，因此请在后台运行它，再将输出的 URL 提供给用户，并请他们打开该 URL 完成登录。用户完成后，命令会结束并保存令牌，随后即可继续。

  或者，请用户自行运行 meticulous auth login — 在他们自己的终端中运行会直接打开浏览器。

• 在远程或沙盒计算机上（云 Agent、SSH 会话、容器），其他设备上的浏览器无法访问此计算机的 localhost：

  meticulous auth login --device
  

  此命令会使用 OAuth 设备流程：输出 URL 和短代码，而不是等待本地回调。请在后台运行它，再将 URL 和代码提供给用户，并请他们在任意设备上打开该 URL 并输入代码。用户确认后，命令会结束并保存令牌。

这两种方式都会跳过交互式项目选择器，因此如果已知道要使用哪个项目，请添加 --project "Organization/Project" — 这样即可一步完成登录并固定项目。如果不添加 --project，可以访问多个项目的帐户将进入下方的情况 (d)，因此登录完成后请重新运行 meticulous auth whoami，并根据其报告的情况进行处理，然后再继续步骤 5。

在完全没有真人可参与的类似 CI 的环境中，替代方法是使用 API 令牌：设置 METICULOUS_API_TOKEN（或传入 --apiToken），而不是登录。

(d) 已通过 OAuth 登录，但未设置默认项目

whoami 执行成功，并额外记录了以下内容（输出到 stderr）：

未设置默认项目。运行 meticulous auth set-project 以选择一个项目。

此状态下，项目范围的命令无法解析项目。拥有多个项目访问权限的账户会遇到此情况，包括刚通过 --non-interactive 或 --device 登录后，因为这两种方式会跳过选择器。列出可选项，然后固定一个项目：

meticulous auth list-projects   # one "organization/project" slug per line
meticulous auth set-project --project "Organization/Project"

除非选项明确无歧义（例如只列出一个项目，或仓库显然对应其中一个项目），否则应询问用户要使用哪一个。或者，请用户自行运行 meticulous auth set-project——不带 --project 时会显示交互式选择器。

此选择会保存到账户，而不是机器，因此也适用于 MCP 服务和用户的其他机器。单独运行 meticulous auth get-project 会输出当前解析出的项目。

第 5 步 — 更新已安装的 Meticulous 技能

技能本身也在积极开发中。如何更新取决于技能的安装方式（尽力而为，参见上方说明）：

• 通过 npx skills 安装——默认方式。技能文件位于 .claude/skills/、.cursor/skills/ 或 Agent 对应的目录下，并附有 skills-lock.json：

  # Install or update all skills, for the specified agents
  npx skills add alwaysmeticulous/skills --skill "*" --agent claude-code --agent codex --agent cursor -y
  

只有在项目中确认看到 skills-lock.json（或技能文件本身）后，才运行此命令，否则会在插件安装的副本旁再安装一份。

• 作为 Claude Code 插件安装——技能会以 /meticulous:<skill-name> 的命名空间形式显示，且 claude plugin list 会列出 meticulous@meticulous。npx skills 不会影响这些技能；应改为更新插件：

  claude plugin update meticulous@meticulous
  

告知用户，只有重启 Claude Code 后更新才会生效（用户也可以自行通过 /plugin 菜单完成此操作）。有一种例外情况：如果 claude plugin list 显示插件的作用域为 managed，说明插件由其组织的托管设置固定；不要尝试更新，只需告知用户。

• 作为 Codex 插件安装——codex plugin list 会列出 meticulous@meticulous。npx skills 同样不会影响这些插件；应刷新市场，这也会在插件发生变化时重新安装插件：

  codex plugin marketplace upgrade meticulous
  

更新会在下一个 Codex 会话中生效。

• 从 Cursor 插件市场安装——无需运行命令；建议用户从 Cursor 的 Customize → Plugins 中更新。

如果适用的命令不在白名单中，建议用户自行运行。无论命令是否已运行，或用户是否拒绝，都应继续执行调用技能。