@speclip/pi-subvision

面向 Pi 的本机硬字幕 OCR 插件包。它调用正在运行的 SubVision macOS 桌面服务，把工作区视频画面中的烧录字幕识别为标准 SRT。

这个包不做语音转写，也不包含 OCR 模型、媒体解码器或 SubVision.app。 实际识别由 http://127.0.0.1:17321 上的 SubVision 服务完成。

能力

• 校验回环服务确实是 SubVision，避免向错误的本机服务发送视频路径。
• 只接受工作区内的视频，拒绝绝对路径、目录逃逸和符号链接逃逸。
• 要求 Agent 先通过自适应 12 + 12 帧联系表判断字幕 ROI。
• 提交本地路径任务、轮询状态、下载 SRT。
• 输出只允许新的工作区相对 .srt 路径，不覆盖已有文件。
• 等待中断后可按 job ID 恢复，不重复提交 OCR 任务。

Pi 工具

| 工具 | 作用 | |---|---| | subvision_status | 检查服务、模型和任务状态 | | subvision_extract | 提交视频、等待 OCR、保存新 SRT | | subvision_job_resume | 恢复已有任务并保存 SRT |

安装与验证

当前代码针对本机 Pi 0.84.1 验证：

npm install
npm run check
pi install ./

本地开发时也可以直接加载：

pi -e ./

使用前需要在 macOS 13 或更高版本安装并打开 SubVision.app，确保桌面 面板显示服务已启动。Agent 的 ROI 联系表流程还需要可用的 ffmpeg 和 ffprobe；SubVision 服务本身不依赖它们。

程序化 API

包根导出 SubVisionClient、请求/响应类型以及工作区安全辅助函数。完整 服务端点和参数范围见 skills/subvision/references/api-reference.md。

CI/CD 自动发版

普通 push 和 Pull Request 会执行 .github/workflows/ci.yml，检查类型、 测试和 npm 打包内容。npm 发布只由已发布的 GitHub Release 触发，不会在 普通 push 时发布。

Release 标签必须严格等于 v<package.json version>。正式 Release 发布到 latest，Prerelease 发布到 next。发布工作流使用 npm Trusted Publishing （OIDC），仓库不保存 NPM_TOKEN。

由于 @speclip/pi-subvision 目前还是新的 npm 包，需要先用有权限的 npm 账号完成一次 bootstrap 发布，然后在 npm 包设置中配置 Trusted Publisher：

• Organization/User：linyqh
• Repository：pi-subvision
• Workflow filename：publish.yml
• Allowed actions：npm publish

也可以在 npm CLI 11.19.0+ 登录后执行：

npm trust github @speclip/pi-subvision \
  --file publish.yml \
  --repo linyqh/pi-subvision \
  --allow-publish \
  --json -y

后续版本发版示例：

npm version patch
git push origin main --follow-tags
gh release create "v$(node -p 'require("./package.json").version')" \
  --verify-tag --generate-notes

仓库当前是 private，因此 OIDC 仍可发布，但 npm 不会为私有 GitHub 仓库 生成公开 provenance；需要 provenance 时应先明确将仓库调整为 public。

当前边界

• 仅支持本机无鉴权回环服务，不允许把视频路径发送到远端主机。
• /api/jobs/path 由运行 SubVision.app 的同一 macOS 用户读取。
• 服务端任务仅保存在当前进程内；重启 SubVision.app 后旧 job ID 失效。
• Agent 工具不开放 multipart 上传，避免把大型视频完整缓存在内存中。