meticulous-cli-update

安装或更新 Meticulous CLI

@alwaysmeticulous/cli 包正在积极开发中，频繁发布变更和改进。其他 Meticulous 技能假定 meticulous 命令已在 PATH 中且为最新版本，因此在任何 Meticulous 工作流开始时运行此技能一次。

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

如何处理安装/更新命令

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

• 您通常无法提前知道某个命令是否被列入白名单。如果被列入白名单，它会静默运行；如果没有，尝试执行会弹出权限提示。无论哪种结果都可以——让这成为您发现的方式。
• 如果某个命令需要您没有的权限（出现提示，或用户拒绝），则将其视为推荐而非强制的信号。告诉用户建议执行 XYZ——例如“建议通过运行 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
  

• 本地安装在项目中（@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
  

如果更新已运行，重新运行 meticulous --version 并确认它与最新版本匹配，然后再继续。

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

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

meticulous auth whoami

如果报告“未找到身份验证”，则需要登录。登录是浏览器 SSO，因此用户始终需要在浏览器中完成；使用哪个登录命令取决于您运行的环境：

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

  meticulous auth login --non-interactive
  

  这会打印一个登录 URL，然后等待本地回调服务器，因此在后台运行它，然后将打印的 URL 展示给用户，并请他们打开并完成登录。完成后，命令结束并存储令牌，您可以继续。

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

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

  meticulous auth login --device
  

  这使用 OAuth 设备流程：它打印一个 URL 和一个短代码，而不是等待本地回调。在后台运行它，然后将 URL 和代码展示给用户，并请他们在任何设备上打开 URL 并输入代码。确认后，命令结束并存储令牌。

如果报告“未选择项目”（当用户属于多个项目时会发生——包括在非交互式登录后，因为登录跳过了项目选择器），则必须选择一个项目，项目范围的命令才能工作。询问用户要使用哪个组织/项目（如果您还不知道），然后非交互式地固定它：

meticulous auth set-project --project "Organization/Project"

或者，请用户自行运行 meticulous auth set-project（它会显示一个交互式选择器）。

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

技能本身也在积极开发中。将它们更新到最新版本（尽力而为，参见上面的说明）：

npx skills update --project

如果此命令未被列入白名单，建议用户自行运行。无论哪种方式——无论它运行了，还是用户拒绝了——继续执行调用技能。