核心用法
TaskFlow 是一套面向 AI Agent 和开发者的工作流管理系统，采用"Markdown 为源、SQLite 为索引"的架构设计。用户通过编辑 tasks/*.md 文件管理任务，系统自动同步至 SQLite 数据库供查询分析。
关键工作流：
1. 初始化：设置 OPENCLAW_WORKSPACE 环境变量，运行 taskflow setup 完成向导式配置
2. 项目管理：在 PROJECTS.md 中以二级标题块定义项目，创建 tasks/<slug>-tasks.md 跟踪任务
3. 任务追踪：使用固定格式的任务行 - [ ] (task:id) [P1] [owner] Title，通过移动至不同章节（In Progress/Backlog/Blocked/Done）更新状态
4. 双向同步：taskflow sync files-to-db 将 Markdown 变更写入数据库，db-to-files 反向同步
5. 查询分析：直接阅读 Markdown 或使用 SQL 查询 tasks_v2 表进行跨项目统计
6. Apple Notes：可选将项目状态推送至 macOS Apple Notes 实现移动端查看
显著优点：
- 人机协作友好：Markdown 格式使开发者和 AI 都能直接读写，无需专用客户端
- 版本控制天然适配：纯文本源文件可纳入 Git 管理，便于 diff 和回滚
- 查询性能：SQLite 索引支持复杂查询（按优先级、状态、项目聚合），弥补 Markdown 结构化查询的不足
- Agent 集成：标准化输出格式便于 LLM 解析上下文，减少幻觉
- 轻量部署：单 Node.js 脚本集合，无需复杂服务端
潜在局限：
- 平台限制：Apple Notes 导出仅限 macOS；LaunchAgent 守护进程暂无 Linux/systemd 支持
- 单文件约束：每个项目仅限一个任务文件，大型项目可能文件臃肿
- Notes 单向性：注释行仅支持 Markdown→DB 单向同步，删除注释需直接操作数据库
- ID 格式敏感：任务 ID 必须零填充三位（
-001），否则MAX(id)查询会出现字典序错误 - 标签顺序严格：优先级标签必须位于所有者标签之前，顺序错误导致解析失败
- Node 版本锁定：依赖
node:sqlite（Node 22.5+），无 Python 降级方案
适合人群：
- 使用 OpenClaw 或其他 AI Agent 框架的开发者
- 偏好 Markdown 而非传统看板工具（Trello/Notion）的工程师
- 需要版本控制任务历史的技术团队
- 寻求轻量级项目管理的独立开发者
常规风险：
- 数据一致性：双向同步存在冲突可能，虽采用"最后写入胜出"策略，但并发编辑仍需人工校验
- 锁定机制 TTL 60 秒：异常终止（如
kill -9）会导致最长一分钟的同步阻塞 - Apple Notes 依赖 Core Data ID：误删共享笔记将破坏链接，需重新生成配置
- 配置漂移：环境变量
OPENCLAW_WORKSPACE未设置时回退至process.cwd()，极易导致数据误放