前言¶
讓模型直接寫 HTML 報告，最常見的失敗方式不是拋異常，而是靜默失效：類名是模型憑印象編的，頁面打開後那一塊沒有樣式；<head> 裏漏了一條 <link>，組件類名全都對，但整段沒樣式；骨架層級寫錯，佈局塌了，控制台也不報錯。這三種情況的共同點是——沒有人打開看一眼就不會被發現。
owain323/dsh-plugin-agentcss 就是衝着這三類問題來的。它是 DeepSeek Harness 的一個插件，維護者 owain323，社區目錄 SkillHub 上歸在「工作流」分類下（目錄頁顯示當前 0 星），MIT 許可。它把 agentcss 這套報告頁庫包裝成四個模型可以直接調用的工具：查組件、生成頁面骨架、交付前自檢、導出 PDF。
下面介紹這個插件的具體能力、安裝方式和實際一輪的用法。
它解決什麼¶
README 裏把三個坑列得很清楚：
| 坑 | 現象 | 誰能發現 |
|---|---|---|
| 類名憑感覺編 | 頁面不報錯，只是那一塊沒樣式 | 沒人，直到人打開看 |
<head> 漏一條 <link> |
組件類名都對，但那部分完全沒樣式 | 沒人，直到人打開看 |
| 骨架層級錯 | 佈局塌了，但不拋異常 | 沒人，直到人打開看 |
已有的做法要麼是讓模型把整個庫抄進頁面（體積大、版本容易漂），要麼是寫完人工打開檢查。這個插件選的是第三條路：讓模型查庫、按規則生成，然後的機器自檢把上面三類問題攔在交付前。它明確不含組件定義，組件、令牌、判據全部來自 npm 上的 agentcss。
四個工具¶
插件註冊的工具名字都以 agentcss_ 開頭。四個工具對應「查得到、起得對、交得出去、發得出去」四步。
1、agentcss_catalog：寫 HTML 之前調用。按關鍵詞或者分層查組件，返回組件 id、所屬分層、根類名、需要引入的樣式表路徑，以及一句話用途。需要額外組件時先用它查。
2、agentcss_new_page：新頁面從這裏開始，不要手寫 <head>。返回一個自包含的目錄，裏面有 index.html 和 agentcss/（庫樣式表副本）。
3、agentcss_check：每次改完頁面跑一次。返回結構化問題列表，每條帶規則名、行號、級別和說明。
4、agentcss_pdf：內容定稿、要發出去或者要交給打印時用。返回 PDF 路徑、頁數、紙幅、字節數；如果有 JS 異常會點名。
agentcss_check 的檢查項包括：類名在庫裏有沒有、類名有但頁面沒引到定義它的樣式表、圖片缺不缺 alt、表頭有沒有 scope、標題有沒有跳級、表單控件有沒有可讀名稱、id 有沒有重複。它是純靜態檢查，不聯網、不開瀏覽器。
agentcss_pdf 會起一次本機 Chrome/Edge，不開端口、不復用你的瀏覽器配置。導出順序是庫定死的：頁面加載 → 字體就緒 → 可選可見元素 → 額外等待 → 定格動畫 → 打印。失敗或超出頁數預算時，它不改寫舊 PDF，也不替你截斷內容——README 的說法是截斷是靜默丟東西，比報錯停下危險得多。
安裝與啓用¶
安裝命令直接來自 README。Harness 裏「添加插件」有三個入口：npm 包名（推薦，版本隨庫走）、GitHub 地址、本地目錄。命令行等價寫法：
# 從 npm 裝
dsh plugin --profile desktop add dsh-plugin-agentcss
# 或從 GitHub 裝（跟蹤 main）
dsh plugin --profile desktop add https://github.com/owain323/dsh-plugin-agentcss
裝完需要重啓 Harness，工具纔會出現到模型的可調用列表裏。
典型一輪¶
下面的流程取自 README 的例子：
用戶：用 agentcss 做一份三季度營收分析頁，放在 /work/reports/q3
模型 → agentcss_new_page({ dir: "/work/reports/q3", recipe: "report/finance" })
← 已生成 /work/reports/q3/index.html；樣式表已複製到 …/agentcss
模型 寫內容（需要額外組件就先 agentcss_catalog 查一下）
模型 → agentcss_check({ path: "/work/reports/q3/index.html", recipe: "report/finance" })
← 不通過：1 個 error
L42 error class-not-linked .bar 在庫裏，但這頁沒引 09-assets/bar/bar.css
模型 補一條 <link>，再跑一次 → 通過：0 error · 0 warn
要點是：不要先手寫 <head> 和骨架，交給 agentcss_new_page 生成；內容寫完用 agentcss_check 認一次賬；要交付了再走 agentcss_pdf。dir 和 path 都必須傳絕對路徑，傳錯會明確報錯，不會猜。
依賴與兼容¶
README 給的兼容表：
| 項 | 要求 |
|---|---|
| Node | >= 18（Harness 桌面版自帶 24） |
agentcss |
^0.27.5 |
| Harness | 0.2.x 實測（0.2.2-rc.1） |
^0.27.5 這個下限不是隨便選的。README 說明過半能力取決於庫那一層：0.27.3 之前是灰底淺字；0.27.4 之前 .rep__fig 裏的圖沒有寬度約束，一張 1920px 的截圖會把整頁撐破；0.27.5 才把倉庫名與包名統一、站點根路徑改 /agentcss/。這三件事在屏幕上都不顯眼，要麼打出來才知道，要麼寫進 URL 才知道。0.x 的 caret 範圍只在同一個 minor 內，庫出 0.28 時插件要跟着升一次。
另外兩個刻意的選擇值得知道：
- 不依賴任何
@deepseek-ai/*包。不用defineTool，直接用ctx.tools.register()註冊裸定義。README 指出defineTool只是把參數編譯成 JSON Schema 的包裝器，二者等價，少一個 peer 依賴就少一整類版本解析故障。 - 不聲明
engines.dsh。0.2.x 是預發佈版，semver 的預發佈規則會讓>=0.2.0這類範圍判不通過，安裝直接被拒。
已知限制¶
1、dir / path 必須傳絕對路徑。寫錯會明確報錯，不會猜。
2、建頁時會把庫樣式表複製到頁面旁邊，約 340 KB、80 個文件。這是拿體積換自包含：頁面雙擊就能打開，不髮網絡請求，發給別人也不會掉樣式。
3、ai shot（橫向溢出與 JS 報錯的截圖體檢）還沒接進來。README 明確說它是「看」的循環，與這裏「寫對 + 發出去」不是一條線。
4、PDF 是屏幕渲染結果。實體打印機的紙張、驅動縮放、雙面、頁眉頁腳仍需人工打樣一次，agentcss_pdf 不聲稱替你驗過。
5、agentcss_new_page 默認不覆蓋已有文件。目標 index.html 存在時默認拒絕，除非顯式傳 overwrite: true。
6、包本身只有約 700 行適配代碼（含註釋），沒有任何組件定義。組件、令牌、判據全部來自 npm 上的 agentcss，agentcss_check 的類名白名單是從庫的 CSS 現算的。README 解釋了這樣做的理由：複製一份組件樹過來就等於同時存在兩份真值，改一次 token 就開始不同步，兩邊各跑各的門禁，沒人會發現。
適用場景與注意¶
適合的場景：用 Harness 寫 HTML 報告頁、想用一套既定組件庫和版式、需要在人工打開之前做一次機器自檢、需要把頁面導出 PDF 發出去。
幾點需要注意：
- 這個插件以當前 dsh 進程的權限運行。它能起本機 Chrome 導出 PDF，也能按絕對路徑讀寫任意位置的文件。安裝前先看一遍源碼和許可證（MIT，包的
files裏包含index.js、cordis.patch.yml、README.md、LICENSE）。 - 包的
dsh.bundle.patch指向cordis.patch.yml，說明安裝時會對 Harness 的打包環節打補丁。這是插件自己做的適配，接第三方插件前值得先打開這個文件看一眼改了什麼。 - 庫是 0.x，
^0.27.5意味着 minor 升級會帶來行爲變化。升級插件時留意它聲明的agentcss範圍，不要單獨把庫升上去。 - 目錄頁（SkillHub）是社區站點，與 DeepSeek / 幻方無官方從屬關係，也不代表這是官方應用商店條目。
- 需要人工兜底的地方：PDF 上機打樣，以及「看一眼渲染出來對不對」這件事，插件目前不覆蓋。
小結¶
這個插件的價值不在於多一個組件庫，而在於它替模型建了一道交付前的閘門：頁面骨架按規定生成，類名和樣式表引用可以查、可以自檢，自檢不過就不收尾，PDF 失敗寧可停下也不靜默截斷。它解決的是「不報錯但不好看」這一類問題，這一類問題在沒有這道閘門時只能靠人打開頁面發現。
- 目錄頁：https://www.skillhub.cn/plugins/owain323/dsh-plugin-agentcss
- GitHub：https://github.com/owain323/dsh-plugin-agentcss
