[临时AI稿][2026.9.27] 从大模型包装到生产级执行宿主：OMP Agent Harness 架构设计与实现全景

文档定位：本文档是关于 omp（Oh-My-Pi）作为生产级 CLI Agent 执行宿主（Agent Harness）的系统性架构设计与实现细节全景梳理。旨在拆解其作为大模型与本地操作系统之间的核心执行容器，并明确划分上游原生（Upstream Baseline）的设计理念与本地 Fork 演进分支针对生产级高频实战场景所做的系统级加固、协议扩展与交互重构。本篇作为博客成文的系统性架构底稿。

目录

• 1. 什么是 Agent Harness：执行宿主的本质边界

• 2. 全景对比矩阵：Upstream vs. Fork 演进
• 2.1 调度韧性与会话生命周期（Scheduling & Session Lifecycle）
• 2.2 网络协议与中转反代对抗（Wire Protocol & Relay Resilience）
• 2.3 工具运行时、虚拟协议与环境扩展（Tool Runtime, Virtual URIs & Extensions）
• 2.4 检索通道与长期记忆后端（Search Channels & Memory Backend）
• 2.5 终端呈现工程与交互美学（TUI Presentation & Interaction Ergonomics）
• 2.6 运行时可观测性与计量度量（Observability & Telemetry）

• 3. 调度循环、状态生命周期与执行韧性
• 3.1 原生 ReAct 调度、上下文滑动压缩与会话 DAG
• 3.2 Fork 流式中途断连恢复机制（Mid-Stream Death Recovery）
• 3.3 Fork 子任务细粒度不可变状态机与显式续跑协议
• 3.4 Fork 启动期冷启动优化：异步 Git 状态预热

• 3.5 全局模糊检索与会话流转引擎（Fuzzy Search & Resume Engine）

• 4. 工具执行运行时、虚拟资源协议与记忆外延
• 4.1 原生工具集体系、MCP 网关与 Rust Native 加速
• 4.2 Fork 虚拟 URI 资源路由体系（agent://, history://, xd://）
• 4.3 Fork 工具调用意图（Intent）的一等公民管道穿透
• 4.4 Fork 运行时扩展机制（Extension Engine）与 Rebase 免疫架构
• 4.5 Fork 全局长程记忆双引擎：history_search 与 session_search 深度剖析
• 4.6 Fork 惰性 MCP 网关（Lazy MCP Gateway）与 Notion 深度实战
• 4.7 Wiki 知识库与 Mnemopi 本地向量双层记忆系统深度剖析
• 4.8 伴生桌面微宠守护进程（Desktop Pet Bridge）与只读工作区检查器（Workspace Inspector）
• 4.9 Browser Relay 架构深度剖析：真实浏览器接管、CDP 伪装多路复用与安全防线
• 4.10 Hashline 行级精确定位编辑引擎：告别 Patch 漂移与幻觉覆写
• 4.11 持久化 PTY 会话与 Bash 工具安全沙箱深度剖析
• 4.12 Native 性能基石：Rust 动态库（pi-natives）计算下沉架构
• 4.13 Auto-Learn 机制与 Managed Skill 智能体自进化闭环

