内容
align="center">
<img src="./assets" alt="Otter width="440" />
</p>
<p align="center"><b</b> · <a href="./README.zh.md">中文></p>
> O**ffice **T**ransforms · **T**racked · **E**dited &eviewed · surgical **Patch** write-back — an Agent reviewable **safe-commit layer documents.
> 选中区域 → 输入指令 → 查看差异 → 高保真回写。
> （类似：为 `.xlsx` / `.docx` / `.drawio` 文件开启一个 PR。）
> ⚠️ 早期框架 — 正在积极。
## 为什么
代理不应直接编辑文件。在 OtterPatch 中，代理仅**提议**一个结构化的 `ChangeSet`；系统验证它，应用到一个影子副本，显示**的差异**（按块接受），然后**手术式**回写 — 只有被修改的部分发生变化，其余部分保持字节不变。
在实际的 531 KB `.docx` 文件上验证：回写保持了 **30/31 部分字节不变而模型往返重 11/31 部分。参见 `packages/writeback`。
## 文档
文档位于 [`docs/`](./docs/README.md)（英文 · 中文）架构](./docs/en/architecture · [代理循环](./docs/en/agent.md) ·
[技能本](./docs/en/skills.md) · [审查 UX](./docsux.md) ·
](./docs/en/testing.md)基准测试日志](./docsbench.md)
## 结构
packages/core/ 格式无关的抽象层
/ ChangeSet / Diff / Skill / Adapter / Registry / Transactionback）
packages/agent/ 意 受限 ChangeSetOK，8 个提供商
（Claude 原生AI 兼容：DeepSeek/GLimi/Doubao/MiniMax/Gemini/ChatGPT）
packages/adapter/ Excel 适配器）— ChangeSet → XML 编译器
packages/adapter-drawio/ draw适配器 — mxCell 操作引擎 + 图表级手术式回写
packages/adapter-word Word 适配器 — 单红线（w:ins/w:del）手术式回packages/adapter-pdf/ PDF 适配器 — AcroForm 表单填写回写（pdf-lib）
packages/adapter-pptx/ PowerPoint 适配器 — 幻灯片文本手术（<a:t>）
packages/writeback-surgical/ 式 OOXML 回写 — 验证 + 测试
packages/runtime 无头编排器：提议 → 差异 → 提交 事件流
apps/desktop/ 渐进式披露驾驶舱 BYOK 模型Vite + React；Electron）
apps/mcp-server/ OtterPatch 作为 MCP 服务器）+ 无头 CLI（otterpatch-run）
```
## 通过集成
OtterPatch 服务器提供，因此任何代理/IDE 都可以驱动提议 → → 回写循环：
```text
otterpatch_skills 列出内置文档技能
otterpose 意图（上下文）→ 受限 可审查的差异 （BYOK）
otterpatch_diffSet → 可审查的差异patch_commit ChangeSet（base64）→ 手回写 → 新文件真度报告
```
c
// 注册服务器（ 密钥通过环境变量的 apiKey 参数 "mcpServers": { "otterpatch": { "commandotterpatch-mcp", " { "OtterPatch_API "sk-..." } } } }
```
或运行无头并流式传输 JSON 事件（每行一个）：
```bash
otterpatch-run --format excel --intent "fill amount = qty × price" --in book.xlsx --out book.out.xlsx
# {"type":"propose:start",...} {"type":"diff:done",...} {"type":"commit:done","ok":true,"touchedParts":["xl/worksheets/sheet1.xml"],...}
舱 UI 通过本地 HTTP 桥接器与运行时通信（`otterpatch-serve`）它，然后将模型面板的patch-serve URL*（BYOK）：
otterpatch-serve # GET /health · POSTpose {format,intent,provider,apiKey} /commit {format,fileBase64,changeSet}
```
```bash
npm install
npm run typecheck # tsc -b across packages/*
npm # 驾驶舱 UI → http://localhost:5173
npm run app -wpatch/desktop # 启动 Electron 桌面窗口 run app:pack -w @otterpatch/desktop # 打包安装程序（electron-builder → release/）
npm test -w @otterpatch/core # 适配器注册表
npm test -otterpatch/agent # 意图 → ChangeSet（模拟 8 提供商工厂）
npm test -w @otterpatch-univer # 意图 → ChangeSet → 手术xlsx 回写
npm test -w @otterpatch/adapter # mxCell 操作 + 跨图表手术式回npm test -w @/writeback-surgical
```
- [x]po 框架；核心 + 适配器注册表
- [x] 手术式 OOXML 回写（验证）
- [x] ：自然语言意图 → 受限 `ChangeSet`（BYOK，8 提供商）
- [x] drawio器：mxCell 添加/删除/设置属性/移动 +级手术式回写
] 无头运行时：意图 → ChangeSet →的差异 → 手术，端到端（rawio）
- [x] MCP 服务器 + 无头带有 JSON 事件流（）
- [x] Word + PDF 表单填写 + PowerPoint 幻灯适配器 — 为 excel//ppt/drawio 提议- [x] 功能区格式应用于实时选择体/斜体/对齐/数字格式 [x] Electron 桌面壳 + electron-builder 打包中文/英文 UI）
- [x] 驾驶舱中的闭环回写（otterpatch）：加载文件 → 提议 → 审查差异（逐/拒绝）→ 接受子集 → 手术式 → 下载编辑后的文件
- [x] Word： 样式六标签功能 **内联跟踪更改 — 逐更改悬，4 状态视图切换/标记/干净/最终时扁平化（接受物理上完成；无标记污染）
- [x] 代理读取工具 — Excel `read_range`/`aggregate`；Word `read_blocks`/`find_text`/`get_outline`/`get_style_usage`（完整文档快照，两个模型通道）
- [x] 具有渐进式披露的领域剧本（`load_skill`）：GB/T 9704 官方文档布局，财务表格规则，图表选择
- [x] 验证注册表（重新计算 · Word 锚点可落位 · drawio 拓扑）轮修复 +语义自检；Anthropic 通道上的
- [x] 页面级布局操作（列/边距/方向 — 双列 IEEE 布局）+ 文档级更改芯片，带有真实的前后切换
- [x]继续（“下一批次”按钮 + 选择性自动继续，和重新锚定）；逐编辑接受遥按键能力基准测试（/expert-bench.mjs`）
- [x]审查 UX，适用于所有三个（共享 **DiffToggle**）：Excel 原始/比较三态，带有，Word 4 状态包括整个段落删除红线，drawio 逐块审查，带有板级高亮；Box 交互界面 + 重新审查未提交的过去回合
- [x] Word 结构化代理操作 — 双通道锚定（引用 + 段落编号），`deletePara`，逐段图像感知 + 图像删除/调整大小；Excel 值×格式在提示中硬门控
-] Word 手术式回写闭环：全部接受 → `/commit` → `WordWriteback` 仅重写 `word/document.xml`（单词级红线，段删除修订，图像操作），其他部分字节不变 → 下载 `<name>.otterpatch.docx实时评估（`npm run eval:excel|word|word:struct|word:commit`，在 `OA_E` 上门控
