ElyOffice/PRD.md

# Ely Office 产品需求文档

版本：1.0  
日期：2026-10-01  
状态：产品与工程实施基线  
目标平台：Linux、Windows、macOS  
产品形态：开源、离线优先、可独立安装和运行的桌面应用套件

本文中的“必须”是发布要求。“默认”是初始设置，用户可以按文中规定修改。功能表中的所有条目均属于首个正式版本，不代表分阶段计划。性能数值是验收目标，不是已有测试结果。第三方项目提供的能力与 Ely 已完成的能力分开记录。

## 1. 产品定义

Ely Office 提供八个桌面应用。用户可以写文档、计算表格、制作演示、编辑 PDF、收发邮件、管理 Git 仓库、编辑 Markdown 和管理 Agent 会话。

办公文件保存在用户选择的目录。应用不要求注册 Ely 账号，不要求上传文件，不依赖在线文档服务器。全部应用使用 Ely GPUI Components 的设计体系。编辑、解析、计算和协议处理复用现有项目，不重写专业内核。

### 1.1 应用构成

| 应用 | 职责 | 内核或后端基线 | 主要数据 |
| --- | --- | --- | --- |
| ElyDoc | 分页文档编辑 | LibreOfficeKit，简称 LOK | DOCX、ODT |
| ElyTable | 电子表格编辑与计算 | LOK | XLSX、ODS、CSV |
| ElyShow | 演示文稿编辑与放映 | LOK | PPTX、ODP |
| ElyPDF | PDF 阅读、编辑、批注、表单和页面处理 | MuPDF；OCR 复用 Tesseract | PDF |
| ElyMail | 邮件收发、本地存储和搜索 | MailCore 2，加本地同步与存储 | 邮件、附件、草稿 |
| ElyTree | Git 图形化版本管理 | Git CLI | 本地 Git 仓库 |
| ElyMark | 本地 Markdown 编辑 | Ely-GPUI-Components 的 Markdown 文档组件，markdown-rs 解析；参考 MarkText、ColaMD、Markion | Markdown 与本地附件 |
| ElyAgent | 独立的 Agent 配置与会话管理 | 嵌入的 Kigi CLI Rust 代码 | 配置、会话记录、运行状态 |

LOK、MuPDF 和 GPUI 是已确定的方向。MailCore 2、Markdown 文档组件、邮件正文渲染和下文的发行默认值，是本 PRD 采用的工程基线，仍须通过三端接入验收。不得把未测试的接口写成已支持功能。

ElyAgent 参考 Magpie 的独立工具定位，但不要求复制其全部功能。它不是其他七个应用的聊天侧栏，也不是整个套件的控制中枢。[S19]

### 1.2 固定决策

1. 首个正式版交付全部八个应用及本文定义的功能，不发布只有入口和占位界面的套件。
2. Doc、Table、Show 共用 LOK 适配实现。PDF 使用 MuPDF。不开设替代内核路线。
3. GPUI 负责应用界面。专业内容区域可以使用内核渲染结果，但外观和行为必须遵守 Ely 规范；不用 CEF 与 Electron。
4. 应用可以独立启动、更新和卸载。安装 ElyMark、ElyTree 或 ElyAgent 不得强制安装 LOK。
5. 用户文件采用通用格式。应用数据库只保存索引、配置和运行记录，不取代用户文件。
6. 不建设云端文档平台、微服务系统、统一业务数据库或跨应用 Agent 编排系统。

### 1.3 成功标准

用户在断网电脑上安装发行包后，可以创建、修改、保存、重新打开和打印本文范围内的本地文件。文件中的受支持内容不丢失。界面不会切回上游产品的工具栏或高级设置窗口。邮件、远程 Git 和远程模型连接失败时，本地工作仍可继续。

“对标 Office”指完成本文列出的日常工作，不代表兼容微软所有历史格式、宏、插件和企业服务。不以组件数量、文件扩展名数量或界面截图代替验收。

## 2. 用户与工作场景

面向处理本地文件的个人、开发者和小团队。用户可能只安装一个应用，也可能安装整套产品。首次使用不要求建立工作区、创建账号或完成教程。

| 场景 | 用户操作 | 完成条件 |
| --- | --- | --- |
| 审阅合同 | 打开 DOCX，修改条款，添加批注，保存并导出 PDF | 原有表格、编号、页眉页脚和修订记录按支持范围保留 |
| 整理数据 | 导入 CSV，编辑公式，筛选、汇总并绘制图表 | 导入规则可检查，计算结果可复现，导出不静默丢失工作表 |
| 制作汇报 | 修改 PPTX 母版、图文和备注，在外接屏幕放映 | 编辑对象仍可修改，观众屏与演讲者视图分离 |
| 处理 PDF | 修改文字对象、整理页面、填写表单并删除敏感内容 | 保存后的 PDF 可在独立阅读器打开，删除内容不能从输出文件恢复 |
| 离线处理邮件 | 阅读已缓存邮件，检索附件，写回复 | 草稿和发件队列落盘；联网后的发送状态有证据 |
| 管理仓库 | 查看差异、分块暂存、提交、合并并处理冲突 | Git 仓库与终端操作结果一致，危险操作先说明影响 |
| 编写 Markdown | 编辑本地文档，插入图片，与外部编辑器共同使用 | 未修改内容不被无故重写，外部变更不覆盖未保存内容 |
| 管理 Agent | 配置后端，在多个目录启动会话，查看执行和产物 | 会话状态与后端一致，重启后的恢复能力如实显示 |

## 3. 产品范围与离线边界

### 3.1 离线能力

| 应用 | 无网络时必须可用 | 需要连接时才可执行 |
| --- | --- | --- |
| Doc、Table、Show | 本地编辑、搜索、保存、导出、打印、放映 | 用户主动更新外部链接或打开远程资源 |
| PDF | 本地编辑、OCR、批注、表单、页面处理、导出 | 在线证书吊销查询、时间戳服务等外部请求 |
| Mail | 读取已缓存内容、搜索、写草稿、管理待发送邮件 | 首次授权、收取新邮件、下载未缓存内容、发送 |
| Tree | 查看已有历史、差异、暂存、提交、分支、合并、变基 | 访问远程仓库、下载尚未缓存的 LFS 对象 |
| Mark | 编辑、预览、搜索、公式与图表渲染、PDF/HTML 导出 | 用户主动加载远程图片或打开外部链接 |
| Agent | 查看本地配置和历史；运行依赖均已安装的本地后端 | 远程模型、远程工具及其授权 |

应用资源、帮助、默认模板、Markdown 渲染资源和 PDF 中英文 OCR 语言数据随对应发行包提供。不从 CDN 加载脚本、字体或样式。断网不能阻止应用启动，也不能触发登录弹窗。

本地模型及第三方 Agent 不强制打包。离线使用它们的前提是用户已安装对应程序、模型和依赖。应用必须检查这些条件，不能把“能打开会话界面”显示成“模型可离线运行”。

### 3.2 不纳入产品范围

不建设实时多人协同、云盘、在线 Office 服务、组织管理后台、应用商店、计费系统、项目管理系统或完整日历产品。

不自研文字排版、公式计算、PDF 解析、邮件协议、Git 存储、模型推理和通用 Agent 执行框架。不承诺执行 VBA、ActiveX、COM 插件、Power Query、Power Pivot 或微软专有协作功能。

不提供远程桌面、跨电脑 Agent 调度、自动代发邮件、自动跨应用修改文件或无限制后台任务。用户可通过系统文件和明确的“用其他应用打开”操作连接应用。

这些是产品边界，不是推迟交付的清单。

## 4. 平台与发行

### 4.1 支持目标

以下版本是本项目的支持目标，不是上游库已经通过验证的结论。

| 平台 | 首版架构与验收环境 | 发行方式 |
| --- | --- | --- |
| Windows | Windows 11，x86_64 | 离线安装程序；支持按用户安装 |
| macOS | macOS 14 及以上，Apple Silicon 与 Intel | 按架构提供签名和公证后的应用包 |
| Linux | x86_64；Ubuntu 24.04 LTS；固定日期的 Arch/Omarchy 测试快照 | AppImage；提供原生包构建说明 |

Linux 必须覆盖 Wayland 和 X11。macOS 两种架构分别测试，不以另一架构模拟运行代替。Windows ARM、Linux ARM、移动端和浏览器版不在首版支持清单。同时，针对 Omarchy Linux，需要适配 Omarchy Linux 的 Theme Sync 功能

必须发布图形后端、系统库和最低运行环境说明。不承诺任意虚拟机或无图形加速环境可运行；无法初始化图形后端时显示原因，不留下空白窗口。

### 4.2 安装与更新

全套发行包包含八个应用。每个应用也有独立发行包，并附带其所需运行库。用户不必安装开发工具、Node.js、Python、Docker 或文档服务器。开发和构建依赖不受此限制。

各应用共享同一套发布版本与设计规范。独立安装包自带所需运行库，允许必要的重复打包，不建设全局运行库管理器。升级一个应用不得替换其他应用依赖的内核版本。

自动检查更新默认关闭。提供手动检查、下载和离线安装。更新前要求保存编辑内容；更新失败可继续使用原版本。Linux 包管理器安装的版本不绕过包管理器自行覆盖文件。

卸载应用保留用户文档。删除缓存、账号或本地历史必须单独确认。不得把用户选择的工作目录视为应用缓存删除。

## 5. 统一 UI/UX

