写完这一套之后，我最大的感受是：很多 Agent 项目跑不好，关键经常卡在任务拆分上，模型被迫一次处理太多东西。

前面几篇已经把 Idea2Site 的各个 skill 都拆开讲了。

这篇做一个总结，主要记录一下我在写这套 skill suite 时觉得比较有价值的几个工程经验。

我想从更工程的角度回头看这个项目：它到底提供了哪些经验？哪些设计可以迁移到其他 Agent 项目？

1. 第一条经验：先把模糊任务拆出问题形状

用户说：

帮我做一个个人博客。

这句话看起来像建站请求，但其实里面包含很多未决问题。这里如果不先拆，后面基本会乱。

  • 是博客、作品集、研究主页还是数字花园？
  • 视觉方向是什么？
  • 有没有参考网站？
  • 有没有用户信息？
  • 有没有文章？
  • 是否需要发布？
  • 发布到哪里？
  • 是从零生成，还是改已有站点？

Agent 直接进入实现层时，就会被迫自己脑补。脑补得好还行，脑补错了就会生成一个完全不像用户的网站。

所以 Idea2Site 前面加了：

search-blog-theme
find-style-references

先把方向从模糊变具体，再开始建站。

这个思路可以迁移到很多任务。

有些任务适合先把问题形状处理一下。

有些任务应该先做方向澄清、参考研究、约束建模。

2. 第二条经验：skill 的边界比 skill 的能力更重要

一个 skill 如果什么都能做，看起来很强，实际很危险。这个项目里我最大的一个体会就是：边界比能力更重要。

比如如果 make-personal-site 既负责选主题、又负责复刻网站、又负责导入文章、又负责发布，那它最后会变成一个很长的提示词，边界模糊。

Idea2Site 里每个 skill 都有明确边界：

search-blog-theme：主题方向
find-style-references：真实参考和设计 brief
make-personal-site：原创静态站
copy-website-style：体验语言复刻
personalize-site：身份和 metadata 替换
add-blog-posts：沿用现有文章系统导入内容
edit-site-part：局部修改
review-static-site：交付前检查
publish-static-site：发布准备和部署路径

边界清楚之后，路由才可能稳定。否则每个 skill 都想顺手多做一点，最后会变成一团。

3. 第三条经验：每个 skill 都应该有 Contract

Idea2Site 里每个 skill 都有：

Inputs
Outputs
Boundaries
Success gate
If gate fails

我觉得这是一个很好的模式，也非常适合给 Agent 用。

因为它把一个 skill 从“能力描述”变成了“工作协议”。

比如：

review-static-site
Inputs：静态站根目录
Outputs：findings / fixes / pass-fail
Boundaries：检查静态站交付质量
Success gate：没有 blocker
If gate fails：路由到最小负责 skill

这比单纯写：

这个 skill 用来检查网站。

要强很多。

Agent 既知道“干什么”，也知道“什么时候算干完”和“干不完该怎么办”。这比单纯写一堆规则要稳定很多。

4. 第四条经验：质量门禁要尽量确定性

纯靠模型检查很容易漏。尤其是路径、编码、placeholder、隐私文件这种东西，模型看一遍很难保证全覆盖。

比如：

请检查有没有路径错误。
请检查有没有乱码。
请检查有没有隐私文件。

模型可能会看一部分文件，然后说没问题。

但是路径、编码、placeholder、secret-like string、root-absolute path 这些东西，其实很多可以用脚本查。

所以 Idea2Site 加了：

review-static-site/scripts/static_site_check.py

这个脚本会检查：

  • UTF-8；
  • mojibake；
  • missing charset；
  • broken href/src/css url；
  • root-absolute local path；
  • placeholder；
  • forbidden strings；
  • privacy-sensitive files；
  • secret-like assignments；
  • local absolute paths；
  • temp artifacts；
  • inferred page types；
  • EDITING.md。

