landing-site

落地页——目的、用户体验与设计标准

入口页面位于 site/（Vite + React + Tailwind，仅支持深色模式），部署在 vigiles.sh 上。这项规范是衡量每次更改的标准。它旨在避免一种反复出现的问题：不断添加元素而不是删减元素，导致页面显得拥挤、像套用模板（“tilda 风格”），而非现代简洁。

统领其他所有规则的一条原则：拿不准时，就删掉。用减法做设计。 如果删掉某个元素不会丢失任何信息，就删掉它。凡是_添加_方框、说明文字、第二个按钮或一句安抚性文案的更改，在证明其确有必要之前都值得怀疑。

目的（网站的用途）

• 首要目标——最大化实际运行 npx vigiles audit 的访客比例。 这是所有设计决策都要服务的唯一转化指标。CTA 必须出色（无摩擦、一目了然、始终触手可及）。如果某项改动不能帮助用户运行命令，那它就不值得保留。
• **受众：**已经在日常使用 Agent 编码工具（Claude Code、 Codex、Cursor）的开发者。他们持怀疑态度，而且会在手机上快速浏览。
• 亮点是分级报告——展示结果，不要解释机制。
• 入口承诺：“为你的 Agent 工具链打造的 Lighthouse”——只需一条命令、 零配置、不会上传任何内容，即可为你的技能／钩子／子 Agent／参考资料评级。
• 演示框架同时承担四项任务——设计时四者都要兼顾，不能让某一项挤占其余部分。（1）介绍——让人一眼看懂 vigiles 是什么（分级报告本身就是宣传内容）。（2）演示——无需任何操作即可立即看到真实评级（内置的 FEATURED 标签）。（3）浏览器内运行——输入你的公开仓库，实时评级（GitHub 匿名 API；仅限公开仓库）。（4）为其余用户复制命令——私有或本地仓库无法在浏览器内运行，因此这里的任务是提供清晰醒目的 npx vigiles audit 复制项（交接命令，不是假装在浏览器内运行）。由此得出两条承重级清晰度规则：（a）框架必须始终明确显示正在展示的是哪个仓库，以及它是预设示例（标签）还是你自己的仓库（输入）——绝不能含糊；（b）私有仓库的操作路径必须是显眼的一等选项，不能事后塞进一句话里——提供标注明确、干净的命令复制项，并在 390px 宽度下验证。不要把命令堆叠成三行反复展示（顶部的 $ vigiles audit <slug> 显示在已经标明仓库名称的高亮标签上方，信息过多——顶部的作用是标识被评级的仓库及其来源，而不是重复打印命令）。
• 文案：具体胜过巧妙，而且绝不能凭空制造读者原本没有的疑虑。这能避免两种实际失误：（1）故弄玄虚的标题显得晦涩（“‘Valid’ 并不等于 ‘true.’”）——直击具体痛点（“配置有效，Agent 却坏了。”），把细微差别留给下方的卡片；（2）暴露弱点的防御式常见问题会让读者注意到原本没察觉的问题（“它足够稳定，值得采用吗？”会把目光引向令人担忧的版本号）——用建立信心的内容取代制造疑虑的内容，回答持怀疑态度的用户真正会问的问题（“有任何内容会离开我的设备吗？”、“我能给私有仓库评级吗？”）。以冷静的怀疑者视角检验每一行：它会让我更有还是更没有可能运行命令？如果会降低可能性，就删掉或改写。
• 可信度：演示报告只展示真实扫描结果——绝不伪造结果。 品牌理念是“以测量说话，而非空口宣称”，所以报告中哪怕有一个硬编码或伪造的数字，都会让人事后怀疑所有真实发现。对于确实无法在此运行的内容（受模型限制的触发率），可以显示带有诚实占位符的锁定预告（长破折号“运行后填充”，不显示数字）——这不会伪造任何内容。对于工具实际会计算的内容，绝不能伪造“结果”——应展示实际计算结果，或者在报告框架外放置诚实说明卡片。
• **降低尝试门槛：**提供预先填入热门 OSS 仓库的一键“为此仓库评级”标签，让访客无需输入，也无需拥有自己的仓库，就能看到真实报告。已上线——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，但可以通过 github.com 使用 git clone）。选择一个（a）广为人知，（b）存在客观且只需一行即可修复的问题（失效的工具、无法识别的 skills/ 目录、失效的钩子事件——而不是故意设计得很差），这样公开评分才公正（Lighthouse 模型评定的正是公开产物的公开评分）。将报告放入 site/src/demo/reports/，并接入 FEATURED。模型层级的问题不要放进浏览器演示：演示按设计只提供确定性检查（见下文的浏览器内演示不变量），因此，诚实的呈现方式是在 LockedRow 中预告，而不是伪造结果。
• 只提名称却不解释，是文案的头号问题——每个概念都要解释清楚，否则就删掉。 初次访问的用户不知道“代码检查工具”、“引用”、“强制执行”、“规范”或类别名称是什么意思。每个概念首次出现时，都要用通俗易懂的语言解释，否则就删掉。不要随意抛出术语（旧版 README 已经吸取了教训——“首次出现时定义 HARNESS”；网站后来又犯了同样的问题，不得不重新吸取教训）。逐行检查文案，设想读者是从未听说过 vigiles 的 Claude Code/Codex 新用户。
• 把补充说明融入报告——不要额外添加独立的说明卡片。 报告本身就是惊喜所在。浏览器无法展示的概念（由模型决定的触发率、需要本地配置的代码检查工具交叉引用）应作为报告仅限 CLI 的虚线行（report-view/src/Report.tsx 中的 LockedRow / CliRulesRow），而不是悬浮在报告框架下方的卡片。如果网站在两个地方解释同一份报告，就删掉重复内容（这就是为什么移除了 Wedge 的五类别条和独立的“你的规则 → 强制执行”卡片——报告已经包含了两者）。
• 一次只展示一种输入方式——使用公开/私有标签页，不要堆叠。 主视觉区域的输入框曾同时堆叠输入框、“public API”说明、私有命令入口和隐私说明，显得拥挤。现在 DemoAudit 中改为 Public | Private 标签页：Public = 可实时输入仓库的组合框；Private = 复制 npx vigiles audit 命令。一次只展示一种输入方式。
• 诚实地预告，绝不模糊或造假（取代任何旧的“模糊渲染”说明）。 由模型决定的行使用破折号占位符（recall — · precision —），而不是模糊处理的虚假数字。模糊处理看起来像渲染错误，也像暗黑付费墙手法；捏造数字则违背“测量所得，而非声称如此”的原则——尤其是放在嘲讽声称数字的文案旁边，更是错上加错。如果之后想要更有力的预告，就使用真实测得的数字并标注 example，绝不要伪造或模糊数字。

