Epic: LibreOffice 迁移 Phase 1 执行（Phase 0 已 GO）/ LibreOffice migration Phase 1 execution (Phase 0 = GO)

[zeweihan]

承接 RFC #13（docs/LIBREOFFICE_MIGRATION_PLAN.md）与 Phase 0 原型 #39。Phase 0 已完成、结论 GO（走路线 A / ZetaOffice WASM），正式立项 Phase 1。所有工作在分支 feat/libreoffice-migration，master 继续发 WPS 稳定版，互不影响。

Phase 0 验收结论（GO）/ Phase 0 verdict

四个生死项的 PoC 均在真机/浏览器跑通（截图与日志见 #39）：

• ✅ CJK 渲染：CDN 默认 LOWA 无中文字体→豆腐块；注入 CJK 字体即正确渲染（简繁皆可）。
• ✅ 中文输入：Qt5-WASM 上游无 IME；自建"真 input 承接系统 IME → compositionend → UNO 在光标处 insertString"输入桥可正常连续中文输入（焦点交还、追加不替换/不选中均已修）。
• ✅ zetajs 程序化能力：取选区 / 模型原生搜索（XSearchable、findFirst/findNext）/ RecordChanges 修订留痕——RFC §0.2"弃整数 offset、用模型原生"主张功能性验证通过。
• ⚠️ 性能/包体：50 页批量生成 ≈26.5s（程序化写入、非真实编辑）；加载既有 docx 的真实耗时与安装包体积增量待量化补测（Phase 1 任务 ⑤）。

Phase 1 任务（可认领）/ Phase 1 tasks (claimable)

• ① 字体焙进自托管 LOWA bundle：自托管运行时到安装包 + 把 Noto Sans CJK/思源（OFL）放进 /instdir/share/fonts/truetype/，构建期由 fontconfig 原生扫到（替代 PoC 的运行时注入）。area: desktop
• ② IME 输入桥工程化：PoC 的"真 input 承接 IME"→做成覆盖 canvas 光标处的透明可编辑层（跟随 LO 光标、合成中预览、Backspace/方向键/Enter 转 UNO 命令），体验＝"直接在文档里打字"。area: frontend
• ③ 后端工具契约改名（小重构、先行）：WpsTools/WpsActionService/useWpsBridge 等 WPS 命名 → 编辑器无关命名（后端命令逻辑不动，仅命名解耦）。area: ai
• ④ 前端 executor 按模型重写（核心 ~2–3k 行）：定位→XSearchable+XParagraphCursor+书签锚点（弃整数 offset）；修订→RecordChanges 默认开；选区/插入/替换→UNO 游标+XReplaceable。area: frontend
• ⑤ 性能/包体量化补测：加载既有 50 页 docx 打开/保存耗时 + 编辑流畅度；WASM+data 对安装包体积增量。
• ⑥ Electron 集成：spike 的 onHeadersReceived（COOP/COEP）+ WASM 渲染窗，按独立 session/partition 接进 desktop/main/main.js（不动主应用现有 webSecurity 设置）。area: desktop
• ⑦ Phase 3 灰度：WPS 与 LibreOffice executor 并存、开关切换、真实合同回归"定位/修订"准确率；稳定后默认切换、移除 WPS SDK 依赖。

接手者必读·关键工程事实 / Key facts

1. LOWA 运行时＝cdn.zetaoffice.net/zetaoffice_latest/ 的 soffice.{js,wasm,data}，但 zeta.js 桥不在 CDN，须本地 vendored。
2. 主线程线程端口＝Module.uno_main（非 Module.zetajs，后者只在 office worker 里），且须在 soffice.js 的 onload 里挂。
3. WASM 需 SharedArrayBuffer → 页面须跨源隔离（COOP same-origin + COEP require-corp）；Electron 用 session.webRequest.onHeadersReceived 注入。
4. emscripten 全局 out（stdout）会覆盖页面全局 out —— 勿用 out 当全局名（spike 已改 zlog）。
5. 字体注入须在 fontconfig 启动扫描前（Module.preRun；LOWA data 挂载是 merge 进 MEMFS，故 preRun 写入有效）。
6. 跑 spike：cd experiments/zetaoffice-spike && node serve.mjs → 真 Chrome:8777；或 ../../desktop/node_modules/.bin/electron .（真机）。

