refactor(skill): 主技能 subskill 目录更名 subskills（09-02 用户要求）

- V1.0/subskill/ → V1.0/subskills/（browser-harness/mcn-dou-analysis/mcn-script-review/mcn-video-prompt，git 识别 R100 纯重命名保留历史） - 路径说明同步：V1.0/SKILL.md（96/105行）、Lite1.0/SKILL.md（66行）、mcn-dou-analysis/SKILL.md 红线行、操作规范.md 159/175行、mcn-work-shop app.js SKILL_HINT_ACCOUNT - 用户环境 ~/.workbuddy/skills/短视频脚本创作/ 与源仓库 V1.0 同 inode（junction），自动同步无需单独改 - mcn-dou-analysis 内部 subskills/nuwa-skill-main 为正常结构不受影响
2026-09-02 10:36:23 +08:00
1 parent 19bf4949a9
commit f1f6288b7b
@@ -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,134 @@
+# MCP 工具调用规范
+
+本文件是 MCP 依赖配置、安装引导、登录检查、降级策略的**单一权威源**。SKILL.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) 环境判定与安装策略
+
+| 环境 | 判定条件 | 安装内容 |
+|------|---------|---------|
+| **开发环境** | Skill 根目录路径包含 `MCNVideo AI` 或 `MCNDouAnalysis` | `myai-mcp-production` + `myai-mcp-test`（推荐两个都装，可选只装正式） |
+| **非开发环境** | 部署到其他路径（组员机器、服务器） | 只装 `myai-mcp-production`（正式），不装测试环境 |
+
+---
+
+## 3) 自动检测与安装引导流程
+
+**触发时机：执行工作流前（视频解析前）即检测并提醒安装。**
+
+| 触发点 | 行为 |
+|--------|------|
+| **Step 4 视频解析**（upload_douyin_video） | 检测 MCP 可用性 → 未安装 → 提醒安装 |
+| **Step 7 账号数据分析**（补解析入选视频） | 若已提醒过 → 不重复，直接使用或降级；若未提醒过 → 按本流程提醒 |
+
+按以下流程处理：
+
+1. **检测**：检查 `myai-mcp-production` 的 MCP 工具是否在可用列表中。可用 → 跳到 [4 登录检查]；不可用 → 进入步骤2
+2. **判定环境 + 提示**：
+   - **开发环境**：
+     > 本工作流需要 MCN MCP 服务进行视频解析。开发环境可同时安装正式环境和测试环境。是否自动配置？
+     > - 两个都装（推荐）：正式环境用 `myai-mcp-production`，测试环境用 `myai-mcp-test`
+     > - 只装正式环境
+   - **非开发环境**：
+     > 本工作流需要 `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 MCP 功能将不可用。Step 4 视频解析将无法执行，功能四按拆解降级规则处理。」
+
+---
+
+## 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 不可用时 |
+|------|-----------|-------------|
+| Step 1 获取账号信息 | 浏览器抓取（不依赖 MCP） | 不受影响 |
+| Step 2 获取视频列表 | 浏览器抓取（不依赖 MCP） | 不受影响 |
+| Step 4 视频解析 | 登录检查 → `upload_douyin_video` → 等待3-5分钟 → `short_video_detail` 轮询 | 无法执行，需用户手动提供解析数据或安装 MCP |
+| Step 7 账号数据分析（补解析） | 登录检查 → 补解析入选视频（最好/最差） → 逐条拆解 | 无法补解析：无解析视频**不进入逐条拆解**，只做数据层分析（拆解降级规则见 `references/feature/04_分析视频数据.md` 7.4） |
+| Step 3/5/6 | 不依赖 MCP，正常执行 | 不受影响 |
+
+**降级触发条件：**
+
+| 降级原因 | 处理方式 |
+|---------|---------|
+| MCP 未安装/未 Trust | 引导安装（见 [3 自动检测与安装引导流程](#3-自动检测与安装引导流程)） |
+| 登录失败（`auth_status` 三次重试后仍未登录） | 告知用户手动登录，视频解析无法执行 |
+| 服务异常 | 告知用户稍后重试，视频解析无法执行 |
+| 视频解析超时（超过 25 分钟） | 按 SKILL.md 视频补充规则，用排名下一位视频替补 |
+
+---
+
+## 6) MCP 工具清单
+
+| 工具 | 用途 | 必填参数 | 适用场景 |
+|------|------|---------|---------|
+| `auth_status` | 检查当前登录状态是否有效 | 无 | 每天首次调用 MCP 前检查 |
+| `feishu_login` | 飞书 OAuth 授权登录，打开浏览器自动完成 | 无 | 未登录时自动触发 |
+| `submit_auth_code` | 手动提交飞书回调的授权码（自动登录失败时兜底） | `code_or_url` | 自动登录失败时兜底 |
+| `logout` | 退出登录，清除本地凭证 | 无 | 切换账号时 |
+| `upload_douyin_video` | 提交抖音链接做 AI 内容解析入库 | `share_text`（链接/分享文案） | Step 4 视频解析提交 |
+| `upload_other_video` | 上传本地视频文件做 AI 内容解析入库 | `title` + `file_path` | 对标视频是本地文件时 |
+| `short_video_detail` | 查询解析结果（文案+拆解），判断是否完成 | `id`（详情ID） | Step 4 轮询获取解析内容 |
+| `current_user` | 获取当前登录用户完整资料 | 无 | 确认登录身份 |
+
+> ⚠️ **工具边界（数据源红线）**：MCP 服务另暴露 `list_hot_accounts`（内部账号列表）、`hot_account_detail`（内部账号详情）等工具（工具命名 hot_accounts 有误导性，实为 **MCN 内部维护的达人账号库**，含人设/赛道/标签/代表作，非抖音页面实时数据）——**仅作内部账号库查询，禁止作为功能一「获取账号信息」的数据源**。功能一数据源 = 浏览器访问抖音账号主页（**浏览器优先，如无必要不用查 MCP 达人信息**；浏览器无法访问时才可兜底并注明来源）。
@@ -0,0 +1,21 @@
+# 本地接口调用规范（功能三写库用）
+
+> 本文件记录功能三（提炼账号设定）写库时调用的本地 MCN 接口规范。
+> 来源：从 `references-add/铁律避坑规则/账号设定执行避坑.md` 的「快速参考」沉淀而来，独立成文件便于复用。
+
+## 一、接口基地址判定（按优先级）
+
+1. `$env:DSH_WEB_URL`（当前为 `http://127.0.0.1:3080`）
+2. 为空则依次试 `http://127.0.0.1:3081`、`http://127.0.0.1:3080`
+
+## 二、接口清单
+
+| 接口 | 方法 | 用途 | 关键参数 |
+|------|------|------|---------|
+| `/mcn/api/account/videos` | GET | 获取账号视频列表/账号信息 | `accountId` + `pageSize` |
+| `/mcn/api/external/import` | POST | 人设卡/解析结果写库（data 模式） | `{"data":{"analyses":[{"type":"persona","account_name":"X","content":"全文","summary":"摘要"}]}}`；脚本层自动去重 |
+| `/mcn/api/account/update` | POST | 更新账号定位/赛道 | `{"id":X,"content":"六项键值段落","track":"赛道"}` |
+
+## 三、请求构造铁律
+
+大文本（人设卡全文等）一律用 Python `urllib.request` + `json.dumps(ensure_ascii=False)` 直连，**禁止用 PowerShell `ConvertTo-Json` 序列化大文本**（会超时卡死）。小 payload 两者皆可。