研发交付格式-随风（ym-dev-deliver-format）
管「同样的内容，用哪种载体交出去、怎么保证打开就是整齐的」。不管内容对不对（那是各专业角色的事）。
> 本技能来自「编程专家团-随风」专家团的 研发交付经理 角色（Agent ym-dev-team-lead）——该角色在 Phase 7 用它做交付格式落地。全流程编排见配套技能 ym-dev-team-lead。
运行前提
- 依赖：无第三方依赖，纯方法论技能（不联网、不读写用户文件）
- 无运行时配置与本地数据，不读写任何配置文件
- 产出默认写入用户指定的产出目录（运行时产物），用户未指定时落到当前工作区的
output/<需求标识>/下
第 0 步 · 版本自检（每次动手前先跑）
python scripts/sync.py --json
只读比对线上版本：退出码 0 最新 · 10 有新版建议重装 · 20 主版本不同必须重装 · 30 联网失败按旧版继续。
本技能不自动更新自己 —— 换版本只有一条路：用户明确重装（skillhub install ym-dev-deliver-format）。
何时使用
- 被问「这份文档能给 Word 吗 / 能不能导成 PDF」
- 交付件打开后发现排版乱、表格被折进段落、目录缺失
- 需要在
md/docx/html/xlsx之间选一种交付格式 - 交付前要过一遍质量门禁
第一步：先定格式（不要中途改）
| 格式 | 适合 | 不适合 | 代价 |
|---|---|---|---|
| Markdown | 内部流转、需二次编辑、篇幅长且结构简单 | 给外部客户/领导看的正式稿 | 最低，零转换风险 |
| HTML | 要排版美观、内外都能看、含大量表格 | 对方必须在 Word 里改批注 | 低，浏览器即可打开 |
| DOCX | 对方要在 Word 里批注 / 签署、走正式流程 | 含大量复杂表格与图示（易失真） | 中高，转换链路最容易出问题 |
| XLSX | 数据、清单、人天表、需要筛选排序 | 长文叙述、章节型文档 | 中 |
铁律：格式在开工前问定。中途改格式 = 前面所有排版工作作废。
第二步：选转换链路
| 目标 | 路径 | 说明 |
|---|---|---|
| md → html | 直接渲染 + 自建样式层 | 最稳，样式完全可控，推荐作为默认交付格式 |
| md / html → docx | 走官方文档技能链路 | 失败率最高的一段，先验证链路可用再投入内容排版 |
| 表格 → xlsx | 走表格技能链路 | 有源表格时优先改源文件，不要重新生成一份 |
链路体检（30 秒的事，能省几小时）：如果这次要交 docx，先拿一段样文跑通「转换 → 打开 → 格式正确」，链路不通就立刻回退 HTML。不要一边调链路一边排版正文。
第三步：成稿质量门禁（交付前逐条过）
结构性
- [ ] 有目录 / 章节编号，层级连续（不出现 h2 直接跳到 h4）
- [ ] 每个二级标题下至少有一段导语，不是标题直接怼表格
- [ ] 表格没有被折进段落 —— markdown 里表格前后必须各留一个空行
- [ ] 无占位内容（
TODO、待补、示例文本）
可读性
- [ ] 单段落不超过 500 字，超长段落按句界拆开
- [ ] 没有孤行标题（标题落在区块末尾，正文翻到下一块）
- [ ] 表格列数 ≤ 8，超了就拆表或改成分条叙述
- [ ] 数字都有单位与口径，不留裸数字
一致性
- [ ] 全文术语统一，同一概念只用一种写法
- [ ] 编号体系统一（章节 / 任务 / 需求 / 用例各一套，不混用）
- [ ] 配色与字号走同一套变量，不出现临时硬编码的裸值
可交付
- [ ] 文件名说清「是什么 + 给谁 + 版本」
- [ ] 文件落在约定的交付目录，并把路径告知用户
- [ ] 长正文不塞进聊天消息，用文件呈现
有内置排版检查工具时，先跑一遍自动检查、再人工抽查上面这些项；自动检查通过 ≠ 可以交付。
高频坑（都是真踩过的）
- 表格被折进段落：markdown 里「加粗小标题」紧跟表格且中间没空行时，渲染器会把小标题和整张表折成一个段落，表格结构直接丢失，变成一串竖线纯文本。防法：表格前后各留一个空行。
- 段落长度按源文件算、不按渲染结果算：源里 400 字的段落，渲染后带上标签与实体可能超 500 字。一律按渲染后的结果判断长度。
- 转换脚本在 Windows 上静默失败：脚本里写
venv/bin/python在 Windows 上应为Scripts/python.exe；报错若被>/dev/null吞掉，表面成功、实际没产出。转换后必须验证产物存在且能打开。 - 中途改格式：内容已排好版再换格式，等于重做一遍。格式必须开工前定。
- 拿半成品占位交付：文件是生成了，但排版乱。这比不交更糟 —— 用户会以为这就是最终质量。成稿前过完门禁再呈现。
- 只交付一个总数、不给口径：表格类交付物（人天、报价、清单）只有数字没有口径说明时，用户会误当承诺。数字类交付必须附口径。
交付方式
- 完整产出写入用户指定的产出目录（默认
output/<需求标识>/ym-dev-deliver-format.md，UTF-8），并在回执里给出文件路径 —— 长正文只放消息里会丢内容 - 长正文不塞进聊天消息，用文件呈现给用户
- 回执只放结论、依据、不确定项与文件路径；不确定项标注为「待确认」，不替用户拍板
目录说明
scripts/— 只含scripts/sync.py版本自检器（只读，不改任何文件）
