我們如何使用 impeccable 優化前端介面設計與實現穩定性

2026年7月4日

我們如何使用 impeccable 優化前端介面設計與實現穩定性

引言

很多團隊做 UI 時都有同一個痛點：設計語言靠經驗，互動細節靠記憶，最後產物容易「能用但不穩」。

在 HagiCode monorepo 裡，impeccable 不是當成「靈感工具」來用，而是被放進一套可執行、可校驗、可回歸的工程鏈路中：

• 任務入口有結構化約束（命令、場景、倉庫範圍）
• 站點內容和上游命令定義自動對齊
• 本地開發埠、執行參數、校驗流程固定化

這篇文章基於倉庫現有實現，拆成四塊：Background、Analysis、Solution、Practice。

背景（Background）

目前倉庫快照中，和 impeccable 直接相關的主線主要在三個位置：

1. 靜態站點運行編排：scripts/static-sites-dev.mjs
2. impeccable 文件站點：repos/impeccable-site
3. UI task preset 契約範例：designs/task-preset-plugin-examples/ui-master

其中第三塊是設計範例，不是線上後端運行時程式碼本體。這點要先講清楚，避免把「設計契約」誤認為「已發布行為」。

分析（Analysis）

1) 設計意圖先結構化，減少「自由發揮」的抖動

ui-master 的後端契約範例裡，先把依賴和輸入釘死，再進入執行。

designs/task-preset-plugin-examples/ui-master/backend/task-preset.json：

{
  "taskKey": "uiMaster",
  "scriptKey": "autotask.ui-master",
  "requirements": [
    {
      "type": "skills",
      "name": "impeccable"
    },
    {
      "type": "cli",
      "name": "impeccable",
      "command": "npm",
      "args": ["exec", "--offline", "--", "impeccable", "--help"]
    }
  ],
  "inputBindings": [
    {
      "input": "uiMasterDescription",
      "promptParameter": "uiMasterDescription",
      "required": true
    },
    {
      "input": "uiMasterCommandIds",
      "promptParameter": "uiMasterCommandIds",
      "required": true
    },
    {
      "input": "sceneKey",
      "promptParameter": "sceneKey"
    }
  ]
}

關鍵點：

• 先驗證 skills:impeccable 和 cli:impeccable，避免運行中才發現鏈路斷掉。
• uiMasterCommandIds 強制命令化輸入，避免「描述很長但方向不明」。
• sceneKey 統一場景鍵，避免每個 preset 發明一套輸入名稱。

這套結構對穩定性的價值很直接：前置失敗、失敗可解釋、輸入可重放。

2) 命令目錄和文件路由統一，減少語義漂移

designs/task-preset-plugin-examples/ui-master/frontend/commands.json 定義了命令分組、文件路由模板、命令 prelude：

{
  "docs": {
    "baseUrl": "https://impeccable.hagicode.com",
    "routeTemplate": "/{lang}/docs/{commandId}",
    "languageResolver": "supported-language"
  },
  "commands": [
    {
      "id": "craft",
      "groupId": "build",
      "skill": "impeccable",
      "docsSlug": "craft",
      "preludeTemplate": "/impeccable {commandId} {uiMasterDescription}"
    }
  ]
}

這讓「執行命令、文件說明、語言路由」共用同一組 ID，減少常見錯位：

• 文件裡叫 A，面板裡叫 B
• 中文頁連結到英文錯命令
• prompt prelude 和 docs slug 不一致

3) 站點實現把「內容正確性」做成可校驗資產

repos/impeccable-site/package.json 裡，validate 串起整條品質門：

{
  "scripts": {
    "validate": "npm run i18n:check && npm run catalog:check && npm run typecheck && npm run test && npm run build"
  }
}

並且 catalog:check 背後的腳本（scripts/build-command-catalog.mjs）對 frontmatter 結構有硬校驗：

function parseFrontmatter(sourceText, sourcePath) {
  const match = sourceText.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/u);
  assert(match, `${sourcePath} must include YAML frontmatter`);
  const frontmatter = load(match[1]);
  assert(isPlainObject(frontmatter), `${sourcePath} frontmatter must be a mapping`);
  return {
    frontmatter,
    body: match[2].trim(),
  };
}

這類 assert 很樸素，但對穩定性特別關鍵：比起上線後才發現文件缺欄位，最好在本地和 CI 直接 fail。

