核心用法
TaskFlow 为 OpenClaw 代理提供了一套 Markdown-first 的项目/任务管理体系。核心设计原则是 Markdown 为信源（canonical），SQLite 仅为派生索引。用户或代理直接编辑 tasks/*.md 文件，通过 taskflow sync 或后台守护进程（60 秒周期）将变更同步至 SQLite 数据库。
主要功能模块
- 项目创建：通过
PROJECTS.md注册项目，生成tasks/<slug>-tasks.md（任务清单）与可选的plans/<slug>-plan.md（架构文档） - 任务管理：严格格式
- [ ] (task:<id>) [<priority>] [<owner>] <title>，支持 P0-P3/P9 优先级与代理标签 - 状态流转：通过移动任务行至不同章节（In Progress / Backlog / Blocked / Done 等）驱动状态变更
- 双向同步：
files-to-db（Markdown → SQLite）与db-to-files（SQLite → Markdown）两种方向 - 查询能力：直接读 Markdown 文件，或使用 Node.js
node:sqliteAPI 进行参数化 SQL 查询 - Apple Notes 集成（macOS）：将项目状态导出为富文本笔记，支持自动刷新
CLI 快速入口
taskflow setup # 交互式初始化向导 taskflow add <project> "..." --priority P1 --owner codex taskflow list <project> taskflow status
显著优点
1. 人机共用格式：Markdown 既是机器可读的数据层，也是人类可读的文档，避免"配置漂移"
2. 去中心化信源：不依赖外部 SaaS，数据完全本地可控，适合隐私敏感场景
3. 代理原生设计：任务 ID、优先级标签、所有者标记均为 AI 工作流优化
4. 安全默认：文档强制要求参数化 SQL、路径校验、环境变量隔离，降低注入与遍历风险
5. 可选后台同步：LaunchAgent（macOS）/ systemd timer（Linux）实现准实时同步，无需手动触发
潜在缺点与局限性
- v1 限制：Note 单向同步（Markdown → DB，删除不生效）、每项目仅支持单一任务文件、
db-to-files会重写全部文件 - Node.js 强依赖：要求 Node.js 22.5+，无 Python 降级方案
- 平台限制：Apple Notes 集成仅限 macOS；systemd 用户单元需登录会话或启用 lingering
- 学习成本：严格的标签顺序规则（优先级必须在所有者之前）、固定的五个章节标题，对格式错误容错低
- 无协作机制：本地 SQLite 与 Markdown 文件，天然不支持多用户并发编辑
适合人群
- AI 代理开发者：需要为 OpenClaw 或其他代理框架提供结构化任务追踪能力
- Markdown 原生用户：习惯以文本文件管理项目，排斥 Jira/Trello 等 Web 工具
- 隐私优先的开发者：不希望任务数据上传至第三方云服务
- macOS/Linux 终端用户：具备 shell 环境配置能力，能处理 LaunchAgent/systemd 单元
常规风险
| 风险类别 | 说明 | 缓解措施 |
|---------|------|---------|
| 路径遍历 | `OPENCLAW_WORKSPACE` 若被恶意注入，可能导致文件系统越权访问 | 严格从受控来源（shell profile、systemd 模板）设置；使用 `path.resolve()` 与前缀校验 |
| SQL 注入 | 查询时若将变量直接拼入 SQL 字符串，存在注入风险 | **强制使用** `db.prepare()` 与命名/位置参数，文档中明确禁止字符串插值 |
| 竞态条件 | 后台同步与手动编辑可能并发，存在 TOCTOU 风险 | 60 秒 TTL 锁机制；建议避免在同步周期内高频手动编辑 |
| 数据丢失 | `db-to-files` 会重写整个任务文件，若进程崩溃可能导致文件损坏 | 依赖文件系统/版本控制备份；该流程设计为幂等但非原子 |
| 配置泄露 | `taskflow.config.json` 包含 Apple Notes Core Data ID，虽非敏感但具用户标识性 | 建议纳入 `.gitignore` 或权限保护 |
安全等级判定依据
文档对 OPENCLAW_WORKSPACE 设置了明确的信任边界（Trust Boundary），强制要求路径存在性校验、绝对化解析、参数化 SQL 查询，并显式警告 TOCTOU 与路径遍历风险。虽未提供自动化安全扫描报告，但设计文档本身体现了 S 级 的安全意识与防御性编程实践。