企业官网建设流程全解析

• AI 应用
• 人工智能
• AI Agent
• AI 写作
• 媒体生成

导读：本文以开源项目 html-anything（Agentic HTML 编辑器）内置的team-okrs技能模板为线索，完整拆解一个 OKR 追踪 Dashboard 模板的定义方式（SKILL.md frontmatter 与布局规格）、加载与解析链路（loader.ts / API 路由）以及真实渲染实现（example.html）。读完你既能复刻出一个可直接落地的 OKR 追踪页面，也能掌握"为一个 Skill 模板编写 SKILL.md 并接入模板市场"的完整方法论。

一、模板本质：一份写给 AI 的"页面蓝图"

在 html-anything 中，一个 Skill 模板 = 一个目录，目录内包含可选的SKILL.md、example.html、example.md。其中SKILL.md是写给本地 AI Agent 的结构化提示词——它不包含具体数据，只定义"可用版面 / 风格 / 组件库"，由 Agent 在生成 HTML 时结合用户输入内容动态套用。

team-okrs模板就是这一机制的典型样本，其核心定位在 SKILL.md 中一句话概括：

【意图】OKR 追踪页, 一眼看出进度。

目标读者是产品团队：把一个季度的目标（Objectives）、关键结果（Key Results）及其进度状态浓缩到一屏之内，让管理者无需翻页即可评估季度健康度。模板的 frontmatter 还标注了适配形态：

• category: dashboard—— 属于仪表盘类模板；
• scenario: product—— 面向产品/业务场景；
• aspect_hint: "桌面 1440"—— 提示生成时优先按 1440px 宽桌面布局设计。

二、SKILL.md 的 frontmatter 字段详解

team-okrs/SKILL.md头部是标准的 YAML 风格 frontmatter，完整字段如下：

--- name: team-okrs zh_name: "团队 OKR 追踪" en_name: "Team OKRs" emoji: "🎯" description: "季度 banner + 3 个目标 + KR 进度条 + owner + 状态 pill" category: dashboard scenario: product aspect_hint: "桌面 1440" tags: ["okr", "objectives", "key results", "目标"] ---

这些字段并非仅供人类阅读，而是被 loader.ts 的parseFrontmatter逐一解析，并映射为模板注册表元数据。结合fmToMeta（loader.ts#L160-L194）可以看清每个字段的实际作用与默认值：

注意parseFrontmatter是零依赖实现，仅支持扁平结构：字符串（可带引号）、整数、以及tags: ["a", "b"]这种单行数组字面量。若数组值引号包裹，解析时会自动剥离引号并过滤空项。

三、模板正文：四段式布局规格

SKILL.md的正文部分（---之后）是模板的灵魂，它用简洁的层级列表定义了 OKR 追踪页必须包含的四大布局要素：

【模板: Team OKRs】 【意图】OKR 追踪页, 一眼看出进度。 【布局】 - Quarter banner (Q? + 主题) - 3 个 objectives 列, 每个含一组 KR - 每个 KR 一条进度条 + 数值 + owner avatar + 状态 pill - 右侧 'this quarter at a glance' 摘要

逐条展开：

1. Quarter banner：页面顶部的季度横幅，必须包含季度编号（Q4）、年度（FY25）与季度主题，用于第一时间建立时间上下文。
2. 3 个 objectives 列：核心信息区，每一列是一个 Objective，内部承载一组 Key Results（KR）。
3. KR 行：每条 KR 需要同时呈现四种信息——进度条（可视化完成度）、数值（百分比或 x of y）、owner avatar（负责人头像）、状态 pill（On track / At risk / Off track 三态标签）。
4. 右侧摘要栏：this quarter at a glance侧边栏，聚合全局统计（进行中的目标数、绿色 KR 数、剩余天数、风险评级），以及 Top movers 与 Blockers 等管理视角信息。

这套规格刻意保持"组件级"而非"像素级"，正是为了给 Agent 留出排版自由度：数字（如"3 个 objectives"）是短示例下的参考下限，而非硬性上限——这一点在 shared.ts 的全局设计指令中被反复强调："输出数量完全由用户内容的实际长度和信息结构决定，不许总结、压缩、丢弃信息"。

四、落地实现：example.html 逐段拆解

规格写好后，模板还需要一个预渲染示例。team-okrs/example.html（example.html）就是一个可直接双击打开、约 200 行的自包含单文件示例，它把上面的四段式规格翻译成了真实界面。下面按结构拆解。

4.1 设计令牌（CSS 变量）

:root中定义了完整的色彩令牌与字体栈，这是"1 个主色 + 2 个中性色 + 至多 1 个强调色"设计准则的实践：

