长任务最危险的并不总是模型能力不足，而是目标、事实和边界在几十次工具调用后悄悄漂移。一个好的检查点应该让任务被打断后可以继续，也让人能发现它正在回答旧问题。 三份持续更新的状态 事实表 只记录已经验证的事实、证据位置和时间。易变化的信息带日期；不确定内容明确标记为假设。 决策表 记录已经确认的选择、否决项、理由和生效范围。新消息与旧决定冲突时，先停下来处理冲突。 执行表 每个步骤只有 pending、in_progress、completed 三种状态，并写出验收证据。任何时刻最多一个主要步骤处于进行中。 什么时候建立检查点 完成一个可独立验收的阶段后。 即将进行不可逆或高风险操作前。 工具返回异常、环境发生变化或用户追加要求后。 上下文将被压缩、任务将转交或运行时间较长时。 停止条件比“继续努力”更重要 提前定义预算、最长运行时间、最大重试次数、允许修改的对象和必须转人工的事件。检查点不是为了让 Agent 永远运行，而是为了让它知道何时应该停。 编辑说明：2026-08-15，COHAO 编辑部基于长任务执行和社区建设记录整理；AI 协助起草，项目负责人复核。

Agent 调用外部工具时，网络超时只说明“没有收到结果”，不说明“操作没有发生”。如果收到超时就盲目重试，可能重复付款、重复发帖、重复发信或重复创建资源。 最小幂等设计 在业务层生成幂等键，例如 actor + action + object + confirmed_version 的稳定摘要。 工具执行前记录 pending，并以唯一约束保证同一个键只能创建一次。 外部系统支持幂等键时，把同一个键传给它；不支持时，在本地状态机中保存外部请求标识。 超时后先查询状态，不立即再次执行。 结果进入 succeeded、failed、unknown 或 needs_review，不要把“未知”伪装成失败。 为无法原子回滚的动作准备补偿，例如撤销草稿、退款申请或人工复核单。 Agent 应该看到什么 模型可以得到经过裁剪的状态，例如“请求已经提交，结果未知，请等待查询”，而不是数据库连接和任意重试工具。是否允许重试由后端状态机判断。 一个简单的停止条件 出现以下任一情况就转人工：外部结果未知、高价值或不可逆动作、幂等状态冲突、对象版本已经变化、确认已过期。 可靠性不是“多重试几次”，而是知道每一次执行是否发生、现在处于什么状态、下一步由谁负责。 编辑说明：2026-08-15，COHAO 编辑部根据外部工具调用与支付类系统的通用工程模式整理；AI 协助起草，项目负责人复核。

AI 工具变化太快，一篇没有日期和版本的“最佳实践”可能在几周后就无法复现。版本化不是形式主义，而是在告诉读者：这条结论在哪个时间窗口和环境里成立。 标题下方建议固定写六项 最后验证：YYYY-MM-DD，时区 工具或模型：准确名称与版本 客户端或 SDK：版本号 运行环境：操作系统、运行时、关键依赖 账号或能力范围：只写必要的套餐/权限，不泄露身份和密钥 结论状态：已复现 / 部分复现 / 已失效 / 待更多样本 正文要区分三类信息 事实：官方文档、返回字段、日志、测试结果。 观察：在多少样本、什么条件下出现的表现。 推断：对原因的解释，尚未被直接证明。 如果工具是在线服务，还应记录地区、请求时间、重试策略和速率限制，因为这些因素会改变延迟与成功率。价格类内容要写币种、计价单位和查询日期，不把历史价格说成当前价格。 更新而不是悄悄覆盖 结论变化时，在顶部增加更新记录：改了什么、为什么改、旧结论哪里失效。读者看到的不是一篇永远正确的文章，而是一段可以追踪的知识维护历史。 编辑说明：2026-08-15，COHAO 编辑部基于 AI 工具文档与生产核验经验整理；AI 协助起草，项目负责人复核。

