概述

Adeu 是一个专为 Microsoft Word 文档设计的 AI 原生虚拟 DOM（Virtual DOM），它充当 docx ↔ LLM 翻译器，让大型语言模型能够安全地读取和编辑 Word 文件，同时保留复杂的 OpenXML 格式和样式结构。

资料来源：README.md:1

传统的 python-docx 等库在从头生成文档方面表现出色，但在非破坏性修订（non-destructive redlining）方面存在明显不足。Adeu 通过将 .docx 文件转换为令牌高效的 Markdown 表示（使用 CriticMarkup 语法）来解决这一问题，使 AI 智能体能完全专注于文档语义，而无需在 OpenXML 结构上耗费精力。

核心价值主张

• 双向抽象层：在 Word 复杂 XML 结构与 LLM 可读的 Markdown 之间建立桥梁
• 非破坏性修订：所有编辑以原生 Word Track Changes（修订模式）呈现
• MIT 许可证：开源友好，适配法律科技等广泛场景
• 多平台支持：提供 Python 和 TypeScript 两种实现，以及 MCP、LangChain、n8n 等集成方式

资料来源：AI_CONTEXT.md:1-10

核心概念

CriticMarkup 语法

Adeu 使用 CriticMarkup 语法在 Markdown 中表示文档变更：

资料来源：python/src/adeu/cli.py:1-50

操作类型

Adeu 支持四种核心操作类型：

资料来源：langchain/langchain_adeu/apply_changes.py:1-30

安装方式

方式一：uvx 快速运行（推荐）

uvx adeu --version

uvx 是 uv 的工具运行模式，无需全局安装即可运行 adeu。

方式二：pip 安装

pip install adeu

方式三：扩展集成

资料来源：python/skills/adeu-redlining/SKILL.md:1-30

基本工作流程

graph TD
    A[读取 DOCX] --> B[查看文档内容]
    B --> C[分析跟踪修订]
    C --> D[制定编辑计划]
    D --> E[生成变更 JSON]
    E --> F[应用变更]
    F --> G[输出修订后文档]
    
    B --> B1[全页模式<br/>mode=full]
    B --> B2[大纲模式<br/>mode=outline]
    B --> B3[附录模式<br/>mode=appendix]
    B --> B4[清洁视图<br/>clean_view=True]

核心功能

1. 读取文档

Adeu 可以将 DOCX 文件转换为 LLM 友好的 Markdown 格式，支持多种查看模式。

#### MCP 工具调用

read_docx(
    file_path="/path/to/contract.docx",
    mode="full",        # full | outline | appendix
    page=1,            # 页码
    clean_view=False   # True=显示最终文本, False=显示修订
)

#### CLI 命令

# 基本读取
adeu read input.docx

# 输出清洁视图（无修订标记）
adeu read input.docx --clean

# 大纲模式
adeu read input.docx --outline

# 附录模式
adeu read input.docx --appendix

#### 查看模式说明

资料来源：python/src/adeu/mcp_components/_response_builders.py:1-80

2. 应用编辑

#### 修改文本（最常用）

[
  {
    "type": "modify",
    "target_text": "laws of Scotland",
    "new_text": "laws of England and Wales",
    "comment": "根据客户要求修改管辖法律"
  }
]

#### 接受/拒绝修订

[
  {"type": "accept", "target_id": "Chg:12"},
  {"type": "reject", "target_id": "Chg:15"}
]

#### 回复批注

[
  {"type": "reply", "target_id": "Com:5", "text": "已与客户确认接受此修改"}
]

资料来源：langchain/langchain_adeu/apply_changes.py:30-60

3. CLI 命令详解

#### apply - 应用变更

adeu apply <input.docx> <edits.json> -o <output.docx>

参数：

#### markup - 生成批评Markup

adeu markup <input> <edits.json> -o output.md

参数：

#### sanitize - 文档脱敏

adeu sanitize input1.docx input2.docx --outdir ./sanitized

功能：剥离元数据、接受所有修订、应用只读锁。

资料来源：python/src/adeu/cli.py:50-150

分页系统

Adeu 使用无状态分页器将投影后的 Markdown 文档分割为虚拟页面。

graph LR
    A[Markdown 文档] --> B[分页器]
    B --> C[PAGE_TARGET_CHARS = 19000 字符]
    B --> D[尊重 CriticMarkup 边界]
    B --> E[保持表格完整性]
    B --> F[保留脚注关联]
    F --> G[分页结果]

分页规则

• 每页目标字符数：19,000（PAGE_TARGET_CHARS）
• CriticMarkup 语法块不会被分割
• 表格保持完整性
• 脚注与引用保持关联
• 附录内容可附加到每页末尾

资料来源：python/src/adeu/pagination.py:1-40

与 AI Agent 集成

LangChain 工具

from langchain_adeu import AdeuReadDocx, AdeuApplyChanges

# 读取文档
read_tool = AdeuReadDocx()
result = read_tool.invoke({
    "file_path": "/path/to/contract.docx",
    "mode": "full",
    "page": 1
})

# 应用变更
apply_tool = AdeuApplyChanges()
result = apply_tool.invoke({
    "original_docx_path": "/path/to/contract.docx",
    "changes": [{"type": "modify", "target_text": "...", "new_text": "..."}]
})

MCP 协议

Adeu 提供 MCP 服务器，支持通过 Model Context Protocol 与 AI 模型集成：

{
  "name": "adeu",
  "description": "Word document redlining and review",
  "tools": ["read_docx", "process_batch"]
}

原子批量验证

重要提示：所有变更都针对原始文档状态评估，不要在一个批次内链接依赖编辑。

graph TD
    A[接收变更批次] --> B[预验证全部变更]
    B --> C{所有变更有效?}
    C -->|是| D[应用变更到文档]
    C -->|否| E[拒绝整个批次]
    D --> F[输出修订后文档]
    E --> G[返回错误信息]

资料来源：python/src/adeu/mcp_components/tools/document.py:1-50

常见问题

Q: 如何处理多个 Chg ID 对应单个逻辑编辑？

问题描述：当单个修改操作替换一段包含多种格式的文本时，引擎可能在一个气泡中生成多个 [Chg:N] ID。

示例：将 "laws of Scotland" 替换为 "England and Wales" 可能产生 [Chg:4], [Chg:5], [Chg:6] 三个 ID。

这属于已知的 XML runs 粒度问题。在接受/拒绝时需要指定正确的 ID。

资料来源：issue #16

Q: 如何在非 AGPL 工作流中使用可视化？

当前的可视化方案采用 AGPL 许可。对于 MIT 许可的集成方式，可以考虑：

• 使用 MCP 工具在终端查看
• 通过 n8n 节点在自动化流程中处理
• 使用 LangChain 工具集成到自定义应用

资料来源：issue #1

下一步

集成架构概述

Adeu 采用分层集成策略，核心引擎专注于 OOXML 操作，上层通过标准化的接口适配不同的 AI 框架和工作流平台。

graph TB
    subgraph "核心层 Core"
        A[Adeu RedlineEngine] --> B[python-docx + diff-match-patch]
        B --> C[OOXML XML Injection]
    end
    
    subgraph "协议适配层 Protocol Adapters"
        D[MCP Server<br/>Model Context Protocol]
        E[LangChain Tools]
        F[n8n Nodes]
        G[Claude Desktop Plugin]
        H[Gemini CLI Extension]
    end
    
    subgraph "应用层 Applications"
        I[AI Agent Workflows]
        J[No-Code Automation]
        K[Desktop Integration]
        L[CLI Tools]
    end
    
    A --> D
    A --> E
    A --> F
    A --> G
    A --> H
    D --> I
    E --> I
    F --> J
    G --> K
    H --> L

