这个项目看起来像是做博客，其实往细了看，里面全是 Agent 工程里的小坑。
我觉得这个项目挺有意思的，正好它也是一个很典型的 Agent workflow 问题，我们来试试把它扒开。
这个项目的名字叫 Idea2Site，仓库是 Gyschuaner/from-idea-to-personal-site。
它表面上看起来是一套个人博客 / 个人网站相关的 Agent Skills，但我觉得它真正想解决的问题要更具体一点，甚至可以说更麻烦一点：
当用户只说一句“帮我做一个个人博客”的时候，Agent 到底应该怎么把这个模糊愿望变成一个可打开、可修改、可继续导入文章、最后还能发布的网站？
这件事情第一眼看上去真的很简单，毕竟现在让大模型写一个 HTML 页面已经很常见了。随便一句 prompt：
帮我做一个个人博客，要好看一点，技术感一点。模型很快就能输出一坨 HTML/CSS。甚至如果你给它一个参考网站，它也能大概写出一个看起来有点像的页面。
但是一旦你真的想长期使用这个网站，问题马上就会暴露出来。这很正常，我一开始也预料到会这样，因为“生成一个页面”和“交付一个可维护的网站”中间差了很多环节。
1. 最开始遇到的问题
我一开始真正不满意的地方，主要有这几个。
第一，Agent 生成的网站经常看起来像模板。
大部分生成结果都有一种熟悉的味道：蓝紫渐变、玻璃卡片、大圆角、bento grid、hero 里放一堆漂亮但没什么信息量的话。它可以看，但缺少个人气质。你让它做研究主页，它像 SaaS landing page；你让它做技术博客，它像产品官网；你让它参考一个安静的个人站，它最后还是回到那套万能模板。
第二，Agent 经常停在一个首页。
但是个人网站需要超过首页。一个真实可用的个人博客至少要有：
- 首页
- 关于页
- 文章列表页
- 文章详情页
- 项目页
- 资源、链接、笔记或其他内容入口
如果产物只有一个 index.html，它更像展示 demo，缺少长期使用所需的结构。
第三，Agent 不理解“后续维护”。
用户真正想要的是：
这次先做一个站。
以后我还能继续加文章。
以后我还能替换简介。
以后我还能改某个区域。
以后我还能发布到 GitHub Pages 或 Cloudflare Pages。但是很多生成结果目录结构不清晰，缺 EDITING.md、文章模板和数据位置说明。下一次 Agent 再进来改的时候，还要重新猜这个网站是怎么组织的。
第四，发布前经常有坑。
静态网站最常见的问题集中在这些小细节：
- 本地 HTTP 能打开，但是双击
index.htmlCSS 全挂。 - 首页能打开，但是文章页里的
../assets/style.css写错。 - CSS 里
url("/assets/bg.png")在 GitHub Pages 子路径下直接 404。 - 复制参考网站时忘了清掉原作者名字、邮箱、域名、统计代码。
- 发布目录里混进
.env、本机绝对路径、临时文件。 - 中文源文件在浏览器看着正常，但源码已经乱码。
这些问题单独看都不大，但是一旦叠起来，就会让“帮我做个博客”变成一个很烦的工程活。尤其是对于 Agent 来说，最烦的地方在于它每一步看起来都做了，但最后合起来还达不到放心交付的状态。
2. 为什么先选择纯静态？
做个人博客有很多成熟方案，比如 Hugo、Jekyll、Astro、Next.js、VuePress、Quartz。
这些方案当然都很好，但我当时想做的是一套 Agent 更容易稳定执行的建站工作流，目标用户和主题框架不同。
对 Agent 来说，复杂框架会引入很多额外的不确定性：
- 依赖需要安装；
- 构建命令可能失败；
- 路由和内容集合需要理解框架约定；
- 主题配置藏在多个文件里；
- 发布前还要确认 build output；
- 一旦报错，Agent 需要花很多上下文去修工具链，注意力会从网站本身移开。
所以这个项目一开始就选择了一个很朴素的方向，把建站环境压到最简单：
纯静态 HTML / CSS / JS。
零框架。
零构建步骤。
零运行时依赖。
index.html 直接打开能看。
静态托管平台直接部署也能看。这听起来好像降低了技术含量，但我觉得恰恰相反。对于 Agent 工作流来说，纯静态是一种很有用的约束。
因为这个约束能让 Agent 把注意力放回真正重要的事情：
- 这个网站的视觉方向是否合适？
- 页面结构是否完整？
- 用户内容是否放对位置？
- 文章系统是否方便继续增加内容？
- 路径在不同环境里是否稳定？
- 发布前是否还有隐私和源码残留？
3. 这个项目的目标
我给 Idea2Site 定的目标可以概括成这句话：
把一个想法、一份笔记、一个参考网站，变成属于用户自己的、经过验证的静态个人网站。
这里有几个关键词，我一个一个拆开说。
第一个是 想法。
很多用户一开始设计稿还很模糊，通常会说：
我想做一个安静一点的技术博客。
我想做一个适合写研究笔记的个人主页。
我喜欢自然、低噪声、有一点档案感的风格。这时候先帮用户把方向找清楚，后面写出来的网站才会有个人气质。方向模糊时，Agent 很容易一股脑写出一个看起来还行的通用首页。
第二个是 笔记。
很多个人网站的真正内容来自用户已有的 Markdown、Obsidian、Word 草稿、旧博客 HTML、图片和公式。Agent 要能把这些东西自然地放进现有文章系统，避免为了导入内容重做整站。
第三个是 参考网站。
用户经常会说：
我喜欢这个网站的感觉。
帮我做一个气质相近的。这里的难点在于识别它的布局、节奏、动效、阅读体验，然后用干净的静态实现重新写出来，同时清理掉原站身份和资产。
第四个是 经过验证。
这点我觉得非常重要。一个 Agent 生成的网站，需要经过路径、编码、页面类型、隐私、浏览器和发布目录的检查，才能交付。
4. 为什么要做成一系列 Skills？
如果把整个过程塞进一个超级大的 prompt，大概会长这样：
理解用户想要什么风格
找参考网站
决定页面结构
写 HTML/CSS/JS
导入用户文章
替换用户个人信息
修移动端
检查断链
检查隐私
准备发布
写最终报告这看起来像一个完整流程，但实际上很容易崩，而且崩的时候还很难定位到底是哪一步的问题。
因为这里面每一步的判断标准都不一样。
找主题的时候，重点是审美方向和参考质量； 建站的时候，重点是结构、样式、静态路径； 导入文章的时候，重点是内容格式、图片、数学公式、链接； 审查的时候，重点是错误、风险和发布阻塞； 发布的时候，重点是平台设置、deploy root 和远程操作安全。
如果让一个 skill 同时负责所有事情，它就会变成一个又长又模糊的说明书。Agent 读完之后也许知道“应该做很多事”，但不知道当前这一步到底应该优先做什么。
所以我最后把它拆成了 11 个 skill：
search-blog-theme
find-style-references
make-personal-site
copy-website-style
personalize-site
add-blog-posts
edit-site-part
review-static-site
publish-static-site
from-idea-to-personal-site
build-personal-site这 11 个 skill 组成了一条可以组合的流水线。
其中有些负责“做事”：
make-personal-sitecopy-website-stylepersonalize-siteadd-blog-postsedit-site-part
有些负责“判断和研究”：
search-blog-themefind-style-references
有些负责“兜底和交付”：
review-static-sitepublish-static-site
还有两个负责“编排”：
from-idea-to-personal-sitebuild-personal-site
这样拆开之后，每个 skill 的边界更清楚，出问题也更容易定位。
如果用户说“风格还没想好”，那就走主题搜索； 如果用户说“参考这个 URL 做一个”，那就走风格复刻； 如果用户说“这篇 Obsidian 笔记加进去”，那就走文章导入； 如果用户说“发布到 Cloudflare Pages”，那就先审查再发布。
5. 这个项目和普通 README 的区别
普通 README 会告诉你：
这个项目有哪些功能。
怎么安装。
怎么使用。
有哪些 skill。但是如果要写成项目类博客，我更想讲的是它背后的工程思考：
- 为什么 Agent 建站要先找方向？
- 为什么视觉方向要先被研究和落地成 brief？
- 为什么静态路径是一个必须单独处理的问题？
- 为什么导入文章会超过 Markdown 转 HTML？
- 为什么发布前要把 review-static-site 做成硬门禁？
- 为什么 from-idea-to-personal-site 和 build-personal-site 都是编排 skill，但职责不一样？
这套文章后面会按这些问题展开。
我觉得 Idea2Site 最有意思的地方就在这里：它把一个很常见、很模糊、很容易糊弄过去的任务，拆成一套可路由、可验证、可修复、可发布的工程流程。
这也是它和单次网页生成最大的区别。
单次网页生成的目标是：
给我一个看起来不错的页面。Idea2Site 的目标是：
给我一个我真的可以继续使用的网站。这两个目标看起来只差一点点，但在 Agent 工程里，差的是整套架构。
