Communitygithub.com

zernie/vigiles

定义 vigiles.sh 网站 (site/) 的目的、用户体验流程和现代极简设计标准。在接触 site/ 的任何组件、英雄区、版块或营销文案之前,先阅读本文,并将所有改动与本文对照。不适用于 docs/ 或应用程序本身。

vigiles 是什么?

该 AI Agent 技能(skill)为 vigiles.sh 落地页(`site/` 目录,基于 Vite + React + Tailwind 的暗色主题网站)定义了核心目的、用户体验流程和设计标准。其首要目标是最大化实际运行 `npx vigiles audit` 命令的访客比例。该技能详细规定了网站的设计哲学:**减法设计**,即删除任何非必要的元素;**以测评为先**,通过展示真实、可共享的评级报告来吸引用户;**明确的价值主张**,将 vigiles 定位为“AI Agent 的 Lighthouse”,提供一个一键式、零配置的评分工具。该网站面向使用 Claude Code、Codex 和 Cursor 等 Agent 编码工具的开发者,并特别强调在首选浏览器内运行的演示必须展示真实的、非伪造的评测结果,以维护品牌“可测量,而非吹嘘”的信誉。该技能还涵盖了关于转化漏斗、《隐私友好型分析》、低摩擦尝试路径(如一键点击的默认仓库芯片)以及避免常见反模式(如信息过载、使用模糊的文案或伪造结果)的具体要求。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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

前端大门是 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 范围内

相关技能