资料来源：node/packages/n8n-nodes-adeu/README.md:1-15

MCP 服务器集成

Model Context Protocol (MCP) 是 adeu 的主要集成协议，提供文档读取、编辑和审核的标准化接口。

工具列表

读取模式

graph LR
    A[read_docx] --> B{Mode 参数}
    B -->|full| C[分页正文内容]
    B -->|outline| D[标题大纲地图]
    B -->|appendix| E[结构附录<br/>定义条款/交叉引用]
    
    C --> F[支持页面导航]
    D --> G[快速定位长文档]
    E --> H[编辑前必读]

资料来源：python/src/adeu/mcp_components/tools/document.py:1-50

处理操作类型

资料来源：python/src/adeu/mcp_components/tools/document.py:45-80

LangChain 集成

Adeu 提供完整的 LangChain 工具封装，支持在 LangGraph 工作流中构建文档处理管道。

可用工具

from langchain_adeu import AdeuReadDocx, AdeuApplyChanges, AdeuToolkit

# 独立工具
read_tool = AdeuReadDocx()
edit_tool = AdeuApplyChanges()

# 工具包 (推荐)
toolkit = AdeuToolkit()
tools = toolkit.get_tools()

工具包组件

资料来源：langchain/langchain_adeu/toolkit.py:1-50

批处理原子性

⚠️ 重要提示：所有变更操作基于原始文档状态评估。请勿在单个批处理中链接依赖编辑。

正确流程：

1. 先执行重命名操作（如 X → Y）
2. 再发送第二个批处理修改 Y

错误示例：

// ❌ 错误：第二次编辑的 target_text 在原始文档中不存在
[
  {"type": "modify", "target_text": "X", "new_text": "Y"},
  {"type": "modify", "target_text": "Y", "new_text": "Z"}  // Y 不存在于原始文档
]

资料来源：langchain/langchain_adeu/apply_changes.py:1-30

n8n 工作流节点

Adeu 提供官方的 n8n 节点，可在无代码环境中构建 AI 驱动的文档处理流程。

节点操作

资料来源：node/packages/n8n-nodes-adeu/README.md:30-60

Clean View 切换

原子批处理验证

Adeu 在修改文档前会预验证整个编辑数组。即使只有一个编辑无效（如目标文本未找到、匹配歧义），引擎也会安全拒绝整个批处理，防止产生部分或损坏的文档状态。

资料来源：node/packages/n8n-nodes-adeu/README.md:50-55

Claude 桌面集成

Adeu 提供 Claude Desktop 插件，实现与 Claude AI 的本地集成。

安装命令

# 使用 npm 安装
npm install -g @adeu/mcp-server

# 或使用 uvx 直接运行
uvx adeu --version

功能覆盖

• 文档读取与分页导航
• 追踪变更的红线编辑
• 评论添加与回复
• 多轮合同协商测试

资料来源：python/skills/adeu-redlining/SKILL.md:1-30

Gemini CLI 扩展

Adeu v1.6.8 修复了 Gemini CLI 扩展的归档结构问题。

安装方法

gemini extensions install github.com/dealfluence/adeu

修复历史

资料来源：Release v1.6.8

CLI 命令行工具

Adeu 提供完整的命令行界面，支持脚本化和批处理场景。

子命令概览

常用命令示例

# 读取文档
uvx adeu read contract.docx --page 1

# 应用编辑
uvx adeu apply input.docx edits.json -o output.docx

# 生成红线标记
uvx adeu markup input.docx edits.json -o redline.md --index

# 清理敏感信息
uvx adeu sanitize contract.docx -o clean.docx --keep-marks

资料来源：python/src/adeu/cli.py:1-100

Adeu Redlining Skill

专业的红线与审核技能，封装为 Claude 可调用的标准格式。

核心能力

1. Extract（提取）：高保真读取文本，保留评论和结构标题
2. Diff（差异）：比较两个 DOCX 文件变更
3. Edit（编辑）：应用搜索替换修改，产生追踪变更
4. Review（审核）：接受/拒绝变更或回复评论

执行模型

graph LR
    A[User Request] --> B[Adeu Skill]
    B --> C[uvx adeu CLI]
    C --> D[RedlineEngine]
    D --> E[OOXML Manipulation]
    E --> F[Track Changes XML]

资料来源：python/skills/adeu-redlining/SKILL.md:1-50

工作流示例：AI Agent 文档处理

以下是一个典型的 AI Agent 工作流配置：

graph TD
    A[Start: DOCX Input] --> B[Extract Markdown]
    B --> C{cleanView?}
    C -->|false| D[Show Tracked Changes]
    C -->|true| E[Clean Baseline]
    D --> F[AI Analysis]
    E --> F
    F --> G[Generate Edit JSON]
    G --> H[Validate Edits]
    H --> I{Valid?}
    I -->|No| J[Report Errors]
    I -->|Yes| K[Apply to DOCX]
    K --> L[Output Redlined DOCX]
    J --> A

资料来源：node/packages/n8n-nodes-adeu/examples/AI_Agent_workflow.json

社区集成请求

活跃的功能请求

已知限制

• Issue #16：单个逻辑编辑可能产生多个 [Chg:N] ID（如替换包含格式的文本时）
• Issue #11：Claude Opus 4.7 测试者反馈建议继续使用 {++}{--}{>>} 标准语法

资料来源：GitHub Issues #1, #16, #19, #20

许可证兼容性

MIT 许可证使 adeu 成为法律科技领域广泛采用的理想选择，尤其适合需要避免 AGPL 强制开源传播的场景。

资料来源：python/skills/adeu-redlining/SKILL.md:1-5

下一步

• 快速入门：安装指南
• MCP 配置：MCP 服务器设置
• 工作流示例：LangChain 教程

核心设计理念

Adeu 将 Word 文档视为可编辑的结构化对象，而非静态文件。这种设计使得：

1. 高保真读取：保留批注、跟踪更改和结构化标题
2. 原子化编辑：所有修改作为原生 OOXML w:ins（插入）和 w:del（删除）应用
3. LLM 友好输出：将文档投影为 Markdown，配合 CriticMarkup 语法显示变更

graph LR
    A[.docx 文件] --> B[Ingest 解析层]
    B --> C[Redline Engine]
    C --> D[Markdown 投影]
    D --> E[LLM / Agent]
    E --> F[DocumentChange JSON]
    F --> C
    F --> G[更新后的 .docx]

模块架构

Adeu 采用多包 monorepo 结构，主要分为以下几个核心模块：

Python 核心引擎

核心引擎位于 python/src/adeu/redline/engine.py，负责：

• 接收 DocumentChange 操作数组
• 验证所有编辑对原始文档状态的有效性
• 原子化应用变更（全部成功或全部失败）
• 生成跟踪更改 ID（Chg:N 格式）

graph TD
    A[接收 DocumentChange 数组] --> B{批量预验证}
    B -->|全部有效| C[应用 w:ins/w:del XML]
    B -->|存在无效| D[拒绝整个批次]
    C --> E[生成变更报告]
    E --> F[输出更新的 .docx]

Ingest 解析层

ingest.py 模块负责将 DOCX 文件转换为 LLM 可读的 Markdown 格式：

from adeu.ingest import _extract_text_from_doc

result = _extract_text_from_doc(
    doc, 
    return_paragraph_offsets=True  # 启用快速大纲路径
)

关键功能：

