mcn-short-video/project/短视频脚本创作/V1.0/references/接口调用/WeKnora_极致事件检索.md

WeKnora 极致事件检索规范

维度：接口调用 | 定位：极致事件库的调用契约（两个作用位共用） 依赖 MCP 服务：weknora（工具 hybrid_search）；不可用时静默降级（见 §5），不影响 S1-S11 核心创作流程 上游串联：../知识库/05_极致事件/00_极致事件总纲.md（类型层判定）→ 01_极致类型-素材标签映射表.md（类型↔标签）→ 创作极致事件_通用_内容设计.md（怎么用）→ 本文件（怎么取到） 变更（2026-09-24）：新建。素材层由「读 md 文件 + 四维标签筛条」切换为「WeKnora 语义检索（主）+ md 源文件（降级）」；实测依据见 §7。 变更（2026-09-29）：作用位由 1 个扩展为 2 个 —— 新增 S9 事件素材召回（润色），见 §三之三；S7 填空侧补 取条上限 1-2 个。

---

〇、两个作用位（先看这张表，再决定怎么调）

	作用位① 填空	作用位② 润色
用在	S7：布位定完 → 事件展开前	S9：格式选定 → 写台词前
解决	写不出具体桥段 → 要机制样本	台词概括 → 要表达质感样本
取什么	落差结构 + 手法类别 + 铺垫量级	原话 / 微反应 / 意外 的写法
粒度	按 L1 节点（按需）	按场次（每场 1 条 query，固定执行）
取条上限	🔴 1-2 个/轮（全轮总条数）	≤2 条/场
触发	按需（自评"写不写得出"）	固定执行，不靠自评
方法文件	创作极致事件 §二	创作极致事件 §三

🔴 两者是上下游不是并列：① 按需可能整轮不触发；② 必须独立执行，否则润色环节恒空。 以下 §一~§五 的参数/降级/复筛对两个作用位通用；§三之三单独说 ② 的问法。

---

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

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

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

---

二、调用：工具与参数

工具：hybrid_search（MCP 服务 weknora）

参数	取值	说明
kb_id	MCN极致事件素材库	用库名（服务自动解析），禁写死 UUID
query	情境化事件陈述（见 §3）	唯一召回杠杆
match_count	3	⚠️ 参数名必须是 match_count；写成 top_k/limit/size 会被静默忽略并恒返回 10 条（实测，2026-09-28）
vector_threshold	0.5（必须显式传）	⚠️ 省略该参数不等于 0.5——实测省略时正常业务 query 会直接返回 0 条。另：0 会被当"未设置"处理，低阈值请写 0.1
keyword_threshold	❌ 不传	FAQ 库恒为纯向量召回，关键词不参与

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

🔴 阈值不能提升召回质量（实测）：同一 query 在 thr=0.1~0.5 区间命中数完全相同，阈值只做事后过滤（≥0.65 起才截断）。想召回得准，唯一有效手段是把 query 写好（见 §3）。

---

三、问法：情境化事件陈述

核心原则：把节点写成一件「具体可能发生的事」 —— 卡片正文描述的是画面里发生了什么，query 也应如此，而非"我要什么机制"的抽象请求。

⚠️ 本节的实测结论（2026-09-28，勿高估问法改写的收益）： 用反查法（取库内确有的卡 → 两种问法分别表达同一事件 → 看能否召回自身）实测 35 张卡（覆盖 12 标签）： 旧问法 R@1 = 34/35（97.1%）／新问法 R@1 = 35/35（100%） —— 两者差异在噪声范围内。 结论：当 query 信息足够（把事件讲清楚）时，两种写法都能召回；问法改写的真实收益是「降低编导写出低信息量 query 的概率」，不是「提升召回率」。 真正带来确定性收益的是 §二 的两条参数纠正（match_count / 显式阈值），见 §7.1。

3.1 主写法：把节点翻译成一件具体的事

「{谁} 在 {什么处境} 下 {做了什么具体动作}，结果 {发生了什么」}

要素	来源	说明
谁	S6 场次事件的角色	用角色身份，不用人名
什么处境	S7 布位节点	承接上文的压力/期待
做了什么	方法层（知识库/05_极致事件/ 各创作体系）+ 本账号具象锚点	必须是可拍摄的动作
结果	落差结构 [期待A]—被X打破→[结果B] 的 B 端

