企业官网建设流程全解析

WebToApp 内建 Agent 深度解析：手机端基于工具调用的全功能自动化助手

【免费下载链接】web-to-appThe most full featured web-to-app toolkit on Android, a complete APK workshop that runs entirely on your phone项目地址: https://gitcode.com/GitHub_Trending/web/web-to-app

导读

WebToApp 的内建 Agent 是一个运行在应用内部的"工具调用型（tool-calling）"AI 助手，它不只停留在对话层面，而是能够直接操作整个 WebToApp 的界面与能力面：创建/编辑/构建应用、管理端口与浏览器引擎、安装运行时、维护广告拦截订阅、检查应用健康度，甚至读写项目文件。本文以 docs/guide/more-features/agent.md 为主体，结合仓库中app/src/main/java/com/webtoapp/core/agent的引擎、工具注册表、权限与计划模式实现，带你理解该功能的完整能力边界、使用方式与底层工作原理。

Agent 是什么，从哪里进入

Agent 是应用内置的一名"能动手的助手"。与普通聊天机器人不同，它的核心机制是function/tool calling：大模型在推理过程中声明需要调用哪些工具、传入哪些参数，应用在本机执行这些工具并返回结果，模型再基于结果继续推理，如此循环直到任务完成。

入口位置：主界面右上角⋮（更多菜单）→ Agent。相关导航说明见 docs/guide/main-screen/more.md。

能力清单：Agent 能做什么

除生成 Web App、扩展模块、userscript、MV3 Chrome 扩展与本地运行时项目外，Agent 还能直接在应用内执行以下操作：

• 应用生命周期：创建、编辑、复制、删除、构建 APK/AAB、导出、分享、创建快捷方式、移动到分类。
• 端口与引擎：扫描/杀掉端口，查看/选择/删除浏览器内核引擎（WebView、GeckoView）。
• 运行时：查看状态、安装、清理 Node.js、PHP、Python、Go、WordPress 以及 Linux 环境的缓存。
• 广告拦截：查看规则数量与来源，导入/移除/启用/禁用 hosts 订阅。
• 统计与健康：使用统计、URL 健康检查。
• 应用修改器：列出已安装应用、克隆/换壳（clone/rebrand）应用、从文本批量导入、导出模板。
• 构建环境与合规：初始化 Linux 构建环境、安装组件、执行 Google Play 政策检查。
• 模块：列出、创建、更新扩展模块。
• 文件：对项目文件进行读、写、编辑、删除、列表、glob、grep 操作。

这些能力并非纸面清单——在源码中每一个能力都对应一个真实注册的工具类。参见 ToolRegistryFactory.kt 中的baseTools()列表：CreateAppTool、BuildApkTool、ExportAabTool、ScanPortsTool、KillPortTool、SelectEngineTool、InstallRuntimeTool、ManageHostsRulesTool、CloneAppTool、InitializeBuildEnvTool、CheckPlayPolicyTool、CreateModuleTool、ReadFileTool/WriteFileTool/EditFileTool/DeleteFileTool/GlobTool/GrepTool等一应俱全。

核心特性

会话（Sessions）

每次对话都有独立的标题与历史记录。从 SessionModels.kt 可见，每个AgentSession包含id、title（且支持titleAutoGenerated自动生成）、messages、config、planSlugs（关联的计划文件）、pinned置顶标记与时间戳；SessionConfig则记录了该会话使用的文本/图像模型、temperature（默认 0.7）、maxTurns（默认 24）、自定义规则、上下文关联的应用/模块 ID 以及会话期间构建出的 APK 产物（builtApks会持久化，重启应用后依然存在）。

最多 57 个内置工具

Agent 内置工具按领域分组：文件、应用、生命周期、端口/引擎、hosts/运行时、统计/修改器/导入、构建环境/Play、模块、图像（imagery）、计划模式（plan mode）。其中：

• 图像工具（GenerateImageTool、ViewImageTool、ListImagesTool）仅在加载了具备图像能力的模型时才注册——见 ToolRegistryFactory.kt，hasImageModel为真且图像生成器注册表非空时才注入。
• 只读工具直接执行，无需确认；写操作工具会先征求用户许可。
• 数量核算：基础工具 52 个 + 计划模式 2 个（EnterPlanMode/ExitPlanMode）+ 图像 3 个 = 57 个，正好对应文档中的 "up to 57 built-in tools"。

计划模式（Plan mode）

Agent 可以先提出方案，等待你批准后再实际改动，处于计划模式时会显示计划模式徽标（plan-mode badge）。底层由 PlanManager.kt 支撑：

• 进入计划模式后会在会话沙箱中创建一个.plans/<slug>.md计划文件（PLANS_DIR = ".plans"），slug 由形容词+名词随机组合生成（如amber-eagle-river），并尝试保证唯一性。
• 计划模式下 PermissionChecker.kt 会收紧工具权限：只允许Read、Glob、Grep、ListFiles、AskUserQuestion、EnterPlanMode、ExitPlanMode，以及仅针对计划文件本身的Write/Edit/Delete（通过effectivePlanFile()路径校验），其余写工具一律 Deny。
• 提交计划后触发PlanReviewRequired事件，待用户批准后approve()才把权限模式恢复到基线（baseline）并关闭计划状态。

