Menu
当用户提到「PRD」「需求文档」时触发。基于 IMAP / 原型输出 PRD 亦触发。 PRD 形态为 md（含本地截图，推 Confluence 时脚本自动上传图片）。
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/CaufieldZ/pm-workspace-public --skill prdThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
| name | prd |
| description | 当用户提到「PRD」「需求文档」时触发。基于 IMAP / 原型输出 PRD 亦触发。 PRD 形态为 md（含本地截图，推 Confluence 时脚本自动上传图片）。 |
| type | pipeline |
| output_format | .md |
| output_prefix | prd- |
| pipeline_position | 5 |
| depends_on | ["scene-list"] |
| optional_inputs | ["interaction-map","prototype"] |
| consumed_by | ["cross-check"] |
| owns | ["字段口径","池策略全局规则","埋点事件属性","状态机","跳转规则文字"] |
| forbids | ["视觉规范","技术实现","状态机交互细节"] |
| scripts | {"gen_prd_skeleton.py":"新建 PRD 空骨架 — python3 gen_prd_skeleton.py -p {产品线/项目} -v 1 [--mode single|split] [--profile baseline|delta] [--tier patch|feature|bundle]（baseline 落产品线根无版本号 / delta 落 deliverables 有版本号；缺省 = 普通 PRD。--tier 仅 delta 生效，定迭代档位 + §2 行文，见下文 delta 档位）","prd_compose.py":"split 模式拼接成完整 md（push 前自动调用）— python3 prd_compose.py <prd.md> -o composed.md","read_prd_section.py":"按章节读 / TOC / grep — python3 read_prd_section.py <prd.md> --toc | -s 5.1 | --grep 关键词。--toc 给每章标 [静态]/[动态]（动态 = 变更记录/决策/排期等演化章）","split_prd.py":"single → split 一次性迁移 — python3 split_prd.py <prd.md>","screenshot_for_prd.py":"PRD 截图 framework（IMAP 模式 shoot_from_imap + 原型模式 shoot_from_proto（骨架原型按 view × page discover）+ 截图同步落 .freshness.json manifest（v2：hash 而非 mtime，IMAP 按 .flow / 原型按 .p-page DOM 子树 hash 判定，无关 CSS/注释/reformat 不再误报；缺 manifest 自动降级 mtime）+ 通用 helpers）— python3 screenshot_for_prd.py --imap <html> -o <assets_dir> / --proto <html> -o <assets_dir>；项目原型脚本 import shoot_from_imap / shoot_from_proto / dismiss_all_overlays / assert_screenshots_fresh。--assert-fresh 模式供 check_prd_md.sh 调用","check_prd_md.sh":"md 自检（FAIL/WARN 分级，--skeleton 模式跳占位符 + 截图 + freshness）— bash check_prd_md.sh <prd.md> [--skeleton]。§X.Y 锚点 + 裸场景编号死链查只对 split（有 `-scenes/` 子目录）开，单文件（single delta / baseline）天然豁免；profile（按文件名 prd-*-baseline.md 判）只控 baseline 其他行为","cold_read.py":"交付前冷读反测打包（叶子完整性 7 类盲区）— python3 cold_read.py --prepare <prd.md> [--targets 3.1,4.1,5.1]。compose 全文 + 附 scene-list 落 context 文件 + 生成 N 个干净子代理探针 prompt + 落 cold-read-{date}.md 盲点清单模板。脚本只打包，实际冷读由「交付前冷读」Step 派 Agent 子代理跑","humanize/md_scan.py":"md 版扫描 — scan_human_voice_md(md_text) / scan_prd_structural_md(md_text)","core/md_renderer.py":"md 输出原语 — MdWriter / scene_5section_card / 等（被 sections_md.py 调用）","sections_md.py":"普通 12 章骨架 + 场景卡生成（被 gen_prd_skeleton.py 调用）：build_full_skeleton（普通 12 章）/ build_scene_file（split 子场景）+ 章节 render 原语与 SceneInfo 模型","sections_md_baseline.py":"baseline / delta 迭代文档集骨架（被 gen_prd_skeleton.py 调用）：build_baseline_skeleton（baseline 模块树）/ build_delta_skeleton（delta 单轮迭代）。依赖 sections_md 的 SceneInfo / build_chapter_4","check_baseline_fresh.py":"baseline 反向合并新鲜度校验（根 scripts/，非本 skill 目录）— python3 scripts/check_baseline_fresh.py {产品线}。已上线 delta 未合并报红 + 模块章超期报黄","export_tracking_xlsx.py":"埋点章节导出合并单元格 xlsx（备用：需单独发给研发时用）— python3 export_tracking_xlsx.py <prd.md> [-o out.xlsx]。按 10 列表头签名定位埋点表，通吃 baseline §9.1 / delta §7。**推 Confluence 时不用此脚本**，直接在 md_to_confluence.py 加 --merge-tracking 即可在 wiki 上实现同等合并单元格效果"} |
收到新需求 → 先按 CLAUDE.md「收到需求路由」过 PM-GATE 4 风险扫描 + 复杂度判链路，再进 Step 0。
做什么：scene-list / IMAP / prototype 之后的最终行为规格 md 文档（md + 本地截图，推 Confluence 时图片自动上传）。自包含、PM 与研发 / 设计 / QA AI 都能直接消化。承载业务对象词典 / 业务动作区块表 / 通用文案清单 / 信息层次矩阵。
何时触发：用户说「PRD / 需求文档」；IMAP / prototype 完成后输出 PRD 亦触发。
写给谁（立场）：PRD 首先要 PM 自己读得懂。全文讲人话——契约层（§3.2 业务对象词典 / §3.3 状态机）也用中文业务名（写「主播 TRTC 标志」不写 trtc_enabled）。spec coding 能力靠业务语义精度达成（类型 / 约束 / 枚举 / 状态全集写全），不靠技术黑话，研发 AI 自己反推 key / SQL / 事件。唯一英文标识符例外 = 埋点事件 / 属性名（神策外部契约，已注册 key 不可翻译，详见 §三点八）。业务方案专名（TRTC / OBS / RTMP 等行业通用词）保留。
链路分流（复杂度判定走 CLAUDE.md，本表只列 PRD 专属形态）：
gen_prd_skeleton.py 自动判projects/biweekly/README.md §4），自检仍跑 check_prd_md.shprd-{产品线}-baseline.md → 本轮需求写 delta（gen_prd_skeleton.py --profile delta），上线后 ① 补 baseline changelog 行 ② 反向合并进 baseline 模块章（手动 Edit 不重跑骨架）。baseline / delta 都要达 spec coding 规范。详见 Step 5 + artifact-conventions.md §六不做：UI 视觉规范（设计稿 + design system 承载）/ 技术方案（归 architecture-diagrams）/ 实现细节（不写 SQL / 接口 schema / 框架状态）。
hook 守的是「Read 过本文件」不看读了多少行。改 scripts/.py 用
Read 此文件 limit=80（§1+§2 即够）。改产出物（prd-.md）建议全文。
Public API（不可改签名）：
python3 gen_prd_skeleton.py -p {产品线/项目} -v {N} [--mode single|split] [--profile baseline|delta] — 新建空骨架（baseline 落产品线根无版本号 / delta 落 deliverables / 缺省普通 12 章）python3 prd_compose.py <prd.md> -o composed.md — split → 单页（push 前自动调用）python3 read_prd_section.py <prd.md> --toc | -s 5.1 | --grep 关键词 — 按章节读 / TOC / greppython3 split_prd.py <prd.md>python3 screenshot_for_prd.py --imap <html> -o <assets_dir> — IMAP 模式截图；--proto <html> 骨架原型通用截图（view × page discover）。路由规则：项目根有 scripts/screenshot_proto.py → 必须走项目脚本，禁用 --proto（项目脚本读 registry.shot_setup，含多场景页面会截到正确态；通用模式不读 registry，会停在默认态；框架已加 screenshot-route-gate 拦截）bash check_prd_md.sh <prd.md> [--skeleton] — md 自检（FAIL/WARN 分级；死链查按是否有 -scenes/ 判 split，单文件 delta / baseline 豁免）python3 cold_read.py --prepare <prd.md> [--targets 3.1,4.1,5.1] — 交付前冷读打包（context 文件 + 探针 prompt + 报告模板），实际冷读派子代理跑python3 export_tracking_xlsx.py <prd.md> [-o out.xlsx] — 埋点章节导出合并单元格 xlsx（事件级列同事件 merge）from humanize.md_scan import scan_human_voice_md, scan_prd_structural_md — md 扫描from core.md_renderer import MdWriter, scene_5section_card — md 输出原语from sections_md import build_full_skeleton, build_scene_file, SceneInfo — 普通 12 章骨架编排；from sections_md_baseline import build_baseline_skeleton, build_delta_skeleton — baseline / delta 迭代骨架改场景块前读 quickref：references/prd-scene-template-quickref.md（50 行，左图右文骨架 + 三段式定义 + 3 条约束），比读 300 行全量模板省 token。
会拦你的 hook（真实 gate 名，dispatcher 在 lib/post-checks.sh / lib/checkers.sh / lib/pre-writeedit-guards.sh）：
script-syntax-gate / cjk-punct — 写 .py/.sh + md 自动跑prd-check-gate — gen_prd*.py 后自动跑 check_prd_md.sh --skeletonprd-cross-check-gate — PRD 写入后自动跑 7 维结构校验plain-language-gate — 扫正文裸编号 / 锚点 / 翻译腔pm-visual-gate — 扫视觉越界（颜色 / 尺寸 / 描边 / 圆角 / 设备壳等视觉规格）baseline-fresh-gate — 编辑 baseline / delta 后查反向合并新鲜度cold-read-gate — delta PRD 推 Confluence 前查同目录冷读产物（缺则拦，SKIP_COLD_READ_GATE=1 跳过）skill-load-gate — 改 prd-*.md / prd-*-scenes/*.md 必先 Read 本 SKILL.md + info-ownership.md改完跑啥：
bash .claude/skills/prd/scripts/check_prd_md.sh projects/{项目}/deliverables/prd-*.md
深入读什么：完整章节归属 Read references/prd-chapter-rules.md；场景模板 Read references/prd-scene-templates.md（写 5/6/7 章前）；自检规则 grep -A 15 "^## 自检清单" SKILL.md。
写 PRD 前脑里装 4 条正文红线（踩一条
check_prd_md.sh就 FAIL）： ① 禁裸场景编号A-1 / B-2（除标题 / 2.1 表 / 截图名 / 埋点名），引用用「章节号 + 白话名」或纯白话。单文件豁免（baseline + single delta 都是单文件，模块树按编号索引合法）——死链只在 split（有-scenes/）查 ② 禁章节锚点§5.1 / §X.Y（章节号锚点 split 拼页后是死链，PRD 正文直接用白话名「见『发帖』章节」）。单文件豁免（baseline + single delta 内 §具名锚点是合法内跳）——死链只在 split 查 ③ 全文讲人话，契约层也用中文：§3.2 业务对象 / §3.3 状态机写中文字段名 + 类型 + 约束 + 枚举（不写trtc_enabled，写「主播 TRTC 标志｜布尔｜默认关」）。唯一例外 = 埋点章：PM 起事件英文名 + 属性英文名，既有事件抄神策真名（走probe_event_properties.py），新事件按 §三点八 命名约定 ④ 禁「（新增）」「（变更）」行内版本标签（会被date_tag_hits抓）。版本 delta 统一写在 1.4 章集中列
trtc_enabled / card_id）+ 禁 触发 / 读 / 写 / 事件 / API schema / DB schema。PM 用业务语义描述（「新增一条帖子记录」），研发 AI 自己反推 SQL / 事件名 / key。唯一例外 = 埋点章事件 / 属性英文名（神策外部契约）。业务方案专名（TRTC / OBS / RTMP）保留。完整禁用清单 references/prd-scene-templates.mdA-1 / B-2 / M-1 / F-1 和 §5.1 / §4.1 只能在章节标题、第 2.1 场景地图表、截图文件名、埋点事件名、md 链接里出现。正文跨章引用用「章节号 + 白话名」（见 4.1 一帖一卡）或「编号 + 白话名」（F-1 推荐加权）或纯白话名。plain-language-gate hook + check_prd_md.sh 兜底5.1.1 / 5.1.2 嵌套。一件事需要拆就拆并列 5.1 / 5.2。split_prd.py 检测嵌套直接报错references/prd-scene-templates.md §4.3.1。完整归属矩阵 references/prd-chapter-rules.md §二,:;()，禁圈数字 ①②③。check_cjk_punct.py --strict + humanize/md_scan.py 兜底flowchart skill 出 SVG / PNG 后  引用。详见 references/prd-chapter-rules.md §三点五/activity-center /user/profile = 越权。业务语义用「独立页 / 独立路由 / 独立落地页」描述，具体路径让前端决定。唯一例外：M-2 编辑页讲运营填"相对路径"字段（字段含义说明）。check_prd_md.sh 兜底hover / onclick）② DOM API（DOM / display:none）③ 国际化（i18n key）④ 缓存（cache / localStorage）⑤ 框架状态（dirty / pristine）⑥ UI 英文（modal / chip / tooltip 用「弹窗 / 胶囊 / 提示」）⑦ 像素断点（<768px / @media）⑧ 技术变量名（topicData / tag.hot 驼峰）。埋点章节是 PM 必写区：事件英文名 / 属性英文名 / 数据类型 / 触发机制 PM 必填，10 列模板见 references/prd-chapter-rules.md §三点八
probe_event_properties.py 查不到神策真实事件，若该 PRD 埋点章本就标了拟名 / 待注册，说明是本轮新增埋点、神策还没这个事件是预期状态，不等于 PM 杜撰；只有正文声称"已有事件"却查不到才是真问题。--- 水平线分隔符 — Confluence 不渲染 md 水平线且显示丑（横线断裂 / 撑满整宽），章节靠 # / ## 标题自然分隔。MdWriter.hr() 为 no-op（禁用入口），check_prd_md.sh 扫单独成行 --- → FAIL；表格分隔符 |---| 不受影响（含 |）> 引用块 — Confluence blockquote 渲染丑（左竖线 + 灰底 + 缩进，破坏文档流）。业务故事（章节 / 场景定调）改 **业务故事**：正文（「业务故事」加粗、正文不加粗），章首不要定调金句。MdWriter.pullquote() 为 no-op、chapter_story() 已改粗体引导，check_prd_md.sh 扫 ^> → FAIL（baseline 历史 living 文档豁免，等迭代消化）写 bullet / 散文时守这三条，check_prd_md.sh 报 WARN 只是兜底——写时就该写对：
1. 2. 3. 编号（表格行豁免）打点口径 = X。B 点 = Y。展示位置 = Z）→ 一项一 bullet，句号只落行尾（表格行 / 决策记录章 / 冒号引子 bullet 豁免）别换标点绕检测：把多件独立事从分号改成逗号 / 顿号焊同一行只是骗过 checker（它数不到逗号），认知负荷更高。判断该不该拆看语义（多件独立事 vs 一件事的子项），不看凑没凑过阈值。权威定义 + Red Flags 见 .claude/runbooks/human-voice-rules.md ⑥。
§2.x 场景正文的 **现状** / **修改点**（delta，旧称「本轮」）bullet 是 FAIL 级契约（不是 WARN）：这几个标签下的 bullet 一条只扛一个原子事实——一件事的多阶段（原状态 → 变更 → 现状）用 → 串成一行链，多件独立事各自一条 bullet，句号只落行尾不做行内焊接。check_prd_md.sh 的 scene_prose_runon 维阻断 commit（§6 决策记录章天然够不着，论证句照旧可长）。连贯叙事确实该整段保留时走逃生阀 SKIP_SCENE_PROSE_GATE=1——用前先向用户说明为什么这段不该拆（知会制）。
正反例 + 细则（含 delta 叙事对保留指引）见 references/prd-chapter-rules.md §三，自检清单 9/10/11。
三件套只管一行内怎么写；下面两条管同一件事被写几遍——delta 臃肿的真源是跨小节复读，不是长句：
prd-scene-templates.md §4.0）。跨模块 / 验收 / §6 决策需带到时只写差异或指针（「见 §5.1」/「同上，仅 H5 不同：…」），不重抄原句。[ ] 前缀、1:1 对应，删掉。判据：读者在 A 处已知的规则，B 处再出现全文 = 废话；B 处只在"这里有什么不同 / 跳哪看"时才写。
PRD 是 baseline 决策的集中体现，不是重新发明。md 形态保证：自包含 / 人读友好 / AI 可消费。
| 模式 | 触发 | 结构 |
|---|---|---|
| Single | 场景数 ≤ 10 | prd-{简称}-v{N}.md（单文件，12 章全在内）+ assets/ |
| Split | 场景数 > 10 / --mode split 强制 | prd-{简称}-v{N}.md（主骨架）+ prd-{简称}-v{N}-scenes/（每场景一个 md，~80-150 行）+ assets/ |
模式自动判定：gen_prd_skeleton.py 读 scene-list.md 数场景数。single → split 用 split_prd.py，反向用 prd_compose.py。
PRD md 是单一权威产出物，下列类型信息直接写进对应章节：
| 类型 | 落位 |
|---|---|
| 业务对象词典（属性 / 生命周期 / 数据来源 / 关系） | 第 3.2 章 |
| 业务动作（UI 场景） | 5/6/7.x 子场景的「页面元素 & 规则」区块表 4 列 |
| 业务动作（横切策略 / 后端流程） | 5/6/7.x 子场景的粗体段 + bullet |
| 条件分支业务规则（可断言形式 · 可选档） | 第 4 章「给定 ｜ 当 ｜ 则」三列表（含分支 / 阈值 / 多业务态时用，见 references/prd-scene-templates.md §4.5；branch_prose_hits WARN 兜底） |
| 状态机 | 第 3.3 章 |
| 非功能性 SLA | 第 10 章 |
| 优先级 P0/P1/P2 | 第 2.2 章 |
| 通用文案清单 | 第 8 章 |
| 场景独有文案 | 区块表「文案」列 |
| 信息层次 / 数据来源 | 区块表「数据来源」列 |
| 视觉调性 | 不单独记录（UI 设计稿 + design system 承载） |
PRD 里禁写 mermaid / PlantUML 源码——Confluence 不渲染。按复杂度分档：
flowchart skill 出 drawio + SVG，PRD 用  引图详见 references/prd-chapter-rules.md §三点五。
写 §1 PR-FAQ 前 → Read
.claude/runbooks/pm-methodology.md §三 Outcome over Output（含 PR-FAQ 自检）。写 delta §6 决策段 → Readpm-methodology.md §二 决策段四段法（§6 只写 WHY / 否决 / 取舍，禁复述 §2 已有的交互 / 字段 / 页面细节——这是 delta 最大字数黑洞）。
python3 .claude/skills/prd/scripts/gen_prd_skeleton.py -p {产品线/项目} -v {N}
生成空骨架（含 {{ 待填：... }} 占位符）。PM + AI 按章节填，截图放 deliverables/assets/，md 用 ./assets/xxx.png 相对路径。
填充顺序（自上而下，编号规则 → artifact-conventions.md §一，回读上下文 → §三）：
references/prd-scene-templates.md）md_to_confluence.py <prd.md> --merge-tracking，wiki 上事件级列自动合并单元格，无需额外文件python3 .claude/skills/prd/scripts/export_tracking_xlsx.py <prd.md> 导 xlsx，用于不看 wiki 的场景每填完一段跑一次 check_prd_md.sh <md> --skeleton（宽松模式跳占位符 / 截图 / freshness）。终态推 Confluence 前去 --skeleton 跑严格。
md 是源文件，PM 直接 VS Code / Edit 改。改完跑 check_prd_md.sh 过则推。不需要 gen_prd_v{N+1}.py 这种 per-project 生成器。
split 模式：
prd-xxx-v{N}.mdprd-xxx-v{N}-scenes/{view}-{编号}-{名}.mdgen_prd_skeleton.py --force 会覆盖生成的文件，但不会清理以下 stale：
⚠ 已迁移 / 挪到 J 系列后 → 老子场景 md 仍在 {scenes-dir}/back-X-N-*.md 没删mv 重命名骨架后再 --force → 脚本再生一份，二次 mv 可能嵌套重生前固定流程：
# 1. 看现状
ls projects/{项目}/deliverables/prd-*-v{N}-scenes/
# 2. 对照 scene-list 期望（去掉 ⚠ 已迁移 行）
# 3. 强烈建议先删主 md + scenes 目录
rm -f projects/{项目}/deliverables/prd-*-v{N}.md
rm -rf projects/{项目}/deliverables/prd-*-v{N}-scenes/
# 4. 跑 gen
python3 .claude/skills/prd/scripts/gen_prd_skeleton.py -p {项目} -v {N}
# 5. 如要 rename（骨架短名 → 项目全称），单步 mv 别累加
别 --force 一把跑完——旧 stale 会被拼进 compose，check_prd_md.sh 会抓裸编号 / 消失场景引用 / 类型错位。
何时必须重拍（任一触发）：源 HTML 改了 / 新增 / 修改 / 删除场景编号 / 改设备布局 / 视觉规范 / 截图覆盖范围。
优先级 & 调用：
projects/{项目}/scripts/screenshot_for_prd*.py → 直接调，不自己写：
python3 projects/{项目}/scripts/screenshot_for_prd.py
shoot_from_imap）；原型截图模式自管的（如 activity-center），应 import framework helperspython3 .claude/skills/prd/scripts/screenshot_for_prd.py --imap <imap.html> -o deliverables/assets/
--scenes 时按 .st h2 discover 全截；白名单格式 --scenes "scene-A-1.png=A-1 · 完整全貌,..."python3 .claude/skills/prd/scripts/screenshot_for_prd.py --proto <proto.html> -o deliverables/assets/
build_proto_skeleton 约定（.gnav-view-section × .p-page）自动遍历 view × page，出 proto-{view}-{page}.png；白名单 keyword 匹配 view_id/page_id。仅适用骨架生成的原型（现行标准）launch_page / dismiss_all_overlays / fix_dpi / assert_screenshots_fresh），不从零起步（--proto 遇非骨架结构会报错引导到此）：
sys.path.insert(0, "<repo>/.claude/skills/prd/scripts")
from screenshot_for_prd import launch_page, dismiss_all_overlays, fix_dpi
源 HTML 探测：discover_source_html 合并 prototype + IMAP 候选（*原型*.html / proto-*.html / *交互大图*.html / imap-*.html），取 mtime 最新。任一源动了 → PNG stale。archive / deprecated 子串排除。
命名 / 路径：
scene-{编号}.png（如 scene-A-1.png / scene-D-0-mylive.png）；原型模式 proto-{view}-{page}.png（如 proto-h5-center.png）deliverables/assets/，md 引用 （split 子场景用 ../assets/）自动守门：check_prd_md.sh --assert-fresh 比对源 HTML mtime（实为 .freshness.json hash 判定 .flow DOM 子树，无关 CSS / 注释不再误报；缺 manifest 降级 mtime），FAIL raise + 列过期清单。
推 Confluence：图片由 scripts/md_to_confluence.py 自动上传 attachment（扫 ./assets/），PM 无需手调。
机械自检（
check_prd_md.sh+ cross-check 7 维）抓「形」——编号 / 术语 / 字段格式 / 死链。叶子完整性盲区（实时字段刷新触发点没写、快照字段生命周期模糊、展示窗口与数据保留期不对齐、跨章口径打架）是单文档语义缺口，机械抓不到，靠冷读反测。7 类盲区权威定义在references/prd-scene-templates.md §4.6。硬约束：冷读判断必须派干净上下文子代理（Agent 工具）——同 session 已读上下文会脑补，测不出盲点。脚本只打包探针，不调 Agent。
python3 .claude/skills/prd/scripts/cold_read.py --prepare <prd.md> [--targets 3.1,4.1,5.1]
--targets 时自动选「静态」实体 / 规则 / 状态机章（最易埋叶子洞的章）。脚本产出：① context 文件（compose 全文 + scene-list，落 /tmp）② 每个 target 一段 === PROBE === 探针 prompt ③ cold-read-{date}.md 盲点清单模板（落 PRD 同目录）。Explore / general-purpose），N 个 target 并行派。子代理 prompt 已内置隔离铁律（只 Read context 文件、禁读写 session-state、不脑补作者本意）。cold-read-{date}.md，每条四件套（位置 + 盲区类别 + 冷读者会怎么误读 + 建议补法）。check_prd_md.sh。cross-check skill 的 Reader Testing 终验时调用本工序（不在 cross-check 复述机制）。
split 模式：脚本检测到 -scenes/ 强制 PM 选推送方式（不再静默 compose 推单页）。
方式 A · 1 父页 + N 章节子页（推荐 split 项目）：
# 新建
python3 scripts/md_to_confluence.py <prd.md> --split-children-by-chapter --parent-id <PARENT_SPACE_ID>
# 更新
python3 scripts/md_to_confluence.py <prd.md> --split-children-by-chapter --update-id <PARENT_PAGE_ID>
父页含 §1-3 + §8-12 全文 + §4-7 章节链接到子页；子页 = 该章全部场景内容。更新模式按子页 title 自动匹配（子页名固定「{Part 0/1/2/3 白话标题}」）。
方式 B · 单页 compose（场景少 / 历史页已是单页）：
python3 scripts/md_to_confluence.py <prd.md> --no-split --parent-id <id>
python3 scripts/md_to_confluence.py <prd.md> --no-split --update-id <id>
--no-split 绕开 split 门强制 compose 单页；single 模式 PRD（无 -scenes/）不需要此 flag。
single 模式 PRD：
python3 scripts/md_to_confluence.py <prd.md> --parent-id <id>
python3 scripts/md_to_confluence.py <prd.md> --update-id <id>
自动行为（所有模式）：
 与 <img src="./..."> → 上传 attachment → 路径改写为 attachment 文件名（DEFAULT_IMAGE_WIDTH=360px）<table>：生成器吐的带表头 HTML <table>（左列 <img> + 右列 <ol>/<ul> 三段式）byte-clean 直渲原生 storage table，wiki 可编辑单元格 + 往返回流（fetch_confluence.py pandoc 模式拉回零丢失）<table> + <ul><li> bullet（按 cell 内 ； 切）。source 写 ； 串多条规则即可，不要手敲 <br> / bullet- / > / --- / 空行」。由此形成承重约定：协作头用表格（| 开头）→ 保留上 wiki；内部机制说明用 bullet → 剥掉。delta 协作表因此留在 wiki 上给同事看版本 / 责任人 / 节奏，baseline 的「承重不变量」bullet 仍被剥离。源 md 不动只裁推送版。--exclude-section <关键词> 追加排除 / --keep-preamble 保留头部（细节见 cli-cheatsheet）推送方式选择规则：
首推同名冲突：--parent-id create 时若 space 下已有同名页，Confluence 返回 HTTP 400。脚本在 create 前已做 search_pages 同名预检，命中会打印同名页 URL + 提示 PM 三选一：
--title "示例社区交易卡片 PRD（2026-05-12）" 改名（带日期 / 版本号 / 场景范围）--update-id <历史 pageId> 覆盖推AI 在 PM 推之前主动问一次。
产品线已立 prd-{产品线}-baseline.md 时，迭代不重写 baseline，走文档集循环（模型全貌见 artifact-conventions.md §六）：
gen_prd_skeleton.py -p {产品线} -v 1 --profile baseline，落产品线根、无版本号、living。此后绝不重跑骨架（--force 会 clobber 已填内容），反向合并一律手动 Edit。gen_prd_skeleton.py -p {产品线} -v {版本} --profile delta 生成 delta 骨架，脚本直接落 deliverables/{季度}/{版本}/（季度 = 2026Q3 格式，按季度 KPI 聚集；一个季度下多版本，如 deliverables/2026Q3/2.1.1/）。--quarter 缺省用当前季；启动时自动打印 baseline 路径 + 该季已有版本供定版（不自动 +1）。该目录整包装该轮 delta PRD + imap + prototype + 该版 assets。只写本轮 N 需求 + WHY，术语 / 模块树 / 未变规则引 baseline 不重复，跨引 baseline 锚场景编号 / 业务规则 ID。archive/{季度}/。
check_baseline_fresh.py {产品线} + baseline-fresh-gate hook 守第一层（已上线 delta 未合并报红）；baseline 模块章头 最后核对线上: 日期 / 人 守第二层（超 60d 报黄）。骨架真实产出章节集：baseline = 概览 / 术语 / 模块树 / 全局规则 / N 个模块章 / 文案 / 非功能 / 变更记录；delta = 协作头表 + 9 章树（§1 背景价值 / §2 本轮需求 / §3 业务对象增量 / §4 状态机增量 / §5 全局规则增量 / §6 决策记录 / §7 埋点 / §8 排期 / §9 反向合并指引）。
delta 协作头表（紧跟 H1，对齐公司 PRD 模板的 PRD信息 / 团队信息 / 资源对接三张表，压成一张）：PRD 版本 / 状态 / 拟制人 · 日期 / 火效 / 重要性 · 紧迫性 / 迭代档位 / 端侧范围 / 提测 · 走查 · 上线 / 产品 · 交互 / 设计 · 设计稿 / 前端 · 后端 / 测试。三条约束：
sync_hx_status.py 按此回写，勿调列位delta 迭代档位（--tier，决定 §2 行文）：一份 delta 先认档位，再按档位组织 §2 本轮需求。
| 档位 | --tier | 触发 | 版本号 | §2 行文 |
|---|---|---|---|---|
| 补丁包 | patch | 散修复 + 小调，互不依赖 | x.y.z 三段 | §2.0 索引表 6 列（编号 / 需求 / 端 · 模块 / 修改点 / 验收 / 优先级）收口，默认全部进表；命中升块判据的重项才另起 H3（见下） |
| 内聚特性 | feature（默认） | 单一能力，有新对象 / 状态机 | x.y 两段 | 平铺，按用户旅程叙事 |
| 集合体 / 多团队 | bundle | N 个松耦合需求跨模块 / 团队 | x.y 两段 | 强制 §2.0 索引表 + 按单轴分组 H2 |
patch / bundle 自动吐 §2.0 本轮需求索引表。两档列不同：
patch = 编号 / 需求 / 端 · 模块 / 修改点 / 验收 / 优先级。骨架不为任何需求预生成 H3 块——轻项在表里就讲完了，重项才另起。升块判据（任一命中）：新增 / 变更业务对象 · 涉状态流转 · 跨端行为不一致 · 有取舍要在 §6 交代；重项模板在骨架 §2.0 表后的 HTML 注释里，复制出来用。「默认最轻、升块是加法」是承重设计，反过来（预生成四槽靠删）必然被填满。check_prd_md.sh §1.6 报 WARN 兜底（该塌没塌 + 「详见 2.N」悬空指针）bundle = 编号 / 需求 / 分组 / 反向合并目标 / 优先级，分组只许沿一条轴（模块 > 用户旅程 > 跟版边界 > 团队，选读者跨引最少的一条），每条需求仍出 H3 块prd-{线}-{版本}-{端}.md（如 -web.md / -app.md），每个文件是完整独立的 delta（含自己的 §1–§9），静态章按本端内容裁剪（无关的业务对象 / 状态机 / 规则整章删），原合并文件加废弃注释指向拆分后的文件。同版本的索引表只在原文件或约定的一端保留，拆分后各文件 §2.0 只列本端需求。--tier（§2 组织）与四支柱填充（§3/§4/§5）正交，是两根独立的轴：
--tier 只管 §2 怎么排版（索引 + 分组 vs 平铺叙事），不决定四支柱有没有内容。两者各管各的，别混。反向合并映射唯一落在 §9 表：骨架正文不吐「本轮无 X 则删本章 / 上线后反向合并进 baseline §X」这类章首导语（plumbing 进不了交付物）。哪章可删、合并到 baseline 哪章，看 §9 反向合并指引表（推 Confluence 时 §9 自动剥离，见 Step 4）。
# 输出 md 字符串
from core.md_renderer import MdWriter, scene_5section_card, bold, italic
w = MdWriter()
w.h1("1. 项目背景与目标")
w.h2("1.1 背景")
w.bullet_list(["痛点 A", "痛点 B"])
w.field_bullet("业务描述", "用户点「发布」把内容发到社区")
w.field_bullet_list("前置条件", ["已登录", "未被禁言"])
w.table(headers=["编号", "场景"], rows=[["A-1", "发帖"]])
w.image("./assets/scene-A-1-wireframe.png", alt="发帖低保真")
md = w.render()
# 12 章骨架编排
from sections_md import build_full_skeleton, build_scene_file, SceneInfo
md = build_full_skeleton(info={"project_name": "xxx", "version": "1", "scenes": [...]})
# 解析现有 md
from humanize.md_scan import scan_human_voice_md, scan_prd_structural_md
voice_hits = scan_human_voice_md(md_text)
struct_hits = scan_prd_structural_md(md_text, scene_count=10)
埋点表交付方式（两种，按场景选）：
# 推 Confluence（首选）——wiki 上事件级列自动 rowspan 合并，无需额外文件
python3 scripts/md_to_confluence.py <prd.md> --merge-tracking --update-id <pageId>
# 单独发给研发（备用）——导 xlsx，用于不看 wiki 的场景
python3 .claude/skills/prd/scripts/export_tracking_xlsx.py <prd.md> [-o out.xlsx]
bash check_prd_md.sh <prd.md> exit 0（§X.Y 锚点 + 裸场景编号死链查只对 split 开，单文件 = baseline + single delta 天然豁免；profile 仅控 baseline 其他行为）./assets/ 下所有引用文件存在grep -E "^- \*\*(触发|读|写|事件|API)" <md> 无命中（UI 场景统一走区块表）[ABCDEFM]-[0-9] 仅出现在「编号 + 白话名」组合或链接里（单文件 = baseline + single delta 豁免，仅 split 拦）{{ 待填 无命中（终态）python3 scripts/check_cjk_punct.py <md> --strict exit 0见 X.Y 白话名 而非裸 见 X.Y / 见 A-1； / ;）= 子句堆一坨，拆成 bullet 或 1. 2. 3. 编号；表格行豁免（cell 内 ； 是 Confluence 切 bullet 的约定分隔符）。！？； 之间）≥ 100 字 = 一口气读不完，拆句或转列表；表格行豁免。与分号校验互补（分号管「；」串，长句管「，」串）打点口径 = X。B 点 = Y。展示位置 = Z → 各自成 bullet）。一项一行、句号只落行尾。表格行 / 决策记录章 / 冒号引子 bullet 豁免。与分号 / 长句互补，细则 references/prd-chapter-rules.md §三cold_read.py + 派干净子代理），盲点逐条 triage。7 类盲区见 references/prd-scene-templates.md §4.6---：grep -cE '^-{3,}\s*$' <md> = 0（单独成行连字符 = Confluence 丑水平线；表格 |---| 不算）。章节用 h1/h2 分隔>：grep -cE '^\s*>' <md> = 0（Confluence blockquote 渲染丑；业务故事改 **业务故事**：正文；baseline 例外）必读（写 PRD 前加载）：
references/prd-chapter-rules-quickref.md — 12 章结构 / 迭代 scope / baseline-vs-delta / 字段归属 / Confluence 约束 / 越界禁词 / must-have / split 结构（~100 行速查，写 PRD 前读这页）按需读（命中具体步骤再加载）：
references/prd-chapter-rules.md — 章级细则（禁词完整清单 / 状态机模板 / 埋点边界 / 自检清单），写具体章节命中细则时读references/prd-scene-templates.md — 写第 5/6/7 章场景前加载（UI 场景区块表 / 横切策略模板 / 数据影响写法）references/prd-optional-sections.md — §1.6 竞品调研 / §1.7 多方案对比 模板，PM 加可选章节时 copyreferences/metrics-framework.md — 写 §9 埋点 / §1.4 北极星指标时加载.claude/runbooks/human-voice-rules.md，PRD 形态规则在 prd-chapter-rules §三 / §三点八gen_prd_skeleton.py 默认生成 12 章骨架。以下两节按需追加在 §1.5 后、§2 前：
模板见 references/prd-optional-sections.md，骨架不默认生成，PM 觉得需要时从模板 copy 进 PRD md。
判定信号（任一）：
不强制 12 章。PM 自定章节（建议对标共建 PRD 模板），文档仍 md，仍走 md_to_confluence.py 推 wiki。
文档分工建议：方案概览 / 系统拓扑 / 各系统职责 / 接口 schema / 资金对账 / 风险与回滚 / 灰度计划。