生成只是开始，后面那句“这里稍微改一下？”经常才是真正考验 Agent 的地方。

Idea2Site 里有两个非常工程化的 skill：

edit-site-part
review-static-site

它们一个负责小范围修改，一个负责质量门禁。

这两个 skill 看起来比较低调，但我觉得它们决定了这个项目的长期可用性。因为真实使用里，用户一定会反复改小地方，也一定要在发布前检查。

因为真实工作流里，用户会反复提出“生成网站”之后的新要求。

用户后面一定会说：

这个 section 太大了。
这块文字换一下。
移动端这里挤了。
hover 强度低一点。
文章页行宽太宽。
这个按钮颜色不对。
检查一下发布状态。

如果每次小改都重建整站，那就会把已有结构和内容搞乱。这种情况在 Agent 生成项目里很常见，改一个按钮，顺手把整个布局都换了。

如果每次交付都不审查，那就会把路径、隐私、乱码、断链留到发布时爆炸。

所以这两个 skill 的价值就在这里：

edit-site-part：让 Agent 学会小修小补，控制修改范围。
review-static-site：让 Agent 学会交付前检查，用证据说话。

1. edit-site-part：小范围修改的纪律

edit-site-part 的目标是：

在已有静态站里，对一个局部区域做精准修改，同时保留其他部分。

这听起来很简单，但其实非常容易做坏。因为小改最需要克制。

很多 Agent 面对一个小需求时，会忍不住大改。

用户只是说：

把首页项目卡片紧凑一点。

结果 Agent 改了整套 CSS 变量，顺手换了配色，又调整了 nav 和 footer。

用户只是说：

移动端这里别溢出。

结果 Agent 重新写了整页 layout。

这就是缺少局部编辑边界。用户要的其实只是一个小修小补，Agent 却开始重新发挥。

edit-site-part 专门为这种情况存在。

1.1 它的输入

它可以接受：

  • 现有静态站目录；
  • 目标页面；
  • 截图；
  • 本地 URL；
  • 用户自然语言描述；
  • EDITING.md；
  • 相关 HTML/CSS/JS；
  • 具体 before/after 文案或样式方向。

目标区域模糊时，它会先去定位。

多数情况下先定位再改；只有多个修改方向会产生完全不同结果时，再追问用户。

1.2 它的工作流

这个 skill 的流程很像一个谨慎的前端工程师：

先在浏览器确认目标区域
读取 EDITING.md
搜索可见文本 / class / id / data block
把浏览器区域映射到源码
做最小 coherent edit
回到同一浏览器区域验证
只报告改了哪里

其中最重要的是：

先定位，再修改。

如果直接在源码里凭感觉改，很容易改错区域。尤其是生成站里有很多重复卡片和 data block，只看文件名不够。

尤其是生成站里经常会有重复卡片、重复 section、JS data 渲染内容。你以为文本在 HTML，实际在 assets/script.js 的数组里。

所以它的 locate 策略是多层的：

  1. 搜索可见文本；
  2. 搜索 EDITING.md；
  3. 看导航和文件名；
  4. 看 semantic tags；
  5. 看 CSS selector；
  6. 看 JS event hook；
  7. 必要时用浏览器 devtools 或截图辅助。

1.3 Scope Control

edit-site-part 最核心的原则是 scope control。

它会尽量：

  • 改现有 section，避免复制一个新 section；
  • 改现有 class，避免新建一套平行样式；
  • 不动无关页面；
  • 不改全局变量，除非用户要全站变化；
  • 不引入依赖；
  • 不引入 root-absolute path；
  • 不破坏现有导航和 EDITING.md 约定。

这其实是在避免 Agent 的“过度热心”。

有时候小改比大改更难，因为它要求模型克制。

1.4 适合的任务

这个 skill 适合：

  • 改一个 section；
  • 改一张 card；
  • 调整 spacing；
  • 修移动端溢出；
  • 改一段文案；
  • 调整 hover；
  • 修主题 toggle；
  • 改 mobile nav；
  • 降低动画强度；
  • 修按钮大小；
  • 调整文章页行宽。

