@maxiaochao/pi-toolkit 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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
+
 ## 2026-09-24 - v0.8.1
 
 - lowercase the herdr skill name in its description and H1 (a deliberate local edit over the upstream v0.9.1 copy, now recorded in NOTICE, README and AGENTS.md); drop the stale `herdr --skill` pointer from the agent-team skill

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
 
@@ -87,6 +87,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 +110,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:
+## Codex Edit (apply_patch)
 
-```bash
-pi install npm:@maxiaochao/pi-codex-edit
-```
+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.
 
-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:
-
-```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-*"
+  ]
+}

package/extensions/codex-edit/index.ts

@@ -0,0 +1,218 @@
+import { access, lstat, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname } from "node:path";
+import { Text } from "@earendil-works/pi-tui";
+import {
+  generateDiffString,
+  generateUnifiedPatch,
+  withFileMutationQueue,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+  APPLY_PATCH_LARK_GRAMMAR,
+  applyUpdate,
+  parsePatch,
+  resolveWorkspacePath,
+} from "./parser.ts";
+import { modelIsAllowed } from "./model-routing.ts";
+
+const editorToolNames = new Set(["edit", "apply_patch"]);
+const settingsUrl = new URL("./config.json", import.meta.url);
+
+async function loadSettings() {
+  try {
+    return JSON.parse(await readFile(settingsUrl, "utf8"));
+  } catch {
+    return { enabled: true, models: [] };
+  }
+}
+
+function syncEditorTools(pi, ctx, model, settings) {
+  const active = pi.getActiveTools();
+  if (!active.some((name) => editorToolNames.has(name))) return;
+  const selected = modelIsAllowed(model, settings) ? "apply_patch" : "edit";
+  const next = active.filter((name) => !editorToolNames.has(name));
+  next.push(selected);
+  pi.setActiveTools([...new Set(next)]);
+  if (ctx.hasUI) ctx.ui.setStatus("codex-edit", `editor: ${selected}`);
+}
+
+async function fileInfo(path, label) {
+  let info;
+  try {
+    info = await lstat(path);
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : "unknown";
+    throw new Error(`${label} is unavailable (${code})`);
+  }
+  if (info.isSymbolicLink()) throw new Error(`${label} must not be a symbolic link`);
+  if (!info.isFile()) throw new Error(`${label} must be a regular file`);
+  await access(path, constants.R_OK | constants.W_OK);
+  return info;
+}
+
+async function ensureParentIsSafe(path, workspace) {
+  let current = dirname(path);
+  while (current !== workspace && current.startsWith(`${workspace}/`)) {
+    try {
+      const info = await lstat(current);
+      if (info.isSymbolicLink()) throw new Error(`Parent path is a symbolic link: ${current}`);
+      if (!info.isDirectory()) throw new Error(`Parent path is not a directory: ${current}`);
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+        current = dirname(current);
+        continue;
+      }
+      throw error;
+    }
+    current = dirname(current);
+  }
+  if (current !== workspace) throw new Error(`Parent path escapes workspace: ${path}`);
+}
+
+async function pathExists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function withPathQueues(paths, fn) {
+  const ordered = [...new Set(paths)].sort();
+  async function acquire(index) {
+    if (index === ordered.length) return fn();
+    return withFileMutationQueue(ordered[index], () => acquire(index + 1));
+  }
+  return acquire(0);
+}
+
+function buildFileDetail(path, action, before, after, moveTo) {
+  const diff = generateDiffString(before, after);
+  const patch = generateUnifiedPatch(path, before, after);
+  return { path, action, moveTo, diff: diff.diff, patch, firstChangedLine: diff.firstChangedLine };
+}
+
+export default async function (pi) {
+  const settings = await loadSettings();
+
+  pi.registerTool({
+    name: "apply_patch",
+    label: "apply_patch",
+    description: "Apply a Codex-style patch. This is a FREEFORM tool, so provide raw patch text and never wrap it in JSON or a Markdown fence.",
+    promptSnippet: "Apply Codex-style freeform patches to add, delete, update, or move files",
+    promptGuidelines: [
+      "Use apply_patch for file changes and provide raw text between *** Begin Patch and *** End Patch.",
+      "Do not wrap apply_patch input in JSON or a Markdown code fence.",
+    ],
+    parameters: Type.Object({
+      patch: Type.String({ description: "Raw Codex-style patch text" }),
+    }),
+    constrainedSampling: {
+      type: "grammar",
+      variants: { openai_lark: APPLY_PATCH_LARK_GRAMMAR },
+    },
+    executionMode: "sequential",
+    async execute(_toolCallId, { patch }, signal, _onUpdate, ctx) {
+      const operations = parsePatch(patch);
+      const resolved = [];
+      const targets = [];
+      for (const operation of operations) {
+        const source = resolveWorkspacePath(ctx.cwd, operation.path);
+        const destination = operation.moveTo ? resolveWorkspacePath(ctx.cwd, operation.moveTo) : undefined;
+        targets.push(source, ...(destination ? [destination] : []));
+        resolved.push({ ...operation, source, destination });
+      }
+      if (new Set(targets).size !== targets.length) throw new Error("Multiple patch operations target the same resolved path");
+
+      const committed = [];
+      return withPathQueues(targets, async () => {
+        const prepared = [];
+        for (const operation of resolved) {
+          if (signal?.aborted) throw new Error("Operation aborted");
+          await ensureParentIsSafe(operation.source, ctx.cwd);
+          if (operation.destination) await ensureParentIsSafe(operation.destination, ctx.cwd);
+          if (operation.action === "add") {
+            if (await pathExists(operation.source)) throw new Error(`Cannot add existing file ${operation.path}`);
+            prepared.push({ ...operation, before: "", after: operation.content });
+          } else {
+            await fileInfo(operation.source, `Source file ${operation.path}`);
+            const before = await readFile(operation.source, "utf8");
+            const after = operation.action === "delete" ? "" : applyUpdate(before, operation.chunks, operation.path);
+            if (operation.destination && await pathExists(operation.destination)) {
+              throw new Error(`Cannot move over existing file ${operation.moveTo}`);
+            }
+            prepared.push({ ...operation, before, after });
+          }
+        }
+
+        for (const operation of prepared) {
+          if (signal?.aborted) throw new Error("Operation aborted");
+          if (operation.action === "add") {
+            await mkdir(dirname(operation.source), { recursive: true });
+            await writeFile(operation.source, operation.after, "utf8");
+          } else if (operation.action === "delete") {
+            await unlink(operation.source);
+          } else if (operation.destination) {
+            await mkdir(dirname(operation.destination), { recursive: true });
+            await writeFile(operation.destination, operation.after, "utf8");
+            await unlink(operation.source);
+          } else {
+            await writeFile(operation.source, operation.after, "utf8");
+          }
+          committed.push(operation);
+        }
+
+        const files = committed.map((operation) => buildFileDetail(
+          operation.path,
+          operation.destination ? "move" : operation.action,
+          operation.before,
+          operation.after,
+          operation.moveTo,
+        ));
+        return {
+          content: [{ type: "text", text: `Applied ${committed.length} file operation(s): ${committed.map((operation) => operation.path).join(", ")}` }],
+          details: {
+            files,
+            committedPaths: committed.map((operation) => operation.path),
+            exact: true,
+            combinedPatch: files.map((file) => file.patch).join("\n"),
+          },
+        };
+      }).catch((error) => {
+        const prefix = committed.length ? ` Committed before failure: ${committed.map((operation) => operation.path).join(", ")}.` : "";
+        throw new Error(`${error instanceof Error ? error.message : String(error)}${prefix}`);
+      });
+    },
+    renderCall(args, theme, context) {
+      const component = context.lastComponent || new Text("", 0, 0);
+      const patch = typeof args?.patch === "string" ? args.patch : "";
+      const files = [...patch.matchAll(/\*\*\* (?:Add|Delete|Update) File: ([^\n]+)/g)].map((match) => match[1]);
+      component.setText(theme.fg("toolTitle", "apply_patch") + theme.fg("muted", files.length ? ` ${files.join(", ")}` : " patch"));
+      return component;
+    },
+    renderResult(result, options, theme, context) {
+      const details = result?.details;
+      const component = context.lastComponent || new Text("", 0, 0);
+      if (context.isError) {
+        component.setText(theme.fg("error", result?.content?.map((item) => item.text || "").join("\n") || "apply_patch failed"));
+        return component;
+      }
+      const files = details?.files || [];
+      let text = theme.fg("success", `Applied ${files.length} file operation(s)`);
+      if (options.expanded) {
+        for (const file of files) {
+          text += `\n${theme.fg("toolTitle", file.action)} ${file.path}`;
+          if (file.diff) text += `\n${theme.fg("dim", file.diff)}`;
+        }
+      }
+      component.setText(text);
+      return component;
+    },
+  });
+
+  pi.on("session_start", (_event, ctx) => syncEditorTools(pi, ctx, ctx.model, settings));
+  pi.on("model_select", (event, ctx) => syncEditorTools(pi, ctx, event.model, settings));
+}

package/extensions/codex-edit/model-routing.ts

@@ -0,0 +1,12 @@
+export function globMatches(value, pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*");
+  return new RegExp(`^${escaped}$`).test(value);
+}
+
+export function modelIsAllowed(model, settings) {
+  if (!settings.enabled || !model) return false;
+  if (model.api !== "openai-responses" && model.api !== "openai-codex-responses") return false;
+  return (settings.models || []).some((pattern) =>
+    typeof pattern === "string" && globMatches(model.id, pattern),
+  );
+}

package/extensions/codex-edit/parser.ts

@@ -0,0 +1,154 @@
+import { relative, resolve, sep } from "node:path";
+
+export const APPLY_PATCH_LARK_GRAMMAR = `start: begin_patch hunk+ end_patch
+begin_patch: "*** Begin Patch" LF
+end_patch: "*** End Patch" LF?
+hunk: add_hunk | delete_hunk | update_hunk
+add_hunk: "*** Add File: " filename LF add_line+
+delete_hunk: "*** Delete File: " filename LF
+update_hunk: "*** Update File: " filename LF change_move? change?
+filename: /(.+)/
+add_line: "+" /(.*)/ LF -> line
+change_move: "*** Move to: " filename LF
+change: (change_context | change_line)+ eof_line?
+change_context: ("@@" | "@@ " /(.+)/) LF
+change_line: ("+" | "-" | " ") /(.*)/ LF
+eof_line: "*** End of File" LF
+%import common.LF`;
+
+export function parsePatch(patch) {
+  const lines = patch.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim().split("\n");
+  if (lines[0]?.trim() !== "*** Begin Patch") throw new Error("The first line of the patch must be '*** Begin Patch'");
+  if (lines.at(-1)?.trim() !== "*** End Patch") throw new Error("The last line of the patch must be '*** End Patch'");
+  const operations = [];
+  let index = 1;
+  while (index < lines.length - 1) {
+    const line = lines[index];
+    if (line.startsWith("*** Add File: ")) {
+      const path = line.slice("*** Add File: ".length);
+      index += 1;
+      const content = [];
+      while (index < lines.length - 1 && !lines[index].startsWith("*** ")) {
+        if (!lines[index].startsWith("+")) throw new Error(`Invalid add line ${index + 1}`);
+        content.push(lines[index].slice(1));
+        index += 1;
+      }
+      if (content.length === 0) throw new Error(`Add file hunk for path '${path}' is empty`);
+      operations.push({ action: "add", path, content: `${content.join("\n")}\n` });
+      continue;
+    }
+    if (line.startsWith("*** Delete File: ")) {
+      const path = line.slice("*** Delete File: ".length);
+      if (!path) throw new Error(`Delete file hunk on line ${index + 1} has an empty path`);
+      operations.push({ action: "delete", path });
+      index += 1;
+      continue;
+    }
+    if (line.startsWith("*** Update File: ")) {
+      const path = line.slice("*** Update File: ".length);
+      index += 1;
+      let moveTo;
+      if (lines[index]?.startsWith("*** Move to: ")) {
+        moveTo = lines[index].slice("*** Move to: ".length);
+        index += 1;
+      }
+      const chunks = [];
+      while (index < lines.length - 1 && !lines[index].startsWith("*** ")) {
+        let context;
+        if (lines[index] === "@@" || lines[index].startsWith("@@ ")) {
+          context = lines[index].slice(2).trim() || undefined;
+          index += 1;
+        }
+        const oldLines = [];
+        const newLines = [];
+        const contextLineIndices = [];
+        while (index < lines.length - 1 && !lines[index].startsWith("*** ") && !lines[index].startsWith("@@")) {
+          const change = lines[index];
+          const marker = change[0];
+          if (!["+", "-", " "].includes(marker)) throw new Error(`Invalid update line ${index + 1}`);
+          const text = change.slice(1);
+          if (marker === "+") newLines.push(text);
+          else if (marker === "-") oldLines.push(text);
+          else {
+            contextLineIndices.push([oldLines.length, newLines.length]);
+            oldLines.push(text);
+            newLines.push(text);
+          }
+          index += 1;
+        }
+        const endOfFile = lines[index] === "*** End of File";
+        if (endOfFile) index += 1;
+        if (oldLines.length === 0 && newLines.length === 0) throw new Error(`Empty update chunk on line ${index + 1}`);
+        chunks.push({ context, oldLines, newLines, contextLineIndices, endOfFile });
+      }
+      if (chunks.length === 0) throw new Error(`Update file hunk for path '${path}' is empty`);
+      operations.push({ action: "update", path, moveTo, chunks });
+      continue;
+    }
+    throw new Error(`Invalid hunk header on line ${index + 1}: ${line}`);
+  }
+  if (operations.length === 0) throw new Error("Patch contains no file operations");
+  const targets = operations.flatMap((operation) => [operation.path, operation.moveTo].filter(Boolean));
+  if (new Set(targets).size !== targets.length) throw new Error("Multiple operations target the same path");
+  return operations;
+}
+
+function normalizeLineEndings(text) {
+  return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+function findCandidates(lines, pattern, start, eof, compare) {
+  const candidates = [];
+  for (let index = start; index + pattern.length <= lines.length; index += 1) {
+    if (pattern.every((line, offset) => compare(lines[index + offset], line))) candidates.push(index);
+  }
+  candidates.sort((left, right) => eof ? right - left : left - right);
+  return candidates;
+}
+
+function locate(lines, pattern, start, eof, label) {
+  if (pattern.length === 0) return Math.min(start, lines.length);
+  const comparisons = [
+    (left, right) => left === right,
+    (left, right) => left.trimEnd() === right.trimEnd(),
+    (left, right) => left.trim() === right.trim(),
+  ];
+  for (const compare of comparisons) {
+    const candidates = findCandidates(lines, pattern, start, eof, compare);
+    if (candidates.length === 1) return candidates[0];
+    if (candidates.length > 1) throw new Error(`Ambiguous ${label || "patch"} match: ${candidates.length} regions found`);
+  }
+  throw new Error(`Failed to find expected lines${label ? ` in ${label}` : ""}: ${pattern.join("\\n")}`);
+}
+
+export function applyUpdate(content, chunks, path) {
+  const bom = content.startsWith("\ufeff") ? "\ufeff" : "";
+  const withoutBom = bom ? content.slice(1) : content;
+  const ending = withoutBom.includes("\r\n") ? "\r\n" : "\n";
+  const normalized = normalizeLineEndings(withoutBom);
+  const hadFinalNewline = normalized.endsWith("\n");
+  const lines = normalized === "" ? [] : normalized.split("\n");
+  if (hadFinalNewline) lines.pop();
+  const replacements = [];
+  let cursor = 0;
+  for (const chunk of chunks) {
+    if (chunk.context !== undefined) cursor = locate(lines, [chunk.context], cursor, false, path) + 1;
+    const start = locate(lines, chunk.oldLines, cursor, chunk.endOfFile, path);
+    replacements.push({ start, length: chunk.oldLines.length, next: chunk.newLines });
+    cursor = start + chunk.oldLines.length;
+  }
+  const output = [...lines];
+  for (const replacement of [...replacements].reverse()) output.splice(replacement.start, replacement.length, ...replacement.next);
+  let next = output.join("\n");
+  if (hadFinalNewline || next.length > 0) next += "\n";
+  if (ending === "\r\n") next = next.replace(/\n/g, "\r\n");
+  return bom + next;
+}
+
+export function resolveWorkspacePath(cwd, rawPath) {
+  if (!rawPath || rawPath.includes("\0")) throw new Error(`Unsafe patch path: ${rawPath}`);
+  const absolute = resolve(cwd, rawPath);
+  const rel = relative(cwd, absolute);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`)) throw new Error(`Patch path escapes workspace: ${rawPath}`);
+  return absolute;
+}

