Imported from leeleo11/framework-model-comparison (checkpoints/train-all/skills/osis-calcbook/SKILL.md). Install upstream with npx skills add leeleo11/framework-model-comparison --skill osis-calcbook. Copyright stays with the author.

计算书 Markdown 文档构建流程

前置条件

• 用户提供了模板文件，如果没有就从 <skill_dir>/templates 下选用一个案例

模板说明：

• OSIS计算书案例.docx — OSIS软件风格的计算书模板（默认模板）
• midas计算书案例.docx — midas Civil软件风格的计算书模板
• 已使用 osis-check 完成规范验算（验算数据是计算书的数据来源），如用户尚未验算，需先加载 osis-check 完成验算再回到本 Skill 构建计算书
• 已运行 <skill_dir>/scripts/data.py 生成 项目数据结构.json
• 工具脚本：docx_to_md.py、fill_tables.py、renumber.py

⚠️ 工作目录：所有命令（data.py、docx_to_md.py、fill_tables.py、renumber.py）和文件输出均应在项目根目录（与 py/ 同级，即 image/ 和 json/ 所在目录）执行。不要在 py/ 子目录下执行，否则计算书中的 image/、json/ 相对路径将无法正确解析。

核心原则

1. 模板转换优先：先将 DOCX 模板转换为 Markdown，获得结构清晰的模板
2. 批量渲染，避免逐条 Edit：计算书构建是数据驱动的确定性任务，应通过直接 Write 完整初稿一次性完成所有替换。Edit 仅用于用户提出的局部修改
3. 保留章节，删除无数据图表：JSON 中为 null 的数据，仅删除对应的图片和表格，保留章节标题和文字说明
4. 完全模仿模板行文风格：模板怎么写，你就怎么写。模板在某个位置列出了数据，你就仿照着列出对应的OSIS数据；模板只给定性描述没给数字的地方，不要自行添加数据
5. 编号后置：所有编号（标题、图、表）在内容修改完成后再统一生成，避免删改导致编号断裂
6. 清理临时文件：交付前删除中间产物（裸模板、初稿、填表中间件等）

流程速览

DOCX模板 ──docx_to_md──► 裸模板.md
                              │
项目数据结构.json ◄───────────┤
                              ▼
                       [AI 直接 Write 完整初稿]
                               │
                               ▼
                        计算书_初稿.md
                               │
                        fill_tables.py
                               │
                        renumber.py
                               ▼
                        计算书.md
                               │
                        清理临时文件
                               ▼
                            交付 ✅

完整构建流程

1. 生成项目数据结构

如果还没有 项目数据结构.json，先运行：

python <skill_dir>/scripts/data.py -o 项目数据结构.json

data.py 会在当前工作目录下创建 json/ 和 image/ 两个子目录，输出验算数据的 JSON 文件和内力图。确保在项目根目录执行。

2. 转换 DOCX 模板为 Markdown

若用户未提供模板，使用默认模板 <skill_dir>/templates/计算书案例.docx。

python <skill_dir>/scripts/docx_to_md.py "模板.docx" "裸模板.md" --h1 "一级标题" --h2 "二级标题" --h3 "三级标题"

建议：先用 --list-styles 查看样式名，再映射标题层级。不要加 --auto-number。

3. 提取关键数据

读取 项目数据结构.json，从中提取写初稿所需的信息：

• 模型基本信息（节点数、单元数等）
• 验算摘要值（各验算的最值与满足/不满足结论），用于替换结论段落中的数字
• 图片路径映射，用于替换图片占位符
• 表格路径，用于写 {{TABLE:...}} 占位符

只读 项目数据结构.json，不要逐个打开 json/ 下的原始数据文件——表格数据由 fill_tables.py 自动填充。

4. 生成完整 Markdown 初稿（直接 Write）

读取裸模板和 JSON 数据后，一次性 Write 完整初稿，在 Write 过程中完成：

4.1 理解模板风格

读取裸模板，把握模板的行文逻辑：

• 模板在哪里展示数据（如"节点数量：63个"），你就在对应位置展示OSIS数据
• 模板只给定性描述的地方（如"不满足规范要求"），不要自行添加定量数据
• 保留模板的句式、措辞和描述方式

4.2 保留章节，删除无数据图表

JSON 中为 null 的数据，仅删除对应的图片占位符、表格及其题注，保留章节框架和文字说明。

4.3 填充数据

核心原则：模板怎么写，你就怎么写。

