docx-processing-superdoc

SuperDoc CLI（v1）

使用 SuperDoc CLI 处理 DOCX。使用 v1 命令（规范操作及其辅助封装）。 除非明确需要 v0 风格的批量工作流，否则不要默认使用旧版命令。

如果已安装，请使用 superdoc；否则可使用 npx @superdoc-dev/cli@latest 作为备用方案。

第一步：查明确切参数

对于未知命令或标志，先检查运行时元数据：

superdoc describe
superdoc describe command find
superdoc describe command "comments add"

使用 describe command 查看各命令的参数和限制。

首选工作流

1) 有状态的多步编辑（推荐）

superdoc open ./contract.docx
superdoc query match --select-json '{"type":"text","pattern":"termination"}' --require exactlyOne
superdoc replace --target-json '{"kind":"text","blockId":"p1","range":{"start":0,"end":11}}' --text "expiration"
superdoc save --in-place
superdoc close

• 始终使用 query match（而非 find）来查找修改目标——它会返回带有基数保证的精确地址。
• open 之后，如果省略 <doc>，命令会针对当前活动/默认会话运行。
• 使用 superdoc session list|set-default|save|close 显式控制会话。
• 对脏状态执行 close 时，必须使用 --discard，或先执行 save。

2) 无状态的单次读取

superdoc get-text ./proposal.docx
superdoc get-markdown ./proposal.docx
superdoc info ./proposal.docx

3) 无状态的单次修改

superdoc replace ./proposal.docx \
  --target-json '{"kind":"text","blockId":"p1","range":{"start":0,"end":5}}' \
  --text "Updated" \
  --out ./proposal.updated.docx

• 在无状态模式下（提供 <doc>），修改命令必须使用 --out，除非使用 --dry-run。

安全：应用前先预览

• 使用 --dry-run 预览任何修改，而不实际应用。
• 对有状态修改使用 --expected-revision <n> 进行乐观并发检查。

常用 v1 命令

查询与检查

• 搜索/浏览内容：find --type text --pattern "..." 或 find --query-json '{...}'
• 查找修改目标：query match --select-json '{...}' --require exactlyOne
• 检查块：blocks list、get-node、get-node-by-id
• 提取内容：get-text、get-markdown、get-html

修改

• 替换文本：replace --target-json '{...}' --text "..."
• 插入行内文本：insert --block-id <id> --offset <n> --value "..."
• 删除文本/节点：delete --target-json '{...}'
• 删除块：blocks delete、blocks delete-range
• 批量修改：mutations apply --steps-json '[...]' --atomic true --change-mode direct
• 创建段落：create paragraph --text "..."（可选使用 --at-json）
• 创建标题：create heading --input-json '{"level":<n>,"text":"..."}'

格式

• 应用格式：format apply --block-id <id> --start <n> --end <n> --inline-json '{"bold":true}'
• 快捷命令：format bold、format italic、format underline、format strikethrough

列表

• 列出列表项：lists list、lists get
• 插入列表项：lists insert --node-id <id> --position after --text "..."
• 修改：lists indent、lists outdent、lists set-level、lists set-type、lists convert-to-text

评论

• 添加/回复：comments add、comments reply
• 读取：comments get、comments list
• 编辑/解决/移动：comments edit、comments resolve、comments move、comments set-internal
• 删除：comments delete（规范命令）或 comments remove（别名）

修订

• 列出：track-changes list、track-changes get
• 处理：track-changes accept、track-changes reject、track-changes accept-all、track-changes reject-all

历史记录

• history get、history undo、history redo

底层操作

• 直接调用：call <operationId> --input-json '{...}'（仅支持 JSON 输出——不支持 --pretty）

JSON/文件载荷标志

并非每个命令都提供 --*-file 变体。使用 describe command <name> 进行检查。

以下标志始终与对应的 -json 标志配对提供（任选其一，不要同时使用）：

标志对	可用于
--query-json / --query-file	find、lists list
--address-json / --address-file	get-node、lists get
--input-json / --input-file	call、create paragraph
--at-json / --at-file	create paragraph

--target-json 广泛适用于修改命令，但没有对应的 --target-file。可改用扁平标志（--block-id、--start、--end）代替 --target-json。

输出和全局标志

• 默认输出为 JSON 信封。
• 使用 --pretty 输出人类可读的内容（call 不支持）。
• 全局标志：--output <json|pretty>、--session <id>、--timeout-ms <n>。
• <doc> 可以是 -，用于从标准输入读取 DOCX 字节。

旧版兼容性（谨慎使用）

旧版 v0.x 桥接命令仍然可用：

superdoc search <pattern> <files...>
superdoc replace-legacy <find> <to> <files...>
superdoc read <file>

仅在确实需要 v0 风格的行为时使用这些命令（尤其是多文件 glob 搜索/替换）。 对于新的自动化任务，优先使用 v1 操作。