插件打包流程完全指南Impeccable 的 build.js 如何一鍵生成 dist 與 plugin 產(chǎn)物【免費(fèi)下載鏈接】impeccableThe design language that makes your AI harness better at design.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/im/impeccableImpeccable 是一款為 AI 編碼代理提供設(shè)計(jì)技能與反模式檢測(cè)的開源項(xiàng)目。它的插件打包流程由 scripts/build.js 這個(gè)主編排器驅(qū)動(dòng)讀取skill/下的源文件通過配置驅(qū)動(dòng)的轉(zhuǎn)換器工廠一次性生成 17 種 AI 工具Cursor、Claude Code、Gemini、Codex 等的 provider 產(chǎn)物到dist/再組裝 universal 目錄、打包 ZIP、同步倉庫根目錄的 harness 目錄最終產(chǎn)出./plugin插件子樹。本文帶你走讀這條完整流水線。構(gòu)建命令從哪條入口跑起來在 package.json 中定義了四條常用構(gòu)建命令命令作用bun run build:skills生成 provider 產(chǎn)物跳過倉庫根目錄同步--skip-root-syncbun run build:skills:release完整構(gòu)建含根目錄同步與./plugin子樹生成bun run build構(gòu)建后把dist拷入build/_data/dist供 Cloudflare Pages 下載功能讀取bun run clean清理dist與build目錄構(gòu)建流程在 docs/DEVELOP.md 的 “Building” 一節(jié)有簡明說明前置條件只有 Bun無需外部依賴。構(gòu)建流水線四步走第一步讀取源技能文件build()函數(shù)從 skill/SKILL.src.md 及其reference/、scripts/兄弟目錄讀取源文件readSourceFiles并統(tǒng)計(jì)用戶可調(diào)用的命令數(shù)。源文件是唯一的事實(shí)來源所有 provider 產(chǎn)物都由它派生。第二步配置驅(qū)動(dòng)的 provider 轉(zhuǎn)換這是整個(gè)打包流程最精妙的部分。scripts/lib/transformers/providers.js 中的PROVIDERS映射表為每個(gè) AI 工具定義一份配置輸出目錄如.claude、.cursor、frontmatter 字段白名單、是否發(fā)射 hooks、agent 格式等。scripts/lib/transformers/factory.js 的createTransformer(config)工廠根據(jù)配置生成轉(zhuǎn)換函數(shù)替換{{model}}、{{config_file}}、{{ask_instruction}}等占位符按各 provider 支持的字段輸出 frontmatter并寫入 provider 專屬標(biāo)記塊如codex標(biāo)簽。build.js只需一個(gè)循環(huán)即可完成全部 17 個(gè) provider 的轉(zhuǎn)換for (const config of Object.values(PROVIDERS)) { const transform createTransformer(config); transform(skills, DIST_DIR, { skillsVersion }); }新增一個(gè) provider 只需在PROVIDERS里加一條配置構(gòu)建循環(huán)會(huì)自動(dòng)拾取這正是配置驅(qū)動(dòng)架構(gòu)的價(jià)值。第三步組裝 universal 目錄并打包 ZIPassembleUniversal()把各 provider 的 dotfile 目錄.cursor/、.claude/、.gemini/等合并進(jìn)dist/universal/并生成一份README.txt說明每個(gè)文件夾對(duì)應(yīng)哪個(gè)工具因?yàn)檫@些隱藏目錄在 Finder 里默認(rèn)不可見。隨后 scripts/lib/zip.js 用 archiver 庫而非 shell 的zip生成universal.zip保證在 Cloudflare Pages 構(gòu)建環(huán)境等無 zip 命令的平臺(tái)上也能跨平臺(tái)工作。值得注意的是它的“大聲失敗”策略ZIP 為空或 0 字節(jié)會(huì)直接拋錯(cuò)退出絕不讓空產(chǎn)物靜默上線。第四步同步根目錄并生成 plugin 子樹不加--skip-root-sync時(shí)構(gòu)建會(huì)把各 provider 的技能鏡像同步到倉庫根目錄的.cursor/skills、.claude/skills等位置mirrorDirContentsSync只替換生成物保留本地 harness 的私有產(chǎn)物并清理廢棄技能殘留。同時(shí)構(gòu)建./plugin/子樹從.claude-plugin/plugin.json派生出plugin/.claude-plugin/plugin.jsonskills 字段帶尾斜杠這是 Issue #86 中修復(fù)的加載陷阱、復(fù)制技能與 agents、寫入plugin/hooks/hooks.json鉤子清單。這個(gè)約 0.3 MB 的精瘦目錄就是 Claude Code 市場(chǎng)與 Grok Build 的安裝源。另外OpenAI 插件是獨(dú)立產(chǎn)物stageOpenAIPlugin每次構(gòu)建都會(huì)重新生成dist/openai/并打包openai-plugin.zip確保上傳包與本地預(yù)覽永不漂移。六道質(zhì)量閘門構(gòu)建為什么經(jīng)?！笆　眀uild.js的后半段是一組驗(yàn)證器任何一道不通過都會(huì)以非零碼退出版本一致性validatePluginVersions見 scripts/lib/validate-plugin-versions.jsmarketplace、./plugin子樹、捆綁的 SKILL.md 三處版本必須與根plugin.json完全一致防止版本漂移issue #274。清單形狀validatePluginManifestShape見 scripts/lib/validate-plugin-manifest.js拒絕 Claude Code 加載器不認(rèn)的 manifest 鍵比如曾導(dǎo)致子代理全部失效的agents數(shù)組。計(jì)數(shù)校驗(yàn)generateCounts掃描 README、AGENTS.md、plugin.json 中的“N commands / N detection rules”表述與源數(shù)據(jù)不符即報(bào)錯(cuò)讓頁面數(shù)字永不過期。文案反 AI 腔校驗(yàn)validateProse/validateSkillProse按 docs/STYLE.md 的禁詞表攔截 em dash、seamless、delve等營銷腔短語每條規(guī)則都附帶打印失敗理由。占位符句法校驗(yàn)validateAskInstructionSites{{ask_instruction}}替換后是完整句子必須處于句首防止把拼錯(cuò)的指引同時(shí)發(fā)給所有 provider。frontmatter 校驗(yàn)description 不得超過 1024 字符。這種“生成即驗(yàn)證”的設(shè)計(jì)讓./plugin這類提交進(jìn)倉庫的生成產(chǎn)物永遠(yuǎn)與源碼同步。產(chǎn)物總覽dist 里到底有什么一次完整構(gòu)建后dist/gitignore不入庫的結(jié)構(gòu)大致如下dist/ universal/ # 17 個(gè) provider dotfile 目錄 README.txt universal.zip # 通用安裝包 openai-plugin.zip # OpenAI 插件上傳包 provider/.dir/... # 各 provider 單獨(dú)輸出而提交進(jìn)倉庫的持久產(chǎn)物是./plugin子樹plugin/ .claude-plugin/plugin.json # 市場(chǎng)安裝入口 .grok-plugin/plugin.json # Grok 原生清單 skills/impeccable/ # 技能本體 agents/ # 四個(gè)子代理 hooks/hooks.json # PostToolUse Stop 鉤子小結(jié)這套打包流程值得借鑒的三個(gè)設(shè)計(jì)配置驅(qū)動(dòng)而非代碼復(fù)制provider 差異全部收斂為 providers.js 中的數(shù)據(jù)新工具接入成本近乎為零。單一事實(shí)來源所有產(chǎn)物從skill/SKILL.src.md派生加上版本與計(jì)數(shù)雙重校驗(yàn)杜絕多份拷貝各自漂移。大聲失敗0 字節(jié) ZIP、缺失 provider 目錄、版本不一致都會(huì)讓構(gòu)建直接終止壞產(chǎn)物永遠(yuǎn)到不了用戶手里。如果想深入各 harness 的能力矩陣frontmatter 字段、占位符體系、目錄結(jié)構(gòu)差異可閱讀 docs/HARNESSES.md完整的開發(fā)者指南見 docs/DEVELOP.md?！久赓M(fèi)下載鏈接】impeccableThe design language that makes your AI harness better at design.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/im/impeccable創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考