幂等设计

定义

同一操作无论执行多少次，结果始终一致的设计原则。在 Agent 工程中尤为关键，因为 Agent 会频繁重试（网络超时、执行结果不确定、任务中断恢复）。

要点

• 声明式优于命令式：定义期望状态，系统自动协调
• --if-not-exists 或 ensure 语义防止重复创建
• --idempotency-key 让服务端去重
• 非幂等操作 + Agent 重试 = 重复用户、重复邮件等副作用

示例

• kubectl apply -f deployment.yaml — 无论执行多少次，结果一致
• mytool user ensure --name "john" — 声明式，幂等
• 飞书 CLI --idempotency-key — 传入唯一标识符，服务端只处理一次

相关概念

• Agent-CLI设计
• Agent Harness

参考资料

• Agent-CLI设计原则〔待补〕