linx6g/html-transform

Fork 0

Files

T

linx6g 5fe3ba771e feat: adding JSDoc

2026-05-03 10:12:42 +08:00

5.4 KiB

Raw Permalink Blame History

AGENTS.md

專案概念

HTML Transform 是 prototype-driven orchestration framework。目標是把 HTML prototype 轉成可 review、可驗證、可追溯的 Vuetify frontend output。

這個 repo 目前是 MVP，不是完整產品。核心價值先放在 CLI pipeline 與 artifact-first workflow：

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。

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：

node_modules/.bin/playwright-cli
全域 playwright-cli
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 再操作。

安裝瀏覽器：

pnpm playwright-cli:install-browser

Linux CI 或乾淨容器若需要系統 dependency，先 dry-run：

npx --no-install playwright-cli install-browser --with-deps --dry-run

預設資料夾

預設 config：

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。

驗證

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

pnpm test
pnpm typecheck

若改到環境偵測、Playwright CLI、設定載入，也執行：

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。

5.4 KiB Raw Permalink Blame History Unescape Escape