当 AI 功能表现不稳定时，团队常见的第一反应是继续改 Prompt。没有固定评测集时，这种调整很容易让一个例子变好、另十个例子悄悄变坏。 先建立一个很小但真实的评测集 初版不需要上千条数据。可以从 20 到 50 个真实任务开始，至少覆盖： 最常见的正常请求。 信息不全、表达含糊和格式异常的请求。 工具超时、空结果、权限不足和重复回调。 应该拒绝或转人工的高风险请求。 曾经发生过的回归样本。 每条样本写清输入、允许使用的上下文、期望行为、禁止行为和判定方法。能用代码判定的就用代码；涉及帮助程度、事实完整性或语气的，再使用有量表的人类复核或模型评分，并定期校准评分器。 每次改动都问四个问题 通过率是否提高，还是只对展示案例提高？ 原来通过的样本有没有回归？ 成本、延迟和工具调用次数发生了什么变化？ 失败是否更容易被发现和人工接管？ OpenAI 的评测指南也强调持续评测、任务特定样本和人工反馈校准。无论使用哪家模型，这个方法都成立：先把“好”写成可检查的行为，再调整 Prompt、工具或模型。 参考： https://developers.openai.com/api/docs/guides/evaluation-best-practices https://platform.openai.com/docs/guides/evals 编辑说明：2026-08-15，COHAO 编辑部依据官方评测指南和工程实践整理；AI 协助起草，项目负责人复核。

Agent 安全最容易犯的错误，是把“你只能操作自己的数据”写进提示词，然后相信模型会一直遵守。模型输出只能表达意图，不能证明调用者是谁，也不能决定它有权操作哪个对象。 一个可靠的调用链 后端从已验证会话或访问令牌得到 actor，不接受模型提供的 user_id。 工具接口只接收业务对象和必要参数，站点、租户、所有者范围由后端补全。 策略层同时检查角色、对象所有权、动作风险和当前状态。 付款、删除、公开发布、改权限等动作需要明确确认，并把确认绑定到对象、内容和有效期。 写操作带幂等键，重复请求不会重复扣款、发送或删除。 审计记录保存是谁、何时、对什么对象、依据什么策略做了什么，不保存不必要的密钥和隐私。 不应交给模型决定的内容 当前用户身份、租户或站点。 对象是否属于当前用户。 是否为管理员、财务人员或审核员。 是否已经获得某次高风险操作的确认。 API 密钥、钱包签名、数据库直连和角色修改。 提示注入之所以危险，不只是模型可能说错话，而是被污染的内容可能诱导模型调用真实工具。OWASP 的生成式 AI 安全项目也把 Prompt Injection 作为核心风险；工程上的答案不是继续堆提示词，而是限制工具能力与后端授权范围。 参考： https://genai.owasp.org/llmrisk/llm01-prompt-injection/ https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence 编辑说明：2026-08-15，COHAO 编辑部根据公开安全资料与本项目“权限优先”原则整理；AI 协助起草，项目负责人复核。

很多 Agent 演示只留下一个成功截图。真正需要维护时，我们更需要知道：它在什么条件下运行、获得了什么权限、哪里失败、能否再次得到相近结果。 下面是一份可以直接复制的最小运行记录。 任务名称： 记录时间与时区： 执行者：人 / Agent / 人机协作 工具、模型与版本： 代码或提示词版本： 运行环境：操作系统、运行时、关键依赖 目标结果： 允许读取的输入： 允许调用的工具： 明确禁止的动作： 预算与最长运行时间： 停止条件： 实际步骤摘要： 关键工具调用及返回： 最终结果：成功 / 部分成功 / 失败 / 人工中止 可核验证据：日志、测试、提交、截图或输出文件 时间、Token、API 与人工成本： 失败现象： 已验证根因： 尚未验证的推测： 重试是否安全： 修复或补偿动作： 下次需要新增的检查： 为什么要把权限也写进去 同一段提示词，在只读文件系统和拥有生产管理员权限时，风险完全不同。可靠性不是只看回答质量，还要看 Agent 在失败、超时和歧义情况下会不会越过边界。 最小验收 另一个人能依据记录重跑主要步骤。 关键结果有机器可读或可截图的证据，不只是一句“看起来可以”。 失败后能判断应该重试、人工接管还是回滚。 记录没有包含密码、Token、Cookie、私密原文或未脱敏个人数据。 这份模板也是 COHAO《AI Agent 工具可靠性报告》的起点。欢迎回复你认为缺失但必须记录的字段。 编辑说明：2026-08-15，COHAO 编辑部基于本项目真实部署与 Agent 操作经验整理；AI 协助结构化，项目负责人复核。