名称： turix-mac
描述： 使用 TuriX 实现 macOS 自动化的计算机使用代理（CUA）。当你需要在桌面上执行视觉任务时使用，例如打开应用程序、点击按钮或导航没有 CLI 或 API 的 UI。

TuriX-Mac 技能

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

何时使用

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

主要特性

🤖 多模型架构

TuriX 使用一个复杂的多模型系统：
- Brain（大脑）：理解任务并生成分步计划
- Actor（执行者）：基于视觉理解执行精确的 UI 操作
- Planner（规划器）：协调高层次的任务分解（当 use_plan: true 时）
- Memory（记忆）：跨任务步骤维护上下文

📋 技能系统

技能是指导代理执行特定领域任务的 Markdown 剧本：
- github-web-actions：GitHub 导航、仓库搜索、加星标
- browser-tasks：通用网页浏览器操作
- 自定义技能可以添加到 skills/ 目录中

🔄 恢复能力

代理可以通过设置一个稳定的 agent_id 来恢复被中断的任务。

运行 TuriX

基本任务

skills/local/turix-mac/scripts/run_turix.sh "打开 Chrome 并访问 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’，并点击第一个结果”
- “打开系统设置，点击深色模式，然后返回系统设置”
- “打开访达，导航到文稿，并创建一个名为 ‘项目 X’ 的新文件夹”

❌ 避免：
- 模糊的指令：“帮我”或“修复这个”
- 不可能的操作：“删除所有文件”
- 需要系统级权限但未提前告知的任务

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

快捷键

• 强制停止：Cmd+Shift+2 - 立即停止代理

监控与日志

日志保存在项目目录的 .turix_tmp/logging.log 中。检查此文件以获取：
- 分步执行详情
- LLM 交互与推理过程
- 错误及恢复尝试

重要说明

TuriX 如何运行

• TuriX 可以通过 clawdbot exec 命令在 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

为什么？ screencapture 工具位于 /usr/sbin/screencapture，它不在默认的 PATH 中。

检查 TuriX 是否正在运行

# 检查进程
ps aux | grep "python.*main" | grep -v grep

# 应该显示类似这样的内容：
# 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

架构

用户请求
     ↓
[Clawdbot] → [TuriX 技能] → [run_turix.sh] → [TuriX 代理]
                                              ↓
                    ┌─────────────────────────┼─────────────────────────┐
                    ↓                         ↓                         ↓
               [规划器]                 [大脑]                  [记忆]
                    ↓                         ↓                         ↓
                                         [执行者] ───→ [控制器] ───→ [macOS UI]

技能系统详情

技能是位于 skills/ 目录下带有 YAML 前言（frontmatter）的 Markdown 文件：

---
名称： 技能名称
**描述：** 何时使用此技能
---
# 技能说明
高层次工作流，例如：打开 Safari，然后访问 Google。

规划器根据名称/描述选择相关技能；大脑使用完整内容来指导步骤执行。

高级选项

TuriX 技能系统

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

1. 内置技能

2. 创建自定义技能

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

---
名称： 我的自定义技能
**描述：** 当执行 X 特定任务时
---
# 自定义技能

## 指南
- 步骤 1：首先做这个
- 步骤 2：然后做那个
- 步骤 3：验证结果

字段定义：
- 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 "在 GitHub 上搜索 turix-cua 并为其加星标"

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

5. 中文文本支持

背景：
通过 shell 插值传递中文文本可能会破坏 UTF-8 编码，并且将不受信任的文本插值到 heredoc 中是不安全的。

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

import json

# 使用 UTF-8 读取
with open(config_path, 'r', encoding='utf-8') as f:
    data = json.load(f)

# 写入时不转义非 ASCII 文本
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 发送文件

from docx import Document
doc = Document()
doc.add_heading('标题')
doc.save('/path/to/file.docx')

建议工作流：
1. 使用 web_fetch 收集信息
2. 使用 Python 创建 Word 文档
3. 使用 TuriX 发送文件。指定文件路径并说明发送文件，而不仅仅是文件名。
4. 如果你确实需要 TuriX 手动创建 Word 文档并输入收集的信息，请将内容放在 turix 技能中（对于大量内容）或任务名称中（对于少量内容）。

7. 示例：添加新技能

创建 skills/browser-tasks.md：

---
名称： browser-tasks
**描述：** 当在网页浏览器中执行任务时（搜索、导航、填写表单）。
---
# 浏览器任务

## 导航
- 使用地址栏或搜索框进行导航
- 为每个不同的任务打开新标签页
- 等待页面完全加载后再继续

## 表单
- 点击输入框以获取焦点
- 清晰地输入内容
- 寻找提交/按钮以完成操作

## 安全
- 提交表单前进行确认
- 未经用户许可不要下载文件

8. 技能开发技巧

1. 描述要精确 - 帮助规划器正确选择
2. 步骤要清晰 - 大脑需要明确的指导
3. 包含安全检查 - 对重要操作进行确认
4. 保持简洁 - 建议在 4000 字符以内

监控与调试指南

1. 运行任务

# 在后台运行（推荐）
cd your_dir/clawd/skills/local/turix-mac/scripts
./run_turix.sh "你的任务描述" --background

# 或者使用 timeout 设置最大运行时间
./run_turix.sh "任务" &

2. 监控进度

方法 1：会话日志

# 列出正在运行的会话
clawdbot sessions_list

# 查看历史记录
clawdbot sessions_history <session_key>

方法 2：TuriX 日志

# 实时跟踪日志
tail -f your_dir/TuriX-CUA/.turix_tmp/logging.log

# 或者检查已完成的步骤文件
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：检查生成的文件

# 列出代理创建的文件
ls -la your_dir/TuriX-CUA/examples/.turix_tmp/*.txt

3. 日志文件参考

关键日志标记：
- 📍 步骤 N - 新步骤开始
- ✅ 评估：成功/失败 - 当前步骤评估
- 🎯 本步骤要实现的目标 - 当前目标
- 🛠️ 操作 - 已执行的操作
- ✅ 任务成功完成 - 任务完成

4. 常见监控问题

5. 强制停止

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

命令：

pkill -f "python examples/main.py"

6. 查看结果

完成后，代理将：
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 中的 analysis 和 next_goal
2. 检查执行者操作：查看 actor_llm_interactions.log_actor_*.txt 中的操作
3. 检查屏幕截图：TuriX 每步都会捕获屏幕截图（保存在内存中）
4. 读取记录文件：代理使用 record_info 将关键信息保存到 .txt 文件中

8. 示例监控流程

# 1. 运行任务
./run_turix.sh "搜索 AI 新闻并总结" &

# 2. 等待几秒并检查进程
sleep 10 && ps aux | grep main.py

# 3. 检查是否正在创建日志
ls -la your_dir/TuriX-CUA/examples/.turix_tmp/

# 4. 实时跟踪进度
tail -f your_dir/TuriX-CUA/.turix_tmp/logging.log

# 5. 检查当前步骤数
ls your_dir/TuriX-CUA/examples/.turix_tmp/brain_llm_interactions.log_brain_*.txt | wc -l