feat: renew mvp
This commit is contained in:
skytek_xinliang
@@ -1,290 +1,173 @@
|
||||
## A prototype-driven orchestration framework for CLI coding agents in TypeScript monorepos
|
||||
## HTML Transform
|
||||
|
||||
- **prototype-driven**：不是純 spec，也不是純 code-first。
|
||||
- **orchestration framework**：主體是 workflow 與 gates，不是模型本身。
|
||||
- **CLI coding agents**：Claude Code、Codex、Gemini 只是 adapter targets，不是核心。
|
||||
HTML Transform 是 prototype evidence 工具。現行 MVP 只做兩件事：
|
||||
|
||||
## MVP
|
||||
- `doctor`：檢查執行 `scan` 需要的前置條件。
|
||||
- `scan`：讀取 HTML prototype，產生瀏覽器證據與頁面級 UI Contract。
|
||||
- `app-map.json`：推論每個 prototype 的頁面角色與 layout 使用策略。
|
||||
|
||||
這個版本提供一個可執行的 `ht` CLI 骨架，依照 PRD 的 stage 產出可 review 的中間 artifact：
|
||||
不提供 `plan`、`run`、`diff`、`verify`、`go`、`status`。這些舊骨架已移除，避免把尚未完成的自動化流程誤認成可用功能。
|
||||
|
||||
- `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`：串起完整流程
|
||||
## MVP 範圍
|
||||
|
||||
外部 vision/agent/Playwright 尚未假裝成已整合；目前以 deterministic HTML evidence 建立 MVP artifact，缺少的執行環境會在 report 或 `ht doctor` 中明確標示。
|
||||
`scan` 會執行：
|
||||
|
||||
## 使用方式
|
||||
```text
|
||||
Stage 1 Capture
|
||||
Stage 3-lite Page Contract
|
||||
Stage 4-lite Contract Validation
|
||||
```
|
||||
|
||||
### 1. 確認 Node 版本
|
||||
Stage 2 decomposition 不執行。現有 prototype 主要是後台系統頁面，重點是表單、查詢條件、表格、actions 與資訊架構；切 region screenshot 對 MVP 價值不高。
|
||||
|
||||
目前沒有 Codex slash command。也就是說，在 repo 根目錄輸入 `/scan` 不會自動執行本工具。
|
||||
|
||||
## 指令
|
||||
|
||||
在 `packages/html-transform` 目錄內：
|
||||
|
||||
```bash
|
||||
node src/cli.js doctor
|
||||
node src/cli.js scan
|
||||
```
|
||||
|
||||
在 repo 根目錄：
|
||||
|
||||
```bash
|
||||
node packages/html-transform/src/cli.js doctor
|
||||
node packages/html-transform/src/cli.js scan
|
||||
```
|
||||
|
||||
若要在根目錄用簡短指令，建議由根目錄 `package.json` 包一層：
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"scan": "node packages/html-transform/src/cli.js doctor && node packages/html-transform/src/cli.js scan"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
之後即可執行：
|
||||
|
||||
```bash
|
||||
pnpm scan
|
||||
```
|
||||
|
||||
## 前置需求
|
||||
|
||||
需要 Node.js 20 以上。
|
||||
|
||||
```bash
|
||||
node --version
|
||||
pnpm --version
|
||||
```
|
||||
|
||||
### 2. 安裝專案相依套件
|
||||
|
||||
建議使用專案級安裝，不依賴全域 `playwright-cli`：
|
||||
安裝相依套件：
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
本專案使用 `@playwright/cli`，指令名稱是 `playwright-cli`。安裝後可以用：
|
||||
確認 `playwright-cli` 可用：
|
||||
|
||||
```bash
|
||||
npx --no-install playwright-cli --version
|
||||
pnpm --filter html-transform exec playwright-cli --version
|
||||
```
|
||||
|
||||
或透過 npm script：
|
||||
若環境還沒有 Chromium：
|
||||
|
||||
```bash
|
||||
pnpm playwright-cli -- --version
|
||||
pnpm --filter html-transform exec playwright-cli install-browser chromium
|
||||
```
|
||||
|
||||
若環境還沒有瀏覽器 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/ # 產生結果
|
||||
packages/prototype/
|
||||
```
|
||||
|
||||
最小可跑範例：
|
||||
|
||||
```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` 時會使用預設值。若要覆寫路徑或關閉互動確認，可以建立：
|
||||
本 repo 根目錄目前使用：
|
||||
|
||||
```js
|
||||
// ht.config.js
|
||||
export default {
|
||||
prototype: './packages/prototype',
|
||||
frontend: './packages/web',
|
||||
backend: './packages/api',
|
||||
output: './packages/result',
|
||||
agent: 'codex',
|
||||
prototype: './prototype',
|
||||
frontend: './apps/frontend/hwu-re',
|
||||
backend: './apps/backend',
|
||||
output: './output',
|
||||
plan: {
|
||||
interactiveReview: false,
|
||||
requireApiContractMatch: true
|
||||
},
|
||||
project: {
|
||||
qualityCommands: {
|
||||
typecheck: 'pnpm typecheck',
|
||||
lint: 'pnpm lint',
|
||||
test: 'pnpm test'
|
||||
}
|
||||
interactiveReview: false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
也可以使用 `ht.config.ts`：
|
||||
目前 MVP 只使用 `prototype`。其他欄位可以留著給外部工作流參考，但 `packages/html-transform` 不會執行 frontend/backend/output 相關步驟。
|
||||
|
||||
```ts
|
||||
import { defineConfig } from 'html-transform'
|
||||
|
||||
export default defineConfig({
|
||||
prototype: './packages/prototype',
|
||||
frontend: './packages/web',
|
||||
backend: './packages/api',
|
||||
output: './packages/result'
|
||||
})
|
||||
```
|
||||
|
||||
### 5. 檢查環境
|
||||
## Doctor
|
||||
|
||||
```bash
|
||||
node src/cli.js doctor
|
||||
node packages/html-transform/src/cli.js doctor
|
||||
```
|
||||
|
||||
`doctor` 會檢查 prototype/frontend/backend/output parent、playwright-cli、agent CLI、pnpm 是否存在。缺少項目會標示為 `missing`。
|
||||
檢查項目：
|
||||
|
||||
`playwright-cli` 的偵測順序：
|
||||
- `prototype` directory
|
||||
- package-local `vite`
|
||||
- `playwright-cli`
|
||||
- `pnpm`
|
||||
|
||||
1. `node_modules/.bin/playwright-cli`
|
||||
2. 全域 `playwright-cli`
|
||||
3. `npx --no-install playwright-cli`
|
||||
|
||||
### 6. 執行 scan
|
||||
## Scan
|
||||
|
||||
```bash
|
||||
node src/cli.js scan
|
||||
node packages/html-transform/src/cli.js scan
|
||||
```
|
||||
|
||||
產出：
|
||||
`scan` 會自動：
|
||||
|
||||
- 用 Vite static server 提供 prototype。
|
||||
- 用 `playwright-cli` 開啟每個 HTML。
|
||||
- 等待 `networkidle`，再等待 500ms。
|
||||
- 截取 desktop `1440 x 900` full-page screenshot。
|
||||
- 產生 DOM summary。
|
||||
- 產生 accessibility snapshot。
|
||||
- 記錄 resource failure 與 console error/warning。
|
||||
- 建立頁面級 `pageContract`。
|
||||
- 驗證 contract 與 DOM evidence 是否明顯衝突。
|
||||
- 產出 `.ht/app-map.json`，供通用 prompt 判斷 auth、legacy shell、feature page 與 layout 策略。
|
||||
|
||||
## 產物
|
||||
|
||||
每個 HTML 的 capture artifact：
|
||||
|
||||
```text
|
||||
.ht/cache/prototype/
|
||||
.ht/spec/*.spec.json
|
||||
.ht/spec/*.validation.json
|
||||
.ht/spec/*.ui-contract.md
|
||||
.ht/cache/prototype/{page}/desktop-default.png
|
||||
.ht/cache/prototype/{page}/dom-summary.json
|
||||
.ht/cache/prototype/{page}/accessibility-tree.json
|
||||
.ht/cache/prototype/{page}/capture-metadata.json
|
||||
```
|
||||
|
||||
這一步會從 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
|
||||
```
|
||||
|
||||
產出：
|
||||
每個 HTML 的 contract artifact：
|
||||
|
||||
```text
|
||||
.ht/plan/tasklist.json
|
||||
.ht/plan/project-conventions.md
|
||||
.ht/plan/api-contract.md
|
||||
.ht/plan/component-mapping.json
|
||||
.ht/app-map.json
|
||||
.ht/spec/{page}.spec.json
|
||||
.ht/spec/{page}.validation.json
|
||||
.ht/spec/{page}.ui-contract.md
|
||||
```
|
||||
|
||||
若 `plan.interactiveReview` 設為 `true`，CLI 會在產生 TaskList 後要求輸入 `y` 才繼續。
|
||||
`.spec.json` 會包含 `pageContract`。`regions` 欄位目前仍保留，目的是相容既有資料形狀；不要把它視為 Stage 2 decomposition。
|
||||
|
||||
### 8. 產生 output
|
||||
`.ht/app-map.json` 是跨頁面的應用結構推論。通用 prompt 應先讀它，再決定每個 prototype 是 `auth`、`legacy-shell-reference`、`feature-page` 或其他角色。MVP 固定策略是 template layout/style 優先，prototype 只提供內容與功能證據。
|
||||
|
||||
## 驗證
|
||||
|
||||
修改本 package 後至少執行：
|
||||
|
||||
```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
|
||||
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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user