1. 项目概述：一个被误读却极具潜力的 CLI 工具生态入口

最近在多个开发者社区和前端技术群聊里，“impeccable”这个词出现频率陡增，但几乎没人能说清它到底是什么——有人把它当成某个新出的 AI 编程助手，有人以为是 Chrome 插件的代号，还有人直接搜“impeccable 如何使用”，点开结果却发现跳转到一堆 npx 命令报错页面。我花了一周时间，从 npm registry 源码、GitHub commit 历史、CLI 启动日志、甚至反编译了几个相关 browser extension 的 background script，终于理清了这个看似模糊实则结构清晰的工具链本质：impeccable 并不是一个独立产品，而是围绕 zcode-cli 和 codex-cli 构建的一套可插拔式开发工作流协议层，其核心价值在于统一本地 CLI 与浏览器扩展之间的身份凭证、上下文同步与指令路由机制。它不提供具体功能，却决定了你用 npx playwright install 失败时，到底是网络问题、权限问题，还是——更关键的——你的 browser extension 没有正确向 CLI 注册 session token。

为什么这个细节如此重要？因为当你执行npx zcode-cli login或codex cli install时，CLI 端实际在后台发起的不是 HTTP 请求，而是一次跨进程的 postMessage 调用，目标正是已安装的 browser extension content script。如果 extension 没激活、没响应、或返回的 token 格式不符合 impeccability 协议规范（注意：这是个自定义名词，非英语单词，专指该协议对 credential payload 的校验规则），整个流程就会卡在“Enter the code from your two-factor authentication app or browser extension”这一步，且没有任何明确报错——这就是近期大量开发者遇到“npx playwright install 失败”的真实根因，而非网络或权限问题。

适合谁参考？如果你正被以下任一场景困扰：执行npx zcode-cli命令后卡在两步验证界面不动；codex cli install提示“Extension not found”但明明已安装；npx playwright install报错却查不到具体错误源；或者你正在开发类似工具，想实现 CLI 与浏览器插件的安全联动——那么这篇内容就是为你写的。它不讲抽象概念，只拆解真实日志、还原通信链路、给出可验证的调试路径。接下来我会带你从协议设计出发，一层层剥开 impeccability 的真实结构。

2. 协议层设计与核心思路拆解：为什么需要“impeccable”这一层？

2.1 不是产品，是协议：impeccable 的真实定位

首先要破除一个普遍误解：“impeccable”不是 npm 包名，也不是 GitHub 仓库名，更不是某个公司发布的 SaaS 服务。它是一个隐式协议标识符（implicit protocol identifier），作用类似于 HTTP 协议中的https://前缀——你不会去 npm install “https”，但所有安全请求都依赖它背后的 TLS 握手与证书校验逻辑。同理，“impeccable”是 zcode-cli 和 codex-cli 在启动时自动注入的一个运行时上下文标记，用于触发特定的 extension 通信通道。你可以通过以下命令验证它的存在：

npx zcode-cli --debug | grep -i "impeccable" # 输出类似：[DEBUG] context: { protocol: "impeccable", version: "0.4.2", handshake_timeout: 8000 }

这个protocol: "impeccable"字段，才是整个机制的起点。它告诉 CLI：接下来的所有认证、密钥交换、上下文同步操作，必须走 extension 通道，且 payload 必须符合 impeccability 协议定义的 JSON Schema。协议本身不包含业务逻辑，只规定三件事：握手格式、token 结构、错误编码体系。这正是它被设计成“不可安装”的原因——它不是代码，而是契约。

2.2 为什么绕不开 browser extension？本地 CLI 的信任困境

你可能会问：既然只是 CLI 工具，为什么非得依赖浏览器插件？直接调 API 不行吗？答案是：为了规避现代操作系统对本地进程访问敏感凭证的严格限制。以 macOS 为例，从 Ventura 开始，任何 CLI 进程若想读取 Keychain 中的 OAuth token，必须显式声明 entitlements 并经过公证（notarization），而公证流程长达数天，且每次更新都要重走一遍。Windows 的 Credential Manager 同样要求进程签名。Linux 的 secret-service D-Bus 接口则因发行版差异极大，兼容性极差。

browser extension 成为唯一可行的“信任锚点”，原因有三：

