turix-mac

TuriX-Mac 技能

此技能允许 Clawdbot 使用 TuriX Computer Use Agent 以可视化方式控制 macOS 桌面。

适用场景

• 当需要在 Mac 桌面上执行操作时（例如：“打开 Spotify 并播放我喜欢的歌曲”）。
• 当需要浏览没有命令行界面的应用程序时。
• 当需要执行多步骤的可视化工作流时（例如：“在我的电子邮件中找到最新的发票，并将其上传到公司门户”）。
• 当需要 Agent 自主规划、推理并执行复杂任务时。

主要功能

🤖 多模型架构

TuriX 使用复杂的多模型系统：

• Brain：理解任务并生成分步计划
• Actor：基于视觉理解执行精确的 UI 操作
• Planner：协调高层任务分解（当 use_plan: true 时）
• Memory：在任务各步骤之间保持上下文

📋 技能系统

技能是用于指导 Agent 处理特定领域任务的 Markdown 操作手册：

• github-web-actions：GitHub 导航、仓库搜索、加星标
• browser-tasks：通用网页浏览器操作
• 可以将自定义技能添加到 skills/ 目录

🔄 继续执行能力

通过设置稳定的 agent_id，Agent 可以继续执行中断的任务。

运行 TuriX

基本任务

skills/local/turix-mac/scripts/run_turix.sh "Open Chrome and go to github.com"

继续执行中断的任务

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 - 立即停止 Agent

监控与日志

日志保存在项目目录下的 .turix_tmp/logging.log 中。可在此查看：

• 分步执行详情
• 大模型交互和推理过程
• 错误及恢复尝试

重要说明

TuriX 的运行方式

• 可以通过 clawdbot exec 以 pty:true 模式启动 TuriX
• 首次启动需要 2-5 分钟加载所有 AI 模型（Brain、Actor、Planner、Memory）
• 后台输出会被缓冲——任务完成或停止之前，你看不到实时进度

运行前

务必先设置 PATH：

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 是否正在运行

# 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_tmp 目录可能要等 TuriX 开始执行步骤后才会创建。

故障排除

常见问题

错误	解决方案
NoneType has no attribute 'save'	缺少屏幕录制权限。请在系统设置中授予权限，然后重启 Terminal。
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
键盘监听器权限错误	为 Terminal/IDE 添加辅助功能权限

调试模式

日志默认包含 DEBUG 级别的内容。请查看：

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 前置元数据的 Markdown 文件：

---
name: skill-name
description: When to use this skill
---
# Skill Instructions
High-level workflow like: Open Safari,then go to Google.

Planner 会根据名称/描述选择相关技能；Brain 会使用完整内容来指导各步骤。

高级选项

选项	描述
use_plan: true	为复杂任务启用规划
use_skills: true	启用技能选择
resume: true	从上次中断处继续
max_steps: N	限制总步骤数（默认值：100）
max_actions_per_step: N	每步的操作数（默认值：5）
force_stop_hotkey	用于停止 Agent 的自定义快捷键

---

TuriX 技能系统

TuriX 支持技能：帮助 Agent 在特定领域中更可靠地执行任务的 Markdown 操作手册。

1. 内置技能

技能	用途
github-web-actions	GitHub 网页操作（搜索仓库、加星等）

2. 创建自定义技能

在 TuriX 项目的 skills/ 目录中创建 .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：技能标识符（供 Planner 选择）
• description：此技能的使用时机（Planner 会根据此项进行匹配）
• 下方正文：完整的执行指南（供 Brain 使用）

3. 启用技能

在 examples/config.json 中：

{
  "agent": {
    "use_plan": true,
    "use_skills": true,
    "skills_dir": "skills",
    "skills_max_chars": 4000
  }
}

4. 使用技能运行任务

skills/local/turix-mac/scripts/run_turix.sh "Search for turix-cua on GitHub and star it"

Agent 将自动：

1. Planner 读取技能名称和描述
2. 选择相关技能
3. Brain 使用完整的技能内容来指导执行

5. 中文文本支持

背景： 通过 shell 插值传递中文文本可能会破坏 UTF-8 编码，而将不可信文本插入 heredoc 中则不安全。

解决方案： run_turix.sh 脚本使用 Python 正确处理 UTF-8，并从环境变量中读取任务文本：

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 Agent，因此速度可能较慢，且确定性较低。建议仅在 Clawdbot 无法完成任务或 TuriX 速度更快时使用 TuriX。

**推荐做法：**自行创建文档，只让 TuriX 发送

1. 使用 python-docx 创建 Word 文档
2. 只让 TuriX 发送文件

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：

---
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. 准确描述——帮助 Planner 正确选择
2. 明确步骤——Brain 需要明确的指导
3. 加入安全检查——对重要操作进行确认
4. 保持简洁——建议少于 4000 个字符

---

监控与调试指南

1. 运行任务

# 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：会话日志

# List running sessions
clawdbot sessions_list

# View history
clawdbot sessions_history <session_key>

方法 2：TuriX 日志

# 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：检查进程

ps aux | grep "python.*main.py" | grep -v grep

方法 4：检查生成的文件

# 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	Brain 模型对话（每步一个）
actor_llm_interactions.log_actor_N.txt	Actor 模型对话（每步一个）

关键日志标记：

• 📍 Step N - 开始新步骤
• ✅ Eval: Success/Failed - 当前步骤评估结果
• 🎯 Goal to achieve this step - 当前目标
• 🛠️ Action - 已执行操作
• ✅ Task completed successfully - 任务已成功完成

4. 常见监控问题

问题	检查方法
进程无响应	`ps aux
卡在第 1 步	检查是否已创建 .turix_tmp/
模型加载缓慢	首次运行时，加载模型可能需要 1-2 分钟
没有日志输出	检查 config.json 中的 logging_level

5. 强制停止

快捷键：Cmd+Shift+2 - 立即停止 Agent

命令：

pkill -f "python examples/main.py"

6. 查看结果

完成后，Agent 将：

1. 在 .turix_tmp/ 中创建交互日志
2. 创建记录文件（如果使用了 record_info）
3. 将屏幕截图保留在内存中，供后续步骤使用

示例：查看摘要文件

cat your_dir/TuriX-CUA/examples/.turix_tmp/latest_ai_news_summary_jan2026.txt

7. 调试提示

1. 检查 Brain 推理过程：查看 brain_llm_interactions.log_brain_*.txt 中的 analysis 和 next_goal
2. 检查 Actor 操作：查看 actor_llm_interactions.log_actor_*.txt 中的操作
3. 检查屏幕截图：TuriX 每一步都会截取屏幕截图（保留在内存中）
4. 读取记录文件：Agent 使用 record_info 将关键信息保存到 .txt 文件中

8. 示例监控流程

# 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