feat:Preset Hook 系统功能清单

[AfishInLake]

一、核心基础设施

1. Hook 调度器 (src/wordformat/hooks.py)

• 定义所有钩子点（事件名称）：on_config_loaded、on_tree_built、on_node_format
  、on_caption_check、on_heading_numbering、on_document_save 等
• register(event, callback) — 注册回调
• emit(event, **kwargs) — 触发回调，收集返回值/修改
• 支持回调返回值合并到流水线参数（钩子可修改传入的数据）

2. Preset 加载器 (src/wordformat/preset_loader.py)

• 扫描 presets/ 目录，找到所有 .py 文件
• 动态 importlib 加载模块，调 register(hooks) 入口函数
• 支持按名称加载指定 preset：load_preset("tsinghua")
• 预设优先级：先加载的被后加载的覆盖（支持多 preset 叠加）

3. CLI 接入 (src/wordformat/cli.py)

• wf cf/af thesis.docx --preset tsinghua 参数
• wf list-presets 列出可用预设

二、钩子点定义（按流水线顺序）

┌─────┬─────────────────┬───────────────┬──────────────┬─────────────────┐
│ # │ 钩子 │ 触发位置 │ 传入参数 │ 回调返回值用途 │
├─────┼─────────────────┼───────────────┼──────────────┼─────────────────┤
│ 1 │ on_config_loade │ 配置加载后 │ config: Node │ 修改/补充配置 │
│ │ d │ │ ConfigRoot │ │
├─────┼─────────────────┼───────────────┼──────────────┼─────────────────┤
│ 2 │ on_tree_built │ 文档树构建后 │ root_node: │ 自定义节点分类 │
│ │ │ │ FormatNode │ │
├─────┼──────────────────┼───────────────┼───────────────┼────────────────┤
│ │ before_node_form │ 每个节点格式 │ node, │ │
│ 3 │ at │ 化前 │ paragraph, │ 预处理段落内容 │
│ │ │ │ config │ │
├─────┼──────────────────┼───────────────┼───────────────┼────────────────┤
│ │ after_node_forma │ 每个节点格式 │ node, │ 追加自定义格式 │
│ 4 │ t │ 化后 │ paragraph, │ 规则 │
│ │ │ │ config │ │
├─────┼──────────────────┼───────────────┼───────────────┼────────────────┤
│ 5 │ on_caption_check │ 题注校验时 │ node, parsed, │ 追加自定义题注 │
│ │ │ │ issues: list │ 规则 │
├─────┼──────────────────┼───────────────┼───────────────┼────────────────┤
│ │ on_heading_numbe │ │ heading_node, │ │
│ 6 │ ring │ 标题编号时 │ numbering_co │ 自定义编号策略 │
│ │ │ │ nfig │ │
├─────┼──────────────────┼───────────────┼───────────────┼────────────────┤
│ 7 │ before_document_ │ 保存前 │ document, │ 插入声明页、封 │
│ │ save │ │ config │ 面等 │
├─────┼──────────────────┼───────────────┼───────────────┼────────────────┤
│ 8 │ on_comment │ 添加批注时 │ paragraph, │ 修改批注文案/ │
│ │ │ │ text: str │ 级别 │
└─────┴──────────────────┴───────────────┴───────────────┴────────────────┘

三、预设文件规范

• 位置：presets/.py
• 必须暴露 register(hooks) 函数
• 提供配置 manifest：预设可声明自己需要的 YAML 配置项，加载时自动合并
• 示例模板：presets/_template.py 包含所有钩子的使用示例

四、具体实现步骤（建议顺序）

1. hooks.py — 事件调度器
2. preset_loader.py — 加载器
3. 在 set_style.py、caption.py、numbering.py 中埋入 emit() 调用点
4. cli.py — --preset 参数 + list-presets 子命令
5. presets/_template.py — 模板文件
6. 测试 + 文档

五、可延后的功能

• 预设间依赖：A 预设依赖 B 预设
• 预设热加载：改 preset 文件后自动生效
• 预设市场/远程下载
• GUI 预设选择器（Vue 前端）