AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载导读本文围绕 Operit 的 ToolPkg工具包体系系统讲解两大核心机制一是 manifest 中api_version字段的引入、默认值与宿主兼容性校验Operit 从1.12.14起支持 ToolPkg API1.0.1缺失字段的旧包按1.0.0解释二是基于requires声明、插件列表用户顺序与包 ID 的确定性加载顺序解析。全文以仓库中的设计文档为骨架结合 Kotlin 源码、示例 manifest 与市场 API 模型给出可直接用于包开发与排查的完整参考。一、为什么需要 ToolPkg API 版本旧实现的局限在引入api_version之前ToolPkg manifest 只声明包元数据和资源结构schema_version、toolpkg_id、version、main、display_name等宿主无法获知某个包究竟使用了哪一版 ToolPkg API。这带来两个实际问题宿主升级 API 后旧包可能悄悄依赖已变更或移除的桥接能力行为不可预期包作者无法在开发期声明自己面向的宿主 API 版本调试与兼容性排查成本高。此外旧实现中 ToolPkg 容器按包名排序加载没有 manifest 级别的必需包和加载顺序约束插件列表虽有拖动排序 UI但顺序只影响列表显示与启动加载顺序没有形成清晰关系。设计文档明确了修改意图见 index.md为 ToolPkg 增加稳定、可识别的宿主 API 版本约定并支持包声明必需包和加载顺序约束。缺少api_version的旧包按1.0.0解释Operit 在1.12.14开始支持1.0.1。依赖与顺序只在宿主加载阶段解析不把运行态或持久化状态引入 ToolPkg API。二、manifest 中的api_version字段与默认值2.1 字段定义与默认值在 ToolPkgParser.kt 中ToolPkgManifest数据类定义了api_version字段Serializable internal data class ToolPkgManifest( SerialName(schema_version) val schemaVersion: Int 1, SerialName(toolpkg_id) val toolpkgId: String, val version: String , SerialName(api_version) val apiVersion: String ToolPkgApiCompatibility.LEGACY_API_VERSION, val requires: ListToolPkgManifestRequirement emptyList(), ... )两个关键设计点字段序列化名为api_versionsnake_case与 manifest 文件中的写法保持一致默认值为ToolPkgApiCompatibility.LEGACY_API_VERSION即1.0.0。这意味着缺失该字段的旧 manifest 不会被拒绝而是自动按1.0.0解释实现向后兼容。2.2 兼容性常量与版本解析ToolPkgApiVersion.kt 集中定义了全部兼容性规则internal object ToolPkgApiCompatibility { const val LEGACY_API_VERSION 1.0.0 const val API_VERSION_1_0_1 1.0.1 const val API_VERSION_1_0_1_INTRODUCED_IN_OPERIT 1.12.14 ... }宿主支持的 API 版本集合按 Operit 自身版本动态计算所有版本都支持1.0.0当 Operit 版本 ≥1.12.14时额外加入1.0.1fun supportedApiVersions(operitVersion: String BuildConfig.VERSION_NAME): ListToolPkgApiVersion { val currentVersion OperitVersion.parse(operitVersion) return buildList { add(legacyApiVersion) if (currentVersion apiVersion101IntroducedIn) { add(apiVersion101) } } }版本解析本身严格限定为major.minor.patch三段式ToolPkgApiVersion.parse使用正则^(\d)\.(\d)\.(\d)$Operit 版本则额外支持build后缀^(\d)\.(\d)\.(\d)(?:\(\d))?$例如1.12.14。2.3 一个真实的 manifest 示例仓库中的示例包 worldbook/manifest.json 完整展示了新字段的写法{ schema_version: 1, toolpkg_id: com.operit.worldbook, version: 1.2.0, api_version: 1.0.0, main: dist/main.js, author: [黒羽 燕, 冰蓝天影], display_name: { zh: 世界书, en: World Book, default: World Book }, enabled_by_default: false, subpackages: [ { id: worldbook_tools, entry: dist/packages/worldbook_tools.js, enabled_by_default: false, display_name: { zh: 世界书工具, en: World Book Tools } } ] }三、兼容性校验与错误报告在执行阶段之前拦截3.1 校验逻辑requireSupported是核心校验入口它同时完成三件事解析声明版本、计算宿主支持集合、在版本不支持时抛出携带完整信息的异常fun requireSupported( apiVersion: String, operitVersion: String BuildConfig.VERSION_NAME ): ToolPkgApiVersion { val declaredVersion parseDeclaredApiVersion(apiVersion) val supportedVersions supportedApiVersions(operitVersion) require(declaredVersion in supportedVersions) { ToolPkg API version $declaredVersion is not supported by Operit $operitVersion. Supported ToolPkg API versions: ${supportedVersions.joinToString(, )}. ToolPkg API $API_VERSION_1_0_1 requires Operit $API_VERSION_1_0_1_INTRODUCED_IN_OPERIT or newer. } return declaredVersion }注意parseDeclaredApiVersion对空字符串做了兜底ifBlank { LEGACY_API_VERSION }因此声明为空白或缺失的 manifest 一律落入1.0.0分支。3.2 错误在何时、以何种方式暴露按设计文档的约定不支持的 API 版本必须在包进入执行阶段之前被明确报告报告内容包含三个要素包名packageName、声明版本declaredapi_version和宿主支持版本列表。校验失败时该包不会进入执行阶段不注册工具、不挂载 hook避免运行期出现莫名其妙的桥接缺失。对应的包加载错误会被收集进包扫描快照供 UI 展示与排查相关逻辑位于 PackageManager.kt。3.3 支持版本作为扫描签名的一部分值得一提的细节PackageManager.buildExternalPackageScanSignature将ToolPkgApiCompatibility.supportedApiVersionText()纳入外部包扫描签名PackageManager.kt。这意味着当宿主升级后支持的 API 版本集合发生变化时扫描缓存会随之失效并重新扫描防止旧缓存掩盖新版本判定属于对兼容性机制的工程化加固。四、包依赖与加载顺序requires声明4.1 依赖对象的字段与语义ToolPkgManifestRequirement.kt 定义了requires中的每一项依赖Serializable data class ToolPkgManifestRequirement( val id: String, val description: String, SerialName(min_version) val minVersion: String? null, SerialName(max_version) val maxVersion: String? null )id被依赖包的 ID必填description面向用户的依赖说明必填min_version/max_version可选major.minor.patch格式的版本约束依赖本身决定加载顺序被依赖包必须先于声明方加载。targetVersionFailure实现了版本约束判定目标包版本低于min_version或高于max_version即判定失败并生成具体原因文案below minimum / above maximum / does not declare a version / invalid version 等。4.2 manifest 解析期的归一化校验在 ToolPkgParser.kt 的normalizeRequirements中解析期即完成如下校验id与description去除首尾空白后不得为空min_version/max_version若存在则必须通过ToolPkgPackageVersion.parse的三段式解析若同时声明了上下限则min_version max_version否则报 has a minimum version above its maximum versionrequires列表中不允许出现重复的包 ID大小写不敏感去重。4.3 加载顺序解析引用解析、拓扑排序与环检测ToolPkgLoadOrder.kt 中的ToolPkgLoadOrderResolver是顺序解析核心其输入为容器集合、可用包映射、已启用包名集合与用户偏好顺序preferredOrder。引用解析resolveReference依赖 ID 按小写匹配优先级为容器包Container→ 子包Subpackage→ 可用包Package。要求引用另一容器时依赖边指向该容器要求子包时边指向子包所属容器。失败判定依次检查依赖目标不存在 →requires ... but that package is not available.目标包版本不满足约束 → 输出具体版本差异包要求自身含容器要求自己的子包归属场景→cannot require itself.依赖目标未启用 →requires ... to be enabled.依赖的包自身加载失败 → 级联标记which cannot be loaded.。排序算法构建有向边before → after即依赖方在后对选中容器做基于indegree的拓扑排序每步从入度为 0 的候选中用比较器选出一个比较器优先级为用户偏好顺序索引preferredOrderIndex未出现在列表中的包取Int.MAX_VALUE→ 包名小写 → 包名原串。当requires无约束时加载顺序即用户顺序最终以包 ID 保证确定性。环检测若拓扑排序结束后仍有未排出的节点即判定存在依赖环报告ToolPkg load order contains a dependency cycle involving: ...并让环上所有包进入失败集合不进入执行阶段。五、插件列表顺序 UI用户顺序参与加载根据 3_plugin_order_ui.md插件列表复用已有的拖动排序 UI 与保存机制用户手动排序的结果成为加载顺序解析的基础顺序即上文的preferredOrdermanifest 中的requires依赖关系优先级更高始终覆盖用户顺序最终以包 ID 作为确定性兜底大小写不敏感比较。这意味着包作者可以通过 manifest 声明硬性依赖与顺序而普通用户则能在无约束包之间自由调整加载先后两者互不冲突。六、DTS 声明与文档一致性4_dts_and_documentation.md 确立了以下维护约定examples/types/toolpkg.d.ts保持一份最新版声明不手写多份按版本拆开的 DTS新增公开能力时在相关类型、注册函数与底层 NativeInterface 声明处标注since ToolPkg API x.y.zmanifest 的api_version与宿主注册桥负责实际可用性DTS 只负责开发期提示和文档来源。仓库中已大量落实该约定例如toolpkg.d.ts 顶部声明since ToolPkg API 1.0.0文件内大量 API 标注/** since ToolPkg API 1.0.1 */如生命周期、hook、注册函数等chat.d.ts、core.d.ts、results.d.ts、compose-dsl.d.ts 等类型文件同样按此规范标注。开发者在 IDE 中即可通过since注解判断某 API 需要的最低 ToolPkg API 版本进而决定 manifest 中应声明的api_version。七、市场链路api_version→apiVersion7.1 命名约定5_market_api_version.md 明确了两个命名空间的约定manifest 字段使用api_version包内声明市场发布请求和响应的版本对象使用apiVersion网络/UI 层apiVersion描述宿主 ToolPkg API不代表包自身的version或归档格式formatVer非 ToolPkg 版本不设置apiVersion市场响应中的apiVersion必须可选PACKAGE类型已有数据缺失该字段时客户端按1.0.0解释但不改写市场数据。7.2 客户端实现在 ArtifactMarketModels.kt 中const val LEGACY_TOOLPKG_API_VERSION 1.0.0 fun String?.effectiveToolPkgApiVersion(): String { return this?.trim()?.takeIf { it.isNotBlank() } ?: LEGACY_TOOLPKG_API_VERSION } fun MarketV2Version.effectiveToolPkgApiVersion(): String { return apiVersion.effectiveToolPkgApiVersion() }市场服务模型 MarketStatsApiService.kt 的版本响应对象如ArtifactProjectRankDefaultVersionResponse携带可空字段val apiVersion: String? null新发布与发布新版本请求携带version.apiVersion并沿发布界面只读字段、市场列表卡片、详情、版本历史与发布预览保持一致展示。7.3 端到端语义小结环节字段名缺省行为说明manifest包内api_version按1.0.0解释描述包使用的宿主 API 版本市场请求/响应apiVersion可选缺失按1.0.0展示不改写数据与包自身version、归档formatVer无关DTS 类型声明since ToolPkg API x.y.z—开发期提示不参与运行期校验宿主校验requireSupported1.0.0兜底不支持的版本在包进入执行阶段前报告八、包开发实践清单基于以上机制面向 ToolPkg 包作者给出可落地的检查清单声明api_version新包建议显式写明api_version: 1.0.0若使用1.0.1新增的 API可借助 DTS 的since标注识别请确认目标用户 Operit 版本 ≥1.12.14否则包会被拒绝进入执行阶段保持三段式版本api_version与依赖约束min_version/max_version必须为major.minor.patchOperit 版本判定支持build后缀合理使用requires每个依赖项必须提供id与面向用户的description有版本要求时给出min_version/max_version且上下限顺序合法、无重复 ID避免依赖环与自引用包不能要求自身依赖关系成环时环上所有包都不会加载并收到明确的 cycle 报告理解加载顺序优先级requires决定硬性先后 → 插件列表用户顺序作为无约束包的基础顺序 → 包 ID 兜底确定性发布到市场时确认apiVersion随版本对象正确携带缺失旧数据按1.0.0展示但不会被改写。九、相关设计文档与源码索引本主题的完整设计记录位于 docs/TODO/toolpkg_api_version_and_load_order/共 6 个文件index.md总览与分步记录、1_manifest_and_compatibility.md本文核心、2_package_dependencies_and_order.md依赖与顺序、3_plugin_order_ui.md插件列表顺序、4_dts_and_documentation.mdDTS 标注约定、5_market_api_version.md市场 API 版本。关键源码与证据位置ToolPkgApiVersion.kt兼容性常量、版本解析、requireSupported校验ToolPkgParser.ktmanifest 字段定义与requires归一化ToolPkgManifestRequirement.kt依赖对象与版本约束判定ToolPkgLoadOrder.kt引用解析、失败判定、拓扑排序与环检测PackageManager.kt包加载流程与扫描签名ArtifactMarketModels.kt 与 MarketStatsApiService.kt市场版本对象apiVersion链路examples/types/toolpkg.d.tsDTS 单一来源与since标注examples/worldbook/manifest.json带api_version的真实 manifest 示例。赞分享AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载相关推荐Operit DeepSeek Harness ToolPkg 交付链路解析从示例 manifest 到可安装 .toolpkg 的完整打包与验证Operit DeepSeek Harness ToolPkg 交付链路解析从示例 manifest 到可安装 .toolpkg 的完整打包与验证 DeepSAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit 市场客户端版本兼容性强制安装前版本校验的端到端落地Operit 市场客户端版本兼容性强制安装前版本校验的端到端落地 导读 本文基于 Operit 仓库中「市场客户端版本兼容性Marketplace clieAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit 市场包版本兼容性治理客户端安装强制校验与双端一致化实践Operit 市场包版本兼容性治理客户端安装强制校验与双端一致化实践 本文聚焦 Operit 开源项目中市场Marketplace条目版本兼容性这一主AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化上一篇录音低频糊了看不见Spek 声学频谱分析器 3 分钟上手指南下一篇Office文件快速预览指南2分钟装好 QuickLook OfficeViewer-Native 插件空格打开 Word、Excel、PPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考