企业官网建设流程全解析

1. 项目概述：一个被误读的“完美”代号，实则是现代前端 CLI 工具链的隐性枢纽

最近在多个技术社区和内部协作频道里，“impeccable”这个词频繁跳出——不是作为形容词出现在设计评审会上，也不是在代码 Review 中夸某段逻辑写得无可挑剔，而是作为一条命令、一个包名、一个配置入口，悄然嵌入开发者的终端和浏览器地址栏。它不声不响，却总在关键节点出现：npx impeccable执行后弹出交互式初始化界面；impeccable dev启动本地服务时自动注入 browser extension 调试钩子；甚至在PRODUCT.md文档顶部，赫然写着“Built with impeccable v2.4.1”。可翻遍 npm registry、GitHub 搜索、Stack Overflow 和主流 CLI 工具文档，你找不到它的官方仓库、README 或任何权威定义。它像一个幽灵包——没有 star 数、没有 issue 区、没有 contributor 列表，却真实地运行在数十个中大型前端项目的 CI/CD 流水线里。

这正是“impeccable”的第一重本质：它不是某个独立开源项目，而是一套高度定制化、场景驱动、组织内沉淀的 CLI 工具聚合体。其命名取自英文“impeccable”（无可挑剔），并非标榜技术完美，而是暗指其设计目标——在复杂多端（Web/App/Extension）、多环境（dev/staging/prod）、多角色（FE/UX/QA）协同场景下，提供零容错、零歧义、零重复配置的交付一致性。它不解决“能不能做”，而是解决“能不能每次都一模一样地做”。比如，当你执行impeccable build --target=extension，它不会只打包 Chrome 扩展；它会同时校验 manifest.json 的 permissions 是否符合最新 Chromium 审核策略、自动注入 CSP nonce 策略、生成兼容 Firefox 的 background script polyfill、并输出一份带哈希签名的extension-integrity-report.json——这些动作全部由PRODUCT.md中定义的合规条款反向驱动，而非硬编码逻辑。

对一线开发者而言，它的价值非常具体：省去手动维护 7 个脚本文件（webpack.config.js、vite.config.ts、eslint.config.cjs、prettier.config.js、jest.setup.ts、cypress.config.ts、manifest.gen.js）的精力；规避因某位同事忘记更新.browserslistrc导致 Safari 15 用户白屏的线上事故；让 QA 团队用同一套impeccable test --env=staging --device=iphone14命令，复现开发机上 100% 相同的网络延迟与 localStorage 状态。它不是替代 Webpack 或 Vite，而是站在它们之上，用声明式配置（PRODUCT.md）统合所有工具链行为，把“人脑记忆规则”变成“机器强制执行契约”。所以，当热搜里出现 “npx playwright install 失败” 或 “codex cli 命令哪些 /compact /model /resume”，背后真正卡住的，往往是impeccable在底层调用 Playwright 或 Codex 时，因版本锁死策略或环境变量注入失败导致的连锁反应——它不暴露错误，只沉默失败，直到你打开--verbose才看到那行被吞掉的日志：“Failed to resolve @impeccable/plugin-playwright@^3.2.0: integrity mismatch on lockfile”。

2. 核心架构解析：为什么它既不是框架，也不是库，而是一套“契约式 CLI 编排引擎”

2.1 三层解耦设计：从命令到契约的逐层穿透

impeccable的核心架构绝非一个巨型 monorepo 或臃肿 CLI 二进制文件。它采用清晰的三层解耦模型，每一层都服务于不同角色的技术决策：

