valkryhx Dex Skill 使用指南
Dex 是一个专门用于处理长耗时异步任务的任务管理系统。它将“思考”（Agent）与“执行”（后台进程）解耦。
核心原则：何时使用 Dex？
- ⚡ 由于网络延迟或计算量大，预计耗时 > 10 秒的操作 -> 使用 Dex
- 📡 需要在 Agent 思考循环之外持续运行的服务 -> 使用 Dex
- 💻 简单的文件操作、系统信息查询、快速的 CLI 命令 -> 使用 bash
核心定位
Dex 不再只是“长命令后台执行器”，而是 Kairos 的异步任务引擎。
当任务需要被后台持续观察、需要跨轮次检查结果、需要被 Kairos handoff/attach/汇报时，必须使用 Dex。
任务完成标准
- 任务必须有明确的结构化状态：
pending/running/completed/failed/canceled - 任务必须暴露结构化结果摘要与错误摘要
- 任务必须提供日志 artifact 路径
- 任务必须能被 Kairos 通过 bridge 稳定读取
工具详解
Dex 提供了一组原生 Python 工具，Agent 可以直接调用：
1. dex_create_task
创建一个新的任务记录。
description: 任务简述 (e.g. "Fine-tune model v2")context: 详细参数或目标
2. dex_start_task
关键步骤。启动一个后台进程来执行具体命令。
task_id:dex_create_task返回的 IDcommand: 完整的命令行字符串 (e.g. "python scripts/train.py --epochs 100")- 注意：命令会在后台异步执行，Agent 会立即获得 "Task started" 的响应，而不会被阻塞。
3. dex_list_tasks & dex_get_task_details
查询任务状态。
- 定期调用
dex_list_tasks查看任务是否从running变为completed。 - 任务完成后，调用
dex_get_task_details查看result字段中的日志摘要。
典型工作流 (Workflow)
场景：用户要求开始一个耗时的训练任务。
创建任务
task_info = dex_create_task(description="Training Llama3", context="Epochs: 50, Data: data.csv") # Returns: {"id": "a1b2c3d4", ...}启动进程
dex_start_task(task_id="a1b2c3d4", command="python train_model.py --data data.csv") # Returns: [OK] Task started in background...Agent 继续其他工作... (或者每隔几轮对话检查一次)
检查状态
tasks = dex_list_tasks() # Returns: [{"id": "a1b2c3d4", "status": "completed", "result": "..."}]查看结果
details = dex_get_task_details("a1b2c3d4") # 分析 details['result'] 中的日志，回报给用户。
注意事项
- 所有输出都会被重定向到
.dex/logs/{id}.log。 - 如果是 Windows 环境，后台进程是一个独立的进程；Linux 下是 nohup 进程。
- 如果任务失败，
status会变成completed，但在result中会包含 "FAILED" 字样和错误码。