docs: 新增 Office AI 技术方案对比（源码级分析）[小糯]

.vitepress/config.mts

@@ -26,6 +26,7 @@ export default defineConfig({
           items: [
             { text: 'Aspose AI 产品能力分析', link: '/research/aspose-ai' },
             { text: 'OfficeCLI：为 AI Agent 而生的 Office 工具', link: '/research/officecli' },
+            { text: 'Office AI 技术方案对比', link: '/research/office-ai-tech-comparison' },
           ],
         },
       ],

research/index.md

@@ -6,3 +6,4 @@
 
 - [Aspose AI 产品能力分析](./aspose-ai) — 老牌文档处理公司的 AI 转型之路
 - [OfficeCLI：为 AI Agent 而生的 Office 工具](./officecli) — 开源命令行 Office 套件，AI-first 设计
+- [Office AI 技术方案对比](./office-ai-tech-comparison) — OfficeCLI vs Aspose 源码级技术分析

research/office-ai-tech-comparison.md

@@ -0,0 +1,370 @@
+# Office AI 技术方案对比：OfficeCLI vs Aspose
+
+> 调研时间：2026 年 5 月 | 作者：沙洲工作室
+>
+> 基于源码分析，非黑盒测评
+
+## 概述
+
+本文从源码层面对比两种"AI + Office"技术方案：
+
+| 项目 | OfficeCLI | Aspose.Words MCP Server |
+|------|-----------|------------------------|
+| 开源 | ✅ Apache 2.0 | ✅ MIT（Server 层），核心 SDK 闭源商业 |
+| 语言 | C#（.NET 10） | Python |
+| 代码量 | 137,827 行 | ~6,628 行 |
+| 核心依赖 | OpenXML SDK（开源） | Aspose.Words SDK（商业） |
+| AI 集成方式 | CLI 命令 + MCP Server | MCP Server |
+| 覆盖格式 | Word + Excel + PPT | 仅 Word |
+
+两者代表了截然不同的技术路线：**OfficeCLI 自己实现文档引擎**，**Aspose MCP Server 包装商业 SDK**。
+
+---
+
+## OfficeCLI 技术分析
+
+### 架构
+
+```
+┌─────────────────────────────────────────────┐
+│              AI Agent / 终端用户              │
+├──────────┬──────────────┬───────────────────┤
+│  CLI 命令  │  MCP Server  │  Resident 管道    │
+├──────────┴──────────────┴───────────────────┤
+│              CommandBuilder                  │
+│         （System.CommandLine 路由）            │
+├─────────────────────────────────────────────┤
+│            IDocumentHandler                  │
+│     ┌──────────┬──────────┬──────────┐      │
+│     │ WordHandler│ExcelHandler│PPTHandler│     │
+│     └──────────┴──────────┴──────────┘      │
+├─────────────────────────────────────────────┤
+│  Core（公式引擎、图表渲染、样式系统、SVG）     │
+├─────────────────────────────────────────────┤
+│        DocumentFormat.OpenXML SDK            │
+│              （微软开源）                      │
+└─────────────────────────────────────────────┘
+```
+
+### 核心设计决策
+
+**1. 基于 OpenXML SDK 自研引擎**
+
+OfficeCLI 没有依赖任何商业文档处理库，而是直接基于微软开源的 OpenXML SDK 构建了完整的文档操作引擎。这意味着：
+
+- ✅ 完全开源，无许可费
+- ✅ 可以深度定制每一层行为
+- ⚠️ 需要自己处理 Office 格式的所有复杂性
+- ⚠️ 13.8 万行代码的维护压力
+
+总共只有 3 个 NuGet 依赖：
+- `DocumentFormat.OpenXml 3.4.1` — 微软 OpenXML SDK
+- `OpenMcdf 3.1.3` — OLE 复合文档（处理旧格式 .doc/.xls）
+- `System.CommandLine 3.0.0-preview` — CLI 框架
+
+依赖极简，是一个非常刻意的设计选择。
+
+**2. 三层抽象架构**
+
+| 层级 | 命令 | 适合场景 |
+|------|------|---------|
+| L1 语义层 | `view`（text/annotated/outline/stats/issues） | AI 快速理解文档 |
+| L2 DOM 层 | `get/query/set/add/remove/move/swap` | 结构化编辑 |
+| L3 XML 层 | `raw/raw-set/add-part/validate` | 处理冷门功能 |
+
+这个分层非常聪明——AI Agent 日常用 L1+L2 就够了，遇到 L2 覆盖不到的功能可以降级到 L3 直接操作 XML。相当于给了 AI 一个"逃生舱"。
+
+**3. 驻留进程（Resident Mode）**
+
+通过**命名管道（Named Pipe）**实现常驻进程模式：
+
+- 文档只打开/解析一次，后续操作直接在内存中执行
+- 两种模式：自动启动（60 秒空闲退出）和显式 open/close（12 分钟空闲退出）
+- 并发安全，支持多个 AI Agent 同时操作不同文档
+
+这解决了 CLI 工具的固有性能问题——每次执行命令都要加载 .NET 运行时 + 解析文件，驻留模式把这个开销摊薄到近乎零。
+
+**4. 单二进制分发**
+
+通过 .NET 的 `PublishSingleFile + SelfContained + PublishTrimmed` 编译为单文件二进制：
+- 内嵌 .NET 运行时，无需用户安装任何依赖
+- Skills、Schemas、CSS/JS 资源全部作为 `EmbeddedResource` 打入二进制
+- 支持 8 个平台目标（macOS/Linux/Windows × ARM64/x64，Linux 还有 musl 版本）
+
+对 AI Agent 来说，`curl | sh` 一行安装，立即可用。
+
+**5. AI 技能系统**
+
+`skills/` 目录包含 12 个技能包，每个包含 `SKILL.md` + 参考文件：
+
+| 技能 | 用途 |
+|------|------|
+| officecli-docx | Word 文档操作指南 |
+| officecli-xlsx | Excel 操作指南 |
+| officecli-pptx | PPT 操作指南 |
+| morph-ppt | PPT Morph 动画 |
+| morph-ppt-3d | 3D Morph 效果 |
+| officecli-academic-paper | 学术论文模板 |
+| officecli-data-dashboard | 数据仪表板 |
+| officecli-financial-model | 财务模型 |
+| officecli-pitch-deck | 商业路演 PPT |
+| officecli-word-form | Word 表单 |
+
+`schemas/help/` 目录是 JSON Schema 驱动的帮助系统——运行时从内嵌资源加载，AI 可以查询任何命令的参数说明。
+
+### 代码质量观察
+
+**优点**：
+- 架构层次分明，`IDocumentHandler` 接口统一了三种格式的操作
+- 代码注释包含设计决策理由（不只是"做了什么"还有"为什么这样做"）
+- 错误处理完善——`SafeRun` 包装、友好的 XML 异常信息、JSON 错误信封
+- 跨平台细节考虑周到（Windows 句柄继承、macOS 代码签名、UTF-8 输出）
+
+**风险**：
+- **零测试覆盖**——13.8 万行代码没有自动化测试，这是最大技术债务
+- 使用 `System.CommandLine` 的 preview 版本
+- Excel 处理器复杂度极高，大量 partial class 散布在多个文件中
+- 单人开发，bus factor = 1
+
+---
+
+## Aspose.Words MCP Server 技术分析
+
+### 架构
+
+```
+┌─────────────────────────────────────────────┐
+│              AI Agent（Claude 等）            │
+├─────────────────────────────────────────────┤
+│         FastMCP（MCP 协议框架）               │
+├─────────────────────────────────────────────┤
+│      mcp_server.py（70+ 工具注册）            │
+│         ↓ tool_xxx() 辅助函数                │
+├─────────────────────────────────────────────┤
+│              core/ 模块                      │
+│  ┌────────┬────────┬────────┬────────┐      │
+│  │content │tables  │layout  │export  │      │
+│  │reading │styles  │links   │notes   │      │
+│  │io      │comments│watermarks│protection│   │
+│  └────────┴────────┴────────┴────────┘      │
+├─────────────────────────────────────────────┤
+│          Aspose.Words SDK（商业）             │
+│         （闭源，需许可证或评估模式）             │
+└─────────────────────────────────────────────┘
+```
+
+### 核心设计决策
+
+**1. 薄包装层设计**
+
+整个 MCP Server 本质上是 Aspose.Words SDK 的一层薄包装。核心逻辑不到 7000 行 Python，因为重活全部交给了 Aspose.Words 商业库。
+
+三层调用链：
+- MCP 工具函数（`@mcp.tool` 装饰器注册）
+- `tool_xxx()` 辅助函数（可脱离 MCP 独立调用，方便测试）
+- `core/` 模块（实际调用 Aspose.Words API）
+
+这种分离设计意味着换掉 MCP 协议层（比如改成 REST API），只需要改最外层。
+
+**2. 文档存储模型**
+
+使用文件系统 + 内存映射：
+- 每个文档用 UUID 标识，保存为 `.docx` 文件在 `./data` 目录
+- `DocumentStore` 是线程安全的内存字典，维护 doc_id → name 映射
+- 支持多文档同时打开和操作
+
+这是一个简单但实用的设计——不需要数据库，重启后扫描 data 目录即可恢复状态。
+
+**3. 依赖商业 SDK**
+
+核心依赖 `aspose-words>=26.4.0`（商业库）。这决定了：
+- ✅ 文档处理能力经过 20 年打磨，格式兼容性极强
+- ✅ 代码量小，维护负担低
+- ⚠️ 无许可证时有评估限制（水印、页数限制）
+- ⚠️ 只覆盖 Word 格式（Excel 有独立的 Aspose.Cells MCP Server）
+
+**4. 安全考虑**
+
+- 正则表达式查找替换有安全验证，防止 ReDoS 攻击
+- 文档保护功能支持加密和编辑范围限制
+- 有 `AGENTS.md` 规范 AI Agent 的编码行为
+
+### 70+ 工具清单
+
+MCP Server 注册了约 70 个工具，覆盖 Word 文档的几乎所有操作：
+
+| 类别 | 工具数 | 能力 |
+|------|--------|------|
+| 文档管理 | ~8 | 创建、复制、删除、合并、列表、导入 |
+| 内容编辑 | ~10 | 插入文本/标题/段落/HTML/Markdown、查找替换 |
+| 表格 | ~8 | 创建、合并单元格、着色、对齐、列宽 |
+| 页面布局 | ~8 | 边距、方向、纸张、分栏、分节符、页眉页脚 |
+| 样式格式 | ~6 | 自定义样式、文本格式化、列表 |
+| 链接注释 | ~8 | 书签、超链接、批注、脚注、尾注 |
+| 水印保护 | ~5 | 文字/图片水印、文档保护 |
+| 导出读取 | ~10 | 多格式导出、页面渲染、段落读取、统计 |
+| 属性 | ~4 | 标题、作者、关键词等文档元数据 |
+
+### 代码质量观察
+
+**优点**：
+- 分层清晰，MCP 层 / 工具层 / 核心层职责分明
+- 有测试覆盖（10 个测试文件，含单元测试和功能测试）
+- 使用 Ruff 进行代码格式化和 lint
+- 版本号与 Aspose.Words SDK 对齐（26.4.0）
+
+**不足**：
+- `mcp_server.py` 单文件 1758 行，70+ 个工具注册在同一个函数里，可读性差
+- 每个工具都是对 `tool_xxx()` 的简单包装，存在大量重复模式
+- 仅覆盖 Word——Excel 和 PPT 需要独立的 MCP Server
+
+### Aspose 的 AI 开源生态
+
+| 仓库 | 说明 |
+|------|------|
+| aspose-words/Aspose.Words-MCP-Server | Word MCP Server（Python） |
+| aspose-cells/Aspose.Cells-MCP | Excel MCP Server（TypeScript） |
+| aspose-words/agentic-net-examples | AI 验证的 C# 示例 |
+| aspose-cells/agentic-net-examples | AI 验证的 C# 示例 |
+| aspose-words/Aspose.Words-for-MarkItDown | 文档转 Markdown 插件 |
+| aspose-words/Aspose.Words-for-Docling | 文档转 DoclingDocument 插件 |
+
+模式很统一：每个产品线 = MCP Server + Agentic 示例 + 生态插件。
+
+---
+
+## 核心差异对比
+
+### 技术栈对比
+
+| 维度 | OfficeCLI | Aspose MCP Server |
+|------|-----------|-------------------|
+| 语言 | C# (.NET 10) | Python |
+| 代码量 | 137,827 行 | ~6,628 行 |
+| 文档引擎 | 自研（基于 OpenXML SDK） | 商业 SDK（Aspose.Words） |
+| 外部依赖 | 3 个 NuGet 包 | 2 个 pip 包 |
+| 分发方式 | 单二进制，零依赖 | pip install，需 Python 环境 |
+| 测试 | 无 | 有（10 个测试文件） |
+| 格式覆盖 | docx + xlsx + pptx | 仅 docx |
+| AI 接口 | CLI + MCP | 仅 MCP |
+| 许可证 | Apache 2.0（完全免费） | MIT（Server），商业（SDK） |
+
+### 架构哲学对比
+
+| 维度 | OfficeCLI | Aspose MCP Server |
+|------|-----------|-------------------|
+| 引擎策略 | 自研 13.8 万行 | 包装商业 SDK |
+| 设计目标 | AI Agent 的通用 Office 工具 | Aspose 生态的 AI 入口 |
+| 性能优化 | 驻留进程 + 批处理 + 实时预览 | 文件级操作，无常驻优化 |
+| 抽象层次 | 三层（语义/DOM/XML） | 单层（70+ 扁平工具） |
+| 扩展性 | 通过 L3 XML 层"逃生" | 受限于 SDK 暴露的能力 |
+| 生态集成 | SKILL.md 技能系统 | MCP 协议标准 |
+
+### 能力覆盖对比
+
+| 能力 | OfficeCLI | Aspose MCP |
+|------|-----------|------------|
+| Word 基础编辑 | ✅ | ✅ |
+| Word 高级功能（表单、内容控件、OLE） | ✅ | 部分 |
+| Excel 操作 | ✅（150+ 函数、透视表、图表） | ❌ |
+| PPT 操作 | ✅（Morph、3D、动画） | ❌ |
+| 文档格式转换 | 有限（同格式内操作） | ✅（docx→pdf/png/html） |
+| 内置 AI 能力 | ❌ | ❌（Server 层无，SDK 有） |
+| i18n / RTL | ✅ | ✅（SDK 层） |
+| 实时预览 | ✅（Watch Mode + HTTP 服务器） | ❌ |
+
+---
+
+## 适用场景分析
+
+### OfficeCLI 最适合的场景
+
+1. **AI 编辑器集成**（Claude Code、Cursor、Windsurf）
+   - 原因：CLI 是最自然的集成方式，无需配置 MCP 客户端
+   - SKILL.md 让 AI 零学习成本上手
+
+2. **需要同时操作 Word + Excel + PPT**
+   - 原因：一个工具覆盖三种格式，Aspose 需要三个独立 Server
+
+3. **对成本敏感的团队**
+   - 原因：完全免费开源，Aspose SDK 起价 $1,199
+
+4. **需要交互式文档编辑**
+   - 原因：Watch Mode 实时预览 + Resident Mode 高性能，适合"边做边看"
+
+5. **PPT 制作场景**
+   - 原因：PPT 是 OfficeCLI 的强项（Morph、3D、动画），Aspose MCP 不覆盖
+
+### Aspose MCP Server 最适合的场景
+
+1. **企业级 Word 文档自动化**
+   - 原因：Aspose.Words 20 年积累的格式兼容性远超 OpenXML SDK 直接操作
+
+2. **需要格式转换**（docx → pdf / png / html）
+   - 原因：Aspose 的渲染引擎是核心优势，OfficeCLI 不覆盖
+
+3. **已有 Aspose 许可证的团队**
+   - 原因：MCP Server 是免费的，只需要已有的 SDK 许可证
+
+4. **对文档正确性要求极高**
+   - 原因：商业 SDK 经过大量企业验证，边缘情况覆盖更全
+
+5. **需要内置 AI 能力**（摘要、翻译、语法检查）
+   - 原因：通过 Aspose.Words SDK 可直接调用 LLM 处理文档
+
+---
+
+## 风险评估
+
+### OfficeCLI 的风险
+
+| 风险 | 严重程度 | 说明 |
+|------|---------|------|
+| 零测试覆盖 | 🔴 高 | 13.8 万行代码无自动化测试，格式兼容性靠手动验证 |
+| 单人开发 | 🔴 高 | 核心开发者 1 人，bus factor = 1 |
+| Office 格式复杂性 | 🟡 中 | OpenXML 规范极其庞大，边缘情况无穷，小团队难以穷举 |
+| .NET preview 依赖 | 🟡 中 | System.CommandLine 仍是预览版 |
+| 商业模式缺失 | 🟡 中 | 纯开源无收入，长期可持续性存疑 |
+
+### Aspose MCP Server 的风险
+
+| 风险 | 严重程度 | 说明 |
+|------|---------|------|
+| 商业 SDK 锁定 | 🟡 中 | 核心能力依赖闭源商业库，价格由 Aspose 决定 |
+| 仅覆盖 Word | 🟡 中 | Excel/PPT 需要独立 Server，集成复杂度高 |
+| 代码组织 | 🟢 低 | 1758 行单文件可读性差，但功能正确 |
+| MCP 生态成熟度 | 🟡 中 | MCP 协议仍在早期，标准可能变化 |
+
+---
+
+## 总结
+
+### 两种路线的本质差异
+
+```
+OfficeCLI 路线：
+  自研引擎 → 掌控一切 → 代码量大 → 维护压力大 → 但完全自由
+
+Aspose 路线：
+  包装 SDK → 站在巨人肩上 → 代码量小 → 受制于人 → 但质量有保障
+```
+
+这是一个经典的"自研 vs 集成"权衡：
+
+- OfficeCLI 选择了**自由但艰难**的路——13.8 万行代码、零测试、单人维护，但不依赖任何商业组件
+- Aspose 选择了**省力但受限**的路——6600 行代码、有测试、成熟 SDK，但被锁定在商业生态中
+
+### 给技术选型的建议
+
+- **如果你是 AI Agent 开发者，想快速给 Agent 加上 Office 能力** → OfficeCLI。一行安装、CLI 直接调用、免费开源
+- **如果你是企业，需要在生产环境中处理大量 Word 文档** → Aspose。格式兼容性、稳定性、技术支持都更可靠
+- **如果你需要做 PPT 或 Excel** → OfficeCLI 是目前唯一选择（Aspose Cells MCP Server 存在但较新）
+- **如果你需要 docx → pdf 转换** → Aspose。OfficeCLI 不做渲染
+
+### 行业趋势判断
+
+OfficeCLI 代表的"CLI-first AI 工具"范式正在兴起——工具不再为人类设计 GUI，而是为 AI Agent 设计命令行接口。这个趋势如果持续，**未来每个生产力软件都需要一个"AI Agent 接口"**，无论是 CLI、MCP 还是其他协议。
+
+Aspose 代表的"传统软件 + AI 层"范式则更稳健——不颠覆已有架构，在成熟产品上叠加 AI 能力。风险低但想象空间有限。
+
+两条路线未必会合一。更可能的结局是：OfficeCLI 类工具成为 AI Agent 的"默认手"（轻量、快速、免费），Aspose 类产品在需要高保真渲染和企业级兼容性时被调用。