Safe DOCX 套件

English | Español | 简体中文 | Português (Brasil) | Deutsch

safe-docx 由 UseJunior 提供 — 让编程智能体也能处理文书工作。

属于 UseJunior 开发者工具 系列。

Safe Docx 是一个开源的 TypeScript 技术栈，用于对现有的 Microsoft Word .docx 文件进行精细化编辑。它专为智能体提出修改建议、而人类仍需进行可靠且保留格式的文档编辑的工作流而构建。

如果您使用 AI 审阅合同，最耗时的步骤通常是在 Word 中应用已接受的建议。Safe Docx 将其转化为确定性的工具调用。

为什么存在这个项目

AI 编程 CLI 在处理代码和文本文件方面表现出色，但在处理现有的 .docx 编辑时却很薄弱。商业和法律工作流仍然依赖 Word 文档，因此我们构建了一个原生的 TypeScript 路径，用于：

• 以 token 高效的格式读取和搜索现有文档

• 进行精细化编辑而不破坏格式

• 生成干净/带修订记录的输出和修订提取工件

使命：让编程智能体也能处理文书工作。Safe Docx 专注于对现有 Word 文件进行确定性编辑，确保格式和审阅语义在自动化过程中得以保留。

Related MCP server: DOCX MCP Server

定位

Safe Docx 针对需要对现有 .docx 文件进行确定性、本地优先编辑的智能体工作流进行了优化：

• 用于编辑、对比、修订提取、批注、脚注和布局的类型化 MCP 工具

• 具有测试证据和可追溯性工件的可审计行为

• TypeScript 运行时分发，在支持的使用场景下无需 Python 或 LibreOffice

Safe Docx 不旨在取代生成优先的 .docx 库。

受信任方

• Am Law 前 10 强律所 — 多步骤合同翻译流水线

• 150 名律师的区域性律所 — 处理了超过 2200 万 token 的合同标记

• Gemini CLI — 兼容的 Word 编辑 MCP 扩展

从这里开始

npx -y @usejunior/safe-docx

有关详细设置和工具参考，请参阅 packages/docx-mcp/README.md。

示例：智能体编辑合同

当您在安装了 Safe Docx 的情况下提示编程智能体（Claude Code、Cursor、Gemini CLI）时，智能体会进行如下 MCP 工具调用：

User: Edit the NDA at ~/docs/NDA.docx — change the governing law
      from "State of New York" to "State of Delaware" and save both
      a clean copy and a tracked-changes copy.

Agent calls:

  1. read_file(file_path="~/docs/NDA.docx", format="toon")
     → Returns paragraphs with stable IDs: _bk_1, _bk_2, ...

  2. grep(file_path="~/docs/NDA.docx", pattern="State of New York")
     → Match in paragraph _bk_47

  3. replace_text(
       file_path="~/docs/NDA.docx",
       target_paragraph_id="_bk_47",
       old_string="State of New York",
       new_string="State of Delaware",
       instruction="Change governing law to Delaware"
     )

  4. save(
       file_path="~/docs/NDA.docx",
       save_to_local_path="~/docs/NDA-clean.docx",
       tracked_save_to_local_path="~/docs/NDA-tracked.docx",
       save_format="both"
     )

智能体会自动处理工具调用。您将获得一个干净的文件和一个供人工审阅的修订记录文件。

MCP 快速入门

Claude Code

claude mcp add safe-docx -- npx -y @usejunior/safe-docx

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)：

{
  "mcpServers": {
    "safe-docx": {
      "command": "npx",
      "args": ["-y", "@usejunior/safe-docx"]
    }
  }
}

Gemini CLI

{
  "mcpServers": {
    "safe-docx": {
      "command": "npx",
      "args": ["-y", "@usejunior/safe-docx"]
    }
  }
}

任何 MCP 客户端

• 命令： npx

• 参数： ["-y", "@usejunior/safe-docx"]

• 传输： stdio

Safe Docx 的优化方向

• 对现有 .docx 文件的存量编辑

• 保留格式的文本替换和段落插入

• 批注和脚注工作流

• 用于审阅的修订记录输出 (download, compare_documents)

• 作为结构化 JSON 的修订提取 (extract_revisions)

Safe Docx 不优化的方向

Safe Docx 不是一个从零开始的文档生成工具包。

如果您的主要需求是从模板/程序化布局生成新的 .docx 文件，请使用诸如 docx 之类的包。

目前的本地 Safe Docx 运行时也暂时有意拒绝 Word 模板文件 (.dotx)。请在打开之前将模板转换为普通的 .docx 文档。

文档系列

本仓库中的自动化测试覆盖

• 通用纸张风格的互惠 NDA 测试

• Bonterms 互惠 NDA 测试

• 意向书测试

• ILPA 有限合伙协议修订测试

专为复杂的法律和商业 .docx 类设计

• NVCA 融资表格

• YC SAFE

• 发行备忘录

• 订单表格和服务协议

• 有限合伙协议

包

• @usejunior/docx-core：现有 .docx 文档的原语 + 对比引擎

• @usejunior/docx-mcp：MCP 服务器实现和工具界面

• @usejunior/safe-docx：规范的最终用户安装名称 (npx -y @usejunior/safe-docx)

• @usejunior/safedocx-mcpb：私有 MCP 包封装

可靠性和信任面

• 工具模式由 packages/docx-mcp/src/tool_catalog.ts 生成。

• OpenSpec 可追溯性矩阵：packages/docx-mcp/src/testing/SAFE_DOCX_OPENSPEC_TRACEABILITY.md

• 假设矩阵：packages/docx-mcp/assumptions.md

• 一致性指南：docs/safe-docx/sprint-3-conformance.md

常见问题解答

什么是 Safe Docx？

一个以 TypeScript 为先的 DOCX 编辑栈，适用于需要对现有 Word 文档进行确定性、保留格式编辑的编程智能体工作流。

这在编辑过程中能保留格式吗？

这是核心设计目标。工具界面围绕精细化操作（replace_text、insert_paragraph、布局控制）构建，尽可能保留文档结构和格式语义。

在正常运行时需要 .NET、Python 或 LibreOffice 吗？

不需要。支持的运行时使用 JavaScript/TypeScript 配合 jszip + @xmldom/xmldom。

这能从零开始生成合同吗？

不是主要重点。对于从零开始的生成，请使用诸如 docx 之类的包。

这在仓库内测试中测试过哪些文档类型？

互惠 NDA（包括 Common Paper/Bonterms 风格的测试）、意向书和 ILPA 有限合伙协议修订测试。

这只适用于律师吗？

不是。同样的问题也出现在人力资源、采购、财务、销售运营和其他文书工作繁重的工作流中。

作为 MCP 用户，我应该从哪里开始？

通过 npx 使用 @usejunior/safe-docx，然后按照 packages/docx-mcp/README.md 中的设置示例进行操作。

我在哪里可以查看工具模式？

请参阅 packages/docx-mcp/docs/tool-reference.generated.md 中的生成参考。

开发

npm ci
npm run build
npm run lint --workspaces --if-present
npm run test:run
npm run check:spec-coverage
npm run test:coverage:packages
npm run coverage:packages:check
npm run coverage:matrix

另请参阅

• Open Agreements — 使用编程智能体填充标准法律模板（NDA、SAFE、NVCA）

• UseJunior 开发者工具 — 包含安装选项和工具目录的产品页面

隐私

Safe Docx 完全在您的本地机器上运行。不会将任何文档内容发送到外部服务器。详情请参阅我们的 隐私政策。

治理

• 贡献指南

• 行为准则

• 安全策略

• 更新日志