示例对照：

写法 A（抽象机制式，易造成信息不足）	写法 B（情境化事件陈述，推荐）
找一条 坚持用真材实料的人 被同行投诉举报 后厨 留人型 事件素材	坚持用真材实料的人被同行举报用死虾，检查的人来了他当场开箱捞活虾，反手把举报人堵回去
找一条 被当场刁难的人 用一连串专业细节把对方顶回去 厨房 留人型 事件素材	客人当众挑刺说食材不新鲜，她一句话不说直接端出后厨原箱让对方当场哑口

✅ 推荐 B 的理由（不是召回率，而是「信息量保障」）：A 式把事件塞进「找一条…型事件素材」的壳里，壳词会稀释事件本身的信息权重，且编导容易只填空心机制词就提交；B 式强制写出「谁+动作+结果」，从形式上杜绝低信息量 query。

3.2 补充写法：结构词加成（仅有明确结构诉求时用）

若本节点明确要"反差/反转/冲突"这类结构，可在事件陈述后追加结构词：

{情境化事件陈述} + 反差 反转 冲突

⚠️ 不要只用结构词（如仅 反差 冲突 打脸）—— 裸词串信息量过低。

3.3 五条禁忌（实测支撑）

禁忌	后果	实测
❌ 纯抽象机制词（"制造反差""引起共鸣""制造极致感"）	零命中或落到泛化卡	data: null
❌ 赛道词当主检索词（"亲子""美妆"）	库内 72.6% 为剧情赛道，赛道词只会落到极少数条且分数低	赛道词只作为具象锚点的一部分
❌ 依赖 CustomMetadata 过滤	不参与过滤	想收敛范围只能靠 query 语义 + 检索后复筛
❌ 只堆关键词串	裸词串召回差	必须成句
❌ query 过短（<40 字）	HTTP 400 报错	需最短长度保护

3.4 分数怎么读（重要认知修正）

🔴 库内相似素材密集，top1~top10 分数带极窄（实测同 query 首尾仅差 0.047，第 1-2 名间隔常在 0.00~0.03）。 → 分数和间隔都不能用来判断"召回对不对"；间隔小 ≠ 召回错，只是该主题素材本身多而相似。 → 正确的动作是：取回后人工复筛「落差结构是否同构」（§4.3），分数只用于粗筛。

3.5 作用位②（S9 润色）的问法：复现该场事件

与 ① 的区别：① 是"我写不出某个节点，帮我找机制"（找）；② 是"这场事件已经定了，别人是怎么说、怎么演的"（复现）。

写法：用该场「场次标题 + 事件概述」拼成一件具体的事，≥40 字。

「{本场角色} 在 {本场空间/处境} 下 {本场核心动作链}，{对方的反应/结果}」

示例（对照 脚本07 场3「看鳃拆穿」）：

❌ 「小学生拆穿老板卖隔夜鱼」
✅ 「一个买鱼的孩子蹲在鱼摊前把鱼嘴掰开，指着鳃的颜色一条条数给老板听，围观的人越来越多，老板本来还在笑，手停在了半空」

逐场次执行：场1 → 场2 → … → 场N，每场 1 条 query。调用次数 = 场次数（典型 5-6 次）。

复筛判据（不同于 ①）：① 看落差结构同构；② 看是否含可借的表达质感 —— 即卡片里有没有 原话（语气词/方言/口误/半截话）、微反应（身体部位+幅度）、意外（计划外打断）。 三者有其一二即可留，≤2 条/场。

⚠️ 零命中同样不是错误：该场留空、不重试、不报错，继续下一场（同 §4.1）。

---

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

4.1 零命中不是错误

