★ FEATURED ARTICLE 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/doc-src/architecture/DEFAULT_TOOLS_ARCH.md 展开系统讲解 Android AI Agent 中“默认工具default tools”的完整链路从 LLM 看到的 Prompt/Schema到 Kotlin 执行实现、JS/TS 脚本封装、示例与打包产物。读完本文你将掌握修改任意工具参数/签名时必须同步修改的全部文件清单、全局搜索防遗漏方法、编译级自检命令以及新增一个工具时的一站式落地方案并能在源码层面理解每一层的真实实现。1. 默认工具的组成一条从上到下的数据流在 Operit 中“默认工具”不是单个文件而是一条贯穿“对外契约”与“内部实现”的数据流。文档将其归纳为 7 层工具 Prompt / Schema——工具对 LLM 的“说明书”决定模型如何生成 tool call工具注册——把toolName - executor绑定起来工具执行实现——Kotlin 侧真正做事的逻辑脚本侧封装JS Tools——给 JS/TS 脚本更好用的 API示例与类型定义——examples/types与examples/**文档——docs/doc-src/package-dev等打包资源 / 产物——app/src/main/assets/packages/*.js等。其中第 (1)(4)(5)(6) 层是“对外契约”第 (2)(3) 层是“实现”。任何一层不同步都会出现“LLM 按旧参数调用”或“脚本侧类型不一致”这类运行时问题。在源码中可以逐一印证这 7 层Schema 层SystemToolPrompts.kt 中的ToolPrompt与ToolParameterSchema约 1007 行例如read_file定义了path、environment、intent、direct_image、direct_audio、direct_video等参数且environment的取值说明为android | linux | repo:仓库名注册层ToolRegistration.kt 中的registerAllTools(handler, context)约 2745 行通过handler.registerTool(name, descriptionGenerator, executor)完成绑定实现层core/tools/defaultTool/下的standard/、debugger/、admin/、root/、accessbility/五套实现JS 封装层JsTools.kt 中的getJsToolsDefinition()约 1593 行生成注入到 JS 运行时的Tools对象类型定义层examples/types/*.d.ts如files.d.ts、chat.d.ts、core.d.ts、system.d.ts等示例层examples/*.ts及其编译产物examples/*.js打包层app/src/main/assets/packages/*.js如system_tools.js、extended_file_tools.js、browser.js等约 30 个运行时包。小结修改任何一个工具的“参数/签名”本质上是在这条 7 层数据流上做一致性变更。下面每一节对应一层并给出必改项。2. 改参数时必须改哪些文件Checklist文档的核心价值在于一份可执行的“必改/常见遗漏/可选校验”清单。本节按层展开并补充源码级依据。2.1 必改工具 Schema / Prompt文件SystemToolPrompts.kt要做的事修改对应工具的parametersStructured新增/删除/改名/调整required更新description/details尤其是规则、示例、参数解释注意中英文双份描述如basicTools与basicToolsCn、fileSystemTools与fileSystemToolsCn两处都要同步。源码佐证ToolParameterSchema支持name、type、description、required、default等字段。例如sleep工具的参数duration_ms声明为type integer、default 1000、required falseuse_package的package_name为required true。中英文两份定义basicTools/basicToolsCn结构完全对应。为什么必须改这是 LLM 生成 tool call 的唯一依据。只改执行层不改这里LLM 仍会按旧参数调用造成“参数不匹配”的连续失败。2.2 必改工具注册toolName - executor文件ToolRegistration.kt要做的事工具名不变时一般无需改注册但要确认注册项绑定的 executor 没变若工具名/分组变更如拆分工具必须同步调整注册项。源码佐证注册层大量使用handler.registerTool(name ..., descriptionGenerator { tool - ... }, executor { tool - ... })。描述生成器会从tool.parameters.find { it.name ... }读取参数拼装人类可读描述——例如execute_shell读取command、create_terminal_session读取session_name。这意味着即使参数名变了而描述生成器里的it.name未同步描述也会变成空值。另外ToolRegistration.kt 中的parseProxyInvocation展示了“代理调用”的参数白名单机制只允许tool_name、params及__operit_package_caller_name等系统上下文参数多余参数会直接返回Unexpected parameters错误。若你改动的是代理类工具需要关注这里的白名单。为什么必须看改工具名或拆分工具时注册未同步会出现“工具不存在/无法执行”。2.3 必改Kotlin 执行实现参数读取与校验常见目录均在app/src/main/java/com/ai/assistance/operit/core/tools/defaultTool/下standard/*标准权限实现如 StandardFileSystemTools.kt、StandardUITools.ktdebugger/*如 DebuggerFileSystemTools.ktadmin/*如 AdminFileSystemTools.ktroot/*如 RootFileSystemTools.ktaccessbility/*如 AccessibilityFileSystemTools.ktToolGetter.kt按权限级别选择具体实现。要做的事将旧参数的读取逻辑替换为新参数典型写法tool.parameters.find { it.name ... }如果某工具在debugger/root/admin/accessibility目录下有 override/替代实现这些实现里同样要同步更新参数读取与校验新增参数合法性校验必填、互斥、默认值、兼容性策略更新错误消息使其能引导正确用法。源码佐证ToolGetter.kt 是权限分发的核心getFileSystemTools、getUITools、getSystemOperationTools、getDeviceInfoToolExecutor都依据androidPermissionPreferences.getPreferredPermissionLevel()在ROOT / ADMIN / DEBUGGER / ACCESSIBILITY / STANDARD之间切换null时回退到Standard*实现。因此同一工具在不同权限级别下可能有 4~5 份实现漏改其中一份就会导致“高权限环境行为不一致”。为什么必须改不改这里即使 schema 改了执行层也拿不到参数或行为不对。2.4 必改JS 侧工具封装Tools.*文件JsTools.kt要做的事更新对应的 JS wrapper 函数签名更新 wrapper 内部构造的params对象字段名注意undefined/null的处理JS 传参常见问题。源码佐证getJsToolsDefinition()生成的Tools对象中Tools.Files封装了list/read/readBinary/readPart/write/writeBinary/deleteFile/exists/move/copy/mkdir/find/grep/grepContext/info/apply/create/edit/zip/unzip/open/share/download等。注意封装层与 LLM 工具的命名并不一一对应Tools.Files.read实际调用toolCall(read_file_full, ...)Tools.Files.readBinary调用toolCall(read_file_binary, ...)Tools.Files.write调用toolCall(write_file, ...)Tools.Files.apply(path, type, oldContent, newContent, environment)调用toolCall(apply_file, { path, type, old?, new? })Tools.Files.create调用toolCall(create_file, { path, new })Tools.Files.edit调用toolCall(edit_file, { path, old, new })。这印证了文档中的关键警告“许多脚本调用的是Tools.Files.xxx而不是直接 toolCall”。修改底层工具参数时必须同步改写 wrapper 里params的字段名否则脚本侧仍然会按旧字段组装。2.5 必改TypeScript 类型定义对脚本作者的契约文件examples/types/*.d.ts尤其是examples/types/files.d.ts、examples/types/chat.d.ts、examples/types/core.d.ts、examples/types/system.d.ts等要做的事更新函数签名与参数类型若新增枚举/联合类型如replace | delete | create补充 type 定义确认返回类型与字段名仍然正确。为什么必须改这是脚本作者写 TS 时的类型提示来源。类型与运行时不一致编辑器不报错但运行报错是最隐蔽的一类问题。2.6 必改示例代码TS/JS目录examples/**如 examples/system_tools.ts、examples/extended_file_tools.ts 等要做的事更新示例里对Tools.*的调用参数通常优先改*.ts源码仓库中存在*.ts - *.js的编译产物一般只需要改 TS 并重新构建产物不建议手动修改*.js若存在“编译后的 JS 产物/打包后的单文件”需确保重新构建后产物也被更新见 2.7。补充说明advice-only 工具若某个工具仅用于说明/提示如usage_advice在 examples 的 metadata 里加入advice: true标记为advice: true的工具不要求在运行时存在真实实现可跳过“工具不存在”的校验。为什么必须改示例是实际用法会直接误导使用者同时示例产物可能被打包进 app。2.7 必改打包资源 / 产物文件常见位置app/src/main/assets/packages/*.jsApp 运行时加载的包文件如system_tools.js、browser.js、workflow.js等约 30 个examples/*.js可能是构建产物或分发用 bundle。要做的事若这些文件由构建脚本生成优先重新构建若当前仓库直接提交产物需手动同步修改产物中的调用签名。packages 同步约定重要examples/*.ts通常作为脚本包的源代码examples/*.js作为编译产物/分发产物不建议手改app/src/main/assets/packages/*.js作为 App 运行时加载的包文件仓库提供 sync_example_packages.py约 1099 行按 packages_whitelist.txt 中的清单含12306.js、system_tools.js、browser.js、linux_ssh、worldbook等 40 项将examples/*.js复制到app/src/main/assets/packages/*.js。同步执行约定重要做包同步时只需执行一条命令python tools/example_packages/sync_example_packages.py不要额外手动复制examples/*.js到assets/packages/避免源/产物不一致。因此修改脚本包功能的推荐流程是优先改examples/package.ts通过构建/编译生成对应的examples/package.js运行python tools/example_packages/sync_example_packages.py同步到assets/packages/不建议直接手动修改examples/*.js或assets/packages/*.js避免被后续构建覆盖或造成源/产物不一致。为什么必须改App 实际运行时可能直接加载 assets 里的 JS 包只改了 TS 不改 assets运行仍会调用旧参数。2.8 必改文档常见位置docs/doc-src/package-dev/*.md、docs/doc-src/**/*.md要做的事更新 API 描述、参数说明、示例以及“关键规则/注意事项”。为什么必须改文档是对外说明很多线上问题其实来自文档与实现不一致——文档写旧参数用户照抄自然报错。3. 强烈建议全局搜索旧参数名找遗漏当你把某个参数例如content改为old/new/type时建议按需调整关键词执行以下搜索确认没有遗留在 toolCall、schema、示例、assets 中搜工具名如apply_file搜旧参数名如content搜新参数名如old/new/type。注意如果你在 Kotlin/TS/JS 三端都封装了同一套工具接口任何一端遗留都会导致不一致。搜索时应覆盖app/src/main/java/**、examples/**、app/src/main/assets/packages/**三个区域。从源码结构看apply_file确实是“一对多”委派的枢纽create_file、edit_file的 schema 说明里明确写着“delegating to apply_file with typecreate / typereplace”见 SystemToolPrompts.kt 第 152-169 行。因此改apply_file的参数时create_file/edit_file的 schema、Tools.Files.apply/create/edit的 wrapper、files.d.ts的类型定义都要联动检查。4. 编译/运行级别的自检避免提交后才爆4.1 Kotlin 编译自检推荐运行:app:compileDebugKotlin或等价 Gradle 任务目的捕捉 JsTools.kt、ToolRegistration.kt、Standard*Tools.kt的签名/引用错误。4.2 示例/脚本侧检查按需如果 examples 有 TypeScript 构建流程跑一次构建例如npm run build或仓库内的 build 脚本如果 assets 由构建生成重新打包生成 assets。5. 常见坑位总结文档总结的四类高频事故每一条都能对应到前面某一层坑位现象对应层级只改了执行层没改 promptLLM 仍按旧参数调用2.1 Schema只改了 prompt 没改 JS wrapper脚本仍按旧参数组装params2.4 JS 封装只改了 TS忘了 assets 里的 bundleApp 运行仍加载旧 bundle2.7 打包产物参数名改动但错误提示没更新用户不知道正确用法反复试错2.3 执行实现结合仓库代码可以补充第五个隐蔽坑只改 LLM 工具名、忘了Tools.*的调用目标名。例如Tools.Files.read调用的是read_file_full而不是read_fileTools.Files.exists调用的是file_exists——封装名与底层工具名并不总是相同的搜索时不能只搜工具名。6. 扩展当你新增一个工具时简版新增工具时通常需要SystemToolPrompts.kt新增ToolPrompt中英文两份ToolRegistration.kt注册执行器Standard*Tools.kt必要时配套Debugger/Root/Admin/Accessibility*Tools.kt实现逻辑JsTools.kt暴露给脚本侧如需要examples/types/*.d.ts类型定义如需要Tools.System.*记得同步examples/types/system.d.tsdocs/doc-src/补文档。这条清单与“改参数”的 7 层一一对应新增工具 在每层各加一个条目而已有工具改参数 在每层同步修改。两者共享同一套一致性心智模型。结语Operit 的默认工具体系是典型的多层契约架构Kotlin 实现负责能力Schema 负责让 LLM 正确调用Tools.*封装与.d.ts类型负责让脚本作者安全调用示例与打包产物负责把改动真正送达运行时。修改任何一个工具的参数/签名本质上是沿着这 7 层做一次“全链路同步”。以本文的 Checklist 为索引配合 SystemToolPrompts.kt、ToolRegistration.kt、ToolGetter.kt、JsTools.kt 与 sync_example_packages.py 逐层核对即可把“改一个参数”这件事从易错的手工活变成可复现的标准流程。赞分享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点击查看免费下载相关推荐gRPC 默认 HTTP 代理映射器Default HTTP Proxy Mapper完全指南环境变量、Channel 参数与源码级实现剖析gRPC 默认 HTTP 代理映射器Default HTTP Proxy Mapper完全指南环境变量、Channel 参数与源码级实现剖析 本指南聚焦后端RPC框架微服务通信Hugo 默认版本default version完全指南从 defaultContentVersion 到源码级解析Hugo 默认版本default version完全指南从 defaultContentVersion 到源码级解析 导读 Hugo 0.153.0 起开发工具前端CLISphinx 2.0 升级指南HTML5 默认输出、master_doc 变更与弃用 API 全景解析Sphinx 2.0 升级指南HTML5 默认输出、master_doc 变更与弃用 API 全景解析 Sphinx 2.0 是 Sphinx 文档生成器本文档开发工具上一篇AssetRipper3步把Unity游戏资源搬进你的项目下一篇魔兽争霸3终极优化指南WarcraftHelper 2024完全配置教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
