落地页 — 目的、用户体验和设计标准
前端大门是 site/(使用 Vite + React + Tailwind,仅支持暗色模式),部署在
vigiles.sh。本技能是衡量每一项变更的标准。它存在是为了阻止反复出现的失败模式:
添加元素而非删除元素,这会让页面显得拥挤和模板化(类似“tilda”),而不是现代风格。
所有规则之下的核心原则:犹豫不决时,就删除。通过减法进行设计。 如果删除一个元素不会丢失任何含义,就删掉它。任何添加了框、说明文字、第二个按钮或安抚性说明的变更,除非能证明其必要性,否则都应受到质疑。
目的(网站的作用)
- 首要目标 — 最大化实际运行
npx vigiles audit的访客比例。 这是每个设计决策所服务的唯一转化指标。行动号召必须非常出色(无摩擦、显而易见、始终可触达)。如果一项变更不能帮助用户运行该命令,那么它就没有存在的价值。 - 目标受众: 已经习惯使用 Agent 编码工具(Claude Code、 Codex、Cursor)的开发者。他们持怀疑态度,并且通常在手机上快速浏览。
- 让人惊艳的东西 是 分级报告 — 直接展示结果,不要解释机制。
- 前门承诺: “适用于你的 Agent 工作流的 Lighthouse” — 一个单命令、零配置、无需上传任何内容即可为你技能/钩子/子代理/引用进行评级的工具。
- 演示帧承担四项工作 — 为所有四项工作进行设计,不要让其中一项挤占其他项。 (1) 介绍 — 一目了然地向用户科普 vigiles 是什么(分级报告本身就是推销点)。(2) 演示 — 零成本即时展示真实评级(内置的
FEATURED标签)。(3) 浏览器内运行 — 通过输入仓库名对你的公共仓库进行实时评级(GitHub 匿名 API;仅限公共仓库)。(4) 其他情况的命令复制 — 私有或本地仓库无法在浏览器内运行,因此其任务是提供一个清晰、明显的npx vigiles audit复制(命令交接,而非虚假的浏览器内运行)。由此衍生出两条关键的清晰性规则:(a) 该帧必须始终明确显示的是哪个仓库,以及它是一个预定义的示例(标签)还是你自己的输入(键入)—— 绝不可出现歧义;(b) 私有仓库路径是第一等体验,不是事后硬塞进一句话里的——应是一个清晰带标签的命令复制,并在 390px 宽度下验证通过。 不要用三行叠加的命令来重复陈述(在顶部显示$ vigiles audit <slug>的头部,下面紧跟一个已经命名了该仓库的高亮标签,这属于信息过载 —— 头部的职责是标识被评级的仓库及其来源,而不是重新打印命令)。 - 文案:具体优于聪明,且切勿植入读者本没有的疑虑。 这条规则要阻止两个常见的错误:(1) 一个读起来令人费解的聪明标题(例如“'Valid' is not 'true.'”)—— 以具体的痛点开篇(“有效的配置。有问题的 Agent。”),让下方的卡片来承载细微差别;(2) 一个防守性的常见问题解答,凸显了读者本没注意到的弱点(例如“Is it stable enough to adopt?”会将注意力引向一个吓人的版本号)—— 用怀疑者实际会问的、能建立信心的问题(例如“我的机器上会有什么数据泄露吗?”、“我可以为私有仓库评级吗?”)来替换那些植入疑虑的问题。以冷静怀疑者的身份测试每一行文案:它让我更愿意还是更不愿意运行这个命令?如果更不愿意,就删掉或重新措辞。
- 可信度:演示报告仅展示真实扫描 —— 绝不捏造结果。 品牌定位是“可测量,而非吹嘘”,因此报告中任何一个硬编码/虚假的数字都会追溯性地毒害对每个真实发现的信任。对于确实无法在此处运行的内容(模型受限的触发率),使用带有真实占位符(破折号“运行以填充”,无数字)的锁定预览是可以的 —— 它什么也没伪造。但对于工具实际能计算的内容伪造“结果”则绝对不行 —— 展示真实计算的结果,或者将其保持为报告框架外的一张诚实的解释性卡片。
- 降低尝试的门槛: 提供预填充的热门开源仓库作为一键点击的“为此评级”标签,这样访客无需输入或拥有自己的仓库就能看到真实的报告。已完成 —
DemoAudit中的FEATURED标签可以即时渲染预先构建的真实报告。 - 每个结果页面都必须携带分享功能和稳定链接。 读者无法传递给队友的评级是个死胡同,因此:(1) 每个完成的评级都是一个可复制的深度链接(
vigiles.sh/?repo=owner/repo#try),可在加载时自动运行评测 —— 此 URL 即为分享单元;(2) 任何结果都有一个一键分享功能(移动端使用原生分享面板,其他终端则复制链接 ——DemoAudit中的ShareRow);(3) 深度链接使用与输入/标签相同的仓库名,因此分享的链接、输入框键入的仓库和标签都解析到同一个代码路径。新的结果页面必须同时具备这两个功能。已完成 — 请保持其正常工作。(它所遵循的声誉规则 —— 分享是自愿的,拒绝是免费的,评级对象是工件而非用户 —— 是根目录CLAUDE.md中的gate-first-adoption规则;此处不再赘述。) - 分析转化流程: 对漏斗进行分析(命令复制、输入提交、标签尝试、重新评级、分享点击)。该网站部署在 GitHub Pages,而非 Vercel —— 因此 Vercel Analytics 不适用。对于静态托管,请使用轻量级、注重隐私、可通过脚本标签集成的分析工具:Plausible / Fathom / GoatCounter。转化漏斗已经完成 分析埋点 —
track()(site/src/lib/track.ts)会触发demo_*事件,并且在配置提供商之前是一个安全的空操作。待办: 将提供商脚本标签添加到index.html并确认事件成功上报。分析工具仅收集结果类型的数据,绝不收集输入的仓库名(私有仓库名绝不能泄露)。
方向 — 已记录的决策(保持最新;此处为方向内容)
当前网站背后的战略决策。当方向发生变化时,更新此部分 —— 它是设计文档,而不仅仅是样式指南。每一项都是经过大量迭代才达成的决策;不要默默地撤销其中任何一项。
- 默认演示必须展示一个失败案例 —— 以真实低评级开场,切忌满屏 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预览,而不是捏造的结果。 - 只提概念不解释是头号文案失败 —— 要么用通俗语言解释每个概念,要么删除它。 一位毫无准备的访客不知道“linter”、“reference”、“enforce”、“spec”或者某个分类名称是什么意思。每个概念在首次出现时都要附带一句通俗的解释,否则就删除。不要随便抛出术语(旧版 README 已经吸取过这个教训 —— “首次使用时定义工作流”;网站曾经退步过,不得不重新学习)。以一位从未听说过 vigiles 的、冷静的 Claude Code/Codex 用户的身份测试每一行文案。
- 将解释内容折叠到报告中 —— 不要添加独立的解释卡片。 报告本身就是让人惊艳的东西。浏览器无法展示的概念(模型受限的触发率,需要你本地配置的 linter 交叉引用)应作为报告内部带虚线的CLI 专属行(
report-view/src/Report.tsx中的LockedRow/CliRulesRow),而不是浮动在框架下方的卡片。如果网站在两个地方解释同一个报告内容,请删除重复的解释(这就是为什么楔形五分类条和独立的“你的规则 → 已执行”卡片被移除的原因 —— 报告本身已经包含了它们)。 - 一次只提供一个输入方式 —— 公共/私有标签,不要堆叠。 英雄区输入框曾经是输入框 + “公共 API” 说明 + 私有命令交接 + 隐私声明全部堆叠在一起(很拥挤)。现在
DemoAudit中采用了公共 | 私有标签页:公共 = 实时的输入仓库名组合框;私有 =npx vigiles audit命令复制。一次只显示一个输入方式。 - 诚实的预览,绝不模糊/伪造(取代任何更早的“将其渲染为模糊”的说明)。
模型受限的行使用破折号占位符(
recall — · precision —),而不是模糊的虚假数字。模糊看起来像渲染错误,也是一种付费墙的暗黑模式,而捏造数字则破坏了“可测量,而非吹嘘”的原则 —— 如果它紧挨着嘲讽虚假数字的文案,那就是双倍错误。如果将来需要更强的预览效果,请使用一个带有example标签的真实测量数字,而绝不能使用伪造/模糊的数字。
用户体验要求
- 命令优先。
npx vigiles audit是通用操作(适用于每个操作系统、每个终端)。它是主要的行动号召。其他所有都是次要的。 - Claude Code 深度链接 (
claude-cli://) 是仅限桌面的增强功能**,绝不能作为主要路径 —— 它在移动端 / CC Web / 未安装 CC 的桌面上会无声地失效。仅在其能正常工作的地方渲染;绝不要发布一个毫无作用的按钮。 - 对移动端要诚实。 不要有无效按钮。在桌面端独有的操作无法运行的地方,要直白地说明,并给出真正可行的操作(即命令)作为替代。
- 每屏一个主要操作。 次要操作应该是 安静的 —— 一个文本链接或一个浅色药丸按钮,绝不要使用与主要操作同样明显且宽大的全宽按钮来与其竞争。
- 工作流无关。 说“Claude Code 或 Codex”,不要把 Claude Code 作为开头 —— 它是一个实现细节,不是标题。不要过度解释内部机制。
- 低门槛 + 友好。 快速浏览者应该能在一屏之内理解它是什么以及如何试用,无需阅读长篇大论。
设计标准 — 现代与极简(防拥挤规则)
参考 Linear / Vercel / Raycast 的感觉:自信的暗色、充裕的空间、精炼的文字、每部分一个清晰的焦点。不要像塞满功能的模板。
- 每个元素都必须证明其存在的价值。 删除任何仅仅是在重复其他元素的内容(例如说明文字重复了截图内容;一句信任声明被说了两次;一个冗余的副标题)。
- 删除被其他元素已经隐含了的任何标签。 当已经有 GitHub/星标链接时,“自由 & 开源”的徽章就是多余的;在“为特定仓库评级”标题之上的“评级特定仓库”徽章则是重复。如果上下文已经告诉了读者,那么标签就是噪音。
- 每个链接/行动号召都必须是可操作的且具体**。读者必须确切知道点击后会发生什么。没有模糊或被动的次要链接(例如“你有 Claude Code 吗?……”)。如果一条次要路径不值得一个清晰、具体的操作,就删除它(或者将其移到导航栏,因为一个持久链接胜过一条无力的折叠链接)。
- 每部分一个焦点。 眼睛应该首先落在一个事物上。
- 空白+排印优于框。 不要堆叠 3 个或以上的通栏有边框的框;这种重复给人的感觉就是拥挤。倾向于使用排印层次和空间而不是边框。但空白必须是有意的 —— 也不要有近乎空白的视口空隙。
- 信任声明只说一次,用一行话。 信任文案(例如“不上传任何内容”)只出现一次,简洁明了 —— 绝不要写成三行的段落,也绝不要在每个部分重复。
- 凝聚力。 英雄区(徽章 + 标题 + 副标题 + 视觉效果)必须作为一个整体来阅读,每个部分都增加了_新的_信息。如果副标题只是在重复截图已经展示的内容,就删除或修改它。
- 颜色/强调要克制。 使用一个强调色,语义性带区颜色必须始终_有含义_(评级带)。每点内容只加粗一个短语,而不是每个子句。不要有装饰性的表情符号纸屑。
- 一致的间距比例。 不要手工调整一次性的边距,以避免破坏页面节奏。
反模式(在此犯过的错误)
- 在一个屏内堆叠:输入框 + 大按钮 + 3 行信任声明 + 分隔线 + 命令 + 说明文字 + 另一个按钮。(解决方案:保留约 3 个元素,删除其余部分。)
- 在产品截图下方的说明文字重复了产品截图的内容。
- 针对_每个问题_添加一个通知/按钮,而不是重新思考整个流程。
- 两个竞争的主要行动号召(深度链接 + 命令),没有层次结构。
- 以 CC 为中心的框架(例如“在你自己的 Claude Code 中运行……”)作为标题的信任声明。
- 在移动设备上,一个桌面端独有流程(Claude Code 的
claude-cli://深度链接)仍然可见,作为一个回退方案,但这仅仅是在另一个板块已经显示过的命令的重复 —— 导致在手机上相邻板块出现了同一个npx vigiles audit块。(解决方案:为整个桌面端独有板块添加hidden sm:block样式;英雄区 + 行动号召已经包含了此功能。)
浏览器内演示(已完成 — 需维护的不变性规则)
实时的“为任意仓库评级”演示已构建完成(位于 DemoAudit.tsx + site/src/demo/ 中):键入/粘贴一个公共仓库或点击一个精选标签,它会在客户端获取工作流文件,并运行与 CLI 相同的编译后引擎。以下规则现在是需要维护的不变性,而非未来方向。
- 每个结果都可分享(参见上面的可分享性目标)。 完成的评级带有一键分享功能和稳定的自动运行
?repo=深度链接。这是演示的硬性要求,而非锦上添花 —— 不要发布不满足此要求的结果页面。 - 在浏览器中运行,而非托管。 评测计算完全在访客的浏览器中客户端执行(通过 GitHub API 获取仓库文件,用 JS 运行纯检测器)→ 强化了“你的机器上无任何数据泄露”的印象;后端/成本为零。唯一的“托管”就是在 Vigiles/vi 上进行静态文件服务。注意:
/report路由是存在的,但仅用于接收演示结果——报告的路由在site/src/routes/中,不是浏览器内演示本身的一部分。 - 仅限确定性评级。 浏览器内演示运行从仓库文件映射到确定性评级的纯检测器(工具检测、技能目录存在性、钩子事件、基本配置有效性)。它专门且有意地不运行任何调用语言模型的检测器。模型受限行(触发率、关于文件内容的上下文风格检查)在演示报告中以虚线行形式呈现,显示为
LockedRow。这是诚实且有意为之的设计。不要尝试在浏览器中运行模型检测,也不要伪造其结果。 - 内置的
FEATURED仓库芯片渲染预先计算好并静态交付的评测结果。 在site/src/demo/reports/中更新它们:git clone该仓库 →npx vigiles audit <dir> --json→ 将results粘贴到新的.ts模块中。DemoAudit的FEATURED数组中的条目必须精确匹配它们的 slug。不要捏造或手动调整结果。 - 与
CLAUDE.md的一致性。 浏览器内演示基于与 CLI 相同的site/src/demo/deptrac/config.yaml和检测器(Error→ErrorDetector等)。更改公共检测器或类别时,必须同时更新演示的路径。如果公共 API 发生变化,在site/src/demo/deptrac/中添加一个适当的存根(stub)。 - 分享是深度链接,而非状态快照。 分享操作会复制一个自动运行的 URL,而非当前内存状态。因此,只要深度链接解析器指向正确的组件,对演示 UI 的更改就不会破坏现有分享的链接。
- 分析事件来自
track()。 不要向全局track调用添加内联脚本或独立的gtag逻辑。所有演示事件都通过site/src/lib/track.ts中单一的track门面函数进行处理。
浏览器内演示的架构(仅供上下文参考 — 不要盲目重构)
- 入口:
DialogAudit.tsx渲染了完整的浏览器内评测 UI(输入、结果、分享)。 - 评测运行器:
runAudit.ts(站点通用)启动评测过程,该过程由site/src/demo/detectors/中的 Pure JS 检测器组成,使用site/src/demo/deptrac/config.yaml中的配置。 - 静态报告:
site/src/demo/reports/包含预计算好的FEATURED仓库评测结果,格式为导出的 TypeScript 对象。 - 评测状态管理主要包含在
site/src/demo/的组件中,DialogAudit协调演示流程。
各层级的本地开发指南
- 从
site/目录运行npm run dev以启动 Vite 开发服务器。 - 检测器逻辑位于
site/src/demo/detectors/—— 在ErrorDetector.ts、ToolDetector.ts等处添加/修改检测器。 - 配置(类别、权重、规则)位于
site/src/demo/deptrac/config.yaml。修改后重新运行开发服务器。 - 精选仓库评测结果存储在
site/src/demo/reports/中的 TypeScript 模块中。要添加新的精选仓库:git clone https://github.com/<slug>cd <slug> && npx vigiles audit . --json > results.json- 将
results内容转换为 TypeScript 对象并添加到site/src/demo/reports/中的一个新文件。 - 在
DemoAudit.tsx的FEATURED数组中注册新仓库。
- 运行
npm run lint来检查代码风格问题。 - 通过
npm run build构建生产版本以进行部署。
颜色与排版
- 背景: 纯黑 (
#000000) 或非常暗的灰色 (#0a0a0a),具体取决于部分的深度。 - 文本: 中性白色渐变(
#ffffff用于标题,#e0e0e0用于正文,#888888用于次要文本)。 - 强调色: 青色/蓝绿色(例如
#00d4aa)用于链接、按钮和评级徽章。单个强调色贯穿始终。 - 评级带区颜色: A = 绿色,B = 蓝色,C = 黄色,D = 橙色,F = 红色。这些颜色具有语义含义,应挖挖用于表示状况。
- 字体: 系统字体栈(
Inter作为首选,然后是-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif)。不要引入额外的自定义字体。 - 排版比例: 标题使用
text-4xl(英雄区)、text-2xl(部分)、text-xl(子部分)。正文使用text-base。次要文本使用text-sm。避免 < 14px 的文本。 - 间距: 部分之间使用
gap-8或gap-12;部分内部使用gap-4或gap-6。使用 Tailwind 的间距比例,尽量减少自定义值。
实施风格
- 使用 Tailwind CSS 进行样式设计。 优先使用实用工具类而非自定义 CSS。仅对无法通过 Tailwind 实现的复杂效果使用内联样式或
<style>标签。 - 响应式设计: 移动优先,在移动设备上测试所有组件(宽度 < 640px)。使用
hidden和sm:block/lg:block有条件地显示/隐藏元素。从不断变化的移动视口宽度进行思考。 - 性能: 保持包体积小。演示中无忌缓存大型依赖项。延迟加载非关键代码。减少 HTTP 请求。
- 可访问性: 所有交互元素使用语义化 HTML(
<button>而非<div>)。图像提供合适的alt文本。使用表单元素的<label>。确保对比度满足 WCAG AA 标准。 - 无 JavaScript 的回退: 核心信息在没有 JavaScript 的情况下仍可查看。如果 JS 不可用,评测演示可使用简单的
<noscript>标签优雅降级,提供命令复制功能。 - 动画: 最小化且基于意图。对于页面元素,使用细粒度 CSS 过渡(不透明度、变换)。除非在列表上下文中,否则避免关键帧动画。保持动画时间在 150-300ms 范围内