# WeKnora 极致事件检索规范

> 维度：接口调用 | 定位：**S7「极致触点素材检索」的调用契约**
> 依赖 MCP 服务：`weknora`（工具 `hybrid_search`）；**不可用时静默降级**（见 §5），不影响 S1-S11 核心创作流程
> 上游串联：`../知识库/05_极致事件/00_极致事件总纲.md`（类型层判定）→ `../知识库/05_极致事件/01_极致类型-素材标签映射表.md`（类型↔标签）→ **本文件（检索取条）**
> 变更（2026-09-24）：新建。素材层由「读 md 文件 + 四维标签筛条」切换为「WeKnora 语义检索（主）+ md 源文件（降级）」；实测依据见 §7。

---

## 一、定位：本规范解决什么

| 层 | 文件 | 回答 |
|:--|:--|:--|
| 方法层 | `../知识库/05_极致事件/` 各创作体系 + `../知识库/03_框架节奏/02_冲突叙事套路.md` | 这场**用什么手法**制造极致感 |
| 判定层 | `00_总纲` / `01_映射表` / `02_赛道形态` / `03_评估标准` | 这**是什么**极致、定哪个库 |
| **检索层** | **本文件** | **怎么取到**可参考的事件素材 |
| 素材层 | WeKnora 容器（主）+ `../素材库/*.md`（源与降级） | 取到**什么材料** |

> 🔴 **调用方向自上而下**：方法 → 判定 → 素材。**不得反向**（先看有什么素材再想故事＝素材驱动，会导致内容与账号人设脱节）。

---

## 二、调用：工具与参数

```
工具：hybrid_search（MCP 服务 weknora）
```

| 参数 | 取值 | 说明 |
|:--|:--|:--|
| `kb_id` | `MCN极致事件素材库` | **用库名**（服务自动解析），**禁写死 UUID** |
| `query` | 镜像式五要素问法（见 §3） | 唯一召回杠杆 |
| `match_count` | **3** | 默认 5；压到 3 以控上下文（见 §6） |
| `vector_threshold` | **0.5**（显式传） | 默认恰为 0.5，仍显式传以防版本变化；**不得调高**（提到 0.6 会大面积漏召） |
| `keyword_threshold` | ❌ **不传** | FAQ 库恒为**纯向量**召回，关键词不参与 |

> ⚠️ **禁用 `chat` / `agent_chat` 替代**：二者走 RAG+LLM 总结，会把卡片**摘要化**——而卡片的价值恰在不可概括的细节（原话、微反应、铺垫量级、镜头语言）。**必须用 `hybrid_search` 取卡片原文。**

---

## 三、问法：镜像式五要素

> 核心原则：**问法要与库内标准问的语域同构**（库内标准问即"编导检索意图句"）。

```
「找一条 {①落差对象} {②打破方式} {③具象锚点} 的 {④段落功能} 型事件素材」
```

| 要素 | 来源 | 示例 |
|:--:|:--|:--|
| ① 落差对象 | S7 布位表节点 + S6 场次事件 | 被当场刁难的人 / 等了一整天的人 |
| ② 打破方式 | **方法层**（见 §一 表格左列） | 用一连串专业细节把对方顶回去 |
| ③ 具象锚点 | **必须有**，取自本账号赛道与人设 | 厨房 / 接送孩子 / 试妆镜前 |
| ④ 段落功能 | 布位表四型之一 | 钩子型 / 留人型 / 转粉型 |

### 3.1 三条禁忌（实测支撑）

| 禁忌 | 后果 |
|:--|:--|
| ❌ 纯抽象机制词（"制造反差""引起共鸣"） | **零命中**（实测："一句话让所有人都沉默了，因为谁都没法反驳" → `data: null`） |
| ❌ 赛道词当主检索词（"亲子""美妆"） | 库内 **77.5% 为剧情赛道**，赛道词检索只会落到极少数条且分数低。赛道词只作为③具象锚点的一部分 |
| ❌ 依赖 `CustomMetadata` 过滤 | **不参与过滤**（实测）。想收敛范围只能靠 query 语义 + 检索后复筛 |

---

## 四、返回值判据（三个必知行为）

### 4.1 零命中不是错误

```json
{ "data": null, "success": true }      ← 零命中
```

> 判据：**`success == true 且 data == null` → 零命中**。
> ❌ 不得判为"调用失败"；✅ 不重试、不报错，直接走 §5 降级。

### 4.2 同一张卡内容返回三份

