时间都去哪儿了？

我每周最烦的时间点，基本就是写周报。

前阵子我粗略算了一下，过去 3 个月我光是手写 prompt、翻记录、拼周报，差不多花了 12 个小时。平均下来，每周 50 分钟左右。这里面写字的时间其实不多，大头都花在找材料上：翻 GitHub，看这周提交了什么；翻 Jira，看哪些 ticket 还在自己手里；最后再把这些碎片凑成一段还算体面的文字。

有一次快写完的时候，同事突然问我："你这周 GitHub 上那个 PR 进度怎么样了？"

我才发现，那个 PR 被我漏掉了。

不是没做，也不是故意不写。就是翻到一半已经快到 deadline 了，脑子开始只想赶紧交差，于是漏了。结果周报看起来像是我这周只做了一个小需求。

这件事挺小，但让我开始认真想：周报最累的地方，可能不是"写"，而是每周都要重新把自己做过的事捞一遍。

什么是 loop？

简单说，loop 就是让 AI 不只回答一次，而是按一套流程反复跑，直到条件满足才停。

以前的做法是：我写 prompt，AI 给结果，然后结束。Loop Engineering 更像是：我先设计一套流程，让它定时拉数据、生成草稿、检查结果；如果没过检查，就停下来留下原因。

所以它和 cron 不太一样。

cron 只是到点执行脚本。它不关心脚本结果好不好，也不会自己判断下一步该做什么。loop 里面多了一层判断：现在拿到了什么数据，够不够写，哪里缺了，能不能继续。

这层判断很麻烦。也正是这层判断，让它不只是"定时跑一下 AI"。

你的任务适合做成 loop 吗？

不是所有重复任务都值得上 loop。我现在会先看四件事：

1. 这件事是不是每周都会发生？
2. 跑完之后，能不能看出来成功还是失败？
3. 中途失败后，能不能从失败点接着来？
4. 省下来的时间，值不值得维护这套流程？

如果这四条里有两三条都说不清，先别急着自动化。写个一次性脚本，或者继续手动做，可能更省心。

周报这个场景比较适合。它每周发生，输入数据也比较清楚：GitHub、Jira、日历、文档。问题是这些数据分散在好几个地方，人每周手动捞一遍，很容易漏。

5 个组件怎么落到周报场景

Addy 的文章里提到 5 个组件，再加一个贯穿全程的 Memory：Automations、Worktrees、Skills、Plugins、Sub-agents，以及 Memory。

我第一次看这套东西时也有点头大。名词很多，但放到周报里，其实可以拆得很朴素：什么时候跑、按什么模板写、从哪里拿数据、在哪里隔离运行、谁来检查、怎么记录上次失败。

1 Automations：每周五 18:00 跑一次

Automation 就是闹钟。不过这里别手写一个看起来像配置文件的 YAML，然后期待 Codex 自动识别。

更稳的做法是在 Codex 桌面 App 里打开 Settings -> Automations -> New automation，填这几项：

• Name：weekly-report-loop
• Schedule：每周五 18:00
• Workspace / CWD：周报工作区，比如 ~/weekly-report-loop
• Execution environment：第一版先选 local
• Prompt：让 Codex 读取 company-weekly-report skill，按 data-fetcher、drafter、reviewer 三步生成草稿

如果你更习惯直接对 Codex 说话，也可以在当前项目里发这一句：

请创建一个本地 automation：每周五 18:00 在 ~/weekly-report-loop 运行。任务是读取 company-weekly-report skill，汇总本周 GitHub 和 Jira 进展，生成 raw/week-{W}.json、draft/week-{W}.md、review/verdict-{W}.json 和 state/progress.md。review 不通过时不要发布，只把失败原因写进 state/progress.md。

创建之后，可以在 ~/.codex/automations/ 下面看到对应的 automation.toml。这个文件是 Codex App 生成的，我一般不手改。要改时间、工作区或 prompt，回到 Settings 里改。

2 Skills：把周报要求写清楚

