AGENTS.md

專案概念

HTML Transform 是 prototype evidence 工具。目標是把 HTML prototype 轉成可 review、可驗證、可追溯的前端實作依據。

目前只保留新 MVP 有價值的功能：

doctor -> scan

目前 MVP 狀態

已完成：

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
頁面級 pageContract
基本 E2E 測試

刻意不保留：

ht plan
ht run
ht diff
ht verify
ht go
ht status
Stage 2 decomposition
TaskList
output renderer
visual similarity scoring
coding agent invocation

不要重新加入未完成的 pipeline 骨架。只有在使用者明確要求某個能力，且需求足夠具體時才新增。

套件管理

使用 pnpm，不使用 npm 或 yarn。

pnpm install
pnpm test
pnpm typecheck

不要新增 package-lock.json 或 yarn.lock。lockfile 應該是 pnpm-lock.yaml。

Playwright CLI 決策

這個專案使用 @playwright/cli，透過 shell command 操作 playwright-cli，不使用 MCP。

解析順序在 src/lib/playwright-cli.js：

node_modules/.bin/playwright-cli
package-local node_modules/.bin/playwright-cli
全域 playwright-cli
npx --no-install playwright-cli

doctor 必須能顯示 playwright-cli (local)、playwright-cli (package-local)、playwright-cli (global)、playwright-cli (npx-local) 或 missing。

安裝瀏覽器：

pnpm playwright-cli:install-browser

預設資料夾

預設 config：

packages/prototype   # HTML prototype
.ht                  # tool artifacts

本 repo 根目錄可用 ht.config.mjs 把 prototype 指到 ./prototype。

開發原則

保持 MVP 邊界，只保留 doctor 與 scan 的實際價值。
不要把 placeholder 包裝成完整實作。
不要新增未完成 command。
Stage 2 decomposition 目前不做。
每個輸出 artifact 都要能重跑與人工 review。
不修改 prototype/ 原始輸入資料夾。
產物只寫入 .ht/。

驗證

完成任何改動後至少執行：

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

重要檔案

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/doctor.js：前置檢查。
src/stages/scan.js：capture、page contract、validation。
test/cli-e2e.test.js：doctor/scan E2E 測試。

下一個方向

下一個有價值的方向是改善 pageContract 品質，例如更準確的 form label、table header、action 分類與 evidence warning。不要先做 TaskList 或自動寫 code。

3.1 KiB Raw Blame History Unescape Escape