# https://github.com/dealfluence/adeu 项目说明书

生成时间：2026-06-02 00:50:24 UTC

## 目录

- [Adeu 项目介绍](#intro)
- [快速开始](#quick-start)
- [生态与集成](#ecosystem)
- [架构总览](#arch-overview)
- [Python 引擎详解](#python-engine)
- [TypeScript 引擎详解](#typescript-engine)
- [跨平台一致性](#cross-platform-parity)
- [MCP 协议集成配置](#mcp-setup)
- [Claude Desktop 集成](#claude-integration)
- [Live MS Word 集成（Windows）](#live-word-integration)

<a id='intro'></a>

## Adeu 项目介绍

### 相关页面

相关主题：[快速开始](#quick-start), [架构总览](#arch-overview), [生态与集成](#ecosystem)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/dealfluence/adeu/blob/main/README.md)
- [AI_CONTEXT.md](https://github.com/dealfluence/adeu/blob/main/AI_CONTEXT.md)
- [python/skills/adeu-redlining/SKILL.md](https://github.com/dealfluence/adeu/blob/main/python/skills/adeu-redlining/SKILL.md)
- [python/src/adeu/mcp_components/_response_builders.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/_response_builders.py)
- [python/src/adeu/pagination.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/pagination.py)
- [langchain/langchain_adeu/read_docx.py](https://github.com/dealfluence/adeu/blob/main/langchain/langchain_adeu/read_docx.py)
- [node/packages/core/README.md](https://github.com/dealfluence/adeu/blob/main/node/packages/core/README.md)
- [node/packages/n8n-nodes-adeu/README.md](https://github.com/dealfluence/adeu/blob/main/node/packages/n8n-nodes-adeu/README.md)
- [python/src/adeu/cli.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/cli.py)
</details>

# Adeu 项目介绍

## 概述

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]()

---

## 架构设计

### 核心组件

```mermaid
graph TD
    subgraph "读取路径 Read Path"
        A[DOCX 文件] --> B[python-docx / jszip]
        B --> C[Ingestion 模块]
        C --> D[Markdown + CriticMarkup]
        D --> E[Semantic Appendix]
    end
    
    subgraph "编辑路径 Edit Path"
        F[LLM 文本编辑] --> G[Mapper 模块]
        G --> H[Engine 计算差异]
        H --> I[XML Patch w:ins/w:del]
        I --> J[更新后的 DOCX]
    end
    
    subgraph "Agent 接口"
        K[MCP Server] 
        L[CLI 工具]
        M[LangChain Tool]
        N[n8n Node]
    end
```

### 四步执行模型

Adeu 作为智能代理，处理 AI 编辑作为安全的原子事务：

| 阶段 | 功能 | 描述 |
|------|------|------|
| **1. Read** | 读取 | 将文档（从磁盘或实时 Word）翻译为 LLM 友好的 CriticMarkup，包含语义附录（defined terms、cross-references、typos） |
| **2. Validate** | 验证 | 充当严格的安全门，自动阻止模糊的文本匹配或无效的结构变更 |
| **3. Apply** | 应用 | 将 AI 的文本编辑转换为原生 Word Track Changes |
| **4. Preserve** | 保留 | 处理底层 XML，确保现有布局、字体和边距注释完美保留 |

资料来源：[README.md:20-35]()

### 关键技术决策

**格式化标记隔离原则**：Markdown 格式化标记（如 `**`、`_` 等）**绝对不能**包裹换行字符 `\n`。

```markdown
# 正确写法
**Line 1**
**Line 2**

# 错误写法
**Line 1
Line 2**
```

原因：换行符包裹会破坏许多 Markdown 解析器，并使基于行的文本分割复杂化。

资料来源：[AI_CONTEXT.md:14-22]()

---

## CriticMarkup 语法

Adeu 使用 CriticMarkup 作为跟踪修订的标记语言，这是 LLM 最易理解的差异表示格式。

### 语法标记

| 标记类型 | 语法 | 用途 |
|----------|------|------|
| 插入 | `{++text++}` | 新增内容 |
| 删除 | `{--text--}` | 删除内容 |
| 高亮/评论 | `{==text==}{>>comment<<}` | 标记待审阅内容 |
| 气泡注释 | `{>>comment<<}` | 独立注释 |

资料来源：[python/skills/adeu-redlining/SKILL.md:20-25]()

### 编辑操作示例

```json
// 修改操作（最常用）
{
  "type": "modify",
  "target_text": "laws of Scotland",
  "new_text": "laws of England and Wales",
  "comment": "Updated governing law clause per client request"
}

// 接受修订
{
  "type": "accept",
  "target_id": "Chg:12"
}

// 拒绝修订
{
  "type": "reject",
  "target_id": "Chg:12"
}

// 回复评论
{
  "type": "reply",
  "target_id": "Com:5",
  "text": "Acknowledged, will revise accordingly"
}
```

资料来源：[langchain/langchain_adeu/apply_changes.py:1-30]()

---

## 支持的操作类型

### 操作矩阵

| 操作 | 描述 | 支持平台 |
|------|------|----------|
| `modify` | 搜索替换文本，支持 Markdown 标题、加粗、斜体、段落分割 | MCP / CLI / LangChain / n8n |
| `accept` | 接受指定 ID 的修订 | MCP / CLI / LangChain / n8n |
| `reject` | 拒绝指定 ID 的修订 | MCP / CLI / LangChain / n8n |
| `reply` | 对评论进行回复 | MCP / CLI / LangChain / n8n |
| `insert_row` | 在表格中插入行 | MCP / CLI / LangChain / n8n |
| `delete_row` | 删除表格行 | MCP / CLI / LangChain / n8n |

资料来源：[python/src/adeu/mcp_components/tools/document.py:1-20]()

### 读取模式

| 模式 | 用途 | 描述 |
|------|------|------|
| `full` | 默认 | 分页正文内容，使用 page=N 导航 |
| `outline` | 大文档概览 | 仅标题地图（L1-L2），帮助规划目标阅读 |
| `appendix` | 语义附录 | 已定义术语、锚点、交叉引用目标 |

资料来源：[node/packages/mcp-server/src/index.ts:1-10]()

---

## 分页机制

### 设计原则

分页器以**无状态**方式工作，每次调用确定性计算分页，不使用缓存。

| 参数 | 值 | 说明 |
|------|------|------|
| `PAGE_TARGET_CHARS` | 19,000 | 每页目标字符数 |
| 边界保护 | CriticMarkup、表格、脚注 | 智能识别语义边界 |

### CriticMarkup 边界处理

```python
_CRITIC_TOKENS: Dict[str, str] = {
    "{++": "++}",
    "{--": "--}",
    "{==": "==}",
    "{>>": "<<}",
}
```

分页时，分页器尊重 CriticMarkup 完整性，确保不会在标记对中间截断。

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

### 响应构建器

响应构建器负责将分页结果转换为 LLM 可读的格式：

| 响应类型 | 函数 | 用途 |
|----------|------|------|
| 分页响应 | `build_paginated_response()` | 返回请求的页面内容 |
| 附录响应 | `build_appendix_response()` | 返回结构化附录（分页） |
| 大纲响应 | `build_outline_response()` | 返回标题树结构 |

资料来源：[python/src/adeu/mcp_components/_response_builders.py:1-50]()

---

## 集成方式

### Model Context Protocol (MCP)

MCP 是核心接口，提供 Python 和 Node.js 双实现：

```bash
# Python MCP Server
python -m adeu.mcp_components.server

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

资料来源：[README.md:40-50]()

### Claude CLI 集成

```bash
# 安装为 Claude CLI 扩展
claude extensions install github.com/dealfluence/adeu
```

资料来源：[Release v1.6.8]()

### LangChain 工具

```python
from langchain_adeu import AdeuReadDocx, AdeuApplyChanges

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

# 应用编辑
apply_tool = AdeuApplyChanges()
apply_tool.invoke({
    "original_docx_path": "/path/to/contract.docx",
    "output_docx_path": "/path/to/redlined.docx",
    "changes": [...]
})
```

资料来源：[langchain/langchain_adeu/read_docx.py:1-30]()

### n8n 工作流节点

| 操作 | 输入 | 输出 |
|------|------|------|
| Extract Markdown | `.docx` 二进制 | `{ markdown, fileName, cleanView }` |
| Apply Edits | `.docx` + changes JSON | redlined `.docx` + 统计信息 |
| Generate Diff | 两个 `.docx` | 子词级别差异 |

资料来源：[node/packages/n8n-nodes-adeu/README.md:1-30]()

### TypeScript 核心库

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

async function main() {
  const buffer = readFileSync("contract.docx");
  
  // 1. 提取为 CriticMarkup
  const markdown = await extractTextFromBuffer(buffer, false);
  
  // 2. 加载文档 DOM
  const doc = await DocumentObject.load(buffer);
  const engine = new RedlineEngine(doc, "AI Reviewer");
}
```

资料来源：[node/packages/core/README.md:1-35]()

### 命令行工具

```bash
# 读取文档
uvx adeu read contract.docx --clean-view

# 应用编辑
uvx adeu apply contract.docx edits.json -o redlined.docx

# 生成差异
uvx adeu diff original.docx modified.docx

# 清理文档
uvx adeu sanitize contract.docx --outdir ./clean/
```

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

---

## 语义附录 (Semantic Appendix)

Adeu 自动提取文档的语义元数据，为 LLM 提供更深层的上下文理解。

### 附录内容

| 类型 | 描述 |
|------|------|
| **已定义术语** | 文档中定义的术语及其位置 |
| **命名锚点** | 可作为交叉引用目标的标记位置 |
| **潜在错别字** | 检测到的疑似拼写错误 |
| **诊断信息** | 文档结构分析结果 |

### 分页附录使用

```python
# 先检查文档是否有附录
outline = build_outline_response(doc, projected_text, file_path)
has_appendix = outline.metadata.get("has_appendix", False)

# 按需获取附录
if has_appendix:
    appendix = build_appendix_response(projected_text, page=1, file_path=file_path)
```

资料来源：[python/src/adeu/mcp_components/_response_builders.py:50-80]()

---

## 社区关注点

根据 GitHub Issues 反馈，用户关注的主要方向：

### 高优先级功能需求

| Issue | 描述 | 状态 |
|-------|------|------|
| #1 | 非 AGPL 的 VS Code 可视化工作流 | 开放 |
| #20 | 辖区感知的条款验证钩子 | 开放 |
| #19 | 自动部署到所有 MCP 渠道 | 开放 |

### 技术改进建议

| Issue | 描述 | 影响 |
|-------|------|------|
| #16 | 单次修改操作产生多个 Chg ID | 同一逻辑编辑产生多个变更 ID |
| #11 | Claude Opus 4.7 测试反馈 | 语法工作正常，建议优化 UX |

### 多轮谈判测试

社区已验证 Adeu 在 3 轮 Claude-vs-Claude 合同谈判场景中的表现，工具链工作正常。

资料来源：[Multi-Round Negotiation Testing #4]()

---

## 版本历史

### 最新版本: v1.9.0

完整变更日志：[v1.8.0...v1.9.0](https://github.com/dealfluence/adeu/compare/v1.8.0...v1.9.0)

### 近期重要更新

| 版本 | 关键变更 |
|------|----------|
| v1.8.0 | 完整变更日志 |
| v1.7.4 | jszip 替换为 fflate，提升 DOCX 压缩/读取性能 |
| v1.7.3 | 首个 n8n 集成版本 |
| v1.6.8 | Gemini CLI 扩展修复 |

---

## 安装与使用

### 快速安装

```bash
# MCP Server (Python)
pip install adeu

# MCP Server (Node.js)
npm install @adeu/mcp-server

# Claude CLI 扩展
claude extensions install github.com/dealfluence/adeu

# Gemini CLI 扩展
gemini extensions install github.com/dealfluence/adeu
```

### 验证安装

```bash
uvx adeu --version
```

资料来源：[python/skills/adeu-redlining/SKILL.md:30-40]()

---

## 总结

Adeu 通过其创新的 Virtual DOM 架构，成功解决了 LLM 与 Word 文档之间的交互难题。其核心优势包括：

1. **令牌高效**：CriticMarkup 比原始 XML 消耗更少令牌
2. **格式保留**：复杂样式、布局、评论均完好保留
3. **原子操作**：批量编辑预验证，防止部分更新导致文档损坏
4. **多端支持**：MCP、CLI、LangChain、n8n 覆盖主流 AI 工作流
5. **开源友好**：MIT 许可证适合商业和法律技术集成

作为 AI 原生文档处理的解决方案，Adeu 正在成为法律、金融、技术文档自动化工作流的关键基础设施。

---

<a id='quick-start'></a>

## 快速开始

### 相关页面

相关主题：[Adeu 项目介绍](#intro), [MCP 协议集成配置](#mcp-setup), [Claude Desktop 集成](#claude-integration)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/dealfluence/adeu/blob/main/README.md)
- [python/src/adeu/cli.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/cli.py)
- [python/skills/adeu-redlining/SKILL.md](https://github.com/dealfluence/adeu/blob/main/python/skills/adeu-redlining/SKILL.md)
- [python/src/adeu/mcp_components/tools/document.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/tools/document.py)
- [python/src/adeu/mcp_components/_response_builders.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/_response_builders.py)
- [python/src/adeu/pagination.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/pagination.py)
- [langchain/langchain_adeu/read_docx.py](https://github.com/dealfluence/adeu/blob/main/langchain/langchain_adeu/read_docx.py)
- [langchain/langchain_adeu/apply_changes.py](https://github.com/dealfluence/adeu/blob/main/langchain/langchain_adeu/apply_changes.py)
- [node/packages/n8n-nodes-adeu/README.md](https://github.com/dealfluence/adeu/blob/main/node/packages/n8n-nodes-adeu/README.md)
</details>

# 快速开始

Adeu 是一个用于 Word 文档（.docx）版本控制和协作编辑的工具。它充当 DOCX 文件的"虚拟 DOM"，支持以 Markdown 格式读取文档、提出编辑建议，并将修改作为原生 Word 跟踪修订（Track Changes）应用。

## 核心概念

### CriticMarkup 语法

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

| 语法 | 含义 | 示例 |
|------|------|------|
| `{++text++}` | 插入内容 | `{++新增条款++}` |
| `{--text--}` | 删除内容 | `{--已废止条款--}` |
| `{==text==}` | 高亮显示 | `{==关键内容==}` |
| `{>>comment<<}` | 批注 | `{>>需要法务确认<<}` |

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

### 操作类型

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

| 操作类型 | 说明 | 参数 |
|----------|------|------|
| `modify` | 搜索替换文本 | `target_text`, `new_text`, `comment` |
| `accept` | 接受指定修订 | `target_id`（如 `Chg:12`） |
| `reject` | 拒绝指定修订 | `target_id`（如 `Chg:12`） |
| `reply` | 回复批注 | `target_id`, `text` |

资料来源：[langchain/langchain_adeu/apply_changes.py:1-30]()

## 安装方式

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

```bash
uvx adeu --version
```

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

### 方式二：pip 安装

```bash
pip install adeu
```

### 方式三：扩展集成

| 平台 | 安装命令 |
|------|----------|
| Claude CLI | `claude extensions install github.com/dealfluence/adeu` |
| Gemini CLI | `gemini extensions install github.com/dealfluence/adeu` |
| n8n | 通过 n8n-nodes-adeu 包集成 |

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

## 基本工作流程

```mermaid
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 工具调用

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

#### CLI 命令

```bash
# 基本读取
adeu read input.docx

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

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

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

#### 查看模式说明

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `full`（默认） | 分页显示文档正文 | 常规阅读和编辑 |
| `outline` | 仅显示标题结构 | 规划针对性阅读 |
| `appendix` | 显示术语定义、锚点、交叉引用 | 法律/技术文档编辑前查阅 |
| `clean_view=True` | 显示"接受所有"后的最终文本 | 生成新的修订 |

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

### 2. 应用编辑

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

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

#### 接受/拒绝修订

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

#### 回复批注

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

资料来源：[langchain/langchain_adeu/apply_changes.py:30-60]()

### 3. CLI 命令详解

#### apply - 应用变更

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

参数：

| 参数 | 说明 | 必需 |
|------|------|------|
| `input` | 输入 DOCX 文件路径 | 是 |
| `edits` | JSON 变更文件路径 | 是 |
| `-o, --output` | 输出 DOCX 文件路径 | 是 |
| `--author` | 跟踪修订作者名 | 否（默认：系统用户名） |

#### markup - 生成批评Markup

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

参数：

| 参数 | 说明 |
|------|------|
| `-i, --index` | 在输出中包含编辑索引 `[Edit:N]` |
| `--highlight` | 仅高亮目标文本，不应用变更 |

#### sanitize - 文档脱敏

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

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

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

## 分页系统

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

```mermaid
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 工具

```python
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 模型集成：

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

### 原子批量验证

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

```mermaid
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](https://github.com/dealfluence/adeu/issues/16)

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

当前的可视化方案采用 AGPL 许可。对于 MIT 许可的集成方式，可以考虑：
- 使用 MCP 工具在终端查看
- 通过 n8n 节点在自动化流程中处理
- 使用 LangChain 工具集成到自定义应用

资料来源：[issue #1](https://github.com/dealfluence/adeu/issues/1)

## 下一步

| 主题 | 说明 |
|------|------|
| [完整 CLI 参考](../cli-reference) | 所有命令行参数详解 |
| [API 参考](../api-reference) | Python API 和 MCP 工具文档 |
| [最佳实践](../best-practices) | 企业级部署建议 |
| [故障排除](../troubleshooting) | 常见问题解决方案 |

---

<a id='ecosystem'></a>

## 生态与集成

### 相关页面

相关主题：[Adeu 项目介绍](#intro)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [node/packages/n8n-nodes-adeu/README.md](https://github.com/dealfluence/adeu/blob/main/node/packages/n8n-nodes-adeu/README.md)
- [langchain/README.md](https://github.com/dealfluence/adeu/blob/main/langchain/README.md)
- [langchain/langchain_adeu/toolkit.py](https://github.com/dealfluence/adeu/blob/main/langchain/langchain_adeu/toolkit.py)
- [node/packages/n8n-nodes-adeu/examples/AI_Agent_workflow.json](https://github.com/dealfluence/adeu/blob/main/node/packages/n8n-nodes-adeu/examples/AI_Agent_workflow.json)
- [python/skills/adeu-redlining/SKILL.md](https://github.com/dealfluence/adeu/blob/main/python/skills/adeu-redlining/SKILL.md)
- [python/src/adeu/mcp_components/tools/document.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/tools/document.py)
</details>

# 生态与集成

Adeu 作为法律文档处理的"虚拟 DOM"解决方案，提供了丰富的生态系统，支持多种主流 AI 平台和工作流自动化工具的集成。本页面详细说明 adeu 的集成架构、支持的平台、以及各集成的使用方式。

## 集成架构概述

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

```mermaid
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 的主要集成协议，提供文档读取、编辑和审核的标准化接口。

### 工具列表

| 工具名称 | 功能描述 | 主要参数 |
|---------|---------|---------|
| `read_docx` | 读取 DOCX 文件为 Markdown | `file_path`, `clean_view`, `mode`, `page` |
| `process_batch` | 批量应用编辑操作 | `original_docx_path`, `new_docx_path`, `changes` |
| `sanitize_docx` | 清理文档元数据 | `file_path`, `output_path`, `remove_comments` |

### 读取模式

```mermaid
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]()

### 处理操作类型

| 操作类型 | 描述 | 关键参数 |
|---------|------|---------|
| `modify` | 搜索替换编辑 | `target_text`, `new_text`, `comment` |
| `accept` | 接受指定变更 | `target_id` (如 `Chg:12`) |
| `reject` | 拒绝指定变更 | `target_id` |
| `reply` | 回复评论 | `target_id`, `text` |

**资料来源**：[python/src/adeu/mcp_components/tools/document.py:45-80]()

## LangChain 集成

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

### 可用工具

```python
from langchain_adeu import AdeuReadDocx, AdeuApplyChanges, AdeuToolkit

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

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

### 工具包组件

| 工具 | 描述 | 返回格式 |
|-----|------|---------|
| `adeu_read_docx` | 读取 DOCX 为 Markdown | `content_and_artifact` |
| `adeu_apply_changes` | 应用编辑并返回结果 | `content_and_artifact` |
| `adeu_diff_docs` | 比较两个 DOCX 差异 | `content_and_artifact` |

**资料来源**：[langchain/langchain_adeu/toolkit.py:1-50]()

### 批处理原子性

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

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

**错误示例**：
```json
// ❌ 错误：第二次编辑的 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 驱动的文档处理流程。

### 节点操作

| 操作 | 输入 | 输出 |
|-----|------|-----|
| **Extract Markdown** | DOCX 二进制 | `{ markdown, fileName, cleanView }` |
| **Apply Edits** | DOCX + changes JSON | 新的红线 DOCX + 应用统计 |
| **Generate Diff** | 两个 DOCX | 子词级差异对比 |

**资料来源**：[node/packages/n8n-nodes-adeu/README.md:30-60]()

### Clean View 切换

| 模式 | 说明 | 适用场景 |
|-----|------|---------|
| `cleanView: false` (Raw View) | 显示所有待处理变更 | 解决对方编辑 |
| `cleanView: true` (Clean View) | 模拟"接受全部"状态 | 在干净基准上生成新红线 |

### 原子批处理验证

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

**资料来源**：[node/packages/n8n-nodes-adeu/README.md:50-55]()

## Claude 桌面集成

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

### 安装命令

```bash
# 使用 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 扩展的归档结构问题。

### 安装方法

```bash
gemini extensions install github.com/dealfluence/adeu
```

### 修复历史

| 版本 | 修复内容 |
|-----|---------|
| v1.6.8 | `gemini-extension.json` 现在位于归档根目录，而非嵌套在 `adeu/` 目录中 |

**资料来源**：[Release v1.6.8](https://github.com/dealfluence/adeu/releases/tag/v1.6.8)

## CLI 命令行工具

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

### 子命令概览

| 命令 | 功能 | 典型用途 |
|-----|------|---------|
| `read` | 读取 DOCX 为 Markdown | 文档检查 |
| `apply` | 应用编辑到文档 | 批量处理 |
| `markup` | 输出为 CriticMarkup Markdown | 生成差异报告 |
| `sanitize` | 清理文档元数据 | 发送给第三方前准备 |
| `diff` | 比较两个文档 | 版本对比 |

### 常用命令示例

```bash
# 读取文档
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（审核）**：接受/拒绝变更或回复评论

### 执行模型

```mermaid
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 工作流配置：

```mermaid
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 | 描述 | 状态 |
|-------|------|------|
| #1 | VS Code 可视化的非 AGPL 工作流 | 开放 |
| #19 | 自动部署到所有 MCP 渠道 | 开放 |
| #20 | 司法管辖区感知红线的可选条款验证钩子 | 开放 |

### 已知限制

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

**资料来源**：[GitHub Issues #1](https://github.com/dealfluence/adeu/issues/1), [#16](https://github.com/dealfluence/adeu/issues/16), [#19](https://github.com/dealfluence/adeu/issues/19), [#20](https://github.com/dealfluence/adeu/issues/20)

## 许可证兼容性

| 集成平台 | 许可证 | 说明 |
|---------|-------|------|
| Core Engine | MIT | 可自由用于商业用途 |
| LangChain | MIT | 与 LangChain 框架兼容 |
| n8n Nodes | MIT | 支持企业工作流 |
| Claude/Gemini | MIT | 适合法律科技采用 |

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

**资料来源**：[python/skills/adeu-redlining/SKILL.md:1-5]()

## 下一步

- 快速入门：[安装指南](../getting-started/installation)
- MCP 配置：[MCP 服务器设置](../mcp/setup)
- 工作流示例：[LangChain 教程](../tutorials/langchain-integration)

---

<a id='arch-overview'></a>

## 架构总览

### 相关页面

相关主题：[Adeu 项目介绍](#intro), [Python 引擎详解](#python-engine), [TypeScript 引擎详解](#typescript-engine), [跨平台一致性](#cross-platform-parity)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [AI_CONTEXT.md](https://github.com/dealfluence/adeu/blob/main/AI_CONTEXT.md)
- [docs/ARCHITECTURE.md](https://github.com/dealfluence/adeu/blob/main/docs/ARCHITECTURE.md)
- [docs/spec-monorepo-node-port.md](https://github.com/dealfluence/adeu/blob/main/docs/spec-monorepo-node-port.md)
- [python/src/adeu/redline/engine.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/redline/engine.py)
- [python/src/adeu/ingest.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/ingest.py)
- [python/src/adeu/markup.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/markup.py)
- [python/src/adeu/domain.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/domain.py)
- [python/src/adeu/pagination.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/pagination.py)
- [python/src/adeu/mcp_components/_response_builders.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/_response_builders.py)
- [node/packages/core/src/engine.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/core/src/engine.ts)
- [node/packages/core/src/ingest.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/core/src/ingest.ts)
- [node/packages/mcp-server/src/index.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/mcp-server/src/index.ts)
- [langchain/langchain_adeu/read_docx.py](https://github.com/dealfluence/adeu/blob/main/langchain/langchain_adeu/read_docx.py)
</details>

# 架构总览

Adeu 是一个用于 Word 文档（.docx）修订、批注和审阅的"虚拟 DOM"引擎。它通过后端 XML 注入（python-docx + diff-match-patch）处理红线标记，而非使用重量级前端引擎，从而实现了 MIT 许可证下的法律科技广泛采用。资料来源：[issues#1](https://github.com/dealfluence/adeu/issues/1)

## 核心设计理念

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

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

```mermaid
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 结构，主要分为以下几个核心模块：

| 模块 | 路径 | 职责 |
|------|------|------|
| **Core Engine** | `python/src/adeu/redline/engine.py` | 核心红线引擎，处理变更应用 |
| **Ingest** | `python/src/adeu/ingest.py` | DOCX 解析和 Markdown 投影 |
| **Markup** | `python/src/adeu/markup.py` | CriticMarkup 语法生成和解析 |
| **Pagination** | `python/src/adeu/pagination.py` | 分页渲染逻辑 |
| **Domain** | `python/src/adeu/domain.py` | 数据模型定义 |

### Python 核心引擎

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

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

```mermaid
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 格式：

```python
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](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/ingest.py)

## 数据流架构

### 读取流程（Read Pipeline）

```mermaid
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）

```mermaid
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）暴露四个核心工具：

| 工具 | 功能 | 模式 |
|------|------|------|
| `read_docx` | 读取 DOCX 为 Markdown | `full` / `outline` / `appendix` |
| `process_batch` | 批量应用编辑 | `modify` / `accept` / `reject` / `reply` |
| `extract_diff` | 比较两个 DOCX | 生成逐字差异 |
| `sanitize_docx` | 清理元数据和敏感信息 | 脱敏处理 |

资料来源：[python/src/adeu/mcp_components/tools/document.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/tools/document.py)

### 响应构建器

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

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

支持三种响应模式：

| 模式 | 说明 | 典型用途 |
|------|------|----------|
| `full` | 分页的正文内容 | 逐页阅读长文档 |
| `outline` | 标题树结构 | 规划针对性读取 |
| `appendix` | 定义术语和锚点 | 编辑前查阅避免破坏引用 |

## 分页系统

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

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

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

资料来源：[python/src/adeu/pagination.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/pagination.py)

## CriticMarkup 语法

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

| 标记 | 含义 | 示例 |
|------|------|------|
| `{++...++}` | 插入内容 | `{++新文本++}` |
| `{--...--}` | 删除内容 | `{--旧文本--}` |
| `{==...==}` | 高亮文本 | `{==重要内容==}` |
| `{>>...<<}` | 批注气泡 | `{>>评论内容<<}` |

社区反馈表明，`{++insertion++}{--deletion--}{>>bubble<<}` 是最常用的编辑对形状，三种不同的括号风格确保了视觉清晰度。资料来源：[issues#11](https://github.com/dealfluence/adeu/issues/11)

## 多平台集成

### LangChain 集成

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

```python
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](https://github.com/dealfluence/adeu/blob/main/node/packages/n8n-nodes-adeu/README.md)

### MCP Server

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

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

## CLI 接口

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

```bash
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](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/cli.py)

## 变更类型定义

```python
# 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](https://github.com/dealfluence/adeu/issues/16)

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

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

## 技术栈概览

| 组件 | 技术选型 | 说明 |
|------|----------|------|
| 核心语言 | Python 3.x | 主引擎实现 |
| DOCX 解析 | python-docx | OOXML 操作 |
| 差异算法 | diff-match-patch | 文本差异计算 |
| MCP 协议 | TypeScript | MCP Server 实现 |
| 工作流集成 | n8n | 自动化工作流 |
| LLM 集成 | LangChain | Agent 工具封装 |

## 相关文档

- [快速开始指南](../getting-started.md) — 安装和基础使用
- [API 参考](../api/reference.md) — 完整的 API 文档
- [CLI 参考](../cli/reference.md) — 命令行工具详解
- [MCP 工具](../mcp/tools.md) — MCP 协议工具说明
- [LangChain 集成](../integrations/langchain.md) — LangChain 工具使用

---

<a id='python-engine'></a>

## Python 引擎详解

### 相关页面

相关主题：[架构总览](#arch-overview), [TypeScript 引擎详解](#typescript-engine), [跨平台一致性](#cross-platform-parity)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [python/src/adeu/ingest.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/ingest.py)
- [python/src/adeu/markup.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/markup.py)
- [python/src/adeu/redline/engine.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/redline/engine.py)
- [python/src/adeu/redline/mapper.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/redline/mapper.py)
- [python/src/adeu/redline/comments.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/redline/comments.py)
- [python/src/adeu/pagination.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/pagination.py)
- [python/src/adeu/mcp_components/_response_builders.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/_response_builders.py)
- [python/src/adeu/cli.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/cli.py)
- [AI_CONTEXT.md](https://github.com/dealfluence/adeu/blob/main/AI_CONTEXT.md)
</details>

# Python 引擎详解

## 概述

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

**核心能力**：

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

资料来源：[AI_CONTEXT.md]()

## 架构设计

### 核心设计原则

```mermaid
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
```

### 四阶段处理管线

| 阶段 | 组件 | 职责 |
|------|------|------|
| **Ingestion** | `ingest.py` | 创建 Markdown/CriticMarkup 文档表示 |
| **Mapping** | `mapper.py` | 构建文本跨度索引，关联回 python-docx 对象 |
| **Reconciliation** | `engine.py` | 计算并应用 XML 原子补丁 |
| **Agent Interface** | `server.py` / `cli.py` | 暴露 MCP 服务和命令行接口 |

资料来源：[AI_CONTEXT.md]()

## 文本提取与格式化

### ingest.py 核心功能

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

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

**关键特性**：

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

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

资料来源：[python/src/adeu/ingest.py]()

### clean_view 模式

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

| 模式 | 行为 |
|------|------|
| `clean_view=False` | 保留所有 CriticMarkup 标记（`{++` `++}` `{--` `--}`） |
| `clean_view=True` | 输出"已接受"文本，移除所有追踪修订标记 |

## 追踪修订引擎

### RedlineEngine 架构

```mermaid
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

```python
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:
        """序列化修改后的文档到字节流"""
```

**变更类型支持**：

| 类型 | 描述 | 参数 |
|------|------|------|
| `ModifyText` | 搜索替换文本 | `target_text`, `new_text` |
| `InsertComment` | 添加评论气泡 | `target_text`, `comment` |
| `AcceptChange` | 接受追踪修订 | `target_id` (Chg:N) |
| `RejectChange` | 拒绝追踪修订 | `target_id` (Chg:N) |
| `ReplyComment` | 回复评论 | `target_id` (Com:N) |

资料来源：[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](https://github.com/dealfluence/adeu/issues/16)

## Mapper 文本跨度映射

### mapper.py 功能

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

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

**SpanMapping 结构**：

| 字段 | 类型 | 描述 |
|------|------|------|
| `start_offset` | int | 文本在投影 Markdown 中的起始位置 |
| `end_offset` | int | 文本结束位置 |
| `paragraph` | `CT_P` | 对应的 OOXML 段落对象 |
| `run_index` | int | 段落内 run 的索引 |

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

资料来源：[python/src/adeu/redline/mapper.py]()

## 评论系统

### comments.py 组件

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

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

**评论输出格式**：

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

资料来源：[python/src/adeu/redline/comments.py]()

## 分页系统

### pagination.py 设计

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

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

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

**分页保护规则**：

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

**CriticMarkup 标记定义**：

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

资料来源：[python/src/adeu/pagination.py]()

### 结构附录处理

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

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

```python
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 工具的响应构建组件，提供三种输出模式：

```python
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
```

**输出模式对比**：

| 模式 | 用途 | 典型用例 |
|------|------|----------|
| `full` (默认) | 分页正文内容 | 阅读文档页面 |
| `outline` | 标题树 | 导航大文档 |
| `appendix` | 结构元数据 | 编辑前查阅术语定义 |

**页面 Banner/Footer 格式**：

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

---

[正文内容]

---

> **Continues on page N+1 of M.**
```

资料来源：[python/src/adeu/mcp_components/_response_builders.py]()

## 命令行接口

### cli.py 子命令

```bash
adeu apply      # 应用变更到 DOCX
adeu markup     # 输出为 CriticMarkup Markdown
adeu sanitize   # 剥离敏感信息
adeu read       # 读取并分页显示文档
```

#### apply 子命令

```bash
adeu apply [OPTIONS] ORIGINAL_DOCX EDITS_JSON
```

| 选项 | 描述 | 默认值 |
|------|------|--------|
| `-o, --output` | 输出 DOCX 路径 | 覆盖原文件 |
| `--author` | Track Changes 作者名 | 系统用户名 |

#### markup 子命令

```bash
adeu markup INPUT EDITS [OPTIONS]
```

| 选项 | 描述 |
|------|------|
| `-o, --output` | 输出 Markdown 路径 |
| `-i, --index` | 包含 `[Edit:N]` 编辑索引 |
| `--highlight` | 高亮模式（仅标记，不应用变更） |

资料来源：[python/src/adeu/cli.py]()

## Markup 处理

### markup.py 核心函数

```python
def apply_edits_to_markdown(
    markdown_text: str,
    edits: List[ModifyText],
    include_index: bool = False,
    highlight_only: bool = False,
) -> str
```

**CriticMarkup 输出格式**：

```markdown
{--deleted text--}{++inserted text++}{>>comment<<}
```

**编辑索引**：

```markdown
{--deleted--}{++inserted++}{>>[Edit:42] comment<<}
```

### 匹配与验证

```python
def _find_match_in_text(text: str, target: str) -> Tuple[int, int]:
    """在文本中查找目标字符串，返回 (start, end) 位置"""

def _validate_no_overlaps(edits: List[Tuple]) -> bool:
    """验证编辑范围无重叠"""
```

**已知限制**：

- 纯插入（无 `target_text`）在文本模式下不支持
- 找不到目标文本时跳过并记录警告

资料来源：[python/src/adeu/markup.py]()

## MCP 服务器集成

### 工具接口定义

```python
class AdeuReadDocxInput(BaseModel):
    file_path: str           # 绝对文件系统路径
    clean_view: bool = False # 是否移除 markup
    mode: Literal["full", "outline", "appendix"] = "full"
    page: int = 1            # 页码
    outline_max_level: int = 2  # 标题层级上限
    outline_verbose: bool = False
```

### 输出结构

```python
ToolResult(
    content=llm_content,          # LLM 可见内容（包含路径标注）
    structured_content={
        "markdown": ui_markdown,  # 纯 UI Markdown
        "title": "文档标题.docx",
        "file_path": "/abs/path/to/doc.docx",
        "page": 1,
        "total_pages": 10,
    }
)
```

资料来源：[langchain/langchain_adeu/read_docx.py]()

## CriticMarkup 语法参考

| 语法 | 含义 | 示例 |
|------|------|------|
| `{++text++}` | 插入 | `{++new paragraph++}` |
| `{--text--}` | 删除 | `{--obsolete text--}` |
| `{==text==}` | 高亮 | `{==important==}` |
| `{>>comment<<}` | 评论气泡 | `{>>Needs review<<}` |
| `{>>[Edit:N]<<}` | 带索引评论 | `{>>[Edit:42] rationale<<}` |
| `[Chg:N]` | 追踪修订 ID | Accept/Reject 目标 |
| `[Com:N]` | 评论 ID | Reply 目标 |

资料来源：[Issue #11](https://github.com/dealfluence/adeu/issues/11)

## 常见工作流

### 1. 文档读取与导航

```python
from adeu.ingest import _extract_text_from_doc

# 获取文档内容
text, doc = _extract_text_from_doc(docx_path, clean_view=False)

# 提取大纲
outline = build_outline_response(doc, text, docx_path)

# 分页读取第3页
page3 = build_paginated_response(text, page=3, file_path=docx_path)
```

### 2. 批量编辑文档

```python
from io import BytesIO
from adeu import RedlineEngine
from adeu.redline.models import ModifyText

changes = [
    ModifyText(
        target_text="Original clause text",
        new_text="**Revised** clause text",
        comment="Updated per client feedback"
    )
]

engine = RedlineEngine(BytesIO(original_bytes), author="Legal Bot")
engine.process_batch(changes)
output = engine.save_to_stream()
```

### 3. 生成验收测试黄金文件

```bash
python scripts/generate_goldens.py --test-name "my_test"
```

此脚本生成三个对照文件：

- `golden_raw.md` — 原始投影 Markdown
- `golden_clean.md` — 清理后 Markdown
- `golden_abstract.xml` — 抽象 XML 快照

资料来源：[python/scripts/generate_goldens.py]()

## 安全与清理

### sanitize 模块

```python
def sanitize_docx(
    input_path: Path,
    output_path: Path,
    keep_markup: bool = False,
    strip_comments: bool = True,
    strip_tracked_changes: bool = False,
) -> SanitizeResult
```

**清理选项**：

| 选项 | 效果 |
|------|------|
| `keep_markup` | 保留 Track Changes |
| `strip_comments` | 移除所有评论 |
| `strip_tracked_changes` | 接受所有追踪修订 |

资料来源：[python/src/adeu/sanitize/core.py]()

## 扩展与集成

### LangChain 集成

```python
from langchain_adeu import AdeuReadDocx, AdeuApplyChanges

read_tool = AdeuReadDocx()
apply_tool = AdeuApplyChanges()

# 在 LangGraph 中使用
result = await read_tool.ainvoke({"file_path": "/path/to/doc.docx"})
```

### MCP Server 部署

```bash
adeu server start --port 8765
```

通过 MCP 协议暴露所有工具，供 AI 代理调用。

## 总结

Adeu Python 引擎通过四阶段管线实现了 DOCX 文档的 LLM 友好编辑：

1. **提取**：将复杂 OOXML 转换为 Markdown/CriticMarkup 文本
2. **映射**：建立文本跨度与底层 XML 对象的双向索引
3. **计算**：基于语义匹配计算精确的 XML 补丁
4. **应用**：生成 Word 原生 Track Changes 或标准 CriticMarkup

引擎采用 MIT 许可证，设计上优先考虑后端 XML 注入而非重型前端引擎，使其特别适合法律科技领域的广泛采用。

---

<a id='typescript-engine'></a>

## TypeScript 引擎详解

### 相关页面

相关主题：[架构总览](#arch-overview), [Python 引擎详解](#python-engine), [跨平台一致性](#cross-platform-parity)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [node/packages/core/src/index.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/core/src/index.ts)
- [node/packages/core/README.md](https://github.com/dealfluence/adeu/blob/main/node/packages/core/README.md)
- [node/packages/mcp-server/src/index.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/mcp-server/src/index.ts)
- [node/packages/mcp-server/src/response-builders.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/mcp-server/src/response-builders.ts)
- [node/packages/mcp-server/src/tools/document.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/mcp-server/src/tools/document.ts)
- [node/packages/mcp-server/src/shared.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/mcp-server/src/shared.ts)
- [python/src/adeu/mcp_components/_response_builders.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/_response_builders.py)
- [python/src/adeu/mcp_components/tools/document.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/tools/document.py)
- [python/src/adeu/pagination.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/pagination.py)
- [python/src/adeu/markup.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/markup.py)
</details>

# TypeScript 引擎详解

## 概述

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

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

## 架构概览

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

```mermaid
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` 导出以下核心接口：

| 导出项 | 功能说明 |
|--------|----------|
| `DocumentObject` | 文档对象模型，用于加载和操作 DOCX |
| `RedlineEngine` | 修订引擎，处理 tracked changes |
| `BatchValidationError` | 批量验证错误类型 |
| `DocumentMapper`, `TextSpan` | 文档映射和文本跨度 |
| `generate_edits_from_text`, `trim_common_context`, `create_unified_diff`, `create_word_patch_diff` | 差异生成工具 |
| `apply_edits_to_markdown` | Markdown 标记应用 |
| `paginate`, `split_structural_appendix`, `PaginationResult`, `PageInfo` | 分页系统 |
| `extract_outline`, `OutlineNode` | 文档大纲提取 |
| `extractTextFromBuffer` | 缓冲区文本提取 |
| `finalize_document`, `FinalizeOptions`, `FinalizeResult` | 文档最终化 |

资料来源：[node/packages/core/src/index.ts]()

### DocumentObject 文档对象

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

```typescript
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 作为中间表示格式：

| 语法 | 含义 | 示例 |
|------|------|------|
| `{++text++}` | 插入文本 | `{++新增条款++}` |
| `{--text--}` | 删除文本 | `{--已废止条款--}` |
| `{==text==}` | 高亮文本 | `{==重要内容==}` |
| `{>>comment<<}` | 评论气泡 | `{>>建议修改<<}` |

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

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

## MCP 服务器集成

### 工具定义

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

| 工具名称 | 功能 |
|----------|------|
| `read_docx` | 读取 DOCX 文件，返回 CriticMarkup 格式的文本 |
| `process_batch` | 批量应用编辑和审阅操作到 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.
```

**模式选项：**
- `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.
```

**支持的操作类型：**

| 类型 | 说明 |
|------|------|
| `modify` | 搜索替换，new_text 支持 Markdown 语法 |
| `accept` | 接受指定 ID 的修订 |
| `reject` | 拒绝指定 ID 的修订 |
| `reply` | 回复指定 ID 的评论 |
| `insert_row` | 在表格中插入行 |
| `delete_row` | 从表格中删除行 |

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

### 响应构建器

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

```typescript
// 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]()

## 分页系统

### 分页配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `PAGE_TARGET_CHARS` | 19,000 | 每页目标字符数 |
| `APPENDIX_MARKER` | `<!-- READONLY_BOUNDARY_START -->` | 结构附录标记 |

### CriticMarkup 边界保护

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

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

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

资料来源：[python/src/adeu/pagination.py]()

## 用户界面资源

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

```typescript
// 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 的完整移植，核心功能保持一致：

| 特性 | Python SDK | TypeScript 引擎 |
|------|------------|-----------------|
| 文档加载 | `docx` 库 | `@xmldom/xmldom` + `jszip` |
| 运行环境 | Python 3.x | Node.js |
| MCP 集成 | ✅ | ✅ |
| LangChain 集成 | ✅ | 规划中 |

## 已知问题

### 多 Chg ID 问题

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

资料来源：[社区 issue #16](https://github.com/dealfluence/adeu/issues/16)

## 安装使用

```bash
npm install @adeu/core
```

快速示例：

```typescript
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` 进行打包：

```typescript
// 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 两种格式输出。

---

<a id='cross-platform-parity'></a>

## 跨平台一致性

### 相关页面

相关主题：[Python 引擎详解](#python-engine), [TypeScript 引擎详解](#typescript-engine), [架构总览](#arch-overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [python/src/adeu/mcp_components/_response_builders.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/_response_builders.py)
- [node/packages/mcp-server/src/response-builders.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/mcp-server/src/response-builders.ts)
- [python/src/adeu/pagination.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/pagination.py)
- [shared/cross_platform_tests/01_basic_text_modification/test.json](https://github.com/dealfluence/adeu/blob/main/shared/cross_platform_tests/01_basic_text_modification/test.json)
- [shared/cross_platform_tests/01_basic_text_modification/golden_abstract.xml](https://github.com/dealfluence/adeu/blob/main/shared/cross_platform_tests/01_basic_text_modification/golden_abstract.xml)
- [shared/cross_platform_tests/01_basic_text_modification/golden_raw.md](https://github.com/dealfluence/adeu/blob/main/shared/cross_platform_tests/01_basic_text_modification/golden_raw.md)
- [python/skills/adeu-redlining/SKILL.md](https://github.com/dealfluence/adeu/blob/main/python/skills/adeu-redlining/SKILL.md)
</details>

# 跨平台一致性

## 概述

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

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

## 架构设计

### 双实现架构

```mermaid
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
```

### 核心一致性模块

| 模块 | Python路径 | Node.js路径 | 职责 |
|------|-----------|-------------|------|
| 响应构建器 | `_response_builders.py` | `response-builders.ts` | 构建工具返回的Markdown响应 |
| 分页器 | `pagination.py` | 分页逻辑内联 | 文档分页处理 |
| 大纲提取 | `outline.py` | `extract_outline` | 提取文档标题结构 |
| 附录分离 | `split_structural_appendix` | `splitStructuralAppendix` | 分离定义术语和诊断信息 |

## 响应构建器一致性

### 响应结构设计

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

```typescript
// 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实现 | Node.js实现 |
|------|-----------|-------------|
| 分页目标字符数 | `PAGE_TARGET_CHARS = 19_000` | 同左（常量） |
| CriticMarkup边界保护 | ✅ | ✅ |
| 表格完整性 | ✅ | ✅ |
| 脚注区域保留 | ✅ | ✅ |
| 附录分离 | `split_structural_appendix` | `splitStructuralAppendix` |

**分页核心常量：**

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

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

### CriticMarkup 标记处理

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

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

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

## 附录分离机制

### 结构化附录设计

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

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

### 附录内容类型

| 类型 | 描述 | 分离标识 |
|------|------|---------|
| 定义术语 | 文档中定义的关键词汇 | `<!-- defined-term:xxx -->` |
| 命名锚点 | 书签和交叉引用目标 | `<a name="xxx">` |
| 诊断信息 | 潜在问题标记 | 语法检查标记 |

**附录分离逻辑（Python）：**

```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_...                  # 更多测试用例
```

### 测试用例格式

```json
{
  "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]()

### 一致性验证流程

```mermaid
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
<!-- 问题根源：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` 工具具有相同的功能模式：

| 参数 | 说明 | Python | Node.js |
|------|------|--------|---------|
| `file_path` | 文档路径 | ✅ | ✅ |
| `clean_view` | 显示最终文本 | ✅ | ✅ |
| `mode` | 读取模式 | ✅ | ✅ |
| `page` | 分页导航 | ✅ | ✅ |

**模式类型：**
- `full`：分页正文内容（默认）
- `outline`：标题结构地图
- `appendix`：定义术语和锚点

### apply_changes 工具一致性

| 操作类型 | Python | Node.js | 说明 |
|----------|--------|---------|------|
| `modify` | ✅ | ✅ | 搜索替换 |
| `accept` | ✅ | ✅ | 接受变更 |
| `reject` | ✅ | ✅ | 拒绝变更 |
| `reply` | ✅ | ✅ | 回复评论 |

**操作参数规范：**

```json
// 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 通过跨平台设计支持多种部署渠道：

| 渠道 | 平台 | 说明 |
|------|------|------|
| MCP Server | Python/Node.js | 模型上下文协议服务 |
| Claude CLI | Node.js | Claude命令行集成 |
| Gemini CLI | Node.js | Gemini命令行集成 |
| n8n Nodes | Node.js | 工作流自动化 |
| LangChain | Python | LLM应用框架 |

### Gemini CLI 扩展修复

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

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

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

资料来源：[Release v1.6.8](https://github.com/dealfluence/adeu/releases/tag/v1.6.8)

## 最佳实践

### 确保跨平台一致性

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

### 测试验证命令

```bash
# 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]()

---

<a id='mcp-setup'></a>

## MCP 协议集成配置

### 相关页面

相关主题：[快速开始](#quick-start), [Claude Desktop 集成](#claude-integration), [Live MS Word 集成（Windows）](#live-word-integration)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [python/src/adeu/server.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/server.py)
- [python/src/adeu/mcp_components/tools/document.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/tools/document.py)
- [python/src/adeu/mcp_components/tools/auth.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/tools/auth.py)
- [python/src/adeu/mcp_components/shared.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/shared.py)
- [python/src/adeu/mcp_components/_response_builders.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/_response_builders.py)
- [python/src/adeu/mcp_components/resources/markdown_ui.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/resources/markdown_ui.py)
- [node/packages/mcp-server/src/index.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/mcp-server/src/index.ts)
- [node/packages/mcp-server/src/tools/document.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/mcp-server/src/tools/document.ts)
- [node/packages/mcp-server/src/response-builders.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/mcp-server/src/response-builders.ts)
- [docs/MCP_APPS_PROTOCOL.md](https://github.com/dealfluence/adeu/blob/main/docs/MCP_APPS_PROTOCOL.md)
</details>

# MCP 协议集成配置

## 概述

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 实现：

```mermaid
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 实现 | Node.js 实现 |
|------|------------|-------------|
| MCP SDK | mcp library | @modelcontextprotocol/sdk |
| HTTP Server | FastAPI / SSE | Express / SSE |
| 工具定义 | Python decorators | TypeScript decorators |
| 响应构建 | _response_builders.py | response-builders.ts |

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

### 工具注册流程

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

```mermaid
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]()

#### 参数规格

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| file_path | string | 必需 | DOCX 文件的绝对路径 |
| clean_view | boolean | false | true 时返回接受所有变更后的干净文本 |
| mode | string | "full" | 读取模式：full/outline/appendix |
| page | integer | 1 | 分页模式下请求的页码 |
| outline_max_level | integer | 2 | 大纲模式显示的最大标题级别 |
| outline_verbose | boolean | false | 大纲模式是否包含详细元数据 |

#### 读取模式

| 模式 | 用途 | 返回内容 |
|------|------|----------|
| full | 默认模式，分页阅读 | 当前页的文档内容和分页导航信息 |
| outline | 大型文档结构预览 | 标题树状结构，便于定位阅读区域 |
| appendix | 附录信息查询 | 定义条款、锚点、交叉引用目标 |

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

### process_batch 工具

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

#### 操作类型

```mermaid
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 操作**
```json
{
  "type": "modify",
  "target_text": "待替换的精确文本",
  "new_text": "替换后的新文本",
  "comment": "可选的修改理由"
}
```

| 特性 | 说明 |
|------|------|
| target_text | 必须唯一匹配，可包含上下文以消除歧义 |
| new_text | 支持 Markdown 语法（标题、粗体、斜体、段落分隔） |
| new_text 为空 | 执行删除操作 |
| comment | 使用 comment 参数而非 CriticMarkup 标签 |

**accept / reject 操作**
```json
{"type": "accept", "target_id": "Chg:12"}
{"type": "reject", "target_id": "Chg:12"}
```

**reply 操作**
```json
{"type": "reply", "target_id": "Com:5", "text": "回复内容"}
```

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

资料来源：[langchain/langchain_adeu/apply_changes.py:1-50]()

## 响应构建系统

### 响应结构

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

```typescript
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]()

### 分页响应构建

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

```mermaid
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]()

#### 分页配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| PAGE_TARGET_CHARS | 19,000 | 每页目标字符数 |
| 边界保护 | CriticMarkup 边界 | 确保不拆分变更对 |
| 表格保护 | 整表保留 | 表格不会跨页拆分 |
| 脚注保护 | 脚注区域完整保留 | |

### CriticMarkup 语法映射

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

| 操作 | 语法 | 示例 |
|------|------|------|
| 插入 | `{++text++}` | `{++新增内容++}` |
| 删除 | `{--text--}` | `{--删除内容--}` |
| 高亮 | `{==text==}` | `{==高亮文本==}` |
| 评论 | `{>>comment<<}` | `{>>这是一个评论<<}` |
| 变更对 | `{++新++}{--旧--}{>>说明<<}` | 完整编辑标记 |

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

## 配置选项

### Python Server 配置

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

```python
@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 模式：

```typescript
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 活动窗口中的文档：

```python
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 规范，提供额外的协议扩展：

```mermaid
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 工具结果：

```python
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 集成

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

### Gemini CLI 扩展安装

```bash
gemini extensions install github.com/dealfluence/adeu
```

资料来源：[docs/MCP_APPS_PROTOCOL.md]()

### n8n 工作流集成

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

```mermaid
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](https://github.com/dealfluence/adeu/releases/tag/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](https://github.com/dealfluence/adeu/issues/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 许可证，适合在法律科技等领域的广泛采用。

---

<a id='claude-integration'></a>

## Claude Desktop 集成

### 相关页面

相关主题：[快速开始](#quick-start), [MCP 协议集成配置](#mcp-setup)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [python/src/adeu/mcp_components/_response_builders.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/_response_builders.py)
- [python/src/adeu/mcp_components/tools/document.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/tools/document.py)
- [python/skills/adeu-redlining/SKILL.md](https://github.com/dealfluence/adeu/blob/main/python/skills/adeu-redlining/SKILL.md)
- [README.md](https://github.com/dealfluence/adeu/blob/main/README.md)
- [python/src/adeu/cli.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/cli.py)
- [langchain/langchain_adeu/read_docx.py](https://github.com/dealfluence/adeu/blob/main/langchain/langchain_adeu/read_docx.py)
</details>

# Claude Desktop 集成

## 概述

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

## 核心架构

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

| 实现 | 位置 | 用途 |
|------|------|------|
| Python MCP | `python/src/adeu/mcp_components/` | 主要实现，支持完整功能集 |
| Node.js MCP | `node/packages/mcp-server/` | TypeScript 版本，用于特定生态 |

### MCP 工具接口

```mermaid
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
# 资料来源：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"
)
```

**支持的模式：**

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `full` | 分页正文内容（默认） | 常规文档阅读 |
| `outline` | 标题大纲地图 | 大文档结构预览 |
| `appendix` | 定义条款、锚点、交叉引用 | 法律/技术文档编辑前查询 |

**参数：**

- `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
# 资料来源：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"
)
```

**支持的操作类型：**

| 类型 | 参数 | 说明 |
|------|------|------|
| `modify` | `target_text`, `new_text`, `comment` | 搜索替换，生成修订标记 |
| `accept` | `target_id` | 接受指定修订（如 `Chg:12`） |
| `reject` | `target_id` | 拒绝指定修订 |
| `reply` | `target_id`, `text` | 回复指定批注 |
| `insert_row` | `target_text`, `position`, `cells` | 表格行插入 |
| `delete_row` | `target_text` | 表格行删除 |

**ID 稳定性说明：**

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

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

## 响应构建器

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

```mermaid
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
# 资料来源：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
```

**响应结构：**

```python
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 还提供命令行接口用于脚本化和批量处理：

```bash
# 读取文档
uvx adeu read input.docx

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

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

**子命令：**

| 命令 | 功能 |
|------|------|
| `read` | 读取并转换 DOCX 为 Markdown |
| `apply` | 应用 JSON 编辑到 DOCX |
| `markup` | 输出为 CriticMarkup 格式 |
| `sanitize` | 剥离元数据和敏感信息 |
| `diff` | 对比两个 DOCX 版本差异 |

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

## LangChain 集成

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

```python
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 中表示修订：

| 语法 | 含义 | 示例 |
|------|------|------|
| `{++text++}` | 插入内容 | `{++新增段落++}` |
| `{--text--}` | 删除内容 | `{--待删除文字--}` |
| `{==text==}` | 高亮 | `{==重点内容==}` |
| `{>>comment<<}` | 批注气泡 | `{>>建议修改此处<<}` |

**canonical 编辑对形式：**

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

资料来源：[README.md](https://github.com/dealfluence/adeu/blob/main/README.md)

## 最佳实践

### 文档读取流程

```mermaid
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 格式（标题、粗体、斜体、段落分隔）

### 社区已知限制

| 问题 | 说明 | 状态 |
|------|------|------|
| 单次修改生成多 ID | 替换跨越多个 XML run 的文本时会产生多个 Chg:N | 待修复 |
| 表格编辑限制 | `insert_row`/`delete_row` 不支持 Live Word 画布 | 设计限制 |
| ID 漂移 | accept/reject 后 ID 会改变 | 设计限制 |

资料来源：[GitHub Issue #16](https://github.com/dealfluence/adeu/issues/16)

## 扩展与生态

### n8n 集成

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

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

资料来源：[Release v1.7.3](https://github.com/dealfluence/adeu/releases/tag/v1.7.3)

### Skill 封装

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

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

资料来源：[python/skills/adeu-redlining/SKILL.md](https://github.com/dealfluence/adeu/blob/main/python/skills/adeu-redlining/SKILL.md)

---

<a id='live-word-integration'></a>

## Live MS Word 集成（Windows）

### 相关页面

相关主题：[MCP 协议集成配置](#mcp-setup), [Python 引擎详解](#python-engine)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [python/src/adeu/mcp_components/tools/document.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/tools/document.py)
- [langchain/langchain_adeu/apply_changes.py](https://github.com/dealfluence/adeu/blob/main/langchain/langchain_adeu/apply_changes.py)
- [node/packages/mcp-server/src/index.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/mcp-server/src/index.ts)
- [python/skills/adeu-redlining/SKILL.md](https://github.com/dealfluence/adeu/blob/main/python/skills/adeu-redlining/SKILL.md)
- [README.md](https://github.com/dealfluence/adeu/blob/main/README.md)
</details>

# Live MS Word 集成（Windows）

## 概述

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

### 核心价值

| 特性 | 说明 |
|------|------|
| **实时编辑** | 编辑操作直接作用于活动文档画布 |
| **无缝协作** | 用户在 Word 中看到的更改与 AI 操作同步 |
| **离线文件兼容** | 同时支持从磁盘读取和从活动文档读取 |
| **本地化处理** | 利用 Windows 平台的 COM 接口实现深度集成 |

资料来源：[README.md](https://github.com/dealfluence/adeu/blob/main/README.md)

---

## 架构设计

### 工作原理

```mermaid
graph TD
    A[用户打开 Word 文档] --> B[Adeu MCP Server]
    B --> C{操作模式选择}
    C -->|文件路径为空| D[连接活动 Word 实例]
    C -->|提供文件路径| E[读写磁盘文件]
    
    D --> F[COM 接口通信]
    E --> G[python-docx 操作]
    
    F --> H[实时 XML 注入]
    G --> H
    H --> I[Word Track Changes]
    
    I --> J[用户立即看到修订]
```

### 两种工作模式

Adeu 支持两种文档操作模式，开发者可根据使用场景选择：

| 模式 | 触发条件 | 适用场景 |
|------|----------|----------|
| **Live Canvas 模式** | `file_path` 参数留空 | 用户正在编辑文档，需要实时反馈 |
| **磁盘文件模式** | 提供完整 `file_path` | 批量处理、自动化流水线、无人值守操作 |

资料来源：[python/src/adeu/mcp_components/tools/document.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/tools/document.py)

---

## 工具接口

### 读取文档（read_docx）

#### Windows 特有扩展

```python
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"
)
```

当用户已打开 Word 文档且未提供 `file_path` 时，系统自动连接到活动文档实例并读取当前内容。这对于需要获取用户正在查看的文档状态时特别有用。

#### 工具参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `file_path` | `str` | `""` | 文件路径，留空则读取活动文档 |
| `clean_view` | `bool` | `false` | 是否显示最终接受的文本 |
| `mode` | `str` | `"full"` | 显示模式：`full`、`outline`、`appendix` |
| `page` | `int` | `1` | 分页页码 |

资料来源：[langchain/langchain_adeu/read_docx.py](https://github.com/dealfluence/adeu/blob/main/langchain/langchain_adeu/read_docx.py)

### 批量处理（process_document_batch）

#### Windows 特有扩展

```python
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"
)
```

在 Live Canvas 模式下，所有编辑操作（`modify`、`accept`、`reject`、`reply`）都会实时应用到活动 Word 文档，用户可以在 Word 中立即看到修订标记和批注。

#### 支持的操作类型

| 操作类型 | 说明 | 适用场景 |
|----------|------|----------|
| `modify` | 搜索替换文本 | 修改条款内容 |
| `accept` | 接受指定修订 | 确认某处修改 |
| `reject` | 拒绝指定修订 | 撤销某处修改 |
| `reply` | 回复批注 | 讨论修订内容 |
| `insert_row` | 插入表格行 | **仅磁盘模式** |
| `delete_row` | 删除表格行 | **仅磁盘模式** |

> ⚠️ **注意**：`insert_row` 和 `delete_row` 是结构性编辑，不支持在 Live Word 画布上操作，仅限于磁盘文件模式。

资料来源：[python/src/adeu/mcp_components/tools/document.py](https://github.com/dealfluence/adeu/blob/main/python/src/adeu/mcp_components/tools/document.py)

---

## 身份验证与授权

### 桌面认证机制

Adeu 实现了专门的桌面认证模块来处理 Windows 平台的 COM 连接。该模块确保只有经过授权的 AI Agent 才能访问和修改活动 Word 文档。

```python
# 核心认证流程
def authenticate_desktop_session() -> bool:
    """验证当前桌面会话是否有权访问 Word 实例"""
    # 验证步骤...
    return session_valid
```

### 安全考虑

| 安全措施 | 说明 |
|----------|------|
| **会话验证** | 确保操作来自合法桌面会话 |
| **COM 接口隔离** | 限制对 Word 实例的直接访问 |
| **操作审计** | 所有 Live 编辑操作均有记录 |

---

## 状态管理

### ID 波动性警告

```python
PROCESS_BATCH_OPERATIONS_DESC = (
    "ID VOLATILITY: 'Chg:N' and 'Com:N' shift between document states. "
    "Always call `read_docx` immediately before any accept/reject/reply — "
    "do not reuse IDs from earlier in the conversation.\n\n"
)
```

由于 Live Word 环境中文档状态可能随时变化（用户手动编辑、保存操作等），修订 ID 和批注 ID 具有波动性。每次执行 `accept`、`reject` 或 `reply` 操作前，必须调用 `read_docx` 获取最新的 ID 映射。

```mermaid
graph LR
    A[读取文档] --> B[获取当前 Chg:N IDs]
    B --> C[执行操作]
    C --> D{需要新 ID?}
    D -->|是| E[重新读取文档]
    E --> F[获取新 ID 映射]
    F --> C
    D -->|否| G[完成操作]
```

资料来源：[langchain/langchain_adeu/apply_changes.py](https://github.com/dealfluence/adeu/blob/main/langchain/langchain_adeu/apply_changes.py)

---

## 使用工作流

### 典型场景：AI 辅助审阅

```
┌─────────────────────────────────────────────────────────────────┐
│                      AI Agent 工作流程                           │
├─────────────────────────────────────────────────────────────────┤
│  1. 用户在 Word 中打开合同文档                                    │
│  2. Agent 调用 read_docx(file_path="") 连接活动文档               │
│  3. Agent 分析内容，提出修改建议                                  │
│  4. Agent 调用 process_document_batch 修改条款                   │
│  5. 用户在 Word 中实时看到 Track Changes                          │
│  6. 用户决定接受/拒绝修改                                         │
│  7. Agent 调用 read_docx 获取最新状态                            │
└─────────────────────────────────────────────────────────────────┘
```

### 最佳实践

| 实践 | 原因 |
|------|------|
| **操作前必读** | 确保获取最新文档状态和 ID |
| **原子性操作** | 每次批量提交独立的逻辑变更 |
| **避免依赖链** | 不要在一个批次中链接依赖修改 |
| **及时同步** | 用户手动修改后，Agent 应重新读取 |

资料来源：[python/skills/adeu-redlining/SKILL.md](https://github.com/dealfluence/adeu/blob/main/python/skills/adeu-redlining/SKILL.md)

---

## 技术限制

### 平台限制

| 限制项 | 说明 |
|--------|------|
| **仅 Windows** | Live 集成仅支持 Windows + Word 环境 |
| **需要 Word** | 必须安装 Microsoft Word 客户端 |
| **COM 依赖** | 依赖 pywin32 或 win32com |

### 功能限制

| 限制项 | 说明 |
|--------|------|
| **表格结构性编辑** | `insert_row`/`delete_row` 不支持 Live 模式 |
| **并发冲突** | 同时编辑可能导致状态不一致 |
| **ID 回收** | 删除修订后 ID 可能被重用 |

---

## 多语言实现

### TypeScript MCP Server

```typescript
const 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";
```

Node.js 版本的 MCP Server 同样实现了 Live Word 集成功能，提供与 Python 版本一致的操作接口。

### LangChain 集成

```python
class AdeuReadDocx(BaseTool):
    """LangChain tool: read a .docx file into projected Markdown."""
    
    name: str = "adeu_read_docx"
    description: str = _DESCRIPTION
    args_schema: type[BaseModel] = AdeuReadDocxInput
    response_format: Literal["content_and_artifact"] = "content_and_artifact"
```

通过 LangChain 集成，开发者可以将 Live Word 功能嵌入到更复杂的 AI 工作流中。

资料来源：[node/packages/mcp-server/src/index.ts](https://github.com/dealfluence/adeu/blob/main/node/packages/mcp-server/src/index.ts)

---

## 社区反馈与未来方向

### 相关社区议题

| Issue | 关注点 |
|-------|--------|
| [#1: VS Code 可视化](https://github.com/dealfluence/adeu/issues/1) | 社区希望创建非 AGPL 工作流来实现跨平台可视化，Live Word 集成目前依赖 python-docx（AGPL） |
| [#19: 多渠道自动部署](https://github.com/dealfluence/adeu/issues/19) | MCP 渠道的自动部署需求 |

### 已知问题

| 问题 | 描述 | 影响 |
|------|------|------|
| 单一逻辑编辑产生多个 Chg ID | 当替换包含多种格式的文本时，XML 会产生多个修订标记 | 用户可能需要多次 accept/reject |

资料来源：[GitHub Issues #1](https://github.com/dealfluence/adeu/issues/1)、[#16](https://github.com/dealfluence/adeu/issues/16)

---

## 快速入门

### 前置条件

```bash
# 安装 Adeu
pip install adeu

# 确保已安装 Microsoft Word
# 确保 Windows 环境可访问 COM 接口
```

### 基本使用

```python
from adeu import AdeuClient

# 连接到活动 Word 文档
client = AdeuClient()

# 读取当前活动文档
doc = client.read_docx()

# 应用修改
client.process_document_batch(
    changes=[
        {
            "type": "modify",
            "target_text": "原条款内容",
            "new_text": "修改后的条款内容",
            "comment": "根据法规更新"
        }
    ],
    author_name="AI Reviewer"
)
```

### Claude Desktop 配置

```json
{
  "mcpServers": {
    "adeu": {
      "command": "uvx",
      "args": ["adeu", "mcp-server"]
    }
  }
}
```

资料来源：[README.md](https://github.com/dealfluence/adeu/blob/main/README.md)

---

## 总结

Live MS Word 集成是 Adeu 在 Windows 平台上的核心差异化功能，它通过 COM 接口直接与 Microsoft Word 通信，实现实时、交互式的文档审阅体验。该功能使 AI Agent 能够作为"虚拟法律助手"，在用户面前完成条款分析、修订建议和协商支持等工作。

对于跨平台需求或需要避免 AGPL 依赖的场景，可以考虑使用磁盘文件模式与 VS Code 等编辑器的组合方案。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: dealfluence/adeu; human_manual_source: deepwiki_human_wiki -->