jmdevilleros/niche-map

利基地图：概念空间中的空白

本技能用于发现领域中具有充分依据的空白。它将模糊的领域地图转化为真实商品 × 明确维度的表格，寻找无人占据的组合和区域，将这些空白转化为具体创意，并验证它们并非幻象。

指导原则。 数字组织判断，而非取代判断。编码是分析者的决策，因此概念空间反映评分标准的程度不亚于市场。这就是为什么每个提出的空白都必须通过编码的可靠性检查（步骤2b）和外部验证（步骤6）。

本仓库中的工具

文件	作用
niche_core.py	步骤3-4：编码、聚类、PCA、UMAP、三元组空白、密度空白、候选邻居、供需对比、图表
recode_check.py	步骤2b：盲审复检样本表与各维度一致性（Cohen's kappa）
md_to_pdf.py	步骤7：Markdown报告转PDF
templates/report_template.md	步骤7：报告骨架
examples/	合成、虚构数据集，用于端到端测试管线

---

0. 输入与范围界定问题

开始前获取以下答案。如有缺失，一次性以单个模块形式提问。

输入	问题	为何重要
主题与边界	什么算作一个商品？（例如“核心价值在于X的工具”）	防止混合类别和伪空白。
N	多少个商品？（默认80-100；有用最小值≈50）	N < 50时，三元组计数是噪声。
纳入标准	最低接受度、可用性、平台、语言、日期	在步骤1中应用并记录。
目标用户	谁会构建或购买产出的成果？	是适配度评分和target_filter的基础。
约束	预算、时间、技能、销售渠道、排除主题	成为target_filter和适配度标准。
交付物	语言、货币（及汇率来源）、格式	默认：PDF，包含排名、利基卡片、地图及包含链接的完整语料表。

1. 语料库：N个真实、经过验证的商品

1. 广泛种子。 从各种来源收集约1.3 × N个候选商品：领域商店或目录、“最佳”列表、“X替代品”搜索以及近期长尾发布（发布网站、利基目录、开源注册表）。如果只有知名产品进入，后期会出现虚假空白。
2. 每个商品的存在性检查。 每个商品需要一个可解析的URL：商店页面、定价页面或仓库。记录HTTP状态、最终URL和日期。如果网站屏蔽机器人（403），检查域名根或使用浏览器；屏蔽并不意味着该商品不存在。
3. 接受度信号。 记录一个或多个公开信号（商店评分和评论数、发布网站投票数、仓库星标、安装量、奖项），并声明每个信号的来源和覆盖范围。不要仅因没有信号而放弃某个商品。如果接受度是纳入标准，则使用明确阈值应用。
4. 去重： 处理变体、品牌重塑、版本和区域SKU。保留规范名称和链接。
5. 按边界排除 不符合纳入标准的商品，并在报告中列出原因。
6. 语料库偏差检查（在报告中写入答案）：
   • 长尾商品占比（例如，过去24个月内发布，或低于接受度信号中位数）。如果低于约20%，则增加长尾商品样本。
   • 来源集中度：任何单一来源不应贡献超过约40%的商品。
   • 相对于规定边界的平台或语言偏差。
   • 按来源的信号覆盖范围（某些来源过度代表特定用户类型，例如代码托管网站上的开发者工具）。

输出：items.csv，每行一个商品，包含标识和链接列，以及验证的原始JSON。

2. 维度、量表和编码评分标准

1. 推导8-15个维度，通过阅读约20个商品的样本。将其分为两类：
   • 概念维度说明商品是什么：动词或动作、输入、输出、触发器、领域或主题、用户、美学。空白搜索使用这些维度（gap_dims）。
   • 属性维度说明商品如何构建或销售：复杂度、广度、自助服务、定价模型、价格层级。它们用于过滤和评分。如果用于空白搜索，会产生**“元”空白**，例如“事件触发 + 无AI + 高复杂度”。