这些任务交给其他 skill：

  • 整站重做；
  • 重新选主题；
  • 导入一批文章；
  • 替换全站身份；
  • 发布部署；
  • 复刻新参考站。

这些应该交给别的 skill。

1.5 它的成功标准

edit-site-part 做完需要超过“代码改了”。

它的 success gate 是：

请求的局部变化在同一个浏览器区域可见。
桌面/移动端或交互检查通过。
没有引入无关 layout 或导航变化。

这句话很重要。

局部编辑必须回到原来的页面和区域看一眼。

缺少浏览器工具时，就报告源码或截图 fallback 的结果，把验证范围说清楚。

2. review-static-site：静态站质量门禁

edit-site-part 接住小改问题，review-static-site 接住交付检查问题。

它是整个 Idea2Site 里最像 QA 的 skill。

它的检查对象很明确：

检查一个静态网站输出是否真的可用、可发布、可继续维护。

我觉得这个 skill 是整套项目的保险丝。一旦没有它，很多问题会拖到发布阶段才暴露。

因为最终要交给用户或发布时，这一关都很关键。

3. review-static-site 检查什么？

它的核心检查很多，但可以分成几类。

3.1 文件和编码

检查 HTML、CSS、JS、JSON、Markdown、SVG、XML 等文本文件是否能用 UTF-8 读取。

检查有没有：

  • mojibake；
  • replacement character；
  • 缺少 <meta charset="utf-8">；
  • 浏览器看起来对但源码已经乱码的情况。

这一点对中文博客尤其重要。

如果源码已经乱码，未来 Agent 再编辑就会非常痛苦。

3.2 本地引用和路径

检查：

  • href
  • src
  • srcset
  • poster
  • action
  • data-src
  • CSS url(...)

是否指向存在的本地文件。

同时检查是否误用了 root-absolute site-local path：

/assets/...
/posts/...
/data/...
/images/...

默认这些是错误，因为它们会破坏 direct-open 和子路径部署。

这也是整个项目反复强调的路径规则。

3.3 页面类型覆盖

如果网站说自己是博客，但没有文章详情页，那就是问题。

如果 nav 指向 projects.html，但文件不存在，那也是问题。

review-static-site 会根据文件名、路径、HTML 结构和 EDITING.md 推断页面类型：

  • home；
  • about/profile；
  • list/archive；
  • article/detail；
  • projects/work；
  • links/special；
  • interactive/special。

这能帮助判断生成站是否只剩一个漂亮首页。

3.4 placeholder 和源站残留

检查是否还有：

TODO
FIXME
replace me
your name
hello@example.com
example.com
lorem ipsum
sample post
sample project
coming soon

如果是 style recreation，还可以传入 forbidden strings，比如原作者名字、原域名、原邮箱。

这一步就是防止模板残留和复制残留。

当然，有些 placeholder 是有意保留给用户替换的。这种可以作为 warning 记录，无需直接删除。

3.5 隐私和本机残留

发布前最危险的是把不该发布的东西放进 deploy root。

review-static-site 会检查：

  • .env
  • .npmrc
  • .pypirc
  • private key
  • credentials JSON
  • service-account
  • token-like assignment
  • private key block
  • 本机绝对路径
  • file:///...
  • D:\...
  • /Users/...
  • /home/...
  • 临时文件、日志、备份文件。

这些在个人站里看起来不常见，但一旦出现就是高风险。

我觉得这也是 Agent 发布类工作流必须有的检查。

因为模型可能忽略某个文件进入 deploy root 之后会被公开。

3.6 浏览器验证

文件检查只是一部分，真实浏览器里还会暴露另一批问题。

还需要用本地 HTTP 打开：

python -m http.server 8000
http://127.0.0.1:8000/

