核心用法
TaskFlow 是一套为 OpenClaw 智能体设计的项目管理技能，采用Markdown 优先的架构原则：所有任务以纯文本 Markdown 文件存储于 tasks/<slug>-tasks.md，SQLite 数据库仅作为派生索引用于高效查询，而非数据源。系统支持双向同步（files-to-db 和 db-to-files），并可通过 CLI 工具 taskflow 进行交互管理。
关键工作流程：
- 项目创建：在
PROJECTS.md中添加项目块，创建对应的任务文件（含五个固定章节：In Progress、Pending Validation、Backlog、Blocked、Done） - 任务管理：遵循严格的行格式
- [ ] (task:<id>) [<priority>] [<owner>] <title>，通过移动任务行到不同章节来更新状态 - 查询方式：可直接阅读 Markdown 文件，或使用 SQLite 进行复杂跨项目查询
- Apple Notes 集成（macOS 限定）：将项目状态导出为富文本笔记，支持自动刷新
显著优点
1. 人机双友好：Markdown 作为通用格式，人类可直接阅读和编辑，智能体也能高效解析
2. Git 原生友好：纯文本存储天然支持版本控制，变更可追溯、可 diff
3. 轻量高效：SQLite 索引提供毫秒级查询，同时保留文本的便携性
4. 智能体工作流深度集成：明确区分人类验证环节（Pending Validation）、支持智能体标签（[codex]/[sonnet] 等）
5. 状态机清晰：五个章节对应明确的生命周期，避免任务状态混乱
6. 可选后台同步：macOS LaunchAgent 支持 60 秒自动同步
潜在缺点与局限性
1. 平台限制：Apple Notes 集成为 macOS 独占功能；Linux 后台同步为"post-MVP"优先级
2. Node.js 依赖：要求 22.5+ 版本，依赖 node:sqlite 原生模块，无 Python 降级方案
3. 严格的格式约束：任务行格式要求极高——标签顺序错误（[codex] [P1] vs [P1] [codex]）会导致静默解析失败
4. 单向笔记同步：- note: 行仅支持 Markdown → DB 单向写入，删除或修改不会回传
5. 单文件限制：每个项目仅支持一个任务文件，多文件支持为后期功能
6. 手动 ID 管理：需手动扫描或查询确定下一个任务 ID，存在冲突风险
7. 锁机制脆弱性：60 秒 TTL 锁若遇 kill -9 崩溃，可能阻塞后续同步
适合人群
- OpenClaw / AI 智能体开发者：需要结构化、可查询的任务系统来协调长期项目
- 偏好 Markdown 的技术用户：厌倦传统 GUI 项目管理工具的键盘重度用户
- macOS 生态深度用户：希望任务状态同步到 Apple Notes 跨设备查看
- 小型团队或个人开发者：项目规模适中，无需 Jira/Linear 等重型工具
常规风险
| 风险类别 | 说明 |
|---------|------|
| **数据一致性** | 双向同步存在"最后写入获胜"冲突策略，并发编辑 Markdown 和 DB 可能导致状态丢失 |
| **格式损坏** | 手动编辑时偏离严格格式（尤其是标签顺序、ID 零填充）会导致同步静默失败或数据错乱 |
| **Apple Notes 依赖** | 共享笔记的 Core Data ID 存储于本地 config，误删笔记会破坏同步链路（虽可重建但丢失分享链接） |
| **环境变量依赖** | `OPENCLAW_WORKSPACE` 未设置时回退到 `process.cwd()`，几乎必然导致路径混乱 |
| **单点故障** | SQLite 作为索引若损坏，需从 Markdown 重建；虽可恢复但耗时 |
安全评估：系统为本地优先架构，无网络传输组件，无敏感数据加密需求，主要风险在于本地文件操作和 AppleScript 执行（macOS Notes 集成）。建议对 OPENCLAW_WORKSPACE 目录进行常规备份。