WORKFLOW · BLOG × AGENT
我只看两次稿,
文章是怎么上线的?
和 Agent 合写博客:九步流程与五个做法
11 月 2 日下午到 3 日凌晨,这个博客合并了 17 个 PR,有新文章、译文,也有多轮改稿。每篇文章里,我只定题、看两次稿、点合并,其余交给 Agent 和 GitHub。
这样分工能行,靠五个做法:只在两处看稿、规则写进文件、一篇文章一个 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 步看生成后的整页,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 的九步,每一步由谁来做、用到哪些文件、出了问题回到哪里,都在下面。
-
01确定问题、例子和资料
- 谁来做
- 我定要讲的问题和贯穿全文的例子;Agent 找资料,核对出处与数据。
- 用到
- 原文、固定版本的源码、实验记录。
-
02建独立工作区,读规范和原稿
- 谁来做
- Agent 从最新 main 建独立工作区,只读这次任务需要的指南。
- 用到
AGENTS.md按任务指向 doc-lint、个人写作偏好和视觉规范。- 为什么
- 在同一个工作区并行改几件事,曾让别的改动混进 PR。
-
03先写正文,我来通读
- 谁来做
- Agent 写正文,我逐段读。我提意见,它当轮改稿,并记下原句、我的原话和改后版本。
- 用到
- doc-lint、个人写作偏好、修改记录。
- 出问题时
- 正文还有问题就留在这一步继续改;定稿后才进入排版。
-
04排版与配图
- 谁来做
- Agent 沿用博客的配色和字体画图,图放在正文列内,手机上沿用同一张图。
- 用到
- 视觉规范、图源和 SVG 生成脚本。
- 出问题时
- “配图感觉很不和谐”“这个箭头很奇葩”这类意见,都回到这一步改图源。
-
05生成与验证,我看整页
- 谁来做
- Agent 运行生成和检查,在桌面和手机上预览;我看整页效果。
- 用到
python3 scripts/render-site.py、python3 scripts/verify.py。
-
06只提交本篇文件,开或更新 PR
- 谁来做
- Agent 逐个暂存本篇的文件,用
git diff --cached核对,再创建 PR,或者更新已有的那一个。 - 截图
- 运行
node scripts/pr-screenshots.cjs,把改动页面的桌面和手机截图贴进 PR 描述,我在 PR 里就能看到页面效果。 - 约定
- 同一篇文章发布前的改稿集中在一个 PR;公共样式和导航另开 PR。
-
07CI 通过,且与 main 同步
- 谁来做
- PR 创建或更新时 GitHub Actions 自动检查。main 要求检查通过、分支保持最新。
- 出问题时
- 修源文件,或同步 main 并保留双方的修改意图,重新生成后回 05。
- 遇到过
- 正文和自动计算的阅读时长挤在同一行 HTML,两边各改一处就冲突。之后把手写正文和生成的元信息分行放。
-
08合并 main,等 Pages 发布
- 谁来做
- 合并后 main 再跑一遍检查,GitHub Pages 发布静态文件,不需要构建步骤。
-
09在线确认,交付链接
- 谁来做
- Agent 打开线上页面,确认能看到这次的新文字和新图,再交付正式链接、PR 与验证结果。
- 遇到过
- 我在页面上看到一段已经删掉的话。核对线上内容和发布提交后,删除其实已经生效。之后交付时都附上正式链接,不凭旧标签页判断。
5. 一句“不顺”,Agent 记下什么
先看一个例子。写 Super-agent 那篇文章时,我指着第 01 节的开头说:“这句话非常不顺,太AI味,太读不懂了。”Agent 改了一版,我还是没用,自己写了一句:
需求是在群聊里提出的,而代码在 PR 里评审,需求后续的问题还是得回到群聊中讨论解决。
这句话随后进了正文。下一篇文章还会遇到同样的问题,所以 Agent 得从这次改稿里学到东西。只记住“而”和“还是得”两个词没用,下一篇照着套,读起来只会换一种方式不像我。它要看出我为什么这样写。
所以我纠正表达时,不用额外说“记下来”。Agent 在改稿的同一轮记下四样东西:原句和位置、我的原话、改后的版本,以及它对我真实意思的分析。最难的是最后一样:我很少解释原因,它要从原句和我改过的地方,看出我在意的是什么。
下面是写 Super-agent 文章时的六处反馈。切换卡片,可以看到每处我说了什么、谁改的、AI 怎么理解,以及最后归进了哪条偏好。
WF-03 · 群聊、PR 与后续问题
第 01 节开头
“这句话非常不顺,太AI味,太读不懂了”
在群聊提出请求,在 PR 里评审,用 CI 检查改动,隔几周再反馈回归:入口改变,任务可以延续。让多个独立会话各自理解整段历史,既费推理,也需要人反复搬运信息。
需求在群聊里提出,代码在 PR 里评审,后续问题又回到群聊。如果每次都由一个新 Agent 接手,人就得找出旧需求和 PR,重新解释之前做了什么。
需求是在群聊里提出的,而代码在 PR 里评审,需求后续的问题还是得回到群聊中讨论解决。
AI 分析:我真实想表达的 AI 味是什么原稿把几件事压成一串并列短句,读者要自己补出它们的关系。我的版本先说清群聊和 PR 各管什么,用“而”分开两处的分工,用“还是得”交代后续仍要回群聊讨论。AI 第一次改写太早转到了新 Agent 接手的成本。
WF-01 · “作者”指的是谁
介绍双层分工及其他提到原团队的段落
“这里不要用作者了吧,直接就是 dsh 或者 superagent原作者”
作者把职责分成两层。
dsh 把职责分成两层。
AI 分析:我真实想表达的是什么泛称“作者”,读者分不清是本站作者还是原团队。
只用于这篇对原团队的称呼,没有升成长期偏好。
WF-02 · 图里的注释
重绘架构图的图注与图内注释
“然后图片里面的很多注释都没意义”
据原文图 4 重绘|Router 维持共享的高层关联,Worker 在各自上下文中执行。 来源 · 对照原图。沿用博客字体与配色;作者设计与公开实现的范围仍按正文说明。
图 4 · 双层分工(重绘)。dsh 原文 · 原图
AI 分析:我真实想表达的是什么重复正文、交代绘图过程的注释,读者用不上,只增加阅读负担。来源链接和原图入口仍有用,要留下。
归入 WP-04。
WF-04 · 结尾的投入评估
第 06 节结尾
“这句话也不需要”;后来又说“这句话也不用了”
再观察一个验收通过的任务需要人主动操作多少分钟,质量与返工如何变化,新增模型与维护开销是否值得。失败、误触发和额外审查也计入,不能只统计成功演示。botmux 已有不少接入、执行和恢复能力,投入应由真实缺口决定,具体比较见配套文章。
整段删除。
AI 分析:我真实想表达的是什么这段转向了通用的投入评估建议,打断了结尾。两次指向同一段,只算一条反馈。
归入 WP-04。
WF-05 · 实验限制
第 05 节补充实验之后
“这句话不太像是人话,你结合我之前的说话习惯,改一下”
分摊开销下降,但整批等待超过一分钟。耗时包含 CLI/Harness 路径;模板有限、大批次重复少,历史原始响应缺失,只能说明趋势,不能证明生产路由正确率。完整次数、汇总与缺失记录的限制见实验附录。
每条消息平均用的时间少了,但要等到整批结果,还是得一分钟以上。这里的耗时也包括 CLI 和 Harness 运行所花的时间。
这次用的消息模板不多。每批 128 条的测试,每个模型只跑了两次,原始返回结果也没有保存下来,没法再逐条核对。所以,这组数据可以用来看批量处理后的耗时变化,实际用起来能不能把消息分对,还得另外测试。具体数据和测试记录见实验附录。
AI 分析:我真实想表达的是什么耗时、测试方法和结果限制挤在分号和术语里。拆开说,把“大批次重复少”换成具体次数,会更好懂;“128 条、两次”来自实验附录。
归入 WP-03。
WF-06 · “续办流程”和“任务身份”
引言第二段
“这句话也看不懂”
Super-agent 想接管这段续办流程。Router 判断任务关联,Worker 执行工作,程序保存任务与讨论的关系。聊天、PR 和一次执行可以结束,任务的身份仍然保留。
Super-agent 会把这次 CSV 修复记成一项任务,记录它来自哪个群聊、对应哪个 PR、目前处理到哪一步。PR 合并后,这条任务记录仍会保留。两周后同事在原话题里追问旧版 Excel 的问题,系统还能找到之前的需求和修复记录,接着处理。
AI 分析:我真实想表达的是什么“续办流程”“任务的身份”放在开头,没有具体指向。接着讲 CSV 的例子,先说记了什么、以后怎么用,再讲角色分工。
归入 WP-01。
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。
| 程序能拦住 | 只能靠人看 |
|---|---|
| 改了模板或目录,生成的页面没更新 | 语气像不像我 |
| 站内链接、锚点或图片路径失效 | AI 对我意思的分析准不准 |
| HTML 和图片超出加载预算 | 页面在浏览器里排得对不对 |
| SEO、sitemap 与配置不同步 | 交互在手机上能不能用 |
右边一栏,文字按 doc-lint 逐段读,页面在桌面和手机上实际打开看。交付时 Agent 要说明做了哪些检查,不能把“静态检查通过”说成“页面没问题”。
8. 想照着做,从这五件事开始
- 只在两处看稿:定好看正文和看整页两个时间点,别的步骤不排队等你。
- 规则写进文件:在仓库根目录放一张表,写清什么任务读哪份规范。
- 一篇文章一个 PR:每篇从最新的 main 开独立工作区,只提交本篇的文件。
- 一条命令检查:本地和 CI 跑同一个入口,main 设分支保护。
- 反馈变成偏好:改稿时只说哪里不对,让 Agent 记原话、写分析,整理进偏好文件。
评论
评论由 GitHub Discussions 提供。