Demand

---
name: demand
argument-hint: <你想验证的产品点子 / 需求假设>
description: "深度验证一类需求是否真实存在、值不值得做。输入一个模糊的产品/需求假设，并行 fan-out 多个子 agent 从双支柱采集证据（自上而下：行业报告/官方数据/资本信号；自下而上：Reddit/HN/App 评论/搜索趋势/社交舆情），套 7 项需求验证评分卡 + 对抗红队证伪 + 正反对账，产出带引用、带置信度的 HTML 验证报告，给出 Go/有条件做/转向/别做的裁决。使用 /demand 命令触发。当用户想验证一个产品点子、市场需求、做需求调研/市场调查、判断要不要做某个功能、问「这个需求真的存在吗/有多大/有人做过吗」时必须触发此 skill。"
---

# Demand Radar — 需求深度验证

你不是在帮用户「找证据支持他的点子」，你是在做一次严格的需求验证：用外部真实数据判断这个需求到底成不成立。默认假设是「这可能是个伪需求」，由证据来推翻它。每一条结论都要挂真实引用，没有来源就不下判断。

## 核心原则（写正文前先内化）

1. **反证伪优先**：用户有确认偏误，你没有。第 ⑤ 步专门派红队去杀这个假设。
2. **双支柱交叉验证**：自上而下（权威报告）+ 自下而上（社区/评论）缺一不可，上下矛盾本身是最值钱的发现。
3. **零登录 / 不碰爬虫**：不要求用户任何注册、OAuth、key。只用无需 key 的官方 API（HN/iTunes/Play）+ WebSearch/WebFetch。要限定来源用 WebSearch 的 `allowed_domains` 参数（注意：query 里的 `site:` 操作符会被忽略）。⚠️ **Reddit 屏蔽了 Anthropic 爬虫**（WebSearch/WebFetch 都拿不到），社区信号改靠 HN + App 评论 + 不限域名的普通搜索（对比博客/Medium/可访问论坛），可靠 Reddit 访问留付费版。
4. **三角验证**：一个信号要算「已验证」，必须 ≥2 个独立源出现；单源只是「线索」。平台名用固定词表、标 `origin` 防转载虚数（见 validation-framework.md C/G 节）。
5. **报告语言跟用户走**：用户用中文问就出中文报告，用英文问就出英文报告（单语言，不混排）。在 `report.json` 里设 `"lang":"zh"` 或 `"en"`，所有文本字段用对应语言写。**评委评分卡的 `dim` 例外：一律用中文 canonical 维名**（脚本权重靠它）。
6. 动手前读 `references/validation-framework.md` 和 `references/forbidden-patterns.md` 全文。

## 输出目录（中间产物全部落盘，可复核可重渲染）

报告根目录默认 `~/.demand-radar/reports/`（不存在就 `mkdir -p` 建）；如设了 `$COWORK_OUTPUTS_DIR` 则优先用它。**每次 run 建一个子目录** `<根目录>/<需求slug>-<YYYYMMDD-HHMM>/`，存进 `$RUN_DIR`。本次 run 的**所有**产物都写在里面，绝不用 `/tmp`（跨 run 覆盖、报告出完就丢，可追溯性会断）：

```
$RUN_DIR/
├── hypothesis.json      # ① 假设卡（主卡 + 子断言）
├── evidence.json        # ③ 全量证据
├── tri.json             # ④ 三角验证结果
├── judges.json          # ④ 三评委评分卡
├── agg-initial.json     # ④ 初评聚合
├── agg-final.json       # ⑤ 红队闭环后终评聚合
├── report.json          # ⑥ 报告数据（改它可重渲染）
└── <需求slug>-需求验证报告.html
```

## 工作流程

### ① 框定需求（交互，不可跳过；一轮问完）

