缓存

你每天早上运行同一个代码审计。大多数文件自昨天以来没变 —— auth 模块一样、配置加载器一样，只有一个 PR 动了计费服务。然而每天早上你都要为重新分析全部内容付费。

taskflow 的缓存正是为了解决这个。它有两层在不同时间尺度上工作的机制，合起来确保你只为输入真正变化的工作付费。

两层一览

运行内续跑是免费的

你运行 flow 的那一刻，运行内续跑就已经开了。你不需要配置任何东西。

它做的是：如果一个阶段的 inputHash 匹配同一次运行中先前 done 的阶段，该阶段被跳过，复用其先前输出。阶段被标记为 cacheHit: "run-only"，且其先前的 usage 被保留，这样运行摘要可以告诉你这次复用原本会花费多少。

这正是 resume 之所以廉价的原因。中止一个进行中的运行，修一个拼写错误，再重新运行 —— 只有输入真正变化的阶段重新执行。其余的都是一次哈希比较。

{
  "name": "audit",
  "phases": [
    {
      "id": "scan",
      "type": "agent",
      "task": "List the changed files under src/."
    }
  ]
}

就这样。没有 cache 字段，没有标志。该阶段已经是内容寻址的、可在运行内续跑的。

跨运行记忆化

运行内续跑只在一次运行内查找。如果你明天运行同一个 flow，它会从零开始 —— 即使什么都没变。

跨运行记忆化修复了这点。设 cache.scope 为 "cross-run"，阶段的结果就存储在 .pi/taskflows/cache/ 下的磁盘上。下一次运行 —— 明天、下周、在另一个会话中 —— 用相同的 inputHash 对照那个存储检查。命中意味着零 token、零成本。

这是 80% 场景：一个只要 git 提交没动就该复用结果的阶段。

{
  "id": "analyze-auth",
  "type": "agent",
  "task": "Summarize how auth works in src/auth/.",
  "context": ["src/auth/**/*.ts"],
  "cache": {
    "scope": "cross-run",
    "fingerprint": ["git:HEAD"]
  }
}

运行一次，它花费 agent 的成本。在相同提交下再运行一次，它花费为零。推送一个新提交，git:HEAD 指纹变化、键变化，阶段重新执行 —— 这正是你想要的。

跨运行命中时，完整的阶段状态被恢复（保留 gate 裁决、approval 状态、reads、loop/tournament 元数据、警告），usage 被清零，阶段被标记为 cacheHit: "cross-run"。

何时该用跨运行？

cache 字段

三个可选字段。空的 cache: {} 合法且等价于默认值。

三个作用域

TTL：当过期结果危险时

有时"输入没变"还不够 —— 结果本身会过期。两周前写的安全摘要可能不反映昨天引入的漏洞，即使 task 文本和 context 文件逐字节相同。

ttl 给跨运行命中加一个时间界限：

{
  "id": "security-summary",
  "type": "agent",
  "task": "Summarize known security risks in src/.",
  "cache": {
    "scope": "cross-run",
    "ttl": "6h",
    "fingerprint": ["git:HEAD"]
  }
}

这个阶段在首次计算后的最多六小时内复用其结果。之后，该条目被视为未命中，阶段重新执行。

语法是一个数字后跟可选单位：

格式错误或非正的 ttl 是硬验证错误。运行 /tf verify 在花费任何 token 之前捕获它。

指纹：告诉缓存关于世界的事

没有指纹时，cross-run 阶段只在其声明输入变化时失效 —— task 文本、context 文件、args、上游输出。这通常够了。但有时应该让缓存失效的东西住在 flow 定义之外：当前 git 提交、一个配置文件的内容、一个环境变量的值。

fingerprint 把那些外部信号折叠进缓存键。每项是一个字符串 <前缀><值>。运行时把每项解析为一个确定性字符串，将拼接结果哈希，并把摘要折叠进键。

五个前缀

glob: vs glob!:

"fingerprint": ["glob:src/**/*.ts"]

"fingerprint": ["glob!:src/**/*.ts"]

一个真实的指纹

{
  "id": "lint-summary",
  "type": "agent",
  "task": "Summarize the lint findings across the repo.",
  "cache": {
    "scope": "cross-run",
    "fingerprint": ["git:HEAD", "glob:src/**/*.ts", "glob!:package.json"]
  }
}

这在提交移动、任意 TypeScript 文件被修改、或 package.json 内容变化时未命中 —— 三个独立信号，全部折叠进一个摘要。

