todolist-md-clawdbot

核心用法

todolist-md-clawdbot 是一套专为 Markdown 待办文件设计的自动化管理技能，采用两阶段工作流（prepare/apply）实现低成本、高效率的任务处理。该技能操作 todolist-md 格式的 Markdown 文件（使用 GFM 复选框 - [ ] 语法），通过特定的 <!-- bot: ... --> HTML 注释标记与文件进行交互，确保人工与 AI 协作的边界清晰。

在 Prepare 阶段，脚本会扫描指定存储后端（Google Drive、本地文件夹或 S3）中的 .md 文件，通过对比 modifiedTime 或文件大小检测变更，仅下载有变动的文件并提取未完成任务（- [ ]），生成紧凑的 JSON 请求文件供 LLM 处理，避免不必要的 API 调用。在 Apply 阶段，脚本将 LLM 生成的建议通过 Drive API 的 files.update 方法原地写回同一文件（保持 fileId 不变），并采用 headRevisionId 修订门控机制防止覆盖用户正在 Chrome 应用中编辑的内容。

技能支持多种存储后端，其中 Google Drive 集成最为完善，提供专用的 Node.js 脚本实现完整的文件夹遍历、变更检测、OAuth 认证管理和原子写入功能。

显著优点

1. 极简 Token 设计：通过代码优先的变更检测机制，只有在文件实际变更时才调用 LLM，且仅传递提取后的未完成任务而非完整文档，大幅降低 API 成本。
2. 行稳定写入：严格遵守行位置不变原则，所有 bot 生成的内容通过单行编辑或特定区块（如 ## Tasks (bot-suggested)）追加，不破坏任务 ID（基于行位置）的稳定性。
3. 身份保留机制：使用 Drive API 的原地更新（overwrite-update）而非删除重建，确保文件的 fileId 等稳定身份标识不变，维护共享链接和历史版本完整性。
4. 并发安全：通过 headRevisionId 检查实现乐观锁，检测到文件在审阅期间被修改时中止写入，防止编辑冲突。
5. 灵活的配置机制：支持通过 .todolist-md.config.json 配置文件或文件内标记 <!-- bot: ai_enabled --> 控制 AI 审阅范围，适应多文件场景下的精细化管理需求。

潜在缺点或局限性

1. 来源可信度限制：该项目由个人开发者（nitsujy）维护，属于 T3 级社区来源，GitHub Stars 数较少，长期维护稳定性和社区支持相对有限。
2. 外部工具依赖：Google Drive 功能依赖 gog CLI 工具，需要单独安装并配置，增加了部署复杂度；且脚本使用 sudo 执行外部命令，在某些受限环境中可能遇到权限问题。
3. 格式限制：仅支持特定结构的 Markdown 待办格式（todolist-md 规范），对于其他 Todo 管理工具（如 Todoist、Notion）的格式不兼容，迁移成本较高。
4. OAuth 配置门槛：首次使用需要完成 Google OAuth 授权流程，对非技术用户有一定门槛，且 Token 存储在本地文件系统，需要确保运行环境的安全。

适合的目标群体

• todolist-md Chrome 应用用户：已与该应用配合使用，需要 AI 辅助审阅和更新 Drive 上待办文件的用户。
• 成本敏感型团队：需要管理大量 Markdown 文档但希望严格控制 LLM API 调用成本的项目组。
• 技术型个人用户：熟悉 Node.js 和命令行操作，具备 Google Cloud 平台基础配置能力，寻求自动化任务管理方案的开发者或产品经理。
• 文档驱动型工作流：习惯使用 Markdown 作为单一事实来源（Single Source of Truth），希望通过 Git 风格的变更追踪管理任务状态的专业人士。

使用风险

• 并发编辑冲突：尽管实现了修订门控，但在高频协作场景下仍可能出现"检查-写入"时间窗口内的冲突，导致本次审阅结果无法写入。
• 外部命令执行：脚本使用 execFileSync 调用 gog CLI，虽然参数经过硬编码处理，但若 gog 工具本身被篡改或替换，存在命令注入风险。
• OAuth 权限管理：需要授予对 Google Drive 的完全读写权限（https://www.googleapis.com/auth/drive），若运行环境被入侵，攻击者可能获取 Token 并访问用户的云端文件。
• 存储后端差异：目前对 Google Drive 支持最完善，S3 和本地文件夹的功能相对基础，且需要用户自行配置稳定身份键（如 S3 的 bucket+key）的逻辑映射。