jmdevilleros/niche-map

利基圖譜：概念空間中的空白地帶

此技能用於在特定領域中尋找有根據的空白地帶。它將模糊的領域景觀轉化為一個真實項目 × 明確維度的表格，尋找無人佔據的組合與區域，將這些空白轉化為具體構想，並驗證它們並非海市蜃樓。

指導原則。 數字輔助判斷，而非取代判斷。編碼是分析師的決定，因此空間反映的是評分量表與市場本身。這就是為什麼每個提出的空白都必須通過編碼的信度檢查（步驟 2b）和外部驗證（步驟 6）。

此儲存庫中的工具

檔案	角色
niche_core.py	步驟 3-4：編碼、聚類、主成分分析、UMAP、三重組合空白、密度空白、候選鄰居、供給 vs. 需求、圖表
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、聚類結果或報告）的獨立代理程式會話，僅使用書面評分量表和項目的公開頁面來編碼該工作表。如果必須由同一代理程式執行，請開始一個全新的上下文，並僅提供工作表和評分量表。在比較之前鎖定結果（例如儲存一個校驗和）。
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. 閱讀不一致處並分類：評分量表模糊性（重疊的值、不可測量的錨點）、呈現 vs. 結構混淆，或編碼者錯誤。
   2. 使用步驟 2.3 中的一個決策規則（優先順序、可測量錨點、合併無法區分的值）來修正評分量表。
   3. 使用修正後的評分量表重新編碼整個語料庫中的該維度，然後對該維度使用一個新的 10% 樣本（新的種子）重新執行檢查。
   4. 如果仍然失敗：降低其權重（≤ 0.6），將其從 gap_dims 中移除，或丟棄它。永遠不要報告一個由兩次失敗的維度所解釋的三重組合空白。
6. 報告表格（維度、n、% 一致性、κ/κw、狀態），所做的量表修改，以及第二位編碼者的身份類型（人類、獨立代理程式）。

典型結果：關於功能（動作、目標、輸入/輸出、觸發條件）的維度一致性良好；感知或估計維度（風格、空間結構、持續時間）是常見的失敗點，這正是步驟 2.3 中存在決策規則的原因。

3. 空間：編碼、聚類、梯度與視覺化

由 niche_core.py 執行。黃金法則：聚類和空白是在原始編碼空間中計算的；UMAP 僅用於繪圖。

• 編碼。 對名目維度使用 One-hot × 權重/√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. 供給 vs. 需求（可選）。 按聚類：項目數量（供給）與需求訊號的中位數（評論、安裝量、搜尋量、星星數），並始終附上其覆蓋範圍（supply_demand_clusters.csv）。一個需求高但供給小的聚類是一個空白提示**（推論）**。

4d. 初步評分。 新穎性（1-5 分，基於相對距離與解釋空白的三重組合）、可行性（1-5 分，使用用戶資源的 MVP 工作量）與契合度（1-5 分，來自步驟 0 的偏好與限制）。對於每個候選項目，透過將其添加到 candidates 並重新運行，檢查其 3 個最近鄰居。

5. 語義轉換：從向量到構想

從最高 z 值的三重組合和最遠的密度空白中選取 8-12 個候選項目；合併訊號並刪除重複項。每個候選項目獲得：

• 工作名稱以及一個 2-3 句的具體電梯簡報：用戶做什麼，產品提供什麼。
• 所有維度上的向量；必須滿足規則。
• 最近項目及其距離（乘以中位數）。
• **為何在語料庫中看起來是空的：**哪個三重組合或區域解釋了它，以及它的任何維度是否在步驟 2b 中失敗。
• **風險：**技術、市場和契合度風險。

6. 外部驗證與海市蜃樓測試

1. 對每個候選項目進行目標搜尋，在語料庫之外：

   • "[概念] + app/tool + pricing"；
   • "[概念] alternative"；
   • 使用 2-3 個同義詞搜尋領域商店；
   • 開源儲存庫。

   記錄 3-5 個競爭對手及其連結和價格。**假設幾乎總是會出現一些：**一個 N ≈ 100 的語料庫無法覆蓋長尾。相應地調整新穎性。

2. 海市蜃樓測試（改編自 white-space-analysis，請參閱參考文獻）。候選項目面對四個問題：

   • **規模：**是否有足夠多的人有此工作要做？
   • **付費或轉換意願：**從最強到最弱的證據，他們已經為部分解決方案付費，維持一個昂貴的替代方案，或嘗試自己建構。
   • **現有業者問題：**為什麼沒有人填補它？可接受的答案：商業模式或管道衝突、最近的外部變化、一個成長中的細分市場。令人擔憂的答案：「我找不到原因」。
   • **可贏性：**目標用戶能否克服使空白保持空白的障礙？

   裁決：通過（係數 1.0）、可疑（0.7）或失敗（0.4）。

3. 最終分數 = 新穎性 × 可行性 × 契合度 × 海市蜃樓係數（範圍 0.4-125）。

4. 在驗證中失敗的候選項目會留在報告中作為「虛假空白」。它們暴露了語料庫偏差，並且……

…[因翻譯而截斷]