feat: projcet Initialization

2026-05-03 09:38:24 +08:00
commit 81bca6aa80
22 changed files with 1867 additions and 0 deletions
@@ -0,0 +1,290 @@
+## A prototype-driven orchestration framework for CLI coding agents in TypeScript monorepos
+
+- **prototype-driven**：不是純 spec，也不是純 code-first。
+- **orchestration framework**：主體是 workflow 與 gates，不是模型本身。
+- **CLI coding agents**：Claude Code、Codex、Gemini 只是 adapter targets，不是核心。
+
+## MVP
+
+這個版本提供一個可執行的 `ht` CLI 骨架，依照 PRD 的 stage 產出可 review 的中間 artifact：
+
+- `ht scan`：讀取 `prototype/` HTML，產生 `.ht/cache/prototype/`、`.ht/spec/*.spec.json`、`ui-contract.md`
+- `ht plan`：掃描 frontend/backend，產生 `.ht/plan/tasklist.json`、conventions、API contract、component mapping
+- `ht run`：依 TaskList 產生 Vuetify `.vue` 檔到 `output/`
+- `ht diff`：產生 `.ht/diff/*.diff.html`
+- `ht verify`：執行 quality commands 並產生 `.ht/verify/verification-report.json`
+- `ht go --yes`：串起完整流程
+
+外部 vision/agent/Playwright 尚未假裝成已整合；目前以 deterministic HTML evidence 建立 MVP artifact，缺少的執行環境會在 report 或 `ht doctor` 中明確標示。
+
+## 使用方式
+
+### 1. 確認 Node 版本
+
+需要 Node.js 20 以上。
+
+```bash
+node --version
+```
+
+### 2. 安裝專案相依套件
+
+建議使用專案級安裝，不依賴全域 `playwright-cli`：
+
+```bash
+pnpm install
+```
+
+本專案使用 `@playwright/cli`，指令名稱是 `playwright-cli`。安裝後可以用：
+
+```bash
+npx --no-install playwright-cli --version
+```
+
+或透過 npm script：
+
+```bash
+pnpm playwright-cli -- --version
+```
+
+若環境還沒有瀏覽器 binary，先安裝預設瀏覽器：
+
+```bash
+pnpm playwright-cli:install-browser
+```
+
+Linux CI 或乾淨容器可能還需要系統套件，先用 dry-run 看會做什麼：
+
+```bash
+npx --no-install playwright-cli install-browser --with-deps --dry-run
+```
+
+### 3. 準備資料夾
+
+預設設定會讀取以下路徑：
+
+```text
+packages/
+├── prototype/   # 放 HTML prototype
+├── web/         # 既有 Vuetify frontend 專案
+├── api/         # backend API 或 schema
+└── result/      # 產生結果
+```
+
+最小可跑範例：
+
+```bash
+mkdir -p packages/prototype packages/web/src packages/api packages/result
+```
+
+新增一個 prototype：
+
+```html
+<!-- packages/prototype/index.html -->
+<main>
+  <h1>Customer Portal</h1>
+  <form>
+    <label>Email</label>
+    <input name="email" required>
+    <button>Submit</button>
+  </form>
+</main>
+```
+
+### 4. 選擇性建立設定檔
+
+沒有 `ht.config.js` 時會使用預設值。若要覆寫路徑或關閉互動確認，可以建立：
+
+```js
+// ht.config.js
+export default {
+  prototype: './packages/prototype',
+  frontend: './packages/web',
+  backend: './packages/api',
+  output: './packages/result',
+  agent: 'codex',
+  plan: {
+    interactiveReview: false,
+    requireApiContractMatch: true
+  },
+  project: {
+    qualityCommands: {
+      typecheck: 'pnpm typecheck',
+      lint: 'pnpm lint',
+      test: 'pnpm test'
+    }
+  }
+}
+```
+
+也可以使用 `ht.config.ts`：
+
+```ts
+import { defineConfig } from 'html-transform'
+
+export default defineConfig({
+  prototype: './packages/prototype',
+  frontend: './packages/web',
+  backend: './packages/api',
+  output: './packages/result'
+})
+```
+
+### 5. 檢查環境
+
+```bash
+node src/cli.js doctor
+```
+
+`doctor` 會檢查 prototype/frontend/backend/output parent、playwright-cli、agent CLI、pnpm 是否存在。缺少項目會標示為 `missing`。
+
+`playwright-cli` 的偵測順序：
+
+1. `node_modules/.bin/playwright-cli`
+2. 全域 `playwright-cli`
+3. `npx --no-install playwright-cli`
+
+### 6. 執行 scan
+
+```bash
+node src/cli.js scan
+```
+
+產出：
+
+```text
+.ht/cache/prototype/
+.ht/spec/*.spec.json
+.ht/spec/*.validation.json
+.ht/spec/*.ui-contract.md
+```
+
+這一步會從 HTML 擷取 DOM summary、accessibility-like tree、region、LayoutSpec 與 UI contract。MVP 目前使用 deterministic HTML evidence；截圖檔是 placeholder PNG。
+
+後續接真實 browser automation 時，會透過 `playwright-cli` shell 指令操作，不透過 MCP。
+
+### 7. 產生 TaskList
+
+```bash
+node src/cli.js plan
+```
+
+產出：
+
+```text
+.ht/plan/tasklist.json
+.ht/plan/project-conventions.md
+.ht/plan/api-contract.md
+.ht/plan/component-mapping.json
+```
+
+若 `plan.interactiveReview` 設為 `true`，CLI 會在產生 TaskList 後要求輸入 `y` 才繼續。
+
+### 8. 產生 output
+
+```bash
+node src/cli.js run
+```
+
+產出會寫入 `output` 設定的資料夾，例如：
+
+```text
+packages/result/index/main-1.vue
+```
+
+每個 task 的執行記錄會寫入：
+
+```text
+.ht/runs/<runId>/
+```
+
+若只想重跑失敗 task：
+
+```bash
+node src/cli.js run --retry-failed
+```
+
+### 9. 產生 diff report
+
+```bash
+node src/cli.js diff
+```
+
+產出：
+
+```text
+.ht/diff/*.diff.html
+```
+
+MVP 目前會建立可 review 的 HTML report 結構；真實 `playwright-cli` 截圖與 vision similarity scoring 尚未串接。
+
+### 10. 執行驗證
+
+```bash
+node src/cli.js verify
+```
+
+產出：
+
+```text
+.ht/verify/verification-report.json
+```
+
+驗證包含：
+
+- `project.qualityCommands` 中設定的 typecheck/lint/test
+- output target 是否存在
+- flow checks 目前在 MVP 中會標示為 skipped
+
+### 11. 一次跑完整流程
+
+```bash
+node src/cli.js go --yes
+```
+
+等同依序執行：
+
+```bash
+node src/cli.js scan
+node src/cli.js plan
+node src/cli.js run
+node src/cli.js diff
+node src/cli.js verify
+```
+
+### 12. 查看 task 狀態
+
+```bash
+node src/cli.js status
+```
+
+會顯示 `pending`、`running`、`done`、`error` 的 task 數量。
+
+## 開發驗證
+
+```bash
+pnpm test
+pnpm typecheck
+```
+
+## 目前 MVP 限制
+
+- 尚未整合 Playwright static server、真實 full-page screenshot、DOM snapshot API 與 accessibility tree API。
+- Playwright 操作會以 `playwright-cli` shell command 為準，不使用 MCP；目前已加入專案級 `@playwright/cli` 安裝與環境偵測。
+- 尚未真的呼叫 Claude Code/Codex/Gemini 進行 vision decomposition 或 coding task。
+- `diff` 的 similarity score 目前是 deterministic report placeholder，不是 vision scoring。
+- `run` 目前以 LayoutSpec 產生基本 Vuetify Vue component，還不是完整專案級整合。
+- 缺少 quality command 或外部工具時，會在 report 或 `doctor` 中標示為 skipped/missing。
+
+## 常用指令摘要
+
+```bash
+pnpm test
+pnpm typecheck
+node src/cli.js doctor
+node src/cli.js scan
+node src/cli.js plan
+node src/cli.js run
+node src/cli.js diff
+node src/cli.js verify
+```