CaufieldZ
CaufieldZ/pm-workspace-public
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/CaufieldZ/pm-workspace-public --skill prd命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 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 / 资金对账 / 风险与回滚 / 灰度计划。