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 开源仓库中docs/TODO/toolpkg_api_version_and_load_order/5_market_api_version.md为核心骨架结合app/src/main/java下的真实实现源码展开。读者将掌握 ToolPkg 包如何沿「本地发布源 → 市场发布请求 → 市场版本对象 → 发布界面与市场各展示位」完整传递并一致展示宿主 ToolPkg API 版本理解api_version/apiVersion的命名约定、语义边界、缺省回退规则以及为什么旧数据按1.0.0解释但不改写市场数据。一、为什么市场版本对象需要 API 版本Operit 的 ToolPkg 包通过 manifest 声明自身元数据与资源结构。在引入api_version之前manifest 只有包自身的version字段宿无法在加载前得知包所依赖的宿主 ToolPkg API 版本——包声明「我是什么版本」与「我需要宿主提供哪一版 API」是两个不同维度的信息。市场作为包的发布与分发枢纽如果只记录包的version用户在列表、详情与历史版本中看到的将只是包自身的发布版本号无法据此判断「这个包要求我的 Operit 宿主支持到哪一版 ToolPkg API」。因此本设计的目标是让 ToolPkg manifest 中的api_version沿发布链路进入市场版本对象并在发布界面、市场列表、详情和历史版本中保持一致展示。二、命名约定与语义边界方案对字段命名和语义做了明确约定见 5_market_api_version.md位置字段名说明ToolPkg manifestapi_version包声明其需要的宿主 ToolPkg API 版本市场发布请求与响应中的版本对象apiVersion沿发布链路透传的 API 版本包自身版本version包自己的发布版本号与apiVersion无关归档格式版本formatVer市场版本对象中的归档格式标识与apiVersion无关三条硬性语义边界apiVersion描述的是宿主 ToolPkg API即 Operit 提供给 ToolPkg 运行时的接口能力版本不代表包自身的version也不代表归档格式formatVer。非 ToolPkg 版本不设置apiVersion市场同时承载 Scriptscript-artifact与 Packagepackage-artifact两类制品只有PACKAGE类型ToolPkg 包才携带 API 版本Script 制品不设置该字段。市场响应中的apiVersion必须可选PACKAGE类型已有数据缺少该字段时客户端按1.0.0解释但不改写市场数据。第三条尤为重要——它决定了市场服务的响应模型是向后兼容的新字段可空也决定了客户端只能「解释」旧数据而不能「回写」旧数据避免客户端把过期数据反向污染市场。三、字段命名差异的成因与贯通逻辑同一信息在 manifest 中是 snake_case 的api_version在市场 JSON 中是 camelCase 的apiVersion。从源码看这一差异由两端各自的序列化模型自然承接manifest 侧ToolPkgParser.kt 中的ToolPkgManifest数据类使用SerialName(api_version)映射 Kotlin 属性apiVersion其默认值为ToolPkgApiCompatibility.LEGACY_API_VERSION即1.0.0。市场侧MarketStatsApiService.kt 中的MarketV2Version数据类直接声明val apiVersion: String? null天然可空、可选。两端都以apiVersion作为 Kotlin 侧的统一属性名JSON 侧则各自遵循 manifestsnake_case与市场 APIcamelCase的既有约定这正是「manifest 字段用api_version、市场版本对象用apiVersion」约定在代码中的落点。四、客户端侧manifestapi_version的读取与兼容性校验市场链路的数据源头是本地 ToolPkg 发布源对 manifest API 版本的读取。这一环节由三个组件协作完成。4.1 版本值模型与解析ToolPkgApiVersion.kt 定义了major.minor.patch三段式版本值模型并通过VERSION_PATTERN Regex(^(\\d)\\.(\\d)\\.(\\d)$)强制格式不满足格式的值会直接抛出IllegalArgumentException提示必须使用major.minor.patch格式。排序比较按 major → minor → patch 依次进行供后续「依赖最低版本 / 最高版本」与「宿主支持范围」判断使用。4.2 宿主支持范围与缺省解释同文件中的ToolPkgApiCompatibility对象ToolPkgApiVersion.kt固化了三个关键常量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其语义为1.0.0是历史基线版本所有缺少api_version字段的旧 manifest 都被解释为1.0.0见parseDeclaredApiVersion中ifBlank { LEGACY_API_VERSION }的兜底逻辑1.0.1是新增的宿主 API 版本Operit 从1.12.14开始支持supportedApiVersions(operitVersion)依据当前 Operit 版本默认取BuildConfig.VERSION_NAME动态返回支持列表任何版本都包含1.0.0仅当当前 Operit 版本 1.12.14时才追加1.0.1requireSupported(...)在包进入执行阶段前完成校验校验失败时报错信息同时包含「声明的 API 版本」「当前 Operit 版本」和「宿主支持版本列表」并额外提示1.0.1需要1.12.14或更新版本。4.3 manifest 解析阶段的强制校验ToolPkgParser.kt 中ToolPkgArchiveParser.parseToolPkgFromIndexedEntries解析出 manifest 后的第一件事就是调用val apiVersion ToolPkgApiCompatibility.requireSupported(manifest.apiVersion)随后该解析结果被传入parseMainRegistration(...)ToolPkgParser.kt以apiVersion.toString()形式注入主注册脚本的解析上下文——这意味着 ToolPkg 主脚本在运行时能够感知自己运行于哪一版宿主 API 之上。本地发布源正是从这里获得了经过校验的 API 版本值。五、发布链路本地发布源 → 市场版本对象「本地 ToolPkg 发布源读取 manifest API 版本」之后下一步是让新发布和发布新版本的请求都携带version.apiVersion。5.1 发布描述符与市场注册载荷市场侧模型集中在 ArtifactMarketModels.ktLocalPublishableArtifact增加apiVersion: String?承接本地发布源解析出的值PublishArtifactDescriptor增加apiVersion: String? nullMarketRegistrationPayload增加apiVersion: String? null市场元数据ArtifactMarketMetadata同样携带apiVersion: String?。关键的分支逻辑在buildPublishArtifactDescriptorArtifactMarketModels.ktapiVersion if (type PublishArtifactType.PACKAGE) { localArtifact.apiVersion.effectiveToolPkgApiVersion() } else { null },即只有PACKAGE类型ToolPkg 包设置apiVersionScript 制品显式置空——这与「非 ToolPkg 版本不设置apiVersion」的约定严格对应。buildArtifactMarketMetadataArtifactMarketModels.kt在生成市场元数据时采用完全相同的类型分支保证发布请求体与市场注册元数据行为一致。5.2 缺省回退但绝不改写effectiveToolPkgApiVersion()ArtifactMarketModels.kt是客户端侧「旧数据按1.0.0解释」的落点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() }注意它的语义边界当发布源本地 manifest或市场响应缺少 API 版本时客户端在读取时将其视为1.0.0用于展示与兼容性判断但市场数据本身不会被回写。仓库中的约束是市场响应里的apiVersion字段保持可空MarketV2Version.apiVersion: String?客户端只解释、不改写。5.3 发布服务的实际装配GitHubForgePublishService.kt 负责把发布描述符转成实际的市场注册请求apiVersion descriptor.apiVersionL246与apiVersion payload.apiVersionL449、L484分别出现在发布注册与版本更新请求的组装处确保version.apiVersion真正进入发往市场服务的请求体。发布 release 的说明正文buildPublishReleaseDescriptorArtifactMarketModels.kt也会写入ToolPkg API version: ...行供人工核对。六、市场数据模型可选的apiVersion字段市场响应侧的服务端模型定义在 MarketStatsApiService.ktSerializable data class MarketV2Version( val id: String , val version: String , val formatVer: String , val apiVersion: String? null, ... )三个相邻字段version、formatVer、apiVersion正好构成三个正交维度version包自身的发布版本号formatVerToolPkg 归档格式版本市场格式标记如toolpkg_v2见PublishArtifactType.marketFormatVersion()ArtifactMarketModels.ktapiVersion宿主 ToolPkg API 版本可空。MarketV2EntryMarketStatsApiService.kt通过versions: ListMarketV2Version与latestVersion: MarketV2Version?暴露版本历史与当前最新版本apiVersion由此进入列表卡片、详情页与历史版本三种展示场景。七、界面一致展示只读字段贯通五处「发布界面以只读字段展示 API 版本市场列表卡片、详情、版本历史和发布预览展示 API 版本」是本次改造的收尾要求。对应源码落点发布界面ArtifactPublishScreen.kt 在发布表单中读取versionValue?.apiVersionL110与toolPkgApiVersionL1495以只读字段呈现——API 版本来源于 manifest 解析结果发布者不可在此编辑避免发布界面上的值与包内 manifest 不一致发布预览MarketPublishPreview.kt 在发布前的预览视图中展示将要写入市场的 API 版本供发布者确认市场列表卡片MarketBrowseList.kt 在列表卡片上展示 API 版本详情PackageDetailsDialog.kt 在包详情弹窗中展示当前版本的 API 版本版本历史由 ArtifactMarketViewModel.kt 统一装配市场数据L200、L521将apiVersion分发到上述各 UI 状态。这五处 UI 共享同一个数据源与同一条effectiveToolPkgApiVersion()回退逻辑从而保证「保持一致展示」无论数据来自新发布还是历史遗留展示层看到的都总是「显式值或回退后的1.0.0」。八、与整个 API 版本体系的衔接市场 API 版本并非孤立设计它是 Operit ToolPkg「API 版本与加载顺序」整体方案见 index.md的收尾一环1_manifest_and_compatibility.mdapi_version字段引入、缺省1.0.0、1.12.14支持1.0.0/1.0.1不支持的版本在包进入执行阶段前明确报告2_package_dependencies_and_order.mdrequires依赖与加载顺序约束3_plugin_order_ui.md插件列表用户顺序作为无约束时的加载顺序4_dts_and_documentation.md在 toolpkg.d.ts 中为新增公开能力标注since ToolPkg API x.y.z且明确「manifest 的api_version和宿主注册桥负责实际可用性DTS 只负责开发期提示和文档来源」。市场侧的贯通使这套版本体系从「加载期的本地校验」延伸到「分发期的可见信息」发布者声明、市场记录、用户查看三者始终是同一个 API 版本语义。九、边界与注意事项apiVersion不等于兼容性保证市场记录的apiVersion是发布时声明的宿主 API 需求加载时的最终拦截仍由 ToolPkgParser.kt 的requireSupported完成两者职责不同。旧数据不回写PACKAGE 类型历史数据缺apiVersion时按1.0.0解释但客户端不修改市场数据如需修正应通过重新发布版本来更新市场记录。版本格式强约束API 版本必须为major.minor.patch三段式非法格式在解析阶段即被拒绝Operit 应用版本支持x.y.z或x.y.zn格式见 ArtifactMarketModels.kt 与ToolPkgApiVersion.kt中的OperitVersion.parse。类型分支一致性发布描述符、市场元数据、release 说明三处对apiVersion的处理都必须与「仅 PACKAGE 类型设置」的分支保持一致否则会出现 Script 制品携带无意义 API 版本或 ToolPkg 包丢失版本信息的不一致现象。十、总结Operit 通过「manifestapi_version读取 → 兼容性校验 → 发布请求携带version.apiVersion→ 市场版本对象可选字段 → 五处 UI 一致展示」的完整链路将宿主 ToolPkg API 版本从包的内部声明变成了市场可检索、可展示、可追溯的公开信息。其核心工程决策是命名区分api_versionvsapiVersion、语义正交API 版本 ≠ 包版本 ≠ 归档格式、缺省回退旧数据按1.0.0解释与不回写市场数据。这四个决策共同保证了版本信息在发布链路中的一致性、兼容性与可信度。赞分享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 包 Logo 渲染与 UI 集成指南从 ProviderLogoLoader 到市场卡片Operit ToolPkg 包 Logo 渲染与 UI 集成指南从 ProviderLogoLoader 到市场卡片 本指南以 docs/TODO/toolAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit ToolPkg 市场来源溯源导入通知与自动化测试实现指南Operit ToolPkg 市场来源溯源导入通知与自动化测试实现指南 本文基于 Operit 仓库 docs/TODO/toolpkg_market_oriAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit DeepSeek Harness ToolPkg 交付链路解析从示例 manifest 到可安装 .toolpkg 的完整打包与验证Operit DeepSeek Harness ToolPkg 交付链路解析从示例 manifest 到可安装 .toolpkg 的完整打包与验证 DeepSAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化上一篇douyin-downloader v2.0架构解析双引擎策略与分布式下载队列设计下一篇番茄小说下载器完整指南3分钟学会永久保存任何小说创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考