### 5.1 组件使用

应用窗口、菜单、导航、标签页、工具栏、属性面板、对话框、通知和设置使用 Ely GPUI Components。优先复用现有组件。新增通用交互回到组件库实现，不在八个应用里复制。

仓库已有文档、Git、邮件、Agent 等组件分类，但任务清单中的 `host`、`prove` 等标签说明仍有宿主数据或接入要求。组件展示与应用能力分开验收。[S1][S2]

不使用上游 Office 的窗口、菜单和侧栏作为正式界面。不得用颜色覆盖掩盖两套交互。平台原生文件选择器、打印对话框和凭据授权窗口属于允许的系统界面。

### 5.2 布局与外观

采用同一套浅色、深色和跟随系统主题。沿用组件库的颜色、字体、间距、圆角、边框和图标 token，不新建每应用主题。不使用渐变、霓虹、装饰性玻璃效果、大面积品牌色或多层卡片。

窗口主体按需要使用标题与标签区、左侧导航、中央内容区、右侧属性区和底部状态区。无内容的侧栏不占位。属性区只显示当前选择对象的属性。专业工具不同，但相同操作的位置、名称和图标相同。

ElyMark 默认只显示必要的标签、文件和编辑入口。ElyMail 使用文件夹、邮件列表和正文。ElyTree 使用仓库导航、提交或改动列表与差异区。不得为了布局相同而强迫所有应用常驻三栏。

界面主题不修改文档本身的字体、背景、单元格填色或打印颜色。深色阅读显示与输出内容分开。

### 5.3 共用交互

| 编号 | 要求 | 验收方式 |
| --- | --- | --- |
| UX-01 | 文件菜单中的新建、打开、保存、另存为、导出和打印使用统一命名 | 在各适用应用逐项检查 |
| UX-02 | 相同操作使用相同快捷键语义；macOS 使用 Command，其他平台使用 Ctrl | 从菜单和快捷键得到相同结果 |
| UX-03 | Tab 顺序可预测，焦点可见；Esc 关闭当前浮层，不连带退出文档 | 仅用键盘完成主要工作流程 |
| UX-04 | 禁用操作说明原因；混合选择显示“混合”，不冒用首个对象属性 | 多选不同格式内容后检查属性栏 |
| UX-05 | 长任务显示范围、状态、错误和可用的取消操作 | 导出、OCR、同步、Git 操作不阻塞窗口 |
| UX-06 | 失败提示保留用户输入，并提供重试或另存路径 | 模拟权限不足、断网和磁盘不足 |
| UX-07 | 危险操作说明具体对象和影响，不只显示“确定吗” | 检查删除、覆盖、硬重置和内容删除 |
| UX-08 | 支持简体中文与英文；错误正文不用未解释的内部错误码替代 | 切换语言后检查主要界面 |
| UX-09 | 中文输入法组合输入、候选框、撤销与跨区域焦点一致 | 三端分别测试拼音输入和中英文混排 |
| UX-10 | 多屏缩放变化不造成点击偏移、选区漂移或浮层遮挡 | 100%、150%、200% 缩放下跨屏拖动 |
| UX-11 | 正文、标签、错误和状态不只通过颜色表达 | 检查灰度显示和高对比主题 |
| UX-12 | 使用系统辅助技术所需的名称、角色、状态和文本信息 | 三端完成键盘与屏幕阅读器检查 |

同一窗口只允许一个活动编辑焦点。菜单操作可作用于编辑器当前选区，但不得先清除选区。内核快捷键与 GPUI 快捷键不得重复执行同一操作。

## 6. 文件、保存与恢复

### 6.1 文件会话

Doc、Table、Show、PDF 和 Mark 的每个打开文件都有独立会话。会话记录文件位置、最后加载的文件指纹、编辑修订号、保存状态、光标或选区、缩放和恢复副本位置。

同一个文件再次打开时聚焦已有会话，或在用户要求下打开明确标注的只读视图。不允许两个窗口在不知情的情况下交替覆盖同一文件。

| 编号 | 要求 |
| --- | --- |
| FILE-01 | 新建文件在首次保存前没有隐含目标路径；关闭前处理未保存内容 |
| FILE-02 | 显示加载中、已保存、未保存、保存中、只读、外部已修改、保存失败等状态 |
| FILE-03 | 保存任务记录对应修订号；旧修订保存完成不得把更新的编辑标为已保存 |
| FILE-04 | 写入临时文件并检查写入结果，再替换目标；失败保留原文件与未保存内容 |
| FILE-05 | 保存前检查外部修改；冲突提供重新加载、保留本地副本和比较，不静默覆盖 |
| FILE-06 | 导出默认生成独立文件，不改变正在编辑文件的格式和路径 |
| FILE-07 | 复制、粘贴、拖放和附件导入失败时不删除原始数据 |
| FILE-08 | 保存、导出、打印都针对可识别的文档修订，不输出一半新一半旧的内容 |
| FILE-09 | 路径支持空格、中文、非 ASCII 字符和长文件名；保留原有大小写 |
| FILE-10 | 对损坏、加密、缺少字体和不支持的内容给出可执行提示 |

本地文件系统采用原子替换能力。网络盘、云盘占位文件或不支持原子替换的目标必须保留上一份文件，并提示相应限制，不把本地原子保存保证套用于所有存储介质。

### 6.2 默认保存行为

Doc、Table、Show、PDF 默认显式保存，后台只生成恢复副本，不擅自覆盖源文件。用户可以对普通未签名文件启用自动保存。检测到外部变更或兼容风险后，停止自动覆盖并提示。

ElyMark 对已有路径文件默认自动保存：输入停止 1 秒后提交保存任务。无路径文件先生成恢复副本，首次保存仍由用户选择位置。自动保存失败后保持未保存状态。

恢复副本默认每 10 秒生成一次，采用后台任务。同一文档只允许一个恢复任务在运行。大文件无法完成时显示最后成功恢复时间，不宣称已经持久化。保留最近 20 个恢复点，最多 7 天；用户可更改容量上限。恢复内容不得同步到外部服务。

关闭时提供保存、放弃和取消。显式放弃后记录结果，不在下次启动时把它误判为崩溃恢复。删除敏感内容相关临时文件遵守 PDF 章节的单独规则。

### 6.3 崩溃与恢复

内核崩溃不得带走其他应用。当前应用显示故障、最近一次恢复时间和重新打开入口。恢复生成新副本，不先覆盖源文件。

能重新打开恢复文件，不等于恢复了崩溃前的全部撤销历史。界面必须区分内容恢复、光标恢复和历史恢复。未具备后端支持时不宣称三者全部恢复。

## 7. LOK 共用接入要求

LOK 提供 C/C++ 接口、分块渲染、输入事件、编辑命令和回调。相关编辑 API 中存在不稳定接口，必须锁定版本并维护回归测试。[S3][S4]

LOK 负责文档模型、布局、计算、内容编辑与文件转换。GPUI 负责操作界面与显示内核输出。不得先转成另一份简单 JSON，再用组件库重新实现页面、表格或幻灯片编辑。

| 编号 | 要求 |
| --- | --- |
| LOK-01 | 使用随应用交付的固定 LOK 构建，隔离用户已安装的 LibreOffice 配置 |
| LOK-02 | 每项界面操作有明确的内核命令、参数、结果和状态回调映射 |
| LOK-03 | 处理内容区域失效通知，只更新必要图块；旧修订的画面不得覆盖新画面 |
| LOK-04 | 统一转换文档坐标、视图缩放、滚动和平台 DPI；输入与选区使用同一坐标规则 |
| LOK-05 | 字体、字号、样式、选择对象、修改状态和撤销可用性以内核为准 |
| LOK-06 | 复制粘贴覆盖纯文本、富文本、图片和表格；不只实现键盘事件转发 |
| LOK-07 | 中文输入法包含组合开始、更新、提交和取消；不拆成普通按键模拟输入 |
| LOK-08 | 页面设置、图表、样式、批注等需要的对话框由 Ely 实现；上游原生对话框不得泄露 |
| LOK-09 | 保存与导出只通过内核支持的过滤器；错误码不能被当成成功 |
| LOK-10 | 关闭文档释放内核对象、图块和临时文件；不终止其他应用的会话 |
| LOK-11 | 不执行宏和自动更新外部链接；打开后明确显示这些内容的处理状态 |
| LOK-12 | 维护功能到接口的映射表和三端测试，不以“LOK 本身支持”作为交付证据 |

图块渲染不自动提供完整无障碍文本树。辅助技术需要的文档文本、光标和选择信息必须单独接入。无法完成某项必需交互时属于发布阻断问题，不以只读截图代替编辑。

## 8. ElyDoc

### 8.1 定位与布局

用于合同、报告、方案、说明书和信函。默认采用分页视图。左侧放置大纲、搜索与页面导航，中央显示文档，右侧放置文字、段落、页面、对象或审阅属性。

新建默认格式为 DOCX，用户可以改为 ODT。已有文件保留原格式。格式转换必须由用户触发。

### 8.2 功能要求