{ "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-28）

项	结果
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.64 区间，最高 0.6696
库内库存	631 条事件卡（旧记"450+"已过时）；赛道：剧情 ≈72.6% / 生活vlog ≈27% / 美妆等 ≈0.7%
标签覆盖（已补齐感官向缺口）	12 标签：反差175 / 反常识119 / 价值观冲击93 / 视觉冲击67 / 自嘲反差44 / 细节专业32 / 感官沉浸26 / 氛围沉浸25 / 预见式服务20 / 品质对比19 / 食材极致9 / 难度极限2 —— 感官向 12 标签均有库存（难度极限/食材极致 由 0 补齐为 2/9）

7.1 检索机制实测（2026-09-28 新增，纠正既往认知）

A. 确定性收益 —— 参数纠正（本次优化的主要价值）

项	实测结果	结论
数量参数名	top_k / limit / size / count / k / topK = 3 → 一律返回 10 条；match_count = 3 → 返回 3 条	⚠️ 必须用 match_count，写错会被静默忽略（不报错）
上下文成本收益	同 query：top_k=3 返回 32122 字符 → match_count=3 返回 10087 字符	✅ 省 69% 上下文（此前设计意图从未生效）
省略 vector_threshold	正常业务 query → 返回 0 条	⚠️ 必须显式传 0.5，省略 ≠ 默认 0.5

B. 噪声级差异 —— 问法改写（收益有限，勿高估）

验证法	样本	结果
反查法（库内确有的卡 → 两种问法表达同一事件 → 看能否召回自身）	35 卡 / 12 标签	旧问法 R@1 = 34/35（97.1%）；新问法 R@1 = 35/35（100%） → 差异在噪声范围内
需求法（凭空编导需求）	5 节点	两法 3/5 节点均 0 命中 → 说明测的是「库内有无该素材」，不是「问法优劣」

✅ 问法改写的真实价值 = 「信息量保障」：强制写出「谁+动作+结果」，从形式上杜绝低信息量 query。不是提升召回率。 ⛔ 不要对外宣称「新问法把召回率从 97% 提升到 100%」 —— 那是噪声，且反查法的自然上限本就是 100%。

C. 认知修正（与检索无关，但会误导判断）

项	实测结果	结论
阈值区间作用	thr=0.1/0.2/0.3/0.4/0.5 命中数相同；0.6→3 条；0.65→0 条	阈值只做事后过滤，不能提升质量
分数带宽度	同一 query top1=0.6338 → top10=0.587（首尾差 0.047）；第 1-2 名间隔常 0.00~0.03	⚠️ 分数/间隔不能判优，靠人工复筛落差结构
感官类（F1 型入库）召回	全量 101 卡，仅用事件名查询 → R@1 = 97/97（100%），加不加意图/结构词无差异	F1 型问法本身即完整事件描述，查询已饱和
戏剧类（F3 型入库）召回	纯口语间隔仅 0.054；补结构词/画面词后 ×2.7	间隔指标（非召回率）有改善

🔴 本节最重要的一条：召回能力的天花板由「入库存的是哪一型问法」决定（F1 型 100% vs F3 型需补词），不由 query 写法决定。 库内现状：F3 需求壳句 318 条（50.4%）/ F4 白描陈述 202 条（32.0%）/ F1 编号+后缀 75 条（11.9%）/ F2 30 条（4.8%）/ F5 6 条（1.0%）。 → 编导侧可控的只是「别把 query 写差」；要真正提升召回，须改入库模板（见 §8 待决策项）。

7.2 已知限制

⚠️ 标签偏斜已缓解但结构性问题仍在（P1）：库内戏剧极致 ≈78%、感官极致 ≈22%（旧记 88%/12%），因早期队列按点赞降序导入，而感官类素材（美食/装修/手工）点赞普遍偏低；难度极限 仅 2 条。 影响：检索「手工难度极限」这类极窄感官向 query 时仍可能零命中。 缓解：降级矩阵已覆盖（零命中 → 仅用判定层类型子类指引，不编造）；补采侧走 tools/weknora-ingest/ 定向取批（--target <标签> N）。

⚠️ 真实瓶颈 = 素材覆盖，不是检索技术：需求法实测显示，编导提出的 5 个真实节点需求中 3 个在库内零命中（顾客刁难反杀 / 品质验货 / 身份反差）。问法再优化也召不回不存在的素材。

⚠️ 已知限制：标签偏斜（P1）。库内戏剧极致 ≈88%、感官极致 ≈12%，因队列按点赞降序导入，而感官类素材（美食/装修/手工）点赞普遍偏低。 影响：检索「美食视觉冲击」「装修氛围沉浸」「手工难度极限」这类感官向 query 时会零命中或召回不相关卡。 缓解：降级矩阵已覆盖（零命中 → 仅用判定层类型子类指引，不编造）；补采侧走 tools/weknora-ingest/ 的 --sensory 优先取批流程。

---

八、与其他接口的分工

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

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