Communitygithub.com

zernie/vigiles

定義 vigiles.sh 登陸頁面 (site/) 的目的、用戶體驗流程與現代極簡設計標準。用於設計、編輯、新增或審查任何 site/ 元件、英雄區塊、章節或行銷文案時 — 請在接觸 site/ 之前閱讀,並以它為標準審查每一項變更。不適用於 docs/ 或應用程式本身。

vigiles 是什麼?

此技能為 vigiles.sh 登陸頁面 (site/) 提供了明確的目的、UX 流程與設計標準。其核心原則是「減法設計」:任何無法證明其必要性的元素都應刪除,以對抗頁面變得擁擠、模板化的常見問題。最終目標是最大化實際執行 `npx vigiles audit` 命令的訪客比例,這是所有設計決策服務的單一轉換指標。目標受眾為已熟悉 agentic-coding 工具(如 Claude Code、Codex、Cursor)的開發者。關鍵的「殺手級應用」是分級報告:展示結果,而非解釋機制。此技能詳細說明了英雄區塊、文案、可信度、轉換手段及設計風格的要求,並提供了一份已犯錯誤的「反模式」清單以免重蹈覆轍。它基於 Vite + React + Tailwind 構建,僅支援深色模式,部署於 GitHub Pages,並使用 Plausible/Fathom/GoatCounter 等輕量級隱私友善分析工具。

相容平台✓Claude Code✓Codex CLI✓Cursor✓Antigravity
npx skills add https://github.com/zernie/vigiles/tree/HEAD/.claude/skills/landing-site

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

登陸頁面 — 目的、UX 與設計標準

前端大門是 site/(Vite + React + Tailwind,僅深色模式),部署在 vigiles.sh。此技能是每項變更都必須遵守的標準。它存在的目的是為了防止一個反覆出現的失敗:不斷添加元素而非刪除它們,導致頁面顯得擁擠且模板化(「類 tilda」風格),而非現代簡潔。

在所有規則之上的唯一法則:如有疑慮,就刪除。以減法進行設計。 如果刪除一個元素不會失去任何意義,就刪掉它。任何 新增 一個方框、說明文字、第二個按鈕或安撫性說明的變更,直到被證明必要之前都應受到質疑。

