介绍
# TuriX-Mac Skill
该技能允许 Clawdbot 通过 TuriX 计算机使用代理在视觉上控制 macOS 桌面。
## 何时使用
- 当被要求在 Mac 桌面上执行操作时（例如，“打开 Spotify 并播放我喜欢的歌曲”）。 - 当导航缺乏命令行界面的应用程序时。 - 用于多步骤可视化工作流（例如，“在我的电子邮件中查找最新的发票并将其上传到公司门户”）。 - 当您需要代理自主规划、推理和执行复杂任务时。
## 主要功能
### 🤖 多模型架构 TuriX 使用复杂的多模型系统： - **大脑**：理解任务并生成分步计划 - **执行者**：基于视觉理解执行精确的 UI 操作 - **规划器**：协调高级任务分解（当 `use_plan: true` 时） - **记忆**：在任务步骤之间维护上下文
### 📋 技能系统 技能是针对特定领域指导代理的 markdown 剧本： - `github-web-actions`：GitHub 导航、代码库搜索、加星标 - `browser-tasks`：常规 Web 浏览器操作 - 可以将自定义技能添加到 `skills/` 目录中
### 🔄 恢复能力 代理可以通过设置稳定的 `agent_id` 来恢复被中断的任务。
## 运行 TuriX
### 基本任务 ```bash skills/local/turix-mac/scripts/run_turix.sh "Open Chrome and go to github.com" ```
### 恢复被中断的任务 ```bash skills/local/turix-mac/scripts/run_turix.sh --resume my-task-001 ```
> ✅ **注意**：`run_turix.sh` 会为您更新 `examples/config.json`（任务、恢复、`use_plan`、`use_skills`）。如果您想保留手动编辑的配置，请跳过传递任务，直接编辑 `examples/config.json`。
### 编写有效任务的技巧
**✅ 好的示例：** - “打开 Safari，前往 google.com，搜索 'TuriX AI'，然后点击第一个结果” - “打开系统设置，点击深色模式，然后返回系统设置” - “打开 Finder，导航到文档，然后创建一个名为 'Project X' 的新文件夹”
**❌ 避免：** - 含糊的指令：“帮助我”或“修复这个” - 不可能的操作：“删除所有文件” - 需要系统级权限但未发出警告的任务
**💡 最佳实践：** 1. 明确指定目标应用程序 2. 将复杂任务分解为清晰的步骤，但不要提及屏幕上的精确坐标。
## 快捷键
- **强制停止**：`Cmd+Shift+2` - 立即停止代理
## 监控与日志
日志保存到项目目录中的 `.turix_tmp/logging.log`。检查此文件以获取： - 分步执行详细信息 - LLM 交互和推理 - 错误和恢复尝试
## 重要说明
### TuriX 如何运行 - TuriX 可以通过带有 `pty:true` 模式的 clawdbot `exec` 启动 - 首次启动需要 2-5 分钟来加载所有 AI 模型（大脑、执行者、规划器、记忆） - 后台输出会被缓冲 - 在任务完成或停止之前您将看不到实时进度
### 运行前 **请务必先设置 PATH：** ```bash export PATH="/usr/sbin:$PATH" cd your_dir/TuriX-CUA /opt/anaconda3/envs/turix_env/bin/python examples/main.py ```
**为什么？** `screencapture` 工具位于 `/usr/sbin/screencapture`，该路径不在默认 PATH 中。
### 检查 TuriX 是否正在运行 ```bash # Check process ps aux | grep "python.*main" | grep -v grep
# Should show something like: # user 57425 0.0 2.4 412396704 600496 s143 Ss+ 5:56PM 0:04.76 /opt/anaconda3/envs/turix_env/bin/python examples/main.py ```
**注意：** 在 TuriX 开始执行步骤之前，可能不会创建 `.turix_tmp` 目录。
## 故障排除
### 常见问题
| 错误 | 解决方案 | |-------|----------| | `NoneType has no attribute 'save'` | 缺少屏幕录制权限。在系统设置中授予权限并重启终端。 | | `Screen recording access denied` | 运行：`osascript -e 'tell application "Safari" to do JavaScript "alert(1)"'` 并点击允许 | | `Conda environment not found` | 确保 `turix_env` 存在：`conda create -n turix_env python=3.12` | | 模块导入错误 | 激活环境：`conda activate turix_env`，然后运行 `pip install -r requirements.txt` | | 键盘侦听器的权限错误 | 将终端/IDE 添加到 **辅助功能** 权限中 |
### 调试模式
默认情况下，日志包含 DEBUG 级别。检查： ```bash tail -f your_dir/TuriX-CUA/.turix_tmp/logging.log ```
## 架构
``` User Request ↓ [Clawdbot] → [TuriX Skill] → [run_turix.sh] → [TuriX Agent] ↓ ┌─────────────────────────┼─────────────────────────┐ ↓ ↓ ↓ [Planner] [Brain] [Memory] ↓ ↓ ↓ [Actor] ───→ [Controller] ───→ [macOS UI] ```
## 技能系统详细信息
技能是 `skills/` 目录中带有 YAML frontmatter 的 markdown 文件：
```md --- name: skill-name description: When to use this skill --- # Skill Instructions High-level workflow like: Open Safari,then go to Google. ```
规划器根据名称/描述选择相关技能；大脑使用完整内容进行步骤指导。
## 高级选项
| 选项 | 描述 | |--------|-------------| | `use_plan: true` | 启用针对复杂任务的规划 | | `use_skills: true` | 启用技能选择 | | `resume: true` | 从之前的断点恢复 | | `max_steps: N` | 限制总步数（默认：100） | | `max_actions_per_step: N` | 每步操作数（默认：5） | | `force_stop_hotkey` | 用于停止代理的自定义快捷键 |
---
## TuriX 技能系统
TuriX 支持 **技能**：帮助代理在特定领域表现更可靠的 markdown 剧本。
### 1. 内置技能
| 技能 | 用途 | |-------|-----| | `github-web-actions` | GitHub Web 操作（搜索代码库、加星标等） |
### 2. 创建自定义技能
在 TuriX 项目的 `skills/` 目录中创建一个 `.md` 文件：
```md --- name: my-custom-skill description: When performing X specific task --- # Custom Skill
## Guidelines - Step 1: Do this first - Step 2: Then do that - Step 3: Verify the result ```
**字段定义：** - `name`：技能标识符（供规划器选择使用） - `description`：何时使用此技能（规划器据此匹配） - 下方正文：完整执行指南（供大脑使用）
### 3. 启用技能
在 `examples/config.json` 中：
```json { "agent": { "use_plan": true, "use_skills": true, "skills_dir": "skills", "skills_max_chars": 4000 } } ```
### 4. 使用技能运行任务
```bash skills/local/turix-mac/scripts/run_turix.sh "Search for turix-cua on GitHub and star it" ```
代理将自动： 1. 规划器读取技能名称和描述 2. 选择相关技能 3. 大脑使用完整的技能内容指导执行
### 5. 中文文本支持
**背景：** 通过 shell 插值传递中文文本可能会破坏 UTF-8，而且将不受信任的文本插入到 heredoc 中是不安全的。
**解决方案：** `run_turix.sh` 脚本使用 Python 正确处理 UTF-8，并从环境变量中读取任务文本：
```python import json
# Read with UTF-8 with open(config_path, 'r', encoding='utf-8') as f: data = json.load(f)
# Write without escaping non-ASCII text with open(config_path, 'w', encoding='utf-8') as f: json.dump(data, f, indent=2, ensure_ascii=False) ```
**关键点：** 1. 读取/写入文件时始终使用 `encoding='utf-8'` 2. 使用 `ensure_ascii=False` 保留非 ASCII 文本 3. 通过环境变量或 stdin 传递任务内容，并使用单引号 heredoc 以避免 shell 插值
### 6. 文档创建最佳实践
**挑战：** - 要求 TuriX 收集新闻，然后直接创建并发送文档 - TuriX 是一个 GUI 代理，因此它可能速度较慢且确定性较低。请仅对 Clawdbot 无法执行或 TuriX 执行更快的任务使用 TuriX。
**推荐方法：** 您自己创建文档，让 TuriX 仅负责发送 1. 使用 python-docx 创建 Word 文档 2. 让 TuriX 仅发送该文件
```python from docx import Document doc = Document() doc.add_heading('Title') doc.save('/path/to/file.docx') ```
**建议的工作流：** 1. 使用 `web_fetch` 收集信息 2. 使用 Python 创建 Word 文档 3. 使用 TuriX 发送文件。指定文件路径并说明发送文件，而不仅仅是文件名。 4. 如果您确实需要 TuriX 手动创建 Word 文档并键入收集的信息，请将内容放在 turix 技能中（对于大量内容）或任务名称中（对于少量内容）。
### 7. 示例：添加新技能
创建 `skills/browser-tasks.md`：
```md --- name: browser-tasks description: When performing tasks in a web browser (search, navigate, fill forms). --- # Browser Tasks
## Navigation - Use the address bar or search box to navigate - Open new tabs for each distinct task - Wait for page to fully load before proceeding
## Forms - Click on input fields to focus - Type content clearly - Look for submit/button to complete actions
## Safety - Confirm before submitting forms - Do not download files without user permission ```
### 8. 技能开发技巧
1. **描述要精确** - 有助于规划器正确选择 2. **步骤要清晰** - 大脑需要明确的指导 3. **包含安全检查** - 对重要操作进行确认 4. **保持简洁** - 建议不超过 4000 个字符
---
## 监控与调试指南
### 1. 运行任务
```bash # Run in background (recommended) cd your_dir/clawd/skills/local/turix-mac/scripts ./run_turix.sh "Your task description" --background
# Or use timeout to set a max runtime ./run_turix.sh "Task" & ```
### 2. 监控进度
**方法 1：会话日志** ```bash # List running sessions clawdbot sessions_list
# View history clawdbot sessions_history <session_key> ```
**方法 2：TuriX 日志** ```bash # Tail logs in real time tail -f your_dir/TuriX-CUA/.turix_tmp/logging.log
# Or inspect completed step files ls -lt your_dir/TuriX-CUA/examples/.turix_tmp/brain_llm_interactions.log_brain_*.txt ```
**方法 3：检查进程** ```bash ps aux | grep "python.*main.py" | grep -v grep ```
**方法 4：检查生成的文件** ```bash # List files created by the agent ls -la your_dir/TuriX-CUA/examples/.turix_tmp/*.txt ```
### 3. 日志文件参考
| 文件 | 描述 | |------|-------------| | `logging.log` | 主日志文件 | | `brain_llm_interactions.log_brain_N.txt` | 大脑模型对话（每步一个） | | `actor_llm_interactions.log_actor_N.txt` | 执行者模型对话（每步一个） |
**关键日志标记：** - `📍 Step N` - 新步骤开始 - `✅ Eval: Success/Failed` - 当前步骤评估 - `🎯 Goal to achieve this step` - 当前目标 - `🛠️ Action` - 执行的操作 - `✅ Task completed successfully` - 任务完成
### 4. 常见监控问题
| 问题 | 检查 | |-------|-------| | 进程无响应 | `ps aux | grep main.py` | | 卡在步骤 1 | 检查是否创建了 `.turix_tmp/` | | 模型加载缓慢 | 首次运行可能需要 1-2 分钟来加载模型 | | 无日志输出 | 检查 `config.json` 中的 `logging_level` |
### 5. 强制停止
**快捷键**：`Cmd+Shift+2` - 立即停止代理
**命令**： ```bash pkill -f "python examples/main.py" ```
### 6. 查看结果
完成后，代理将： 1. 在 `.turix_tmp/` 中创建交互日志 2. 创建记录文件（如果使用了 `record_info`） 3. 将截图保留在内存中以供后续步骤使用
**示例：查看摘要文件** ```bash cat your_dir/TuriX-CUA/examples/.turix_tmp/latest_ai_news_summary_jan2026.txt ```
### 7. 调试技巧
1. **检查大脑推理**：检查 `brain_llm_interactions.log_brain_*.txt` 中的 `analysis` 和 `next_goal` 2. **检查执行者操作**：检查 `actor_llm_interactions.log_actor_*.txt` 中的操作 3. **检查截图**：TuriX 每步都会截取一张屏幕截图（保留在内存中） 4. **阅读记录文件**：代理使用 `record_info` 将关键信息保存到 `.txt` 文件
### 8. 示例监控流程
```bash # 1. Run a task ./run_turix.sh "Search AI news and summarize" &
# 2. Wait a few seconds and check the process sleep 10 && ps aux | grep main.py
# 3. Check if logs are being created ls -la your_dir/TuriX-CUA/examples/.turix_tmp/
# 4. Tail progress in real time tail -f your_dir/TuriX-CUA/.turix_tmp/logging.log
# 5. Check current step count ls your_dir/TuriX-CUA/examples/.turix_tmp/brain_llm_interactions.log_brain_*.txt | wc -l ```