核心用法
Task Runner 是一个类守护进程风格的持久化任务队列系统，采用「INTAKE + DISPATCHER」双模式架构：
- INTAKE 模式：用户通过自然语言添加任务（如「帮我分析这三份报告」），系统自动解析、拆分为独立任务项（T-01、T-02…），写入
task-queue.json队列文件并确认，绝不内联执行。 - DISPATCHER 模式：由心跳（heartbeat）或每 15 分钟的 cron 任务触发，读取队列、检查运行中任务状态、调度新任务至并发上限（默认 2 个），并在任务完成或阻塞时向用户推送通知。
任务执行通过子代理（subagent）完成，支持重试（默认 3 次）、自动归档（7 天后）、跳过/取消/重试等控制命令。首次使用自动初始化目录、队列文件、心跳注册与备份 cron，无需手动配置。
显著优点
1. 真正的异步持久化：任务累积在磁盘，会话中断不丢失，适合跨会话、跨天的长期项目。
2. 零配置开箱即用：首次触发自动完成目录、文件、心跳、cron 的全套注册。
3. 弹性调度：心跳 + 双保险 cron 确保任务即使在高负载或心跳延迟时仍能被调度。
4. 细粒度可控：支持单任务重试、跳过、标记完成，以及全局并发与重试策略配置。
5. 结构化追踪：每个任务独立 ID、状态可追溯，输出格式统一（状态表、完成通知、阻塞说明）。
潜在缺点与局限性
1. 单文件队列瓶颈：所有任务存储于单一 JSON 文件，高频率写入或海量任务（数百+）时存在 I/O 竞争与性能衰减风险，无内置分片或数据库后端。
2. 无原生依赖管理：任务间依赖需手动标注 blocked_reason，不会自动按 DAG 拓扑排序执行。
3. 子代理隔离但非沙箱：任务执行依赖子代理能力，复杂任务仍可能因环境、权限或工具缺失而阻塞。
4. 调试链路较长：任务失败需跨「主代理 → 子代理 → 队列文件 → 用户通知」多环节排查，异步特性增加了实时调试成本。
5. 归档策略固定：仅按天数归档，不支持按项目、标签或优先级分层归档。
适合人群
- 需要批量提交任务、稍后统一查看结果的知识工作者（研究员、分析师、内容运营）。
- 执行耗时操作（数据抓取、文档生成、多轮分析）且不希望阻塞当前会话的用户。
- 希望建立「任务收件箱」、逐步清空的 GTD 风格工作流用户。
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 队列文件损坏 | 异常断电或并发写导致 JSON 损坏 | 系统内置原子写（先写临时文件再重命名），但极端情况仍需用户备份 |
| 无限重试循环 | 任务因环境缺陷永远失败 | 默认 3 次重试上限，达到后标记 blocked 并通知 |
| 僵尸任务 | 子代理会话 ID 丢失，任务僵死 | Dispatcher 每次心跳检查会话状态，异常任务自动重置为 pending |
| 存储膨胀 | 长期运行后队列文件累积 | 自动归档机制清理 7 天以上终态任务 |
| 权限泄露 | 任务交付物写入默认目录 | 目录权限遵循系统 umask，敏感任务建议显式配置 `TASK_RUNNER_DIR` |
使用建议
- 定期（如每周）查看
archive/目录大小，必要时手动清理旧归档。 - 复杂项目建议任务描述中显式标注依赖关系（如「等待 T-05 完成后执行」），便于人工追踪。
- 高优先级任务可通过「先取消再重新添加」间接实现插队，未来版本可关注原生优先级字段。