OfficeAgent.NET

OfficeAgent.NET

OfficeAgent.NET 是一个基于 Open XML SDK 构建的 .NET 文档自动化库。它的直接 .NET API 可将文档意图转换为经过验证的类型化操作，用于处理 Word .docx、PowerPoint .pptx 和 Excel .xlsx 包。

可用它来生成文档和演示文稿、进行有针对性的编辑、更新表格、样式和图像，或管理批注和审阅状态。MCP 服务以及 Microsoft Agent Framework 和 Microsoft.Extensions.AI 的适配器，都是同一引擎的可选接口。应用程序也可以直接使用该引擎，而无需 MCP。

例如，可对 Word 文档进行有针对性的编辑，并保留可供审阅的结果：

本项目的功能

Office Open XML 文件是由相关 XML 部件组成的包。即使是微小改动，也可能影响文本运行、样式、编号、批注、内容控件或修订标记。OfficeAgent.NET 会处理这些特定于文档的工作。模型使用结构化文档数据和可序列化为 JSON 的操作，例如“将此条款替换为修订”或“向此表格添加一行”。

同一引擎提供以下三种形式：

• 面向支持 Model Context Protocol 的 Agent 的 MCP 服务；
• 适用于 Microsoft Agent Framework 和 Microsoft.Extensions.AI 的工具；
• 面向希望直接控制工作流的应用程序的 .NET API。

它支持 Word .docx、PowerPoint .pptx 和 Excel .xlsx；一个客户端会将每份文档路由到负责处理它的模块。若要用于依赖 Office 布局或计算引擎的工作流，请先阅读范围与限制。

可以构建什么

领域	支持的工作流
Word 创建和编辑	创建 .docx 文件；检查和修改文本、段落、表格、图片、样式、内容控件、页眉、页脚、注释、页面设置和文档属性
Word 审阅	阅读和管理批注，保留或解决审阅状态，为每个计划设置一个修订者身份，并将受支持的编辑记录为修订
PowerPoint 创建和编辑	构建或更新演示文稿，包括幻灯片、版式、文本、表格、可原生编辑的图表、图片、媒体、备注、批注、节、切换效果和动画
Excel 检查和编辑	检查工作表、表格和有界范围；查找原始值或显示值；设置单元格和公式；向表格追加行；管理单元格备注
模板生成	绑定唯一的 Word 内容控件标签或 PowerPoint 形状名称，扩展重复的 Word 表格行，并创建有界批次，且每个输出都有一份回执
Word 比较	以只读方式比较受支持的正文段落文本；仅当所有其他包内容均未更改时，生成绑定快照的原生修订计划
Agent 和应用集成	通过 stdio 或 HTTP 使用 MCP、Microsoft Agent Framework 工具或直接使用 .NET API，并通过 SHA-256 应用回执和宿主提供的审计执行者身份记录操作
文档访问	使用有界文件系统根目录、SharePoint、内存会话或自包含的内联内容

选择起点

我想要……	从这里开始
判断 OfficeAgent 是否适合我的应用	库选择指南
尝试针对性的 Word 编辑	尝试编辑 Word 文档
在 Claude Desktop 中使用 OfficeAgent，或在不安装 .NET 的情况下运行服务（从 1.2.0 起）	独立下载
从头创建 Word 文档	创建文档
创建或编辑 PowerPoint 演示文稿	PowerPoint 支持
检查或编辑 Excel 工作簿	Excel 支持
连接 Codex、Claude Code、Copilot Studio 或 Microsoft 365 Copilot	部署和客户端设置
在 C# 中使用 OfficeAgent	入门指南
向 Microsoft Agent Framework Agent 添加工具	Agent 集成
托管 MCP 服务或使用 SharePoint	MCP 服务和文档提供程序
添加按用户授权的托管连接	托管网关参考
添加可选的 PDF／页面图像渲染	视觉渲染
在未配置存储的情况下编辑文档	无存储时处理文档
运行带修订记录的审阅工作流	可选的 Word 文档审阅技能
构建 .NET、MCP 或 Agent Framework 集成	可选的 officeagent-integration 技能
构建合同审阅 Agent	ContractReview 示例
填充报价模板或比较 Word 文档	模板和比较工作流
根据新工作簿更新本月的报告或演示文稿	报告刷新
翻译文档并保留其格式	翻译文档
在整个文件夹中重命名公司或更新免责声明	一次编辑多个文档
查看支持、兼容性或安全策略	支持和安全
参与贡献	贡献

