impeccable 怎么安装：CLI 与 ZIP 2 种方式

impeccable 是一套给 AI 编程代理使用的设计与审查指令，可用于打磨界面、检查可用性并拦截常见的 AI 模板化设计。

截至 2026-03-07 抓取时，官方 FAQ 与仓库 README 给出的安装路径已经比较明确：优先使用 npx 安装器；如果下载的是 ZIP，则手动复制文件。两种方法只适合不同来源，安装前应先确定文件从哪里来，避免把 ZIP 文件错误地套进安装器流程。

下文会区分官方原文与操作判断：命令、安装目录和兼容性要求来自官方页面；不同安装方式的适用场景则是根据官方步骤整理。

动手前确认 3 件事

1. 确认 Node.js 版本。 官方 FAQ 要求 Node.js 18.19 或更高版本。先查看当前 Node.js 版本，低于 18.19 时先升级，再继续安装。

2. 进入目标项目目录。 CLI 安装和后续更新都需要从项目目录运行。确认终端当前路径对应准备接入 Impeccable 的项目，而不是临时目录或其他仓库。

3. 确认使用的 AI 编程工具。 官方 README 列出的支持范围包括 Claude Code、Cursor、Codex CLI、GitHub Copilot、Devin、Gemini CLI、OpenCode、Kiro、Trae 等。安装器会为所选工具选择对应构建，不需要手动猜目录名。

方式一：CLI 安装器，最适合直接开始

CLI 安装器是官方首选路径。它会询问要接入哪个编程工具，并区分安装到当前项目还是所有项目。

1. 在终端进入项目目录，执行：

npx impeccable install

2. 在安装界面中选择 AI 编程工具，再选择项目级或用户级安装。项目级安装适合团队共享配置；用户级安装适合希望多个项目都能使用的个人用户。

3. 安装结束后，重新加载代码工具。不要在旧会话里继续使用已经写入磁盘的新技能，否则可能看不到新命令。

4. 在 AI 工具的对话输入框中运行初始化命令。官方 README 给出的通用命令是：

/impeccable init

如果使用 Codex，则执行：

$impeccable init

这里出现两种斜杠形式不是安装失败，而是不同客户端的命令输入规则不同。Claude Code、Cursor 等工具使用 /impeccable init，Codex 使用 $impeccable init。

官方仓库：pbakaus/impeccable

方式二：下载 ZIP，适合无法运行安装器时

如果文件来自下载页面，而不是通过 npx 安装器安装，就使用 ZIP 方式。官方 FAQ 特别强调：必须复制压缩包内容，并保留隐藏文件夹；不要让它们与 package.json 或 src/ 并排放在一个多套一层的目录中。

以 Codex 项目为例，安装完成后的关键结构是：

your-project/
├── .agents/
│   └── skills/
│       └── impeccable/
│           └── SKILL.md
├── package.json
└── src/

判断是否放对位置，要看 .agents/ 是否与 package.json、src/ 处于同一级。如果出现 your-project/impeccable/.agents/... 这样的额外外层目录，安装器或工具通常无法按预期发现技能。

macOS 的 Finder 默认可能隐藏以点开头的目录。按 Command–Shift–. 可以显示隐藏文件夹，然后确认 .agents/ 或其他工具对应的隐藏目录已经出现在项目根目录。

Cursor 的官方安装包还提供了对应检查命令。下载并解压 impeccable-cursor.zip 后，可执行：

cd your-project/
unzip ~/Downloads/impeccable-cursor.zip -d .
ls -la .cursor/skills/

最后一条命令用于确认 .cursor/skills/ 是否出现。解压完成后，还要回到 Cursor，在聊天输入框键入 /，检查是否能看到 Impeccable 提供的命令。

两种方式怎么选

在选择安装方式前，可以通过对比 CLI 安装器与 ZIP 手动安装的官方路径、操作门槛及验证标志，结合不同开发环境的特点来确定最适合自己的方案。

