doc_batch
Apply multiple Word .docx edits in one atomic batch as tracked changes or plain approved writes, with dry-run previews, conflict checks, and stale-file guards.
Instructions
The main editing tool: apply several edits in one verified write, as tracked changes, all or nothing. One family per batch: text.replace, para.insert, para.delete, para.move, style.apply, format.apply, comment.add/reply/resolve; or table.row.insert/delete; or style.create/update/rename/merge; or revision.accept/reject. Example ops: [{"op": "text.replace", "at": "p3#a1b2c3d4:10-15", "text": "new"}]. Every address is as read; overlapping edits are BATCH_CONFLICT, outdated ones STALE_ADDRESS. File engine: backed up first, dry_run previews, expect.sha256 refuses a changed file, history.undo takes the batch back. tracked: false writes approved text plainly, on either engine. engine live edits the open app (comment.add, text.replace, para.insert only; no dry_run or rollback). server.help gives each kind's fields.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc | Yes | Path to the .docx (live: or the file name of one open in a live app). | |
| ops | Yes | Operations, applied together. Every address refers to the document as read; an operation placed relative to a paragraph another operation deletes or moves is a BATCH_CONFLICT. Kinds: text.replace ['at', 'text']; para.insert ['after', 'before', 'text']; para.delete ['at']; para.move ['after', 'at', 'before']; style.apply ['at', 'style']; format.apply ['align', 'at', 'bold', 'font', 'indent_first_line_cm', 'indent_left_cm', 'indent_right_cm', 'italic', 'line_spacing', 'size_pt', 'small_caps', 'spacing_after_pt', 'spacing_before_pt', 'underline']; comment.add ['at', 'text']; comment.reply ['comment', 'text']; comment.resolve ['comment', 'resolved']; style.create ['based_on', 'custom', 'default', 'id', 'link', 'name', 'next', 'paragraph', 'quick', 'run', 'type']; style.update ['based_on', 'link', 'next', 'paragraph', 'quick', 'run', 'style']; style.rename ['id', 'name', 'style']; style.merge ['from', 'into']; revision.accept ['all', 'at', 'author', 'ids']; revision.reject ['all', 'at', 'author', 'ids']; table.row.insert ['after_row', 'cells', 'table']; table.row.delete ['row', 'table']. | |
| tag | No | Appended to the author. | |
| author | No | Revision author. | |
| engine | No | `live` edits the document open in Word or LibreOffice (see live.open). | |
| expect | No | Write guard: the sha256 read earlier (doc.info, or a reply's doc.sha256), e.g. {"sha256": "9f86d081…"}; a file changed since is DOC_CHANGED_ON_DISK. | |
| dry_run | No | Preview only; write nothing. | |
| tracked | No | true (default): edits are tracked changes. false: a plain write, for a change the writer already approved: built as the tracked edit, then this call's own revisions are accepted in the same verified write (no revision marks; the log has it, and undo takes it back from the backup, only while the document is exactly as the write left it: no out-of-order undo). Refused (UNSUPPORTED_CONTENT) when a paragraph it rewrites holds another unresolved tracked change. Text, paragraph and style/format edits only (refused with revision, row and comment operations). engine live: the app's change tracking is off for the edit and put back after; text.replace and para.insert, refused (UNSUPPORTED_CONTENT) next to another unresolved tracked change; the app's undo takes it back. A plain edit inside a tracked-inserted table row is allowed: rejecting that row later removes the plain text too. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | Always true on success. | |
| op | Yes | The operation that ran. | |
| api | Yes | API version (1.0). | |
| doc | No | The document read or written: path, sha256 and paragraph count. | |
| next | Yes | Cursor for the next page (pass as cursor), or null. | |
| result | Yes | What the operation returns. | |
| warnings | Yes | Things to know about the result. |