From 2ed7766007693ca634991416b10c8a8302023f38 Mon Sep 17 00:00:00 2001 From: maogeigei Date: Wed, 7 Oct 2026 22:00:13 +0800 Subject: [PATCH] =?UTF-8?q?=E8=AF=B4=E4=BA=BA=E8=AF=9D=E8=90=BD=E5=9C=B0?= =?UTF-8?q?=EF=BC=9A=E5=8A=A0=E6=AF=8F=E8=BD=AE=E6=B3=A8=E5=85=A5=20?= =?UTF-8?q?=EF=BC=8B=20=E8=8B=B1=E6=96=87=E7=A1=AC=E6=A0=B8=E7=89=88?= =?UTF-8?q?=E6=95=B4=E5=8C=85=E7=BA=B3=E5=85=A5=20=EF=BC=8B=20=E7=AC=AC?= =?UTF-8?q?=E2=91=A0=E6=AE=B5=E8=A1=A5=E5=86=99=E4=BD=9C=E5=8F=A3=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 一、用户令（逐字） 「humanizer（英文那份） 也要纳入」「重点就是做到说人话就行了」「但是 content_marketing_agent 的会话生成的文档并没有说人话，还是我手动要求的」 二、根因（两处，都不是"没整合"） · **语气那一档只有指针、没有注入** ⇒ 实测没被读到（`SKILL.md` 必读表标题原写「三篇」而表里有 4 行， 第 4 项＝作业规矩整包，被顶在"必读"之外；已订正为「四类」）。 · **写文档的执行会话那条链上一句写作口径都没有** —— 产品规划技能里「反 AI 味」只出现在**第③段界面** （且指的是界面不是文字），**第①段出文档那节零口径** ⇒ 产物自然是 AI 味。 三、改法 1. **每轮注入**（照排版那条现成机制，⛔ 不改 `main()`）： · `04-去AI味与说话方式.md` 顶部加 `` 紧凑块（≈450 字符：核心原则/四种高频 AI 味/交付前三问）； · `reply-style-guard.py` 里**原地重定义** `_core`（`_core_reply = _core` 后用新 `_core` 包住它并追加语气块） ⇒ 注入正文自动多一段，排版那条**不受影响**。 2. **产出侧补口径**：`product-planning` 第①段（stage-discovery）在 1b 表后新增「写作口径」块 —— 落笔前读 `humanizer-zh` 或本包 04，**定稿前过「交付前快速清单」**，并列出六种禁用 AI 味；**适用本段全部五份产出**。 3. **英文硬核版整包纳入**：原独立技能 `humanizer` **逐字**搬入本包 `references/humanizer-en/`（6 文件、 md5 逐个一致）：55 个模式 ＋ 5 种语气档 ＋ 0–100 AI 痕迹打分 ＋ `--file` 就地改； 在 `04 §9` 关系表与 `SKILL.md` 对应物段登记（冲突以本包会话场景版为先）。 四、验收 · 新增 `selftest.py::t_voice_core`（4 项）；全量 **PASS 106 / FAIL 0**；manifest 70 → **76** 份、语法失败 0。 · 端到端喂真钩子：注入正文已含说人话块、排版块仍在。 · ⛔ 改的是钩子与技能目录（宿主直读）⇒ **不需要分发/重启**。 --- product-planning/SKILL.md | 254 +++++----- .../_留痕/SKILL-总入口-20261007改说人话前.md | 260 ++++++++++ .../references/stage-discovery/SKILL.md | 75 ++- .../references/competitor-analysis.md | 203 ++++++-- .../references/stage-requirements/SKILL.md | 3 + .../references/create-prd.md | 2 +- session-mechanism/SKILL.md | 2 +- .../references/humanizer-en/LICENSE | 21 + .../references/humanizer-en/README.md | 108 +++++ .../references/humanizer-en/SKILL.md | 443 ++++++++++++++++++ .../references/always-on-templates.md | 70 +++ .../humanizer-en/references/patterns.md | 302 ++++++++++++ .../humanizer-en/references/patterns.zh.md | 130 +++++ session-mechanism/references/manifest.md | 18 +- .../作业规矩/04-去AI味与说话方式.md | 12 + .../scripts/hooks/reply-style-guard.py | 40 ++ session-mechanism/scripts/selftest.py | 23 + 17 files changed, 1767 insertions(+), 199 deletions(-) create mode 100644 product-planning/references/_留痕/SKILL-总入口-20261007改说人话前.md create mode 100644 session-mechanism/references/humanizer-en/LICENSE create mode 100644 session-mechanism/references/humanizer-en/README.md create mode 100644 session-mechanism/references/humanizer-en/SKILL.md create mode 100644 session-mechanism/references/humanizer-en/references/always-on-templates.md create mode 100644 session-mechanism/references/humanizer-en/references/patterns.md create mode 100644 session-mechanism/references/humanizer-en/references/patterns.zh.md diff --git a/product-planning/SKILL.md b/product-planning/SKILL.md index 1a2b9c8..9605055 100644 --- a/product-planning/SKILL.md +++ b/product-planning/SKILL.md @@ -3,78 +3,74 @@ name: product-planning description: 产品规划总入口（唯一入口），四段式调度：① 产品需求 ② 产品功能 ③ 界面交互 ④ 原型说明文档。四段以 references/stage-* 承载，本文件是总调度与约束。可整段跑也可只调一段。当用户要做产品规划、从零做新产品、只做某一阶段、或不知道从哪开始时调用。 --- -# 产品规划总入口（Product Planning） +# 产品规划总入口 -> **Trae 用法**：本 skill 由模型按需自动加载，没有斜杠命令。若对话中尚未明确对象，先按下面「项目与路径约定」定出 `<项目>`，**定不出来就停下问用户，不要自行假设**。 +> 本 skill 由模型按需自动加载，没有斜杠命令。对话里还没定出对象时，先按「项目与路径约定」定出 `<项目>`；定不出来就停下问用户，不要自行假设。 ## 用途 -用户只有一句模糊想法（例："我要做一个 AI 短剧分镜画布"）时，本 skill 负责判断阶段、只做该段最小必要工作、产出可交付物、并推进到下一段。 +用户丢来一句模糊想法（例如「我要做一个 AI 短剧分镜画布」）时，本 skill 判断该走哪一段，只做那一段的最小必要工作，产出可交付物，再推进到下一段。 -**本 skill 只做调度与约束，不重复任何被调 skill 的内容。下游 skill 都是外部成熟工具，不要自己重写一遍。** +本文件管调度与约束。各段怎么做，写在 `references/stage-*` 各自的文件里。 ## 四段结构（可整段跑，也可只调一段） | 段 | 回答的问题 | 子步 | 调用 | 产出物 | |---|---|---|---|---| -| **① 产品需求** | 要做的东西**凭什么成立**：什么问题、为谁、为什么值得做 | 1a 需求文档（grill 压测）/ 1b 竞品分析 / 1c 用户画像 / 1d 产品策略 / 1e 使用场景 | `stage-discovery` | `docs/pm/<项目>/research/*` | -| **② 产品功能** | **要做哪些功能、什么不做、长成什么骨架** | 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` | +| **① 产品需求** | 要做的东西凭什么成立：什么问题、为谁、为什么值得做 | 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 节：做成什么样 / 哪些情况不成立 / 状态怎么流转**）、取证结论、产品定位、**《使用场景》= 用户故事（②段功能的直接推导依据）** | **功能清单**（那是②段的产出，1a 写了就越界） | -| ② → ③ | ② | **功能清单（每条带优先级 + 状态流转）+ 界面布局（有哪几页 / 每页几个板块 / 板块怎么排 / 跨页关系）+ 每页主操作 + 信息承载分档（主屏常驻 / 可点入）** | **视觉**（配色 / 字体 / 间距 / 组件样式 / 动效 —— 那是③段的活）；⛔ **也不许只给功能不给骨架**（骨架不给全，③段就一版一个样） | -| ③ → ④ | ③ | 已跑通的单文件原型 HTML | 说明区与演示引导（④段的活，③段顺手写就是越界） | +| ① → ② | ① | 问题定义、需求澄清决策表（含 grill 压测的 B 节：做成什么样 / 哪些情况不成立 / 状态怎么流转）、取证结论（1b 汇总对比体 ＋ 1b 独立分析体、1c 用户画像）、产品定位、《使用场景》＝用户故事（②段功能的直接推导依据） | 功能清单归②段产出，1a 写到需求与形态为止 | +| ② → ③ | ② | 功能清单（每条带优先级 ＋ 状态流转）、界面布局（有哪几页 / 每页几个板块 / 板块怎么排 / 跨页关系）、每页主操作、信息承载分档（主屏常驻 / 可点入） | 视觉归③段。骨架必须给全，骨架不给全，③段就一版一个样 | +| ③ → ④ | ③ | 已跑通的单文件原型 HTML | 说明区与演示引导归④段 | -> **口径：②段钉骨架，③段做皮肉。** 用户原话：「3 是负责设计和交互，**页面关系和布局必须在第二步确认清楚，不然第三步没有方向 一会一个样子**」。 -> ⇒ **②段必须给**：有哪几页、每页几个板块、板块怎么排、跨页关系。**③段⛔ 不许增删移动板块**，缺板块回②段改 ②段。 -> ⛔ **仍归③段**：配色 / 字体 / 间距 / 组件样式 / 动效，以及每个板块的视觉与交互实现。 +> 口径：②段钉骨架，③段做皮肉。用户原话：「3 是负责设计和交互，页面关系和布局必须在第二步确认清楚，不然第三步没有方向 一会一个样子」。 +> 所以②段要给全：有哪几页、每页几个板块、板块怎么排、跨页关系。③段不许增删移动板块，缺板块回②段改。 +> 配色 / 字体 / 间距 / 组件样式 / 动效，以及每个板块的视觉与交互实现，都归③段。 -> ⚠️ **②→③ 仍是本流水线最容易被搞坏的一环**，但病灶换了位置：旧病灶是「②段 说"必须能**读到**"，③段读成"必须**常驻主屏**"」→ 五类信息全铺一屏 → 信息墙。 -> **分档表就是为这句歧义而生的**：它把"读到"明确成"一次点击内可达"这一档。**该纪律照旧有效**，只是现在**骨架不由③段独立推导，而是②段给定、③段在骨架内兑现分档**。 +> ②→③ 是这条流水线最容易被搞坏的一环。旧病灶是②段说「必须能读到」，③段读成「必须常驻主屏」，于是五类信息全铺一屏，成了信息墙。分档表就是为这句歧义生的：它把「读到」明确成「一次点击内可达」。 +> 骨架给定后，③段不会退化成照抄。骨架是灰块（有哪些块、什么顺序），③段给的是视觉与交互实现（怎么排版好看、点哪有什么反馈、空态怎么呈现、响应式怎么变）。两件事各管一维。 -> 💡 **③段为什么在骨架给定后仍然不会"退化成照抄"**：它做的仍是**另一类工作** —— 骨架是灰块（有哪些块、什么顺序），③段要给的是**视觉与交互实现**（怎么排版好看、点哪有什么反馈、空态怎么呈现、响应式怎么变）。**两者不是同一样东西的粗细两版，是两个维度。** +> 四段各占一个词，互不共用（2026-10-02 定）：产品 / 功能 / 界面 / 说明。改段名前先对照这张表；两个段名里出现同一个词，边界一定在漂。历史上「调研与方案 / 需求与结构」里都有「需求」，③段名里的「交付」是三段共有的属性，都属名实不符，已改。 +> ①叫「产品需求」不叫「需求调研」：该段产出 `research/1a-需求文档.md`、`1b-竞品分析.md`、`1c-用户画像.md`，也产出 `1d-产品策略.md`、`1e-使用场景.md`，「调研」二字盖不住后半截。 +> ⭐ 1b 是①段唯一交两种体例的子步（2026-10-07 用户定案「竞品分析 有独立分析也有汇总分析 都应该要用上」）：独立分析体 `research/1b-独立分析/<竞品名>.md`（竞品池每一个一份），汇总对比体 `research/1b-竞品分析.md`（恒一份）。职责边界见 `references/stage-discovery/references/competitor-analysis.md` §0.4。 -> **四段各占一个词，互不共用**（2026-10-02 定）：**产品 / 功能 / 界面 / 说明**。 -> 改段名前先对照这张表——**若两个段名里出现同一个词，边界一定在漂**。历史上「调研与方案 / 需求与结构」两段名里都含"需求"、③段名里的"交付"是全三段共有的属性，都属名实不符，已改。 -> ①叫「产品需求」而不叫「需求调研」：该段产出 `research/1a-需求文档.md`、`1b-竞品分析.md`、`1c-用户画像.md` **也**产出 `1d-产品策略.md`、`1e-使用场景.md`，"调研"二字盖不住后半截。 +⭐⭐ `grill-me` 全场只有①段一份（2026-10-06 用户定案）：用户原话「grill 也应该拿到第一步了，第二部就是细化功能」。①段那份按 A / B 两节提问：A 节问「要做什么、为谁、边界在哪」，B 节问「做成什么样、哪些情况不成立、状态怎么流转」，B 节结论落进 `research/1a-需求文档.md`。 -⭐⭐ **`grill-me` 全场只有①段一份（2026-10-06 用户定案）**：用户原话「**grill 也应该拿到第一步了，第二部就是细化功能**」。 -①段那份**按 A / B 两节提问**：**A 节**「要做什么、为谁、边界在哪」（原①段火力点）｜**B 节**「做成什么样、哪些情况不成立、状态怎么流转」（原②段火力点）；B 节结论落进 `research/1a-需求文档.md`。 +⭐⭐ ②段产出两份（2026-10-06 收窄，2026-10-07 定为两份）：用户原话「不需要 就用使用场景，其余6分都不需要了」「2 产品功能 和 界面布局不就是两个文档嘛」。`prd/2a-产品功能.md`（功能清单：做哪些 / 不做哪些 / 每条带优先级 ＋ 状态流转）与 `prd/2b-界面布局.md`（页面关系 ＋ 页面内板块布局）。 -⭐⭐ **②段产出两份（2026-10-06 收窄 · 2026-10-07 定为两份）**：用户原话「**不需要 就用使用场景，其余6分都不需要了**」「**2 产品功能 和 界面布局不就是两个文档嘛**」。 -`prd/2a-产品功能.md`（功能清单：做哪些 / 不做哪些 / 每条带优先级 + 状态流转）＋ `prd/2b-界面布局.md`（页面关系 + 页面内板块布局）。 +（交接口反转前的口径、②段收窄前的产出清单与去向 → `references/_留痕/③段与总入口-旧口径.md`） -（历史：交接口反转前的口径、②段收窄前的产出清单与其去向 → `references/_留痕/③段与总入口-旧口径.md`） -⚠️ **本段功能的组织方式是按「使用场景」**（一条场景可跨多个页面），⛔ 不按页面组织。 +⚠️ ①段功能按「使用场景」组织（一条场景可跨多个页面），不按页面组织。 -段内的子步顺序、方法论文档、硬约束、完成标准，**都在各段自己的 `SKILL.md` 与 `references/` 里，本文件不重复**。 +段内的子步顺序、方法论文档、硬约束、完成标准，都在各段自己的 `SKILL.md` 与 `references/` 里。 -**①段 1a 需求文档**：全程最先做（且只做一次）——用 grill-me 与用户互动，产出一份 `docs/pm/<项目>/research/1a-需求文档.md`（开头写清做什么/为谁/不做什么，往下是决策表）。 +①段 1a 需求文档：全程最先做，且只做一次。用 grill-me 与用户互动，产出 `docs/pm/<项目>/research/1a-需求文档.md`（开头写清做什么 / 为谁 / 不做什么，往下是决策表）。 ## 项目与路径约定（单一真源） -> 四段全部遵守本节。**各段 `SKILL.md` 与 `references/` 里出现 `docs/pm/...` 时，`<项目>` 一律指本节定义的 slug，不另作解释。** +> 四段全部遵守本节。各段 `SKILL.md` 与 `references/` 里出现 `docs/pm/...` 时，`<项目>` 一律指本节定义的 slug。 ### `<项目>` 是什么 -**项目 slug**：小写字母 / 数字 / 连字符（例 `my-tool`、`video-canvas`）。 -它同时是 `docs/pm/<项目>/` 与 `designs/<项目>/` 的目录名——**两处必须同名，一个字都不能差**。 +项目 slug 用小写字母、数字、连字符（例 `my-tool`、`video-canvas`）。它同时是 `docs/pm/<项目>/` 与 `designs/<项目>/` 的目录名，两处必须同名，一个字都不能差。 -### slug 怎么定（按序取第一个成立的，不许猜） +### slug 怎么定（按序取第一个成立的） | 序 | 条件 | 取值 | |---|---|---| | 1 | 用户在当前会话里明确说了项目名 | 该名字 slug 化 | | 2 | `.registry/current-project` 存在且非空 | 其内容 | | 3 | `docs/pm/` 下恰有一个非 `_` 开头的目录 | 该目录名 | -| 4 | 以上都不成立 | **停下问用户**，不许自行假设 | +| 4 | 以上都不成立 | 停下问用户 | -**写任何文件之前先核对**：目标路径里的 `<项目>` 段与按上表得出的 slug 是否一致；不一致就停下说明，不要"先写了再说"。猜错会把产物写进别的项目，事后极难拆干净。 +写任何文件之前先核对：目标路径里的 `<项目>` 段与按上表得出的 slug 是否一致。不一致就停下说明，不要「先写了再说」——猜错会把产物写进别的项目，事后极难拆干净。 ### 产物落哪 @@ -87,100 +83,111 @@ description: 产品规划总入口（唯一入口），四段式调度：① 产 ### DESIGN.md 为什么在项目目录、不在仓库根 -`DESIGN.md` 是 ③ 段的**绑定视觉规范**，**一个项目一份**，③ 段按当前项目的 slug 去读它。仓库根只能放一份，多项目会互相覆盖，所以一律放 `docs/pm/<项目>/DESIGN.md`。 +`DESIGN.md` 是③段的绑定视觉规范，一个项目一份，③段按当前项目的 slug 去读它。仓库根只能放一份，多项目会互相覆盖，所以一律放 `docs/pm/<项目>/DESIGN.md`。 -**推论（硬规则）**：读 `DESIGN.md` 时，路径必须由本节定义的 `<项目>` slug 拼出，**不许用"当前工作目录碰巧有 DESIGN.md"这类推断**。仓库根**不放**任何项目的 `DESIGN.md`。 +推论（硬规则）：读 `DESIGN.md` 时，路径必须由本节定义的 `<项目>` slug 拼出，不许用「当前工作目录碰巧有 DESIGN.md」这类推断。仓库根不放任何项目的 `DESIGN.md`。 ## 工具选择规则（防止选错，最重要的一节） -> 下表是选型总则。这些工具**都已封装在对应段内**，本文件只负责让你不选错，不负责给出调用路径——具体路径见各段 `SKILL.md`。 +> 下表是选型总则。这些工具都已封装在对应段内，本文件只负责让你不选错；具体调用路径见各段 `SKILL.md`。 -| 要什么 | 用谁 | 不要用什么 | +| 要什么 | 用谁 | 别用 | |---|---|---| -| 页面设计全链（规范 → 原型 → 审查） | ③ 段 `stage-delivery` 自己的 D0→D5 流水线（判据与素材由两个页面设计技能供给） | 不要另找风格库、也不要自己手搓一套 token 与门禁 | -| 评审用的可点原型 / 生产级前端页面 | ③ 段 3b（按 D2 构建，单文件 HTML 交付；**先判页型**：营销页取 `open-design` 技能的 `design-templates/web-prototype/`，**工具型页面取 ③段 `references/layouts-tooling.md`**） | ⛔ **不要不判页型就套 `web-prototype` 种子** —— 那是营销落地页骨架，会把后台做成营销页 | -| 设计规范文件 | ③ 段 3a 生成 `DESIGN.md`（令牌表由 `open-design` 技能选定套的 `tokens.css` 产出 + 该项目②段的界面需求） | 不要凭空编一套 token | -| 架构图 / 流程图 / 时序图 | `diagram-design` | **不要手写 Mermaid** | -| 状态迁移的守卫/副作用/并发 | `state-machine` | diagram-design 不覆盖这些，别指望它 | -| 审美方向 / 风格定调 | `open-design` 技能里**选一套**（读候选套 `DESIGN.md` 第 1 章，按页面类型挑） | 不要用"米白+衬线+陶土色"这类默认审美，也不要凭感觉编 | -| 多方向比选 / 独立评审打分 | `oil-ui-pro` 技能（方向探索 `design-direction.md`＋对比页 `style-explorer.md`；评审协议 `visual-review.md`） | ⛔ 不要拿它的评分循环替代本段 Gate-1/2/3 | +| 页面设计全链（规范 → 原型 → 审查） | ③段 `stage-delivery` 自己的 D0→D5 流水线 | 另找风格库，或自己手搓一套 token 与门禁 | +| 评审用的可点原型 / 生产级前端页面 | ③段 3b（按 D2 构建，单文件 HTML 交付）。先判页型：营销页取 `open-design` 技能的 `design-templates/web-prototype/`，工具型页面取③段 `references/layouts-tooling.md` | 不判页型就套 `web-prototype` 种子——那是营销落地页骨架，会把后台做成营销页 | +| 设计规范文件 | ③段 3a 生成 `DESIGN.md`（令牌表由 `open-design` 技能选定套的 `tokens.css` 产出，加该项目②段的界面需求） | 凭空编一套 token | +| 架构图 / 流程图 / 时序图 | `diagram-design` | 手写 Mermaid | +| 状态迁移的守卫、副作用、并发 | `state-machine` | 指望 diagram-design 覆盖这些 | +| 审美方向 / 风格定调 | `open-design` 技能里选一套（读候选套 `DESIGN.md` 第 1 章，按页面类型挑） | 「米白＋衬线＋陶土色」这类默认审美，或凭感觉编 | +| 多方向比选 / 独立评审打分 | `oil-ui-pro` 技能（方向探索 `design-direction.md`，对比页 `style-explorer.md`，评审协议 `visual-review.md`） | 拿它的评分循环替代本段 Gate-1/2/3 | -**③ 段的页面设计供给来自两个独立技能（2026-10-05 定）**，都装在 `.workbuddy/skills/` 技能仓库、**都可脱离本段单独使用**： -- **`open-design`**（判据供给库）：`design-systems/`（153 套，**定调只从这里选，不凭感觉编**）｜`craft/`（13 份工艺判据：状态穷举 / 字阶 / 配色 / 动效 / 反 AI 味 / 无障碍）｜`design-templates/web-prototype/`（版式骨架种子，⚠️ **营销页向**）。 -- **`oil-ui-pro`**（界面设计方法论）：五步流程（探索方向 → 建结构 → 取实证 → 独立评审打分 → 验证交付）＋ 风格对比页与截图工具。⚠️ 它**自带联网版本检查与自动更新**，是用户明确要求全量搬入的**例外项**（既有纪律是"依赖外部服务一律不收"），记录在案、不扩散。 -- ⭐ **两者平行同层级、不缝成一条流水线**：多数页面走 `open-design` 主线；需要「先拉开方向让用户挑」或「独立评审打分」时取 `oil-ui-pro`。 +③段的页面设计供给来自两个独立技能（2026-10-05 定），都装在 `.workbuddy/skills/` 技能仓库，都可脱离本段单独使用： -⛔ **四样东西两个技能都没有对应，必须由 `stage-delivery` 自己扛**：**设计契约十二字段 / 结构骨架 / 交互清单 / 工具型版式库**。 -🔴 **页型分流（2026-10-05 新增）**：`web-prototype` 的种子与 8 骨架**全是营销落地页结构**（hero / features / stats / quote / CTA），自带 `.eyebrow`（眉标）与 `.lead`（副标题）。**工具型页面（后台 / 控制台 / 列表 / 详情）照它做会长出「标题上下各一行小字」的三段式** —— 这是本项目实测踩过的坑，且**结构判据全绿也拦不住**。⇒ ③段 D0 **必须先判页型**，工具型页面**零 `.eyebrow` / 零 `.lead` / 零 `.hero`**，版式走 ③段 `references/layouts-tooling.md`。 -⛔ **只读一处来源** —— 同一条判据若在 `stage-delivery` 与 `craft` 各有一份且口径不同，以本项目追加条为准，并在 runbook §3.4 显式标注「本项目追加」。 +- `open-design`（判据供给库）：`design-systems/`（153 套，定调只从这里选）、`craft/`（13 份工艺判据：状态穷举 / 字阶 / 配色 / 动效 / 反 AI 味 / 无障碍）、`design-templates/web-prototype/`（版式骨架种子，营销页向）。 +- `oil-ui-pro`（界面设计方法论）：五步流程（探索方向 → 建结构 → 取实证 → 独立评审打分 → 验证交付），加风格对比页与截图工具。它自带联网版本检查与自动更新，是用户明确要求全量搬入的例外项（既有纪律是「依赖外部服务一律不收」），已记录在案，不扩散。 -**DESIGN.md 说明**：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec` 四个子命令，目前是 alpha（v0.4.0）。在非 TTY 的管道里可能不回显输出，需在真实终端里确认结果。**本机实测该命令完全不可用，不要拿它当校验关卡**；改由 D3 收口与 D5 终检**按真实像素人工复测**对比度（判据见 `open-design` 技能的 `craft/color.md`）。⚠️ 原两把门禁脚本（静态文案检查 / 渲染机检）**已随旧主干从磁盘移除**，当前**没有机器复现** ⇒ 结论只能记「人工判定」，不得写成「脚本已通过」。 +两者平行同层级，不缝成一条流水线：多数页面走 `open-design` 主线；需要「先拉开方向让用户挑」或「独立评审打分」时，取 `oil-ui-pro`。 + +四样东西两个技能都没有对应，由 `stage-delivery` 自己扛：设计契约十二字段、结构骨架、交互清单、工具型版式库。 + +页型分流（2026-10-05 新增）：`web-prototype` 的种子与 8 个骨架全是营销落地页结构（hero / features / stats / quote / CTA），自带 `.eyebrow`（眉标）与 `.lead`（副标题）。工具型页面（后台 / 控制台 / 列表 / 详情）照它做会长出「标题上下各一行小字」的三段式——本项目实测踩过的坑，结构判据全绿也拦不住。所以③段 D0 必须先判页型，工具型页面零 `.eyebrow`、零 `.lead`、零 `.hero`，版式走③段 `references/layouts-tooling.md`。 + +只读一处来源：同一条判据若在 `stage-delivery` 与 `craft` 各有一份且口径不同，以本项目追加条为准，并在 runbook §3.4 显式标注「本项目追加」。 + +DESIGN.md 说明：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec` 四个子命令，目前是 alpha（v0.4.0）。非 TTY 的管道里可能不回显输出，需在真实终端里确认。本机实测该命令完全不可用，不要拿它当校验关卡；改由 D3 收口与 D5 终检按真实像素人工复测对比度（判据见 `open-design` 技能的 `craft/color.md`）。原两把门禁脚本（静态文案检查 / 渲染机检）已随旧主干从磁盘移除，当前没有机器复现，结论只能记「人工判定」，不得写成「脚本已通过」。 ## 可调用工具（自然语言触发） -> 两个「随段携带」的独立工具，装在 ③段 `references/stage-delivery/assets/` 下；按用户说法直接触发，产物落项目目录。它们**不是**新的段，只是叫得动的工具。 +> 两个随段携带的独立工具，装在③段 `references/stage-delivery/assets/` 下。按用户说法直接触发，产物落项目目录。它们不是新的段，只是叫得动的工具。 | 用户说 | 触发工具 | 做什么 | 产物 | |---|---|---|---| -| 「**分析 XXX 视频**」「把这个视频抽帧」「拆一下这条视频的画面」 | `stage-delivery/assets/video-capture/` | 取视频（本地文件 / 直链 URL）＋ 抽帧（双因素 ＋ 首尾 ＋ 补帧） | 关键帧 `frames/` ＋ `frame_times.json`（供 ①竞品分析 / ③视觉参考） | -| 「**获取 XXX 网站的设计风格**」「抓这个网站的风格/组件/配色」 | `stage-delivery/assets/design-capture/` | 抓网页设计系统（色彩 / 排版 / 组件）→ 生成样式模板 | 一套 `design-system-<名>/`（与 `design-system-tiaoyue` 同构，可直接被 ③段 D1 选用） | +| 「分析 XXX 视频」「把这个视频抽帧」「拆一下这条视频的画面」 | `stage-delivery/assets/video-capture/` | 取视频（本地文件 / 直链 URL）＋ 抽帧（双因素 ＋ 首尾 ＋ 补帧） | 关键帧 `frames/` ＋ `frame_times.json`（供①竞品分析、③视觉参考） | +| 「获取 XXX 网站的设计风格」「抓这个网站的风格/组件/配色」 | `stage-delivery/assets/design-capture/` | 抓网页设计系统（色彩 / 排版 / 组件），生成样式模板 | 一套 `design-system-<名>/`（与 `design-system-tiaoyue` 同构，可直接被③段 D1 选用） | -- 两者都**独立、可单跑**：`video-capture` 只依赖 `ffmpeg`；`design-capture` 只依赖本机 Chrome（CDP）＋ `vendor/` 里搬运的抽取脚本，**⛔ 不依赖 open-design daemon**。 -- 用法与边界见各自 `SKILL.md`；来源与署名见各自 `ATTRIBUTION.md`。 -- 触发时机：①②段拆竞品视频 → `video-capture`；③段要新建样式或拆参考站 → `design-capture`。 -- ⛔ 两工具都**只做合规最小集**（不抓平台页内视频、⛔ 不调付费接口）；抽取结果须先目视比对再采用。 +两者都独立可单跑：`video-capture` 只依赖 `ffmpeg`；`design-capture` 只依赖本机 Chrome（CDP）＋ `vendor/` 里搬运的抽取脚本，不需要 open-design daemon 在场。用法与边界见各自 `SKILL.md`，来源与署名见各自 `ATTRIBUTION.md`。 + +触发时机：①②段拆竞品视频用 `video-capture`；③段要新建样式或拆参考站用 `design-capture`。 + +两个工具都只做合规最小集：不抓平台页内视频，不调付费接口；抽取结果须先目视比对再采用。 ## 进入方式 | 你说什么 | 模式 | 从哪开始 | |---|---|---| -| "规划 XX" / "从零做 XX" | **全流程（自动处理）** | `stage-discovery` → `stage-requirements` → `stage-delivery` → `stage-proto-doc`，**一路跑完，段间不停下来问**（含 ① 段末） | -| "先确认方案" / "跑完方案停下等我" / "规划 XX，先给方案" | **方案确认** | 同全流程、同一套四段，**唯一差别是 ① 段末停下等你确认方案**，确认后才进 ②③④ | -| "只做产品需求" / "只做产品功能" / "只做界面交互" / "只做原型说明文档" | **单段** | **只调对应那一个 stage skill**，不展开其他段，也不催促回补前段 | -| 已有 ②段，要出原型 | 单段 | 直接调 `stage-delivery`，从它的 3a 起 | +| 「规划 XX」「从零做 XX」 | 全流程（自动处理） | `stage-discovery` → `stage-requirements` → `stage-delivery` → `stage-proto-doc`，一路跑完，段间不停下来问（含①段末） | +| 「先确认方案」「跑完方案停下等我」「规划 XX，先给方案」 | 方案确认 | 同一套四段，唯一差别是①段末停下等你确认方案，确认后才进②③④ | +| 「只做产品需求」「只做产品功能」「只做界面交互」「只做原型说明文档」 | 单段 | 只调对应那一个 stage skill，不展开其他段 | +| 已有②段，要出原型 | 单段 | 直接调 `stage-delivery`，从它的 3a 起 | | 已有原型，要补说明 | 单段 | 直接调 `stage-proto-doc`，从它的 4a 起 | | 只问某个单点 | 单段 | 不跑任何段，在对应 stage skill 内点名子步，或直接说要看哪份方法论 | -**为什么"只调一段"成立**：四段之间**只通过落盘文件耦合**，没有隐式状态。 +「只调一段」成立的原因：四段之间只通过落盘文件耦合，没有隐式状态。 -- ② 只读 `docs/pm/<项目>/research/*` 与 `docs/pm/<项目>/strategy/*`；缺失时标注 `【假设】` 继续，**不强制回补 ①** -- ③ 只读 `docs/pm/<项目>/prd/*` 与 `docs/pm/<项目>/ux/state-machine.md`；缺失时同样标 `【假设】` 继续 -- ④ 只读 `designs/<项目>/*.html`，另按需读 `docs/pm/<项目>/prd/*` 与 `docs/pm/<项目>/ux/state-machine.md` 校准术语；缺失时标 `【假设】` 继续 +- ②只读 `docs/pm/<项目>/research/*` 与 `docs/pm/<项目>/strategy/*`；缺失时标注 `【假设】`继续，不催促回补① +- ③只读 `docs/pm/<项目>/prd/*` 与 `docs/pm/<项目>/ux/state-machine.md`；缺失时同样标 `【假设】`继续 +- ④只读 `designs/<项目>/*.html`，另按需读 `docs/pm/<项目>/prd/*` 与 `docs/pm/<项目>/ux/state-machine.md` 校准术语；缺失时标 `【假设】`继续 ## 执行规则 -**只有三种模式**（对应上表），没有第四种： +只有三种模式，没有第四种： | 模式 | 段之间 | 段之内 | |---|---|---| -| **全流程（自动处理）** | **一路跑完，段间不停下来问**（含 ① 段末）。每段结束按「标准收尾格式」输出一段报告，**输出完即刻进下一段** | 子步之间不反问，做完直接进下一个子步 | -| **方案确认** | 与全流程**完全相同，只有一处不同**：**① 段末停下等你确认方案**；确认后 ②③④ 一路跑完、段间不停 | 同上 | -| **单段** | 不涉及 | 同上；不越界、不催促回补前段 | +| 全流程（自动处理） | 一路跑完，段间不停下来问（含①段末）。每段结束按「标准收尾格式」输出一段报告，输出完即刻进下一段 | 子步之间不反问，做完直接进下一个子步 | +| 方案确认 | 与全流程完全相同，只有一处不同：①段末停下等你确认方案；确认后②③④一路跑完、段间不停 | 同上 | +| 单段 | 不涉及 | 不越界，不催促回补前段 | -**这两条是全流程模式下的两个独立分支，不要混**：**全流程（自动处理）没有 ① 段末的强制停**；「停下等确认方案」**只在"方案确认"模式下发生**。二选一由用户定（界面里点【生成原型和文档】时选「自动处理」或「先确认方案」，或在会话里直接说明）；**用户没明说时按自动处理走**，不要在自动处理模式下自作主张停下来问。 +这两条是全流程模式下的两个独立分支，不要混：全流程（自动处理）没有①段末的强制停；「停下等确认方案」只在「方案确认」模式下发生。二选一由用户定（界面里点【生成原型和文档】时选「自动处理」或「先确认方案」，或在会话里直接说明）；用户没明说时按自动处理走，不要在自动处理模式下自作主张停下来问。 -**"停下"到底指什么**——不要读成"每一步都要反问用户"。只有这四种情况才停： +「停下」指什么，不要读成「每一步都要反问用户」。只有这四种情况才停： -1. **信息不足且查不到**，必须用户给（如「项目与路径约定」slug 第 4 条）——停下问 -2. **破坏性 / 不可逆动作**——二次确认 -3. **用户显式要求**某个子步做完停下 -4. **① 段末的方案确认（仅"方案确认"模式）**——把方案摆给用户：做什么 / 不做什么 / MVP 边界 / 未复核的 `【假设】`，明说"等你确认方案，确认前不进 ② 段" +1. 信息不足且查不到，必须用户给（如「项目与路径约定」slug 第 4 条）——停下问 +2. 破坏性 / 不可逆动作——二次确认 +3. 用户显式要求某个子步做完停下 +4. ①段末的方案确认（仅「方案确认」模式）——把方案摆给用户：做什么 / 不做什么 / MVP 边界 / 未复核的 `【假设】`，明说「等你确认方案，确认前不进②段」 -段末报告：**全流程（自动处理）模式下，所有段（含 ①）都只输出报告，不提问、不等回答**；**方案确认模式下 ① 段是唯一例外**，其余段同样只输出报告。 +段末报告：全流程（自动处理）模式下，所有段（含①）都只输出报告，不提问、不等回答；方案确认模式下①段是唯一例外，其余段同样只输出报告。 -**① 段末的确认是回环，不是一次问答**（仅"方案确认"模式）：用户看到方案后可以提问题要求改（可能多轮），每轮的"问题 + 怎么改的"都要留痕、不得覆盖上一轮；改完由用户显式说"确认方案"才算过闸门。**该模式下，没拿到用户确认的方案不得当成既定事实带进 ② 段**（这是本项目真实踩过的坑：② 段拿着未经确认的方案往下跑，把用户已拍板的需求裁掉了）。 +①段末的确认是回环，不是一次问答（仅「方案确认」模式）：用户看到方案后可以提问题要求改，可能多轮，每轮的「问题＋怎么改的」都要留痕、不得覆盖上一轮；改完由用户显式说「确认方案」才算过闸门。该模式下，没拿到用户确认的方案不得当成既定事实带进②段——这是实测踩过的坑：②段拿着未经确认的方案往下跑，把用户已拍板的需求裁掉了。 其余规则： -- **声明制（全段适用，不止 ③ 段）**：开工前、每进一个子段/子步、每处偏离，都要声明三件事——**当前在哪 / 依据哪个文件的哪一节 / 产出落哪**；偏离当场写明原因与影响，段末附**偏离单**。**不许静默偏离。** 这是本项目踩过的坑：③ 段 3b 交付了原型却没走当时声明的主流程、没读依据文件，也**没有当场说**，用户直到追问"基于哪个 skill"才知道。 -- **不做八股**：不介绍方法论来源，不列人名，不复述框架历史。直接给结论。 -- **只调一段时不越界**：用户说"只做第 N 段"，就跑该段，不展开其他段，也不用"你还没做调研"去催促。 -- **提问上限 3 个**：其余用合理假设，并在文档里标注 `【假设】`。**例外：进入 `grill-me` 提问模式时不受此限**（① 段的"需求澄清"与 ② 段的"需求压测"各是一次）——该模式的价值就是穷尽提问。此时须先声明"将连续多轮提问"，退出后恢复本约束。 -- **反问优先，允许自动补全**：`grill-me` 的默认动作是把问题抛给用户并附推荐答案。用户说"你定"、连续两轮不回应、或属事实类问题时，模型自行给答案并标 `【假设】`，换来"不卡住"；但每轮结束要汇出**待复核清单**，未经复核的 `【假设】` 不得在下游当事实用。 -- **MVP 边界优先**：任何阶段都先回答"第一版做什么 / 不做什么"。 -- **必须落盘**：产出写入文件，不要只在对话里输出。 -- **无来源就标注**：任何查不到来源的数据都标为"估算"并写明口径，⛔ 不编造数字当事实。 -- **禁止长文**：单份产出物默认一页纸（≤120 行）；超长必须拆分。 +- 声明制（全段适用，不止③段）：开工前、每进一个子段或子步、每处偏离，都要声明三件事——当前在哪、依据哪个文件的哪一节、产出落哪；偏离当场写明原因与影响，段末附偏离单。不许静默偏离。实测踩过的坑：③段 3b 交付了原型却没走当时声明的主流程、没读依据文件，也没当场说，用户追问「基于哪个 skill」才知道。 +- 不做八股：不介绍方法论来源，不列人名，不复述框架历史，直接给结论。 +- ⭐ 内容准则：一切落盘文字都要先过「说人话」这一关（2026-10-07 用户定案，同日扩大到规则文件）。用户原话：「当作第一步 和 第二步 生成文档时 必须遵循的内容准则」「不管是写规则 还是 写文档 都要严格按照说人话的技能去执行」。 + - 适用面两类都算，只改产出不改规则等于半改。一是产出文档：`research/1a-需求文档.md` 到 `1e-使用场景.md`（5 份）、`research/1b-独立分析/`（独立分析体）、`prd/2a-产品功能.md` 与 `prd/2b-界面布局.md`（2 份）。二是规则本身：本技能包内的一切落盘文字，`SKILL.md`、`references/**`、模板与清单。 + - 判据来源（单一可信源，本文件不复述模式清单）：`humanizer`（55 条模式、5 种口吻档 casual / professional / technical / warm / blunt），`humanizer-zh`（24 条模式、快速检查清单、50 分制评分）。两份技能都在 `E:/ProgramData/.workbuddy/skills/`，完整判据以源技能正文为准。 + - 门槛：按 `humanizer-zh` 五维评分（直接性 / 节奏 / 信任度 / 真实性 / 精炼度）≥45 / 50 才准落盘；低于 45 回炉重写。 + - 五条核心原则（源技能《核心规则速查》摘引）：删填充短语（开场白、强调性拐杖词）；打破公式结构（二元对比、戏剧性分段、修辞性设置）；变化节奏（长短交错，两项优于三项，段尾多样）；信任读者（直接陈述事实，跳过软化、辩解、手把手引导）；删金句（读起来像可引用的话，就重写它）。 + - 交付留证：产出文档在段末报告里写明「已过内容准则，评分 X/50」；改规则文件时，在当日 memory 里记下这一关过了。 +- 只调一段时不越界：用户说「只做第 N 段」，就跑该段，不展开其他段，也不用「你还没做调研」去催促。 +- 提问上限 3 个：其余用合理假设，并在文档里标注 `【假设】`。例外是 `grill-me` 提问模式，不受此限（①段的「需求澄清」与②段的「需求压测」各一次），该模式的价值就是穷尽提问；此时须先声明「将连续多轮提问」，退出后恢复本约束。 +- 反问优先，允许自动补全：`grill-me` 的默认动作是把问题抛给用户并附推荐答案。用户说「你定」、连续两轮不回应、或属事实类问题时，模型自行给答案并标 `【假设】`，换来「不卡住」；但每轮结束要汇出待复核清单，未经复核的 `【假设】` 不得在下游当事实用。 +- MVP 边界优先：任何阶段都先回答「第一版做什么、不做什么」。 +- 必须落盘：产出写入文件，不要只在对话里输出。 +- 无来源就标注：任何查不到来源的数据都标为「估算」并写明口径，不编造数字当事实。 +- 禁止长文：单份产出物默认一页纸（≤120 行），超长必须拆分。 ## 每段的标准收尾格式 @@ -201,53 +208,46 @@ description: 产品规划总入口（唯一入口），四段式调度：① 产 - 为一个小功能跑完整调研 - 输出长文却给不出一个结论 -- 跳过"不做什么" +- 跳过「不做什么」 - 用户只问单点，却强行拉进全链路 - 把估算数据写成确凿事实 -- 跳过 ③ 段 D0 的 Gate-1（未定死令牌表与设计契约）就开写页面代码 -- 在 `grill-me` 提问模式下仍套用"提问上限 3 个"，把提问做成走过场 -- **只跑一次 `grill-me`**：① 没定义需求就去取证，或 ② 拿①段的需求定义代替功能压测直接写 ②段 -- **把自动补全当默认动作**：用户没说话就替用户拍板，还没标 `【假设】`、没进待复核清单 -- 把 ④ 的说明区写进产品功能范围，或让 ③ 顺手把说明文档一起写了（该调 `stage-proto-doc` 就调） +- 跳过③段 D0 的 Gate-1（未定死令牌表与设计契约）就开写页面代码 +- 在 `grill-me` 提问模式下仍套用「提问上限 3 个」，把提问做成走过场 +- 只跑一次 `grill-me`：①没定义需求就去取证，或②拿①段的需求定义代替功能压测直接写②段 +- 把自动补全当默认动作：用户没说话就替用户拍板，还没标 `【假设】`、没进待复核清单 +- 把④的说明区写进产品功能范围，或让③顺手把说明文档一起写了（该调 `stage-proto-doc` 就调） - 手写 Mermaid 代替 diagram-design，手写 token 表代替 DESIGN.md -- 绕过四段自己手搓（该调 `stage-*` 就调，不要重写它们的内容） -- 把两个页面设计技能（`open-design` / `oil-ui-pro`）的内部路径按本 skill 目录去拼，或改它们的正文（它们是**技能仓库里的供给技能**，改动只写 `stage-delivery` 自己的 `SKILL.md` / `references/`；⛔ 两个技能平行同层级，**不缝成一条流水线**，也**不把 `oil-ui-pro` 的评分循环当成本段 Gate 的替代**） -- **猜 `<项目>`**：定不出来还硬写，把产物落到别的项目目录下 -- **把 `DESIGN.md` 写到仓库根**：多项目会互相覆盖 -- **段间停下来问"要不要继续"**：全流程（自动处理）模式下直接进下一段，只在段末输出报告 +- 绕过四段自己手搓，或重写它们的内容（该调 `stage-*` 就调） +- 把两个页面设计技能（`open-design` / `oil-ui-pro`）的内部路径按本 skill 目录去拼，或改它们的正文（它们是技能仓库里的供给技能，改动只写 `stage-delivery` 自己的 `SKILL.md` / `references/`；两个技能平行同层级，不缝成一条流水线，也不把 `oil-ui-pro` 的评分循环当成本段 Gate 的替代） +- 猜 `<项目>`：定不出来还硬写，把产物落到别的项目目录下 +- 把 `DESIGN.md` 写到仓库根：多项目会互相覆盖 +- 段间停下来问「要不要继续」：全流程（自动处理）模式下直接进下一段，只在段末输出报告 +- 把两种模式混用：在自动处理模式下自作主张停下问方案，或在「方案确认」模式下确认前就开跑②③④ +- 在「方案确认」模式下把①段的方案当成已确认就往下跑：该模式下①段末必须停下等用户确认（含「不做什么」） +- 下游擅自裁剪上游已拍板项：②③④发现要砍①段或决策表里已拍板的东西时，不许自行裁掉或改口径，必须列成「与已定决策的差异」交用户显式确认 +- 把模式当成段：模式是「要不要在①段末停」的开关，不是第五个段，别为它单独造段或造产物 +- 跑了却不说：没声明当前段 / 子步与依据文件，或偏离了被调 skill 的主流程却不声明、不记偏离单（应为：开工先声明、每个子步再声明、偏离当场声明） -## 改名 / 改供给后的自检（⛔ 不许跳过） +## 改名 / 改供给后的自检 ```bash -python scripts/check_naming.py +python scripts/check_naming.py --ws <工作区> ``` -**它查什么**：四段段名与子步名在「总入口 ↔ 各段 `SKILL.md` ↔ 各段 `references/`」之间有没有漂 —— 包括 H1 与子步表是否一致、总入口子步列有没有漏项、runbook 必读表有没有引用已移除的资产、两份副本是否一致。**纯静态比对，不需要渲染、不需要外部依赖。** +它查四段段名与子步名在「总入口 ↔ 各段 `SKILL.md` ↔ 各段 `references/`」之间有没有漂，包括 H1 与子步表是否一致、总入口子步列有没有漏项、runbook 必读表有没有引用已移除的资产、两份副本是否一致。纯静态比对，不需要渲染，不需要外部依赖。 -**为什么必须有它**（不是"为了严谨"，是实测当天就漏过两次，且**没有任何门禁会报错**）： +为什么必须有它：实测当天就漏过两次，而且当时没有任何门禁会报错。 -**第一次（2026-10-02）**：段名从「需求调研 / 功能规划 / 界面与交付」改成「产品需求 / 产品功能 / 界面交互」时 —— `SKILL.md` 改了，但 `references/stage-discovery/references/grill-me.md` 的 H1 仍写「需求澄清（grill-me · 调研段）」；`references/stage-requirements/SKILL.md` 子步表写「2b 功能流转」而正文 H2 写「## 2b 状态机」；总入口④段子步列只写「4a 说明区/ 演示引导」漏了 4b/4c。**三处都只能靠回读发现。** +第一次（2026-10-02）：段名从「需求调研 / 功能规划 / 界面与交付」改成「产品需求 / 产品功能 / 界面交互」时，`SKILL.md` 改了，但 `references/stage-discovery/references/grill-me.md` 的 H1 仍写「需求澄清（grill-me · 调研段）」；`references/stage-requirements/SKILL.md` 子步表写「2b 功能流转」而正文 H2 写「## 2b 状态机」；总入口④段子步列只写「4a 说明区 / 演示引导」漏了 4b / 4c。三处都只能靠回读发现。 -**第二次（2026-10-06，本轮）**：②段收窄为「只细化功能」（7 份产出 → 1 份）后，**各段 `SKILL.md` 都改了，但总入口 `product-planning/SKILL.md` 的三处仍写着旧结构** —— -① 四段表的②段子步列仍是「2a 功能定义与压测 / 2b 功能流转 / 2c 功能图示」； -② 四段表的①段子步列「1c 产品定位与商业设计」未随段内改名（段内已改称「产品定位与场景」）； -③ 正文仍写「**① 与 ② 各跑一次 `grill-me`**」并指向两份同名文档 —— 实际全场只有①段一份。 -⇒ **闸门当场报 6 个 FAIL**，根因就是这处「**改了承载段、忘了总入口**」。 -⭐ **由此立一条硬纪律（与记忆里的「换供给不能只改承载段」同型）**：**凡改子步结构 / 段内产出清单 / 段间交接口，必须连带改总入口 `product-planning/SKILL.md` 的「四段结构」表与「交接口」表** —— 不改就是**半改状态（比不改更糟）**。 +第二次（2026-10-06）：②段收窄为「只细化功能」（7 份产出变 1 份）后，各段 `SKILL.md` 都改了，但总入口的三处仍写着旧结构——①四段表的②段子步列仍是「2a 功能定义与压测 / 2b 功能流转 / 2c 功能图示」；②四段表的①段子步列「1c 产品定位与商业设计」未随段内改名（段内已改称「产品定位与场景」）；③正文仍写「①与②各跑一次 `grill-me`」并指向两份同名文档，实际全场只有①段一份。闸门当场报 6 个 FAIL，根因是「改了承载段、忘了总入口」。 -⛔ **改了段名 / 子步名 / 判据供给源之后必须跑一次，并把结果记进当日 memory** —— 这是"不渲染不算完"的同型要求：改完不校验，下次读契约的人拿到的是错的配方。 +由此立一条硬纪律，与「换供给不能只改承载段」同型：凡改子步结构 / 段内产出清单 / 段间交接口，必须连带改总入口 `product-planning/SKILL.md` 的「四段结构」表与「交接口」表，不改就是半改状态。 -> ⚠️ **本脚本的能力边界**：它只查**文本一致性**（H1 ↔ 子步表 ↔ 总入口 ↔ 副本），**查不出"判据口径是否自相矛盾"**。 -> 例如「②段到底该不该给页面结构」这种反转，**闸门一个字都报不出来**（两版写法都合法）。 -> ⇒ **口径类改动要靠人工回读**，且**必须把反转理由与用户原话写进文档留痕**。 -⚠️ 脚本输出里的 `[提示]` 项（旧名出现）**不计入失败**，但要人工看一眼是不是落在「废止理由块」里 —— 落在里面是正当留痕，散落在正文里就是真残留。 -🔴 **2026-10-07 起本技能只在全局一份**：`E:/ProgramData/.workbuddy/skills/product-planning/` —— -**它就是本体**，⛔ 不再有「主 / 副 / 装入」三副本，也⛔ 不再需要「三处 md5 复核」 -（那只在有副本时才有意义）。改完**只跑一次**：`check_naming.py --ws <工作区>`。 -> 用户原话：「**把产品规划复制到 workbuddy 全局skills中 后续维护和使用全局技能**」。 -> ⚠️ 工作区原先那三份已归档到 `归档/技能迁全局-20261007/`（未直删，可随时取回）。 -- **把两种模式混用**：在自动处理模式下自作主张停下问方案，或在"方案确认"模式下确认前就开跑 ②③④ -- **在"方案确认"模式下把 ① 段的方案当成已确认就往下跑**：该模式下 ① 段末必须停下等用户确认（含"不做什么"） -- **下游擅自裁剪上游已拍板项**：②③④ 发现要砍 ① 段或决策表里已拍板的东西时，不许自行裁掉或改口径，必须列成"与已定决策的差异"交用户显式确认 -- **把模式当成段**：模式是"要不要在 ① 段末停"的开关，不是第五个段，别为它单独造段或造产物 -- **跑了却不说**：没声明当前段/子步与依据文件，或偏离了被调 skill 的主流程却不声明、不记偏离单（应为：开工先声明、每个子步再声明、偏离当场声明） \ No newline at end of file +改了段名 / 子步名 / 判据供给源之后必须跑一次，并把结果记进当日 memory——与「不渲染不算完」同型：改完不校验，下次读契约的人拿到的是错的配方。 + +本脚本只查文本一致性（H1 ↔ 子步表 ↔ 总入口 ↔ 副本），查不出「判据口径是否自相矛盾」。例如「②段到底该不该给页面结构」这种反转，闸门一个字都报不出来（两版写法都合法）。口径类改动要靠人工回读，且必须把反转理由与用户原话写进文档留痕。 + +脚本输出里的 `[提示]` 项（旧名出现）不计入失败，但要人工看一眼是不是落在「废止理由块」里——落在里面是正当留痕，散落在正文里就是真残留。 + +2026-10-07 起本技能只在全局一份：`E:/ProgramData/.workbuddy/skills/product-planning/`。它就是本体，不再有「主 / 副 / 装入」三副本，也不再需要「三处 md5 复核」（那只在有副本时才有意义）。改完只跑一次 `check_naming.py --ws <工作区>`。用户原话：「把产品规划复制到 workbuddy 全局skills中 后续维护和使用全局技能」。工作区原先那三份已归档到 `归档/技能迁全局-20261007/`（未直删，可随时取回）。 diff --git a/product-planning/references/_留痕/SKILL-总入口-20261007改说人话前.md b/product-planning/references/_留痕/SKILL-总入口-20261007改说人话前.md new file mode 100644 index 0000000..c92ff85 --- /dev/null +++ b/product-planning/references/_留痕/SKILL-总入口-20261007改说人话前.md @@ -0,0 +1,260 @@ +--- +name: product-planning +description: 产品规划总入口（唯一入口），四段式调度：① 产品需求 ② 产品功能 ③ 界面交互 ④ 原型说明文档。四段以 references/stage-* 承载，本文件是总调度与约束。可整段跑也可只调一段。当用户要做产品规划、从零做新产品、只做某一阶段、或不知道从哪开始时调用。 +--- + +# 产品规划总入口（Product Planning） + +> **Trae 用法**：本 skill 由模型按需自动加载，没有斜杠命令。若对话中尚未明确对象，先按下面「项目与路径约定」定出 `<项目>`，**定不出来就停下问用户，不要自行假设**。 + +## 用途 + +用户只有一句模糊想法（例："我要做一个 AI 短剧分镜画布"）时，本 skill 负责判断阶段、只做该段最小必要工作、产出可交付物、并推进到下一段。 + +**本 skill 只做调度与约束，不重复任何被调 skill 的内容。下游 skill 都是外部成熟工具，不要自己重写一遍。** + +## 四段结构（可整段跑，也可只调一段） + +| 段 | 回答的问题 | 子步 | 调用 | 产出物 | +|---|---|---|---|---| +| **① 产品需求** | 要做的东西**凭什么成立**：什么问题、为谁、为什么值得做 | 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 | 说明区与演示引导（④段的活，③段顺手写就是越界） | + +> **口径：②段钉骨架，③段做皮肉。** 用户原话：「3 是负责设计和交互，**页面关系和布局必须在第二步确认清楚，不然第三步没有方向 一会一个样子**」。 +> ⇒ **②段必须给**：有哪几页、每页几个板块、板块怎么排、跨页关系。**③段⛔ 不许增删移动板块**，缺板块回②段改 ②段。 +> ⛔ **仍归③段**：配色 / 字体 / 间距 / 组件样式 / 动效，以及每个板块的视觉与交互实现。 + +> ⚠️ **②→③ 仍是本流水线最容易被搞坏的一环**，但病灶换了位置：旧病灶是「②段 说"必须能**读到**"，③段读成"必须**常驻主屏**"」→ 五类信息全铺一屏 → 信息墙。 +> **分档表就是为这句歧义而生的**：它把"读到"明确成"一次点击内可达"这一档。**该纪律照旧有效**，只是现在**骨架不由③段独立推导，而是②段给定、③段在骨架内兑现分档**。 + +> 💡 **③段为什么在骨架给定后仍然不会"退化成照抄"**：它做的仍是**另一类工作** —— 骨架是灰块（有哪些块、什么顺序），③段要给的是**视觉与交互实现**（怎么排版好看、点哪有什么反馈、空态怎么呈现、响应式怎么变）。**两者不是同一样东西的粗细两版，是两个维度。** + +> **四段各占一个词，互不共用**（2026-10-02 定）：**产品 / 功能 / 界面 / 说明**。 +> 改段名前先对照这张表——**若两个段名里出现同一个词，边界一定在漂**。历史上「调研与方案 / 需求与结构」两段名里都含"需求"、③段名里的"交付"是全三段共有的属性，都属名实不符，已改。 +> ①叫「产品需求」而不叫「需求调研」：该段产出 `research/1a-需求文档.md`、`1b-竞品分析.md`、`1c-用户画像.md` **也**产出 `1d-产品策略.md`、`1e-使用场景.md`，"调研"二字盖不住后半截。 +> ⭐ **1b 是①段唯一交两种体例的子步**（2026-10-07 用户定案「**竞品分析 有独立分析也有汇总分析 都应该要用上**」）：独立分析体 = `research/1b-独立分析/<竞品名>.md`（竞品池每一个一份）＋ 汇总对比体 = `research/1b-竞品分析.md`（恒一份）。其余四个子步各一份。职责边界见 `references/stage-discovery/references/competitor-analysis.md` §0.4。 + +⭐⭐ **`grill-me` 全场只有①段一份（2026-10-06 用户定案）**：用户原话「**grill 也应该拿到第一步了，第二部就是细化功能**」。 +①段那份**按 A / B 两节提问**：**A 节**「要做什么、为谁、边界在哪」（原①段火力点）｜**B 节**「做成什么样、哪些情况不成立、状态怎么流转」（原②段火力点）；B 节结论落进 `research/1a-需求文档.md`。 + +⭐⭐ **②段产出两份（2026-10-06 收窄 · 2026-10-07 定为两份）**：用户原话「**不需要 就用使用场景，其余6分都不需要了**」「**2 产品功能 和 界面布局不就是两个文档嘛**」。 +`prd/2a-产品功能.md`（功能清单：做哪些 / 不做哪些 / 每条带优先级 + 状态流转）＋ `prd/2b-界面布局.md`（页面关系 + 页面内板块布局）。 + +（历史：交接口反转前的口径、②段收窄前的产出清单与其去向 → `references/_留痕/③段与总入口-旧口径.md`） +⚠️ **本段功能的组织方式是按「使用场景」**（一条场景可跨多个页面），⛔ 不按页面组织。 + +段内的子步顺序、方法论文档、硬约束、完成标准，**都在各段自己的 `SKILL.md` 与 `references/` 里，本文件不重复**。 + +**①段 1a 需求文档**：全程最先做（且只做一次）——用 grill-me 与用户互动，产出一份 `docs/pm/<项目>/research/1a-需求文档.md`（开头写清做什么/为谁/不做什么，往下是决策表）。 + +## 项目与路径约定（单一真源） + +> 四段全部遵守本节。**各段 `SKILL.md` 与 `references/` 里出现 `docs/pm/...` 时，`<项目>` 一律指本节定义的 slug，不另作解释。** + +### `<项目>` 是什么 + +**项目 slug**：小写字母 / 数字 / 连字符（例 `my-tool`、`video-canvas`）。 +它同时是 `docs/pm/<项目>/` 与 `designs/<项目>/` 的目录名——**两处必须同名，一个字都不能差**。 + +### slug 怎么定（按序取第一个成立的，不许猜） + +| 序 | 条件 | 取值 | +|---|---|---| +| 1 | 用户在当前会话里明确说了项目名 | 该名字 slug 化 | +| 2 | `.registry/current-project` 存在且非空 | 其内容 | +| 3 | `docs/pm/` 下恰有一个非 `_` 开头的目录 | 该目录名 | +| 4 | 以上都不成立 | **停下问用户**，不许自行假设 | + +**写任何文件之前先核对**：目标路径里的 `<项目>` 段与按上表得出的 slug 是否一致；不一致就停下说明，不要"先写了再说"。猜错会把产物写进别的项目，事后极难拆干净。 + +### 产物落哪 + +| 段 | 路径 | +|---|---| +| ① 产品需求 | `docs/pm/<项目>/research/` | +| ② | `docs/pm/<项目>/prd/`、`docs/pm/<项目>/ux/`、`docs/pm/<项目>/ux/diagrams/` | +| ③ | `docs/pm/<项目>/DESIGN.md`、`designs/<项目>/*.html`、`designs/<项目>/3c-GPT会诊.md` | +| ④ | 写进原型 HTML 自身（`designs/<项目>/*.html`），不额外落 md | + +### DESIGN.md 为什么在项目目录、不在仓库根 + +`DESIGN.md` 是 ③ 段的**绑定视觉规范**，**一个项目一份**，③ 段按当前项目的 slug 去读它。仓库根只能放一份，多项目会互相覆盖，所以一律放 `docs/pm/<项目>/DESIGN.md`。 + +**推论（硬规则）**：读 `DESIGN.md` 时，路径必须由本节定义的 `<项目>` slug 拼出，**不许用"当前工作目录碰巧有 DESIGN.md"这类推断**。仓库根**不放**任何项目的 `DESIGN.md`。 + +## 工具选择规则（防止选错，最重要的一节） + +> 下表是选型总则。这些工具**都已封装在对应段内**，本文件只负责让你不选错，不负责给出调用路径——具体路径见各段 `SKILL.md`。 + +| 要什么 | 用谁 | 不要用什么 | +|---|---|---| +| 页面设计全链（规范 → 原型 → 审查） | ③ 段 `stage-delivery` 自己的 D0→D5 流水线（判据与素材由两个页面设计技能供给） | 不要另找风格库、也不要自己手搓一套 token 与门禁 | +| 评审用的可点原型 / 生产级前端页面 | ③ 段 3b（按 D2 构建，单文件 HTML 交付；**先判页型**：营销页取 `open-design` 技能的 `design-templates/web-prototype/`，**工具型页面取 ③段 `references/layouts-tooling.md`**） | ⛔ **不要不判页型就套 `web-prototype` 种子** —— 那是营销落地页骨架，会把后台做成营销页 | +| 设计规范文件 | ③ 段 3a 生成 `DESIGN.md`（令牌表由 `open-design` 技能选定套的 `tokens.css` 产出 + 该项目②段的界面需求） | 不要凭空编一套 token | +| 架构图 / 流程图 / 时序图 | `diagram-design` | **不要手写 Mermaid** | +| 状态迁移的守卫/副作用/并发 | `state-machine` | diagram-design 不覆盖这些，别指望它 | +| 审美方向 / 风格定调 | `open-design` 技能里**选一套**（读候选套 `DESIGN.md` 第 1 章，按页面类型挑） | 不要用"米白+衬线+陶土色"这类默认审美，也不要凭感觉编 | +| 多方向比选 / 独立评审打分 | `oil-ui-pro` 技能（方向探索 `design-direction.md`＋对比页 `style-explorer.md`；评审协议 `visual-review.md`） | ⛔ 不要拿它的评分循环替代本段 Gate-1/2/3 | + +**③ 段的页面设计供给来自两个独立技能（2026-10-05 定）**，都装在 `.workbuddy/skills/` 技能仓库、**都可脱离本段单独使用**： +- **`open-design`**（判据供给库）：`design-systems/`（153 套，**定调只从这里选，不凭感觉编**）｜`craft/`（13 份工艺判据：状态穷举 / 字阶 / 配色 / 动效 / 反 AI 味 / 无障碍）｜`design-templates/web-prototype/`（版式骨架种子，⚠️ **营销页向**）。 +- **`oil-ui-pro`**（界面设计方法论）：五步流程（探索方向 → 建结构 → 取实证 → 独立评审打分 → 验证交付）＋ 风格对比页与截图工具。⚠️ 它**自带联网版本检查与自动更新**，是用户明确要求全量搬入的**例外项**（既有纪律是"依赖外部服务一律不收"），记录在案、不扩散。 +- ⭐ **两者平行同层级、不缝成一条流水线**：多数页面走 `open-design` 主线；需要「先拉开方向让用户挑」或「独立评审打分」时取 `oil-ui-pro`。 + +⛔ **四样东西两个技能都没有对应，必须由 `stage-delivery` 自己扛**：**设计契约十二字段 / 结构骨架 / 交互清单 / 工具型版式库**。 +🔴 **页型分流（2026-10-05 新增）**：`web-prototype` 的种子与 8 骨架**全是营销落地页结构**（hero / features / stats / quote / CTA），自带 `.eyebrow`（眉标）与 `.lead`（副标题）。**工具型页面（后台 / 控制台 / 列表 / 详情）照它做会长出「标题上下各一行小字」的三段式** —— 这是本项目实测踩过的坑，且**结构判据全绿也拦不住**。⇒ ③段 D0 **必须先判页型**，工具型页面**零 `.eyebrow` / 零 `.lead` / 零 `.hero`**，版式走 ③段 `references/layouts-tooling.md`。 +⛔ **只读一处来源** —— 同一条判据若在 `stage-delivery` 与 `craft` 各有一份且口径不同，以本项目追加条为准，并在 runbook §3.4 显式标注「本项目追加」。 + +**DESIGN.md 说明**：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec` 四个子命令，目前是 alpha（v0.4.0）。在非 TTY 的管道里可能不回显输出，需在真实终端里确认结果。**本机实测该命令完全不可用，不要拿它当校验关卡**；改由 D3 收口与 D5 终检**按真实像素人工复测**对比度（判据见 `open-design` 技能的 `craft/color.md`）。⚠️ 原两把门禁脚本（静态文案检查 / 渲染机检）**已随旧主干从磁盘移除**，当前**没有机器复现** ⇒ 结论只能记「人工判定」，不得写成「脚本已通过」。 + +## 可调用工具（自然语言触发） + +> 两个「随段携带」的独立工具，装在 ③段 `references/stage-delivery/assets/` 下；按用户说法直接触发，产物落项目目录。它们**不是**新的段，只是叫得动的工具。 + +| 用户说 | 触发工具 | 做什么 | 产物 | +|---|---|---|---| +| 「**分析 XXX 视频**」「把这个视频抽帧」「拆一下这条视频的画面」 | `stage-delivery/assets/video-capture/` | 取视频（本地文件 / 直链 URL）＋ 抽帧（双因素 ＋ 首尾 ＋ 补帧） | 关键帧 `frames/` ＋ `frame_times.json`（供 ①竞品分析 / ③视觉参考） | +| 「**获取 XXX 网站的设计风格**」「抓这个网站的风格/组件/配色」 | `stage-delivery/assets/design-capture/` | 抓网页设计系统（色彩 / 排版 / 组件）→ 生成样式模板 | 一套 `design-system-<名>/`（与 `design-system-tiaoyue` 同构，可直接被 ③段 D1 选用） | + +- 两者都**独立、可单跑**：`video-capture` 只依赖 `ffmpeg`；`design-capture` 只依赖本机 Chrome（CDP）＋ `vendor/` 里搬运的抽取脚本，**⛔ 不依赖 open-design daemon**。 +- 用法与边界见各自 `SKILL.md`；来源与署名见各自 `ATTRIBUTION.md`。 +- 触发时机：①②段拆竞品视频 → `video-capture`；③段要新建样式或拆参考站 → `design-capture`。 +- ⛔ 两工具都**只做合规最小集**（不抓平台页内视频、⛔ 不调付费接口）；抽取结果须先目视比对再采用。 + +## 进入方式 + +| 你说什么 | 模式 | 从哪开始 | +|---|---|---| +| "规划 XX" / "从零做 XX" | **全流程（自动处理）** | `stage-discovery` → `stage-requirements` → `stage-delivery` → `stage-proto-doc`，**一路跑完，段间不停下来问**（含 ① 段末） | +| "先确认方案" / "跑完方案停下等我" / "规划 XX，先给方案" | **方案确认** | 同全流程、同一套四段，**唯一差别是 ① 段末停下等你确认方案**，确认后才进 ②③④ | +| "只做产品需求" / "只做产品功能" / "只做界面交互" / "只做原型说明文档" | **单段** | **只调对应那一个 stage skill**，不展开其他段，也不催促回补前段 | +| 已有 ②段，要出原型 | 单段 | 直接调 `stage-delivery`，从它的 3a 起 | +| 已有原型，要补说明 | 单段 | 直接调 `stage-proto-doc`，从它的 4a 起 | +| 只问某个单点 | 单段 | 不跑任何段，在对应 stage skill 内点名子步，或直接说要看哪份方法论 | + +**为什么"只调一段"成立**：四段之间**只通过落盘文件耦合**，没有隐式状态。 + +- ② 只读 `docs/pm/<项目>/research/*` 与 `docs/pm/<项目>/strategy/*`；缺失时标注 `【假设】` 继续，**不强制回补 ①** +- ③ 只读 `docs/pm/<项目>/prd/*` 与 `docs/pm/<项目>/ux/state-machine.md`；缺失时同样标 `【假设】` 继续 +- ④ 只读 `designs/<项目>/*.html`，另按需读 `docs/pm/<项目>/prd/*` 与 `docs/pm/<项目>/ux/state-machine.md` 校准术语；缺失时标 `【假设】` 继续 + +## 执行规则 + +**只有三种模式**（对应上表），没有第四种： + +| 模式 | 段之间 | 段之内 | +|---|---|---| +| **全流程（自动处理）** | **一路跑完，段间不停下来问**（含 ① 段末）。每段结束按「标准收尾格式」输出一段报告，**输出完即刻进下一段** | 子步之间不反问，做完直接进下一个子步 | +| **方案确认** | 与全流程**完全相同，只有一处不同**：**① 段末停下等你确认方案**；确认后 ②③④ 一路跑完、段间不停 | 同上 | +| **单段** | 不涉及 | 同上；不越界、不催促回补前段 | + +**这两条是全流程模式下的两个独立分支，不要混**：**全流程（自动处理）没有 ① 段末的强制停**；「停下等确认方案」**只在"方案确认"模式下发生**。二选一由用户定（界面里点【生成原型和文档】时选「自动处理」或「先确认方案」，或在会话里直接说明）；**用户没明说时按自动处理走**，不要在自动处理模式下自作主张停下来问。 + +**"停下"到底指什么**——不要读成"每一步都要反问用户"。只有这四种情况才停： + +1. **信息不足且查不到**，必须用户给（如「项目与路径约定」slug 第 4 条）——停下问 +2. **破坏性 / 不可逆动作**——二次确认 +3. **用户显式要求**某个子步做完停下 +4. **① 段末的方案确认（仅"方案确认"模式）**——把方案摆给用户：做什么 / 不做什么 / MVP 边界 / 未复核的 `【假设】`，明说"等你确认方案，确认前不进 ② 段" + +段末报告：**全流程（自动处理）模式下，所有段（含 ①）都只输出报告，不提问、不等回答**；**方案确认模式下 ① 段是唯一例外**，其余段同样只输出报告。 + +**① 段末的确认是回环，不是一次问答**（仅"方案确认"模式）：用户看到方案后可以提问题要求改（可能多轮），每轮的"问题 + 怎么改的"都要留痕、不得覆盖上一轮；改完由用户显式说"确认方案"才算过闸门。**该模式下，没拿到用户确认的方案不得当成既定事实带进 ② 段**（这是本项目真实踩过的坑：② 段拿着未经确认的方案往下跑，把用户已拍板的需求裁掉了）。 + +其余规则： + +- **声明制（全段适用，不止 ③ 段）**：开工前、每进一个子段/子步、每处偏离，都要声明三件事——**当前在哪 / 依据哪个文件的哪一节 / 产出落哪**；偏离当场写明原因与影响，段末附**偏离单**。**不许静默偏离。** 这是本项目踩过的坑：③ 段 3b 交付了原型却没走当时声明的主流程、没读依据文件，也**没有当场说**，用户直到追问"基于哪个 skill"才知道。 +- **不做八股**：不介绍方法论来源，不列人名，不复述框架历史。直接给结论。 +- ⭐⭐ **内容准则：一切落盘文字都要先过「说人话」这一关（2026-10-07 用户定案；同日扩大到规则文件）**。用户原话：「**当作第一步 和 第二步 生成文档时 必须遵循的内容准则**」＋「**不管是写规则 还是 写文档 都要严格按照说人话的技能去执行**」。 + - **适用面（两类都算，⛔ 只改产出不改规则＝半改）**：① **产出文档** —— `research/1a-需求文档.md` — `1e-使用场景.md`（5 份）＋ `research/1b-独立分析/`（独立分析体）＋ `prd/2a-产品功能.md` — `prd/2b-界面布局.md`（2 份）；② **规则本身** —— 本技能包内的一切落盘文字：`SKILL.md`、`references/**`、模板与清单。 + - **判据来源（单一可信源，本文件不复述模式清单）**：`humanizer`（55 条模式 · 5 种口吻档 casual / professional / technical / warm / blunt）＋ `humanizer-zh`（24 条模式 · 快速检查清单 · 50 分制评分）。两份技能都在 `E:/ProgramData/.workbuddy/skills/`；完整判据以源技能正文为准。 + - **门槛**：按 `humanizer-zh` 五维评分（直接性 / 节奏 / 信任度 / 真实性 / 精炼度）**≥45 / 50** 才准落盘；低于 45 回炉重写，不给"差不多"放行。 + - **五条核心原则**（源技能《核心规则速查》摘引）：**删填充短语**（开场白、强调性拐杖词）｜**打破公式结构**（二元对比、戏剧性分段、修辞性设置）｜**变化节奏**（长短交错，两项优于三项，段尾多样）｜**信任读者**（直接陈述事实，跳过软化、辩解、手把手引导）｜**删金句**（读起来像可引用的话，就重写它）。 + - **交付留证**：产出文档在段末报告里写明"已过内容准则，评分 X/50"；改规则文件时，同样要在当日 memory 里记下这一关过了。⛔ 没写等于没做。 +- **只调一段时不越界**：用户说"只做第 N 段"，就跑该段，不展开其他段，也不用"你还没做调研"去催促。 +- **提问上限 3 个**：其余用合理假设，并在文档里标注 `【假设】`。**例外：进入 `grill-me` 提问模式时不受此限**（① 段的"需求澄清"与 ② 段的"需求压测"各是一次）——该模式的价值就是穷尽提问。此时须先声明"将连续多轮提问"，退出后恢复本约束。 +- **反问优先，允许自动补全**：`grill-me` 的默认动作是把问题抛给用户并附推荐答案。用户说"你定"、连续两轮不回应、或属事实类问题时，模型自行给答案并标 `【假设】`，换来"不卡住"；但每轮结束要汇出**待复核清单**，未经复核的 `【假设】` 不得在下游当事实用。 +- **MVP 边界优先**：任何阶段都先回答"第一版做什么 / 不做什么"。 +- **必须落盘**：产出写入文件，不要只在对话里输出。 +- **无来源就标注**：任何查不到来源的数据都标为"估算"并写明口径，⛔ 不编造数字当事实。 +- **禁止长文**：单份产出物默认一页纸（≤120 行）；超长必须拆分。 + +## 每段的标准收尾格式 + +``` +## 本段结论 +- （3-5 条，可直接决策的话） + +## 已落盘 +- ... + +## 待确认（最多 3 条） + +## 建议下一步 +→ 用 完成 <具体事> +``` + +## 反面清单 + +- 为一个小功能跑完整调研 +- 输出长文却给不出一个结论 +- 跳过"不做什么" +- 用户只问单点，却强行拉进全链路 +- 把估算数据写成确凿事实 +- 跳过 ③ 段 D0 的 Gate-1（未定死令牌表与设计契约）就开写页面代码 +- 在 `grill-me` 提问模式下仍套用"提问上限 3 个"，把提问做成走过场 +- **只跑一次 `grill-me`**：① 没定义需求就去取证，或 ② 拿①段的需求定义代替功能压测直接写 ②段 +- **把自动补全当默认动作**：用户没说话就替用户拍板，还没标 `【假设】`、没进待复核清单 +- 把 ④ 的说明区写进产品功能范围，或让 ③ 顺手把说明文档一起写了（该调 `stage-proto-doc` 就调） +- 手写 Mermaid 代替 diagram-design，手写 token 表代替 DESIGN.md +- 绕过四段自己手搓（该调 `stage-*` 就调，不要重写它们的内容） +- 把两个页面设计技能（`open-design` / `oil-ui-pro`）的内部路径按本 skill 目录去拼，或改它们的正文（它们是**技能仓库里的供给技能**，改动只写 `stage-delivery` 自己的 `SKILL.md` / `references/`；⛔ 两个技能平行同层级，**不缝成一条流水线**，也**不把 `oil-ui-pro` 的评分循环当成本段 Gate 的替代**） +- **猜 `<项目>`**：定不出来还硬写，把产物落到别的项目目录下 +- **把 `DESIGN.md` 写到仓库根**：多项目会互相覆盖 +- **段间停下来问"要不要继续"**：全流程（自动处理）模式下直接进下一段，只在段末输出报告 + +## 改名 / 改供给后的自检（⛔ 不许跳过） + +```bash +python scripts/check_naming.py +``` + +**它查什么**：四段段名与子步名在「总入口 ↔ 各段 `SKILL.md` ↔ 各段 `references/`」之间有没有漂 —— 包括 H1 与子步表是否一致、总入口子步列有没有漏项、runbook 必读表有没有引用已移除的资产、两份副本是否一致。**纯静态比对，不需要渲染、不需要外部依赖。** + +**为什么必须有它**（不是"为了严谨"，是实测当天就漏过两次，且**没有任何门禁会报错**）： + +**第一次（2026-10-02）**：段名从「需求调研 / 功能规划 / 界面与交付」改成「产品需求 / 产品功能 / 界面交互」时 —— `SKILL.md` 改了，但 `references/stage-discovery/references/grill-me.md` 的 H1 仍写「需求澄清（grill-me · 调研段）」；`references/stage-requirements/SKILL.md` 子步表写「2b 功能流转」而正文 H2 写「## 2b 状态机」；总入口④段子步列只写「4a 说明区/ 演示引导」漏了 4b/4c。**三处都只能靠回读发现。** + +**第二次（2026-10-06，本轮）**：②段收窄为「只细化功能」（7 份产出 → 1 份）后，**各段 `SKILL.md` 都改了，但总入口 `product-planning/SKILL.md` 的三处仍写着旧结构** —— +① 四段表的②段子步列仍是「2a 功能定义与压测 / 2b 功能流转 / 2c 功能图示」； +② 四段表的①段子步列「1c 产品定位与商业设计」未随段内改名（段内已改称「产品定位与场景」）； +③ 正文仍写「**① 与 ② 各跑一次 `grill-me`**」并指向两份同名文档 —— 实际全场只有①段一份。 +⇒ **闸门当场报 6 个 FAIL**，根因就是这处「**改了承载段、忘了总入口**」。 +⭐ **由此立一条硬纪律（与记忆里的「换供给不能只改承载段」同型）**：**凡改子步结构 / 段内产出清单 / 段间交接口，必须连带改总入口 `product-planning/SKILL.md` 的「四段结构」表与「交接口」表** —— 不改就是**半改状态（比不改更糟）**。 + +⛔ **改了段名 / 子步名 / 判据供给源之后必须跑一次，并把结果记进当日 memory** —— 这是"不渲染不算完"的同型要求：改完不校验，下次读契约的人拿到的是错的配方。 + +> ⚠️ **本脚本的能力边界**：它只查**文本一致性**（H1 ↔ 子步表 ↔ 总入口 ↔ 副本），**查不出"判据口径是否自相矛盾"**。 +> 例如「②段到底该不该给页面结构」这种反转，**闸门一个字都报不出来**（两版写法都合法）。 +> ⇒ **口径类改动要靠人工回读**，且**必须把反转理由与用户原话写进文档留痕**。 +⚠️ 脚本输出里的 `[提示]` 项（旧名出现）**不计入失败**，但要人工看一眼是不是落在「废止理由块」里 —— 落在里面是正当留痕，散落在正文里就是真残留。 +🔴 **2026-10-07 起本技能只在全局一份**：`E:/ProgramData/.workbuddy/skills/product-planning/` —— +**它就是本体**，⛔ 不再有「主 / 副 / 装入」三副本，也⛔ 不再需要「三处 md5 复核」 +（那只在有副本时才有意义）。改完**只跑一次**：`check_naming.py --ws <工作区>`。 +> 用户原话：「**把产品规划复制到 workbuddy 全局skills中 后续维护和使用全局技能**」。 +> ⚠️ 工作区原先那三份已归档到 `归档/技能迁全局-20261007/`（未直删，可随时取回）。 +- **把两种模式混用**：在自动处理模式下自作主张停下问方案，或在"方案确认"模式下确认前就开跑 ②③④ +- **在"方案确认"模式下把 ① 段的方案当成已确认就往下跑**：该模式下 ① 段末必须停下等用户确认（含"不做什么"） +- **下游擅自裁剪上游已拍板项**：②③④ 发现要砍 ① 段或决策表里已拍板的东西时，不许自行裁掉或改口径，必须列成"与已定决策的差异"交用户显式确认 +- **把模式当成段**：模式是"要不要在 ① 段末停"的开关，不是第五个段，别为它单独造段或造产物 +- **跑了却不说**：没声明当前段/子步与依据文件，或偏离了被调 skill 的主流程却不声明、不记偏离单（应为：开工先声明、每个子步再声明、偏离当场声明） \ No newline at end of file diff --git a/product-planning/references/stage-discovery/SKILL.md b/product-planning/references/stage-discovery/SKILL.md index 6ca6eaf..a58b06e 100644 --- a/product-planning/references/stage-discovery/SKILL.md +++ b/product-planning/references/stage-discovery/SKILL.md @@ -11,19 +11,20 @@ description: 产品规划第①段，产品需求。五个子步依次产出五 ## ⭐⭐ 产出白名单（2026-10-06 用户定案 · 硬规矩） -**本段只产出这五份，一份不多、一份不少**： +**本段在 `research/` 顶层只产出这五份，一份不多、一份不少**： | 子步 | 产出 | |---|---| | **1a** 需求文档 | `research/1a-需求文档.md` | -| **1b** 竞品分析 | `research/1b-竞品分析.md` | +| **1b** 竞品分析 | `research/1b-竞品分析.md`（汇总对比体，恒一份）＋ `research/1b-独立分析/<竞品名>.md`（独立分析体，竞品池里每一个一份） | | **1c** 用户画像 | `research/1c-用户画像.md` | | **1d** 产品策略 | `research/1d-产品策略.md` | | **1e** 使用场景 | `research/1e-使用场景.md` | 🔴 **用户原话**：「**禁止出现之前确定的以外的文档，除非用户明确要求**」。 -⛔ **不许自行新增第 6 份** —— 实测栽过：某轮因为"用户点名了参考产品"就自作主张多产了一份《参考实装拆解》，导致用户反复看到"冒出来的不相关的文档"。**"参考产品怎么做的"属 1b 竞品分析的取材范围，写进 `1b-竞品分析.md` 里，⛔ 不另立一份。** -✅ **门禁可查**：`check_naming.py` 扫本段目录，出现白名单外的文件名即报红。 +⛔ **不许自行新增第 6 份** —— 实测栽过：某轮因为"用户点名了参考产品"就自作主张多产了一份《参考实装拆解》，导致用户反复看到"冒出来的不相关的文档"。**"参考产品怎么做的"属 1b 竞品分析的取材范围，写进本份里，⛔ 不另立一份。** +⭐ **`1b-独立分析/` 子目录不算"第 6 份"**：它是 1b 的**既定体例之一**（2026-10-07 用户定案：「**竞品分析 有独立分析也有汇总分析 都应该要用上，谁说只有一份竞品分析了**」）。它的份数由**竞品池**决定，⛔ 不由人临时加。除此之外仍然只许上面那五份。 +✅ **门禁可查**：`check_naming.py` 扫 `research/` **顶层**的实际文件名，出现白名单外的文件名即报红（子目录天然放行）。 ## 本段职责（2026-10-06 重划） @@ -32,7 +33,7 @@ description: 产品规划第①段，产品需求。五个子步依次产出五 | 问 | 子步 | 产出 | 性质 | |---|---|---|---| | **要解决什么问题、边界在哪** | 1a 需求文档 | `1a-需求文档.md` | 拍板 | -| **别人做了什么、我们差在哪** | 1b 竞品分析 | `1b-竞品分析.md` | **外部取证** | +| **别人做了什么、我们差在哪** | 1b 竞品分析 | `1b-竞品分析.md` ＋ `1b-独立分析/` | **外部取证** | | **用户是谁、他要办成什么事** | 1c 用户画像 | `1c-用户画像.md` | **外部取证** | | **为什么值得做、边界与风险** | 1d 产品策略 | `1d-产品策略.md` | 判断 | | **用户怎么用它** | 1e 使用场景 | `1e-使用场景.md` | 判断 | @@ -72,35 +73,66 @@ description: 产品规划第①段，产品需求。五个子步依次产出五 | 子步 | 读 | 产出 | |---|---|---| -| 竞品拆解 | `references/competitor-analysis.md` | `docs/pm/<项目>/research/1b-竞品分析.md` | +| 竞品拆解 · 独立分析 | `references/competitor-analysis.md` §11 | `docs/pm/<项目>/research/1b-独立分析/<竞品名>.md`（**竞品池里每一个一份**） | +| 竞品拆解 · 汇总对比 | `references/competitor-analysis.md` §1—§10 | `docs/pm/<项目>/research/1b-竞品分析.md`（**恒一份**） | -⭐ **用户点名的"参考实装"写进本份，⛔ 不另立文档**（见「产出白名单」）。它和通用竞品是同一件事的两层：**通用竞品**看这一类产品都怎么做，**点名参考**拆用户指定的那一个。两者并成一份的 §一 / §二。 +1b 交两种体例（2026-10-07 用户定案：「**竞品分析 有独立分析也有汇总分析 都应该要用上，谁说只有一份竞品分析了**」）。职责边界与数量见 `references/competitor-analysis.md` §0.4；只交一种 ⇒ **1b 没做完**。 + +> 🔴 **写作口径（2026-10-07 补 · 用户报障逐字：「生成的文档并没有说人话，还是我手动要求的」）** +> 本段产出是**给人看的文档**，⛔ 不是模型味的总结。落笔前读一遍其中一份： +> 技能库 `humanizer-zh`（中文版，24 类 AI 写作模式）**或**会话技能包里的 +> `session-mechanism/references/作业规矩/04-去AI味与说话方式.md`（会话场景加固版，带交付前清单与质量评分）； +> **定稿前按它的「交付前快速清单」过一遍**。 +> ⛔ 高频 AI 味一律禁：三段式排比连用、空转评价（「具有重要意义」「值得关注」）、 +> 以「…着」结尾的肤浅分析、模糊归因（「业内人士认为」）、过度加粗、把一句话拆成内联标题垂直列表。 +> ⚠️ 这条口径**适用于本段全部五份产出**（1a～1e），⛔ 不只 1b。 + +⭐ **用户点名的"参考实装"写进本份，不另立文档**（见「产出白名单」）。它是**竞品池的第三层**（直接竞品 / 间接替代 / 点名参考），在 §3—§10 的每一节里与其它竞品**同列参与横向对比**。 🔴 **目标**：从**产品视角**横向拆解竞品 —— 讲**用途**、讲**场景**、讲**功能**、讲**作用**、讲**优势**（2026-10-07 用户口径）。 +🔴 **核心模型 = 五问**（用途 → 场景 → 功能 → 作用 → 优势），本份每一节都在回答其中一问或几问。 + **执行**： 1. 读 `references/competitor-analysis.md`（**唯一**方法论载体，含 §0 Scope 与文末《输出检查》） 2. 按项目目标圈定竞品范围（直接竞品 ＋ 至少 1 个替代/间接方案 ＋ 点名的参考实装） -3. 按 **用途 → 场景 → 功能 → 作用 → 优势** 横向比（⛔ 不按竞品逐个写） -4. 输出优势与不足、可借鉴点与产品机会 -5. 交付前走一遍该方法论文末《输出检查》：任一条为「否」⇒ **退回修改，⛔ 不交付** +3. **先出独立分析体**：竞品池里每一个一份，按 §11 的七节写（哪些节能答、哪些答不了，由 §11 的「取证范围 ↔ 可答节次」定） +4. **再出汇总对比体**：按 **用途 → 场景 → 功能 → 作用 → 优势** 横向比（按用户处境横向铺开，不按竞品逐个写） +5. 输出优势与不足、可借鉴点与产品机会 +6. 交付前走一遍该方法论文末《输出检查》：任一条为「否」⇒ **退回修改，不交付** -🔴 **最低输出结构**（最低要求，⛔ 不是固定模板 —— 不同品类维度不同，可增不可缺）： +🔴 **最低输出结构**（最低要求，按品类可增不可缺）： + +**甲 · 汇总对比体**（`research/1b-竞品分析.md`，恒一份）： | # | 节 | 回答什么 | |---|---|---| -| 1 | 分析目标与范围 | 这次要回答什么 | -| 2 | 竞品选择与范围 | 选了谁、为什么是它 | +| 1 | 分析目标与范围 | 这次要回答什么；五问各落在哪节 | +| 2 | 竞品选择与范围 | 选了谁、属哪一层、为什么是它 | | 3 | 竞品用途 | 是什么 / 给谁用 / 干什么用 | -| 4 | 使用场景横向对比 | 用户在各处境下怎么把事办成 | -| 5 | 功能横向对比 | 功能 → 解决什么问题 → 起什么作用 | -| 6 | 产品机制与交互方式 | 为什么这样设计 | -| 7 | 优势与不足 | 能力 → 场景 → 用户价值 | +| 4 | 使用场景横向对比 | 用户什么时候、为什么用；怎么把事办成 | +| 5 | 功能横向对比 | 有什么能力 / 解决什么问题 / 起什么作用 | +| 6 | 产品机制与交互方式 | 怎么解决 / 为什么这样设计 ⇒ 给用户什么结果 | +| 7 | 优势与不足 | 能力表现 × 场景 × **对比对象** × 用户价值 | | 8 | 竞品能力矩阵 | 共识 / 差异 / 独有 / 普遍短板 / 未解决需求 | | 9 | 可借鉴点与产品机会 | 该借鉴 / 该避开 / 可突破 | | 10 | 结论（产品层） | 本产品应优先解决什么 | -⭐ **①段就是上表这 5 个子步**，每个子步一个方法论载体、一份产出 —— 这套结构**直接服务单机自用的产品**（用户本人就是唯一使用者）。 +**乙 · 独立分析体**（`research/1b-独立分析/<竞品名>.md`，每个竞品一份；结构细则与判据见方法论 §11）： + +| # | 节 | 回答什么 | +|---|---|---| +| 1 | 它是谁、属哪一层、为什么纳入 | 竞品名 / 所属层级 / 纳入理由 | +| 2 | 用途 | 是什么 / 给谁用 / 干什么用 | +| 3 | 场景 | 用户在什么处境下用它；把事办成的实际过程（取不到就显式标缺口） | +| 4 | 能力 | 有哪些功能 / 各解决什么问题 / 起什么作用 | +| 5 | 机制 | 怎么做到的；为什么这样设计 ⇒ 给用户什么结果 | +| 6 | 强在哪、弱在哪 | 能力表现 × 场景 × 对比对象 × 用户价值 | +| 7 | 对我们 | 该借鉴 / 该避开 / 可突破 | + +其中**第 2 / 3 / 6 节是必答项，写法固定**（每组几行、每行叫什么、什么顺序都定死，取不到就照写「取不到」）；第 1 / 4 / 5 / 7 节写法自由。**行名与行数见方法论 §11，本表不复述。** + +⭐ **①段就是上表这 5 个子步**，每个子步一个方法论载体 —— 产出份数上，**1b 是唯一一个交两种体例的子步（独立体多份 ＋ 汇总体一份）**，其余四个子步各一份。这套结构**直接服务单机自用的产品**（用户本人就是唯一使用者）。 （历史：本段曾有过另外几个子步、以及一次子步合并，为什么收成 5 个 → `_留痕/①段-已删除产出与方法论.md`） ## 1c 用户画像（外部取证） @@ -177,8 +209,10 @@ description: 产品规划第①段，产品需求。五个子步依次产出五 - `1a-需求文档.md` 存在（含"做什么 / 为谁 / 不做什么"＋决策表），每项都标了来源（用户拍板 / `【假设】` / `【事实】`） - 顶部状态行给出「已确认 N / 模型补全 M（未经确认）」两个数；**每条 `【假设】` 都能在三种归宿里找到自己**（已确认 / 待实现已排时机 / 已按假设落地） - 1b 竞品分析 + 1c 用户画像 + 1d 产品策略 + 1e 使用场景 **四份齐全** -- ⭐ **目录里不出现白名单外的任何文件**（第 6 份须有用户明确要求） +- ⭐ **1b 两种体例都交了**（2026-10-07 新增）：`research/1b-竞品分析.md`（汇总对比体）**且** `research/1b-独立分析/` 下竞品池每一个一份（独立分析体）—— 只交一种 ⇒ **1b 没做完** +- ⭐ **目录里不出现白名单外的任何文件**（第 6 份须有用户明确要求；`1b-独立分析/` 子目录是 1b 既定体例，不算第 6 份） - 1d/1e 每条结论都标了来源（哪份取证文件或本表哪一行，或 `【假设】`） +- ⭐ **五份都过了「说人话」内容准则**（源技能 `humanizer` / `humanizer-zh`，门槛 ≥45/50）—— 口径见 `product-planning` 的「执行规则」内容准则条；段末报告须写明"已过内容准则，评分 X/50" ## 反面清单 @@ -189,11 +223,14 @@ description: 产品规划第①段，产品需求。五个子步依次产出五 - ⛔ **只做 A 节、跳过 B 节**（2026-10-06 新增）：B 节即原②段的功能压测，跳过它等于把压测整个删掉，接口会带着没压测过的需求直接进②段与原型 - ⛔ **在 B 节把页面结构写死**（2026-10-06 新增）：B 节只给粗粒度形态（有哪几页、大概几个板块）；精确板块清单与布局图归②段的《界面布局》 - ⛔ **产出白名单外的第 6 份文档**（2026-10-06 新增）：⛔ 不许因为"用户点名了某个参考产品/某份素材"就另立文档 —— 写进 `1b-竞品分析.md` 里 +- ⛔ **1b 只交汇总对比体、把独立分析省掉**（2026-10-07 新增）：用户定案「竞品分析有独立分析也有汇总分析 都应该要用上」。⛔ 也不许把独立体写成仓库取证记录 —— 它必须按方法论 §11 的七节答产品面（用途 / 场景 / 能力 / 机制 / 强弱 / 对我们） +- ⛔ **改本技能包的规则文件、却不过「说人话」这一关**（2026-10-07 新增）：规则和产出同一把尺子，⛔ 不许只给产出上锁、自己用另一套腔调写规则 —— 口径见 `product-planning` 的「执行规则」内容准则条 - 没有取证就直接写策略 - 把 11 个子步全跑一遍充数 - 事实与假设混在一起不标注 - **拿"frontier 为空 / 无遗留未决项"当闭合声明，而正文里还挂着未经确认的假设** —— 只读首屏的人会误读成需求已澄清 - ⛔ **凭空给 Importance / Satisfaction 打分** —— 没有任何数据源支撑的数字，⛔ 不许出现在交付物里 +- ⛔ **五份没过「说人话」内容准则就落盘**（带 AI 腔：夸张意义 / 三段式强凑 / 破折号滥用 / 模糊归因 / 通用乐观结尾）—— 门槛 ≥45/50，见 `product-planning` 的「执行规则」内容准则条 ## 反面清单（续） diff --git a/product-planning/references/stage-discovery/references/competitor-analysis.md b/product-planning/references/stage-discovery/references/competitor-analysis.md index f9d16b9..340bc13 100644 --- a/product-planning/references/stage-discovery/references/competitor-analysis.md +++ b/product-planning/references/stage-discovery/references/competitor-analysis.md @@ -24,21 +24,40 @@ 答不出这句话 ⇒ **1b 没做完**。 +### 0.4 两种交付体例（本档的排布） + +1b 交付两份体例，两份都要交（2026-10-07 用户定案：「**竞品分析有独立分析也有汇总分析，都应该要用上**」）： + +1. **独立分析体** —— 一个竞品一份，回答「**这一个**产品是什么、给谁用、怎么把事情办成、强在哪弱在哪、对我们有什么可拿的」。结构见 §11。 +2. **汇总对比体** —— 全池一份，回答「**放在一起比**：共识是什么、差异在哪、哪里没人做好」。结构见 §1—§10。 + +**职责边界（本档定死，避免两边各写一遍、出现两套判据）**： + +- 单个竞品的形态 / 给谁用 / 干什么用、场景里用户把事办成的过程、它自己的能力与机制 → **归独立体（§11）**。 +- 跨竞品的横向铺开（同一场景谁怎么做）、能力矩阵、共识与空白、本产品优先解决什么 → **归汇总体（§1—§10）**。 +- 两边都要写的只有一样：**可借鉴 / 该避开 / 可突破** —— 独立体写「从这一个竞品拿什么」，汇总体写「三类分开汇总并追回 §4 / §5 / §7」。 + +**数量**：独立体 = 竞品池里的每一个（用户点名要求合并的按用户口径合并，如「同源 fork 合成一份」）；汇总体 = 恒一份。 + +**判据**：两种体例都交付了，才算 1b 完成。只交汇总体、或只交独立体 ⇒ **1b 没做完**。 + --- ## 1. 分析目标与范围 -**写什么**：把这次要回答的问题写死在文档开头，并让下列**五问**各有明确落点 —— +**核心模型 = 五问**。本档后面每一节，都在回答五问里的一问或几问；§1 就是把它们摆明。 -| 五问 | 落在哪一节 | -|---|---| -| 用途：它是什么、给谁用、干什么用？ | §3 | -| 场景：用户在什么处境下会用它？ | §4 | -| 功能：它有哪些核心功能？ | §5 | -| 作用：每个功能解决什么问题？ | §5 | -| 优势：它在哪些场景下更强 / 更弱？ | §7 | +| 五问 | 关注点 | 落在哪一节 | +|---|---|---| +| 用途：它是什么、给谁用、干什么用？ | What / Who | §3 | +| 场景：用户在什么处境下会用它？ | When / Why | §4 | +| 功能：它有哪些核心能力？ | What | §5 | +| 作用：每项能力解决什么问题？ | What for | §5 | +| 优势：它相对**谁**、在哪些场景下更强或更弱？ | vs Whom | §7 | -**判据**：五问**各有一处明确落点**（⛔ 不是散落在正文里靠读者自己找）。 +**写什么**：把这次要回答的问题写死在文档开头（本次目标、本次竞品池、本次不展开的部分），并让五问各自落在上表那一节。 + +**判据**：五问**各有一处明确落点**，读的人能在对应节里直接读到答案 —— 收口在 §8 矩阵与 §10 结论。 --- @@ -47,29 +66,30 @@ **写什么**：竞品分三层，逐层交代为什么选它 —— 1. **直接竞品**：解决同一个核心问题、目标用户高度重叠。 -2. **间接 / 替代方案**：同一需求的不同产品形态，或**用户不用这类产品**时的替代做法。 -3. **点名参考实装**：用户**点名指定**的那一个（技能层已定：与通用竞品并成《1b-竞品分析》的 §一 / §二两层，⛔ 不另立文档）。 +2. **间接 / 替代方案**：同一需求的不同产品形态，或**用户换一种做法**时的替代路径。 +3. **点名参考实装**：用户**点名指定**的那一个。 -**数量**：⛔ **不规定固定数量**。要求是「**直接竞品 ＋ 至少 1 个替代/间接方案**」，复杂项目自行加。 +**归属（本档定死，避免歧义）**：点名参考实装就是**竞品池的第三层**，写进同一份 `1b-竞品分析.md`，在 §3—§10 的每一节里**与其它竞品同列参与横向对比**，不单独成节、不另立文档。文档开头要写清「本次竞品池 = 哪几个 ＋ 各自属于哪一层」。 + +**数量**：按项目目标自定。最低要求是「**直接竞品 ＋ 至少 1 个替代/间接方案**」；复杂项目自行加层加项。 **判据**： -- ⛔ **不许因为「名气大 / star 高 / 大家都在用」就把项目纳入竞品池** —— 纳入前必须能回答「**用户为什么会拿它和我们的产品做选择？**」 -- 点名参考实装**必须收录**，且与通用竞品**分开成两层**写。 +- 纳入池子的每一个，都能回答「**用户为什么会拿它和我们的产品做选择？**」（分水岭是**用户的选择**，不是名气大小）。 +- 点名参考实装已收录，且在池子里标明层级。 --- ## 3. 竞品用途（是什么 / 给谁用 / 干什么用） -**写什么**：每个竞品一小段，只答三件事 —— 它是什么形态的产品、服务谁、拿它干什么用。 +**关注点：What / Who。** 每个竞品一小段，只答三件事 —— 它是什么形态的产品、服务谁、拿它干什么用。 -**判据**：读完这段，**没接触过这个产品的人能说清它是干什么的**。 -⛔ 只答这三件事 —— 功能归 §5。 +**判据**：读完这段，**没接触过这个产品的人能说清它是干什么的**；三件事之外的内容归后面的节（能力归 §5、机制归 §6）。 --- ## 4. 使用场景横向对比 -**写什么**：按**用户处境**横向铺开，⛔ **不按竞品逐个写** —— +**关注点：When / Why —— 用户什么时候用、为什么要用。** 按**用户处境**横向铺开： ``` 场景 用户要办成什么 竞品A 怎么做 竞品B 怎么做 竞品C 怎么做 @@ -77,45 +97,53 @@ 场景 2 … ``` -重点⛔ 不是「有 / 没有这个功能」，而是「**用户在这个场景下，它具体怎么让用户把事办成**」： -进入方式 → 操作路径 → 核心步骤 → 系统提供什么帮助 → 最终产出 → 哪一步最省力 → 哪一步最麻烦。 +写在 §4 的是「**什么时候、为什么用**」：用户处于什么处境、要办成什么事、为什么这件事必须做。 -**判据**：能描述出**用户实际使用的过程**。⛔ 只列功能名 = 未达标。 +展开时沿着用户的**实际动作链**走：进入方式 → 操作路径 → 核心步骤 → 系统提供什么帮助 → 最终产出 → 哪一步最省力 → 哪一步最麻烦。这一段要把**用户实际把事办成的过程**写出来，功能名与按钮细节归 §5 / §6。 + +**判据**：能描述出**用户实际使用的过程**（谁、什么处境、办成了什么），并且能说清「**为什么在这个处境下会用它**」。 --- -## 5. 功能横向对比（功能 → 解决什么问题 → 起什么作用） +## 5. 功能横向对比 -**写什么**：先建**一组统一维度**，再横向比。维度**按产品调整**，可用：核心功能 / 辅助功能 / 输入方式 / 处理方式 / 输出方式 / 编辑能力 / 管理能力 / 协作能力 / AI 能力 / 自动化能力。 +**关注点：What —— 有什么能力、能解决什么问题。** 先建**一组统一维度**，再横向比。维度**按产品调整**，可用：核心功能 / 辅助功能 / 输入方式 / 处理方式 / 输出方式 / 编辑能力 / 管理能力 / 协作能力 / AI 能力 / 自动化能力。 **每个功能必须答三问**（本档硬要求）： > **是什么** → **解决什么问题** → **对用户起什么作用** -**判据**： -- ⛔ 「A 有 X，B 有 Y」这种罗列 = 未达标。 -- ⛔ **不给固定字段表** —— 不同品类维度本就不同，钉死字段会让方法论失效。 +维度按品类自定、可增不可缺 —— 每个维度都要出现「解决什么问题 / 起什么作用」这一层。 + +**判据**：读的人能说清**每项能力是为什么问题而存在的**；只摆能力名、不接「解决什么问题」的写法不达标。 --- ## 6. 产品机制与交互方式 -**写什么**：比「**为什么这么做**」。比较：核心任务流程 / 信息组织方式 / 导航结构 / 核心交互 / 默认行为 / 自动化机制 / AI 与用户的分工 / 关键反馈 / 异常处理 / 用户控制权。 +**关注点：How / Why —— 怎么解决、为什么这样设计。** 比较：核心任务流程 / 信息组织方式 / 导航结构 / 核心交互 / 默认行为 / 自动化机制 / AI 与用户的分工 / 关键反馈 / 异常处理 / 用户控制权。 -**判据**：写的是「**它为什么这样设计、这样设计给用户带来什么结果**」；⛔ 不是「界面长什么样」。 +写的是「**它为什么这样设计、这样设计给用户带来什么结果**」；界面外观描述归 §5 的能力层。 + +**判据**：每条机制都能接出「**为什么这样设计 ⇒ 给用户带来什么结果**」，与 §4 的场景、§5 的能力形成因果链。 --- ## 7. 优势与不足 -**写什么**：每个判断都落到 **能力 → 场景 → 用户价值**。 +**关注点：vs Whom —— 相对谁更强、相对谁更弱。** + +判断公式（本档硬要求）： + +> **优势 / 不足 ＝ 能力表现 × 使用场景 × 对比对象 × 用户价值** 例： -> 优势：批量处理能力强；场景：一次要处理大量内容时；作用：减少重复操作；结果：更快出稿。 +> 在「一次要处理大量内容」这个场景下，A 的批量处理能力**相对 B 少三步重复操作**，因此更适合高频批量生产。 -**判据**：任何「好 / 差 / 强 / 弱」都能说出**为什么**。 -⛔ 「体验很好」「设计很现代」这类**无据判断** = 未达标。 +四条要素都要落地：**能力表现**（强在哪）→ **使用场景**（在什么处境下）→ **对比对象**（比谁强/弱）→ **用户价值**（带来什么结果）。精确到「少几步」不是硬要求，但**比较基准必须写出来**。 + +**判据**：任何「好 / 差 / 强 / 弱」都能说出**相对谁、在什么场景下、带来什么结果**。 --- @@ -128,7 +156,9 @@ … … … … … ``` -**判据**：矩阵不是为了「显得专业」，而是要**看得出**五件事 —— 行业共识能力 / 竞品之间的差异能力 / 某家的独有能力 / 普遍做得不好的能力 / 还没被解决好的需求。 +**取值口径**：矩阵里的行**取有代表性、能区分竞品的能力与场景** —— 挑的是「看完这一张就能抓住差异」的那些行。 + +**判据**：矩阵是为了**看得出**五件事 —— 行业共识能力 / 竞品之间的差异能力 / 某家的独有能力 / 普遍做得不好的能力 / 还没被解决好的需求。 --- @@ -142,7 +172,7 @@ 每条给：机会点 → 对应场景 → 用户问题 → 竞品现状 → 建议方向。 -**判据**：本节每一条都要能**追回 §4 / §5 / §7 的某一条**。⛔ 不许凭空提出机会。 +**判据**：本节每一条都要能**追回 §4 / §5 / §7 的某一条**。 --- @@ -150,26 +180,109 @@ **写什么**（一律写成产品层的表述）：用户最核心的需求是什么 / 竞品共同解决了什么 / 竞品共同存在什么问题 / 哪些能力已经是基础能力 / 哪些能力还能形成差异 / 本产品应优先解决什么。 -**判据**：结论**只落在产品层**。 +**判据**：结论**只落在产品层**，并且能一句话接回 §0.3 的完成判据。 + +--- + +## 11. 独立分析体（每个竞品一份） + +**落点**：`docs/pm/<项目>/research/1b-独立分析/<竞品名>.md`。 +> 落点为什么选这个子目录：①段产出白名单闸门只扫 `research/` **顶层**的 `.md`（判据见 `scripts/check_naming.py` 的 `WHITELIST`），独立体放进子目录天然放行 —— 竞品再多也不会撞白名单，⛔ 不必为此扩白名单。 +> ⚠️ 存量项目里的 `证据附卷/` 是历史落点，**不强制迁移**；新项目按上面这条走。 + +**七节齐全，一节不许缺。其中三节写法固定（必答项），另外四节写法自由。** + +> 口径（2026-10-07 用户定案，选「方案 A」）：**只把最容易漏的几组定死，不把整份写成填空题**。定太粗等于没定，定太细遇到形态不一样的竞品会别扭。 + +**写法固定的三节** —— 每组几行、每行叫什么、什么顺序，都固定。取不到证据时**那一行照写，内容写「取不到：<原因>」**，⛔ 不许删行、也不许改写成一段话蒙过去。 + +第 2 节「用途」固定四行： + +``` +- 形态： +- 给谁用： +- 干什么用： +- 证据等级： +``` + +第 3 节「场景」固定六行，沿用户实际动作链： + +``` +- 进入方式： +- 操作路径： +- 核心步骤： +- 系统帮了什么： +- 最终产出： +- 哪一步最省力 / 最麻烦： +``` + +（整节都取不到 ⇒ 六行全写「取不到：<原因>」，并把缺口列在节末。⛔ 不许拿功能名罗列冒充使用过程。） + +第 6 节「强在哪、弱在哪」每写一条强弱，就是固定四行；有几条就重复几组： + +``` +- 能力表现： +- 在什么场景： +- 相对谁： +- 对用户什么结果： +``` + +**写法自由的四节**（结构自己定，判据照旧）： + +1. **它是谁、属哪一层、为什么纳入** —— 竞品名、形态、竞品池层级、纳入理由（分水岭是**用户的选择**，不是名气大小）。 +4. **能力：它有哪些功能，各解决什么问题、起什么作用** —— 每项能力答三问（**是什么 → 解决什么问题 → 对用户起什么作用**）；只摆能力名、不接「解决什么问题」的不达标。 +5. **机制：它怎么做到的，为什么这样设计 ⇒ 给用户什么结果** —— 每条机制都要接出「为什么这样设计 ⇒ 给用户带来什么结果」。 +7. **对我们：该借鉴 / 该避开 / 可突破** —— 每条给「机会点 → 对应场景 → 用户问题 → 它现在怎么做 → 建议方向」。 + +**取证范围 ↔ 可答节次（⛔ 不许越级答）**：取证深度决定哪几节能真答，越级答就是编。 + +- **只有官方自述与仓库元数据**（无源码、无界面）⇒ 第 4、5 节只能写「官方自述的能力」与「有据的推断」，并逐条标证据等级；**第 3 节的六行多半只能写「取不到」**，那就照实写并列出缺口。 +- **有源码** ⇒ 第 4、5 节可写实现级结论。 +- **有界面**（截图 / demo / 亲自跑过）⇒ 第 3 节才写得完整。 + +**判据**：七节齐全；三组必答项的行都在，取不到的写「取不到」而不是留白；第 4 节每项能力都接了「解决什么问题 / 起什么作用」；第 6 节每条强弱都写了「相对谁」。 --- ## 附：输出检查 -交付前逐条过。任一条为「否」⇒ **退回修改，⛔ 不交付**。 +交付前逐条过。任一条为「否」⇒ **退回修改，不交付**。 -- [ ] 五问（用途 / 场景 / 功能 / 作用 / 优势）各有明确落点 -- [ ] 点名参考实装已收录，且与通用竞品分成两层 -- [ ] 场景对比能描述出用户实际把事办成的过程 -- [ ] 每个功能都答了「解决什么问题 / 起什么作用」 -- [ ] 优势与不足都落到「能力 → 场景 → 用户价值」 -- [ ] 可借鉴点每一条都能追回场景 / 功能 / 优势的某一条 +**汇总对比体**（`research/1b-竞品分析.md`，§1—§10）： + +- [ ] §1 把本次目标与竞品池写死在开头，五问各有明确落点 +- [ ] 竞品池三层齐全，点名参考实装已收录并标明层级 +- [ ] §4 能说清「用户什么时候、为什么用」，并写出实际把事办成的过程 +- [ ] §5 每个维度都接了「解决什么问题 / 起什么作用」 +- [ ] §6 每条机制都接了「为什么这样设计 ⇒ 给用户什么结果」 +- [ ] §7 每条判断都写明了「相对谁、在什么场景、什么结果」 +- [ ] §8 矩阵取的是有代表性、能区分竞品的行，且看得出共识/差异/独有/短板/未解决需求 +- [ ] §9 每一条都能追回 §4 / §5 / §7 - [ ] 全文只围绕用途 / 场景 / 功能 / 作用 / 优势展开 -- [ ] 结论只落在产品层 +- [ ] §10 结论只落在产品层，并可一句话回答 §0.3 + +**独立分析体**（`research/1b-独立分析/<竞品名>.md`，§11）： + +- [ ] 第 1 节写了它属哪一层、为什么纳入（判据是用户的选择，不是名气） +- [ ] 第 2 节的四行都在（形态 / 给谁用 / 干什么用 / 证据等级），没有留白 +- [ ] 第 3 节的六行动作链都在；取不到的写了「取不到」，⛔ 没有留白、也没有拿功能名罗列顶替 +- [ ] 第 4 节每项能力都接了「解决什么问题 / 起什么作用」 +- [ ] 第 5 节每条机制都接了「为什么这样设计 ⇒ 给用户什么结果」 +- [ ] 第 6 节的每组强弱都是四行（能力表现 / 在什么场景 / 相对谁 / 对用户什么结果） +- [ ] 第 7 节三分类齐全（该借鉴 / 该避开 / 可突破） + +**两种体例齐备**： + +- [ ] 竞品池里每一个都有独立分析体（用户点名合并的按用户口径合并） +- [ ] 汇总对比体存在，且没有把独立体的内容整段抄一遍（横向铺开才算汇总体） --- ## 变更历史 -- **2026-10-07**：全文重写为《竞品分析方法论（1b · 产品视角）》（用户口径：讲用途 / 场景 / 功能 / 作用 / 优势）。 - 新增 §0 Scope 与文末《输出检查》。改版前的英文版已退役留痕于 `_superseded-competitor-analysis-英文商业版.md`（⛔ 不再引用）。 +- **2026-10-07 第四版**：独立分析体定下「必答项」写法。用户 2026-10-07 在「只定必答项 / 七节全定死 / 只定最疼两处」三个候选里选了**方案 A**（只定必答项）。改动：§11 把第 2 节（用途）四行、第 3 节（场景）六行、第 6 节（强弱）每组四行定为固定写法，取不到照写「取不到」；第 1、4、5、7 节写法自由；《输出检查》同步改成按行核。 + +- **2026-10-07 第三版**：补「两种交付体例」。起因：用户 2026-10-07 原话「**竞品分析 有独立分析也有汇总分析 都应该要用上，谁说只有一份竞品分析了**」—— 本档第二版只描述了汇总对比体（§1—§10），独立分析体一字未提，于是独立分析被写成仓库取证记录、没有产品面。本次改动：① 新增 §0.4「两种交付体例」定死职责边界与数量；② 新增 §11「独立分析体」给出七节结构与「取证范围 ↔ 可答节次」对应表；③ 《输出检查》拆成汇总对比体 / 独立分析体 / 两体例齐备三段。 + +- **2026-10-07 第二版**：按评审意见收紧机制层。① §1 把「五问」明确定为**核心模型**并给出关注点列；② §4 / §5 / §6 明确职责边界（When·Why / What / How·Why）；③ §7 判断公式补上**对比对象**（相对谁）；④ §2 把「点名参考实装」的归属**定死在竞品池第三层**，消除与章节结构的歧义；⑤ §8 补矩阵取值口径；⑥ 全文改成正向表述。 +- **2026-10-07 第一版**：全文重写为《竞品分析方法论（1b · 产品视角）》（用户口径：讲用途 / 场景 / 功能 / 作用 / 优势）。新增 §0 Scope 与文末《输出检查》。改版前的英文版已退役留痕于 `_superseded-competitor-analysis-英文商业版.md`。 diff --git a/product-planning/references/stage-requirements/SKILL.md b/product-planning/references/stage-requirements/SKILL.md index d26b2ca..6795960 100644 --- a/product-planning/references/stage-requirements/SKILL.md +++ b/product-planning/references/stage-requirements/SKILL.md @@ -148,6 +148,7 @@ description: 产品规划第②段，产品功能。只做一件事：把①段 - ⛔ **全文零视觉词**（配色 / 字体 / 间距 / 组件样式 / 动效） - **每条假设都有归宿**（三选一，无第四种）；凡依据假设的功能 / 状态流转 / 分档，条目里都带上了假设状态标注 - 本段所有「待确认 / 暂缓」条目都带齐 **复核人 / 复核时机 / 结论落点** 三字段 +- ⭐ **两份都过了「说人话」内容准则**（源技能 `humanizer` / `humanizer-zh`，门槛 ≥45/50）—— 口径见 `product-planning` 的「执行规则」内容准则条；段末报告须写明"已过内容准则，评分 X/50" ## 反面清单 @@ -167,6 +168,8 @@ description: 产品规划第②段，产品功能。只做一件事：把①段 - 越界去出原型或写说明文档（那是第③④段） - **把 `【假设】` 原样带进②段当既定事实**；或假设已被实现却从不回填状态 - **只写"暂缓"而不给复核人 / 复核时机 / 结论落点** —— 等于让这条永远挂着 +- ⛔ **两份没过「说人话」内容准则就落盘**（带 AI 腔：夸张意义 / 三段式强凑 / 破折号滥用 / 模糊归因 / 通用乐观结尾）—— 门槛 ≥45/50，见 `product-planning` 的「执行规则」内容准则条 +- ⛔ **改本技能包的规则文件、却不过「说人话」这一关**（2026-10-07 新增）：规则和产出同一把尺子 —— 口径见 `product-planning` 的「执行规则」内容准则条 ## 本段读什么、守什么 diff --git a/product-planning/references/stage-requirements/references/create-prd.md b/product-planning/references/stage-requirements/references/create-prd.md index 4379991..ce770fc 100644 --- a/product-planning/references/stage-requirements/references/create-prd.md +++ b/product-planning/references/stage-requirements/references/create-prd.md @@ -118,7 +118,7 @@ ## 四、通用要求 -- **写给人看**：短句、少术语、能读给不熟悉项目的人听懂。 +- **写给人看**：短句、少术语，能读给不熟悉项目的人听懂。**落盘前必须过「说人话」内容准则**（源技能 `humanizer` / `humanizer-zh`，门槛 ≥45/50；五条核心原则与口径见 `product-planning` 的「执行规则」内容准则条）。 - **每条都能追来源**：功能追①段场景，假设带状态标注，判据给一句话。 - **⛔ 全文零视觉词**：配色 / 字体 / 间距 / 组件样式 / 动效，一个字都不许出现。 - **保留修订记录**：改了实现必须回填条款正文，⛔ 不能只在修订记录里写。 diff --git a/session-mechanism/SKILL.md b/session-mechanism/SKILL.md index d5089c5..44e5498 100644 --- a/session-mechanism/SKILL.md +++ b/session-mechanism/SKILL.md @@ -969,7 +969,7 @@ assets/ board.html design-tokens.css **⛔ 已无必需外部依赖（2026-10-04）**：原先声明「依赖 `agent-operating-rules`」——现已把**排版核心块收进本包并定为权威** ⇒ `references/03-回复排版-核心块.md` （2026-10-06 校正：原措辞是「内联副本」，与 03 号自称「权威源」打架 ⇒ 权威声明分裂）、把 `_env.py` 的技能库识别特征改为**候选数组（首个＝本包自己）** ⇒ **本包自包含**。📌 **2026-10-07 订正**：上面末句原写「**那个技能**若同时装着，属可选增强（多了跨项目排版/去 AI 味的完整版），⛔ 不装也能跑」—— 那个技能（`agent-operating-rules`）**已于 2026-10-06 整包并入本包并删除**，⛔ **现在没有它可装**（照旧句去找必然扑空）。 -本包自带的对应物：排版 → `references/03-回复排版-核心块.md`（权威）；语气/去 AI 味 → `references/作业规矩/04-去AI味与说话方式.md`（**会话场景加固版**，含中文会话专属加固 ＋ 交付前清单 ＋ 质量评分）。📌 **通用版**（示例更全）在独立技能 `humanizer-zh`，属**可选增强，⛔ 不装也能跑**。 +本包自带的对应物：排版 → `references/03-回复排版-核心块.md`（权威）；语气/去 AI 味 → `references/作业规矩/04-去AI味与说话方式.md`（**会话场景加固版**，含中文会话专属加固 ＋ 交付前清单 ＋ 质量评分）。📌 **通用版**（示例更全）在独立技能 `humanizer-zh`，属**可选增强，⛔ 不装也能跑**。📌 🔴 **2026-10-07 按用户令把英文硬核版整包纳入本包**：`references/humanizer-en/`（原独立技能 `humanizer` 逐字搬入，6 文件；含 **55 个模式** ＋ **5 种语气档** ＋ **0–100 AI 痕迹打分** ＋ `--file` 就地改）—— 要更硬的检测/打分或要指定语气档时读它。 --- diff --git a/session-mechanism/references/humanizer-en/LICENSE b/session-mechanism/references/humanizer-en/LICENSE new file mode 100644 index 0000000..c076de0 --- /dev/null +++ b/session-mechanism/references/humanizer-en/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Adam Boudjemaa + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/session-mechanism/references/humanizer-en/README.md b/session-mechanism/references/humanizer-en/README.md new file mode 100644 index 0000000..f961739 --- /dev/null +++ b/session-mechanism/references/humanizer-en/README.md @@ -0,0 +1,108 @@ +# Humanizer + +A standalone Claude Code skill that transforms AI-generated text into natural human writing. Drop it into any plugin. No dependencies, no MCP server, no configuration. + +## What it does + +- Detects **55 AI writing patterns** (P1-P55, based on Wikipedia's "Signs of AI Writing" + 2025-2026 community research + the wider humanizer ecosystem) +- Rewrites text to sound like a specific human wrote it +- Injects authentic voice using burstiness and perplexity principles +- Three modes: scan-only, full rewrite, in-place file editing +- 5 voice profiles: casual, professional, technical, warm, blunt +- Zero dependencies. Pure Markdown. Works in every editor that reads skill files. + +## Installation + +### As a standalone skill + +```bash +mkdir -p ~/.claude/skills/humanizer +cp SKILL.md ~/.claude/skills/humanizer/ +``` + +### Inside a plugin + +Copy `SKILL.md` into your plugin's `skills/humanizer/` directory. Add to your plugin's skill registry if applicable. + +### Usage + +``` +# Full rewrite (default) +/humanizer "Your AI-sounding text goes here" + +# Scan only: report patterns without changing text +/humanizer "text" --mode detect + +# Score the AI-tell density (0-100, lower is more human) +/humanizer "text" --mode detect --score + +# Edit a file in place +/humanizer --mode edit --file src/docs/README.md + +# Specify voice +/humanizer "text" --voice casual + +# Aggressive mode + iterate to convergence (max 3 passes) +/humanizer "text" --aggressive --iterate 3 + +# Layer purpose-specific rules on top of voice +/humanizer "text" --voice warm --purpose marketing +``` + +### Voice options + +| Voice | Best for | +|---|---| +| `casual` | Blog posts, social media, informal docs | +| `professional` | Business communication, formal docs | +| `technical` | API docs, READMEs, code comments | +| `warm` | Tutorials, onboarding, support content | +| `blunt` | Internal comms, reviews, direct feedback | + +### Purpose presets (`--purpose`) + +Layered on top of voice. Add content-type rules without losing voice flavor. + +| Purpose | Effect | +|---|---| +| `essay` | No contractions, formal headings, structured arguments | +| `email` | Greetings allowed, signoff allowed, no markdown | +| `marketing` | Short paragraphs, concrete benefits, one CTA at end | +| `technical` | Code blocks preserved, precise jargon retained | +| `general` | No purpose-specific overrides (default) | + +### Brand voice file + +Drop a `humanizer-context.md` at the project root with your samples and banned phrases. Auto-loaded if present. + +## How it works + +1. **Parse**: Extracts text and flags from arguments +2. **Detect**: Scans for 55 AI patterns across 6 categories (content, language, style, communication, filler, craft/forensic) + emerging 2026 patterns +3. **Inject**: Applies voice profile, varies sentence length (burstiness), increases word unpredictability (perplexity) +4. **Verify**: Checks output against detection patterns, sentence variance, and the "who wrote this?" test +5. **Output**: Clean text with change summary + +## Pattern categories + +| Category | Patterns | Examples | +|---|---|---| +| Content | P1-P8 | Significance inflation, notability name-dropping, -ing phrases, copula avoidance | +| Language & Style | P9-P18 | Negative parallelisms, em dash overuse, bold abuse, list syndrome | +| Communication | P19-P21 | Chatbot artifacts, disclaimers, sycophancy | +| Filler & Hedging | P22-P30 | Filler phrases, hedging, generic conclusions, uniform sentence length | +| Emerging (2026) | P31-P43 | Elegant variation, citeturn markup leaks, utm_source=chatgpt URLs, treadmill effect | +| Craft & Forensic | P44-P55 | False agency, diff-anchored writing, reasoning-chain artifacts, unicode obfuscation, argument residue | + +Deep dives and provenance live in [`references/patterns.md`](references/patterns.md); the core `SKILL.md` is standalone and does not require it. + +## Credits + +Built from research across: +- [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) +- William Strunk Jr., *The Elements of Style* (1918) +- Community research from Reddit, HackerNews, and writing communities + +## License + +MIT diff --git a/session-mechanism/references/humanizer-en/SKILL.md b/session-mechanism/references/humanizer-en/SKILL.md new file mode 100644 index 0000000..574e4cd --- /dev/null +++ b/session-mechanism/references/humanizer-en/SKILL.md @@ -0,0 +1,443 @@ +--- +name: humanizer +description: Detects 55 AI writing patterns and rewrites text in five voice profiles so it reads like a specific human wrote it, with an optional 0-100 AI-tell score. Use when text sounds AI-generated or like a chatbot, when preparing a blog post, README, or LinkedIn post for publication, when auditing prose for AI tells, or when editing a Markdown file in place. Triggers on phrases like "humanize this", "make this sound less AI", "make this sound human", "remove AI tells", "does this read like ChatGPT", and "rewrite so it does not sound AI-generated". Pure Markdown, zero dependencies, no network calls. +user-invocable: true +argument-hint: '"your text" [--mode detect|rewrite|edit] [--voice casual|professional|technical|warm|blunt] [--file path/to/file.md] [--aggressive] [--iterate N] [--score] [--purpose essay|email|marketing|technical|general] [--openings N] [--ignore-code] [--ignore-quotes]' +allowed-tools: + - Read + - Write + - Edit + - Grep + - Glob + - AskUserQuestion +--- + +# Humanizer: Make Text Sound Like a Human Wrote It + +Take text that smells like a chatbot wrote it and rewrite it as a specific, opinionated human. Detects 55 AI writing patterns, scores them 0-100, applies a chosen voice profile, and varies sentence-length burstiness so the result reads as written by a person. + +## Quick reference + +**Modes** + +| Mode | What it does | +|:-----|:-------------| +| `detect` | Scan text, report patterns, output a 0-100 AI-tell score. No rewrite. | +| `rewrite` | Full transform with voice injection. Default mode. | +| `edit` | In-place file editing using the Edit tool. Minimal targeted changes. | + +**Voices** + +| Voice | Personality | Best for | +|:------|:-----------|:---------| +| `casual` | Contractions, first person, fragments | Blog posts, social media | +| `professional` | Selective contractions, dry wit | Business comms, reports | +| `technical` | Precise vocabulary, code-like clarity | API docs, READMEs | +| `warm` | "We" language, empathy, short paragraphs | Tutorials, onboarding | +| `blunt` | Shortest sentences, no hedging, active voice | Internal comms, reviews | + +**Pattern catalog (55 total)** + +| Category | Count | IDs | +|:---------|:------|:----| +| Content | 8 | P1 to P8 | +| Language & Style | 10 | P9 to P18 | +| Communication | 3 | P19 to P21 | +| Filler & Hedging | 9 | P22 to P30 | +| Emerging | 13 | P31 to P43 | +| Craft & Forensic | 12 | P44 to P55 | + +**Flags** + +| Flag | Effect | +|:-----|:-------| +| `--score` | Prepend a `[Score: NN/100]` AI-tell density header | +| `--iterate N` | Loop detect, rewrite, detect until convergence (max N=3) | +| `--aggressive` | Heavier rewrite, shorter sentences, more personality | +| `--purpose` | Layer `essay`, `email`, `marketing`, `technical`, or `general` rules | +| `--openings N` | Generate N maximally-different opening hooks, surface the strongest | +| `--ignore-code` | Mask fenced code blocks before detect/score (do not flag inside them) | +| `--ignore-quotes` | Mask blockquotes before detect/score (do not rewrite quoted text) | + +Deep dives and full trigger lists for every pattern live in [`references/patterns.md`](references/patterns.md), loaded on demand, along with a before/after pair for each of the 34 patterns that benefits from one. A provisional native-Chinese appendix is in [`references/patterns.zh.md`](references/patterns.zh.md). This file is standalone and needs neither. + +## When to use this skill + +- The text reads like a chatbot wrote it (uniform sentence length, no specifics, "delves into" energy) +- You're publishing a blog post, README, or LinkedIn note and want a real human voice +- You're auditing an existing document for AI tells before shipping +- You want a 0-100 score that quantifies how AI-flagged the text reads right now +- You want the skill to edit a Markdown file in place rather than print a rewrite to chat + +Auto-loads `humanizer-context.md` from the project root if present. Use that file for brand samples and banned phrases. + +## Guardrails: what NOT to flag, and what to preserve + +Read this before you change a single word. A ruthless editor who over-edits is worse than no editor: it launders a real person's voice into the same flat prose it claims to fix. Restraint is part of the job. + +### What NOT to flag (false positives) + +- **Flag clusters, not isolated tells.** One em dash, one "crucial", one three-item list is how humans write too. Flag a pattern only when several co-occur in the same passage. +- **Perfect grammar is not AI.** Clean spelling, correct punctuation, and a consistent Oxford comma are signs of a careful writer or a copy editor, not proof of a machine. +- **A single em dash, curly quote, or tidy sentence alone means nothing.** These matter only as part of a cluster. +- **Never rewrite watched phrases inside quotes, block quotes, titles, headings, code, or examples.** If "delve" appears in a direct quotation, a book title, a variable name, or a pasted sample of AI text the author is critiquing, leave it exactly as written. Rewriting quoted or code content changes meaning and breaks references. When `--ignore-code` or `--ignore-quotes` is set, mask those spans before you even scan. +- **Jargon and repetition can be correct.** Technical writing repeats the exact term on purpose; do not "vary" `useEffect` into "the effect hook" for elegance. Reference and encyclopedic prose is supposed to be plain and neutral; that plainness is the human voice there, not a defect. +- **Short samples are unreliable.** Under about 40 words there is not enough signal to score. Say so instead of guessing. +- **Consistent, formulaic structure alone is not proof of AI.** Autistic and ADHD writers often produce precise, low-variance, formulaic-consistent prose as their natural voice, and burstiness-based heuristics cannot tell "naturally low-variance human style" from "machine-generated low-variance." Don't let low sentence-length variation alone raise the score; look for the vocabulary and content tells too before flagging. +- **Formal or non-native-English prose is not proof of AI either.** Detectors trained mostly on native-English text disproportionately flag non-native English writers (Liang et al., [arXiv:2304.02819](https://arxiv.org/abs/2304.02819)); apply the same caution here. A stiff, textbook-formal register can be a second-language writer's honest voice, not a chatbot's. + +### Signs of human writing (preserve these) + +When you see these, protect them. They are hard for a model to fake and they are the whole point. + +- **Hard-to-fabricate specifics:** real dates, dollar amounts, file paths, proper names, measured numbers ("dropped from 900ms to 40ms"). +- **Mixed or unresolved feelings:** "I still can't decide if I love it," admitted uncertainty, a stated bias. +- **Lived, sensory, first-person detail:** the 2am debugging session, the coffee machine no one can work. +- **Era-bound or in-group voice:** slang, references, and jokes tied to a time and community. +- **Deliberate imperfection:** a fragment, a tangent, a self-correction, an ending that just stops. +- **Content written or edited before late 2022:** it predates the tools you are looking for. Do not "fix" it into sounding newer. + +If a passage is already carrying a pulse, the correct edit is often no edit. + +## Operating principles + +You are a ruthless editor who despises AI slop. Take text that smells like a chatbot and rewrite it as a specific, opinionated human. Don't just remove bad patterns. Replace them with something that has a pulse. + +North star: **LLMs regress to the statistical mean. Humans are weird, specific, and inconsistent. Write like a human.** + +The fundamental AI tell: text that emerges from nowhere, addressed to no one, with no stake in its claims. Human writing reveals a mind behind it. If the reader can't picture a specific person writing this, it's not done. + +**No fabrication.** A rewrite may sharpen, cut, and restructure, but it may not invent facts, names, dates, numbers, or quotes that are not in the source. The Concretizer pass (Step 3) replaces vague abstractions with specifics that are already implied or stated in the source; when a genuinely concrete detail isn't available there, flag the gap or ask the author for it, never invent one. + +Arguments received: $ARGUMENTS + +--- + +## Step 1: Parse Arguments + +Extract from `$ARGUMENTS`: + +- **Text**: The content to humanize. Everything not part of a flag. If no text and no `--file`, prompt: "Paste the text you want me to humanize, or pass `--file path/to/file.md`." +- **--mode**: `detect` (scan and report, no changes), `rewrite` (full rewrite, the default), or `edit` (read `--file` and apply in-place changes with the Edit tool). +- **--voice**: One of `casual`, `professional`, `technical`, `warm`, `blunt`. Default: infer from input text register. +- **--file**: Path to a file to humanize. If provided, read the file as input. With `--mode edit`, apply changes in place. +- **--aggressive**: Rewrite more heavily (shorter sentences, more personality, kill all hedging). Default: balanced. +- **--iterate N**: Run detect, rewrite, detect up to N times (N <= 3). Stop early when the report finds zero patterns. Default: 1. +- **--score**: Prepend a `[Score: NN/100]` header (0 = pristine human, 100 = maximum AI smell) using the Step 5 rubric. Works in all modes. +- **--purpose**: Layer content-type rules on top of `--voice`: `essay` (no contractions, formal headings, structured arguments), `email` (greetings and signoff allowed, no markdown), `marketing` (short paragraphs, concrete benefits, one CTA at the end), `technical` (code blocks preserved, precise jargon, numbers over adjectives), or `general` (no override, the default). +- **--openings N**: Generate N maximally-different opening hooks and surface the strongest (see Step 3, Opening tournament). Default: off. +- **--ignore-code**: Mask fenced code blocks (triple-backtick and indented) before detection and scoring, so sample code does not inflate the score or get rewritten. Default: off. +- **--ignore-quotes**: Mask Markdown block quotes (`>` lines) before detection and scoring, so pasted AI examples the author is critiquing do not count against them. Default: off. + +**Auto-load brand context.** Before parsing further, check for `humanizer-context.md` in the current working directory using the Read tool. If it exists, load it as additional voice guidance (brand samples, banned phrases, preferred terms), a personal extension of the `--voice` profile. If it doesn't exist, proceed without warning; this is opt-in. + +Store parsed values. Proceed to Step 2. + +--- + +## Step 2: Detect AI Patterns + +Scan the input text for all 55 patterns below. Track each match with its location and category. Each entry is a compact trigger summary; the full trigger lists, the "what's happening" notes, and before/after examples live in [`references/patterns.md`](references/patterns.md). + +### CONTENT PATTERNS + +**P1: Significance Inflation.** Puffing up importance by claiming arbitrary facts represent broader trends. Fix: state what the thing is or does; cut the "represents" commentary. Triggers: stands/serves as, is a testament/reminder, pivotal/vital/crucial moment, underscores importance, marks a shift, evolving landscape, indelible mark, deeply rooted. + +**P2: Notability Name-Dropping.** Proving importance by listing publications instead of what they said. Fix: pick one source and say what it reported, or cut it. Triggers: featured in, profiled in, independent coverage, active social media presence, written by a leading expert. + +**P3: Superficial -ing Phrases.** Present-participle clauses tacked on to fake depth. Fix: delete the -ing clause, or promote its real information to a sourced sentence. Triggers: highlighting, underscoring, emphasizing, ensuring, reflecting, symbolizing, fostering, showcasing. + +**P4: Promotional Language.** Travel-brochure adjectives instead of facts. Fix: replace adjectives with what specifically makes it notable. Triggers: nestled, in the heart of, vibrant, breathtaking, must-visit, cutting-edge, seamless, robust, world-class, state-of-the-art, rich (figurative), renowned. + +**P5: Vague Attributions.** Phantom authorities lending weight to opinions. Fix: name the specific expert, paper, or report, or delete the claim. Triggers: experts argue, research suggests, observers have cited, several sources, it is widely believed, industry reports. + +**P6: Formulaic Challenges Sections.** "Despite [good thing], [vague problems]. Despite these, [platitude]." Fix: state specific problems with dates and data, or cut the section. Triggers: despite its, faces several challenges, challenges and legacy, future outlook, looking ahead, the road ahead. + +**P7: AI Vocabulary Words.** A cluster of words that appear 3-10x more often in post-2023 text. Fix: cut or replace with plain language (see the tiered list below). Triggers: delve, leverage, multifaceted, tapestry, testament, underscore, interplay, realm, pivotal, crucial, vibrant, foster, garner, bolster, notably, moreover, furthermore, "it's worth noting", "in today's landscape". + +**P8: Copula Avoidance.** Elaborate verbs replacing simple "is" and "has". Fix: use is, are, has, was; simple copulas are clear, not boring. Triggers: serves as, stands as, marks, represents, boasts, features, offers (when is/are/has works). + +### LANGUAGE & STYLE PATTERNS + +**P9: Negative Parallelisms.** Once is fine, twice is a pattern, three times is a chatbot. Fix: state the point directly without the theatrical build-up. Triggers: "not only X but Y", "it's not just X, it's Y", "it's not merely X, it's Y". + +**P10: Rule of Three.** Forced triads to sound authoritative. Fix: use the natural number; two and four are underrated. Triggers: three-item lists of abstract nouns ("innovation, inspiration, and industry insights"). + +**P11: Synonym Cycling (Elegant Variation).** Repetition penalty makes the model swap "protagonist" for "main character" for "central figure". Fix: pick one term and repeat it. Triggers: the same entity named differently in consecutive sentences without reason. + +**P12: False Ranges.** "From X to Y" where X and Y are not on a real spectrum. Fix: name the actual items. Triggers: forced "from ... to ..." spans. + +**P13: Em Dash Ban.** Em-dash overuse mimicking punchy editorial writing; the single most common formatting tell. Fix: replace with commas, colons, or hyphens. Triggers: any em dash (U+2014). Zero tolerance. + +*Related, lower-confidence note (not zero tolerance like P13 above):* semicolons or colons in 3+ consecutive sentences are an emerging, anecdotally-reported tell in the same family (LOW-MEDIUM confidence, community-reported, no controlled study behind it yet). Never flag a lone semicolon or colon; flag only a cluster, and treat even that as a soft signal. + +**P14: Boldface/Formatting Overuse.** Mechanical emphasis and decoration standing in for clear writing. Fix: use bold sparingly, once per section. Triggers: bold on every other phrase, emoji-decorated or emoji-bulleted headers, skipped heading levels, a horizontal rule before every heading, tables where prose reads better, Markdown in non-Markdown contexts. + +**P15: Structured List Syndrome.** Bullets doing the job of prose. Fix: write flowing paragraphs when the content flows. Triggers: bullets starting `**Bold Header:** description`, excessive bullets for information that reads as prose. + +**P16: Title Case in Headings.** Fix: use sentence case. Triggers: "Strategic Negotiations And Global Partnerships" instead of "Strategic negotiations and global partnerships". + +**P17: Curly Quotes and Typographic Tells.** ChatGPT uses curly quotes; Claude uses straight quotes. Fix: match the author's existing typography. Triggers: smart quotes instead of straight quotes, a rigidly consistent Oxford comma. + +**P18: Formal Register Overuse.** Bureaucratic register where the audience expects plain talk. Fix: drop to the register the context calls for. Triggers: "it should be noted that", "it is essential to", "in the context of", "the implementation of". + +### COMMUNICATION PATTERNS + +**P19: Chatbot Artifacts.** Fix: delete the assistant chatter. Triggers: "I hope this helps", "Of course!", "Certainly!", "You're absolutely right!", "Would you like me to", "Let me know if", "Here is a". + +**P20: Knowledge-Cutoff Disclaimers.** Fix: state the fact or cut the hedge. Triggers: "As of [date]", "up to my last training update", "while specific details are limited", "based on available information". + +**P21: Sycophantic Tone.** Fix: answer without the flattery. Triggers: "Great question!", "That's an excellent point!", "You raise a very important issue", "Absolutely!". + +### FILLER & HEDGING PATTERNS + +**P22: Filler Phrases.** Wordy connectors that add nothing. Fix: delete or shorten. Triggers: "in order to", "due to the fact that", "at this point in time", "it's worth noting", "when it comes to", "in connection with", "connected with/to", "in association with", "associated with". + +**P23: Excessive Hedging.** Stacked qualifiers. Fix: commit, or state the one real uncertainty. Triggers: "could potentially possibly", "it might perhaps be argued". + +**P24: Generic Positive Conclusions.** Fix: end on a specific fact or open question. Triggers: "the future looks bright", "exciting times lie ahead", "poised for growth", "a step in the right direction". + +**P25: Hallucination Markers.** Fix: verify or cut. Triggers: overly specific dates or numbers that feel fabricated, attribution to sources that don't exist, confident claims about obscure facts without citations. + +**P26: Perfect/Error Alternation.** Fix: hold one quality level throughout. Triggers: syntactically perfect prose alternating with basic errors, suggesting a partial human edit of AI output. + +**P27: Question-Format Section Titles.** Fix: use statement headings in long-form content. Triggers: "What makes X unique?", "Why is Y important?", "How does Z work?". + +**P28: Markdown Bleeding.** Fix: strip Markdown where it won't render. Triggers: `**bold**` in emails, social posts, or Word docs. + +**P29: The "Comprehensive Overview" Opening.** Fix: start with the actual content. Triggers: "this comprehensive guide/overview covers", "in this article, we will explore", "let's dive into". + +**P30: Uniform Sentence Length.** Statistically average sentences with no variation. Fix: mix short punches with long flowing thoughts (see the Burstiness Principle). Triggers: every sentence 15-25 words, no short or long outliers. + +### EMERGING PATTERNS + +**P31: Elegant Variation (Noun-Phrase Cycling).** Whole noun phrases swapped for one entity (distinct from P11 word-level). Fix: pick the clearest term and repeat it. Triggers: same referent named 3+ ways in a paragraph ("the artist", "the visionary creator", "the non-conformist painter"). + +**P32: Collaborative Communication Leaking.** Chat framing pasted into published content (distinct from P19 identity disclosure). Fix: delete the meta-commentary and start with the content. Triggers: "in this article, we will explore", "let me walk you through", "here's what you need to know". + +**P33: Placeholder Text / Mad Libs.** Fill-in-the-blank templates left uncompleted. Fix: fill it in or delete it. Triggers: `[Your Name]`, `[INSERT SOURCE URL]`, `2025-XX-XX`, square-bracketed instructions. + +**P34: Chatbot Reference Markup Leaking.** Internal citation tokens preserved on copy-paste, now across five providers. Fix: delete the markup; add a real reference if it mattered. Triggers: ChatGPT (`citeturn0search0`, `contentReference[oaicite:0]{index=0}`, `oai_citation`), Gemini (`[cite: 1]`, `[span_1](start_span)`), Grok (`grok_card`, `grok_render_citation_card_json`), DeepSeek (lenticular brackets, dagger symbols), Perplexity (`attached_file`, `ppl-ai-file-upload`), RAG `attribution`/`attributableIndex` tags, orphan footnote characters. + +**P35: UTM Source Parameters from AI Tools.** Fix: strip UTM parameters from URLs. Triggers: `utm_source=chatgpt.com`, `utm_source=openai`, `utm_source=copilot.com`, `referrer=grok.com`. + +**P36: Sudden Style/Register Shift.** AI-written sections carry a different voice and error profile than human ones. Fix: hold one register; rewrite AI sections to match the author. Triggers: formal English beside casual text with errors, spelling that switches mid-piece. + +**P37: Overattribution / Source-Listing as Content.** Treating a source list as proof (distinct from P2 famous-name dropping). Fix: pick one source and say what it reported. Triggers: "featured in [A], [B], and other outlets", "has been cited in", "maintains an active social media presence". + +**P38: Paragraph-Reshuffling Immunity.** Parallel self-contained blocks instead of an unfolding argument. Test: can you swap paragraphs 2 and 4 without breaking it? Fix: make each paragraph depend on the last; merge or cut interchangeable ones. Triggers: mini-theses that never build on each other. + +**P39: Paragraph-Closing "Whether" Summaries.** SEO-style recaps ending paragraphs and sections. Fix: cut the closing recap; end on the strongest specific point. Triggers: paragraphs ending "Whether you...", "Whether it's...", and section-enders "In summary,", "To sum up,", "Overall,". + +**P40: Symbolic Gloss / Meaning-Telling.** Narrating the meaning of a fact instead of trusting it (distinct from P1 framing). Fix: state the fact and let the reader interpret. Triggers: "represents", "symbolizes", "speaks to", "embodies", "reflects broader" applied to mundane things. + +**P41: Infomercial Engagement Hooks.** Fake dramatic pauses from social-optimized writing. Fix: delete the hook line; let the next sentence make its point. Triggers: "The catch?", "The kicker?", "Here's the thing.", "The brutal truth?", "Sound familiar?". + +**P42: Erratic Inline Bolding.** Patternless bold spans with no shared rule (distinct from P14 systematic overuse). Fix: strip inline bold except glossary terms and UI labels. Triggers: 1-4 word bold spans mid-paragraph with no shared category. + +**P43: The Treadmill Effect (Low Information Density).** Long passages that restate one idea. Fix: apply the "what's actually new here?" test per sentence; delete rephrasings. Triggers: mid-paragraph "In other words,", "Put simply,", "Essentially,", "That is to say,". + +### CRAFT AND FORENSIC PATTERNS + +**P44: False Agency.** Inanimate things performing human actions. Fix: name the human actor or address the reader as "you". Triggers: "the data tells us", "the market rewards", "the decision emerges", abstractions as the subject of a willed verb. + +**P45: Narrator-from-a-Distance.** Detached third person floating above the scene. Fix: put the reader in the room; "you" beats "people". Triggers: "nobody designed this", "people tend to", "one might say", "there is a sense that". + +**P46: Diff-Anchored Writing.** Docs that narrate a change instead of the current state. Fix: describe the thing as it is; delete the edit history. Triggers: "was added to", "now uses", "has been updated to", "replaces the old", "previously". + +**P47: Hyphenated-Pair Overuse.** Uniform hyphenation even after the noun. Fix: hyphenate a compound modifier before a noun; drop the hyphen when it follows the verb. Triggers: "the report is high-quality", "the results are well-documented", "the API is easy-to-use". + +**P48: Aphorism Formulas.** Fake-profound templates standing in for a concrete claim. Fix: cut the aphorism; state the actual point. Triggers: "X is the new Y", "the currency of", "not a X but a Y", "X is where Y meets Z". + +**P49: Fragmented Headers.** A heading followed by one line restating it. Fix: cut the restating line or replace it with a real fact. Triggers: H2/H3 immediately followed by one sentence echoing the heading, or "This section covers X." + +**P50: Passive / Subjectless Constructions.** Agentless passive that hides who acts. Fix: name the actor and use active voice. Triggers: "no configuration is needed", "the results are preserved automatically", "it is recommended that", "changes were made". + +**P51: Reasoning-Chain Artifacts.** Chain-of-thought scaffolding leaking into the final text. Fix: delete the scaffolding; keep the conclusion in the author's voice. Triggers: "Let me think", "Step 1:", "Breaking this down", "First, I'll", numbered thinking meant to stay internal. + +**P52: Unicode Obfuscation.** Invisible or look-alike characters inserted to dodge detectors. Fix: strip zero-width and control characters, normalize to plain NFC text. Triggers: zero-width space (U+200B), zero-width joiner (U+200D), soft hyphen (U+00AD), dense non-breaking spaces, Cyrillic or Greek homoglyphs for Latin letters. + +**P53: Hedged-Enumeration Openers.** Announcing a vague list instead of committing to an answer. Fix: give the specific answer first; drop the throat-clearing. Triggers: "There are several ways to", "There are a few things to consider", "In general,", "It is generally a good idea to", "Generally speaking,". + +**P54: Argument Residue.** Rebutting an objection nobody raised, a trace of an internal draft the model discarded but never fully deleted. Fix: cut the phantom rebuttal; state the position directly, or address a real, named objection if one actually exists in the piece. Triggers: "While some might argue...", "It would be easy to dismiss this as...", "One might object that... but", any sentence structured as a rebuttal with no corresponding claim anywhere else in the piece. + +**P55: Leftover Hedge Debris.** A qualifier that made sense mid-draft, before the writer had committed to a claim, but that a real revision pass would have deleted once the claim solidified. Fix: reread every hedge next to its sentence; delete any hedge whose caution no longer matches the sentence's actual confidence. Triggers: "to some extent", "in some ways", "to a certain degree", "arguably" sitting beside an otherwise flatly confident claim; a hedge and its claim that pull in opposite directions. + +### Tiered-confidence vocabulary (refines P7) + +Not every AI word is equally damning. Flag by tier to cut false positives. Tier 1 itself splits in two: evidence-grade words that are close to definitive on their own, and wordiness-grade words that are legitimate but often a lazy choice, and should not by themselves push a score toward "AI." + +- **Tier 1A, evidence-grade, always flag:** delve, tapestry (figurative), testament (figurative), multifaceted, realm, interplay, "in today's ... landscape". These almost never survive in unedited human prose; a single hit here already carries real weight. +- **Tier 1B, wordiness-grade, flag but weight lower:** underscore (verb), leverage (verb), "it's worth noting", "it's important to note". A careful human might reach for these too, just usually as a lazier choice than the plain alternative. Flag them, but a Tier 1B hit alone should never carry the same weight as a Tier 1A hit: a wordiness fix is not proof of AI authorship. +- **Tier 2, flag in density (2+ in a paragraph):** crucial, pivotal, vibrant, robust, seamless, foster, enhance, showcase, notably, moreover, furthermore, garner, bolster, "align with", utilize. One is fine; a cluster is a tell. +- **Tier 3, context only (never flag alone):** key, important, significant, various, effective, valuable, powerful, essential. Ordinary words. Flag only when they cluster with Tier 1 or 2 hits, or when they stand in for a specific fact. + +Rule: a lone Tier 1B, 2, or 3 word is not evidence. A Tier 1A hit, or a cluster across tiers, is. + +### The Burstiness Principle + +AI detectors measure "burstiness": sentence length variance. Human writing has HIGH burstiness. AI has LOW. + +**Target these sentence length patterns:** +- Mix short (3-8 words), medium (12-20 words), and long (25-40 words) in every paragraph +- Never have 3+ consecutive sentences of similar length +- Use fragments. They work. Really. +- One-word sentences? Occasionally. +- Let a sentence run long when the thought needs room to breathe, winding through qualifications before landing + +### The Perplexity Principle + +AI detectors also measure "perplexity": how predictable each word is. AI text has LOW perplexity. Human text has HIGHER (more surprising word choices). + +**Increase perplexity naturally by:** +- Choosing the second or third word that comes to mind, not the first (the most statistically likely one AI would pick) +- Using domain-specific jargon or slang appropriate to the audience +- Making unexpected analogies from personal experience +- Occasionally using informal transitions ("Anyway,", "So here's the thing:", "Look,", "Thing is,") + +--- + +## Step 3: Rewrite Craft + +These turn a clean rewrite into a human one. Pull only what the piece needs; on neutral reference or legal text, most of them stay holstered. + +**Voice Read (do this before rewriting).** Emit one line naming the piece and its reader before you touch a word: "Reading this as: for , register ." It anchors every choice that follows. Skip it only in `edit` mode on a file that already has a settled voice. + +**Anti-Default Discipline.** Name the reflexive moves and refuse them: the automatic rule-of-three, the tidy summary sentence closing every paragraph, the balanced both-sides hedge, the "In conclusion" wrap, the opening that restates the prompt. Injecting personality into text that wants to stay plain is its own kind of slop. + +**Position engine (give it teeth).** The deepest AI tell is text with no stake in its claims. For any opinion or argument, force one defensible strong stance and a named target. An opinion no one could argue against is not an opinion. On neutral, technical, or reference text, skip this: there the stance is the facts. + +**Concretizer pass.** Sweep the draft and turn every abstraction into an image, analogy, or concrete action. "The process is complex" becomes the actual steps. "Improves performance" becomes "cuts p99 latency from 900ms to 40ms". A sentence that could describe anything describes nothing. + +**Opening tournament (`--openings N`).** When set, generate N maximally-different opening hooks (for example: a blunt claim, a concrete scene, a question you then answer), surface the strongest, and say in one line why it won. The first three lines carry the piece. + +### Voice Profiles + +Apply based on `--voice` flag (or infer from input): + +- **casual:** contractions always; first person where it fits; informal transitions ("So", "Anyway", "Look"); occasional parenthetical asides; sentence fragments for emphasis; "And"/"But" starters allowed. +- **professional:** selective contractions; third person by default, first person for opinions; clean transitions; dry wit over jokes; concrete examples; short paragraphs (3-5 sentences). +- **technical:** precise vocabulary, the exact term over a simpler one; one point per sentence; "Note:" and "Important:" sparingly; deadpan observations allowed; concrete numbers over vague quantities; no metaphors unless they genuinely clarify. +- **warm:** contractions always; "we" and "our" to build shared experience; acknowledge difficulty ("this part is tricky"); encouragement without sycophancy; shorter paragraphs, more whitespace. +- **blunt:** shortest possible sentences; no hedging; "X is bad. Here's why." energy; strong opinions stated as facts; cut all pleasantries; active voice only. + +### Soul Injection Techniques + +These make the difference between "clean" and "human": + +1. **Have actual opinions.** React, don't just report. "This API design is frustrating" beats "The API has certain limitations." +2. **Calibrate certainty on a spectrum, don't just hedge.** Match word choice to real belief strength. High conviction: "clearly", "no question". Medium: "I think", "in my experience". Genuine doubt: "I'm not sure, but". A real mind moves across this range; AI parks in flat medium confidence. Never stack hedges. +3. **Use specific sensory/experiential details.** Not "the process is complex" but "debugging this at 2am with a cold coffee and a stack trace that makes no sense." +4. **Reference shared human experiences.** "You know that feeling when..." creates connection. +5. **Allow tangents and asides.** A brief digression signals a thinking mind. +6. **Vary paragraph length dramatically.** Four sentences, then one line. Like this. +7. **Use the "imperfect start" technique.** Start mid-thought: "So I was looking at the logs and..." +8. **Break parallel structure occasionally.** Three items with the same grammar, then make the fourth different. +9. **Use callbacks.** Reference something mentioned earlier. "Remember that API I called frustrating? It gets worse." +10. **Self-correct.** "The system handles auth... well, authentication and authorization are separate, but you get the idea." A small correction signals real-time thinking. +11. **End without wrapping up.** Not every piece needs a neat conclusion. Sometimes just stop. + +--- + +## Step 4: Execute Based on Mode + +**Masking first (all modes).** If `--ignore-code` is set, replace fenced code blocks (triple-backtick and indented) with a placeholder before scanning, so their contents never trigger a pattern or get rewritten. If `--ignore-quotes` is set, do the same for Markdown block quotes. Restore the masked spans verbatim in the output. + +### Mode: `detect` + +1. Scan input text for all 55 patterns. +2. For each match, record the pattern ID and name, the offending text (quoted), why it triggers, and a suggested fix. +3. Output a report: + +``` +## AI Pattern Report + +**Patterns found:** 12 +**Severity:** HIGH (8+ patterns = heavy AI smell) + +| # | Pattern | Text | Fix | +|---|---------|------|-----| +| P3 | Superficial -ing | "ensuring reliability and fostering growth" | Delete or expand with source | +| P7 | AI Vocabulary | "Additionally", "crucial", "landscape" | Replace: "Also", "important", [delete] | +| P13 | Em Dash Overuse | 4 em dashes in 2 paragraphs | Replace 3 with commas | + +**Burstiness:** LOW (sentence lengths 18, 19, 17, 20, 18; very uniform) +**Estimated AI probability:** HIGH + +### Recommendations +[Prioritized list of changes with the most impact] +``` + +### Mode: `rewrite` + +1. Run detection (Step 2) internally; don't output the report. +2. Apply fixes for every detected pattern. +3. Apply voice injection (Step 3) based on `--voice`. +4. Verify the rewrite: no remaining AI blacklist words unless genuinely needed, zero em dashes (U+2014), sentence-length variance > 30%, no more than 2 consecutive sentences of similar structure, no orphaned formatting. +5. Output the rewritten text with a brief change summary: + +``` +[Rewritten text here] + +--- +Changes: Removed 12 AI patterns (3x significance inflation, 2x -ing phrases, 4x AI vocabulary, 2x filler, 1x generic conclusion). Injected casual voice. Varied sentence length from 4 to 38 words. Added 2 specific examples to replace vague claims. +``` + +### Mode: `edit` + +1. Verify `--file` was provided; read the file with the Read tool. +2. **Refuse non-prose targets.** If the file is source code, configuration, or structured data (extensions like `.js`, `.ts`, `.py`, `.go`, `.rs`, `.json`, `.yaml`, `.yml`, `.toml`, `.env`, `.csv`, `.lock`, or content that plainly isn't prose even if the extension is ambiguous), stop and say so: "This looks like code or structured data, not prose. Humanizer edits prose, and rewriting this could break it." Do not edit. Markdown, plain text, and other prose formats proceed to step 3. +3. Run detection on the contents. +4. If 0 patterns found: "This file reads clean. No AI patterns detected." +5. If patterns found: apply fixes with the Edit tool (targeted edits, not full rewrites), preserve the author's already-human voice, then re-read and verify patterns are resolved. +6. Output a summary of edits made. + +--- + +## Step 5: Final Quality Check + +Before presenting output, verify: + +1. **Read it aloud mentally.** Does it sound like a person talking, or a press release? +2. **Check the opening.** If it starts with a boring overview sentence, rewrite to hook. +3. **Check the ending.** If it wraps up with a generic positive, cut or replace with a specific. +4. **Count the "delves."** Kill any surviving AI blacklist words. +5. **Zero em dashes.** Search for U+2014; replace with commas, colons, or hyphens. +6. **Sentence length audit.** If you see 3+ sentences of similar length in a row, vary them. +7. **The "who wrote this?" test.** If someone read this, could they picture a specific person behind it? If it could have been written by anyone (or anything), it needs more voice. + +### Draft, self-audit, final (cheap quality pass, distinct from `--iterate`) + +After the first rewrite, ask one question of your own draft: "What still makes this read as AI?" Answer honestly in two or three bullets, then do one corrective pass targeting exactly those. This metacognitive step is cheaper than a full `--iterate` detect loop and catches the tells a checklist misses. It complements `--iterate`, it does not replace it. + +### Scoring rubric (used when `--score` is set) + +Compute a 0-100 AI-tell density score. Lower is more human. + +| Range | Verdict | What it means | +|:------|:--------|:--------------| +| 0-20 | Pristine | Reads like a specific human wrote it. No detector should flag it. | +| 21-40 | Mostly human | One or two minor tells, easy to clean. | +| 41-60 | Mixed | Half-AI half-human; partial editing likely. | +| 61-80 | AI-leaning | Multiple structural tells; detectors will probably catch it. | +| 81-100 | Pure AI smell | Wholesale chatbot output with no editing. | + +Compute as: `score = 4 × patterns_hit + 25 × (1 - burstiness_normalized) + 15 × (vocabulary_blacklist_ratio)`, clamped to 0-100. Show the score on the first line of output before the rewrite. + +A model grading its own output in the same session tends to inflate the result. Treat `--score` as a signal, not a verdict: the real gate is an independent pass or a human reader. For a computed, deterministic version of these metrics (burstiness, type-token ratio, sentence-length CoV, trigram repetition, Flesch-Kincaid) plus a CI quality-gate, see the optional `cli/` tool in the repo. The skill core here needs none of it. + +### Iterate handling (used when `--iterate N` is set) + +After producing the rewrite, re-run Step 2 (Detect) on the output. If patterns_hit > 0 AND iteration_count < N, recurse with the rewritten text as the new input. Stop when patterns_hit == 0 OR iteration_count == N. In the final change summary, note how many iterations ran (e.g., "Converged in 2 iterations"). + +Worked before/after examples for technical docs, blog posts, and LinkedIn are in [`references/patterns.md`](references/patterns.md). + +--- + +## Always-On Mode + +To make an agent write clean by default, not only when you invoke `/humanizer`, bake the core rules into its standing instructions. Ready copy-paste blocks for `CLAUDE.md`, `SOUL.md`, a system prompt, and ChatGPT custom instructions live in [`references/always-on-templates.md`](references/always-on-templates.md). This keeps the skill on-demand while giving power users an always-on option. + +--- + +*Write like a human. Be weird, specific, inconsistent.* diff --git a/session-mechanism/references/humanizer-en/references/always-on-templates.md b/session-mechanism/references/humanizer-en/references/always-on-templates.md new file mode 100644 index 0000000..c5502b0 --- /dev/null +++ b/session-mechanism/references/humanizer-en/references/always-on-templates.md @@ -0,0 +1,70 @@ +# Always-On Mode templates + +Copy one of these blocks into your agent's standing instructions so it writes clean by default, not only when you run `/humanizer`. Each is self-contained: it bakes in the core anti-slop rules without needing the full skill loaded. + +Pick the surface that matches your tool. The rules are identical; only the wrapper changes. + +--- + +## For `CLAUDE.md` or `AGENTS.md` (project or global) + +```markdown +## Writing rules (always on) + +When you write prose (docs, comments, messages, commit bodies, PR descriptions): + +- No em dashes. Use commas, colons, or hyphens. +- Vary sentence length. Follow a long sentence with a short one. Fragments are fine. +- Cut AI vocabulary: delve, leverage, tapestry, testament, underscore, multifaceted, + realm, seamless, robust, "it's worth noting", "in today's landscape". +- No rule-of-three by reflex, no tidy summary sentence closing every paragraph, + no "In conclusion" wrap. +- State facts, not their significance. Delete "this represents / underscores / highlights". +- Prefer active voice and a named actor over agentless passive. +- Have a stake: for any opinion, take one defensible stance instead of both-sides mush. +- Replace abstractions with concrete specifics: numbers, file paths, real examples. +``` + +--- + +## For a `SOUL.md` or persona file + +```markdown +# Voice + +I write like a specific person, not a committee. Short sentences next to long ones. +Concrete over abstract. I take positions and name what I disagree with. I skip the +throat-clearing openers ("There are several ways to...") and the neat conclusions. +No em dashes, no "delve", no "leverage", no rule-of-three on autopilot. If a sentence +could describe anything, I rewrite it until it describes one thing. +``` + +--- + +## For a system prompt (API or custom assistant) + +``` +Write in a human voice. Rules: vary sentence length (mix 3-word and 30-word sentences); +no em dashes; avoid AI-vocabulary (delve, leverage, tapestry, testament, seamless, +robust, multifaceted, "it's worth noting"); no reflexive rule-of-three; no summary +sentence at the end of every paragraph; use active voice with a named actor; take a +defensible position instead of hedging; replace abstractions with concrete numbers, +names, and examples. Never rewrite text inside quotes or code blocks. +``` + +--- + +## For ChatGPT Custom Instructions ("How would you like ChatGPT to respond?") + +``` +Write like a real person, not a chatbot. Vary sentence length a lot. No em dashes. +Don't use words like delve, leverage, tapestry, testament, seamless, robust, or +"it's worth noting". Don't group things in threes by habit. Don't end every paragraph +with a summary line. Take a clear position instead of listing pros and cons. Use +concrete specifics (numbers, names, examples) instead of abstract claims. Keep code +and quoted text exactly as written. +``` + +--- + +These templates cover the highest-signal rules only. For the full 55-pattern catalog, voice profiles, and scoring, run the `/humanizer` skill on demand. diff --git a/session-mechanism/references/humanizer-en/references/patterns.md b/session-mechanism/references/humanizer-en/references/patterns.md new file mode 100644 index 0000000..5a07808 --- /dev/null +++ b/session-mechanism/references/humanizer-en/references/patterns.md @@ -0,0 +1,302 @@ +# Pattern deep dives and provenance + +Loaded on demand. The core `SKILL.md` is standalone and does not need this file. This is the depth behind the compact catalog: the "what's happening" notes, the full trigger lists, a before/after pair for each pattern that benefits from one, and the sources behind the 2026 emerging set (P31-P43). + +The core catalog (P1-P30) is derived mostly from [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing). + +## Contents + +- [The craft and forensic set (P44-P55)](#the-craft-and-forensic-set-p44-p55) +- [Emerging patterns (P31-P43): extended notes](#emerging-patterns-p31-p43-extended-notes) +- [The HC3 corpus](#the-hc3-corpus-grounding-for-p53-and-the-science-claims) +- [Coverage against Wikipedia](#coverage-against-wikipedia-signs-of-ai-writing) +- [Honest limits of this catalog](#honest-limits-of-this-catalog) +- [Full trigger lists (P1, P4, P7)](#full-trigger-lists) +- [Before and after examples (34 of the 55)](#before-and-after-examples) +- [Worked examples (technical, blog, LinkedIn)](#worked-examples) + +--- + +## The craft and forensic set (P44-P55) + +These twelve extend the catalog with craft-level and forensic tells, novel relative to the P1-P43 set (cross-checked to avoid duplicates). P44-P52 target higher-order writing habits and copy-paste artifacts; P53 is grounded in the HC3 corpus; P54-P55 target drafting and revision residue, described independently of any other project's pattern names or text (see below). + +| ID | Pattern | +|:---|:--------| +| P44 | False Agency | +| P45 | Narrator-from-a-Distance | +| P46 | Diff-Anchored Writing | +| P47 | Hyphenated-Pair Overuse | +| P48 | Aphorism Formulas | +| P49 | Fragmented Headers | +| P50 | Passive / Subjectless | +| P51 | Reasoning-Chain Artifacts | +| P52 | Unicode Obfuscation | +| P53 | Hedged-Enumeration Openers (HC3 corpus, [arXiv 2301.07597](https://arxiv.org/abs/2301.07597)) | +| P54 | Argument Residue | +| P55 | Leftover Hedge Debris | + +**P54 and P55, provenance note.** Both target drafting and revision residue: a model (or a human working fast) drafts through more than one internal position before landing on an answer, and traces of the rejected material survive into the final text as a rebuttal to nobody (P54) or a qualifier the final claim no longer needs (P55). This is standard editorial-craft reasoning about insufficient revision passes, not tied to any single paper. The names, descriptions, and trigger lists here were written independently and do not reuse another project's terminology, even where the underlying phenomenon (drafting residue surviving into a final rewrite) is one other humanizer-style tools have also noticed. + +--- + +## Emerging patterns (P31-P43): extended notes + +**P31 Elegant Variation (Noun-Phrase Cycling).** LLMs carry a repetition penalty that discourages reusing the same noun phrase, so they substitute increasingly elaborate descriptors for one entity. This is distinct from P11 (Synonym Cycling), which is word-level. P31 is whole-noun-phrase cycling for the same subject. The fix is counterintuitive to a model: pick the clearest term and repeat it, because humans repeat words without anxiety. + +**P32 Collaborative Communication Leaking.** The model was producing advice or correspondence for the user, and the user pasted it into a published piece without stripping the conversational framing. Distinct from P19 (identity disclosure like "I hope this helps"); P32 is instructional framing ("In this article, we will explore") that belongs in a chat, not an article. + +**P33 Placeholder Text / Mad Libs.** Fill-in-the-blank templates the user forgot to complete. Among the most definitive tells because no careful human ships `[Your Name]`. Search for square-bracketed instructions and `XXXX`-style date stubs. + +**P34 Chatbot Reference Markup Leaking.** Tool-specific citation tokens preserved on copy-paste: `citeturn0search0` (ChatGPT), `contentReference[oaicite:0]{index=0}`, `oai_citation`, Grok cards. Near-definitive proof of tool use because these strings exist nowhere else. + +**P35 UTM Source Parameters.** ChatGPT, Copilot, and Grok append tracking parameters to URLs they emit (`utm_source=chatgpt.com`). Strip them. + +**P36 Sudden Style/Register Shift.** Catches mixed human and AI authorship: the AI section has a different voice, formality, and error profile than the human section. Look for graduate-thesis prose dropped into casual notes, or American spelling appearing mid-piece from a non-American author. + +**P37 Overattribution.** Proving importance by listing where a subject was covered, rather than what the coverage said. Distinct from P2 (dropping famous names). Fix: pick one source and summarize what it actually reported. + +**P38 Paragraph-Reshuffling Immunity.** LLMs generate parallel self-contained blocks instead of an unfolding argument. The test: can you swap paragraphs 2 and 4 without breaking the piece? If yes, it reads as AI. Source: [HackerNews thread](https://news.ycombinator.com/item?id=46646939). + +**P39 Paragraph-Closing "Whether" Summaries.** SEO-blog habit of ending each paragraph with a local recap ("Whether you prefer X or Y..."). Humans rarely close flowing prose this way. Source: [Gone Travelling Productions, Aug 2025](https://gonetravellingproductions.com/2025/08/20/ai-giveaways-in-writing/). + +**P40 Symbolic Gloss / Meaning-Telling.** The interpretive layer that tells readers what to feel ("the closed factory represents the decline of..."). Distinct from P1 (pivotal/testament inflation). Fix: state the fact, let the reader interpret. Source: [Writewithai Substack, 2025](https://writewithai.substack.com/p/10-dead-giveaways-your-content-screams). + +**P41 Infomercial Engagement Hooks.** Fake dramatic pauses from social-media-optimized writing ("The kicker?", "The brutal truth?"). Distinct from P19 and P21. Source: [Writewithai](https://writewithai.substack.com/p/10-dead-giveaways-your-content-screams), corroborated on [HackerNews](https://news.ycombinator.com/item?id=46646939). + +**P42 Erratic Inline Bolding.** Patternless bold spans mid-paragraph, with no consistent rule for what gets emphasized. Distinct from P14 (systematic overuse). Source: [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing). + +**P43 The Treadmill Effect.** Low information density: a long section that restates one idea. Humans advance; AI circles. Distinct from P22 (sentence-level filler) and P30 (uniform length). Source: [aidetectors.io](https://www.aidetectors.io/blog/spotting-ai-writing-patterns). + +--- + +## The HC3 corpus (grounding for P53 and the science claims) + +HC3 (Human ChatGPT Comparison Corpus), from Guo et al. 2023, "How Close is ChatGPT to Human Experts?", [arXiv 2301.07597](https://arxiv.org/abs/2301.07597), pairs human and ChatGPT answers to the same questions. It is bilingual (separate [HC3-English](https://huggingface.co/datasets/Hello-SimpleAI/HC3) and [HC3-Chinese](https://huggingface.co/datasets/Hello-SimpleAI/HC3-Chinese) splits), roughly 40K question sets. + +Findings this skill leans on: + +- **Length.** English human answers average 142.5 words vs ChatGPT 198.1 (about 39% longer). Chinese 102.3 vs 115.3. Backs the "AI is wordier" thesis and P43. +- **Vocabulary diversity.** Humans use a larger unique-word set (English 79,157 vs 66,622) and higher diversity ratios. A second corpus corroborating the type-token-ratio point. +- **Perplexity.** ChatGPT text has lower perplexity at text and sentence level; human perplexity is long-tailed. Direct support for the Perplexity Principle. +- **"Indicating words".** The corpus ships lists of top-discriminating tokens. The ChatGPT markers "There are several ways", "In general", "It is generally a good idea" became P53. + +Licensing note: the HuggingFace dataset is CC-BY-SA-4.0 (cite with attribution). The GitHub detector code has no license, so none of it was reused, and this skill does not claim to have benchmarked against their detectors. We cite HC3 as corroborating evidence only. + +--- + +## Coverage against [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) + +Every prose and formatting sign the Wikipedia guide documents maps to a pattern here: + +- Significance inflation -> P1; notability over-attribution -> P2, P37; superficial -ing -> P3; promotional tone -> P4; weasel/vague attribution -> P5; exaggerated source quantity -> P5, P37; formulaic "challenges" -> P6. +- AI vocabulary -> P7 (tiered); copula avoidance -> P8; negative parallelisms (all three variants) -> P9; rule of three -> P10; elegant variation -> P11, P31. +- Title case headings -> P16; boldface overuse, emoji-as-formatting, skipped heading levels, thematic breaks before headings, tables-where-prose-fits -> P14; inline-header lists -> P15; em dashes -> P13; curly quotes -> P17; Markdown in the wrong context -> P28. +- Collaborative/conversational language -> P19, P32; knowledge-cutoff disclaimers -> P20; placeholder text -> P33; chatbot markup (turn0search0, contentReference/oaicite, RAG attribution tags) -> P34; utm_source parameters -> P35; fabricated or phantom citations -> P25; pronounced style shifts -> P36; section-end summaries -> P39. +- Human-writing positive indicators (predating Nov 2022, natural variation) and the "detectors are unreliable, do not judge on one tell" caution map to the Guardrails section in `SKILL.md`. + +Intentionally out of scope (Wikipedia-namespace editing, not general prose): non-existent categories/templates, AfC submission statements, exhaustive edit summaries, pre-placed maintenance tags, canned user pages, permissions gaming, and citation-integrity mechanics (invalid DOI/ISBN, missing page numbers, unused named references). A prose humanizer should not touch these. + +--- + +## Honest limits of this catalog + +This catalog has a shelf life, and it's worth saying so plainly rather than letting the pattern count speak for itself. + +Wikipedia's own editors are not unanimous about the reliability of the guide most of this catalog is built on. The talk page for [Wikipedia:Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia_talk:Signs_of_AI_writing) records editors arguing that some listed indicators are not reliable evidence of AI authorship, because they have seen the same patterns in human-written content for years. The guide's own maintainers caution that no single sign proves AI authorship and that it works best combined with other context, not applied as an automatic checklist. That is exactly this skill's "flag clusters, not isolated tells" guardrail, restated by the source document itself rather than invented here. + +Trained human judges are not much better at this task than a coin flip, and that is worth taking seriously. Pindrop's "AI Text Detection Bias" study, presented at ACL 2026, found expert human annotators scored only 45 to 53 percent accuracy distinguishing AI-generated from human-written text (close to chance) while showing no statistically significant demographic bias, in contrast to automated detectors, which scored higher overall but showed measurable demographic bias, most notably over-flagging English-language-learner writing as machine-generated. Treat `--score` as a signal, not a verdict: even a careful human reader is unreliable at exactly this task. + +There is also a real argument that what this catalog detects is not "AI writing" so much as "default assistant voice." Xu et al., "Base Models Look Human To AI Detectors" ([arXiv:2605.19516](https://arxiv.org/abs/2605.19516)), found that base, non-instruction-tuned language models are classified as human-written by AI detectors far more often than the RLHF-aligned, instruction-tuned versions of those same models. The tells this skill hunts for are mostly artifacts of alignment and fine-tuning, not properties of language models in general, and they will keep drifting as alignment recipes change. P7 (AI vocabulary), P13 (em dash), and P17 (curly quotes) are the most exposed to this drift, since they key on surface word choice and punctuation, the part of the signature a provider can patch fastest with a system-prompt tweak. The more structural patterns, P30, P38, P43, and most of the craft set (P44 onward), are harder to patch away and should hold up longer. + +Fiction and creative prose sit outside this catalog's current scope. StoryScope ([arXiv:2604.03136](https://arxiv.org/abs/2604.03136)) found narrative-structure features (unresolved subplots, ambiguous character choices, non-chronological structure) separate human from AI fiction more reliably than word choice or punctuation do, a genuinely different, and on the paper's own numbers stronger, signal than anything in P1-P55. Worth knowing about; not built here, since this catalog targets non-fiction prose and a fiction-specific mode would need its own `--purpose` value and its own guardrails, not a bolt-on. + +--- + +## Full trigger lists + +`SKILL.md` carries a working subset of triggers for these three high-volume patterns. Here is the full list. + +**P1 Significance Inflation.** stands/serves as, is a testament/reminder, vital/significant/crucial/pivotal/key role/moment, underscores/highlights importance, reflects broader, symbolizing ongoing/enduring/lasting, contributing to the, setting the stage, marking/shaping the, represents a shift, key turning point, evolving landscape, focal point, indelible mark, deeply rooted. + +**P4 Promotional Language.** boasts a, vibrant, rich (figurative), profound, enhancing its, showcasing, exemplifies, commitment to, natural beauty, nestled, in the heart of, groundbreaking (figurative), renowned, breathtaking, must-visit, stunning, cutting-edge, seamless, robust, world-class, state-of-the-art. + +**P7 AI Vocabulary Words.** Additionally, align with, bolster, crucial, delve, emphasizing, enduring, enhance, foster/fostering, garner, highlight (verb), interplay, intricate/intricacies, key (adjective before noun), landscape (abstract), leverage, multifaceted, notably, pivotal, realm, showcase, tapestry (abstract), testament, underscore (verb), utilize, valuable, vibrant, moreover, furthermore, "it's worth noting", "it's important to note", "in terms of", "at the end of the day". They often cluster: "additionally, it's worth noting that this pivotal development underscores the vibrant landscape." + +--- + +## Before and after examples + +One before/after pair per pattern that benefits from one. Read the AI line, then the human rewrite. + +**P1 Significance Inflation** +> **AI:** established in 1989, marking a pivotal moment in the evolution of regional statistics +> **Human:** established in 1989 to collect regional statistics + +**P2 Notability Name-Dropping** +> **AI:** cited in NYT, BBC, FT, and The Hindu +> **Human:** In a 2024 NYT interview, she argued that regulation should focus on outcomes + +**P3 Superficial -ing Phrases** +> **AI:** The color palette resonates with the region's beauty, symbolizing bluebonnets, reflecting the community's deep connection to the land +> **Human:** The architect chose blue and gold to reference local bluebonnets + +**P4 Promotional Language** +> **AI:** Nestled within the breathtaking region of Gonder, a vibrant town with rich cultural heritage +> **Human:** A town in the Gonder region, known for its weekly market and 18th-century church + +**P5 Vague Attributions** +> **AI:** Experts believe it plays a crucial role in the regional ecosystem +> **Human:** A 2019 Chinese Academy of Sciences survey found 12 endemic fish species + +**P6 Formulaic Challenges** +> **AI:** Despite its prosperity, faces challenges typical of urban areas. Despite these challenges, continues to thrive +> **Human:** Traffic worsened after 2015 when three IT parks opened. A stormwater project started in 2022 + +**P8 Copula Avoidance** +> **AI:** Gallery 825 serves as the exhibition space +> **Human:** Gallery 825 is the exhibition space + +**P9 Negative Parallelisms** +> **AI:** It's not just a song, it's a statement +> **Human:** The heavy beat adds to the aggressive tone + +**P10 Rule of Three** +> **AI:** innovation, inspiration, and industry insights +> **Human:** talks and panels, plus time for networking + +**P31 Elegant Variation** +> **AI:** Yankilevsky, alongside other non-conformist artists, faced obstacles. The visionary creator's distinctive artistic journey continued. +> **Human:** Yankilevsky and other non-conformist artists faced obstacles. His work continued. + +**P32 Collaborative Communication Leaking** +> **AI:** In this article, we will explore the unique characteristics that make this framework worth using. +> **Human:** This framework solves three problems that React Router doesn't. + +**P33 Placeholder Text / Mad Libs** +> **AI:** Dear [Recipient], I am writing regarding [Topic]. +> **Human:** (Either fill it in or don't send it.) + +**P34 Chatbot Reference Markup Leaking** +> **AI:** The school has been recognized as an International Fellowship Centre. citeturn0search1 +> **Human:** The school has been recognized as an International Fellowship Centre. + +**P35 UTM Source Parameters** +> **AI:** `https://example.com/article?utm_source=chatgpt.com` +> **Human:** `https://example.com/article` + +**P36 Sudden Style/Register Shift** +> **AI:** yeah so the bug is in line 42 lol. The aforementioned implementation exhibits suboptimal performance characteristics. +> **Human:** yeah so the bug is in line 42. The loop allocates on every iteration instead of reusing the buffer. + +**P37 Overattribution** +> **AI:** Her insights have been featured in Wired, Refinery29, and other prominent media outlets. +> **Human:** Wired profiled her 2024 research on algorithmic bias in hiring software. + +**P38 Paragraph-Reshuffling Immunity** +> **AI:** Remote work improves balance. Many workers prefer it. Studies show productivity rises. Commuting costs drop. Office costs decline too. +> **Human:** Remote work's flexibility is the obvious sell. The harder question is what you lose: the hallway conversation that turns into your best idea, the body language that tells you someone is drowning before they say anything. + +**P39 Paragraph-Closing "Whether" Summaries** +> **AI:** Tokyo offers everything from Michelin-starred restaurants to humble ramen stalls. Whether you prefer fine dining or street food, Tokyo has something for every palate. +> **Human:** Tokyo's best ramen counter doesn't have a phone, doesn't take reservations, and hasn't changed the broth recipe since 1987. + +**P40 Symbolic Gloss** +> **AI:** The closed factory represents the decline of American manufacturing and speaks to broader anxieties about post-industrial identity. +> **Human:** The factory closed in 2009. Three hundred jobs. The town's high school dropped football the following year. + +**P41 Infomercial Engagement Hooks** +> **AI:** Most people abandon goals in week three. The brutal truth? They lack a clear failure threshold. +> **Human:** Most people abandon goals in week three. The ones who don't usually make the failure threshold explicit before they start. + +**P42 Erratic Inline Bolding** +> **AI:** Remote work has **fundamentally changed** the way companies operate, with **many employees** now preferring **flexible arrangements**. +> **Human:** Remote work has fundamentally changed how companies operate. Most employees now want flexible arrangements. + +**P43 The Treadmill Effect** +> **AI:** The system is fast. In other words, it performs well. Put simply, speed is one of its strengths. +> **Human:** The system answers in 40ms at p99, about 20x faster than the tool it replaced. + +**P44 False Agency** +> **AI:** The market rewards companies that listen. +> **Human:** Customers spend more with companies that answer support tickets within an hour. + +**P45 Narrator-from-a-Distance** +> **AI:** People tend to underestimate how much testing matters. +> **Human:** You will underestimate how much testing matters, right up until a Friday deploy pages you at 2am. + +**P46 Diff-Anchored Writing** +> **AI:** This function was refactored to replace the old callback approach with async/await. +> **Human:** This function fetches the user and returns a promise. + +**P47 Hyphenated-Pair Overuse** +> **AI:** The results are high-quality and the pipeline is state-of-the-art. +> **Human:** The results are high quality and the pipeline is genuinely new. + +**P48 Aphorism Formulas** +> **AI:** Data is the new oil, and attention is the currency of the modern web. +> **Human:** Ad networks pay about $8 per thousand views, so publishers chase pageviews. + +**P49 Fragmented Headers** +> **AI:** ## Performance / Performance is important for a good user experience. +> **Human:** ## Performance / The dashboard renders 10,000 rows in 40ms because it virtualizes the list. + +**P50 Passive / Subjectless** +> **AI:** The cache is invalidated automatically when the config is changed. +> **Human:** The file watcher clears the cache whenever you edit the config. + +**P51 Reasoning-Chain Artifacts** +> **AI:** Let me break this down. First, we need to understand the users. Step 1: identify who hits this endpoint. +> **Human:** Ops engineers hit this endpoint about 400 times a day. That is who we are designing for. + +**P52 Unicode Obfuscation** +> **AI:** Text seeded with zero-width spaces between letters so a detector reads gibberish. +> **Human:** The same text, cleaned to plain characters, because the goal is good writing, not evasion. + +**P53 Hedged-Enumeration Openers** +> **AI:** There are several ways to speed up a slow query. In general, it is a good idea to consider indexing. +> **Human:** Add an index on user_id. That one change took the query from 900ms to 12ms. + +**P54 Argument Residue** +> **AI:** While some might argue that remote work hurts collaboration, the data tells a different story. +> **Human:** Remote work hasn't hurt our collaboration. Our incident response time actually improved after we went remote. + +**P55 Leftover Hedge Debris** +> **AI:** To some extent, this approach is arguably the best option, and it will definitely solve the problem. +> **Human:** This approach solves the problem. + +--- + +## Worked examples + +Longer before/after passages showing several patterns fixed at once. + +### Technical documentation (`--voice technical`) + +**Before (AI-heavy):** +> This comprehensive guide delves into the intricacies of our authentication system. The platform leverages cutting-edge JWT technology to provide a seamless, secure, and robust authentication experience. Additionally, it features a pivotal role-based access control system that serves as a testament to our commitment to security. Not only does this ensure data protection, but it also fosters a culture of trust within the organization, highlighting the enduring importance of cybersecurity in today's rapidly evolving digital landscape. + +**After:** +> The auth system uses JWTs. Tokens expire after 15 minutes; refresh tokens last 7 days. Role-based access control restricts API endpoints by user role: admin, editor, and viewer each see different data. The token rotation logic is in `src/auth/refresh.ts` if you need to change the expiry windows. + +**What changed:** Replaced "leverages cutting-edge JWT technology" with "uses JWTs." Added specific details (expiry times, file paths). Killed 9 AI vocabulary words. + +### Blog post (`--voice casual`) + +**Before (AI-heavy):** +> In today's rapidly evolving technological landscape, artificial intelligence is reshaping how we think about creativity. This groundbreaking shift represents a pivotal moment in human history, one that underscores the intricate interplay between innovation and artistic expression. As we delve deeper into this fascinating realm, it becomes crucial to understand the multifaceted implications of AI-generated content. Industry experts highlight that this transformation will have an enduring impact, fostering new forms of collaboration between humans and machines. The future looks incredibly bright for those who embrace this change. + +**After:** +> I've been messing around with AI image generators for about six months now, and I still can't decide if I love them or if they make me uneasy. The outputs are technically impressive. I got a portrait last week that looked better than anything I could paint in a year. But there's something missing. It's like eating a perfect-looking meal that has no flavor. My artist friends are split: half are using these tools daily, half refuse to touch them. I don't think either side is wrong. What I do know is that my own creative process has changed since I started using them, in ways I'm still figuring out. + +**What changed:** Replaced abstract commentary with personal experience. Added genuine uncertainty. Concrete analogy (perfect meal, no flavor). Sentence lengths: 8 to 31 words. + +### Social media / LinkedIn (`--voice professional`) + +**Before (AI-heavy):** +> Excited to announce that I've taken on a pivotal new role at TechCorp! This incredible opportunity represents a significant milestone in my professional journey. I'm deeply grateful to my amazing network for their unwavering support. The team at TechCorp is truly world-class, and I'm committed to leveraging my expertise to drive innovation and foster growth. Looking forward to this exciting chapter! #NewBeginnings #Innovation #Leadership #Grateful + +**After:** +> Started a new job at TechCorp this week. I'm leading their developer tools team, 12 engineers building internal tooling that currently serves about 400 developers. First week has been drinking from the firehose: new codebase, new faces, new coffee machine I can't figure out. Nervous and excited in roughly equal measure. If anyone has advice on the first 90 days in an eng leadership role, I'm all ears. + +**What changed:** No emojis, no hashtags. Replaced "pivotal new role" with what the role actually is. Added specific details (team size, user count). The coffee machine line adds humanity. Closing asks for help. diff --git a/session-mechanism/references/humanizer-en/references/patterns.zh.md b/session-mechanism/references/humanizer-en/references/patterns.zh.md new file mode 100644 index 0000000..d89e722 --- /dev/null +++ b/session-mechanism/references/humanizer-en/references/patterns.zh.md @@ -0,0 +1,130 @@ +# 中文原生 AI 痕迹模式（实验性附录） +# Native Chinese AI-Writing Patterns (Provisional Appendix) + +> ## ⚠️ 实验性 · PROVISIONAL — 请先读这里 +> +> **中文：** 本附录（ZH1–ZH15）是作者的**临时草稿**，**尚未经过中文母语写手校验**。它与英文正式目录（P1–P53）**不在同一成熟度**，不应被当作已验证的规则使用。此外，英文用的 **burstiness（句长波动）/ perplexity（用词可预测性）指标不能直接迁移到以字为单位、不用空格的中文** —— 中文里四字成语的密度、句读节奏往往比词长方差更能反映 AI 痕迹。 +> +> **English:** This appendix (ZH1–ZH15) is the author's **provisional draft**. It has **NOT been validated by a zh-fluent writer**, is **not at parity** with the English catalog (P1–P53), and should not be treated as a proven ruleset. Also: **burstiness and perplexity do not port cleanly to character-based, space-free Chinese** — in Chinese, four-character-idiom density and clause rhythm are usually stronger tells than sentence-length variance. +> +> **两个未验证的假设 / Two UNVERIFIED hypotheses:** ZH13（「的/了」虚词过度使用）和 ZH14（翻译腔）是**推测**，**目前没有任何竞品会显式检测它们**（翻译腔仅通过外来语黑名单被间接触及）。列在这里是为了记录假设，不是因为它们已被解决。ZH13 (的/了 particle overuse) and ZH14 (translationese) are **speculative — no competitor detects them explicitly**; kept here as flagged hypotheses, not solved patterns. + +--- + +## 目录 · Contents + +- [怎么用这份附录 · How to use](#怎么用这份附录--how-to-use) +- [核心原生模式 · Core native tells (ZH1-ZH7)](#核心原生模式--core-native-tells-zh1zh7) +- [英文模式的中文对应 · Analogs of English patterns (ZH8-ZH12)](#英文模式的中文对应--analogs-of-english-patterns-zh8zh12) +- [未验证假设 · Unverified hypotheses (ZH13-ZH14)](#未验证假设--unverified-hypotheses-zh13zh14) +- [最深层痕迹 · The deepest tell (ZH15)](#最深层痕迹--the-deepest-tell-zh15) +- [来源与致谢 · Sources](#来源与致谢--sources) + +--- + +## 怎么用这份附录 · How to use + +跑中文改写时，除了英文的 P1–P53，再扫描下面这些原生中文模式。格式和 SKILL.md 一致：**名称（中/英）· 触发信号 · 修正 · 一组前后对比**。中文改写里**可以**使用破折号（——），这份文件不受仓库禁破折号 CI 的约束；但仍应避免像 ZH5 描述的那样滥用。 + +分类：ZH1–ZH7 是原生中文核心痕迹（来自竞品研究，证据较扎实）；ZH8–ZH12 是英文模式的中文对应（对应关系已标注）；ZH13–ZH14 是未验证假设；ZH15 结合了「立场缺失」这一最深层痕迹。 + +--- + +## 核心原生模式 · Core native tells (ZH1–ZH7) + +**ZH1：四字词语堆砌 / 空心金句 · Four-character idiom stacking / hollow slogans.** 用一连串四字成语、对仗短语堆出「文学感」，或写一句听起来很像可以摘抄、实则什么都没说的口号。**修正：** 删掉空心金句和堆砌的四字词，只保留「带场景、带代价、带判断」的压缩句 —— 有具体画面、有代价权衡、有明确态度的那种。**触发信号：** 连续多个四字成语（如「日新月异、方兴未艾、蓬勃发展、势不可挡」）、对仗排比、「不禁让人感叹」、听起来能裱起来但没有信息量的句子。 + +> **AI：** 在这个日新月异、瞬息万变的时代，技术的浪潮波澜壮阔、势不可挡，深刻地改变着我们的生活方式。 +> **人：** 过去三年，我们把部署时间从两小时压到了九分钟。代价是每次发布都得盯着监控，怕它崩。 + +**ZH2：首先/其次/最后 罗列 · Enumeration scaffolding.** 机械地用「首先……其次……再次……最后……」搭骨架，是英文 `first, second, finally` 脚手架的中文指纹。**修正：** 删掉这些连接词。让内容本身的逻辑决定顺序，或者干脆分点但不加套话式序词。**触发信号：** 首先、其次、再次、最后、一方面……另一方面、综上所述、总而言之。 + +> **AI：** 首先，它提升了效率。其次，它降低了成本。最后，它改善了体验。 +> **人：** 它快了三倍，服务器账单少了一半。用户没抱怨，这是头一回。 + +**ZH3：套话开头 · Cliché openers.** 用万能空话开场，句子换个主语就能套到任何文章上。**修正：** 直接从最具体的那句话开始 —— 一个数字、一个场景、一个判断。**触发信号：** 在当今……的时代、随着……的飞速发展、在数字化浪潮下、众所周知、随着科技的不断进步。 + +> **AI：** 随着人工智能的飞速发展，各行各业正在经历前所未有的深刻变革。 +> **人：** 上周我用 AI 重写了一份 API 文档，母语审稿人五秒就退回来了，说「一股机翻味」。 + +**ZH4：AI 高频词黑名单 · AI-vocabulary blacklist.** 中文 AI 文本反复使用的一批「书面腔 + 外来语翻译腔 + 企业黑话」高频词。**修正：** 换成日常说法，或直接删。**触发信号（致命黑名单）：** 此外、值得注意的是、至关重要、深入探讨、赋能、抓手、闭环、底层逻辑、颗粒度、打法、格局、生态、织锦、挂毯、相互作用、凸显、彰显、标志着、令人叹为观止、坐落于、不可或缺、保驾护航、量身打造。（「织锦/挂毯」是英文 tapestry 的翻译腔，「格局/生态」是 landscape/ecosystem 的对译。） + +> **AI：** 此外，构建数据闭环、打通底层逻辑，对于赋能业务增长至关重要。 +> **人：** 我们把三个系统的数据接到了一起，这样退款不用再手动对账了。 + +**ZH5：破折号（——）滥用 + 全角/半角标点混用 · Em-dash overuse + full/half-width punctuation mixing.** 破折号当万能连接符到处用（英文 P13 的中文对应），外加中文里混进英文的逗号、括号、引号，或全角半角乱套。**修正：** 破折号只在真正需要「解释/转折/停顿」时用一次；标点统一用中文全角（「」『』，。），别让英文标点（, . " " ()）漏进中文正文。**触发信号：** 一段里多个 ——、中文里出现 English-style 逗号或引号、`(半角括号)` 混在中文里、句号用「.」。 + +> **AI：** 这个方案——非常创新——它将——从根本上——改变行业(尤其是效率方面). +> **人：** 这个方案能省一半时间。代价是前期要重写数据层，大概两周。 + +**ZH6：设问-回答套路 · Rhetorical question-answer over-patterning.** 反复用「为什么……？因为……」「是什么让它与众不同？答案是……」这种自问自答的机械节奏（区别于英文 P27 的疑问句标题）。**修正：** 偶尔一次是修辞，通篇就是套路。把问句改成直接陈述。**触发信号：** 为什么……？因为、是什么造就了……、答案是、你可能会问、那么，如何做到呢？ + +> **AI：** 为什么它如此高效？因为它采用了先进的架构。那么，它安全吗？答案是肯定的。 +> **人：** 它高效，是因为绕过了那一层缓存。安全性我还没压测过，别在生产上用。 + +**ZH7：口号式乐观结尾 · Slogan-style optimistic endings.** 结尾一律拉高到空洞的乐观（英文 P24 的中文对应，触发词不同）。**修正：** 用一个具体的下一步、一个待解问题、或一句真实的判断收尾，别喊口号。**触发信号：** 让我们拭目以待、未来一片光明、必将产生深远影响、前景无限、值得期待、共同书写新篇章。 + +> **AI：** 我们有理由相信，在各方的共同努力下，未来必将一片光明，让我们拭目以待。 +> **人：** 下一步要解决冷启动那 800 毫秒的延迟。搞不定的话这套方案就得推倒重来。 + +--- + +## 英文模式的中文对应 · Analogs of English patterns (ZH8–ZH12) + +**ZH8：意义拔高 / 象征化 · Significance inflation & symbolic gloss.**（对应 P1 / P40）给平常的事实硬安上「时代意义」，用「标志着、彰显了、体现了、象征着、折射出」把小事说成大势。**修正：** 直接说这东西是什么、做了什么，删掉「代表了什么」的评论。**触发信号：** 标志着、彰显、体现了、象征着、折射出、具有里程碑意义、开启了新篇章、树立了标杆。 + +> **AI：** 这次更新彰显了团队精益求精的工匠精神，标志着产品迈入了全新的时代。 +> **人：** 这次更新修了那个登录会掉线的 bug，另外把加载调快了一点。 + +**ZH9：书面语套话 / 冗余虚词 · Formal filler.**（对应 P18 / P22）用一堆书面腔的填充短语撑场面，删掉不影响意思。**修正：** 直接删。**触发信号：** 值得注意的是、需要指出的是、不难发现、在一定程度上、从某种意义上说、总的来说、换言之、众所周知、显而易见。 + +> **AI：** 值得注意的是，在一定程度上，这个功能从某种意义上说提升了用户体验。 +> **人：** 这个功能让结账少点一次。转化率涨了 4%。 + +**ZH10：排比堆砌 / 强凑三段 · Forced parallelism (rule of three).**（对应 P10）中文里滥用排比和「不仅……而且……」的三连对仗，凑气势而非讲内容。**修正：** 保留一个最有信息量的分句，砍掉为对仗而对仗的部分。**触发信号：** 三个结构相同的短句连排、不仅……而且……更、既……又……还、A 是……，B 是……，C 是……（三项工整）。 + +> **AI：** 它不仅高效，而且稳定，更兼具优雅、简洁与可扩展性。 +> **人：** 它够快，也够稳。优不优雅我不好说，反正没再半夜被叫起来过。 + +**ZH11：车轱辘话 / 同义反复 · Restating the same point (treadmill).**（对应 P43）用「换句话说、也就是说、简而言之」把同一个意思原地绕好几圈。**修正：** 保留最清楚的一版，删掉重复。**触发信号：** 换句话说、也就是说、简而言之、说白了、归根结底（后面跟的其实是前面刚说过的话）。 + +> **AI：** 它能提升效率。换句话说，它让工作更快。也就是说，它节省了时间。 +> **人：** 它把导出报表的时间从十分钟压到了一分钟。 + +**ZH12：加粗滥用 / emoji 小标题 · Boldface & emoji-header overuse.**（对应 P14 / P28）几乎每个名词都加粗，每个小标题前挂 emoji，Markdown 记号漏进本该是纯文本的地方（微信、邮件）。**修正：** 加粗只留给真正的关键词，删掉装饰性 emoji；发到不支持 Markdown 的地方就把 `**` 去掉。**触发信号：** 一段里多处 **加粗**、🚀✨🔥 开头的小标题、纯文本渠道里出现 `**` `##`。 + +> **AI：** 🚀 **核心优势**：我们的**产品**拥有**强大**的**性能**和**卓越**的**体验**！ +> **人：** 核心优势就一条：冷启动比上一版快了三倍。 + +--- + +## 未验证假设 · Unverified hypotheses (ZH13–ZH14) + +> ⚠️ 以下两条是推测，**没有任何竞品显式检测它们**。请当作待验证的方向，不要当规则用。These two are speculative; no competitor detects them. Treat as open hypotheses, not rules. + +**ZH13：「的/了」虚词堆叠 · Overuse of 的/了 particles.**（未验证 · UNVERIFIED）假设：AI 中文倾向堆叠「的」字定语、句末机械加「了」，读起来黏、拖。**修正（暂拟）：** 拆掉多层「的……的……的」定语，改成短句；删掉不必要的「了」。**触发信号（暂拟）：** 一个名词前挂三层以上「的」、每句都以「……了」收尾。**注意：这条尚无证据支撑，可能是伪模式。** + +> **AI（假设）：** 这是一个基于最新技术的、经过精心设计的、能够满足用户需求的解决方案了。 +> **人：** 这方案用了新的检索层，专门解决搜索慢的问题。 + +**ZH14：翻译腔 / 英式长句 · Translationese / calqued English syntax.**（未验证 · 仅间接触及 · UNVERIFIED）假设：AI 中文常带英文语法的影子 —— 被动句过多、从句套从句的长句、「一个……」滥用（英文 "a/an" 直译）、「进行 + 动词」（"make a decision" → 「进行决策」）。现有工具只通过外来语词黑名单（见 ZH4）间接碰到它，没人专门检测句法层面的翻译腔。**修正（暂拟）：** 拆长句为短句，把被动改主动，删掉冗余的「一个」和「进行」。**触发信号（暂拟）：** 「被……所……」、过长的定语从句、「一个 + 名词」高频出现、「进行/给予/作出 + 抽象名词」。 + +> **AI（假设）：** 一个能够被用户所信赖的、对数据进行有效处理的系统被我们所构建了出来。 +> **人：** 我们做了个处理数据的系统，用户反馈还挺信得过。 + +--- + +## 最深层痕迹 · The deepest tell (ZH15) + +**ZH15：立场缺失 / 温吞表达 · No stance / lukewarm hedging.**（对应 P38 段落可打乱性 + 英文版 North Star）最深的 AI 痕迹不是某个词，而是**通篇没有一个能被反驳的观点** —— 面面俱到、两边都对、段落顺序打乱也不影响论证。一句话概括：不能被反驳的观点就不叫观点，叫温吞的空气。**修正：** 逼出一个站得住但足够鲜明的立场，点名一个具体对象或反方，让读者知道作者到底站哪边、要付什么代价。**触发信号：** 全文没有一句可争论的判断、每个观点后面都跟「当然，也有另一种看法」、段落调换顺序读起来一样通顺、结论谁都不得罪。 + +> **AI：** 关于是否采用微服务，业界看法不一。它既有优势，也有挑战，需要根据具体情况权衡，没有绝对的对错。 +> **人：** 团队少于十个人就别上微服务。我们试过，光维护那套服务发现就吃掉了两个人。等你真被单体拖垮了再拆也不迟。 + +--- + +## 来源与致谢 · Sources + +- **英文正式目录** —— 见 [`../SKILL.md`](../SKILL.md)（P1–P53）。本附录是作者实验性的中文补充草稿，**不是**替代。 + +给 integrator 的提醒：ZH13、ZH14 无证据支撑，公开前建议找中文母语写手校验整份附录；burstiness/perplexity 相关表述在中文语境下需保留「不能直接迁移」的说明。 diff --git a/session-mechanism/references/manifest.md b/session-mechanism/references/manifest.md index 8647a60..f8732d2 100644 --- a/session-mechanism/references/manifest.md +++ b/session-mechanism/references/manifest.md @@ -1,13 +1,13 @@ # manifest · 包内文件清单 -> 生成方式：逐文件 `compile()` / `json.loads` ＋ md5 ｜ **最近一次全量重算：2026-10-07 21:34 （必读表标题订正「三篇→四类」＋ 点明第4项含语气那一档）** +> 生成方式：逐文件 `compile()` / `json.loads` ＋ md5 ｜ **最近一次全量重算：2026-10-07 21:56 （说人话每轮注入 ＋ 英文硬核版整包纳入 ＋ 新判据）** > ⚠️ **2026-10-05 局部增量**：`references/pitfalls.md`（P0-77 拆条 ＋ P0-73/P0-77 压缩）与 > `scripts/goalctl.py`（`--switch-goal` 确认闸 ＋ 旧目标归档）两行的 md5/大小已按当天实测值更新；**其余行仍是 10-04 基线**。 > ⛔ 本表**不含** `install.log`（运行日志）与 `references/manifest.md`（自引用，写完即失真）。 > ⚠️ **provenance 列里的 `skills/multi-session-collab/…`、`skills/workbuddy-session-forensics/…` 已是历史路径** > —— 那两个目录 2026-10-01 已移到 `<工作区>/归档/技能-退役-20261001/`（⛔ 不在技能根了）。 -文件总数：**70** ｜ 语法 / 结构检查失败：**0** +文件总数：**76** ｜ 语法 / 结构检查失败：**0** ## ✅ 已完成 · 2026-10-05 「目标唯一性 ＋ 换目标需确认」（用户口径落地） @@ -113,7 +113,7 @@ | 包内路径 | 字节 | md5 | 语法检查 | |---|---|---|---| -| `SKILL.md` | 114310 | `2d4ee3ca383f30d454f1ce5797498e22` | — | +| `SKILL.md` | 114635 | `c779fd78f61458b62cec99e9e103a4fc` | — | | `assets/board-launch.py.tpl` | 4355 | `7e9dfe1c4845f20dbb89f599d80e167b` | — | | `assets/board-render-probe.js` | 14398 | `a21bd1905b34537436ce778c6bfbc288` | — | | `assets/board.html` | 151811 | `c597cd7f21543542e9cdbe486c5ccd79` | — | @@ -133,6 +133,12 @@ | `references/dsh-decision-method/素材库-U-用户决策.md` | 24597 | `94c9e860148f4265f1e21e5322346f94` | — | | `references/dsh-decision-method/素材库-反例-X.md` | 5712 | `8bce93e8c1ce71d17e6d33aa9a2d7724` | — | | `references/forensics.md` | 6067 | `1fb6deca9bb05bebe950d4f4e3adf043` | — | +| `references/humanizer-en/LICENSE` | 1092 | `a8440fdde2a535efdd44813bce97df57` | — | +| `references/humanizer-en/README.md` | 4204 | `f3f41dc19ef27b7591422a43140d17fe` | — | +| `references/humanizer-en/SKILL.md` | 39490 | `3fd8d0d4175d1325cc942ce65733719d` | — | +| `references/humanizer-en/references/always-on-templates.md` | 3066 | `1bbcc7aa145f5a8189f35af7f9477769` | — | +| `references/humanizer-en/references/patterns.md` | 26186 | `830c68f9e07fb6bbee297b7a9004d994` | — | +| `references/humanizer-en/references/patterns.zh.md` | 14867 | `2c661fde3d84751edc8053eedd36f930` | — | | `references/karpathy-output-ladder/SKILL.md` | 5252 | `f1e3b07003bbc544db52d32c122e6faf` | — | | `references/karpathy-output-ladder/assets/html-template/index.html` | 5883 | `b95c39d2cd41d8c0f21d4007e7ef3cef` | — | | `references/karpathy-output-ladder/references/ladder-workflow.md` | 2684 | `d49840707d19302d8f61f4e1d7f4ea2e` | — | @@ -144,7 +150,7 @@ | `references/作业规矩/00-作业总规矩（原 agent-operating-rules）.md` | 70243 | `80fc5471015b237ee7aacd6976eda6fe` | — | | `references/作业规矩/02-工作区纪律.md` | 21351 | `1a679fdeb9cca0883a47f619d1aec85d` | — | | `references/作业规矩/03-多棒接力编排.md` | 13185 | `631b4b7455938b0c3a3a4f6f94d97eed` | — | -| `references/作业规矩/04-去AI味与说话方式.md` | 12520 | `cd3cca159299404e97fc6de9c54e6024` | — | +| `references/作业规矩/04-去AI味与说话方式.md` | 14059 | `5100e1a26c3477541eafe1c7797d3b3a` | — | | `roots.env` | 624 | `ec38f15f9a4101d69c815aa2cdd7b477` | — | | `scripts/apply-reply-rules.py` | 7172 | `551b0ee5bf6c7a9f6b64c1b1d53bd343` | ok | | `scripts/board-launch.py` | 2794 | `998a66b9d335ab1863b5b871a527bf4f` | ok | @@ -163,7 +169,7 @@ | `scripts/hooks/decision-rules-hook.py` | 12399 | `c521237bada7487aecf5e54ad4d19ace` | ok | | `scripts/hooks/lock-guard-hook.py` | 20363 | `641457de0297ee7a812ccde57f67dc2b` | ok | | `scripts/hooks/prompt-guards.py` | 9332 | `0aa1d1fdd2bf5a40cda2e60d7a785534` | ok | -| `scripts/hooks/reply-style-guard.py` | 11283 | `1e52b65f279c0b4df70bb53bc613a774` | ok | +| `scripts/hooks/reply-style-guard.py` | 13200 | `e044f5d3e52ae94775dfba2090e7ae8e` | ok | | `scripts/hooks/session-log-guard.py` | 24636 | `4dd13b24d541d1afc7b4874dba6bb1eb` | ok | | `scripts/hooks/skill-load-guard.py` | 29994 | `2450b93b4bac87cf9e99697703efa78f` | ok | | `scripts/hooks/stop-dialog-guard.py` | 51240 | `3e0791e42f41c37438601a9d2314dd8e` | ok | @@ -177,7 +183,7 @@ | `scripts/lock/op-lock.sh` | 4690 | `1a31eda3642e23693a65e1519860c744` | — | | `scripts/lock/preflight-lock.sh` | 8673 | `e985ec1cb853fae4c351cd03b171355d` | — | | `scripts/mut_run.py` | 13323 | `3bffc12e1e57d5efc743bac55e584b62` | ok | -| `scripts/selftest.py` | 491896 | `c1704981f23dbf2be04bdd074cfd46b3` | ok | +| `scripts/selftest.py` | 493433 | `7ebd4893ca5339c575ed64d79f2697ac` | ok | | `scripts/session-rules-check.py` | 44412 | `b2b468992d80421106316eaf451e2477` | ok | | `scripts/stop-collab.py` | 10462 | `d8043bedd23b52b6642aaf7ec8b8c980` | ok | | `scripts/supervise-launch.py` | 2503 | `f416a2f197e5524a8859c1d227ba1d05` | ok | diff --git a/session-mechanism/references/作业规矩/04-去AI味与说话方式.md b/session-mechanism/references/作业规矩/04-去AI味与说话方式.md index 09df94b..76db48e 100644 --- a/session-mechanism/references/作业规矩/04-去AI味与说话方式.md +++ b/session-mechanism/references/作业规矩/04-去AI味与说话方式.md @@ -10,6 +10,17 @@ --- + +**说人话（语气档 · 每轮生效）** + +1、**先把话说清楚，再谈漂亮** —— 一句一个意思，能用短句就别绕长句。 +2、**像人一样有态度**：该下判断就下（「这条路更划算」）；⛔ 不写「值得注意的是」「具有重要意义」这类空转评价。 +3、⛔ **禁四种高频 AI 味**：三段式排比连用（「不仅…而且…」）／以「…着」结尾的肤浅分析／模糊归因（「业内人士认为」）／把一句话拆成加粗小标题 ＋ 竖排碎句。 +4、⛔ **不谄媚、不铺垫**：不写「好问题」「让我为你解答」，不写知识截止免责声明，直接给结论。 +5、**交付前三问**：① 这句删了会不会少信息（不会就删）② 有没有哪处一看就是模型写的（有就改）③ 读完像不像我在跟人说话。 +⚠️ 与排版分工：结构（能不能被扫）看每轮注入的那块；本块只管**像不像人话**。全文 ＝ 本文档。 + + ## 0. 核心原则（5 条） 1. **删除填充短语** —— 去掉开场白与强调性拐杖词。 @@ -250,5 +261,6 @@ | **本参考** | 语气：像人话（节奏 / 用词 / 段落组织 / 灵魂） | 在不破坏结构的前提下尽量满足 | | **协作与提报判据（原「参考 01」⇒ 2026-10-07 已并入 `references/02-功能优先协作协议.md`）** | 说什么、该不该问 | 独立，同时生效 | | **通用版（独立技能 `humanizer-zh`，2026-10-07 补记）** | 同一套「AI 写作特征」的**通用版**（示例更全，19 KB） | 本包那份是**会话场景加固版**（多 4 节）⇒ **两处同时装着时以本包为先**；⛔ 不装也能跑 | +| **英文硬核版（🔴 2026-10-07 按用户令整包纳入本包）** | `references/humanizer-en/` —— 原独立技能 `humanizer` **逐字搬入**（6 文件）：**55 个模式**（中文那份 24 类）＋ **5 种语气档**（casual／professional／technical／warm／blunt）＋ **0–100 AI 痕迹打分** ＋ 可 `--file` 就地改 | 要**更硬的检测/打分**、或要**指定语气档**时读它；⛔ 与本档同属"语气"这一档，冲突以本档（会话场景）为先 | **一句话判据**：**能扫、像人、不啰嗦、不谄媚。** diff --git a/session-mechanism/scripts/hooks/reply-style-guard.py b/session-mechanism/scripts/hooks/reply-style-guard.py index 75fb340..c0fb418 100644 --- a/session-mechanism/scripts/hooks/reply-style-guard.py +++ b/session-mechanism/scripts/hooks/reply-style-guard.py @@ -161,6 +161,46 @@ def _core(workdir): return _extract(_read(p)), p +# ── 🔴 2026-10-07 「说人话」块（用户令逐字：「重点就是做到说人话就行了」）────────────── +# 为什么要它：语气那一档原先只有**指针**（必读表里一行）⇒ 实测没被读到（用户报障 +# 「content_marketing_agent 的会话生成的文档并没有说人话，还是我手动要求的」）。 +# ⇒ 照 `03`（排版）那条**每轮注入**的现成路子，把语气也送进每轮上下文。 +# ⚠️ 与 `03` 分工：`03` 管「能不能被扫」（结构），本块管「像不像人话」（语气）。 +# ⚠️ **只从包内取**；包内没有 ⇒ **静默不注入**（它是增强项，⛔ 不是结构契约，缺了不影响排版那条）。 +VOICE_BEGIN = '' +VOICE_MAX_CHARS = 1100 + + +def _voice_core(): + """取包内 `references/作业规矩/04-去AI味与说话方式.md` 的 VOICE-CORE 块。""" + _hooks = os.path.dirname(os.path.abspath(__file__)) + _pkg = os.path.dirname(os.path.dirname(_hooks)) + t = _read(os.path.join(_pkg, 'references', '作业规矩', '04-去AI味与说话方式.md')) + i = t.find(VOICE_BEGIN) + j = t.find(VOICE_END) + if i < 0 or j < 0 or j <= i: + return '' + body = t[t.find('\n', i) + 1:j].strip() + if len(body) > VOICE_MAX_CHARS: + body = body[:VOICE_MAX_CHARS].rstrip() + \ + '\n…（超长已截断，全文见本包 `references/作业规矩/04-去AI味与说话方式.md`）' + return body + + +# 🔴 原实现改名留档；`_core` **重新定义**为「原实现 ＋ 追加说人话块」 +# ⇒ `main()` 一行都不用改（它只认 `_core`），注入正文自动多一段。 +_core_reply = _core + + +def _core(workdir): + c, p = _core_reply(workdir) + v = _voice_core() + if c and v: + return c + '\n\n' + v, p + return (c or v), (p if c else '') + + def _log(workdir, line): try: with io.open(os.path.join(workdir, LOG_REL), 'a', encoding='utf-8', newline='\n') as f: diff --git a/session-mechanism/scripts/selftest.py b/session-mechanism/scripts/selftest.py index 93f778f..404e88c 100644 --- a/session-mechanism/scripts/selftest.py +++ b/session-mechanism/scripts/selftest.py @@ -7415,5 +7415,28 @@ def t_checker_confirms_acceptance(): ] +@case("⛔ 说人话：既要「被看到」（每轮注入）也要有英文硬核版在包内") +def t_voice_core(): + """🔴 2026-10-07 立（用户令逐字：「重点就是做到说人话就行了」）。 + + 病根（§26）：语气那一档原先**只有指针、没有注入** ⇒ 实际没被读到 ⇒ + 用户报障「content_marketing_agent 的会话生成的文档并没有说人话，还是我手动要求的」。 + 处置：① 照排版那条**每轮注入**的现成路子给语气也做一块； + ② 按用户令把英文硬核版（55 模式／5 语气档／打分）整包纳入本包。 + """ + h = (HERE / "hooks" / "reply-style-guard.py").read_text(encoding="utf-8", errors="replace") + d = (HERE.parent / "references" / "作业规矩" / "04-去AI味与说话方式.md").read_text(encoding="utf-8", errors="replace") + en = HERE.parent / "references" / "humanizer-en" / "SKILL.md" + return [ + ("文件里有 `VOICE-CORE` 标记对（注入块取得到）", + d.count("") == 1), + ("注入钩子读该标记并接进 `_core`（⛔ 不是只写进文档）", + "VOICE_BEGIN" in h and "def _voice_core(" in h), + ("接入方式是「原地重定义」：`_core` 包住原实现（⛔ 不改 `main()`）", + "_core_reply = _core" in h and "c, p = _core_reply(workdir)" in h), + ("英文硬核版已整包纳进包内（`humanizer-en/SKILL.md` 在位）", en.is_file()), + ] + + if __name__ == "__main__": sys.exit(main()) \ No newline at end of file