这给了整个系统一个确定性底座。这个底座很重要，因为它能帮我们把一部分“凭感觉”的检查变成程序检查。

我觉得 Agent 工程里一个很重要的原则是：

程序能检查的，就交给程序。

模型适合判断、生成、归纳、修复。

脚本适合重复、严格、无聊但关键的检查。

两者结合才稳。

5. 第五条经验：路径策略要尽早统一

静态网站路径问题看起来小，但它贯穿所有 skill。这个问题真的很容易低估。

make-personal-site 要生成正确路径。

copy-website-style 要把 framework/root route 转成静态相对路径。

personalize-site 替换头像和链接时要保持路径正确。

add-blog-posts 生成 nested article 时要计算 ../ 深度。

edit-site-part 改链接或图片时也要保持路径策略。

review-static-site 要检查路径。

publish-static-site 发布前还要确认路径在目标平台上稳定。

所以 Idea2Site 统一选择：

默认 page-relative path。
本地资源统一写相对路径。

这条规则虽然保守，但对普通静态个人站很适合。它能少掉很多发布之后才发现的 404。

因为它同时支持：

  • 直接打开 index.html；
  • 本地 HTTP；
  • 静态托管根路径；
  • GitHub Pages 子路径；
  • 任意子目录。

我觉得这类底层约定一定要早定。

否则每个 skill 都按自己的习惯写路径，最后 review 会到处报错。

6. 第六条经验：生成结果要为下一次 Agent 修改服务

EDITING.md 是这个项目里一个很小但很有用的设计。我一开始只是想给后续修改留点说明，后来发现它其实很关键。

它面向未来用户或未来 Agent。

它应该记录：

  • 目录结构；
  • 页面地图；
  • 首页每个区域在哪里；
  • 文章模板在哪里；
  • 数据放在哪里；
  • 颜色变量在哪里；
  • 导航怎么改；
  • 项目怎么加；
  • 哪些内容是 placeholder；
  • 哪些路由被省略；
  • 哪些交互被简化。

这样下一次用户要改网站时，可以直接接着已有结构继续做。

我觉得这代表了一种 Agent 友好的产物设计。

完成当前任务的同时，也要让未来任务更容易完成。

7. 第七条经验：复刻网站要复制“体验语言”，避开网站本体搬运

copy-website-style 里很强调：

复制风格和交互模式。
代码、资产、个人身份、文章和 analytics 留在原站。

这点很重要。

因为用户说“复制这个网站”，很多时候真正想要的是：

  • 它的排版节奏；
  • 它的导航方式；
  • 它的文章列表风格；
  • 它的动效感觉；
  • 它的页面组织。

需要留在原站的东西：

  • 原作者的头像；
  • 原作者的文章；
  • 原站的域名；
  • 原站的统计代码；
  • 原站的代码 bundle；
  • 原站的私有内容。

所以要先做 signature inventory，再重写一个干净版本。

这个思路也可以迁移到别的“模仿”类任务。很多时候我们真正要学的是结构和体验，源对象本身留在原处。

真正要抽象的是结构和体验，避免把源对象搬过来。

8. 第八条经验：发布是高风险动作，默认要保守

publish-static-site 里最重要的是远程安全，平台教程只是其中一部分。

它反复强调：

  • push 需要明确授权；
  • 创建仓库需要明确授权；
  • 部署需要明确授权；
  • 绑定域名需要明确授权；
  • 修改 DNS 需要明确授权；
  • 本地路径问题先修；
  • 私密文件先排查；
  • 发布前先 review。

我觉得这是所有 Agent 发布/部署类技能都应该有的原则。生成阶段可以大胆一点，发布阶段一定要保守。

因为部署是外部状态改变。

本地文件写错了还能改。

一旦 push、上传、公开，就可能造成实际影响。

所以发布层必须比生成层更谨慎。

9. 第九条经验：编排层应该追求最短可靠路径

