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工具包公开 API 的能力声明与版本分发设计版本声明不再由 Kotlin 侧维护集中映射表而是直接写在每个 JS facade 的属性旁通过ToolPkgApi.namespace(Tools.Chat, { call: ToolPkgApi.method().since(1.0.1, implementation) })这类链式语法糖完成。读完本文你将理解 manifest 中api_version的校验语义、JS runtime 如何在调用时按版本选择实现变体、注册桥如何在本地声明能力限制以及 native 工具分发为何不再感知 API 版本。一、设计背景从集中 catalog 到本地声明1.1 原本状况在引入本地声明之前ToolPkg API 的版本判断散落在三个位置Tools.Chat.call调用点、ToolPkg 注册桥、以及运行时参数传递。上一版集中 catalog 的设计又把公开 API 名称、tool 名称、registration 名称塞进同一张表三者之间的对应关系需要人工维护任何一侧新增接口或改名都要同步修改映射维护成本居高不下。该设计文档docs/TODO/toolpkg_api_capability_dispatch/index.md给出的核心修正是彻底放弃集中映射表把能力声明下沉到每个 API 自己的 JS facade 属性旁Kotlin 只做两件事——校验 manifest 的api_version是否受当前宿主支持并把该值放入执行上下文。1.2 修改意图精简ToolPkgApiCompatibility为“版本解析 支持版本判断”不再维护 API/tool/registration 的等价关系manifest.requires仅作为包依赖和加载顺序元数据解析ToolPkg.registerChatMessageMenuItem/registerChatRuntimeHook在注册桥本地声明能力限制Tools.Chat.call在JsTools.kt的 JS facade 中本地声明版本变体移除 tool/registration 到公开 API 的集中映射表。二、JS API 声明语法糖namespace 与 method().since2.1 目标语义按 1_capability_registry.md 的定义声明语法糖需要满足调用点使用ToolPkgApi.namespace(Tools.Chat, { call: ToolPkgApi.method().since(1.0.1, implementation) })链式声明runtime 用namespace 和属性键自动确定公开 API 名称版本限制在公开 API 调用时检查Kotlin 只验证 manifest 的api_version是否为宿主支持的版本不维护tool 名称、registration 名称到公开 API 的等价集中映射。2.2 底层实现JsToolPkgApiRuntime该设计在仓库中已有对应实现runtime 辅助脚本由 JsToolPkgApiRuntime.kt 生成并通过__operitExpose挂载为__operitToolPkgApi对外暴露currentCallId、currentVersion、namespace、method四个入口。其内部实现了完整的声明与分发语义method()返回一个链式 builder通过since(apiVersion, invoke)持续追加版本变体build(apiName)产出最终的可调用函数function method() { var variants []; var builder { __operitToolPkgApiMethod: true, since: function(apiVersion, invoke) { variants.push({ since: apiVersion, invoke: invoke }); return builder; // 支持继续追加同名 API 的新版本实现 }, build: function(apiName) { return versionedMethod(apiName, variants); } }; return builder; }namespace(publicName, members)用“命名空间 属性键”拼出完整公开 API 名称遍历 members凡是被标记为__operitToolPkgApiMethod true的成员就调用member.build(normalizedNamespace . memberName)把Tools.Chat与call组合成Tools.Chat.call普通成员如常量、普通函数原样透传function namespace(publicName, members) { var normalizedNamespace cleanNamespace(publicName); // ... members 必须是普通对象 Object.keys(members).forEach(function(memberName) { var member members[memberName]; output[memberName] member member.__operitToolPkgApiMethod true typeof member.build function ? member.build(normalizedNamespace . memberName) : member; }); return output; }2.3 版本比较与变体选择版本解析parseVersion强制要求major.minor.patch三段式正则^([0-9])\.([0-9])\.([0-9])$不满足则抛出must use major.minor.patch format错误变体归一化normalizeVariants要求至少声明一个版本变体、每个变体必须提供invoke实现函数、since版本不得重复并按since升序排序调用时选择selectVariant读取当前调用上下文中的manifest.api_version见currentApiVersion()先与最早引入版本比较——若当前版本早于 API 引入版本抛出统一的unsupported错误throw new Error( apiName requires ToolPkg API requiredVersion , but manifest.api_version is currentText . );随后从排序后的变体列表中选出since 当前版本的最后一个实现即“当前版本能用的最新实现”若一个都不满足则抛出apiName has no implementation for ToolPkg API current.text。这套逻辑印证了文档中的预期行为“新增同名 API 多版本实现时在该 API 的本地链式调用追加.since(version, implementation)即可”无需改动任何映射表。三、manifest.api_versionKotlin 只做支持性校验3.1 版本解析与支持列表Kotlin 侧的版本模型在 ToolPkgApiVersion.kt 中定义ToolPkgApiVersion数据类major/minor/patch三段compareTo逐位比较ToolPkgApiCompatibility常量LEGACY_API_VERSION 1.0.0默认值所有未声明api_version的旧包都视为 1.0.0API_VERSION_1_0_1 1.0.1API_VERSION_1_0_1_INTRODUCED_IN_OPERIT 1.12.14即 ToolPkg API 1.0.1 从 Operit 1.12.14 起才受支持supportedApiVersions(operitVersion)始终包含 1.0.0仅当当前 Operit 版本 ≥1.12.14时才追加 1.0.1requireSupported(apiVersion, operitVersion)解析 manifest 声明值并断言其在支持列表中否则给出明确错误提示“ToolPkg API 1.0.1 requires Operit 1.12.14 or newer”。3.2 解析入口ToolPkgParser.ktapp/src/main/java/com/ai/assistance/operit/core/tools/packTool/ToolPkgParser.kt在解析 manifest 时SerialName(api_version) val apiVersion: String ToolPkgApiCompatibility.LEGACY_API_VERSION字段缺省时回落为1.0.0解析流程调用ToolPkgApiCompatibility.requireSupported(manifest.apiVersion)做支持性校验requires: ListToolPkgManifestRequirement作为包依赖与加载顺序元数据单独解析不再承载 API 能力信息。JS 引擎侧JsEngine.kt在装载包时同样调用ToolPkgApiCompatibility.requireSupported(...)并把解析出的版本放入执行上下文供 JS runtime 的currentApiVersion()读取。3.3 真实包示例仓库内示例包的 manifest 即为佐证examples/message_translation/manifest.json 使用api_version: 1.0.1其余大多数示例如 examples/apktool/manifest.json、examples/plan_mode/manifest.json 使用1.0.0{ schema_version: 1, toolpkg_id: com.operit.message_translation, version: 0.1.0, api_version: 1.0.1, main: dist/main.js, display_name: { zh: 消息翻译, en: Message Translation }, description: { zh: 在聊天消息长按菜单中加入翻译入口并通过 ToolPkg Compose DSL 弹窗显示原文与译文。 }, enabled_by_default: true, subpackages: [] }四、注册桥的本地能力声明注册桥 JsToolPkgRegistration.kt 正是语法糖的直接消费者。registerChatMessageMenuItem与registerChatRuntimeHook两个注册能力用toolPkgApi.method().since(1.0.1, ...)本地声明其最低 API 版本实现函数分别是buildCustomRegistration(...)菜单项定义归一化与buildFunctionRegistration(...)钩子函数注册registerChatMessageMenuItem: toolPkgApi.method().since( 1.0.1, buildCustomRegistration( registerChatMessageMenuItem, registerToolPkgChatMessageMenuItem, normalizeChatMessageMenuItemDefinition ) ), registerChatRuntimeHook: toolPkgApi.method().since( 1.0.1, buildFunctionRegistration( registerChatRuntimeHook, registerToolPkgChatRuntimeHook ) )这意味着若当前包的manifest.api_version低于1.0.1调用这两个注册能力时 runtime 会抛出统一的requires ToolPkg API 1.0.1错误而 Kotlin/native 侧无需为这两个注册器做任何版本分支——能力限制完全由 facade 本地声明承载。其余一批旧注册 APIregisterAppLifecycleHook、registerMessageProcessingPlugin、registerXmlRenderPlugin、registerChatMessageHook等则通过apiMethod(name, nativeName)直接安装函数注册未附加since版本门槛对应 1.0.0 时代的既有能力。五、Native 分发边界业务处理器不再感知版本按 3_native_dispatch.md 的设计边界toolCall()继续通过执行会话携带 ToolPkg API 上下文__operitCurrentCallId→__operitGetCallState(callId)→state.toolPkgApi.apiVersionJS facade 在调用时自行读取并检查公开 facade 自己声明并检查能力限制native 工具分发不维护 tool 名称到公开 API 名称的集中映射业务工具处理器不再接收__operit_toolpkg_api_version这类内部版本字段。也就是说版本感知被严格限制在“JS facade 调用时”这一个点上游把api_version放进执行上下文下游只消费已选择好的实现中间层的工具分发器对 API 版本完全无感。仓库当前代码中已不存在__operit_toolpkg_api_version内部参数印证了该边界已经落实。六、测试与文档预期4_tests_and_docs.md 明确了配套测试与文档的验收口径旧 API 调用新公开能力例如 1.0.0 包调用since(1.0.1, ...)的能力时得到统一错误——即requires ToolPkg API 1.0.1错误路径新 API 走对应本地实现变体——通过selectVariant的升序变体列表选择最新可用实现测试不依赖集中 catalog 或 tool/registration 映射表直接针对 facade 本地声明行为断言面向用户开发者的文档只说明 manifest 版本语义与使用要求api_version的取值、默认值、支持矩阵不写内部开发日志或实现过程。仓库内的 JS 测试app/src/androidTest/js、app/src/test/java下共 183 个 Kotlin/JS 测试文件覆盖 ToolPkg 加载与执行链路可作为验证上述行为的参考。七、总结一次“就近声明”的能力治理这套设计的本质是把“某 API 需要哪个 ToolPkg API 版本”这一信息从集中 catalog 挪回 API 自己的定义处职责归属实现位置版本解析、支持版本判断KotlinToolPkgApiVersion.ktmanifestapi_version/requires解析KotlinToolPkgParser.ktnamespace/method().since 语法糖与运行时选择JS runtimeJsToolPkgApiRuntime.kt注册能力本地声明菜单项/运行时钩子JS facadeJsToolPkgRegistration.kt工具调用分发不感知版本NativetoolCall()执行会话链路收益直观新增接口只改接口附近代码同名 API 的新版本实现只需追加.since(version, implementation)Kotlin 不再维护三重名称映射。对 ToolPkg 包开发者而言只需要在 manifest 中如实声明api_version并在自己的 JS facade 中用语法糖标注每个能力的最低版本其余版本适配与错误提示均由 runtime 自动完成。赞分享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 API 版本声明与加载顺序机制全解析Operit ToolPkg API 版本声明与加载顺序机制全解析 本文以 Operit 仓库中 docs/TODO/toolpkg_api_version_aAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit ToolPkg API 本地能力分发Native 分发边界的内部版本字段移除与版本变体设计Operit ToolPkg API 本地能力分发Native 分发边界的内部版本字段移除与版本变体设计 本文聚焦 Operit 中 ToolPkg工具包AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit ToolPkg 共享 JS Runtime 设计namespace() 与 method().since() 驱动的本地化 API 版本变体声明Operit ToolPkg 共享 JS Runtime 设计 namespace 与 method .since 驱动的本地化 API 版本变体声明 导读AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化上一篇FeHelper终极指南20实用工具让前端开发效率翻倍下一篇如何用DouyinLiveRecorder轻松录制60平台直播内容终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