让整个 flow 加入：incremental: true

如果你的大多数阶段都该跨运行缓存，在 flow 级设 incremental: true。它把每个阶段的缓存作用域默认为 "cross-run"。

{
  "name": "code-review",
  "incremental": true,
  "phases": [
    {
      "id": "discover",
      "type": "agent",
      "task": "List the changed files.",
      "cache": { "fingerprint": ["git:HEAD"] }
    },
    {
      "id": "review",
      "type": "agent",
      "task": "Review {steps.discover.output}.",
      "dependsOn": ["discover"]
    }
  ]
}

现在重新运行 flow 会跨运行和会话复用未变阶段。优先级规则很简单：

值得知道的边界情况

idempotent: false 禁用所有缓存

执行不可逆副作用（部署、webhook POST、DB 写入）的阶段绝不能从缓存重放。设 idempotent: false，有效作用域变为 "off" —— 一次赋值覆盖每条缓存路径，包括 map 的逐项路径。

被阻止的阶段类型

这些阶段类型不能使用 cache.scope: "cross-run"：

这被两次强制执行：schema 校验在 /tf verify（零成本）拒绝它，运行时作为纵深防御将其降级为 "run-only"。

当 flow 定义无法被哈希时

如果 flow 定义哈希计算失败（flowDefHash === "failed"），该次运行中所有 cross-run 阶段都被降级为 "run-only"。没有 flow 哈希，键会退化为仅 flow 名称，重新打开跨 flow 碰撞。运行 /tf verify 诊断哈希为何失败。

缓存键如何计算

cross-run 阶段的完整身份是一个 SHA-256，截断为 16 个十六进制字符：

key = sha256(
  "flow:" + flowName,
  "v3:phasefp:" + (phaseFp ?? flowDefHash),   // 每阶段结构子指纹
  phaseId,
  agentName,
  model,
  resolvedTaskText,          // 插值之后
  "think:" + thinking,
  "tools:" + JSON(tools),
  "ctx:" + preRead,          // 解析后的 context 文件内容
  fingerprintDigest          // 仅当 scope === "cross-run"
).slice(0, 16)

几点值得注意：

• 插值发生在哈希之前。 一个对 {steps.discover.json} fan-out 的 map 阶段在 discover 输出变化时获得不同的逐项键 —— 无需 fingerprint。
• context 文件内容是身份的一部分。 编辑 context 文件总让阶段失效，无论 task 文本是否提及它。
• 指纹摘要仅对 cross-run 阶段解析。 对 run-only 它是空字符串 —— 运行内续跑已捕获声明输入的变化。
• 编辑阶段 B 只让 B 及其传递依赖失效，而不是整个 flow。这就是每阶段结构子指纹（v3:phasefp:）。

各阶段类型的额外项

每个阶段类型把多一点折叠进键：

向后兼容：四个键，一次写入

cacheKeys() 为每个阶段生成四个键。只有 key 被写入；其余为只读回退项，确保升级不会引发未命中风暴：

任意层级的命中都作为缓存命中恢复。taskflow 不写穿，因此缓存大小保持稳定，遗留条目会自然老化淘汰。

缓存在哪里

跨运行缓存是项目下 .pi/taskflows/cache/ 目录中的 .json 文件集合 —— 从 cwd 向上查找最近的 .pi 目录，从不到 ~/.pi/。

淘汰是机会式的：在每次写入时触发。超过 90 天兜底的条目被丢弃；如果存活数超过 1000，最旧的先被淘汰。

调试

阅读复用摘要

每次运行结果都带有一个 reuse 摘要：

每个阶段状态带有一个 cacheHit 标记："run-only"、"cross-run" 或 undefined（全新执行）。

强制重新运行

forceRerun 种子对单个阶段同时绕过运行内先前结果和跨运行存储。下游阶段不被强制 —— 它们自然重新评估：如果种子的新输出改变了它们的 inputHash，它们未命中并重新运行；否则命中。

检查缓存

# 缓存在哪里？
ls .pi/taskflows/cache/

# 有多少条目？
ls .pi/taskflows/cache/*.json | wc -l

# 检查具体条目（来源：flowName、phaseId、runId、createdAt）
cat .pi/taskflows/cache/<key>.json | jq '{flowName, phaseId, runId, createdAt, output}'

常见陷阱

清空缓存

DSL 中没有清空命令 —— 存储只是文件：

rm -rf .pi/taskflows/cache/

常见错误

下一步

Last updated on