尝试一次 Word 编辑

这个小工作流演示 OfficeAgent 可以在不破坏其结构的情况下修改现有的 OOXML 文件。它使用修订模式，因为在 Word 中验证结果非常容易；审阅只是更广泛的文档操作集的一部分。

安装此版本所记录的精确服务版本：

dotnet tool install --global OfficeAgent.Mcp --version 1.2.0

创建一个供 Agent 工作的文件夹，并将示例合同下载到其中 —— 这是一份虚构的服务协议，其中包含一个需要修改的条款、一个表格、一条未解决的批注，以及一处待处理的修订标记：

mkdir -p ~/officeagent-documents
curl -Lo ~/officeagent-documents/services-agreement.docx \
  https://raw.githubusercontent.com/ilia-sokolov/OfficeAgent.NET/v1.2.0/samples/documents/services-agreement.docx

PowerShell：

$officeAgentDocuments = Join-Path $env:USERPROFILE "officeagent-documents"
New-Item -ItemType Directory -Force $officeAgentDocuments | Out-Null
Invoke-WebRequest `
  https://raw.githubusercontent.com/ilia-sokolov/OfficeAgent.NET/v1.2.0/samples/documents/services-agreement.docx `
  -OutFile (Join-Path $officeAgentDocuments "services-agreement.docx")

你自己的任何 .docx 文件也可以 —— 示例只是为你提供了一个已经包含批注和待处理修订的文件。

用 Claude Code 注册该服务，指向该文件夹，不要指向其他任何位置：

claude mcp add \
  --env OfficeAgent__FileSystemConnections__0__ConnectionId=documents \
  --env OfficeAgent__FileSystemConnections__0__RootPath=$HOME/officeagent-documents \
  --transport stdio \
  officeagent -- officeagent-mcp --stdio

PowerShell：

claude mcp add `
  --env OfficeAgent__FileSystemConnections__0__ConnectionId=documents `
  --env "OfficeAgent__FileSystemConnections__0__RootPath=$officeAgentDocuments" `
  --transport stdio `
  officeagent -- officeagent-mcp --stdio

对于这个审阅专用的工作流，你可以选择在启动客户端之前安装 word-document-review 技能。

然后这样提问：

在 services-agreement.docx 中，将付款期限从三十天改为四十五天。

当客户端正确调用 OfficeAgent 时的预期结果：apply_plan 报告 writeOutcome: "committed" 并返回一个输出 id，且第 3 条读作四十五天，并作为可接受或拒绝的修订标记呈现。在 Word 中打开该输出并验证更改。回归测试还会验证示例中现有的表格、批注、先前的付款修订标记和标题均以其经过测试的 XML 语义保留存在。它并不声称每个不相关的 OOXML 部分都逐字节一致；请参阅有限的保留证据。

如果 Agent 未调用 apply_plan，或者 writeOutcome 不是 committed，请不要将编辑报告为已完成。对于 unknown 或 writtenNotRegistered，请保留 possibleOutput 并遵循存储恢复，而不是盲目重试。

示例还有什么用途 —— 审阅批注、接受修订、编辑表格。

接下来，尝试创建 Word 文档、生成 PowerPoint 演示文稿，或使用直接的 .NET 工作流。

如果它不起作用

claude mcp list 显示 officeagent 失败	检查 RootPath 是否为指向存在目录的绝对路径。
Agent 说找不到该文档	使用相对名称，或仍能解析到 RootPath 内的绝对路径。
保存时出现 io-error	在 Word 中关闭该文件，然后检查文件系统权限和可用磁盘空间。
outcome-unknown 或 registration-failed	不要重复该编辑。保留 possibleOutput 并遵循恢复流程以确定输出是否已存在。

配置更广泛的工作流

上面的快速开始刻意只保留能跑通的最小配置。有四个设置可以扩展它：