韧性（Resilience）

遇到 429/5xx 等可恢复错误时，Agent 会自动带退避（backoff）重试。在 AgentEngine.kt 中：重试次数上限为MAX_RATE_LIMIT_RETRIES，退避时间优先取服务端返回的retryAfterMs，否则按1000L shl (n-1)指数递增（最多左移 4 位）；重试时会从本轮起点截断已累积的输出（rebuildAccFromPrefix()），避免界面时间线与持久化消息中出现重复内容或"幽灵工具调用"。此外还内置流空闲超时（STREAM_IDLE_TIMEOUT_MS）与输出长度续写机制（maxContinuations = 3）。

配置：模型与密钥来自 AI Settings

Agent 使用AI Settings中配置的模型与 API 密钥，详见 docs/guide/more-features/ai-settings.md。要点：

• 内置提供商目录覆盖推荐（Google Gemini、OpenRouter）、国际（OpenAI、Anthropic、Grok）、聚合（Together、Perplexity、Fireworks）、中文（DeepSeek、Qwen、GLM）、自托管（Ollama、LM Studio、vLLM）五类；其余走Custom自定义端点，可声明 API 格式（Chat Completions/chat/completions、Anthropic Messages/v1/messages、OpenAI Responses/responses、Gemini），网关按声明格式路由。
• 每个密钥可带别名，支持连接测试（connection OK / fail），密钥安全存储在设备本地。
• 模型可单独或批量添加，配置能力（capabilities）与可用场景，并有价格参考辅助选型。
• 高级选项可设置Context capacity（上下文窗口大小）。
• 注意：在至少配置一个有效 API 密钥与模型之前，Agent 无法工作。

在源码层，请求路由由 LlmGateway.kt 完成：DefaultLlmGateway内部持有 Anthropic、Gemini、Ollama、Responses、OpenAI-Compatible 五个 Provider，按supports()依次匹配；Custom 端点按其声明的ApiFormat匹配 Provider，而非仅凭枚举类型。

工作原理：从系统提示到工具循环

Agent 的运行可拆解为四个环节：

1. 系统提示组装：SystemPromptBuilder.kt 按顺序拼接六个区块——身份（Identity）、行为（Behavior）、工具用法（ToolUsage，注入当前会话可用工具的声明）、环境（Environment，含模型名与会话目录）、项目文件摘要（ProjectFiles）、计划模式说明（PlanMode，仅计划模式下注入），并会随应用语言切换提示语言。
2. 多轮工具循环：AgentEngine.kt 的run()在1..maxTurns轮内反复：向网关发起流式聊天请求（携带工具声明）→ 解析文本增量/思考增量/工具调用参数流 → 按批执行工具（支持并行批runParallel与串行批runSequential）→ 将工具结果回填为TOOL角色消息 → 进入下一轮，直到模型不再调用工具或达到轮次上限。
3. 工具执行与权限：每个工具实现 Tool.kt 接口（name、description、parametersSchema、isReadOnly()、execute()）；PermissionChecker依据四种模式裁决——AutoApprove直接放行、Plan仅允许只读与计划文件写入、Default对写工具弹窗询问（支持"始终允许"记忆到会话内alwaysAllow）、Dream仅放行只读与.memory/目录写入。执行前还会对参数做 200 字符预览截断，保证权限弹窗不会因异常参数而崩溃。
4. 产物落盘：工具返回的ToolResult会被记录进消息历史（含运行状态哨兵、结果预览），本轮输出、思考片段与工具调用标记（TH:/TC:内联标记）都会持久化，使界面时间线能按真实发生顺序交错渲染思考块与工具调用。

使用注意：Agent 产出的是"源码"与"动作"

文档特别强调：Agent产出源码（producessource）并执行动作（performsactions）。例如它生成了一个扩展模块文件，这不等于该扩展已安装生效——需要走Extension Modules的保存流程将其正式安装，详见 docs/guide/more-features/extension-modules.md。

源码层面这一分工由agent/export包落实：SaveSessionAsModuleUseCase.kt 会把会话中检测出的 JS 模块、样式模块、userscript 等产物解析并保存为正式扩展模块（含ModuleAuthor、ModuleCategory、ModuleVersion、UrlMatchRule等元数据），而 SaveSessionAsAppUseCase.kt 负责把会话产物落成应用。也就是说：生成在会话沙箱，安装/生效则在导出用例中完成，两者边界清晰。

小结

WebToApp 的 Agent 是"对话式生成 + 本机工具执行"的完整实现：57 个按领域分组的工具覆盖应用生命周期、运行时、构建、广告拦截与文件操作；计划模式、只读直放/写操作确认的权限模型、429/5xx 自动退避重试保证了它在手机端可安全、稳定地长期运行。理解core/agent下的引擎、权限与导出分层，是二次开发或深度使用该功能的最佳起点。

【免费下载链接】web-to-appThe most full featured web-to-app toolkit on Android, a complete APK workshop that runs entirely on your phone项目地址: https://gitcode.com/GitHub_Trending/web/web-to-app