| name | docx-editing |
| description | 当用户需要【编辑已有的 Word 文档(.docx)】时使用。触发词：改这个文档、docx、Word 文档、修订、批注。
输出：保留格式的修改后文档（可含修订追踪）。不做：从零生成新文档。
|
| metadata | {"author":"usejunior","version":"0.1.1","openclaw":{"homepage":"https://github.com/UseJunior/safe-docx","requires":{"bins":"[Truncated]"},"install":["[Truncated]"]}} |
Editing .docx Files with Safe-DOCX
Safe-DOCX is a local MCP server for surgically editing existing .docx files. It preserves formatting, generates tracked-changes redlines, and runs entirely on the local filesystem — no hosted endpoint, no data leaves the machine.
Safety Model
- Local-only stdio runtime — the MCP server runs as a child process, never binds a port.
- Path policy — only files under
~/ (home directory) and system temp directories are accessible. Symlinks must resolve to allowed roots.
- Archive guardrails — zip bomb detection and hostile payload rejection protect against malformed
.docx inputs.
案件材料与文件安全门（2026-08-22 新增）
- 案件材料一律本地处理：案件文书、当事人信息、证据内容禁止上传到外部服务、第三方 API 或中转；Safe-DOCX 为本地 stdio 运行，符合此要求，不得改用线上编辑/转换服务处理案件材料。
- 编辑前创建/确认副本：在副本上编辑，不覆盖原始文件；保存目标路径与原文件不同（或先复制原文件再编辑）。
- 保存后回读验证：保存完成后重新 read_file（或重新打开）验证正文、页数、修订、批注和关键字段（当事人/金额/日期等零容忍字段逐项核对）。
- 输出记录：同时输出清洁稿和修订稿时，记录二者路径、版本和生成时间；重跑时版本递增，不静默覆盖。
- 深链协作：本技能在复杂深链（环节 6 引注与文书输出）中运行时，更新案件实体页「过程性文件台账」并回写
pipeline/02-文书草稿.md 状态（或标注 [产物未落盘/未验收]）。
- 与 legal-citation-comprehensive 对接：引用插入必须通过专用脚注工具（
add_footnote / update_footnote / delete_footnote），不得用普通文本替换破坏脚注。
- 会话失效处理：文档会话过期、段落 ID 失效、保存失败时，必须停止并重新读取文档获取新 ID，不得复用旧 ID 继续编辑。
When to Use This Skill
Use Safe-DOCX when you need to:
- Change clauses or paragraphs in an existing
.docx
- Insert or delete content with formatting preservation
- Add comments or footnotes for reviewers
- Produce a tracked-changes redline from edits
- Compare two
.docx files into a redline
- Extract revisions to structured JSON
- Apply layout formatting (spacing, row heights, cell padding)
Not for From-Scratch Generation
Safe-DOCX edits already-existing .docx files — it does not create documents from blank. For new document generation, use a template-filling workflow (e.g. OpenAgreements). Safe-DOCX can refine generated docs downstream.
不触发情况（强制排除）
以下场景即使提到 DOCX/Word，也不触发本 skill：
- 编程/脚本类："写个脚本/程序/代码 读取/生成/处理 DOCX"——这是编程任务，不是文档编辑
- 库/工具推荐类："用什么库读取 DOCX""python-docx 怎么用"——这是技术问答
- 格式转换类："把 DOCX 转成 PDF/Markdown"——这是文件转换任务（除非用户明确说"用 Safe-DOCX"）
- 从零生成：创建全新文档而非编辑已有文件
判定原则：用户目标是写代码/脚本，而非直接编辑文档内容 → 不触发
Quick Start
1. read_file(file_path="~/doc.docx") → see paragraphs + _bk_* IDs
2. grep(file_path="~/doc.docx", patterns=["target phrase"]) → find paragraph IDs
3. replace_text(session_id, target_paragraph_id, old_string, new_string, instruction)
4. save(session_id, save_to_local_path="~/doc-edited.docx")
Core Workflow: Read, Locate, Edit, Save
Step 1 — Read. Call read_file with format: "toon" (token-efficient table) to see paragraphs and their stable _bk_* IDs.
Step 2 — Locate. Use grep with regex patterns to find target paragraphs. It returns paragraph IDs with surrounding context.
Step 3 — Edit. Use replace_text to swap text within a paragraph, or insert_paragraph to add new paragraphs before/after an anchor.
Step 4 — Save. Call save to write output. Default is save_format: "both" which produces a clean copy and a tracked-changes redline.
Gotchas That Will Bite You
Unique match required
replace_text needs old_string to match exactly one location in the target paragraph. If the text appears multiple times, you get MULTIPLE_MATCHES. Fix: include more surrounding context in old_string.
BAD: old_string: "the Company" → 5 matches, fails
GOOD: old_string: "the Company shall indemnify" → 1 match, succeeds
Footnote markers are display-only
read_file shows footnotes as [^1], [^2], etc., but these markers are not part of the editable text. You cannot search for or replace [^1] via replace_text. To modify footnotes, use the dedicated add_footnote, update_footnote, and delete_footnote tools.
Hyperlinks are read-only
read_file shows links as <a href="...">text</a>, but you cannot create new hyperlinks via replace_text or insert_paragraph. The <a> tag is stripped from new text. Existing hyperlinks are preserved when surrounding text is edited.
Paragraph IDs are session-scoped
The _bk_* bookmark IDs are generated when a document is opened and are tied to that session. Do not store or reuse IDs across sessions. Always re-read the document to get fresh IDs.
Smart text matching
replace_text is tolerant of:
- Quote variants: straight
", curly \u201c\u201d, angle \u00ab\u00bb all match each other
- Whitespace differences: multiple spaces, tabs, and line breaks are normalized
This means you can copy text from read_file output and use it in old_string even if the underlying XML uses different quote characters.
Formatting Tags
When writing new_string in replace_text or insert_paragraph, use inline tags to apply formatting:
| Tag | Effect |
|---|
<b>text</b> | Bold |
<i>text</i> | Italic |
<u>text</u> | Underline |
<highlighting>text</highlighting> | Yellow highlight |
Tags can be nested: <b><i>bold italic</i></b>. Formatting from the original matched text is preserved for untagged replacement text.
Batch Edits with apply_plan
For 3+ edits on one document, prefer apply_plan over sequential replace_text calls. It validates all steps before applying any, so you get all-or-nothing transactional semantics.
1. read_file / grep → gather paragraph IDs and text
2. apply_plan(file_path, steps=[
{ step_id: "1", operation: "replace_text", target_paragraph_id, old_string, new_string, instruction },
{ step_id: "2", operation: "insert_paragraph", positional_anchor_node_id, new_string, instruction },
...
])
3. save(session_id, save_to_local_path)
Insert Paragraphs
insert_paragraph adds new content before or after an anchor paragraph.
position: "BEFORE" or "AFTER" (default "AFTER")style_source_id: optional _bk_* ID of a paragraph whose formatting you want to clone- Multi-paragraph: separate with
\n\n in new_string (each becomes its own paragraph)
Comments and Footnotes
Comments: add_comment anchors to a paragraph (optionally to a text span via anchor_text). Use get_comments to list, delete_comment to remove. Supports threaded replies via parent_comment_id.
Footnotes: add_footnote inserts a footnote marker in a paragraph (optionally after specific text via after_text). Use get_footnotes, update_footnote, delete_footnote to manage.
Comparing Documents
Two modes:
- Two files:
compare_documents(original_file_path, revised_file_path, save_to_local_path) — produces a redline
- Session edits:
compare_documents(session_id) — compares current session state against the original
Use extract_revisions on any document with tracked changes to get structured JSON diffs.
Accepting Tracked Changes
Call accept_changes(session_id) to flatten all tracked changes into a clean document. This removes all revision markup.
Session Behavior
- Sessions auto-create when you first use
file_path with any tool
- Sessions expire after 1 hour of inactivity (each tool call resets the timer)
- Call
clear_session to clean up when done
- Documents are normalized on open: format-identical runs are merged and proof-error markers removed, which improves text matching reliability
Layout Formatting
format_layout applies paragraph spacing, table row height, and cell padding without touching text content. Units are in twips (1/20 of a point) or DXA (1/635 of an inch).
Path Restrictions
By default, only files under ~/ (home directory) and system temp directories are accessible. Symlinks must resolve to allowed roots.