| 编号 | 功能 | 完成要求 |
| --- | --- | --- |
| DOC-01 | 新建与模板 | 提供空白、报告和信函模板；支持从本地模板新建，不修改模板原件 |
| DOC-02 | 文字编辑 | 支持输入、选择、复制粘贴、撤销重做、字体、字号、粗斜体、上下标、颜色和高亮 |
| DOC-03 | 段落 | 支持对齐、缩进、行距、段前段后、制表位、项目符号与多级编号 |
| DOC-04 | 样式 | 支持应用、创建和修改字符及段落样式；标题样式驱动大纲和目录 |
| DOC-05 | 页面与分节 | 支持纸张、方向、页边距、分页符、分节、分栏；分页由内核负责 |
| DOC-06 | 页眉页脚 | 支持页码、首页不同、奇偶页不同；分节关系可查看和修改 |
| DOC-07 | 表格 | 支持插入、行列调整、合并拆分、边框底色、重复标题行与跨页控制 |
| DOC-08 | 图片与对象 | 支持插入、替换、裁剪、缩放、锚点和文字环绕；保留对象顺序 |
| DOC-09 | 引用结构 | 支持目录、脚注、尾注、书签、超链接、题注和交叉引用 |
| DOC-10 | 公式 | 使用内核已有公式能力插入与修改；导出后保留可编辑表示或说明格式限制 |
| DOC-11 | 审阅 | 支持批注、回复、修订记录、接受或拒绝修改；批注可定位到内容 |
| DOC-12 | 查找与检查 | 支持查找替换、大小写选项、字数统计；提供随包词典支持的离线拼写检查 |
| DOC-13 | 文档比较 | 对两个本地版本生成差异或审阅结果；保留两个源文件，不自动合并 |
| DOC-14 | 邮件合并文档 | 从 CSV 选择字段并预览，生成独立文档或 PDF；不自动发送邮件 |
| DOC-15 | 打印与导出 | 支持打印预览、页面范围、DOCX/ODT 保存与 PDF 导出；批注和修订输出方式可选择 |
| DOC-16 | 长文档导航 | 大纲、页码、搜索和书签能跳转；跳转后可回到原位置 |

### 8.3 关键流程与限制

打开合同后先检查密码、字体和可识别的兼容风险。用户修改条款、添加批注后保存。另用目标 Office 应用打开保存结果，检查内容、编号、表格、修订和页码。截图相近但修订丢失，仍判失败。

不执行 VBA、嵌入式程序或 ActiveX。对不能保证往返保存的宏文件、受保护对象和专有嵌入内容，打开时进入只读或风险状态。转换为 DOCX/ODT 时另存新文件，不覆盖原件。

## 9. ElyTable

### 9.1 定位与布局

用于清单、预算、数据整理、公式计算、图表和汇总分析。上方提供名称框与公式栏，中间是内核表格视图，下方是工作表标签和选择统计。属性面板按单元格、图表或数据区域变化。

新建默认格式为 XLSX。公式、单元格值、工作表和依赖关系只由 LOK 维护。组件库中的表格逻辑不作为第二个计算内核。

### 9.2 功能要求

| 编号 | 功能 | 完成要求 |
| --- | --- | --- |
| TABLE-01 | 工作簿 | 新建、保存、重命名、复制、移动、隐藏和删除工作表；删除前说明引用影响 |
| TABLE-02 | 区域编辑 | 支持单元格和区域选择、插入删除、行列尺寸、合并、冻结、隐藏和填充柄 |
| TABLE-03 | 公式输入 | 支持公式栏、引用选取、函数提示、错误定位及相对、绝对、混合和跨表引用 |
| TABLE-04 | 公式计算 | 覆盖算术、逻辑、条件统计、文本、日期、查找和动态数组；使用 LOK 计算结果 |
| TABLE-05 | 计算控制 | 支持自动计算、手动重算、循环引用提示；加载和保存后保持所选计算规则 |
| TABLE-06 | 名称与引用 | 支持命名区域、范围更新、引用跳转和引用错误提示 |
| TABLE-07 | 格式 | 支持数字、货币、百分比、日期、自定义格式、对齐、边框、填色和自动换行 |
| TABLE-08 | 数据整理 | 支持排序、筛选、去重、查找替换、分列和粘贴为值或公式 |
| TABLE-09 | 规则 | 支持数据验证、下拉选择、输入提示、无效数据提示和条件格式 |
| TABLE-10 | 汇总分析 | 支持数据透视表的创建、字段调整、聚合方式和刷新；显示源数据范围 |
| TABLE-11 | 图表 | 支持柱、线、条、散点和饼图；编辑数据范围、轴、图例和标题 |
| TABLE-12 | CSV/TSV | 导入前选择编码、分隔符、引号与列类型；保留账号、编号和前导零 |
| TABLE-13 | 导出 | 保存 XLSX/ODS；CSV/TSV 导出明确只含哪个工作表，并提示公式和样式损失 |
| TABLE-14 | 打印 | 支持打印区域、重复标题、分页、方向、缩放和 PDF 导出 |
| TABLE-15 | 保护 | 支持内核已实现的工作表保护、锁定单元格和编辑许可；不绕过密码 |
| TABLE-16 | 大数据浏览 | 只渲染可视区域；滚动不为所有空单元格创建 UI 对象 |

公式验收至少包含 SUM、AVERAGE、COUNT、SUMIF/SUMIFS、COUNTIF/COUNTIFS、IF/IFS、IFERROR、ROUND、文本与日期函数、INDEX/MATCH、VLOOKUP/XLOOKUP、FILTER、SORT 和 UNIQUE。该清单是产品目标；必须确认所锁定 LOK 版本及文件过滤器能完成计算和往返保存，不能因函数名可输入就认定已支持。

### 9.3 数据正确性

日期系统、时区相关输入、区域小数点和分隔符应有明确处理规则。数值和显示格式分开比较。导入 CSV 不自动把长编号转换成科学计数法，也不把所有文本都作为公式执行。

不支持的函数显示错误或兼容提示，并保留原公式和可用的缓存值；不能用 0、空值或旧缓存冒充重算结果。外部数据链接离线时保留可识别的旧值，显示未刷新状态。

不纳入 Power Query、Power Pivot、Excel VBA、外部数据库连接管理和专有插件。包含这些内容的文件按兼容规则处理，不承诺原样编辑往返。

## 10. ElyShow

### 10.1 定位与布局

用于创建、编辑和播放演示文稿。左侧显示幻灯片缩略图，中间显示编辑画布，右侧显示当前对象或页面属性，下方提供备注。新建默认格式为 PPTX。

### 10.2 功能要求

| 编号 | 功能 | 完成要求 |
| --- | --- | --- |
| SHOW-01 | 幻灯片管理 | 支持新建、复制、删除、重排、隐藏、章节管理和页面尺寸设置 |
| SHOW-02 | 模板与母版 | 支持主题、母版、布局与占位符；修改母版后更新其引用页面 |
| SHOW-03 | 文字 | 支持文本框、段落、列表、字体、颜色、尺寸和自动适配规则 |
| SHOW-04 | 图形 | 支持基本图形、连接线、填充、描边、旋转、透明度和阴影 |
| SHOW-05 | 图片 | 支持本地插入、替换、裁剪、缩放和图层顺序 |
| SHOW-06 | 对象操作 | 支持多选、对齐、分布、组合、锁定、吸附、参考线和对象列表 |
| SHOW-07 | 表格与图表 | 插入并修改表格和常用图表；数据与对象在保存后仍可编辑 |
| SHOW-08 | 备注与审阅 | 支持演讲备注、批注和定位；备注不出现在观众屏上 |
| SHOW-09 | 动画与切换 | 支持淡入淡出等基础动画、顺序、持续时间和页面切换；提供预览 |
| SHOW-10 | 媒体 | 插入并播放本地音视频；丢失链接和不支持的编码有提示 |
| SHOW-11 | 放映 | 支持全屏、从当前页播放、跳页、黑屏、激光指示和退出 |
| SHOW-12 | 多屏 | 支持选择观众屏和演讲者视图，显示当前页、下一页、备注与计时 |
| SHOW-13 | 输出 | 支持 PPTX/ODP、PDF、页面图片和讲义打印；导出范围可选择 |
| SHOW-14 | 演示准备 | 检查缺失字体、缺失媒体、外部链接和不支持对象，并给出文件位置 |

### 10.3 放映与兼容

放映使用内核能力及必要的平台媒体支持，不把页面截图轮播当成完整放映。缩略图与动画预览不阻塞编辑。

基础动画、媒体播放和演讲者视图必须分别验证 LOK 接口与平台实现。上游桌面应用具备某功能，不表示 LOK 接入已经完成。未完成这些功能不得以隐藏按钮方式通过首版验收。

首版媒体验收覆盖本地 MP4 的 H.264/AAC 组合与常用音频文件。发行前检查解码依赖及许可；媒体不能播放时保留文件和对象，显示原因。嵌入媒体随文档保存；外部链接媒体按链接处理，不伪装成已嵌入。

不承诺任意 PowerPoint 高级特效和专有对象的等效行为。不能编辑的对象采用兼容提示，不能静默栅格化后继续宣称可编辑。

## 11. ElyPDF

### 11.1 定位与内核

提供 PDF 阅读、对象编辑、批注、表单、页面组织、OCR、内容删除和签名相关操作。MuPDF 通过 C 接口接入 Rust；不为使用 MuPDF 强制引入 Python。MuPDF 是底层库，编辑器交互由 Ely 实现。[S6][S7]

左侧提供缩略图、书签和附件，中央显示页面，右侧显示编辑、批注或表单属性。所有模式使用同一套选择、撤销、保存和状态规则。

### 11.2 功能要求

