核心用法
todolist-md-clawdbot 是一套面向 Markdown-first 任务管理的工作流协议，而非传统意义上的 AI 工具。它通过标准化的 <!-- bot: ... --> 注释标记，让外部 AI 助手能够读取、分析并建议修改 Markdown 格式的待办清单，同时将最终决定权保留给用户。
关键操作原则：
- Markdown 即真相源：所有决策必须落笔为 Markdown 文件中的实际修改
- 严格行稳定性：编辑时禁止增删任务项或描述区块内的行，仅允许单行原位替换
- 身份保护：不得通过"替换文件"方式改变 Drive fileId、本地 path 或 S3 bucket+key 等稳定标识键
- 显式确认原则：绝不在未经用户明确许可的情况下将任务标记为完成
两阶段最小化 Token 工作流：
1. Prepare 阶段：代码驱动检测文件变更（对比 modifiedTime/size/etag），仅下载变更的 .md，提取开放任务（- [ ]），生成紧凑的 LLM 请求 JSON
2. Apply 阶段：接收 LLM 建议，仅在专用区域（## Tasks (bot-suggested)）写回，使用 Drive API files.update 按 fileId 覆盖，配合 revision gate 防止冲突
支持的 bot 标记类型：
<!-- bot: suggested -->— AI 建议的任务区块<!-- bot: question -->— 任务详情区的澄清问答<!-- bot: digest -->— 任务摘要<!-- bot: note -->— 审计备注<!-- bot: last_review -->— 顶部时间戳（Option B 模式，永不新增行）
显著优点
1. 存储无关的通用协议：支持 Google Drive、本地文件夹、S3 等多种后端，通过统一注释语法解耦
2. 成本极低的变更感知：代码层对比元数据即可跳过未变更文件，避免不必要的 LLM 调用
3. 人机协作的清晰边界：AI 只能写入专用建议区域，用户拥有完全的采纳/拒绝/修改权
4. Git-friendly 的 diff 体验：行稳定编辑策略确保版本控制中的变更可读性
5. 配套完整的自动化脚本：提供 Node.js 脚本（todolist_drive_folder_agent.mjs）实现 Drive 文件夹的完整扫描-检测-请求生成-写回闭环
潜在局限
- 学习曲线：用户需掌握 GFM 任务语法（
- [ ]）及 bot 标记规范 - Chrome 扩展依赖：完整的 per-file 启用/禁用控制需要配套浏览器扩展写入
.todolist-md.config.json - OAuth 配置门槛：Google Drive 集成需要手动完成授权流程（Managed OAuth 模式）
- 并发编辑风险：虽可通过 revision gate 缓解，但无法完全消除与 Chrome 扩展的同时编辑冲突
- 非实时协作：基于轮询的变更检测机制，不适合需要毫秒级同步的场景
适合人群
- 偏好 Markdown 作为知识/任务载体的开发者、技术写作者
- 需要低成本维护大量待办文件的个人或小团队
- 希望引入 AI 辅助但保持数据主权（Drive/本地/S3）的用户
- 已使用或愿意配合 todolist-md Chrome 扩展的现有用户
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 数据丢失 | 覆盖写回可能意外丢失并行编辑 | revision gate + 建议先在副本测试 |
| 身份漂移 | 误操作导致 fileId/path 变更 | 脚本强制使用 `files.update` 而非重新创建 |
| Token 泄露 | 脚本中的 refresh token 文件权限设置不当 | 遵循最小权限原则（`/tmp` 替代 `/root`） |
| 幻觉建议 | LLM 生成不合理的任务拆分 | 专用建议区域 + 强制人工审核 |
| 配置扩散 | 多个 `.md` 文件的配置状态不一致 | 优先使用集中的 `.todolist-md.config.json` |