核心内容摘要
EcomGPT-7B模型压缩实战：4-bit量化部署指南
Open-AutoGLM项目结构解析开发者快速上手
为什么需要理解Open-AutoGLM的项目结构你刚 clone 下来Open-AutoGLM仓库执行pip install -e .后运行python main.py成功完成了“打开小红书搜美食”的指令——但当你想改一个按钮点击逻辑、加一个新应用的适配规则或者调试某次截图识别失败的原因时却在几十个文件里反复 grep、跳转、猜模块职责这正是多数开发者卡在“能跑通”和“能改明白”之间的关键断层。
Open-AutoGLM 不是一个黑盒工具而是一个可调试、可扩展、可定制的手机端 AI Agent 框架。
它的价值不仅在于开箱即用的自动化能力更在于清晰分层的工程设计视觉感知、意图理解、动作规划、设备控制、安全兜底各司其职又紧密协同。
理解它的目录骨架与模块边界不是为了背代码而是为了在遇到真实问题时能三秒定位到该看哪一层、该改哪个类、该补哪段日志。
本文不讲“如何部署模型”也不堆砌参数说明而是带你像维护自己写的项目一样真正走进 Open-AutoGLM 的源码世界。
我们将逐层拆解核心目录说明每个模块的职责边界、关键类设计、典型调用链路并给出3个高频二次开发场景的实操路径——让你从“使用者”真正升级为“协作者”。
项目根目录与初始化逻辑
1 顶层结构概览克隆仓库后你看到的是一个典型的 Python 包结构Open-AutoGLM/ ├── phone_agent/ # 核心功能包已安装为可导入模块 ├── examples/ # 可运行的使用示例 ├── tests/ # 单元测试与集成测试 ├── requirements.txt # 运行依赖 ├── pyproject.toml # 构建与开发配置 ├── main.py # 命令行入口脚本 └── README.md # 项目说明注意phone_agent/是整个框架的“心脏”所有业务逻辑都封装在此包内。
它被pip install -e .安装为可导入模块因此你在任何 Python 脚本中都能直接写from phone_agent import PhoneAgent—— 这种设计让集成成本极低也意味着你修改phone_agent/下的代码会立即生效无需重新安装。
2main.py命令行入口的轻量封装main.py看似简单却是理解整体流程的绝佳起点。
它不做复杂逻辑只做三件事解析命令行参数--device-id、--base-url、--model、自然语言指令等组装核心对象创建PhoneAgent实例传入ADBConnection和ModelClient触发主流程调用agent.run(instruction)并打印结果。
关键代码片段已简化# main.py from phone_agent import PhoneAgent from phone_agent.adb import ADBConnection from phone_agent.model import ModelClient def main(): args parse_args() # 解析参数 adb_conn ADBConnection(device_idargs.device_id) model_client ModelClient(base_urlargs.base_url, model_nameargs.model) agent PhoneAgent(adbadb_conn, modelmodel_client) result agent.run(args.instruction) # ← 所有魔法从此开始 print(result) if __name__ __main__: main()这里没有隐藏逻辑没有抽象工厂只有清晰的对象协作。
PhoneAgent是总控ADBConnection是手脚ModelClient是大脑——这种职责划分贯穿整个项目。
phone_agent/核心模块深度解析
1phone_agent/agent.pyAI Agent 的总控中枢这是整个框架的“指挥室”。
PhoneAgent类不处理具体操作而是定义任务执行的标准生命周期run(instruction)主入口启动完整流程_perceive()调用 ADB 截图 模型识别获取当前屏幕状态_plan()将自然语言指令 屏幕内容输入大模型生成结构化动作序列_execute(action)将模型输出的动作如{type: click, x: 120, y: 340}交由actions/模块执行_verify()执行后再次截图验证是否达成目标例如“小红书首页”是否出现。
重点看_plan()方法的设计哲学# phone_agent/agent.py def _plan(self, instruction: str, screenshot_path: str) - List[Dict]: #
读取截图二进制数据 with open(screenshot_path, rb) as f: image_bytes f.read() #
构造多模态请求兼容 OpenAI 格式 messages [ {role: user, content: [ {type: text, text: f请根据以下屏幕内容完成指令{instruction}}, {type: image_url, image_url: {url: fdata:image/png;base64,{b64encode(image_bytes).decode()}}} ]} ] #
调用模型客户端 response self.model.chat(messages) return self._parse_action_list(response) # ← 将大模型文本输出解析为结构化动作这个方法暴露了两个关键事实① 它完全依赖self.model.chat()接口意味着你只要实现一个符合 OpenAI API 规范的ModelClient就能无缝替换底层模型vLLM / SGlang / 本地 Ollama② 动作解析逻辑_parse_action_list()是可重写的钩子函数如果你的模型输出格式不同比如 JSON Schema只需重载此方法无需动其他模块。
2phone_agent/adb/设备控制的稳定基石adb/目录是整个框架的“物理层”负责与安卓设备建立真实连接并执行原子操作。
它不关心 AI只确保每条指令精准送达phone_agent/adb/ ├── __init__.py ├── adb.py # 核心 ADB 命令封装截图、点击、滑动、输入 ├── connection.py # 设备连接管理USB/WiFi 自动发现与切换 ├── keyboard.py # ADB Keyboard 输入法控制解决中文输入问题 └── utils.py # 辅助工具坐标转换、设备信息获取最值得细读的是adb.py中的screenshot()和tap()方法# phone_agent/adb/adb.py def screenshot(self, output_path: str) - bool: 执行 adb shell screencap -p output_path自动处理 Windows 换行符问题 cmd [adb, -s, self.device_id, shell, screencap, -p] try: result subprocess.run(cmd, capture_outputTrue, checkTrue) # 关键修复Android 返回的 PNG 在 Windows 上需替换 \r\n → \n png_data result.stdout.replace(b\r\n, b\n) with open(output_path, wb) as f: f.write(png_data) return True except Exception as e: logger.error(f截图失败: {e}) return False def tap(self, x: int, y: int) - bool: 执行 adb shell input tap x y带重试机制 for i in range(
: # 最多重试3次 cmd [adb, -s, self.device_id, shell, input, tap, str(x), str(y)] if subprocess.run(cmd, capture_outputTrue).returncode 0: return True time.sleep(
0.
return False这段代码体现了工程化思维兼容性处理主动修复 Android 截图在 Windows 下的换行符问题鲁棒性设计点击操作内置重试延迟避免因设备响应慢导致单点失败日志友好错误时记录详细上下文方便排查是设备掉线还是权限问题。
3phone_agent/actions/动作执行的策略中心如果说adb/是“肌肉”actions/就是“运动神经”。
它将agent.py规划出的抽象动作如click,scroll,input_text翻译成具体的 ADB 命令序列并处理常见交互模式phone_agent/actions/ ├── __init__.py ├── base.py # Action 基类定义 execute()、validate() 接口 ├── click.py # 点击动作支持坐标、元素ID、文本匹配三种方式 ├── scroll.py # 滑动动作支持上/下/左/右以及“滑到指定文本”智能滚动 ├── input.py # 文本输入自动切换 ADB Keyboard处理中文编码 └── wait.py # 等待动作等待元素出现、等待页面加载完成以click.py为例它实现了三种点击策略的统一调度# phone_agent/actions/click.py class ClickAction(BaseAction): def execute(self, context: Dict) - bool: target self.params.get(target) if isinstance(target, dict) and x in target and y in target: return self._tap_by_coord(target[x], target[y]) # 坐标点击 elif isinstance(target, str) and target.startswith(id:): return self._click_by_id(target[3:]) # ID 点击 elif isinstance(target, str): return self._click_by_text(target) # 文本点击OCR 匹配 return False这种设计让你在写提示词时可以灵活选择要求模型输出坐标适合固定布局应用要求输出id:com.xiaohongshu:id/search_tab适合有稳定 resource-id 的应用或直接说“点击‘搜索’文字”依赖 OCR通用性强但稍慢。
框架不强制你用哪种而是把选择权交给提示词工程和实际场景。
4phone_agent/config/可配置化的业务适配层硬编码应用包名、Activity 名称、敏感操作关键词那是反模式。
config/目录提供了面向业务的可配置化能力phone_agent/config/ ├── __init__.py ├── app_mapping.py # 应用别名映射小红书 → com.xiaohongshu ├── prompts.py # 多语言提示词模板zh/en 提示词分离支持自定义 ├── safety.py # 敏感操作白名单哪些应用允许自动登录哪些操作需人工确认 └── constants.py # 全局常量超时时间、重试次数、截图分辨率等app_mapping.py是典型例子# phone_agent/config/app_mapping.py APP_MAPPING { 小红书: { package: com.xiaohongshu, launch_activity: com.xiaohongshu.main.MainActivity, search_box_id: com.xiaohongshu:id/search_input }, 抖音: { package: com.ss.android.ugc.aweme, launch_activity: com.ss.android.ugc.aweme.main.MainActivity, search_box_id: com.ss.android.ugc.aweme:id/a7a } }当你新增一个应用支持时只需修改这个字典无需动任何业务逻辑代码。
同理prompts.py中的SYSTEM_PROMPT_ZH定义了模型的系统角色“你是一个安卓手机助理请严格按步骤思考
分析当前界面...”修改此处即可调整模型的推理风格。
5phone_agent/model/模型服务的统一抽象层model/目录是框架的“大脑接口”它屏蔽了底层模型服务vLLM/SGlang/Ollama的差异提供统一的chat()方法phone_agent/model/ ├── __init__.py ├── base.py # ModelClient 基类定义 chat() 接口 ├── openai.py # OpenAI 兼容客户端对接 vLLM/SGlang 的 /v1/chat/completions ├── config.py # 模型配置类base_url, model_name, timeout 等 └── utils.py # 工具函数base64 编码、流式响应处理openai.py的核心是OpenAIModelClient# phone_agent/model/openai.py class OpenAIModelClient(ModelClient): def __init__(self, base_url: str, model_name: str, **kwargs): self.client OpenAI(base_urlbase_url, api_keynone) # vLLM 不校验 key self.model_name model_name def chat(self, messages: List[Dict], **kwargs) - str: response self.client.chat.completions.create( modelself.model_name, messagesmessages, max_tokens1024, temperature
0, ) return response.choices[0].message.content这意味着你想换用 SGlang只需改base_url为http://localhost:30000/v1你想本地跑 Ollamabase_url改为http://localhost:11434/v1再装ollama run autoglm-phone-9b你想加 token 统计重载chat()方法在返回前打印response.usage。
所有模型服务的切换都在一行base_url配置中完成。
三个高频二次开发场景实战指南
1 场景一为新应用添加专属操作逻辑如“微信发朋友圈”问题默认框架能打开微信但无法自动进入“发现→朋友圈→发表”路径。
解法不改核心代码只扩展actions/和config/。
步骤在config/app_mapping.py中补充微信的 Activity 路径微信: { package: com.tencent.mm, launch_activity: com.tencent.mm.ui.LauncherUI, friend_circle_entry: com.tencent.mm.plugin.sns.ui.SightTabTopView }新建phone_agent/actions/wechat.py实现朋友圈专用动作class PostToFriendCircleAction(BaseAction): def execute(self, context: Dict) - bool: adb context[adb] #
点击底部发现 adb.tap(200,
# 坐标需根据实际屏幕调整 time.sleep(
#
点击朋友圈 adb.tap(200,
time.sleep(
#
点击右上角号 adb.tap(1000,
return True在agent.py的_plan()后添加判断逻辑或通过提示词引导模型调用此动作。
2 场景二优化 OCR 文本点击的准确率问题click_by_text在复杂界面如新闻列表误匹配标题和正文。
解法增强 OCR 后处理而非重写整个流程。
步骤修改actions/click.py中的_click_by_text方法def _click_by_text(self, text: str) - bool: #
调用 OCR 获取所有文本框及其坐标 ocr_results self.ocr_engine.recognize(self.screenshot_path) #
过滤只保留字体大小 24px 的文本通常是标题 candidates [r for r in ocr_results if r[font_size] 24] #
模糊匹配支持错别字 matched fuzzy_match(text, [r[text] for r in candidates]) if matched: coord candidates[matched.index].get(center_coord) return self._tap_by_coord(coord[0], coord[1]) return False将ocr_engine注入ClickAction初始化复用adb/中的截图能力。
3 场景三增加远程调试的 Web 控制台问题想在浏览器里实时查看手机截图、发送指令、查看执行日志。
解法利用现有模块快速搭建轻量 Web 服务。
步骤新建web_console.py不放入phone_agent/作为独立脚本from flask import Flask, render_template, request, jsonify from phone_agent.adb import ADBConnection from phone_agent import PhoneAgent app Flask(__name__) adb ADBConnection(device_idyour_device_id) agent PhoneAgent(adbadb, modelyour_model_client) app.route(/) def index(): return render_template(console.html) # 显示截图和输入框 app.route(/screenshot) def get_screenshot(): adb.screenshot(/tmp/latest.png) return send_file(/tmp/latest.png, mimetypeimage/png) app.route(/run, methods[POST]) def run_instruction(): instruction request.json[instruction] result agent.run(instruction) return jsonify({result: result})运行flask run --host
0.
0.
0:5000访问http://localhost:5000即可调试。
5.
总结结构即能力清晰即生产力Open-AutoGLM 的项目结构不是教科书式的理想分层而是在真实手机自动化场景中反复打磨出的问题驱动型架构agent.py把“AI 思考”和“机器执行”解耦让你能单独测试规划逻辑adb/用最小侵入封装 ADB把设备差异USB/WiFi/模拟器收口到connection.pyactions/用策略模式支持多种交互方式避免为每个应用写死逻辑config/将业务规则外置让非程序员也能参与应用适配model/通过 OpenAI 兼容接口让模型服务成为可插拔组件。
这种结构带来的直接好处是当 ADB 连接不稳定时你只需盯adb/connection.py的重连逻辑当模型输出格式变更时你只需改model/openai.py的解析部分当要支持 iOS 时你只需新增ios/目录复用agent.py和config/当客户要求审计所有操作时你只需在actions/base.py的execute()中加日志钩子。
真正的快速上手不是跑通 demo而是第一次 debug 就能精准定位到第 37 行代码。
现在打开你的编辑器cd 进phone_agent/从agent.py开始亲手触摸这个框架的脉搏吧。
--- **