| 编号 | 功能 | 完成要求 |
| --- | --- | --- |
| PDF-01 | 阅读 | 支持连续、单页、双页、缩放、旋转显示、书签、文本选择与全文搜索 |
| PDF-02 | 页面组织 | 支持插入、删除、重排、旋转、裁剪、拆分、合并和提取；修改后更新页码与引用 |
| PDF-03 | 文字编辑 | 支持编辑可识别的现有文字对象、插入文字、调整字体字号颜色和文本框；不通过白块遮盖冒充编辑 |
| PDF-04 | 图像与对象 | 支持插入、替换、移动、缩放和删除图片及受支持对象 |
| PDF-05 | 批注 | 支持高亮、下划线、删除线、便签、形状、手绘、印章与批注列表 |
| PDF-06 | 表单 | 创建和编辑基础 AcroForm 字段；支持文本、复选、单选、选择框和填写后保存 |
| PDF-07 | 文档结构 | 支持书签、链接、元数据和附件的查看与管理 |
| PDF-08 | OCR | 对扫描页进行本地中英文识别，生成可搜索文字层；可选页面范围、语言和覆盖策略 |
| PDF-09 | 内容删除 | 标记区域或文本，预览后执行真正删除；输出文件不保留被删除对象与旧修订内容 |
| PDF-10 | 文档清理 | 提供清除元数据、批注、附件和隐藏内容的明确选项；显示处理范围 |
| PDF-11 | 密码 | 在用户提供授权密码后打开；支持输出加密文件和权限设置；不破解未知密码 |
| PDF-12 | 签名 | 插入可视签名；使用用户提供的本地证书创建数字签名；显示已签文件的验证状态 |
| PDF-13 | 输出 | 保存 PDF、导出页面图片与文本、打印；可检查压缩和图像降采样设置 |
| PDF-14 | 文件恢复 | 支持修复后打开的副本和错误报告，不覆盖损坏原件 |

OCR 复用 Tesseract API 和现成语言数据。识别结果是新增的文字层，不把扫描图片自动宣称为可无损重排的段落。[S21]

### 11.3 文字编辑边界

PDF 编辑以现有页面与对象为单位。支持文本框内修改和必要的局部重排，不承诺 Word 式跨页重排。无法识别为文字的路径或扫描内容，不显示“直接编辑原文字”。

字体缺失、字形不全或原字体不能用于新增内容时，提示用户选择可用字体。替换可能改变布局时提供预览。不得先删除原内容，再因新文字绘制失败留下空白。

### 11.4 内容删除与签名规则

真正删除包括应用删除操作、重新写出文件及清理不再引用的对象。敏感内容删除不得使用保留原始修订的增量保存方式。验收同时检查文本提取、对象内容和图片区域，不能只看页面上的黑色矩形。

内容删除默认输出新文件。明确告知用户：原件、旧备份、外部同步历史和已经发送的副本仍可能包含原内容。清理 Ely 自己生成的临时副本时说明范围；不声称完成了存储介质级安全擦除。

可视签名不等于数字签名。离线验证须分别显示签名完整性、本地证书信任情况以及吊销状态是否核验。无法联网检查时显示“未核验吊销状态”，不显示笼统的“全部有效”。

修改已签文件前说明对签名的影响，默认另存未签修改副本。创建新的数字签名后不得再用普通自动保存改写文件。

XFA 动态表单、任意嵌入脚本执行、专业印前分色及 PDF 到 Office 的无损逆向转换不在范围内。

## 12. ElyMail

### 12.1 定位与后端

提供多账号邮件客户端，不建设邮件托管服务。MailCore 2 负责 IMAP、POP、SMTP 和邮件解析等能力。Ely 负责账号流程、本地存储、搜索、同步队列和界面。MailCore 2 官方列出 C++ API 与三端支持，但发行前仍须验证实际构建和依赖。[S10]

默认布局为账号与文件夹、邮件列表、阅读区。写信可在独立窗口打开。HTML 正文和富文本撰写区不用 CEF 与 Electron，渲染方式随 ElyMail 任务另定；不能把正文 HTML 解析当成完整页面渲染。

### 12.2 功能要求

| 编号 | 功能 | 完成要求 |
| --- | --- | --- |
| MAIL-01 | 账号 | 支持多个 IMAP/SMTP 账号、POP3 账号、服务器配置、TLS 与连通性检查 |
| MAIL-02 | 授权 | 提供 Gmail 与 Microsoft 邮箱的 OAuth 流程；支持服务商允许的应用密码或自定义认证配置 |
| MAIL-03 | 邮箱视图 | 支持统一收件箱、账号独立视图、文件夹、未读、标记和附件筛选 |
| MAIL-04 | 阅读 | 支持纯文本、HTML、内嵌图片、附件、原始邮件头与会话线程 |
| MAIL-05 | 写信 | 支持收件人、抄送、密送、回复、回复全部、转发、签名、附件和纯文本/富文本撰写 |
| MAIL-06 | 草稿 | 编辑中保存本地草稿；可选择同步到服务端草稿箱；恢复不依赖网络 |
| MAIL-07 | 发送 | 提供持久化发件队列、重试、取消待发送、附件大小提示与发送结果 |
| MAIL-08 | 组织 | 支持已读未读、标记、移动、归档、删除与恢复；映射到服务端实际能力 |
| MAIL-09 | 搜索 | 搜索本地已缓存的发件人、收件人、主题、正文、日期和附件文件名 |
| MAIL-10 | 附件 | 支持下载、离线保留、另存、预览和用 Ely 应用打开；显示缓存状态 |
| MAIL-11 | 规则 | 支持按发件人、收件人、主题设置本地过滤规则，执行移动、标记或归档 |
| MAIL-12 | 联系人 | 维护本地地址补全和联系人，支持 vCard 导入导出，不建设完整通讯录服务 |
| MAIL-13 | 迁移 | 支持 EML 查看与导出、MBOX 导入导出；导入数据不直接写入远程邮箱 |
| MAIL-14 | 同步控制 | 支持手动刷新、运行期间定时同步、暂停和按文件夹离线下载 |
| MAIL-15 | 通知 | 支持新邮件通知与静音；锁屏通知默认不显示正文 |

Gmail 和 Microsoft 的 IMAP/SMTP OAuth 有各自的应用注册、权限与服务端条件。正式版内置登录必须完成适用的注册及审核。不得把用户自行申请开发者凭据作为普通账号接入的默认步骤，也不得承诺绕过组织禁用 IMAP/SMTP 的策略。[S11][S12]

### 12.3 缓存与同步

首次连接默认下载邮件头及最近 90 天的正文。附件按需下载，用户可为文件夹启用完整离线保留。界面显示最后同步时间、下载范围、尚未缓存的内容和失败原因。搜索结果注明只覆盖本地缓存。

IMAP 消息身份包含账号、邮箱、UIDVALIDITY 与 UID，不能只用主题或 Message-ID 作为同步主键。线程结合邮件引用关系组织，不把同主题的所有邮件强行合成一组。

离线移动、删除和标记先进入本地待同步队列。服务端状态已变化时重新核对，不无限重试已不存在的消息。POP3 的“保留服务端副本”默认开启，不提供伪造的 IMAP 文件夹同步能力。

附件编辑先创建工作副本。修改附件不覆盖原始 MIME 邮件；用户需要发送修改结果时，将工作副本添加到新草稿。

### 12.4 发送状态

发件状态必须区分：草稿、排队、正在发送、服务器已接受、失败、结果未知和已取消。

SMTP 返回成功后才标记服务器已接受。这不等于收件人已收到或已阅读。服务器已接受但保存“已发送”副本失败时，只重试保存副本，不重发邮件。

传输结束后连接中断、无法确认服务器是否接受时，进入结果未知。保留 Message-ID 和发送记录，允许检查后处理，不自动重发造成重复邮件。

用户在离线状态点击发送，即授权该队列项在恢复连接后尝试发送；界面当时必须说明，并允许取消。应用重启后，对遗留的结果未知项不得自动再次发送。关闭应用时说明未发送队列是否仍会运行；没有后台进程时不声称会继续发送。

HTML 邮件默认阻止远程图片和跟踪资源，禁用脚本。用户可以对当前邮件或发件人授权加载。邮件内容无法调用编辑器的本地文件桥接接口。

完整日历、Exchange 本地部署专有协议、企业归档、S/MIME 与 PGP 密钥管理不在范围内。

## 13. ElyTree

### 13.1 定位与后端

提供独立 Git 桌面客户端。使用 Git CLI 执行仓库操作，使用现有 Git、差异和树形组件呈现结果。不重写 Git 对象存储、索引和合并算法。

通过参数数组启动 Git，不拼接 shell 命令字符串。状态读取使用适合程序处理的格式，例如 `git status --porcelain=v2 -z`，不解析终端彩色输出。[S13]

### 13.2 功能要求

