feat(skill): 素材层切换 WeKnora + 方法层接线

定性：素材载体切换（本地 md -> WeKnora 容器），非扩容；驱动方向由素材驱动改为方法驱动。 - 新建 references/接口调用/WeKnora_极致事件检索.md 调用契约：MCP hybrid_search（服务 weknora）/ kb_id 用库名禁写死 UUID / match_count=3 / vector_threshold=0.5 显式 / 不传 keyword_threshold / 零命中判据 success=true 且 data=null / 只读 chunk_metadata.answers[0] / 禁用 chat 与 agent_chat / 复筛<=2条每节点 / 取材不取形转译 / 降级矩阵 / 成本控制 - S7 布位表新增「候选创作方法」列（4->5 列）打通方法层（此前 05_极致事件 6 个方法文件在创作流程中 0 调用） - S7 新增「极致触点素材检索」按需环节 + {material_content} 定死结构 + 极致触点机制自检（[期待A]-被X打破->[结果B]）；输入章节素材库改双层源（主源 WeKnora / 降级 md，md 永不删除） - 6 个方法文件补「素材供给」块（极致标签 / 定库检索入口 / 问法②打破方式填法） - SKILL.md MCP 依赖节增 WeKnora 检索层（含静默降级口径）；S7 小节补调用链；frontmatter updated_at - 索引_知识素材库.md 修正 03/05/06/07/08/11 定性（实为字段结构模板而非素材库）；新增「接口调用」章节 - S9 输入增 {material_cards} + 新增台词毛边三档参考；S11 类1「爆点贯穿」升级为爆点溯源 4 判据，八类35项清单同步 - 根目录补 3 份方案/规范文档 + 2 份 09-23 WeKnora 文档；变更日志归档
2026-09-24 14:47:19 +08:00
1 parent 0165144292
commit 6e4ce9441c
@@ -0,0 +1,245 @@
+# 技能接入 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` 次数 |