• CriticMarkup 投影：将跟踪更改转为 {++insertion++}、{--deletion--}、{==highlighted==}、{>>comment<<}
• 结构附录提取：定义术语、锚点和交叉引用目标
• 段落偏移映射：支持快速大纲生成（见 Issue #16 关于 Chg ID 的讨论）

资料来源：python/src/adeu/ingest.py

数据流架构

读取流程（Read Pipeline）

sequenceDiagram
    participant LLM as LLM/Agent
    participant MCP as MCP Server
    participant IR as Ingest 模块
    participant Pag as Pagination
    participant Doc as DOCX 文件

    LLM->>MCP: read_docx(file_path, mode='full')
    MCP->>IR: _extract_text_from_doc()
    IR->>Doc: 解析 document.xml
    Doc-->>IR: OOXML 结构
    IR-->>MCP: 原始 Markdown + 结构元数据
    MCP->>Pag: paginate(body, structural_appendix="")
    Pag-->>MCP: 分页结果
    MCP-->>LLM: ToolResult(markdown, metadata)

写入流程（Write Pipeline）

sequenceDiagram
    participant LLM as LLM/Agent
    participant MCP as MCP Server
    participant Eng as Redline Engine
    participant Doc as DOCX 文件

    LLM->>MCP: process_batch(changes=[...])
    MCP->>Eng: apply_changes(changes)
    Eng->>Eng: 预验证所有操作
    Eng->>Doc: 注入 w:ins/w:del XML
    Doc-->>Eng: 更新后的 document.xml
    Eng-->>MCP: 应用报告
    MCP-->>LLM: ToolResult(stats)

MCP 工具架构

Adeu 通过 MCP（Model Context Protocol）暴露四个核心工具：

资料来源：python/src/adeu/mcp_components/tools/document.py

响应构建器

python/src/adeu/mcp_components/_response_builders.py 中的响应构建函数负责生成 LLM 可读的格式：

def build_paginated_response(text: str, page: int, file_path: str) -> ToolResult:
    """将投影的 Markdown 分割为页面并返回请求的页面"""
    body, appendix = split_structural_appendix(text)
    result = paginate(body, structural_appendix="")
    # ... 构建分页响应

支持三种响应模式：

分页系统

pagination.py 实现了无状态分页器，将投影后的 Markdown 正文分割为虚拟页面：

PAGE_TARGET_CHARS = 19_000  # 每页目标字符数

分页策略：

• 尊重 CriticMarkup 边界
• 保持表格完整性
• 保护脚注部分
• 结构附录追加到每页末尾

资料来源：python/src/adeu/pagination.py

CriticMarkup 语法

Adeu 使用四种 CriticMarkup 标记表示文档变更：

社区反馈表明，{++insertion++}{--deletion--}{>>bubble<<} 是最常用的编辑对形状，三种不同的括号风格确保了视觉清晰度。资料来源：issues#11

多平台集成

LangChain 集成

langchain/langchain_adeu/ 包提供了 LangChain 工具封装：

from langchain_adeu import AdeuReadDocx, AdeuApplyChanges

read_tool = AdeuReadDocx()
apply_tool = AdeuApplyChanges()

n8n 集成

node/packages/n8n-nodes-adeu/ 提供了 n8n 工作流节点支持：

• Extract Markdown：将 DOCX 投影为 Markdown
• Apply Edits：应用 JSON 变更数组
• Generate Diff：生成逐字级别差异

资料来源：node/packages/n8n-nodes-adeu/README.md

MCP Server

node/packages/mcp-server/ 提供 MCP 协议支持：

import { startMcpServer } from '@adeu/mcp-server';
startMcpServer();

CLI 接口

python/src/adeu/cli.py 提供了命令行接口：

uvx adeu --version
uvx adeu read <file.docx>
uvx adeu apply <input.docx> edits.json -o <output.docx>
uvx adeu markup <input.md> edits.json -o <output.md>
uvx adeu sanitize <input.docx> -o <output.docx>

资料来源：python/src/adeu/cli.py

变更类型定义

# MODIFY (搜索替换 — 最常用)
{'type': 'modify', 'target_text': '精确匹配的文本', 
 'new_text': '替换文本', 'comment': '可选的变更理由'}

# ACCEPT / REJECT (完成或撤销跟踪更改)
{'type': 'accept', 'target_id': 'Chg:12'}
{'type': 'reject', 'target_id': 'Chg:12'}

# REPLY (回复批注)
{'type': 'reply', 'target_id': 'Com:5', 'text': '回复内容'}

# INSERT_ROW / DELETE_ROW (表格结构编辑)
{'type': 'insert_row', 'target_text': '相邻行单元格', 
 'position': 'above'|'below', 'cells': ['col1', 'col2', ...]}

所有变更根据原始文档状态进行评估，不可在单个批次内链接依赖编辑（如将 X 重命名为 Y，然后修改 Y）。

已知架构限制

Issue #16：单次修改产生多个 Chg ID

当单个 modify 操作替换一段文本时，引擎会在同一气泡中发出多个 [Chg:N] ID（每个底层 XML run 一个，而非每个逻辑编辑一个）。例如，将"laws of Scotland"替换为"England and Wales"产生了三个 ID（[Chg:4], [Chg:5], [Chg:6]）。

这是因为 OOXML 格式将粗体等格式信息存储在独立的 run 元素中，而非文本节点中。资料来源：issues#16

Issue #20：条款验证钩子（计划中）

当前 README 将红线定义为捕获格式和结构错误。下一个差距是验证每个提议的条款在管辖区域内的法律有效性。资料来源：issues#20

技术栈概览

相关文档

• 快速开始指南 — 安装和基础使用
• API 参考 — 完整的 API 文档
• CLI 参考 — 命令行工具详解
• MCP 工具 — MCP 协议工具说明
• LangChain 集成 — LangChain 工具使用

概述

Adeu Python 引擎是文档协作编辑的核心处理单元，其设计理念是充当 DOCX 文件的"虚拟 DOM"。引擎通过文本代理（Markdown/CriticMarkup）使 LLM 能够编辑复杂 XML 结构的 Word 文档，同时保持文件的完整性和格式保真度。

核心能力：

• 将 DOCX 文档转换为 LLM 可读的 Markdown 表示
• 支持 CriticMarkup 标准进行精确的插入、删除、高亮和评论
• 通过 w:ins/w:del XML 原子补丁实现追踪修订（Track Changes）
• 多轮对话式文档编辑支持

资料来源：AI_CONTEXT.md

架构设计

核心设计原则

graph TD
    subgraph "输入层"
        A[DOCX 文件] --> B[python-docx 解析]
    end
    
    subgraph "处理层"
        B --> C[ingest.py<br/>文本提取]
        C --> D[mapper.py<br/>Span 映射]
        D --> E[RedlineEngine<br/>变更计算]
    end
    
    subgraph "输出层"
        E --> F[XML 原子补丁]
        E --> G[CriticMarkup 标注]
        F --> H[Word Track Changes]
    end
    
    subgraph "接口层"
        G --> I[MCP Server]
        G --> J[CLI 工具]
        G --> K[LangChain 集成]
    end

四阶段处理管线

资料来源：AI_CONTEXT.md

文本提取与格式化

ingest.py 核心功能

ingest.py 负责将 DOCX 文档转换为结构化文本：

# 核心提取流程
def _extract_text_from_doc(
    doc: "DocumentObject",
    clean_view: bool = False,
    return_paragraph_offsets: bool = False,
) -> str

关键特性：

• 换行隔离原则：Markdown 格式化标记（、_ 等）禁止包裹换行符**
• 正确：Line 1\nLine 2
• 错误：Line 1\nLine 2
• 原因：避免破坏 Markdown 解析器和文本分段逻辑

