Understand-Anything 首页更新设计详解：功能卡片 3 到 6 扩展、多平台安装文案与页脚标语重构

本文基于仓库中的首页更新设计文档 2026-03-29-homepage-update-design.md，完整解读 Understand-Anything 的 Astro 首页（homepage/）是如何围绕 v1.2.0、v1.3.0、v2.0.0 三个版本的新特性做定向更新的：功能卡片区从 3 张扩展到 6 张、安装区文案从「仅 Claude Code」升级为多平台说明、页脚标语从「Claude Code 插件」改为面向所有 AI 编程助手。读完后，你将掌握这次更新的设计边界（改什么、不改什么）、每张功能卡片的文案规格，以及这些改动在 Features.astro、Install.astro、Footer.astro 三个组件中的落地方式与验证手段。

一、设计目标与变更边界

设计文档在 docs/superpowers/specs/2026-03-29-homepage-update-design.md 中开宗明义地给出了目标：

Update the Astro homepage (homepage/) to reflect features added across v1.2.0, v1.3.0, and v2.0.0 releases. The README and homepage structure/layout stay unchanged.

即：只更新首页对外传达的能力信息，使其与 v2.0.0 的实际功能对齐；README 与首页整体结构/布局保持不动。这是一次典型的「文案与内容级」更新，而非改版。

文档明确圈定了三个变更区域（Scope）：

1. Features 区：功能卡片从 3 张扩展为 6 张（2 行 x 3 列）；
2. Install 区：平台说明从 Claude Code 单平台改为多平台；
3. Footer 区：更新一行标语（tagline）。

需要修改的文件被精确限定为三个组件：

文件	改动
homepage/src/components/Features.astro	3 张卡片替换为 6 张
homepage/src/components/Install.astro	更新平台说明
homepage/src/components/Footer.astro	更新标语

同时，文档用 Out of Scope 一节排除了所有容易「顺手动到」的相邻模块：

• README.md 的更新；
• Showcase 区 / 截图；
• Nav 组件；
• Hero 区；
• 布局与全局 CSS 结构调整。

这种「文件清单 + 排除清单」的写法把一次营销页面更新压缩成了一次可审查、可回滚的窄变更。与之配套的实施计划见 2026-03-29-homepage-update-impl.md，其中进一步给出了逐任务的改法与验证步骤，后文会对照引用。

二、Features 区：从 3 张卡片到 6 张卡片

2.1 卡片规格：完整的 6 卡片设计表

更新前，首页只展示 3 张卡片（Interactive Knowledge Graph、Plain-English Summaries、Guided Tours）。设计文档给出的目标状态是 6 张卡片、排布为 2 行 3 列，完整规格如下（表内 Description 为设计文档中的原文）：

#	标题	图标	描述（设计文档原文）
1	Interactive Knowledge Graph	◈	Visualize files, functions, and dependencies as an explorable graph with hierarchical drill-down and smart layout.
2	Beyond Code Analysis	⬡	Analyze your entire project — Dockerfiles, Terraform, SQL, Markdown, and 26+ file types mapped into one unified graph.
3	Smart Filtering & Search	⊘	Filter by node type, complexity, layer, or edge category. Fuzzy and semantic search to find anything instantly.
4	Export & Share	⎙	Export your knowledge graph as high-quality PNG, SVG, or filtered JSON — ready for docs, presentations, or further analysis.
5	Dependency Path Finder	⟿	Find the shortest path between any two components. Understand how parts of your system connect at a glance.
6	Guided Tours & Onboarding	⟐	AI-generated walkthroughs that teach the codebase step by step, plus onboarding guides for new team members.

这张表值得留意两点：

• 新能力被显式点名。第 2 张卡片（Beyond Code Analysis）直接列出 Dockerfiles、Terraform、SQL、Markdown 与「26+ 文件类型」，与项目多语言解析器的实际覆盖面相呼应——从源码结构看，languages/configs 目录下确实按文件类型组织了 40 余个配置模块（如 dockerfile.ts、terraform.ts、sql.ts、markdown.ts 等），首页文案与核心包能力是对得上的。
• 每张卡片一个单字符 Unicode 图标（◈ ⬡ ⊘ ⎙ ⟿ ⟐），不引入图标字体或 SVG 资源，保持了首页零重依赖的实现风格。