Skill 是这套流程的说明书。路径可以放在 ~/.codex/skills/company-weekly-report/SKILL.md。

一个最小版本大概长这样：

---
name: company-weekly-report
description: Generate a weekly company report draft from GitHub/Jira evidence, with source citations and a reviewer gate.
---

# 目的
按公司周报模板，把本周工作汇总成文档，标注完成度与风险。

# 模板位置
- references/template.md # 公司模板（10 段固定结构）

# 数据源（用 MCP，不要让 Agent 自己爬网页）
- GitHub connector / MCP：本周 commits、PR、review、issue
- Jira connector / MCP：本周更新过、由我负责或参与的 tickets
- 如果 Jira 没接好，不要猜；写入 `[数据缺失，需补充：Jira]`

# 产物路径
- raw/week-{W}.json：原始证据，只放结构化数据和来源链接
- draft/week-{W}.md：周报草稿
- review/verdict-{W}.json：reviewer 的结论，必须包含 pass 和 reasons
- state/progress.md：每次运行追加一段状态

# 写作约束
- 每条 bullet 必须有数据源引用 [src:github:abc123]
- 数字必须从 connector / MCP 返回，禁止 Agent 编造
- 不要写"下周计划"超过 5 条

# Gate
- reviewer 必须检查全文每一段是否有来源
- review/verdict-{W}.json 里的 pass 不是 true，就不要发布

这里最值得花时间写的是两块：数据源和写作约束。周报最怕的不是写得不漂亮，而是 AI 很自然地补一句看似合理的话。尤其是数字，没来源就别写。

3 Plugins：先把数据接上

Plugins 或 MCP 连接器，负责让 Codex 读到外部数据。周报里至少要接 GitHub。如果你们公司有 Jira/Atlassian connector，或者内部 MCP，再把 Jira 接上。

# 先看当前 Codex 里有哪些插件
codex plugin list

# 当前 Codex CLI 的安装命令是 add，不是 install
codex plugin add github@openai-curated

如果 Jira 不是插件市场里的现成 connector，而是公司内部 MCP，可以用这种方式接：

codex mcp add company-jira --url https://your-company.example.com/mcp

装完先确认一下：

codex plugin list
codex mcp list

只读周报，不应该给写权限。能读就够了。repo:write 这种权限，除非你真的要让它开 PR，否则别给。

4 Worktrees：第一版不用急

Worktrees 是隔离运行环境。要是这个 loop 会改代码、开 PR、跑测试，那最好给每个 agent 单独的 worktree。

但周报第一版只是读数据、写草稿，用 local 就够了。等它稳定跑两三周，再考虑改成 worktree 环境。先跑通，比一上来把架构搭满更重要。

5 Sub-agents：把三步写进 prompt

这里不用急着发明一套流水线配置。第一版最容易跑通的办法，是在 automation prompt 里把三步写清楚：

请按三步执行：

1. data-fetcher：读取本周 GitHub commits / PR / review；如果 Jira connector 可用，也读取本周相关 tickets。把原始结果写入 raw/week-{W}.json。任何 connector 报错都必须写入 state/fetch-error-{W}.md，并停止后续步骤。
2. drafter：只根据 raw/week-{W}.json 和 references/template.md 写 draft/week-{W}.md。没有数据的地方写 "[数据缺失，需补充]"，不要补编。
3. reviewer：检查 draft/week-{W}.md 是否每段都有来源、是否出现无来源数字、是否把空数据写成了"无进展"。把结果写入 review/verdict-{W}.json，格式为 {"pass": true/false, "reasons": [...]}。

只有 reviewer pass 为 true，才在 state/progress.md 里记录 "ready_to_publish"。

这不够精致，但能跑。第一版 loop 要的不是漂亮，而是能看见它在哪一步失败。

6 Memory：把上次失败记下来

Memory 先别想复杂。第一版就放一个 state/progress.md。

# Weekly Report Loop State

