# 技能接入 WeKnora 实施规范 V1.0

> 日期：2026-09-24 ｜ 类型：技术实现方案（**未改动技能文件**，待授权）
> 配套：`极致事件素材接入创作流程方案_V1.1_20260924.md`（架构与范围）
> 本文件回答"**技能具体怎么调 WeKnora**"，含可直接复制进技能文件的调用契约草稿。

---

## 〇、结论：走 MCP 工具，不写脚本

| 接入方式 | 结论 | 依据（2026-09-24 实测） |
|:--|:--|:--|
| **MCP 工具 `hybrid_search`** | ✅ **主路径** | 会话内可直接调用，零脚本；`kb_id` 支持**库名**；已实测可召回 FAQ 条目，分数与 REST 完全一致 |
| REST 脚本 `/faq/search` | 仅批量场景 | 需 py + Key + 代理处理；用于**生产端**（批量导入/终验），不是创作端 |

> **实测证据**：`mcp__weknora__hybrid_search(kb_id="MCN极致事件素材库", query="被当场刁难的人，用一连串专业细节一步步把对方顶回去")` → 命中 `28325-3`，`score=0.6058205716953738`，`chunk_type=faq`，与 REST `/faq/search` 同 query 同分。

### 0.1 两条路径的分工

| | MCP `hybrid_search`（创作端） | REST `/faq/search`（生产端） |
|:--|:--|:--|
| 使用者 | AI 会话（S7 执行时） | `tools/weknora-ingest/*.py` 批量脚本 |
| 频次 | 每视频 1-3 次（按节点） | 每批 5 视频 + 15 条终验 |
| 依赖 | `mcp.json` 的 `weknora` 服务 + 已授信 | python + 显式 `unset` 代理 |
| 留痕 | 无（会话内） | 日志落 `out/*.txt` |
| 冲突 | 无 | 导入通道独占（dry_run 必须轮询 completed） |

---

## 一、调用契约（可直接复制进技能文件）

### 1.1 工具与参数

```
工具：hybrid_search（MCP 服务 weknora）
必填：kb_id  = "MCN极致事件素材库"      ← 用库名，禁写死 UUID
      query  = 镜像式五要素问法（见 §1.3）
建议：match_count      = 3              ← 默认 5，降到 3 控上下文（见 §三）
      vector_threshold = 0.5            ← 默认恰为 0.5，但仍显式传
```

| 参数 | 实测行为 | 技能侧写法 |
|:--|:--|:--|
| `kb_id` | **支持库名或 UUID**，自动解析 | 写库名 `MCN极致事件素材库`（不硬编码 UUID） |
| `vector_threshold` | 默认 **0.5**（与要求一致） | 显式传 `0.5`（防版本变化） |
| `match_count` | 默认 5 | 传 **3**（返回体很大，见 §三） |
| `keyword_threshold` | **对 FAQ 库无效** | ❌ 不传（FAQ 恒为**纯向量**召回，关键词不参与） |

### 1.2 返回值判据（三个必须写进技能的坑）

**坑 1 · 零命中不是错误** —— 实测：

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

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

**坑 2 · 同一张卡内容返回三份** —— 每条命中同时出现在：

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

> 创作端**只读 `chunk_metadata.answers[0]`**（= 卡片原文），其余字段视为噪声。读卡 → 提取 → 丢弃，不累积。

**坑 3 · `chat` 不能替代 `hybrid_search`** —— `chat`（RAG+LLM 总结）会把卡片**摘要化**，而卡片的价值恰在不可概括的细节（原话、微反应、铺垫量级、镜头语言）。→ **S7 用 `hybrid_search` 取原文，禁用 `chat`/`agent_chat`。**

### 1.3 问法：镜像式五要素

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

| 要素 | 来源 |
|:--:|:--|
| ① 落差对象 | S7 布位表节点 + S6 场次事件 |
| ② 打破方式 | **方法层**（预期反转·道具误导 / 错位化 / 荒诞化…）+ 判定层类型 |
| ③ 具象锚点 | **必须有**，取自本账号赛道与人设 |
| ④ 段落功能 | 钩子型 / 留人型 / 转粉型 / 传播型 |

**实测对照**（同 threshold=0.5）：

| 问法 | 结果 |
|:--|:--|
| 「一句话让所有人都沉默了，因为谁都没法反驳」（纯抽象） | ❌ **零命中**（`data: null`） |
| 「被当场刁难的人，用一连串专业细节一步步把对方顶回去」（具象机制） | ✅ 0.6058 对口 |
| 「找一条对方还没开口就已经做好的极致事件素材」（镜像库内标准问形态） | ✅ 命中 |