• 模型信息：模板写了"节点数量：63个"→替换成OSIS数据；模板没写具体数字→保留原样
• 结论段落：保留模板原有的结论句式（如"结构的重要性系数*作用效应的组合设计最大值>构件承载力设计值，不满足规范要求"），只修正"满足/不满足"判断。模板结论里带了数值（如"最大压应力为10.582 MPa"）才替换，没带数值不要自行补充
• 图片题注：保持模板原有的题注文字风格
• 占位符：{{工程概况描述}} → （请补充工程概况描述）

4.4 替换图片路径

• 有数据：![图片占位符](图片路径) → ![图 xxx](image/实际路径.jpg)
• 无数据：删除图片占位符及其题注
• 题注文本保持原样（renumber.py 最后统一编号）

4.5 标记表格数据路径

将 | {{表格数据}} | 改为 | {{TABLE:json/xxx.json}} |。

无对应数据文件的表格直接删除表格及其题注，不要保留 {{TABLE:...}} 占位符（如：若 JSON 中无 支座沉降 数据，则删除整个沉降表格及题注）。

常用表格路径（与 项目数据结构.json 中的字段一一对应）：

模型数据表格：

验算表格：

5. 批量填充表格

python <skill_dir>/scripts/fill_tables.py "计算书_初稿.md" "计算书_填表.md"

脚本自动查找所有 {{TABLE:path.json}}，读取 JSON 数据并转换为 Markdown 表格。

6. 统一重编号

python <skill_dir>/scripts/renumber.py "计算书_填表.md" "计算书.md" --heading \
    --figure-prefix "图" --figure-format "{chapter}.{seq}" \
    --table-prefix "表" --table-format "{chapter}.{seq}"

AI 根据模板实际题注格式传参：

7. 验证

检查 计算书.md 无残留占位符：

# Git Bash
grep -cE "\{\{TABLE:|\{\{表格数据\}\}|图片占位符" 计算书.md

8. 清理临时文件并交付

删除中间产物：

rm -f 裸模板.md 计算书_初稿.md 计算书_填表.md

确认后交付 计算书.md。

输出格式示例

# 1. 项目基本信息

## 1.1. 工程概况

（请补充工程概况描述）

## 1.5. 材料参数

结构用主要材料的技术指标按《公路钢筋混凝土及预应力混凝土桥涵设计规范》
（JTG 3362-2018）的规定采用，混凝土等级主要力学性能指标摘录于下表。

表1.1 材料主要指标表

| 材料编号 | 材料名称 | 弹性模量(N / m ^ 2) | 泊松比 | 密度(N / m ^ 3) | 线膨胀系数(1 /℃) |
| --- | --- | --- | --- | --- | --- |
| 1 | C50 | 3.45e+10 | 0.20 | 2.500e+04 | 1.00e-05 |

# 2. 模型建立与分析

## 2.1. 计算模型

![图 计算模型图](image/IMG_Structure.jpg)

图2.1 计算模型图

1）节点数量：4；

2）单元数量：2；

3）边界条件数量：4，边界条件表如下：

表2.1 边界约束表

| 编号 | 节点 | UX | UY | UZ | RX | RY | RZ | RW |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | 1 | 约束 | 约束 | 约束 | 约束 | 约束 | 约束 | 自由 |

4）施工阶段数量：4，施工步信息如下：

## 4.1. 持久状况承载能力极限状态验算

### 4.1.1. 正截面抗弯承载能力验算

![图 UxMin下正截面抗弯承载能力包络图](image/IMG_MomentCapacityMin.jpg)

图4.1 UxMin下正截面抗弯承载能力包络图（单位：kN*m）

按照《公路钢筋混凝土及预应力混凝土桥涵设计规范》（JTG 3362-2018）
第5章第5.1.2-1条规范要求验算，由计算结果可知，正截面最小弯矩为0.0kN·m，
正截面最大弯矩为1375.0kN·m，结构极限承载能力验算不满足规范要求。

注意事项

1. 不要提前编号：所有编号由 renumber.py 最后统一生成
2. 图片路径：使用相对项目根目录的路径（如 image/IMG_Structure.jpg），不做绝对路径替换。路径来源见 项目数据结构.json 中的 图片文件 字段。
3. 公式保留：Word 中的 OMML 公式会自动转换为 LaTeX 格式（$...$）
4. 表格占位符格式：必须是 | {{TABLE:path.json}} |（包含外层的 |）
5. 优先 Write，慎用 Edit：数据驱动的确定性任务应通过 Write 一次性生成。Edit 仅用于用户提出的局部修改
6. 及时清理：交付前删除裸模板、初稿、填表中间件等临时文件

避坑指南（来自实战教训）

1. 生成后必须检查一遍文档

Write 初稿后，不能只检查占位符残留，必须阅读整个文档，和模板的格式做对比，确定表格格式，文本，章节等有没有问题。