设置	增加的能力
OfficeAgent__AllowCreation=true	create_document，这样“在 brief.docx 中起草一份项目简介”会创建新文件，而不是失败
OfficeAgent__FileSystemConnections__0__AllowedExtensions__0=.docx 加上 OfficeAgent__FileSystemConnections__0__AllowedExtensions__1=.pptx	在一个连接上同时支持 Word 和 PowerPoint。声明这个列表会替换 .docx 默认值。为演示文稿设置 OfficeAgent__FileSystemConnections__0__DefaultChangeMode=Direct，并对该混合连接上可审阅的 Word 编辑显式发送 "mode": "Tracked"。
OfficeAgent__EphemeralConnectionId=session	显式命名内存中的会话连接。即使完全没有配置，服务器也已经会回退到这样一个连接 - 这用于让它与存储并存运行，或使用不同的 id
OfficeAgent__AllowInlineContent=true	以 base64 携带文档的工具，用于单次自包含调用

超过几个设置后，改用文件 - 同一个 OfficeAgent 节，其中列表 就是列表：

{
  "OfficeAgent": {
    "AllowCreation": true,
    "FileSystemConnections": [
      {
        "ConnectionId": "documents",
        "RootPath": "C:\\officeagent-documents",
        "AllowedExtensions": [ ".docx", ".pptx" ],
        "DefaultChangeMode": "Direct"
      }
    ]
  }
}

同样的配置也可作为 samples/config/word-and-powerpoint.json 获取。使用前请修改 RootPath。

claude mcp add --transport stdio officeagent -- officeagent-mcp --stdio --config ./officeagent.json

环境变量仍然会覆盖文件。Windows、PowerShell、其他 MCP 客户端、 HTTP 托管和 SharePoint 见 部署和客户端设置；每项设置都列在 MCP 服务 中。

Word 审阅的可选指南

skills/word-document-review 讲解了审阅 循环：编辑前先阅读批注和待处理修订，将可审阅的 Word 编辑保留为 红线标记，多步骤工作使用文档 id，并根据稳定的错误码恢复。 安装指南 给出了 Claude Code 和 Codex 的完整 Bash 和 PowerShell 步骤， 包括在全新机器上安装和验证。 只有当任务需要这种审阅纪律时才需要该技能；文档创建、 普通的直接编辑和 PowerPoint 工作流无需它即可使用服务器。

应用集成的可选指南

skills/officeagent-integration 帮助 实现 Agent 优先选择直接的 .NET API，仅在需要时添加 MCP 或 Microsoft Agent Framework， 并运行已安装包配方，用于修订跟踪编辑、模板填充 和完整计划比较。安装指南 涵盖这两个 技能，并明确说明技能不会安装运行时、NuGet 包或 MCP 服务。

什么会到达模型

inspect 和 find 工具会把文档文本和结构返回给模型——这就是它 定位编辑的方式。文件系统和 SharePoint 操作会让包保持在不透明 id 之后。 内联工具每次调用都会以 base64 携带整个文件。如果 Agent 执行这些调用，会话导入/导出也会以 base64 携带 包；宿主集成则可以在模型上下文之外移动 这些字节。请连接适合该数据的存储和模型提供商。

独立服务器不为 HTTP 托管附带任何身份验证层；请将它置于你自己的身份验证之后， 或从已通过身份验证的 HostedGateway 参考 开始。文件系统 根目录是信任边界：其 ACL 必须阻止不受信任的主体在服务器运行期间创建、 重命名或替换条目。

.NET 快速开始

安装核心包和 Word 模块：

dotnet add package OfficeAgent.Core
dotnet add package OfficeAgent.Word

注册服务并配置文档提供程序后，编辑循环如下所示：

var client = services.GetRequiredService<OfficeAgentClient>();
var doc = await client.RegisterAsync("workspace", "/srv/workspace/contract.docx");

var inspect = await client.InspectAsync("workspace", doc.ItemId);
var hit = (await client.FindAsync(
    "workspace", doc.ItemId, new FindQuery("Acme Corp"))).First();

var plan = new DocumentPlan
{
    Snapshot = inspect.Snapshot,
    Revision = new RevisionMetadata { Author = "OfficeAgent Quickstart" },
    Operations = new PlanOperation[]
    {
        new ChangeTextOp
        {
            Target = hit.Anchor,
            With = "Globex Inc.",
            Mode = ChangeMode.Tracked
        }
    }
};

var preview = await client.PreviewAsync("workspace", doc.ItemId, plan);
if (preview.IsValid)
    await client.CommitAsync("workspace", doc.ItemId, plan);

Revision.Author 是 Word 为修订内容显示的名称。它不是经过身份验证的执行者身份。请参阅修订标识与审计凭据。