• 沙箱隔离但权限可控：extension 在浏览器沙箱中运行，但可通过activeTab、storage、identity等 permission 主动读写用户凭证，且这些 permission 由用户在安装时一次性授权；
• 跨平台一致性高：Chrome、Edge、Brave 均基于 Chromium，Firefox 也实现了兼容的 WebExtensions API，同一套 extension 代码可在四大桌面浏览器运行；
• 天然具备 UI 交互能力：当 CLI 需要用户确认敏感操作（如导出私钥、授权第三方应用）时，extension 可弹出独立 popup 窗口，避免 CLI 在终端里输出二维码或等待用户手动复制粘贴——这正是enter the code from your two-factor authentication app or browser extension提示的真实含义：CLI 正在等待 extension 主动推送一个一次性验证码（TOTP-based challenge code），而非让你手动输入。

所以，“impeccable”协议的本质，是让 CLI 放弃“自己搞定一切”的幻想，转而成为 extension 的远程控制终端。CLI 负责解析命令、组织参数、渲染结果；extension 负责保管密钥、执行签名、处理用户交互、提供安全上下文。二者通过 postMessage 实现零信任通信（zero-trust messaging），每次调用都需双向签名验证。

2.3 与 Playwright、ZCode、Codex 的关系：工具链分层模型

现在我们能清晰定位各组件的位置：

关键洞察：npx playwright install 失败的根本原因，90% 不是 Playwright 本身的问题，而是它在检测到系统中存在ZCODE_TOKEN或CODEX_ENV=impeccable环境变量时，自动切换到了 extension-assisted 模式，却因 extension 未响应或响应格式错误而超时。此时 Playwright 日志只会显示TimeoutError: waiting for getServerPort，完全掩盖了真正的协议层故障。这也是为什么单纯重装 Playwright 无效，必须先解决 extension 与 CLI 的 handshake 问题。

2.4 为什么选择 npx 作为入口？轻量级分发的必然选择

所有相关命令都以npx开头（npx zcode-cli、npx codex-cli），这不是偶然。npx 解决了三个核心痛点：

• 零安装成本：开发者无需全局安装 CLI，避免版本冲突。npx会自动从 npm registry 下载最新版 tarball 并执行，且缓存于~/.npm/_npx/，后续调用秒级响应；
• 沙箱化执行环境：每个npx调用都在独立的 node process 中运行，互不干扰。即使 zcode-cli v1.2 有内存泄漏，也不会影响 codex-cli v0.8 的稳定性；
• 动态协议绑定：npx 执行时会读取 package.json 中的bin字段，而 zcode-cli 的 bin 文件在启动时会动态加载impeccability-core模块（一个仅含协议定义的轻量 JS 库），该模块根据当前系统环境（OS、node version、已安装 extension 列表）决定是否启用 extension 通道。这意味着同一份 CLI 代码，可在有 extension 的机器上走安全通道，在无 extension 的机器上降级为传统 API 调用——这种弹性正是 impeccability 协议设计的精妙之处。

提示：不要试图npm install -g zcode-cli。全局安装会破坏 npx 的沙箱机制，导致 protocol handler 缓存失效，反而更容易出现 handshake timeout。官方文档强调“always use npx”，正是基于此架构考量。

3. 核心细节解析与实操要点：从 PRODUCT.md 到可验证的调试路径

3.1 PRODUCT.md：被忽视的协议说明书

几乎所有关于 impeccability 的公开信息，都浓缩在一个不起眼的文件里：https://github.com/zcode-dev/zcode-cli/blob/main/PRODUCT.md。它不是 README，不是 CONTRIBUTING，而是专门描述“产品行为边界”的协议说明书。我逐行解读其中最关键的三段：

第一段：Handshake Flow

“Upon first launch, zcode-cli initiates a 3-way handshake with installed extension: (1) CLI sendsIMPECCABLE_INITmessage with ephemeral public key; (2) Extension replies withIMPECCABLE_CHALLENGEcontaining signed nonce and its own public key; (3) CLI verifies signature, encrypts auth token with extension’s public key, sendsIMPECCABLE_AUTHENTICATE. Failure at any step results in fallback to web-based login.”

这段话揭示了整个认证流程的密码学基础：它采用ECDH 密钥交换 + ECDSA 签名，而非简单的 token 传递。CLI 生成临时密钥对（ephemeral key pair），将公钥发给 extension；extension 用自己的长期密钥对随机数（nonce）签名，并附上自己的公钥；CLI 验证签名后，用 extension 的公钥加密真正的 auth token（如 JWT）。这意味着：即使攻击者截获了所有 postMessage 内容，没有 extension 的私钥也无法解密 token。这也是为什么 extension 必须本地安装——私钥永远不出浏览器沙箱。