对比项	CLI 安装器	ZIP 手动安装
官方步骤	npx impeccable install	解压并复制到项目根目录
工具选择	安装器中选择题型工具	根据压缩包内 README.txt 判断对应目录
隐藏目录	自动选择相应构建	需要保留以点开头的文件夹
后续更新	先 npx impeccable check 查更新，再 npx impeccable update 刷新	从主页下载当前 ZIP 并替换已安装的 Impeccable 文件，然后重载工具（FAQ 原文：download the current archive from the homepage and replace the installed Impeccable files）
主要门槛	Node.js 18.19 或更高版本	需要人工确认目录层级
成功标志	重载工具并运行初始化命令	项目根目录出现对应技能目录，命令列表可见

根据上述对比，CLI 安装器能自动选择相应构建，更新走 npx impeccable check/update 一条命令，主要门槛在于 Node.js 18.19 或更高版本；ZIP 手动安装的更新方式是重新下载当前 ZIP 并替换已安装文件、随后重载工具（官方 FAQ 明确给出，不是“没有更新步骤”），门槛同样集中在文件操作的准确性——目录层级与隐藏文件夹都要对。

操作判断是：能运行 Node.js、准备长期维护配置时，优先使用 CLI 安装器；公司电脑限制执行 npx、或文件明确来自官方下载页时，再使用 ZIP。不要先用 ZIP 解压，又继续运行安装器，否则同一项目可能出现两套来源不同的技能文件。

更新与重复安装怎么处理

由 Impeccable 安装器完成的安装，可以在项目目录直接更新：

npx impeccable update

如果同时存在项目级和用户级安装，更新时需要选择要更新的目标。也可以直接指定：

npx impeccable update --project

或：

npx impeccable update --user

若命令行参数不被当前版本接受，先执行 npx impeccable update，根据交互提示选择目标，不要同时保留两套配置。官方 FAQ 只给出了上述安装器更新路径，因此这套口径适用于安装器安装，不应套用到手动复制的 ZIP。

常见卡点与处理

1. ZIP 解压后找不到技能。

先检查是否保留了隐藏文件夹，再确认技能目录是否与 package.json、src/ 同级。不要只复制可见文件；安装包中的隐藏目录本身就是技能入口。

2. Cursor 中看不到 Impeccable 命令。

安装文档说明，Cursor 的 Agent Skills 需要使用 Nightly channel 并启用 Agent Skills；标准版本当时不支持 skills。处理路径是打开 Cursor Settings，进入 Beta 部分，切换 Nightly channel，重启 Cursor，再到 Rules 部分启用 Agent Skills。

3. GitHub 登录页出现加载错误。

官方 GitHub 登录页的原话是：There was an error while loading. Please reload this page. 此时先刷新页面；若刷新后仍停留在登录界面，进入 GitHub 登录页 重新登录，再回到仓库页面。

4. 重载工具后仍没有新命令。

退出并重新打开 AI 编程工具，而不是只关闭当前对话。重新打开后先运行初始化命令，再输入 / 查看命令列表。

怎么算安装成功

安装成功需要同时满足三个可观察结果：

1. 项目根目录出现工具对应的隐藏技能目录；例如 Codex 应出现 .agents/skills/impeccable/SKILL.md。
2. 重载后的 AI 工具能识别初始化命令，并可运行 /impeccable init 或 Codex 对应的 $impeccable init。
3. 在 Cursor 等提供斜杠命令列表的工具中输入 / 后，可以看到 Impeccable 命令。

只看到 npx impeccable install 执行结束，不代表工具已经加载完成；目录、初始化命令和命令列表都可见，才算完整接通。

官方文档与安装入口

安装器、初始化命令和支持工具列表可查看 Impeccable 官方仓库；ZIP 目录结构、Node.js 要求及更新命令见 Impeccable FAQ；Cursor 的 Nightly channel、Agent Skills 与解压验证步骤见 Installation 文档（官方域，2026-11-03 实测 200）。