Skip to content
Back to search

video-report-agent

A Python video-to-report pipeline and reusable agent Skill for generating structured, source-traceable HTML reports.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 12 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/imexlovery/video-report-agent with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/imexlovery/video-report-agent'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/imexlovery--video-report-agent/badge.svg)](/listings/imexlovery--video-report-agent)

HTML

<a href="/listings/imexlovery--video-report-agent"><img src="/api/listings/imexlovery--video-report-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

需要 Python 3.12、uv、PATH 中的 `ffmpeg` / `ffprobe`,以及 Node.js 22 和 npm。从源码仓库安装:

git clone https://github.com/imexlovery/video-report-agent.git
cd video-report-agent
npm install -g @earendil-works/pi-coding-agent@0.85.0
pi --version
uv sync
uv run playwright install chromium
test -f .env || cp .env.example .env

这里使用项目适配的 Pi 0.85.0。`uv sync` 不会安装 Pi。Apple Silicon 如使用本地 MLX Whisper,将 `uv sync` 换成 `uv sync --extra mlx`。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 255 lines
  1. # Video Report Agent · 公开核心
  2. 简体中文 | [English](README.en.md)
  3. 把视频转写整理成可以扫读、精读和保存的 HTML 阅读报告。可以直接在 [VReport 网站](https://vreport.tri4t.xyz) 使用,也可以把本仓库的 Skill 和模板交给自己的 Coding Agent,在本地生成报告。
  4. **本仓库的核心资产是 [`video-report` 模板 Skill](src/video_report_agent/skills/video-report/)**:它把内容编辑规则、阅读模式、视觉模板和来源约束放在一起,指导 Agent 从完整转写中组织一份可读的报告。Python 流水线负责下载、转写、运行 Agent 和导出长图;网站、账户和额度由独立的 Web Service 维护。
  5. | 你想做什么 | 从这里开始 |
  6. |---|---|
  7. | 在线生成报告 | [打开 VReport](https://vreport.tri4t.xyz) |
  8. | 把已有转写交给自己的 Coding Agent | [下载 Skill ZIP v0.6.0](https://github.com/imexlovery/video-report-agent/releases/download/skill-zip-v0.6.0/video-report-skill-v0.6.0.zip) · [简短使用说明与示例](docs/skill-bundle/README.md) |
  9. | 从视频链接运行完整流程 | [完整 CLI 安装说明](#方式二运行完整-cli-流水线) |
  10. ## 先看成品
  11. 下面是示例报告的顶部,点击图片查看完整长图。
  12. [![阅读报告预览](docs/images/report-preview.png)](docs/examples/report.png)
  13. [示例 HTML](docs/examples/report.html) · [完整 PNG](docs/examples/report.png) · [在线使用](https://vreport.tri4t.xyz)
  14. GitHub 上的 HTML 链接会打开源码页,下载后用浏览器打开即可阅读。示例随仓库提供,无需启动服务。
  15. ## 模板 Skill 如何工作
  16. 输入可以是 Markdown、TXT、SRT 等完整转写,也可以是其他长篇文本。标题、作者、链接和时间戳属于可选信息。Agent 先理解完整来源,再按内容关系组织章节,使用选定模式的 HTML 模板完成写作、图示和修订。
  17. Skill 包含四部分,使用时需要保留整个目录:
  18. | 资产 | 作用 |
  19. |---|---|
  20. | [`SKILL.md`](src/video_report_agent/skills/video-report/SKILL.md) | 共用入口:来源忠实、内容组织、推广排除、语言与交付规则 |
  21. | [`modes/`](src/video_report_agent/skills/video-report/modes/) | Standard / Brief 的内容取舍、阅读深度和组件约定 |
  22. | [`assets/`](src/video_report_agent/skills/video-report/assets/) | 两种模式各自的 HTML 模板,提供内联样式与视觉组件 |
  23. | [`references/`](src/video_report_agent/skills/video-report/references/) | 机制、步骤、实证、论证、叙事五类编辑参考,按需读取 |
  24. 模板提供排版与表达工具,章节按来源内容组织。机制适合关系图,步骤适合流程与条件分支,实证适合数据和证据对照;Agent 选择一个主要编辑方向,必要时补充一个参考。模式、模板和参考按需加载,在同一个 Agent 任务中完成理解、写作与修订。
  25. | 阅读模式 | 适合什么用途 | 表达方式 |
  26. |---|---|---|
  27. | `standard` · 标准阅读(默认) | 理解完整主线,保留必要解释、依据和例子 | 按有效信息量调整篇幅;长文可带章节导航和可靠来源时间 |
  28. | `brief` · 精简速览 | 先抓核心问题、主要判断与决定性条件 | 独立速览模板,视觉表达优先;正文目标 1600–2200 字、上限 2400 字,短来源可更短 |
  29. 两种模式都先读完整来源,保留关键数字口径、条件、归属与不确定性。Skill 要求识别并排除商业推广,正常教程和实测中的有效内容仍需保留。报告使用隐藏的 `data-source-units` 绑定来源位置;这方便核对,但不能单凭绑定证明内容正确。
  30. 最终交付是内联样式的自包含 `report.html`,可直接用浏览器打开。质量取决于转写、模型与实际检查;Skill 不包含 ASR 引擎,也不替用户配置模型。
  31. ## 方式一:交给自己的 Coding Agent
  32. 这是复用核心资产最直接的方式,无需安装本项目的 Python 后端、Pi 或网站。
  33. ### 1. 准备完整转写
  34. 可以使用作者字幕、B站 AI 自动字幕、自己的 ASR 转写或其他已有完整文本,保存为 `transcript.md`、TXT 或 SRT。尽量保留时间戳和说话人;缺少可靠时间时,报告会省略相应章节时间。
  35. ASR 负责把语音变成文字,Coding Agent 的模型负责阅读和生成报告,两者可以独立选择。
  36. ### 2. 获取完整 Skill 目录
  37. 下载 [Skill ZIP v0.6.0](https://github.com/imexlovery/video-report-agent/releases/download/skill-zip-v0.6.0/video-report-skill-v0.6.0.zip) 并解压。包内有完整 Skill、简短说明,以及配套的转写和 HTML 示例;可以先按包内 `README.md` 试用。
  38. 需要源码时,也可以克隆仓库:
  39. ```sh
  40. git clone https://github.com/imexlovery/video-report-agent.git
  41. ```
  42. 使用下载包中的 `video-report/`,或从源码复制完整的 `src/video_report_agent/skills/video-report/`,保持相对路径:
  43. ```text
  44. my-report/
  45. ├── transcript.md
  46. ├── video-report/
  47. │ ├── SKILL.md
  48. │ ├── modes/
  49. │ ├── references/
  50. │ └── assets/
  51. │ ├── report-template.html
  52. │ └── brief-report-template.html
  53. └── output/
  54. ```
  55. 支持 Skills 的 Agent 可以按自身约定安装这个目录;其他能读写本地文件的 Coding Agent 可以直接读取入口。独立使用不要求 `input.json` 或 `source.info.json`。未提供视频简介时,Skill 会移除模板里的简介占位符。
  56. ### 3. 发送生成指令
  57. 在上述目录打开 Coding Agent,发送:
  58. ```text
  59. 读取 video-report/SKILL.md,按其要求生成阅读报告。
  60. 使用 standard 模式,只读取该模式指定的模式文件和模板。
  61. 完整阅读 transcript.md,将自包含 HTML 写入 output/report.html。
  62. 保留重要条件、数字、公式、人物归属与不确定性,不修改原始转写。
  63. 只有来源时间可靠时才显示章节时间。
  64. 如有浏览器工具,检查页面布局;否则说明仅完成静态检查。
  65. ```
  66. 需要速览时,把 `standard` 改成 `brief`。完成后用浏览器打开 `output/report.html`;PNG 导出取决于你的 Agent 是否具备相应工具。
  67. ## 方式二:运行完整 CLI 流水线
  68. 适合从 Bilibili 视频链接开始,自动获取文字稿并生成报告:
  69. ```text
  70. Bilibili URL
  71. → 获取文字稿:作者字幕 → B站 AI 自动字幕 → ASR(默认依次尝试)
  72. 仅需 ASR 时:yt-dlp 下载 → FFmpeg 提取音频 → 语音识别
  73. → 规范转写(正文、来源 ID、时间)
  74. → Pi RPC + video-report Skill → HTML
  75. → Chromium 导出 PNG 长图
  76. ```
  77. Python 负责确定性的处理步骤与任务监督;Pi 提供模型调用、文件/命令工具、会话与 Agent 循环;Skill 决定内容和视觉表达。
  78. ### 安装
  79. 需要 Python 3.12、uv、PATH 中的 `ffmpeg` / `ffprobe`,以及 Node.js 22 和 npm。从源码仓库安装:
  80. ```sh
  81. git clone https://github.com/imexlovery/video-report-agent.git
  82. cd video-report-agent
  83. npm install -g @earendil-works/pi-coding-agent@0.85.0
  84. pi --version
  85. uv sync
  86. uv run playwright install chromium
  87. test -f .env || cp .env.example .env
  88. ```
  89. 这里使用项目适配的 Pi 0.85.0。`uv sync` 不会安装 Pi。Apple Silicon 如使用本地 MLX Whisper,将 `uv sync` 换成 `uv sync --extra mlx`。
  90. ### 配置模型与转写
  91. 编辑仓库根目录的 `.env`,填写报告模型凭证。使用 ASR 时再配置相应后端;以下示例配置云端 ASR,供自动路由回退或手动选用:
  92. ```dotenv
  93. PI_PROVIDER=deepseek
  94. PI_MODEL=deepseek-flash
  95. PI_API_KEY=your-report-model-key
  96. PI_TASK_ISOLATION=local
  97. ASR_BACKEND=paraformer
  98. ASR_MODEL=paraformer-v2
  99. DASHSCOPE_API_KEY=your-dashscope-api-key
  100. ```
  101. Apple Silicon 本地转写替换为:
  102. ```dotenv
  103. ASR_BACKEND=mlx
  104. ASR_MODEL=mlx-community/whisper-large-v3-turbo
  105. ```
  106. 流水线内置 `mlx` 与 `paraformer` 后端,云端还支持代码已适配的 Fun-ASR 文件转写模型。其他 ASR 可用于独立 Skill 流程;接入本流水线需要对应适配器。云端 ASR 会上传音频,报告模型会接收生成所需的转写内容。
  107. ### 生成与查看
  108. ```sh
  109. # 标准阅读
  110. uv run video-report generate 'https://www.bilibili.com/video/BV...'
  111. # 精简速览
  112. uv run video-report generate 'https://www.bilibili.com/video/BV...' --report-mode brief
  113. ```
  114. 输出目录为 `runs/<run-id>/`,主要阅读产物是 `report.html` 和 `report.png`;`transcript.md` 可用于来源核对。截图失败时 HTML 仍可完成,查看 `status.json` 的 `image_error`,确认 PNG 是否生成。
  115. ### 选择字幕与转写来源
  116. CLI 默认使用 `auto`,按“作者字幕轨 → B站 AI 自动字幕 `ai-zh` → ASR”依次尝试。取得可用字幕正文后就进入报告生成;只有前两路不可用时才运行 ASR。也可以通过 `--sources` 主动选择:
  117. | 来源 | CLI 参数 | 说明 |
  118. |---|---|---|
  119. | 作者字幕 | `--sources subtitle_track` | 使用 B站返回的非 AI 字幕轨 |
  120. | B站 AI 自动字幕 | `--sources bilibili_ai` | 直接获取平台已有的中文 `ai-zh` 字幕 |
  121. | ASR 语音识别 | `--sources asr` | 下载媒体并使用配置的 `mlx` 或 `paraformer` 后端 |
  122. | 本地字幕文件 | `--sources subtitle_track --subtitle-file captions.srt` | 导入已有 SRT、VTT 或 ASS 字幕 |
  123. | 多路对照 | `--sources bilibili_ai asr` | 采集所有选中来源,按参数顺序选择首个可用主来源,其余参与局部校对 |
  124. ```sh
  125. # 只使用 B站 AI 自动字幕
  126. uv run video-report generate 'https://www.bilibili.com/video/BV...' --sources bilibili_ai
  127. # 只生成文字稿,后续交给自己的 Coding Agent
  128. uv run video-report transcribe 'https://www.bilibili.com/video/BV...' --sources bilibili_ai
  129. ```
  130. 手动选源只采集选中的来源;上例的 AI 字幕不可用时会报错。多路对照会同时采集 AI 字幕和 ASR。仅选字幕且未开启画面辅助时,不下载媒体,也不要求 ASR 凭证。
  131. 字幕需要登录态时,在 `.env` 中设置 `BILIBILI_SUBTITLE_BROWSER=chrome`(或 yt-dlp 支持的其他浏览器),读取该浏览器已有的 B站登录态;也可通过进程环境提供 `BILIBILI_SESSDATA`。默认不读取浏览器,凭据不要提交到 Git。导入字幕需要 `uv sync --extra enhancement`。详细规则见[选源说明](docs/subtitle-sources.md)。
  132. B站 AI 自动字幕的新接口 Protobuf 字段解析参考了 [ccBilly-aipm/bilibili-ai-subtitle](https://github.com/ccBilly-aipm/bilibili-ai-subtitle)(MIT)。感谢作者公开字幕提取流程与协议解析实现,为本项目的 AI 字幕支持提供了参考。
  133. ### 报告流程中可选的工具与能力
  134. 以下是完整 Core 流水线的开关。独立 Skill ZIP 使用你自己的 Agent 工具与配置。
  135. | 工具/能力 | 默认状态 | 如何开启或关闭 |
  136. |---|---|---|
  137. | 术语纠错 `term_correction` | 关闭 | CLI 添加 `--term-correction` 开启,省略即关闭;Python 用 `create_run(..., term_correction=True/False)` |
  138. | 画面辅助理解 | 关闭 | CLI 添加 `--visual-enhancement` 开启,省略即关闭;Python 用 `visual_enhancement=True/False` |
  139. | 报告检查 `report_inspection` | 关闭 | CLI `--report-inspection` 开启;Python `create_run(..., report_inspection=True/False)` |
  140. | 独立文风校订 `style_edit` | 开启 | CLI `--no-style-edit` 关闭、`--style-edit` 开启;Python `create_run(..., style_edit=True/False)` |
  141. | 独立图示 `generate_diagram` | Standard 开启,Agent 按需调用;Brief 关闭 | Standard 可用 Python `create_run(..., diagrams=False)` 关闭;Brief 暂不提供此功能;当前没有 CLI 开关 |
  142. | OCR 画面文字识别(旧融合流程) | 关闭 | CLI 用 `--transcript-mode fused --ocr-mode auto` 开启,`--ocr-mode off` 关闭;需安装 `enhancement` 扩展 |
  143. 画面辅助会额外取得视频轨、抽取 9 帧,使用本次任务选定的主报告模型生成画面描述,再交给报告 Agent。它沿用主模型的 provider、model、思考档位与 Pi 认证(API Key 或 OAuth),无需单独的视觉模型或 Key。主模型须实际支持图片,并在 `config/pi/models.json` 对应模型中声明 `"input": ["text", "image"]`;未声明图片输入时会明确报错。开启后会增加一次图文模型请求的耗时与用量。
  144. Standard 的独立图示工具最多调用一次,可通过下方的独立绘图模型配置指定模型;开启时也可由 Agent 判断无需绘图。绘图遇到可恢复的请求错误时最多重试一次,共用 180 秒时限;仍无法嵌入时清除占位符,交付已正常完成的正文。
  145. 报告检查工具向同一 Agent 返回程序检查结果与可用截图,最多检查两次、集中修订一次。任务关闭报告检查时,写完初稿直接结束,不通过 Bash 运行检查器。文风校订独立可选,校订后不再运行检查器。`REPORT_REVIEW` 仅作为独立构造 `PiRunner` 时的默认值,完整任务以任务参数为准。基础读写/命令工具、HTML 交付检查和最终 PNG 导出属于常规流程,当前没有对应 CLI 关闭参数。完整参数见 `uv run video-report generate --help`。
  146. ### 术语纠错的搜索服务配置
  147. 术语纠错在阅读或写作遇到重要名称疑点时按需核对,保留原始转写。开启 `--term-correction` 后,Agent 可使用 `record_term_review`、`lookup_term`、`fetch_term_source`;搜索与网页抓取每任务合计最多 3 次,按需产生费用。搜索服务独立于报告模型,通过 `.env` 二选一配置:
  148. ```dotenv
  149. # 方案一:DeepSeek Search/Fetch(默认供应商)
  150. TERM_SEARCH_PROVIDER=deepseek
  151. DEEPSEEK_SEARCH_API_KEY=your-official-deepseek-key
  152. ```
  153. ```dotenv
  154. # 方案二:OpenAI Responses Web Search
  155. TERM_SEARCH_PROVIDER=openai
  156. OPENAI_SEARCH_API_KEY=your-openai-api-key
  157. OPENAI_SEARCH_MODEL=gpt-6-luna
  158. ```
  159. DeepSeek 优先读取 `DEEPSEEK_SEARCH_API_KEY`,留空时使用 `DEEPSEEK_API_KEY`;OpenAI 优先读取 `OPENAI_SEARCH_API_KEY`,留空时使用 `OPENAI_API_KEY`。两者均不读取 `PI_API_KEY` 或 `DASHSCOPE_API_KEY`,需提供对应官方服务凭据。OpenAI 的搜索模型可单独选择;示例显式使用 `gpt-6-luna`,未配置 `OPENAI_SEARCH_MODEL` 时代码默认 `gpt-6.1-sol`,模型和搜索分别计费。
  160. 保存配置后,为生成命令添加 `--term-correction` 即可启用;仅填写搜索配置不会自动开启纠错。配置保存到新任务,运行中的服务修改 `.env` 后需重启。详细证据规则与 Docker 配置见[术语修正说明](docs/term-correction.md)。
  161. ## 运行与数据约定
  162. - **存储**:独立 CLI 默认使用 `runs/state.sqlite3`,保存任务、转写、报告 HTML 与缓存等结构化数据。任务目录里的 JSON、转写和 HTML 是执行导出;媒体、PNG、Pi 会话和诊断日志仍存文件。详见 [SQLite 存储](docs/sqlite-storage.md)。
  163. - **配置**:从工作目录读取 `.env`,进程环境变量优先。Pi 配置保存在工作目录的 `config/pi/`,缺失的模型默认配置会初始化,已有配置保留。其他目录通过启动前的 `PI_CODING_AGENT_DIR` 指定。不要提交凭证。
  164. - **独立绘图模型**:可同时设置 `DIAGRAM_PROVIDER`、`DIAGRAM_MODEL`,可选 `DIAGRAM_THINKING`;在 Pi 中配置对应 provider 的 API Key 或 OAuth。留空时沿用主报告模型和认证,新配置只影响新任务。OAuth 需要无隔离 Local;Docker 绘图使用 API Key。见 [Core 架构](docs/ARCHITECTURE.md#完成与检查)。
  165. - **隔离**:示例使用 `PI_TASK_ISOLATION=local`,Pi 工具拥有本机用户权限。Docker 模式需要应用镜像、Docker daemon 与同一 scope 的健康 task cleaner;选用后失败不会退回本地执行。详见 [Core 架构](docs/ARCHITECTURE.md)。
  166. - **追踪**:`run.trace.jsonl` 记录流水线阶段,`pi.events.jsonl` 记录 Agent 模型与工具事件。完成需等待 `agent_settled`、最终 assistant `stopReason == "stop"`,并通过 HTML 交付检查。
  167. - **边界**:内置视频入口面向公开 Bilibili 视频;字幕提取可使用已有登录态,私有视频不在支持范围。视频上限 5 小时,执行期限 30 分钟;本地停止后已提交的云 ASR 仍可能继续计费。默认只理解转写,画面中的非语音信息可能缺失。完整流水线的原生 Windows 运行未在此作为已验证方案。
  168. ## 开发与进一步阅读
  169. ```sh
  170. uv run --extra enhancement pytest -q
  171. uv run ruff check src tests
  172. uv lock --check
  173. ```
  174. - [项目文档](docs/README.md):目标、架构、计划与重要取舍。
  175. - [报告 Skill 入口](src/video_report_agent/skills/video-report/SKILL.md):实际生成规则与阅读顺序。
  176. - [报告评测](evals/report-review/README.md):公开合成 smoke 与可选真实模型评测。HTML/来源绑定检查和内容、视觉质量需分别判断。
  177. 调用方默认使用包内 Skill;实验时可通过 `PiRunner(skill_dir=...)` 或 Worker 环境变量 `VIDEO_REPORT_SKILL_DIR` 选择完整 Skill 目录。账户、额度、队列和网站部署属于独立 Web Service,公开 Core 只维护生成能力。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.