如何集成和使用 impeccable

2026年6月10日

如何集成和使用 impeccable

其實也沒啥，就是在 HagiCode 專案裡集成個設計工具，勉強算個完整方案吧——包括倉庫結構、多語言工作流、內容維護這些，都是在實踐裡慢慢摸索出來的。

背景

說起軟體開發裡的 UI/UX 設計質量，其實還挺重要的，畢竟能直接決定產品的使用者體驗和商業成功。只是傳統開發流程裡，設計師和開發者之間總有一道無形的牆：設計師畫了精美的靜態稿，開發者努力去實現，卻總是在某些細節上有些偏差。這種割裂讓最終產品很難完全匹配設計願景，迭代成本也跟著水漲船高。

HagiCode 專案在做桌面應用和 Web 產品的時候，也需要專業的 UI/UX 設計支援，同時還要求設計和程式碼實現能夠緊密協作。為此，我們引入了 impeccable 工具——一個專業的 AI 驅動的前端介面設計和優化工具。impeccable 不僅提供設計指導，還能直接處理程式碼實現，算是把設計和開發之間的鴻溝給填上了一些。

為了讓 impeccable 在 HagiCode monorepo 中有效集成和使用，我們需要建立標準化的集成方式、文檔流程和維護規範。這包括工具的安裝配置、技能集成、文檔站點建設，以及團隊協作的最佳實踐。

關於 HagiCode

本文分享的方案來自我們在 HagiCode 專案中的實踐經驗。HagiCode 是一個 AI 程式碼助手專案，提供了 Web 端和桌面端兩種形態，幫助開發者提升編碼效率。在開發過程中，我們需要高質量的設計工具來支援產品的 UI/UX 建設，impeccable 正是在這樣的背景下被引入到專案中的。

技術架構分析

impeccable 的技能驅動設計

impeccable 採用了技能驅動的設計架構，通過標準化的技能文件定義不同設計任務的上下文和行為。在 HagiCode 專案中，impeccable 以 npm 技能包形式集成，主要通過以下方式使用：

1. 技能文件結構：/home/newbe36524/.agents/skills/impeccable/SKILL.md 定義了完整的技能配置，包括命令集合、工具權限、參數提示和許可資訊。

2. 命令分類體系：impeccable 將設計任務分為六大類別：

   • Build：構建型命令（craft、shape、teach、document、extract）
   • Evaluate：評估型命令（critique、audit）
   • Refine：優化型命令（polish、bolder、quieter、distill、harden、onboard）
   • Enhance：增強型命令（animate、colorize、typeset、layout、delight、overdrive）
   • Fix：修復型命令（clarify、adapt、optimize）
   • Iterate：迭代型命令（live）

文檔站點需求分析

為了支援團隊使用 impeccable，HagiCode 建立了獨立的文檔站點 impeccable-site，該站點需要滿足以下需求：

• 多語言支援：提供英文和中文的完整文檔，滿足國際化團隊需求
• 命令目錄：歸一化展示所有命令，包括分類、描述和參考連結
• 本地化內容：維護 HagiCode 特定的使用指南和最佳實踐
• 靜態生成：使用 Astro 構建靜態站點，便於部署和訪問

集成面臨的挑戰

在集成過程中面臨以下挑戰：

1. 源碼同步：上游 impeccable 倉庫包含完整的工具程式碼和文檔，但需要選擇性地集成文檔部分，避免依賴整個工具程式碼庫

2. 內容維護：需要在保持上游更新同步的同時，維護本地化的內容和使用指南

3. 構建流程：建立自動化的內容同步、目錄生成和站點構建流程

4. 多語言工作流：設計高效的翻譯和本地化維護流程

解決方案設計

倉庫結構設計

通過 Git submodule 機制集成上游 impeccable 倉庫：

[submodule "vendor/impeccable"]
    path = vendor/impeccable
    url = https://github.com/pbakaus/impeccable.git

這種設計的優勢包括：

• 版本控制：可以精確控制上游版本，避免意外更新導致的問題
• 輕量級集成：只拉取需要的源碼，避免引入不必要的依賴
• 更新靈活：可以選擇性地更新上游內容

內容模型設計

採用分層的內容模型：

1. 上游源碼：vendor/impeccable/ - 提供原始命令定義和參考文檔
2. 本地化內容：src/content/commands/ - 維護中英文命令說明
3. 共享 UI 文案：src/i18n/locales/ - 管理站點介面的多語言文本
4. 生成式目錄：src/lib/generated/command-catalog.json - 構建時生成的命令目錄

構建流程優化

設計自動化的構建流程，通過 npm 腳本集成各個步驟：