**禁忌**：纯抽象机制词（零命中）／赛道词当主检索词（库内 77.5% 为剧情赛道，会落到极少数条且低分）／依赖 `CustomMetadata` 过滤（不参与过滤）。

### 1.4 结果处理：读卡 → 复筛 → 转译

| 步 | 动作 | 判据 |
|:--:|:--|:--|
| 1 | 读 `chunk_metadata.answers[0]` | 只读这一份 |
| 2 | 复筛 | 看 `内容含义` 的落差结构是否与本节点**同构**；不同构直接弃（分数不参与判断，泛化磁铁卡会挤占 top1） |
| 3 | 保留 | **≤2 条/节点** |
| 4 | 转译 | 只取落差结构 / 手法类别 / 铺垫量级 / 镜头逻辑；**禁搬**人物·台词·道具 |

---

## 二、降级矩阵（P0）

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

> 设计定位：**WeKnora 是可选增强层**，与 SKILL.md「MCP 降级不影响核心创作流程（S1-S11）」一致。
> ⚠️ **md 素材源文件永不删除** —— 用户环境无 WeKnora 服务，删则用户环境零素材。

---

## 三、上下文成本控制（实测推导）

单次 `hybrid_search` 返回体 = 每条卡约 3.5-4KB（**因三份重复**）× `match_count`：

| `match_count` | 单次返回 | 一视频 3 个节点 | 一视频 5 个节点 |
|:--:|:--:|:--:|:--:|
| 5（默认） | ~18KB ≈ 6K tokens | ~18K tokens | ~30K tokens |
| **3（建议）** | **~11KB ≈ 3.5K tokens** | ~10K tokens | ~18K tokens |
| 2 | ~7KB ≈ 2.3K tokens | ~7K tokens | ~12K tokens |

**三条控制规则**：

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

---

## 四、技能文件改动落点（每条：改哪个文件、加什么）

### 4.1 新建 `references/接口调用/WeKnora_极致事件检索.md`

> 定位：与 `MCP_工具调用规范.md` 同级（它就是一份 MCP 工具使用规范）。
> 内容 = 本文件 §一 + §二 + §三 的成稿版。

**草稿（可直接落地）**：