把用户那句模糊的想法逼成**可证伪的假设**。**只打扰用户一次**：用一次 AskUserQuestion（最多 4 问）问走非猜不可的项（通常是 ICP / 地域市场 / 买家 vs 用户 / 定价假设），其余你按最合理解释**草拟整张假设卡**连同子断言一起给用户过目确认——用户改哪条就改哪条，不要逐项拷问。按 validation-framework.md A 节的**假设卡 v2** 定清楚：

- **主卡**：ICP / Job / 现状凑合 / 需求类型（决定 playbook 选源）/ 地域市场（决定中英文源配比）/ 买家 vs 用户（不同就分开写）
- **子断言 H1-H4（★核心）**：把点子拆成 2-4 条**命运独立**、单独可证伪的子断言（痛点存在 / ICP 匹配 / 付费成立 / 模式成立），每条单独标 Go 判据。「需求真」和「买断模式成立」可以一真一假——拆开才能分别验证。

写成 `hypothesis.json` 存 `$RUN_DIR`，后面所有 agent 都围绕它工作，证据用 `claims:["H1"]` 挂靠子断言。

**进度纪律（②-⑤ 每阶段收尾时执行）**：全程可能要跑十几分钟，用户在等。每个阶段结束用一两句话汇报「刚发现了什么 + 下一步做什么」（例：「三角验证完成：9 个信号被 ≥2 源支持，付费意愿只有意见级证据——进入评委打分」）。只说增量，别复述流程。

### ② 选源（读 playbook）

读 `references/source-playbook.md`，根据主卡的需求类型挑选本次要用的源，并为每个源生成 2-4 个搜索变体（中英配比按地域市场定，竞品名要进 query）。

### ③ 并行 fan-out 采集证据 ★核心

**在一条消息里同时 spawn 6 个子 agent**（用 Agent 工具，`subagent_type: general-purpose`），让它们并发跑。每个 agent 的 prompt 里写清：要验证的 hypothesis（含子断言）、负责的源、可用的连接器命令、必须返回结构化 JSON——每条证据按 validation-framework.md G 节的**证据项**结构：原话 + URL + 日期 + `signal` 标签 + `platform`（固定词表）+ `origin`（一手/二手/疑似转载）+ `dims` + `claims`。

**自上而下支柱**
- **权威报告 agent**：WebSearch + WebFetch 找行业报告（Gartner/IDC/Statista/艾瑞/易观）、官方统计、融资数据、上市公司财报、政策。重点抓市场规模、增长率、趋势方向、资本流向。
**自下而上支柱**
- **社区痛点 agent**：HN 跑 `python3 ${CLAUDE_SKILL_DIR}/scripts/connectors/hn_algolia.py "<query>"`；更广的社区信号走 **WebSearch（不限定域名）**——对比测评博客、Medium、可访问论坛会自然浮上来，抓真实抱怨原话并带 URL。⚠️ Reddit 屏蔽了 Anthropic 爬虫；`scripts/connectors/reddit.py` 仅在用户本机 IP 未被限流时 best-effort，拿不到就跳过。挖真实抱怨、「我现在用 X 凑合」。
- **竞品评论 agent**：先 `python3 ${CLAUDE_SKILL_DIR}/scripts/connectors/itunes.py search "<app名>"` 拿 id，再 `itunes.py reviews <id>` 和 `play_reviews.py`。Product Hunt / 其它竞品发现走 WebSearch `site:producthunt.com`（零 token）。挖竞品差评里的缺口、付费用户吐槽。**顺手填竞品对照表**（名字/模式/定价/评分数/最大差评 → report.json 的 `competitors`）。
- **搜索需求 agent**：WebSearch 关键词热度、autocomplete、"people also ask"、Google Trends 趋势方向（全程零登录）。
- **社交舆情 agent**：WebSearch X / 小红书 / 垂直论坛的真实讨论与情绪。

每个 agent 返回后，把证据合并成 `$RUN_DIR/evidence.json`，**不要在这一步下结论**。