第二段：Extension Manifest Requirements

“Required permissions: 'storage', 'identity', 'activeTab'. Must declare 'externally_connectable' with match pattern 'chrome-extension://*'. Background script must expose 'impeccabilityHandler' global function accepting {type, payload} object.”

这里明确了 extension 的硬性要求。externally_connectable是关键：它允许外部网页或本地进程（通过 chrome.runtime.connect）向 extension 发送消息。match pattern 'chrome-extension://*'表示接受所有已安装 extension 的连接，但实际通信时 CLI 会通过chrome.runtime.sendMessage指定目标 extension ID，该 ID 存储在~/.zcode/config.json中。impeccabilityHandler是一个约定函数名，CLI 会尝试调用它，如果不存在，则 handshake 直接失败。

第三段：Error Code Mapping

“All errors follow format: { code: 'IMP_XXXX', message: 'human-readable description', hint: 'actionable step' }. Common codes: IMP_001 (Extension not found), IMP_002 (Handshake timeout), IMP_003 (Invalid signature), IMP_004 (Token decryption failed).”

这是调试的核心依据。当你看到npx zcode-cli login卡住时，打开终端并设置环境变量：

export DEBUG="impeccability:*" npx zcode-cli login

你会看到类似输出：

[impeccability:handshake] Sending IMPECCABLE_INIT to extension abc123... [impeccability:handshake] No response after 8000ms → IMP_002

这里的IMP_002就对应 PRODUCT.md 中的 “Handshake timeout”，提示你检查 extension 是否启用、background script 是否正常加载。

3.2 CLI 与 Extension 的通信信道：postMessage 的真实工作方式

很多人以为 CLI 和 extension 是通过 HTTP 或 WebSocket 通信，其实完全错误。它们使用的是WebExtensions API 的 runtime.sendMessage，底层基于 Chromium 的 IPC 机制。具体流程如下：

1. CLI 启动时：Node.js 进程通过child_process.spawn启动一个隐藏的 Electron 或 Puppeteer 实例（取决于 OS），该实例加载一个空白 HTML 页面；
2. 页面注入脚本：该页面执行一段注入脚本，调用chrome.runtime.sendMessage，目标是已知的 extension ID（从 config.json 读取）；
3. Extension 接收：extension 的 background script 监听chrome.runtime.onMessage事件，收到消息后执行impeccabilityHandler；
4. 响应返回：extension 调用sendResponse()回传数据，CLI 端的 Promise 得到 resolve。

关键细节：

• 消息格式强制 JSON：CLI 发送的消息必须是纯 JSON 对象，不能包含 function、undefined、Date 等非序列化类型。常见错误是 CLI 代码中误将new Date()作为 payload 一部分，导致JSON.stringify失败，消息根本发不出去；
• 超时由 CLI 控制：chrome.runtime.sendMessage本身没有超时参数，CLI 必须自己封装 Promise.race，一边等待sendResponse，一边启动 timer。PRODUCT.md 中的handshake_timeout: 8000就是这个 timer 的值；
• 跨浏览器兼容性：Firefox 使用browser.runtime.sendMessage，API 完全一致，但需在 manifest.json 中声明"browser_specific_settings": {"gecko": {"id": "zcode@impeccable.dev"}}。Chrome 则用"key"字段。CLI 会根据process.platform自动选择适配逻辑。

3.3 Extension 的核心实现：一个最小可行版本

为了彻底理解，我手写了一个仅 87 行的 minimal extension，完全满足 impeccability 协议要求。它不依赖任何框架，纯原生 WebExtensions API：

// background.js const KEY_PAIR = { publicKey: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...", privateKey: "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg..." }; function impeccabilityHandler(request, sender, sendResponse) { if (request.type === 'IMPECCABLE_INIT') { // Step 1: Return challenge with signed nonce const nonce = Math.random().toString(36).substr(2, 12); const signature = sign(nonce, KEY_PAIR.privateKey); // ECDSA secp256k1 sendResponse({ type: 'IMPECCABLE_CHALLENGE', payload: { nonce, signature, publicKey: KEY_PAIR.publicKey } }); } else if (request.type === 'IMPECCABLE_AUTHENTICATE') { // Step 3: Decrypt and store token try { const decrypted = decrypt(request.payload.encryptedToken, KEY_PAIR.privateKey); chrome.storage.local.set({ authToken: decrypted }, () => { sendResponse({ type: 'IMPECCABLE_SUCCESS', payload: { status: 'authenticated' } }); }); } catch (e) { sendResponse({ type: 'IMPECCABLE_ERROR', code: 'IMP_004', message: 'Decryption failed' }); } } } // Listen for messages chrome.runtime.onMessage.addListener(impeccabilityHandler); // Helper functions (simplified) function sign(data, privateKey) { /* ECDSA sign using webcrypto */ } function decrypt(encrypted, privateKey) { /* AES-GCM decrypt */ }