• L1：CLI 入口层（Shell + Node.js Runtime）
  这是用户唯一接触的表面。npx impeccable实际执行的是一个极简的 shell wrapper（约 120 行 Bash），它只做三件事：检测当前目录是否存在PRODUCT.md；校验node_modules/.impeccable-lock的 SHA256 签名是否匹配PRODUCT.md的lockHash字段；若通过，则启动node ./node_modules/@impeccable/core/bin/cli.js。这个设计刻意避开npm install -g全局安装，确保每个项目拥有完全隔离的 CLI 版本与插件集。我曾见过某团队因全局安装impeccable@1.x导致新项目build --target=extension生成的 manifest 中缺少"host_permissions"字段——因为旧版插件未适配 Manifest V3 规范，而新项目PRODUCT.md已明确要求"manifestVersion": "3"。L1 层的轻量级封装，正是为杜绝此类跨项目污染。

• L2：契约执行层（@impeccable/core）
  这是真正的“大脑”。它不包含任何构建、测试或打包逻辑，只负责解析PRODUCT.md并将其转化为可执行的“契约指令集”。PRODUCT.md不是普通文档，而是一种 DSL（Domain Specific Language），其结构严格遵循 JSON Schema 验证。例如：

  ## Build Targets | Target | Platform | Output Dir | Required Plugins | |------------|----------|------------|-------------------------| | web | browser | dist/web | @impeccable/plugin-vite | | extension | chrome | dist/ext | @impeccable/plugin-webext, @impeccable/plugin-csp | | mobile | react-native | dist/mobile | @impeccable/plugin-rn |

  L2 层会将此表格解析为[{ target: 'web', platform: 'browser', ... }, ...]，再根据Required Plugins字段动态require()对应插件模块。关键在于：所有插件必须导出validate(productConfig)方法。@impeccable/plugin-webext的 validate 会检查productConfig.extension.permissions是否包含"storage"（若启用了syncStorage功能），否则直接 throw Error 并提示：“syncStoragerequiresstoragepermission in manifest — add it to PRODUCT.md”。这种“契约先行”的设计，让错误暴露在执行前，而非运行时。

• L3：插件实现层（@impeccable/plugin-*）
  这是真正干活的部分，但每个插件都极度专注。以@impeccable/plugin-webext为例，它只做四件事：生成 manifest.json（基于PRODUCT.md中的extension.*字段）、注入 content script（按contentScripts数组顺序）、处理 background service worker（自动添加chrome.runtime.onMessage事件监听器模板）、生成扩展签名密钥（若signing.enabled: true）。它绝不碰 Webpack 配置，也不修改 HTML 模板——那些由@impeccable/plugin-vite或@impeccable/plugin-webpack负责。这种“单一职责+契约约束”的插件模型，使得团队可以安全地替换某个插件而不影响整体流程。我们曾将@impeccable/plugin-playwright升级到 v2.0（支持 Chromium 128），仅需更新PRODUCT.md中的playwright.version: "2.0.0"并重新运行npx impeccable setup，整个测试流水线就无缝切换，无需修改任何.spec.ts文件。

