技能三副本迭代：路径重构+输出边界铁律+开场口径区分+审计修复

- 路径重构：脚本创作 V1.0/Lite1.0 扁平化（去技能文件夹层），分镜技能迁移至短视频提示词生成/V1.0，旧路径清理 - 输出边界铁律固化：创作流程规范.md 新增「交付物输出边界（通用铁律）」+ S9 输出模板新增「输出边界」块（验收口径=执行约束非输出内容） - 开场钩子铁律三层固化：00_开场/06_编导终审/S9 相关规则 + S5 预设钩子口径区分（前3秒=呈现窗口，3-7秒=开场段总时长） - 帮助文档：新增「从账号分析到脚本创作」跨技能章节（你这样问|我会做什么风格） - mcn-dou-analysis 内嵌副本：红线边界声明+人设卡术语更新（设定分析说明）
2026-08-26 17:28:21 +08:00
1 parent 6fb6dc19ff
commit eada288999
@@ -0,0 +1,96 @@
+# 短视频解析接口（MCP）
+
+通过 MCP 服务 `myai-mcp-production`（正式环境）或 `myai-mcp-test`（测试环境）调用，实现"提交视频 → AI 解析 → 获取拆解与脚本"的流程。
+
+> ⚠️ 原 Python 脚本 `Douyin_Video_Analysis_API.py` 已弃用，全部功能由 MCP 工具替代。
+
+## 前置条件
+
+- MCP 服务已配置并 Trust（详见 `MCP_工具调用规范.md` 3 自动检测与安装引导）
+- 已完成飞书登录（登录检查机制见 `MCP_工具调用规范.md` 4 登录状态检查）
+
+---
+
+## 1) 三个 MCP 工具
+
+| 工具 | 用途 | 必填参数 | 适用场景 |
+|------|------|---------|---------|
+| `upload_douyin_video` | 提交抖音链接做 AI 内容解析入库 | `share_text`（链接/分享文案） | 对标视频是抖音链接时 |
+| `upload_other_video` | 上传本地视频文件做 AI 内容解析入库 | `title` + `file_path` | 对标视频是本地文件时 |
+| `short_video_detail` | 查询解析结果（文案+拆解），判断是否完成 | `id`（详情ID） | 上传后轮询获取解析内容 |
+
+---
+
+## 2) 使用流程
+
+### 场景一：抖音链接解析
+
+```
+步骤1：upload_douyin_video(share_text="https://v.douyin.com/xxxxx")
+       → 返回 detailId（如 "1819"）
+
+步骤2：等待 3-5 分钟（解析中，完成后飞书通知；最多等待 15 分钟）
+
+步骤3：short_video_detail(id="1819")
+       → content 和 analysis 均有内容 = 解析完成
+       → 仍有空值 = 继续等待后重试（每轮间隔 1-2 分钟，超过 15 分钟判定超时）
+```
+
+**`share_text` 支持的格式：**
+- 网页地址：`https://www.douyin.com/video/xxxxx`
+- 分享短链：`https://v.douyin.com/xxxxx`
+- APP 分享全文（自动从中识别链接）
+
+### 场景二：本地视频文件解析
+
+```
+步骤1：upload_other_video(title="视频标题", file_path="C:/Videos/demo.mp4")
+       → 返回 detailId
+
+步骤2：等待 3-5 分钟（最多等待 15 分钟）
+
+步骤3：short_video_detail(id="{detailId}")
+       → 查询解析结果（每轮间隔 1-2 分钟，超过 15 分钟判定超时）
+```
+
+> 注意：`upload_other_video` 的 `file_path` 必须是本地视频文件的绝对路径，不要传抖音链接。
+
+---
+
+## 3) short_video_detail 返回说明
+
+| 字段 | 说明 |
+|------|------|
+| `content` | **视频脚本**（解析完成后填充，可直接用于创作流程参考） |
+| `analysis` | **视频拆解**（结构化分析：钩子/节奏/情绪/选题等） |
+| `title` | 视频标题 |
+| `track` | 赛道分类 |
+| `authorName` | 作者名称 |
+| `likeNum` | 点赞数 |
+| `commentNum` | 评论数 |
+| `shareNum` | 分享数 |
+| `favoriteNum` | 收藏数 |
+| `watchNum` | 播放量 |
+
+**完成判断**：`content` 和 `analysis` 均有内容时视为解析完成；任一为空表示仍在解析中。
+
+---
+
+## 4) 与创作流程的集成
+
+解析结果直接作为步骤3（对标视频拆解）的输入：
+
+| 解析字段 | 对应创作流程用途 |
+|---------|----------------|
+| `content` | 对标视频脚本原文 |
+| `analysis` | 视频结构化拆解（钩子/节奏/情绪等） |
+| `track` | 赛道归类参考 |
+| `watchNum` / `likeNum` | 爆款数据判定 |
+| `authorName` | 对标账号信息 |
+| `title` | 选题方向参考 |
+
+---
+
+## 5) 降级策略
+
+降级触发条件与处理方式见 `MCP_工具调用规范.md` 5 降级策略。视频解析不可用时，步骤3改为用户手动提供视频信息或跳过，核心创作流程不受影响。
@@ -0,0 +1,223 @@
+# Python 调用 Dify chat-messages（后端示例）
+
+本文档用于指导在后端实现真正的 Dify `POST /v1/chat-messages` 调用。
+
+## 脚本入口
+
+- 脚本路径：`scripts/MCN_CYLG_API.py`
+
+## 1) 环境变量配置（必填）
+
+- `DIFY_MCN_CYLG_KEY`: 创意灵感技能专用 KEY（必须，通过系统环境变量设置）
+- `DIFY_MCN_MODEL`: 模型名称（可选，默认为 `gemini`）
+- `DIFY_URL`: Dify 接口基础地址（可选，默认为 `https://mydify.youmanvideo.com/v1`）
+
+> 密钥通过系统环境变量注入，不要在 Skill 目录或代码仓库中存放 `.env.local` 文件。
+
+> ⚠️ 注意：该接口无需 `app_id`，请求体中不要传该字段，否则 CDN 会 400 拦截。另外 curl 发中文 query 也会被 CDN 拦截，推荐用 Python 调用。
+
+---
+
+## 2) 两种调用模式
+
+脚本支持两种子命令模式，分别对应不同的信息获取方式：
+
+| 模式 | 子命令 | `is_online` | 提示词前缀 | 输入参数 | 适用场景 |
+|:---:|:---:|:---:|------|------|------|
+| **联网搜索** | `search` | `1` | `联网搜索` | 创作意图 + 搜索内容 | 查热词释义、最新热点、时事话题、竞品趋势 |
+| **查询事件库** | `recall` | `0` | `查询事件库` | 创作意图 + 搜索标签 + 搜索内容 | 查询事件库中的创作知识、爆款案例、框架模板 |
+
+### 模式一：联网搜索（search）
+
+**输入参数：**
+- `--intent`：创作意图（账号定位、视频目标、赛道方向等）
+- `--content`：需要搜索的内容（热词释义、热点趋势、竞品分析等）
+
+**query 构造格式：**
+```
+联网搜索
+创作意图：{intent}
+搜索内容：{content}
+```
+
+**调用示例：**
+```bash
+$env:DIFY_MCN_CYLG_KEY="app-xxxx"
+python scripts/MCN_CYLG_API.py search `
+  --intent "为萌宠账号写一个猫咪应激的搞笑短视频" `
+  --content "抖音上'耄耋猫'是什么梗，有哪些爆款视频" `
+  --timeout 300
+```
+
+### 模式二：查询事件库（recall）
+
+**输入参数：**
+- `--intent`：创作意图（账号定位、视频目标、赛道方向等）
+- `--tags`：搜索标签（逗号分隔的关键词，用于事件库检索匹配，如 `萌宠,搞笑,应激,反差萌`）
+- `--content`：搜索内容（需要查询的具体事件/知识描述）
+
+**query 构造格式：**
+```
+查询事件库
+创作意图：{intent}
+搜索标签：{tags}
+搜索内容：{content}
+```
+
+**调用示例：**
+```bash
+$env:DIFY_MCN_CYLG_KEY="app-xxxx"
+python scripts/MCN_CYLG_API.py recall `
+  --intent "为萌宠账号写一个猫咪应激的搞笑短视频" `
+  --tags "萌宠,搞笑,应激,反差萌" `
+  --content "猫咪应激反应的表现和常见搞笑场景" `
+  --timeout 300
+```
+
+---
+
+## 3) 接口信息（Dify chat-messages）
+
+- URL: `https://mydify.youmanvideo.com/v1/chat-messages`
+- Method: `POST`
+- Headers：
+  - `Authorization: Bearer <MCN_KEY>`
+  - `Content-Type: application/json`
+
+### 请求体结构
+
+```json
+{
+  "inputs": {
+    "is_think": "0",
+    "is_online": "1",
+    "model": "gemini"
+  },
+  "query": "联网搜索\n创作意图：...\n搜索内容：...",
+  "response_mode": "blocking",
+  "user": "用户唯一标识"
+}
+```
+
+### 参数含义
+
+| 参数 | 位置 | 含义 | search 模式 | recall 模式 |
+|------|:---:|------|:---:|:---:|
+| `is_online` | `inputs` | 是否联网搜索 | 固定 `"1"` | 固定 `"0"` |
+| `is_think` | `inputs` | 是否深度思考（复杂剧情/多反转用 `"1"`） | 可选 | 可选 |
+| `model` | `inputs` | 模型名称（默认 `gemini`） | 可选 | 可选 |
+| `query` | body | 组装后的完整提示词 | 脚本自动构造 | 脚本自动构造 |
+| `response_mode` | body | `blocking`（同步）或 `streaming`（流式） | 默认 `blocking` | 默认 `blocking` |
+| `user` | body | 用户唯一标识 | 可选 | 可选 |
+
+---
+
+## 4) 命令行参数对照
+
+### 公共参数（两种模式通用）
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--is-think` | 是否深度思考 (0/1) | `0` |
+| `--model` | 模型名称 | `gemini` |
+| `--response-mode` | 响应模式 (blocking/streaming) | `blocking` |
+| `--user` | 用户唯一标识 | `wb-skill-001` |
+| `--timeout` | HTTP 超时（秒） | `1200` |
+
+### search 模式专属参数
+
+| 参数 | 说明 | 必填 |
+|------|------|:---:|
+| `--intent` | 创作意图（账号定位、视频目标等） | ✅ |
+| `--content` | 需要搜索的内容（热词释义、热点趋势等） | ✅ |
+
+### recall 模式专属参数
+
+| 参数 | 说明 | 必填 |
+|------|------|:---:|
+| `--intent` | 创作意图（账号定位、视频目标等） | ✅ |
+| `--tags` | 搜索标签（逗号分隔关键词） | ✅ |
+| `--content` | 需要查询的事件/知识描述 | ✅ |
+
+---
+
+## 5) 返回值说明
+
+脚本输出 API 原始 JSON 响应，关键字段：
+
+| 字段 | 含义 |
+|------|------|
+| `answer` | LLM 生成的回答正文（创作流程中实际使用的内容） |
+| `conversation_id` | 会话 ID，传回可续接多轮对话 |
+| `metadata.usage` | token 消耗与费用 |
+| `metadata.retriever_resources` | RAG 检索引用资源（recall 模式下可能有值） |
+
+---
+
+## 6) 调试示例（终端测试，可选）
+
+```bash
+# 联网搜索（search）
+curl -X POST 'https://mydify.youmanvideo.com/v1/chat-messages' \
+  --header "Authorization: Bearer $DIFY_MCN_CYLG_KEY" \
+  --header 'Content-Type: application/json' \
+  --data-raw '{
+    "inputs": { "is_think": "0", "is_online": "1", "model": "gemini" },
+    "query": "联网搜索\n创作意图：为萌宠账号写猫咪应激搞笑短视频\n搜索内容：抖音耄耋猫是什么梗",
+    "response_mode": "blocking",
+    "user": "demo-user-001"
+  }'
+
+# 查询事件库（recall）
+curl -X POST 'https://mydify.youmanvideo.com/v1/chat-messages' \
+  --header "Authorization: Bearer $DIFY_MCN_CYLG_KEY" \
+  --header 'Content-Type: application/json' \
+  --data-raw '{
+    "inputs": { "is_think": "0", "is_online": "0", "model": "gemini" },
+    "query": "查询事件库\n创作意图：为萌宠账号写猫咪应激搞笑短视频\n搜索标签：萌宠,搞笑,应激,反差萌\n搜索内容：猫咪应激反应的表现和搞笑场景",
+    "response_mode": "blocking",
+    "user": "demo-user-001"
+  }'
+```
+
+---
+## 7) 选题搜索的内容设计原则（三层递进）
+
+> ⚠️ **搜索输入决定选题边界。** `content` 和 `tags` 中的行为词会锁定 Dify 的输出方向。
+
+### content 字段设计规则
+
+| 规则 | 说明 |
+|------|------|
+| ❌ 禁止 | `content` 中出现账号核心行为词超过 1 次（如账号核心行为是做饭，则"做饭""美食""下厨"不应同时出现） |
+| ✅ 第1层 | 可含 1 次核心行为词，确认框架内可能性 |
+| ✅ 第2层起 | 去掉所有行为词，改用**场景词 + 互动类型词**（如"露营 亲子互动 户外挑战"） |
+| 🔄 第3层 | 更换视角关键词（如"露营教育""露营角色反转""露营环保"） |
+
+### 反例 vs 正例（以亲子美食账号搜"露营"为例）
+
+```bash
+# ❌ 第1层就把"做饭""美食"写死，Dify 永远在做饭框架里打转
+--content "露营美食爆款选题 亲子露营做饭 小学生野外做饭"
+
+# ✅ 第1层：框架内探索（可含1次做饭）
+--content "亲子露营爆款选题 露营美食创意 小学生露营内容"
+
+# ✅ 第2层：跳出框架（去掉做饭，场景驱动）
+--content "亲子露营互动创意 露营意外搞笑 户外亲子挑战 露营趣味内容"
+
+# ✅ 第3层：近一步跳出框架（换视角）
+--content "露营教育亲子对话 露营角色反转 无电子设备露营 露营环保正能量"
+```
+
+### tags 字段同理（recall 模式）
+
+```bash
+# ❌ 标签自带锁定
+--tags "露营,美食,亲子,反差萌,户外做饭"
+
+# ✅ 场景驱动标签
+--tags "露营,亲子,互动,挑战,搞笑,教育,情感,户外"
+```
+
+> 该原则同步写入 `创作流程/5_生成短视频选题.md` 处理规则「联网搜索策略 — 三层递进」。
@@ -0,0 +1,140 @@
+# MCP 工具调用规范
+
+本文件是 MCP 依赖配置、安装引导、登录检查、降级策略的**单一权威源**。其他文件（SKILL.md、Douyin_Video_Analysis.md 等）只做指针引用，不重复内容。
+
+---
+
+## 1) 依赖的 MCP 服务
+
+| 服务名 | 配置文件 | 环境标识 | API 地址 | 用途 |
+|--------|---------|:---:|---------|------|
+| `myai-mcp-production` | `scripts/mcp-config.json` | 正式 | `https://maiya-trans.youmanvideo.com/api` | 创意灵感搜索、抖音/本地视频解析等 |
+| `myai-mcp-test` | `scripts/mcp-config.json` | 测试 | `http://maiya-trans.test.youmanvideo.com/api` | 开发调试用，数据非生产数据 |
+
+---
+
+## 2) 环境判定与安装策略
+
+复用技能已有的部署检测机制（路径含 `MCNVideo AI` = 开发环境）。
+
+| 环境 | 判定条件 | 安装内容 |
+|------|---------|---------|
+| **开发环境** | Skill 根目录路径包含 `MCNVideo AI` | `myai-mcp-production` + `myai-mcp-test`（推荐两个都装，可选只装正式） |
+| **非开发环境** | 部署到其他路径（组员机器、服务器） | 只装 `myai-mcp-production`（正式），不装测试环境 |
+
+---
+
+## 3) 自动检测与安装引导流程
+
+**触发时机：用户首次提问（技能被触发）时即检测并提醒安装，不等到真正用到 API 功能才提示。**
+
+| 触发点 | 行为 |
+|--------|------|
+| **用户首次提问**（技能触发，无论问什么） | 立即检测 MCP 可用性 → 未安装 → 主动提醒（步骤2-4） |
+| **创作流程步骤3 对标拆解 / 步骤5 创意灵感** | 若首次提问已提醒过 → 不重复提醒，直接使用或降级；若未提醒过 → 按本流程提醒 |
+| **直接工具调用**（"解析这个视频/查账号设定"） | 未安装 → 按本流程提醒 |
+
+按以下流程处理：
+
+1. **检测**：检查 `myai-mcp-production` 的 MCP 工具是否在可用列表中。可用 → 跳到 [4 登录检查]；不可用 → 进入步骤2
+2. **判定环境 + 提示**：
+   - **首次提问（轻量提醒，不打断创作）**：
+     > 本技能部分功能（对标视频解析 / 创意灵感 / 账号设定查询）依赖 MCN MCP 服务。是否现在安装？暂时不需要可跳过，不影响核心创作流程，用到时会再次提醒。
+   - **创作中需用 API 功能 · 开发环境**：
+     > 本技能的 MCN API 功能需要安装 MCP 服务。开发环境可同时安装正式环境和测试环境。是否自动配置？
+     > - 两个都装（推荐）：正式环境用 `myai-mcp-production`，测试环境用 `myai-mcp-test`
+     > - 只装正式环境
+   - **创作中需用 API 功能 · 非开发环境**：
+     > 本技能的 MCN API 功能需要安装 `myai-mcp-production` MCP 服务。是否自动配置？
+3. **用户同意 → 前置检查运行环境 → 自动安装**：
+   - **部署预检（先做，按顺序）**：
+     1. **运行时版本**：检查 Node.js（`node --version`）和 Python（`python --version`）是否已安装。缺失则先引导安装对应运行时再继续——`npx` 型 MCP 依赖 Node.js，`python` 型 MCP 依赖 Python，缺失会导致 MCP 安装/启动失败。
+     2. **npm 缓存权限（macOS 高发坑，必须查）**：`npx` 型 MCP 首次运行需写入 npm 缓存（默认 `~/.npm` 的 `_npx`/`_cacache`）。若缓存目录里有 **root 权限文件**（常见于曾用 sudo 装过包、系统迁移/重装后遗留），npx 无权限写入 → MCP 启动静默失败。典型症状：包能正常下载（源没问题）、配置也写入了，但 MCP 一直连不上/不出现。
+        - **检查**：`npm config get cache` 确认缓存目录（默认 `~/.npm`）；`find ~/.npm -user root 2>/dev/null | head` 查看是否有 root 文件
+        - **处理**：缓存可重建，直接清理（目录本身归用户所有，**无需 sudo**）：`rm -rf ~/.npm/_npx ~/.npm/_cacache`，下次 npx 运行自动重建
+        - **注意**：只清缓存目录，**不要**动 `~/.npmrc`（含 registry 配置）和全局已安装的包
+     3. **（可选）npm 源**：国内网络确认 registry 已配镜像（`npm config get registry`，如 `https://registry.npmmirror.com`）避免拉包超时。但镜像**不是**启动失败的根因，排查顺序永远是 1 → 2 → 3。
+   - 读取 `scripts/mcp-config.json`
+   - 读取用户现有的 `~/.workbuddy/mcp.json`（如不存在则创建）
+   - **开发环境**：将 `myai-mcp-production` + `myai-mcp-test` 两个服务合并写入（保留已有服务，不覆盖）
+   - **非开发环境**：只将 `myai-mcp-production` 服务合并写入（保留已有服务，不覆盖）
+   - 提示用户：「配置已写入。请打开右上角「连接器管理」页面，找到 `myai-mcp-production`（开发环境额外找到 `myai-mcp-test`），分别点击 **Trust** 启用。启用后重新发起任务即可。」
+4. **用户拒绝/跳过 → 降级**：
+   - 告知用户：「MCN API 功能将不可用，脚本创作核心流程（步骤1-11）不受影响，可正常使用。之后实际用到这些功能时会再次提醒安装。」
+   - 继续执行不依赖 MCP 的创作流程
+
+---
+
+## 4) 登录状态检查
+
+MCP 工具可用后，调用任何 MCP 工具前须先检查飞书登录状态。
+
+**检查频率：每天检查一次**（当天缓存结果，当天内不重复检查）
+
+**检查流程：**
+
+```
+1. auth_status()
+   → 已登录 → 缓存状态，继续执行 MCP 调用
+   → 未登录 → 进入步骤2
+
+2. feishu_login()
+   → 自动打开浏览器进行飞书 OAuth 授权
+   → 等待用户完成授权（浏览器自动回调）
+
+3. auth_status()
+   → 已登录 → 缓存状态，继续执行 MCP 调用
+   → 仍未登录 → 进入步骤4（兜底）
+
+4. 提示用户：
+   > 自动登录未成功，请手动提交授权码。
+   > 从浏览器地址栏复制回调链接或授权码，粘贴提供给我。
+   submit_auth_code(code_or_url="用户提供的值")
+
+5. auth_status()
+   → 已登录 → 缓存状态，继续执行 MCP 调用
+   → 仍未登录 → 告知用户登录失败，进入降级流程
+```
+
+**缓存规则：**
+- 缓存粒度：按天，每天首次调用时检查一次
+- 缓存失效：跨天自动重新检查
+- 缓存位置：运行时内存（不需要写文件）
+
+---
+
+## 5) 降级策略
+
+| 功能 | MCP 可用时 | MCP 不可用时 |
+|------|-----------|-------------|
+| 步骤3 对标视频拆解 | 登录检查 → MCP 调用视频解析工具 → 等待3-15分钟 → 轮询结果 | 用户提供视频信息或跳过 |
+| 步骤5 选题创意灵感 | 登录检查 → MCP 调用创意灵感 API（联网搜索/事件库） | 用户手动提供选题方向 |
+| 步骤1-2、4、6-11 | 不依赖 MCP，正常执行 | 不受影响 |
+
+**降级触发条件：**
+
+| 降级原因 | 处理方式 |
+|---------|---------|
+| MCP 未安装/未 Trust | 引导安装（见 [3 自动检测与安装引导流程](#3-自动检测与安装引导流程)） |
+| 登录失败（`auth_status` 三次重试后仍未登录） | 告知用户手动登录，跳过 API 功能 |
+| 服务异常 | 告知用户稍后重试，跳过 API 功能 |
+| 视频解析超时（超过 15 分钟） | 告知用户超时，可稍后用 detailId 手动查询 |
+
+---
+
+## 6) MCP 工具清单
+
+| 工具 | 用途 | 必填参数 | 适用场景 |
+|------|------|---------|---------|
+| `auth_status` | 检查当前登录状态是否有效 | 无 | 每天首次调用 MCP 前检查 |
+| `feishu_login` | 飞书 OAuth 授权登录，打开浏览器自动完成 | 无 | 未登录时自动触发 |
+| `submit_auth_code` | 手动提交飞书回调的授权码（自动登录失败时兜底） | `code_or_url` | 自动登录失败时兜底 |
+| `logout` | 退出登录，清除本地凭证 | 无 | 切换账号时 |
+| `upload_douyin_video` | 提交抖音链接做 AI 内容解析入库 | `share_text`（链接/分享文案） | 对标视频是抖音链接时 |
+| `upload_other_video` | 上传本地视频文件做 AI 内容解析入库 | `title` + `file_path` | 对标视频是本地文件时 |
+| `short_video_detail` | 查询解析结果（文案+拆解），判断是否完成 | `id`（详情ID） | 上传后轮询获取解析内容 |
+| `list_hot_accounts` | 列出全部达人账号 | 无 | 查看达人库 |
+| `hot_account_detail` | 查看某个账号完整详情 | `account`（账号名或ID） | 对标账号拆解 |
+| `current_user` | 获取当前登录用户完整资料 | 无 | 确认登录身份 |
+
+> 视频解析工具的详细使用流程见 `Douyin_Video_Analysis.md`。