| 编号 | 功能 | 完成要求 |
| --- | --- | --- |
| TREE-01 | 仓库 | 支持初始化、打开、克隆、最近仓库和多仓库切换；显示实际路径 |
| TREE-02 | 工作区 | 区分未跟踪、未暂存、已暂存、冲突和忽略文件；响应外部 Git 操作 |
| TREE-03 | 差异 | 支持行内/并排差异、空白选项、文件重命名和图片差异预览 |
| TREE-04 | 暂存 | 支持按文件、差异块及可验证的行选择暂存和取消暂存；提交前显示实际索引内容 |
| TREE-05 | 提交 | 支持提交、修改最近提交、提交信息、身份与已有 Git 签名设置 |
| TREE-06 | 历史 | 支持提交图、提交详情、文件历史、Blame 和提交搜索 |
| TREE-07 | 分支与标签 | 支持创建、切换、重命名、删除分支，以及创建和删除标签 |
| TREE-08 | 合并与变基 | 支持 merge、rebase、cherry-pick、revert，以及继续、中止和错误恢复 |
| TREE-09 | 冲突 | 显示 base、当前侧和另一侧，提供块级选择与手动编辑；保存后明确标记已解决 |
| TREE-10 | 暂存工作 | 支持 stash 创建、查看、应用、弹出和删除；应用失败保留原 stash |
| TREE-11 | 远程 | 支持远程地址管理、fetch、pull、push、上游分支和进度取消 |
| TREE-12 | 仓库结构 | 支持 worktree、submodule 的状态与基础管理；显示 LFS 指针及对象可用状态 |
| TREE-13 | 恢复与清理 | 提供 reflog 查看、恢复引用、丢弃改动和清理未跟踪文件；危险操作先预览 |
| TREE-14 | 外部工具 | 支持打开终端、文件管理器和指定编辑器；可在 ElyMark 打开 Markdown |

### 13.3 操作规则

同一仓库的写操作串行执行。外部 Git 进程占用锁时等待或提示，不擅自删除锁文件。用户从终端切换分支后，应用必须重新读取工作区、索引和 HEAD。

强制推送默认采用带租约保护的方式，显示远端、分支及待覆盖影响。普通按钮不得隐含硬重置。丢弃工作区文件、清理未跟踪文件和删除分支的确认不可复用为以后所有危险操作的永久授权。

合并与变基中的两侧名称按当前操作解释，不能固定把“ours”标为用户期望保留的一侧。冲突编辑结果与暂存动作分开。取消差异查看不改变仓库。

认证复用 Git credential helper、系统 SSH 和用户已有签名工具。密钥不写入应用数据库。终端交互、凭据提示和 hook 失败必须可见，不隐藏输出后只给出“操作失败”。

Git 与必要的 LFS 运行程序随 ElyTree 发行包提供，允许用户切换到已验证的系统版本。显示当前路径和版本。代理、凭据和签名遵守所选 Git 环境，不维护一套不可见的替代配置。

DOCX、XLSX、PPTX 和 PDF 默认按二进制文件展示变更。可提供预览，但不承诺文本级合并。ElyTree 不强制其他应用把文件放入 Git 仓库。

Git 托管、PR 审核平台、Issue 系统、CI 平台和远程开发环境不在范围内。

## 14. ElyMark

### 14.1 定位与编辑框架

提供以本地 Markdown 文件为中心的编辑器。支持可视化编辑、源码编辑和只读预览。文件可由其他编辑器、Git 或 Agent 修改，不要求导入专有知识库。

界面用 Ely-GPUI-Components 的 Markdown 文档组件，全部原生 GPUI：全文只在一个源码编辑器里，可视模式按块渲染，按下的块以原文编辑；源码与预览共用同一份文本。解析用 markdown-rs，公式用 RaTeX，Mermaid 用 mermaid-rs-renderer。文本即文件原文，不经编辑模型序列化。[S14][S15][S16]

参考 MarkText 的 Markdown 编辑行为、ColaMD 的本地文件同步和内容保留规则、Markion 的 GPUI 原生 Markdown 编辑，不复制其整个应用窗口。不用 Electron，不用 CEF 或其他网页内容宿主。[S17][S18]

### 14.2 功能要求

| 编号 | 功能 | 完成要求 |
| --- | --- | --- |
| MARK-01 | 本地文件 | 新建、打开、保存、重命名和另存；支持直接打开文件或文件夹 |
| MARK-02 | 编辑模式 | 可视化、源码和只读预览可切换；切换本身不修改文件内容 |
| MARK-03 | Markdown | 支持 CommonMark 与 GFM 常用语法：标题、列表、任务、引用、链接、图片、表格和代码块 |
| MARK-04 | 扩展语法 | 支持脚注、数学公式、Mermaid 与 YAML front matter；资源随包提供 |
| MARK-05 | 导航 | 提供文件树、文档大纲、多标签、最近文件和按标题跳转 |
| MARK-06 | 编辑工具 | 支持查找替换、源码正则搜索、缩进、列表续写、表格行列操作和代码高亮 |
| MARK-07 | 附件 | 支持拖放和粘贴图片，默认复制到文档旁的资源目录并写入相对路径 |
| MARK-08 | 外部修改 | 监视文件内容、删除、重命名和原子替换；未保存内容参与冲突处理 |
| MARK-09 | 书写视图 | 支持专注模式、打字机滚动、正文宽度和字体设置；不改变 Markdown 语义 |
| MARK-10 | 搜索 | 提供当前文件与用户打开文件夹内的搜索；不默认扫描整盘 |
| MARK-11 | 输出 | 导出自包含或带资源目录的 HTML、PDF 和纯文本；支持打印及富文本复制 |
| MARK-12 | 会话恢复 | 恢复打开标签、未保存内容、光标、滚动和视图设置 |
| MARK-13 | Git 配合 | 在仓库内显示文件是否有改动，并可调用 ElyTree 查看；不内置第二套 Git 客户端 |
| MARK-14 | 大文件 | 大文件采用延迟渲染或源码视图，说明限制，不截断保存内容 |

数学与 Mermaid 默认仅渲染文档中已保存的源代码，不执行任意本地命令。语法错误显示原文与错误位置，不清空代码块。

### 14.3 原文与保存规则

未发生编辑时，打开、切换视图和保存不得改写原文件。保留 BOM 状态、换行风格、front matter 原文、代码块内容和不认识的扩展语法。

可视化编辑允许规范化实际修改的语法块，但不得借机重写整篇文档。框架无法保留的结构应显示为原文块，或提示在源码模式编辑，不能删除后重建。

模式切换前提交当前编辑事务，保留内容历史与当前修订。撤销只作用于本文件；不能撤销另一个标签的编辑，也不能把视图切换变成一次内容重写。

换行解释采用明确规则，默认遵循所选 CommonMark/GFM 语义。提供单换行显示为换行的阅读选项时，不自动在源文件插入 `<br>` 或额外空格。

### 14.4 外部变更

文件未修改时，外部写入触发重载，并尽量保持滚动和光标。文件有未保存内容时，不自动覆盖；提供磁盘版本、本地版本与共同基线的比较。

文件被外部删除后，仍保留内存内容并提示另存。原子保存导致的重命名事件不能被误判为永久删除。网络目录和监听失效时提供手动刷新，不声称所有文件系统都支持相同监听能力。

AI 或脚本修改文件与其他外部修改使用同一套处理规则。ElyMark 不需要依赖 ElyAgent 才能响应文件变化。

知识图谱、双向链接数据库、笔记同步服务、多人协同和插件市场不在范围内。

## 15. ElyAgent

### 15.1 定位与独立性

提供独立的 Agent 配置和会话管理界面。用户选择已安装的 Agent、工作目录、模型配置和执行参数，查看输入输出、工具调用、文件改动和运行状态。

推理循环来自嵌入的 Kigi，不另写一套；不成为其他 Ely 应用的内置 AI 功能，也不自动读取邮件或办公文档。用户通过工作目录或选定文件向后端提供内容。

### 15.2 接入基线

后端以 Kigi CLI（https://git.zacharyzhang.com/ZacharyZhang-NY/Kigi-CLI，Rust）为基础，以 Rust 依赖直接嵌入，不用 ACP（用户 2026-10-05 定）。提供商登录（订阅账号或 API 密钥）、模型与端点配置沿用 Kigi 的实现，不另写一套。不解析终端装饰文本来伪造结构化事件。

会话恢复只在 Kigi 的会话存储支持并通过验证时启用。不能把本地历史回放当成后端会话已经恢复。

### 15.3 功能要求

| 编号 | 功能 | 完成要求 |
| --- | --- | --- |
| AGENT-01 | 工具管理 | 检测、添加和选择本地 Agent 路径，显示版本、启动参数与可用状态 |
| AGENT-02 | 配置管理 | 按后端支持配置提供商、端点、模型及参数；密钥引用系统凭据库 |
| AGENT-03 | 配置保护 | 修改已有工具配置前备份；只修改明确字段，保留未知字段和用户注释 |
| AGENT-04 | 会话 | 按工作目录分组，支持新建、命名、搜索、归档和删除本地记录 |
| AGENT-05 | 输入输出 | 支持流式输出、停止生成、复制、日志展开和发送失败重试 |
| AGENT-06 | 并行运行 | 支持多个本机会话并行；显示各自目录、后端、模型和状态 |
| AGENT-07 | 工具与授权 | 展示后端提供的工具调用和授权请求；用户决定允许或拒绝 |
| AGENT-08 | 文件与产物 | 展示后端声明的改动、差异和产物；可打开文件或交给 ElyTree 查看 |
| AGENT-09 | 会话恢复 | 后端支持时恢复会话；否则只能查看历史或新建，不提供虚假的恢复按钮 |
| AGENT-10 | 执行控制 | 支持取消请求、停止进程和清理已退出会话；强制终止前说明影响 |
| AGENT-11 | 历史 | 本地保存可用的消息、工具事件、时间、后端会话标识和错误；可导出文本或 JSON |
| AGENT-12 | 用量 | 仅显示后端返回的 token、费用或上下文信息；缺失时显示未知 |
| AGENT-13 | 本地模型 | 允许连接后端本身支持的本地兼容端点，显示连通性；不内置模型下载与推理引擎 |
| AGENT-14 | 托盘 | 提供菜单栏或托盘入口与运行会话数量；可关闭，不依赖托盘完成操作 |

