1. 项目概述一个能“看懂”浏览器行为的AI代理如果你曾经为了自动化某个网站操作比如批量下载账单、自动填写表单而不得不去研究它背后那些混乱、未经文档化的内部API那么你肯定知道这活儿有多磨人。你得打开开发者工具在“网络”标签页里大海捞针手动找出关键的请求分析它的参数、依赖关系然后才能开始写代码。整个过程繁琐、易错而且一旦网站前端稍有改动你的脚本可能就失效了。Integuru v0这个开源项目就是为了解决这个痛点而生的。它本质上是一个AI代理其核心能力是通过分析你在浏览器中的操作记录自动逆向工程出平台内部API的调用逻辑并生成可直接运行的Python代码。简单来说你把想做的操作比如“下载2023年的所有电费账单”在浏览器里手动执行一遍Integuru会录下这个过程里所有的网络请求和Cookie。然后你只需要用一句简单的自然语言描述你的意图它就能分析出完成这个操作需要按什么顺序、调用哪些API接口并把这些逻辑转换成代码。这不仅仅是简单的请求重放它最大的价值在于能智能地构建出请求之间的依赖关系图。比如下载账单的请求需要一个动态的accountId而这个accountId又来自另一个获取用户信息的请求。Integuru能自动发现这种依赖链并生成一个从登录认证开始到最终完成目标操作的完整工作流代码。这个工具非常适合开发者、自动化工程师以及任何需要与缺乏官方API或API文档不全的Web服务进行程序化交互的人。它降低了逆向工程的技术门槛让你能更专注于业务逻辑而不是在纷繁复杂的网络请求中耗费大量时间。2. 核心原理从“黑盒”操作到“白盒”代码的智能转换Integuru的工作流程可以看作是一个智能的、数据驱动的逆向工程过程。它不关心网站前端的UI长什么样只关心背后实际发生了哪些数据交换。理解其原理能帮助我们在使用中更好地定位问题甚至进行定制化开发。2.1 数据采集捕获完整的交互上下文一切始于create_har.py脚本。当你运行它时它会启动一个受控的浏览器实例通常基于Playwright或Selenium并开始记录所有HTTP/HTTPS请求和响应最终生成一个HARHTTP Archive文件。同时它还会导出当前浏览器会话的所有Cookie保存为JSON文件。注意这里有一个关键细节。单纯的HAR记录器很多但Integuru要求你在记录过程中完成一次完整的、包含目标动作的流程。比如你的目标是下载报告那么你就需要在浏览器里完成登录、导航到报告页面、点击下载这一系列操作。这确保了HAR文件里包含了从认证到目标动作的完整请求链为后续的依赖分析提供了必要的上下文。如果只记录了最后一步AI将无法推断出前置的认证或数据获取步骤。2.2 依赖图构建AI如何理解请求间的“血缘关系”这是Integuru最核心的智能部分。当你提供提示词如“download utility bills”后它会将HAR文件和提示词一同发送给大语言模型如GPT-4o。LLM的任务是扮演一个“网络流量分析师”其推理过程可以分解为以下几个步骤目标请求定位LLM首先扫描HAR中的所有请求根据你的提示词找出最可能是执行目标动作的那个请求。例如一个返回PDF文件流、URL中包含/download或/export的GET请求就很有可能是下载动作的终点。动态参数溯源找到目标请求后LLM会分析其URL和请求体如果有识别出哪些参数是动态的、每次请求可能变化的。比如https://api.example.com/bills?accountId12345period2023-10中的accountId12345和period2023-10。LLM会判断period可能是由用户输入决定的变量而accountId更可能来自于系统之前返回的某个数据。依赖关系解析与图构建接下来LLM会在HAR文件中“回溯”寻找生成这些动态参数的源头请求。例如它可能发现另一个GET https://api.example.com/user/profile的请求其响应体是一个JSON其中包含了accountId: 12345。于是LLM会建立一条依赖边下载账单的请求依赖于获取用户资料的请求因为前者需要的accountId来自后者的响应。 这个过程会递归进行。获取用户资料的请求可能需要一个认证Token而这个Token又来自登录请求的响应。最终LLM会构建出一个有向无环图DAG图的根节点是仅依赖初始Cookie的请求通常是登录或会话初始化叶子节点就是我们的目标请求中间节点则是层层递进的数据获取步骤。变量识别与抽象在构建图的过程中LLM还会区分“动态变量”和“输入变量”。动态变量如accountId是程序运行中从上游请求响应中提取的。而输入变量如YEAR是用户希望从外部传入的。项目文档提到v0版本支持在构建图时识别输入变量但在代码生成时暂不支持这提示我们生成的代码可能需要手动替换这部分为参数。2.3 代码生成将依赖图翻译为可执行逻辑当依赖图构建完毕后Integuru会再次调用LLM这里推荐使用更擅长代码生成的o1-preview模型将这张图转换成Python代码。转换逻辑非常直观每个请求成为一个函数图中的每个节点请求被转换成一个独立的函数例如def fetch_user_profile(cookies):。依赖关系成为函数调用链函数内部会调用它所依赖的上游函数来获取必要参数。例如download_bill函数内部会先调用fetch_user_profile来拿到accountId。错误处理与数据传递生成的代码会包含基础的错误处理如检查HTTP状态码和从响应中提取所需数据的逻辑通常使用json.loads()和字段访问。Cookie管理初始的Cookie会被作为最基础层的参数在整个调用链中传递或由会话对象如requests.Session管理以维持登录状态。最终你会得到一个完整的Python脚本运行它就能模拟你之前在浏览器中的操作自动完成下载账单等任务。3. 实战演练从零开始用Integuru逆向一个示例服务理论讲完了我们动手实操一遍。假设我们要自动化下载某个虚构的“云服务商”的月度用量报告。该网站没有公开API所有操作都需要通过网页完成。3.1 环境准备与配置首先克隆项目并搭建环境。Integuru使用Poetry管理依赖这能很好地解决环境隔离问题。# 1. 克隆仓库 git clone https://github.com/Integuru-AI/Integuru.git cd Integuru # 2. 安装Poetry如果尚未安装 # 访问 https://python-poetry.org/docs/ 查看安装指南 # 3. 使用Poetry安装项目依赖 # Poetry会读取pyproject.toml创建虚拟环境并安装所有包 poetry install # 4. 激活Poetry的虚拟环境 # 后续所有命令都需要在这个虚拟环境中运行 poetry shell接下来是关键的API密钥配置。Integuru依赖OpenAI的LLM你需要一个有效的OpenAI账户。登录 OpenAI平台 在“API Keys”页面创建新的密钥。将密钥设置为环境变量。在Linux/macOS的终端或Windows的PowerShell中执行# Linux/macOS export OPENAI_API_KEY你的-api-key-here # Windows (PowerShell) $env:OPENAI_API_KEY你的-api-key-here重要提示为了获得最佳效果尤其是依赖图构建的准确性你的OpenAI账户需要能够访问gpt-4o或o1系列模型。根据项目说明gpt-4o因其函数调用能力被推荐用于图生成而o1-preview则用于最终的代码生成。如果账户可用Integuru会自动切换模型。3.2 记录操作生成HAR与Cookie文件现在开始记录我们的目标操作。# 在项目根目录下运行记录脚本 poetry run python create_har.py这个命令会弹出一个浏览器窗口。请务必在此浏览器中完成整个操作流程访问目标网站例如https://mycloudprovider.com。登录你的账户。如果网站有二次验证2FA在此浏览器内完成验证。这是成功的关键因为2FA后的会话Cookie才是有效的。导航到用量报告页面。选择月份比如2024-03点击“生成报告”或“下载PDF”。操作完成后不要关闭浏览器回到终端按CtrlC停止记录脚本。此时项目根目录下会生成两个文件network_requests.har: 包含所有网络请求的详细记录。cookies.json: 包含浏览器当前的所有Cookie。实操心得为了提高成功率建议在记录时操作尽量“干净”。关闭不必要的浏览器标签页避免在记录过程中进行与目标无关的浏览。这样生成的HAR文件噪音更少有助于AI更精准地定位关键请求。另外对于复杂的多步操作可以考虑分段记录但要注意保持会话Cookie的连续性。3.3 运行AI代理生成依赖图与代码有了数据文件就可以请AI代理上场分析了。# 基本命令使用默认的gpt-4o模型分析HAR并尝试生成代码 poetry run integuru --prompt download the monthly usage report for March 2024 --generate-code # 更详细的命令示例指定模型和输入变量 poetry run integuru \ --model gpt-4o \ # 指定用于图生成的模型 --prompt download monthly usage report \ --har-path ./network_requests.har \ --cookie-path ./cookies.json \ --input_variables YEAR 2024 MONTH 03 \ # 声明输入变量目前主要用于图分析 --generate-code # 指示工具生成最终的可执行Python代码运行后Integuru会开始工作。你会在终端看到它的思考过程如果模型支持包括它如何识别目标请求、如何发现依赖关系。最终它会在当前目录生成一个Python文件文件名可能基于你的提示词里面就是完整的自动化脚本。3.4 审查与运行生成的代码千万不要直接运行生成的代码首先必须进行人工审查。安全检查仔细检查代码中是否包含你的敏感信息如硬编码的账号ID、个人令牌等。虽然这些信息来自Cookie和HAR但确保它们被恰当地处理或参数化。逻辑审查浏览代码看其逻辑是否清晰。检查它是否正确地处理了登录状态通常通过requests.Session依赖函数调用顺序是否正确关键参数如报告日期是否被正确提取和传递。输入参数化正如之前提到的v0版本在代码生成时可能不会自动将input_variables转化为函数参数。你很可能需要手动修改代码将类似YEAR 2024这样的硬编码值改为从函数参数或配置文件读取。添加健壮性AI生成的代码通常是“最佳路径”下的缺乏错误处理和重试机制。你需要添加try-except块、状态码检查、日志记录以及对于网络波动的重试逻辑例如使用tenacity库。修改完毕后你可以在隔离的环境下首次运行python generated_integration_code.py如果运行成功恭喜你你已经拥有了一个可以自动化该网站操作的脚本。如果失败就需要进入排查环节。4. 深度排查与进阶调优指南在实际使用中你可能会遇到各种问题。下面是我在多次实践中总结的常见问题及其解决方案。4.1 常见问题与解决方案速查表问题现象可能原因排查步骤与解决方案AI无法识别目标请求1. 提示词过于模糊。2. HAR文件中目标请求特征不明显。3. 目标动作是POST且请求体复杂。1.优化提示词使用更具体、包含关键动词和名词的描述。例如用“点击‘导出PDF’按钮下载报表”代替“下载报表”。2.手动辅助在HAR文件中找到目标请求的URL或响应类型如application/pdf在提示词中直接给出线索“查找返回PDF且URL中包含/export的请求”。3.检查模型确认使用的模型如gpt-4o是否支持足够的上下文长度和理解能力。生成的依赖图不完整或错误1. 动态参数来自JavaScript计算或页面DOM不在网络请求中。2. 请求间依赖非数据依赖而是状态依赖如先A后B的顺序。3. LLM推理步骤受限。1.扩大采集范围确保记录的操作覆盖了所有前置页面状态变更。对于JS生成的值有时需要观察初始化页面的多个XHR请求。2.调整max_steps参数默认是20步对于复杂流程可能不够。使用--max_steps 50增加AI推理的深度。3.分治策略如果流程非常长尝试将其拆分成多个子任务如“登录并获取仪表盘”、“在仪表盘找到报告入口”、“下载报告”分别记录HAR和运行Integuru最后手动拼接代码。生成的代码运行失败认证错误1. Cookie已过期。2. 认证机制非简单Cookie如Bearer Token、JWT需要刷新。3. 存在反爬虫机制如验证码、请求签名。1.更新Cookie重新运行create_har.py获取最新会话的Cookie。2.分析认证流在HAR中搜索authorization,token,jwt等关键词找到Token的获取和刷新接口在代码中实现完整的认证生命周期管理。3.模拟浏览器对于强反爬网站考虑使用playwright或selenium直接运行生成的导航逻辑而不是纯HTTP请求。Integuru生成的依赖图依然是极好的路线图。代码无法处理输入变量当前v0版本代码生成功能对输入变量支持不完善。手动参数化这是目前最主要的处理方式。在生成的代码中找到硬编码的数值如日期2024-03-01将其替换为函数参数。例如将主函数改为def main(year, month):并在内部替换相应的值。create_har.py脚本无法启动浏览器缺少浏览器驱动或依赖。1.安装Playwright浏览器在Poetry shell内运行playwright install。2.检查系统依赖确保有图形界面或配置了虚拟显示对于无头服务器。4.2 性能与成本优化技巧使用商业LLM API会产生成本尤其是处理大型HAR文件时。以下是一些优化建议精简HAR文件HAR文件可能很大几十MB。在运行Integuru前可以用文本编辑器或脚本手动删除其中与目标域名无关的请求如第三方CDN、分析脚本只保留目标网站的关键请求。这能显著减少Token消耗并降低AI的干扰。分阶段使用模型严格按照项目推荐图生成阶段使用gpt-4o以保证推理质量代码生成阶段使用o1-preview如果可用以获得更优的代码质量和性价比。可以通过--model参数分别试验。利用缓存如果未来版本支持关注项目更新看是否会引入对相同HAR和提示词的推理结果缓存功能避免重复分析。4.3 处理复杂认证与反爬策略对于现代Web应用简单的Cookie复用可能不够。OAuth2/Token流程如果网站使用OAuth2你需要在记录HAR时完成整个授权码流程。生成的代码将包含向认证服务器请求token的步骤。你需要将client_id和client_secret等敏感信息移出代码放入环境变量。请求签名一些API会对请求参数、时间戳等进行加密签名。如果HAR中的请求带有signature、nonce等参数说明存在签名机制。逆向签名算法极其困难。此时Integuru的价值在于帮你定位到签名的生成位置通常是某个特定的JavaScript文件但你需要手动去分析或寻找现成的逆向方案。状态依赖有些操作依赖于前一个请求在服务器端创建的“状态”而这个状态可能只存在于服务端会话中不在响应里体现。这种情况下依赖图可能无法捕获这种隐式依赖需要你根据业务逻辑手动确保请求的顺序。5. 项目架构浅析与扩展思路虽然作为用户我们主要使用命令行工具但了解其内部架构有助于我们进行调试和潜在贡献。Integuru v0的代码结构相对清晰create_har.py: 基于Playwright的浏览器自动化与记录脚本。integuru/: 核心模块目录。agent.py: 包含与OpenAI API交互、管理推理循环的核心代理逻辑。graph_builder.py: 负责处理LLM输出构建和操作请求依赖图的数据结构。code_generator.py: 将依赖图转换为Python代码的模块。models.py: 定义数据模型如RequestNode请求节点、DependencyGraph依赖图。main.ipynb: Jupyter Notebook入口适合交互式探索和调试。一个潜在的扩展方向是支持更多LLM提供商。目前代码深度绑定OpenAI API。社区可以贡献适配层使其支持Anthropic Claude、Google Gemini或本地部署的Llama等模型这能大大提高工具的灵活性和可访问性。另一个方向是增强代码生成模板。目前的代码生成比较基础。可以引入更强大的模板引擎生成包含更完善错误处理、日志记录、配置管理如使用pydantic-settings以及异步请求aiohttp的高质量代码。最后交互式调试工具会非常有用。例如一个GUI可以可视化展示AI构建的依赖图允许用户手动添加/删除边、修正参数映射然后再重新生成代码。这将把AI从一个黑盒代码生成器变成一个强大的“人机协同”逆向工程助手。Integuru v0展示了一条有趣的路径利用LLM的世界知识和推理能力将非结构化的网络流量数据转化为结构化的、可执行的程序逻辑。它并非万能在遇到极其复杂的客户端逻辑或强对抗性反爬时仍会力有不逮。但对于大量常见的、基于请求-响应模式的Web操作自动化它能显著提升开发效率把开发者从繁琐的抓包和调试中解放出来。随着模型能力的进化和项目功能的完善这类工具有望成为开发者工具箱中的常备利器。