2. 量表。 具有3-14个互斥值的名义类别，每个值有可读标签，或短序数（0-1、0-2、1-3），带有描述性锚点。
3. 书面评分标准： 每个值一行，包含定义和示例商品，以及下面的决策规则。它放入报告附录，并且是步骤2b中第二编码员收到的唯一材料。
   • 编码逻辑结构，而非呈现方式。 对于空间或结构维度，编码用户实际如何交互或推理该事物，而非其外观（例如，在平面上使用的3D渲染产品不是“3D”）。
   • 重叠值的优先级顺序。 当名义量表描述某种感知或风格性内容（外观、语气、风格）时，值会重叠。给出明确的决策顺序（“如果A适用，编码A；否则如果B……”），或合并编码员无法区分的值。
   • 序数的可测量锚点。 持续时间、大小或工作量等锚点必须说明如何测量以及来源（例如，“商店描述中所述或演示视频中观察到的典型会话；对于关卡类商品，一个关卡”）。如果无法观察，则编码主要情况并标记。
   • 编码主要模式。 如果某个商品模棱两可，则编码其主要模式并在notes列中记录疑问。
4. 权重。 默认1.0。提高核心概念维度（例如，动词至1.2），降低外围维度（例如，定价模型至0.4）。为每个权重提供理由。
5. 结构性检查：
   • 任何类别中商品数量不少于2个；合并或删除（niche_core.py会发出警告）。
   • 交叉表以检测冗余维度（相关性≈1）：删除或合并其中一个。
6. 承认局限性： 编码是判断。

输出：商品 × 维度CSV文件和包含量表、权重及规则的config.json。

2b. 盲审复检（强制）

目的：衡量是评分标准（而非编码员的记忆）决定了编码。基于不可靠维度的空白是评分标准的人为产物。

1. 抽样。 随机抽取语料库的10%，至少10个商品，使用固定种子： python recode_check.py sample --items items.csv --config config.json --out recode_sheet.csv --keep link 该表格仅包含商品ID和链接，维度列为空。
2. 第二编码员，盲审。 一个不同的人，或一个从未见过第一轮编码（无权访问items.csv、聚类结果或报告）的独立AI会话，仅使用书面评分标准和商品的公开页面进行编码。如果必须由同一AI代理完成，则启动一个新上下文，仅提供表格和评分标准。在比较前锁定结果（例如，存储校验和）。
3. 各维度一致性： python recode_check.py agree --items items.csv --config config.json --recode recode_sheet.csv --out agreement.csv
   • 类别维度：Cohen's kappa（κ）。
   • 序数维度：线性加权Cohen's kappa（κw），对接近但略有偏差的答案给予部分信用。
   • 同时报告原始百分比一致性，以及按商品列出的不一致列表。
4. 阈值。 当κ（或κw）≥ 0.60 且原始一致性≥ 80%时，维度通过。当n ≈ 10时，kappa存在噪声：用于分类处理，并阅读每个不一致项。
5. 低于阈值时，按此顺序处理：
   1. 阅读不一致项并分类：评分标准模糊（值重叠、锚点不可测量）、呈现与结构混淆、或编码员错误。
   2. 使用步骤2.3中的决策规则之一修复评分标准（优先级顺序、可测量锚点、合并无法区分的值）。
   3. 使用修订后的评分标准重新编码整个语料库的该维度，然后对该维度在新抽取的10%样本（新种子）上重新运行检查。
   4. 如果仍然失败：降低其权重（≤ 0.6），将其从gap_dims中移除，或删除该维度。永远不要报告其解释性三元组依赖于两次失败的维度的空白。
6. 报告 表格（维度、n、%一致性、κ/κw、状态）、所做的评分标准修改以及第二编码员的身份类型（人类、独立AI代理）。

典型结果：关于功能（动作、目标、输入/输出、触发器）的维度一致性良好；感知或估计维度（风格、空间结构、持续时间）是常见失败点，这也就是步骤2.3中存在决策规则的原因。

3. 空间：编码、聚类、梯度和可视化

由niche_core.py完成。黄金法则：聚类和空白在原始编码空间中计算；UMAP仅用于绘图。

• 编码。 类别维度使用独热编码 × 权重/√2，序数维度使用 (x − min)/(max − min)，使得切换类别的成本与序数的端到端移动相同。
• 聚类。 凝聚Ward聚类，k通过k_range内的轮廓系数选择。只有当改进超过0.005时，才接受更大的k。
  • k范围检查： 如果选择的k落在范围的任何一端，则扩大范围并重新运行；脚本会发出警告。如果仍处于边缘，则通过可解释性选择k并说明。
  • 对于类别数据，轮廓系数在0.15到0.30之间是正常的；不要将其宣传为“清晰的聚类”。
  • 标记少于3个商品的聚类和具有相同向量的商品；后者表明评分标准过于粗糙，无法区分商品。
  • 手动从cluster_profiles.md命名每个聚类，并将名称存储在cluster_names中。