**迭代补搜循环（最多 3 轮，缺口由脚本算）**：每轮证据收齐后先跑
```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/triangulate.py $RUN_DIR/evidence.json --gaps --out $RUN_DIR/tri.json
```
看 stderr / `gaps` 字段：哪些维度证据 <2 条、哪些信号只有单源、`unrecognized_platforms` 里有没有该归一的写法。**缺什么脚本说了算，补哪里你决定**——再叠加两条语义判断：双支柱结论打架需要加证据判谁对、提到了某竞品/某说法但没挖透。有缺口就**再派一轮定向 agent**（只针对缺口，别重复已覆盖的），没有就进 ④。三轮还补不齐的，留到报告「未能验证的部分」。

### ④ 三角验证 + 多评委打分

③ 的最后一轮 `tri.json` 就是三角验证结果：每个 signal 被几个独立平台支持、置信度（线索/中/高）。单源的只能当线索。

**派 3 个评委 agent 独立打分**（一条消息并行、互相不可见）：每个评委拿到 hypothesis + tri.json + 全部证据，按 7 项评分卡各产出一份评委评分卡 JSON（结构见 G 节）。**三个评委必须用 G 节的三个人设**：乐观派 / 严格派 / 中立派——同 prompt 跑三遍分数高度相关，中位数防偏就失效了。两条打分纪律：
- `dim` 用中文 canonical 维名；**没证据的维打 `score: null`**，禁止猜 0 分。
- 第 6 维是「**差异化楔子**」不是「有没有竞争」：竞争存在是需求被验证的**正向**证据（计入付费意愿/市场规模），红海只在「你没有任何别人没占的切口」时压第 6 维——见 validation-framework.md「竞争怎么算分」。

三份合并成 `$RUN_DIR/judges.json` 后跑：
```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/aggregate_scores.py $RUN_DIR/judges.json --out $RUN_DIR/agg-initial.json
```
脚本给出加权裁决档 + 分歧维度 flag（报告要标注）+ `insufficient_dims`（数据不足的维，整体置信度要降档；付费意愿/市场规模数据不足时裁决不得高于「有条件做」）+ `demand_state`（喂报告 `demand_tags` 当参考；竞争状态轴你按竞品证据补）。

**双支柱交叉验证**：自上而下（报告/资本）和自下而上（社区/评论）是否一致？矛盾要单独高亮当关键发现（例：报告说市场大但社区零讨论）。

### ⑤ 红队证伪 + 闭环重评

spawn 一个**红队 agent**，喂它 hypothesis（含子断言）+ ④ 的初步裁决，按 `references/red-team-checklist.md` 的九种杀法**专门找证据杀死这个需求**（按子断言分别攻击），反证也要挂引用。

**闭环重评（走评委，不自己拍）**：红队若拿出有数据支撑的反证——
1. 把反证加进 `evidence.json`（该重跑 tri.json 就重跑）；
2. **受影响的维度重新交给严格派 + 中立派两个评委打分**（喂原证据 + 红队反证），替换 judges.json 里对应维度的分；
3. 重跑 `aggregate_scores.py` 出 `$RUN_DIR/agg-final.json` 作最终裁决。

初评/终评两份 agg 都留着——报告的 `score_history`（delta 条）要用。正反对账：哪些初步判断被推翻、哪些扛住、哪些悬而未决；红队 8/9 号杀法的反证进 `risks`，「致命」级进 `do_not`，被证伪的子断言更新 `claims` 状态。红队若全程找不到反证，如实写「红队未能证伪」——这是强信号。

### ⑥ 产出报告（面向提问者，答案优先）

报告是给**提出需求的人**看的，不是给分析师看的。第一眼必须回答「我的需求解决了没、我该干嘛」。按 `references/report-template.md` 组装 `$RUN_DIR/report.json`——**只写语义字段**（判断、判词、建议、声音、风险……），`scorecard` / `score_history` / `signals` / `evidence` / `weighted_pct` 五个数据字段**不要手抄**，交给 `--run-dir` 从中间产物直读。先校验后渲染：

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/generate_report.py \
  --report $RUN_DIR/report.json --run-dir $RUN_DIR --check     # 硬伤退出码 1，修完再渲染