完整示例（包括服务注册和读取已保存的文件）请参阅入门指南。最小化的直接 .NET 示例针对内置的虚构合同运行，因此不需要 MCP 客户端、语言模型或你自己的文档：

dotnet run --project samples/QuickEdit -- \
  samples/documents/services-agreement.docx quickedit-output.docx

在 Word 中打开 quickedit-output.docx，验证付款条款是否为修订内容，同时现有修订、批注、表格和标题保持不变。QuickEdit 也支持为你自己的文档指定精确的源文本和替换文本。发行版还附带 quickedit-sample.zip，这是一个基于包的副本，可在仓库外部针对已发布的 NuGet 包运行。

仓库还包含一个直接使用 IChatClient 的 Word 编辑示例和一个交互式 Agent Framework 示例，以及一个完整的合同审查 Agent，它将模型判断与经验证的文档写入分离。TemplateBatch 示例从一个带标签的模板生成两份报价，而 DocumentComparison 将涵盖的正文段落差异转换为可审阅的 Word 红线标记。DocumentAssembly 示例将提案、工作说明书和附录合并为一个可编辑的包，并附带多来源审计凭据。其格式和兼容性范围请参阅 Word 文档组装。

工作原理

每次编辑都遵循相同的四个步骤：

1. 检查 返回文档的结构化映射：其大纲、 段落、样式、内容控件、表格、图像和修订。
2. 查找 搜索文本，并为每个匹配项返回经过内容验证的锚点。
3. 预览 根据当前文档验证计划，并报告 拟议的更改，但不写入。
4. 应用 提交完整计划，并通过配置的 提供程序保存。

计划（DocumentPlan）是一个类型化、可 JSON 序列化的操作列表。锚点 同时记录位置和该位置预期的内容。如果内容 或可选的文档快照已更改，验证会失败，而不是静默地 定位到其他位置。所有操作要么应用于同一个内存事务， 要么都不应用；后续提供程序故障仍可能使存储状态不确定，因此调用方必须在重试前检查 writeOutcome。

Word 模块支持对文本、段落、表格、图像、样式、 内容控件、评论线程、脚注和尾注、页面几何和 分页、文档属性以及修订记录的更改。具有 Word 修订 表示的操作会在连接请求时记录红线 - 插入的条款、 删除的行和重新设置样式的标题都会作为审阅者接受或拒绝的修订返回， 而不仅仅是被替换的短语。图像缩放会直接应用，因为 WordprocessingML 没有绘图尺寸的修订表示。 PowerPoint 模块实现了一组广泛且明确记录在案的幻灯片 操作：文本、项目符号、文本运行和段落格式、模板 槽位、样式复制、表格、图像、文本框、嵌入的视频和音频、 演讲者备注、可解析的评论、页脚和幻灯片编号、节、 切换和动画，以及幻灯片生命周期 - 添加、删除、 重新排序和复制。一个计划中的多次幻灯片插入可以端到端地创作一份幻灯片， 因此一次调用就能从无到有生成完整的演示文稿。它不支持的 任何动词都会被明确指出，而不是静默跳过。完整的操作 模式记录在 Document plans 中，幻灯片 相关细节记录在 PowerPoint support 中。

文档通过配置的提供程序访问。注册后， 编辑调用使用 (connectionId, documentId) 对，而不是存储路径 或凭据。文件系统提供程序将其注册限制在其根目录内； SharePoint 提供程序使用其配置身份的权限。 CreateAsync 在连接内启动一个新文档：请求的 .docx 或 .pptx 扩展名会选择已注册的空白文档工厂。引擎 在内存中应用可选的初始计划，然后请求 提供程序创建并注册它，且不覆盖现有名称。

文档

指南	涵盖内容
文档中心	学习路径、包映射以及完整的文档集
库选型指南	支持的作业、非目标、包选择、替代方案，以及经过验证的 .NET 直接用法示例
快速上手	从服务注册到读取结果的完整编辑流程
核心概念	锚点、快照、计划、提供程序、事务和功能
C# API 参考	为每个库包生成的公共类型和成员
文档计划	每种操作的 JSON 结构和验证规则
文档提供程序	文件系统、SharePoint、保存模式以及自定义提供程序
PowerPoint 支持	幻灯片寻址、演示文稿模块实现的动词，以及它保留的内容
模板填充与比较	批量绑定、重复 Word 行、比较限制以及红线生成
Agent 集成	Microsoft Agent Framework 和 Microsoft.Extensions.AI 工具
MCP 服务	服务配置、传输方式、安全注意事项和工具契约
部署与客户端设置	Codex、Claude Code、Microsoft Copilot 客户端、容器和 Azure
运维	并发、流、取消、遥测和生产环境注意事项
故障排查	启动、注册、验证、并发和提供程序故障
失败模式	常见的计划错误以及后续处理方式
发布	发布到 NuGet、MCP Registry 和 GitHub