## Last Run
- week: 2026-W23
- raw_path: raw/week-2026-W23.json
- draft_path: draft/week-2026-W23.md
- verdict_path: review/verdict-2026-W23.json
- gate_passed: true

## Backoff
- consecutive_failures: 0
- next_attempt_at: 2026-06-12T18:00:00+08:00

## Failures Log
- 2026-W19: gate_failed(reviewer caught hallucinated ticket count)

不要默认 App 会帮你维护这个文件。把"每次运行必须追加 state/progress.md"写进 automation prompt 和 SKILL.md。下一次运行时，先读上一次为什么失败，再决定要不要继续。

我踩过的 3 个坑

跑起来之后，我遇到过几个很烦的问题。不是大事故，但足够让人不敢直接全自动发布。

踩坑①：安静失败（Quiet Failure）

有一次周五 18:00 触发后，Jira token 过期了。data-fetcher 没有明确报错，只返回了空数据。

drafter 看见空 raw，就写了一句"本周无 Jira 进展"。reviewer 只检查引用是否一致，所以也过了。周报发出去以后，周一才发现少了一大块。

后来我加了三条规则：

1. data-fetcher 失败时必须写 state/fetch-error.md，不写就当整个 loop 失败。
2. connector 报错或返回结构异常时，直接停止，不进入 drafter。
3. 如果本周 commits 和 tickets 都是 0，reviewer 要直接 fail，除非 raw 里有明确的休假或停工证据。

踩坑②：周报幻觉（Weekly Report Hallucination）

另一次，模板里有"用户增长"段落，但 GitHub 返回的只是后端 commits。drafter 顺手写了一句"本周 DAU 上升 12%"。

这数字完全没来源。

reviewer 当时没拦住，因为它只检查了有引用的段落。没有引用的段落，反而被跳过去了。

后来我把规则改成：

1. 没有原始数据的段落，写 [数据缺失，需补充]。
2. reviewer 扫全文，不是只扫有引用的行。
3. DAU、MAU、转化率这类业务指标，只能来自数据看板 MCP，不能从 commit 或 PR 里推断。

踩坑③：Token 失控（Token Runaway）

还有一次，reviewer fail 了。automation 重试时，drafter 把上周 draft 当作上下文示例塞了进去。重试几次后，token 消耗开始变得离谱。

这类问题不一定马上炸，但它会让你越来越不敢开自动化。

我现在的做法是：

1. prompt 里写清楚，只读取本周 raw、模板和最近一次 progress。
2. drafter 不带历史 draft 作为示例。
3. reviewer 失败后，先看规则哪里有问题，不要马上重跑整条链路。

动手试试

如果你想做一个自己的周报 loop，可以先按这个顺序来。别一上来追求无人值守。

Step 1：先做一次 4 条件测试

把你每周都要做的任务，放进前面的 4 个问题里过一遍。答不上来，就先别做 loop。

Step 2：准备周报工作区

建一个专门目录，比如 ~/weekly-report-loop，里面放这几个子目录：

references/
raw/
draft/
review/
state/

公司周报模板放进 references/template.md。

Step 3：写 SKILL.md

照着上面的骨架写。别急着写得很完整，先把数据源、产物路径和禁止编造写清楚。

Step 4：安装并确认连接器

在 Codex 桌面 App 的 Settings -> Plugins 里安装 GitHub。如果公司有 Jira/Atlassian connector，也一起装。

然后用 CLI 确认一下：

codex plugin list
codex mcp list

看到 GitHub/Jira 是 enabled，再做下一步。

Step 5：创建 automation，第一周盯着跑

在 Settings -> Automations 创建每周五 18:00 的本地 automation。

第一周不要完全放手。手动触发一次，看这三个文件：

• raw/week-{W}.json 不是空的
• draft/week-{W}.md 没有无来源数字
• review/verdict-{W}.json 的 pass 是 true

这些都没问题，第二周再让它自己跑。

我现在对周报自动化的看法很简单：别急着让 AI 替你发布。先让它学会留下证据，学会承认自己没拿到数据。它能做到这一步，已经省很多事了。