mcn-short-video/技能接入WeKnora实施规范_V1.0_20260924.md

技能接入 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 · 零命中不是错误 —— 实测：

{ "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 工具使用规范）。 内容 = 本文件 §一 + §二 + §三 的成稿版。

草稿（可直接落地）：

# 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 次数