自定义TuriX动作Registry装饰器与动态Pydantic模型扩展桌面操作的完整教程【免费下载链接】TuriX-CUAThis is the official website for TuriX Computer-use-Agent项目地址: https://gitcode.com/gh_mirrors/tu/TuriX-CUATuriX-CUATuriX Computer-Use-Agent是一款开源的桌面自动化 AI 智能体让大模型直接上手操作你的电脑点击、输入、滚动、打开应用。它的动作系统基于Registry 装饰器与动态 Pydantic 模型构建你只需几行 Python 代码就能为 TuriX 注册一个全新的桌面动作让 AI 学会执行它原本不会的操作。本教程带你完整走一遍读懂动作注册机制 → 注册第一个自定义动作 → 利用动态 Pydantic 模型自动生成参数校验 → 运行验证。无需深入源码也能上手。一、先认识 TuriX 的动作执行链路 TuriX 采用多模型分工架构brain决策大脑、actor动作执行、planner规划、memory记忆各司其职通过 examples/config.json 自由切换模型。其中动作Action是 AI 与桌面之间的双手执行链路如下注册用controller.action()装饰器把 Python 函数登记进ActionRegistry建模系统为每个动作生成/绑定一个 Pydantic 参数模型用于校验 AI 输出的参数提示get_prompt_description()把所有动作的名称、描述、参数汇总成文字注入 planner 提示词让模型知道自己会哪些动作执行AI 输出结构化动作后execute_action()校验参数并真正调用你的函数。理解这条链路你就理解了为什么注册一个动作 给 AI 教会一个新技能。二、动作系统的三个核心文件路径导航文件职责src/controller/registry/service.pyRegistry类装饰器action()、同步函数自动转异步、动态参数模型生成src/controller/registry/views.pyActionRegistry、ActionModel、RegisteredAction数据结构src/controller/service.pyController注册全部内置动作点击、输入、滚动、打开 App 等src/controller/views.py内置动作的 Pydantic 参数模型如InputTextAction、DragActionsrc/mac/actions.pymacOS 底层操作函数left_click_pixel、type_into、press等内置动作都在 src/controller/service.py 的_register_default_actions()中注册例如左键点击像素、组合快捷键、运行 AppleScript等。三、准备工作克隆仓库与配置环境git clone https://gitcode.com/gh_mirrors/tu/TuriX-CUA cd TuriX-CUA conda create -n turix_env python3.12 conda activate turix_env pip install -r requirements.txt⚠️ macOS 用户记得在系统设置 → 隐私与安全性 → 辅助功能中授权你的终端/IDE否则动作无法执行详见 README.md。四、Step 1看懂一个内置动作是怎么注册的以 src/controller/service.py 中的输入文本动作为例关键就三行self.registry.action( Type, # 给 LLM 看的动作描述越清晰调用越准 param_modelInputTextAction) # Pydantic 参数模型 async def input_text(text: str): ... return ActionResult(extracted_contentSuccessfully input text)其中 src/controller/views.py 里的InputTextAction就是text: str一个字段的 Pydantic 模型——这就是参数校验的来源。五、Step 2注册你的第一个自定义动作在 examples/main.py 中创建Controller后即可用controller.action()装饰器注册新动作它是Registry.action()的直接代理见 src/controller/service.pyfrom src.controller.service import Controller, NoParamsAction from src.agent.views import ActionResult controller Controller() controller.action(Open TextEdit and type a custom greeting) async def open_textedit(greeting: str): import subprocess script ftell application TextEdit to activate subprocess.run([osascript, -e, script], checkTrue) return ActionResult(extracted_contentfOpened TextEdit: {greeting})然后把controller传入Agent(...)参考 examples/main.py 的controllercontroller参数。几个自动发生的魔法源码src/controller/registry/service.py✨没写param_model系统会读取函数签名的类型注解用 Pydantic 的create_model()动态生成参数模型_create_param_modelsrc/controller/registry/service.py——所以greeting: str会自动变成greeting: str字段写了同步函数会被asyncio.to_thread自动包装成异步不阻塞事件循环想隐藏某个内置动作构造时传Controller(exclude_actions[Click])即可跳过注册。六、Step 3动态 Pydantic 模型到底做了什么Registry.create_action_model()src/controller/registry/service.py会把所有已注册动作动态拼成一个大模型例如ActionModel( open_textedit Optional[Open_texteditParameters], # 你的自定义动作 Click Optional[LeftClickPixel], done Optional[NoParamsAction], ... )执行时execute_action()src/controller/registry/service.py会用action.param_model(**params)先校验参数再调用函数类型错误会在到达你的函数前就被拦截AI 也会收到明确的报错记忆从而自我修正。 想让参数带说明在 Pydantic 模型字段上用Field(..., description...)描述会一并进入提示词示例见 src/controller/views.py。七、避坑清单让 AI 准确调用你的新动作 ✅常见坑正确做法描述写得含糊描述是 LLM 判断何时调用的唯一依据写清做什么 何时用参考 src/agent/planner_service.py 中注入的action_descriptions忘记返回值统一返回ActionResult(extracted_content...)出错的分支同时填error字段可让智能体记住并换策略坐标用错类型内置动作统一使用归一化坐标position: List[float]src/controller/views.py自定义动作保持一致需要 UI 树上下文注册时加requires_mac_builderTrue函数末尾参数声明mac_tree_builder即可接收见 src/controller/service.py八、运行验证一句话让 AI 用上你的新动作修改 examples/config.json 中的任务例如{ agent: { task: 使用 open_textedit 动作向 TextEdit 发送一句问候 } }然后启动python examples/main.py观察日志中 actor 模型输出的结构化动作里出现open_textedit即代表自定义动作已被 AI 正确识别并执行 九、小结Registry 装饰器controller.action(description, param_model...)一行完成动作注册同步/异步都支持动态 Pydantic 模型不传参数模型时从函数类型注解自动生成传了则严格校验提示词自动注入动作描述与参数会汇入 planner 提示词描述质量直接决定调用准确率想继续深挖可看 src/controller/registry/ 的完整实现以及 src/agent/service.py 中create_action_model()的接入位置。给 TuriX 教会第一个新技能只需十几行代码——接下来让它操作你的桌面吧【免费下载链接】TuriX-CUAThis is the official website for TuriX Computer-use-Agent项目地址: https://gitcode.com/gh_mirrors/tu/TuriX-CUA创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考