R7 文档处理 blazar-source/dsh-r7-office

dsh-r7-office

R7-Office（Р7-Офис）文档处理插件，同时是 DeepSeek Harness 的 Model Context Protocol（MCP）服务器。

让 AI 智能体检查、读取、创建、排版、编辑和转换 DOCX、XLSX、PPTX 和 PDF 文档——走标准 OOXML 操作，加上你已经装好的 R7 转换器——不用模拟鼠标和键盘。

⚠️ 非官方社区项目

这是独立维护的社区项目。它与 АО «Р7»（R7-Office）和 DeepSeek 没有隶属关系，也未获其认可、赞助或支持，不是 R7-Office 或 DeepSeek 的官方产品。

R7-Office 和 Р7-Офис 是各自所有者的商标，此处仅用于说明本软件与什么互操作。

本仓库不含任何 R7-Office 代码、二进制文件或其他资产。它检测你机器上已安装的 R7-Office，并在本地驱动它。你需要自行安装 R7-Office 并取得授权。

俄语文档： README.ru.md

它能做什么

- 保留格式的编辑——替换和修改会保留原有 XML 样式、字体、颜色和编号层级。文档中未改动的部分逐字节保留。
- 四种格式全支持——DOCX（标题、段落、列表、表格、分页符）、XLSX（工作表、区域、值、公式）、PPTX（幻灯片、标题、文本框）、PDF（通过本地 R7 x2t 引擎转换）。
- 内置校验——r7_validate 在改动前后检查包完整性。
- 两种运行方式——作为原生 DeepSeek Harness 插件，或作为独立 MCP 服务器，通过 stdio 对接任何 MCP 客户端。
- 实时桌面桥接——可选功能，通过回环 WebSocket 驱动你在 R7-Office Desktop 中打开的文档。

架构

DeepSeek Harness ──► dsh-r7-office plugin ──┐
├──► DOCX / XLSX / PPTX / PDF
Any MCP client ────► MCP server (stdio) ────┤
│
R7-Office Desktop ◄── desktop bridge ◄──────┘

详见 docs/architecture.md；设计决策见 docs/decisions/。

环境要求

| Node.js | 运行插件和 MCP 服务器需要 >= 20.0.0。运行完整测试套件需要 >= 22.0.0（桥接和 CDP 客户端使用全局 WebSocket，Node 22 起才有）。 |
| 运行时依赖 | 无——插件没有任何运行时依赖 |
| R7-Office Desktop | 可选。 r7_convert（→ PDF/HTML）、对特殊文档的 inspect 保真度，以及整个桌面桥接都依赖它。没有它，纯 OOXML 工具照样能用。 |
| Platform | Windows、Linux 和 macOS。R7 自动检测覆盖三者的标准安装位置；实时桌面桥接仅在 Windows 上验证过（见已知限制）。 |

从零开始干净安装

以下步骤假设目录为空，机器上装有 Node.js 20+。

1. Get the code
git clone https://github.com/blazar-source/dsh-r7-office.git
cd dsh-r7-office

2. Install the optional dev dependencies (test-only: the MCP client SDK)
npm install

3. Verify the checkout — no R7-Office required for this step
npm test

npm test 是可移植测试套件，除 Node 外不需要任何东西：单元测试、OOXML 往返回归测试、文件端到端工作流、安全策略测试，以及外部 MCP 客户端冒烟套件。测试对象是已安装产品的那些测试——R7 自带模板、x2t 转换器、桌面编辑器——会自行跳过并给出原因，而不是失败，所以一台从未见过 R7-Office 的机器也能跑出绿色结果，并看到跳过计数。

$ npm test
tests 469
pass 390
fail 0
skipped 79

依赖 R7 的测试只有在装了 R7-Office 的地方才有意义，所以它们有单独的命令；这条命令没装就直接拒绝运行，而不是跳过一切然后报告成功：