package/extensions/codex-edit/summary.md

@@ -0,0 +1,56 @@
+# GPT-5.6 Edit Benchmark Final Report
+
+Generated: 2026-09-04
+
+## Isolation
+
+All Pi runs used no-context-files, a temporary PI_CODING_AGENT_DIR, a dedicated session directory, fresh temporary workspaces, and no ambient extensions. The global /home/maxiaochao/.pi/agent/AGENTS.md was not loaded. The fair comparison gave both arms read, bash, and write; only the editor tool differed.
+
+## Main comparison
+
+| Metric | A current edit | C production apply_patch | Difference |
+|---|---:|---:|---:|
+| Fixed fixtures | 20 | 20 | same |
+| Final exact correctness | 18/20 (90%) | 18/20 (90%) | 0 points |
+| First editor success | 85% | 95% | +10 points |
+| Median editor calls | 1 | 1 | same |
+| Median recovery editor calls | 0 | 0 | same |
+| Median agent turns | 4 | 4 | same |
+| Median input+output tokens | 9732 | 9978 | +2.5% |
+| Median all tokens including cache | 26722 | 26503 | -0.8% |
+| Median duration | 17.75s | 16.95s | -4.5% |
+| Protocol failures | 1 | 0 | improved |
+| Context files loaded | 0 | 0 | valid |
+
+A/B prompt exploration with the restricted read+edit tool set produced 75% final correctness for both current and neutral prompt arms. That result is not used as the main decision because it excluded the real Pi write and bash tools. It is useful only as evidence that the current edit contract cannot express add/delete/move operations by itself.
+
+## What apply_patch improved
+
+- GPT-5.6 emitted valid first-pass custom-tool calls in 19 of 20 fair cases; the remaining case used another available tool instead of apply_patch.
+- The production route eliminated the observed editor protocol failure in the fair set.
+- The Codex protocol naturally handles add, delete, update, and move in one patch, but the fair baseline could often complete those tasks through write/bash, so final correctness did not improve.
+- Custom Lark tool encoding was verified through persisted apply_patch calls with ctc_ identifiers.
+
+## What it did not improve
+
+- Exact final correctness remained 90% for both arms.
+- Median editor calls and agent turns were unchanged.
+- Input/output tokens were slightly higher; cache-inclusive token totals were effectively unchanged.
+- Median duration improved only 4.5%, below the 15% production threshold.
+- Codex CLI could not serve as a reference arm because the proxy returned HTTP 401 even when retried with the Pi-configured key.
+
+## Dynamic routing
+
+The production extension route probe passed:
+
+- GPT-5.6 Sol: active tools included read and apply_patch, with grammar capability true.
+- DeepSeek V4 Flash: active tools included read and edit, with grammar capability false.
+- The unrelated active tools were preserved and no extension errors occurred after fixing the settings closure bug.
+
+The probe conditions above reflect v0.1.5, when the route still required grammar capability. Since v0.1.6 the route is `model.api` plus the model-ID allowlist only; a provider without grammar tools falls back to a normal function tool.
+
+## Decision
+
+No-go for universal enablement in the original benchmark environment. The evidence did not justify routing every model through `apply_patch` or making it the default editor for the whole Pi workflow. The shipped route is therefore a model-ID allowlist (`gpt-5.6-*` plus an `openai-responses`/`openai-codex-responses` API check) that keeps `edit` as the fallback everywhere else. The implementation now ships inside `@maxiaochao/pi-toolkit` instead of as a standalone opt-in package, but the allowlist — not the packaging — is what bounds the change: for a non-allowlisted model the extension only re-syncs an already-active editor tool and otherwise returns early.
+
+The production route was validated with `pudu-openai-proxy/gpt-5.6-sol:high` and `pudu-openai-proxy/gpt-5.6-luna:high`. Sol's 20-case fair run improved first editor-call success from 85% to 95% with equal final correctness. A corrected Luna rerun used the fully qualified `pudu-openai-proxy/gpt-5.6-luna:high` in both arms, with 20/20 normally completed runs in each arm: both reached 18/20 final correctness, while first editor-call success was 18/20 for `edit` and 20/20 for `apply_patch`. Among the 17 cases correct in both arms, the paired median total-duration delta was +2.3s for `apply_patch`, with 8 cases faster and 9 slower; across all 20 paired runs, the median delta was +1.2s, with 9 cases faster and 11 slower. The measured tradeoff justified validating Sol first; the shipped `gpt-5.6-*` glob additionally enables Luna and Terra, whose gap is protocol adaptation rather than a stable duration win.

