skytek_xinliang
126 lines
3.1 KiB
Markdown
126 lines
3.1 KiB
Markdown
# AGENTS.md
|
||
|
||
## 專案概念
|
||
|
||
HTML Transform 是 prototype evidence 工具。目標是把 HTML prototype 轉成可 review、可驗證、可追溯的前端實作依據。
|
||
|
||
目前只保留新 MVP 有價值的功能：
|
||
|
||
```text
|
||
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。
|
||
|
||
```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。
|
||
|
||
解析順序在 `src/lib/playwright-cli.js`：
|
||
|
||
1. `node_modules/.bin/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 (package-local)`、`playwright-cli (global)`、`playwright-cli (npx-local)` 或 missing。
|
||
|
||
安裝瀏覽器：
|
||
|
||
```bash
|
||
pnpm playwright-cli:install-browser
|
||
```
|
||
|
||
## 預設資料夾
|
||
|
||
預設 config：
|
||
|
||
```text
|
||
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/`。
|
||
|
||
## 驗證
|
||
|
||
完成任何改動後至少執行：
|
||
|
||
```bash
|
||
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。
|