使用手冊

Agentic HTML Editor / Skill Template Runtime

Local-first Agentic HTML Editor 技術解析。

HTML Anything 繁體中文技術解析：Next.js 16、local coding-agent CLI detection、SKILL.md templates、SSE streaming、sandboxed iframe preview、WeChat/X/Zhihu/PNG export 與安全邊界。

HTML Anything 是一個 local-first 的 agentic HTML editor：瀏覽器提供輸入、模板選擇與 sandbox preview，Next.js API 在本機呼叫你已登入的 coding-agent CLI，透過 SSE 把代理輸出的 HTML 串流回 iframe，最後一鍵輸出 WeChat、X、Zhihu、HTML 或 PNG。

nexu-io/html-anything
星標
5.5K
分支
545
授權
—
資料截至
閱讀時間
7 分
更新日期
開啟原始報告
Template Library
75 skills
Delivery Surfaces
9 modes
Agent Adapters
8+ CLI
License 2.0
Apache
本頁章節

01Repository Signal

以本機 coding-agent CLI 為後端的設計產線架構解析。

HTML Anything 接受 Markdown、CSV、JSON、SQL 或零散筆記作為輸入，輸出經設計的 HTML。它不持有 LLM key，不將生成工作移至雲端。它偵測本機已登入的 Claude Code、Codex、Cursor Agent、Gemini CLI 等工具，由既有訂閱與 session 承擔推理工作。

repo metadata 顯示專案以 HTML/Next 為主，採 Apache-2.0 授權，homepage 是 open-design.ai/html-anything/。README 把它定位為「agentic HTML editor」，強調 75 個 SKILL.md 技能模板、9 種交付 surface、local sandbox preview，以及 WeChat/X/Zhihu/PNG/HTML 匯出。

架構分三層：agent adapter 不知道模板語義，template registry 不知道 CLI 細節，export layer 不知道 prompt 怎麼組裝。這種切分讓「新增 agent」、「新增 skill」、「新增 export target」各自成為獨立 PR。

02Runtime Loop

核心閉環是 detect、prompt、spawn、stream、preview、export。

  1. Input

  2. Skill

  3. Agent CLI

  4. SSE

  5. Iframe

  6. Export

next/src/app/api/agents/route.ts 負責偵測本機可用 CLI；next/src/lib/agents/argv.ts 定義每個 agent 的 argv、stdin/stdout protocol 與 line parser；next/src/app/api/convert/route.ts 載入 skill、組 prompt、呼叫 invokeAgent，再把 agent stdout 轉成 text/event-stream。

前端收到 SSE event 後把 HTML 追加到 iframe srcdoc，使用者可即時看到生成中的頁面。若輸出跑偏，可中斷並重試。若已有上一版 HTML，API 支援 editFromHtml 與 editFromContent，以最小差異修改降低多輪修改的創意漂移。