2.2 Features.astro 中的实现方式

Features.astro 的结构非常克制：所有卡片数据放在 frontmatter 的 features 数组里（当前源码 第 2–33 行），模板部分仅用 features.map((f, i) => ...) 渲染（第 36–48 行）：

<section class="features" id="features">
  <div class="features-grid">
    {features.map((f, i) => (
      <div class={`feature-card reveal reveal-delay-${(i % 2) + 1}`}>
        <span class="feature-icon grad">{f.icon}</span>
        <div class="feature-body">
          <h3 class="feature-title">{f.title}</h3>
          <p class="feature-desc">{f.description}</p>
        </div>
      </div>
    ))}
  </div>
</section>

「数据数组 + map 渲染」意味着后续每次新增或改文案，只需要动 frontmatter 里的字符串，模板与样式完全不动——这正是设计文档能做到「3 个文件、纯内容级修改」的原因。

实施计划（Task 1）针对 3 变 6 的布局还提出了两个配套调整：

1. 进场动画的错峰（stagger）逻辑：全局样式里只为 reveal-delay-1/2/3 定义了三个延迟档，6 张卡片两行排布时，用取模让每一行各自错峰 1/2/3，计划中给出的写法是 reveal-delay-${(i % 3) + 1}；
2. 网格 CSS 无需改动：grid-template-columns: repeat(3, 1fr) 天然会把第 4–6 张卡片换行到第二行，移动端 1fr 断点同样成立，因此该任务明确「No CSS changes required」。

值得对照的是当前仓库源码的实际状态：网格已演进为两列三行（grid-template-columns: repeat(2, 1fr)，第 57–61 行），错峰取模也相应变为 (i % 2) + 1（第 39 行），卡片描述文案也做了更精炼的压缩（例如第 1 张卡片从设计稿的 "Visualize files, functions, and dependencies…" 变为 "Explorable graph with hierarchical drill-down, smart layout, and community clustering."）。从源码结构看，这说明该设计文档记录的是 v2.0.0 发布时点的规格，首页其后仍持续迭代；但「数据驱动卡片、只改 frontmatter」的核心实现方式一直保留。

2.3 滚动进场动画的支撑机制

卡片上的 reveal reveal-delay-N 类并不是孤立的，其机制横跨全局样式与页面脚本：

• global.css 第 158–181 行 定义了 fadeSlideUp 关键帧（上移 18px + 淡入，时长 0.7s），.reveal 初始 opacity: 0，加上 .visible 后才播放动画；三个延迟档分别是 0.1s / 0.25s / 0.4s；
• pages/index.astro 第 24–38 行 用一个 IntersectionObserver（阈值 0.15）监听所有 .reveal 元素，进入视口即添加 visible 并 unobserve，即只播一次。

因此 6 张卡片的「按行错峰浮现」效果完全由纯 CSS 延迟档 + 一段 15 行左右的原生 JS 实现，没有引入任何动画库。另外 global.css 第 200–213 行 对 prefers-reduced-motion: reduce 做了全局降级，动效可访问性也是这套方案的一部分。响应式方面，Features.astro 第 106–112 行 在 768px 断点以下把网格降为单列、间距收紧，保证移动端 6 张卡片依次排布。

三、Install 区：从「仅 Claude Code」到多平台说明

3.1 文案的 Before / After

设计文档对 Install 区的改动只有一行说明，但信息量大：

• Before: "Works with Claude Code — Anthropic's official CLI for Claude."
• After: "Works with Claude Code, Codex, OpenCode, Gemini CLI, and more."

当前仓库的 Install.astro 第 20 行 已经落地为：

<p class="install-note">Works with <strong>Claude Code</strong>, <strong>Codex</strong>, <strong>OpenCode</strong>, <strong>Gemini CLI</strong>, and more.</p>

「and more」的留白是刻意的：项目实际支持的平台远不止这四个。从根目录 README.md 的平台支持表可以印证：Cursor、VS Code + GitHub Copilot、Copilot CLI、Codex、OpenCode、Gemini CLI 等均标记为 ✅ Supported，且各有不同的接入方式（Cursor 与 VS Code Copilot 靠克隆仓库后自动发现 .cursor-plugin/plugin.json / .copilot-plugin/plugin.json，其余走 install.sh codex、install.sh opencode、install.sh gemini 等子命令）。README 还特别提示了调用前缀差异：多数平台用 /understand 斜杠命令，Codex 用 $understand——这类细节属于各平台安装章节，被 Out of Scope 的 README 边界挡在了本次首页更新之外。

