hzhua/nexau-cookbook/docx-report

docx-report — Word 文档生成技能

将结构化 JSON 数据渲染为标准 .docx 文件。支持公文和通用文档。

加载本技能后，{skill_path} 指 LoadSkill("docx-report") 返回的技能文件夹路径。

首次使用

确保脚本有执行权限：

chmod +x {skill_path}/scripts/build

第一次 render 会自动检测并编译 .NET 渲染引擎（约 2-3 秒），输出 ✅ 引擎编译完成 后开始渲染。后续调用直接使用缓存，无需重复编译。

💡 也可以用 {skill_path}/scripts/build warmup 提前编译，但不是必须的。

生成文档

{skill_path}/scripts/build render <type> <input.json> <output.docx>

示例：

{skill_path}/scripts/build render notice /tmp/data.json /tmp/output.docx

脚本会自动：

1. 校验 JSON（检查 required 字段 + section 结构），格式不对立即报错
2. 调用渲染引擎生成 .docx
3. 输出 ✅ 生成完成：/tmp/output.docx (XXXX bytes)

⚠️ 关键规则

1. 只用 build render，禁止 dotnet run

# ✅ 正确
{skill_path}/scripts/build render notice data.json output.docx
 
# ❌ 错误 → CS8802 编译冲突（多个 top-level statements 文件）
cd {skill_path}/templates && dotnet run --project GovDoc.csproj ...

build render 内部自动隔离编译（只编译 GovDocEngine.cs），避免 CS8802。

2. JSON 的 section 结构必须用 heading + level + paragraphs

{
  "heading": "一、总体要求",
  "level": 1,
  "paragraphs": ["第一段正文……", "第二段正文……"],
  "children": [
    { "heading": "（一）目标", "level": 2, "paragraphs": ["……"] }
  ]
}

3. 输出文件名用英文

# ✅ /tmp/output_notice.docx
# ❌ /tmp/关于XX的通知.docx（中文在 Linux shell 下可能乱码）

可用模板类型

查看完整清单：

{skill_path}/scripts/build templates

常用类型及其 required 字段：

⚠️ 不同模板的 required 字段不同。按 notice 构造的 JSON 不能用 generic 模板渲染（字段不匹配）。

其他命令

{skill_path}/scripts/build templates       # 查看模板清单
{skill_path}/scripts/build check-index     # 校验模板索引完整性
{skill_path}/scripts/build batch <type> <input_dir> <output_dir>  # 批量生成
{skill_path}/scripts/build diff <type> <old.json> <new.json> <output.docx>  # 版本对比

常见错误速查

Schema 参考文件

详细 schema 定义在技能文件夹的 schemas/ 目录下：

• schemas/base.json — 公共定义（section、policy_ref、table 等结构在这里）
• schemas/govdoc/<type>.json — 各公文类型的字段定义
• schemas/general/generic.json — 通用文档

⚠️ 各类型 schema 中的 sections 字段通过 $ref 引用 base.json#/definitions/section。 构造 JSON 时以上面「section 结构」为准。