層檔案作用
Agent detectionnext/src/lib/agents/detect.ts掃描 PATH 與常見本機 bin 目錄，找出可用 coding-agent CLI。
Adapternext/src/lib/agents/argv.ts每個 CLI 一個 thin adapter，處理 argv 與 JSON-line/delta parsing。
Convert APInext/src/app/api/convert/route.ts組 prompt、spawn agent、回傳 SSE stream。
Template loadernext/src/lib/templates/loader.ts載入 SKILL.md frontmatter、example 與設計 metadata。
Previewnext/src/components/preview-pane.tsx把輸出放入 sandboxed iframe，隔離 host page。
Exportnext/src/lib/export/*把同一份 HTML 轉成 WeChat、Zhihu、PNG、deck、Notion、Remotion 等目標。

03Quickstart

workspace 很小, 但 agent 必須留在你的本機。

root package 只保留 workspace metadata 與 scripts/guard.ts；主要 Next app 在 next/，E2E 測試在 e2e/。next/package.json 使用 Next 16.2.6、React 19.2.4、Tailwind v4、zustand、juice、modern-screenshot、xlsx、papaparse、marked、highlight.js 與 dompurify。

bash
git clone https://github.com/nexu-io/html-anything
cd html-anything
pnpm install
pnpm -F @html-anything/next dev

# browser: http://localhost:3000
bash
pnpm exec tsx scripts/guard.ts
pnpm -F @html-anything/next typecheck
pnpm -F @html-anything/next test
pnpm -F @html-anything/next build
pnpm -F @html-anything/e2e typecheck
pnpm -F @html-anything/e2e test

04Agent Adapters

沿用本機既有登入憑證，將 coding-agent CLI 接入 HTML renderer。

Claude Code

claude -p

使用 stream-json、verbose、partial messages 與 bypassPermissions。parser 也能從 Write tool call 救回 HTML，避免只收到「已輸出到檔案」。

OpenAI Codex

codex exec

使用 --json、--sandbox workspace-write 與網路開關設定。適合把 Codex CLI 變成本機 HTML 生成後端。

Cursor / Gemini

stream JSON

Cursor Agent 與 Gemini CLI 都走 stream-json 類協定，前端可即時 append delta 到 preview iframe。

Other CLIs

thin argv shapes

README 主打 8 個 CLI；程式碼也可看到 OpenClaw、Qoder、DeepSeek 等路徑。ACP JSON-RPC 類 agent 目前仍明確丟 unsupported error。

Parser State

防重複輸出

makeParser 保存跨行狀態，避免 agent 同時輸出 token delta 與 final assistant message 時把 HTML append 兩次。

BYOK

Zero app-level API key

HTML Anything 不收你的模型 API key；它沿用你在本機 CLI 內完成的 login、auth 或 subscription。

05Template System

SKILL.md 資料夾即技能單元：frontmatter 驅動模板分類與設計約束。

每個技能是一個資料夾：SKILL.md、example.html、可選 assets/ 與 references/。frontmatter 描述 mode、scenario、surface、preview、design_system 等欄位，template picker 依此分類。新增技能以新增可讀、可審、可測的資料夾為單位，無需實作 plugin 介面。

README 說明技能 prompt 內建硬性約束：CJK-first font stack、8px baseline grid、contrast ≥ 4.5、不能用 lorem ipsum、必須使用真實資料。這些約束以結構化規則形式寫入 prompt，降低 agent 生成通用 AI 樣板內容的機率。

Surface代表技能適用交付物
Prototypeprototype-web、saas-landing、dashboard網頁原型、SaaS landing、資料看板。
Deckdeck-swiss-international、deck-guizang-editorialKeynote 風格簡報、編輯感長頁、課程模組。
Socialcard-twitter、card-xiaohongshuX/Twitter、微博、小紅書卡片。
Frame / VFXvideo-hyperframes、frame-glitch-title1920x1080 影片 frame、Remotion/Hyperframes 前置腳本。
Officepm-spec、eng-runbook、finance-report產品規格、工程 runbook、財務摘要、HR onboarding。

06Export Layer

同一份 HTML, 針對不同平台做最後一哩格式化。

WeChat / Zhihu

CSS inline

juice 將 CSS inline 化，配合平台需要的 markers；Zhihu 另處理 LaTeX image placeholder。

PNG

High-DPI screenshot

modern-screenshot 把 iframe render 成 2x PNG，再走 ClipboardItem 或下載。

Deck

Presentation handling

next/src/lib/deck.ts 與 export/deck 支援 slide navigation、deck extraction 與簡報場景。

Remotion

Hyperframes handoff

frame 與 vfx 技能輸出可交給 Hyperframes/Remotion 後續 render mp4。這是 roadmap 的高價值方向。

07Security Boundary

local-first 不等於無風險, 因為 API 可以 spawn CLI。

08Codex Playbook

把 HTML Anything 當作 agent UI runtime 來研究。

先讀 adapter 測試

next/src/lib/agents/__tests__/argv.test.ts 是理解 CLI 協定差異的入口。

新增 skill 從鄰居複製

複製相近 SKILL.md，改 frontmatter、硬性設計規則與 example.html。

用 export adapter 拆平台問題

新平台不要改 prompt，先新增 next/src/lib/export/<target>.ts。

保留 prompt diff-edit

editFromHtml 是降低多輪修改漂移的關鍵，適合拿來做版本化內容工作流。

把安全設為產品要求

Host guard、sandbox preview、local-only deployment 不應被視為可選項；這是 spawn-agent 架構的基本代價。

參考資料