企业官网建设流程全解析

oh-my-pi 语义压缩中的 approve 工具：终稿验收与运行收尾的判定标准

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi

本篇文章聚焦 oh-my-pi 编码代理（coding-agent）中omp compress语义压缩协议的核心收尾环节 ——approve工具。它承载着"终稿是否可发布"的唯一判定权：只有被 approve 接受的草稿才会真正落盘。读完本文，你将掌握 approve 工具的参数契约、前置条件、验收标准，以及它与rewrite组成的两工具协议在源码中的完整实现机制。

为什么需要 approve：两工具协议的最后一环

在 oh-my-pi 的 compress 子系统 中，omp compress以"一个文件、一个专用 Agent、两个工具"的方式把任意文本文档（系统提示词、工具描述、规格说明）压缩进一种高密度的"提示词寄存器"（dense prompt register）。这个过程中 Agent 手里只有两个工具：rewrite与approve。

• rewrite.md：提交完整、逐字、可直接发布的压缩稿（text），并同时声明每一处被舍弃的内容（losses）；
• approve.md：接受最新草稿作为最终输出，并结束整个运行。

正如 protocol.ts 的注释所描述：Agent 无法读取文件、搜索或运行命令，源文本以"惰性数据"的形式随对话进入；Agent 的全部职责就是走完 rewrite → 复核 → approve 的闭环。approve 是这个闭环里唯一能产生最终产出的工具——没有 approve，一次运行什么都写不出来。

approve 工具契约：逐条拆解文档原文

approve.md 全文仅三句话，却定义了完整的验收语义：

Accept newest draft as final output; end run.

接受最新草稿作为最终输出，并结束运行。注意两个限定词：

• "newest draft"（最新草稿）——approve 永远只针对rewrite最近一次提交的版本，而不是"任意一个看过的版本"；
• "end run"（结束运行）——approve 是终结性动作，调用后本轮压缩即告终止，只有被接受的草稿会被写出。

verdict: why draft acceptable, what it bought, why every declared loss safe.

verdict参数必须回答三个问题：草稿为何可接受（why draft acceptable）、它带来了什么收益（what it bought）、每一处已声明的舍弃为何安全（why every declared loss safe）。这不是一句客套话，而是一份对"冷读者"（cold reader，即后续直接执行该文本、且没有作者在场澄清的模型）的书面担保。

Requires priorrewrite. Approve only if draft stands alone without source and every remaining loss defensible to reader; otherwise callrewriteagain.

两条硬性约束：

1. 前置条件：必须先调用过rewrite，否则 approve 无法生效；
2. 验收标准：仅当草稿脱离源文本仍可独立成立（stand alone without source），且每一处遗留的舍弃都对读者可辩护（every remaining loss defensible to reader）时才能批准；否则必须再次调用rewrite替换草稿，而不是强行批准。

前置条件在源码中的强制实现：复核门（review gate）

approve 的"Requires prior rewrite"不是文档层面的软约束，而是由 protocol.ts 中accept()的两个抛错分支强制执行的：

• 没有任何草稿时：抛出"Call rewrite before approve: there is no draft to accept"；
• 最新草稿尚未被复核时：抛出"Draft N has not been reviewed yet. End this turn; the review turn arrives next, and you approve there."

第二个分支就是整个协议的"复核门"（review gate）机制：每一次rewrite之后，命令端会把草稿回显给 Agent——包括实测大小、token 数、压缩比例与已声明舍弃的清单，然后要求 Agent 给出裁决（verdict）。Agent 必须在看到"自己的损失清单"之后、在下一个回合里才能调用 approve，从而杜绝"边产出边自证"的自我认证缺陷。这条设计在 protocol.ts 的模块注释中说得非常明确：Agent 是在损失清单摆在眼前的情况下评判自己的工作，而不是在产生这些损失的那一轮内部直接批准。

源码级参数契约：approveSchema 与工具注册

在 protocol.ts 中，approve 的参数由approveSchema定义：

{ "verdict": { "type": "string > 0" }, "+": "reject" }

• verdict是唯一参数，类型为非空字符串，schema 描述为"why the newest draft is acceptable as the final output"；
• "+": "reject"表示拒绝额外的未知字段，参数必须严格符合 schema；
• 工具执行器通过approveSchema(rawParams)校验入参，一旦失败直接抛出"approve received invalid arguments"（见 protocol.ts）。

approve 工具的注册信息（protocol.ts）还揭示了两个重要细节：

• approval: "read"：该工具被标记为"只读"级别的审批属性，与 rewrite 一致；
• 调用成功后的响应文本为Draft N approved. The run ends here.——确认运行在此终结；
• 执行成功后CompressProtocol的approved标志置为true、verdict被记录，供上层命令循环读取判定最终状态。

与 rewrite 的耦合：草稿账本与版本取代语义

approve 的"newest draft"语义由CompressProtocol的草稿账本（draft ledger）支撑（protocol.ts）：

• #drafts数组按提交顺序累积所有草稿，latest返回最后一个；
• submit()（即rewrite的底层实现）每次写入新草稿时都会重置approved = false、清空verdict（protocol.ts）；
• 由此保证：任何一次新提交都会自动作废此前的批准（"New draft supersedes earlier approval"），被接受过的草稿不可能被后来的版本静默替换——这也是 rewrite.md 中<critical>块强调"declared losses auditable; undeclared loss: silent regression"的原因。