### 15.4 会话状态与生命周期

会话状态包括未启动、启动中、空闲、运行中、等待输入、等待授权、已完成、已取消、失败和连接中断。只有收到后端证据才能进入相应状态。未提供进度百分比时不估造百分比。

界面关闭窗口时，如有运行会话，提示继续在应用后台运行或停止后退出。继续运行指 ElyAgent 进程仍在，不额外安装系统级守护服务。系统无托盘时仍需保留可重新打开的应用入口。

明确选择退出应用时，说明哪些任务会终止并等待用户决定。崩溃或系统重启后只展示持久化历史及可验证的恢复选项，不承诺进程继续运行，也不自动重放可能改写文件的请求。

同一工作目录启动多个可写会话时提示可能发生冲突，提供使用独立目录或 worktree 的入口，但不强制建设自动工作树编排系统。

切换模型或提供商只按后端支持的机制执行。不宣称所有历史会话可以无损迁移到不同后端。不内置跨协议转换网关、账户轮换或额度规避功能。

独立 Agent 的安装、授权和模型供应商条件不应影响其他七个应用的本地功能。

## 16. 应用之间的连接

应用间只提供明确、可取消的文件操作，不建设跨应用事务系统。

| 入口 | 行为 | 边界 |
| --- | --- | --- |
| 邮件附件用 Ely 打开 | 将附件复制为工作副本，再交给对应应用 | 不修改原始邮件 |
| 文档导出后查看 | 在 ElyPDF 或系统默认 PDF 应用打开输出文件 | 不把导出文件当成原编辑会话 |
| Markdown 查看版本 | 向 ElyTree 传递仓库路径和文件路径 | 不自动提交、不自动创建仓库 |
| Agent 查看产物 | 按用户选择调用已安装的 Ely 应用 | 不静默打开敏感目录或执行文件 |
| 文件作为邮件附件 | 创建草稿并附加指定文件 | 不自动发送 |
| 应用切换 | 显示已安装应用并启动 | 不要求先打开统一启动器 |

目标应用未安装时，提供系统默认应用或安装说明，不阻塞原工作。应用间不读取彼此的内部数据库。

## 17. 工程结构与接入边界

### 17.1 项目组织

使用一个 Rust workspace。各应用独立编译，共享 UI、平台适配和文件处理代码。内核依赖按应用引入，不因 workspace 共存而全部链接。

```text
ely-office/
  apps/
    ely-doc/
    ely-table/
    ely-show/
    ely-pdf/
    ely-mail/
    ely-tree/
    ely-mark/
    ely-agent/
  crates/
    ely-ui/          # 组件库的应用级组合与共用交互
    ely-platform/    # 文件对话框、打印、凭据、系统集成
    ely-files/       # 文件会话、保存、恢复、监听
    ely-lok/         # LOK 接入；仅 Doc/Table/Show 使用
    ely-pdf-engine/  # MuPDF 与 OCR 接入
    ely-mail-engine/ # 邮件协议、同步和本地存储
  assets/
  tests/
  packaging/
```

Ely GPUI Components 保持独立仓库依赖。ElyTree 的 Git 调用与 ElyAgent 的适配器先放在各自应用内；没有重复需求时不抽出通用框架。

### 17.2 进程与状态

GPUI 主进程负责界面和用户输入。LOK 和 MuPDF 放在本地工作进程中，避免解析或原生库故障直接终止整个界面。默认按应用实例启动所需工作进程，不预建全套进程池。

工作进程使用本地管道传递控制消息和结果。每条请求包含会话标识、请求标识及所需的修订信息。只在进程边界使用通信协议；进程内使用普通 Rust 类型和函数，不把所有组件都包装成消息服务。

文档会话、编辑状态和内核对象的责任必须明确。内核持有文档的可写状态，UI 保存可展示的状态，不双向同步两份完整文档模型。调用顺序和线程规则按内核要求执行。

C/C++ 异常、原生错误与资源释放在 FFI 边界处理，不能跨 Rust 调用栈传播未处理的原生错误。原生库版本和绑定一起锁定。

邮件同步、Git 命令、OCR、缩略图与索引构建在后台任务中执行，不阻塞 UI 事件循环。后台指应用运行期间的本地任务，不表示默认安装常驻系统服务。

### 17.3 内容渲染

不用 CEF，不用 Electron（用户 2026-10-11 定）。Mark 的编辑与预览全部由 GPUI 绘制（§14.1）。Mail 的 HTML 正文和富文本撰写的渲染方式随 ElyMail 任务另定，定前不写成已有。

Ely 主题 token 用于内容区。键盘、焦点、选择、缩放、右键菜单和输入法进入统一适配规则。对话框和应用菜单由 GPUI 展示。

邮件阅读不运行正文脚本。Markdown 文档里的 HTML 不运行；数学与图只渲染保存的源码。外部文档内容不能调用任意本地命令。

### 17.4 不建设的技术设施

不引入 Kubernetes、Docker 运行依赖、远程数据库、消息中间件、事件溯源系统、通用插件市场、统一知识图谱、分布式搜索或独立账号中心。

应用间不做 RPC 服务发现。Agent 不以独立后台服务器为前提。Git 不同时接入多个 Git 内核。Markdown 只有一个解析内核（markdown-rs）。新抽象必须服务于已有的重复需求。

## 18. 数据、配置与隐私

### 18.1 存储边界

| 数据 | 存储位置与规则 |
| --- | --- |
| 办公文件、PDF、Markdown | 用户指定目录；不强制复制到应用资料库 |
| Git 数据 | 仓库自身的 Git 目录及工作区；ElyTree 只缓存视图状态 |
| 邮件与附件 | ElyMail 独立 SQLite 索引和本地内容目录；可导出和设置容量 |
| Agent 会话 | ElyAgent 独立本地记录；区分应用记录与后端自身记录 |
| 通用偏好 | 版本化的本地配置文件；仅保存主题、语言及共用交互设置 |
| 应用偏好 | 各应用独立保存窗口、最近文件、编辑和业务设置 |
| 恢复副本 | 各应用恢复目录；受时间和容量限制 |
| 密钥与令牌 | 系统凭据库；不写入普通配置、诊断日志或同步索引 |

数据库不作为通用文档格式。全文索引是可重建数据，索引损坏不能导致邮件原文、文档或会话原始记录丢失。

配置修改采用原子写入与必要的文件锁。多个应用同时修改共用偏好时合并已知字段，不互相覆盖其他字段。不为此启动常驻配置服务。

### 18.2 凭据与私密内容

Windows 使用系统凭据能力，macOS 使用 Keychain，Linux 使用可用的 Secret Service。系统凭据库不可用时，允许凭据只保留到本次退出，不能静默退回明文保存。

加密文档的密码只在需要期间保留。其恢复副本不得以明文落盘；使用成熟加密库和系统密钥保护。用户不能解锁恢复密钥时，提示无法恢复，不导出不受保护副本。

第三方模型、邮箱和 Git 服务的连接由用户配置或授权。文档编辑不向这些服务发送内容。打开文件不会自动产生 AI 请求。

诊断日志默认不写正文、附件、密钥和提示词。Agent 的本地会话历史是用户数据，不属于可自动上传的诊断日志。导出诊断包前显示内容范围，并允许移除路径和个人信息。

不内置行为广告和自动上传分析。崩溃报告由用户触发提交。更新检查与远程内容加载遵守离线及隐私设置。

### 18.3 数据管理

设置中提供缓存容量、清理、恢复副本管理、邮件导出和 Agent 历史导出。删除账号先说明会删除哪些本地缓存、草稿和凭据，不影响未授权删除的服务端数据。

数据库升级前创建备份。升级失败保留旧数据，并阻止用不兼容结构继续写入。应用降级不尝试猜测转换；允许恢复备份或只读导出。

## 19. 文件兼容与输出

### 19.1 格式范围

| 应用 | 正式编辑与保存范围 | 导入或受限范围 | 输出 |
| --- | --- | --- | --- |
| Doc | DOCX、ODT | DOC、RTF、TXT，以及可识别的模板；按兼容提示转换 | DOCX、ODT、PDF、文本 |
| Table | XLSX、ODS | XLS；CSV/TSV 按导入设置转换；宏文件只读或另存 | XLSX、ODS、CSV、TSV、PDF |
| Show | PPTX、ODP | PPT、模板及含专有对象的文件按兼容提示处理 | PPTX、ODP、PDF、PNG/JPEG |
| PDF | 本文定义的 PDF 对象、批注、表单和页面功能 | XFA、嵌入程序或无法编辑的对象只读或提示 | PDF、页面图片、文本 |
| Mail | 本地消息、草稿与服务端协议操作 | EML、MBOX、vCard | EML、MBOX、附件、vCard |
| Tree | 标准本地 Git 仓库 | 浅克隆、LFS、submodule 等显示其限制 | Git 原生提交与引用 |
| Mark | MD、Markdown 文本与本地资源 | 未支持语法保留原文；编码转换需确认 | Markdown、HTML、PDF、文本 |
| Agent | 已验证后端的配置与会话记录 | 外部会话按适配器能力读取，不作通用格式承诺 | 文本、JSON、后端支持的格式 |