package/extensions/codex-edit/tests/package.test.mjs

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import { modelIsAllowed } from "../model-routing.ts";
+
+const extensionDir = dirname(dirname(new URL(import.meta.url).pathname));
+
+test("config is next to the extension entry file", async () => {
+  const source = await readFile(join(extensionDir, "index.ts"), "utf8");
+  assert.match(source, /new URL\("\.\/config\.json", import\.meta\.url\)/);
+  assert.match(source, /model-routing\.ts/);
+  const config = JSON.parse(await readFile(join(extensionDir, "config.json"), "utf8"));
+  assert.equal(config.enabled, true);
+  assert.deepEqual(config.models, ["gpt-5.6-*"]);
+});
+
+test("matches allowed model IDs with globs independently of provider and grammar support", () => {
+  const settings = { enabled: true, models: ["gpt-5.6-*"] };
+  const baseModel = {
+    id: "gpt-5.6-terra",
+    api: "openai-codex-responses",
+    compat: { supportsOpenAIGrammarTools: true },
+  };
+  assert.equal(modelIsAllowed({ ...baseModel, provider: "openai-codex" }, settings), true);
+  assert.equal(modelIsAllowed({ ...baseModel, provider: "another-provider" }, settings), true);
+  assert.equal(modelIsAllowed({ ...baseModel, compat: { supportsOpenAIGrammarTools: false } }, settings), true);
+  assert.equal(
+    modelIsAllowed(
+      { ...baseModel, api: "openai-responses", compat: { sessionAffinityFormat: "openai-nosession" } },
+      settings,
+    ),
+    true,
+  );
+  assert.equal(modelIsAllowed({ ...baseModel, api: "openai-completions" }, settings), false);
+  assert.equal(modelIsAllowed({ ...baseModel, id: "gpt-5.5" }, settings), false);
+  assert.equal(modelIsAllowed(baseModel, { enabled: false, models: ["gpt-5.6-*"] }), false);
+});

