用途
dex 是一个命令行任务管理工具，用于协调智能体或开发者处理复杂工作。它适合把大型工作拆解为子任务、跨多个会话跟踪实现项、在交接时持久化上下文，以及记录决策供后续参考。当工作只是单个原子操作、能在一次会话内完成且无需后续跟进时，可以不使用 dex。
主要能力
dex 的任务是“工单”，而非简单待办。每个任务包含：
- 名称：一行摘要（类似 issue 标题）
- 描述：完整背景、需求与实现方式（类似 issue 正文）
- 结果：实现细节、决策与产出（类似 PR 描述）
任务支持三层结构：史诗（大型计划）→ 任务（重要工作）→ 子任务（原子步骤）。任务数据以文件形式保存在 .dex/ 目录中，因此可跨会话持久存在。
dex 与部分 AI 智能体内置的任务工具不同：内置工具仅限当前会话、上下文较基础、结构扁平；dex 则持久化、上下文更丰富、支持层级。持久性工作应使用 dex，会话内的临时跟踪可使用内置任务工具。
使用方式
所有命令直接使用 dex。如果 dex 不在 PATH 中，改用 npx @zeeg/dex：
command -v dex &>/dev/null && echo "use: dex" || echo "use: npx @zeeg/dex"
创建任务：
dex create "Short name" --description "Full implementation context"
描述应包含：需要做什么、为什么、实现方式、验收标准。
列出与查看任务：
dex list # Pending tasks
dex list --ready # Unblocked tasks
dex show <id> # Full details
完成任务：
dex complete <id> --result "What was accomplished" --commit <sha>
与 GitHub/Shortcut 关联的任务需要提供 --commit <sha> 或 --no-commit：有代码变更时用 --commit <sha>（合并后关闭 issue）；非代码任务（如规划、设计）用 --no-commit（issue 保持打开）。完成前必须验证，结果需包含证据，例如测试数量、构建状态、手动测试结果。
编辑与删除：
dex edit <id> --description "Updated description"
dex delete <id>
创建子任务：
dex create --parent <id> "Subtask name" --description "..."
任务字段与上下文
任务有两个文本字段：名称（一行摘要，显示在 dex list 中）和描述（完整细节，使用 --full 显示）。运行 dex show <id> 时描述可能被截断，CLI 会提示使用 --full 查看完整内容。
接手任务时应收集相关上下文：
dex show <id> --full # Full task details
dex show <parent-id> --full # Parent context (if applicable)
dex show <blocker-id> --full # What blockers accomplished
开始前应能回答：具体要做什么、为什么需要、如何实现、何时算完成（验收标准）。若答案不清晰，可查看父任务或已完成的阻塞任务，或建议进入计划模式先明确需求。任务为琐碎原子操作、对话已提供缺失上下文、或描述本身足够详细时，可直接进行。
层级选择
- 小型功能（1-2 个文件）→ 单个任务
- 中型功能（3-7 个步骤）→ 任务加子任务
- 大型计划（5 个以上任务）→ 史诗加任务
结果记录与提交信息
实现并验证后应立即完成任务，趁记忆新鲜记录决策、偏离计划之处、已执行的验证，并为技术债创建后续任务。结果必须包含明确的验证证据，而不只是描述做了什么。
当任务关联 GitHub issue 时（在 dex show 输出中显示），提交信息应包含 issue 引用：根任务（任务本身有 GitHub 元数据）使用 Fixes #N，合并后关闭 issue；子任务（父级或祖先有 GitHub 元数据）使用 Refs #N，仅关联而不关闭。提交前查看 dex show <id> 确认 GitHub issue 信息，出现“(via parent)”表示使用 Refs，直接元数据表示使用 Fixes。
最佳实践
- 任务规模适中：能在一次专注会话内完成
- 完成标准清晰：描述应定义“完成”
- 不要过度拆解：每个父任务 3-7 个子项
- 描述以动词开头：如 Add、Fix、Update
- 完成前验证：测试通过、手动测试完成
限制与注意事项
dex 任务 ID 是临时的，不应在外部产物（提交、PR、文档）中引用 dex 任务 ID，因为任务完成后 ID 如 abc123 会失去意义；应描述工作本身，而非跟踪它的任务。
附加资源
资料中提到的附加文档包括：cli-reference.md（完整 CLI 文档）、examples.md（好/坏上下文与结果示例）、verification.md（验证清单与流程）、hierarchies.md（史诗/任务/子任务组织）。这些文件的具体内容暂未提供。