支持文件格式不等于支持该格式所有功能。发行说明必须提供版本化兼容清单，注明已验证的内容、限制和保存行为。

### 19.2 往返验证

每个办公测试文件依次执行：在 Ely 打开、编辑指定内容、保存、关闭、再次打开，再由独立目标应用打开。检查结构、内容、公式、修订、批注、对象可编辑性和输出画面。

不只与同一个内核比较。DOCX/XLSX/PPTX 应包含与 Microsoft Office 的交叉检查；测试机和目标 Office 版本写入报告。用于测试的第三方软件由团队合法取得，不要求终端用户安装。

字体一致的环境与字体缺失环境分别测试。字体缺失时出现分页差异不应被隐瞒，替换规则和缺失字体列表必须可见。产品不捆绑无再分发许可的微软字体。

数值计算使用独立预期结果。精确整数、日期、错误值和文本严格比较；浮点数按测试用例声明的容差比较，不设一个掩盖所有误差的全局容差。

已知高风险文件默认不自动覆盖。无法完整识别所有未知对象时，不宣称“已经检测全部兼容风险”。首次修改此类文件应提示另存副本。

### 19.3 打印与 PDF 输出

打印预览与实际输出使用同一文档修订、纸张、页边距和缩放设置。显示页数和范围。打印取消不改变文档内容。

Doc、Table、Show 的 PDF 输出由 LOK 完成，不要求安装 ElyPDF。ElyMark 的 PDF 输出由本地渲染与打印能力完成，不要求安装 LOK。ElyPDF 用于后续编辑和查看，而不是全套应用的强制导出服务。

## 20. 质量与性能要求

### 20.1 验收环境

基准使用 16 GB 内存、NVMe 存储、至少 6 个 CPU 核心或同档 Apple Silicon，以及满足所选图形后端要求的设备。三端记录具体 CPU、GPU、驱动、系统、字体、编译版本和样本哈希。

以下指标按发行构建、每项 30 次测试的 P95 统计。首次安装初始化与日常冷启动分开记录。网络、远程模型速度及打印机出纸时间不计入本地响应指标。指标是项目目标，调整需要在发布前更新文档和理由。

| 编号 | 项目 | 目标与样本 |
| --- | --- | --- |
| PERF-01 | 启动 | 无文件冷启动至窗口可操作不超过 3 秒；不预加载未使用内核 |
| PERF-02 | 交互 | 普通点击与按键反馈不超过 100 毫秒；长任务不连续阻塞主线程 100 毫秒以上 |
| PERF-03 | 文档打开 | 100 页、20 张图片、10 MB 内 DOCX，5 秒内显示首屏并接受操作 |
| PERF-04 | 表格打开 | 10 万非空单元格、1 万个简单公式的工作簿，5 秒内接受操作；重算另记录 |
| PERF-05 | PDF 浏览 | 本地 1000 页、200 MB 内 PDF，3 秒内显示第一页；不先渲染全部页面 |
| PERF-06 | 本地搜索 | 已完成索引的 10 万封邮件或 10 万提交仓库，常见查询首屏结果不超过 1 秒 |
| PERF-07 | Markdown | 1 MB 文档 2 秒内进入可编辑模式；超大文件允许进入明确的源码模式 |
| PERF-08 | 资源释放 | 连续打开关闭 20 次后，活动文档对象与句柄回到基线，内存无持续单向增长 |
| PERF-09 | 多会话 | 4 个 Agent 会话同时流式输出时，其他会话选择和日志滚动仍满足交互目标 |

不提前宣传固定内存占用或比其他 Office 更快。发布报告列出单应用与内核子进程的总内存，不能只测 GPUI 主进程。

### 20.2 稳定性

保存失败、内核崩溃、强制结束、磁盘不足、目录只读、临时文件损坏、失去网络、OAuth 失效、外部文件替换和系统休眠必须有测试。

主要应用完成连续 8 小时编辑与切换测试。测试中不得出现源文件损坏、跨文档撤销、无提示覆盖、邮件重复发送或 Git 状态伪报。

不能取消的操作应明确说明所处步骤，并允许用户等待或安全关闭界面。不得为了满足“有取消按钮”而在破坏性写入中任意杀进程。

### 20.3 无障碍与国际化

键盘能完成打开、编辑、保存、搜索和主要工具操作。焦点框不依赖鼠标悬停。内容区和 GPUI 区域间的焦点切换可预测。正文及常规界面文字的对比度目标至少为 4.5:1。

覆盖简体中文与英文输入、混合字体、标点、组合输入和非 ASCII 路径。日期、数字与纸张设置使用显式区域配置。修改界面语言不得重解释已存储的单元格数值或文档日期。

不因内核渲染成图块就把整个文档对辅助技术隐藏。文档内容、表格单元格和编辑状态的可访问性属于正式验收。

## 21. 开源与许可证

### 21.1 自有代码默认许可

本 PRD 对新增应用代码采用 AGPL-3.0-or-later 作为发行默认，便于与 MuPDF 的开源使用路线保持一致。Ely GPUI Components 继续保留现有 MIT/Apache-2.0 许可，不因被应用使用而改写其许可证。[S1]

第三方代码保持原许可证。不得把 LibreOffice、Git 或其他依赖的版权声明统一替换成 Ely 的声明。最终发行须按实际链接、进程调用、修改和打包方式审查，进程隔离不作为免除许可义务的依据。

### 21.2 第三方发行要求

| 依赖 | 发行要求 |
| --- | --- |
| MuPDF | 按锁定版本的 AGPL 条款提供对应源码、修改、集成和构建资料；不把公开 UI 仓库当成已完成合规 [S8][S9] |
| LibreOffice/LOK | 保留 MPL 2.0 及附带依赖的相应声明；发布对受约束文件的修改与所需资料 [S5] |
| MailCore 2 | 保留其许可、版权和免责条款，并检查其传递依赖 [S24] |
| Git | 作为独立程序分发并遵守其 GPLv2 等实际适用条款；提供所发行版本的源码取得方式 [S23] |
| Markdown | 保留 markdown-rs、RaTeX（含随带字体）、mermaid-rs-renderer 及其依赖的许可；逐项检查实际发行包 [S14][S15][S16] |
| OCR、字体、词典和媒体组件 | 记录每个资源的来源、版本和再分发条件，不从系统目录随意拷贝受限资源 |

MuPDF 的 AGPL 路线允许符合条件的开源集成；“项目开源”本身不足以证明整个发行包已经符合条件。是否收费与源码义务分开处理。[S8][S9]

普通用户文档不因经过应用编辑而自动成为应用源码。不要在产品协议中要求用户公开文档或邮件。许可证审查涉及应用与依赖，不把用户内容列入发布源码包。[S9]

### 21.3 发布资料

每个发行版本必须附带自有源码、锁定依赖清单、上游补丁、构建步骤、第三方通知和许可证文本。二进制下载页提供对应版本源码入口。不得只链接到会变化的上游默认分支。

公开构建说明必须足以让贡献者重建应用，不依赖未公开私有脚本。签名密钥和用户凭据不属于公开构建资料。

本节作为发布检查要求，不替代针对最终发行包的法律审查。

## 22. 测试与验收

### 22.1 测试资料

使用可再分发、自行制作或已获得测试授权的样本。真实客户资料须先取得授权并去除不应公开的信息，不放入公共仓库。

每个功能编号至少关联一个测试用例。每项用例记录输入样本、操作、预期结果、平台、内核版本和实际结果。测试未运行、失败与不适用分开记录。不能用“接口存在”替代操作验证。

UI 自动测试、内核测试和手工交互测试互相补充。三端的输入法、打印、屏幕阅读器、外接显示器和系统凭据流程需要真实环境检查。

### 22.2 跨应用验收用例

