← 所有文章

WORKFLOW · BLOG × AGENT

我只看两次稿,
文章是怎么上线的?

和 Agent 合写博客:九步流程与五个做法

11 月 2 日下午到 3 日凌晨,这个博客合并了 17 个 PR,有新文章、译文,也有多轮改稿。每篇文章里,我只定题、看两次稿、点合并,其余交给 Agent 和 GitHub。

· 阅读约 8 分钟 · AI 写作 · 工程实践
红笔改过的初稿、记着 AI 分析和长期偏好的修改记录、verify.py 检查清单和发布后的网页,由一条红线串起。

这样分工能行,靠五个做法:只在两处看稿、规则写进文件、一篇文章一个 PR、一条命令检查、反馈变成偏好。第 1 节先交代这个博客的技术架构,以及它为什么需要这套做法;第 2、3 节讲流程和五个做法为什么管用;后面几节讲每一步具体怎么做,其中流程和改稿卡片两处可以点开操作。

1. 纯静态博客,自由也容易走样

这个博客是一个纯静态站。页面用原生 HTML、CSS 和 JavaScript 写成,没有框架,也没有构建步骤,GitHub Pages 直接发布 main 分支的 docs 目录。导航、页脚和文章目录由几个 Python 脚本从模板和 JSON 生成,生成后的 HTML 一起提交。访问统计和加载性能交给 Cloudflare Web Analytics,评论区用 giscus,评论存在 GitHub Discussions 里。

和 WordPress、Hexo 这类博客系统比,这样做有两个好处。一是快:页面只是静态文件,统计脚本异步加载,评论区快滚到眼前才加载,图片按屏幕宽度给 WebP。优化以后,最重的一篇译文在受控网络下 DOM 就绪时间缩短到原来的约 1/15。二是自由:每篇文章可以有自己的版式和交互,这篇里能点开的流程图和改稿卡片,就是文章自带的一份 CSS 和 JS。

代价是没有现成的主题替我约束样式。每一页都由 Agent 直接改 HTML 和 CSS,它改得快,也容易改偏:配图和页面风格不搭,我说“配图感觉很不和谐”;图比版心宽出一截;为手机单独画的配图,我看了只觉得“难看的不行”,最后全部删掉,手机端直接用桌面版。正文也一样,Agent 写得通顺,但新开一个会话,上次提过的意见它就不记得了。

所以我需要一套和 Agent 协作的办法:样式和写法有文件可查,每次改动的范围清楚,改坏了有检查拦住,我说过的意见下次还算数。下面先看这套办法落到一篇文章上是什么样子。

2. 九步流程,我只在两处看稿

一篇文章从定题到上线分九步,分给三方:我、Agent 和 GitHub。

三条泳道的流程图:我在第 03 步通读正文、第 05 步看整页,最后点合并;其余步骤由 Agent 执行,GitHub 负责 CI 检查与发布。虚线回头路:正文要改回 03,图要改回 04,CI 失败或冲突修好后回 05。
图 1|一篇文章的九步。红框两处由我看稿,虚线是回头路。

我定下要讲的问题和例子,在第 03 步通读正文,在第 05 步看生成后的整页,CI 通过后点合并。找资料、改文件、画图、生成页面、跑检查、开 PR、确认上线,都由 Agent 做。

虚线是回头路。正文的问题留在第 03 步当轮改;图和排版的问题回第 04 步;CI 失败或与 main 冲突,修好后回第 05 步重新生成、检查。哪一步出问题就回哪一步,前面定好的部分不用重做。

3. 五个做法,为什么管用

和 Agent 合写,最常遇到五个麻烦:每一步都等我确认;新开的会话忘了上次的要求;几件事的改动混进同一个 PR;改坏了没人发现;同样的意见要说很多遍。下面五个做法,各自对着其中一个。

只在两处看稿

Agent 能自己核对的事,不排队等我。我在第 03 步看正文,在第 05 步看整页,看稿是为了提内容意见,不用逐句批准;已经给过的操作授权,后面继续有效。整页看过以后,PR 开出来就只等 CI。17 个 PR 里,有 8 个从创建到合并不到两分钟。

规则写进文件

我的要求不靠 Agent 记住对话。仓库根目录的 AGENTS.md 是一张表:写作读 doc-lint 和个人写作偏好,改页面读视觉规范,改生成逻辑读生成说明。每次只读这次任务需要的几份,新开的会话也按这张表读。我提过的“宽度整体都超出太多”“这个箭头很奇葩”,改完都写进了视觉规范和画图脚本,下一篇按新的规则画。

一篇文章一个 PR