• 多级列表处理：
• 读取时：w:ilvl 直接映射为标准 Markdown 缩进（每级 4 空格）
• 写入时：解析前导空格除以 4 来注入 <w:ilvl> 到 <w:numPr>

资料来源：python/src/adeu/ingest.py

clean_view 模式

def extract_text_from_stream(
    stream: BytesIO,
    clean_view: bool = False,
) -> str

追踪修订引擎

RedlineEngine 架构

graph LR
    A[原始 DOCX] --> B[process_batch<br/>批量处理]
    B --> C[change_calculator<br/>变更计算]
    C --> D[change_applier<br/>XML 应用]
    D --> E[save_to_stream<br/>输出流]
    
    C --> F[插入 w:ins]
    C --> G[删除 w:del]
    C --> H[评论 w:comment]

核心 API

class RedlineEngine:
    def __init__(self, docx_source: BytesIO, author: str = "Adeu"):
        """初始化引擎，绑定源文档和修订作者"""
    
    def process_batch(self, changes: List[DocumentChange]) -> None:
        """批量处理变更请求"""
    
    def save_to_stream(self) -> BytesIO:
        """序列化修改后的文档到字节流"""

变更类型支持：

资料来源：python/src/adeu/redline/engine.py

已知限制：单次修改产生多个 Chg ID

问题描述：当单个 modify 操作替换包含多个 XML runs 的文本时，引擎会为每个底层 XML run 生成独立的 [Chg:N] ID。

示例：

替换 "laws of **Scotland**" 为 "England and Wales"

输出：生成三个 ID [Chg:4], [Chg:5], [Chg:6]，而非预期的单一逻辑 ID。

这是因为 OOXML 中粗体文本由多个 <w:r> runs 组成，引擎按 XML 结构而非逻辑编辑粒度分配 ID。

资料来源：Issue #16

Mapper 文本跨度映射

mapper.py 功能

mapper.py 构建文档文本与 python-docx 内部对象的线性索引：

def build_paragraph_map(
    doc: "DocumentObject",
) -> List[SpanMapping]

SpanMapping 结构：

此映射使引擎能够精确定位原始 DOCX 结构中的任意文本片段，从而正确计算 XML 补丁位置。

资料来源：python/src/adeu/redline/mapper.py

评论系统

comments.py 组件

评论系统支持在文档中添加、回复评论气泡：

@dataclass
class CommentData:
    id: str           # Com:N 格式 ID
    author: str       # 评论作者
    text: str         # 评论内容
    parent_id: str    # 父评论 ID（用于回复链）
    range_start: int  # 评论范围起点
    range_end: int    # 评论范围终点

评论输出格式：

{==target text==}{>>This is a comment<<}

资料来源：python/src/adeu/redline/comments.py

分页系统

pagination.py 设计

无状态分页器，将投影后的 Markdown 文档拆分为虚拟页面：

PAGE_TARGET_CHARS = 19_000  # 每页目标字符数

@dataclass
class PageInfo:
    page: int
    total_pages: int
    has_next: bool
    page_content: str

分页保护规则：

1. CriticMarkup 边界保护：不拆分 {++...++}、{--...--}、{==...==}、{>>...<<} 对
2. 表格完整性保护：整表不跨页
3. 脚注区域保护：脚注段保持连续

CriticMarkup 标记定义：

_CRITIC_TOKENS: Dict[str, str] = {
    "{++": "++}",    # 插入
    "{--": "--}",    # 删除
    "{==": "==}",    # 高亮
    "{>>": "<<}",    # 评论气泡
}

资料来源：python/src/adeu/pagination.py

结构附录处理

文档包含结构附录（Structural Appendix），包含：

• 定义术语（Defined Terms）
• 命名锚点（Named Anchors）
• 交叉引用目标（Cross-reference Targets）
• 诊断信息（Diagnostics）

APPENDIX_MARKER = "<!-- READONLY_BOUNDARY_START -->"

def split_structural_appendix(markdown: str) -> Tuple[str, str]:
    """拆分投影 Markdown 为 (body, appendix)"""

分页行为：

• 正文分页，不包含附录
• 附录单独分页，使用专属 banner
• 每页末尾可包含指向附录的指针

资料来源：python/src/adeu/pagination.py

响应构建器

_response_builders.py 模块

MCP 工具的响应构建组件，提供三种输出模式：

def build_paginated_response(
    text: str,
    page: int,
    file_path: str,
) -> ToolResult

def build_appendix_response(
    text: str,
    page: int,
    file_path: str,
) -> ToolResult

def build_outline_response(
    doc: "DocumentObject",
    projected_text: str,
    file_path: str,
    outline_max_level: int = 2,
    outline_verbose: bool = False,
) -> ToolResult

输出模式对比：

页面 Banner/Footer 格式：

> **Page N of M** — call `read_docx` with `mode='outline'` for a heading map...

概述

@adeu/core 是 adeu 项目的纯 TypeScript 实现，采用零依赖设计，允许 AI 智能体和大型语言模型安全地读取和编辑 Microsoft Word (.docx) 文件。它将复杂的 OpenXML 转换为令牌高效的 CriticMarkup（Markdown 格式），并将 AI 文本编辑应用为原生 Word 修订和评论。

该引擎是 Adeu Python SDK 的 TypeScript 移植版本，使用 @xmldom/xmldom 和 jszip 实现，完全运行在 Node.js 环境中。资料来源：node/packages/core/README.md:1-15

架构概览

TypeScript 引擎采用模块化设计，核心组件包括文档对象模型、差异引擎、标记处理和分页系统。

graph TD
    A[DOCX 文件] --> B[DocumentObject]
    B --> C[RedlineEngine]
    B --> D[extractTextFromBuffer]
    C --> E[CriticMarkup 标记]
    D --> E
    E --> F[LLM 读取/编辑]
    F --> G[apply_edits_to_markdown]
    G --> C
    C --> H[最终化 DOCX]

核心模块

导出 API

@adeu/core 通过 index.ts 导出以下核心接口：

资料来源：node/packages/core/src/index.ts

DocumentObject 文档对象

DocumentObject 是 DOCX 文件的内存表示，负责加载和解析 OpenXML 结构。

import { DocumentObject, RedlineEngine, extractTextFromBuffer } from "@adeu/core";

