mirror of
https://gitee.com/mateos/mateclaw.git
synced 2026-09-13 19:23:42 +08:00
9e33782b7d
* feat(browser): 放开内网服务访问限制，新增局域网部署模式开关 ### 背景 局域网部署时，Agent 用浏览器工具访问 http://192.168.x.x:port 等内网服务会被默认 SSRF 严格模式拦截。 ### 方案 新增两个 .env 开关（默认 false，行为与改动前完全一致）： - PLAYWRIGHT_ALLOW_PRIVATE_NETWORK=true ：放行本地回环和私有 IP，云元数据端点仍拦截 - PLAYWRIGHT_IGNORE_HTTPS_ERRORS=true ：忽略 HTTPS 证书错误（自签证书场景） 顺带修复 IPv6 AWS IMDS 网段 fd00:ec2::/64 在严格模式下漏网的问题。 ### 验证 24 个单元测试全通过（UrlSafetyChecker 21 + BrowserProperties 3），覆盖严格/豁免两模式 + 4 个 check 重载 + IPv6 IMDS 网段。 ### 风险 开关仅作用于浏览器工具；公网部署务必保持 false。 * feat(browser): Playwright 超时可配 + snapshot 智能截断与 selector 作用域 ### 背景 Agent 用浏览器工具访问慢链路或大页面（超大表格）时遇到两类问题： 1. Playwright 默认 30s 超时不够用，且无法配置 2. snapshot 全量抓取页面文本，硬截断在 20000 字符处会切在元素中间，LLM 拿到残缺数据且不知道有截断 ### 方案 新增三个 .env 开关（默认值与改动前完全一致）： 开关 作用 PLAYWRIGHT_DEFAULT_TIMEOUT_SECONDS 单次操作超时（click / fill / waitForLoadState） PLAYWRIGHT_NAVIGATION_TIMEOUT_SECONDS 导航超时（page.navigate / load-state） PLAYWRIGHT_SNAPSHOT_MAX_LENGTH snapshot 文本截断长度 snapshot 改造： - 支持 selector 参数作用域到子树（之前只用于 click/type） - budget 机制按元素边界智能截断，不再切在 <td> 中间 - 返回 truncated:true + hint 引导 LLM 用 selector 重抓 - JSON 字段顺序优化：truncated/hint 放 content 前，确保框架 spill preview（head 800 chars）能切到 ### 验证 - 28 个单元测试全通过（BrowserPropertiesTest 7 + UrlSafetyCheckerTest 21） - IDE 诊断 0 错误 - 覆盖：默认值不变 + setter 往返 + 严格/豁免两模式 ### 兼容性 - 默认值保持 30s / 30s / 20000，行为与改动前完全一致 - selector 参数本就是 @ToolParam(required=false) ，LLM schema 无变化，只是描述更新引导 snapshot 场景也能用 - 不影响 webhook / image download 等其他 SSRF 守卫 ## 改动汇总 文件 改动 BrowserProperties.java +3 字段： defaultTimeoutSeconds / defaultNavigationTimeoutSeconds / snapshotMaxLength （默认 30/30/20000） BrowserLauncher.java 抽 applyContextDefaults(context) 在三处 context 创建点调用；补全 setIgnoreHTTPSErrors 在 wrapLocalBrowser 落地 BrowserUseTool.java 工具描述 + selector 描述引导 LLM 在 snapshot 场景用 selector；doSnapshot 改造支持 selector 参数 + budget 智能截断 + JSON 字段顺序（truncated/hint 放 content 前确保 spill preview 能切到） docker-compose.yml +3 开关： PLAYWRIGHT_DEFAULT_TIMEOUT_SECONDS / PLAYWRIGHT_NAVIGATION_TIMEOUT_SECONDS / PLAYWRIGHT_SNAPSHOT_MAX_LENGTH .env.example +3 开关，简短说明 BrowserPropertiesTest.java +4 测试覆盖新字段默认值和 setter ## 测试结果 ## 数据流论证的关键决策 决策 依据 truncated:true 和 hint 放在 JSON content 字段之前 ToolResultStorage.buildPreview 会把 >8000 chars 的结果截到 head 800 chars，放在前面确保 LLM 看到 selector 参数描述从 "for click/type" 改为明确说 "OPTIONAL for snapshot" LLM 读 JSON schema 时按描述判断参数用途，原描述误导 LLM 不在 snapshot 用 selector 截断从硬 substring(0, N) 改为 JS budget 机制递归累计 避免切在 <td>订单号 ABC 中间，截断发生在 TEXT_NODE 完整段或下一个子元素开始之前 用 ElementHandle.querySelector + evaluate 替代字符串拼接 selector 进 JS 防止 selector 注入（selector 含特殊字符如引号、反斜杠） 三处 context 创建点统一调 applyContextDefaults 确保 CDP / external-CDP / 本地 launch 三条路径都应用配置的 timeout ## 临时改动还原 文件 改动 还原状态 mateclaw-server/pom.xml 临时加 maven-compiler-plugin + Lombok annotation processor ✅ 已删除，恢复原始状态 ## 未测项 项 原因 doSnapshot 的 JS budget 逻辑 需启动真 Playwright + 大页面，单元测试范围外 BrowserLauncher.applyContextDefaults 是否真的影响 page.click 行为 同上，集成测试范围 LLM 是否真的会按 hint 用 selector 重调 取决于 LLM 推理能力，需端到端测试 |
||
|---|---|---|
| .. | ||
| browser | ||
| builtin | ||
| disclosure | ||
| document | ||
| guard | ||
| image | ||
| mcp | ||
| service | ||
| video/provider | ||