从控制Agent的手开始构建ReAct Agent的命令转发器本文记录了 OpenRY 项目 Phase 1 的设计思路——一个跨平台的命令转发器用于在 ReAct Agent Workflow 体系中实现对 Agent 行为的硬约束。一、问题的原点Agent 的手不可信在基于 ReAct 模式的 AI Agent 开发中一个反复出现的痛点是Agent 太自由了。以 OpenCLaw 或 Claude Code 这类 Agent 框架为例Agent 可以自由调用ls、cat、python、curl等任何系统命令。这种自由带来了三个致命问题问题 1状态机断裂Agent 完成一个步骤后可能不发送状态更新、发送错误的状态码、或者发送了但格式不对。硬代码无法判断当前步骤到底完成了没有整个 Workflow 流程卡死。问题 2无限循环烧 TokenAgent 在某个步骤中陷入工具调用 → 结果 → 思考 → 再调用的死循环。没有外部刹车机制一次对话轻松烧掉几十美元的 Token 费用。问题 3虚假完成Agent “认为自己完成了任务但实际上产物缺失、数据错误。它自信满满地告诉编排器我做好了”而下一个步骤拿到错误输入后全线崩溃。根因只有一个Agent 同时拥有大脑推理和双手执行命令没有任何中间层做约束。二、解法命令转发器模式我们的核心思路是把 Agent 的手砍掉换上一个可控的假肢。改造前Agent 直接调用系统命令完全自由。改造后所有动手操作必须通过openry这个中间层转发Agent 不再直接接触系统。这样做的好处能力实现方式强制状态机Agent 完成步骤后必须显式声明完成状态硬代码可查询验证软刹车openry 可以修改返回内容告知 Agent 立即停止当前操作命令白名单不同 step 可限制允许的命令集合Phase 2免费审计所有命令调用自动记录完整可追溯调用计数每个 step 的 openry 调用次数可统计超限可熔断三、架构设计3.1 三层分离整个系统分为三层Orchestrator硬代码负责路由、验证、调度。它加载 Workflow 配置决定每一步做什么验证 Agent 是否真正完成了任务。Agent大脑只管推理和决策。它不知道 workflow 是什么、当前在第几步、run_id 是什么。它只收到当前任务的描述然后用 openry 干活。openry手执行命令、记录日志、返回结构化结果。它是最底层的执行器对 Agent 透明对 Orchestrator 可控。关键设计Agent 完全不知道 workflow、step、run_id 这些概念。上下文由 Orchestrator 通过环境变量注入给 openryAgent 全程无感。3.2 跨平台 Shell 策略平台优先 Shell回退WindowsPowerShell 7cmd.exemacOS/bin/zsh/bin/bashLinux/bin/sh/bin/bashWindows 上选择 PowerShell 7 的原因处理嵌套引号和管道符最稳定避免 cmd.exe 的引号地狱。3.3 数据存储使用 SQLite 作为本地数据层两张核心表命令日志表记录每一次命令转发的完整信息命令内容、退出码、标准输出、错误输出、耗时任务状态表记录每个 run_id 的当前状态进行中、已完成、已失败和 Agent 提交的 Payload 数据两张表互不依赖各司其职。Orchestrator 通过查询这两张表就能完整掌握所有 Agent 的行为轨迹。四、Phase 1 核心能力Phase 1 聚焦于最核心的三件事执行命令、更新状态、传递 Payload。4.1 命令转发Agent 调用openry -c 命令openry 自动检测当前平台选择最优 Shell 执行命令捕获标准输出、错误输出和退出码将结果以简洁 JSON 返回给 Agent。Agent 看到的响应极其精简——只包含 exit_code、stdout、stderr、duration_ms 四个字段。它不知道这条记录同时被写入了 SQLite更不知道自己的 run_id 是什么。4.2 状态更新Agent 完成任务后必须显式调用openry --status completed来声明完成。如果失败则调用openry --status failed。这个设计的关键在于Agent 说自己完成了但我们默认它不可信。状态写入 SQLite 后由 Orchestrator 执行硬代码验证规则比如检查指定文件是否真的被创建了通过后才算真正完成。4.3 Payload 传递Workflow 中多个步骤之间需要传递数据。比如发邮件的第一步获取了 message_id第二步编辑草稿时需要用到这个 ID。Agent 通过openry --status completed --payload {message_id:xxx}将数据提交Orchestrator 在启动下一个 step 时自动注入。4.4 实测验证以下是在 macOS 上的实际终端输出基础命令转发$ openry -c echo hello world {exit_code: 0, stdout: hello world\n, stderr: , duration_ms: 4}复杂命令$ openry -c ls -la openry/ {exit_code: 0, stdout: total 64\n-rw-r--r-- cli.py\n-rw-r--r-- executor.py\n..., stderr: , duration_ms: 9}带环境变量注入模拟 Orchestrator$ OPENRY_RUN_IDtest-001 OPENRY_WORKFLOWdemo \ OPENRY_STEP_IDcheck openry -c echo building... {exit_code: 0, stdout: building...\n, stderr: , duration_ms: 4}状态更新 Payload$ OPENRY_RUN_IDtest-001 openry --status completed \ --payload {message_id:abc123} {status: completed, payload: {message_id: abc123}, acknowledged: true}从输出可以看到Agent 收到的 JSON 干净简洁不包含任何 workflow 元数据。而 SQLite 中已正确记录commands_log (3, test-001, demo, check, echo building..., 0) task_state (test-001, demo, check, completed, {message_id:abc123}, ...)五、软刹车机制软刹车的核心思路openry 不只做透明转发它可以在特定条件下修改返回给 Agent 的内容引导 Agent 停止操作。具体做法当 Orchestrator 检测到当前 step 的调用次数超过阈值、耗时过长或 Token 预算耗尽时openry 不再返回命令的真实执行结果而是返回{exit_code:0,stdout:User requested immediate stop,stderr:,duration_ms:0}Agent 的 System Prompt 中提前约定如果你收到的 stdout 内容是 “User requested immediate stop”你必须立即停止当前操作调用 openry --status completed 或 openry --status failed不得继续执行任何命令。这比在 JSON 中增加额外字段更优雅——Agent 不需要理解新的协议字段它只是在读取命令输出这个已有的行为路径上被引导。对于 LLM 来说stdout 里的自然语言指令是最自然的刹车信号。六、项目结构Phase 1 的 Python 包只包含 6 个模块依赖极简一个 pyyaml其余全部标准库cli命令行入口参数解析主流程编排executor跨平台命令执行Shell 检测与选择dbSQLite 初始化、命令日志写入、任务状态更新configYAML 配置文件加载合并默认值utils时间戳生成、输出截断、编码安全处理七、下一步Phase 2Phase 1 解决了手的问题。Phase 2 将构建 Orchestrator编排引擎核心能力包括Workflow YAML 配置用声明式语法定义 big_step → sub_step 的树形结构每个 step 可配置验证规则和路由策略巡查循环Orchestrator 作为守护进程每 N 秒扫描 SQLite调度 queued 任务检测僵死进程并自动重置硬代码验证Agent 说完成了先跑一遍文件存在性检查、命令回归测试、Payload 完整性校验再说并发控制Worker Pool 管理同一 workflow 可多实例并行执行实例内 big_step 和 sub_step 严格串行八、总结OpenRY Phase 1 做的事情非常简单在所有 Agent 和系统命令之间插入一个可控的中间层。这个中间层对 Agent 几乎透明它只看到简洁的 JSON 返回但对硬代码完全可控所有行为被记录、所有状态被追踪、关键节点可干预。这就像一个沙箱——Agent 在里面可以自由思考但每一次伸手触碰外部世界都必须经过我们的安检门。Agent 应该动脑不应该动手。手动得越多系统越不可控。把手指砍掉换上我们能控制的那一根。项目地址[GitHub] | 设计文档design/phase1-command-forwarder.mdgithub暂时无法上传明日再试试。
【开发Day 1】给 AI Agent 戴上镣铐跳舞——OpenRY 命令转发器从 0 到 1
发布时间：2026/7/17 21:48:37
从控制Agent的手开始构建ReAct Agent的命令转发器本文记录了 OpenRY 项目 Phase 1 的设计思路——一个跨平台的命令转发器用于在 ReAct Agent Workflow 体系中实现对 Agent 行为的硬约束。一、问题的原点Agent 的手不可信在基于 ReAct 模式的 AI Agent 开发中一个反复出现的痛点是Agent 太自由了。以 OpenCLaw 或 Claude Code 这类 Agent 框架为例Agent 可以自由调用ls、cat、python、curl等任何系统命令。这种自由带来了三个致命问题问题 1状态机断裂Agent 完成一个步骤后可能不发送状态更新、发送错误的状态码、或者发送了但格式不对。硬代码无法判断当前步骤到底完成了没有整个 Workflow 流程卡死。问题 2无限循环烧 TokenAgent 在某个步骤中陷入工具调用 → 结果 → 思考 → 再调用的死循环。没有外部刹车机制一次对话轻松烧掉几十美元的 Token 费用。问题 3虚假完成Agent “认为自己完成了任务但实际上产物缺失、数据错误。它自信满满地告诉编排器我做好了”而下一个步骤拿到错误输入后全线崩溃。根因只有一个Agent 同时拥有大脑推理和双手执行命令没有任何中间层做约束。二、解法命令转发器模式我们的核心思路是把 Agent 的手砍掉换上一个可控的假肢。改造前Agent 直接调用系统命令完全自由。改造后所有动手操作必须通过openry这个中间层转发Agent 不再直接接触系统。这样做的好处能力实现方式强制状态机Agent 完成步骤后必须显式声明完成状态硬代码可查询验证软刹车openry 可以修改返回内容告知 Agent 立即停止当前操作命令白名单不同 step 可限制允许的命令集合Phase 2免费审计所有命令调用自动记录完整可追溯调用计数每个 step 的 openry 调用次数可统计超限可熔断三、架构设计3.1 三层分离整个系统分为三层Orchestrator硬代码负责路由、验证、调度。它加载 Workflow 配置决定每一步做什么验证 Agent 是否真正完成了任务。Agent大脑只管推理和决策。它不知道 workflow 是什么、当前在第几步、run_id 是什么。它只收到当前任务的描述然后用 openry 干活。openry手执行命令、记录日志、返回结构化结果。它是最底层的执行器对 Agent 透明对 Orchestrator 可控。关键设计Agent 完全不知道 workflow、step、run_id 这些概念。上下文由 Orchestrator 通过环境变量注入给 openryAgent 全程无感。3.2 跨平台 Shell 策略平台优先 Shell回退WindowsPowerShell 7cmd.exemacOS/bin/zsh/bin/bashLinux/bin/sh/bin/bashWindows 上选择 PowerShell 7 的原因处理嵌套引号和管道符最稳定避免 cmd.exe 的引号地狱。3.3 数据存储使用 SQLite 作为本地数据层两张核心表命令日志表记录每一次命令转发的完整信息命令内容、退出码、标准输出、错误输出、耗时任务状态表记录每个 run_id 的当前状态进行中、已完成、已失败和 Agent 提交的 Payload 数据两张表互不依赖各司其职。Orchestrator 通过查询这两张表就能完整掌握所有 Agent 的行为轨迹。四、Phase 1 核心能力Phase 1 聚焦于最核心的三件事执行命令、更新状态、传递 Payload。4.1 命令转发Agent 调用openry -c 命令openry 自动检测当前平台选择最优 Shell 执行命令捕获标准输出、错误输出和退出码将结果以简洁 JSON 返回给 Agent。Agent 看到的响应极其精简——只包含 exit_code、stdout、stderr、duration_ms 四个字段。它不知道这条记录同时被写入了 SQLite更不知道自己的 run_id 是什么。4.2 状态更新Agent 完成任务后必须显式调用openry --status completed来声明完成。如果失败则调用openry --status failed。这个设计的关键在于Agent 说自己完成了但我们默认它不可信。状态写入 SQLite 后由 Orchestrator 执行硬代码验证规则比如检查指定文件是否真的被创建了通过后才算真正完成。4.3 Payload 传递Workflow 中多个步骤之间需要传递数据。比如发邮件的第一步获取了 message_id第二步编辑草稿时需要用到这个 ID。Agent 通过openry --status completed --payload {message_id:xxx}将数据提交Orchestrator 在启动下一个 step 时自动注入。4.4 实测验证以下是在 macOS 上的实际终端输出基础命令转发$ openry -c echo hello world {exit_code: 0, stdout: hello world\n, stderr: , duration_ms: 4}复杂命令$ openry -c ls -la openry/ {exit_code: 0, stdout: total 64\n-rw-r--r-- cli.py\n-rw-r--r-- executor.py\n..., stderr: , duration_ms: 9}带环境变量注入模拟 Orchestrator$ OPENRY_RUN_IDtest-001 OPENRY_WORKFLOWdemo \ OPENRY_STEP_IDcheck openry -c echo building... {exit_code: 0, stdout: building...\n, stderr: , duration_ms: 4}状态更新 Payload$ OPENRY_RUN_IDtest-001 openry --status completed \ --payload {message_id:abc123} {status: completed, payload: {message_id: abc123}, acknowledged: true}从输出可以看到Agent 收到的 JSON 干净简洁不包含任何 workflow 元数据。而 SQLite 中已正确记录commands_log (3, test-001, demo, check, echo building..., 0) task_state (test-001, demo, check, completed, {message_id:abc123}, ...)五、软刹车机制软刹车的核心思路openry 不只做透明转发它可以在特定条件下修改返回给 Agent 的内容引导 Agent 停止操作。具体做法当 Orchestrator 检测到当前 step 的调用次数超过阈值、耗时过长或 Token 预算耗尽时openry 不再返回命令的真实执行结果而是返回{exit_code:0,stdout:User requested immediate stop,stderr:,duration_ms:0}Agent 的 System Prompt 中提前约定如果你收到的 stdout 内容是 “User requested immediate stop”你必须立即停止当前操作调用 openry --status completed 或 openry --status failed不得继续执行任何命令。这比在 JSON 中增加额外字段更优雅——Agent 不需要理解新的协议字段它只是在读取命令输出这个已有的行为路径上被引导。对于 LLM 来说stdout 里的自然语言指令是最自然的刹车信号。六、项目结构Phase 1 的 Python 包只包含 6 个模块依赖极简一个 pyyaml其余全部标准库cli命令行入口参数解析主流程编排executor跨平台命令执行Shell 检测与选择dbSQLite 初始化、命令日志写入、任务状态更新configYAML 配置文件加载合并默认值utils时间戳生成、输出截断、编码安全处理七、下一步Phase 2Phase 1 解决了手的问题。Phase 2 将构建 Orchestrator编排引擎核心能力包括Workflow YAML 配置用声明式语法定义 big_step → sub_step 的树形结构每个 step 可配置验证规则和路由策略巡查循环Orchestrator 作为守护进程每 N 秒扫描 SQLite调度 queued 任务检测僵死进程并自动重置硬代码验证Agent 说完成了先跑一遍文件存在性检查、命令回归测试、Payload 完整性校验再说并发控制Worker Pool 管理同一 workflow 可多实例并行执行实例内 big_step 和 sub_step 严格串行八、总结OpenRY Phase 1 做的事情非常简单在所有 Agent 和系统命令之间插入一个可控的中间层。这个中间层对 Agent 几乎透明它只看到简洁的 JSON 返回但对硬代码完全可控所有行为被记录、所有状态被追踪、关键节点可干预。这就像一个沙箱——Agent 在里面可以自由思考但每一次伸手触碰外部世界都必须经过我们的安检门。Agent 应该动脑不应该动手。手动得越多系统越不可控。把手指砍掉换上我们能控制的那一根。项目地址[GitHub] | 设计文档design/phase1-command-forwarder.mdgithub暂时无法上传明日再试试。