async function main() {
  const buffer = readFileSync("contract.docx");

  // 1. 提取为 CriticMarkup 供 LLM 读取
  const markdown = await extractTextFromBuffer(buffer, false);
  console.log(markdown); 

  // 2. 加载文档 DOM
  const doc = await DocumentObject.load(buffer);
  const engine = new RedlineEngine(doc, "AI Reviewer");

资料来源：node/packages/core/README.md:25-35

RedlineEngine 修订引擎

RedlineEngine 是核心的差异应用引擎，负责：

• 将 LLM 生成的编辑操作转换为 Word 原生的 tracked changes
• 管理变更 ID 分配
• 处理批量的搜索替换操作

资料来源：node/packages/core/src/engine.ts

CriticMarkup 语法

引擎使用 CriticMarkup 作为中间表示格式：

社区反馈表明 {++insertion++}{--deletion--}{>>bubble<<} 是标准的编辑对形状，清晰无歧义。

资料来源：node/packages/mcp-server/src/tools/document.ts

MCP 服务器集成

工具定义

MCP 服务器将 TypeScript 引擎封装为 MCP 工具：

#### read_docx 工具

Reads a DOCX file. Returns text with inline CriticMarkup for Tracked Changes and Comments: {++inserted++}, {--deleted--}, {==highlighted==}{>>comment<<}. Set clean_view=True for the finalized 'Accepted' text without markup.

模式选项：

• full（默认）：分页的正文内容，使用 page=N 导航
• outline：仅标题地图，适合大型文档规划定向阅读
• appendix：术语定义、锚点和交叉引用目标

资料来源：node/packages/mcp-server/src/index.ts、python/src/adeu/mcp_components/tools/document.py

#### process_batch 工具

Applies a batch of edits and review actions to a DOCX.

All changes evaluate against the ORIGINAL document state — do not chain dependent edits within one batch (e.g. rename X to Y, then modify Y). Apply the rename first, then send a second batch.

支持的操作类型：

资料来源：node/packages/mcp-server/src/index.ts、langchain/langchain_adeu/apply_changes.py

响应构建器

MCP 服务器使用响应构建器将文档内容转换为 LLM 可读的格式：

// node/packages/mcp-server/src/response-builders.ts
export function build_paginated_response(text: string, page: number, file_path: string): ToolResult {
  const body, appendix = split_structural_appendix(text);
  const result = paginate(body, structural_appendix="");
  
  const banner = _build_page_banner(selected.page, selected.total_pages);
  const footer = _build_page_footer(selected.page, selected.total_pages, selected.has_next);
  const appendix_pointer = _build_appendix_pointer(file_path, has_appendix);
  
  return ToolResult({
    content: [{ type: 'text', text: llm_content }],
    structured_content: { markdown, title, file_path }
  });
}

资料来源：node/packages/mcp-server/src/response-builders.ts

分页系统

分页配置

CriticMarkup 边界保护

分页系统会保护 CriticMarkup 标记不被拆分：

# python/src/adeu/pagination.py
_CRITIC_TOKENS: Dict[str, str] = {
    "{++": "++}",
    "{--": "--}",
    "{==": "==}",
    "{>>": "<<}",
}

分页逻辑会：

1. 尊重 CriticMarkup 边界完整性
2. 保持表格结构不被拆分
3. 将脚注区域保持在同一页

资料来源：python/src/adeu/pagination.py

用户界面资源

MCP 服务器提供交互式 HTML UI 资源：

// node/packages/mcp-server/src/shared.ts
export const MARKDOWN_UI_URI = "ui://adeu/markdown-ui";
export const EMAIL_UI_URI = "ui://adeu/email-ui";

资料来源：node/packages/mcp-server/src/shared.ts

与 Python SDK 的差异

TypeScript 引擎是 Python SDK 的完整移植，核心功能保持一致：

已知问题

多 Chg ID 问题

当单个修改操作替换一段文本时，引擎会在同一气泡中发出多个 [Chg:N] ID——每个底层 XML run 一个，而非每个逻辑编辑一个。例如，将 "laws of Scotland" 替换为 "England and Wales" 会产生三个 ID（[Chg:4]、[Chg:5]、[Chg:6]），因为 Scotland 被加粗处理。

资料来源：社区 issue #16

安装使用

npm install @adeu/core

快速示例：

import { readFileSync, writeFileSync } from "fs";
import { DocumentObject, RedlineEngine, extractTextFromBuffer } from "@adeu/core";

const buffer = readFileSync("contract.docx");
const markdown = await extractTextFromBuffer(buffer, false);
const doc = await DocumentObject.load(buffer);
const engine = new RedlineEngine(doc, "AI Reviewer");

资料来源：node/packages/core/README.md

构建配置

TypeScript 引擎使用 tsup 进行打包：

// node/packages/core/tsup.config.ts
export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  splitting: false,
  sourcemap: true,
  clean: true,
});

同时支持 CommonJS 和 ES Module 两种格式输出。

概述

Adeu 是一个跨平台的 DOCX 红线处理引擎，同时提供 Python 和 Node.js 两种实现。跨平台一致性是指两种实现能够在相同输入下产生语义等价输出的能力，确保用户无论使用哪个平台都能获得一致的结果。

Adeu 的核心架构基于"后端 XML 注入"模式，使用 python-docx + diff-match-patch 处理红线和格式化，而非依赖重量级前端引擎。这种设计使得核心逻辑可以在两种平台上复用，MIT 许可证也使其适合在法律技术领域广泛采用。

架构设计

双实现架构

graph TB
    subgraph Python平台
        P_INGEST[adeu.ingest]
        P_ENGINE[RedlineEngine]
        P_BUILDERS[_response_builders.py]
        P_MCP[MCP组件]
    end
    
    subgraph Node.js平台
        N_CORE[@adeu/core]
        N_SERVER[mcp-server]
        N_BUILDERS[response-builders.ts]
        N_RESOURCES[resources]
    end
    
    subgraph 共享资源
        SHARED[shared/cross_platform_tests]
        GOLDEN[golden_*.xml/md]
    end
    
    P_INGEST --> P_ENGINE
    P_ENGINE --> P_BUILDERS
    P_BUILDERS --> P_MCP
    
    N_CORE --> N_BUILDERS
    N_BUILDERS --> N_SERVER
    N_SERVER --> N_RESOURCES
    
    SHARED --> GOLDEN

核心一致性模块

响应构建器一致性

响应结构设计

两种实现都遵循相同的响应结构，确保 MCP 客户端和 LangChain 工具能够统一处理：

// Node.js 响应格式
interface ToolResult {
  content: [{ type: 'text', text: string }]
}

// Python 响应格式 (FastMCP)
ToolResult(
  content=llm_content,
  structured_content={
    "markdown": ui_markdown,
    "title": Path(file_path).name,
    "file_path": str(Path(file_path).resolve()),
  }
)

资料来源：node/packages/mcp-server/src/response-builders.ts:1-50

分页逻辑一致性

分页是跨平台一致性的关键环节。Python 和 Node.js 都实现了相同的分页算法：

分页核心常量：

# python/src/adeu/pagination.py
PAGE_TARGET_CHARS = 19_000
APPENDIX_MARKER = "<!-- READONLY_BOUNDARY_START -->"

资料来源：python/src/adeu/pagination.py:1-30

CriticMarkup 标记处理

分页器需要保护 CriticMarkup 边界的完整性：

# CriticMarkup 开闭标记映射
_CRITIC_TOKENS: Dict[str, str] = {
    "{++": "++}",
    "{--": "--}",
    "{==": "==}",
    "{>>": "<<}",
}

Node.js 实现使用相同的标记定义，确保分页不会破坏配对标记。

附录分离机制

结构化附录设计

Adeu 将文档的结构化元数据（定义术语、锚点、交叉引用）与正文分离，单独作为附录返回：

graph LR
    A[原始DOCX] --> B[投影为Markdown]
    B --> C[split_structural_appendix]
    C --> D[body]
    C --> E[appendix]
    D --> F[分页正文]
    E --> G[分页附录]

附录内容类型

附录分离逻辑（Python）：

# 附录标记在投影阶段注入
APPENDIX_MARKER = "<!-- READONLY_BOUNDARY_START -->"

def split_structural_appendix(text: str) -> Tuple[str, str]:
    """将附录与正文分离"""
    if APPENDIX_MARKER in text:
        body, appendix = text.split(APPENDIX_MARKER, 1)
        return body, appendix
    return text, ""

资料来源：python/src/adeu/mcp_components/_response_builders.py:60-100

跨平台测试框架

测试目录结构

shared/cross_platform_tests/
├── 01_basic_text_modification/
│   ├── test.json           # 测试用例定义
│   ├── golden_abstract.xml  # OOXML抽象层期望输出
│   └── golden_raw.md       # Markdown投影期望输出
└── 02_...                  # 更多测试用例