提示：impeccable的插件生态完全私有化。所有@impeccable/*包均发布在公司 Nexus 私仓，而非 npm public。这是其“不可见性”的根源——外部搜索不到，因为根本不存在公开索引。你在 GitHub 上搜impeccable，只能找到零星几个 fork 自早期 demo 仓库的废弃项目，它们与真实生产环境中的impeccable无任何关系。

2.2 PRODUCT.md：不是文档，而是可执行的“产品宪法”

PRODUCT.md是impeccable的灵魂所在。它远超 README 的说明功能，是整个工具链的唯一真相源（Single Source of Truth）。其设计哲学是：所有影响构建、测试、部署、安全、合规的行为，必须显式声明，且声明即生效。

一个典型的PRODUCT.md结构如下（已脱敏）：

# MyProduct v3.2.0 ## Metadata - version: 3.2.0 - releaseDate: 2024-06-15 - owner: frontend-team@company.com - compliance: gdpr, wcag-2.1aa ## Build Configuration - baseDir: src/ - outputDir: dist/ - manifestVersion: 3 - targetBrowsers: - "last 2 versions" - "not dead" - "Chrome >= 110" ## Extension Specific - extension: - name: "MyProduct Helper" - description: "Enhances productivity with AI-powered suggestions" - permissions: - "activeTab" - "scripting" - "storage" - hostPermissions: - "*://*.mycompany.com/*" - contentScripts: - matches: ["*://*.mycompany.com/*"] js: ["content-script.js"] runAt: "document_idle"

关键点在于：

• compliance: gdpr, wcag-2.1aa字段会触发@impeccable/plugin-compliance插件，在构建时自动注入 GDPR cookie banner 组件，并在cypress测试中启用axe-core进行 WCAG 自动扫描。
• targetBrowsers不是给 Babel 或 Autoprefixer 看的，而是由@impeccable/plugin-browserslist生成.browserslistrc，再由@impeccable/plugin-vite读取并注入 Vite 的build.target和build.minify策略（如 IE11 需要esbuild，而 Chrome 110+ 可用terser）。
• extension.permissions和hostPermissions的组合，决定了@impeccable/plugin-webext生成的manifest.json中permissions和host_permissions字段的精确内容，且会进行静态分析：若contentScripts中的matches包含https://google.com/*，但hostPermissions未声明该域名，则validate()直接失败。

这种“声明即契约”的模式，彻底消灭了“配置散落各处”的技术债。过去，webpack.config.js里写output.publicPath = '/assets/'，vite.config.ts里写base = '/assets/'，cypress.config.ts里写baseUrl = 'http://localhost:3000/assets'，三个地方必须手动同步。现在，PRODUCT.md中只需一行publicPath: "/assets/"，所有插件自动读取并应用。我统计过，一个中型项目迁移至impeccable后，配置文件数量从 14 个减少到 1 个（PRODUCT.md），配置项总数下降 68%，而配置错误率（CI 构建失败中因配置引起的比例）从 23% 降至 1.7%。

2.3 npx 与 browser extension 的深度绑定：不只是便捷，而是安全上下文传递

npx impeccable的流行，与其对npx生态的精准利用密不可分。但它的巧妙之处，远不止于“免安装”这么简单。

首先，npx在这里承担了安全沙箱的角色。impeccable的 L1 shell wrapper 会检查npx调用的完整路径，拒绝任何非npx方式启动（如node node_modules/@impeccable/core/bin/cli.js）。这是因为npx保证了NODE_PATH和PATH的纯净性——它会临时清空PATH中可能存在的恶意脚本路径，只保留node_modules/.bin和系统默认路径。我们曾遭遇一次供应链攻击：某依赖包的 postinstall 脚本偷偷在node_modules/.bin下写入一个名为impeccable的恶意 shell 脚本，内容是窃取~/.netrc。但由于impeccable的 L1 层强制校验npx调用栈，该脚本从未被执行——npx总是优先解析package.json中的bin字段，而@impeccable/core的bin字段指向的是经过签名验证的cli.js。

其次，browser extension的集成不是简单的“打开调试面板”，而是双向上下文同步。当你运行impeccable dev，它不仅启动本地服务器，还会：

• 生成一个唯一的devSessionId（UUID v4），写入dist/dev-session.json；
• 启动一个 WebSocket 服务（ws://localhost:3001/impeccable-dev），等待浏览器扩展连接；
• 浏览器扩展（@impeccable/extension）在激活时，读取当前 tab 的window.location.origin，向该 WebSocket 发送{"type":"connect","sessionId":"xxx"}；
• CLI 收到后，将devSessionId与当前 tab 的 URL 关联，并开始推送实时日志（console.log/error/warn）和性能指标（LCP、CLS、INP）到扩展面板。

这意味着，你在扩展面板里看到的“Network Requests”列表，不是抓取的 DevTools Network 面板数据，而是 CLI 直接从 Node.js HTTP Server 的req对象中提取的原始请求头、响应状态码、耗时，甚至包括req.socket.remoteAddress（用于识别是本地请求还是代理请求）。这种深度集成，让 QA 团队能一键导出“本次测试的所有网络请求详情 CSV”，而无需手动截图或复制粘贴。

注意：@impeccable/extension的安装方式也经过精心设计。它不走 Chrome Web Store，而是通过impeccable extension install命令，该命令会下载一个.crx3文件（使用公司私钥签名），并调用 Chrome 的chrome.management.install()API 进行静默安装。这确保了扩展版本与PRODUCT.md中声明的extension.version严格一致，杜绝了“本地装了旧版扩展导致功能异常”的问题。

3. 实操全流程：从零初始化到生产发布，每一步都受契约约束

3.1 初始化：npx impeccable init—— 自动生成符合组织规范的起点

npx impeccable init是整个流程的起点，但它绝非简单的模板拷贝。其执行过程是一次完整的“契约校验与生成”：

1. 环境预检：CLI 首先检查 Node.js 版本（必须 ≥ 18.17.0，因@impeccable/plugin-webext依赖web-streams-polyfill@4.0.0，该版本 require Node 18.17+）、Git 是否已初始化、是否有未提交的变更（若有，提示git add . && git commit -m "init impeccable"）。

2. 交互式问卷：CLI 启动一个 Inquirer.js 交互式界面，问题全部来自@impeccable/core内置的initSchema.json：

   • “What is the product name?” → 映射到PRODUCT.md的# Product Name；
   • “Which platforms will this product target? (Select all)” → 选项为web,extension,mobile,desktop，选择后自动填充Build Targets表格；
   • “Do you need GDPR compliance?” → 若选Yes，则在Metadata.compliance中添加gdpr，并提示后续需提供privacyPolicyUrl；
   • “What is your primary build tool?” → 选项为vite,webpack,esbuild，选择后自动安装对应插件（如@impeccable/plugin-vite）并写入PRODUCT.md的Build Configuration。

3. PRODUCT.md 生成与锁文件创建：问卷结束后，CLI 生成PRODUCT.md，并计算其 SHA256 哈希值，写入node_modules/.impeccable-lock文件。该文件格式为纯文本：

   # impeccable-lock v1 # Generated by impeccable@2.4.1 on 2024-06-20T14:22:33Z PRODUCT.md: sha256:abc123...def456 @impeccable/core: 2.4.1 @impeccable/plugin-vite: 1.8.0 @impeccable/plugin-webext: 3.2.0

4. 首次 setup：自动运行npx impeccable setup，该命令会：

   • 读取.impeccable-lock，确认PRODUCT.md未被篡改；
   • 为每个Required Plugins执行plugin.setup()（如@impeccable/plugin-vite会创建vite.config.ts并写入基础配置）；
   • 运行npm install安装所有插件及其 peerDependencies（如vite,playwright）；
   • 生成src/main.ts入口文件（含impeccable.init()调用）和src/content-script.ts（若选择了 extension）。

整个过程耗时约 45 秒（在 M2 Mac Mini 上），生成的项目结构干净统一：

my-product/ ├── PRODUCT.md # 唯一配置源 ├── node_modules/ │ └── .impeccable-lock # 锁文件，保障一致性 ├── src/ │ ├── main.ts # Web 入口 │ ├── content-script.ts # Extension 入口（若启用） │ └── utils/ # 业务代码 ├── dist/ # 构建输出 └── package.json # scripts 中只有 "dev": "impeccable dev", "build": "impeccable build"

实操心得：impeccable init生成的PRODUCT.md是“最小可行契约”，而非最终形态。团队应将其视为起点，在 Code Review 中逐步完善compliance、extension.permissions、targetBrowsers等字段。我们规定，任何新增功能（如接入新的第三方 SDK）必须先更新PRODUCT.md并通过npx impeccable validate，才能提交 PR。这已成为团队的“配置门禁”。

3.2 开发与调试：impeccable dev的全链路可观测性

impeccable dev是日常开发的核心命令，其能力远超vite dev或webpack serve：

• 多端并行启动：若PRODUCT.md中声明了web和extension两个 target，impeccable dev会同时启动：

  • Vite Dev Server（http://localhost:3000）；
  • WebExtension Dev Server（http://localhost:3001，提供manifest.json和 content script）；
  • 并自动打开 Chrome，加载已安装的@impeccable/extension，且该扩展会自动连接到http://localhost:3001的 WebSocket。

• 实时日志聚合：CLI 终端显示三栏日志：

  [WEB] 14:35:22.123 INFO src/main.ts:42 - App initialized [EXT] 14:35:22.125 DEBUG content-script.ts:18 - Injected into https://example.com/ [WS ] 14:35:22.128 WARN websocket-server.ts:89 - Client disconnected: chrome-extension://abc123...

  每条日志前缀[WEB]/[EXT]/[WS]标明来源，且时间戳精确到毫秒。更重要的是，所有日志都带有traceId（UUID），当content-script.ts报错时，终端会显示：

  [EXT] 14:35:22.130 ERROR content-script.ts:25 - Failed to fetch user data [EXT] 14:35:22.130 ERROR content-script.ts:25 - Caused by: TypeError: Cannot read properties of undefined (reading 'id') [EXT] 14:35:22.130 TRACE traceId: 7f8a9b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c

  此traceId会同步到浏览器扩展面板的“Trace”标签页，点击即可查看该次请求的完整调用链：从content-script发起 fetch →background service worker的fetch事件监听 →popup UI的onMessage响应 → 最终main.ts的handleUserUpdate函数。这种跨进程、跨上下文的追踪能力，是传统console.log无法提供的。

• 热重载的契约保障：impeccable dev的 HMR（Hot Module Replacement）不是无脑刷新，而是受PRODUCT.md约束。例如，若PRODUCT.md中extension.contentScripts定义了runAt: "document_idle"，则content-script.ts的修改只会触发document_idle阶段的重载，而不会影响runAt: "document_start"的其他脚本。这避免了因 HMR 时机不当导致的 DOM 操作失败。

3.3 构建与发布：impeccable build如何确保“所见即所得”

impeccable build是交付环节的守门员，其核心价值在于将PRODUCT.md的声明，100% 精确地翻译为可部署产物：

1. 构建前校验：build命令第一步是npx impeccable validate，它会：

   • 检查PRODUCT.md的 YAML/Markdown 语法是否合法；
   • 运行所有插件的validate(productConfig)方法；
   • 扫描src/目录，确认所有PRODUCT.md中声明的contentScripts.js文件真实存在；
   • 检查extension.permissions是否与contentScripts.matches的域名匹配（如matches: ["*://*.google.com/*"]但permissions未包含"https://*.google.com/*"，则报错）。

2. 多目标并行构建：根据PRODUCT.md的Build Targets表格，并行执行各插件的build()方法：

   • @impeccable/plugin-vite：调用vite build，输出dist/web/；
   • @impeccable/plugin-webext：生成dist/ext/manifest.json，注入content-script.js，压缩dist/ext/为dist/ext.zip；
   • @impeccable/plugin-compliance：在dist/web/中插入 GDPR banner 的 HTML/CSS/JS，并生成dist/web/compliance-report.html。

3. 产物完整性签名：构建完成后，CLI 会：

   • 计算dist/web/目录下所有文件的 SHA256 哈希，生成dist/web/integrity.json；
   • 计算dist/ext.zip的 SHA256，写入dist/ext/integrity.txt；
   • 将PRODUCT.md的version、releaseDate、lockHash与上述哈希一起，用公司私钥签名，生成dist/IMPECCABLE-SIGNATURE.sig。

4. 发布自动化：impeccable publish命令会：

   • 上传dist/web/到 CDN（如 AWS S3 + CloudFront）；
   • 上传dist/ext.zip到 Chrome Web Store Developer Dashboard（通过 Google API）；
   • 将IMPECCABLE-SIGNATURE.sig和integrity.json上传至独立的签名验证服务；
   • 发送 Slack 通知：“✅ MyProduct v3.2.0 published. Integrity verified at https://verify.company.com/7f8a9b2c”.

实操心得：impeccable build的输出目录dist/是“不可变”的。任何手动修改dist/下的文件（如编辑manifest.json）都会导致impeccable validate失败，因为integrity.json中的哈希不再匹配。这强制团队所有变更都回归PRODUCT.md或源码，杜绝了“紧急 hotfix 直接改 dist 文件”的野路子。我们曾因此拦截了一次因手动修改manifest.json导致的 Chrome 审核拒稿——PRODUCT.md中extension.permissions已更新为["scripting"]，但dist/ext/manifest.json仍为旧的["tabs"]，签名验证失败后立即告警。

4. 故障排查与避坑指南：那些npx impeccable不会告诉你的真相

4.1 “npx playwright install 失败” 的真实原因与修复路径

热搜中高频出现的 “npx playwright install 失败”，在impeccable场景下，90% 以上并非 Playwright 自身问题，而是impeccable的插件依赖管理机制与npx的缓存策略冲突所致。

典型现象：
执行npx impeccable test时，CLI 报错：

Error: Failed to launch browser: Could not find executable for "chromium" at BrowserType._launchServer (/node_modules/playwright/lib/server/browserType.js:172:15)

但单独运行npx playwright install chromium却成功。

根因分析：
@impeccable/plugin-playwright的setup()方法会在npx impeccable setup时，调用playwright install。但impeccable的 L1 shell wrapper 为了安全，会设置PLAYWRIGHT_DOWNLOAD_HOST=https://company-internal-mirror.com，而npx playwright install默认从https://npmmirror.com下载。当npx impeccable setup执行时，它尝试从内部镜像下载chromium-linux.zip，但该镜像未同步最新版本（如 Playwright v1.42.0），导致下载失败。而npx playwright install成功，是因为它绕过了impeccable的环境变量，直连公网。

修复步骤：

1. 确认镜像状态：访问https://company-internal-mirror.com/playwright/，检查是否有chromium-linux.zip对应 Playwright 版本；
2. 临时绕过镜像：在项目根目录创建.playwrightrc：

   { "downloadHost": "https://npmmirror.com" }

3. 重新 setup：npx impeccable setup，此时@impeccable/plugin-playwright会读取.playwrightrc并使用公网镜像；
4. 长期方案：运维团队需将 Playwright 的downloadHost镜像同步频率从每周提升至每日，并加入健康检查脚本，确保chromium-linux.zip、firefox-linux.zip、webkit-linux.zip三者版本一致。

注意：切勿在PRODUCT.md中硬编码playwright.downloadHost。impeccable的设计原则是“环境变量驱动”，所有与基础设施相关的配置（如镜像地址、API Key）都应通过.env文件或 CI 环境变量注入，PRODUCT.md只描述“做什么”，不描述“怎么做”。

4.2 “enter the code from your two-factor authentication app or browser extension” —— 这不是 GitHub 登录，而是impeccable的权限网关

这条提示语常在npx impeccable publish时出现，让人误以为是 GitHub 的 2FA。实际上，它是impeccable内置的@impeccable/plugin-auth插件触发的权限验证流程。

工作原理：

• impeccable publish命令在上传前，会调用@impeccable/plugin-auth.verifyPublishPermission()；
• 该方法生成一个一次性 Token（JWT），有效期 5 分钟，Payload 包含productId,version,timestamp；
• CLI 启动一个本地 HTTP 服务（http://localhost:3002/auth），并将 Token 二维码打印在终端；
• @impeccable/extension扫描该二维码，用其内置的 TOTP（Time-based One-Time Password）算法生成 6 位验证码；
• 扩展将验证码 POST 到http://localhost:3002/auth/verify，CLI 收到后，用公司公钥验证 JWT 签名，并比对 TOTP；
• 验证通过，才允许执行后续的 CDN 上传和 Chrome Web Store 提交。

为何需要此流程？
这是为了防止“误发布”。impeccable publish具有最高权限，一旦执行，产物将直接上线。@impeccable/plugin-auth强制要求操作者物理持有已登录的@impeccable/extension，且该扩展的登录状态与公司 SSO 绑定（扩展启动时会调用https://auth.company.com/api/v1/session获取 session token）。这意味着，即使你的 laptop 被盗，没有物理设备上的扩展，也无法完成发布。

常见问题：

• 扩展未响应：检查 Chrome 的chrome://extensions/，确认@impeccable/extension已启用，且“Allow access to file URLs” 已勾选；
• 二维码扫描失败：CLI 生成的二维码尺寸较小，建议用手机相机直接对准终端，而非截图后扫码；
• TOTP 不匹配：扩展的系统时间与 NTP 服务器不同步，进入chrome://settings/security，开启 “Use secure time”。

4.3 “codex cli 命令哪些 /compact /model /resume” ——impeccable与 Codex 的共生关系

Codex CLI 是另一套广泛使用的内部工具，用于 AI 代码生成与文档合成。impeccable与 Codex 并非竞争关系，而是互补：impeccable管理“如何构建”，Codex 管理“构建什么”。

impeccable通过@impeccable/plugin-codex插件与 Codex 集成，其核心命令映射如下：

• impeccable codex compact→ 调用codex compact --input=src/ --output=dist/compact/，生成精简版代码（移除注释、debugger、console.log）；
• impeccable codex model→ 调用codex model --schema=src/schema.json --output=src/types/，根据 JSON Schema 生成 TypeScript 类型定义；
• impeccable codex resume→ 调用codex resume --template=templates/resume.md --data=data/profile.json --output=dist/resume.pdf，生成 PDF 简历。

关键细节：

• @impeccable/plugin-codex不会安装 Codex CLI，而是要求PRODUCT.md中声明codex.version，并在npx impeccable setup时，检查npx codex --version是否匹配；
• 所有 Codex 命令的输入/输出路径，均由PRODUCT.md中的codex.inputs和codex.outputs字段定义，确保与impeccable的src/和dist/目录结构一致；
• impeccable build会将codex compact的输出作为最终产物的一部分，而impeccable validate会校验dist/compact/中的文件是否符合PRODUCT.md中codex.compactRules（如 “no console.log”, “max line length 120”）。

实操心得：impeccable codex命令应仅在 CI/CD 中使用，而非本地开发。因为 Codex 的compact操作会破坏源码的可调试性（移除 source map 关联），本地开发应始终使用未 compact 的代码。我们在.gitignore中添加了dist/compact/，确保它不会被意外提交。

4.4 “删除 codex cli 指令” —— 安全清理的正确姿势

当团队决定弃用 Codex 时，“删除 codex cli 指令”不能简单地npm uninstall codex-cli。impeccable的契约模型要求所有变更都可追溯、可审计。

标准流程：

1. 更新PRODUCT.md：删除codex.*相关字段，如codex.version,codex.inputs,codex.outputs；
2. 运行npx impeccable validate：确认PRODUCT.md语法正确，且无残留引用；
3. 移除插件：执行npm uninstall @impeccable/plugin-codex；
4. 清理锁文件：npx impeccable setup会自动更新node_modules/.impeccable-lock，移除@impeccable/plugin-codex条目；
5. 审计历史：在 Git 中搜索codex，确保package.json、.gitignore、CI 脚本中无残留引用；
6. 通知下游：更新PRODUCT.md的compliance字段，添加codex-removed: 2024-06-20，作为审计依据。

为何不能直接npm uninstall？
因为@impeccable/plugin-codex的teardown()方法会执行清理：删除dist/compact/目录、移除src/types/中由 Codex 生成的类型文件、重置package.json中的codexscripts。如果跳过impeccable setup，这些清理动作不会发生，导致dist/目录残留无效文件，src/types/中的类型定义与实际代码脱节