然后检查：

  • 桌面第一屏；
  • 移动端第一屏；
  • primary nav；
  • 每种页面类型；
  • theme toggle；
  • filter/search；
  • copy button；
  • mobile menu；
  • console error；
  • missing network resources；
  • 基础可访问性。

缺少浏览器工具时，就把检查范围和 fallback 方式说清楚。

可以用静态 audit 或 Playwright fallback，但要说清楚限制。

4. static_site_check.py：把一部分检查写死

review-static-site 里最工程化的是它配了一个确定性脚本：

scripts/static_site_check.py

这个脚本会输出：

  • HTML page 数量；
  • checked local refs 数量；
  • inferred page types；
  • errors；
  • warnings。

它检查的东西包括：

  • UTF-8；
  • mojibake；
  • placeholder；
  • forbidden strings；
  • secret-like assignments；
  • local absolute paths；
  • root-absolute local paths；
  • CSS url；
  • HTML link/src；
  • private publish files；
  • temp artifacts；
  • EDITING.md 是否存在。

这非常重要。因为这些东西如果全靠模型记，迟早会漏。

因为 prompt 里的“请检查路径和隐私”很容易被模型略过。

但脚本会稳定执行。

这也是我觉得 Idea2Site 已经超过 prompt 项目的原因之一。

它把一些容易明确判断的规则变成了可执行检查。

5. review-static-site 的严重级别

这个 skill 的报告按严重程度排序：

Blocker
Major
Minor

Blocker 包括：

  • 主导航坏；
  • 必要页面缺失；
  • 编码不可读；
  • 本地 asset 丢失；
  • console crash；
  • 移动端不可用；
  • root-absolute path 导致发布/直开风险。

Major 包括：

  • placeholder/source residue；
  • 交互不完整；
  • 缺少 EDITING.md；
  • 页面覆盖不完整；
  • 复刻站视觉差异严重。

Minor 包括：

  • 小响应式瑕疵；
  • 可选可访问性问题；
  • 不阻塞发布的 polish warning。

这个分级能帮助 Agent 决定下一步。

Blocker 必须修。

Major 看情况修或说明。

Minor 可以记录。

6. 两个 skill 的配合关系

edit-site-part 和 review-static-site 经常一起工作。

比如 review 发现：

移动端文章页标题溢出。

这种情况应该交给 edit-site-part 做局部 CSS 修复。

再比如 review 发现：

blog index 链接到不存在的 post。

如果是文章导入导致的，就回到 add-blog-posts。

如果只是某个导航 href 写错，可以用 edit-site-part。

所以它们的关系是：

review-static-site 发现问题
  ↓
根据问题类型路由
  ↓
edit-site-part 或其他 skill 修
  ↓
再跑受影响检查

这就是整个系统的修复闭环。

7. 一个例子

假设生成站点后 review 发现：

Errors:
  - posts/hello.html: href on line 10 missing local reference: assets/style.css
  - index.html: root-absolute local reference: /posts/hello.html

Warnings:
  - EDITING.md missing
  - index.html placeholder-like text: your name

这说明至少有几个问题：

  • 文章页 CSS 路径深度错了；
  • 首页链接用了 root-absolute；
  • 缺少 editing guide；
  • 个人信息没替换。

修复路线可能是：

路径错误 -> edit-site-part 或 make-personal-site 修
placeholder -> personalize-site
缺少 EDITING.md -> make-personal-site 或 edit-site-part 补
修完 -> review-static-site 再跑

这样比“模型看一眼说没问题”可靠很多。

8. 小结

edit-site-part 和 review-static-site 代表了 Idea2Site 里很重要的一种工程态度：

每次都按最小范围修改。
交付前都要有检查结果。

前者让 Agent 学会局部、克制、可验证地修改。

后者让 Agent 学会用确定性检查和浏览器验证来确认结果。

这两个 skill 让整个项目从“能生成”往“能维护、能交付”前进了一大步。

我觉得有了它们之后，Idea2Site 才更像一套能长期维护的建站工作流。

有了它们，它才更像一套真正能跑完闭环的 Agent 工程流程。