{
  "scripts": {
    "prepare": "npm run i18n:generate && npm run catalog:generate",
    "i18n:generate": "node scripts/generate-i18n-resources.mjs",
    "catalog:generate": "node scripts/build-command-catalog.mjs",
    "content:sync:vendor": "node scripts/sync-vendor-command-content.mjs",
    "validate": "npm run i18n:check && npm run catalog:check && npm run typecheck && npm run test && npm run build"
  }
}

構建流程分為四個階段：

1. 準備階段：生成多語言資源和命令目錄
2. 內容同步：從上游同步命令內容到本地
3. 驗證階段：檢查內容完整性和構建正確性
4. 構建輸出：生成靜態站點文件

多語言工作流

基於 hagi18n 工具鏈建立標準化的多語言工作流：

localesRoot: src/i18n/locales
repoRoot: .
baseLocale: en-US
targetLocales:
  - zh-CN

提供完整的維護腳本：

• i18n:audit - 檢查翻譯完整性
• i18n:sync - 同步翻譯條目
• i18n:prune - 清理過期翻譯
• i18n:doctor - 診斷翻譯問題

實踐指南

初始化設置

首先初始化 submodule 並安裝依賴：

# 進入 monorepo 根目錄
cd /home/newbe36524/repos/hagicode-mono

# 初始化 submodule
git submodule update --init --recursive

# 進入 impeccable-site 目錄
cd repos/impeccable-site

# 安裝依賴
env -u NPM_CONFIG_PREFIX npm install

這一步是整個集成流程的基礎，submodule 初始化失敗會導致後續所有步驟無法進行。HagiCode 在首次集成時就遇到了這個問題，後來在文檔中明確了初始化步驟。

日常開發流程

在 repos/impeccable-site 目錄下執行日常開發命令：

# 啟動開發伺服器
env -u NPM_CONFIG_PREFIX npm run dev

# 類型檢查
env -u NPM_CONFIG_PREFIX npm run typecheck

# 運行測試
env -u NPM_CONFIG_PREFIX npm test

# 構建站點
env -u NPM_CONFIG_PREFIX npm run build

# 完整驗證
env -u NPM_CONFIG_PREFIX npm run validate

開發伺服器默認運行在 http://localhost:31266，可以通過環境變量 PORT_IMPECCABLE_SITE 自定義端口。HagiCode 的團隊成員在開發過程中發現，頻繁在不同語言環境切換時，使用統一的前綴命令可以避免環境變量污染問題。

內容維護策略

添加或更新命令文檔時，需要在兩個語言目錄中創建對應的文件：

# 英文命令文檔
src/content/commands/en-US/polish.mdx

# 中文命令文檔
src/content/commands/zh-CN/polish.mdx

每個 MDX 文件需要包含 frontmatter 元資料：

---
title: "Polish"
slug: "polish"
seoTitle: "Polish Command - Impeccable"
seoDescription: "Final quality pass before shipping with impeccable polish command"
routeSlug: "polish"
highlights:
  - "Visual hierarchy review"
  - "Spacing and typography optimization"
  - "Accessibility validation"
related:
  - "audit"
  - "critique"
---

上游內容同步

當上游 impeccable 更新時，需要同步最新的命令內容：

# 更新 submodule
cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --remote vendor/impeccable

# 同步命令內容
env -u NPM_CONFIG_PREFIX npm run content:sync:vendor

# 同步單個命令
env -u NPM_CONFIG_PREFIX node scripts/sync-vendor-command-content.mjs --slug polish

# 重新生成目錄
env -u NPM_CONFIG_PREFIX npm run catalog:generate

同步腳本會從 vendor/impeccable/site/content/skills/ 讀取上游命令內容，並將其複製到 src/content/commands/en-US/ 目錄中。HagiCode 團隊在實踐中發現，每次同步後都需要重新生成命令目錄，否則會出現內容不一致的問題。

多語言維護

維護站點介面的多語言文本：

# 檢查翻譯完整性
env -u NPM_CONFIG_PREFIX npm run i18n:audit

# 同步翻譯條目
env -u NPM_CONFIG_PREFIX npm run i18n:sync

# 清理過期翻譯
env -u NPM_CONFIG_PREFIX npm run i18n:prune

# 診斷翻譯問題
env -u NPM_CONFIG_PREFIX npm run i18n:doctor

翻譯文件位於 src/i18n/locales/ 目錄：

src/i18n/locales/
├── en-US/
│   ├── common.yml
│   └── docs.yml
└── zh-CN/
    ├── common.yml
    └── docs.yml

YAML 文件範例：

src/i18n/locales/en-US/docs.yml

commands:
  title: "Commands"
  subtitle: "Explore the complete command surface"
  overview: "Overview"
  related: "Related Commands"

# src/i18n/locales/zh-CN/docs.yml
commands:
  title: "命令"
  subtitle: "探索完整的命令集"
  overview: "概覽"
  related: "相關命令"