2. material.json 混合材料问题

material.json 包含所有材料（C50、HRB400、钢绞线-1860）在一个文件中。OSIS 模板的"材料主要指标表"是一张合并表，直接映射没问题。但 midas 模板按材料类型拆成了"混凝土""预应力钢筋""普通钢筋"三张独立表。

• 做法：用 Edit 直接从已渲染的表格中删除无关行（如从混凝土表中删除 HRB400 和钢绞线行），再补回其他材料表
• 不要创建 material_concrete.json 等中间文件（无谓增加项目文件）
• 不要重新跑 fill_tables 和 renumber 全流程（Edit 已渲染的表格内容即可）

3. td_prop.json ≠ 材料性能

4. midas 模板数据匹配度低

midas 模板验算章节多（抗扭、裂缝宽度、挠度、配筋率、抗倾覆等），实际项目数据往往只有部分覆盖：

• 有数据的章节：按模板行文风格填充，结论数值从 项目数据结构.json 的 验算表格 字段提取
• 无数据的章节：整节删除（含标题、图片、表格、结论），不要留空壳

5. 局部修正用 Edit，不要全量重建

初稿生成后发现问题，原则：

• 表格数据内容错（如多行了、映射错了）：直接 Edit 已渲染的 Markdown 表格，删除/修正行内容
• 图片路径错：Edit 图片链接
• 结论数值错：Edit 结论段落中的数字
• 表/图编号断裂：手动 Edit 修正编号（表格1.2 → 表格1.3）

不需要重写整个初稿，也不需要重新跑 fill_tables 和 renumber。Write 是一次性交付，Edit 是精修。

6. midas 模板没有验算数据大表格

midas 模板的验算章节只有包络图 + 结论文字，没有 OSIS 模板中那种逐单元的数据大表格。不要往 midas 风格的计算书里塞 {{TABLE:json/正截面抗弯承载能力验算.json}} 这类验算数据表。

7. Shell / PowerShell 编码陷阱

当前环境为 Windows MinGit（Git Bash），请优先使用 Bash + Python 工具链处理文件操作。Select-String、Set-Content、Out-File 等 PowerShell cmdlet 默认使用系统编码（Windows-1252），写入含中文的 Markdown 文件时会破坏中文字符。

解决：涉及中文文件读写时，用 Python 脚本替代 shell 文本处理，避免 PowerShell 编码问题：

# ❌ 不推荐使用 PowerShell cmdlet 处理中文 Markdown
# (请在当前环境下避免这样做)
# (Get-Content file.md) -replace 'a','b' | Set-Content file.md

# ✅ 推荐：用 Python 脚本替代
python - <<'PY'
with open('file.md', 'r', encoding='utf-8') as f:
    c = f.read()
c = c.replace('a', 'b')
with open('file.md', 'w', encoding='utf-8') as f:
    f.write(c)
PY

8. 旧文件干扰

不要修改已存在的 计算书.md（可能是 OSIS 风格或用户已有的计算书）。必须从模板重新生成完整文件。

解决：直接 Write 全新文件覆盖，或在文件名加后缀区分（计算书_midas.md），保留旧文件。

9. 模板题注前缀差异

不同模板的图表题注前缀不同，renumber.py 参数需要对应调整：

注意 midas 模板的表格前缀是"表格"而非"表"，如果传错参数会导致表格编号不生效。

10. 保存中间文件用 Python 而非 PowerShell

fill_tables.py 和 renumber.py 输出后需要二次修改（如图表修正、材料表行删除），这些修改必须用 Edit 工具完成，不要用 PowerShell 的 Set-Content，否则中文必乱码。

工具说明

docx_to_md.py

DOCX 转 Markdown 转换器，输出"裸"格式（不带编号）：

• 标题：# 项目基本信息（不带 1.）
• 图题注：图 计算模型图（不带 2.1）
• 表题注：表 材料主要指标表（不带 1.1-1）
• 支持标题样式映射（--h1 ~ --h6）、公式转换（OMML → LaTeX、EQ域 → LaTeX）、图片/表格占位符

data.py

生成项目数据结构 JSON，包含基本信息、材料参数路径、验算结果摘要与路径、图片文件列表。执行时会在当前工作目录下创建 json/ 和 image/ 两个子目录存放验算数据文件和内力图。

fill_tables.py

通用表格填充脚本：自动查找所有 {{TABLE:path.json}}，读取 JSON 数据并转换为标准 Markdown 表格。

renumber.py

标题与图表题注重编号脚本：按 Markdown 标题层级生成连续编号，按出现顺序为图/表分配编号，支持自定义前缀和格式（{chapter}、{seq} 占位符）。