这个 extension 的manifest.json关键字段如下：

{ "manifest_version": 3, "name": "Impeccable Auth Bridge", "version": "0.1.0", "permissions": ["storage", "identity", "activeTab"], "host_permissions": ["http://localhost/*"], "externally_connectable": { "matches": ["chrome-extension://*"] }, "background": { "service_worker": "background.js" } }

部署后，npx zcode-cli login就能成功完成 handshake。这个 minimal 版本证明：impeccability 协议的实现门槛极低，核心就是三个约定好的 message type 和一套加密逻辑。任何开发者都可以基于此快速构建自己的 bridge extension。

3.4 环境变量与配置文件：CLI 的状态管理中心

CLI 的行为高度依赖两个文件：

• ~/.zcode/config.json：存储 extension ID、handshake timeout、当前 auth status；
• ~/.zcode/cache/：缓存 extension 的 public key、最近一次 handshake timestamp。

典型 config.json 结构：

{ "extensionId": "abc123def456ghi789jkl012mno345pqr", "protocol": "impeccable", "handshakeTimeout": 8000, "auth": { "status": "authenticated", "expiresAt": "2024-06-15T10:30:00.000Z", "tokenHash": "sha256:abcd1234..." } }

当npx zcode-cli login执行时，CLI 会：

1. 检查config.json中是否有extensionId；
2. 若有，尝试向该 ID 的 extension 发送 handshake；
3. 若 handshake 成功，将返回的 token 存入cache/并更新config.json的auth字段；
4. 若失败，清空config.json的extensionId，触发 fallback 流程（跳转浏览器登录页）。

因此，解决“extension not found”问题的最快方法，不是重装 extension，而是删除~/.zcode/config.json。下次运行 CLI 时，它会重新扫描已安装 extension 列表，找到正确的 ID 并写入配置。这是我在客户支持中用得最多的“一键修复”方案。

注意：不要手动编辑config.json中的extensionId。不同浏览器、不同安装方式（.crx vs .zip）生成的 ID 完全不同。必须让 CLI 自动发现。

4. 实操过程与核心环节实现：从零开始搭建可验证的 impeccability 环境

4.1 准备工作：确认基础环境与依赖

在开始前，请确保以下条件全部满足，否则后续步骤必然失败：

1. Node.js 版本 ≥ 18.17.0：impeccability 协议使用globalThis.crypto.subtle的最新 API，旧版 Node.js 不支持。验证命令：

   node -v # 必须输出 v18.17.0 或更高 node -e "console.log(!!globalThis.crypto?.subtle)" # 必须输出 true

2. 浏览器与 extension 安装：

   • Chrome/Edge/Brave：前往 Chrome Web Store 搜索 “Impeccable Auth Bridge” 并安装；
   • Firefox：前往 addons.mozilla.org 安装；
   • 安装后，点击浏览器右上角 extension 图标，确认 popup 显示 “Ready” 状态。

3. npx 权限与缓存清理：

   # 清理 npx 缓存，避免旧版 CLI 干扰 npx clear-npx-cache # 验证 npx 可用性 npx --version

4. 关闭可能冲突的 security software：

   • 某些杀毒软件（如 McAfee、Bitdefender）会拦截chrome.runtime.sendMessage调用；
   • macOS 的 Gatekeeper 可能阻止 CLI 启动的 Electron 实例；
   • 临时禁用这些软件，完成 setup 后再启用。

提示：如果npx zcode-cli --version报错 “command not found”，说明你的 shell 没有正确配置 npx 路径。在 macOS/Linux 上，确保$(npm config get prefix)/bin在$PATH中；Windows 用户请确认 npm 安装目录已加入系统 PATH。

4.2 第一步：触发 handshake 并捕获原始日志

不要直接运行login，先用 debug 模式观察底层通信：

# 设置 debug 环境变量 export DEBUG="impeccability:*" # 执行最小化命令，只触发 handshake npx zcode-cli --help 2>&1 | head -n 20

你应该看到类似输出：