测试用例格式

{
  "name": "基本文本修改",
  "description": "验证单个文本替换操作",
  "input_docx": "input.docx",
  "edits": [
    {
      "type": "modify",
      "target_text": "原文",
      "new_text": "修改后",
      "comment": "修改原因"
    }
  ],
  "expected_abstract": "golden_abstract.xml",
  "expected_markdown": "golden_raw.md"
}

资料来源：shared/cross_platform_tests/01_basic_text_modification/test.json

一致性验证流程

graph TD
    A[加载测试用例] --> B[Python执行编辑]
    A --> C[Node.js执行编辑]
    B --> D[生成Python输出]
    C --> E[生成Node.js输出]
    D --> F[对比golden文件]
    E --> F
    F --> G{通过?}
    G -->|是| H[测试通过]
    G -->|否| I[输出差异报告]

已知限制

多重 Chg ID 问题

问题描述： 当单个修改操作替换一段文本时，引擎会在同一气泡中发出多个 [Chg:N] ID，而非每个逻辑编辑对应一个 ID。

示例： 将 "laws of Scotland" 替换为 "England and Wales" 时，产生了三个 ID（[Chg:4], [Chg:5], [Chg:6]），因为底层 XML 运行生成了多个标记。

<!-- 问题根源：XML run 分割 -->
<w:del w:id="4"...>laws of </w:del>
<w:del w:id="5"...><w:rPr><w:b/>...</w:rPr>Scotland</w:del>
<w:ins w:id="6"...>England and Wales</w:ins>

社区讨论： 此问题在 GitHub Issue #16 中被报告，是跨平台一致性的重要关注点，因为 Python 和 Node.js 需要统一处理这种边界情况。

工具响应模式

read_docx 工具一致性

两种平台提供的 read_docx 工具具有相同的功能模式：

模式类型：

• full：分页正文内容（默认）
• outline：标题结构地图
• appendix：定义术语和锚点

apply_changes 工具一致性

操作参数规范：

// MODIFY
{"type": "modify", "target_text": "exact phrase", "new_text": "replacement", "comment": "optional"}

// ACCEPT/REJECT
{"type": "accept", "target_id": "Chg:12"}
{"type": "reject", "target_id": "Chg:12"}

// REPLY
{"type": "reply", "target_id": "Com:5", "text": "response body"}

资料来源：langchain/langchain_adeu/apply_changes.py:1-30

部署渠道支持

Adeu 通过跨平台设计支持多种部署渠道：

Gemini CLI 扩展修复

v1.6.8 版本修复了 gemini-extension.json 的位置问题，确保扩展验证正常工作：

# 修复前
archive/
└── adeu/
    └── gemini-extension.json

# 修复后
archive/
└── gemini-extension.json  (位于归档根目录)

资料来源：Release v1.6.8

最佳实践

确保跨平台一致性

1. 使用共享测试用例 - 将新功能添加到 shared/cross_platform_tests/ 目录
2. 维护 golden 文件 - 两种实现应生成相同的 OOXML 和 Markdown 输出
3. 避免平台特定逻辑 - 核心算法应在两种实现中保持一致
4. 使用常量定义 - 分页大小等关键参数应定义为常量

测试验证命令

# Python CLI
uvx adeu --version
uvx adeu read input.docx

# Node.js MCP Server
npx @adeu/mcp-server start

资料来源：python/skills/adeu-redlining/SKILL.md:1-20

概述

MCP（Model Context Protocol）协议集成是 Adeu 项目的核心架构特性，它允许 AI 代理通过标准化的工具接口与 DOCX 文档进行交互。Adeu 同时提供 Python 和 Node.js 两种 MCP Server 实现，支持通过 MCP 协议进行文档读取、编辑、批处理等操作。

核心功能包括：

• 文档读取（支持分页、大纲、附录模式）
• 批量变更处理（修改、接受、拒绝、回复评论）
• CriticMarkup 语法支持（用于表示追踪变更和评论）
• 干净的文档视图（接受所有变更后的最终文本）

资料来源：python/src/adeu/mcp_components/tools/document.py:1-50

架构设计

双端实现架构

Adeu 采用跨平台策略，同时维护 Python 和 Node.js 两套 MCP Server 实现：

graph TD
    subgraph "客户端"
        A[Claude / AI Agent]
        B[Gemini CLI]
        C[n8n Workflow]
    end
    
    subgraph "MCP Server 层"
        D[Python MCP Server]
        E[Node.js MCP Server]
    end
    
    subgraph "核心引擎"
        F[RedlineEngine]
        G[Ingest Module]
        H[Pagination Module]
    end
    
    subgraph "输出格式"
        I[Markdown + CriticMarkup]
        J[Clean View]
        K[UI HTML]
    end
    
    A --> D
    A --> E
    B --> E
    C --> D
    
    D --> F
    E --> F
    
    F --> G
    F --> H
    
    G --> I
    G --> J
    H --> I

两套实现共享相同的业务逻辑层，但使用各自语言生态的 MCP SDK：

资料来源：python/src/adeu/mcp_components/_response_builders.py:1-30

工具注册流程

MCP 工具通过统一的注册机制暴露给 AI Agent：

sequenceDiagram
    participant Client as AI Agent
    participant Server as MCP Server
    participant Tool as Tool Handler
    participant Engine as RedlineEngine
    
    Client->>Server: MCP list_tools
    Server-->>Client: [read_docx, process_batch, ...]
    
    Client->>Server: MCP call_tool(read_docx, params)
    Server->>Tool: delegate(params)
    Tool->>Engine: extract_text_from_doc(file_path, mode)
    Engine-->>Tool: projected_text
    Tool->>Server: build_paginated_response()
    Server-->>Client: ToolResult with markdown

资料来源：node/packages/mcp-server/src/index.ts:1-50

MCP 工具详解

read_docx 工具

read_docx 是核心文档读取工具，支持多种模式和分页导航。

#### 工具描述

Reads a DOCX file. Returns text with inline CriticMarkup for Tracked Changes 
and Comments: {++inserted++}, {--deleted--}, {==highlighted==}{>>comment<<}. 
Set clean_view=True for the finalized 'Accepted' text without markup.

资料来源：python/src/adeu/mcp_components/tools/document.py:50-60

#### 参数规格

#### 读取模式

资料来源：python/src/adeu/mcp_components/tools/document.py:60-75

process_batch 工具

process_batch 用于批量应用编辑操作和审阅动作。

#### 操作类型

graph LR
    A[process_batch] --> B[modify]
    A --> C[accept]
    A --> D[reject]
    A --> E[reply]
    A --> F[insert_row]
    A --> G[delete_row]
    
    B --> B1[搜索替换]
    C --> C1[确认变更]
    D --> D1[撤销变更]
    E --> E1[评论回复]
    F --> F1[表格行插入]
    G --> G1[表格行删除]

资料来源：python/src/adeu/mcp_components/tools/document.py:100-130

#### 操作参数规格

modify 操作

{
  "type": "modify",
  "target_text": "待替换的精确文本",
  "new_text": "替换后的新文本",
  "comment": "可选的修改理由"
}

accept / reject 操作

{"type": "accept", "target_id": "Chg:12"}
{"type": "reject", "target_id": "Chg:12"}

reply 操作

{"type": "reply", "target_id": "Com:5", "text": "回复内容"}

表格操作

{
  "type": "insert_row",
  "target_text": "相邻行中的单元格文本",
  "position": "above|below",
  "cells": ["col1", "col2", "col3"]
}