每篇文章从最新的 main 建独立的 git worktree,只提交本篇的文件。早先在同一个工作区里并行改几件事,别处的导航改动混进了性能优化的 PR,只好另开 #5 把它移出去。写这篇的同时,Super-agent 那篇也在另一个工作区改稿,两篇各开各的 PR。

一条命令检查

改完以后,Agent 运行 python3 scripts/verify.py,一共 11 项检查。GitHub Actions 在每个 PR 上跑同一条命令;main 设了分支保护,检查不通过、分支落后于 main,都合不进去,管理员也不例外。写这篇时,这项检查在 GitHub 上已经跑了 40 次,全部通过。

反馈变成偏好

我纠正文字时,常常只说“不顺”“看不懂”,不解释原因。Agent 当轮改稿,记下我的原话和前后版本,再分析我真正想表达的是什么,整理成长期偏好。下一篇动笔前,它先读这份偏好,同样的意见我就不用再说一遍。

4. 每一步怎么做

从这一节开始讲具体做法。图 1 的九步,每一步由谁来做、用到哪些文件、出了问题回到哪里,都在下面。

点开每一步,看谁来做、用到什么,出了问题回到哪里。

  1. 01确定问题、例子和资料

    谁来做
    我定要讲的问题和贯穿全文的例子;Agent 找资料,核对出处与数据。
    用到
    原文、固定版本的源码、实验记录。
  2. 02建独立工作区,读规范和原稿

    谁来做
    Agent 从最新 main 建独立工作区,只读这次任务需要的指南。
    用到
    AGENTS.md 按任务指向 doc-lint、个人写作偏好和视觉规范。
    为什么
    在同一个工作区并行改几件事,曾让别的改动混进 PR。
  3. 03先写正文,我来通读

    谁来做
    Agent 写正文,我逐段读。我提意见,它当轮改稿,并记下原句、我的原话和改后版本。
    用到
    doc-lint、个人写作偏好、修改记录。
    出问题时
    正文还有问题就留在这一步继续改;定稿后才进入排版。
  4. 04排版与配图

    谁来做
    Agent 沿用博客的配色和字体画图,图放在正文列内,手机上沿用同一张图。
    用到
    视觉规范、图源和 SVG 生成脚本。
    出问题时
    “配图感觉很不和谐”“这个箭头很奇葩”这类意见,都回到这一步改图源。
  5. 05生成与验证,我看整页

    谁来做
    Agent 运行生成和检查,在桌面和手机上预览;我看整页效果。
    用到
    python3 scripts/render-site.py、python3 scripts/verify.py。
    出问题时
    正文问题回 03,图和排版问题回 04。
  6. 06只提交本篇文件,开或更新 PR

    谁来做
    Agent 逐个暂存本篇的文件,用 git diff --cached 核对,再创建 PR,或者更新已有的那一个。
    截图
    运行 node scripts/pr-screenshots.cjs,把改动页面的桌面和手机截图贴进 PR 描述,我在 PR 里就能看到页面效果。
    约定
    同一篇文章发布前的改稿集中在一个 PR;公共样式和导航另开 PR。
  7. 07CI 通过,且与 main 同步

    谁来做
    PR 创建或更新时 GitHub Actions 自动检查。main 要求检查通过、分支保持最新。
    出问题时
    修源文件,或同步 main 并保留双方的修改意图,重新生成后回 05。
    遇到过
    正文和自动计算的阅读时长挤在同一行 HTML,两边各改一处就冲突。之后把手写正文和生成的元信息分行放。
  8. 08合并 main,等 Pages 发布

    谁来做
    合并后 main 再跑一遍检查,GitHub Pages 发布静态文件,不需要构建步骤。
  9. 09在线确认,交付链接

    谁来做
    Agent 打开线上页面,确认能看到这次的新文字和新图,再交付正式链接、PR 与验证结果。
    遇到过
    我在页面上看到一段已经删掉的话。核对线上内容和发布提交后,删除其实已经生效。之后交付时都附上正式链接,不凭旧标签页判断。

标记的两步需要我审阅。

5. 一句“不顺”,Agent 记下什么

先看一个例子。写 Super-agent 那篇文章时,我指着第 01 节的开头说:“这句话非常不顺,太AI味,太读不懂了。”Agent 改了一版,我还是没用,自己写了一句:

需求是在群聊里提出的,而代码在 PR 里评审,需求后续的问题还是得回到群聊中讨论解决。

这句话随后进了正文。下一篇文章还会遇到同样的问题,所以 Agent 得从这次改稿里学到东西。只记住“而”和“还是得”两个词没用,下一篇照着套,读起来只会换一种方式不像我。它要看出我为什么这样写。

