核心用法
TaskFlow 为 OpenClaw 智能体提供结构化的项目/任务/计划管理能力，采用 Markdown 作为唯一数据源，SQLite 仅作为派生索引。核心工作流包括：
1. Markdown 优先编辑：直接在 tasks/<slug>-tasks.md 中增删改任务，通过五个固定章节（In Progress / Pending Validation / Backlog / Blocked / Done）管理状态
2. 双向同步引擎：task-sync.mjs 支持 files-to-db（Markdown→SQLite）和 db-to-files（反向）两种同步模式，每 60 秒后台自动同步
3. CLI 工具链：taskflow setup 初始化向导、taskflow add 快速创建任务、taskflow status 状态总览、taskflow notes 推送至 Apple Notes
4. Apple Notes 集成（macOS 专属）：将项目状态渲染为富 HTML 笔记，支持自动更新与共享链接
任务格式规范
- [ ] (task:myproject-007) [P1] [codex] 实现 OAuth 登录 - note: 等待 API 密钥
关键规则：优先级标签 [P0-P3/P9] 必须位于所有者标签 [codex/sonnet] 之前；任务 ID 采用 <slug>-NNN 零填充格式。
显著优点
- 人机双模式：CLI 向导面向人类用户，结构化 API 面向智能体自动化
- 安全设计：强制参数化 SQL（
db.prepare）、路径遍历防护（safeJoin）、OPENCLAW_WORKSPACE信任边界隔离 - 原生生态集成：macOS LaunchAgent / Linux systemd timer 守护进程、Apple Notes 原生体验
- 版本友好：纯文本 Markdown 天然支持 Git 版本控制与 diff 审阅
潜在缺点与局限性
- v1 限制：笔记单向同步（Markdown→DB，删除不生效）、每项目单文件限制、
db-to-files全量重写 - 平台依赖：Apple Notes 功能仅限 macOS；
node:sqlite要求 Node.js 22.5+ - 学习成本：严格的标签顺序规则、固定章节标题、零填充 ID 等规范需适应
- 无协作冲突解决：多代理并发编辑 Markdown 可能产生合并冲突，依赖外部版本控制
适合人群
- 需要结构化任务追踪的 AI 智能体开发者与运维人员
- 偏好 Markdown 原生体验、排斥 SaaS 看板的技术团队
- macOS 用户寻求与 Apple Notes 深度集成的本地化方案
- 需要离线优先、数据自主可控的项目管理场景
常规风险
| 风险类别 | 说明 |
|---------|------|
| 路径遍历 | `OPENCLAW_WORKSPACE` 若被污染，可能导致敏感文件读写；需严格验证路径前缀 |
| SQL 注入 | 虽有参数化查询规范，但 `sqlite3` CLI 示例若被误用于动态变量仍存在风险 |
| 任务 ID 冲突 | 手动编辑时零填充错误（`-1` vs `-001`）导致排序异常与 ID 重复 |
| 同步竞态 | 60 秒同步周期内 Markdown 与 DB 状态不一致；守护进程崩溃可能导致 60 秒锁残留 |
| Apple Notes 误删 | 共享笔记被删除后 Core Data ID 失效，需重建配置；`taskflow notes` 会自动恢复 |
| 标题注入 | 未过滤的用户输入若包含 `#` 或章节标题关键字，可能破坏 Markdown 结构 |
总体而言，TaskFlow 是一款设计严谨、安全优先的本地化任务管理方案，适合技术团队与 AI 工作流，但需严格遵守其格式规范与安全实践。