# idea-reality-mcp v0.3 Plan

> **One thing only:** Keyword extraction overhaul.
> 更準、更穩、更少泛詞。其他大型功能全部延後，等使用者真的痛再做。

Status: **PLANNING** — do not start implementation until signaled.

---

## 目標

把「使用者輸入的點子」轉成**更穩、更準、更不亂飄**的 query set，直接提升：

- `top_similars` 更貼近真實意圖（相似專案品質）
- `reality_signal` 更少亂跳（分數穩定性）
- `pivot_hints` 建立在正確的關鍵字上（不再廢話）

**只動 keyword extraction，不碰架構大改。**

---

## 問題定義：Keyword Extraction 的 5 種失敗型態

修它不是憑感覺，而是針對這 5 類：

| # | 型態 | 範例 |
|---|------|------|
| 1 | **過泛** | 抽到 `AI / tool / platform / system / solution` 這種垃圾詞 |
| 2 | **過窄** | 只抓到一個很偏的詞，漏掉真正意圖 |
| 3 | **語言問題** | 中文輸入被拆得亂七八糟；中英混雜抓不到重點 |
| 4 | **領域詞漏掉** | `LLMOps / observability / evals / tracing` 被整個漏掉 |
| 5 | **同義詞沒展開** | `monitoring` 沒展到 `observability / tracing / telemetry` |

---

## 解法：三段式 Keyword Pipeline

### Stage A — 清理 + 反垃圾詞（Stopword / Boilerplate Filter）

- Hard filter 掉常見泛詞：`ai, tool, platform, system, solution, app, service, engine, framework, library, helper, manager, builder, generator`
- 太短（≤ 2 字元）、太常見、沒有區別力的詞降權或丟棄

**產出：** `clean_tokens[]`

---

### Stage B — 意圖錨點（Intent Anchors）

用極少量規則抽「意圖骨架」。這是什麼類型的東西？

```
evaluation | monitoring | agent | RAG | automation | MCP | CLI
SDK | workflow | orchestration | scraping | embedding | tracing
```

規則：
- 從 clean_tokens 中找到 1–2 個意圖錨點
- 後面生成的所有 queries 永遠包含至少一個 anchor

**產出：** `anchors[]`（1–2 個）

---

### Stage C — 同義詞展開 + 組合查詢（Synonym Expansion）

對 anchors 使用小型同義詞字典（手寫 50–150 個，不需要大模型）：

```python
SYNONYMS = {
    "monitoring":   ["observability", "tracing", "telemetry", "metrics"],
    "evaluation":   ["evals", "benchmark", "regression", "testing"],
    "agent":        ["tool calling", "orchestration", "workflow", "agentic"],
    "rag":          ["retrieval", "embedding", "rerank", "vector search"],
    "mcp":          ["model context protocol", "mcp server", "mcp tool"],
    "automation":   ["workflow", "pipeline", "no-code", "scripting"],
    "cli":          ["command line", "terminal", "shell", "TUI"],
    "scraping":     ["crawler", "spider", "extraction", "parsing"],
}
```

Query 模板（生成 3–8 條，不要爆量）：

```
{anchor} {keyword}
{anchor} "{exact phrase}"
{anchor} {keyword} github
{anchor} {keyword} mcp         # 若與 MCP 生態相關
{synonym_1} {keyword}
{synonym_2} {keyword}
```

**產出：** `query_set[]`（精簡但有效）

---

## 最小評測方法（A/B，30 分鐘能跑）

不做大架構，但要看改動有沒有真的變好。

### 建立 Golden Set

20–50 條固定 ideas，每條手動標記：
- 2 個「應該出現的關鍵詞」（粗略就好）
- 1 個「應該排在 top_similars 前 3 的專案」（如果知道的話）

### 4 個評測指標

| 指標 | 定義 | 目標 |
|------|------|------|
| **Anchor 命中率** | queries 裡含至少 1 個意圖錨點的比例 | ↑ |
| **垃圾詞比例** | top keywords 裡 stopwords 佔比 | ↓ ≥ 50% |
| **Query 多樣性** | 生成的 queries 是否重複太高（Jaccard similarity < 0.5） | ↑ |
| **Top-3 相關率** | 對每條 idea 前 3 個結果人工打 0/1，看相關佔比 | ↑ ≥ +20% |

### 跑法

```bash
# 跑評測腳本（待實作）
python tests/eval_keywords.py --golden tests/golden_ideas.json

# 輸出
Old extractor: anchor_hit=52%, junk_ratio=38%, top3_rel=44%
New extractor: anchor_hit=89%, junk_ratio=15%, top3_rel=71%  ← 達標
```

---

## Release Criteria（達成任兩項即可發布）

- [ ] Golden set 的「前 3 個結果相關率」提升 **≥ +20%**
- [ ] 垃圾詞比例降低 **≥ 50%**
- [ ] 同一 idea 重跑 3 次（含中文 / 中英混合）query set 更穩（不會每次換一批）

---

## 範圍控制

### ✅ v0.3 做

- Keyword extraction pipeline（Stage A / B / C）
- 同義詞字典（優先覆蓋：MCP、agents、LLMOps、eval、monitoring、RAG）
- 最小 golden set 測試（`tests/golden_ideas.json` + `tests/eval_keywords.py`）
- 中文 / 中英混合輸入的 tokenization 改善

### ❌ v0.3 不做

- Proof Pack（等 v0.4）
- Drift Watch（等 v0.4）
- 任何需要常駐服務的東西
- 任何需要新 UI / 後台的東西
- 大模型 embedding（等 v0.4，先看規則有多夠用）

---

## 檔案影響範圍

```
src/idea_reality_mcp/
└── scoring/
    └── engine.py          ← 主要修改：extract_keywords() 函式
    └── synonyms.py        ← 新增：同義詞字典
tests/
└── golden_ideas.json      ← 新增：評測 golden set
└── eval_keywords.py       ← 新增：評測腳本
└── test_keywords.py       ← 修改：現有 keyword tests 更新
```

不動：`sources/`、`server.py`、`tools.py`、API 介面、MCP 工具簽名。

---

## Release Note 草稿（釘死風格）

```
## [0.3.0] - TBD

### Changed
- **Keyword extraction overhaul** (Stage A/B/C pipeline)
  - Stage A: Hard-filter boilerplate words (ai, tool, platform...)
  - Stage B: Intent anchor detection (monitoring, agent, RAG, MCP...)
  - Stage C: Synonym expansion with curated 100+ term dictionary
- Chinese and mixed-language input now produces stable query sets
- reality_signal variance reduced (same idea = consistent score)

### Improved
- top_similars relevance: +XX% on golden set (front-3 accuracy)
- Junk keyword ratio: -XX%
- Query stability: 3x runs on same idea produce consistent results

### Not in this release
- LLM-powered semantic similarity (v0.4)
- Trend detection (v0.4)
```

---

*Plan written: 2026-02-26. Implementation pending Sean's signal.*