4) 開發環境固定埠和 env，避免「我這能跑你那不行」

monorepo 根腳本 scripts/static-sites-dev.mjs 裡，impeccable 被明確編排：

{
  id: 'impeccable',
  name: 'Impeccable',
  repoPath: 'repos/impeccable-site',
  productionUrl: 'https://impeccable.hagicode.com/',
  command: 'npm',
  args: ['run', 'dev'],
  env: {
    PORT_IMPECCABLE_SITE: '36296'
  },
  portHint: 36296,
  order: 56
}

測試 scripts/static-sites-dev.test.mjs 也對這些值做斷言（埠、args、env、productionUrl）。

這類「寫死 + 測試」的方式不花俏，但穩定：

• 本地入口統一
• 排障路徑固定
• 文件站點連結不亂漂

解決（Solution）

如果你要用 impeccable 同時優化介面品質和實現穩定性，在現有倉庫實踐裡可以落成四層。

第一層：任務入口契約化

做法：複用 ui-master 這類 preset 結構。

目標：

• 限定允許的倉庫範圍（targetRepositories）
• 限定命令來源（uiMasterCommandIds）
• 限定上下文入口（uiMasterDescription）

收益：每次派單都能覆盤「輸入是什麼、為什麼這樣改」。

第二層：命令語義統一化

做法：命令 ID、docs slug、prelude template 三件套綁定。

目標：

• 面板選中的命令能跳轉到同 ID 文件
• prompt 裡的 /impeccable <command> 和文件解釋一致

收益：減少「術語一致、行為不一致」的隱性風險。

第三層：內容資產校驗化

做法：堅持 npm run validate 作為提交前門禁。

目標：

• i18n key 不缺失
• 命令目錄和上游結構不漂移
• 類型、測試、構建一次通過

收益：把「偶發內容問題」提前到本地。

第四層：開發運行環境標準化

做法：透過 static-sites-dev 統一拉起，固定 PORT_IMPECCABLE_SITE。

目標：

• 多人協作埠衝突最小化
• 多站點聯調路徑固定

收益：節省調環境時間，問題更快定位到程式碼本體。

實踐（Practice）

Step 1：初始化 impeccable-site

cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --init --recursive
env -u NPM_CONFIG_PREFIX npm install

Step 2：本地開發和總校驗

env -u NPM_CONFIG_PREFIX npm run dev
env -u NPM_CONFIG_PREFIX npm run validate

validate 一次性覆蓋 i18n、catalog、typecheck、test、build。

Step 3：在 monorepo 統一編排裡運行

從 monorepo 根目錄走 scripts/static-sites-dev.mjs 體系，複用已定義的 PORT_IMPECCABLE_SITE=36296。

這一步重點不是「能跑起來」，而是「所有人都按同一方式跑起來」。

Step 4：把 UI 請求轉成命令化輸入

在 task preset 流程裡優先讓需求落成：

• uiMasterDescription：業務目標
• uiMasterCommandIds：本次命令（如 craft、audit、polish）
• sceneKey：場景上下文

再進入改動階段，減少「直接改 UI 導致方向偏移」。

Step 5：明確目前材料缺口

基於目前倉庫快照，能確認的是：

• impeccable-site 的站點與校驗鏈路是落地程式碼。
• ui-master 與 impeccable 的深度聯動契約主要呈現在 designs/task-preset-plugin-examples 與設計文件中。

如果你要寫「已在生產後端全量啟用」的結論，目前證據不足，先別下這個判斷。

HagiCode 資訊展示

HagiCode 是一個把多倉庫工程、AI 任務執行、文件站點和工具鏈整合在一起的平台化專案。它的核心能力不是單點「會生成程式碼」，而是把任務輸入約束、執行上下文、校驗門禁、跨倉庫協同串成一條穩定流水線。典型使用場景包括：結構化 UI 迭代、跨倉庫功能聯調、規範驅動的技術內容生產，以及帶品質門的自動化交付。

總結

impeccable 真正的價值不在「幫你想一個更好看的按鈕」，而在「把介面優化這件事工程化」。在 HagiCode 現有實踐裡，這件事靠四個動作完成：任務契約化、命令語義統一、內容校驗前置、運行環境標準化。先把這些基礎打穩，再談更炫的設計增強，收益更大，也更可持續。

Tags:

• impeccable
• frontend
• stability
• hagicode

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