TuriX-Mac 技能

此技能允许 Clawdbot 使用 TuriX 计算机使用代理，以视觉方式控制 macOS 桌面。

使用时机

• 当被要求对 Mac 桌面执行操作时（例如，“打开 Spotify 并播放我喜欢的歌曲”）。
• 当导航缺乏命令行界面的应用程序时。
• 对于多步骤的视觉工作流程（例如，“在我邮件中找到最新的发票并上传到公司门户”）。
• 当您需要代理自主规划、推理并执行复杂任务时。

主要特性

🤖 多模型架构

TuriX 采用一个复杂的多模型系统：

• 大脑：理解任务并生成分步计划
• 执行器：基于视觉理解执行精确的 UI 操作
• 规划器：协调高级任务分解（当use_plan: true时）
• 记忆在任务步骤间维持上下文

📋 技能系统

技能是指导智能体执行特定领域任务的 Markdown 操作手册：

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

🔄 恢复能力

智能体可以通过设置一个稳定的agent_id来恢复中断的任务。

运行 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（任务、恢复、使用计划,使用技能)。如果你想保留手动编辑的配置，请跳过传递任务，直接编辑examples/config.json文件。

有效任务的提示

✅ 好的例子：

• "打开 Safari，访问 google.com，搜索 'TuriX AI'，并点击第一个结果"
• "打开系统设置，点击深色模式，然后返回系统设置"
• "打开 Finder，导航到文档，并创建一个名为 '项目 X' 的新文件夹"

❌ 避免：

• 模糊的指令："帮我" 或 "修复这个"
• 不可能的操作："删除所有文件"
• 需要系统级权限但未事先警告的任务

💡 最佳实践：

1. 明确指定目标应用程序
2. 将复杂任务分解为清晰的步骤，但不要提及屏幕上的精确坐标。

快捷键

• 强制停止:Cmd+Shift+2- 立即停止代理程序

监控与日志

日志保存于项目目录下的 .turix_tmp/logging.log请检查此文件以获取：

• 逐步执行详情
• LLM 交互与推理过程
• 错误与恢复尝试

重要注意事项

TuriX 如何运行

• TuriX 可通过 clawdbotexec以pty:true模式启动
• 首次启动需要 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

为什么？该屏幕截图工具位于/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 开始执行步骤后才会被创建。故障排除

常见问题

错误

调试模式

日志默认包含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.

规划器基于名称/描述选择相关技能；大脑则使用完整内容进行步骤指导。

高级选项

TuriX 技能系统

TuriX 支持技能：帮助代理在特定领域更可靠地行事的 Markdown 剧本。

1. 内置技能

2. 创建自定义技能

创建一个.md 文件TuriX项目中的skills/目录下的文件：

---
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中：

{
  "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"

代理将自动：

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

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文本通过环境变量或标准输入传递任务内容，并使用单引号heredoc来避免shell插值
3. 6. 文档创建最佳实践

挑战：

要求TuriX收集新闻，然后直接创建并发送文档

• TuriX是一个GUI代理，因此可能速度较慢且确定性较低。建议仅在Clawdbot无法完成的任务或TuriX速度更快的场景下使用TuriX。
• 推荐方法：

自行创建文档，仅让TuriX负责发送使用python-docx创建Word文档

1. 仅让TuriX发送文件
2. Let TuriX only send the file

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. 描述要精确- 有助于计划者正确选择
2. 步骤要清晰- 大脑需要明确的指导
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. 监控进度

方法一：会话日志

# List running sessions
clawdbot sessions_list

# View history
clawdbot sessions_history <session_key>

方法二：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

方法三：检查进程

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

方法四：检查生成的文件

# List files created by the agent
ls -la your_dir/TuriX-CUA/examples/.turix_tmp/*.txt

3. 日志文件参考

关键日志标记：

• 📍 步骤 N- 新步骤已开始
• ✅ 评估：成功/失败- 当前步骤评估
• 🎯 本步骤需达成的目标- 当前目标
• 🛠️ 行动- 已执行操作
• ✅ 任务成功完成- 任务已完成

4. 常见监控问题

5. 强制停止

快捷键:Cmd+Shift+2- 立即停止代理

命令6. 查看结果

pkill -f "python examples/main.py"

完成后，代理将：

在

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

示例：查看摘要文件

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

7. 调试技巧

1. 检查大脑推理过程：查看brain_llm_interactions.log_brain_*.txt文件以进行分析和确定下一步目标
2. 检查执行器操作：查看actor_llm_interactions.log_actor_*.txt文件以了解操作详情
3. 检查截图：TuriX 每一步都会捕获截图（保存在内存中）
4. 读取记录文件：代理使用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