Requires an installed R7-Office. Runs the whole suite with nothing skipped,
then drives the live desktop editor over CDP and saves a document for real.
npm run test:r7

Just the suite, or just the live editor, if you want them separately:
npm run test:r7 -- --suite
npm run test:r7 -- --live

想看看可移植套件在没有 R7 的机器上表现如何，即使你已经装了 R7，也可以设 R7_OFFICE_DISABLED=1——检测会报告未安装，这正是 CI 运行时的条件。

然后验证你实际打算用的集成：

R7-Office file pipeline (author → edit → validate → PDF). Skips if R7 is absent.
npm run test:live

DeepSeek Harness plugin activation. Boots a fresh Harness and asserts the
28 r7_* tools reached the tool registry.
npm run test:harness -- --profile web

作为 DeepSeek Harness 插件

把包目录作为 bundle 安装：

in the DeepSeek Harness UI: plugin_manager → install_bundle
target: /absolute/path/to/dsh-r7-office

或者用对应你配置档的命令行等价命令：

dsh plugin --profile <profile> add /absolute/path/to/dsh-r7-office

确认它已激活——新启动的 Harness 会打印：

[r7-office] зарегистрировано инструментов: 27 (r7_inspect, r7_read, ...); desktop bridge port=7888, developerMode=false

注意。 这一行要么通过 install_bundle 添加，要么手动写入配置档里的 cordis.patch.yml —— 两者只能选一个。两条条目用同一个 r7-office id，这一行就无法激活。

插件还会往智能体系统提示词里注册一小段用法说明，这样智能体就知道有哪些工具，以及推荐的 inspect → read → edit → validate → convert 顺序。

作为独立 MCP 服务器

MCP 服务器在 stdio 上使用按行分隔的 JSON-RPC 2.0。

{
"mcpServers": {
"r7-office": {
"command": "node",
"args": ["/absolute/path/to/dsh-r7-office/src/mcp/cli.js"]
}
}
}

把这段放进你客户端的配置文件（例如 claude_desktop_config.json 或 .cursor/mcp.json）。任何 stdio MCP 客户端都能用；互操作性在 npm test 里对着官方 @modelcontextprotocol/client SDK 验证过。

你也可以手动运行：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/mcp/cli.js

工具