资料来源：langchain/langchain_adeu/apply_changes.py:1-50

响应构建系统

响应结构

所有 MCP 工具返回统一的 ToolResult 结构：

interface ToolResult {
  content: [{ type: 'text', text: string }];
  structured_content?: {
    markdown: string;
    title: string;
    file_path: string;
    page?: number;
    total_pages?: number;
  };
}

资料来源：python/src/adeu/mcp_components/_response_builders.py:30-50

分页响应构建

分页响应包含页面内容、导航横幅和附录指针：

graph LR
    A[文档文本] --> B[split_structural_appendix]
    B --> C[body]
    B --> D[appendix]
    
    C --> E[paginate]
    D --> F[缓存备用]
    
    E --> G[PageInfo]
    E --> H[页面内容]
    
    G --> I[banner]
    H --> J[footer]
    I --> K[完整响应]
    J --> K

资料来源：python/src/adeu/pagination.py:1-40

#### 分页配置

CriticMarkup 语法映射

Adeu 在 Markdown 中使用 CriticMarkup 表示追踪变更：

资料来源：python/src/adeu/mcp_components/tools/document.py:50-55

配置选项

Python Server 配置

Python MCP Server 通过 @server.list_tools() 装饰器注册工具：

@server.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="read_docx",
            description=_DESCRIPTION,
            inputSchema={
                "type": "object",
                "properties": {
                    "file_path": {"type": "string"},
                    "clean_view": {"type": "boolean", "default": False},
                    "mode": {"type": "string", "enum": ["full", "outline", "appendix"]},
                    "page": {"type": "integer", "default": 1},
                }
            }
        ),
        # ... 其他工具
    ]

Node.js Server 配置

TypeScript 实现使用 MCP SDK 的 builder 模式：

const server = new Server(
  {
    name: "adeu-mcp-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
      resources: {},
    },
  }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [readDocxTool, processBatchTool]
}));

资料来源：node/packages/mcp-server/src/index.ts:50-100

Win32 特殊配置

Windows 平台支持读取 Word 活动窗口中的文档：

READ_DOCX_WIN32_EXTRA = (
    "If the file is open in Word, reads from the live canvas automatically. "
    "Leave file_path empty to read whatever document is currently active.\n\n"
)

PROCESS_BATCH_WIN32_EXTRA = (
    "If the file is open in Word, edits run live on the canvas. "
    "Leave original_docx_path empty to edit whatever document is currently active.\n\n"
)

资料来源：python/src/adeu/mcp_components/tools/document.py:75-85

MCP Apps Protocol 扩展

Adeu 支持 MCP Apps Protocol 规范，提供额外的协议扩展：

graph TD
    subgraph "MCP Apps Protocol"
        A[Protocol Handlers]
        B[UI Resources]
        C[Email Templates]
    end
    
    subgraph "Resources"
        D[markdown_ui]
        E[email_notification]
    end
    
    A --> B
    B --> D
    B --> E

Markdown UI 资源

交互式 HTML 应用用于渲染 Markdown 工具结果：

MARKDOWN_UI_URI = "resource://markdown_ui"

@resource(MARKDOWN_UI_URI, annotations={"readOnlyHint": True}, mime_type="text/html")
def markdown_ui_app() -> str:
    """Interactive HTML App for rendering Markdown tool results."""
    marked_js_code = _get_marked_js_content()
    adeu_svg_code = _get_adeu_svg_content()
    template = jinja_env.get_template("markdown_ui.html")
    return template.render(marked_js_code=marked_js_code, adeu_svg_code=adeu_svg_code)

资料来源：python/src/adeu/mcp_components/resources/markdown_ui.py:30-50

集成示例

Claude Desktop 集成

{
  "mcpServers": {
    "adeu": {
      "command": "uvx",
      "args": ["adeu-mcp-server"],
      "env": {
        "PYTHONPATH": "/path/to/adeu"
      }
    }
  }
}

Gemini CLI 扩展安装

gemini extensions install github.com/dealfluence/adeu

资料来源：docs/MCP_APPS_PROTOCOL.md

n8n 工作流集成

Adeu 提供 n8n 节点支持，可通过工作流自动化处理文档：

graph LR
    A[n8n Trigger] --> B[Adeu Read Node]
    B --> C[LLM Processing]
    C --> D[Adeu Write Node]
    D --> E[Output]

资料来源：Release v1.7.3

常见问题与限制

批量操作原子性

所有变更评估基于原始文档状态——不要在一个批次内链接依赖编辑（例如先将 X 重命名为 Y，然后修改 Y）。请先应用重命名，再发送第二个批次。

资料来源：python/src/adeu/mcp_components/tools/document.py:85-95

多个变更 ID 问题

单一修改操作可能产生多个 [Chg:N] ID，因为底层 XML 可能包含多个运行（run）：

• 原因：DOCX 内部格式中，粗体/斜体等格式会拆分文本为多个 run
• 影响：一次替换可能被标记为多个变更对
• 状态：社区议题 #16 已报告此问题

资料来源：社区议题 #16

Windows 平台限制

• 需要 pywin32 库支持 Word 自动化
• 仅支持 Windows 平台
• 不支持 macOS/Linux 上的实时 Word 集成

总结

MCP 协议集成是 Adeu 项目实现 AI 辅助文档编辑的核心基础设施。通过提供标准化的工具接口（read_docx、process_batch 等），ADEu 使各类 AI Agent 能够：

1. 读取文档：支持分页、大纲、附录多种模式
2. 追踪变更：使用 CriticMarkup 语法表示插入、删除、评论
3. 批处理编辑：通过单一 API 完成复杂的多步骤编辑
4. 跨平台支持：Python 和 Node.js 双实现满足不同技术栈需求

该设计遵循 MIT 许可证，适合在法律科技等领域的广泛采用。

概述

Claude Desktop 集成是指通过 Model Context Protocol (MCP) 将 Adeu 的 DOCX 编辑能力接入 Anthropic Claude 桌面应用的配置方案。Adeu 作为 DOCX ↔ LLM 翻译器，通过 MCP 服务器为 AI 代理提供文档的读写接口，使其能够在不破坏 Word 文档结构的前提下进行精确的修订和批注操作。

核心架构

Adeu 提供两套 MCP 服务器实现：

MCP 工具接口

graph TD
    A[Claude Desktop] -->|MCP Protocol| B[Adeu MCP Server]
    B --> C[read_docx 工具]
    B --> D[process_batch 工具]
    C --> E[文档读取 - CriticMarkup 输出]
    D --> F[批量修改 - Track Changes 写入]
    E --> G[python-docx + diff-match-patch]
    F --> G

工具函数详解

read_docx - 文档读取

read_docx 是 MCP 工具中最重要的接口，负责将 DOCX 文件转换为 LLM 可读的 Markdown 格式。

# 资料来源：python/src/adeu/mcp_components/tools/document.py:18-26
READ_DOCX_FULL = (
    "Reads a DOCX file. Returns text with inline CriticMarkup for "
    "Tracked Changes and Comments: {++inserted++}, {--deleted--}, "
    "{==highlighted==}{>>comment<<}. Set clean_view=True for the "
    "finalized 'Accepted' text without markup.\n\n"
)

支持的模式：

参数：

• file_path: DOCX 文件的绝对路径
• page: 页码（默认 1）
• clean_view: 是否返回不含修订标记的清洁视图
• mode: 读取模式 (full | outline | appendix)
• outline_max_level: 大纲显示的最大标题级别（默认 2）

资料来源：python/src/adeu/mcp_components/tools/document.py:46-57

process_batch - 批量处理