所以我纠正表达时,不用额外说“记下来”。Agent 在改稿的同一轮记下四样东西:原句和位置、我的原话、改后的版本,以及它对我真实意思的分析。最难的是最后一样:我很少解释原因,它要从原句和我改过的地方,看出我在意的是什么。

下面是写 Super-agent 文章时的六处反馈。切换卡片,可以看到每处我说了什么、谁改的、AI 怎么理解,以及最后归进了哪条偏好。

6. 六处反馈,变成五条偏好

六处反馈里,AI 把能用到下一篇的部分整理成长期偏好,写进个人写作偏好文件。每条写明从哪些反馈来、适用到哪里;只针对这一篇的要求,比如 WF-01 的称谓,留在修改记录里,不往外推。

偏好来自写作时怎么用
WP-01 先讲具体场景和动作,再解释抽象概念。WF-03、WF-06开头先接着讲例子里发生了什么,概念放到后面。
WP-02 写清分工、转折和实际需要,不把几个名词并列起来当解释。WF-03 我写的句子参照我的句子怎么交代关系,不照搬“而”“还是得”。
WP-03 实验限制用具体事实说清楚,不压成一串备注。WF-05写出次数和条数,一句说一件事。
WP-04 图注和结尾只留读者用得上的信息。WF-02、WF-04删掉重复正文、交代过程和泛泛建议的句子,留来源。
WP-05 文章写给别人读,正文不放内部记录的标签,也不列没做完的事。这篇文章的改稿说法放委婉,或只写最后的做法。

最后一条来自这篇文章本身。初稿的卡片上标着“待确认”,结尾列了“还没做完的”。我说:“写博客文章是要给别人阅读的,所以需要一些委婉的表达,或者只说未来的终局”。这句话当轮记进修改记录,也成了 WP-05。

写下一篇前,Agent 先读这份简短的偏好文件,需要例子时再沿链接读对应的记录,不用每次加载全部历史。偏好写得不对,我再纠正一次,新说法替换旧的,旧记录留着。

配图和 PR 的意见,不算文风

同一次写作里,我还提过不少和文字无关的意见。它们按问题类型放进不同的文件,不当作文风证据。

意见之后怎么做放在哪里
“配图感觉很不和谐”“宽度整体都超出太多”沿用博客配色与字体,图放在正文列内,桌面和手机都实际预览。视觉规范、文章 CSS 与图源
“这个箭头很奇葩”重叠的线段和箭头连接点分开,检查方向、节点和文字。SVG 生成脚本
本地修好了,PR 还显示冲突先核对 PR 实际用的分支和提交,再把修正推回那个分支。PR 与 CI 状态

7. 一条命令检查,剩下的靠看

改完以后,Agent 运行 python3 scripts/verify.py。本地和 CI 用同一个入口,一共 11 项只读检查,分成七组。所有检查都会跑完,任何一项失败都返回非零,CI 的 check 不通过,PR 就合不进 main。

verify.py 示意图:Agent 在本地第 05 步、GitHub Actions 在每个 PR 上运行同一条命令,共 11 项只读检查,分为生成区块(2 项)、站内链接(2 项)、学习页样式、加载预算、分享与 SEO(3 项)、评论和 verify 自测七组。全部通过可以合并;任一失败列出失败项,修好后重跑。
图 2|verify.py 的 11 项检查。本地和 CI 跑的是同一份清单。
程序能拦住只能靠人看
改了模板或目录,生成的页面没更新语气像不像我
站内链接、锚点或图片路径失效AI 对我意思的分析准不准
HTML 和图片超出加载预算页面在浏览器里排得对不对
SEO、sitemap 与配置不同步交互在手机上能不能用

右边一栏,文字按 doc-lint 逐段读,页面在桌面和手机上实际打开看。交付时 Agent 要说明做了哪些检查,不能把“静态检查通过”说成“页面没问题”。

8. 想照着做,从这五件事开始

  1. 只在两处看稿:定好看正文和看整页两个时间点,别的步骤不排队等你。
  2. 规则写进文件:在仓库根目录放一张表,写清什么任务读哪份规范。
  3. 一篇文章一个 PR:每篇从最新的 main 开独立工作区,只提交本篇的文件。
  4. 一条命令检查:本地和 CI 跑同一个入口,main 设分支保护。
  5. 反馈变成偏好:改稿时只说哪里不对,让 Agent 记原话、写分析,整理进偏好文件。

资料

评论

评论由 GitHub Discussions 提供。