miao 与 opencode 基线：差异、证据与可用范围
miao 延续 opencode 的开源编程工作流，把工程投入集中在上下文效率、会话执行控制和可观察的运行成本上。本页介绍 fork 的实现与已有的基准记录，不是对当前上游产品的功能审计。模型选择、MCP、子代理等共有能力，不作为 miao 独有功能宣传。
**状态截至 2026-10-04：**最新正式发布版为 v0.1.4。本页区分已发布功能与之后合入 main 的
源码改动。源码或 preview 构建仍可能显示相同版本号；具体包含哪些修复，应以提交和构建来源为准。
对日常工作流有用的差异
Section titled “对日常工作流有用的差异”| 方向 | miao 的实现 | 实际价值 | 可用状态 |
|---|---|---|---|
| 执行中补充要求 | 先持久化输入；steer 在安全轮次边界生效，显式 queue 在空闲边界处理 | 工作继续推进，新增要求有待处理记录 | V2 |
| 会话协作 | task、可继续的子会话、项目内 list_sessions／send_message |
把专项工作委派出去，在不同对话之间交换发现 | V2；消息受权限约束 |
| 上下文稳定性 | 不可变的 Context Epoch 基线，按时间顺序引入变化 | 减少缓存前缀不必要的变化 | V2 |
| 成本与缓存可见性 | 逐轮用量、估算成本、TTFT、缓存命中率与状态分类 | 用数据定位昂贵或缓慢的轮次 | 已实现 |
| 上下文控制 | 工具输出限额、可选裁剪、压缩设置、缓存 TTL | 限制大量工具输出与长历史占用上下文 | V2；高级设置按需开启 |
| 长任务续跑 | 待办驱动循环、迭代／停滞检测、可选费用预算 | 多步骤任务无需每次空闲后都手动发送继续 | V2，需开启 |
| 持久化历史 | 输入箱与事件记录、会话分叉与导出 | 终端关闭后仍有可检查的工作记录 | V2；不含崩溃后自动续跑 |
| 独立分发 | 独立版本与更新源，正式／源码／预览三个入口 | 日常工具与开发验证可以并存 | 已实现 |
| 会话记录更新 | 按持久化事件增量应用、按视口窗口渲染 | 减少完整历史重载与屏幕外渲染工作 | v0.1.4 已发布 |
| 待处理输入恢复 | 读取其他进程准入、没有 live 事件通知的持久化排队输入 | 跨进程恢复可见的待处理工作 | 已发布；v0.1.4 二进制已在 Linux 验证 |
| 供应商故障可见性 | 显示最终错误与有界重试状态 | 区分请求失败与看似空闲的代理 | v0.1.4 已发布 |
费用估算依赖配置的模型费率与货币信息。预算达到阈值后停止调度，不截断正在执行的请求，也不能替代供应商账单。缓存效果取决于供应商与任务，没有承诺固定的整任务省钱比例。
最新源码进展与规划
Section titled “最新源码进展与规划”下列改动在 v0.1.4 发布之后已合入 main，但尚未进入新的正式发布版：
| 方向 | 已合并实现 | 证据与边界 |
|---|---|---|
| 流式状态一致性 | 对账排队的流式文本与历史快照，防止陈旧全量快照覆盖 live todo | 有重复文本、live 更新回退的回归覆盖（#45、#42） |
| 会话生命周期 | 释放已删除会话的历史缓存与 TUI 旧会话记录状态 | 有清理回归覆盖（#31、#32）；不等于证明一般性内存泄漏已修复 |
| 请求恢复 | 为瞬时连接与超时故障分类并有界重试 | 真实 TCP 断连回归（#47）；不重放已发布输出 |
| 重复输出保护 | 中止文本/reasoning 的高置信度短句循环；只隔离供应商上下文，保留持久化记录与已完成工具 | 有按流隔离、无副作用重放的回归（#53）；不是已证实修复了供应商或模型根因 |
| 读取路径效率 | 缓存不可变 blob 编码、跳过无变化的投影写入及纯投影会话的旧表读取、分页读取持久化事件尾部 | 有独立实现和回归（#48–#52）；没有新的端到端提速百分比 |
| 项目架构 | 项目持久化由 core 负责，删除旧 miao Project facade | 已完成迁移与生命周期回归（#35、#36、#46） |
重复输出调查发现，同一供应商/模型同时存在正常会话，其中一些报告的输入更大。因此，长度本身 不足以解释故障。首版保护识别短的换行自然语言循环，不覆盖所有重复形式，详见 调查与边界。
V2 工具接入后台任务、崩溃后自动续跑、MCP 工具渐进发现、blob 垃圾回收，以及 bash 之外的沙箱 覆盖仍处于规划或未完成状态，不作为当前可用功能宣传。当前工作见路线图。
近期会话记录、缓存与读取路径优化已有回归证据，但没有受控的前后对比证明相对当前上游 opencode 的整任务提速或特定内存下降。下面的基准是另一种范围的历史测量。
已有的原生基准记录
Section titled “已有的原生基准记录”基线是本仓库引入原生模块之前的 TypeScript 实现，不是当前的 anomalyco/opencode。数据为同机 release 构建的中位数，测量经 Rust 插件调用的独立操作，不包含双方共有的编排、I/O、LSP、格式化、供应商延迟或模型推理。本次文档更新没有重新运行这些基准。表中的原生 edit／patch 路径属于已被删除的 V1 兼容工具，数字作为历史组件测量保留。
| 操作 | TypeScript 基线 | Rust 原生 | 提速 | 接入范围 |
|---|---|---|---|---|
| edit 精确匹配（12k 行） | 0.21 ms | 0.12 ms | 1.7x | 已删除的 V1 路径 |
| edit 模糊匹配（12k 行） | 0.76 ms | 0.39 ms | 1.9x | 已删除的 V1 路径 |
| edit 匹配 + diff 统计（12k 行） | 2.03 ms | 1.78 ms | 1.14x | 已删除的 V1 路径 |
apply_patch deriveNewContents exact（20k 行） |
1.67 ms | 1.28 ms | 1.3x | 已删除的 V1 路径 |
| apply_patch trim 匹配（20k 行） | 3.47 ms | 1.76 ms | 2.0x | 已删除的 V1 路径 |
| apply_patch unicode 归一化（20k 行） | 13.06 ms | 5.21 ms | 2.5x | 已删除的 V1 路径 |
| git status 小仓（10 文件 / 2 变更） | 12.3 ms | 1.0 ms | 11.9x | 原型，未接入默认路径 |
| git status 大仓（2200 文件 / 400 变更） | 13.6 ms | 5.8 ms | 2.4x | 原型，未接入默认路径 |
匹配和归一化等 CPU 密集操作的收益更明显；进程内 Git 原型减少了子进程启动开销。这些结果都不等于完整编程任务的端到端提速。
原生工具与沙箱：适用范围
Section titled “原生工具与沙箱：适用范围”V2 是唯一的会话运行时，工具位于 packages/core/src/tool；V1 兼容工具及其在 packages/miao/src/tool 的原生 edit／patch 路径均已删除。
- edit／patch： V2 工具是 TypeScript 实现（
edit-fuzzy.ts等）。上表中的原生 edit／patch 加速已不再接入任何已发布工具。 - OS 沙箱： V2
bash工具可以把每条命令放进沙箱运行。macOS 用 seatbelt，Linux 用 Landlock，Windows 暂无后端。用sandbox.mode: "workspace-write"或MIAO_SANDBOX=1开启，MIAO_SANDBOX_DENY_NETWORK=1禁止网络。默认关闭，需显式开启。 - native addon：
MIAO_NATIVE=0可禁用 addon。它为沙箱 runner 和其他原生辅助提供支持，不用于 V2 edit／patch。 - 进程内 Git： 已有
gix实现和基准，尚未成为默认 Git 路径。
依赖沙箱前，请阅读 使用指南 与 接入风险。Windows 内核沙箱尚未实现同等能力。
边界与后续工作
Section titled “边界与后续工作”- V1 会话运行时及其
/session/*路由已删除，所有已发布客户端都运行 V2；旧数据库与配置读取为兼容保留；无前缀的非会话旧路由也已移除。 - 持久化历史与精确提示重试校验，不等于模型执行自动恢复或 Shell 副作用严格只发生一次。
- 会话执行和消息唤醒限于本进程，不宣传跨机器代理集群。
- Code Mode 属于实验功能；生成的客户端与内嵌 host 是私有工作区包，契约仍在演进。
- 消息权限的逐目标策略持久化、接收会话的循环成本计量仍有设计工作，见 会话消息规格。
产品概览见 README，操作方法见 使用指南，运行时契约见 CONTEXT.md。
Synced from oxdingzg/miao@efb8c00.