```markdown
# WeKnora 极致事件检索规范

> 定位：S7「极致触点素材检索」的调用契约。与 `知识库/05_极致事件/01_极致类型-素材标签映射表.md`
> （类型→标签）串联使用：方法定手法 → 类型层定判定 → 本规范定检索 → 素材库取条。
> 依赖：MCP 服务 `weknora`（`hybrid_search`）；不可用时静默降级（见 §4）。

## 1. 调用
工具 `hybrid_search`：
- `kb_id` = `MCN极致事件素材库`（用库名，禁写死 UUID）
- `query` = 镜像式五要素问法（§2）
- `match_count` = 3 ｜ `vector_threshold` = 0.5（显式）
- 禁用 `keyword_threshold`（FAQ 库恒为纯向量召回）

## 2. 问法：镜像式五要素
「找一条 {落差对象} {打破方式} {具象锚点} 的 {段落功能} 型事件素材」
- 落差对象 ← 布位表节点 / S6 场次事件
- 打破方式 ← 方法层（预期反转·道具误导 / 错位化 / 荒诞化…）
- 具象锚点 ← 本账号赛道与人设（**必须有**）
- 段落功能 ← 钩子型 / 留人型 / 转粉型 / 传播型
禁忌：纯抽象机制词（实测零命中）；赛道词作主检索词；依赖 metadata 过滤。

## 3. 返回值判据
- 只读 `chunk_metadata.answers[0]`（卡片原文）；其余字段为噪声，同一内容重复出现三份
- **`success=true 且 data=null` = 零命中，不是调用失败** → 走降级，不重试
- 复筛：看 `内容含义` 落差结构是否与节点同构；保留 ≤2 条/节点
- 转译：只取落差结构 / 手法类别 / 铺垫量级 / 镜头逻辑；**禁搬**人物·台词·道具（取材不取形）

## 4. 降级
MCP 未挂载 / 服务不可用 / 库不存在 / 零命中 → 静默回退读 `references/素材库/*.md`
（md 为权威源，永不删除）；零命中时退化为「仅用类型层子类指引」，**不编造素材**。

## 5. 成本控制
`match_count=3`；**按需检索**（只检想不出桥段的节点，通常一视频 1-3 次）；
串行、读后即弃，不堆积多节点结果。
```

### 4.2 `SKILL.md` —— 两处

| 位置 | 加什么 |
|:--|:--|
| 「MCP 依赖（摘要）」章节 | 增一条：**WeKnora 检索层**（服务 `weknora` / 工具 `hybrid_search` / 库 `MCN极致事件素材库`），不可用降级不影响 S1-S11 |
| S7 小节目的行 | 「按知识库/05_极致事件 指引调取素材」补全调用链：**类型层 →(映射表)→ 方法层 →(检索规范)→ 素材（WeKnora 检索 + md 源降级）** |

### 4.3 `references/创作流程/7_生成短视频大纲.md` —— 四处

| 位置 | 加什么 |
|:--|:--|
| 「输入」素材库条目 | 素材库定义改**双层源**：WeKnora 检索（主）+ `references/素材库/*.md`（源与降级） |
| 「极致触点节点布位」表 | **新增一列「候选创作方法」**（钩子型→极致行为四分类；留人型→预期反转/冲突套路；转粉型→克制/荒诞化/抽象化；传播型→无厘头/专属符号） |
| 处理规则**新增第五步**「极致触点素材检索」 | 引用 `接口调用/WeKnora_极致事件检索.md`；写明按需触发 + `match_count=3` + 复筛 ≤2 + 转译 |
| User Prompt 的 `{material_content}` | 换成定死结构（见 4.4）；深度自检增「极致触点机制自检」：每个 L1 节点须写得出 `[期待A]—被X打破→[结果B]` |

### 4.4 `{material_content}` 定死结构

```
【素材内容 · 来源：极致事件机制检索】
（检索不可用时此段留空，按 references/素材库/ 源文件填充）

■ 节点① 开场钩子（0-3s）｜钩子型｜方法：{极致行为·感官刺激}｜机制来源：{卡编号 或 类型层子类}
  · 落差结构：[期待A] —被X打破→ [结果B]
  · 手法与铺垫量级：{手法类别} ＋ 铺垫 短/中/长
  · 拍摄参考：{镜头语言} ｜ {画面风格}
  · 本账号转译：{换成本账号人/物/场景后的桥段}
```

> ⚠️ 注入内容**不含原卡人物名与台词**（转译已在读卡后完成），避免污染 S9/S10/S11 与产出文件。

### 4.5 其余落点

| 文件 | 加什么 |
|:--|:--|
| `references/索引_知识素材库.md` | ① 修正 03/05/06/07/08/11 定性（"字段结构模板"非"素材库"）；② 补检索规范条目 |
| `references/创作流程/9_生成短视频脚本.md` | 输入增补 `{material_cards}`；补「台词毛边三档参考」（原话/微反应/意外） |
| `references/创作流程/11_脚本检查和诊断.md` | 「爆点贯穿」升级为爆点溯源三判据 |
| 6 个方法文件 | 各补一行「素材供给：本方法需用极致标签 X / 到 Y 取 Z」 |
| **不入技能包** | REST 脚本与 Key 只留 `tools/weknora-ingest/`；技能内**只写 MCP 契约与降级** |

---

## 五、环境矩阵

| 环境 | `mcp.json` 有 weknora | 服务 31607 | 实际行为 |
|:--|:--:|:--:|:--|
| **开发机**（当前） | ✅ | ✅ Up 4 days | 检索生效 |
| 用户环境（技能软链分发） | 取决于用户是否配 | ❌ 无 | 调用失败 → **静默降级读 md** |
| 未来若在用户机部署 WeKnora | 需配 | 需起 | 检索生效（技能无需改动） |

**因此技能文案必须写成"能力探测式"**：先试图检索 → 失败/零命中 → 降级，而非"假定可用"或"假定不可用"。

---

## 六、待验证项（落地前建议补测）

| # | 项 | 方法 |
|:--:|:--|:--|
| 1 | 载体类素材（21 条菜品）进同容器后，与事件卡是否互相挤占 | 补问法导入后，用「找一道深夜吃很治愈的面」测是否召回菜卡 |
| 2 | `match_count=3` 对小众赛道是否够用（亲子/沉浸类库存极少） | 用亲子问法实测 top3 质量 |
| 3 | 零命中率在真实 S7 场景下的比例 | 按镜像问法跑 10 组节点级问法，统计 `data:null` 次数 |