Skip to main content Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Un comando directo omite el prompt de revisión. Revisa el origen antes de ejecutarlo.
npx skills add https://github.com/CaufieldZ/pm-workspace-public --skill prdEl comando permanece en una sola línea. Desplázate horizontalmente para revisarlo antes de copiarlo.
¿Prefieres una copia local? Descarga los archivos que SkillsMP tiene disponibles ahora.
Explorador de archivos
24 archivos| 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 上实现同等合并单元格效果"} |
PRD Skill（产品需求文档，md 版）
触发与定位
收到新需求 → 先按 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 专属形态）：
- single 模式 → 场景 ≤ 10，单 md
- split 模式 → 场景 > 10，主骨架 + scenes/，
gen_prd_skeleton.py 自动判
- 散件链路（biweekly 内 / 单功能点 / 小修，≤ 50 行 md）→ 不走 12 章骨架，用 6 章紧凑模板（见
projects/biweekly/README.md §4），自检仍跑 check_prd_md.sh
- 方案型项目（跨 ≥ 2 系统 / 资金流转 / 多团队 / 纯后端）→ 不走 pipeline，PM 自定章节，文档仍 md（详见 § 注意事项）
- 老项目持续迭代（baseline 文档集模型）：产品线已立
prd-{产品线}-baseline.md → 本轮需求写 delta（gen_prd_skeleton.py --profile delta），上线后 ① 补 baseline changelog 行 ② 反向合并进 baseline 模块章（手动 Edit 不重跑骨架）。baseline / delta 都要达 spec coding 规范。详见 Step 5 + artifact-conventions.md §六
- 老项目 docx 维护 → 从零写新 md v{N+1} 推覆盖原 wiki 页，老 docx 进 archive/legacy-docx/
不做：UI 视觉规范（设计稿 + design system 承载）/ 技术方案（归 architecture-diagrams）/ 实现细节（不写 SQL / 接口 schema / 框架状态）。
改脚本前 30 秒
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 / grep- — single → split 一次性迁移
python3 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。
硬规则（FAIL 即拦）
写 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 章集中列
10 条核心硬规则
- 全文讲人话，不写技术黑话 — 全文（含契约层 §3.2/3.3）禁 snake_case 研发字段（
trtc_enabled / card_id）+ 禁 触发 / 读 / 写 / 事件 / API schema / DB schema。PM 用业务语义描述（「新增一条帖子记录」），研发 AI 自己反推 SQL / 事件名 / key。唯一例外 = 埋点章事件 / 属性英文名（神策外部契约）。业务方案专名（TRTC / OBS / RTMP）保留。完整禁用清单 references/prd-scene-templates.md
- 正文禁裸场景编号 + 禁 §X.Y 章节锚点（见红线 ①②，单文件 = baseline + single delta 同样豁免，死链只在 split 查）—
A-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/6/7 章子场景必须扁平 — 禁
5.1.1 / 5.1.2 嵌套。一件事需要拆就拆并列 5.1 / 5.2。split_prd.py 检测嵌套直接报错
- 同一字段只写一次 — 跨场景共用规则进第 4 章，场景独有进 5/6/7.x 系统检查；通用文案进第 8 章，场景文案进 5/6/7.x；状态机进 3.3，场景状态分支进 5/6/7.x；异常场景共性进第 4 章「全局异常降级总则」（接口超时 / 缓存兜底 / 全站规则继承 / 承载方边界），场景文件只留 1–3 条独有项 + 一行豁免注释。异常表 4 不写规则见
references/prd-scene-templates.md §4.3.1。完整归属矩阵 references/prd-chapter-rules.md §二
- CJK 标点 + 圈数字 — CJK 旁禁半角
,:;()，禁圈数字 ①②③。check_cjk_punct.py --strict + humanize/md_scan.py 兜底
- 禁 mermaid / PlantUML / HTML 注释 — Confluence markdown 宏不渲染，写了在 wiki 上看到源码。流程图改「起点 / 终点 / 触发 / 延迟」表 + 一句路径文字；状态机改「起始状态 / 触发事件 / 终止状态 / 谁触发」表。必须图走
flowchart skill 出 SVG / PNG 后  引用。详见 references/prd-chapter-rules.md §三点五
- 禁具体 URL / 路由 — PM 定业务不定技术实现。出现
/activity-center /user/profile = 越权。业务语义用「独立页 / 独立路由 / 独立落地页」描述，具体路径让前端决定。唯一例外：M-2 编辑页讲运营填"相对路径"字段（字段含义说明）。check_prd_md.sh 兜底
- PM 角色越界禁词 — 禁词分类：① JS 事件（
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 §三点八
- 核埋点真伪先看该 PRD 是否自标「拟名 / 待注册」：
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 文档豁免，等迭代消化）
行文 WARN 三件套（写作时就按这个写，别等 check 抓）
写 bullet / 散文时守这三条，check_prd_md.sh 报 WARN 只是兜底——写时就该写对：
- 单行 ≥ 2 分号 → 拆 bullet 或
1. 2. 3. 编号（表格行豁免）
- 句段 ≥ 100 字 → 拆句或转列表（表格行豁免）
- bullet 行内句号串并列项（
打点口径 = 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 最大字数黑洞，句法三件套管不到）
三件套只管一行内怎么写；下面两条管同一件事被写几遍——delta 臃肿的真源是跨小节复读，不是长句：
- 一条规则只完整讲一次（单一真相位）：每条业务规则的完整表述只落一个位置（delta 走三列时 = 规格表格子；见
prd-scene-templates.md §4.0）。跨模块 / 验收 / §6 决策需带到时只写差异或指针（「见 §5.1」/「同上，仅 H5 不同：…」），不重抄原句。
- 验收写"可验证判定点"，不复述规格：每条验收 = QA 能勾的断言（做了 X → 应观察到 Y）。能从规格表直读的（有 X 字段、显示 Y）不写；只写反向 / 边缘 / 跨端断言。若某条只是规格加
[ ] 前缀、1:1 对应，删掉。
- 禁反向声明：PRD 不写「不展示 X」「不做 Y」这类反向否定，把「是什么」列清楚即可——无穷的否定只会添乱。
判据：读者在 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 不渲染。按复杂度分档：
- 简单二端流程（≤ 3 节点 / 单分支）→ 起点 / 终点 / 触发 / 延迟表，骨架默认生成在 §2.3 / §3.3
- 多角色 / 多分支 / 跨系统（内审 L58 硬指标必填）→ 走
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 决策段 → Read pm-methodology.md §二 决策段四段法（§6 只写 WHY / 否决 / 取舍，禁复述 §2 已有的交互 / 字段 / 页面细节——这是 delta 最大字数黑洞）。
Step 0：新建 PRD（scaffold + 手填）
python3 .claude/skills/prd/scripts/gen_prd_skeleton.py -p {产品线/项目} -v {N}
生成空骨架（含 {{ 待填：... }} 占位符）。PM + AI 按章节填，截图放 deliverables/assets/，md 用 ./assets/xxx.png 相对路径。
填充顺序（自上而下，编号规则 → artifact-conventions.md §一，回读上下文 → §三）：
- 第 1 章背景目标（对照 baseline 概览 / 术语章 + projects/product-lines.md）
- 1.4 核心变更的基线是「当前线上」，不是「之前的 PRD 版本」。线上无此功能 → 全部【新增】，不写【变更】；元数据「线上基线」字段也写「无（本期全新增）」
- 1.5 用户角色写真实角色（发帖者 / 阅读者 / 运营 / 数据分析）+ 可见 / 可操作范围，不凑没上的角色
- 第 2 章场景地图（已自动从 scene-list 填好，PM 调整优先级）
- 第 3 章术语 + 业务对象
- 3.2 业务对象只写本期新增对象，既有对象（帖子 / 评论 / 作者等社区线上已有实体）一句「沿用线上现状，本 PRD 不重新定义」带过，不脑补状态机 / 字段 / 生命周期
- 3.3 状态机同理：只画本期新对象，既有对象状态沿用现状
- 第 4 章全局业务规则（先定 contract）
- 第 5/6/7 章子场景（按模板逐个填，可并行；UI 场景走区块表 4.1，横切策略走粗体段 4.2，详见
references/prd-scene-templates.md）
- 第 8/9/10 章（文案 / 埋点 / SLA，并行）。埋点表写完后：
- 推 Confluence（首选）：
md_to_confluence.py <prd.md> --merge-tracking，wiki 上事件级列自动合并单元格，无需额外文件
- 单独发给研发（备用）：
python3 .claude/skills/prd/scripts/export_tracking_xlsx.py <prd.md> 导 xlsx，用于不看 wiki 的场景
- 第 11/12 章（排期 + 附录，最后）
每填完一段跑一次 check_prd_md.sh <md> --skeleton（宽松模式跳占位符 / 截图 / freshness）。终态推 Confluence 前去 --skeleton 跑严格。
Step 1：升版（直接改 md）
md 是源文件，PM 直接 VS Code / Edit 改。改完跑 check_prd_md.sh 过则推。不需要 gen_prd_v{N+1}.py 这种 per-project 生成器。
- 改主骨架（1-4 / 8-12 章）→ 直接编辑
prd-xxx-v{N}.md
- 改某场景 → 编辑
prd-xxx-v{N}-scenes/{view}-{编号}-{名}.md
- 加新场景 → 主 md 的 5/6/7 章 bullet 加链接 + scenes/ 目录建新 md
- 删场景 → 主 md 删链接行 + 删 scenes/ 文件
Step 2：重生骨架的 stale 清理（--force 陷阱）
gen_prd_skeleton.py --force 会覆盖生成的文件，但不会清理以下 stale：
- scene-list 把旧场景标
⚠ 已迁移 / 挪到 J 系列后 → 老子场景 md 仍在 {scenes-dir}/
- scene-list View 分组调整（如 back → cross 前缀）→ 旧
back-X-N-*.md 没删
- PM 手动
mv 重命名骨架后再 --force → 脚本再生一份，二次 mv 可能嵌套
ls projects/{项目}/deliverables/prd-*-v{N}-scenes/
rm -f projects/{项目}/deliverables/prd-*-v{N}.md
rm -rf projects/{项目}/deliverables/prd-*-v{N}-scenes/
python3 .claude/skills/prd/scripts/gen_prd_skeleton.py -p {项目} -v {N}
别 --force 一把跑完——旧 stale 会被拼进 compose，check_prd_md.sh 会抓裸编号 / 消失场景引用 / 类型错位。
Step 3：截图回填
何时必须重拍（任一触发）：源 HTML 改了 / 新增 / 修改 / 删除场景编号 / 改设备布局 / 视觉规范 / 截图覆盖范围。
- 项目内有
projects/{项目}/scripts/screenshot_for_prd*.py → 直接调，不自己写：
python3 projects/{项目}/scripts/screenshot_for_prd.py
历史项目脚本多是 wrapper（保留项目 SCENE_MAP 白名单 + 调 framework shoot_from_imap）；原型截图模式自管的（如 activity-center），应 import framework helpers
- IMAP 模式新项目 → framework CLI：
python3 .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 · 完整全貌,..."
- 骨架原型模式（小迭代只做 prototype 常用） → framework CLI，无需写项目脚本：
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。仅适用骨架生成的原型（现行标准）
- 手写 / 非骨架原型 → 写项目脚本 import framework helpers（
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 无需手调。
Step 3.5：交付前冷读（叶子完整性反测 · 推 Confluence / 交付研发前必跑）
机械自检（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 同目录）。
- 派干净子代理逐 target 跑：把每段 PROBE prompt 原样喂 Agent 工具（
Explore / general-purpose），N 个 target 并行派。子代理 prompt 已内置隔离铁律（只 Read context 文件、禁读写 session-state、不脑补作者本意）。
- 回填盲点清单：把各子代理返回的盲点聚合进
cold-read-{date}.md，每条四件套（位置 + 盲区类别 + 冷读者会怎么误读 + 建议补法）。
- 逐条 triage：每条标「补文档 / 留版本 / 误报」。补 = 回 PRD 对应章补一句 / 一列 / 一行（业务语言）；属承重不变量则同步反向合并进 baseline（走 §9 指引）。补完重跑
check_prd_md.sh。
cross-check skill 的 Reader Testing 终验时调用本工序（不在 cross-check 复述机制）。
Step 4：推 Confluence
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。
python3 scripts/md_to_confluence.py <prd.md> --parent-id <id>
python3 scripts/md_to_confluence.py <prd.md> --update-id <id>
- 正文原生渲染：markdown-it 把散文 / 标题 / 表格 / 嵌套列表转原生 Confluence storage（不再包 markdown 宏灰框，wiki 上可视化编辑）。markdown-it 不可用时降级回宏 fallback
- 本地图片：扫
 与 <img src="./..."> → 上传 attachment → 路径改写为 attachment 文件名（DEFAULT_IMAGE_WIDTH=360px）
