幂等性（Idempotency）

同一个操作执行一次与执行多次，对外部状态产生相同结果的性质。是安全重试的前提。

生产方式：人写签发：晓黎学习复核：2026年9月21日被 2 个词条引用

一句话定义

幂等操作 = 执行一次和执行多次，对系统状态产生相同的结果。

为什么 Agent 系统特别需要它

Agent 的重试比传统系统更频繁，原因有三：

  1. 工具调用可能超时，但实际已经执行
  2. 模型可能重复发起同一个调用
  3. 失败恢复需要重放之前的操作

如果重试一个非幂等操作，就会产生副作用叠加。

// 非幂等：重试会创建两条记录
async function createRecord(data) {
  return await db.insert('records', data)
}

// 幂等：重试不会产生重复
async function createRecord(data, idempotencyKey) {
  const existing = await db.findByKey('records', idempotencyKey)
  if (existing) return existing
  return await db.insert('records', { ...data, idempotencyKey })
}

天然幂等 vs 需要设计

类型例子说明
天然幂等读文件、查询、HTTP GET重复执行无副作用
需要设计创建记录、发送消息、扣款必须有去重机制
无法幂等追加日志、累加计数需改用「设置值」而非「增加量」

第三类常被忽略：「把计数加 1」不是幂等的，「把计数设为 5」才是。

实现的三层

层做法
接口层接受 idempotency key 参数
存储层对 key 建唯一索引，重复插入自动失败
执行层先查后写，或使用原子 upsert

在 Agent Harness 中的位置

关注点归属
工具是否幂等工具声明（第 06 讲）
能否重试重试策略依据幂等性判断（第 16 讲）
副作用回滚补偿逻辑（第 16 讲）

DeepSeek Harness 的工具定义中，idempotent 是一个显式属性，重试策略据此决定是否允许重试。

相关

互链

链接来自概念卡正文里的双链，编译时能解到本期词条集的才成为站内链接。

反链（2）

出现在哪些课时里（2）

判据与「课时正文里能不能点出来」是同一个：那一节确实提到了它。点课时走当前页跳转， 它是导航，不是词条链接。

关联图

只画这一条与它直接相连的词条，边与上面两区同源。可拖拽、可缩放，点节点是新标签。

以列表方式看这 3 个节点

出处

路径是本地知识库（Obsidian 库）里的位置，正文与概念卡逐字对应。

  • 概念卡原文幂等性（Idempotency）03_RESOURCES/概念/幂等性.md
  • 所属知识地图栏目概念页索引 · 可观测性与可靠性03_RESOURCES/概念/Index.md
  • 正文引用的知识库笔记第 16 讲 错误恢复02_AREAS/AI开发/Harness Engineering/Agent Harness 课程/16-错误恢复：失败是常态.md
  • 正文引用的知识库笔记第 6 讲 Tool Calling02_AREAS/AI开发/Harness Engineering/Agent Harness 课程/06-Tool Calling：模型如何安全地影响世界.md

编译入库：2026年11月2日。词条由知识库编译而来， 修正要回到概念卡改，再重新编译。