使用 impeccable 命令

在 HagiCode 專案中，可以通過以下方式調用 impeccable 命令：

# 設計新功能
npx impeccable craft "user settings page"

# 規劃 UI/UX
npx impeccable shape "checkout flow"

# 設置專案上下文
npx impeccable teach

# 生成設計文檔
npx impeccable document

# 審查設計質量
npx impeccable critique "landing page"

# 技術質量檢查
npx impeccable audit "navigation component"

# 最終優化
npx impeccable polish "onboarding flow"

# 實時迭代設計
npx impeccable live

每個命令都有特定的用途和參考文檔。例如，craft 命令用於端到端構建功能，包括 UX/UI 規劃和程式碼實現；audit 命令用於技術質量檢查，包括可訪問性、性能和響應式設計。HagiCode 團隊在開發過程中，這些命令已經成為日常開發流程的一部分。

部署驗證

部署前進行完整的驗證：

# 運行完整驗證流程
env -u NPM_CONFIG_PREFIX npm run validate

驗證流程會檢查：

• vendor 路徑是否正確
• 所有命令在中英文目錄中都有對應內容
• 生成的多語言資源是最新的
• 命令目錄是最新的
• Astro 路由編譯正確
• 靜態輸出構建成功

注意事項與最佳實踐

重要注意事項

1. Submodule 更新：更新 submodule 後需要重新生成派生資源並提交。HagiCode 團隊曾經遇到過一次忘記重新生成資源就直接提交的情況，導致線上站點出現了內容不一致的問題。

2. 語言對等性：確保所有命令在中英文目錄中都有對應內容，否則構建會失敗。這個檢查已經集成到了驗證流程中，可以在開發早期發現問題。

3. 前端代理：impeccable-site 通過 monorepo 根目錄的靜態站點開發腳本進行代理：

# 從 monorepo 根目錄啟動
npm run dev:static-sites

4. 生產部署：生產站點部署到 https://impeccable.hagicode.com，通過 GitHub Actions 自動化部署。HagiCode 採用了完全自動化的 CI/CD 流程，確保每次提交都能自動部署。

5. 命令文檔連結：在 Web 前端的 UI Master 中選擇 impeccable 命令時，會顯示對應的文檔連結，連結格式為：

https://impeccable.hagicode.com/{lang}/commands/{command-name}

最佳實踐總結

1. 定期同步上游：關注上游 impeccable 的更新，定期同步新的命令和改進。HagiCode 團隊採用每週一次的同步頻率，確保不會錯過重要的更新。

2. 維護本地化內容：在同步上游內容後，及時更新中英文文檔，確保內容的準確性和時效性。

3. 版本控制：submodule 更新後需要驗證構建結果，再提交到版本控制系統。

4. 團隊協作：通過標準化的多語言工作流，支援團隊成員協作維護文檔內容。

5. 質量保證：在每次內容更新後運行完整的驗證流程，確保站點的正確性。

6. 命令分類使用：根據設計任務的不同階段選擇合適的命令類別：

   • 設計新功能時使用 craft 或 shape
   • 審查現有設計時使用 critique 或 audit
   • 優化設計質量時使用 polish、bolder 或 quieter
   • 增強視覺效果時使用 animate、colorize 或 delight
   • 修復問題時使用 clarify、adapt 或 optimize
   • 實時迭代時使用 live

7. 上下文管理：在使用 craft 命令前，確保已通過 teach 命令設置了專案的 PRODUCT.md 和 DESIGN.md 上下文文件。

總結

通過以上集成和使用方式，HagiCode 專案能夠有效利用 impeccable 工具的專業設計能力，提升產品的 UI/UX 質量，同時建立了標準化的文檔維護流程，支援團隊的長期協作和發展。

本文分享的這套方案，是 HagiCode 在實際開發中經過多次迭代優化出來的。它不僅解決了設計和開發協作的問題，還建立了一套可擴展的文檔體系，為其他工具的集成提供了參考。

如果你也在團隊中面臨類似的設計-開發協作問題，希望本文的實踐對你有所啟發。這套方案的核心思想是：建立標準化的流程、保持與上游的同步、注重本地化維護、支援團隊協作。

總結

圍繞”如何集成和使用 impeccable”，更穩妥的推進方式是先把關鍵配置、依賴邊界和落地路徑逐步跑通，再補齊優化細節。

當目標、步驟和驗收點都明確之後，這類方案通常就能更順暢地進入實際交付。

Tags:

• impeccable
• design
• integration
• workflow

MonoSpecs 是什麼：為什麼說它是對 OpenSpec 的進一步升級和擴展

用不同的 Agent 優化 OpenSpec 各階段效能：HagiCode 實踐總結