• 5. 网络协议、中转对抗与提示词缓存保活
• 5.1 原生多 Provider 抽象与 KDL 声明式规则引擎
• [5.2 Fork 第三方 Relay 思考预算与错误容错阶梯（400 / [1210] / 始终思考）](#52-fork-第三方-relay-思考预算与错误容错阶梯400--1210--始终思考)
• 5.3 Fork Claude Code 伪装锚定与 Prompt Cache 缓存穿透根治
• 5.4 Fork 动态热重载重试规则引擎（retry-rules.json）
• 5.5 Fork 搜索通道同源复用与 Grok Relay 适配
• 5.6 Fork 协议报头穿透（Extra Betas / Codex Pins）与多 API Key 轮询凭据池
• 5.7 多 Provider 缓存计量差异与协议方言兼容深度剖析

• 6. 终端呈现工程（TUI）与人机交互交互面
• 6.1 原生 Pi-Tui 差分渲染引擎与生命周期管理
• 6.2 终端多协议图形渲染与 Kitty Unicode 占位符引擎深度剖析
• 6.3 Fork 终端排版美学重构：气泡、代码块边框与 Markdown 语法脱敏
• 6.4 Fork 交互效率跃升：Bash 历史检索、补全与全局视口跳转
• 6.5 无头终端评测工模与真实 PTY 像素级截屏（Headless Verification Rig）
• 6.6 TUI 智能输入补全体系：斜杠指令、上下文引用与 Bash 幽灵文本（Composer & Ghost Text）

• 7. 运行时可观测性与计量度量
• 7.1 原生单次调用计数与统计数据库（stats.db）
• 7.2 Fork Turn 级别聚合计量看板（work-usage.ts）
• 7.3 Fork 工具与搜索吞吐量遥测（searchThroughput）

• 8. 生产级配置全景示例（含 Claude Code 伪装、Codex 与中转实战脱敏模版）
• 8.1 智能体主配置：config.yml
• 8.2 模型与 Provider 注册表：models.yml（多协议实战）
• 8.3 热重载重试规则配置：retry-rules.json
• 8.4 惰性 MCP 配置：mcp.json（Notion 实战）

1. 什么是 Agent Harness：执行宿主的本质边界

1. 调度与状态管理（Scheduler & Lifecycle）：维护单 Turn 的 ReAct 循环，编排工具结果反馈，管理历史会话的树状分支，并在达到上下文阈值时实施智能压缩。

2. 环境与工具执行沙箱（Tool Runtime & Sandboxing）：将模型输出的 JSON 结构化动作映射为本地文件 I/O、Patch 修改、PTY 终端命令执行或 LSP 类型诊断。

3. 协议与流式网络防御（Transport & Wire Resilience）：处理跨供应商差异、思考输出隔离、流式断流恢复，以及针对中转 Relay 和 Prompt Cache 机制的底层微调。

4. 终端交互与视觉反馈（Presentation Engineering）：以极低延迟（<16ms）通过差分算法渲染 TUI，实现跨终端图像协议呈现，并保证输入法、补全与快捷键的流畅。

5. 上下文外延与长期记忆（Context Extension & Recall）：在有限的上下文窗口之外，构建开销可控的文件、Git 历史、全局会话与外部 Wiki 检索机制。

2. 全景对比矩阵：Upstream vs. Fork 演进

2.1 调度韧性与会话生命周期（Scheduling & Session Lifecycle）

2.2 网络协议与中转反代对抗（Wire Protocol & Relay Resilience）

2.3 工具运行时、虚拟协议与环境扩展（Tool Runtime, Virtual URIs & Extensions）

2.4 检索通道与长期记忆后端（Search Channels & Memory Backend）

2.5 终端呈现工程与交互美学（TUI Presentation & Interaction Ergonomics）

2.6 运行时可观测性与计量度量（Observability & Telemetry）

3. 调度循环、状态生命周期与执行韧性

3.1 原生 ReAct 调度、上下文滑动压缩与会话 DAG

上下文滑动压缩（Context Compaction）

1. 锁定最早的未保护 Turn 集合。

2. 构造专用的 Summary Prompt，调用轻量模型将早期历史提炼为结构化的摘要块（包含文件变更状态、未完成目标、已验证的结论）。

3. 用摘要块替换被裁减的历史消息，并重建会话在内存中的上下文指针。

会话 DAG 持久化

3.2 Fork 流式中途断连恢复机制（Mid-Stream Death Recovery）

1. 断连拦截与分类器：引入 matchesMidStreamDeathText，联合 @oh-my-pi/pi-utils 的 isUnexpectedSocketCloseMessage，精确捕获底层 Socket 关闭与中途断流异常。

2. 三路续跑决策：
• 若断流发生在工具调用已经全部结算之后，走 classifyResolvedInterruptedToolTurn 正常完结。
• 若未曾产生可见输出，走常规回滚重新生成。
• 核心创新：若断流发生在已提交（Committed）部分可见文本之后，触发 handlePartialStreamDeath。

3. 隐藏指示注入与防重复断言：
• 不抹除当前已生成的半截 Assistant 消息，将其封冻在转录历史中。
• 动态追加一条隐藏的系统层级指令（prompts/system/partial-stream-resume.md），以 developer 角色提示模型：“上一轮输出在传输层非预期中断，请紧密承接上文继续输出，切勿重复已生成的前半部分”。
• 设置最大递增计数器 PARTIAL_STREAM_RESUME_MAX_ATTEMPTS = 3，保障在连续异常时能够安全熔断而不死循环。

3.3 Fork 子任务细粒度不可变状态机与显式续跑协议

1. 不可变状态机快照（Immutable Phase Machine）：
设计了具有严格单向跃迁特性的 10 阶段状态机：
每次状态变迁均返回经 Object.freeze() 深度冻结的全新快照，杜绝并发竞争导致的状态污染。

2. 低开销写入与崩溃自愈：
仅当 persist: true 且阶段发生实质变化时，才将执行状态持久化到注册表，避免流式心跳刷爆转录日志；一旦进程重启或会话暂停，历史快照即可作为恢复现场的证据链。

3. 统一协议显式续跑：
在 upstream v18.3.0 彻底移除外部 hub 独立工具后，Fork 将子任务恢复机制全面升格为标准的内部 URI 协议：
write agent://<id>?resume=1
• 携带完整的延续血统（Continuation Lineage），将新 Turn 的重试指标与已沉淀的历史合并计算。
• 具备幂等调度保护：对处于排队中的恢复请求进行防抖去重，避免重复派发并发冲突。

3.4 Fork 启动期冷启动优化：异步 Git 状态预热

3.5 全局模糊检索与会话流转引擎（Fuzzy Search & Resume Engine）

1. CLI -r / --resume <term> 模糊唤醒算法（fuzzyMatchResumableSessions，Patch 6）

• 双重文本域联合检索：
对本地及全局会话列表展开扫描，提取每个会话的两个核心文本特征：会话标题（session.title）与用户首轮 Prompt 诉求（session.firstMessage）；

• 分级惩罚打分模型（Lower Score = Better Match）：
1. 连续子串匹配（Substring）：lower.indexOf(normalizedTerm)。子串匹配拥有绝对优先权，匹配位置越靠前（MatchOffset 越小）得分越好；且标题匹配权重大于首条消息匹配（首条消息增加 100 惩罚分）；
2. 离散字符子序列（Subsequence Fallback）：若未命中子串，启动 isFuzzySubsequence 检查（确保搜索词的每个字符按顺序出现在文本中）。命中子序列赋予 1,000 的保底分；
3. 项目作用域优先（Scope Boost）：当前工程本地的会话享受 0 惩罚，跨项目的全局历史会话叠加 +1 惩罚分，确保同等匹配度下本地会话恒定胜出；

• 时间衰减仲裁：当得分相同时，严格按照修改时间逆序排列（b.session.modified - a.session.modified），最近活跃的会话排在最前；

• 二元交互短路矩阵：
• 单命中（Single Match）：直接短路跳过一切 TUI 渲染与选择菜单，毫秒级直接加载目标会话进入主界面，实现“一敲即达”；
• 多命中（Multiple Matches）：自动拉起 TUI 会话选择器，但将用户的搜索词直接预填（Prefill）进交互过滤框，高亮首选项供用户快速确认或方向键筛选。

2. TUI 内部 Session Selector 虚拟化滚动与词局部匹配（packages/tui/src/fuzzy.ts）

• 词局部匹配（Word-Local Matching）：
原生通用的子序列模糊匹配容易产生严重的“离散噪音”（例如输入 "image"，长句中由于随机分散出现了 i-m-a-g-e 五个字母而被错误召回）。packages/tui/src/fuzzy.ts 引入基于单词边界的匹配引擎：只在单词首字母、驼峰边界（CamelCase）或连续词块中寻找命中，并给予前缀命中 1,200 分的强劲加成（COMPACT_PHRASE_BONUS）；

• 虚拟滚动视口（Virtualized Viewport）：
无论本地沉淀了 50 个还是 5,000 个会话，列表组件仅渲染终端视口高度内可见的行切片，配合快速轻量的二分定位，确保无论列表多大，每一击按键的过滤延迟均小于 2 毫秒；

• 行内原子重命名（Ctrl+R Rename，Patch 4）：
在选择器列表中选中任一历史会话，按下 Ctrl+R 即可在当前行原地置换出输入弹窗（HookInputComponent）。提交后调用 FileSessionStorage.updateSessionTitle 原子修改 JSONL 头部的标题，并显式标注 source: "user"。该标记赋予该标题最高守护权，杜绝后续模型在会话再次恢复时使用自动摘要将其覆盖。

3. Composer 编辑框 @ 文件引用与符号模糊补全

• 文件系统前缀树与 Ripgrep 预热：通过后台 Worker 缓存活跃 Git 仓库的文件树索引；

• 终端东亚宽字符光标对齐：通过 Bun.stringWidth() 严格计算中文路径与 Nerd 图标的物理单元格占用，确保浮窗始终精确锚定在 @ 字符正下方，杜绝光标视觉错位。

4. 工具执行运行时、虚拟资源协议与记忆外延

4.1 原生工具集体系、MCP 网关与 Rust Native 加速

• 文件与搜索：read（支持行区间、多路径、SVG/图片预览）、edit（基于 hashline 的高精度局部行编辑，摒弃不稳定的全文正则替换）、write、glob、grep、find。

• 执行宿主：bash（内置持久化 Shell 会话、PTY 仿真）、eval（基于 Bun / QuickJS 的行内代码沙箱）。

• Native 扩展：核心计算密集型操作（如文本模糊匹配、基于 Tree-sitter 的代码高亮切片、Ripgrep 驱动的文件扫描）下沉至 crates/pi-natives，编译为 Node-API（.node）动态库接入，在 Node/Bun 运行时内取得接近 C/Rust 的极限性能。

• MCP 接入：具备标准的 Model Context Protocol 客户端支持，支持通过 stdio 或 SSE 连接远程第三方工具服务器。

4.2 Fork 虚拟 URI 资源路由体系（agent://, history://, xd://）

4.3 Fork 工具调用意图（Intent）的一等公民管道穿透

1. Schema 扩展：在所有核心工具的入参中统一定义 i（Present-participle Intent，如 "Reading model role settings"）参数。

2. 管道穿透：将 toolCall.intent 穿透至事件控制流实时渲染器、会话重建器（chat-transcript-builder）及合并卡片渲染上下文。

3. 视觉突显：在 TUI 工具卡片的顶边栏首行，以专属高亮字重和 ✦/* 图标独立浮雕渲染该意图标签，使 Agent 的思维步调与人类意图对齐。

实机呈现：意图穿透与代码智能工具卡片（LSP References）

• 首行高亮意图浮雕：✦ Locating symbol references across auth and router modules 采用金色 Accent 字体直接嵌入边框内，在工具尚未开始执行或流式传输时即向用户透明化执行动机；

• 分层引用索引树：清楚呈现跨文件（src/server/auth.ts, src/server/middleware/session.ts, src/server/router.ts, test/auth.test.ts）的精确行列定位与符号上下文；

• 透明框架与折叠交互：支持通过 Ctrl+O 动态展开折叠局部代码上下文，摒弃冗长杂乱的终端日志打印。

实机呈现：多模态图像资产只读探测卡片（Read Image Metadata）

• 意图注入：✦ Inspecting system architecture overview graphic asset 标明当前读取意图；

• 物理规格精确呈现：清晰呈现 MIME 类型、宽高像素、宽高比、Alpha 透明通道及原始字节数；

• 终端协议自适应：在 Kitty 终端下自动转码 PNG 触发图形协议传输缩略图，在非图形终端下安全降级为结构化元数据块。

实机呈现：生产环境透明 Diff 卡片、意图浮雕与多 Tab 会话工作台

• 首行意图高亮穿透（Patch 9）：Edit 卡片首行呈现专属紫色的 ✦ Add LSP and Image card showcases to Section 4.3，紧随其后的 Read 卡片呈现绿色 ✦ Read Section 6.3 lines 360-390，使 Agent 在复杂多文件穿梭时的每一步“心智模型”均清晰投射在屏幕上；

• 去背景实心块的通透边框（Patch 5）：Edit 与 Read 工具卡片采用 boxRound 边框包裹，彻底剔除了刺眼的黑色纯色填充背景，让文件 Diff 行（+ 绿色高亮）与上下文行轻盈悬浮于桌面壁纸与毛玻璃之上；

• 多 Tab 跨项目会话编排：顶部 Tab 栏展示了开发者当前的并发任务流（π > OMP Harness 设计思路总览、π 🗘 更新并启动 aistudio2api、~/code/rosereader），证实 Harness 支持跨项目即时切换与沉浸式操作。

4.4 Fork 运行时扩展机制（Extension Engine）与 Rebase 免疫架构

1. 扩展生命周期与两阶段状态机

• 加载阶段（Load Phase）：宿主扫描 ~/.omp/agent/extensions/*.ts 或工作区 .omp/extensions/*.ts，通过动态导入（Dynamic Import）执行扩展模块导出的默认工厂函数：
在此阶段，任何尝试调用即时运行时行为（如 pi.sendMessage()）的操作都会被严格拦截并抛出 ExtensionRuntimeNotInitializedError，杜绝启动期产生难以控制的副作用。

• 运行时接管阶段（Runtime Phase）：ExtensionRunner.initialize(...) 将加载就绪的扩展与活跃的交互模式（InteractiveMode）、上下文会话（ToolSession）以及转录树建立双向绑定。

2. 全方位扩展能力契约（ExtensionAPI）

• 工具注册（pi.registerTool）：定义强类型入参 Schema（基于 TypeBox / ArkType / Zod），向模型暴露自定义动作，并在执行函数 execute(toolCallId, params, signal, onUpdate, ctx) 中通过 ctx 访问当前工作区、转录树与交互视口；

• 指令注册（pi.registerCommand）：注册 / 斜杠指令，支持在交互终端中自定义运维动作（如 /turns 快速跳转、/wiki 知识库编译）；

• 自定义渲染器（pi.registerCustomRenderer）：为特定工具或系统事件注入专属的 TUI 组件，自定义颜色、外框与进度条；

• 事件总线与切面拦截（Interception Pipeline）：
• session_start / session_end：会话生命周期感知；
• tool_call：在工具即将执行前触发切面审查。扩展可返回 { block: true, reason: string } 强制中断危险操作，或者在原地动态重写工具入参；
• tool_result：拦截工具输出，在结果回传给模型前执行脱敏过滤或摘要压缩；

• 交互式 UI 注入（pi.ui）：扩展可调用 pi.ui.notify(msg, level) 发送轻量通知，或通过 pi.ui.select(prompt, options) / pi.ui.prompt(...) 唤起模态弹窗向用户请求决策输入。

3. Rebase 免疫部署体系（Rebase-Immune Deployment）

• 源码统一保存在独立的 extensions/ 目录下，并通过符号链接（Symlink）挂载至用户全局目录 ~/.omp/agent/extensions/；

• 无论底层的 omp 核心二进制如何基于上游 synthetic commit 经历何种跨大版本升级（如 v18.0 v18.3），扩展代码本身不需要重新编译，也不在主干源码树中引入脆弱的侵入式 Diff；

• 宿主启动时，Bun 运行时直接即时编译执行 TypeScript 扩展代码，实现了真正零维护成本、即插即用的热插拔能力生态。

4.5 Fork 全局长程记忆双引擎：history_search 与 session_search 深度剖析

1. 单会话内存全分支检索：history_search

• 零 I/O 内存穿刺：每次执行直接调用 ctx.sessionManager.getBranch()，瞬间提取从根节点到当前叶节点的完整原始转录链（涵盖 pre-compaction 与 pre-/clear 的全部条目），耗时 < 1ms；

• 分层加权 BM25 检索：建立面向工程对话特征的层级加权机制：
确保开发者最早提出的关键约束和任务目标拥有最高的召回判定优先级；

• CJK Bigram 中文分词器：内置针对中文字符的双字滑动切分分词算法，攻克由于无空格导致中文长句无法被标准分词器命中的顽疾；同时原生支持 /pattern/ 正则表达式精准定位；

• 多媒体资产重挂载（include_images: true）：模型在会话初期见过的截屏（如报错截图、UI 设计稿），随着上下文压缩会被降级。history_search 配合 expand: [entryId] 能够直接根据持久化哈希重新唤醒底层的 Image Blob 并挂载回当前 Turn，实现多模态视界的时空连通。

2. 全机跨会话离线挖掘：session_search

• 语料真相与规模界定：实测单机沉淀了 800+ 个历史会话（约 765 MB 的有效 JSONL 转录库；排除了单个可达 14 GB 的 *.bash.log 侧车日志干扰）；

• 裸字节极速预过滤（Bare-Byte Prefilter）：利用底层的 Buffer#indexOf，在不进行整文件解码的前提下，直接在原始二进制字节流中扫描多字符 Token 与 CJK 串，只有发生物理命中的行才触发昂贵的 UTF-8 解码与 JSON.parse（实测 220 MB / 173 个会话预过滤耗时仅 ~1.1s）；

• 活链路拓扑重构（Active Lineage Reconstruction）：由于 JSONL 是只追加写入日志，包含了大量用户执行 /rewind 回滚或者分支探索遗留下的“死分支行”。算法从文件的最后一条 entry 出发，沿着 parentId 逆向攀爬溯源，严格剔除从未真正在活跃分支上生效的幽灵记录；

• Term Slots 与 Int32Array 极致性能优化：针对 27,000+ 文档的大规模打分，彻底放弃传统的 JS Map 与对象堆分配，改用连续内存的 Int32Array 与固定 Term Slots 统计词频，将排序时间从 2.7 秒极限压缩至 0.1 秒，彻底消除垃圾回收（GC）卡顿；

• 透明预算防御：设置 5 秒硬超时、6,000 行候选上限，并在结果尾部诚实上报扫描会话总数、有效候选数、过滤死分支数以及跳过文件清单。

4.6 Fork 惰性 MCP 网关（Lazy MCP Gateway）与 Notion 深度实战

1. 冷启动性能雪崩：每次启动 CLI，宿主必须逐一与所有声明的 MCP Server 执行 stdio/SSE 握手并同步拉取工具列表，配置 3 个以上服务即可导致冷启动卡顿 3~5 秒；

2. 上下文空间严重挤占：一个功能完备的 MCP 服务（如 Notion）往往包含十几个工具，其冗长的 JSON Schema 在首轮 Prompt 中瞬间吞噬数千 Token，即便本次编码任务只是修改一行变量名，这部分上下文也会永久消耗宝贵的首轮预算。

1. 惰性网关设计与状态机模型

• 启动期配置剥离：在配置中声明 lazy: true 后，MCPConfigLoader 在启动时将该服务从常规自启动列表中移出，交由 MCPManager.#lazyHeld 与 #lazySources 独立托管；

• 轻量占位网关暴露：启动时不建立网络连接、不拉取 Schema，仅在模型可用设备表中挂载一个名为 LazyMCPServerGateway 的占位工具（对应 URI 为 xd://mcp__<server>_gateway）。该网关在 System Prompt 中仅占用极其廉价的一行提示语：

"Lazily-connected MCP server gateway for 'notion': none of its tools are loaded yet. Write {} here to connect the server now and mount its real tools under xd:// devices."

2. Notion MCP 深度实战与无感升级

• 常态开发状态：日常进行本地代码编写时，Notion 保持完全休眠，会话享有纯净的毫秒级冷启动与无污染的 Prompt 空间；

• 按需激活流转：当任务明确要求“将本篇架构设计总结发布至我的 Notion 技术博客”时，Agent 识别到该占位设备，主动向 xd://mcp__notion_gateway 写入 {}；

• 实时连接与无感置换：
1. 网关拦截到写入，底层异步触发真实 Node/Python MCP 进程的拉起与 stdio 握手；
2. 握手成功后，管理器将 #lazyHeld 标记清除，从设备表中摘除占位网关；
3. 真实的 Notion 工具集（notion_append_block、notion_query_database 等）被原子化注入当前会话，并触发 onToolsChanged 事件刷新模型可见的工具表；
4. 整个激活与替换过程对当前 Turn 透明完成，无需重开会话，实现了极速开发与丰富生态的完美融合。

4.7 Wiki 知识库与 Mnemopi 本地向量双层记忆系统深度剖析

1. 外部独立 Markdown Wiki 知识库（The Wiki Vault）

• 收件箱追加模型（Inbox Pattern）：
当调用 retain 沉淀经验时，系统绝不直接覆写任何既有文件，而是在 raw/inbox/<scope>/ 目录下生成一个带时间戳与唯一 UUID 的独立 Markdown 文件（记录事实描述、发生场景、原始证据与作用域）；

• 离线编译管线（/wiki compile）：
当开发者执行 /wiki compile 指令时，宿主启动专门的知识编译器模型：
1. 扫描未处理的 raw/inbox/ 文件集合；
2. 运用知识图谱聚类算法，将零碎、重复的事实归纳提炼至对应的领域百科（wiki/<topic>.md）；
3. 在编译生成的条目下方强制保留原始证据链接（Evidence Links），确保每一句结论都有据可查；

• 四维记忆设备闭环：
• retain：将关键事实以不可变追加模式写入 Inbox；
• recall：结合编译好的 wiki/ 百科与待编译的 inbox/ 原文，执行双轨语义检索；
• reflect：调阅多条领域知识，跨越会话时空推演出综合解决方案；
• memory_edit：以增量追加修正项的方式记录事实勘误，绝不破坏历史审计链。

2. Mnemopi 本地混合向量检索引擎（Local Vector Store）

• 双轨索引架构：底层建立“sqlite-vec 稠密向量索引 + FTS5 稀疏全文检索”双轨制。稀疏检索补充专有代码符号的硬匹配，稠密向量解决同义语义泛化；

• CJK Bigram 双字分词器：针对原生 SQLite FTS 在处理无空格中文自然语言时的分词缺陷，内建滑动双字分词切片，确保中文技术术语精准命中；

• 多 Key 轮询嵌入管道：嵌入模型选用 google/gemini-embedding-2，通过 authStorage.keys.setConfigPool 建立透明凭据池，避免因并发请求触碰 Google API 免费限速（429）；

• 启动差分同步门禁（Patch 24: Gated on Drift）：原生在每次打开数据库时都会盲目全量重扫文件并重建 FTS 镜像，引入了近 500ms 的冷启动延迟。Fork 增加了版本哈希与漂移门禁，仅当检测到元数据实质变更时才触发差分同步；

• 向量重排冷却熔断（Patch 26: Reconcile Cooldown）：在网络偶发断连或 API 429 报错时，原生会导致未完成对齐的向量被误删，随后引发永无止境的重复构建死循环。Fork 引入数据丢失保护门禁与重入冷却时间戳，强行拦截异常状态下的清库行为，守护本地向量资产安全。

4.8 伴生桌面微宠守护进程（Desktop Pet Bridge）与只读工作区检查器（Workspace Inspector）

1. 伴生桌面微宠（Desktop Pet Bridge，Patch 12）：
• 基于 extensions/pet-bridge.ts 扩展，通过 Unix Domain Socket 异步连接至系统底层独立的 GTK4 Layer-Shell 守护进程（omp_pet.py）；
• 实时监听宿主事件总线：当模型处于思考推理、工具执行阻塞、遇到网络重试或最终结算时，微宠在屏幕角落实时做出细腻的动作姿态镜像；
• 巧妙绕过了在开发者全屏工作时极易被系统静音机制（如 KDE 勿扰模式）吞没的传统桌面通知，提供了低侵入感且充满灵动的物理级可观测性。

2. 只读工作区检查器（Workspace Inspector，Patch 14）：
• 实现于 workspace-inspector/ 与 git-snapshot.ts；
• 专为代码审查与自动化自省提供强隔离的只读环境视口。通过建立瞬态 Git 快照，Agent 能够对当前目录下的文件树指纹、未跟踪文件和 Staged 变更进行全局透视，杜绝在检查阶段因误执行清理脚本造成不可逆的文件破坏。

4.9 Browser Relay 架构深度剖析：真实浏览器接管、CDP 伪装多路复用与安全防线

1. 身份认证墙（The Auth Wall）：全新的无头实例是“白板”，缺乏用户的登录态（Cookie / Session / SSO / 2FA / WebAuthn）。强迫智能体在白板中执行模拟登录不仅脆弱，还会经常触发云盾验证码（Turnstile / Cloudflare 5s 盾）；

2. 高额系统负载：每次启动一个完整的 Chromium 进程，至少侵占 300~500 MB 物理内存与大量 CPU 调度；

3. 反爬与指纹检测暴露：Headless 特征（navigator.webdriver = true、WebGL 指纹缺失等）极易被目标站点 WAF 判定为僵尸流量并封禁出口 IP。

1. 反向代理拓扑与逆向握手架构

1. 中继守护进程（daemon.ts / server.ts）：
宿主在 127.0.0.1:9224 启动一个轻量级 HTTP/WebSocket 中继服务器（通过单例 Broker 守护，多工程共享，单工程退出不销毁端口）；

2. 扩展主动握手：
开发者只需通过 omp browser-relay install 安装一次轻量 MV3 扩展。扩展启动后自动连接本机的 WS /ext，工具栏图标点亮为绿色的 "on"；

3. 标准 CDP 伪装暴露：
中继服务器对外完美伪装成一个原生的 Chrome DevTools 调试端点：暴露 GET /json/version、GET /json/list 以及 WS /cdp。上层的任何标准客户端（如 Puppeteer、Playwright 甚至普通 Chrome 调试工具）都可以直接把 http://127.0.0.1:9224 当成一台真正的远程 Chromium 实例进行连接，完全不感知底层扩展的存在。

2. 突破 Chrome 单调试器限制：CDP 伪装与虚拟多路复用（bridge.ts）

Chrome 规定：任意一个网页 Tab，在同一时刻绝对只允许附加（Attach）一个 chrome.debugger 客户端。

1. 单点物理 Attachment 托管：
扩展与 Chrome 之间，对每个被接管的 Tab 永远只维持唯一的一个物理 chrome.debugger 附加通道；

2. 虚拟会话命名空间划分（Minted Pseudo-Sessions）：
向下游的每个独立 CDP 客户端分发虚拟的会话 ID：
• Tab 级虚拟会话（ST<tab>.<conn>.<n>）：用于响应下游发起的 Target.* 自动附加（Auto-attach）协议发现；
• Page 级虚拟会话（SP<tab>.<conn>.<n>）：当下游向此 Session 发送具体指令（如 Page.navigate、DOM.getDocument、Input.dispatchMouseEvent）时，网桥负责将该虚拟 ID 解包，映射到底层该 Tab 的物理通道，并将 Chrome 的物理回复打包分发给对应的下游客户端；
• 子级物理会话穿透：对于页面内部派生出的 OOPIF（跨域 iframe）或 Web Worker，网桥直接透传 Chrome 原生分发的真实 Child Session ID。

3. 运行时执行上下文追踪与上下文重放（Context Replay）

当下游客户端连接到一个已经加载完毕的既有网页时，由于网页没有重新加载，Chrome 绝不会再次主动推送 Runtime.executionContextCreated 事件。

• 网桥内部为每个被调试的 Tab 维护全生命周期的 runtimeContexts 拓扑缓存；

• 一旦检测到某个下游连接向该 Tab 发起虚拟绑定或发送 Runtime.enable，网桥立即从缓存中提取已存在的 Context 元数据，合成标准 CDP 事件：
定向向该连接执行即时事件重放（Context Replay），使下游 Puppeteer 客户端在握手微秒内立即捕获上下文，流畅执行 DOM 查询。

4. 安全红线与人机隔离防线（Safety Invariants）

1. 回环地址与同源防穿透：
中继服务坚决仅监听 127.0.0.1 本地回环；针对 WS /cdp 连接，若 HTTP 报头中携带任何 Origin 头（表明该连接尝试从某个普通网页中利用 WebSocket 跨域攻击本地中继），直接无条件返回 403 Forbidden 拒绝升级；

2. 前台视觉免打扰（Preserve User Focus）：
当 Agent 未指明目标而自动认领前台活跃 Tab 时，严禁主动将浏览器窗口置顶抢夺焦点；在截取整页快照时（activateForScreenshot），优先使用无焦点捕获技术，杜绝开发者打字时被焦点突然切走；

3. 标签组织隔离（"omp" Chrome Tab Group）：
所有由 Agent 新建或主动纳入受控范围的标签页，会被扩展通过 Chrome 原生的 Tab Group API 自动归拢进一个名为 "omp"（青色 Accent 标记）的独立标签分组中，并排在标签栏右侧，与用户的私人浏览标签形成清晰的物理隔离；

4. 严禁越权导航（No Unauthorized Navigation）：
严格禁止智能体在没有用户显式授权的情况下，对用户当前正在浏览的前台私人标签页执行 Page.navigate 跳转，防止破坏用户未保存的工作现场；

5. 断开永不杀进程（Disconnect Never Kills）：
在任务完结、会话退出或执行 /clear 时，宿主只会向中继发送 Detach 指令安全断开 CDP 调试连接并释放标签组，绝对不会调用 process.kill() 终止整个 Chrome 进程。用户打开的数十个日常网页、未读消息与后台播放均安然无恙。

4.10 Hashline 行级精确定位编辑引擎：告别 Patch 漂移与幻觉覆写

1. Unified Diff 补丁派（如 patch）：模型必须生成标准 GNU Diff 格式。由于大模型缺乏对空格与换行符的绝对精度控制，一个微小的缩进漂移、行号偏差或空白字符缺失，就会导致底层 patch 工具抛出 Hunk failed 并整体拒绝；

2. 全局搜索替换派（如 search_and_replace / replace）：模型提供被替换的原代码片段与新代码片段。但在大型工程中，类似 return true;、});、import * as path from "node:path"; 的通用行随处可见，极易发生多处匹配歧义（Ambiguous Matches），导致错误地覆写了非目标函数。

1. 4 字节快照哈希锚定（Snapshot Tagging）

• 乐观锁并发防御：如果该文件在模型阅读后被外部 Git 切换分支、后台格式化工具或并发任务修改过，快照哈希将发生失配（Snapshot mismatch）。

• 强制前置阅读：Harness 在应用补丁前立即拦截并硬拒绝修改，强制模型重新执行 read 刷新上下文，彻底消除了“基于陈旧幻觉修改代码”的重大生产事故隐患。

2. 精确行号操作与 AST 语法块感知

• 确定性行号区间（PUT N.=M:）：直接指定待替换的物理闭区间行号 N..M，所有行号均基于原始未修改的快照，不随同一个请求中前面其他 Hunk 的增删而发生动态偏移；

• 行隙插入（PUT <N: / PUT >N: / PUT >$:）：支持在行 N 前后或文件末尾追加内容，语义清晰单一；

• 语法块智能替换（PUT N*:）：
借力 Tree-sitter 语法分析，模型只需声明语法块起始行（如第 42 行），引擎自动从 AST 树上识别该函数、类或类型声明的物理结束边界并整体置换，无需模型在 Prompt 中苦苦计数大括号配对。

3. 命名寄存器（Named Registers）与零 Token 代码重构

• 零 Token 消耗与零幻觉搬运：被剪切的代码片段暂存于当前会话的内存寄存器中。目标文件直接以引用形式粘贴，模型无需在回复中重新吐出这 45 行代码对应的数百个 Token。不仅重构吞吐速度提升数倍，而且彻底杜绝了代码搬迁过程中因模型重新采样漏写一行逻辑的经典风险。

4.11 持久化 PTY 会话与 Bash 工具安全沙箱深度剖析

1. 环境与目录丢失：每个命令都在全新的子进程中运行，模型执行 cd packages/core 后，下一个命令的工作目录依然停留在根目录；通过 source .env 加载的环境变量在下一轮即刻蒸发；

2. 交互式命令伪死锁：缺少真实终端 PTY 支持，许多针对终端控制台优化的构建工具（Webpack、Vite、Docker CLI）会丢失颜色、输出混乱甚至因等待 TTY 输入而永久挂起。

1. 会话状态继承与 PTY 仿真

• 持久化会话维持：后台维护长期存活的伪终端（PTY）进程实例，模型在跨 Turn 执行的 cd 导航、环境变量变更（export）、Shell 函数定义在整个会话生命周期内全局保持；

• 真实终端尺寸同步（SIGWINCH）：随着外部 TUI 视口缩放实时向后台 PTY 下发窗口重绘信号，保障长文本输出自动软折行不被硬截断。

2. 哨兵提示符注入（Prompt Sentinel）与边界精确捕获

• 宿主向后台 PTY 注入专属定制的 PROMPT_COMMAND 与特化 PS1 哨兵序列；

• 哨兵中携带带随机哈希与状态标记的转义特征帧；

• 无论被执行的脚本输出了多少杂乱的 ANSI 乱码或二进制流，Harness 的流状态机均能精准定位命令输出的绝对边界，并无损捕获真实退出码。

3. 异步后台守护作业控制面（async: true / proc://<pid>）

• 支持传入 async: true 将命令解耦为后台托管作业；

• 统一接入虚拟设备总线 proc://<pid>：
• read proc://<pid>：实时非阻塞读取增量输出流；
• write proc://<pid>：向后台进程注入标准输入（模拟回车确认）；
• write proc://<pid>/kill：优雅发送 SIGTERM 并提供超时 SIGKILL 兜底，防止遗留孤儿进程僵尸占用端口。

4.12 Native 性能基石：Rust 动态库（pi-natives）计算下沉架构

• 在包含数十万行代码的大型单体仓（Monorepo）中，全量正则遍历、代码高亮分词、Git 拓扑分析若全由 V8 / JSC 引擎在主线程跑，必然引发主交互帧率暴跌。

1. 核心计算加速域

• Ripgrep 引擎直接内联：搜索核心由 Rust 原生接管，绕过跨进程管道调用的序列化开销，直接与操作系统的 mmap 与多线程文件 I/O 对接；

• Tree-sitter 增量语法高亮引擎：在 Rust 内存空间中维护语法树，毫秒级为终端 TUI 提供代码着色与 AST 语法块切片（直接支撑 Patch 32 的圆角行号框渲染）；

• 微秒级哈希计算与 Git 拓扑探测：采用 SIMD 加速的快速哈希算法（xxHash / BLAKE3）秒级产出 Hashline 快照指纹。

2. ABI 严格锁死与 Sentinel 版本安全门禁（__piNativesV18_x_x）

• Fork 在升级合并过程中，严格遵循原生二进制同步演进规则；

• 底层导出一个形如 __piNativesV18_1_10 的版本强校验哨兵符号。在创建会话的首毫秒内，JS 层会主动探针该哨兵；若发现底层二进制版本不匹配，立即抛出明确异常拦截执行，杜绝因 ABI 漂移破坏开发者的现场代码。

4.13 Auto-Learn 机制与 Managed Skill 智能体自进化闭环

1. 学习时机裁决与状态机看门狗（Learning Trigger & Conditions）

1. 基础开关：必须显式开启 autolearn.enabled === true；

2. 复杂度阈值（minToolCalls）：
单个回合内调用的工具数必须达到阈值（默认 cfgAutolearnMinToolCalls = 5）。简单的问答、单文件阅读等低复杂度任务自动被看门狗过滤，唯有经过多轮重构、排障与测试的高复杂度交互才有资格进入采撷评估；

3. 中止保护（Abort Suppression）：
若回合以用户的 Esc 或 Ctrl+C 强行打断告终（stopReason === "aborted"），看门狗立刻放弃，防止将半途而废的错误排障经验固化为伪经验；

4. 任务模式排他保护（Goal / Plan Mode Exclusions）：
当处于 Goal Mode 连续目标推进循环或 Plan Mode 架构评审中时，严格跳过学习触发，绝不与核心任务的调度逻辑产生竞争或逻辑抢占；

5. 双运行模式与 Prompt Cache 锁死保活权衡：
• 被动常态模式（Passive Mode，autoContinue: false）：
仅向 System Prompt 注入静态常驻的 autolearnGuidance 与 autolearnGuidanceLearn 指令。智能体在任务推进中若发现具有通用复用价值的操作规程，直接在主流程中自发调用 manage_skill 或 learn。
架构权衡抉择：系统早期版本曾尝试在任务结算后向转录队列排队压入一条隐藏的自定义触发消息（Custom Message），但该行为动态改变了历史上下文的前缀字节，直接击穿了 Anthropic Prompt Cache！因此最终改用完全静态的常驻系统指导，确保长会话下的缓存键绝对稳定；
• 主动独立采撷模式（Active Capture Mode，autoContinue: true）：
在满足门槛的主任务回合结算后，宿主异步拉起一个专用的轻量级采撷子智能体（runAutolearnCapture）。该智能体携带专用的独立指令（autolearn-nudge-autocontinue.md），并且在工具层进行了严格的沙箱隔离（Tool Resolver Isolation）：仅暴露 manage_skill 与 learn，绝不继承主会话的文件读写或 Shell 执行工具，杜绝采撷阶段产生意外的外部副作用。

2. 技能召回时机、优先级仲裁与渐进式披露（Recall Timing & Hierarchy）

• 物理目录隔离（Physical Isolation）：
• 用户手动编写的手写技能存放于 ~/.omp/agent/skills/ 或工作区 .omp/skills/；
• 系统自生成的托管技能严格隔离在 ~/.omp/agent/managed-skills/<name>/SKILL.md；
• 权限硬红线：智能体通过 manage_skill 只能对 managed-skills/ 进行增删改，严禁任何指令越权触碰用户的手写技能；

• 最低优先级仲裁（Lowest Priority Provider，MANAGED_SKILLS_PRIORITY = 5）：
在技能发现与去重管线中，用户手写技能拥有绝对裁决权（优先级高于 10）。若托管技能与用户技能重名，系统永远优先加载手写技能；并且在 manage_skill 执行创建时，会提前通过 isNameClaimedByAuthoredSkill 检查用户技能池，若同名则直接在前端抛错拒绝，杜绝生成被静默覆盖的无效死技能；

• 渐进式披露召回（Progressive Disclosure）：
当新会话启动或切换工作区时，系统绝不将所有技能的正文全量塞进 Prompt。System Prompt 中仅以微小的 Token 成本注入一览表（包含技能名称与一句话适用场景描述）；唯有当模型在面临特定任务、判定命中了某项技能时，才按需触发 read skill://<name> 动态读取该技能的详细执行步骤，实现长效记忆与轻量上下文的最佳平衡。

3. Prompt 体系与结构化自动合成

1. autolearn-guidance.md：界定 manage_skill 的适用边界——专门捕获可复用的结构化规程（环境搭建时序、复杂缺陷排障流程、跨组件工作流）；

2. autolearn-guidance-learn.md：界定 learn 的适用边界——捕获长效事实、全局约定与用户私人偏好，直接联动 Wiki 或本地向量库；

3. 标准 Frontmatter 自动合成：模型在沉淀技能时无需手动排版复杂的 YAML 前置元数据，系统自动对其自然语言入参进行校验清洗，合成出包含 name、description 标准声明的规范 Markdown 实体。

5. 网络协议、中转对抗与提示词缓存保活

5.1 原生多 Provider 抽象与 KDL 声明式规则引擎

• 所有的模型能力边界、价格模型、上下文限制、思考预算（Thinking Budget）支持、API 路由偏好均抽离在 packages/catalog/src/compat/rules/ 下的 KDL 规则树 中。

• 编译脚本 bun run gen:compat 将声明式规则编译为高度优化的静态 rules.json。

• 运行时统一由 classifyModel() 提供结构化事实判断，确保代码库拥有长周期的可维护性。

5.2 Fork 第三方 Relay 思考预算与错误容错阶梯（400 / [1210] / 始终思考）

• 中转服务商对带有 thinking: { type: "enabled" } 的请求报错 400: 不支持 thinking / 请使用 reasoning_effort。

• 特定网关路由错误时抛出 [1210] 或中文提示“模型负载已满/内部错误”，但 HTTP 状态码伪装为 400（不可重试）。

1. 中文正则容错降级（openai-reasoning-fallback.ts）：针对中文提示语（“不支持/请使用”等关键词）建立自适应协商链，在保持模型原有思考倾向的同时，安全地将不规范字段置空或转换为供应商兼容形式。

2. fetch-retry.ts 专用通道：引入 retryNonRetryableResponse 专有选项，打破“400 绝不重试”的传统教条，使特定中转站的伪 400 报错能够安全复用退避重试循环，且不破坏正常流式 Body 的读取。

3. 自动剥离历史思考痕迹：当捕获到目标 Relay 属于“始终思考型”（Always-thinking）且拒绝历史 Message 中携带的 <think> 标签时，自动触发清洗钩子（stripThinkTagsFromCompletionsParams），确保上下文顺利过关。

5.3 Fork Claude Code 伪装锚定与 Prompt Cache 缓存穿透根治

1. cch 认证哈希作用域化：
原生伪装实现中，每次计算 Attestation 哈希可能受到微观时间戳或未对齐上下文影响，导致请求报头中的 cch 每一轮都在漂移。Fork 通过将其限定在稳定前缀哈希范围内，实现了跨 Turn 的哈希值恒定。

2. 用户 Turn 强制块格式序列化（Content Blocks Serialization）：
在 convertAnthropicMessages 中，原生实现常将简单的用户文本序列化为裸字符串；但在需要挂载缓存锚点（cache_control）时，该条目会被临时升级为 [{type: "text"}] 块数组。这一来回切换直接在长上下文的中段引入了字节级变动，导致后续所有的缓存前缀完全失效。Fork 强制所有用户消息均采用块格式序列化，彻底守住缓存前缀稳定性。

3. 实测收益：
实测在 5 轮工具调用的标准编码任务中，缓存命中率从 0/6 逆转至 4/6，Cache-write Token 消耗降低 61%，单次会话响应耗时由 80.8 秒腰斩至 43.4 秒。

5.4 Fork 动态热重载重试规则引擎（retry-rules.json）

• 支持为特定的供应商、模型或错误响应体定义双向正则表达式（RegEx）。

• 支持配置自定义重试预算（Retry Budget）与特定退避延时。

• 运行时文件监听生效：当线上出现突发的新型非标 HTTP 响应码时，开发者无需修改 TypeScript 源码或重新编译打包 CLI，只需在 JSON 中追加一条规则即可实现全进程秒级生效。

5.5 Fork 搜索通道同源复用与 Grok Relay 适配

1. 活跃模型同源搜索通道复用（Search Affinity）：
• 当当前对话的主模型为 GPT 系列时，自动提升 Codex 搜索通道，并复用当前活跃连接的凭据。
• 当主模型为自定义 Messages 接口的 Claude 时，通过 anthropic-affinity.ts 自动复用其底层传输端点、伪装标头与连接池，无需为网络搜索额外购买昂贵的独立专用通道。

2. Grok 搜索流接入：
针对 xAI Grok 的搜索特性，扩展了专用的中转适配器，使得拥有 Grok API 的开发者能够无缝将其作为高质量网页实时信息的注入通道。

5.6 Fork 协议报头穿透（Extra Betas / Codex Pins）与多 API Key 轮询凭据池

1. 声明式 Betas 报头穿透（compat.extraBetas，Patch 19）：
• 痛点：部分第三方 Relay（如 anyrouter）在支持 1M 上下文时，强制要求客户端携带 context-1m-2025-08-07 请求头，否则直接以 400 拦截报错（“请启用 1m 上下文后重试”）。而原生为了防止官方 OAuth 凭据撞击未授权 1M 额度导致的 429 报错，硬编码拒绝向外透传该 Beta；
• 机制：在 AnthropicCompat 配置模型中挂载 extraBetas 声明列表，通过 buildBetaHeader 与内置伪装链深度合并去重，使自定义中转的特殊门禁头得以安全抵达底层 Wire，成功瓦解反代准入报错。

2. Codex / Responses 身份特征头保活透传（Patch 27）：
• 修复了 createCodexHeaders 中无条件覆写 Originator / User-Agent 导致的身份指纹丢失，改为仅在缺省时才补充默认标识（Set-if-absent），允许中转专用鉴权请求头完整保留。

3. Prompt 包含型 Token 修正（Patch 22）：
• 在 Anthropic 协议线路上，部分国内中转镜像返回的 input_tokens 计数已经叠加了缓存读取（Cache Read）的 Token 数量，导致上层 Harness 误判当前上下文已逼近极限而过早触发激进压缩；
• Fork 引入 promptIncludesCacheRead 协议特征判定，自适应剔除虚高计数，捍卫了上下文滑动预算与费用账单的真实性。

4. 运行时多 API Key 轮询凭据池（Multi-API-Key Pool）：
• 在模型认证存储层（authStorage.keys.setConfigPool）实现动态凭据池；
• 支持为单个 Provider 配置多组备用 API Key，在运行时侦测到 429 限速或配额耗尽时，透明轮转切换并设置冷却时间，无需手动重启即可支撑子智能体团队长时间高吞吐并发作业。

5.7 多 Provider 缓存计量差异与协议方言兼容深度剖析

1. 三大模型家族 Prompt Caching 的底层 Wire 差异与成本数学

2. 中转反代“双重计费”虚高陷阱与纠偏算法（promptIncludesCacheRead，Patch 22）

• 官方标准规范：在 Anthropic 官方 Messages API 中，usage.input_tokens 严格定义为“本次请求新产生、未命中缓存的增量输入 Token 数”。
例如：总提示词 80K，命中缓存 75K，官方返回：
input_tokens: 5000, cache_read_input_tokens: 75000；

• 中转反代严重异化：国内大量基于 New API / One API 二次修改的分发网关，其内部计费中间件在重组响应时，粗暴地将 cache_read_input_tokens 重新叠加进了 input_tokens：
returned_input_tokens = actual_new_tokens (5K) + cache_read_tokens (75K) = 80000；

• 对 Harness 的毁灭性打击：
Harness 的上下文滑动窗口看门狗（Context Compaction Watchdog）依赖 input_tokens 监控当前窗口水位。当阈值设为 95%（例如 100K 窗口）、当前实际仅消耗 5K 增量时，虚高的 80K 报文导致看门狗误判“上下文即将爆仓”，在第一轮工具调用后便过早且强制触发了 /compaction 紧急折叠！这一折叠强行重写了历史消息，把原本稳定命中的 75K 缓存前缀全部抹杀，不仅没有省钱，反而在每一轮都付出高昂的 125% 重新建仓代价；

• Fork 差分纠偏机制：
通过在模型注册表声明 compat.promptIncludesCacheRead: true，Harness 在流式收尾提取 Usage 时执行动态校准：
彻底平复上下文水位监控，守住了 Prompt Cache 的连贯生命周期。

3. KDL 声明式规则引擎与无分配指针置换（Zero-Allocation Pointer Swap）

• 四层严格职责分层：
1. taxonomy/*.kdl：定义模型谱系与派生关系（如 Claude、GPT、DeepSeek、Qwen、Kimi）；
2. classes/*.kdl：定义模型固有属性（如最大上下文窗口、原生多模态支持、思考参数支持）；
3. providers/*.kdl：定义特定托管商的魔改行为与约束（如某平台必须关闭 strict 语法校验、某平台思考格式强制采用 zai 或 qwen 方言）；
4. runtime/behavior.kdl：定义全局运行时启发式、路由兜底与降级梯队；

• 离线编译机制：构建时运行 bun run gen:compat，将散落的 KDL 规则经过优先级仲裁（Priority Arbitration）编译为紧凑、不可变且严格校验的 rules.json；

• 运行时无分配指针置换（Zero-Allocation Pointer Swap）：
在单次对话或高频流式通信中，每次动态深拷贝或合并对象都会引发 V8 / JavaScriptCore 引擎的内存碎片与 GC 停顿。Harness 在启动时便针对每个模型预先构建好了普通模式与思考模式（whenThinking）的静态兼容策略对象；在单次请求发生时，仅需通过单行指针引用置换即可完成协议切换：
实现真正的零对象分配、零 GC 损耗与极速运行吞吐。

6. 终端呈现工程（TUI）与人机交互交互面

6.1 原生 Pi-Tui 差分渲染引擎与生命周期管理

• 虚拟双缓冲与差分输出：在内存中维护终端网格缓冲，每一帧仅计算产生差异的单元格，最小化写入终端的标准 ANSI 控制码序列，彻底消除了传统终端全量刷新时的闪烁感。

• 三态转录生命周期：
• Active：可变状态，驻留于活跃视口，随窗口尺寸动态重排；
• Settled：已结算但仍在当前屏展示，随时准备被历史队列吸收；
• Committed：已写入终端回滚缓冲（Scrollback Buffer），释放内存占有。

• 这一架构确保了即便在大规模代码输出与流式 Markdown 高频推送下，终端仍能保持 60fps 级别的顺滑输入响应。

6.2 终端多协议图形渲染与 Kitty Unicode 占位符引擎深度剖析

1. 终端图形协议矩阵与自动探测降级

1. Kitty Graphics Protocol（优先）：最先进的现代终端图形标准（Kitty、Ghostty、WezTerm 原生支持），具备 GPU 纹理加速、分块传输与虚拟排版；

2. iTerm2 Inline Images：macOS 经典终端标准，基于 OSC 1337;File=inline=1:...^G 协议传输单帧或动图；

3. Sixel 协议：DEC VT 系列古老但兼容性极广的点阵图形标准，由 Rust 原生库 encodeSixel（crates/pi-natives）极速压缩编码输出；

4. 半块字符回退（Half-Block ANSI Fallback）：当终端完全不支持图形协议时，自动提取图片调色板，利用 ▀ / ▄ 字符配合 24-bit TrueColor 背景色构建紧凑低分辨率字符画预览。

2. Kitty Graphics Protocol 底层线缆规范与分块传输

• 格式硬约束（f=100）：Kitty 仅支持 PNG 格式。所有输入的 JPEG、GIF、WebP 资产在送入传输管线前，必须经过预处理转码为标准 PNG 流；

• 分块传输与流量整形（m=1 / m=0）：单条转义控制序列受限于终端 PTY 缓冲区（通常为 4096 字节）。大图像的 Base64 载荷被自动切割为 4096 字节的微块流式下发，前置块标记 m=1（还有后续块），收尾块标记 m=0；

• zlib 压缩载荷（o=z）：传输超大高清屏幕截图时，自动启用 zlib 内存压缩，大幅缩减写入 PTY 的字符流体积。

3. 虚拟排版引擎：Kitty Unicode 占位符机制（packages/tui/src/kitty-graphics.ts）

• 基底字符与组合标记：选用 Plane 16 私有保留字 KITTY_PLACEHOLDER = "\u{10eeee}" 作为占位基底，结合 297 个专用的 ROWCOLUMN_DIACRITICS 组合字符（Unicode combining class 230，无分解歧义）；

• 文本网格完全平等化：每一个占位字符单元直接在自身字节中嵌入了对应的 (row, col) 图像切片坐标。图像因此获得了纯文本单元格的一切物理特性：
• 随着终端滚动平滑移出屏幕；
• 支持与其他 ANSI 文本混排，甚至能被文本选择光标选中文本流；
• 支持差分渲染（仅更新重叠区域）与终端自适应软折行（Soft Wrap）。

4. 跨屏状态账本与 GPU 纹理冲刷自愈（ImageBudget，Patch 13）

• GPU 纹理擦除危机：Kitty 与 Ghostty 在终端切入 Alt Screen 时，会清空备用屏的图形显存。原生如果简单将已发送的 Image ID 视为全局已缓存，当用户退出全屏查看器回到主屏时，主转录流中的图像由于显存被擦除，将全数变成空白残影；

• 双屏独立账本（ImageBudget）：
Fork 在 packages/tui/src/components/image.ts 中维护了独立的表面状态账本：
在每次进出 Alt Screen 时，状态机精准感知当前物理表面的显存状态；当检测到目标表面的 GPU 纹理未就绪时，自动差分重放图像传输指令，彻底解决了全屏交互后主屏图片坏死的历史顽疾。

5. 异步转码竞态防御与转录块冻结门禁（Post-Merge 关键修复）

1. 终端启动前几毫秒，由于异步能力探测尚未完成，TERMINAL.imageProtocol 处于 undefined；

2. 此时若用户恢复包含 WebP 图片的会话，非原生格式向 PNG 的异步转码需要约 400ms；

3. 原生组件在首帧未就绪时先渲染了临时的文字占位符（如 [Image: image/webp]），该帧立刻被追加不可变机制永久固化进转录历史；等 400ms 后真正的 PNG 转换完毕时，界面已经无法刷新该已冻结块！

• ImageStrip 暴露 conversionsPending 计数器，严格追踪处于飞行中（In-flight）的转录转换；

• 在 UserMessageComponent 中实现严格的 isTranscriptBlockFinalized 门禁：只要异步转码尚未完全落地，该区块绝不允许被判定为 Finalized；

• 确保只有当真正的高清 PNG 纹理在终端中完成物理绘制后，区块才获准沉淀至不可变历史，终结了图片恢复时偶发白框的竞态暗疾。

实机呈现：Kitty 图形协议终端内联渲染与半透明毛玻璃工作台

• 终端内联图像直出（Inline Graphics）：终端直接响应 show_image 指令，将生成的 tui-markdown-rendering.png 作为高精度图元无缝绘制在转录流中，上下紧凑衔接命令指令与下游的 LSP 工具卡片；

• 全透明背景与毛玻璃融合：打破传统终端“纯黑不透光方块”的沉闷感，转录文本与图元悬浮于桌面工作环境之上，既提供高对比度的阅读体验，又保留与系统桌面壁纸的层次呼应；

• 连续 Turn 工具链无缝排版：图像上方承接生成任务指示，下方无缝展开下一个工具调用（Show LSP card showcase 与 💡 LSP references），体现流式 Agent 会话的连贯节奏。

6.3 Fork 终端排版美学重构：气泡、代码块边框与 Markdown 语法脱敏

1. Markdown 代码块圆角高亮框（#renderCodeBlockBox）：
• 彻底废除仅有两道暗淡横线的简易 Fence，采用 theme.symbols.boxRound 构建包裹外框（╭─── lang ───╮ / ╰───╯）。
• 引入专用的右对齐行号槽（Line Number Gutter），且当代码行发生软折行时，续行自动留白槽位，保证代码缩进严格对齐。

2. Markdown 标题语法脱敏与字重阶梯：
• 彻底剔除三级以下标题直接裸露打印在屏幕上的 ### 语法标记。
• 建立纯视觉字重阶梯：H1 采用 OSC 66 终端双倍字高 + 粗体下划线；H2 粗体；H3 保持正文字重但采用主题主色；H4+ 采用斜体。消除语法泄漏，还给用户沉浸式的阅读体验。

3. 工具执行透明边框卡片：
• 针对 Pending / Running / Error 状态的工具调用卡片，移除刺眼的实心背景底色填充，改为仅渲染精致的周边线框，避免破坏终端深色透明主题的通透感。

4. 用户气泡圆角包裹与 OSC 133 标记：
• 为用户输入的指令渲染完整的圆角外框，并无缝包裹 OSC 133 Shell 集成转义标记，便于高级终端利用快捷键实现精确的分段定位跳转。

实机排版渲染展示（Markdown 全要素真彩截图）

• 标题语法完全脱敏：首行 H1 标题 架构解析与执行上下文 与次级 H2 核心接口契约定义 彻底摆脱了源码中的 # 与 ## 前缀，以双倍高粗体与主色对比自然拉开阅读层级；

• 圆角包裹代码块与独立行号槽：TypeScript 接口定义被平滑收纳在 ╭─── typescript ───╮ 与 ╰───╯ 之间，行号 1–5 拥有严格的右对齐槽位与右侧隔离边距，关键字、类型名均获得 Tree-sitter 高亮；

• 引用边条（Blockquote Rail）：引用段落左侧配以柔和的 ▏ 边缘指示条，斜体强化设计准则；

• 清晰紧凑的表格布局：采用细线框 boxSharp 渲染四列组件指标，自适应单元格宽度且不溢出物理屏幕。

6.4 Fork 交互效率跃升：Bash 历史检索、补全与全局视口跳转

1. Bash 模式下的 Ctrl+R 历史检索与 Tab 补全：
在 CLI 内置的 Bash 执行模式下，完整还原了现代 Shell（如 Zsh/Fish）的操作习惯，引入了基于历史命令的实时幽灵文本（Ghost Text）提示与 Ctrl+R 模糊逆向检索。

2. 全局视口跳转（session-nav.ts / Alt+U）：
在动辄几百轮的长会话中，传统的滚动条滚动手感极其沉重。Fork 开发了无侵入的扩展组件 session-nav，用户只需按下 Alt+U 即可唤起所有用户 Turn 的模糊检索面板，轻敲回车即可瞬间将真实转录视口定位至对应问答段落，极大释放了长程审阅负担。

6.5 无头终端评测工模与真实 PTY 像素级截屏（Headless Verification Rig）

1. 原生 PTY 会话沙箱：利用 Bun 底层 PTY 接口（Bun.spawn + terminal: { cols, rows, data }）加载 omp-patched 真实二进制；

2. WASM 级 Kitty 终端内核追踪：通过 kitty-vt-wasm（编译自 Kitty 的 screen.c 与 vt-parser.c）接管 PTY 全量字节流，精准还原 SGR 属性、多屏切换（Alt Screen）、Unicode 宽字符折行与 Kitty Graphics 协议图元；

3. Skia 像素级栅格化与 CJK 字库合成：借助 @napi-rs/canvas，在内存中动态注册等宽编程字体（如 Maple Nerd Font Mono）与中文字库（Noto Sans CJK SC），模拟真实终端以 2x 缩放光栅化生成 1664x1024 像素的 RGBA 真实真彩截图，为博客及自动化测试提供零误差的可视化证据链。

实机运行抓取效果展示（Space Bunny 模型驱动）

• 代码块圆角边框与行号槽：第 5–21 行 Python LRU Cache 代码块被完整包裹在 boxRound 边框内，左侧为独立的右对齐行号槽，注释与类型高亮层次分明；

• 语法脱敏正文：代码下方的 1–3 点设计说明排版紧凑，正文字重分明，无任何漏网的 Markdown 源码字符；

• 单 Turn 耗时与速率度量：倒数第 4 行记录了模型单次请求的统计（ 423  412  24K  2.6s  67.2/s）；

• Fork work-usage 计费看板：倒数第 2–3 行由两道细分界线框出，聚合统计了本轮用户交互经历的完整开销（3 次请求，总耗时 17.3s，Cache 命中率 98.7%）；

• 冷启动预热状态栏：底部常驻 Status Line 清晰呈现模型标识 Space Bunny Alpha、预热拉取的分支状态 master *7 ?2 与 󰁨 1M 上下文标识。

6.6 TUI 智能输入补全体系：斜杠指令、上下文引用与 Bash 幽灵文本（Composer & Ghost Text）

1. 斜杠指令层级补全与频次动态加权（Slash Commands /）

• 全指令拓扑索引：统一聚合内置系统核心指令（/exit, /clear, /model, /compact, /rewind）、自定义 Prompt 模板、用户自建指令以及通过 Extension 动态注册的全部插件命令；

• 调用频次动态加权（Frequency Ranking）：
底层通过 commandUsage 记录开发者日常敲击每条指令的历史热度。高频命令（如常用的 /model, /clear）无需打完整单词，敲出 / 后自动浮现在候选菜单的第一位，实现零思考回车直达；

• 次级参数智能级联补全（Sub-argument Completion）：
针对复合指令提供上下文感知的二级补全。例如输入 /mcp 时，补全引擎自动转入服务名与子动作状态机，动态列出当前已注册的 MCP Server 清单及 enable / disable / test 动作；输入 /move 时，无缝级联调出工作区目标目录补全浮窗。

2. 上下文文件引用与符号模糊补全（@ Context Files）

• 非阻塞 Git 文件树缓存与 Ripgrep 预扫描：
针对数十万文件的大型 Monorepo，引擎坚决避免在击键时同步遍历文件系统，而是复用后台预热的活跃 Git 树索引；

• 智能过滤与图标渲染：
天然遵守 .gitignore 规范，自动过滤 node_modules/、target/、dist/ 等二进制或中间构建产物；在弹窗列表左侧根据扩展名动态渲染对应的 Nerd Font 文件类型图标（如 TypeScript 的 、Rust 的 、Python 的 ）；

• 东亚宽字符像素级锚定（East Asian Width Alignment）：
在现代终端中，中文字符与部分 Nerd 图标物理占据 2 个显示单元格（Columns）。若使用常规 string.length 计算光标位置，输入框中的弹窗菜单会严重向右漂移撕裂。Harness 全面调用 Bun.stringWidth() 精确计算物理视口占用，确保候选浮窗在任何宽窄字符混排下均严格垂直对齐在 @ 字符的正下方。

3. Bash 模式专用补全与幽灵文本预测（! / !!，Patch 15/16）

• 首词命令与路径智能分流（Token Routing）：
• 若首个词以 /、./、../ 或 ~ 开头，引擎自动将其判定为路径执行，无缝委托给文件系统补全；
• 若首个词为常规字符串，引擎立即进入可执行程序与别名扫描管线；

• 全量 $PATH 扫描与缓存：
扫描环境变量 $PATH 下所有目录中的可执行二进制名称，并基于 $PATH 字符串指纹建立进程级缓存；

• 用户个人 Shell 别名预热（alias -L）：
为了不破坏开发者的肌肉记忆，Harness 在后台异步以单例模式拉起一次用户的登录交互式 Shell（$SHELL -ic 'alias -L'），带 300ms 按键等待与 5000ms 兜底超时。开发者在个人 .zshrc / .bashrc 中定义的各种私有简写（如 gco, gst, k8s）在初次按下 Tab 时即刻享有毫秒级补全；

• 行内幽灵文本历史预测（Ghost Text Prediction）：
通过流式分析 ~/.omp/agent/shell-history.json 中的历史命令序列，当开发者键入命令前缀时，光标后方自动以半透明的暗灰色字体投影出最有可能的历史整句。按下 Tab 或 Right-Arrow，整句直接一键采纳上屏，媲美 Fish / Zsh-autosuggestions 的极速交互手感。

4. 行内拼写预测与 Emoji 快捷展开

• 行内单词补全（spelling.autocomplete）：针对英文长单词提供轻量级行内提示，Tab 键带空格采纳，Right-Arrow 键无空格采纳；

• Emoji 快捷展开（emojiAutocomplete）：支持 :smile: 等标准 Shortcode 补全，并在打字回车时自动将 :D、:-) 等传统 ASCII 字符表情就地展开为标准 Unicode 图标。

5. 扩展插件补全堆叠架构（addAutocompleteProvider）

7. 运行时可观测性与计量度量

7.1 原生单次调用计数与统计数据库（stats.db）

• 后台异步同步 Worker（__omp_worker_stats_sync）：
为了防止高频写数据库导致终端 TUI 渲染发生微卡顿，宿主在启动时通过隐藏的 argv 选择器拉起专用的 Worker 线程。主进程通过非阻塞 IPC 将每次流式通信的 Metrics 投递给 Worker，由后者在后台异步向 SQLite 数据库 ~/.omp/stats.db 批量落盘；

• 结构化三维度量模型：
数据库维护 sessions、turns 与 requests 三级树状关联表，精细记录每次请求的 timestamp、model_id、provider、input_tokens、output_tokens、cache_read_tokens、cache_write_tokens、duration_ms 以及折算后的美分成本 cost_cents；

• 多维大盘报表（omp stats）：
提供类似 ccusage 风格的终端仪表盘，支持按日、周、月的时间序列统计，并支持按项目目录（Folder）、模型家族（Model Family）以及代码功能块（Blocks）展开多维透视，帮助开发者精确掌握算力支出分布。

7.2 Fork Turn 级别聚合计量看板（work-usage.ts）

1. 监控缺陷：ReAct 循环的“黑盒记账失真”

2. WorkUsageAccumulator 双层状态机实现

• 贯穿多轮请求生命周期：跨多次流式网络往返累加输入、输出、缓存写入与读取 Token 数；

• 精细耗时拓扑拆分：将总耗时严格划分为四个物理维度：
1. workTime：整个回合的总跨度耗时；
2. modelTime：所有模型请求的净网络出流时间之和；
3. toolTime：本地文件 I/O、Git 扫描或 PTY 执行等工具耗时之和；
4. waitTime：网络建立、排队调度与空闲等待时间；

• TUI 转录流优雅呈现：在每个用户 Turn 的最末尾，以低侵入感的暗色样式渲染双行聚合看板：

3. 用户 Esc 强制打断时的计费强健对账机制（Interrupted Request Reconciliation）

• 原生记账漏洞：客户端触发 AbortController.abort() 关闭流式传输后，原生异常处理往往将该次请求标记为 Aborted 并直接丢弃，导致本地统计中这部分 Token 凭空蒸发；但实际上远端大模型服务商早已生成了这部分内容并如实计费，导致本地账单与云端对账产生严重偏差；

• Fork 对账自愈：在流式中止捕获逻辑中，Fork 从传输层已经成功接收并结算的字节帧中抽取截断处的 Usage 报文，强制推入 Accumulator 并落盘入库，杜绝“隐瞒实际算力成本”。

7.3 Fork 工具与搜索吞吐量遥测（searchThroughput）

• 首字节到达时间（TTFB）与出流时间分离：
将网络建连、搜索引擎接口排队、反爬握手的等待时间与后续模型阅读摘要的真实出流时间严格剥离；

• 吞吐率计算模型：

• 故障与未完成语义严肃性：当网络发生 504 超时、降级重试或未完成完整测量时，卡片上显式打印为 null 而非具有欺骗性的 0 tok/s，为开发者排查网络瓶颈源自搜索源还是模型本身提供了坚实的量化依据。

8. 生产级配置全景示例（含 Claude Code 伪装、Codex 与中转实战脱敏模版）

8.1 智能体主配置：~/.omp/agent/config.yml

8.2 模型与 Provider 注册表：~/.omp/agent/models.yml（多协议实战）

8.3 热重载重试规则配置：~/.omp/agent/retry-rules.json

8.4 惰性 MCP 配置：~/.omp/agent/mcp.json（以 Notion 实战为例）

1. 当会话启动时，notion 与 github 均不会拉起子进程，也不会与远端服务通信，启动耗时 0ms；

2. 系统仅在当前可用设备树中分别暴露 xd://mcp__notion_gateway 与 xd://mcp__github_gateway 两个极其轻量的占位设备；

3. 仅当任务指明“向 Notion 追加博客”时，Agent 向 xd://mcp__notion_gateway 写入 {}；

4. Harness 底层即时拉起 node 进程完成握手，随后触发 onToolsChanged，将真正的 notion_append_block、notion_query_database 等十余个专业工具注入当前会话，完成无感即时升级。