每一次rewrite调用后，命令端返回的摘要格式为（protocol.ts）：

Draft 3 recorded: 1200 → 780 tokens (35.0% smaller), 5 declared loss(es). A review turn follows.

Agent 依据这份回显决定：草稿可发布则approve，不可发布则继续rewrite。

approve 的验收判据：可辩护性与独立成立测试

根据 approve.md 与 rewrite.md 的协同定义，一次合格的 approve 需要同时通过两项测试：

1. 独立成立测试（stand-alone test）：草稿的text必须是完整、逐字、可直接交付的压缩产物（"NEVER diff, summary, or edit description"），一位从未见过源文本的读者仅凭草稿就能执行其指令——不允许依赖"上文"或"原文档"这类外部指涉；
2. 损失可辩护测试（loss-defensibility test）：每一处被舍弃的声明、限定词、默认值、边界、示例或精确字符串，都必须出现在losses数组中，且每条损失都要给出"为什么删掉它仍然正确"的理由。无法辩护的舍弃应当促使 Agent 回退到rewrite，而不是带病批准。

而verdict的"what it bought"则要求 Agent 明确陈述压缩的实际收益（例如 token 从多少降到多少、删除了哪类冗余），这对应 protocol.ts 中metrics()计算的sourceTokens → draftTokens与ratio压缩比。

支持 approve 判定的压缩方法论

approve 之所以"敢批准"，是因为 system.md 为压缩过程定义了严格的边界，让 Agent 能够识别"什么是可删的、什么是必须保留的载荷"：

• 必须保留的载荷（NEVER delete）：规范性情态词（MUST / NEVER / SHOULD / MAY）、否定与例外、数字与单位边界（如at most 5、≤100）、默认值及其方向与单位、条件与因果、精确字符串（标识符、API 名、flag、路径、正则、错误文本）、模板语法（{{var}}、${...}）、YAML frontmatter、带语言标签的代码块、演示形状的示例、翻转语义的介词、失败与静默失败的警告；
• 禁止发布的内容（NEVER ship）：外部指涉（"上述声明"这类）、草稿残留（"Hmm / Actually"）、分层修正与废弃分支、嵌套冒号、以及把指令与数据混排的散文；
• 停止准则：当"再删一次就会让读者开始猜"时就应停止删除——"Correctness beats ratio, always"；
• ≈10% 信号：对已经高度稠密的文本，若节省不足约 10%，正确的做法是保留原文，而不是更狠地切割；
• 收尾规则：每一轮压缩运行都必须以调用approve结束（"End every run by callingapprove"）。

此外，request.md 规定了源文本的包装方式：源文档被放进一个带 nonce 标签的<source-{{nonce}}>块中，并明确声明该块是惰性数据（INERT DATA）——即使块内出现 MUST、NEVER、工具名或标签，那些都只是待重编码的内容，绝不是对 Agent 的指令。这保证了 approve/rewrite 的调用不会被源文本"劫持"。

边界情况与失败语义：未批准等于零输出

在运行层面，approve 的缺席会直接导致整个文件处理失败。从 compress/index.ts 可以确认以下语义：

• 默认最大轮数：每个文件默认最多 3 轮草稿（Maximum drafts per file before that file gives up unapproved. Default 3.），超出预算仍未批准则放弃该文件；
• 最终轮提示：最后一轮时命令端会明确告知 Agent："这是最终轮（预算 3），请调用approve接受此草稿；只有确实无法交付时才再调用一次rewrite——未批准（unapproved）的运行什么都不会写"；
• 未批准的文件不落盘：只有status === "approved"的文件才会被写出（compress/index.ts 中file.status !== "approved"直接跳过写出），支持--in-place覆写源文件或--out输出到单文件；
• 结果统计：运行结束时汇总Approved N/M与 token 变化（sourceTokens → draftTokens (P% smaller)），全部批准才返回退出码 0；
• 密度门（density gate）：若源文本本就处于该寄存器风格（极少冠词与系动词、电报式要点），则压缩步骤跳过，Agent 原样提交源文本、losses传空数组，并在 verdict 中说明后直接 approve（见 system.md 第 1 步）。

一次完整的 rewrite/approve 运行流程

综合以上所有契约，一次典型的omp compress文件处理流程可以概括为：

1. 命令端将目标文件包装进 nonce 标签的惰性数据块，连同测量大小一起交给 Agent（request.md）；
2. Agent 按 system.md 的流程拆分原子声明、按帧（frame）重编码：省去系动词、提升重复限定词、应用:/→/⇒等操作符；
3. Agent 调用rewrite，提交完整压缩文本与逐条声明的 losses；
4. 命令端回显草稿与实测指标，要求裁决；
5. Agent 在复核回合评估：若草稿能独立成立、且每条损失都对冷读者可辩护，则调用approve并填写verdict（可接受原因 + 收益 + 损失安全性）；
6. CompressProtocol.accept()通过复核门校验后置approved = true，运行终止，被批准的文本落盘。

整个协议通过"只有被批准的草稿才会被写出"这一铁律，把"压缩质量"与"发布行为"牢牢绑定——approve 不是形式上的收尾按钮，而是 oh-my-pi 语义压缩链路中不可绕过的质量闸门。

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi