实用笔记：Pi如何设计能够长时间运行的智能体
《实用笔记》操作指南：pi如何设计能够长时间运行的智能体——为采用该模式的团队提供的契约、校验机制以及可直接插入的代码模块。
可将此内容视为《π如何设计能长时间运行的智能体》一文中理念面向操作员的重构版本：清晰的阶段划分、有序的代码模块，以及可在交接时保留的恢复说明。
AI
将此阶段视为可度量的结构来处理效果最佳。在扩大范围之前，先记录一份理想的运行日志、一个故障案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某一步骤出错时，故障应指向单一责任点，而非复杂的流程链。 保持图结构的状态简洁且具有类型定义。嵌套的数据块会掩盖哪个节点编写了哪个字段的信息，还会在中断后导致无法继续运行。
3,446行规格要求让“能否从崩溃处继续运行”成为整个运行时的首要约束
将包含3,446行的规格阶段视为可测量的界面来处理效果最佳。在扩大范围之前，先记录一份完美的测试用例、一个故障案例以及回滚说明。 把这一阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现无声的、不完整的处理过程。 保持图表状态简洁且具有明确类型。嵌套的数据块会掩盖是哪个节点修改了哪个字段，还会在中断后导致无法继续处理。
“只需保存消息”是不够的
将“仅保存消息”阶段视为可度量的对象来处理，效果最佳。在扩大范围之前，先记录一份完美的测试用例、一个失败案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解这些成本，就能避免在从演示环境过渡到共享环境时出现意外费用。要保持图表状态简洁且类型明确，嵌套的数据块会掩盖是哪个节点修改了哪个字段，还会在中断后导致无法继续处理。
先明确意图，再采取行动
将“编写意图然后进入阶段”的流程视为可度量的对象来处理时效果最佳。在扩大范围之前，先记录一份完美的示例文本、一个失败案例以及回滚说明。 将配置置于应用程序代码之外。环境文件、密钥存储和功能标志应集中存放于一个位置，这样操作人员无需查看整个结构即可进行审计。 保持图结构的状态简洁且具有类型约束。嵌套的数据块会掩盖是哪个节点修改了哪个字段，还会在中断后导致无法继续处理。
会话的四层状态
将 Session 的四层结构视为可度量的对象时，其效果最佳。在扩大范围之前，需记录一份理想状态下的流程记录、一个故障案例以及回滚说明。 同时记录正常流程与恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。 保持图表状态简洁且类型明确。嵌套的数据块会掩盖哪个节点编写了哪个字段的信息，还会在中断后导致无法继续处理。 将 Session 的四层结构视为可度量的对象时，其效果最佳。在扩大范围之前，需记录一份理想状态下的流程记录、一个故障案例以及回滚说明。 应将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现无声无息的半完成状态。
tree (shared, append-only) lanes
a ── b ── c ── d main → d (op log: …)
└── e ── f slack:171943… → f (op log: …)
global facts: name = "Refactor auth", label(b) = "checkpoint-1"
三种操作类型
对于三种操作阶段，在修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。对于会产生支出或修改生产数据的操作，必须经过人工审批。编译时的配置并不等同于业务功能的完整性。
上下文仅在尾部扩展
由于上下文仅在特定阶段才会变化，因此在修改代码之前应先明确输入参数、该步骤的负责人以及结束标准。操作人员应当能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置应置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审核。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务功能的完整性。
R step_attempt request in flight, context ends at user message U
session.appendMessage(M) caller resolves here
R write_deferred full payload, provisioned id
E assistant message A provider cached [.., U, A]
E message M checkpoint applies the write; tail append
溢出情况仅有唯一一次处理机会
由于 Overflow 只有一个处理阶段，因此在修改代码之前必须明确输入参数、该步骤的负责人以及结束条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都是产品功能的一部分，而非后续需要补充的内容。 对于任何会耗费资金或修改生产数据的操作，都必须经过人工审批。编译时的逻辑连接并不等同于业务功能的完整性。 由于 Overflow 只有一个处理阶段，因此在修改代码之前必须明确输入参数、该步骤的负责人以及结束条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将这一阶段视为输入与验证后输出之间的契约。为相关产出命名，明确成功标准，绝不允许出现无声无息的半完成状态。
function isRecoverableLength(message: AssistantMessage, desiredMaxOutput: number): boolean {
if (message.stopReason !== "length") return false;
if (desiredMaxOutput > 0 && message.usage.output >= desiredMaxOutput) return false;
return true;
}
单次工具调用中的五个故障点
在处理阶段内的五个故障点时，首先需明确相关约定：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外费用。 需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。若没有这些记录，调试过程将会浪费大量时间。
E assistant message, calls c1, c2
X1 before before_tool nothing durable for c1
H before_tool(c1)
X2 decision made, nothing written same as X1
R tool_started(c1)
X3 tool executing
H after_tool(c1)
X4 hook interrupted same durable state as X3
E tool result c1
X5 result durable c1 finished
暂停状态的任务与发生故障的任务看起来相同
在处理带有暂停通道的阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 在耗时较高的步骤之后设置检查点。当操作人员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。
先记录账本，再处理正确性问题
在处理“账本被写入”阶段时，首先需明确合同条款：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。 在成本较高的操作之后设置检查点。当操作员重新尝试某个节点时，恢复流程不应再次调用相同的大语言模型接口。 在处理“账本被写入”阶段时，首先需明确合同条款：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 将此阶段视为输入与验证后输出之间的契约。为相关产物命名，定义成功判定标准，并拒绝默许部分完成的情况。
竞态条件仅有两种解决方式
将“Race”问题视为可测量的指标时，其解决效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，就能避免在从演示环境过渡到共享环境时出现意外费用。要保持图表状态简洁且类型明确，嵌套的数据结构会掩盖是哪个节点修改了哪个字段，还会在出现中断后导致无法继续执行。
恢复机制的自我检查
将恢复检查的各阶段视为可度量的界面来处理，效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 将配置与应用程序代码分开。环境文件、密钥存储和功能标志应集中存放于一处，这样操作人员无需查看整个结构即可进行审计。 保持数据结构的层次简单且类型明确。嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，还会在出现中断后导致恢复失败。
通过逐一枚举所有崩溃点进行测试
将暴力枚举测试阶段视为可度量的对象时，其效果最佳。在扩大测试范围之前，需记录一份理想状态下的输出、一个失败案例以及回滚说明。同时文档化正常流程与恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的一部分，而非后续需要补充的内容。保持数据结构扁平且类型明确，否则嵌套的数据块会掩盖具体是哪个节点设置了哪个字段，从而导致中断后无法继续处理。将暴力枚举测试阶段视为输入与已验证输出之间的契约，为相关文档命名、明确成功标准，绝不允许出现无声无息的半完成状态。
成本
在成本阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。对于会产生支出或更改生产数据的操作，必须经过人工审批。编译时的配置并不等同于业务功能的完整性。
总结
在收尾阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务功能的完整性。
操作检查清单
在完成操作检查清单阶段时，首先需明确相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持透明可追溯。
应优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一责任点，而非复杂的流程链。
在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次计费相同的LLM调用。
锁定依赖项的版本，并记录用于运行演示的镜像摘要。可重复性比经验知识更为重要。
将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，拒绝默许的半完成状态。
在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次计费相同的LLM调用。
在推广该技术栈之前，应先冻结版本，为关键流程记录标准输出日志，并明确回滚步骤。共享环境需要设置速率限制、租户验证机制，以及负责密钥轮换的明确责任人。与其展示花哨的一次性演示，不如追求扎实可靠的性能。
关于58b36f32f593的批量处理说明：请将提供商密钥移出代码仓库，设定单次会话的令牌上限，并将日志存储在评估用示例文件旁，以便后续更换模型时保持数据可比性。
在处理强化安全性的第0阶段时，首先需明确相关规范：所需输入参数、成功标识，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。同时要一并记录正常流程与故障恢复路径，重试机制、人工审核环节以及错误处理方式都是产品不可或缺的部分，而非后续才需要补充的内容。
强化细节 0/778：测量该记录的耗时、错误类型以及代币消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
强化笔记的第1阶段若被视为可测量的对象，则效果最佳。在扩大范围之前，需记录一份理想案例、一个故障实例以及回滚说明。将此阶段视为输入与经过验证的输出之间的契约，为相关文档命名、定义成功标准，并拒绝默许的半完成状态。
强化细节 1/778：测量该记录的耗时、错误类型以及代币消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在强化措施的第2阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。
强化措施细节2/778：针对此项措施，需统计执行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非主观判断来决定是否保留该变更。
在处理强化措施的第3阶段时，首先写下相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合既定标准。 相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障应能指向单一责任点，而非复杂的流程链。
强化措施细节3/778：需测量该步骤的运行时间、错误类型以及代币消耗情况，然后依据固定的评估标准而非主观判断来决定是否保留该修改。
将强化措施的第4阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一份理想的操作流程、一个失败案例以及回滚说明。 在功能结果旁同时记录时间消耗及代币或查询成本。提前明确成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
强化措施细节 4/778：为该记录测量运行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个别案例来决定是否保留该变更。
在强化措施的第5阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新执行该步骤，而无需猜测隐藏状态。需同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续的优化工作。
强化措施细节 5/778：为该记录测量运行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个别案例来决定是否保留该变更。
在处理强化措施的第6阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合约定。 将这一阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝默许部分完成的情况。
强化措施细节6/778：需测量该步骤的耗时、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
将强化措施的第7阶段视为可量化的对象来处理效果最佳。在扩大范围之前，先记录一份标准操作示例、一个失败案例以及回滚说明。 应将配置信息与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放于一处，以便操作人员无需查看全部代码结构即可进行审计。
强化措施细节 7/778：测量该代码块的运行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
在强化措施的第8阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新执行该步骤，而无需猜测隐藏的状态。相比复杂的脚本，更应采用小型且可测试的单元。当某一步骤失败时，故障原因应能明确指向某个具体的责任方，而非整个混乱的流程。
强化措施细节 8/778：测量该代码块的运行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。