UX 需求

• 命令优先。 npx vigiles audit 是通用操作（适用于所有操作系统和终端）。这是首要 CTA，其他内容均为次要。
• Claude Code 深层链接（claude-cli://）是仅限桌面端的增强功能，绝不能作为首选路径——它在移动端、CC Web 或未安装 CC 的桌面端上会无声地失效。只在可用的场景中呈现；绝不要提供不起作用的按钮。
• 移动端要坦诚。 不要设置无效按钮。如果仅限桌面端的操作无法运行，就直说，并提供实际可用的操作（命令）。
• 每个屏幕只设一个主要操作。 次要操作应当低调——用文本链接或浅色胶囊按钮，绝不要再放一个醒目的全宽按钮与主要操作争抢注意力。
• 不绑定特定 Harness。 说“Claude Code 或 Codex”，不要把 Claude Code 放在前面——它只是实现细节，不是标题重点。不要过度解释内部机制。
• 轻松上手，亲切友好。 即使只是快速浏览，读者也应能在一个屏幕内了解这是什么以及如何试用，无需阅读大段文字。

设计标准 — 现代、简约（避免拥挤的规则）

参考 Linear / Vercel / Raycast 的感觉：深色系、从容大气、留白充足、言简意赅，每个区块都有一个明确焦点。不要做成塞满功能的模板。