贡献

缺陷报告、文档修复、新的文档操作、提供程序集成以及有针对性的测试用例 都是有用的贡献。如果你发现了问题， 请提交 issue，说明涉及的 文档功能、你尝试的操作，以及错误或 意外结果。请勿附上机密文档；一个经过脱敏的小型 复现示例就足够了。

要参与代码开发，请安装 .NET 10 SDK 和 .NET 8 运行时，fork 仓库，然后运行：

dotnet build OfficeAgent.NET.sln
dotnet test OfficeAgent.NET.sln

在开始较大的改动之前，尤其是会更改公共类型或 JSON 传输格式的改动，请先提交 issue 以便讨论设计方案。有关代码风格、测试和 pull request 期望， 请参阅 CONTRIBUTING.md。

范围和限制

OfficeAgent.NET 可编辑 Word .docx、PowerPoint .pptx 和 Excel .xlsx 文件； 它不会自动化操作 Office 桌面应用程序。

演示文稿模块会针对每项操作拒绝演示文稿不支持的动词—— setProperty、revision、pageSetup、insertBreak 和 note，而不是只执行计划的一部分；也会拒绝对任何支持跟踪模式的动词显式启用跟踪模式。PresentationML 没有修订标记模型，因此仅 Word 支持跟踪更改；幻灯片也没有页眉（页眉属于备注和讲义的概念）。动画仅支持可表示为经过筛选的 p:animEffect 的效果；对于飞入、缩放和运动路径，会直接拒绝，而非近似处理。请参阅PowerPoint 支持，了解演示文稿支持和不支持的操作。

核心引擎不会渲染页面、计算 Word 域或计算 Excel 公式。 公式编辑会将工作簿设为在 Excel 打开时重新计算。可选的 OfficeAgent.Excel.Calculation 软件包可计算经过验证的一组 Excel 函数，并将结果写入缓存值；请参阅公式计算。依赖分页、目录渲染或域重新计算的操作不属于核心范围。预览会报告结构变化。可选的渲染软件包可通过外部进程生成基于 PDF 的页面图像，但尚不能检测内容溢出或页面适配问题。请在有代表性的文档上测试工作流，并确保对重要编辑保留人工审核环节。

在基于它构建之前，还应了解另外两项限制：

• 节省的令牌数取决于连接方式。 通过 ID 指定文档可避免将软件包内容带入对话；使用 fidelity 和分页可以缩小检查范围——节省的令牌主要来自这两点。内联 *_content 工具则是有意设置的例外：它们会在两个方向上都以 base64 形式传递整个文件，消耗的令牌数与文件大小成正比。它们适用于一次自包含的调用，不适合一连串编辑——如果让模型在第二次编辑时传回几 KB 的文档，模型很容易无法完整复现，导致后续操作失败。如果还要进行多次编辑，请使用连接或会话连接。
• 审核指南是可选的。 对于审核任务，仅靠服务端并不能确保 Agent 在编辑前阅读未解决的批注或选择修订标记。word-document-review 技能介绍了该工作流；若没有它，审核行为取决于模型和提示词。

商业支持

OfficeAgent.NET 采用 MIT 许可证，可自托管。dotaction 提供商业支持和部署协助： 联系 dotaction。 该服务与项目相互独立：它受自身协议约束，不会改变该库的许可证、兼容性承诺或社区支持政策。

隐私政策

OfficeAgent.NET 在你的计算机或自有服务上运行，不会收集任何信息：没有遥测数据、分析数据，也不会向外部服务器发送请求。它只读取和写入提供给它的文件夹、SharePoint 库或会话连接中的文档；除主机为 SharePoint 连接配置的 Microsoft Graph 外，不会联系任何第三方。工具结果会按照使用它的 AI 助手自身的政策提供给该助手。完整政策（包括存储的内容及存储时长）见 PRIVACY.md。

许可证

MIT。请参阅 LICENSE。