package/extensions/codex-edit/tests/parser.test.mjs

@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { applyUpdate, parsePatch, resolveWorkspacePath } from "../parser.ts";
+
+test("parses add, delete, update, and move operations", () => {
+  const operations = parsePatch(`*** Begin Patch
+*** Add File: added.txt
++hello
+*** Delete File: removed.txt
+*** Update File: old.txt
+*** Move to: new.txt
+@@
+-old
++new
+*** End Patch`);
+  assert.deepEqual(operations.map((operation) => operation.action), ["add", "delete", "update"]);
+  assert.equal(operations[0].content, "hello\n");
+  assert.equal(operations[2].moveTo, "new.txt");
+  assert.deepEqual(operations[2].chunks[0].oldLines, ["old"]);
+  assert.deepEqual(operations[2].chunks[0].newLines, ["new"]);
+});
+
+test("rejects malformed patches and duplicate targets", () => {
+  assert.throws(() => parsePatch("bad"), /first line/);
+  assert.throws(() => parsePatch(`*** Begin Patch
+*** Add File: same.txt
++x
+*** Add File: same.txt
++y
+*** End Patch`), /same path/);
+});
+
+test("applies multiple chunks using context and preserves BOM and CRLF", () => {
+  const before = "\ufefffunction run() {\r\n  const value = 1;\r\n  return value;\r\n}\r\n";
+  const operations = parsePatch(`*** Begin Patch
+*** Update File: src/run.js
+@@ function run() {
+-  const value = 1;
++  const value = 2;
+@@
+-  return value;
++  return value + 1;
+*** End Patch`);
+  const after = applyUpdate(before, operations[0].chunks, "src/run.js");
+  assert.equal(after, "\ufefffunction run() {\r\n  const value = 2;\r\n  return value + 1;\r\n}\r\n");
+});
+
+test("supports insertion chunks and EOF matching", () => {
+  const operations = parsePatch(`*** Begin Patch
+*** Update File: file.txt
+@@
++first
+*** End of File
+*** End Patch`);
+  assert.equal(applyUpdate("", operations[0].chunks, "file.txt"), "first\n");
+});
+
+test("rejects ambiguous matches and workspace escapes", () => {
+  const operations = parsePatch(`*** Begin Patch
+*** Update File: file.txt
+@@
+-value
++changed
+*** End Patch`);
+  assert.throws(() => applyUpdate("value\nvalue\n", operations[0].chunks, "file.txt"), /Ambiguous/);
+  assert.equal(resolveWorkspacePath("/tmp/project", "/tmp/project/src/a.js"), "/tmp/project/src/a.js");
+  assert.throws(() => resolveWorkspacePath("/tmp/project", "/tmp/other/a.js"), /escapes/);
+});
+
+test("round-trips a temporary file operation fixture", async () => {
+  const workspace = await mkdtemp(join(tmpdir(), "codex-edit-test-"));
+  try {
+    const path = join(workspace, "file.txt");
+    await writeFile(path, "before\n", "utf8");
+    const operations = parsePatch(`*** Begin Patch
+*** Update File: file.txt
+@@
+-before
++after
+*** End Patch`);
+    await writeFile(path, applyUpdate(await readFile(path, "utf8"), operations[0].chunks, "file.txt"), "utf8");
+    assert.equal(await readFile(path, "utf8"), "after\n");
+  } finally {
+    await rm(workspace, { recursive: true, force: true });
+  }
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.8.1",
-  "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export extensions, browser automation, and bundled theme/skills.",
+  "version": "0.9.0",
+  "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -25,7 +25,8 @@
     "extensions": [
       "./extensions/todo.ts",
       "./extensions/cache-export/index.ts",
-      "./extensions/btw.ts"
+      "./extensions/btw.ts",
+      "./extensions/codex-edit/index.ts"
     ],
     "skills": [
       "./skills"
@@ -47,8 +48,8 @@
     "ws": "^8.19.0"
   },
   "scripts": {
-    "test": "cd extensions/cache-export && node --experimental-strip-types tests/run-tests.mjs && node --experimental-strip-types ../tests/btw-history.mjs && node tests/e2e-browser.mjs",
-    "load-test": "pi -ne -e ./extensions/todo.ts && pi -ne -e ./extensions/cache-export/index.ts && pi -ne -e ./extensions/btw.ts",
+    "test": "cd extensions/cache-export && node --experimental-strip-types tests/run-tests.mjs && node --experimental-strip-types ../tests/btw-history.mjs && node tests/e2e-browser.mjs && cd ../codex-edit && node --experimental-strip-types --test tests/package.test.mjs tests/parser.test.mjs",
+    "load-test": "pi -ne -e ./extensions/todo.ts && pi -ne -e ./extensions/cache-export/index.ts && pi -ne -e ./extensions/btw.ts && pi -ne -e ./extensions/codex-edit/index.ts",
     "eval:agents": "node evaluations/agents-md/run.mjs",
     "eval:agents:test": "node evaluations/agents-md/tests/run-tests.mjs",
     "postinstall": "node scripts/install-agents.mjs"

package/skills/tapd/SKILL.md

@@ -280,6 +280,18 @@ tapd attachment download --id=<必需>  # 获取附件下载链接
 tapd attachment upload --custom-field=<必需> --entry-id=<必需> --file=<必需> --type=<如 story_custom_field>  # 上传附件
 ```
 
+#### 安全下载附件
+
+`attachment download` 返回的是带短期授权 token 的临时 URL，不是附件内容。下载大附件时必须遵循以下流程：
+
+1. 先用 `attachment list` 记录附件文件名和预期大小；每次发起下载或续传前，重新执行 `attachment download` 获取新 URL。
+2. 下载到 `<文件名>.part`，使用 `curl --fail --location --retry 3`；HTTP 失败时立即停止，禁止把响应正文直接写入最终文件。
+3. 续传前检查 `.part` 开头不是 `token expire`、JSON/HTML 错误信息等文本响应。发现污染时删除 `.part` 并重新下载，不修补或继续追加。
+4. 使用新 URL 和 `curl -C -` 续传。已有部分长度为 N 时，只接受状态 `206` 且 `Content-Range` 从 N 开始；返回 `200`、范围不符或服务器不支持 Range 时，删除 `.part` 后从头下载。
+5. 下载完成后，文件大小必须等于 `attachment list` 的预期大小。ZIP 附件还必须通过 `unzip -t`；其他格式执行相应完整性检查。全部通过后才将 `.part` 重命名为最终文件。
+
+临时 URL 过期只需重新获取链接，不能据此判断 TAPD 原附件损坏。
+
 ### baseline — 基线管理
 
 ```bash