admin/workbuddy_skills
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

product-planning：删掉④段「原型说明文档」（用户令「第4部分完全没法用，都删除」）⇒ 四段改三段

Browse Source 
- 删 references/stage-proto-doc/ 整目录（SKILL.md ＋ references/doc-area-spec.md ＋ references/guided-tour.md）。
  原做法＝往原型 HTML 注入说明区注解层（场景 / 从左到右流程图 / 功能作用·输入边界·异常情况 三段说明 / 演示引导），实测不好用。
- 总入口 SKILL.md：description 与「三段结构」表、交接口表（去掉 ③→④）、产物落哪（去掉④行）、
  进入方式（去掉「只做原型说明文档」「已有原型，要补说明」两行）、只读清单、执行规则、反面清单同步改写；
  并在段名命名原则处留一条删除留痕（含用户原话与「新写法待定」）。
- ③段 stage-delivery：撤掉「与④段的界」一条，改掉「说明区归④段」的两处约束（3d 完即交付原型本身）；历史条目加注。
- ①段/②段：段名对称链与越界条目改成三段。
- 闸门 check_naming.py：STAGES 去掉 stage-proto-doc（圈号数组改 ①②③、交界边去掉 ③→④），
  DEPRECATED 收进④段名与 4a/4b/4c 三个子步名。
- 未动：references/_留痕/ 下两份历史存档（含④段的旧口径，属正当留痕）；SKILL.md 与 check_naming.py
  里 2026-10-02/10-06 两次事故记录（历史事实）。
- 验收：`check_naming.py --ws E:/ProgramData/AIProject/contentm_agent` ＝ 通过 2045 / 失败 0 / 提示 31
  （新增 4 条提示全部落在 _留痕/ 里，正当）。
- 备份：tmp/_backup-stage-proto-doc-20261014/（原目录三件 ＋ 改前 SKILL.md）。
This commit is contained in:
admin committed 2026-10-14 23:33:54 +08:00
1 parent 2f656098de
commit daf4e5675a
8 files changed
+43 -305
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

