前言¶
安防回放、活动素材、监控归档里，常见需求不是「整段看完」，而是在长视频里按人物、物体或一句话描述定位片段。手写检测脚本或逐帧翻找成本高，也不方便把「穿红色衣服的人」「有人发言」这类开放语义和结构化报告串在一起。
下面介绍 SkillHub 社区技能 Intelligent Video Search & Retrieval Analysis Skill（坐标 @user_bb47e3e3/video-search-analysis，当前发布版本 1.0.8）。它把常规目标检索、自然语言描述检索和向量化模型匹配收敛到同一套 Agent 工作流里，由技能内脚本调用后端分析服务并返回结构化结果。
这是什么¶
视频搜索检索智能分析技能 是社区发布者 user_bb47e3e3 在 SkillHub 上维护的 Agent Skill，分类为 design-media，来源标注为 community。
一句话定位：基于目标与语义描述做智能视频搜索，支持常规目标检索、自然语言描述检索、向量化模型匹配；输入可为图片、视频、本地路径或网络 URL，输出包括结构化分析报告、识别/监测结果、建议与报告链接。技能内场景码为 VIDEO_SEARCH（开放平台侧文档中亦出现 OPEN_VIDEO_SEARCH_ANALYSIS）。
SkillHub 页面显示：评分 100000，下载 875 次，安装 1 次；标签 requires_api_key=false，表示使用方无需在 Skill 层单独配置 API Key（后端鉴权由技能脚本与公共配置处理）。
官方入口：
- SkillHub 展示页：https://www.skillhub.cn/skills/user_bb47e3e3/video-search-analysis
- API 坐标页：https://api.skillhub.cn/user_bb47e3e3/video-search-analysis
核心功能¶
依据 Skill 包内 SKILL.md 与简介，已核实的能力如下。
- 常规目标检索：通过计算机视觉识别并索引人、车、物等常规目标，用于检测特定物体或人物是否出现。
- 自然语言描述检索：支持用自然语言说明要找的内容（例如描述衣着、动作），由多模态模型做语义与画面内容的跨模态对齐。
- 向量化模型匹配：将视频内容转为高维向量，支持文本、图像、视频混合模态的融合检索，以及多条件组合与模糊语义匹配。
- 历史报告云端查询：用户表达查看历史搜索报告、报告清单等意图时，须通过脚本
--list从云端接口拉取，不得用本地记忆或人工汇总冒充列表。 - 附件与 URL 输入：用户上传的视频/图片可保存为本地文件；网络 URL 由 API 服务侧下载处理（文档说明默认按公网地址处理）。
触发上，技能说明默认在用户需要在视频中搜索特定内容/目标时启用；明确提到视频搜索、找片段、定位目标等关键词且提供了视频与搜索描述时也会进入本技能流程。
安装与启用¶
安装前确认本机已有 skillhub CLI；若无，可按 SkillHub 官方安装说明安装（完整安装或仅 CLI）：
command -v skillhub && skillhub --version
未安装时可执行（摘自 https://skillhub.cn/install/skillhub.md）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安装本技能时，必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被 Agent 加载。SkillHub 页面给出的安装提示为：参照上述安装文档，安装 @user_bb47e3e3/video-search-analysis。
CLI 搜索结果显示的安装命令为：
skillhub install video-search-analysis --namespace user_bb47e3e3 --dir <你的 Agent skills 目录>
常用路径（同样来自 SkillHub 安装文档）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
也可将官方提示发给 AI，让其按 https://skillhub.cn/install/skillhub.md 完成安装。
Python 侧，技能说明列出脚本依赖 requests>=2.28.0；执行分析时需在技能根目录下运行模块 scripts.video_search_analysis。
典型用法¶
标准流程可以概括为：准备视频输入 → 系统内部完成身份关联（不向用户索要身份参数）→ 在技能根目录调用分析脚本 → 查看结构化结果或报告链接。
本地文件 + 搜索描述¶
python -m scripts.video_search_analysis --input /path/to/life.mp4 --text "狗狗出现的片段"
--input 为本地视频路径，--text 为搜索目标或自然语言描述。
网络视频 URL + 自然语言搜索¶
python -m scripts.video_search_analysis --url https://example.com/event.mp4 --text "有人发言的片段"
--url 由 API 服务下载；无需在本地先拉取文件。
查询云端历史搜索报告列表¶
python -m scripts.video_search_analysis --list
历史清单只允许通过该命令走云端接口；--list 还可配合起始日期过滤（见技能参数表）。输出需按技能要求整理为 Markdown 表格，报告链接从接口 JSON 字段生成。
输出粒度与落盘¶
python -m scripts.video_search_analysis --input video.mp4 --text "汽车" --detail basic
python -m scripts.video_search_analysis --input video.mp4 --text "人物出现" --output result.json
--detail 可选 basic / standard / json（默认 json）；--output 可将结果写入文件。可选 --api-url 覆盖默认 API 服务地址。
后端主要接口路径（见技能内 references/api_doc.md）包括：启动分析 /web/ai-analysis/v2/start-common-ai-analysis、获取结果 /web/ai-analysis/v2/get-common-ai-analysis-result、分页历史 /web/ai-analysis/page-common-ai-analysis-result、报告导出 /ai/order/api/getReportDetailExport。
技能演示说明链接：https://lifeemergence.com/sample.html
适用场景与注意¶
适合谁
- 需要在长视频中按目标或自然语言快速定位片段的开发者或运营同学，且希望由 Agent 按固定脚本调用分析服务、统一报告格式。
- 需要查询历史视频搜索分析报告清单、避免 Agent 凭空编造报告列表的场景。
限制与注意
- 文档写明支持 mp4/avi/mov，单文件最大 1GB；搜索结果仅供参考，需以实际画面为准。
- 禁止临时手写替代脚本，只能使用技能包内
scripts/video_search_analysis.py等既定入口。 - 身份相关参数由系统内部处理：不得向用户询问或展示内部身份值；历史报告查询同样依赖内部身份关联。
- SkillHub 标签为
requires_api_key=false，与接口文档中的服务端 API Key 鉴权并存时，以技能脚本与smyx_common配置为准，使用方通常只需按工作流提供视频与搜索文本。 - 仅在需要排查接口字段或错误码时再阅读
references/api_doc.md，避免无关上下文膨胀。
结尾¶
Intelligent Video Search & Retrieval Analysis Skill 把三类检索方式（目标、自然语言、向量匹配）和云端历史报告查询收进同一套 SKILL 工作流，适合作为 Cursor 等 Agent 里「视频里找片段」的固定能力模块。安装与坐标以 SkillHub 为准：https://www.skillhub.cn/skills/user_bb47e3e3/video-search-analysis。