| 工具 | 用途 |
| r7_inspect | 文档大纲：标题、段落、表格、工作表、幻灯片、元数据 |
| r7_read | 结构化文本、Markdown 视图，或电子表格单元格区域 |
| r7_create | 新建 DOCX / XLSX / PPTX。除非 overwrite: true，否则拒绝覆盖已有文件；每个 sheets[] 条目和名称都会照办 |
| r7_edit | 按索引替换、重设样式或删除某个段落 |
| r7_replace | 查找并替换文本，保留 run 格式 |
| r7_insert | 插入段落、标题、项目符号或分页符 |
| r7_table | 创建、查看或更新表格与单元格，包括合并、边框、底纹和列宽 |
| r7_docx_formatting | 读取每个段落、run 和表格单元格的规范化格式：样式、字体、字号、颜色、对齐、缩进、间距、行距、列表 |
| r7_docx_sections | 读取和设置页面大小、方向、页边距、分栏、分页符和分节符 |
| r7_docx_header_footer | 列出、读取、创建或重命名页眉和页脚；页码字段会保留 |
| r7_docx_image | 按指定尺寸插入 PNG/JPEG/GIF，保持宽高比 |
| r7_docx_hyperlink | 列出、插入、重命名或删除超链接及其关系 |
| r7_sheet_read | 读取工作表或区域（如 A1:D10）的值、公式或规范化格式 |
| r7_sheet_write | 按工作表名称或索引写入单元格或二维矩阵；日期存为真正的日期序列值 |
| r7_sheet_format | 设置单元格或区域的格式：字体、背景、边框、对齐、自动换行、数字格式（整数、小数、货币、百分比、日期、日期时间、自定义）、合并、列宽和行高 |
| r7_sheet_add | 往已有工作簿里添加工作表；其他工作表不受影响 |
| r7_sheet_formula | 插入或更新公式 |
| r7_slide_read | 把幻灯片读成规范化结构：每个对象的 id、类型、几何、文本、字体、填充、描边、对齐和段落 |
| r7_slide_create | 新建演示文稿，或追加一张幻灯片，基于演示文稿自带的版式，不改动已有幻灯片 |
| r7_slide_format | 就地调整某个已有对象的样式或位置：字体、几何、填充、边框、对齐、列表、间距、文本 |
| r7_slide_edit | 复制、移动、重排或删除幻灯片 |
| r7_slide_object | 添加或删除对象：形状、文本框或 PNG/JPEG 图片 |
| r7_convert | 通过 R7 x2t 引擎转换（PDF、HTML、TXT、DOCX、XLSX、PPTX）。PDF 转换使用 R7 生成的字体列表，修复畸形的 ToUnicode 计数，并且拒绝返回无法提取文本的 PDF，而不是悄悄输出一份空白 PDF。XLSX 默认导出每个工作表（allSheets） |
| r7_validate | 检查包完整性与 XML 健康状况 |
| r7_pdf_inspect | 报告 PDF 究竟真的包含文本，还是在没有字体的情况下生成：逐字体的嵌入标记与 ToUnicode/Cyrillic 映射计数、文本字形、空填充操作符，并给出 text / outlined / mixed 判定。repair: true 就地修复畸形的 ToUnicode 计数 |
| r7_desktop_status | 桌面桥接连接状态与生效的安全模式 |
| r7_desktop_selection | 读取或替换已打开编辑器中的选区 |
| r7_desktop_exec | 运行安全的编辑器命令，或在开发者模式下运行原始 DocScript |

演示文稿

演示文稿基于它已有的版式构建。添加幻灯片时，会注册幻灯片部件、它的关系部件、[Content_Types].xml 覆盖项、 条目以及演示文稿关系；版式、母版、主题、备注和所有已有幻灯片都保留原始字节。写到幻灯片上的占位符仍是占位符，因此继续从母版继承几何与排版。

读取时会替你解析这层继承关系：r7_slide_read 报告的是标题幻灯片 60 pt 的版式标题，而不是演示文稿 18 pt 的默认值；报告的是占位符从版式或母版继承的位置，而不是 null。

import { PptxEngine } from 'dsh-r7-office/r7'

const pptx = new PptxEngine()

// 1. Read: geometry, text, font, fill, stroke, alignment, paragraphs.
const before = await pptx.readSlide('Deck.pptx', 1)
const title = before.slide.objects.find(o => o.placeholder?.type === 'title')
const body = before.slide.objects.find(o => o.placeholder?.type === 'body')
console.log(title.x, title.width, title.font.family, title.font.size)

// 2. Add a slide on one of the deck's own layouts.
const added = await pptx.addSlide('Deck.pptx', {
layoutType: 'obj',
title: 'Ключевые выводы',
paragraphs: [{ text: 'Выручка +18%', bullet: true }]
})

// 3. Restyle one object. Everything not named keeps its original bytes.
await pptx.formatObject('Deck.pptx', {
slideIndex: added.slideIndex,
objectId: title.id,
font: { family: 'Georgia', size: 32, bold: true, color: '#1F6FEB' },
alignment: 'center'
})
// 4. 添加对象：填充、边框、文本、字体、几何形状——一次调用全搞定。
await pptx.addShape('Deck.pptx', {
slideIndex: added.slideIndex,
shape: 'rounded-rectangle', // rectangle, ellipse, line, arrow, star, …
x: '2cm', y: '10cm', width: '9.4cm', height: '8.2cm',
fill: '#1F6FEB', fillTransparency: 0.1,
line: '#0B3D91', lineWidth: 2, // lineWidth is in points
text: 'KPI 98%',
font: { family: 'Arial', size: 24, bold: true, color: '#FFFFFF' },
alignment: 'center', verticalAnchor: 'middle'
})

