beautiful-html-templates 实战：用 AGENTS.md 让 Agent 选对审美的 HTML 幻灯片模板库

1. 为什么 Agent 生成的 HTML 幻灯片总是“差点意思”用 Agent 生成 HTML 幻灯片最常遇到的不是代码跑不起来而是审美随机。同一个需求问三次可能得到三套风格完全不同的 deck一次是深色科技风一次是米色杂志风一次是蓝紫渐变加圆角卡片。代码都能打开但放在一起就像三个人做的。问题出在模板选择环节。大多数模板库只是把 HTML 文件堆在文件夹里Agent 读不到“这个模板适合什么场合”“那个模板的 tone 是什么”只能靠文件名猜或者干脆自己现写一套 CSS。结果就是每次都在重新发明轮子而且轮子还不好看。beautiful-html-templates这个仓库解决的就是这一层。它不只是 34 套 HTML 幻灯片模板更关键的是带了一份AGENTS.md操作手册和index.json元数据索引。Agent 不再“随机套模板”而是按 occasion、mood、tone、formality、density 这些维度去匹配。你可以把它理解成模板库是衣柜index.json是每件衣服的标签AGENTS.md是穿搭顾问的工作流程。这篇面向的是已经在用 Agent 写 HTML 幻灯片、但被“风格漂移”折磨过的人。我会给出可复制的AGENTS.md配置骨架、TaoToken 统一 Key 的接入方式以及 Agent 选完模板后你应该做的验证动作。全程按“能跟着做”来写不堆概念。2. 前置准备模板库结构、TaoToken Key 与 API 通道2.1 先看清模板库的三层结构在写AGENTS.md之前得先知道 Agent 要读什么。beautiful-html-templates的结构大致分三层第一层是index.json这是检索入口。里面template_count显示 34每个模板带一组 metadataslug、name、tagline、mood、occasion、tone、formality、density、scheme、best_for、avoid_for、slide_count。Agent 靠这些字段做初筛而不是靠文件名。第二层是每个模板文件夹通常包含template.html和配套资源部分模板带导航 runtime比如deck-stage.js。这是 Agent 学习视觉系统的地方——字体、色板、间距、装饰语言都在这里。第三层是AGENTS.md执行手册。它规定 Agent 必须先澄清、再选候选、再出预览、最后才改造。这三层缺一层Agent 就会退化成“随便挑一个”。2.2 用 TaoToken 统一 Key 打通模型调用Agent 要读index.json、生成预览、改造模板背后都需要模型调用。如果每个环节用不同的 Key排查问题会很痛苦。我建议用 TaoToken 做统一通道一个 Key 覆盖对话、编码、Agent 场景。先到控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建后把 Key 写进环境变量不要硬编码进脚本export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api注意 API 地址是https://taotoken.net/api不带任何查询参数。如果你用的是 OpenAI 兼容的 SDK把base_url指到上面这个地址即可。模型对话入口在https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite长期跑编码和 Agent 任务的话Coding Plan 更划算入口https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewriteKey 管理页在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite提示Key 只放环境变量或密钥管理服务别提交到 Git。Agent 脚本里用os.environ读取避免泄露。2.3 把模板库拉到本地git clone https://github.com/zarazhangrui/beautiful-html-templates.git cd beautiful-html-templates ls index.json AGENTS.md确认index.json和AGENTS.md都在根目录。Agent 的工作目录就设在这里它才能同时读到元数据和模板文件。3. 可复制的 AGENTS.md 配置骨架这一节是核心。下面这份骨架你可以直接改字段用重点是三块澄清规则、候选选择规则、设计系统保护规则。3.1 澄清规则不许跳过提问Agent 最容易犯的错是“用户说要做个 deck它直接开干”。AGENTS.md里必须写死先问两个问题拿到答案才能继续。## 澄清阶段不可跳过 在读取 index.json 之前必须向用户确认 1. 这份 deck 的 occasion 是什么教学 / 研究汇报 / pitch / 品牌提案 / 读书分享 / 年度回顾 / 其他 2. 你想要什么 mood / vibe温暖 / 冷静 / 高能 / 克制 / 怀旧 / 机构感 / 其他 如果用户回答模糊追问一次给出 2-3 个具体选项帮助收敛。 禁止在未确认 occasion 和 mood 的情况下选择模板。这两问的作用是把“审美”从形容词变成可检索的字段。用户说“想要高级一点”Agent 没法匹配用户说“occasion 是年度回顾mood 是安静克制”Agent 就能去index.json里找occasion含 review、mood含 calm 的模板。3.2 候选选择规则选 3 个真正不同的## 候选选择阶段 1. 读取 index.json按 occasion 和 mood 初筛。 2. 选出 3 个候选模板要求 - 三者在 tone 或 scheme 上必须有明显差异不能是同一风格的微调。 - 每个候选都要检查 avoid_for 字段命中用户场景的直接排除。 - 优先选择 formality 和 density 与用户需求接近的。 3. 为每个候选生成一个真实的标题页预览HTML 文件 而不是只用文字描述风格。 4. 把 3 个预览路径给用户让用户选择。 5. 用户选定后才克隆完整模板并替换内容。这里的关键是“生成真实标题页预览”。文字描述“这个模板是森林绿、粉尘色”用户没感觉直接给三个能打开的 HTML 标题页对比一目了然。预览文件建议放在previews/目录命名带 slug方便回溯。3.3 设计系统保护规则审美不漂移这是整个AGENTS.md里最该抄的一段。Agent 改造模板时最常见的破坏就是“看起来差不多就行”最后把有风格的模板改成通用 PPT。## 设计系统保护规则改造阶段必须遵守 - 不要更换字体。 - 不要更换色板。 - 不要修改布局网格。 - 不要删除装饰元素。 - 不要混用不同模板的布局。 - 需要新增 slide 时必须用原模板的字体、颜色、间距、装饰语言来扩展。 - 如果内容放不下优先调整文案长度而不是压缩间距或缩小字号。这几条把“审美不漂移”写成了操作规程。Agent 没有审美判断力但它能遵守规则。你把边界写清楚它就不会越界。3.4 完整骨架示例把上面几块拼起来一份可用的AGENTS.md骨架长这样# AGENTS.md - HTML 幻灯片模板选用手册 ## 角色 你是 HTML 幻灯片生成 Agent工作目录为 beautiful-html-templates 仓库根目录。 ## 工作流 1. 澄清确认 occasion 和 mood不可跳过。 2. 检索读取 index.json按字段初筛。 3. 候选选 3 个 tone/scheme 差异明显的模板排除 avoid_for 命中的。 4. 预览为每个候选生成真实标题页 HTML路径给用户。 5. 选择等用户选定不替用户做决定。 6. 改造克隆模板替换内容遵守设计系统保护规则。 7. 验证浏览器打开最终 deck检查清单见下。 ## 设计系统保护规则 见 3.3 节内容 ## 验证清单 - [ ] 最终 deck 能在浏览器直接打开无控制台报错。 - [ ] 字体、色板、网格与所选模板一致。 - [ ] 新增 slide 的装饰语言与原模板统一。 - [ ] 没有混入其他模板的布局。 - [ ] 标题页与预览一致。这份骨架不依赖具体模型换任何 Agent 都能用。你只需要按自己的模板库字段微调。4. 接入示例让 Agent 读 index.json 并生成预览4.1 用 TaoToken 通道跑一个检索脚本下面这段 Python 演示 Agent 如何读index.json、按 occasion 和 mood 初筛、再调模型生成候选说明。Key 从环境变量读base_url 指向 TaoToken。import json import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], # https://taotoken.net/api ) with open(index.json, r, encodingutf-8) as f: index json.load(f) templates index[templates] if templates in index else index def match(occasion, mood): hits [] for t in templates: occ str(t.get(occasion, )).lower() md str(t.get(mood, )).lower() avoid str(t.get(avoid_for, )).lower() if occasion.lower() in occ and mood.lower() in md: if occasion.lower() not in avoid: hits.append(t) return hits candidates match(年度回顾, 安静) print(f初筛命中 {len(candidates)} 个模板) for c in candidates[:5]: print(c.get(slug), |, c.get(tone), |, c.get(scheme))跑之前确认index.json的顶层结构。有的版本直接是数组有的包了一层templates字段脚本里做了兼容。如果字段名不同按实际改。4.2 让模型生成候选对比说明初筛出候选后把 metadata 喂给模型让它生成一段对比说明方便你快速判断prompt f 以下是初筛出的候选模板 metadata {json.dumps(candidates[:3], ensure_asciiFalse, indent2)} 请为每个候选写一段 50 字以内的风格说明 重点说清 tone、scheme、best_for 的差异 不要评价好坏只描述特征。 resp client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: prompt}], ) print(resp.choices[0].message.content)模型名按 TaoToken 文档里支持的填。这段的作用是把 metadata 翻译成人话但最终选择权仍在用户模型只做说明不做决定。4.3 生成标题页预览预览不用完整改造模板只取标题页部分。可以写一个简单脚本把模板的template.html复制一份替换标题和副标题占位符import shutil from pathlib import Path def make_preview(slug, title, subtitle, out_dirpreviews): Path(out_dir).mkdir(exist_okTrue) src Path(slug) / template.html dst Path(out_dir) / f{slug}-preview.html html src.read_text(encodingutf-8) html html.replace({{TITLE}}, title).replace({{SUBTITLE}}, subtitle) dst.write_text(html, encodingutf-8) return str(dst) for c in candidates[:3]: path make_preview(c[slug], 2024 年度回顾, 安静克制的季度复盘) print(预览已生成, path)占位符{{TITLE}}和{{SUBTITLE}}要按模板实际用的替换。有的模板用!-- TITLE --注释有的用真实文本节点先打开一个template.html看一眼再改脚本。5. 验证请求与成功结果5.1 验证 TaoToken 通道是否通在跑 Agent 之前先用一条最小请求确认 Key 和 base_url 没问题curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复 ok}] }返回里能看到choices字段和内容就说明通道正常。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是不是写成了带路径的形式。5.2 验证 Agent 是否按 AGENTS.md 走流程跑一次完整任务观察 Agent 的行为。成功的标志是它先问了你 occasion 和 mood而不是直接生成它读了index.json并给出了 3 个候选它生成了 3 个真实预览文件而不是文字描述它等你选定后才改造模板改造后的 deck 字体、色板、网格与所选模板一致。如果 Agent 跳过了澄清直接选模板说明AGENTS.md里的“不可跳过”没被读到。检查文件是否在 Agent 的工作目录根下以及文件名大小写是否匹配。5.3 验证最终 deck浏览器打开最终 HTML按AGENTS.md里的验证清单逐条过检查项通过标准浏览器打开无控制台报错样式正常加载字体一致与所选模板template.html相同色板一致主色、辅色、背景色未偏移网格一致内容区宽度、间距与模板相同装饰语言新增 slide 的装饰元素与原模板统一无混用没有出现其他模板的布局特征标题页与预览文件一致这张表可以直接贴进AGENTS.md让 Agent 自己跑一遍再交付。6. 本篇常见错排查6.1 Agent 读不到 index.json最常见的原因是工作目录不对。Agent 如果在仓库子目录里跑index.json的相对路径就失效了。解决办法是在AGENTS.md里写死工作目录或者用绝对路径读取。另一个原因是index.json的顶层结构和你脚本假设的不一样先python -c import json; print(type(json.load(open(index.json))))看一眼是数组还是对象。6.2 预览文件样式全丢预览 HTML 打开后没有样式通常是资源路径问题。模板的 CSS 可能是相对路径引用的你把template.html复制到previews/目录后相对路径就断了。解决办法是预览文件仍放在模板目录内或者把 CSS 内联进预览。别为了省事把 CSS 路径改成绝对路径换机器就废了。6.3 Agent 改造后风格漂移这是最典型的失败。表现是字体被换成系统默认、色板被调成“更协调”的配色、装饰元素被删掉“让页面更干净”。根因是AGENTS.md的保护规则没写具体或者 Agent 没读到。把 3.3 节那几条原样抄进去并且在改造阶段开始前让 Agent 复述一遍规则能大幅降低漂移概率。6.4 候选模板风格太像如果 3 个候选看起来差不多说明初筛条件太窄。检查index.json里 occasion 和 mood 的字段值可能你的关键词只命中了一个 tone 分组。放宽 mood 的匹配或者手动指定要覆盖的 tone 范围比如“一个温暖、一个冷静、一个高能”。6.5 TaoToken 请求超时长任务里模型调用超时先确认网络能访问https://taotoken.net/api。如果只是偶发超时在脚本里加重试逻辑指数退避三次。别把超时当成 Key 失效两者排查方向不同。Key 问题看 401超时看网络和重试。6.6 新增 slide 放不下内容Agent 遇到内容溢出时容易压缩间距或缩小字号这直接违反保护规则。正确做法是让 Agent 先精简文案或者拆成两页。在AGENTS.md里明确写“优先调整文案长度而不是压缩间距或缩小字号”能避免这个问题。7. 把审美交给规则而不是运气beautiful-html-templates最值得抄的不是那 34 套模板而是它把“美”拆成了可检索的字段和可执行的流程。index.json让模板从文件夹变成设计资产AGENTS.md让 Agent 从“猜审美”变成“匹配审美”。你现在可以做的三件事把 3.4 节的AGENTS.md骨架复制到你的模板库根目录按实际字段改一遍用 4.1 节的脚本跑一次初筛确认 Agent 能读到 metadata把 5.3 节的验证清单贴进AGENTS.md让 Agent 交付前自己过一遍。模型调用统一走 TaoToken 通道Key 在控制台创建接入文档在文档页长期编码任务用 Coding Plan。通道打通后剩下的就是把规则写细。Agent 不会自己长出审美但它会严格遵守你写下的边界。边界越清楚出来的 deck 越接近你想要的样子。