• 每个元素都必须有存在的理由。 删除那些只是重复其他内容的元素（重复截图内容的说明；重复出现的信任文案；多余的小标题）。
• 删掉其他元素已经暗示的信息标签。 如果已经有 GitHub/星标链接，“免费且开源”徽章就是多余的；在“评估特定仓库”标题上方再放一个“评估特定仓库”徽章也是重复。如果上下文已经说明了信息，标签就是噪音。
• 每个链接/CTA 都必须可操作且具体。 读者必须清楚点击后会发生什么。不要使用模糊或被动的次要链接（例如“有 Claude Code 吗？……”）。如果次要路径无法提供清晰、具体的操作，就删掉它（或移到导航栏中；固定显示的链接胜过折叠区域中无力的链接）。
• 每个区块只设一个焦点。 读者的视线应当首先落在一个地方。
• 用留白和字体排版取代方框。 不要堆叠 3 个或更多全宽边框框体；这种重复才会显得拥挤。优先使用字体层级和留白，而不是边框。但留白必须是有意设计的——也不要留下近乎空白的视口。
• 只用一行文案提供一次安心保证。 信任文案（“不会上传任何内容”）只出现一次，简洁明了——绝不要写成 3 行段落，也不要在每个区块重复。
• 保持连贯。 首屏区域（徽章 + 标题 + 副标题 + 视觉元素）必须表达为一个整体，每个部分都补充新信息。如果副标题只是在描述截图已经展示的内容，就删掉或改得更有信息量。
• 克制使用颜色和强调。 只用一种强调色；语义色带始终应有明确含义（等级色带）。每个要点只加粗一个短语，而不是每个分句都加粗。不要用表情符号装饰。
• 保持间距尺度一致。 不要单独微调边距，破坏整体节奏。

反模式（这里曾经出现的问题）

• 在首屏内堆叠输入框 + 大按钮 + 3 行信任文案 + 分隔线 + 命令 + 说明文字 + 另一个按钮。（修正：保留约 3 个元素，删掉其余内容。）
• 在产品截图下方添加重复描述截图内容的说明。
• 为每个问题都添加一个通知/按钮，而不是重新思考整个流程。
• 放置两个相互竞争的主要 CTA（深层链接 + 命令），却没有层级区分。
• 以 Claude Code 为先导（“在你自己的 Claude Code 中运行……”）作为标题中的安心保证。
• 将仅限桌面端的流程（Claude Code claude-cli:// 深层链接）留在移动端显示，作为一个只会重复其他区块已有命令的备用选项——手机上连续两个区块都出现相同的 npx vigiles audit 代码块。（修正：对整个仅限桌面端的区块使用 hidden sm:block；首屏区域 + CTA 已经足够。）

浏览器内演示（已交付——必须保持的不变量）

实时的“为任意仓库评级”演示已构建完成（位于 DemoAudit.tsx 和 site/src/demo/ 中）： 输入或粘贴一个公开仓库，或点击一个精选标签，即可在客户端获取测试框架文件， 并运行与 CLI 相同的已编译引擎。以下规则现已成为必须保持的 不变量，而非未来方向。

• 每个结果都可分享（参见上文的可分享性目标）。 评级完成后，提供一键分享功能和稳定的自动运行 ?repo= 深层链接。这是演示的硬性要求，而非锦上添花——发布结果界面时必须包含此功能。
• 在浏览器内运行，而不是托管运行。 审计计算完全在访客的浏览器中客户端运行（通过 GitHub API 获取仓库文件，在 JS 中运行纯检测器）→ 强调“没有任何内容离开你的机器”；不需要后端，也没有成本。唯一的“托管”是在 vigiles.sh 上提供静态文件服务，与当前网站一样。明确不采用缓存式无服务器后端。
• 仅执行确定性计算。 运行无需模型的环节（Truthfulness / Structure / Safety-via-lethal-trifecta / description-overlap）。跳过受模型限制的 trigger-rate——该部分需要 LLM 和配额。
• 审计运行时显示真实进度条或流式状态——获取文件、逐个运行各环节——不能只显示静止的加载指示器。应让人感觉确实正在处理。
• 用诚实的占位内容预告受限的 LLM 部分，不要模糊处理（参见上文“诚实预告，绝不模糊处理或造假”的决定——它取代了更早的“将其模糊显示”指导）。受模型限制的 trigger-rate 在报告中显示为 CLI 专属虚线行（LockedRow），包含破折号占位符（recall — · precision —、“运行以填入”），并明确提供“复制提示词 →”选项，说明复制的内容——让人们想要在本地运行，同时绝不捏造内容。模糊处理看起来像渲染失败或付费墙，还会伪造数字；不要这么做。
• 复用真实的报告组件（从 AuditReport JSON 渲染）——绝不使用截图。这就是报告视图位于共享包中的原因（见下文）。