// 5. 插入并替换图片。
const image = await pptx.addImage('Deck.pptx', {
slideIndex: added.slideIndex, imagePath: 'chart.png', x: '4cm', y: '4cm', width: '24cm'
})
await pptx.formatObject('Deck.pptx', {
slideIndex: added.slideIndex, objectId: image.objectId, imagePath: 'chart-v2.png'
})

// 6. 结构操作，再导出一份 PDF。
await pptx.duplicateSlide('Deck.pptx', 1)
await pptx.moveSlide('Deck.pptx', 2, 0)
await pptx.deleteSlide('Deck.pptx', 4)
console.log((await pptx.validate('Deck.pptx')).valid)
await pptx.toPdf('Deck.pptx', 'Deck.pdf')

跑一遍完整的验收演示文稿： bash
node examples/pptx-acceptance.js # writes into os.tmpdir()/r7-acceptance
node examples/pptx-acceptance.js ./out # or wherever you like

度量单位。 裸数字就是 EMU（r7_slide_read 返回的单位），所以读出来的值可以原样调整、原样写回。"2cm"、"1in"、"30px"、"24pt" 也都支持。lineWidth 是例外：小于 100 的数字按磅（pt）处理，因为对没抱着 DrawingML 规范看的人来说，「border: 1.5」就是 1.5 pt。

颜色。 支持 #RRGGBB、#AARRGGBB，透明度则用单独的 0..1 选项。字体的 transparency 和填充的 fillTransparency 故意分开，这样半透明的标题颜色不会把下面的形状也弄成透明的。

形状。 rectangle、rounded-rectangle、ellipse、circle、line、arrow（以及 arrow-left/up/down/left-right）、triangle、diamond、pentagon、hexagon、octagon、star、chevron、plus、cloud、heart、cylinder、cube、donut、pie、parallelogram、trapezoid——或者任何 DrawingML 预设名称。pptx.shapeCatalog() 会列出全部。

典型智能体工作流

「把 Report.docx 拿过来，更新第 3 节，保留格式，加一张汇总表，再存成 PDF。」
text
r7_inspect → r7_read → r7_replace (keeps formatting) → r7_table
→ r7_validate → r7_convert

自己跑一遍： bash
node examples/report-scenario.js

作为库使用： javascript
import { DocxEngine, R7Adapter } from 'dsh-r7-office/r7'

const docx = new DocxEngine()
const adapter = new R7Adapter()

await docx.replaceText('Report.docx', 'draft text', 'approved text', {
outputPath: 'Report_v2.docx' // the original is never overwritten by default
})

await docx.table('Report_v2.docx', {
action: 'create',
rows: [['Objective', 'Timeline', 'Owner'], ['Deploy R7', 'Q2', 'IT']]
})
javascript
console.log((await docx.validate('Report_v2.docx')).valid)

await adapter.convert('Report_v2.docx', 'Report_v2.pdf')

安全

r7_desktop_exec 能在用户打开的编辑器里执行代码。因此，原始 DocScript 默认禁用；生产环境只运行一份固定的安全白名单，里面的命令都由参数驱动。只有刻意为之，才启用原始执行： yaml
- id: r7-office
name: 'dsh-r7-office'
config:
developerMode: true # or export DSH_R7_DEVELOPER_MODE=1

r7_desktop_status 始终报告当前生效的模式。桌面桥接只绑定 127.0.0.1。

完整的威胁模型，以及漏洞上报方式，见 SECURITY.md。

已知限制