• 梯度。 PCA载荷（PC1-PC3，pca_loadings.csv）被解读为“从A到B”的轴。
• 可视化。 UMAP（n_neighbors 10-15，min_dist 0.25，固定种子）配合KDE密度背景。限制：
  • 全局距离和岛屿大小毫无意义；
  • transform倾向于将新点拉到最近的岛屿上，因此候选者的新颖性从原始空间中的dist_min读取，而非图中。
• 成对热图 直观显示空单元格。

4. 空白

4a. 组合空白（三元组）。 对于空白（概念）维度的每个值三元组，比较独立假设下的观测值与期望值：e = N · p(a) · p(b) · p(c)，z = (e − o)/√e。保留三元组的条件：

• o ≤ max_observed（默认1）；
• e ≥ min_expected（默认1.2）；
• 三元组中的每个对至少在min_pair_support个商品中出现（默认2）：即各个部分单独存在；
• 它涉及至少一个锚定维度（anchor_dims，例如领域或动词）。

元空白过滤器： 将属性维度保留在gap_dims之外，并将anchor_dims设置为描述产品内容的维度。仅由属性组成的三元组不是利基。

4b. 密度空白。 生成50,000-400,000个随机合成向量，仅保留满足以下条件的向量：

1. 每一对值至少在一条真实商品中出现（已知部分的重新组合）；
2. 没有一致性规则禁止它们（rules：在领域中荒谬的组合）；
3. 它们匹配目标用户画像（target_filter，例如复杂度 ≤ 1 且自助服务 = 1）。这是用户适配过滤器：没有它，密度空白会漂移到用户无法构建或销售的产品。

幸存者按到最近真实商品的距离排名，并在主要概念维度（density_dedupe）上删除重复项。与不同真实商品之间的中位数最近邻距离（median_nn_distance）进行比较。

4c. 供需对比（可选）。 按聚类：商品数量（供应）与需求信号的中位数（评论、安装量、搜索量、星标），始终附带其覆盖范围（supply_demand_clusters.csv）。一个小聚类伴随高需求是一个空白提示**（推断）**。

4d. 初步评分。 新颖性（1-5，基于相对距离和解释空白的元组）、可行性（1-5，使用用户资源完成MVP所需努力）和适配度（1-5，来自步骤0的偏好和约束）。对于每个候选者，将其添加到candidates并重新运行，检查其3个最近邻。

5. 语义转换：从向量到创意

从最高z值的三元组和最远的密度空白中选择8-12个候选者；合并信号并删除重复项。每个候选者获得：

• 工作名称 和 2-3句话的具体宣传文案：用户做什么，产品交付什么。
• 所有维度的向量；必须满足规则。
• 最近邻商品 及其距离（×中位数）。
• 为何在语料库中看起来是空白： 哪个三元组或区域解释了这个空白，以及是否有任何维度在步骤2b中失败。
• 风险： 技术、市场和适配度。

6. 外部验证与幻象测试

1. 每个候选者的定向搜索，在语料库之外：

   • “[概念] + 应用/工具 + 定价”；
   • “[概念] 替代品”；
   • 使用2-3个同义词搜索领域商店；
   • 开源仓库。

   记录3-5个竞争对手及其链接和价格。假设几乎总会出现一些： N ≈ 100的语料库无法覆盖长尾。相应地调整新颖性。

2. 幻象测试（改编自white-space-analysis，见参考文献）。候选者需要回答四个问题：

   • 规模： 是否有足够多的人有此待完成工作？
   • 付费或切换意愿： 从最强到最弱的证据，他们已经为部分解决方案付费、维持着高成本变通方案、或尝试过自行构建。
   • 在位者问题： 为什么没有人填补这个空白？可接受的答案：商业模式或渠道冲突、近期外部变化、增长中的细分市场。令人担忧的答案：“我找不到原因”。
   • 可获胜性： 目标用户能否克服导致空白存在的障碍？

   结论：通过（因子1.0）、存疑（0.7）或失败（0.4）。

3. 最终得分 = 新颖性 × 可行性 × 适配度 × 幻象因子（范围0.4-125）。

4. 在验证中失败的候选者仍保留在报告中，作为“虚假空白”。它们揭示了语料库偏差，并……

……（为翻译截断）