共享 UI 的仓库结构（已交付——必须保持的不变量）

审计报告（report/）和着陆页（site/）通过工作区包共享同一报告 视图——@vigiles/report-view（packages/report-view/）， 该包负责渲染 AuditReport，并拥有 Report 组件（演示框架使用 variant: "summary"， CLI 独立 HTML 报告使用 "full"）、架构、等级标记和 theme.css。已配置 npm 工作区（workspaces: [packages/*, report, site]）。**不变量：**演示和 CLI 报告必须使用同一个组件，并从同一份 AuditReport JSON 渲染——绝不使用截图，也绝不重复实现或通过相对路径跨包导入组件。使用方必须通过 @source 引入此包的 src （Tailwind v4 会忽略 node_modules）。根目录发布的 vigiles 包及其 CI 门禁（api-surface、coverage）必须保持通过——工作区为私有，且已从其 files 中排除。（CI 关键配置见 research/report-view-and-browser-demo.md。）

流程——发布任何网站更改前

门禁失败 → 先修复门禁（不可妥协）。 如果有本技能的审核本应发现的 bug 流入用户手中——例如移动端布局损坏、元素被裁切、控件用途不明——那么技能才是根本原因，而不仅仅是组件。在修复 bug 之前（或在同一项更改中），先更新本技能，确保门禁下次能发现这一整类问题：将缺失的检查加入下方清单，明确指出漏过的故障，并让检查足够具体，以便严格照做就能发现问题。门禁漏掉已发布的 bug，就是技能的 bug——只修组件然后继续，必然会让下一个问题也漏过去。（这就是第 2 步中存在移动端布局检查清单的原因：它源于真实的疏漏——一个 flex 行把标题挤压得每行只剩一个字，还有一个 <pre> 在手机上将示例裁切到右侧屏幕之外。）

1. 用这条标准来衡量。 先问“我可以删掉什么？”，再问“我可以添加什么？”
2. 截取桌面端和移动端（390px）的完整页面截图，从顶部到底部，每次都要截，并且实际检查。 移动端有自己的布局，不是缩窄后的桌面端；只有看过两种布局，改动才算验证完成。你添加或更改的每个组件，都必须在 390px 下滚动到完整显示，并截屏——不能只看顶部，不能说“它在首屏下方，所以我就相信没问题”。 如果没有在截图中实际看到组件的移动端渲染，就视为未验证，仅此而已。 移动端布局错误检查清单——检查每个更改组件的 390px 截图，确认没有以下问题（每一项都是曾经通过本关卡漏掉并上线的问题；如果无法从截图中排除某项，就说明检查得还不够仔细）：
   • Flex 列挤压——flex ... justify-between 行（文本在一侧，按钮或徽章在另一侧）在手机上本应堆叠却没有，导致文本被挤成每行只有 1～2 个词。修复：使用 flex-col sm:flex-row（移动端堆叠，sm+ 时横排）；不要让 flex-1 min-w-0 文本块在窄屏上与 shrink-0 按钮争空间。
   • 代码或长文本被裁切／溢出——<pre>／<code>／长内联字符串在卡片右边缘被截断（在手机上，overflow-x-auto 区块看起来是_被裁切_，而不是可滚动的）。修复：使用 whitespace-pre-wrap break-words 让文本换行，或缩短示例。在 390px 下检查每一个 <pre> 和等宽字体示例。
   • 文本贴边或溢出边缘，以及任何看起来像渲染错误的元素（从粘性栏后透出，或模糊区块看起来像加载失败）。
   • 响应式网格单元格冲突（两个断点都要检查，不能只看 390px）。 列数会随 sm: 变化的 CSS 网格（例如从 grid-cols-[1fr_auto] 变成 sm:grid-cols-[10.5rem_1fr_auto]），如果另一个子元素被固定在相同的 col-start／row-start 单元格中，就会让自动放置的子元素悄悄移到下一行——于是原本应紧跟命令的标签落到第二行并缩进到中间，看起来像“为什么它居中？”。VerbMap 就曾因此上线出错：模型说明沿用了双列移动端布局中的 col-start-2 row-start-1，却没有设置 sm:col-start-3，所以在桌面端与答案发生冲突，并把答案挤到了第二行。修复：为每个显式放置的网格子元素都设置对应宽屏网格的 sm:col-start，并在桌面端截图中也确认对齐（这个类在 390px 下不会生效——移动端网格没问题，出错的是 sm: 布局）。更改跨断点的网格模板时，重新检查每个子元素在两个断点下的放置位置。 接下来，移动端滚动检查还要留意另外两件事（这两项也都曾造成问题）：
   • 不同区块之间不能重复。 同一个命令区块、CTA 或信任说明不能出现在相邻的两个区块中。如果某个区块的移动端备用布局只是重复 Hero 或 CTA 已经显示的内容，那就是重复——应在移动端隐藏该区块，不要重复显示命令。
   • 不要让仅限桌面端的流程在移动端无以为继。 仅限桌面端的交互（Claude Code 的 claude-cli:// 深层链接）如果在手机上缩成几乎空白或只显示命令的卡片，就只是噪音——应使用 hidden sm:block 隐藏整个区块，而不是显示一个承诺手机无法使用的桌面功能的残缺卡片。（浏览器内演示本身在移动端可用；仅限桌面端的是深层链接交接。） （使用全局 playwright 和 vite preview；或使用 screenshot 技能。）
3. 从多个用户视角连贯地阅读整个页面——不要孤立地只看更改的区块。 某项改动局部上没问题，却可能破坏整页的流程或连贯性；也可能满足一种用户画像，却让另一种用户感到困惑。请在桌面端和 390px 下浏览整个网站，至少代入以下五类读者，并针对每类读者询问：“这是否清楚？流程是否合理？我会采取行动吗（运行 npx vigiles audit）？”
   • Claude Code／Codex 高级用户（有插件／技能；希望了解深入信息），
   • 初次接触的怀疑者／在手机上快速浏览的人（耐心只有 30 秒），
   • 插件／技能作者，
   • 不被说服就不会运行任何东西的资深工程师，
   • 评估是否采用的决策者／负责人。 将这项检查纳入下文的 Fable 检查流程（Fable 擅长同时代入多个视角）；文档方面对应的是 review-docs 技能。重点是在发布前发现整页和不同受众之间的连贯性问题，而不是逐个区块润色。
4. 对所有非简单改动，以冷访客身份进行 Fable 盲审——最重要的审阅者是从未听说过 vigiles、通过链接来到这里的 Claude Code／Codex 用户。把桌面端和 390px 的截图交给 Fable，并提供以下精确流程（不要只说“审查一下”）：
   • 从上到下逐个区块检查。 对每个区块记录三件事：（a）它实际传达的内容（一句话）；（b）任何奇怪、不一致、损坏、拥挤、对比度过低或看起来像渲染错误的地方（例如：令人不安的句子上方出现一整条绿色栏；模糊元素看起来像加载失败；实心进度条旁边出现 —；换行／错位的轨道；“1 hooks”）；（c）此刻脑中冒出的问题（“复制什么？粘贴到哪里？”，“哪些插件？”，“为什么是 92，却看不到任何问题？”，“它会上传我的代码库吗？”）。
   • 实际尝试交互，不要只看——输入一个代码库、点击标签、展开动词行、点击每个复制／分享按钮，并调整到手机尺寸。任何看不明白、没有明显效果或复制了无法解释内容的控件，都是缺陷。
   • 给出两项结论；如果回答“不”，必须指出具体阻碍：（1）我会实际尝试吗——运行 npx vigiles audit／init？（2）我会分享吗——把链接发给队友？分享是增长的关键，因此如果结果页没有让人觉得值得分享，那就是需要修复的问题，不是小瑕疵（参见分享性目标——ShareRow 应当_推动_用户分享，而不只是安静地提供一个按钮）。
   • 按影响从大到小排序，并为每项提供具体修复方法。 可信度问题（演示在必须显得真实的地方看起来像摆拍或已损坏）比润色优先级更高。落实被指出的问题——Fable 提出的 P0／P1“删除／修复”项不是可选项；不要只记下来就继续。将五类用户画像的检查（第 3 步）纳入同一轮审查——Fable 能同时代入多个视角——但首要视角是首次到访的冷访客。
5. 验证构建和 Prettier 检查均无问题；通过推送到 main 时运行的 pages.yml 实现确定性部署。