有了 11 个 skill 之后，一个诱惑是每次都把它们全跑一遍。

但这是不对的。

用户已有站点只是加文章，就不需要重新找主题。

用户只是改一个 section，就不需要重新 personalize。

用户只是发布，就不需要重新建站。

所以 from-idea-to-personal-site 和 build-personal-site 的核心是：

根据当前输入和目标，选择最短可靠路径。

这比“完整流水线”更重要。

好的编排会知道什么时候跳过。全跑一遍看起来完整，但很多时候会浪费上下文，还可能把已有东西改坏。

10. 第十条经验：失败后要路由到最小负责模块

这个项目的 gate loop 也很值得总结。

review 失败后，先看失败类型。

要看失败类型：

路径错 -> edit-site-part / make-personal-site
身份残留 -> personalize-site
文章图片错 -> add-blog-posts
复刻不像 -> copy-website-style
方向不清 -> search-blog-theme / find-style-references
发布设置错 -> publish-static-site

这就像一个多模块系统里的故障定位。哪里坏了回哪里修，避免一出问题就重做整站。

每个 bug 都回到最小负责模块，避免全局重启。

这会减少破坏用户已有内容的概率。

11. 这个项目还可以继续怎么演进

现在 Idea2Site 已经有一套比较完整的 skill suite，但我觉得后续还可以继续扩展。

11.1 更强的视觉 QA

现在 review 里有浏览器验证要求，但如果能进一步做截图对比、移动端布局检测、文字溢出检测，会更稳。

尤其是 copy-website-style，可以做 target/local 对比评分。

11.2 更结构化的文章导入测试

add-blog-posts 支持很多富内容，但可以补更多 fixtures：

  • Obsidian wikilinks；
  • math-heavy post；
  • image-heavy post；
  • old HTML import；
  • footnotes/citations；
  • Mermaid/Excalidraw。

这样每次修改 skill 都能验证不退化。

11.3 更完整的 publishing dry-run

发布前可以加入更多 dry-run 检查：

  • deploy root size；
  • robots/sitemap；
  • OG image；
  • canonical URL；
  • GitHub Pages 子路径模拟；
  • Cloudflare Pages output directory 检查。

11.4 更好的 style reference memory

search-blog-theme 和 find-style-references 可以沉淀一些高质量风格参考库。

目的是让 Agent 对个人站审美有更多真实样本。

11.5 更强的 EDITING.md 标准化

未来可以把 EDITING.md 的结构进一步标准化，让后续 skill 更容易解析。

比如固定记录：

Page Map
Content Sources
Style Tokens
Post System
Path Rules
Known Placeholders
Validation Notes

这样下一轮 Agent 可以更快进入状态。

12. 总结

Idea2Site 的核心可以概括为更完整的 Agent 建站工程。

这个说法太泛了。

我更愿意把它理解成：

把一个模糊的个人建站请求，拆成一套可路由、可验证、可修复、可发布的 Agent Skill Suite。

它解决的是整个链路问题，单次生成只是其中一环：

方向
参考
建站
复刻
个性化
文章导入
局部编辑
质量门禁
发布
编排

每个环节都可以独立优化，每个失败都可以回到对应模块，每次交付都可以经过 review。

这就是我觉得它值得写成项目博客的原因。

它处理的是一个很实际的问题：

当用户把一个模糊愿望交给 Agent 时，
我们如何把它变成可靠的工程结果？

Idea2Site 给出的答案是：

别把方案收敛到一个更大的 prompt。
拆 skill。
写 contract。
加 gate。
做 review。
保守发布。
让产物能被下一次 Agent 继续维护。

这套经验不只适用于个人博客。

它也适用于很多 Agent 工程任务。

凡是用户目标模糊、流程多阶段、结果需要验证、失败需要修复的场景，都可以用类似方式去拆。

这也是这个项目对我最有启发的地方。