feat: renew mvp
This commit is contained in:
skytek_xinliang
@@ -2,49 +2,48 @@
|
||||
|
||||
## 專案概念
|
||||
|
||||
HTML Transform 是 prototype-driven orchestration framework。目標是把 HTML prototype 轉成可 review、可驗證、可追溯的 Vuetify frontend output。
|
||||
HTML Transform 是 prototype evidence 工具。目標是把 HTML prototype 轉成可 review、可驗證、可追溯的前端實作依據。
|
||||
|
||||
這個 repo 目前是 MVP，不是完整產品。核心價值先放在 CLI pipeline 與 artifact-first workflow：
|
||||
目前只保留新 MVP 有價值的功能：
|
||||
|
||||
```text
|
||||
scan -> plan -> run -> diff -> verify
|
||||
doctor -> scan
|
||||
```
|
||||
|
||||
所有中間產物都寫到 `.ht/`，生成結果寫到 `output` 設定指向的資料夾，預設是 `packages/result`。
|
||||
|
||||
## 目前 MVP 狀態
|
||||
|
||||
已完成：
|
||||
|
||||
- `ht` CLI 骨架：`scan`、`plan`、`run`、`diff`、`verify`、`go`、`status`、`doctor`
|
||||
- `ht.config.js/json/ts` 設定載入
|
||||
- deterministic HTML evidence extraction
|
||||
- `ht doctor`
|
||||
- `ht scan`
|
||||
- `ht.config.js/json/ts/mjs` 設定載入
|
||||
- Vite static server
|
||||
- Playwright full-page screenshot
|
||||
- DOM summary artifact
|
||||
- accessibility tree artifact
|
||||
- browser resource failure metadata
|
||||
- `.ht/cache/prototype`
|
||||
- `.ht/spec/*.spec.json`
|
||||
- `.ht/spec/*.validation.json`
|
||||
- `.ht/spec/*.ui-contract.md`
|
||||
- `.ht/plan/tasklist.json`
|
||||
- `.ht/plan/project-conventions.md`
|
||||
- `.ht/plan/api-contract.md`
|
||||
- `.ht/plan/component-mapping.json`
|
||||
- `.ht/runs/<runId>/`
|
||||
- `.ht/diff/*.diff.html`
|
||||
- `.ht/verify/verification-report.json`
|
||||
- 頁面級 `pageContract`
|
||||
- 基本 E2E 測試
|
||||
|
||||
尚未完成，不能假裝已完成：
|
||||
刻意不保留：
|
||||
|
||||
- Playwright static server
|
||||
- 真實 full-page screenshot
|
||||
- 真實 DOM snapshot API
|
||||
- 真實 accessibility tree API
|
||||
- vision-based decomposition/extraction
|
||||
- Zod schema validation
|
||||
- 真實 coding agent invocation
|
||||
- 真實 visual similarity scoring
|
||||
- 完整 DOM-level 與 flow-level smoke tests
|
||||
- `ht plan`
|
||||
- `ht run`
|
||||
- `ht diff`
|
||||
- `ht verify`
|
||||
- `ht go`
|
||||
- `ht status`
|
||||
- Stage 2 decomposition
|
||||
- TaskList
|
||||
- output renderer
|
||||
- visual similarity scoring
|
||||
- coding agent invocation
|
||||
|
||||
目前 screenshot 是 placeholder PNG，`diff` score 是 deterministic placeholder。
|
||||
不要重新加入未完成的 pipeline 骨架。只有在使用者明確要求某個能力，且需求足夠具體時才新增。
|
||||
|
||||
## 套件管理
|
||||
|
||||
@@ -62,21 +61,14 @@ pnpm typecheck
|
||||
|
||||
這個專案使用 `@playwright/cli`，透過 shell command 操作 `playwright-cli`，不使用 MCP。
|
||||
|
||||
原因：
|
||||
|
||||
- PRD 的 pipeline 是 coding-agent orchestration，CLI 比 MCP 更適合放進可重跑 stage。
|
||||
- CLI invocation 較容易寫入 `.ht/runs`、logs、metadata 與 verification report。
|
||||
- 專案應避免依賴使用者全域環境。
|
||||
|
||||
解析順序在 `src/lib/playwright-cli.js`：
|
||||
|
||||
1. `node_modules/.bin/playwright-cli`
|
||||
2. 全域 `playwright-cli`
|
||||
3. `npx --no-install playwright-cli`
|
||||
2. package-local `node_modules/.bin/playwright-cli`
|
||||
3. 全域 `playwright-cli`
|
||||
4. `npx --no-install playwright-cli`
|
||||
|
||||
`doctor` 必須能顯示 `playwright-cli (local)`、`playwright-cli (global)` 或 missing。
|
||||
|
||||
專案級 Codex runtime skill 放在 `.codex/skills/playwright-cli`，本機全域也可能有一份在 `~/.codex/skills/playwright-cli`。處理 browser automation、snapshot、screenshot、trace、video、test generation 或 local web app testing 時，Codex 應優先使用專案級 skill；若沒有自動觸發，先讀取 `.codex/skills/playwright-cli/SKILL.md` 再操作。
|
||||
`doctor` 必須能顯示 `playwright-cli (local)`、`playwright-cli (package-local)`、`playwright-cli (global)`、`playwright-cli (npx-local)` 或 missing。
|
||||
|
||||
安裝瀏覽器：
|
||||
|
||||
@@ -84,60 +76,38 @@ pnpm typecheck
|
||||
pnpm playwright-cli:install-browser
|
||||
```
|
||||
|
||||
Linux CI 或乾淨容器若需要系統 dependency，先 dry-run：
|
||||
|
||||
```bash
|
||||
npx --no-install playwright-cli install-browser --with-deps --dry-run
|
||||
```
|
||||
|
||||
## 預設資料夾
|
||||
|
||||
預設 config：
|
||||
|
||||
```text
|
||||
packages/prototype # HTML prototype
|
||||
packages/web # 既有 Vuetify frontend
|
||||
packages/api # backend API/schema
|
||||
packages/result # output
|
||||
.ht # tool artifacts
|
||||
```
|
||||
|
||||
目前 repo 可能沒有預設輸入資料夾。這時 `doctor` 回報 missing 是正確行為，不是 bug。
|
||||
本 repo 根目錄可用 `ht.config.mjs` 把 prototype 指到 `./prototype`。
|
||||
|
||||
## 開發原則
|
||||
|
||||
- 遵守 PRD 的 artifact-first 思路。
|
||||
- 保持 MVP 邊界，只保留 `doctor` 與 `scan` 的實際價值。
|
||||
- 不要把 placeholder 包裝成完整實作。
|
||||
- 每個 stage 的失敗、缺少環境、skipped 都要明確寫入 report 或 CLI output。
|
||||
- 優先做可重跑、可檢查、可追溯的 deterministic behavior。
|
||||
- 不要讓 agent 修改 `prototype/`、`frontend/`、`backend/` 原始輸入資料夾；生成與執行 artifact 應限制在 `output/` 與 `.ht/`。
|
||||
- 保持 MVP 邊界，避免加泛用抽象或一開始支援所有 monorepo 形態。
|
||||
|
||||
## JSDoc 原則
|
||||
|
||||
- 依專案的 `jsdoc` skill 撰寫 JSDoc；這裡只補充 HTML Transform 專案特有規則。
|
||||
- JavaScript 的 JSDoc 優先補在 exported API、stage 入口、跨模組 helper，或描述非顯而易見契約與限制的位置；不為測試檔或區域性小函式刻意補註解。
|
||||
- JSDoc 使用繁體中文，並把說明重點放在 artifact、pipeline stage、MVP 限制、cache/placeholder 行為、輸入輸出契約等專案脈絡。
|
||||
- 不新增 `jsdoc` 產生 HTML 文件的設定、script 或 build step，除非使用者明確要求。
|
||||
- 補 JSDoc 不應順手 refactor、改行為、加抽象或擴大 scope。
|
||||
- 不要新增未完成 command。
|
||||
- Stage 2 decomposition 目前不做。
|
||||
- 每個輸出 artifact 都要能重跑與人工 review。
|
||||
- 不修改 `prototype/` 原始輸入資料夾。
|
||||
- 產物只寫入 `.ht/`。
|
||||
|
||||
## 驗證
|
||||
|
||||
完成任何改動後至少執行：
|
||||
|
||||
```bash
|
||||
pnpm test
|
||||
pnpm typecheck
|
||||
pnpm --filter html-transform typecheck
|
||||
pnpm --filter html-transform test
|
||||
node packages/html-transform/src/cli.js doctor
|
||||
node packages/html-transform/src/cli.js scan
|
||||
```
|
||||
|
||||
若改到環境偵測、Playwright CLI、設定載入，也執行：
|
||||
|
||||
```bash
|
||||
node src/cli.js doctor
|
||||
```
|
||||
|
||||
若改到 stage pipeline，應確認 E2E 測試仍通過，或新增/更新 `test/cli-e2e.test.js`。
|
||||
|
||||
## 重要檔案
|
||||
|
||||
- `PRD.md`：產品需求來源。
|
||||
@@ -146,18 +116,10 @@ node src/cli.js doctor
|
||||
- `src/lib/config.js`：config loading。
|
||||
- `src/lib/html.js`：deterministic HTML evidence extraction。
|
||||
- `src/lib/playwright-cli.js`：Playwright CLI resolution。
|
||||
- `src/stages/*.js`：各 stage 實作。
|
||||
- `test/cli-e2e.test.js`：完整 CLI pipeline 測試。
|
||||
- `src/stages/doctor.js`：前置檢查。
|
||||
- `src/stages/scan.js`：capture、page contract、validation。
|
||||
- `test/cli-e2e.test.js`：doctor/scan E2E 測試。
|
||||
|
||||
## 下一個最重要的方向
|
||||
## 下一個方向
|
||||
|
||||
下一步最值得做的是把 Stage 1 做真：
|
||||
|
||||
- local static server
|
||||
- `playwright-cli` 三 viewport screenshot
|
||||
- network/resource failure metadata
|
||||
- DOM snapshot artifact
|
||||
- accessibility snapshot artifact
|
||||
- cache hit 時跳過 screenshot
|
||||
|
||||
這完成後，工具才會真正開始觀察 browser-rendered prototype，而不是只解析 HTML source。
|
||||
下一個有價值的方向是改善 `pageContract` 品質，例如更準確的 form label、table header、action 分類與 evidence warning。不要先做 TaskList 或自動寫 code。
|
||||
|
||||
Reference in New Issue
Block a user