python3 ${CLAUDE_SKILL_DIR}/scripts/generate_report.py \
  --report $RUN_DIR/report.json --run-dir $RUN_DIR \
  --output "$RUN_DIR/<需求slug>-需求验证报告.html" --open
```

组装铁律（详见模板，这里只列易错点）：
1. **透传交给脚本**：五个数据字段由 `--run-dir` 自动填充（agg-final / agg-initial / tri / evidence）；你手写了脚本也不覆盖，只在 verdict / weighted_pct 不一致时告警——告警了以脚本为准改回来。
2. **子断言三态必须出现在第一屏**：`claims` 每条 成立/存疑/被证伪 + 一句话；`go_criteria` 回评框定时定的判据（渲染进档案区 E）。
3. **长度铁律**：`verdict_sub` ≤26 字先判断需求；`verdict_sub2` ≤120 字（渲染在第 2 节判词块，不挤 hero）；`--check` 超限会告警，告警就返工文案。
4. **建议三件套**：`one_thing`（只做一件事，时间/成本框写 `window`）+ `actions` ≤3（动词开头 + 判据 + 时限 + `fixes` 挂靠短板维名，渲染时自动拼上该维分数）+ `do_not` ≤2（红队致命项）。「持续关注」这种没判据的废话禁止。
5. `demand_tags` 用固定词表（F 节）；`risks` 按 H 节，没有就空数组；`not_verified` 必填；每条 `why`/`voice`/`risk` 挂 `evidence_ids`（`--check` 会验引用完整性）；绝不过度承诺。

**收尾（对话内，报告之外）**：报告生成后在对话里给一段 5 行以内的文本版结论——裁决 + 分数、一句话判断（verdict_sub）、最关键的一条为什么、「如果只做一件事」、报告路径。再补一句：改 `$RUN_DIR/report.json` 后重跑上面命令可重渲染。用户不打开文件也能拿到答案。

### 快速档（用户赶时间才用）

用户说「快速看一下 / quick / 粗验一下」时降档跑：采集只派 3 个 agent（社区痛点 + 竞品评论 + 权威报告）、补搜最多 1 轮、评委三人设照旧、红队只跑 1-5 号杀法。报告结构不变，但 `confidence` 上限「中」，并在 not_verified 里注明「快速档未覆盖：搜索需求 / 社交舆情 / 红队 6-9 号杀法」。默认走全量，不要自作主张降档。

## 参考文件索引

- `references/validation-framework.md` — 假设卡 v2（子断言）+ 7 项评分卡 + 证据分级 + 评委人设 + 风险清单
- `references/source-playbook.md` — 按需求类型选源 + 搜索变体技巧 + 证据落库规范
- `references/red-team-checklist.md` — 红队九种杀法（含合规/伦理）+ 产出去向
- `references/report-template.md` — 报告结构 v2 + 全字段 + 长度铁律
- `references/forbidden-patterns.md` — 红线：禁编数据、无引用不下判断
- `scripts/connectors/*` — 官方免费 API 连接器（HN/iTunes/Play/Reddit）
- `scripts/triangulate.py` — 证据三角验证（平台归一 + 转载降档 + `--gaps` 每维缺口）
- `scripts/aggregate_scores.py` — 多评委聚合（中位数 + 分歧标记 + 数据不足退出加权 + 加权裁决）
- `scripts/generate_report.py` — report.json → HTML 报告（`--check` 先校验、`--run-dir` 自动透传数据字段；改 report.json 可重渲染）
- `scripts/tests/test_scripts.py` — 脚本回归测试（`python3 scripts/tests/test_scripts.py`）