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 创意灵感	若首次提问已提醒过 → 不重复提醒，直接使用或降级；若未提醒过 → 按本流程提醒
直接工具调用（"解析这个视频/查账号设定"）	未安装 → 按本流程提醒

按以下流程处理：

检测：检查 myai-mcp-production 的 MCP 工具是否在可用列表中。可用 → 跳到 [§4 登录检查]；不可用 → 进入步骤2
判定环境 + 提示：
- 首次提问（轻量提醒，不打断创作）：
  
  本技能部分功能（对标视频解析 / 创意灵感 / 账号设定查询）依赖 MCN MCP 服务。是否现在安装？暂时不需要可跳过，不影响核心创作流程，用到时会再次提醒。
- 创作中需用 API 功能 · 开发环境：
  本技能的 MCN API 功能需要安装 MCP 服务。开发环境可同时安装正式环境和测试环境。是否自动配置？
  - 两个都装（推荐）：正式环境用 myai-mcp-production，测试环境用 myai-mcp-test
  - 只装正式环境
- 创作中需用 API 功能 · 非开发环境：
  
  本技能的 MCN API 功能需要安装 myai-mcp-production MCP 服务。是否自动配置？
用户同意 → 前置检查运行环境 → 自动安装：
- 运行环境检查（先做）：检查本机是否已安装 Node.js（node --version）和 Python（python --version）。缺失则先引导安装对应运行时再继续——npx 型 MCP 依赖 Node.js，python 型 MCP 依赖 Python，缺失会导致 MCP 安装/启动失败。
- 读取 scripts/mcp-config.json
- 读取用户现有的 ~/.workbuddy/mcp.json（如不存在则创建）
- 开发环境：将 myai-mcp-production + myai-mcp-test 两个服务合并写入（保留已有服务，不覆盖）
- 非开发环境：只将 myai-mcp-production 服务合并写入（保留已有服务，不覆盖）
- 提示用户：「配置已写入。请打开右上角「连接器管理」页面，找到 myai-mcp-production（开发环境额外找到 myai-mcp-test），分别点击 Trust 启用。启用后重新发起任务即可。」
用户拒绝/跳过 → 降级：
- 告知用户：「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 自动检测与安装引导流程）
登录失败（`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。

7.3 KiB Raw Blame History Unescape Escape