PRAXIST Agent Runtime 全解析:claude_sdk 与 codex_sdk 适配器架构、Provider 路由与推理策略
PRAXIST Agent Runtime 全解析:claude_sdk 与 codex_sdk 适配器架构、Provider 路由与推理策略
导读
Agent Runtime 是 PRAXIST 自主研究系统中真正驱动“研究同伴(peer)”执行的那一层:它消费统一的 AgentRunRequest,翻译 PRAXIST 的提示词、模型、工具、缓存、沙箱与超时意图,把 SDK 产生的各类事件归一化为标准 AgentEvent,最终返回结构化的 AgentRunResult。本文以 docs/guides/agent-runtimes.md 为骨架,结合仓库内两个生产级运行时的真实源码实现,系统讲解 Runtime 契约、Claude SDK 的存活监控、Codex SDK 的长连接 App-Server 架构、API Provider 中继路由与 reasoning_effort 推理策略,并给出安装、选择与适配器开发清单。读完本文,你将掌握 PRAXIST 运行时体系的工作原理、两个运行时之间的能力差异,以及如何在自己的任务项目中正确配置和选择它们。
统一 Runtime 契约:一次 Agent 执行的生命周期
PRAXIST 对“运行时”的定位非常清晰:运行时控制 Agent 会话本身,而 API Provider(model_provider:* 插件)单独描述 API 形态、端点、模型默认值与凭据。两者职责分离,这也是多个运行时能够共存而不互相干扰的设计基础。
三类核心协议对象
在 praxist/core/protocol.py 中定义了贯穿运行时执行全过程的三个序列化数据契约:
AgentRunRequest:由工作流阶段(workflow stage)构造的完整执行请求,包含request_id、run_id、stage_id、role_ref、agent_runtime_ref、提示词引用、工作目录cwd、ModelCallSpec(模型与 Provider 调用配置)、ToolPermissionSet(工具许可集)、tool_servers(MCP 工具服务器清单)、EnvPolicy、credential_ref、timeout_seconds、CachePolicy以及自由扩展的runtime_options字典。AgentEvent:运行时在执行过程中发出的归一化事件,携带event_id、type、payload、artifact_refs与credential_refs,用于轨迹记录(trajectory)与回放(replay)。AgentRunResult:归一化的最终结果,包含success、events、text_output_refs、tool_uses、error、failover_reason、usage、cost以及terminal_status、timed_out、cancelled等终态标记。
值得一提的是,AgentRunRequest 被设计为完整可序列化的执行契约;进程内共享的句柄(已实例化的工具服务器、消息回调、停止轮询、作用域化环境)则单独放进 AgentRuntimeExecutionContext(见 praxist/core/runtimes.py),因为这类对象无法安全地放进 JSON。
生产运行时必须承担的八项职责
原文档给出的 Runtime Contract 明确要求每个生产运行时适配器负责:
- 翻译 PRAXIST 的提示词、模型、工具、缓存、沙箱与超时意图;
- 只暴露被选中的 MCP 工具服务器,绝不泄漏 API Provider 的响应对象;
- 归一化助手文本、工具调用/结果、错误、用量(usage)与终态;
- 保留取消(cancellation)与超时(timeout)状态;
- 在事件进入轨迹或日志前对凭据做脱敏(redaction);
- 在其声明的容量内支持并发的长时间运行的 peer 会话;
- 运行时必须在无法支持某个契约或遇到未知用量时明确报告,而不是假装能力存在。
这个“明确拒绝而非伪装”的纪律在 Codex 运行时里体现得尤其明显:当请求要求一个可证明无 Shell 的运行时(require_no_shell_runtime)时,codex_sdk 会直接拒绝——因为 Codex 自带 Shell 表面,无法等效于 Claude SDK 的行为,详见后文。
从实现角度看,praxist/core/runtimes.py 中的 execute_runtime() 统一了调用入口:生产运行时实现异步 execute(request, context),而确定性测试插件可以只实现较小的同步 execute_sync(request) 契约供一致性测试使用;RuntimeUsageCollector 则负责在上下文(ContextVar)中聚合用量,并在结果产生时自动收集 usage 与 cost。
内置运行时总览
PRAXIST 仓库随附三种运行时插件,全部以 agent_runtime:* 插件引用形式注册:
| 插件引用 | 定位 |
|---|---|
agent_runtime:claude_sdk |
默认且推荐的生产运行时,面向新任务项目,在 claude-agent-sdk==0.2.136 上完成测试 |
agent_runtime:codex_sdk |
显式选用的生产运行时,构建于官方 openai-codex==0.147.0 Python SDK 之上 |
agent_runtime:fake_runtime |
确定性的离线运行时,仅用于一致性测试(conformance tests) |
需要注意:选择 codex_sdk 并不会改变既有任务的默认运行时——每个任务项目在启动时通过解析(resolve)流程显式决定使用哪个运行时,默认值对老任务保持不变。
fake_runtime 的作用可以从 tests/conformance/test_core_plugin_contracts.py 中看到:它对同一请求的两次 execute_sync 返回完全一致的结果(确定性),且与 claude_sdk 的 execute_sync 共享同一组归一化事件类型(agent_run_started、assistant_text、final_result),从而离线验证所有运行时的事件形状一致。
Claude SDK 运行时:隔离工作线程与存活监控
独立事件循环的隔离执行
agent_runtime:claude_sdk 的实现位于 praxist/plugins/agent_runtimes/claude_sdk/adapter.py。关键设计是:每个 Claude SDK 会话在独立的守护线程(daemon thread)上运行自己的事件循环。原因在源码注释中写得很清楚——Claude SDK 的流消费、进程内 MCP 回调与 hooks 会产生持续的突发负载,如果放在研究循环(research loop)的同一事件循环上,一个会话就可能延迟所有 peer 的生成计时器。通过 _execute_legacy_isolated() 把每个会话放到独立事件循环,同时保留研究循环对超时与取消的最终权威。
Liveness:区分“真卡死”与“健康的长任务”
这是 Claude 运行时最精细的机制之一,实现位于 praxist/plugins/agent_runtimes/claude_sdk/liveness.py 的 ClaudeSessionLiveness。适配器把以下内容作为独立的进度信号分别跟踪:
- 完整的 SDK 消息(
sdk_complete_message_progress_at); - 模型流的部分事件(
model_stream_progress_at,仅用于可观测性,不会复制进权威 Agent 转录); - 前台工具活动(
tool_progress_at); - 受保护的后台工作(通过
record_background_status跟踪running/completed/failed/killed/stopped等状态)。
观察到的会话状态(session_state)共有五种:model_waiting、foreground_tool_running、background_work_running、closing、idle。只有当状态为 model_waiting 且所有进度源在警告间隔内(源码常量 _SDK_STALL_WARNING_SECONDS = 300.0 秒,见 adapter.py)持续沉默时,才会发出存活警告。一个长时间运行的前台工具或活跃后台任务会被报告为低频的健康工作状态,而不是 SDK 流停滞。
ClaudeSessionLiveness.observation() 输出的健康记录只包含工具名称和后台任务数量,绝不包含工具输入、命令、任务 ID 等敏感负载——这与 Runtime Contract 的脱敏要求一致。更重要的是:这些观测不会延长或替代已配置的运行时超时、生成截止时间、停止请求或取消路径。相关单元测试 tests/unit/test_claude_sdk_liveness.py 验证了前台工具状态机、后台任务终态汇总以及完整/部分消息时钟的独立推进。
运行时保护措施
Claude 适配器还集成了若干运行时保护:PreToolUse hook 上的 delete guard(对 Bash/Write/Edit 等危险工具的失败关闭式校验)、生成关闭哨兵(ORCHESTRATOR_SHUTDOWN、STOP_SIGNAL 等)对新的后台工作与求值器启动的冻结,以及 require_no_shell_runtime 模式下禁用 Shell 与写工具的只读规划模式(DIG-Lite)。
Codex SDK 运行时:长连接 App-Server 架构
agent_runtime:codex_sdk 的实现位于 praxist/plugins/agent_runtimes/codex_sdk/adapter.py,它是理解“生产级运行时”的最佳范本。
共享长连接客户端 + 独立临时线程
与传统“每 peer 每轮拉起一条全新 CLI 命令”的方式不同,Codex 运行时使用长生命的本地 Codex App-Server 客户端:一个 agent runtime / API provider / 凭据作用域(scope)可以共享同一个客户端,而每个请求获得一个独立的临时(ephemeral)Codex 线程(thread_start(..., ephemeral=True))。适配器消费 App-Server 的类型化通知(typed notifications),并映射为 PRAXIST 事件。
客户端按 _ClientKey(run_scope, provider, credential_digest, reasoning_policy) 分组缓存(_clients 字典),凭据摘要参与分组,意味着不同 API key 或不同推理策略会自然隔离为不同客户端。若某个客户端被标记为 unhealthy,它会被替换而不牵连同一客户端上其他仍然健康的并发线程(_release_client 只在该客户端无活跃线程时关闭它)。
事件消费与归一化
codex_sdk/_events.py 中的 CodexEventCollector 负责把 App-Server 的各类通知(item/started、item/completed、thread/tokenUsage/updated、turn/started、turn/completed、error)转换为 AgentEvent。当 SDK 发布流式助手文本、工具调用、推理、计划、文件变更、用量与终态通知时,运行时都会转发;工具项类型覆盖 commandExecution、dynamicToolCall、mcpToolCall、webSearch。
停止、超时与受控排空
当收到 PRAXIST 的停止请求或到达截止时间时,_consume_turn 会先调用 turn.interrupt()(在 _INTERRUPT_REQUEST_SECONDS = 2.0 秒内完成中断请求),随后对消费者任务执行有界排空(_INTERRUPT_DRAIN_SECONDS = 5.0 秒),超时未排干的任务会被标记为 detached 并记录观测。中断失败的线程会把客户端标记为 unhealthy。
私有工作线程池与有界流并发
官方异步 SDK 会把每次阻塞的通知读取委托给进程级默认执行器;为避免大型 peer 队列饿死无关的 PRAXIST 异步工作,运行时创建了专有线程池(128 个 worker) 并用信号量把活跃流并发限制在 112(_SDK_IO_WORKERS、_MAX_ACTIVE_STREAMS,见 adapter.py 顶部常量)。每个请求在获取流信号量后才启动线程,结束或异常时释放。
运行作用域状态与认证
- 状态目录:运行时作用域状态位于
<run_dir>/runtime_state/codex_sdk/之下(_state_dir()),每个客户端的私有 home、sqlite、日志与 relay 日志都隔离在该目录内。 - 认证双路径:支持原生 OpenAI 认证——通过
OPENAI_API_KEY,或者通过 SDK 捆绑的 Codex 二进制持有的已保存 ChatGPT 登录(Codex-native 模式)。后者会校验CODEX_HOME、verify_chatgpt_login(),并把操作员 home 暂存(staged)到私有的一次性临时目录,App-Server 关闭后即清除,绝不写入任务文件、运行产物、日志或回放。 - 模型目录探测:
available_chatgpt_models()与verify_chatgpt_model_available()实现只读的账户模型目录探测,让 Codex-native 模式的启动器在启动 peer 队列前就拒绝不支持的显式模型(如示例中的gpt-5.6-luna)。
MCP 直连与工具许可翻译
选中的 PRAXIST 工具服务器被直接作为 stdio MCP 服务器附加到 App-Server(见 codex_sdk/_mcp.py),工具 allow/deny 元数据被翻译进 App-Server 配置,运行时契约中不包含任何 Shell 桥接。
沙箱意图翻译
codex_sdk/_sandbox.py 把 PRAXIST 的运行时中性沙箱意图(RuntimeSandboxIntent,三轴:filesystem ∈ {read_only, workspace_write, full}、network ∈ {off, on}、approval ∈ {auto, on_risk, always_ask},定义见 praxist/core/protocol.py)映射为 Codex SDK 的 read_only / workspace_write / full_access 沙箱。注意两个显式约束:
codex_sdk是无头(headless)运行时,不能支持交互式批准模式,approval != auto会被拒绝;- 全访问沙箱下不能关闭网络(
full + off被拒绝)。
同时,Read/Glob/Grep 等只读工具要么依赖 Bash 权限,要么依赖只读沙箱,二者皆无时会被显式拒绝——这再次体现了“无法支持就明确报告”的契约纪律。
严格输出 Schema 兼容
Codex 线程严格遵守调用方的 output_schema。当已知的非严格对象 schema 缺少 additionalProperties: false 时(_contains_non_strict_object_schema()),PRAXIST 会把它从首个端点请求中省略,而不是发起一个注定被拒绝的调用;既有的提示词解析与任务校验保持有效,并记录一条 runtime_warning 说明该兼容性回退。无关的 API Provider 错误与严格 schema 错误不会被重试或隐藏。任务项目不应使用模型专属 schema 适配器去遮蔽捆绑运行时。
用量上报与无 Shell 请求
- 只有 App-Server 发布 token 用量通知时,用量才精确;否则走 PRAXIST 标准的
usage_unknown行为(运行时插件清单声明usage_reporting: usage_or_usage_unknown)。提示词缓存行为由 agent runtime/API provider 管理。 - 由于 Codex 内置 Shell 表面,要求可证明无 Shell 的请求会被直接拒绝,而不是伪装成与 Claude SDK 行为等价。
无损 Finding 事件批处理
在 Codex-native 模式运行中,PRAXIST 会自动在独立线程之间使用无损 finding 事件批处理:保留完整任务契约与规范产物,提供更大的有界未见 finding 引用集合,仅在需要时要求续接会话重新打开精确原文。这减少了重复的线程引导开销,又不会保留无限增长的 Codex 会话或依赖有损压缩。停止、关闭、资源供给、超时与恢复语义均保持不变。更完整的上下文效率策略见 docs/guides/cost-optimization.md:自动策略适用于 Codex-native 模式与 OpenRouter/OrcaRouter 路由,直接 DeepSeek 路由被显式排除。
能力对照与差异
两个生产适配器瞄准同一个 PRAXIST 请求/结果契约,但并非可互换的实现:
| 能力 | claude_sdk |
codex_sdk |
|---|---|---|
| 选中的 PRAXIST MCP 工具 | 直接 SDK MCP 集成 | 直接 App-Server stdio MCP 集成 |
| 流式 | 由 Claude SDK 消息归一化 | 由类型化 App-Server 通知归一化 |
| 超时与停止 | 运行时专属取消路径 | 线程中断 + 有界通知排空 |
| 用量 | SDK/API Provider 暴露时记录;否则 unknown | 存在 token 用量通知时记录;否则 unknown |
| 沙箱意图 | Claude SDK 权限/沙箱集成 | Codex 只读/工作区/全访问映射;内置 Shell 仍是运行时的一部分 |
| 长运行并发 | 独立的并发 peer 会话 | 共享长连接客户端上的独立线程,带有限流并发 |
| 非原生 API Provider | Claude SDK/API Provider 兼容路径 | 对受支持的 Chat Completions API Provider 走 Responses-to-Chat 中继 |
正如原文档强调的:不要声称两者行为完全等价。工具命名、事件粒度、沙箱能力、缓存行为、API Provider 错误与用量可用性都保留 SDK 专属特征,PRAXIST 只是归一化了它们的持久化结果形态。
API Provider 路由:codex-relay 私有中继
Codex App-Server 消费的是 Responses 协议。因此,凡是只暴露 Chat Completions 的 API Provider,PRAXIST 都会为其启动运行作用域(run-scoped)的私有 codex-relay,把 Responses 请求翻译成 Chat Completions:
| API Provider 形态 | Codex SDK 路径 |
|---|---|
OpenAI / model_provider:openai_compatible |
直接 SDK/App-Server 连接 |
model_provider:deepseek_alias |
运行作用域私有 codex-relay → DeepSeek Chat Completions |
model_provider:openrouter |
运行作用域私有 codex-relay → OpenRouter Chat Completions |
model_provider:orcarouter |
运行作用域私有 codex-relay → OrcaRouter Chat Completions |
model_provider:cloudflare |
运行作用域私有 codex-relay → Cloudflare Workers AI Chat Completions |
model_provider:groq_alias |
运行作用域私有 codex-relay → Groq Chat Completions |
model_provider:mistral_alias |
运行作用域私有 codex-relay → Mistral Chat Completions |
model_provider:xai_alias |
运行作用域私有 codex-relay → xAI Chat Completions |
这与插件清单 codex_sdk/plugin.yaml 中 compatible_model_providers 的声明完全对应(注意 Cloudflare 无 Anthropic 路由,因此刻意不出现在 claude_sdk 的允许列表中)。
Relay 的运维纪律
codex_sdk/_relay.py 展示了实现的细节:
- 生命周期由 PRAXIST 负责:PRAXIST 启动与停止 relay,操作员不得按 peer 单独拉起 relay;
- 安全边界:relay 只监听临时本地端口(
http://127.0.0.1:<port>/v1),且只接收被选中 API Provider 的那一份凭据;未在运行时插件中声明兼容的 API Provider 必须在解析或启动阶段失败,而不是被静默重路由; - OpenRouter 粘性路由:仅对 OpenRouter,relay 追加一个哈希后的运行作用域
session_id(praxist-<sha256 前 32 位>),用于粘性路由与提示词缓存局部性;但不启用响应缓存(研究回复与工具调用不能被逐字重放); - DeepSeek 推理覆盖:仅当任务选择了显式策略时才注入 DeepSeek relay 推理覆盖;
auto保留既有路由行为。
中继二进制 codex-relay 由 praxist<a href="https://link.gitcode.com/i/1c81d7826a4892ae9febed8e4a17e79f" target="_blank">codex] extra 固定版本提供(codex-relay==0.5.5),源码注释还提示 relay 二进制会优先寻找 sys.executable 同级目录,其次才回退到 PATH。更多凭据细节见 [docs/guides/credentials.md。
Reasoning Policy:跨 Provider 的推理策略
任务项目可以在 task.yaml 或运行时选项中为所有 API Provider 上的每个 peer、PI、Chair 与 Deep Innovation Gate(DIG)规划调用统一设置一条推理策略:
agent:
reasoning_effort: max # auto | off | low | high | max
取值语义
max(默认值,新老任务省略该字段时都生效):请求所选路由支持的最强推理级别;auto:显式选择 API Provider / agent runtime 的原生默认;off:在路由支持该控制时显式禁用模型推理;low/high:请求对应档位的推理努力;- 兼容旧设置:
premium_mode: true在reasoning_effort为auto时仍等价于max;显式的非auto策略优先。
该策略的解析入口在 praxist/core/runtimes.py:REASONING_EFFORT_POLICIES = {"auto", "off", "low", "high", "max"},effective_reasoning_effort() 处理非法值回退与 premium_mode 兼容逻辑。任务项目契约中的位置见 docs/guides/task-projects.md(agent.reasoning_effort 一节)。
各路由的映射方式
claude_sdk+ DeepSeek:映射到 DeepSeek 的 Anthropic 兼容字段——thinking.type为enabled或disabled,启用时携带所选 effort(adapter.py 中_claude_reasoning_options()对 DeepSeek 使用{"type": "enabled", "budget_tokens": 1024},DeepSeek 接受该字段用于兼容并忽略其值);其他 Claude 兼容 API Provider 保留原生 adaptive-thinking 映射;codex_sdk+ DeepSeek:运行作用域私有 relay 把同一策略注入 Chat Completions 请求,并在工具调用子请求间保留 API Provider 的推理状态——PRAXIST 不总结也不重建该状态;- 原生 Codex 模型(包括 Codex-native
gpt-5.6-luna):取 SDK 支持的最接近档位(max映射为xhigh); - OpenRouter / OrcaRouter relay 路由:使用统一的
reasoning.effort对象。
需要注意:模型契约要求推理的 API Provider 可能拒绝 off;此时 PRAXIST 会把该 API Provider 错误如实呈现给用户,并保持用户的策略不变。推理控制会改变模型行为,可能影响延迟、输出 token 用量与成本,但不会改变任务证据、晋级、超时或生成关闭契约。
安装与选择运行时
安装 Codex 运行时 extra
python -m pip install 'praxist[codex]'
该 extra 在 pyproject.toml 中固定了 openai-codex==0.147.0、claude-agent-sdk==0.2.136 与 codex-relay==0.5.5,并包含捆绑 PRAXIST 工具所用的 MCP 依赖。这些版本是经过测试的运行时兼容基线:升级时只能与 PRAXIST 运行时验证一起进行。extra 不会安装独立的任务环境。
选择运行时的三种途径
运行时可以通过设置档案(setup profile)、任务配置或显式启动覆盖来选择:
- 设置档案与首次使用档案选择见 Quickstart;
- 任务配置中的插件引用见 docs/guides/task-projects.md(
task.yaml中的 plugin refs 声明 agent runtime 引用); - 显式启动覆盖的完整命令行选项见 CLI Reference,常用形态如:
praxist start --task-path /path/to/task \
--runtime agent_runtime:codex_sdk \
--model-provider model_provider:openai_compatible
Codex-native 模式(使用已保存 ChatGPT 登录、无需 API key)的命令示例见 docs/guides/operators.md(praxist doctor --codex-native 与 praxist start --codex-native ...)以及 docs/guides/credentials.md。凭据所有权、认证优先级、私有 Codex home 与校验也由 docs/guides/credentials.md 管理——例如直接 DeepSeek 路由用 DEEPSEEK_API_KEY + agent_runtime:claude_sdk,而显式选择 codex_sdk 时同一把 key 会被作用域化到私有运行级 codex-relay。
直接使用 Agent Skill
面向人类的 Codex 或 Claude Code CLI 可以直接调用捆绑的 PRAXIST skills。这个操作员宿主(operator host)独立于 peer 运行时:即使操作员工作流由 Claude Code 承载,已保存的 Codex ChatGPT 登录仍可为显式选择原生 OpenAI 的官方 Codex SDK 运行时提供认证。peer 执行仍然通过 PRAXIST 拥有的运行时客户端进行,而不是挂接到交互式操作员会话上。
Adapter Checklist:新增或修改运行时适配器
原文档以清单形式给出了严格的适配器开发流程,任何新增或修改运行时适配器都必须依次完成:
- 接受运行时中性的请求/上下文契约;
- 翻译模型、提示词、MCP、沙箱、缓存、超时与工具选项;
- 发出归一化的类型化事件与归一化的终态结果;
- 用量可用时记录,否则记录 unknown 用量;
- 脱敏密钥与 API Provider 响应对象;
- 保留取消、超时与并发线程隔离;
- 增加离线一致性测试 + 聚焦的 API Provider/MCP 集成覆盖;
- 文档化能力差异,而不是声称跨 SDK 等价。
这套清单与一致性测试体系互相印证:execute_sync() 的确定性转录让 agent_runtime:fake_runtime 与 claude_sdk/codex_sdk 能在离线状态下验证事件形状(见 tests/conformance/test_core_plugin_contracts.py 与 tests/conformance/test_codex_sdk_runtime_conformance.py)。
结语
PRAXIST 的运行时层用一套紧凑的请求/事件/结果协议把两个差异巨大的官方 SDK 统一起来:claude_sdk 以隔离事件循环与精细的存活监控见长,codex_sdk 则以长连接 App-Server、私有中继路由与有界并发支撑起大规模 peer 队列。理解 Runtime Contract 中“明确报告不支持能力”的纪律、Provider 路由中的 codex-relay 边界以及 reasoning_effort 的逐路由映射,是正确运维与研究调优的前提——无论你运行的是默认的 claude_sdk,还是为无 key 的 Codex-native 模式显式选择的 codex_sdk。