product-planning/SKILL.md
+17 -22
View File
@@ -1,6 +1,6 @@
---
name: product-planning
description: 产品规划总入口（唯一入口），四段式调度：① 产品需求 ② 产品功能 ③ 界面交互 ④ 原型说明文档。四段以 references/stage-* 承载，本文件是总调度与约束。可整段跑也可只调一段。当用户要做产品规划、从零做新产品、只做某一阶段、或不知道从哪开始时调用。
description: 产品规划总入口（唯一入口），三段式调度：① 产品需求 ② 产品功能 ③ 界面交互。三段以 references/stage-* 承载，本文件是总调度与约束。可整段跑也可只调一段。当用户要做产品规划、从零做新产品、只做某一阶段、或不知道从哪开始时调用。
---
# 产品规划总入口
@@ -13,28 +13,27 @@ description: 产品规划总入口（唯一入口），四段式调度：① 产
本文件管调度与约束。各段怎么做，写在 `references/stage-*` 各自的文件里。
## 四段结构（可整段跑，也可只调一段）
## 三段结构（可整段跑，也可只调一段）
| 段 | 回答的问题 | 子步 | 调用 | 产出物 |
|---|---|---|---|---|
| **① 产品需求** | 要做的东西凭什么成立：什么问题、为谁、为什么值得做 | 1a 需求文档（grill 压测）/ 1b 竞品分析 / 1c 用户画像 / 1d 产品策略 / 1e 使用场景 | `stage-discovery` | `docs/pm/<项目>/research/*`。其中 1b 交两种体例：`research/1b-竞品分析.md`（汇总对比）＋ `research/1b-独立分析/<竞品名>.md`（独立分析） |
| **② 产品功能** | 要做哪些功能、什么不做、长成什么骨架 | 2a 产品功能 / 2b 界面布局 | `stage-requirements` | `docs/pm/<项目>/prd/2a-产品功能.md` 与 `prd/2b-界面布局.md`（两份） |
| **③ 界面交互** | 长什么样、怎么操作 | 3a 视觉规范 / 3b 原型 / 3c GPT参考版 / 3d 审查打磨 | `stage-delivery` | `docs/pm/<项目>/DESIGN.md`、`designs/<项目>/*.html`、`designs/<项目>/3c-GPT参考版.md` |
| **④ 原型说明文档** | 每个状态有哪些场景、每步做什么、边界在哪、坏了怎样 | 4a 场景盘点 / 4b 说明区 / 4c 演示引导 | `stage-proto-doc` | 同一份原型 HTML 里的说明区与演示引导 |
四段只通过落盘文件耦合。段间交接口如下，这是唯一的契约，越界即失效：
三段只通过落盘文件耦合。段间交接口如下，这是唯一的契约，越界即失效：
| 交接 | 由谁给 | 给什么 | 给到哪为止 |
|---|---|---|---|
| ① → ② | ① | 问题定义、需求澄清决策表（含 grill 压测的 B 节：做成什么样 / 哪些情况不成立 / 状态怎么流转）、取证结论（1b 汇总对比体 ＋ 1b 独立分析体、1c 用户画像）、产品定位、《使用场景》＝用户故事（②段功能的直接推导依据） | 功能清单归②段产出，1a 写到需求与形态为止 |
| ② → ③ | ② | 功能清单（每条带优先级 ＋ 状态流转）、界面布局（有哪几页 / 每页几个板块 / 板块怎么排 / 跨页关系）、每页主操作、信息承载分档（主屏常驻 / 可点入） | 视觉归③段。骨架必须给全，骨架不给全，③段就一版一个样 |
| ③ → ④ | ③ | 已跑通的单文件原型 HTML | 说明区与演示引导归④段 |
> 口径：②段钉骨架，③段做皮肉。两侧逐行对照与用户原话只在②段 `references/stage-requirements/SKILL.md` 的 §②—③ 交接口 定义一次 —— 本入口不复述。要点两条：②段要给全「归②段」列；③段不许增删移动板块，缺板块回②段改。
> ②→③ 最容易搞坏。旧病灶：②段说「必须能读到」，③段读成「必须常驻主屏」，五类信息就全铺一屏成了信息墙。分档表把「读到」明确成「一次点击内可达」，防的就是这句歧义。骨架是灰块（有哪些块、什么顺序），③段给的是视觉与交互实现（排版、点哪有什么反馈、空态、响应式）。两件事各管一维，③段不会退化成照抄。
> 四段各占一个词，互不共用（2026-10-02 定）：产品 / 功能 / 界面 / 说明。改段名前先对照这张表；两个段名里出现同一个词，边界一定在漂。旧名「调研与方案 / 需求与结构」都含「需求」，③段旧名里的「交付」是三段共有的属性，都属名实不符，已改。
> 三段各占一个词，互不共用（2026-10-02 定）：产品 / 功能 / 界面。改段名前先对照这张表；两个段名里出现同一个词，边界一定在漂。旧名「调研与方案 / 需求与结构」都含「需求」，③段旧名里的「交付」是三段共有的属性，都属名实不符，已改。
> 🔴 **④段「原型说明文档」已于 2026-10-14 删除**（用户令：「第4部分完全没法用，都删除」）。原做法是往原型 HTML 里注入说明区注解层（场景 / 流程图 / 三段说明 / 演示引导），实测不好用 ⇒ 整段连方法论一并撤掉。新写法待定（正另行征询）。原件已按改包纪律留备份，备份位置与删段理由见当日 memory 记录。
> ①叫「产品需求」不叫「需求调研」：该段产出 `research/1a-需求文档.md`、`1b-竞品分析.md`、`1c-用户画像.md`，也产出 `1d-产品策略.md`、`1e-使用场景.md`，「调研」二字盖不住后半截。
> ⭐ 1b 是①段唯一交两种体例的子步：独立分析体 `research/1b-独立分析/<竞品名>.md`（竞品池每一个一份），汇总对比体 `research/1b-竞品分析.md`（恒一份）。职责边界与定案原话见 `references/stage-discovery/references/competitor-analysis.md` §0.4。
@@ -52,7 +51,7 @@ description: 产品规划总入口（唯一入口），四段式调度：① 产
## 项目与路径约定（单一真源）
> 四段全部遵守本节。各段 `SKILL.md` 与 `references/` 里出现 `docs/pm/...` 时，`<项目>` 一律指本节定义的 slug。
> 三段全部遵守本节。各段 `SKILL.md` 与 `references/` 里出现 `docs/pm/...` 时，`<项目>` 一律指本节定义的 slug。
### `<项目>` 是什么
@@ -76,7 +75,6 @@ description: 产品规划总入口（唯一入口），四段式调度：① 产
| ① 产品需求 | `docs/pm/<项目>/research/` |
| ② | `docs/pm/<项目>/prd/` |
| ③ | `docs/pm/<项目>/DESIGN.md`、`designs/<项目>/*.html`、`designs/<项目>/3c-GPT参考版.md` |
| ④ | 写进原型 HTML 自身（`designs/<项目>/*.html`），不额外落 md |
### 文档的两态：当前版与过期版
@@ -144,18 +142,16 @@ DESIGN.md 说明：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec
| 你说什么 | 模式 | 从哪开始 |
|---|---|---|
| 「规划 XX」「从零做 XX」 | 全流程（自动处理） | `stage-discovery` → `stage-requirements` → `stage-delivery` → `stage-proto-doc`，一路跑完，段间不停下来问（含①段末） |
| 「先确认方案」「跑完方案停下等我」「规划 XX，先给方案」 | 方案确认 | 同一套四段，唯一差别是①段末停下等你确认方案，确认后才进②③④ |
| 「只做产品需求」「只做产品功能」「只做界面交互」「只做原型说明文档」 | 单段 | 只调对应那一个 stage skill，不展开其他段 |
| 「规划 XX」「从零做 XX」 | 全流程（自动处理） | `stage-discovery` → `stage-requirements` → `stage-delivery`，一路跑完，段间不停下来问（含①段末） |
| 「先确认方案」「跑完方案停下等我」「规划 XX，先给方案」 | 方案确认 | 同一套三段，唯一差别是①段末停下等你确认方案，确认后才进②③ |
| 「只做产品需求」「只做产品功能」「只做界面交互」 | 单段 | 只调对应那一个 stage skill，不展开其他段 |
| 已有②段，要出原型 | 单段 | 直接调 `stage-delivery`，从它的 3a 起 |
| 已有原型，要补说明 | 单段 | 直接调 `stage-proto-doc`，从它的 4a 起 |
| 只问某个单点 | 单段 | 不跑任何段，在对应 stage skill 内点名子步，或直接说要看哪份方法论 |
「只调一段」成立的原因：四段之间只通过落盘文件耦合，没有隐式状态。
「只调一段」成立的原因：三段之间只通过落盘文件耦合，没有隐式状态。
- ②只读 `docs/pm/<项目>/research/*`；缺失时标注 `【假设】`继续，不催促回补①
- ③只读 `docs/pm/<项目>/prd/*`；缺失时同样标 `【假设】`继续
- ④只读 `designs/<项目>/*.html`，另按需读 `docs/pm/<项目>/prd/*` 校准术语；缺失时标 `【假设】`继续
## 执行规则
@@ -164,7 +160,7 @@ DESIGN.md 说明：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec
| 模式 | 段之间 | 段之内 |
|---|---|---|
| 全流程（自动处理） | 一路跑完，段间不停下来问（含①段末）。每段结束按「标准收尾格式」输出一段报告，输出完即刻进下一段 | 子步之间不反问，做完直接进下一个子步 |
| 方案确认 | 与全流程完全相同，只有一处不同：①段末停下等你确认方案；确认后②③④一路跑完、段间不停 | 同上 |
| 方案确认 | 与全流程完全相同，只有一处不同：①段末停下等你确认方案；确认后②③一路跑完、段间不停 | 同上 |
| 单段 | 不涉及 | 不越界，不催促回补前段 |
这两条是全流程模式下的两个独立分支，不要混：全流程（自动处理）没有①段末的强制停；「停下等确认方案」只在「方案确认」模式下发生。二选一由用户定（界面里点【生成原型和文档】时选「自动处理」或「先确认方案」，或在会话里直接说明）；用户没明说时按自动处理走，不要在自动处理模式下自作主张停下来问。
@@ -228,17 +224,16 @@ DESIGN.md 说明：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec
- 在 `grill-me` 提问模式下仍套用「提问上限 3 个」，把提问做成走过场
- 只跑一次 `grill-me`：①没定义需求就去取证，或②拿①段的需求定义代替功能压测直接写②段
- 把自动补全当默认动作：用户没说话就替用户拍板，还没标 `【假设】`、没进待复核清单
- 把④的说明区写进产品功能范围，或让③顺手把说明文档一起写了（该调 `stage-proto-doc` 就调）
- 手写 Mermaid 代替 diagram-design，手写 token 表代替 DESIGN.md
- 绕过四段自己手搓，或重写它们的内容（该调 `stage-*` 就调）
- 绕过三段自己手搓，或重写它们的内容（该调 `stage-*` 就调）
- 把供给件的内部路径按本 skill 目录去拼，或改它们的正文 —— 供给件指③段自带的 `oil-ui-pro`，以及 §供给 各档落在 `assets/` 下的件（它们是随③段携带的供给件，改动只写 `stage-delivery` 自己的 `SKILL.md` / `references/`；默认档与可选档平行，不缝成一条流水线，也不把 `oil-ui-pro` 的评分循环当成本段 Gate 的替代）
- 猜 `<项目>`：定不出来还硬写，把产物落到别的项目目录下
- 把 `DESIGN.md` 写到仓库根：多项目会互相覆盖
- 段间停下来问「要不要继续」：全流程（自动处理）模式下直接进下一段，只在段末输出报告
- 把两种模式混用：在自动处理模式下自作主张停下问方案，或在「方案确认」模式下确认前就开跑②③④
- 把两种模式混用：在自动处理模式下自作主张停下问方案，或在「方案确认」模式下确认前就开跑②③
- 在「方案确认」模式下把①段的方案当成已确认就往下跑：该模式下①段末必须停下等用户确认（含「不做什么」）
- 下游擅自裁剪上游已拍板项：②③④发现要砍①段或决策表里已拍板的东西时，不许自行裁掉或改口径，必须列成「与已定决策的差异」交用户显式确认
- 把模式当成段：模式是「要不要在①段末停」的开关，不是第五个段，别为它单独造段或造产物
- 下游擅自裁剪上游已拍板项：②③发现要砍①段或决策表里已拍板的东西时，不许自行裁掉或改口径，必须列成「与已定决策的差异」交用户显式确认
- 把模式当成段：模式是「要不要在①段末停」的开关，不是第四个段，别为它单独造段或造产物
- 跑了却不说：没声明当前段 / 子步与依据文件，或偏离了被调 skill 的主流程却不声明、不记偏离单（应为：开工先声明、每个子步再声明、偏离当场声明）
## 改名 / 改供给后的自检
@@ -247,7 +242,7 @@ DESIGN.md 说明：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec
python scripts/check_naming.py --ws <工作区>
```
它查四段段名与子步名在「总入口 ↔ 各段 `SKILL.md` ↔ 各段 `references/`」之间有没有漂，包括 H1 与子步表是否一致、总入口子步列有没有漏项、runbook 必读表有没有引用已移除的资产、两份副本是否一致。纯静态比对，不需要渲染，不需要外部依赖。
它查三段段名与子步名在「总入口 ↔ 各段 `SKILL.md` ↔ 各段 `references/`」之间有没有漂，包括 H1 与子步表是否一致、总入口子步列有没有漏项、runbook 必读表有没有引用已移除的资产、两份副本是否一致。纯静态比对，不需要渲染，不需要外部依赖。
为什么必须有它：实测当天漏过两次，当时没有任何门禁会报错。
@@ -255,7 +250,7 @@ python scripts/check_naming.py --ws <工作区>
第二次（2026-10-06）：②段收窄为「只细化功能」（7 份产出变 1 份）后，各段 `SKILL.md` 都改了，但总入口的三处仍写着旧结构——四段表的②段子步列仍是「2a 功能定义与压测 / 2b 功能流转 / 2c 功能图示」，四段表的①段子步列「1c 产品定位与商业设计」未随段内改名（段内已改称「产品定位与场景」），正文仍写「①与②各跑一次 `grill-me`」并指向两份同名文档，实际全场只有①段一份。闸门当场报 6 个 FAIL，根因是「改了承载段、忘了总入口」。
由此立一条硬纪律，与「换供给不能只改承载段」同型：凡改子步结构 / 段内产出清单 / 段间交接口，必须连带改总入口 `product-planning/SKILL.md` 的「四段结构」表与「交接口」表，不改就是半改状态。
由此立一条硬纪律，与「换供给不能只改承载段」同型：凡改子步结构 / 段内产出清单 / 段间交接口，必须连带改总入口 `product-planning/SKILL.md` 的「三段结构」表与「交接口」表，不改就是半改状态。
改了段名 / 子步名 / 判据供给源之后必须跑一次，并把结果记进当日 memory。改完不校验，下次读契约的人拿到的是错的配方。
product-planning/references/stage-delivery/SKILL.md
+4 -5
View File
@@ -8,9 +8,9 @@ description: 产品规划第③段，界面交互。设计工程供给默认来
回答两个问题：长什么样、怎么操作。产出 `docs/pm/<项目>/DESIGN.md` 与 `designs/<项目>/*.html`。
> 段名为什么是「界面交互」（2026-10-02 定）：
> 删「交付」：①②③都产出落盘文件，「交付」是三段共有的属性，不是③的专属；④段也在交付（原型的说明区），留着会让人以为③管完就结束了。
> 删「交付」：①②③都产出落盘文件，「交付」是三段共有的属性，不是③的专属，留着会让人以为③管完就结束了。
> 补「交互」：本段原先只讲「长什么样」，可 3b 原型硬要求每个按钮、每个跳转都真能走（`:236`），3c 的参考版对照也要逐项看空态 / 加载 / 错误 / 反馈（`:148`、`:150`）。交互判据一直在做，却没有名字，补上才与本段实际职责相符。
> 与④段的界：③造物（界面与交互本身），④描述物（说明区与演示引导）。
> ⚠️ 2026-10-14 变更：原先还有一条「与④段的界：③造物、④描述物」，因④段整段删除，该条一并撤掉。③段仍是最后一段，3d 完就交付原型本身。
> `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来就停下问用户，不许猜。`DESIGN.md` 放项目目录，不放仓库根，避免多项目互相覆盖。
@@ -328,7 +328,7 @@ Gate-1 方向门（硬闸，不可跳）——按本表逐项自检（字段定
- 3b 交付前必须用 `browser-harness` 跑实测；脚本查不出死按钮，未跑实测不得进 3c，不得报完成。
- 3c GPT 参考版必做：原型初稿 + 实测过后立刻做，不许用「我觉得没问题」代替。参考版原文（三句话说明 ＋ 完整 HTML）必须落盘，不得伪造或转述失真；未取得参考版时要在 `3c-GPT参考版.md` 与收尾里明示，未取得不等于已通过。贴进去的需求与风格文本先脱敏。
- Gate-2 / Gate-3 不许口头通过：阻断项要么修完，要么留痕；「未取得审查」不等于已通过。
- 原型的说明区与演示引导不是本段的事：各状态下的「场景 / 从左到右流程图 / 步骤说明 / 演示引导」由第④段 `stage-proto-doc` 负责。3d 完就交付原型本身。
- 3d 完就交付原型本身；本段是最后一段，原型之外不再有说明区那一层（原④段已于 2026-10-14 删除）。
- `DESIGN.md` 落 `docs/pm/<项目>/`，不放仓库根。
- 段内子步之间不反问，做完直接进下一个子步。停线规则（哪几种情况停、怎么判）见 `product-planning` 的「执行规则」—— ⛔ 本段不复述，免得两处漂。
- `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来就停下问用户，不许猜。
@@ -370,7 +370,6 @@ Gate-1 方向门（硬闸，不可跳）——按本表逐项自检（字段定
- 把「未取得外部审查」当已通过
- 工具型页面做**逐区块**的入场编排；用 `linear`/`ease` 做过渡曲线；用 `@keyframes` 做交互过渡
- 越界回头改②段的功能取舍（那是第②段）——⚠️ 但「骨架缺板块」是例外：必须回②段改，⛔ 不许就地在原型里加
- 顺手把原型说明文档 / 演示引导写了（那是第④段 `stage-proto-doc`）
## 待补（2026-10-02 登记 · 2026-10-06 更新）
@@ -379,6 +378,6 @@ Gate-1 方向门（硬闸，不可跳）——按本表逐项自检（字段定
⛔ 修复后的纪律：判据来源必须单一可查。某条判据若在 runbook 与 craft 各有一份且口径不同，以本项目追加条为准，并在 §3.4 显式标注「本项目追加」。
- ~~工具型页面的版式库~~：已于 2026-10-02 补齐。新建 `references/layouts-tooling.md`，四类形态各给一份可判定骨架：行式列表 / 表格式清单 / 详情面板 / 主从侧区。每类带形态判定句（判不出形态就去改 D0 `结构骨架`）＋ 可机械核对的判定要点（如「一屏可见行数 ≥6」「数字列右对齐」「表头必须写判据来源」「未跑必须能作为取值存在」）。已接进三处：3b 正文（形态判定先行）｜runbook §1 必读表 D2 行（工具型另读）｜runbook「⛔ 四样 craft 接不住」表（第四行）。
⭐ 红线：⛔ 不许拿营销页骨架顶替工具型，那是「没做形态判定」的默认行为，等于退回 18 轮前的病根。
- ~~①②段的同型改造~~：已于 2026-10-02 完成。四段已改名为「①产品需求 / ②产品功能 / ③界面交互 / ④原型说明文档」，并各自重划了子步职责（见 `product-planning` 的四段表与交接口表）。
- ~~①②段的同型改造~~：已于 2026-10-02 完成。四段已改名为「①产品需求 / ②产品功能 / ③界面交互 / ④原型说明文档」，并各自重划了子步职责（见 `product-planning` 的四段表与交接口表）。⚠️ 其中④段已于 2026-10-14 整段删除（用户令），现为三段。
- ⛔ 骨架归属已于 2026-10-06 反转：本节原口径是「页面结构归本段，唯一落点是 D0」；用户定案改为「②段钉骨架，③段做皮肉」（原话：页面关系和布局必须在第二步确认清楚，不然第三步没有方向 一会一个样子）。⇒ `必要内容` / `结构骨架` 两个字段口径已调整，从「本段独立裁决」改为「在②段给定骨架之内决定视觉与交互实现」。详见本文件开头「⭐⭐ 页面骨架不归本段了」块。
⚠️ 待核：`references/execution-runbook.md` 的 D0 段仍写着旧口径（「独立推导几个页面」），需同步改。另，`gate-<段号>-<段名>.md` 本项目从未建立，属存量缺口。
product-planning/references/stage-discovery/SKILL.md
+2 -2
View File
@@ -7,7 +7,7 @@ description: 产品规划第①段，产品需求。五个子步依次产出五
回答"做什么、为谁、为什么值得做"。产出只有五份，全部落 `docs/pm/<项目>/research/`。
> 段名定为「产品需求」（2026-10-02 定）：本段 1b 做调研，1d/1e 定产品策略与场景，"调研"盖不住后半截，还会让②段的"需求"二字失去归属。四段各占一个词：产品 / 功能 / 界面 / 说明。
> 段名定为「产品需求」（2026-10-02 定）：本段 1b 做调研，1d/1e 定产品策略与场景，"调研"盖不住后半截，还会让②段的"需求"二字失去归属。三段各占一个词：产品 / 功能 / 界面。
## ⭐⭐ 产出白名单（2026-10-06 用户定案 · 硬规矩）
@@ -224,6 +224,6 @@ description: 产品规划第①段，产品需求。五个子步依次产出五
- 凭空给 Importance / Satisfaction 打分：没有任何数据源支撑的数字，不许出现在交付物里
- 五份没过「说人话」内容准则就落盘 —— 口径与门槛见 `product-planning` 的「执行规则」内容准则条
- 把推演出来的用户画像当用研结论进 1c——三个 JTBD 若都追不到一句用户原话，那是自证不是用研
- 越界去写②段、出原型或写原型说明文档（那是第②③④段）
- 越界去写②段或出原型（那是第②③段）
📎 本段删过的产出与方法论（原产出长什么样、为什么删、原反面清单里被撤掉的那一条）见 `_留痕/①段-已删除产出与方法论.md`，正文不展开；防复活由 `scripts/check_naming.py` 的 `DEAD_OUTPUTS` 机器判。
product-planning/references/stage-proto-doc/SKILL.md
-84
View File
@@ -1,84 +0,0 @@
---
name: stage-proto-doc
description: 产品规划第④段，原型说明文档。在已交付的原型 HTML 上补说明区：每个界面状态下方按「状态 → 使用场景 → 从左到右流程图 → 步骤说明（功能作用 / 输入边界 / 异常情况）」铺开，并给每条流程配逐步骤的演示引导。当用户要给原型加功能说明区、写原型说明文档、做操作指引演示，或说"只做原型说明文档"时调用。
---
# ④ 原型说明文档
回答"每个状态有哪些场景、每个场景怎么走、每一步到底做什么、边界在哪、坏了会怎样"。
产出长在原型 HTML 自身（`designs/<项目>/*.html`），不额外落 md，免得两处维护、说法对不上。
顺序 4a → 4b → 4c。说明区先齐，再挂演示引导。
> 表格「读」列是该方法论文档，相对路径的基准是本 skill 目录。执行子步前先读它。
## 输入
| 来自 | 读什么 | 用来定什么 |
|---|---|---|
| ③ | `designs/<项目>/*.html` | 要挂说明区的原型本体；状态数与状态名以它为准 |
| ② | `docs/pm/<项目>/prd/2a-产品功能.md` · `docs/pm/<项目>/prd/2b-界面布局.md` | 术语口径、状态流转、异常路径、页面骨架 |
| ① | `docs/pm/<项目>/research/1d-产品策略.md` | "不做什么"的边界，说明区不得写出范围外的能力 |
上游缺失时标 `【假设】`继续，不强制回补。
## 4a 场景盘点
| 子步 | 读 | 产出 |
|---|---|---|
| 状态 × 场景盘点（必做，最先） | `references/doc-area-spec.md` | 每个界面状态下的使用场景清单 |
每个状态都要盘（正常态 / 加载中 / 空态 / 加载失败），不许只写正常路径。
场景粒度是"人要完成的一件事"，不是"一个按钮"。典型一条：拿到一批数据 → 判一条 → 遇到没跑完的怎么办 → 批量的影响范围 → 筛不到东西时。
## 4b 说明区
读 `references/doc-area-spec.md`，按它给的层级与交互铺：
1. 说明区挂在原型各状态的下方，随演示条切换的状态一起变
2. 每个场景一条：可点开，点开后是该场景的从左到右流程图（序号节点 + 箭头）
3. 点流程里的某一步，在流程图下方出该步说明，固定三段：功能作用 / 输入边界 / 异常情况
4. 同级单开：一次只展开一个场景、一次只选中一个步骤；再点已选中的步骤即收起
三段缺一不可，且必须是对着原型实测过的事实，不是套话：
| 段 | 写什么 | 判定标准（可核对） |
|---|---|---|
| 功能作用 | 这个组件做什么、给谁看、落笔后产生什么 | 换一个组件，这句话就不成立 |
| 输入边界 | 取值域 / 上限 / 前置条件 / 可选与必填 | 能说出"什么不被接受"或"最多几条" |
| 异常情况 | 失败 / 空 / 禁用 / 重复提交 / 文案红线 | 至少覆盖一种"坏了怎么办"，且给出恢复路径 |
## 4c 演示引导
读 `references/guided-tour.md`，给每条流程挂"演示"按钮：
1. 每个步骤补三样数据：`target`（要高亮的选择器）、`setup`（这一步的前置条件）、`hint`（操作指引，与功能说明 `desc` 分开写）
2. 演示按 `上一步 / 下一步 / 完成` 逐步骤推进，气泡给"第 N / M 步"
3. 纯概念步骤不给 target，不参与演示，按钮置灰并写明原因
## 硬约束
- 说明区是非产品功能，它是原型的自解释注解层。交付时要明说，别让人误以为产品里真有一个说明页。
- 只有原型上有的事实才许写。每一段说明都要能在原型里点到对应元素；写不出 `target` 的步骤，要么承认是概念步骤，要么回去改原型。
- 不得把自动结论表述为人工认可（红线，本项目实测抓过）：机器判定只能说"进入队列 / 待人工逐条查看"，不许写成"通过 / 已认可"。
- 文案口径跟②段走。同一个概念在说明区与②段里必须同名，冲突时改说明区。
- 4c 交付前必须浏览器实测，逐步骤真点一遍，走完全流程再退出。未跑实测不得报完成。
- 段内子步之间不反问，做完直接进下一个子步；**停线规则**见 `product-planning` 的「执行规则」，⛔ 本段不复述。
- `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来就停下问用户，不许猜。
## 完成标准
- 原型的每个状态都有场景，四态齐备（缺哪个要写明为什么）
- 每个场景有从左到右流程图，每个步骤都有 `功能作用 / 输入边界 / 异常情况` 三段且非空
- 演示引导能从第一步走到完成，退出后界面回到演示前（含筛选、抽屉）
- 有实测回报（走过的步骤数、失败项、控制台报错原文）
## 反面清单
- 只写正常路径，跳过加载 / 空 / 错误三个状态的说明
- 三段说明写成语义重复的三句话，或整段是"该功能可以提升效率"这类空话
- 把演示引导做成遮罩弹窗，挡住它要教人点的那个东西
- 演示中途改动了用户的筛选 / 抽屉，退出后不还原
- 概念步骤硬凑一个 target，或演示到一半被判"元素不可见"直接结束
- 只写说明区就报完成，没跑过逐步骤实测（自查看不出死按钮）
product-planning/references/stage-proto-doc/references/doc-area-spec.md
-78
View File
@@ -1,78 +0,0 @@
# 原型说明区规范
> 本文件是 `stage-proto-doc` 的方法论文档，由模型按需加载，没有斜杠命令。
## 定位
说明区是原型自带的注解层，不是产品功能。它不回答"长什么样"，回答的是：
> 站在这个界面上，我这一步在干什么、我能输入什么、什么情况下它不给好脸色。
所以它必须贴在原型各状态的下方，随状态切换一起变。抽出来写一份独立文档，读者就得自己脑补对应关系。
## 层级
```
状态（正常态 / 加载中 / 空态 / 加载失败）
└── 使用场景（人要完成的一件事，可点开）
├── 场景引言（一句话：什么前提下、要达成什么）
├── 从左到右的流程图（序号节点 + 箭头，横向可滚动）
└── 步骤说明（点某一步 → 在流程图下方出三段）
├── 功能作用
├── 输入边界
└── 异常情况
```
四层各管一段：状态说"界面此刻处于什么处境"，场景说"人在这个处境下想干成什么"，流程说"这件事分几步走"，步骤说明说"这一步的职责与边界"。少任何一层，读者都会拿别层的信息去补，然后补错。
## 场景怎么写
- 粒度是"人要完成的一件事"，不是一个按钮。"提交驳回"不算场景，"驳回一条片段并完成失败模式归类"才算。
- 一个状态下的场景数控制在 2–4 个。1 个说明不了分支，5 个以上就该拆状态。
- 顺序按发生频率排，不按界面从上到下排。
- 引言一句话写清前提。例："预审排队、执行中或失败时人工仍可决策，但必须清楚自己在无依据的情况下决策。"
## 从左到右流程图
| 规则 | 说明 |
|---|---|
| 形态 | 横向 `ol`，每项 = 序号圆点 + 步骤名，项间一个 `→` 箭头 |
| 溢出 | 横向滚动，不换行——换行会读成两条并行流程 |
| 交互 | 点步骤 → 流程图下方出说明；再点收起；同级只选中一个 |
| 键盘 | 步骤是 `button`；`aria-current` 标当前项；说明区 `role="region"` 带 `aria-controls` |
| 箭头 | `aria-hidden`，它只是视觉连接符，不进朗读 |
步数控制在 2–6 步：超过 6 步说明这个场景该拆，1 步说明它还不算流程。
## 步骤说明：三段
三段是固定骨架，不改名、不合并、不省段。
| 段 | 回答的问题 | 合格判据 | 不合格示例 |
|---|---|---|---|
| 功能作用 | 这一步做什么、给谁看、落笔后产生什么 | 换一个组件这句话就不成立 | "展示相关信息，提升审核效率" |
| 输入边界 | 取值域 / 上限 / 前置条件 / 必填与选填 | 说得出"什么不被接受"或"最多几条" | "支持筛选" |
| 异常情况 | 失败 / 空 / 禁用 / 重复提交 / 恢复路径 / 文案红线 | 至少一种"坏了怎么办"，且给出出路 | "暂不支持" |
写输入边界，常见切入点：数量上限、字数或时长范围、哪些状态才可用、必填项有哪些、一次作用于一条还是全部。
写异常情况，常见切入点：加载中能不能点、失败了怎么重试、重复提交怎么挡、空的时候显示什么、禁用要不要给原因、文案不能写成什么。
### 文案红线
- 不得把自动结论表述为人工认可。机器判定只能说"进入队列 / 待人工逐条查看"，不写成"通过 / 已认可 / 已确认"。
- 不用无法区分成因的笼统文案。"暂无数据"要拆成"批次为空"与"筛选无结果"两条出路。
- 不承诺原型里点不出来的能力。说明区每条都要能在原型上指到对应元素。
- 异常态必须给恢复路径。只写"失败了"不算说明，要写清楚下一步按哪里。
## 状态标签与联动
说明区顶部常驻一行"当前状态：xxx"，与演示条的状态同源。读者就不会拿正常态的说明去套加载态的行为。
## 自查（逐条打勾）
- [ ] 四个状态都有场景，缺的写明原因
- [ ] 每个状态 2–4 个场景，每个场景 2–6 步
- [ ] 每步三段齐全，且各自能通过上面的合格判据
- [ ] 全文没有"通过 / 已认可"这类把机器结论说成人审的词
- [ ] 每个禁用态都给了原因，每个异常态都给了恢复路径
- [ ] 说明区文案与②段术语逐词一致
product-planning/references/stage-proto-doc/references/guided-tour.md
-93
View File
@@ -1,93 +0,0 @@
# 演示引导（操作指引）
> 本文件是 `stage-proto-doc` 的方法论文档，由模型按需加载，没有斜杠命令。
## 它是什么
说明区把流程写清楚了，读者仍要自己在界面上找——"这条筛选在左栏还是顶栏？"
演示引导在真界面上按步骤带一遍：点流程的「演示」，高亮框住这一步该动的元素，气泡给操作指引，`上一步 / 下一步` 推进，`完成` 收尾。
它同样是原型的注解层，不是产品功能。交付时要明说，不能让人以为产品里真有一个新手引导。
## 数据契约
每个步骤在原有字段外必须补三样，缺一样就演示不了：
| 字段 | 作用 | 注意 |
|---|---|---|
| `target` | 要高亮的选择器 | 必须是当前状态下真实存在且可见的元素；纯概念步骤不给 `target` |
| `setup` | 这一步的前置条件 | 例：切到某条片段、填入某关键词、打开某抽屉。浮层类 setup 必须在设 `target` 之前执行，否则量不到 |
| `hint` | 操作指引：手该往哪放 | 与 `desc` 分开写。`desc` 回答"这是什么"，`hint` 回答"你要点哪"；两处写一样等于没写 |
演示可用的步骤数 = 有 `target` 的步骤数。全场景没有可演示步骤时，按钮置灰并写明原因，不是点了没反应。
## 单步的执行顺序（照抄这个顺序）
1. 收掉上一次留下的浮层（抽屉 / 弹窗 / 放大层），把临时筛选复位
2. 应用本步 `setup`（切片段 → 重渲染 → 填筛选 → 开抽屉）
3. 把说明区同步选中到这一步，并展开它所在场景
4. 记下 `target`，滚动到它可见处
5. 画高亮环与气泡，起重绘定时器
6. 播报"第 N 步 + 操作指引"
顺序错了就会出现"抽屉还没露出来就去量它"这类问题。
## 实测踩过的坑
### 1. 一次性测量一定过期 → 必须幂等重绘
量一次目标元素的位置就画环，过一会儿环会错位。实测数据：同一个元素在首帧后仍在变，宽度 `303.33 → 318.67`、顶部 `0.15 → -11.85`（页面滚动量恒定，是滚动条出现/消失带来的回流）。
做法：定时器（约 120ms）反复调用重绘函数，函数幂等——每次重新量、重新画；用几何 key（`left/top/width/height` 取整拼串）去重，没变就直接返回，避免无意义的重排。
别用 `scroll` / `resize` 监听代替定时器：滚动过程中环会滞后，元素自身回流也不触发这两个事件。
### 2. 浮层的可见性过渡会误杀演示
抽屉这类浮层的 `visibility` 会参与 `transition`，`data-open="true"` 之后约 200ms 内 `getComputedStyle().visibility` 仍是 `hidden`，判定函数返回"不可见"。这时直接结束演示，用户会看到"演示刚开始就自己关了"。
做法：给约 2 秒的容错窗口——不可见时先重试，超时才判定失败并给出原因。定时器天然负责重试。
### 3. 高亮环不要加 transition
环的几何每 120ms 重画一次，再加过渡会互相打架：出现拖影，几何断言永远对不上。要让环动起来，靠重绘频率，不靠 CSS 过渡。
### 4. 挖空遮罩用大 spread 的 box-shadow
一个 `position: fixed` 的环 + `box-shadow: 0 0 0 9999px rgba(0,0,0,.45)` 就是"四周压暗、中间挖空"，实测可用（用像素采样验证过：#F7F6F3 的底色被压到约 `(144,143,141)`）。
不要为此改成 `clip-path: polygon(...)`——单个 `polygon()` 是一条自相交多边形，不是多个子路径，想挖洞得用 `path()`。能用一行阴影解决就别引这条坑。
### 5. 退出要成对处理：收浮层 + 还原现场
演示会临时改筛选关键词、开抽屉。退出时只隐藏浮层，这些临时态会留给用户。做法：启动时快照当前筛选与关键词，退出时反向还原，再统一重渲染。
顺序有讲究：先关浮层，后清 `tourOn` 标记。关闭浮层会触发焦点归还逻辑，标记还在时它会被守卫拦住，不会把焦点从用户手上抢走。
### 6. 键盘与边界
| 场景 | 行为 |
|---|---|
| `ESC` | 退出演示（演示进行中优先于"关闭顶层浮层"） |
| 演示进行中按全局快捷键（`j/k/a/r` 等） | 一律屏蔽，否则按 `j` 会切走当前片段，演示当场跑偏 |
| 演示中切换界面状态 | 自动结束演示并播报原因（说明区内容已随状态换掉，会讲错） |
| 焦点 | 演示中不抢焦点；浮层用 `aria-modal="false"`，因为它是注解层不是模态框 |
| 进度文案 | 气泡常驻"第 N / M 步 + 场景名"，末步按钮文案改「完成」 |
### 7. 视觉断言要用像素采样，不要看缩略图
看截图判断颜色 / 遮罩 / 选中态会误判——缩略图渲染会改变颜色与对比，看出来的"遮罩没生效""高亮与说明不一致"经常是假象。
做法：颜色 / 遮罩 / 选中态这类断言，用 `PIL` 取区域均值或点采样来判，别靠肉眼。
## 交付前实测清单
- [ ] 每个有 `target` 的步骤都能从「演示」走到「完成」，无中途自动结束
- [ ] 每一步的高亮环都框住目标元素（框住 = 环矩形与目标矩形在各边差相等）
- [ ] 抽屉类步骤：环确实画在抽屉上，且退出后抽屉被收起
- [ ] 退出后筛选 / 关键词回到演示前的值
- [ ] 演示中按全局快捷键不改变界面
- [ ] 切换界面状态时演示自动结束并播报
- [ ] 纯概念步骤不参与演示，按钮置灰且有原因
- [ ] 全程无控制台报错（异常事件数 = 0）
product-planning/references/stage-requirements/SKILL.md
+2 -2
View File
@@ -8,7 +8,7 @@ description: 产品规划第②段，产品功能。只做一件事：把①段
回答「要做哪些产品功能、哪些明确不做、页面骨架怎么排」。产出两份：
`docs/pm/<项目>/prd/2a-产品功能.md`（功能清单）＋ `docs/pm/<项目>/prd/2b-界面布局.md`（页面骨架）。
> 段名与①「产品需求」构成 `产品需求 → 产品功能 → 界面交互 → 原型说明` 的对称链，四段各占一个词（产品 / 功能 / 界面 / 说明），无一词共用（2026-10-02 用户定）。旧名「需求与结构」「界面与交付」已废。
> 段名与①「产品需求」构成 `产品需求 → 产品功能 → 界面交互` 的对称链，三段各占一个词（产品 / 功能 / 界面），无一词共用（2026-10-02 用户定）。旧名「需求与结构」「界面与交付」已废。
>
> 与①段的分界：①回答「要解决什么问题、用户怎么用它」，②回答「要做哪些功能、长成什么骨架」。判据看文档主体 —— 主体是功能条目的有无与优先级、页面与板块骨架，归②；主体是问题、用户、取证与取舍理由，归①。
>
@@ -154,7 +154,7 @@ description: 产品规划第②段，产品功能。只做一件事：把①段
- ⛔ 把某条信息标为「主屏常驻」却答不上「缺了主操作就做不成事」：按判据应归「可点入」
- 状态流转只画正常路径，不管失败与并发；或状态挂不到任何功能条目上（凭空中间态）
- ⛔ 在本段写视觉（清单见 §②—③ 交接口）—— 那是③段
- 越界去出原型或写说明文档（那是第③④段）
- 越界去出原型（那是第③段）
- 把 `【假设】` 原样带进②段当既定事实；或假设已被实现却从不回填状态
- 只写「暂缓」而不给复核人 / 复核时机 / 结论落点 —— 等于让这条永远挂着
- ⛔ 两份没过「说人话」内容准则就落盘 —— 口径与门槛见 `product-planning` 的「执行规则」内容准则条
product-planning/scripts/check_naming.py
+18 -19
View File
@@ -1,8 +1,8 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""四段流水线**命名一致性**自检（纯静态文本比对，不需要渲染、不需要外部依赖）。
"""三段流水线**命名一致性**自检（纯静态文本比对，不需要渲染、不需要外部依赖）。
只查一件事：**四段的段名 / 子步名，在总入口、各段 SKILL.md、各段 references 之间有没有漂。**
只查一件事：**三段的段名 / 子步名，在总入口、各段 SKILL.md、各段 references 之间有没有漂。**
⛔ 本脚本**不查视觉、几何、配色** —— 那些判据归③段 §供给·工艺数值判据，本脚本一概不碰。
为什么需要它（不是"为了严谨"，是实测过的两次真实事故）：
@@ -48,15 +48,12 @@ STAGES = [
"h1": "# ③ 界面交互",
"subs": ["3a 视觉规范", "3b 原型", "3c GPT参考版", "3d 审查打磨"],
},
{
"slug": "stage-proto-doc",
"cn": "原型说明文档",
"h1": "# ④ 原型说明文档",
# 4b/4c 允许只在一处出现完整（总入口与段内都写全），但**两处都必须能读到**
"subs": ["4a 场景盘点", "4b 说明区", "4c 演示引导"],
},
]
# 2026-10-14 用户令：④段「原型说明文档」整段删除（原做法＝往原型 HTML 注入说明区注解层，
# 实测不好用）⇒ `references/stage-proto-doc/` 连方法论一并撤掉，本表同步去掉该项。
# 该段的段名与子步名转入下面的 DEPRECATED（提示级），用来查正文里的残留引用。
# 已废止的旧名。出现在「废止理由块」里是正当的（那是留痕），
# 所以这里只做**提示级**检查（不计入 FAIL），人工确认上下文即可。
DEPRECATED = [
@@ -71,6 +68,8 @@ DEPRECATED = [
"00-问题定义.md", "01-需求澄清.md",
"10-参考实装拆解.md", "11-竞品分析.md", "12-用户画像.md",
"strategy/30-产品策略.md", "strategy/31-使用场景.md",
# 2026-10-14 ④段整段删除：段名与三个子步名一并废止
"④ 原型说明文档", "4a 场景盘点", "4b 说明区", "4c 演示引导",
]
# ⛔ 2026-10-06 用户定案：①段**产出白名单**——本段只许这五份，第 6 份须用户明确要求。
@@ -201,10 +200,10 @@ def check_root(root, label):
add("PASS", f"[{label}] 技能根存在", root)
# 1) 每段：frontmatter 闭合 + H1 与权威表一致 + 每个子步都有 H2
# ⚠️ 2026-10-05 整合后：四段收进 references/<slug>/，不再是技能根下的平级目录。
# ⚠️ 2026-10-05 整合后：三段收进 references/<slug>/，不再是技能根下的平级目录。
# 本函数按「技能包 = 一个目录，SKILL.md 在最外层」的形态定位：
# <root>/SKILL.md ← 总入口（曾为 <root>/product-planning/SKILL.md）
# <root>/references/<slug>/SKILL.md ← 四段（曾为 <root>/<slug>/SKILL.md）
# <root>/references/<slug>/SKILL.md ← 三段（曾为 <root>/<slug>/SKILL.md）
# ⛔ 不许改回平级探测：那会让整合形态静默退回「一目录套多技能」而门禁照样全绿。
for st in STAGES:
p = os.path.join(root, "references", st["slug"], "SKILL.md")
@@ -242,26 +241,26 @@ def check_root(root, label):
for st in STAGES:
num = STAGES.index(st) + 1
circled = "①②③④"[num - 1]
circled = "①②③"[num - 1]
# 段名必须以「圈号 + 空格 + 段名」成对出现，避免只匹配到散落正文
ok = f"**{circled} {st['cn']}**" in text
add("PASS" if ok else "FAIL",
f"[{label}] {rel} 四段表含 `{circled} {st['cn']}`", "")
f"[{label}] {rel} 三段结构表含 `{circled} {st['cn']}`", "")
# 子步：总入口表里每个子步都要能被逐个读到（防"4a 说明区/ 演示引导"这类漏列）
# 子步：总入口表里每个子步都要能被逐个读到
for st in STAGES:
for sub in st["subs"]:
if sub.split()[0] in ("3d", "4b", "4c"):
# 3d/4b/4c 在总入口可能与相邻子步合并书写，只要求"子步号 + 关键词"能被搜到
if sub.split()[0] in ("3d",):
# 3d 在总入口可能与相邻子步合并书写，只要求"子步号 + 关键词"能被搜到
kw = sub.split(" ", 1)[1] if " " in sub else sub
ok = (sub in text) or (kw in text)
else:
ok = sub in text
add("PASS" if ok else "FAIL",
f"[{label}] {rel} 四段表子步列含 `{sub}`", "")
f"[{label}] {rel} 三段结构表子步列含 `{sub}`", "")
# 交接口表：三条边必须都在
for edge in ("① → ②", "② → ③", "③ → ④"):
# 交接口表：两条边必须都在
for edge in ("① → ②", "② → ③"):
add("PASS" if edge in text else "FAIL",
f"[{label}] {rel} 交接口表含 `{edge}`", "")