目的(網站的用途)

  • 首要目標 — 最大化實際執行 npx vigiles audit 的訪客比例。 這是每個設計決策所服務的唯一轉換指標。CTA 必須是卓越的(無摩擦、直觀、隨時可觸及)。如果一項變更無法幫助使用者執行該命令,它就沒有存在的價值。
  • 目標受眾: 已經習慣使用 agentic-coding 工具(Claude Code、Codex、Cursor)的開發者。他們持懷疑態度,並常在手機上快速瀏覽。
  • 殺手級應用 是分級報告 — 展示結果,而非解釋機制。
  • 前端承諾:「你的 Agent 工具組的 Lighthouse」 — 一條命令、零配置、無需上傳即可為你的 skills/hooks/subagents/references 評級。
  • 演示框架需同時完成四項任務 — 設計時需兼顧所有四項,勿讓任一項排擠其他項。 (1) 介紹 — 讓使用者一眼就明白 vigiles 是什麼(分級報告本身就是推銷)。 (2) 演示 — 即時展示真實評級,無需任何操作(內置的 FEATURED 標籤)。 (3) 線上執行 — 透過輸入網址來為你的公開倉庫評級(GitHub 匿名 API;僅限公開倉庫)。 (4) 命令複製 — 處理其餘情況:私有或本地倉庫無法在瀏覽器中執行,因此其任務是提供一個乾淨、明確的 npx vigiles audit 命令複製(命令交接,而非虛假的瀏覽器內執行)。由此衍生出兩個關鍵的清晰度規則:(a) 框架必須始終明確顯示正在評級的是哪個倉庫,以及它是預定義範例(標籤)還是使用者自行輸入的(輸入框)——絕不能含糊不清; (b) 私有倉庫路徑是一個頭等重要的功能,而非事後塞進一句話裡的附加項——一個帶有清晰標籤的命令複製區塊,並在 390px 寬度下驗證。 不要將命令疊成三行(在一個已經顯示了名稱的高亮標籤上方,再顯示一個「$ vigiles audit 」的標題是資訊過載——標題的任務是識別被評級的倉庫及其來源,而非重新列印命令)。
  • 文案:具體勝過巧妙,絕不植入讀者原本沒有的疑慮。 此原則避免了兩種常見錯誤:(1) 一個看似巧妙但實則晦澀的標題(例如「‘Valid’ is not ‘true.’」)——應以具體的痛點開場(「配置有效,但 Agent 故障」),讓下方的卡片來承擔細微差別;(2) 一篇帶有防禦性的常見問題集,反而凸顯了讀者尚未注意到的弱點(例如「它足夠穩定可以採用嗎?」反而會將注意力引向一個可怕的版本號)——應將引起疑慮的內容替換為持懷疑態度者實際會問的建立信心的內容(例如「會有任何資料離開我的電腦嗎?」、「我可以為私有倉庫評級嗎?」)。以一個冷靜的懷疑者角度測試每一行文案:這會讓我更有可能還是更不可能執行這個命令?如果降低了可能性,就刪除或重新組織。
  • 可信度:演示報告僅顯示真實的掃描結果——絕不偽造結果。 品牌理念是「實測,而非宣稱」,因此報告中任何一個硬編碼或偽造的數字都會事後破壞所有真實發現的可信度。對於一個確實無法在此處執行的項目(模型閘門觸發率),使用帶有誠實預留位置的鎖定提示(使用 em-dash「執行以填充」,不含數字)是可以接受的——它並未偽造任何東西。但是,為工具實際會計算的項目偽造「結果」 則不行——請顯示真實的計算結果,或者將其保留為報告框架之外的誠實說明卡片。
  • 降低嘗試門檻: 提供預先填寫好的流行開源倉庫作為一鍵「評級」標籤,讓訪客無需輸入或擁有自己的倉庫即可看到真實報告。已完成 — DemoAudit 中的 FEATURED 標籤可即時渲染內置的真實報告。
  • 每個結果頁面都必須包含分享功能和穩定連結。 一個無法分享給隊友的評級結果是死路一條,因此:(1) 每個完成的評級都是一個可複製的深層連結 (vigiles.sh/?repo=owner/repo#try),加載時會自動執行審計——該 URL 本身就是分享單位;(2) 任何結果都應提供一鍵分享(手機上使用原生分享功能,其他地方複製連結——DemoAudit 中的 ShareRow);(3) 這個深層連結與輸入框/標籤使用的 slug 相同,因此共享的連結、輸入的倉庫和標籤都會解析到同一個程式碼路徑。新的結果頁面必須同時包含這兩者。已完成 — 請保持其正常運作。(此處適用的聲譽規則是——分享是選擇加入,拒絕是自由的,評級的對象是產物而非人——這些是根目錄 CLAUDE.md 中 gate-first-adoption 規則的內容;此處不再重述。)
  • 衡量轉換: 對漏斗進行分析(命令複製數、提交輸入數、標籤嘗試數、重新評級數、分享點擊數)。該網站部署在 GitHub Pages 上,而非 Vercel ——因此 Vercel Analytics 不適用。請為靜態託管網站使用輕量級、注重隱私的腳本式分析工具:Plausible / Fathom / GoatCounter。漏斗已經完成檢測——track() (site/src/lib/track.ts) 會觸發 demo_* 事件,並且在供應商對接完成前是一個安全的空操作。剩餘工作: 將供應商腳本標籤添加到 index.html 並確認事件能成功發送。分析工具僅追蹤「結果」類型,絕不追蹤輸入的 slug(私有倉庫名稱不得洩露)。

方向 — 決策記錄(保持最新;此處為方向所在)

當前網站背後的戰略性決策。當方向改變時更新此部分——它是設計文檔,而不僅僅是樣式指南。每個決策都花費了實際的迭代才能達成;請勿在未經思考的情況下悄悄撤銷它們。

  • 預設演示必須展示一個「抓獲」案例——以一個真實的低分開場,絕不能展示一片 A 級高分。 FEATURED 標籤在知名倉庫上呈現了一個真實的 F → C → B → A 分級尺度(目前為 davila7/claude-code-templates F 級、disler/claude-code-hooks-mastery C 級、madappgang B 級、obra/superpowers A 級)。為何必須如此: 真實的流行插件在瀏覽器可以執行的確定性軸線上大多獲得 A/B 級——重大的失敗(技能不觸發、描述衝突)存在於瀏覽器無法執行的模型閘門觸發率層級中——因此一個看起來很不錯的預設值反而會反駁該工具(「一切正常,我為什麼需要這個?」)。預設值必須是一個真正有問題的倉庫,這樣「殺手級應用」(報告)才能展示 vigiles 確實抓到了問題。刷新低分預設值(倉庫會隨著時間被修復):使用 git clone https://github.com/<slug> 後執行 node dist/cli.js audit <dir> --json 進行掃描(注意:codeload/api.github.com 在雲端環境中被代理封鎖——git clone 透過 github.com 可以正常運作)。選擇一個符合以下條件的倉庫:(a) 知名;(b) 存在客觀的、一行就能修復的發現(如無效的工具、看不見的 skills/ 目錄、無效的 hook 事件——而非故意讓人難堪的設計),以便公開評級是公平的(Lighthouse 模型本身就是對公開產物的公開評級)。將報告烘焙到 site/src/demo/reports/ 並將其接入 FEATURED。模型層級的發現應保留在瀏覽器演示之外:根據設計,瀏覽器演示僅限於確定性檢查(參見下方瀏覽器內演示的不變量),因此對這些發現的誠實呈現方式是 LockedRow 提示,而非偽造的結果。
  • 只提名字不解釋是 #1 文案失敗——請為每個概念提供解釋,否則就刪除它。 一個初次訪問的訪客不知道「linter」、「reference」、「enforce」、「spec」或某個分類名稱的含義。每個概念在首次使用時都必須有通俗易懂的解釋,否則就刪掉。不要直接拋出專業術語(舊的 README 已經學到了這一課——「在首次使用時定義 HARNESS」;網站曾經倒退,不得不重新學習)。以一個從未聽說過 vigiles 的冷靜 Claude Code/Codex 使用者的角度測試每一行文案。
  • 將說明融入報告中——不要添加獨立的說明卡片。 報告本身就是「殺手級應用」。瀏覽器無法展示的概念(模型閘門觸發率、需要本地配置的 linter 交叉引用)是報告內部的虛線 CLI-only 行 (report-view/src/Report.tsx 中的 LockedRow / CliRulesRow),而不是框架下方漂浮的卡片。如果網站在兩個地方解釋同一個報告,請刪除多餘的那個(這就是為什麼 Wedge 的五類別條帶和獨立的「你的規則 → 已執行」卡片被移除的原因——報告本身已經包含了這兩者)。
  • 一次只提供一個輸入方式——使用「公開/私有」頁籤,而不是堆疊顯示。 原本的英雄區塊輸入框是輸入欄 +「public API」說明 + 私有命令交接 + 隱私說明全部堆疊在一起(非常擁擠)。現在它在 DemoAudit 中變成了 公開 | 私有 頁籤:公開 = 即時輸入倉庫的組合框;私有 = npx vigiles audit 命令複製區塊。每次只顯示一個輸入方式。
  • 誠實提示,絕不模糊/偽造(取代任何舊的「將其模糊渲染」的註記)。 模型閘門觸發率的行使用 em-dash 預留位置(recall — · precision —),而非模糊的偽造數字。模糊處理看起來像渲染錯誤,也是一種付費牆的暗黑模式;而偽造數字則違反了「實測,而非宣稱」的原則——放在嘲笑宣稱數字的文案旁邊更是錯上加錯。如果未來需要更強的提示效果,請使用帶有 example 標籤的真實測量數字,絕不使用偽造或模糊的數字。

UX 需求

  • 命令優先。 npx vigiles audit 是通用操作(適用於所有作業系統、所有終端)。它是主要的 CTA。其他所有功能都是次要的。
  • Claude Code 深層連結 (claude-cli://) 僅作為桌面端增強功能,絕非主要路徑——它在手機 / CC Web / 未安裝 CC 的桌面端會無聲失效。僅在它能正常運作的地方渲染;切勿提供一個點了沒反應的按鈕。
  • 在手機上保持誠實。 不要有無效的按鈕。如果某個桌面端專屬的操作無法執行,請直說,並提供實際操作(即該命令)作為替代。
  • 每個畫面只有一個主要操作。 次要操作應是低調的——一個文字連結或一個輕量藥丸按鈕,絕不能是第二個厚重全寬按鈕與主要操作競爭。
  • 工具組中立。 說「Claude Code 或 Codex」,不要只提 Claude Code——它是一個實現細節,而非標題。不要過度解釋內部機制。
  • 低摩擦 + 友好。 快速瀏覽的人應能在一個畫面內理解這是什麼以及如何嘗試,無需閱讀大段文字。

設計標準 — 現代與極簡(反擁擠規則)

參考 Linear / Vercel / Raycast 的風格:自信的深色背景、充裕的留白、精煉的文字、每個章節一個清晰的焦點。絕非功能堆砌的模板。

  • 每個元素必須證明其存在的價值。 刪除任何僅為重述另一個元素的內容(重複說明的螢幕截圖說明文字;說了兩次的信任文案;多餘的子標題)。
  • 刪除其他元素已暗示的任何標籤。 當已存在 GitHub/星號連結時,「free & open source」徽章是多餘的;在「Grade a specific repo」標題上方的「AUDIT A SPECIFIC REPO」徽章是重複的。如果上下文已經告訴了讀者,那麼標籤就是噪音。
  • 每個連結/CTA 必須是可操作的且具體的**。** 讀者必須確切知道點擊後會發生什麼。沒有模糊或被動的次要連結(例如「Have Claude Code?…」)。如果某個次要路徑不值得一個清晰、具體的操作,那就刪掉它(或將其移到導航欄,在那裡一個持續存在的連結勝過一個軟弱無力的折疊區塊連結)。
  • 每個章節一個焦點。 視線應首先落在一個東西上。
  • 偏好留白與排版,而非方框。 不要堆疊 3 個以上的全寬邊框方框;這種重複感正是頁面顯得擁擠的原因。優先使用排版層次和空間,而非邊框。但留白必須是有意的——也不能有近乎空白的大片視口空洞。
  • 安撫性說明只出現一次,且僅一行。 信任文案(「nothing uploaded」)出現一次,且保持簡潔——絕不寫成三行段落,也不要在每個章節重複。
  • 連貫性。 英雄區塊(徽章 + 標題 + 副標題 + 視覺元素)必須讀起來像一個整體概念,每個部分都提供新的資訊。如果副標題只是在說螢幕截圖已經展示的內容,那就刪掉或精煉它。
  • 色彩/強調要有節制。 一個強調色,語義化的頻段顏色必須總是代表某種意義(分級頻段)。每個要點只加粗一個短語,而非每個子句。沒有裝飾性的表情符號五彩紙屑。
  • 一致的間距比例。 不要手動調整破壞節奏感的單次邊距。

反模式(此處曾出現的問題)

  • 在一個折疊區域內堆疊輸入欄 + 大按鈕 + 三行信任文案 + 分隔線 + 命令 + 說明 + 另一個按鈕。(解決方案:保留約 3 個元素,刪除其餘的。)
  • 產品截圖下方的說明文字重述了產品截圖本身。
  • 為每個問題添加一個通知/按鈕,而非重新思考整個流程。
  • 兩個競爭的主要 CTA(深層連結 + 命令)沒有層級關係。
  • 以 CC 為先的表達方式(例如以「在你的 Claude Code 中執行…」作為標題安撫用語)。
  • 一個桌面端專屬流程(Claude Code 的 claude-cli:// 深層連結)在手機上作為備用方案可見,但它只是重複了另一個章節已經顯示的命令——導致手機上在兩個相鄰的章節中出現相同的 npx vigiles audit 區塊。(解決方案:使用 hidden sm:block 將整個桌面端專屬章節隱藏;英雄區塊 + CTA 已經包含了這個命令。)

瀏覽器內演示(已完成 — 需保持的不變量)

即時「為任何倉庫評級」的演示已經建置完成(在 DemoAudit.tsx + site/src/demo/ 中):輸入/貼上一個公開倉庫或點擊一個精選標籤,它會客戶端獲取工具組檔案,並執行與 CLI 相同的編譯後的引擎。以下規則現在是需要維護的不變量,而非未來方向。

  • 每個結果都是可分享的(參見上面的可分享性目標)。 完成的評級附帶一鍵分享功能以及一個穩定的、可自動執行的 ?repo= 深層連結。這是演示的硬性要求,而非可有可無的功能——請勿提供一個不包含這兩者的結果頁面。
  • 在瀏覽器內執行,而非託管服務。 審計計算完全在訪客的瀏覽器客戶端運行(透過 GitHub API 獲取倉庫檔案,以 JS 運行純檢測器)→ 強調「沒有任何東西離開你的機器」;零後端/成本。唯一的「託管」是 GitHub Pages 上的靜態檔案服務(無伺服器函數、無資料庫、無計費)。這種性質是一個區分要素——保持這種狀態。切勿為了看起來更「專業」(例如使用託管的審計後端)而放棄它。
  • 僅限公開倉庫。 瀏覽器可以且僅可以為公開 GitHub 倉庫評級(無令牌、無私有 API 命中)。當輸入一個私有倉庫時(我們會檢測到),演示會顯示一個清晰的訊息:它無法在瀏覽器內執行,並會提供命令來代替。設想一個想要嘗試的火星漫遊車專案工程師——她複製貼上一個公開的 NASA 倉庫,得到一個真實的評級,然後在自己的私有分支上運行該命令。
  • 精選的倉庫是烘焙在程式碼中的。 FEATURED 標籤載入的是 site/src/demo/reports/ 中完整的、預先計算的 JSON 報告,而不是重新觸發客戶端擷取。這能保證它們總是有效(無網路依賴),並且總是即時顯示(無載入狀態)。一個「重新整理」等於重新訪問 site/src/demo/reports/ 的連結,並在 FEATURED 中更新建置的倉庫。精選的評級與真實的掃描位於相同的 Report 元件中,因此顯示方式相同——它們只是繞過了擷取/執行階段。
  • 使用者輸入的倉庫會即時進行端到端的擷取與評級。我們是即時運算的——不進行烘焙。載入使用者的報告等同於在他們的機器上執行 npx vigiles audit --json,只是在瀏覽器中進行(當然,僅限確定性規則)。
  • 鎖定的(模型閘門觸發率)行在所有報告中都存在。 精選的和使用者輸入的報告都包含 LockedRow 元件,它會為任何被評級的倉庫顯示「模型閘門確定性」提示。這並不是一個僅在烘焙報告中才有的功能——它在所有報告中都是一致的,附帶誠實的 em-dash 預留位置。
  • 離線備用方案: DemoAudit 的 FEATURED 標籤會渲染烘焙的 JSON,即使沒有網路也能運作。如果 GitHub API 離線,精選的評級仍然有效。(使用者輸入的倉庫當然會顯示一個錯誤。)FEATURED 標籤的離線備用方案是一個已經解決的問題——不要破壞它。
  • 分析工具已經檢測了 demo_* 事件(已在 track.ts 中完成)。見上方的分析工具章節。
  • 瀏覽器內演示的不變量文件是權威來源。 這些規則位於 site/src/demo/README.md。如果在這裡和該 README 之間出現歧義,該 README 優先。

相關技能