3.2 Install 区的完整实现：命令块与复制按钮

除了这一行文案，Install.astro 还承载了首页的「30 秒上手」入口。其核心是一个仿终端窗口的代码块（第 4–19 行），内容为 Claude Code 插件安装三步命令：

/plugin marketplace add Egonex-AI/Understand-Anything
/plugin install understand-anything
/understand

代码块右上角有一个复制按钮，配套的内联脚本（第 24–38 行）用 navigator.clipboard.writeText 写入 #install-snippet 的文本，点击后按钮标签变为 "Copied!" 并在 2 秒后恢复——整段逻辑约 15 行原生 JS，无依赖。样式上，代码块使用全局设计 token（--surface-dark、--accent 等，见 global.css 第 66–107 行）保持与整站一致的深底浅字配色，并在 480px 以下收紧内边距与字号。

从源码结构看，Install 区被刻意做成「命令块 + 一行平台说明」的极简结构：具体平台差异全部下沉到 README 的分平台安装章节，首页只负责传达「多平台可用 + 一条可复制命令」这两个事实，这也与 Out of Scope 中不触碰 Nav/Hero/布局的边界自洽。

四、Footer 标语：定位从「Claude Code 插件」到「AI 编程助手工具」

设计文档的第三处改动是页脚标语：

• Before: "Built as a Claude Code plugin"
• After: "Built for AI coding assistants"

这一行文案与 Install 区是同一叙事的两端：v2.0.0 之后，产品的自我定位从「某个 CLI 的插件」升级为「面向 AI 编程助手生态的通用工具」，页脚用一句话把定位变化钉死。

需要说明当前仓库的演变状态：从源码结构看，现在的 Footer.astro 已经重构为 EgonexAI 品牌页脚（第 17–67 行），包含产品导航（Egonex / Understand Anything）、法务链接（Privacy、Terms）、MIT License 与 Source Code 入口以及社交图标，「Built for AI coding assistants」这一行标语本身已不在当前版本中展示。这并不矛盾——设计文档本身就是发布时点的设计快照，本文引用的正是其记录的规格；后续迭代的代码状态可以作为验证该设计「已被执行并继续演进」的证据。

五、验证方式与交付边界

实施计划为这次更新定义了明确的验收动作：

1. 构建验证：cd homepage && npx astro build，预期「Build completes with no errors」。当前 homepage/package.json 显示项目基于 Astro 6（"astro": "^6.1.6"），要求 node >= 22.12.0；
2. pnpm workspace 方式：按 homepage/README.md 的约定，从仓库根目录执行——
   • pnpm --filter homepage dev：启动本地开发服务器；
   • pnpm --filter homepage build：构建静态站点；
   • pnpm --filter homepage preview：预览构建产物；
3. 提交粒度：三个任务对应三条独立提交（feat(homepage): expand features section to 6 cards for v2.0.0、feat(homepage): update install note for multi-platform support、feat(homepage): update footer tagline for multi-platform），每个文件一次提交，便于按区域回滚与审查。

交付边界再强调一次：README、Showcase、Nav、Hero、布局与全局 CSS 结构均不在本次范围内；三个组件文件的改动之外不产生任何新文件。

六、小结

这份首页更新设计文档的示范价值在于：它把一次「页面信息升级」做成了可执行、可验证的窄变更——

• 用一张 6 行规格表完整定义 Features 区目标状态（设计文档），文案与项目核心包的多语言解析能力相互印证；
• 用 Before/After 精确描述 Install 与 Footer 各一行文案的变化，并与 README.md 的分平台支持表形成「首页概览 + 文档详情」的分工；
• 用 Out of Scope 清单锁死变更边界，配合「构建通过 + 按文件独立提交」的验收标准，使整个更新可以在不触碰布局与全局 CSS 的前提下安全落地。

结合 Features.astro、Install.astro、Footer.astro 的现状源码与 实施计划，可以完整还原「设计规格 → 逐任务实施 → 后续持续演进」这条链路，这也是理解该仓库首页各组件设计取舍的入口。