process_batch 工具负责将 AI 的编辑建议转换为 Word 原生的 Track Changes。

# 资料来源：python/src/adeu/mcp_components/tools/document.py:35-38
PROCESS_BATCH_COMMON_DESC = (
    "Applies a batch of edits and review actions to a DOCX.\n\n"
    "All changes evaluate against the ORIGINAL document state — do not chain "
    "dependent edits within one batch"
)

支持的操作类型：

ID 稳定性说明：

⚠️ Chg:N 和 Com:N ID 在文档状态变化后会改变。每次 accept/reject/reply 操作前必须重新调用 read_docx 获取最新 ID。

资料来源：python/src/adeu/mcp_components/tools/document.py:40-47

响应构建器

响应构建器负责将处理结果格式化为 MCP 协议所需的结构化输出。

graph LR
    A[文档处理] --> B[build_paginated_response]
    A --> C[build_outline_response]
    A --> D[build_appendix_response]
    B --> E[ToolResult<br/>content + structured_content]
    C --> E
    D --> E

分页响应

# 资料来源：python/src/adeu/mcp_components/_response_builders.py:112-130
def build_paginated_response(text: str, page: int, file_path: str) -> ToolResult:
    body, appendix = split_structural_appendix(text)
    has_appendix = bool(appendix.strip())
    result = paginate(body, structural_appendix="")
    
    if page < 1 or page > result.total_pages:
        raise ToolError(f"Page {page} out of range...")
    
    selected = result.pages[page - 1]
    ui_markdown = banner + selected.page_content + footer + appendix_pointer

响应结构：

ToolResult(
    content=llm_content,  # 含文件路径头部的完整内容
    structured_content={
        "markdown": ui_markdown,    # UI 渲染用
        "title": Path(file_path).name,
        "file_path": str(Path(file_path).resolve()),
    },
)

CLI 命令行接口

除了 MCP 工具，Adeu 还提供命令行接口用于脚本化和批量处理：

# 读取文档
uvx adeu read input.docx

# 应用编辑
uvx adeu apply edits.json -i input.docx -o output.docx

# 清理文档（去除修订）
uvx adeu clean input.docx -o output.docx

子命令：

资料来源：python/src/adeu/cli.py:1-50

LangChain 集成

Adeu 提供 LangChain 工具封装，便于在 LangGraph 等复杂 AI 工作流中使用：

from langchain_adeu import AdeuReadDocx, AdeuApplyChanges

# 读取工具
read_tool = AdeuReadDocx()

# 应用更改工具  
change_tool = AdeuApplyChanges()

ToolResult 返回格式：

• content: 供模型直接读取的分页 Markdown
• artifact: 包含 markdown, title, file_path 等元数据的字典

资料来源：langchain/langchain_adeu/read_docx.py:1-30

CriticMarkup 语法

Adeu 使用 CriticMarkup 语法在 Markdown 中表示修订：

canonical 编辑对形式：

{++insertion++}{--deletion--}{>>bubble<<}

资料来源：README.md

最佳实践

文档读取流程

graph TD
    A[开始] --> B[大文档?]
    B -->|是| C[使用 outline 模式获取结构]
    B -->|否| D[使用 full 模式读取]
    C --> E{需要编辑?}
    D --> E
    E -->|是| F[使用 appendix 模式检查定义条款]
    E -->|否| G[直接阅读分页内容]
    F --> H[规划编辑位置]
    G --> I[执行阅读]
    H --> J[使用 process_batch 应用修改]

编辑批次规则

1. 单批次独立性：所有变更基于原始文档状态，不要在单批次内链式依赖编辑
2. ID 即时性：Chg:N 和 Com:N 仅在当前会话有效
3. 唯一匹配：target_text 必须唯一匹配，必要时包含周围上下文
4. Markdown 支持：new_text 支持 Markdown 格式（标题、粗体、斜体、段落分隔）

社区已知限制

资料来源：GitHub Issue #16

扩展与生态

n8n 集成

Adeu MCP 服务器可与 n8n 工作流自动化平台集成：

# 安装 MCP 服务器
n8n community package install adeu-mcp

资料来源：Release v1.7.3

Skill 封装

Adu-redlining skill 提供了开箱即用的 Adeu CLI 封装：

# 通过 uvx 执行
uvx adeu --version
uvx adeu read document.docx

资料来源：python/skills/adeu-redlining/SKILL.md

概述

Live MS Word 集成是 Adeu 在 Windows 平台上的核心功能，允许 AI Agent 直接编辑当前打开的 Microsoft Word 文档。该功能使 Adeu 能够作为"实时副驾驶"（real-time copilot），在用户面前实时处理文档修订和审阅操作，无需通过文件系统进行中间读写。

核心价值

资料来源：README.md

Pitfall Log / 踩坑日志

项目：dealfluence/adeu

摘要：发现 12 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Optional clause-validation hook for jurisdiction-aware redlines。

1. 安装坑 · 来源证据：Optional clause-validation hook for jurisdiction-aware redlines

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Optional clause-validation hook for jurisdiction-aware redlines
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d958d22cf43e498a9e36cecc04155467 | https://github.com/dealfluence/adeu/issues/20 | 来源类型 github_issue 暴露的待验证使用条件。

2. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 adeu 与安装入口 @adeu/mcp-server 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：npx @adeu/mcp-server
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | mcp_registry:ai.adeu/adeu:1.7.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.adeu%2Fadeu/versions/1.7.1 | repo=adeu; install=@adeu/mcp-server

3. 配置坑 · 来源证据：Create a non-AGPL workflow for VS Code visualization

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Create a non-AGPL workflow for VS Code visualization
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f1676fd51c1a4448920e55baae10f045 | https://github.com/dealfluence/adeu/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | mcp_registry:ai.adeu/adeu:1.7.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.adeu%2Fadeu/versions/1.7.1 | README/documentation is current enough for a first validation pass.

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | mcp_registry:ai.adeu/adeu:1.7.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.adeu%2Fadeu/versions/1.7.1 | last_activity_observed missing

6. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | mcp_registry:ai.adeu/adeu:1.7.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.adeu%2Fadeu/versions/1.7.1 | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | mcp_registry:ai.adeu/adeu:1.7.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.adeu%2Fadeu/versions/1.7.1 | no_demo; severity=medium

8. 安全/权限坑 · 来源证据：Claude Opus 4.7 testers feedback

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Claude Opus 4.7 testers feedback
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6508f8a8b81b40c5890e02ea1110c791 | https://github.com/dealfluence/adeu/issues/11 | 来源类型 github_issue 暴露的待验证使用条件。

9. 安全/权限坑 · 来源证据：Multi-Round Negotiation Testing

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Multi-Round Negotiation Testing
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ce563606cbda4f2d9273aba3173a2ecc | https://github.com/dealfluence/adeu/issues/4 | 来源类型 github_issue 暴露的待验证使用条件。

10. 安全/权限坑 · 来源证据：The Multiple Chg IDs Per Logical Edit

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：The Multiple Chg IDs Per Logical Edit
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8bcb3776b02a46479a29535f3048d7f7 | https://github.com/dealfluence/adeu/issues/16 | 来源类型 github_issue 暴露的待验证使用条件。

11. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | mcp_registry:ai.adeu/adeu:1.7.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.adeu%2Fadeu/versions/1.7.1 | issue_or_pr_quality=unknown

12. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | mcp_registry:ai.adeu/adeu:1.7.1 | https://registry.modelcontextprotocol.io/v0.1/servers/ai.adeu%2Fadeu/versions/1.7.1 | release_recency=unknown