Word Master Skill

AI-driven Word document creation and editing system with dual-layer architecture:
AI intent layer + deterministic execution layer.

Core Scripts

Format Templates

Available JSON templates: default, formal, casual

DSL Operations Reference

See ${SKILL_DIR}/references/edit-ops.md for complete DSL specification.

Table Cell Operations

Read a document with tables → see cell IDs in the form t{tableidx}r{rowidx}c{col_idx} (e.g. t0r1c2 = table 0, row 1, column 2). Then target them in operations:

[
  {"op": "replace_cell_text", "target": "t0r1c2", "find": "old", "replace": "new"},
  {"op": "rewrite_cell", "target": "t0r0c0", "content": "Brand new cell content"}
]

• replacecelltext: in-cell targeted find/replace (preserves run-level formatting).
• rewrite_cell: full cell content replacement (single paragraph, plain text).
• Invalid target format → ValueError; out-of-range indices → IndexError.

Workflow 1: Edit Mode (修改文档)

For editing existing documents.

Step 1: Read Document

python ${SKILL_DIR}/scripts/docx_reader.py document.docx --overview

This outputs rich-text Markdown with paragraph IDs (p0, p1, …) interleaved with table cell IDs (tNrNcN, e.g. t0r1c2). Use the IDs in subsequent edit operations. Pass --overview to skip tables (paragraphs only).

Step 2: Generate Edit Operations

AI understands user intent and generates JSON DSL operations. See ${SKILL_DIR}/references/edit-ops.md for supported operations.

Example operations:

[
  {"op": "replace_text", "find": "old", "replace": "new"},
  {"op": "rewrite_paragraph", "target": "p0", "content": "New content"},
  {"op": "set_font", "target": "p0", "name": "Arial", "bold": true},
  {"op": "set_paragraph_format", "target": "p0", "alignment": "center"}
]

Step 3: Execute Edit

python ${SKILL_DIR}/scripts/docx_editor.py document.docx operations.json

Original file backed up as document.docx.bak.

Step 4: Verify Changes

python ${SKILL_DIR}/scripts/docx_diff.py document.docx document_modified.docx

Workflow 2: Style Transfer (样式迁移)

学习源模板文档的排版格式风格（包含段落格式与表格样式），应用到目标草稿文档。

Step 1: 提取源模板格式指纹

python ${SKILL_DIR}/scripts/template_analyzer.py template.docx --output style_profile.json

可选参数：

• --para-min-cluster-size N：段落聚类最小样本数（默认 4）
• --para-no-heading-aware：禁用段落标题感知模式（使用普通的格式聚类）

这会直接生成一个包含 roles (段落格式角色) 和 tableroles (表格样式特征) 的综合 styleprofile.json 配置文件。

Step 2: AI 推断与微调样式角色

将生成的 style_profile.json 提供给 AI 审查，或由 AI 自动读取。AI 会推断这些段落和表格样式的应用意图，并对其进行调优。

格式约束：主结构必须包含：

• roles：段落格式角色列表
• table_roles：表格样式规则列表

段落角色 (roles) 白名单值：

表格样式 (table_roles) 结构说明： 每个表格条目包含：

• id: 唯一标识符 (int)
• structure: 物理结构特征 (包含 cols, rows, hasheaderrow)
• border: 六方向边框（top, bottom, left, right, insideH, insideV）的 XML 格式定义
• shading: header 与 body 的底纹颜色 (HEX / None)
• cell_margin: 单元格四周的内边距大小 (如 "1.0pt")
• headertext & bodytext: 表头及表身文字的字体样式、粗细与对齐方式

示例结构：

{
  "roles": [
    {"role": "Heading 1", "fingerprint": {"size": "14.0pt", "font": "黑体", "align": "center", "color": null}},
    {"role": "Normal", "fingerprint": {"size": "11.0pt", "font": "宋体", "align": "justify", "color": null}}
  ],
  "table_roles": [
    {
      "id": 0,
      "structure": {"cols": 3, "rows": 5, "has_header_row": true},
      "border": {
        "top": {"val": "single", "sz": 4, "color": "000000"}
      },
      "shading": {
        "header": "D9E1F2",
        "body": null
      },
      "header_text": {
        "font": "Arial",
        "size": "12.0pt",
        "bold": true,
        "align": "center"
      }
    }
  ]
}

