Tool Idempotency and Recovery

工具幂等分类与恢复决策

🔧 能力 · 🏠 首页 › Tool-Idempotency-and-Recovery

---

📑 本页目录

• 1. 四类幂等性
• 2. 恢复决策矩阵（RecoveryPolicy.decideForOperation）
• 3. 与 journal / checkpoint 的配合
• 4. 为什么"成功也要 SKIP"
• 5. 相关页面

长任务被打断后，"这个操作到底做没做"必须能回答。T76 为此建立了 ToolExecutionPolicy（80 个工具的幂等分类）+ RecoveryPolicy（恢复决策矩阵）。 与 任务运行时 的 journal 配合使用。

1. 四类幂等性

分类	语义	恢复动作
READ_ONLY	重放无副作用	RETRY（放心重放）
IDEMPOTENT_WRITE	重放结果等价	RETRY
NON_IDEMPOTENT	重放会产生重复副作用	VERIFY（先验证再决定）
UNKNOWN	行为不可判定	VERIFY

1.1 归类表（覆盖 80 个已注册工具）

分类	代表工具
READ_ONLY	read_file list_files web_search ui_dump logcat browser_snapshot
IDEMPOTENT_WRITE	write_file（整覆盖）app_install create_directory browser_navigate github_write_file
NON_IDEMPOTENT	app_uninstall ui_tap input_text browser_click terminal_send alarm
UNKNOWN	shell_execute http_request mcp_call terminal_exec code_runner

未列入表的工具默认 UNKNOWN（保守侧）。

Note

这套分类与 工具系统 v3 的 retrySafe = readOnly || idempotent 是同一口径的两处表达： 执行硬化层用它决定是否重试，任务运行时用它决定恢复动作。

2. 恢复决策矩阵（RecoveryPolicy.decideForOperation）

journal 中记录的状态	决策	理由
SUCCEEDED	SKIP	绝不重复已成功落盘的操作（幂等性验收核心）
FAILED	SKIP	失败不会因重放变成功，交给上层重新决策
NOT_STARTED	SKIP	尚未开始，正常流程会重新发起
UNKNOWN（中断时刻）	按分类裁决（下表）	真正需要人为语义的地方

UNKNOWN 的裁决：

ask_user 族      → RETRY     （问人没有副作用）
READ_ONLY        → RETRY
IDEMPOTENT_WRITE → RETRY
NON_IDEMPOTENT   → VERIFY
UNKNOWN          → VERIFY

VERIFY 的语义：不重放，而是向模型注入提示 ——

操作 X 可能已在中断前执行，请先用只读工具验证其实际效果，再决定是否重做。

3. 与 journal / checkpoint 的配合

flowchart LR
    A["TOOL_CALL_STARTED"] --> B["journal 追加 RUNNING<br/>（含幂等分类快照）"]
    B --> C{"进程死亡？"}
    C -->|否| D["TOOL_CALL_FINISHED → SUCCEEDED / FAILED"]
    C -->|是| E["journal 停留在 RUNNING<br/>恢复时判为 UNKNOWN"]
    D --> F["decideForOperation → SKIP"]
    E --> G["decideForOperation → RETRY / VERIFY"]

Loading

4. 为什么"成功也要 SKIP"

一个很容易踩的坑：恢复时把已成功的写操作再跑一遍。

• write_file 整覆盖 → 重放等价，问题不大；
• app_install → 重复安装，浪费流量与时间；
• terminal_send、ui_tap、browser_click → 语义完全不同（再点一次按钮可能提交两次表单）。

所以 journal 里 SUCCEEDED 一律 SKIP，这是"幂等性验收"的核心断言，有专项测试。

5. 相关页面

• 任务运行时与持久化 · 工具系统
• 混沌工程与崩溃审计（同类"中断后正确性"问题）

---

🏠 返回首页 · 📚 文档索引 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图 · 🐛 提 Issue

_{Android Guru Agent · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room}