内容
# animus-document-engine
**MCP（stdio）服务**，用于渲染、解析、转换和编辑 Office 文档 — **Excel（.xlsx）、PowerPoint（.pptx）、Word（.docx）** — 基于结构化的 JSON **规范**。它不涉及身份信息且无状态：从不接触主题、S3 或用户。[animus-launchapp](https://github.com/launchapp-dev/animus-launchapp) 门户负责协调（存储 + 范围 + 主题）；该引擎是可重用的渲染核心。
是 **REQUIREMENT-053** 的一部分 — 文档作为主题。
## 为什么需要规范
**规范是真实来源**。AI 编写规范（而非原始 OOXML）；确定性渲染器将其转换为真实文件。编辑 = 修改规范并重新渲染 — 无损、可审查和可差异化。二进制有效载荷作为 base64 跨 MCP 边界传输。
## 工具
| 工具 | 输入 | 输出 |
|------|-----|-----|
| `render_document` | `format`, `spec` | base64 OOXML 字节 |
| `parse_document` | `format`, `bytes_base64` | 规范（**xlsx 仅在 v1**） |
| `apply_edits` | `format`, `spec`, `ops[]` | 编辑后、重新验证的规范 |
| `convert_document` | `bytes_base64`, `to` | base64 转换字节（例如 `pdf`） |
| `preview_document` | `bytes_base64`, `kind` (`pdf`\|`png`), `page` | base64 PDF 或 PNG 缩略图 |
`convert_document` / `preview_document` 使用 **LibreOffice 编译为 WebAssembly** (`@matbee/libreoffice-converter`) — 无需本地 `soffice`。约 112 MB WASM 存在于此服务中，永不存在于门户镜像中。
## 规范形状（v1）
```jsonc
// xlsx
{ "sheets": [ { "name": "Revenue",
"columns": [ { "header": "Month" }, { "header": "USD" } ],
"rows": [ ["Jul", 1200], ["Aug", 1500] ] } ] }
// pptx
{ "title": "Kickoff",
"slides": [ { "title": "Agenda", "bullets": ["Scope", "Timeline"] },
{ "title": "Next", "body": "…", "notes": "speaker note" } ] }
// docx
{ "title": "Spec",
"blocks": [ { "type": "heading", "level": 1, "text": "Overview" },
{ "type": "paragraph", "text": "…" },
{ "type": "bullets", "items": ["a", "b"] },
{ "type": "table", "rows": [["a","b"],["c","d"]] } ] }
```
`apply_edits` 操作：`{op:"set",path,value}`, `{op:"append",target,value}`, `{op:"remove",target,index}`, `{op:"replace",value}` (`target` = `sheets`\|`slides`\|`blocks`).
## 运行
```bash
npm install
npm run build
node dist/index.js # MCP stdio 服务器
```
将其连接到 Animus 工作流阶段（或任何 MCP 客户端）作为 stdio 服务器：
```jsonc
{ "mcpServers": { "document-engine": { "command": "node", "args": ["dist/index.js"] } } }
```
## 开发
```bash
npm run dev # tsx 监视（stdio 服务器）
npm run typecheck # tsc --noEmit
npm run smoke # 渲染所有 3 种格式 + xlsx 解析/编辑往返
tsx scripts/mcp-smoke.ts # 启动构建的服务器，通过 MCP 调用工具
```
## 范围（v1）& 路线图
- **生成** 所有三种格式 — 完善（pptxgenjs / docx / exceljs）。
- **解析** — xlsx（数据 + 标头）。**pptx/docx 原位解析** 被推迟到未来的 Python 工作程序（python-pptx / python-docx 是唯一忠实地循环遍历任意幻灯片/文档的库）；引擎错误地大声响起，而不是静默地丢弃内容。
- **转换/预览** — 通过 LibreOffice-WASM。