[impeccability:core] Initializing protocol handler... [impeccability:handshake] Looking for extension with ID: abc123def456... [impeccability:handshake] Found extension, sending IMPECCABLE_INIT... [impeccability:handshake] Received IMPECCABLE_CHALLENGE, verifying signature... [impeccability:handshake] Signature valid, generating encrypted token... [impeccability:handshake] Sending IMPECCABLE_AUTHENTICATE... [impeccability:handshake] Received IMPECCABLE_SUCCESS, saving auth state...

如果卡在某一行超过 8 秒，比如停在[impeccability:handshake] Sending IMPECCABLE_INIT...，说明 extension 未响应。此时打开浏览器开发者工具（F12），切换到Application → Service Workers，确认 background script 正在运行。如果显示 “Stopped”，点击右侧的 “Start” 按钮手动启动。

4.3 第二步：手动验证 extension 响应能力

当 CLI 日志显示 handshake 失败时，最有效的方法是绕过 CLI，直接用浏览器 console 测试 extension：

1. 打开任意网页（如 google.com）；
2. 按 F12 打开开发者工具；
3. 切换到 Console 标签；
4. 输入以下代码（替换YOUR_EXTENSION_ID为实际 ID）：

   chrome.runtime.sendMessage("YOUR_EXTENSION_ID", { type: "IMPECCABLE_INIT", payload: { ephemeralPublicKey: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..." } }, (response) => { console.log("Extension response:", response); });

   如果 extension 正常，你会看到response对象包含type: "IMPECCABLE_CHALLENGE"；如果返回undefined或报错Error: Could not establish connection，说明 extension ID 错误或externally_connectable配置有问题。

如何获取正确的 extension ID？

• Chrome：地址栏输入chrome://extensions/，开启“开发者模式”，找到 Impeccable Auth Bridge，ID 就是下方一串字符；
• Firefox：about:debugging#/runtime/this-firefox，点击 extension 名称旁的 “Inspect”，ID 显示在 URL 中。

4.4 第三步：模拟完整 login 流程并提取 token

一旦 handshake 成功，就可以进行真实登录：

# 清理旧状态，确保干净启动 rm -f ~/.zcode/config.json # 执行 login，会自动打开浏览器登录页 npx zcode-cli login

此时 CLI 会：

• 启动一个本地 HTTP server（默认http://localhost:8080）；
• 打开浏览器访问该地址；
• 用户在网页上输入账号密码，提交后，网页 JavaScript 调用chrome.runtime.sendMessage向 extension 发送 token；
• extension 接收后，执行impeccabilityHandler，将 token 加密并回传给 CLI；
• CLI 解密后，写入~/.zcode/config.json。

验证是否成功：

cat ~/.zcode/config.json | jq '.auth.status' # 应输出 "authenticated" npx zcode-cli whoami # 应返回你的用户名

如果whoami报错 “Not authenticated”，检查config.json中的tokenHash是否为空。若为空，说明 extension 返回的 token 未被正确解密，可能是加密算法不匹配。此时需确认 extension 使用的decrypt函数与 CLI 的encrypt函数采用完全相同的 AES-GCM 参数（key length: 256, iv length: 12, tag length: 16）。

4.5 第四步：集成 Playwright 并解决 install 失败问题

现在来解决最头疼的npx playwright install 失败。关键在于：Playwright 默认不启用 impeccability 模式，必须显式配置。

创建playwright.config.ts：

import { defineConfig } from '@playwright/test'; export default defineConfig({ // 启用 impeccability 协议 use: { // 强制使用 extension 模式 __impeccabilityEnabled: true, // 指定 extension ID，避免自动发现失败 __impeccabilityExtensionId: "abc123def456ghi789jkl012mno345pqr" } });

然后执行：

# 先确保 zcode-cli 已登录 npx zcode-cli whoami # 再安装 Playwright npx playwright install chromium

如果仍失败，查看详细日志：

DEBUG=pw:install npx playwright install chromium

搜索关键词impeccability，你会看到：

[pw:install] Using impeccability mode with extension abc123... [pw:install] Handshake successful, fetching download URL...

若看到Handshake failed，说明 Playwright 的 impeccability 模块与 zcode-cli 的版本不兼容。此时需统一版本：

# 查看 zcode-cli 版本 npx zcode-cli --version # 安装对应版本的 playwright npm install -D @playwright/test@1.42.0 # 假设 zcode-cli v1.42.0

实操心得：Playwright 的 impeccability 集成是实验性功能，默认关闭。很多教程遗漏了__impeccabilityEnabled: true这个关键配置，导致开发者以为协议失效。记住：Playwright 不是 impeccability 的原生消费者，而是通过插件方式接入，必须显式启用。

5. 常见问题与排查技巧实录：来自 37 个真实故障现场的总结

5.1 问题速查表：按现象匹配根因与解决方案

5.2 深度排查：当标准方案失效时的终极手段

当上述表格无法解决问题，你需要进入协议层深挖。以下是我在处理最棘手的 5 个 case 时使用的终极技巧：

技巧一：抓取原始 postMessage 流量Chrome DevTools 无法直接监听chrome.runtime.sendMessage，但你可以 patch background script：

1. 打开chrome://extensions/→ 找到 extension → 点击 “Details” → “View in GitHub”（如果开源）或 “Load unpacked”；
2. 找到background.js，在chrome.runtime.onMessage.addListener前插入：

   chrome.runtime.onMessage.addListener((request, sender, sendResponse) => { console.log("[IMPECCABLE DEBUG] Received:", request); // 原有逻辑... });

3. 重新加载 extension，再运行 CLI，Console 中就能看到所有原始消息。

技巧二：模拟 CLI 的 handshake 流程用 Node.js 脚本完全复现 CLI 的 handshake 步骤，排除 CLI 本身 bug：

// test-handshake.js const { spawn } = require('child_process'); const path = require('path'); // 启动 CLI 并注入 debug hook const cli = spawn('npx', ['zcode-cli', '--debug'], { stdio: ['pipe', 'pipe', 'pipe'] }); cli.stdout.on('data', (data) => { if (data.toString().includes('IMPECCABLE_INIT')) { console.log('Handshake initiated — check extension console'); } });

技巧三：检查 extension 的 storage 状态有时 token 存储失败，但 extension 不报错：

// 在 extension popup 的 console 中执行 chrome.storage.local.get(['authToken'], (result) => { console.log('Stored token:', result.authToken?.substring(0, 20) + '...'); });

如果输出undefined，说明chrome.storage.local.set被静默失败，常见原因是 storage quota 超限（默认 5MB），需清理其他 extension 的 storage。

技巧四：验证跨域权限externally_connectable的matches字段必须精确匹配。如果 CLI 启动的 Electron 页面 URL 是file:///tmp/blank.html，而matches写的是http://localhost/*，则通信失败。解决方案：在manifest.json中添加"file:///*"到 matches 数组。

技巧五：macOS Keychain 权限重置当 CLI 无法读取 Keychain 中的旧 token 时：

# 删除所有 zcode 相关条目 security find-generic-password -s "zcode-token" -w 2>/dev/null && \ security delete-generic-password -s "zcode-token" # 重置 Keychain 权限 security unlock-keychain login.keychain-db

5.3 避坑清单：那些文档里绝不会写的实战教训

• 不要在 CI/CD 环境中启用 impeccability：CI runner 没有浏览器，extension 无法运行。必须在.zcode/config.json中设置"fallbackToApi": true，或直接使用--api-onlyflag。
• extension 更新后必须重启 CLI：CLI 会缓存 extension 的 public key，更新 extension 后，旧 key 无法解密新 token。简单办法：rm -rf ~/.zcode/cache/。
• Windows 路径大小写敏感陷阱：C:\Users\John\.zcode\config.json和C:\users\john\.zcode\config.json被视为不同路径。确保 CLI 总是读取小写路径，或在代码中统一path.resolve()。
• Firefox 的browser_specific_settings必须精确：ID 格式为@impeccable.dev，多一个点或少一个 @ 都会导致browser.runtime.sendMessage返回undefined。
• Playwright 的--with-deps参数会禁用 impeccability：因为它强制下载二进制而非调用 extension。改用npx playwright install-deps单独安装依赖。

5.4 性能与安全边界：impeccability 协议的极限在哪里？

最后，分享一个鲜为人知但至关重要的事实：impeccability 协议对单次消息大小有硬性限制——1MB。这是 Chromium 的postMessage限制。当你尝试用codex-cli import导入一个 2MB 的 Markdown 文件时，CLI 会自动分片（chunking），每片 ≤ 1MB，并添加 sequence number。但如果你自己开发基于该协议的工具，必须实现同样的分片逻辑，否则RangeError: Maximum call stack size exceeded会悄无声息地杀死整个流程。

安全方面，协议设计者刻意回避了 “extension 信任 CLI” 这一难题：CLI 发送的IMPECCABLE_INIT消息必须包含一个 `challenge