291 lines
6.3 KiB
Markdown
291 lines
6.3 KiB
Markdown
## 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
|
||
```
|