Codex Harness 上下文引擎移植规范

本文档是将 OpenClaw context-engine 插件生命周期接入 Codex app-server harness 的设计规范（草稿状态）。

目标

使 codex/* 模型或 embeddedHarness.runtime: "codex" 会话能够遵循与嵌入式 PI 相同的 context-engine 生命周期契约，让 lossless-claw 等插件控制上下文组装、摄取和压缩策略。

当前架构

嵌入式运行循环在选择 harness 前解析 context engine：

src/agents/pi-embedded-runner/run.ts — 初始化 context-engine 插件
src/agents/harness/selection.ts — harness 选择
extensions/codex/src/app-server/run-attempt.ts — Codex harness 实现

当前缺口：Codex harness 不调用 contextEngine.bootstrap、assemble、afterTurn、ingest 或 maintain。

期望生命周期

读取镜像的 OpenClaw 会话 transcript
调用 context engine bootstrap（当 session 文件存在时）
调用 assemble 组装上下文
将组装结果投影为 Codex 兼容输入（developer instructions + prompt text）
启动/恢复 Codex thread
镜像 Codex 结果回 OpenClaw transcript
调用 afterTurn 或 ingestBatch/ingest
成功轮次后运行 turn maintenance

实现计划

1. 提取中性 context-engine 辅助模块

将 PI runner 下的生命周期辅助函数迁移到 harness 中性路径：

src/agents/harness/context-engine-lifecycle.ts

新函数命名（去除 PI 前缀）：

bootstrapHarnessContextEngine
assembleHarnessContextEngine
finalizeHarnessContextEngineTurn
runHarnessContextEngineMaintenance

2. 上下文投影层

新增 extensions/codex/src/app-server/context-engine-projection.ts，将 AgentMessage[] 投影为 Codex 输入：

export function projectContextEngineAssemblyForCodex(params: {
  assembledMessages: AgentMessage[];
  originalHistoryMessages: AgentMessage[];
  prompt: string;
  systemPromptAddition?: string;
}): CodexContextProjection;

投影策略：systemPromptAddition 进入 developer instructions，组装的历史上下文包裹在 prompt text 中。

3. 压缩策略

两套压缩系统并存：

OpenClaw context-engine compact()（当 ownsCompaction === true 时为主）
Codex app-server 原生 thread/compact/start（辅助，结果记录在 details.codexNativeCompaction）

设计约束

Codex app-server 仍是原生 thread 状态的权威
上下文投影输出必须字节稳定（无时间戳、无随机 ID）
harness 选择语义不变（runtime: "pi"/"codex"/"auto"）

Wiki AI

目录