164 lines
5.4 KiB
Markdown
164 lines
5.4 KiB
Markdown
# AGENTS.md
|
||
|
||
## 專案概念
|
||
|
||
HTML Transform 是 prototype-driven orchestration framework。目標是把 HTML prototype 轉成可 review、可驗證、可追溯的 Vuetify frontend output。
|
||
|
||
這個 repo 目前是 MVP，不是完整產品。核心價值先放在 CLI pipeline 與 artifact-first workflow：
|
||
|
||
```text
|
||
scan -> plan -> run -> diff -> verify
|
||
```
|
||
|
||
所有中間產物都寫到 `.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/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`
|
||
- 基本 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
|
||
|
||
目前 screenshot 是 placeholder PNG，`diff` score 是 deterministic placeholder。
|
||
|
||
## 套件管理
|
||
|
||
使用 pnpm，不使用 npm 或 yarn。
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm test
|
||
pnpm typecheck
|
||
```
|
||
|
||
不要新增 `package-lock.json` 或 `yarn.lock`。lockfile 應該是 `pnpm-lock.yaml`。
|
||
|
||
## Playwright CLI 決策
|
||
|
||
這個專案使用 `@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`
|
||
|
||
`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` 再操作。
|
||
|
||
安裝瀏覽器：
|
||
|
||
```bash
|
||
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。
|
||
|
||
## 開發原則
|
||
|
||
- 遵守 PRD 的 artifact-first 思路。
|
||
- 不要把 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。
|
||
|
||
## 驗證
|
||
|
||
完成任何改動後至少執行：
|
||
|
||
```bash
|
||
pnpm test
|
||
pnpm typecheck
|
||
```
|
||
|
||
若改到環境偵測、Playwright CLI、設定載入，也執行：
|
||
|
||
```bash
|
||
node src/cli.js doctor
|
||
```
|
||
|
||
若改到 stage pipeline，應確認 E2E 測試仍通過，或新增/更新 `test/cli-e2e.test.js`。
|
||
|
||
## 重要檔案
|
||
|
||
- `PRD.md`：產品需求來源。
|
||
- `README.md`：使用方式與 MVP 限制。
|
||
- `src/cli.js`：CLI command router。
|
||
- `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 測試。
|
||
|
||
## 下一個最重要的方向
|
||
|
||
下一步最值得做的是把 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。
|