:root { --bg: #f5f6f9; --paper: #ffffff; --ink: #161924; --muted: #5d6678; --line: #e3e6ee; --accent: #2c4ee8; --accent-soft: #eaeefe; --positive: #1f8a5a; --warn: #b58522; --danger: #b13b3b; --display: 'Inter', -apple-system, ...; --body: -apple-system, ...; --mono: ui-monospace, SFMono-Regular, Menlo, monospace; }

三态语义色--positive/--warn/--danger直接对应状态 pill 的三档（on-track / at-risk / off-track），整个页面的健康度编码由此统一。

4.2 页面骨架：主区 + 侧栏

.app { display: grid; grid-template-columns: 1fr 320px; min-height: 100vh; }

两列网格：左侧 1fr 为主内容区（季度 banner + objectives），右侧固定 320px 为摘要栏。同时在@media (max-width: 1080px)中断点下退化为单列（侧栏移至下方、KR 行改为单列），保证窄屏可用。

4.3 季度横幅

<div class="quarter-banner"> <div> <h1>Q4 FY25 · Northwind</h1> <div class="meta">14 October → 31 December 2025 · Owner Devon Park · 3 objectives · 9 key results</div> </div> <div class="qb-progress"> <div class="num">42%</div> <div class="label">Quarter through · 47% time elapsed</div> </div> </div>

深色渐变横幅承载季度身份信息，右侧用大字号（56px）展示"季度已过百分比"与"时间已消耗百分比"的对照——这是 OKR 页面最关键的节奏信号之一（时间过半而进度未过半，往往意味着风险）。

4.4 Objective 卡片与三态 Pill

每个 Objective 渲染为一张卡片，头部含目标序号、目标名称、owner（头像 + 姓名）与状态 pill：

.pill { display: inline-flex; align-items: center; gap: 6px; padding: 5px 12px; border-radius: 999px; font-family: var(--mono); ... } .pill.on-track { background: rgba(31,138,90,0.12); color: var(--positive); } .pill.at-risk { background: rgba(181,133,34,0.12); color: var(--warn); } .pill.off-track{ background: rgba(177,59,59,0.12); color: var(--danger); }

pill 使用同色系 12% 透明底 + 语义色文字，配合 6px 圆点（background: currentColor）形成"颜色即状态"的强编码，色弱用户也能通过文字（On track / At risk / Off track）区分。

4.5 KR 行：进度条 + 数值 + 负责人

.kr { display: grid; grid-template-columns: 1fr 200px 110px; gap: 18px; padding: 16px 26px; border-top: 1px solid var(--line); align-items: center; } .kr-fill { background: linear-gradient(90deg, var(--accent), #6e85ff); } .kr-fill.warn { background: linear-gradient(90deg, var(--warn), #f1b13a); } .kr-fill.danger { background: linear-gradient(90deg, var(--danger), #d8625e); }

每条 KR 是三列网格：KR 名称（strong + mono 小字备注）、8px 圆角进度条、右侧百分比/计数。进度条颜色随健康度切换三档渐变，与 pill 语义严格对应。示例中既有百分比型 KR（"Reach SOC 2 Type II readiness · 88%"），也有计数型 KR（"Close 3 of 3 stalled enterprise deals · 2 of 3"），说明数值形态应该由数据本身决定，模板不锁死格式。

4.6 右侧摘要栏

侧栏聚合了三类管理信息：

• This quarter at a glance：Objectives on track 1 of 3、Key results green 4 of 9、Days remaining 53 of 78、Risk score Medium——全局状态一屏可读；
• Top movers (this week)：本周变化最大的三条 KR（+33%/+9 pp/−2.4%），用增量符号着色；
• Blockers：风险卡片，红底红边列出离线项及其决策诉求（"Decision needed Friday"）。

摘要栏让"一眼看出进度"从口号变成了可操作的管理动作：哪里在涨、哪里在跌、哪里需要拍板。

五、加载链路：SKILL.md 如何变成 UI 列表

理解了模板内容之后，还需要知道它在项目里如何被读取、序列化并最终展示在模板选择器中。完整链路如下：

5.1 磁盘加载（服务端）

loader.ts 的loadSkillFromDir负责从src/lib/templates/skills/<id>/目录读取SKILL.md，并同步探测同目录下的example.md/example.html：

const raw = safeRead(path.join(dir, "SKILL.md")); const { fm, body } = parseFrontmatter(raw); const exampleMd = safeRead(path.join(dir, "example.md")); const exampleHtml = safeRead(path.join(dir, "example.html")); const meta = fmToMeta(id, fm, !!exampleHtml, !!exampleMd); return { ...meta, body, exampleMd, exampleHtml };

listSkills()则遍历整个 skills 目录（配合 id 合法性校验isValidBundledId），并把用户通过 marketplace 安装的技能（来自~/.html-anything/skills/，命名空间前缀pkg-<owner>__<repo>--<id>）合并进同一注册表，详见 registry.ts。开发环境下metaCache被绕过（isDev判断），因此新增一个 skill 目录无需重启next dev即可被扫描到；生产环境则缓存元数据，安装/卸载后调用invalidateSkillsCache()失效。

5.2 API 暴露

• GET /api/templates：返回全部模板元数据SkillMeta[]，响应头Cache-Control: public, max-age=5用于短时去重；
• GET /api/templates/:id/example：返回单个 skill 的示例 JSON 包（content+html+ 元数据），让模板选择器点 "Preview" 时一次请求拿全内容与 HTML，避免两次往返。

5.3 客户端消费

客户端 hookuseTemplates()维护模块级缓存 + 进行中请求去重（in-flight promise dedupe），并用generation单调计数器解决"慢请求晚到覆盖新列表"的竞态；refreshTemplates()在安装/卸载后立即刷新列表，让模板选择器无需整页刷新即可切换新注册表。

5.4 CLI 侧的同构实现

命令行工具cli也内置了一份几乎同构的加载器（skills-loader.ts），差异在于接受skillsDir参数而非硬编码process.cwd()。这说明SKILL.md 的 frontmatter 格式是整个项目的共享协议：Web 端与 CLI 端共用同一套解析语义。

六、提示词组装：SKILL.md 正文如何参与生成

当用户选中team-okrs模板并提交内容后，模板正文并不会单独进入模型，而是与全局设计指令、用户内容拼接成最终提示词。核心实现在 shared.ts：

export function assemblePrompt(opts: { body: string; content: string; format: string }): string { return `${SHARED_DESIGN_DIRECTIVES} ${opts.body.trim()} 【输入格式】: ${opts.format} 【用户内容】: ${opts.content} `; }

三段式结构：

1. SHARED_DESIGN_DIRECTIVES（shared.ts#L6-L38）：所有技能共享的硬性规则——输出自包含单文件 HTML、禁止调用文件系统工具、Tailwind v3 Play + Google Fonts 经 CDN 引入、排版（中文Noto Sans SC/ 英文Inter）、8px 基线网格、对比度 ≥ 4.5 等。其中"内容驱动数量"是最优先指令：模板只提供版式池，产出多少 section/卡片完全由用户内容长度决定。
2. 模板正文：即team-okrs的四段式布局规格，在此刻被注入，作为版式约束。
3. 用户内容 + 输入格式：真实数据尾巴，确保"必须使用用户提供的真实数据，不许 lorem ipsum"。

所以team-okrs的"3 个 objectives"会被正确理解为最低参考而非硬上限：如果用户提交了 5 个目标的数据，Agent 必须输出 5 个 Objective 卡片，否则即视为"严重错误"（见 shared.ts#L12 对 12k 字符只输出 4-6 页的批评）。

七、场景体系与新增模板指南

team-okrs的scenario: product对应 scenarios.ts 中 12 个规范场景键之一（marketing / engineering / operations / product / design / finance / sales / hr / personal / education / creator / video）。场景键的作用：

• 驱动模板选择器顶部的筛选 chips（客户端与校验端共用该常量模块）；
• SCENARIO_ORDER控制场景排序；
• 未知场景键不会导致加载失败，只会落入末尾的 "other" 桶并显示原始 id（scenarios.ts#L51-L53）。

若要在本项目贡献一个类似team-okrs的新模板，最小步骤只需三步（无需改动任何 TS 代码）：

1. 新建目录next/src/lib/templates/skills/<your-skill>/；
2. 写入SKILL.md，frontmatter 参考本文第二节字段表，正文按"【意图】+【布局】"结构描述版面要素；
3. （可选）同目录添加example.html（预渲染预览）与example.md（示例输入内容）——存在与否会被listSkills自动探测，并显示在模板选择器的 Preview 中。

八、小结：一份模板的完整价值闭环

回顾team-okrs这个 16 行的SKILL.md，它在 html-anything 中串联起了一条完整链路：

• 定义：frontmatter 元数据（分类、场景、标签、宽高比）让模板可检索、可筛选、可排序；
• 规格：四段式布局指令定义了 OKR 追踪页的信息架构（banner → objectives → KR 行 → 侧栏摘要）；
• 示例：example.html给出了可直接运行的状态编码方案（三态色、渐变进度条、pill、mover/blocker 聚合）；
• 装载：loader.ts 零依赖解析 + API 路由 + 客户端 hook 把它变成模板选择器里的一个可预览卡片；
• 执行：assemblePrompt把正文注入全局设计指令与用户数据，让 Agent 产出"内容驱动、数据真实、单文件可双击打开"的成品页面。

对于想要快速搭建团队 OKR 追踪页的开发者，最直接的做法是把 example.html 作为起点：替换季度横幅的文案与日期、按三态语义维护各 KR 的进度与 pill 状态、更新侧栏的统计与 blocker 文案，一个生产可用的 OKR 追踪页即告完成。

• AI 应用
• 人工智能
• AI Agent
• AI 写作
• 媒体生成