web-to-app 的 AGENTS.md 深度解读双运行时架构、配置漂移防护与 APK 导出工程规范【免费下载链接】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-appAGENTS.md是 web-to-app 仓库为编码代理编码 Agent与开发者编写的工程规范总纲。它回答的核心问题是在这个手机上把网页变 APK的工具箱里同一份运行时源码如何在宿主编辑器Host与导出的壳应用Shell两条路径上各自生效、又如何保证它们不脱节。读完本文你将掌握该项目预览 ≠ 导出的双运行时心智模型、配置字段端到端流转链路、增量导出缓存、10 语言内联国际化约定、W^X 环境下的进程启动策略以及一套可直接照做的变更 Recipe 与验证命令。一、仓库布局每个目录的角色AGENTS.md 用一张表定义了仓库顶层结构路径角色app/完整的构建器宿主编辑 UI、导出流水线、运行时、预览shell/运行时模板。通过:shell:assembleRelease:app:syncShellTemplateApk构建为app/src/main/assets/template/webview_shell.apkclone-host/宿主侧 APK 克隆/身份重塑支持库。其 DEX 资源生成任务syncCloneHostDex被刻意禁用enabled false为规避杀软误报——AppCloner在没有该资产时走 fail-soft 路径modules/模块市场目录registry.json 各模块文件夹docs/VitePress 文档站guide / developer / extensions中英双语由.github/workflows/docs-deploy.yml部署站点 URL 路径与docs/下文件 1:1 映射/zh/...→docs/zh/...scripts/构建辅助与门禁脚本check_config_field_drift.py其中最关键的一条规则是运行时 Kotlin 源码只在app/下编写由syncShellRuntimeSources任务同步进shell模块——只编辑一次app/源码绝不在 shell 下永久 fork 一份拷贝。二、核心架构编辑器、导出工厂与壳运行时的连接文档给出的连接关系图是理解整个项目的地图编辑器app/ 中的 Compose 界面 ↔ 数据模型WebApp、各配置 ↔ 导出工厂ApkConfig / ApkConfigJsonFactory ↔ ApkBuilder / ApkBuildCache → 签名后的生成 APK app/ 源码 → syncShellRuntimeSources → shell DEX → webview_shell.apk模板 生成的 APK 运行时 WebToAppApplication → ShellModeManager → 读取 assets 中的 JSON 配置 → WebViewManager / 运行时服务器Node/PHP/Python/Go/WordPress对应的心智模型宿主预览Host preview运行:app模块所有类都在主 classpath 上生成的 APK运行壳模板中的类完整运行时从app/同步而来通过ShellModeManager从 assets JSON 读取配置关键结论编辑器的一个开关如果不能沿模型 → ApkConfig JSON → 壳配置 → 运行时代码这条链路流下去在导出时就是无效的。从源码看ShellModeManager.kt 确实从 assets 加载app_config.json支持经AssetDecryptor解密读取失败则回退明文读取找不到文件则返回 null按主 App 模式运行并用 Gson 反序列化为ShellConfig——这正是配置漂移会静默丢字段的地方Gson 遇到未知/缺失字段不报错只跳过。三、双运行时预览与导出为什么可能分叉文档对宿主:app与生成 APK做了逐维度对比| | 宿主:app| 生成的 APK | |--|-------------|---------------| | DEX | 全部app/src类 | Shell 同步的 include−exclude 集合完整运行时集 | | 配置 | 编辑器 / 内存模型 | assets JSON经ShellModeManager| | 模板 | 不使用 |app/src/main/assets/template/webview_shell.apk|因此Preview ≠ Export除非三条同时成立宿主侧仍保留真实实现Shell 同步的代码在运行时从 assets JSON 读取配置字段ApkConfigJSON 中的字段名与ShellModeManager中对应字段的SerializedName一致Gson 会静默丢弃不匹配项。文档指出最常见的失败模式预览正常但导出的 APK 静默跳过了某个功能因为导出工厂与壳配置类之间的字段名发生了漂移。3.1 各关注点的编辑位置文档给出了一张改哪看哪的映射表路径以app/...简写表示app/src/main/java/com/webtoapp关注点路径什么内容进入 shellshell/build.gradle.kts →syncShellRuntimeSources的 include/excludeShell 模板构建:shell:assembleRelease:app:syncShellTemplateApk模板产物webview_shell.apk配置 → shell JSONApkConfigJsonFactory.ktShell 配置类型ShellModeManager.kt运行时 WebView 配置ShellWebViewConfig.kt配置漂移门禁check_config_field_drift.py →:app:checkConfigFieldDriftShell 混淆策略shell/proguard-rules.pro在 shell/build.gradle.kts 中可以看到这条同步链的真实实现syncShellRuntimeSources是一个Sync任务from(../app/src/main/java)include 了**/core/shell/**、**/core/webview/**、**/core/linux/**、**/core/nodejs/**、**/core/python/**、**/core/golang/**、**/core/php/**、**/core/wordpress/**、**/util/**等运行时包exclude 了宿主专属的WebToAppApplication.kt、EncryptedApkBuilder.kt、AutoStartLauncher.kt等preBuild显式dependsOn它避免 configuration-cache 下任务扫描失效。同一文件里还有syncShellRuntimeAssets把php_router_server.php与web_extensions/**GeckoView 引擎安装的内建 WebExtension 资产镜像进壳模板。四、i18n 铁律10 语言内联 when 块禁用字符串资源这是文档中最反直觉的约定之一且直接有测试门禁宿主 UI 字符串集中在 Strings.kt按长度拆分为Strings、StringsA…StringsE多个 object实测源码中依次位于第 7、5032、18776、30399、41355、52306 行附近。所有用户可见字符串必须写成内联的when (Strings.lang)块覆盖全部 10 种语言中文、英文、阿拉伯语、葡萄牙语、西班牙语、法语、德语、俄语、日语、韩语。when(lang)块绝不允许else -兜底由 AppStringsResourceConsistencyTest.kt 与 StringsKtTranslationParityTest.kt 强制。绝不用context.getString(R.string.*)/stringResource(R.string.*)加载用户可见文本。原因很具体res/values/strings.xml只存放translatablefalse的资源如app_name且不存在任何values-*/语言目录——资源字符串永远无法覆盖 10 种语言会静默回落到默认的values/中文。R.string只保留给非本地化的translatablefalse资源。参数化字符串用Strings.funName(arg)的模式文档举例linuxEnvInstalledToast(name)。优先在现有拆分 object 上加属性匹配周边风格。五、Android 与打包约束targetSdk 28、W^X 与进程启动这一节解释了为什么把 shell 的 SDK 现代化是个高风险动作生成应用保持低targetSdk28因为依赖设备端 forkexec 运行时shell 的 targetSdk 不可随意上调。宿主 App 目标 SDK 36出于杀软信誉考虑于是 SELinux W^X 会阻止宿主侧 exec 已下载的运行时。RuntimeExecPolicycore/linux通过探测已安装的 targetSdk 来放行/拦截这些预览——生成 APK恒为 28无条件通过。Node 预览经 native 库的 JNI不受影响。所有运行时/工具链进程必须经HostProcessLaunchercore/linux启动平台允许时用普通ProcessBuilderforkexec生成 APKtargetSdk 28W^X 宿主targetSdk ≥ 29上用用户态静态 exec 加载器基于 memfd 的StaticExecProcess无静态 exec 桥时降级为报错。直接在 W^X 设备上Runtime.exec一个下载的二进制会崩溃宿主 App。除非有强理由不新增第三方依赖见 app/build.gradle.kts / shell/build.gradle.kts优先平台 API 与既有模块。通知推送渠道Web Notification polyfill、轮询、WebSocket、FCM开发者自带 Firebase 配置默认不引入 OEM 厂商推送 SDK。前台服务与通知必须用SafeNotificationChannels或等价的 fail-soft 创建渠道创建失败不得崩溃 FGS 启动。唯一壳模板来自:shellrelease 的webview_shell.apk不得引入第二个模板 APK。本地服务器/运行时类 App 需要 host DNS/代理桥接时应接入LocalDnsBridgeProxy大体积运行时下载使用NetworkModule.downloadClient扩展超时的客户端。Gradle 自定义任务syncCloneHostDex等必须对 configuration-cache 安全在配置期捕获File/Provider值任务闭包内不得引用Project/android.sdkDirectory。5.1 源码印证W^X 门禁与启动器RuntimeExecPolicy.kt 的注释把机制讲得很透target 29 的 App 失去对应用数据存储中文件Python/PHP/WordPress/Go 运行时就解压在这里的 exec 能力连对 memfd 的execveat也被 SELinux 拦下但 memfd 上mmap PROT_EXEC仍被允许ART JIT 同类的权限hasMuslExecBridge便依赖打了补丁的 musl linker 以 native lib 形式驻留、从nativeLibraryDirexec 并桥接 app_data ELF 的 exec-mapping。canExecAppDataBinaries()的实现极其简洁targetSdk 29才为 true。HostProcessLauncher.kt 则在文件头注释中声明了降级策略execve 可用时走ProcessBuilder否则走用户态 exec 加载器。5.2 原生库嵌入与 16KB 对齐Node.js 导出必须嵌入libnode_bridge.so、libnode.so16KB 对齐与libc_shared.soGo 导出必须嵌入libgo_exec_loader.so。Android 15 设备要求大型 ELF native 库 16KB 页对齐由 ElfAligner16k.kt 完成node_bridge.cpp / node_launcher.c 在dlopen前开启 16KB app-compat。NodeJniOutputBridge是被 native 代码引用的稳定类须保留其 proguard-keep规则防止 R8 改名onOutput。六、增量导出缓存与配置漂移门禁导出增量重建位于app/.../apkbuilderApkBuildCache.kt ApkBuilder.kt实测源码中枚举确认了三种模式FULL/CONTENT_OVERLAY/REUSE_UNSIGNED。规则模板/入口标识必须内容稳定禁止基于 mtime 的 key加密构建永远强制全量重建不得把已签名或改过名的 APK 回填进全量modifyApk当模板。配置字段漂移的守护由 check_config_field_drift.py 实现脚本直接解析 ApkConfigJsonFactory.kt 中*Payload函数的键、ApkConfig.kt 与 ShellModeManager.kt 中的SerializedName对照 config_field_drift_allowlist.json 做集合比对对应 Gradle 任务:app:checkConfigFieldDrift在 app/build.gradle.kts 注册失败即抛GradleException。改了任何配置字段都应运行它。七、常见变更 Recipe十条逐条照做文档第 Common change recipes 节给出了日常改动的默认打法。核心警告是只停在 UI 或宿主代码上就是预览与导出分叉的根源。加/改宿主 UI 字符串在正确的Strings*拆分对象中加属性并覆盖 10 语言在 Compose 中像邻居一样引用。加一个必须影响生成 APK 的编辑器设置最重的一条需追踪全链路模型WebApp/ 嵌套配置与编辑器 UI 绑定导出映射ApkBuilder/ApkConfig/ApkConfigJsonFactory若运行时读取还要改 shell 配置类型ShellModeManager/ shell 配置 data classshell 同步代码中的运行时使用点导出接线的单元测试必做覆盖测试给WebViewConfig加新 Boolean 字段必须同步加入 WebViewConfigBooleanCoverageTest.kt 的flipAllBooleans()——该测试用反射验证每个声明的 Boolean 字段都被列出漏了 CI 会报出缺失字段名非 Boolean 字段加进关键字段导出往返抽查。按类型播放器界面必做shell UI 对齐Gallery / media / splash 类 App 在预览ui/gallery/、ui/media/与生成 APKui/shell/中走不同 composable配置端到端流通仍可能因 shell 屏幕从不读取该字段而无效曾发生过缩略图条配置和资产都正确送达却什么都不渲染的事故。ShellUiParityTest.kt 强制宿主运行时 UI 读取的每个模型字段shell 运行时 UI 也必须读取要么移植行为要么加显式allow条目并写明理由。新增每类型播放器对时同步扩展其pairs列表。缺任何一步的典型后果编辑器显示开关、导出忽略它或导出嵌入了运行时从不读取的配置。改所有生成 App 共用的 shell 运行时行为改app/下源码 → 确认被syncShellRuntimeSources包含 → 需要验证打包时重建 shell 模板 → 改动保持外科手术式shell 低 targetSdk、依赖薄→ 涉及 FGS/通知渠道创建时用SafeNotificationChannelsfail soft。加宿主独占功能编辑器、市场、工具实现留在宿主专属包core/apkbuilder、宿主界面、sample/market、core/host等不把宿主依赖拉进shell/build.gradle.kts。动 APK 导出或增量重建优先ApkBuildCache/ 内容哈希而非时间戳加密构建保持全量重建签名产物不作模板模板字节变化时确保缓存 key 正确失效。改通知 / 引擎 / 网络加固优先既有渠道抽象polyfill / 轮询 / WebSocket / FCM默认不加 OEM 推送 SDKFGS 渠道创建路径必须容忍 OEM/渠道失败。模块市场 /modules/遵循 modules/README.md 的目录布局registry.json 模块文件夹要随生成 APK 分发的运行时消费仍走 extension/shell 路径。修预览正常、导出后坏了按序排查——shell 配置 JSON 运行时真的含该字段吗ApkConfigJSON 字段名与 shell 配置SerializedName匹配吗跑checkConfigFieldDrift运行时使用点是 shell 同步的还是宿主独占的adblock 专项确认adBlockEnabled映射、宿主从缓存订阅重建过滤器、导出规则编译不清除宿主状态同步变更后重建模板吗旧模板是高频漏点本地服务器运行时 / 下载路径端口经PortManager按配置的冲突策略REASSIGN/AUTO_KILL/ALERT分配并实现真实 stop handler需要 host DNS/代理环境的 forkexec 进程接入LocalDnsBridgeProxy大体积引擎/运行时下载用NetworkModule.downloadClient进程一律经HostProcessLauncher启动使 W^X 宿主降级到静态 exec 加载器而非崩溃。Node.js / Go 导出Node 确认injectNodeJsNativeLibs嵌入三件套libnode.so经ElfAligner16k16KB 对齐Node 二进制解析优先nativeLibraryDir、回退下载缓存Go 确认injectGoExecLoaderNativeLib嵌入libgo_exec_loader.so宿主侧 Go 构建从不跑多进程go build驱动——GoDirectBuilder经HostProcessLauncher以单发进程重放compile/asm/linkW^X 宿主上即用户态静态 exec 加载器并带内容寻址的持久包归档缓存NodeService运行在独立:nodejsOS 进程中隔离 V8 生命周期。八、Recipe 11改动带 Agent 工具的功能App 内 Agent 暴露最多 57 个工具——52 个基础 2 个 plan-mode 3 个 imageryimagery 仅当模型支持图像时加载见ToolRegistryFactory.build()——全部包装宿主 service 类。实测 ToolRegistryFactory.kt 中baseTools()/imageryTools()/ plan 工具正是按hasImageModel imageRegistry ! null条件组装。工具调用链LLM 响应tool_calls → AgentEngine.executeToolCall() → PermissionPrompter写工具向用户询问只读工具静默执行 → Tool.execute(args, ctx) → Service 类ApkBuilder、AppExporter、PortManager、EngineManager、AdBlocker… → ToolResult → 回到 LLM触碰被 Agent 工具包装的功能时的检查清单API 签名漂移service 类构造器/方法签名/返回类型变了同步更新 builtin 工具目录 中对应execute()——旧调用只有旧重载仍存在时才能编译否则直接构建断裂。parametersSchema↔execute()对齐向 LLM 公布的 JSON schema 必须与execute()实际从args读取的一致参数加了却不进 schemaLLM 永远传不了它。description准确性LLM 仅凭descriptionparametersSchema决定何时、如何调用工具行为变了必须改描述误导性描述造成静默误用。isReadOnly()正确性true→ 无需用户确认直接执行false→ 触发 PermissionPrompter.kt 对话框工具获得写副作用就翻false。注册新工具必须加进ToolRegistryFactory.baseTools()按领域注释分组漏注册 LLM 看不见该工具。被删功能删除功能就删除/禁用其工具调用死类的工具会在 Agent 循环里运行时崩溃。宿主独占Agent 工具位于core/agent/永不 shell 同步不得加进syncShellRuntimeSources。关键路径工具接口 Tool.kt、注册表 ToolRegistryFactory.kt、上下文 ToolContext.kt、Agent 主循环 AgentEngine.kt、LLM 提供方 OpenAiCompatProvider.ktSSE 流式。九、Recipe 12编辑器配置卡片的 Compose 视觉语法编辑器屏幕由共享同一套视觉语法的WtaSettingCard构建。文档特别指出activation 卡片系列曾因每一轮都在发明布局而不是复制邻居、且每轮只做编译检查而返工四次。规则是Copy, dont invent——写任何卡片前先打开同屏参考实现逐元素对照参考实现位于 CreateAppWebViewCards.kt你要写的抄谁CreateAppWebViewCards.kt带开关头部的功能卡FullscreenModeCard带WtaChoiceRow头的可折叠卡BrowserAdvancedConfigCard单选 Radio 组sectionOfflinePerformance中的 PWA 离线策略选择器展开区内子开关/字段staticAssetPack块、代理块嵌套条件内容代理 MANUAL/PAC 的AnimatedVisibility切换输入与对话框同语法文本输入用PremiumTextField列表管理对话框 DialogWtaCard 内嵌TopAppBar参考AdBlockSubscriptionSelectorDialog。硬性规则踩坑换来的只有两种合法卡片形态开关头部式WtaSettingCard { WtaToggleRow(header); AnimatedVisibility(enabled, CardExpandTransition/CardCollapseTransition) { … } }与折叠头部式WtaSettingCard { Column { WtaChoiceRow(header); AnimatedVisibility(expanded) { … } } }。对齐网格WtaToggleRow/WtaChoiceRow是自带 16dp padding 的全出血行非行内容文本框、radio、分组标签、按钮、说明文字必须放进Column(padding(horizontal WtaSpacing.RowHorizontal, vertical WtaSpacing.ContentGap))区域区内子开关双重缩进16dp 区 16dp 行是参考实现的既有行为不要修它。Radio 组固定写法Text(labelMedium, primary)标签 Row(fillMaxWidth().clip(MaterialTheme.shapes.small).clickable { … }.padding(vertical 4.dp)) { RadioButton; Spacer(4.dp); Text(bodySmall) }绝不包WtaSection、绝不挂逐项说明。卡片头部只放标题 图标副标题属于真正需要的子行。展开态 ≠ 功能态永远不要把isExpanded/AnimatedVisibility(visible…)绑到功能enabled标志上——展开面板绝不能把功能打开折叠状态是独立的remember { mutableStateOf }。条件子块用AnimatedVisibilityCardExpandTransition/CardCollapseTransition绝不用裸if。编译通过 ≠ 验证通过卡片 UI 改动后必须构建安装到模拟器用uiautomator dump核对元素边界、对比同屏邻居卡片的左边缘/行高必须共享同一内容列外加截图走查。若 PR 收到和别的卡片不一致的反馈修法是回到上述模式对齐而不是继续发明。十、容易踩的坑Easy-to-miss points文档汇总的易漏点多数都有事故编号背书API 30 以下的键盘避让需要经典窗口路径Android 10 及以下没有原生 IME inset 分发edge-to-edge 窗口不会被键盘 resize、IME inset 恒为零任何softInputMode都无效。因此 WindowHelper.kt 的applyImmersiveFullscreen在 API 30 以下的 RESIZE 键盘路径上保持 decor 贴合系统窗口系统SOFT_INPUT_ADJUST_RESIZE才能生效并把 TRANSPARENT/IMAGE 状态栏样式降级为实色。#634 只翻 softInputMode 位、Robolectric 测试还通过了——因为它从未断言布局标志。共享源码以app/为源只改shell/src下文件通常就是错的——同步会覆盖它或使其与宿主分叉。配置字段名会漂移编辑器模型、ApkConfig、JSON 工厂、shell 配置四者必须对齐跑checkConfigFieldDrift。低 targetSdk(28) fork/exec 运行时约束一切现代化 shell SDK的想法。增量导出缓存 key 必须内容寻址mtime 与重签 APK 会造成误命中/误未命中。HTML/FRONTEND 文件访问打包的本地文件 shell 必须allowFileAccess true在buildWebViewBlock与ShellWebViewConfig中强制不得让纯 file 方式的 HTML 加载回退失效。Node native 库三件套缺一即运行时loadNode/loadJniBridge失败。崩溃的 FGS渠道创建一律SafeNotificationChannels。Adblock 同时接预览 导出导出时不得清除宿主过滤器状态宿主 AdBlocker 服务预览编译后的规则集随 APK 分发。运行时权限由功能驱动RuntimePermissionSync从启用功能推导权限列表不得回退静态模板。Splash 预览媒体路径预览读宿主文件系统的splashMediaPath导出打包进 assets不得把assets/splash_media.*硬编码为唯一来源。宿主播放器 UI ≠ shell 播放器 UI两套 composable 只共享配置每个可见行为缩略图条、背景、常亮、方向都要跨端移植由ShellUiParityTest验证——配置端到端流通是必要而不充分的。端口冲突策略本地服务器运行时必须经PortManager分配并在 stop 时清理禁止直接 bind。Agent 工具 ↔ service 漂移service API 变化必须同 PR 更新core/agent/tool/builtin/中对应工具完整工具清单看ToolRegistryFactory.baseTools()。十一、禁止 / 高风险操作清单文档单列了红线区完整 13 条见 AGENTS.md第二个壳模板 APKexclude 了某个 shell 同步类却留着壳源码中对它的 import/构造未经导出应用测试就重开 shell R8 混淆/激进压缩把宿主独占工具塞回 shell 同步shell 里加 OEM 推送 SDK 或无充分理由的重依赖把签名/改名 APK 喂进模板与 modify 路径通知渠道创建失败时让 FGS 崩溃提交密钥/keystore/本机配置打包 shell 的 HTML/FRONTEND 文件访问回退宿主播放器功能不上 shell 对应实现就发版NODEJS_APP 缺libnode_bridge.so/libnode.so/libc_shared.so大 ELF native 库跳过 16KB 对齐卡片布局/间距/动画靠发明而非复制邻居或卡片 UI 只以编译为准。十二、验证命令与 CI 说明文档给出的标准验证命令./gradlew :shell:assembleRelease :app:syncShellTemplateApk --no-configuration-cache ./gradlew :app:compileStandardDebugKotlin -x syncCloneHostDex --no-configuration-cache ./gradlew :app:checkConfigFieldDrift --no-configuration-cache python3 scripts/check_config_field_drift.py适用场景改动 shell 成员、导出打包或配置字段时用前一组仅宿主 UI/字符串工作时对:app做定向编译通常就够了。CI 细节值得注意PR 的check作业只编译:shell:compileDebugKotlindebug 变体并跳过模板同步-PskipShellTemplateSynctrue即 app/build.gradle.kts 中的skipShellTemplateSync属性shellrelease变体R8/proguard与模板流水线只有手动workflow_dispatch打包作业才会走到——动了shell/proguard-rules.pro或 shell 打包配置推送前务必本地先跑第一条命令。文档还建议改动附近时顺带跑的相关测试ApkBuildCacheTest、AdBlockerHostRuntimeTest、AdBlockExportWiringTest、PortManagerTest、BuildInputPreflightTest、GoBuildEnvironmentTest、RuntimePermissionSyncTest——它们在 app/src/test/java/com/webtoapp/core/apkbuilder/ 等目录中均可找到。十三、实现快照规范背后已落地的能力AGENTS.md 的最后一节是一份已落地清单可作为理解项目能力边界的索引单一壳模板 全量运行时同步三模式增量ApkBuildCachepolyfill/轮询/WebSocket/FCM(BYO Firebase) 通知渠道SafeNotificationChannels跨 Node/PHP/Python/Go/WordPress 的PortManager冲突策略与真实 stop handlerLocalDnsBridgeProxyadblock 预览导出接线HTML/FRONTEND 文件访问Node.js 三件套 16KB 对齐 16KB app-compat 稳定 JNI 回调Go 导出嵌入 exec loader、宿主侧GoDirectBuilder单发进程构建多 web 站点源内嵌与降级Gallery 播放循环随机、位置记忆、总览网格、缩略图条、双指缩放宿主/shell 对齐由ShellUiParityTest强制越界位图解码有界化备份/恢复覆盖与当前存储布局对齐NativeBridge 对新建应用默认开启功能驱动的运行时权限同步模块市场的 Chrome Web Store 实时搜索 GreasyFork 浏览安全加固TLS 指纹桥校验上游证书、JS 桥按调用方/来源/scheme 门控、MITM 代理 host 白名单 CA 密钥静态封装、SafeZip解包、并发导出按包串行化、keystore 密码 sidecar 排除出备份以及最多 57 个工具的 Agent 工具系统含 Channel 式权限询问、按段的 SSE 解析容错、plan moderuntime/build 工具向 LLM 暴露localExecAllowed让模型知道 targetSdk29 宿主不能 exec 应用存储中的二进制。结语AGENTS.md的价值不在于罗列规则而在于它把 web-to-app 最脆弱的工程边界——一份源码、两个运行时、一条 JSON 配置链——用可执行的检查漂移脚本、覆盖测试、parity 测试、验证命令固化了下来。对贡献者而言掌握模型 → ApkConfig JSON → 壳配置 → 运行时这条链路与只改app/、绝不 fork shell 副本两条总纲就掌握了在这个仓库安全高效工作的全部钥匙。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 web-to-app 的 AGENTS.md 深度解读：双运行时架构、配置漂移防护与 APK 导出工程规范
web-to-app 的 AGENTS.md 深度解读双运行时架构、配置漂移防护与 APK 导出工程规范【免费下载链接】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-appAGENTS.md是 web-to-app 仓库为编码代理编码 Agent与开发者编写的工程规范总纲。它回答的核心问题是在这个手机上把网页变 APK的工具箱里同一份运行时源码如何在宿主编辑器Host与导出的壳应用Shell两条路径上各自生效、又如何保证它们不脱节。读完本文你将掌握该项目预览 ≠ 导出的双运行时心智模型、配置字段端到端流转链路、增量导出缓存、10 语言内联国际化约定、W^X 环境下的进程启动策略以及一套可直接照做的变更 Recipe 与验证命令。一、仓库布局每个目录的角色AGENTS.md 用一张表定义了仓库顶层结构路径角色app/完整的构建器宿主编辑 UI、导出流水线、运行时、预览shell/运行时模板。通过:shell:assembleRelease:app:syncShellTemplateApk构建为app/src/main/assets/template/webview_shell.apkclone-host/宿主侧 APK 克隆/身份重塑支持库。其 DEX 资源生成任务syncCloneHostDex被刻意禁用enabled false为规避杀软误报——AppCloner在没有该资产时走 fail-soft 路径modules/模块市场目录registry.json 各模块文件夹docs/VitePress 文档站guide / developer / extensions中英双语由.github/workflows/docs-deploy.yml部署站点 URL 路径与docs/下文件 1:1 映射/zh/...→docs/zh/...scripts/构建辅助与门禁脚本check_config_field_drift.py其中最关键的一条规则是运行时 Kotlin 源码只在app/下编写由syncShellRuntimeSources任务同步进shell模块——只编辑一次app/源码绝不在 shell 下永久 fork 一份拷贝。二、核心架构编辑器、导出工厂与壳运行时的连接文档给出的连接关系图是理解整个项目的地图编辑器app/ 中的 Compose 界面 ↔ 数据模型WebApp、各配置 ↔ 导出工厂ApkConfig / ApkConfigJsonFactory ↔ ApkBuilder / ApkBuildCache → 签名后的生成 APK app/ 源码 → syncShellRuntimeSources → shell DEX → webview_shell.apk模板 生成的 APK 运行时 WebToAppApplication → ShellModeManager → 读取 assets 中的 JSON 配置 → WebViewManager / 运行时服务器Node/PHP/Python/Go/WordPress对应的心智模型宿主预览Host preview运行:app模块所有类都在主 classpath 上生成的 APK运行壳模板中的类完整运行时从app/同步而来通过ShellModeManager从 assets JSON 读取配置关键结论编辑器的一个开关如果不能沿模型 → ApkConfig JSON → 壳配置 → 运行时代码这条链路流下去在导出时就是无效的。从源码看ShellModeManager.kt 确实从 assets 加载app_config.json支持经AssetDecryptor解密读取失败则回退明文读取找不到文件则返回 null按主 App 模式运行并用 Gson 反序列化为ShellConfig——这正是配置漂移会静默丢字段的地方Gson 遇到未知/缺失字段不报错只跳过。三、双运行时预览与导出为什么可能分叉文档对宿主:app与生成 APK做了逐维度对比| | 宿主:app| 生成的 APK | |--|-------------|---------------| | DEX | 全部app/src类 | Shell 同步的 include−exclude 集合完整运行时集 | | 配置 | 编辑器 / 内存模型 | assets JSON经ShellModeManager| | 模板 | 不使用 |app/src/main/assets/template/webview_shell.apk|因此Preview ≠ Export除非三条同时成立宿主侧仍保留真实实现Shell 同步的代码在运行时从 assets JSON 读取配置字段ApkConfigJSON 中的字段名与ShellModeManager中对应字段的SerializedName一致Gson 会静默丢弃不匹配项。文档指出最常见的失败模式预览正常但导出的 APK 静默跳过了某个功能因为导出工厂与壳配置类之间的字段名发生了漂移。3.1 各关注点的编辑位置文档给出了一张改哪看哪的映射表路径以app/...简写表示app/src/main/java/com/webtoapp关注点路径什么内容进入 shellshell/build.gradle.kts →syncShellRuntimeSources的 include/excludeShell 模板构建:shell:assembleRelease:app:syncShellTemplateApk模板产物webview_shell.apk配置 → shell JSONApkConfigJsonFactory.ktShell 配置类型ShellModeManager.kt运行时 WebView 配置ShellWebViewConfig.kt配置漂移门禁check_config_field_drift.py →:app:checkConfigFieldDriftShell 混淆策略shell/proguard-rules.pro在 shell/build.gradle.kts 中可以看到这条同步链的真实实现syncShellRuntimeSources是一个Sync任务from(../app/src/main/java)include 了**/core/shell/**、**/core/webview/**、**/core/linux/**、**/core/nodejs/**、**/core/python/**、**/core/golang/**、**/core/php/**、**/core/wordpress/**、**/util/**等运行时包exclude 了宿主专属的WebToAppApplication.kt、EncryptedApkBuilder.kt、AutoStartLauncher.kt等preBuild显式dependsOn它避免 configuration-cache 下任务扫描失效。同一文件里还有syncShellRuntimeAssets把php_router_server.php与web_extensions/**GeckoView 引擎安装的内建 WebExtension 资产镜像进壳模板。四、i18n 铁律10 语言内联 when 块禁用字符串资源这是文档中最反直觉的约定之一且直接有测试门禁宿主 UI 字符串集中在 Strings.kt按长度拆分为Strings、StringsA…StringsE多个 object实测源码中依次位于第 7、5032、18776、30399、41355、52306 行附近。所有用户可见字符串必须写成内联的when (Strings.lang)块覆盖全部 10 种语言中文、英文、阿拉伯语、葡萄牙语、西班牙语、法语、德语、俄语、日语、韩语。when(lang)块绝不允许else -兜底由 AppStringsResourceConsistencyTest.kt 与 StringsKtTranslationParityTest.kt 强制。绝不用context.getString(R.string.*)/stringResource(R.string.*)加载用户可见文本。原因很具体res/values/strings.xml只存放translatablefalse的资源如app_name且不存在任何values-*/语言目录——资源字符串永远无法覆盖 10 种语言会静默回落到默认的values/中文。R.string只保留给非本地化的translatablefalse资源。参数化字符串用Strings.funName(arg)的模式文档举例linuxEnvInstalledToast(name)。优先在现有拆分 object 上加属性匹配周边风格。五、Android 与打包约束targetSdk 28、W^X 与进程启动这一节解释了为什么把 shell 的 SDK 现代化是个高风险动作生成应用保持低targetSdk28因为依赖设备端 forkexec 运行时shell 的 targetSdk 不可随意上调。宿主 App 目标 SDK 36出于杀软信誉考虑于是 SELinux W^X 会阻止宿主侧 exec 已下载的运行时。RuntimeExecPolicycore/linux通过探测已安装的 targetSdk 来放行/拦截这些预览——生成 APK恒为 28无条件通过。Node 预览经 native 库的 JNI不受影响。所有运行时/工具链进程必须经HostProcessLaunchercore/linux启动平台允许时用普通ProcessBuilderforkexec生成 APKtargetSdk 28W^X 宿主targetSdk ≥ 29上用用户态静态 exec 加载器基于 memfd 的StaticExecProcess无静态 exec 桥时降级为报错。直接在 W^X 设备上Runtime.exec一个下载的二进制会崩溃宿主 App。除非有强理由不新增第三方依赖见 app/build.gradle.kts / shell/build.gradle.kts优先平台 API 与既有模块。通知推送渠道Web Notification polyfill、轮询、WebSocket、FCM开发者自带 Firebase 配置默认不引入 OEM 厂商推送 SDK。前台服务与通知必须用SafeNotificationChannels或等价的 fail-soft 创建渠道创建失败不得崩溃 FGS 启动。唯一壳模板来自:shellrelease 的webview_shell.apk不得引入第二个模板 APK。本地服务器/运行时类 App 需要 host DNS/代理桥接时应接入LocalDnsBridgeProxy大体积运行时下载使用NetworkModule.downloadClient扩展超时的客户端。Gradle 自定义任务syncCloneHostDex等必须对 configuration-cache 安全在配置期捕获File/Provider值任务闭包内不得引用Project/android.sdkDirectory。5.1 源码印证W^X 门禁与启动器RuntimeExecPolicy.kt 的注释把机制讲得很透target 29 的 App 失去对应用数据存储中文件Python/PHP/WordPress/Go 运行时就解压在这里的 exec 能力连对 memfd 的execveat也被 SELinux 拦下但 memfd 上mmap PROT_EXEC仍被允许ART JIT 同类的权限hasMuslExecBridge便依赖打了补丁的 musl linker 以 native lib 形式驻留、从nativeLibraryDirexec 并桥接 app_data ELF 的 exec-mapping。canExecAppDataBinaries()的实现极其简洁targetSdk 29才为 true。HostProcessLauncher.kt 则在文件头注释中声明了降级策略execve 可用时走ProcessBuilder否则走用户态 exec 加载器。5.2 原生库嵌入与 16KB 对齐Node.js 导出必须嵌入libnode_bridge.so、libnode.so16KB 对齐与libc_shared.soGo 导出必须嵌入libgo_exec_loader.so。Android 15 设备要求大型 ELF native 库 16KB 页对齐由 ElfAligner16k.kt 完成node_bridge.cpp / node_launcher.c 在dlopen前开启 16KB app-compat。NodeJniOutputBridge是被 native 代码引用的稳定类须保留其 proguard-keep规则防止 R8 改名onOutput。六、增量导出缓存与配置漂移门禁导出增量重建位于app/.../apkbuilderApkBuildCache.kt ApkBuilder.kt实测源码中枚举确认了三种模式FULL/CONTENT_OVERLAY/REUSE_UNSIGNED。规则模板/入口标识必须内容稳定禁止基于 mtime 的 key加密构建永远强制全量重建不得把已签名或改过名的 APK 回填进全量modifyApk当模板。配置字段漂移的守护由 check_config_field_drift.py 实现脚本直接解析 ApkConfigJsonFactory.kt 中*Payload函数的键、ApkConfig.kt 与 ShellModeManager.kt 中的SerializedName对照 config_field_drift_allowlist.json 做集合比对对应 Gradle 任务:app:checkConfigFieldDrift在 app/build.gradle.kts 注册失败即抛GradleException。改了任何配置字段都应运行它。七、常见变更 Recipe十条逐条照做文档第 Common change recipes 节给出了日常改动的默认打法。核心警告是只停在 UI 或宿主代码上就是预览与导出分叉的根源。加/改宿主 UI 字符串在正确的Strings*拆分对象中加属性并覆盖 10 语言在 Compose 中像邻居一样引用。加一个必须影响生成 APK 的编辑器设置最重的一条需追踪全链路模型WebApp/ 嵌套配置与编辑器 UI 绑定导出映射ApkBuilder/ApkConfig/ApkConfigJsonFactory若运行时读取还要改 shell 配置类型ShellModeManager/ shell 配置 data classshell 同步代码中的运行时使用点导出接线的单元测试必做覆盖测试给WebViewConfig加新 Boolean 字段必须同步加入 WebViewConfigBooleanCoverageTest.kt 的flipAllBooleans()——该测试用反射验证每个声明的 Boolean 字段都被列出漏了 CI 会报出缺失字段名非 Boolean 字段加进关键字段导出往返抽查。按类型播放器界面必做shell UI 对齐Gallery / media / splash 类 App 在预览ui/gallery/、ui/media/与生成 APKui/shell/中走不同 composable配置端到端流通仍可能因 shell 屏幕从不读取该字段而无效曾发生过缩略图条配置和资产都正确送达却什么都不渲染的事故。ShellUiParityTest.kt 强制宿主运行时 UI 读取的每个模型字段shell 运行时 UI 也必须读取要么移植行为要么加显式allow条目并写明理由。新增每类型播放器对时同步扩展其pairs列表。缺任何一步的典型后果编辑器显示开关、导出忽略它或导出嵌入了运行时从不读取的配置。改所有生成 App 共用的 shell 运行时行为改app/下源码 → 确认被syncShellRuntimeSources包含 → 需要验证打包时重建 shell 模板 → 改动保持外科手术式shell 低 targetSdk、依赖薄→ 涉及 FGS/通知渠道创建时用SafeNotificationChannelsfail soft。加宿主独占功能编辑器、市场、工具实现留在宿主专属包core/apkbuilder、宿主界面、sample/market、core/host等不把宿主依赖拉进shell/build.gradle.kts。动 APK 导出或增量重建优先ApkBuildCache/ 内容哈希而非时间戳加密构建保持全量重建签名产物不作模板模板字节变化时确保缓存 key 正确失效。改通知 / 引擎 / 网络加固优先既有渠道抽象polyfill / 轮询 / WebSocket / FCM默认不加 OEM 推送 SDKFGS 渠道创建路径必须容忍 OEM/渠道失败。模块市场 /modules/遵循 modules/README.md 的目录布局registry.json 模块文件夹要随生成 APK 分发的运行时消费仍走 extension/shell 路径。修预览正常、导出后坏了按序排查——shell 配置 JSON 运行时真的含该字段吗ApkConfigJSON 字段名与 shell 配置SerializedName匹配吗跑checkConfigFieldDrift运行时使用点是 shell 同步的还是宿主独占的adblock 专项确认adBlockEnabled映射、宿主从缓存订阅重建过滤器、导出规则编译不清除宿主状态同步变更后重建模板吗旧模板是高频漏点本地服务器运行时 / 下载路径端口经PortManager按配置的冲突策略REASSIGN/AUTO_KILL/ALERT分配并实现真实 stop handler需要 host DNS/代理环境的 forkexec 进程接入LocalDnsBridgeProxy大体积引擎/运行时下载用NetworkModule.downloadClient进程一律经HostProcessLauncher启动使 W^X 宿主降级到静态 exec 加载器而非崩溃。Node.js / Go 导出Node 确认injectNodeJsNativeLibs嵌入三件套libnode.so经ElfAligner16k16KB 对齐Node 二进制解析优先nativeLibraryDir、回退下载缓存Go 确认injectGoExecLoaderNativeLib嵌入libgo_exec_loader.so宿主侧 Go 构建从不跑多进程go build驱动——GoDirectBuilder经HostProcessLauncher以单发进程重放compile/asm/linkW^X 宿主上即用户态静态 exec 加载器并带内容寻址的持久包归档缓存NodeService运行在独立:nodejsOS 进程中隔离 V8 生命周期。八、Recipe 11改动带 Agent 工具的功能App 内 Agent 暴露最多 57 个工具——52 个基础 2 个 plan-mode 3 个 imageryimagery 仅当模型支持图像时加载见ToolRegistryFactory.build()——全部包装宿主 service 类。实测 ToolRegistryFactory.kt 中baseTools()/imageryTools()/ plan 工具正是按hasImageModel imageRegistry ! null条件组装。工具调用链LLM 响应tool_calls → AgentEngine.executeToolCall() → PermissionPrompter写工具向用户询问只读工具静默执行 → Tool.execute(args, ctx) → Service 类ApkBuilder、AppExporter、PortManager、EngineManager、AdBlocker… → ToolResult → 回到 LLM触碰被 Agent 工具包装的功能时的检查清单API 签名漂移service 类构造器/方法签名/返回类型变了同步更新 builtin 工具目录 中对应execute()——旧调用只有旧重载仍存在时才能编译否则直接构建断裂。parametersSchema↔execute()对齐向 LLM 公布的 JSON schema 必须与execute()实际从args读取的一致参数加了却不进 schemaLLM 永远传不了它。description准确性LLM 仅凭descriptionparametersSchema决定何时、如何调用工具行为变了必须改描述误导性描述造成静默误用。isReadOnly()正确性true→ 无需用户确认直接执行false→ 触发 PermissionPrompter.kt 对话框工具获得写副作用就翻false。注册新工具必须加进ToolRegistryFactory.baseTools()按领域注释分组漏注册 LLM 看不见该工具。被删功能删除功能就删除/禁用其工具调用死类的工具会在 Agent 循环里运行时崩溃。宿主独占Agent 工具位于core/agent/永不 shell 同步不得加进syncShellRuntimeSources。关键路径工具接口 Tool.kt、注册表 ToolRegistryFactory.kt、上下文 ToolContext.kt、Agent 主循环 AgentEngine.kt、LLM 提供方 OpenAiCompatProvider.ktSSE 流式。九、Recipe 12编辑器配置卡片的 Compose 视觉语法编辑器屏幕由共享同一套视觉语法的WtaSettingCard构建。文档特别指出activation 卡片系列曾因每一轮都在发明布局而不是复制邻居、且每轮只做编译检查而返工四次。规则是Copy, dont invent——写任何卡片前先打开同屏参考实现逐元素对照参考实现位于 CreateAppWebViewCards.kt你要写的抄谁CreateAppWebViewCards.kt带开关头部的功能卡FullscreenModeCard带WtaChoiceRow头的可折叠卡BrowserAdvancedConfigCard单选 Radio 组sectionOfflinePerformance中的 PWA 离线策略选择器展开区内子开关/字段staticAssetPack块、代理块嵌套条件内容代理 MANUAL/PAC 的AnimatedVisibility切换输入与对话框同语法文本输入用PremiumTextField列表管理对话框 DialogWtaCard 内嵌TopAppBar参考AdBlockSubscriptionSelectorDialog。硬性规则踩坑换来的只有两种合法卡片形态开关头部式WtaSettingCard { WtaToggleRow(header); AnimatedVisibility(enabled, CardExpandTransition/CardCollapseTransition) { … } }与折叠头部式WtaSettingCard { Column { WtaChoiceRow(header); AnimatedVisibility(expanded) { … } } }。对齐网格WtaToggleRow/WtaChoiceRow是自带 16dp padding 的全出血行非行内容文本框、radio、分组标签、按钮、说明文字必须放进Column(padding(horizontal WtaSpacing.RowHorizontal, vertical WtaSpacing.ContentGap))区域区内子开关双重缩进16dp 区 16dp 行是参考实现的既有行为不要修它。Radio 组固定写法Text(labelMedium, primary)标签 Row(fillMaxWidth().clip(MaterialTheme.shapes.small).clickable { … }.padding(vertical 4.dp)) { RadioButton; Spacer(4.dp); Text(bodySmall) }绝不包WtaSection、绝不挂逐项说明。卡片头部只放标题 图标副标题属于真正需要的子行。展开态 ≠ 功能态永远不要把isExpanded/AnimatedVisibility(visible…)绑到功能enabled标志上——展开面板绝不能把功能打开折叠状态是独立的remember { mutableStateOf }。条件子块用AnimatedVisibilityCardExpandTransition/CardCollapseTransition绝不用裸if。编译通过 ≠ 验证通过卡片 UI 改动后必须构建安装到模拟器用uiautomator dump核对元素边界、对比同屏邻居卡片的左边缘/行高必须共享同一内容列外加截图走查。若 PR 收到和别的卡片不一致的反馈修法是回到上述模式对齐而不是继续发明。十、容易踩的坑Easy-to-miss points文档汇总的易漏点多数都有事故编号背书API 30 以下的键盘避让需要经典窗口路径Android 10 及以下没有原生 IME inset 分发edge-to-edge 窗口不会被键盘 resize、IME inset 恒为零任何softInputMode都无效。因此 WindowHelper.kt 的applyImmersiveFullscreen在 API 30 以下的 RESIZE 键盘路径上保持 decor 贴合系统窗口系统SOFT_INPUT_ADJUST_RESIZE才能生效并把 TRANSPARENT/IMAGE 状态栏样式降级为实色。#634 只翻 softInputMode 位、Robolectric 测试还通过了——因为它从未断言布局标志。共享源码以app/为源只改shell/src下文件通常就是错的——同步会覆盖它或使其与宿主分叉。配置字段名会漂移编辑器模型、ApkConfig、JSON 工厂、shell 配置四者必须对齐跑checkConfigFieldDrift。低 targetSdk(28) fork/exec 运行时约束一切现代化 shell SDK的想法。增量导出缓存 key 必须内容寻址mtime 与重签 APK 会造成误命中/误未命中。HTML/FRONTEND 文件访问打包的本地文件 shell 必须allowFileAccess true在buildWebViewBlock与ShellWebViewConfig中强制不得让纯 file 方式的 HTML 加载回退失效。Node native 库三件套缺一即运行时loadNode/loadJniBridge失败。崩溃的 FGS渠道创建一律SafeNotificationChannels。Adblock 同时接预览 导出导出时不得清除宿主过滤器状态宿主 AdBlocker 服务预览编译后的规则集随 APK 分发。运行时权限由功能驱动RuntimePermissionSync从启用功能推导权限列表不得回退静态模板。Splash 预览媒体路径预览读宿主文件系统的splashMediaPath导出打包进 assets不得把assets/splash_media.*硬编码为唯一来源。宿主播放器 UI ≠ shell 播放器 UI两套 composable 只共享配置每个可见行为缩略图条、背景、常亮、方向都要跨端移植由ShellUiParityTest验证——配置端到端流通是必要而不充分的。端口冲突策略本地服务器运行时必须经PortManager分配并在 stop 时清理禁止直接 bind。Agent 工具 ↔ service 漂移service API 变化必须同 PR 更新core/agent/tool/builtin/中对应工具完整工具清单看ToolRegistryFactory.baseTools()。十一、禁止 / 高风险操作清单文档单列了红线区完整 13 条见 AGENTS.md第二个壳模板 APKexclude 了某个 shell 同步类却留着壳源码中对它的 import/构造未经导出应用测试就重开 shell R8 混淆/激进压缩把宿主独占工具塞回 shell 同步shell 里加 OEM 推送 SDK 或无充分理由的重依赖把签名/改名 APK 喂进模板与 modify 路径通知渠道创建失败时让 FGS 崩溃提交密钥/keystore/本机配置打包 shell 的 HTML/FRONTEND 文件访问回退宿主播放器功能不上 shell 对应实现就发版NODEJS_APP 缺libnode_bridge.so/libnode.so/libc_shared.so大 ELF native 库跳过 16KB 对齐卡片布局/间距/动画靠发明而非复制邻居或卡片 UI 只以编译为准。十二、验证命令与 CI 说明文档给出的标准验证命令./gradlew :shell:assembleRelease :app:syncShellTemplateApk --no-configuration-cache ./gradlew :app:compileStandardDebugKotlin -x syncCloneHostDex --no-configuration-cache ./gradlew :app:checkConfigFieldDrift --no-configuration-cache python3 scripts/check_config_field_drift.py适用场景改动 shell 成员、导出打包或配置字段时用前一组仅宿主 UI/字符串工作时对:app做定向编译通常就够了。CI 细节值得注意PR 的check作业只编译:shell:compileDebugKotlindebug 变体并跳过模板同步-PskipShellTemplateSynctrue即 app/build.gradle.kts 中的skipShellTemplateSync属性shellrelease变体R8/proguard与模板流水线只有手动workflow_dispatch打包作业才会走到——动了shell/proguard-rules.pro或 shell 打包配置推送前务必本地先跑第一条命令。文档还建议改动附近时顺带跑的相关测试ApkBuildCacheTest、AdBlockerHostRuntimeTest、AdBlockExportWiringTest、PortManagerTest、BuildInputPreflightTest、GoBuildEnvironmentTest、RuntimePermissionSyncTest——它们在 app/src/test/java/com/webtoapp/core/apkbuilder/ 等目录中均可找到。十三、实现快照规范背后已落地的能力AGENTS.md 的最后一节是一份已落地清单可作为理解项目能力边界的索引单一壳模板 全量运行时同步三模式增量ApkBuildCachepolyfill/轮询/WebSocket/FCM(BYO Firebase) 通知渠道SafeNotificationChannels跨 Node/PHP/Python/Go/WordPress 的PortManager冲突策略与真实 stop handlerLocalDnsBridgeProxyadblock 预览导出接线HTML/FRONTEND 文件访问Node.js 三件套 16KB 对齐 16KB app-compat 稳定 JNI 回调Go 导出嵌入 exec loader、宿主侧GoDirectBuilder单发进程构建多 web 站点源内嵌与降级Gallery 播放循环随机、位置记忆、总览网格、缩略图条、双指缩放宿主/shell 对齐由ShellUiParityTest强制越界位图解码有界化备份/恢复覆盖与当前存储布局对齐NativeBridge 对新建应用默认开启功能驱动的运行时权限同步模块市场的 Chrome Web Store 实时搜索 GreasyFork 浏览安全加固TLS 指纹桥校验上游证书、JS 桥按调用方/来源/scheme 门控、MITM 代理 host 白名单 CA 密钥静态封装、SafeZip解包、并发导出按包串行化、keystore 密码 sidecar 排除出备份以及最多 57 个工具的 Agent 工具系统含 Channel 式权限询问、按段的 SSE 解析容错、plan moderuntime/build 工具向 LLM 暴露localExecAllowed让模型知道 targetSdk29 宿主不能 exec 应用存储中的二进制。结语AGENTS.md的价值不在于罗列规则而在于它把 web-to-app 最脆弱的工程边界——一份源码、两个运行时、一条 JSON 配置链——用可执行的检查漂移脚本、覆盖测试、parity 测试、验证命令固化了下来。对贡献者而言掌握模型 → ApkConfig JSON → 壳配置 → 运行时这条链路与只改app/、绝不 fork shell 副本两条总纲就掌握了在这个仓库安全高效工作的全部钥匙。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考