maogeigei
6e4ce9441c
定性：素材载体切换（本地 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 文档；变更日志归档
246 lines
13 KiB
Markdown
246 lines
13 KiB
Markdown
# 技能接入 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` 次数 |
|