使用指南
> 工具 reference：references/<工具名>.md。
🎯 工具索引
node <skill目录>/agent_mcp.cjs call <工具名>，参数用 echo '<JSON>' | 管道传入，不确定时 list <工具名> 查 Schema。
MCP
| 场景 | 工具 | 触发关键词 | 参考文档 |
|---|---|---|---|
| 用户信息 | crawl_current_user |
我的账户、余额、算力、会员<br>查余额、剩余算力、个人信息 | references/user_info.md |
| AI商拍·试衣 | model_try_clothes |
试衣服、换装、AI 试穿<br>上身效果、穿上试试、虚拟试穿 | references/model_try_clothes.md |
| AI商拍·试鞋 | shoes_dressing |
试鞋、上脚试试、上脚效果<br>鞋子试穿、鞋子上脚、鞋子穿上 | references/shoes_dressing.md |
| AI商拍·模特 | model_produce |
生成模特、AI 模特、模特图<br>换模特、模特生成、虚拟人物、创建模特 | references/model_produce.md |
| 商品场景图 | business_product_scene |
商品场景、场景效果、换个背景<br>场景图、商品背景、产品摆拍 | references/business_product_scene.md |
| 商品海报 | business_poster |
做海报、促销海报、活动海报<br>海报设计、生成海报、商品主图、宣传海报 | references/business_poster.md |
| 图文笔记 | ice_design_image_xhs |
小红书配图、种草笔记、小红书图<br>笔记配图、图文笔记、做小红书图、生成笔记图 | references/ice_design_image_xhs.md |
| 社媒发布·抖音 | dy_share_schema |
发到抖音、发布视频、发视频<br>上传视频、抖音扫码、抖音发布 | references/dy_share.md |
| 视频生成·口播 | ice_voice_video |
对口型、配音视频、口型同步<br>给视频配音、让视频说话、数字人口播 | references/ice_voice_video.md |
| 视频生成·唱歌 | image_song |
照片唱歌、图片唱歌、唱歌视频<br>照片MV、老照片唱歌、让照片唱歌、图片演唱 | references/image_song.md |
| 视频生成·混剪 | ai_mixed_script |
混剪、剪视频、素材混剪<br>视频剪辑、素材拼接、剪辑视频、混剪带货 | references/ai_mixed_script.md |
| 视频生成·复刻 | ai_clone_video |
视频复刻、模仿视频、同款视频<br>翻拍视频、拍个一样的、照着做 | references/ai_clone_video.md |
| 链接解析 | get_raw_url |
解析链接、提取视频、抖音去水印<br>抖音解析、提取链接、链接解析、获取地址 | references/get_raw_url.md |
| 视频分析 | analyze_video |
分析视频、视频分析、风格分析<br>视频拆解、脚本提取、拆解视频、解析视频 | references/analyze_video.md |
| 任务状态 | get_job_status |
任务状态、生成进度、好了没<br>查询进度、完成了吗、轮询 | 见下方「轮询」 |
非MCP
| 场景 | 路径 | 触发关键词 |
|---|---|---|
| 环境 & 鉴权 | references/auth.md |
token、授权、登录、配置<br>获取token、密钥、Token过期 |
| 微信分享 | references/wechat_share.md |
发微信、发朋友圈、微信扫码<br>发到微信、分享微信、H5分享 |
| 公共流程 | references/workflows.md |
工作流、发布路径、生成后怎么发 |
| 联系咨询 | references/contact.md |
合作、代理、商务、客服<br>功能建议、反馈 |
🔧 调用方式
> 脚本路径：命令统一执行 <skill目录>/agent_mcp.cjs，<skill目录> 即本 SKILL.md 所在目录（含 agent_mcp.cjs）；references 等文档中的命令示例以 agent_mcp.cjs 简写指代该脚本。Bash 工作目录不在该目录时用绝对路径调用或先 cd，否则报 No such file。可运行 node <skill目录>/agent_mcp.cjs check_env 确认，输出含 SKILL_DIR:<绝对路径>，后续命令复用该路径。
执行调用（正常流程，直接从 reference 确定参数）：
echo '<JSON参数>' | node <skill目录>/agent_mcp.cjs call <工具名> 2>&1
查看 Schema（参数不确定、或返回报错提示参数不匹配时）：
node <skill目录>/agent_mcp.cjs list <工具名>
> 参数以 Schema 为准。reference 提供 Schema 无法表达的额外约束。
📡 全局响应结构
code: 状态码，0成功，任何非0值均表示异常msg: 状态描述，成功时ok，异常时含具体错误信息data: 响应数据，固定包含_id（调用链追踪 ID）
⚡ 异常处理规则
当 code != 0 时：
- 读取
msg，结合上下文分析失败原因 - 临时性错误（网络超时、服务繁忙）→ 自动重试 1-2 次
- 参数/权限/算力错误 → 主动告知用户原因和操作建议
- 不要静默失败：必须将错误信息和处理建议反馈给用户
📁 文件处理规范
文件来源识别
公网URL：
- 必须先验证可访问性：
curl -I --max-time 5 -L <URL> - HTTP 200 → 直接传入工具
- 403/401 → 告知"链接需要登录或权限"
- 404 → 告知"链接已失效"
- 超时/失败 → 告知"链接无法访问"
本地文件路径：
- 需上传到云存储获取公网URL，见下方上传规则
引用文件（@image、@file等）：
- 告知用户"请将文件保存到本地，提供完整路径"
对话中直接上传的图片：
- 告知用户"请右键保存图片，提供完整路径"
绝对禁止：
- ❌ 编造或猜测 URL/文件路径
- ❌ 使用示例 URL、占位符
- ❌ 未验证可访问性/存在性就调工具
文件上传规则
> 接口需要公网可访问 URL，本地文件必须先上传。文件路径必须为绝对路径，相对路径报 ERROR:relative_path。
node <skill目录>/agent_mcp.cjs upload <本地文件的绝对路径> # 替换为真实存在的文件路径，勿直接照抄示例
输出格式：文件: <文件名> + 文件大小: <可读大小> (<字节>) → IMPORT_READY + FILE_URL:<url> + FILE_SIZE:<字节>
管道自动处理
当工具返回 {"error": "need_upload", ...} 时，直接 pipe 给上传脚本：
echo '<上面的JSON>' | node <skill目录>/agent_mcp.cjs upload
> 上传完成后会输出 TOOL_NAME，用得到的 FILE_URL 继续调用
文件搜索限制
禁止全系统搜索：不允许 find /、find /Users、find ~ 等。
允许范围：当前工作目录、下载目录、用户明确指定的目录。
⏳ 轮询（图片 ≥15s / 混剪 ≥30s / 口播 ≥45s，最多 20 次）
> ⚠️ 禁止跳过 sleep、禁止缩短 sleep 值、禁止连续快速轮询。 只执行与任务类型匹配的那行：
sleep 15; echo '{"id":"<任务_id>"}' | node <skill目录>/agent_mcp.cjs call get_job_status 2>&1
sleep 30; echo '{"id":"<任务_id>"}' | node <skill目录>/agent_mcp.cjs call get_job_status 2>&1
sleep 45; echo '{"id":"<任务_id>"}' | node <skill目录>/agent_mcp.cjs call get_job_status 2>&1
| 状态 | 动作 |
|---|---|
processing / pending |
等 sleep 后重试，最多 20 次，超限则告知用户稍后重试 |
complete / success |
展示 data.videos[].url、cover_url，询问发布 |
failed / error |
查看 msg |
> ⚠️ 判断完成以 status 为准，不看 url 是否出现：data.videos[].url 在 processing 阶段就已返回，但文件尚未落盘、直接访问返回 404，不要提前展示。
> cover_url 可能为空字符串，为空时只展示视频、不展示封面。
> 入参 id 取 data._id。
🔍 失败分发
| 失败现象 | 原因 | 动作 |
|---|---|---|
missing_token |
Token 未配置 | node <skill目录>/agent_mcp.cjs save_token <Token>，或见 references/auth.md |
| 403 / code=403 | Token 问题 | references/auth.md |
| 80000000 | 算力不足 | references/profile.md |
| code != 0 | 业务错误 | 读 msg，重试或告知用户 |
> 完整错误码（上传层/CLI层/Token层）见 references/error_codes.md
📋 核心规则
- 参数以 Schema 为准，reference 提供额外业务约束
- 不支持的功能需用户同意后上报（见
references/unsupported_feature_reporting.md） - 文件/URL 必须先验证可达性再调用工具