注意：style_transfer.py 会自动验证 profile 的强类型约束。

匹配规则：样式转换采用精确名称和结构匹配。段落部分会套用对应 role 的 fingerprint；表格部分会基于最近邻打分算法（列数 + 表头行 + 行数相似度）匹配 table_roles 中的最近邻表格样式并自动生成应用操作。

Step 3: 应用样式到目标草稿

python ${SKILL_DIR}/scripts/style_transfer.py --profile style_profile.json draft.docx output.docx

可选参数：

• --review：应用前暂停，供人工确认 profile
• --skip-head N：跳过前 N 个段落（排除封面）
• --skip-tail N：跳过后 N 个段落（排除签字页）

Step 4: 验证结果

python ${SKILL_DIR}/scripts/docx_diff.py draft.docx output.docx

Execution Discipline

1. Read before write: Always read existing code before modifying
2. Test-driven: Write failing test first, then implement
3. Commit frequently: Each task should be a separate commit
4. Backup first: docx_editor.py always creates .bak backup before editing

Heading Numbering

标题编号管理：给 docx 的标题段落添加/移除编号前缀（文本前缀方案，非 Word 原生 numPr）。 与 markdown-master 的 structure.py numbering 对称，模板语法和 YAML 配置完全一致。

CLI

# 添加编号
python ${SKILL_DIR}/scripts/docx_structure.py <file.docx> numbering add \
    [--h1 T] [--h2 T] [--h3 T] [--h4 T] [--h5 T] [--h6 T] \
    [--config FILE] [--start-from N] [--save-config FILE] \
    [-o output.docx]

# 移除编号
python ${SKILL_DIR}/scripts/docx_structure.py <file.docx> numbering remove [-o output.docx]

默认覆盖原文件并生成 .bak 备份；-o 输出到新文件时不生成 .bak。

编号模板语法

N 范围是 1-6，对应标题级别 H1-H6。空模板字符串表示该级标题不添加编号。

YAML 配置文件格式

h1: "第{1}章 "
h2: "{1}.{2} "
h3: "（{3}）"
h4: ""
h5: ""
h6: ""
start_from: 1

原生 Word 自动编号处理：

• 默认 --native-numbering manual：如果标题 1-6 段落已有 Word 原生自动编号，工具报错退出，不修改文档。
• --native-numbering auto-clear：只清除主正文标题 1-6 段落上的 Word 原生编号属性，然后应用文本编号。
• --native-numbering prompt：交互询问；非交互或直接回车时按 manual 处理。

numbering remove 只移除文本编号前缀，不移除 Word 原生自动编号。

常见编号用法示例

# 技术文档风格（1/1.1/1.1.1）
python ${SKILL_DIR}/scripts/docx_structure.py doc.docx numbering add \
    --h1 "{1} " --h2 "{1}.{2} " --h3 "{1}.{2}.{3} "

# 中文章节风格（第1章/1.1/（1））
python ${SKILL_DIR}/scripts/docx_structure.py doc.docx numbering add \
    --h1 "第{1}章 " --h2 "{1}.{2} " --h3 "（{3}）"

# 学术风格（I/A/1/a）
python ${SKILL_DIR}/scripts/docx_structure.py doc.docx numbering add \
    --h1 "{1:R} " --h2 "{2:A} " --h3 "{3} " --h4 "{4:a} "

# 保存当前配置为模板
python ${SKILL_DIR}/scripts/docx_structure.py doc.docx numbering add \
    --h1 "第{1}章 " --h2 "{1}.{2} " --save-config chinese_chapter.yaml

# 使用保存的配置
python ${SKILL_DIR}/scripts/docx_structure.py doc.docx numbering add \
    --config chinese_chapter.yaml