- 演示文稿：构建版式或母版不在支持范围内。 幻灯片创建时，用的是文稿里已有的版式；如果文稿一个版式都没有，就得到通用的标题/正文组合。
- 演示文稿：SmartArt 和图表只保留，不创建。 读取器会报告它们（type: "chart"、type: "graphicFrame"），它们背后的每个部件在任何编辑中都保持字节级不变，但引擎无法创建。手写的 SmartArt 框架只是一个 dgm:relIds 引用，R7 自己的渲染器会解引用它背后的图表部件。
- 演示文稿：替换图片时，如果格式变了或媒体是共享的，会存入新的媒体部件，旧部件可能就此无人引用。所有仍指向它的地方照常工作。
- 演示文稿：主题颜色读回来是 token（scheme:accent1），因为主题解析之前不存在字面十六进制值。写入只接受字面值。
- 实时桌面桥接：Windows 已验证。 桥接插件本身与平台无关，但自动化实时测试通过 CEF DevTools 协议驱动 R7-Office Desktop，只在 Windows 构建（Editors-2026.3.1）上验证过。其他平台应该能用，但未测试。
- PDF 需要 R7。 r7_convert 的 x2t 转换器需要本地安装 R7。其他功能都不依赖它。
- 格式覆盖范围。 读取和编辑覆盖上面列出的常见 OOXML 范围。图表、嵌入对象、SmartArt 和修订记录只保留，无法通过这些工具编辑。
- DOCX：v0.1.0 未实现。 替换或调整已有图片的尺寸；指定表格样式（tblStyle）；修改超链接的目标（改标题，或删除后插入）；为分节不同页眉提供便捷封装（两者都能读取和保留，r7_docx_header_footer 也接受 first/even —— 对 first 还要用 titlePg 调用 r7_docx_sections）。搜索不感知修订：r7_replace 扫描原始 <w:t>，所以修订插入里的文字可编辑，段落索引会把删除内容里的段落也算进去 —— <w:delText> 永远不会被匹配。
- DOCX：批注、修订记录、脚注、尾注、目录，公式和嵌入对象都会保留，绝不编辑。 有测试断言：经过普通编辑后，它们仍然存在，且每一部分字节完全相同。
- DOCX 转 PDF：斜体副标题上可能出现一条细横线。 样式为 Subtitle 的段落（斜体、居中、灰色）在 r7_convert 之后可能渲染出一条淡淡的横线。文档里没有删除线、下划线或段落边框——w:strike、w:u、w:pBdr 全都不存在，同样的样式用在 R7 自带模板上，经同一个转换器渲染却干干净净——所以这条线是 PDF 转换过程中引入的，无法从文档侧修正。它只是外观问题：文字本身正确，提取也正常。量化下来，那段文字区域的墨迹大约多出 5 %。
- PDF 渲染靠肉眼验证，不靠文本提取。 PDF 可能带着正确的文字、正确的页数，validate() 也干净通过，实际画出来的却是错字形或一整块实心色块。scripts/visual-acceptance.py 用两个独立引擎渲染输出，再与 LibreOffice 渲染的源文件比对；只要改动转换路径上的任何东西，就跑一遍。
- XLSX：v0.1.0 未实现。 单元格样式仅限于 r7_sheet_format 列出的那些属性；条件格式、数据验证、图表、数据透视表和定义名称都会保留，但不可编辑。
- PPTX：SmartArt、图表、动画和切换效果都会保留，绝不新建。 引擎无法创建 SmartArt（手写的框架只是一个 dgm:relIds 引用），编辑其内容也不在范围内。
- 不支持并发编辑。 文件工具操作的是静止状态的文档。如果文档正被用户打开，请用桌面桥接；文件工具假定文件没有被其他进程锁定。

开发 bash
npm test # the portable suite; needs only Node, R7 tests skip
npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:r7 # requires R7-Office: full suite + the live desktop editor
npm run test:live # just the live desktop bridge (needs R7-Office)
npm run test:harness # boots a fresh DeepSeek Harness
npm run inspect:r7 # CDP probe of a running R7 Desktop

见 docs/development.md 和 docs/roadmap.md。

许可证

MIT —— 见 LICENSE。

R7-Office 是 АО «Р7» 所有的专有软件。本项目不重新分发它的任何部分。