| 字段 | 内容 | 处理 |
|:--|:--|:--|
| `chunk_metadata.answers[0]` | **卡片原文** | ✅ **只读这一份** |
| `content` | 标准问 + 相似问 + Answers 拼接 | ❌ 噪声 |
| `matched_content` | 又一份全文 | ❌ 噪声 |
| `chunk_metadata.standard_question` / `similar_questions` / `negative_questions` | 问法（生产信息） | ❌ 创作时无用 |

### 4.3 复筛与转译

| 步 | 动作 | 判据 |
|:--:|:--|:--|
| 1 | 读 `chunk_metadata.answers[0]` | 只读这一份 |
| 2 | **复筛** | 看卡片 `内容含义` 的落差结构 `[期待A]—被X打破→[结果B]` 是否与本节点**同构**；不同构直接弃。**分数不参与判断**（存在「泛化磁铁卡」会挤占 top1） |
| 3 | 保留 | **≤2 条/节点** |
| 4 | **转译** | 只取落差结构 / 手法类别 / 铺垫量级（短≤3s·中3-10s·长>10s）/ 镜头逻辑；**禁搬**人物·身份·台词·道具（取材不取形，硬规则见 `../创作流程规范.md` 六） |

> 🔴 卡片来自**他人账号**的具体桥段，直接搬用 = 抄袭且违反硬编码禁止规则。转译产物必须换成本账号的具象锚点（人设卡身份 + 本赛道物品），写入大纲时不留原卡痕迹。

---

## 五、降级矩阵（P0）

| 情形 | 判据 | 行为 |
|:--|:--|:--|
| 会话未挂载 weknora MCP | 工具不可用 | 静默回退读 `../素材库/*.md`（**md = 权威源，永不删除**） |
| 服务不可用（容器未启动 / 用户环境无服务） | 调用报错或超时 | 同上 |
| 库不存在 | 返回错误 | 视为未启用，全流程与原行为一致 |
| **零命中** | `success=true 且 data=null` | 退化为「仅用判定层类型子类」指引；**不编造素材**、不重试 |

> **能力探测式**：先试图检索 → 失败/零命中 → 降级。**既不假定可用，也不假定不可用。**
> 与 `SKILL.md`「MCP 不可用时不影响核心创作流程（步骤 1-11）」原则一致。

---

## 六、上下文成本控制

单条卡约 3.5–4KB（因 §4.2 的三份重复）× `match_count`：

| `match_count` | 单次返回 | 一视频 3 节点 | 一视频 5 节点 |
|:--:|:--:|:--:|:--:|
| 5（默认） | ~18KB ≈ 6K tokens | ~18K | ~30K |
| **3（本规范取值）** | **~11KB ≈ 3.5K tokens** | ~10K | ~18K |

**三条控制规则**：

1. **`match_count=3`**，复筛后留 ≤2 —— 不追求多召回（泛化磁铁卡会挤进前列）；
2. **按需检索** —— 只对「规划时想不出具体桥段的节点」检索；**已有明确桥段的节点跳过**（通常一视频 1–3 次，而非每节点必检）；
3. **串行、读后即弃** —— 一次只检索一个节点，读卡 → 转译 → 丢弃原文，不把多节点结果堆积在上下文里。

---

## 七、实测依据（2026-09-24）

| 项 | 结果 |
|:--|:--|
| MCP 可召回 FAQ 库 | ✅ `hybrid_search(kb_id="MCN极致事件素材库", query="被当场刁难的人，用一连串专业细节一步步把对方顶回去")` → 命中 `28325-3`，`score=0.6058205716953738` |
| 与 REST 路径等价 | ✅ 同 query 分数与 `POST /api/v1/knowledge-bases/{KB}/faq/search` **完全一致** |
| `kb_id` 支持库名 | ✅ 无需 UUID |
| 纯抽象问法 | ❌ `data: null`（零命中） |
| 具象机制问法 | ✅ 0.50–0.61 区间，最高 0.6058 |
| 库内库存 | 240 条事件卡；赛道分布剧情 186（77.5%）/ 生活vlog 38 / 旅行 6 / 小剧场 3 / 亲子 3 / 明星娱乐 3 / 搞笑短剧 1；**感官沉浸、氛围沉浸 = 0 条** |

---

## 八、与其他接口的分工

| 路径 | 使用者 | 场景 |
|:--|:--|:--|
| **MCP `hybrid_search`** | AI 会话（S7 执行时） | 创作端单次检索，每视频 1–3 次 |
| REST `/faq/search` | `tools/weknora-ingest/*.py`（项目侧，**不入技能包**） | 生产端：批量导入 + 检索终验；导入通道独占（dry_run 须轮询 completed） |

> 🔴 MCP 服务地址与 API Key 属**环境配置**，只存在于 `~/.workbuddy/mcp.json`（项目侧 `tools/` 文档内），**不得写入本技能任何文件**。