@maxiaochao/pi-toolkit 0.8.2 → 0.9.1

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2026-09-30 - v0.9.1
+
+- redesign the todo lifecycle with plan replacement, cancellation, automatic advancement, active-only widget rendering, concise model guidance, and deterministic state tests
+
+## 2026-09-30 - v0.9.0
+
+- merge the Codex-style apply_patch extension into the toolkit (from the standalone @maxiaochao/pi-codex-edit v0.1.6): it now ships as extensions/codex-edit/ registered in pi.extensions, its parser and model-routing tests join npm test, and the separate package, release script and publish workflow are removed
+
 ## 2026-09-24 - v0.8.2
 
 - tapd skill: document the safe attachment-download flow for the short-lived signed URLs (re-fetch the URL for every attempt, download to .part with curl --fail --location --retry 3, reject text/error bodies before resuming, accept only 206 with a matching Content-Range, then verify size and zip integrity before renaming); it is a local addition on top of the `tapd skill init` output, recorded in AGENTS.md

package/README.md

@@ -1,6 +1,6 @@
 # pi-toolkit
 
-Personal Pi toolkit with the `/todos`, `/btw`, and `/cache_export` extensions, bundled agent skills including Chrome/Chromium automation, the Night Owl theme, and the `pi-worktree` CLI.
+Personal Pi toolkit with the `/todos`, `/btw`, `/cache_export`, and `apply_patch` extensions, bundled agent skills including Chrome/Chromium automation, the Night Owl theme, and the `pi-worktree` CLI.
 
 ## Install
 