| 用例 | 覆盖范围 | 通过条件 |
| --- | --- | --- |
| QA-01 | 安装与离线启动 | 干净测试机断网安装；八个应用均可打开；没有登录、CDN 或外部文档服务器依赖 |
| QA-02 | 独立安装 | 只安装 Mark、Tree 或 Agent 时不安装或启动 LOK；只安装 Doc 时可独立导出 PDF |
| QA-03 | 统一界面 | 菜单、属性、错误、快捷键和主题符合第 5 节；没有上游产品界面泄露 |
| QA-04 | 输入与焦点 | 三端输入中文、选择文本、打开工具栏、提交组合输入和撤销，结果正确 |
| QA-05 | 多屏 | 缩放和屏幕变化后，选区、点击、浮层及演示画面不偏移 |
| QA-06 | 保存失败 | 断开目标盘、设置只读或写满磁盘，原文件保留，未保存状态和恢复内容正确 |
| QA-07 | 外部冲突 | 外部程序在本地未保存时覆盖文件，Ely 保留两份内容并要求处理 |
| QA-08 | 并发保存 | 在旧修订保存期间继续编辑，完成后仍显示新修订未保存 |
| QA-09 | 崩溃恢复 | 终止内核或应用，重新启动能定位恢复副本；不覆盖原件，不声称恢复不存在的历史 |
| QA-10 | Doc | 合同、长报告、跨页表格、目录和修订文件完成编辑、保存及独立应用往返验证 |
| QA-11 | Table | 函数、引用、日期、透视表、图表和 CSV 样本与预期一致；未知公式不显示伪结果 |
| QA-12 | Show | 母版、图表、备注、动画和本地媒体可编辑；多屏放映不暴露备注；PPTX 对象可继续编辑 |
| QA-13 | PDF 编辑 | 修改文字、图像、表单和页序后，在独立阅读器检查；失败不破坏原对象 |
| QA-14 | PDF 删除 | 应用删除后通过对象、文本和图像检查确认输出文件中无被删内容及旧修订残留 |
| QA-15 | PDF OCR 与签名 | 扫描件可本地搜索；签名显示完整性和信任边界；离线不虚报吊销核验 |
| QA-16 | Mail 离线 | 无网络可读取已缓存内容、搜索、写草稿和入队；未缓存附件不显示成已下载 |
| QA-17 | Mail 发送 | 模拟发送前失败、接受后断连和已发送副本失败，不重复发送，不误报最终状态 |
| QA-18 | Mail 同步 | 文件夹变更、UIDVALIDITY 变化、服务端删除和令牌失效后不丢本地草稿，不发生错误关联 |
| QA-19 | Git 结果 | GUI 操作后用独立 Git 命令检查索引、提交、引用和工作区，结果一致 |
| QA-20 | Git 异常 | 测试冲突、hook 失败、凭据失败、锁竞争、变基中断和取消；状态与实际仓库一致 |
| QA-21 | Mark 原文 | 无编辑保存逐字节一致；局部编辑不重写无关段落、front matter 和未知语法 |
| QA-22 | Mark 外部变更 | 测试原子替换、删除、重命名和并行编辑；不覆盖未保存内容，不截断导出 |
| QA-23 | Agent 能力 | 测试结构化和普通命令后端；不支持恢复、费用或权限事件时显示真实限制 |
| QA-24 | Agent 生命周期 | 并行会话、窗口关闭、停止、完整退出和重启后的状态与进程事实一致 |
| QA-25 | 隐私与断网 | 抓取测试机流量，未授权时无文档、正文、日志、CDN 或自动更新请求 |
| QA-26 | 升级与卸载 | 升级失败保留原版本和数据；卸载不删除用户目录；剩余应用继续启动 |
| QA-27 | 许可证 | 安装包、源码包、通知和构建资料相互对应，所打包资源均有来源与许可记录 |
| QA-28 | 无障碍与性能 | 完成第 20 节指标和键盘、辅助技术检查，报告记录全部子进程资源 |

### 22.3 不得带入正式版的问题

以下任一问题阻止正式发布：源文件损坏；静默丢失受支持内容；覆盖未保存文件；跨标签撤销；公式伪结果；PDF 删除后仍可恢复敏感内容；无法确认的邮件被自动重发；Git 危险操作未说明；Agent 会话被伪报为可恢复；三端核心编辑不能完成；发行包缺少必要许可或对应源码。

其他问题必须写入已知问题说明，并且不破坏本文定义的必需功能。不能通过把必需功能改成隐藏、只读或占位来规避发布要求。

## 23. 必须验证的工程风险

这些检查属于实现和发布流程，不构成分阶段交付。当前文档未包含三端集成程序的实测结果。

| 检查项 | 需要提交的证据 | 不通过时的处理 |
| --- | --- | --- |
| LOK 三端嵌入 | Doc/Table/Show 的编辑、保存、中文输入与窗口操作录像及日志 | 修复适配或更新设计决策；不能只交付查看器 |
| LOK 高级功能 | 母版、放映、图表、修订、输入法、打印和无障碍的接口映射及用例 | 补齐桥接或维护必要上游补丁，不跳回上游原生 UI |
| MuPDF 编辑 | 字体、对象修改、表单、删除及保存的样本结果 | 修复对象编辑与输出；不得改为视觉覆盖冒充编辑 |
| MailCore 2 | 三端可重复构建、TLS、OAuth、同步和 MIME 测试 | 处理依赖及适配问题；替换后端必须显式修订选型 |
| Markdown 原生编辑 | 可视、源码、预览的输入、焦点、缩放、输入法和辅助技术测试 | 未通过不能以 CEF、WebView 或 Electron 代替 |
| Markdown 原文保留 | 无编辑保存、模式切换、局部修改和外部冲突的字节级差异 | 修复映射与保存；未知语法回到原文模式，不删除 |
| 邮箱服务注册 | 正式 OAuth 配置、适用审核状态与用户流程 | 不将未获许可的内置登录描述为可用 |
| Agent 后端差异 | 每个预设后端的版本、启动、控制、日志和恢复能力表 | 按真实能力显示，禁止模拟未提供的接口 |
| 打包与许可 | 三端依赖清单、源码对应关系、资源再分发检查 | 发行前解决，不以“整个项目开源”代替检查 |

选择版本时记录源码提交、编译选项和补丁。升级 LOK、MuPDF、GPUI 或 Markdown 解析与渲染库后运行相关回归测试。不要跟随默认分支自动升级正式构建。

## 24. 交付物与完成定义

### 24.1 工程交付物

交付八个应用的三端发行包、对应源码、构建与打包脚本、依赖与许可证清单、格式兼容清单、测试样本和测试报告。帮助内容包括打开保存、恢复、离线边界、账号授权、仓库操作及 Agent 后端限制。

不为满足交付清单制造独立文档系统。构建说明、已知限制和测试报告可放在仓库现有文档目录。需求以本文件为准，代码中的功能状态不得与文档相反。

### 24.2 首个正式版完成定义

八个应用可以独立安装和运行。本文功能表均有实现与测试。三端核心流程通过。文件保存、计算、发送和 Git 操作的结果可检查。所有应用遵守同一套界面规范，用户不需要学习不同的保存和错误处理方式。

离线安装不缺资源。没有强制 Ely 账号、云服务、在线 Office 服务或跨应用 Agent 依赖。发行包与公开源码匹配，已知兼容限制写明。未验证事项不能写成已完成能力。

## 25. 资料来源

核对日期：2026-10-01。来源用于确认接口、项目结构和许可条件，不证明 Ely 已完成接入。产品功能、默认设置与性能目标由本文定义。正式实现应记录所采用版本的固定提交和许可证，而不是只引用默认分支。

[S1] Ely GPUI Components，README，组件库使用方式、主题及许可证。  
`https://git.zacharyzhang.com/ZacharyZhang-NY/Ely-GPUI-Components/blob/main/README.md`

[S2] Ely GPUI Components，TASKS，组件分类与 host/prove 等状态定义。  
`https://git.zacharyzhang.com/ZacharyZhang-NY/Ely-GPUI-Components/blob/main/TASKS.md`

[S3] LibreOfficeKit 官方文档，C/C++ 接口、分块渲染和输入回调。  
`https://docs.libreoffice.org/libreofficekit.html`

[S4] LibreOfficeKit 官方头文件，实际接口及不稳定 API 条件。  
`https://raw.githubusercontent.com/LibreOffice/core/master/include/LibreOfficeKit/LibreOfficeKit.h`

[S5] LibreOffice 官方许可证说明。  
`https://www.libreoffice.org/licenses/`

[S6] MuPDF 官方 C Library 文档。  
`https://mupdf.readthedocs.io/en/latest/reference/c/index.html`

[S7] MuPDF 官方能力说明。  
`https://mupdf.com/`

[S8] MuPDF 官方许可证文档；本次读取页面版本为 1.28.5。  
`https://mupdf.readthedocs.io/en/1.28.5/license.html`

[S9] GNU Affero General Public License 第 3 版原文。  
`https://www.gnu.org/licenses/agpl-3.0.en.html`

[S10] MailCore 2 官方介绍，协议、API 与平台范围。  
`https://etpan.org/mailcore2.html`

[S11] Google，Gmail IMAP/POP/SMTP OAuth 2.0 与权限要求。  
`https://developers.google.com/workspace/gmail/imap/xoauth2-protocol`

[S12] Microsoft，IMAP/POP/SMTP OAuth 身份验证。  
`https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth`

[S13] Git 官方文档，git-status 与 porcelain 输出格式。  
`https://git-scm.com/docs/git-status`

[S14] markdown-rs 官方仓库，CommonMark、GFM 与扩展语法解析，许可证。  
`https://github.com/wooorm/markdown-rs`

[S15] RaTeX 官方仓库，LaTeX 公式排版与许可证。  
`https://github.com/erweixin/RaTeX`

[S16] mermaid-rs-renderer 官方仓库，Mermaid 图的 Rust 渲染与许可证。  
`https://github.com/1jehuang/mermaid-rs-renderer`

[S17] MarkText 官方仓库，编辑模式、格式能力与许可证。  
`https://github.com/marktext/marktext`

[S18] ColaMD 官方仓库及 package.json，本地文件行为、架构参考与依赖。  
`https://github.com/marswaveai/ColaMD`  
`https://github.com/marswaveai/ColaMD/blob/main/package.json`

[S19] Magpie 官方仓库，独立 Agent 工具定位参考。  
`https://github.com/yetone/magpie`

[S20] Agent Client Protocol，Session Setup 与能力协商。  
`https://agentclientprotocol.com/protocol/v1/session-setup`

[S21] Tesseract 官方 API 示例与本地 OCR 接入。  
`https://tesseract-ocr.github.io/tessdoc/APIExample.html`

[S23] Git 官方 COPYING 文件。  
`https://raw.githubusercontent.com/git/git/master/COPYING`

[S24] MailCore 2 官方 LICENSE 文件。  
`https://raw.githubusercontent.com/MailCore/mailcore2/master/LICENSE`