CopilotKit + Langroid 集成实战:Tool Rendering 工具调用渲染的 QA 验证指南
【免费下载链接】StreamVault-IPTV
StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.
StreamVault 是一款面向 Android TV 的免费 IPTV 播放器(基于 Kotlin、Jetpack Compose、Room、Hilt 和 Media3 构建)。如果你想在保持主程序不变的前提下,为 StreamVault 增加外部内容源、播放前 URL 改写、Cast 投屏改写或自定义配置界面,那么 Plugin API 就是官方推荐的扩展方式。本文将带你完整理解插件架构:伴生 APK 如何被发现、Messenger IPC 的 11 条消息如何工作,以及如何用声明式 Schema 让 StreamVault 帮你渲染配置界面。
StreamVault 插件是什么:伴生 APK 而非代码注入
StreamVault 插件的核心理念是**"伴生 APK"(companion APK)**:
- 插件是一个独立的 Android 应用,不会向主应用注入任何代码;
- StreamVault 通过
PackageManager查询系统中声明了com.streamvault.plugin.API这个 action 的 Service,与它们通过 Android Messenger IPC 通信; - 这种边界让插件可以随时安装、卸载、更新,并且与 Android 包隔离(package isolation)策略完全兼容。
插件可以增强四类能力(capabilities):
| 能力 | 说明 |
|---|---|
provider.m3u | 暴露一个 M3U 地址,被 StreamVault 作为内容源导入 |
playback.prepare | 在播放开始前准备/改写流地址 |
cast.rewriteUrl | 在 Google Cast 加载前改写播放地址 |
configuration.schema | 提供声明式配置 Schema,由 StreamVault 渲染 UI |
configuration.activity | 提供原生 Activity 作为配置界面 |
插件包发现机制:三步接入
StreamVault 的插件发现逻辑实现于 StreamVaultPluginManager.kt,核心步骤如下:
- 查询:宿主用
Intent("com.streamvault.plugin.API")调用queryIntentServices,找到所有导出且带该 intent-filter 的 Service; - 读清单:先通过
MSG_GET_MANIFEST向插件服务请求清单 JSON;若失败则回退到 Service 的com.streamvault.plugin.MANIFEST_JSON元数据,最后才逐个回退到独立的meta-data字段; - 建立通道:绑定服务后,所有请求都带
api_version(当前为1)和request_id,响应必须原样带回这两个字段。
插件端只需在 AndroidManifest.xml 中声明一个导出 Service:
<service android:name=".MyPluginService" android:exported="true">
<intent-filter>
<action android:name="com.streamvault.plugin.API" />
</intent-filter>
</service>
插件支持三种安装方式:直接 HTTP/HTTPS 的 APK 链接、系统文件选择器选中的本地 APK、或任意手动安装的 APK(在插件页刷新即可检测到)。
插件清单(Manifest):你的插件名片
下面是官方文档 docs/PLUGIN_API.md 中给出的标准清单示例,也是 MSG_GET_MANIFEST 需要返回的 manifest_json:
{
"schemaVersion": 1,
"id": "com.example.plugin",
"name": "Example Plugin",
"versionName": "1.0.0",
"versionCode": 1,
"description": "Adds external capabilities to StreamVault.",
"providerName": "Example Provider",
"configurationMode": "host.schema",
"configurationActivityAction": "",
"capabilities": ["provider.m3u", "playback.prepare", "cast.rewriteUrl", "configuration.schema"],
"playbackUrlSchemes": ["http", "https"],
"playbackUrlHosts": ["127.0.0.1", "cdn.example.com"]
}
⚠️ 一个最容易踩的坑:playbackUrlSchemes / playbackUrlHosts 是 playback.prepare 和 cast.rewriteUrl 的前置过滤器。如果清单里这两个列表为空或缺失,插件就不会拥有任何带 host 的 URL——即使这个 URL 正是它自己生成的(比如指向本地 http://127.0.0.1:<port>/... 代理的播放地址),也收不到 MSG_PREPARE_PLAYBACK。想全量匹配请显式使用 "*"。
此外,这两个字段只能从完整的 MANIFEST_JSON 中读取,不支持单独的 meta-data 回退字段。
Messenger IPC:11 条消息一览
所有消息常量定义在 StreamVaultPluginContract.kt,主机侧的发送逻辑见 PluginMessengerClient.kt:
| ID | 消息名 | 用途 |
|---|---|---|
| 1 | MSG_GET_MANIFEST | 返回 manifest_json |
| 2 | MSG_SET_ENABLED | 用 enabled 开关插件功能 |
| 3 | MSG_GET_STATUS | 返回 status_label 和可选 message |
| 4 | MSG_GET_PROVIDER_URL | 返回 url 与可选 provider_name |
| 5 | MSG_PREPARE_PLAYBACK | 准备 input_url,命中时置 handled |
| 6 | MSG_REWRITE_CAST_URL | 改写 input_url,命中时返回 output_url |
| 7 | MSG_GET_CONFIGURATION_SCHEMA | 返回 configuration_schema_json |
| 8 | MSG_GET_CONFIGURATION_VALUES | 返回 configuration_values_json |
| 9 | MSG_SET_CONFIGURATION_VALUES | 持久化 configuration_values_json |
| 10 | MSG_RUN_CONFIGURATION_ACTION | 执行 configuration_action_id |
| 11 | MSG_STOP_PLAYBACK | 释放由 output_url 标识的播放会话 |
关键行为约定:
handled机制:即使通过了 scheme/host 过滤,插件在具体 URL 无法处理时仍应返回handled=false,StreamVault 会继续询问其他插件或回退原始 URL;- magnet 链接:若没有任何启用中的插件接管,主机直接失败,绝不解开未解析的 magnet 传给播放器。插件必须只把流媒体服务绑定在
127.0.0.1,且output_url必须是带端口的回环 HTTP 地址; - 会话释放:播放结束时主机用精确的
output_url发送MSG_STOP_PLAYBACK,投递是尽力而为的,插件还需自行清理过期/被遗弃的会话。
声明式配置:让 StreamVault 替你画 UI
这是 Plugin API 里对新手最友好的部分。选定 host.schema 模式后,插件只需描述字段和动作,视觉外壳、验证提示、焦点行为全部由 StreamVault 负责:
{
"schemaVersion": 1,
"title": "Example Plugin",
"sections": [
{
"id": "connection",
"title": "Connection",
"fields": [
{ "key": "serverUrl", "type": "url", "label": "Server URL", "required": true },
{ "key": "token", "type": "password", "label": "Token", "secret": true },
{ "key": "quality", "type": "select", "label": "Preferred quality",
"options": [ { "value": "auto", "label": "Auto" }, { "value": "1080p", "label": "1080p" } ] }
]
}
],
"actions": [
{ "id": "testConnection", "label": "Test connection", "refreshAfterRun": true }
]
}
支持的字段类型共 8 种:info、text、password、url、number、boolean、select、textarea。保存时流式字段会连同 success / message 回传,校验失败应返回 success=false 并附上用户可读的 message。
下面是 StreamVault 实际渲染出的声明式配置界面效果(必填项缺失时会有红框与错误提示):
host.schema 还是 activity?
| 场景 | 推荐模式 |
|---|---|
| 字段、开关、下拉、简单动作为主 | host.schema |
| 运行时仪表盘、源管理增删改、频道测试、内嵌日志、配对/登录流程 | activity |
选择 activity 时需要声明 configurationActivityAction 并导出对应 Activity(带 DEFAULT category)。官方参考示例是 HaP 插件:它用 Activity 模式承载运行状态、源管理、频道测试与日志等富交互界面。注意:不要为不完整或过期的 Schema 声明 configuration.schema——如果 configurationMode 是 activity,StreamVault 只会打开 Activity,不会再加载宿主渲染的 Schema。
发布前检查清单
按官方 PLUGIN_API.md 的 Integration Checklist,发布前请逐项确认:
- ✅ 恰好暴露一个
com.streamvault.plugin.APIService; - ✅
MSG_GET_MANIFEST返回完整清单,且 Service 元数据与运行时清单保持同步(作为回退); - ✅ 明确选定
host.schema或activity作为主配置模式; - ✅ 只声明完整实现过的 capabilities;
- ✅ 在插件内部对用户输入的 URL 与密钥做校验后再持久化;
- ✅ IPC 失败时返回用户可读的错误消息;
- ✅ 在真机(含 Chromecast 等 TV 设备与手机)上验证:安装、启用、停用、配置、provider URL、播放准备、Cast URL 改写全链路。
小结
StreamVault 的 Plugin API 用"伴生 APK + Messenger IPC + 声明式配置"三件套,在 Android 包隔离的约束下实现了完整的插件化扩展:
- 想加内容源?实现
provider.m3u,返回一个 M3U 地址即可; - 想做磁力/代理播放?实现
playback.prepare,记得声明playbackUrlSchemes/playbackUrlHosts; - 想省掉配置界面开发?用
host.schema声明式 Schema,8 种字段类型覆盖绝大多数设置场景。
建议结合本文与仓库内文档逐步实践:先看 docs/PLUGIN_API.md 的完整协议细节,再对照 StreamVaultPluginContract.kt 确认消息常量,就能开始构建你的第一个 StreamVault 插件了 🚀
【免费下载链接】StreamVault-IPTV
StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.
更多推荐



所有评论(0)