@@ -38,6 +38,8 @@ To synchronize the file directly from a checkout instead:
 bash scripts/install.sh
 ```
 
+The `todo` tool maintains a session checklist for explicit plans and multi-step work. It automatically keeps one task active and advances the next queued task; `replace` starts a clean plan after a change of direction, while `cancelled` records obsolete work honestly. The persistent widget shows active work only, and `/todos` shows active and closed tasks in the current plan.
+
 The `/btw` side chat is a separate agent session. It can inspect the main conversation and repository, and its thread stays out of the main context until you close it and choose to inject a summary. Use `/btw` to open it or `/btw <question>` to ask directly. While the BTW overlay has focus, use `Up` / `Down` to scroll its transcript one line at a time and `PageUp` / `PageDown` to move by one transcript page.
 
 Use `/cache_export [path]` to write an interactive per-request cache dashboard. It defaults to the latest Context segment for current-state diagnosis, and the View selector can show any earlier segment or all session history. Compaction and model changes both break context charts into segments; cache-hit accumulation also resets at model changes, while TTL and other inferred interruptions remain diagnostic events rather than segment boundaries.
@@ -87,6 +89,8 @@ The bundled `pdlog` skill decompresses and reads Pudu `.pdlog` proprietary log f
 
 The bundled `herdr` skill (from [herdrdev/herdr](https://github.com/herdrdev/herdr) at tag `v0.9.1` with the skill name lowercased, Apache-2.0) drives Herdr, a terminal multiplexer for coding agents: inspecting workspaces, tabs, and panes, starting and prompting other agents, running commands in background panes without stealing focus, reading pane output, and waiting on agent lifecycle states. It activates only when you explicitly mention Herdr, and only when the agent itself runs inside a Herdr pane (`HERDR_ENV=1`); outside a pane it refuses to control the session and stops.
 
+The bundled `agent-team` skill runs cross-vendor adversarial review: the current session acts as manager, and the roster in `skills/agent-team/models.json` (one auditor, one replicator, one adversary on different vendors) is started as long-lived herdr panes that get re-prompted round after round until no pane can produce a new finding.
+
 The bundled `tapd` skill documents the third-party `tapd` CLI ([studyzy/tapd-ai-cli](https://github.com/studyzy/tapd-ai-cli)) for TAPD: requirements, defects, tasks, iterations, wikis, comments, attachments, timesheets, and workflow status maps, including the `--filter` advanced query syntax. It is the CLI's own command reference, so refresh the file with `tapd skill init` when the CLI changes.
 
 The bundled `calldiff` skill (copied verbatim from [tanishqkancharla/calldiff](https://github.com/tanishqkancharla/calldiff), MIT, pinned to a `main` commit because upstream has no release tags) teaches call-stack diffs across git commits: `diff` shows which callees appeared, disappeared, or moved under an entrypoint, `tree` prints one call tree, and `reach` finds call paths between two symbols, all with `--entry`/`--file` entrypoint selection, `--locs` source locations, and `--format json` for agents.
@@ -108,21 +112,13 @@ pi update npm:@maxiaochao/pi-tiny-subagent
 
 See [packages/tiny-subagent/README.md](packages/tiny-subagent/README.md) for personas, model selection, child isolation, live transcript rendering, and diagnostics.
 
-## Codex Edit
-
-The Codex edit package is a separate npm package. Install it when you want GPT/Codex models to use the freeform `apply_patch` protocol while other models keep Pi's native `edit` tool:
-
-```bash
-pi install npm:@maxiaochao/pi-codex-edit
-```
+## Codex Edit (apply_patch)
 
-It includes the extension implementation plus the benchmark summary and interactive architecture explainer. Its versions, release workflow, and tag are independent from the root package and tiny subagent:
+The `apply_patch` extension ships with the toolkit as part of `pi.extensions`. It activates Codex's freeform `apply_patch` protocol for GPT/Codex models while other models keep Pi's native `edit` tool. Routing is by model ID (`gpt-5.6-*`) plus API (`openai-responses` or `openai-codex-responses`); provider does not matter. For every other model the extension only re-syncs an already-active editor tool, so it is a no-op.
 
-```bash
-pi update npm:@maxiaochao/pi-codex-edit
-```
+Because it ships with the toolkit, there is nothing extra to install or update — `pi update npm:@maxiaochao/pi-toolkit` covers it. The model allowlist lives in `extensions/codex-edit/config.json` inside the installed package; edit it there only if you need a different allowlist.
 
-See [packages/codex-edit/README.md](packages/codex-edit/README.md) for the routing rules and [packages/codex-edit/summary.md](packages/codex-edit/summary.md) for the measured tradeoffs.
+See [extensions/codex-edit/README.md](extensions/codex-edit/README.md) for the routing rules and [extensions/codex-edit/summary.md](extensions/codex-edit/summary.md) for the measured tradeoffs, including why it stays limited to the `gpt-5.6-*` allowlist instead of replacing `edit` everywhere.
 
 ## Development
 

package/extensions/codex-edit/README.md

@@ -0,0 +1,53 @@
+# Codex Edit (apply_patch)
+
+A Pi extension bundled with `@maxiaochao/pi-toolkit` that exposes Codex-style `apply_patch` for GPT/Codex models and keeps Pi's native `edit` tool for other models.
+
+## Install
+
+Bundled with the toolkit; install or update the root package and the extension comes along:
+
+```bash
+pi install npm:@maxiaochao/pi-toolkit
+pi update npm:@maxiaochao/pi-toolkit
+```
+
+The extension registers `apply_patch` and selects the editing tool from the resolved model configuration:
+
+- Allowlisted GPT/Codex model: `apply_patch`
+- Other models: Pi's native `edit`
+
+The default allowlist enables all `gpt-5.6-*` models regardless of provider. Other model families can be added after separate validation by editing `config.json`.
+
+The extension does not add a permanent AGENTS rule telling models not to use `apply_patch`. Only the selected editor tool is active, so the model receives one editing protocol.
+
+## What `apply_patch` does
+
+The tool accepts raw Codex patch text between `*** Begin Patch` and `*** End Patch`. It supports:
+
+- `Add File`
+- `Delete File`
+- `Update File`
+- `Move to`
+- multiple update hunks with `@@` context
+- EOF-oriented insertions
+
+Before writing, it parses the complete patch, resolves paths, rejects workspace escapes and unsafe symlink/parent paths, reads all source files, and computes every update in memory. Only after preflight succeeds does it mutate files. It returns per-file diff details and reports committed paths if a later filesystem operation fails.
+
+## Configuration
+
+The extension defaults to a model-ID allowlist in `config.json`: `"gpt-5.6-*"`. Provider does not affect routing. Each entry is a `*` glob, so this matches every `gpt-5.6-` variant. The route additionally requires:
+
+```text
+model.api = openai-responses or openai-codex-responses
+```
+
+Grammar support is not part of the route. When a provider does not emit Lark grammar tools, Pi falls back to a normal function tool, so `apply_patch` still runs there — only the grammar-enforced output shape is lost.
+
+Edit `extensions/codex-edit/config.json` inside the installed `@maxiaochao/pi-toolkit` package only if you need to change the default allowlist. The implementation keeps both tools registered for session replay and changes only the active tool set on `session_start` and `model_select`.
+
+## Documentation
+
+- `summary.md`: benchmark summary and decision record.
+- `codex-edit-explainer.html`: self-contained interactive architecture and configuration explainer.
+
+The benchmark found equal final correctness in the fair 20-case comparison, with first editor-call success improving from 85% to 95%. Overall tool-call count and cache-inclusive token use were effectively unchanged, so the route stays limited to the GPT/Codex allowlist rather than replacing `edit` universally.

package/extensions/codex-edit/codex-edit-explainer.html

@@ -0,0 +1,316 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Pi apply_patch 方案说明</title>
+<style>
+:root {
+  --ink: #17221f;
+  --muted: #65736d;
+  --paper: #f5f7f2;
+  --panel: #ffffff;
+  --line: #d9e1db;
+  --green: #0e6b50;
+  --green-soft: #dcefe7;
+  --amber: #a96518;
+  --amber-soft: #fff0d9;
+  --red: #a33c32;
+  --red-soft: #fde5e0;
+  --blue: #245f8c;
+  --blue-soft: #e2eff8;
+  --shadow: 0 12px 32px rgba(23, 34, 31, .08);
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+* { box-sizing: border-box; }
+html { scroll-behavior: smooth; }
+body { margin: 0; color: var(--ink); background: var(--paper); line-height: 1.55; }
+button { font: inherit; }
+.topbar { position: sticky; top: 0; z-index: 5; background: rgba(245,247,242,.94); border-bottom: 1px solid var(--line); backdrop-filter: blur(12px); }
+.topbar-inner { max-width: 1180px; margin: auto; padding: 14px 26px; display: flex; align-items: center; justify-content: space-between; gap: 18px; }
+.brand { font-weight: 800; letter-spacing: .02em; }
+.brand span { color: var(--green); }
+.nav { display: flex; gap: 6px; flex-wrap: wrap; justify-content: flex-end; }
+.nav a { color: var(--muted); text-decoration: none; padding: 6px 10px; border-radius: 7px; font-size: 13px; }
+.nav a:hover, .nav a:focus-visible { color: var(--green); background: var(--green-soft); outline: none; }
+main { max-width: 1180px; margin: auto; padding: 58px 26px 90px; }
+.eyebrow { color: var(--green); font-size: 12px; text-transform: uppercase; letter-spacing: .14em; font-weight: 800; }
+h1 { font-size: clamp(34px, 5vw, 66px); line-height: 1.03; max-width: 860px; margin: 12px 0 18px; letter-spacing: -.035em; }
+.lede { max-width: 760px; font-size: 19px; color: #42514a; margin: 0; }
+.hero-grid { display: grid; grid-template-columns: 1.25fr .75fr; gap: 26px; align-items: end; }
+.signal { border-left: 4px solid var(--amber); padding: 18px 20px; background: var(--amber-soft); }
+.signal strong { display: block; font-size: 18px; margin-bottom: 5px; }
+.signal p { margin: 0; color: #66431f; font-size: 14px; }
+.section { margin-top: 70px; }
+.section-head { display: flex; justify-content: space-between; align-items: end; gap: 20px; margin-bottom: 20px; }
+h2 { font-size: 28px; line-height: 1.12; margin: 0; letter-spacing: -.025em; }
+h3 { margin: 0 0 8px; font-size: 17px; }
+.section-note { max-width: 560px; color: var(--muted); margin: 0; font-size: 14px; }
+.metrics { display: grid; grid-template-columns: repeat(4, 1fr); border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); background: var(--panel); }
+.metric { padding: 21px 18px; border-right: 1px solid var(--line); }
+.metric:last-child { border-right: 0; }
+.metric .value { font-size: 31px; font-weight: 800; line-height: 1.1; }
+.metric .label { color: var(--muted); font-size: 13px; margin-top: 5px; }
+.metric.good .value { color: var(--green); }
+.metric.neutral .value { color: var(--blue); }
+.metric.warn .value { color: var(--amber); }
+.explain { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; }
+.panel { background: var(--panel); border: 1px solid var(--line); box-shadow: var(--shadow); padding: 23px; }
+.panel p:last-child { margin-bottom: 0; }
+.badge { display: inline-flex; align-items: center; gap: 7px; padding: 4px 9px; border-radius: 999px; font-weight: 750; font-size: 12px; }
+.badge::before { content: ""; width: 7px; height: 7px; border-radius: 50%; background: currentColor; }
+.badge.amber { color: var(--amber); background: var(--amber-soft); }
+.badge.green { color: var(--green); background: var(--green-soft); }
+.badge.red { color: var(--red); background: var(--red-soft); }
+.callout { margin-top: 16px; padding: 15px 17px; border-left: 3px solid var(--blue); background: var(--blue-soft); color: #244961; font-size: 14px; }
+.callout code { color: var(--blue); }
+code, pre { font-family: "SFMono-Regular", Consolas, "Liberation Mono", monospace; }
+code { background: #edf1ee; padding: 2px 5px; border-radius: 4px; font-size: .92em; }
+pre { margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; color: #d8eee5; background: #172522; padding: 20px; border-radius: 7px; font-size: 13px; line-height: 1.65; }
+.code-wrap { position: relative; }
+.copy { position: absolute; right: 10px; top: 10px; border: 1px solid #527269; color: #d8eee5; background: #20352f; padding: 5px 8px; border-radius: 5px; cursor: pointer; font-size: 12px; }
+.copy:hover, .copy:focus-visible { background: #2d4c42; outline: 2px solid #97cdb8; outline-offset: 2px; }
+.tabs { display: flex; gap: 8px; flex-wrap: wrap; border-bottom: 1px solid var(--line); margin-bottom: 18px; }
+.tab { border: 0; background: transparent; color: var(--muted); cursor: pointer; padding: 10px 3px; margin-right: 14px; border-bottom: 3px solid transparent; font-weight: 750; }
+.tab[aria-selected="true"] { color: var(--green); border-color: var(--green); }
+.tab:focus-visible { outline: 2px solid var(--green); outline-offset: 3px; }
+.tab-panel { display: none; }
+.tab-panel.active { display: block; }
+.architecture { background: #e9f0eb; border: 1px solid var(--line); padding: 24px; overflow-x: auto; }
+.arch-row { min-width: 900px; display: grid; grid-template-columns: 1fr 36px 1.15fr 36px 1.25fr 36px 1fr; align-items: stretch; gap: 10px; }
+.arch-node { min-height: 124px; background: var(--panel); border: 1px solid #c6d4ca; padding: 16px; position: relative; }
+.arch-node small { color: var(--muted); display: block; font-size: 11px; text-transform: uppercase; letter-spacing: .09em; margin-bottom: 9px; font-weight: 800; }
+.arch-node strong { display: block; font-size: 16px; margin-bottom: 6px; }
+.arch-node p { color: var(--muted); margin: 0; font-size: 13px; line-height: 1.4; }
+.arch-arrow { display: grid; place-items: center; color: var(--green); font-size: 25px; }
+.boundary { margin-top: 20px; padding: 13px 15px; border: 1px dashed #9eb5a6; color: #456453; background: rgba(255,255,255,.55); font-size: 13px; }
+.flow { display: grid; grid-template-columns: repeat(6, 1fr); gap: 0; border-top: 1px solid var(--line); border-bottom: 1px solid var(--line); background: var(--panel); }
+.flow-step { min-height: 150px; padding: 19px 15px 18px; border-right: 1px solid var(--line); position: relative; }
+.flow-step:last-child { border-right: 0; }
+.flow-number { color: var(--green); font-size: 12px; font-weight: 850; letter-spacing: .1em; }
+.flow-step strong { display: block; margin: 15px 0 7px; font-size: 15px; }
+.flow-step p { color: var(--muted); margin: 0; font-size: 13px; }
+.flow-step::after { content: "→"; position: absolute; right: -10px; top: 57px; color: var(--green); background: var(--panel); font-size: 18px; z-index: 1; }
+.flow-step:last-child::after { display: none; }
+.compare { width: 100%; border-collapse: collapse; background: var(--panel); font-size: 14px; }
+.compare th, .compare td { padding: 14px 16px; border-bottom: 1px solid var(--line); text-align: left; }
+.compare th { background: #edf3ee; color: #405148; font-size: 12px; text-transform: uppercase; letter-spacing: .07em; }
+.compare td:not(:first-child), .compare th:not(:first-child) { text-align: right; }
+.compare .positive { color: var(--green); font-weight: 800; }
+.compare .flat { color: var(--muted); }
+.principles { display: grid; grid-template-columns: repeat(3, 1fr); gap: 14px; }
+.principle { border-top: 3px solid var(--green); background: var(--panel); padding: 18px; }
+.principle:nth-child(2) { border-top-color: var(--blue); }
+.principle:nth-child(3) { border-top-color: var(--amber); }
+.principle p { margin: 0; color: var(--muted); font-size: 14px; }
+.status { display: inline-flex; align-items: center; gap: 8px; color: var(--red); font-weight: 800; font-size: 14px; }
+.status i { width: 9px; height: 9px; border-radius: 50%; background: currentColor; }
+footer { max-width: 1180px; margin: 0 auto; padding: 0 26px 54px; color: var(--muted); font-size: 13px; }
+@media (max-width: 820px) {
+  .topbar-inner { padding: 12px 17px; align-items: flex-start; flex-direction: column; }
+  .nav { justify-content: flex-start; }
+  main { padding: 40px 17px 70px; }
+  .hero-grid, .explain { grid-template-columns: 1fr; }
+  .metrics { grid-template-columns: repeat(2, 1fr); }
+  .metric:nth-child(2) { border-right: 0; }
+  .metric:nth-child(-n+2) { border-bottom: 1px solid var(--line); }
+  .flow { display: block; }
+  .flow-step { min-height: auto; border-right: 0; border-bottom: 1px solid var(--line); padding-left: 18px; }
+  .flow-step::after { content: "↓"; top: auto; bottom: -13px; right: 50%; }
+  .flow-step:last-child { border-bottom: 0; }
+  .principles { grid-template-columns: 1fr; }
+  .section-head { display: block; }
+  .section-note { margin-top: 10px; }
+}
+@media print {
+  .topbar { position: static; }
+  .nav, .copy, .tabs { display: none; }
+  .tab-panel { display: block !important; }
+  .panel, .metric, .compare, .flow, .architecture { box-shadow: none; break-inside: avoid; }
+}
+</style>
+</head>
+<body>
+<header class="topbar">
+  <div class="topbar-inner">
+    <div class="brand">Pi <span>apply_patch</span> 方案说明</div>
+    <nav class="nav" aria-label="页面导航">
+      <a href="#answer">结论</a><a href="#architecture">架构</a><a href="#config">配置</a><a href="#principle">原理</a><a href="#evidence">数据</a>
+    </nav>
+  </div>
+</header>
+<main>
+  <section class="hero-grid" id="answer">
+    <div>
+      <div class="eyebrow">GPT-5.6 / Pi / Codex-style editing</div>
+      <h1>它变好了，但改善主要在“第一次编辑能不能正确开始”。</h1>
+      <p class="lede">公平对照下，apply_patch 没有提升最终正确率，却把 GPT-5.6 的首次编辑成功率从 85% 提到 95%，并消除了观察到的编辑协议失败。它适合作为 GPT/Codex 模型的候选工具，不应无条件替代所有模型的 edit。</p>
+    </div>
+    <aside class="signal">
+      <strong>当前包状态：可安装，按模型路由</strong>
+      <p>这个 npm 包包含真正的 apply_patch extension。安装后，GPT/Codex 模型按配置使用 apply_patch，其他模型继续使用 edit。</p>
+    </aside>
+  </section>
+
+  <section class="section">
+    <div class="metrics" aria-label="公平 benchmark 核心指标">
+      <div class="metric good"><div class="value">85% → 95%</div><div class="label">首次编辑成功率</div></div>
+      <div class="metric neutral"><div class="value">90% = 90%</div><div class="label">最终精确正确率</div></div>
+      <div class="metric good"><div class="value">1 → 0</div><div class="label">编辑协议失败</div></div>
+      <div class="metric warn"><div class="value">−4.5%</div><div class="label">中位端到端耗时</div></div>
+    </div>
+  </section>
+
+  <section class="section">
+    <div class="section-head"><div><div class="eyebrow">先解释指标</div><h2>“编辑协议失败：1 → 0”到底是什么？</h2></div><p class="section-note">这是本次 benchmark 自定义的分类名，不是 HTTP、Responses API 或 custom tool 协议错误。</p></div>
+    <div class="explain">
+      <article class="panel">
+        <span class="badge amber">A · 当前 edit</span>
+        <h3 style="margin-top:16px">1 次工具调用失败，但任务后来完成</h3>
+        <p>公平 A 组中唯一被归类为协议失败的是 <code>11-bom</code>。模型先读取了带 UTF-8 BOM 的文件，然后调用 Pi <code>edit</code>，把 BOM 放进了 <code>oldText</code>。Pi 的精确匹配没有找到这段文本，于是返回：</p>
+        <div class="callout"><code>Could not find the exact text in src/bom.js</code><br>old text 必须逐字匹配，包括空白和换行。</div>
+        <p>模型随后使用 bash 做了字节级修改，最终文件正确，所以“最终正确率”仍算成功；但“首次编辑成功率”和“编辑协议失败”仍记录了这次失败。</p>
+      </article>
+      <article class="panel">
+        <span class="badge green">C · apply_patch</span>
+        <h3 style="margin-top:16px">工具协议直接匹配模型的 Codex 先验</h3>
+        <p>GPT-5.6 在 C 组中以 <code>apply_patch</code> 的名字调用 custom tool，输入是原始 patch 文本，而不是嵌套的 <code>path + edits[]</code> JSON。19/20 个公平用例出现了可识别的 custom call，且没有编辑工具执行失败。</p>
+        <div class="callout">因此“1 → 0”表示：首次编辑环节少了一次失败调用。它不是说所有文件修改错误都消失了，也不是说 API 从不失败。</div>
+        <p>最终正确率仍然是 90%，因为剩余问题属于内容语义或文本格式细节，例如换行转义和引号选择。</p>
+      </article>
+    </div>
+  </section>
+
+  <section class="section" id="architecture">
+    <div class="section-head"><div><div class="eyebrow">Architecture</div><h2>工具的完整调用链</h2></div><p class="section-note">关键设计是“模型看到哪种工具”与“工具如何安全落盘”分开。</p></div>
+    <div class="architecture">
+      <div class="arch-row">
+        <div class="arch-node"><small>01 · Model state</small><strong>当前模型配置</strong><p>ctx.model.provider、api、id、compat 能力标记。</p></div>
+        <div class="arch-arrow">→</div>
+        <div class="arch-node"><small>02 · Routing</small><strong>syncEditorTools()</strong><p>命中的 GPT/Codex 模型启用 apply_patch；其他模型启用 edit。</p></div>
+        <div class="arch-arrow">→</div>
+        <div class="arch-node"><small>03 · Provider</small><strong>Responses serializer</strong><p>Grammar 支持时序列化为 type=custom + Lark definition，否则回退为普通 function tool。</p></div>
+        <div class="arch-arrow">→</div>
+        <div class="arch-node"><small>04 · Execution</small><strong>parse → validate → apply</strong><p>完整解析、路径检查、预校验，最后才写文件。</p></div>
+      </div>
+      <div class="boundary"><strong>信任边界：</strong>grammar 只约束模型输出形状，不等于 sandbox。路径、软链接、目录、覆盖和权限必须由执行端再次检查。</div>
+    </div>
+  </section>
+
+  <section class="section">
+    <div class="section-head"><div><div class="eyebrow">Execution</div><h2>一次 apply_patch 如何落盘</h2></div><p class="section-note">先把 patch 变成可信的 change plan，再进入写入阶段。</p></div>
+    <div class="flow">
+      <div class="flow-step"><div class="flow-number">01 / RECEIVE</div><strong>接收原始 patch</strong><p>模型发出 Begin Patch 到 End Patch 的自由格式文本。</p></div>
+      <div class="flow-step"><div class="flow-number">02 / PARSE</div><strong>解析成 AST</strong><p>Add、Delete、Update、Move 和多个 update chunk。</p></div>
+      <div class="flow-step"><div class="flow-number">03 / RESOLVE</div><strong>解析路径</strong><p>相对路径以 ctx.cwd 为根，允许 workspace 内绝对路径。</p></div>
+      <div class="flow-step"><div class="flow-number">04 / PREFLIGHT</div><strong>全部预校验</strong><p>读取快照，匹配上下文，计算每个文件的新内容。</p></div>
+      <div class="flow-step"><div class="flow-number">05 / MUTATE</div><strong>串行写入</strong><p>通过 mutation queue 写入；移动先写目标再删源。</p></div>
+      <div class="flow-step"><div class="flow-number">06 / REPORT</div><strong>返回 diff</strong><p>返回逐文件 diff、unified patch、已提交路径和失败前缀。</p></div>
+    </div>
+  </section>
+
+  <section class="section" id="config">
+    <div class="section-head"><div><div class="eyebrow">Configuration</div><h2>当前配置与可选扩展</h2></div><p class="section-note">默认只为已稳定验证的 Sol High 启用；Luna 的性能结果存在长尾波动，需要显式 opt-in。</p></div>
+    <div class="tabs" role="tablist" aria-label="配置视图">
+      <button class="tab" role="tab" aria-selected="true" aria-controls="config-current" id="tab-current">当前实际配置</button>
+      <button class="tab" role="tab" aria-selected="false" aria-controls="config-recommended" id="tab-recommended">Luna 显式启用</button>
+      <button class="tab" role="tab" aria-selected="false" aria-controls="config-route" id="tab-route">路由规则</button>
+    </div>
+    <div class="tab-panel active" id="config-current" role="tabpanel" aria-labelledby="tab-current">
+      <div class="code-wrap"><button class="copy" data-copy="current-config">复制</button><pre id="current-config">{
+  "enabled": true,
+  "models": [
+    { "provider": "pudu-openai-proxy", "model": "gpt-5.6-sol" }
+  ]
+}</pre></div>
+      <div class="callout">models.json 中的 provider API key 不在页面展示。建议使用环境变量或 Pi auth 存储，并轮换已经出现在配置文件中的 key。</div>
+    </div>
+    <div class="tab-panel" id="config-recommended" role="tabpanel" aria-labelledby="tab-recommended">
+      <div class="code-wrap"><button class="copy" data-copy="recommended-config">复制</button><pre id="recommended-config">{
+  "enabled": true,
+  "models": [
+    { "provider": "pudu-openai-proxy", "model": "gpt-5.6-sol" },
+    { "provider": "pudu-openai-proxy", "model": "gpt-5.6-luna" }
+  ]
+}</pre></div>
+      <p>Luna High 的有效重测中，两组都 20/20 正常结束，最终正确率都是 18/20；首次编辑成功率为 edit 90%、apply_patch 100%。按 17 个两组都正确的配对样本，apply_patch 中位总耗时多 2.3s；按全部 20 个配对样本，中位多 1.2s，9 例更快、11 例更慢。因此 Luna 有协议适配收益，但没有稳定的总耗时优势，当前不默认启用。</p>
+    </div>
+    <div class="tab-panel" id="config-route" role="tabpanel" aria-labelledby="tab-route">
+      <div class="code-wrap"><button class="copy" data-copy="route-rule">复制</button><pre id="route-rule">model = ctx.model
+
+if enabled
+and model.api in ["openai-responses", "openai-codex-responses"]
+and provider/model matches allowlist:
+    active = ["apply_patch"]
+else:
+    active = ["edit"]
+
+# Preserve all unrelated active tools.
+# Register both tools permanently for session replay.</pre></div>
+      <p>切换发生在 <code>session_start</code> 和 <code>model_select</code>。不重新定义同名工具，只改变 active tool 集合。</p>
+    </div>
+  </section>
+
+  <section class="section" id="principle">
+    <div class="section-head"><div><div class="eyebrow">Design principles</div><h2>这个工具的三个核心原则</h2></div></div>
+    <div class="principles">
+      <article class="principle"><h3>模型协议对齐</h3><p>GPT/Codex 模型不再被要求适应 Pi 自定义的 <code>oldText/newText</code> JSON；它看到原生的 <code>apply_patch</code> 名称和 patch grammar。</p></article>
+      <article class="principle"><h3>执行端独立防护</h3><p>grammar 不是安全策略。执行端仍要做 workspace 边界、符号链接、目录、覆盖冲突、权限和取消检查。</p></article>
+      <article class="principle"><h3>按能力选择，不靠 AGENTS 对抗</h3><p>不在 AGENTS 中要求模型“不要使用 apply_patch”。扩展只让模型看到适合自己的一个编辑工具，避免两套协议同时暴露。</p></article>
+    </div>
+  </section>
+
+  <section class="section" id="evidence">
+    <div class="section-head"><div><div class="eyebrow">Evidence</div><h2>公平 benchmark 对照</h2></div><p class="section-note">20 个固定用例；两组都拥有 read、bash、write，只替换编辑工具。</p></div>
+    <table class="compare">
+      <thead><tr><th>指标</th><th>A · current edit</th><th>C · apply_patch</th><th>解读</th></tr></thead>
+      <tbody>
+        <tr><td>最终精确正确率</td><td>18 / 20 · 90%</td><td>18 / 20 · 90%</td><td class="flat">没有下降，也没有提升</td></tr>
+        <tr><td>首次编辑成功率</td><td>85%</td><td class="positive">95%</td><td class="positive">+10 个百分点</td></tr>
+        <tr><td>中位编辑调用</td><td>1</td><td>1</td><td class="flat">无变化</td></tr>
+        <tr><td>中位 agent turns</td><td>4</td><td>4</td><td class="flat">无变化</td></tr>
+        <tr><td>中位 input/output tokens</td><td>9732</td><td>9978</td><td class="flat">+2.5%</td></tr>
+        <tr><td>中位全部 tokens</td><td>26722</td><td>26503</td><td class="flat">−0.8%，基本持平</td></tr>
+        <tr><td>中位耗时</td><td>17.75s</td><td class="positive">16.95s</td><td class="positive">−4.5%，但低于设定门槛</td></tr>
+        <tr><td>编辑协议失败</td><td>1</td><td class="positive">0</td><td class="positive">首次协议更稳定</td></tr>
+      </tbody>
+    </table>
+    <div class="panel" style="margin-top:18px">
+      <div class="status"><i></i>最终判断：候选实现保留，默认自动启用暂不打开</div>
+      <p>本页的耗时比较优先使用同一 fixture 的配对差值，避免两组成功样本构成不同造成中位数偏差。runner 的 180s 进程上限是删失边界，不是 API timeout；本次有效 Luna 重测没有触发该上限。</p>
+    </div>
+  </section>
+
+  <section class="section">
+    <div class="section-head"><div><div class="eyebrow">Files</div><h2>实现位置</h2></div></div>
+    <div class="panel">
+      <p><code>extensions/codex-edit/index.ts</code>：工具注册、执行、防护、renderer 和模型路由。</p>
+      <p><code>extensions/codex-edit/parser.ts</code>：patch grammar 对应的 parser、hunk matcher 和 workspace path resolver。</p>
+      <p><code>extensions/codex-edit/tests/parser.test.mjs</code>：6 个纯函数/文件操作测试，当前全部通过。</p>
+      <p><code>/home/maxiaochao/.pi/agent/evaluations/gpt-edit-benchmark/report-final.md</code>：最终 benchmark 报告。</p>
+    </div>
+  </section>
+</main>
+<footer>说明页基于 Pi 0.84.4、Codex apply_patch 源码分析和 20-case GPT-5.6 benchmark。页面内没有包含任何 API key。</footer>
+<script>
+const tabs = [...document.querySelectorAll('.tab')];
+const panels = [...document.querySelectorAll('.tab-panel')];
+function activateTab(tab) {
+  tabs.forEach(item => item.setAttribute('aria-selected', String(item === tab)));
+  panels.forEach(panel => panel.classList.toggle('active', panel.id === tab.getAttribute('aria-controls')));
+}
+tabs.forEach(tab => tab.addEventListener('click', () => activateTab(tab)));
+tabs.forEach((tab, index) => tab.addEventListener('keydown', event => {
+  if (event.key !== 'ArrowRight' && event.key !== 'ArrowLeft') return;
+  event.preventDefault();
+  const next = tabs[(index + (event.key === 'ArrowRight' ? 1 : tabs.length - 1)) % tabs.length];
+  next.focus(); activateTab(next);
+}));
+document.querySelectorAll('.copy').forEach(button => button.addEventListener('click', async () => {
+  const text = document.getElementById(button.dataset.copy).textContent;
+  try { await navigator.clipboard.writeText(text); button.textContent = '已复制'; setTimeout(() => button.textContent = '复制', 1200); }
+  catch { button.textContent = '复制失败'; setTimeout(() => button.textContent = '复制', 1200); }
+}));
+</script>
+</body>
+</html>

package/extensions/codex-edit/config.json

@@ -0,0 +1,6 @@
+{
+  "enabled": true,
+  "models": [
+    "gpt-5.6-*"
+  ]
+}