---

English (summary). Phase 0 of the LibreOffice migration (RFC #13, spike #39) is complete — verdict GO (route A / ZetaOffice WASM). All four make-or-break checks have working PoCs on branch feat/libreoffice-migration: CJK rendering (inject a CJK font into the LOWA font dir), Chinese input (a real <input> hosts the system IME → compositionend → UNO insertString at the cursor; focus-handoff + append-not-replace fixed), and zetajs programmatic ops (selection, model-native XSearchable search, RecordChanges redline). Perf/bundle is partial (50-page bulk-gen ~26.5s; real load/edit timing + installer size increment TBD). This Epic tracks the claimable Phase 1 tasks: font into self-hosted bundle, IME overlay, backend tool-contract rename, frontend executor rewrite (drop integer offsets → model-native), perf re-measure, Electron integration (COOP/COEP via onHeadersReceived), and gray rollout. master keeps shipping the WPS-based release; migration work stays isolated on the branch. Key engineering facts above.

[zeweihan]

任务④ 起步：LibreOffice editor executor 骨架（加法式，不碰 WPS）/ Task ④ kicked off: editor executor skeleton

先一条勘察修正：原以为任务③（后端工具契约改名）最低风险，实测发现 wps_* 是贯穿 LLM 工具名 + AgentOrchestrator 派发 + 前端线协议（SSE action / /api/ai/agent/wps-result）+ DB 字段 wpsFileId 的活契约——孤立改名会动现有 WPS 流程、且无法独自端到端验证。结论：契约改名并入任务④（前端 executor 重写时两端一起改），不单独先做。

任务④ 加法式起步（提交 1cd8c50）：

• frontend/src/composables/useLibreOfficeBridge.js —— 编辑器无关 executor 客户端，暴露与 useWpsBridge 完全相同的 executeCommand(action, params) 契约（get_selection/find_replace/insert_at_cursor… action 名本就编辑器无关，wps_ 仅在后端工具层）。转发命令到 ZetaOffice office worker（reqId 关联回包），WPS 与 LibreOffice executor 可并存、开关切换（Phase 3 灰度）。connect(port) 接入嵌入式 ZetaOffice 前保持休眠，不碰现有 WPS 路径。
• office_thread.js 加 worker 侧 exec 命令实现（UNO）：insert_at_cursor/replace_selection/find_replace（模型原生 XSearchable+RecordChanges 修订）/get_selection/find_text_locations 用 Phase 0 验过的原语，其余 stub。

已在 spike harness 验证（请求/响应协议）：insert_at_cursor→{success,inserted}；find_replace{合同编号→协议编号,all}→{success,replaced:2,recordChanges:true}（截图：两处均以修订痕迹/redline 呈现）；get_selection→{success,text:"",hasSelection:false}。

任务④后续：补齐其余命令的 worker handler（replace_nth_match/delete_*/get_paragraph/modify_paragraph/get_outline/goto，offset 类按 §0.2 转锚点）；把 worker 脚本与嵌入式 ZetaOffice 共享；与后端契约改名一并落地。

---

English · Correction from investigation: task ③ (backend tool-contract rename) is NOT low-risk — wps_* is a live contract spanning LLM tool names, AgentOrchestrator dispatch, the frontend wire protocol (SSE actions, /api/ai/agent/wps-result), and the wpsFileId DB column. Renaming it in isolation would disturb the working WPS path and can't be e2e-verified alone, so it's folded into task ④ (rename both ends together during the executor rewrite). Task ④ started additively (commit 1cd8c50): useLibreOfficeBridge.js is the editor-agnostic executor client exposing the same executeCommand(action, params) contract as the WPS bridge, forwarding to the ZetaOffice worker so both executors can coexist behind a switch; the worker exec handler implements the contract via UNO (Phase 0-proven primitives). Verified in the spike: insert_at_cursor, find_replace (2 replacements as tracked-change redline), get_selection.

[zeweihan]

任务④ 进展：executor 客户端抽成框架无关核心，真实产品代码端到端验证 / executor client extracted + verified driving real LibreOffice

提交 8daa49d：

• frontend/src/composables/libreofficeExecutorClient.js（新，纯 ESM 框架无关核心）：connect(port)/executeCommand(action,params) + 编辑器无关命令契约（EDITOR_ACTIONS）+ reqId 请求/响应；connect 用 addEventListener 与宿主 onmessage 共存；ppt_*/未知/§0.2-offset 在客户端层拒绝。
• useLibreOfficeBridge.js 改为薄 Vue 包装（仅加 isProcessing/lastError）。
• spike serve.mjs 加只读 scoped /shared/ 路由 → spike 直接驱动真实产品模块而非副本；index.html boot 后 import 并 connect 到 worker，加"executor 自测"按钮。

用真实产品客户端端到端验证（非 eval）：insert_at_cursor→{success,inserted}；find_replace→{success,replaced:1,recordChanges:true}；get_outline→{success,count:0}；set_selection→{success:false,"§0.2 requires anchors"}（有意拒绝）。链路证实：产品 executor 客户端 → office worker → UNO → LibreOffice。

剩余链（后端 SSE → useLibreOfficeBridge → 上述客户端）＝agent-stream 接线，待 app 嵌入 ZetaOffice（独立 session/partition + onHeadersReceived）时落地，属真机步骤。

---

English · Extracted the executor client into a framework-agnostic ESM core (libreofficeExecutorClient.js); useLibreOfficeBridge.js is now a thin Vue wrapper. A scoped read-only /shared/ route lets the spike drive the REAL product module against a running LibreOffice. Verified end-to-end via the product client (not eval): insert_at_cursor, find_replace (redline), get_outline, and set_selection correctly rejected as a §0.2 offset stub. Chain proven: product executor client → office worker → UNO → LibreOffice. The remaining link (backend SSE → useLibreOfficeBridge) is agent-stream wiring, landed when the app embeds ZetaOffice (real-device step).

[zeweihan]

任务④ 进展：§0.2 锚点定位落地（RFC「定位准确」支柱）/ §0.2 anchor-based location implemented

提交 43ceb3b。实现 RFC §0.2 的核心——模型原生稳定锚点取代脆弱整数 offset（RFC 称 offset 是"定位不准"的病根）：

• 锚点 = 隐藏书签（spanning 匹配范围，随编辑移动）。worker 加 anchorBookmark(range)→name / anchorRange(name)→XTextRange。
• find_text_locations 改为返回 {anchorId, text}（书签 id，非 offset；先收集 range 再打书签，避免扰动 findNext）。
• set_selection / replace_at_position 改为锚点制：取 {anchor} 选中 / 替换（替换走 RecordChanges 修订）；整数 {start,end} 有意拒绝。
• 加 clear_anchors；client EDITOR_ACTIONS 同步。

经真实产品客户端端到端验证：find_text_locations('甲方')→count:2、anchorId __ai_anchor_1/2（非 offset）；set_selection({anchor})→选中"甲方"；set_selection({start,end})→拒绝(§0.2)；replace_at_position({anchor,'【甲方】'})→success，替换后定位'【甲方】'→count 1。

任务④阶段性：LibreOffice executor 的前端客户端核心 + worker UNO 层 + 全 Writer 命令契约 + §0.2 锚点定位，作为真实产品代码端到端跑通。剩：agent-stream 接线 + app 内嵌 ZetaOffice（真机）、IME 透明覆盖层、字体焙进 bundle、性能补测、后端契约产出 anchor。

---

English · Implemented RFC §0.2's core — model-native stable anchors replacing fragile integer offsets (the RFC's root cause of "inaccurate location"). Anchor = a hidden bookmark spanning the match. find_text_locations returns {anchorId, text} (bookmark ids, not offsets); set_selection/replace_at_position are now anchor-based (integer offsets deliberately rejected); added clear_anchors. Verified end-to-end via the product client: locate '甲方' → 2 anchorIds (not offsets), select by anchor, offset-based selection rejected (§0.2), replace at anchor under redline, relocate confirms. Task ④ now has the client core + worker UNO layer + full Writer command contract + §0.2 anchors all proven as real product code.