- 左图右文
<table>：生成器吐的带表头 HTML <table>（左列 <img> + 右列 <ol>/<ul> 三段式）byte-clean 直渲原生 storage table，wiki 可编辑单元格 + 往返回流（fetch_confluence.py pandoc 模式拉回零丢失）
- 区块表自动渲染：识别 4 列表头 → 整段切走转原生 storage
<table> + <ul><li> bullet（按 cell 内 ； 切）。source 写 ； 串多条规则即可，不要手敲 <br> / bullet
- 推送前剥离内部内容：① 顶级标题含「反向合并指引」的整章（delta §9，PM 上线后 checklist）② 文档头元信息块——判据是「H1 与首章之间是否全为
- / > / --- / 空行」。由此形成承重约定：协作头用表格（| 开头）→ 保留上 wiki；内部机制说明用 bullet → 剥掉。delta 协作表因此留在 wiki 上给同事看版本 / 责任人 / 节奏，baseline 的「承重不变量」bullet 仍被剥离。源 md 不动只裁推送版。--exclude-section <关键词> 追加排除 / --keep-preamble 保留头部（细节见 cli-cheatsheet）
- split 项目首推 → AI 必须问 PM 选 A / B 再执行
- split 项目复推 → 默认 A 方式（保持 1 父 N 子结构）
- 父子页结构一旦上线就不要轻易变（B 转 A 要手工删旧子页或反之）
首推同名冲突：--parent-id create 时若 space 下已有同名页，Confluence 返回 HTTP 400。脚本在 create 前已做 search_pages 同名预检，命中会打印同名页 URL + 提示 PM 三选一：
- 新建新版页：加
--title "示例社区交易卡片 PRD（2026-05-12）" 改名（带日期 / 版本号 / 场景范围）
- 覆盖历史页：改用
--update-id <历史 pageId> 覆盖推
- 历史页先归档：手工 wiki 把历史页移到 archive 空间 / 加后缀「- 历史版本」，再跑原命令
Step 5：老项目迭代（baseline / delta 循环）
- baseline 首建（仅迁移 / 首建一次）：
gen_prd_skeleton.py -p {产品线} -v 1 --profile baseline，落产品线根、无版本号、living。此后绝不重跑骨架（--force 会 clobber 已填内容），反向合并一律手动 Edit。
- 写本轮 delta：
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。
- 上线后承重不变量（顺序不可乱）：先在 baseline 变更记录章写 changelog 行（日期｜触及模块｜delta 链接｜状态=已登记）→ 反向合并进 baseline 对应模块章（手动 Edit）→ 状态推进「已合并」→ 整季度/版本文件夹归
archive/{季度}/。
- 高价值 delta 的 Outcome 闭环（一句话，不建结构）：§1 价值段用一句话写清本轮假设 + 反转条件（「因为 X 给 Y 用户做 Z，预期 W；若 W 不动 / 反向则回滚」）；archive 前在 §1 回填一句 Review 结论（成立 / 部分成立 / 被证伪，能反哺 baseline 决策或 product-lines 假设）。只对高价值 delta，非每轮；不加表、不加骨架字段，防退化成形式填表。对齐 pm-methodology §三 PR-FAQ 自检。
- 新鲜度：
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 版本 / 状态 / 拟制人 · 日期 / 火效 / 重要性 · 紧迫性 / 迭代档位 / 端侧范围 / 提测 · 走查 · 上线 / 产品 · 交互 / 设计 · 设计稿 / 前端 · 后端 / 测试。三条约束：
- 「状态」「火效」两格固定在第 3 列 key、第 4 列 value（值落行尾单元格），
sync_hx_status.py 按此回写，勿调列位
- 日期不写进协作表，「提测 / 走查 / 上线」格写「见排期章」——日期的单一权威位是 §8 排期表（同一字段只写一次）
- 文档机制说明（baseline 指针 / delta 性质）不进头部，落 §9（推送时整章剥离）
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 块- bundle 按端拆文件（触发条件：各端有独立研发团队 + 开发明确要求）：一个版本号下产多个文件
prd-{线}-{版本}-{端}.md（如 -web.md / -app.md），每个文件是完整独立的 delta（含自己的 §1–§9），静态章按本端内容裁剪（无关的业务对象 / 状态机 / 规则整章删），原合并文件加废弃注释指向拆分后的文件。同版本的索引表只在原文件或约定的一端保留，拆分后各文件 §2.0 只列本端需求。
--tier（§2 组织）与四支柱填充（§3/§4/§5）正交，是两根独立的轴：
- §3/§4/§5 不需要二级开关——全新能力 delta 填实即与 baseline 对应章（§3.2 业务对象 / §3.3 状态机 / §4 全局规则）同构、反向合并直接搬章；只动既有场景的 delta 本轮无该支柱变更直接删空章（符「迭代只写真有改动」铁律）。
--tier 只管 §2 怎么排版（索引 + 分组 vs 平铺叙事），不决定四支柱有没有内容。两者各管各的，别混。
反向合并映射唯一落在 §9 表：骨架正文不吐「本轮无 X 则删本章 / 上线后反向合并进 baseline §X」这类章首导语（plumbing 进不了交付物）。哪章可删、合并到 baseline 哪章，看 §9 反向合并指引表（推 Confluence 时 §9 自动剥离，见 Step 4）。
API 速查
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()
from sections_md import build_full_skeleton, build_scene_file, SceneInfo
md = build_full_skeleton(info={"project_name": "xxx", "version": "1", "scenes": [...]})
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)
python3 scripts/md_to_confluence.py <prd.md> --merge-tracking --update-id <pageId>
python3 .claude/skills/prd/scripts/export_tracking_xlsx.py <prd.md> [-o out.xlsx]
自检清单（PM 交付前过一遍）
- 结构合规：
bash check_prd_md.sh <prd.md> exit 0（§X.Y 锚点 + 裸场景编号死链查只对 split 开，单文件 = baseline + single delta 天然豁免；profile 仅控 baseline 其他行为）
- 截图齐全：
./assets/ 下所有引用文件存在
- 模板字段名锁定：
grep -E "^- \*\*(触发|读|写|事件|API)" <md> 无命中（UI 场景统一走区块表）
- 裸编号清查：正文（非 heading / 非表格）grep
[ABCDEFM]-[0-9] 仅出现在「编号 + 白话名」组合或链接里（单文件 = baseline + single delta 豁免，仅 split 拦）
- 占位符清掉：grep
{{ 待填 无命中（终态）
- CJK 标点：
python3 scripts/check_cjk_punct.py <md> --strict exit 0
- 跨章引用合规：
见 X.Y 白话名 而非裸 见 X.Y / 见 A-1
- 全文讲人话：契约层（§3.2/3.3）无 snake_case 研发字段（用中文业务名），唯埋点章事件 / 属性英文名例外
- 结构化优先（禁分号滥用 · WARN）：单行 ≥ 2 个分号（
； / ;）= 子句堆一坨，拆成 bullet 或 1. 2. 3. 编号；表格行豁免（cell 内 ； 是 Confluence 切 bullet 的约定分隔符）
- 禁长句 run-on（拆句优先 · WARN）：句段（
。！？； 之间）≥ 100 字 = 一口气读不完，拆句或转列表；表格行豁免。与分号校验互补（分号管「；」串，长句管「，」串）
- 禁 bullet 串句（一个 bullet 一个原子断言 · WARN）：bullet 行内句号没落行尾、后面还跟实质内容 = 并列项焊一行（
打点口径 = X。B 点 = Y。展示位置 = Z → 各自成 bullet）。一项一行、句号只落行尾。表格行 / 决策记录章 / 冒号引子 bullet 豁免。与分号 / 长句互补，细则 references/prd-chapter-rules.md §三
- 叶子完整性：实时 / 快照字段标清生命周期与刷新触发点，阈值标端点（含不含），状态机穷举（含自环 / 离线再上线），展示窗口与数据保留期对齐。交付 / 推 Confluence 前跑「交付前冷读」Step（
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 例外）
References 索引
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 §三 / §三点八
注意事项
可选章节（按需 copy）
gen_prd_skeleton.py 默认生成 12 章骨架。以下两节按需追加在 §1.5 后、§2 前：
- §1.6 竞品调研：项目首次涉足某场景 / 内审要求竞品参照 / 决策依据需向 leader 说明时加。简单迭代不加
- §1.7 多方案对比：本期有 2+ 候选方案 / 技术路径有分歧 / 需说明为何选 A 不选 B 时加。单方案需求不加
模板见 references/prd-optional-sections.md，骨架不默认生成，PM 觉得需要时从模板 copy 进 PRD md。
方案型项目（不走标准 pipeline）
- 涉及独立 mid-office + 业务系统 + 风控系统跨系统对接
- 含资金路径 / 跨账户结算
- 涉及法务 / 合规批复路径
- 仅后端架构无 UI 流（如打分引擎 / 数据 pipeline）
不强制 12 章。PM 自定章节（建议对标共建 PRD 模板），文档仍 md，仍走 md_to_confluence.py 推 wiki。
文档分工建议：方案概览 / 系统拓扑 / 各系统职责 / 接口 schema / 资金对账 / 风险与回滚 / 灰度计划。
