架构设计：本地控制面与远程执行环境的分离
本期内容深入探讨如何将 Agent 的执行环境从本地扩展到远程，核心在于构建一个控制面与执行面相分离的架构。在左侧本地侧，保留 Pi Durable Harness、SQLite 数据库、Task 状态管理以及 Document 存储。同时，调用模型所需的 Provider 配置和密钥也严格保留在本机。右侧则是一台独立的远程 Linux 主机，其中仅包含工作目录和工具运行所需的软件环境。两者之间通过 SSH 连接通信。
“真正执行工具的是另一台 Linux 主机。”
在这种架构下，当 Agent 发出 read、write、edit 或 bash 等工具调用指令时，这些操作不直接触碰本机的文件系统。相反，它们通过 RemoteExecutionEnv 接口转发至远程主机执行。这一机制的前提是应用没有主动将 Secret 注入到远程的命令执行环境中。通过这种拓扑结构，Pi Durable 能够确保密钥等敏感信息始终留存在本地可控的安全区域，而将文件读写和代码执行的风险隔离在远程环境中。
实验环境搭建：Docker 模拟与 SSH 安全配置
为了完整演示这一接入过程，博主构建了一个基于 Ubuntu 24.04 的 Docker 容器来模拟远程环境。该容器中仅安装了 OpenSSH、Python 以及基础证书，并创建了一个专用的 agent 用户。工作目录被设定为 /home/agent/workspace，容器的 22 端口映射到宿主机的 2222 端口。SSH 私钥仅存储在项目的实验目录中，未随代码仓库泄露。
在首次连接时，脚本通过 pi-env 执行信任流程。首先调用 scanHostKey() 获取服务器的主机公钥和指纹。这一步必须从云控制台或其他可信渠道交叉确认指纹，以确保中间人攻击未被实施。确认后，脚本调用 acceptHostKey() 将公钥写入项目本地的 known_hosts。这是一个一次性操作，无需每次连接重复执行。此后，pi-env 会以严格模式检查服务器身份，若主机公钥发生变化，连接将直接失败。
“如果主机公钥发生变化 连接会直接失败的 不会自动的接受新的密钥。”
此外，pi-env 会自动在 SSH 连接参数中加入固定主机别名、禁用 agent forwarding、X11 forwardings 和端口转发等安全限制，进一步加固连接安全性。
Agent Client 配置与远程工具调用流程
在客户端配置方面，博主使用了之前视频中的 pi-durable-mini-agent 作为基础。远程地址和端口无需修改代码，而是通过环境变量 PI_REMOTE_HOST 和 PI_REMOTE_PORT 动态指定。SSH 私钥和 known_hosts 文件均使用项目本地的专用文件。Harness、SQLite、模型调用以及 CodingTools 的核心逻辑仍在本地运行，唯一的区别是将 Harness 的环境变量替换为指向远端工作目录的 RemoteExecutionEnv。
当连接建立时，pi-env 会先检查远端的平台类型，然后从 npm 包中选择对应的 daemon。该 daemon 按照 SHA256 命名部署，并在每次启动前进行校验。值得注意的是，远端主机不需要预安装 Node.js，也不保存模型的 API Key。在演示中，博主让 Agent 创建并运行一个 Python 文件。
“模型实际选择了 write 和 bash 终端里的两条 REMOTE 日志 来自于真实的工具调用。”
Agent 返回运行结果后，博主进入 Docker 容器读取同一文件并重新执行。结果显示，该文件确实存在于 /home/agent/workspace 目录中，且输出与本地预期一致。然而，本地项目目录里并没有这个工作文件。这证明了 Pi Durable 自带的 read、write、edit 和 bash 工具依赖于 ExecutionEnv 接口，更换环境实现即意味着更换了实际执行操作的机器。这种设计使得本地仅作为控制中枢，而具体的文件操作和命令执行完全发生在远程。
任务恢复机制：Checkpoint、Document与幂等性设计
Pi Durable 的核心优势在于其恢复能力，这依赖于 Task、Document 和 Checkpoint 的协同工作。博主模拟了一次远程代码验证任务：在远端运行 test_calc.py 脚本，测试通过后记录操作完成。该 Task 分为 prepare、execute 和 verify 三个阶段。
- Prepare：生成稳定的
operation ID。博主指出，.operations目录及其内容并非框架自动提供，而是由外部系统自行实现的操作登记和幂等机制。这里使用远端目录作为最小示例。 - Execute：运行测试并留下一个
receipt文件。这是一个由业务代码写入的普通文本，文件名包含 operation ID，内容记录操作结果凭证。程序随后将其保存至本地的 checkpoint 和 Document。 - Verify：调用
readTextFile()再次读取远端的 receipt。这里并非执行简单的 ssh cat 命令，而是pi-env复用 SSH 上的 daemon 会话，通过 open、pread 和 close 操作取回内容。
“远端文件和本地 checkpoint 一致 任务才结束。”
Document 保存了 stage、尝试次数和 receipt。Durable commit 将 checkpoint 和 Document 原子地写入本地存储。恢复时，系统会继续最近一次提交的阶段。这种设计确保了即使发生中断，任务状态也能被精确追踪。
网络故障与进程崩溃的模拟实验
为了验证系统的鲁棒性，博主进行了两项关键测试：网络断开和进程崩溃。
首先模拟网络中断。第一次读取 hello.txt 成功，随后停止容器。后续操作返回的不是旧数据或模糊超时，而是明确的 SSH exit code 255 以及 connection refused。sshConnection() 函数实现了惰性连接，即创建环境时不需网络，仅在第一次操作时建立会话。如果启动失败且错误属于当前操作，下一次尝试会重新连接。当容器重新启动后，再次运行读取操作即告成功。
其次模拟最危险的进程崩溃。在 execute 阶段，远端运行测试并创建 receipt 文件。实验脚本打印 CREATED:receipt-build-calc-v1，表示远端操作已完成。此时本地尚未提交 verify checkpoint。博主主动杀掉进程，模拟真实崩溃。
“状态已经不同步了 远端已经有了 receipt 本地 SQLite 只知道 Task 还停在 execute 阶段。”
重启脚本后，Harness 打开 durable.sqlite，找到相同的 conversation 和 Task，并从 execute checkpoint 继续。重新执行代码时，程序携带同一个 operation ID，检查 .operations 目录下的 build-calc-v1.done。由于发现远端 receipt 文件已存在，程序跳过远程测试，直接读回原来的结果。终端打印 REUSED 提示。随后程序提交 verify checkpoint，Document 变为 stage done，attempts 设为 1。恢复成功并非因为远端操作被回滚，而是因为外部操作使用了稳定的 ID 实现了去重和结果查询。
Replay-Safe 工具与 Exactly-Once 语义的工程挑战
博主进一步区分了两类工具及其处理逻辑：
1. 非 Replay-Safe 工具：如果进程在调用中间挂起，Pi Durable 不会擅自重跑。它会给模型一个 interrupted 结果，并保留已提交的部分输出。
2. Replay-Safe 工具：开发者可在定义中声明允许恢复后重新执行。但博主强调，允许重试不代表外部操作只会发生一次。例如转账成功但因网络中断未返回结果时，直接重试可能导致重复扣款。
“外部操作最终只发生一次 通常叫 exactly-once 它不是在工具定义里增加一个字段就能够获得的能力。”
实现 Exactly-Once 语义的常见做法是：在执行外部操作前保存稳定的 operation ID，工具每次重试携带同一 ID。远端或外部服务据此去重并查询结果。若目标系统不支持幂等，需先查询状态、提供补偿动作或标记为人工确认。Pi Durable 解决的是“从哪里继续”的问题，而外部操作能否安全重试，仍由工具代码和目标系统共同保证。
关键注意事项与生产环境建议
博主最后列出了三点重要注意事项，提醒开发者避免误用： 1. 版本稳定性：当前使用的 1.1.0 版本 Pi Durable README 仍标注为 Experimental API，接口可能在版本间变化。因此实验中将 npm 包和源码提交都锚定了具体版本。 2. 容器安全性边界：Ubuntu Docker 容器仅用于复现 SSH 行为。普通容器的安全性取决于运行时挂载的网络权限和主机配置，它不是自动成立的生产级 Sandbox。 3. 密钥泄露风险：模型凭据留在本地是该拓扑的默认结果，但并非防泄露策略。如果应用将环境变量和 Secret 显式传给远程命令，密钥依然会离开本机环境。这是使用时的重大风险点。
“Pi Durable 让控制面留在一个可以持久化审计和恢复的位置 再把文件与进程操作送到远程相对安全的执行环境。”
该机制对 GPU 主机、构建机或按会话分配的远程工作区非常有用。但真正的工程挑战在于以下四点：先提交意图并确定稳定 ID；确认操作未完成时再重试；结果不确定时进行查询或补偿。Harness 可从 checkpoint 继续，但远程操作的安全续行需由应用自身的幂等或补偿机制回答。
结论
本期内容详细展示了如何利用 Pi Durable 将 Agent 的执行环境从本地迁移至远程 Linux 主机，通过 SSH 和 RemoteExecutionEnv 实现控制面与执行面的分离。核心架构确保模型密钥和本地状态保留在受控环境中，而文件读写和命令执行则在远程隔离区进行。实验验证了系统在网络中断、进程崩溃等异常场景下的恢复能力，其关键在于利用稳定的 operation ID 和原子化的 Checkpoint/Document 机制实现幂等性。
然而，Pi Durable 本身并不自动提供“Exactly-Once”语义。它解决了任务断点续传的问题，但外部操作的安全重试仍需开发者在工具层实现幂等逻辑或补偿机制。此外，实验环境的安全性依赖于严格的配置（如密钥不注入远程、容器权限限制），且当前 API 仍处于实验阶段。对于需要高安全性和隔离性的场景（如 GPU 集群、构建机），该方案提供了可行的技术路径，但需配合完善的工程实践以确保最终一致性。