todolisted

# Todo Todo 是自然语言适配层。任务数据保存在 `.agent-tasks/tasks/*.md`，确定性读写全部交给本 Skill 自带的 Node CLI。 ## 第一性原则：状态服务于用户的时间主权 Todo 的目标不是让任务机械地穿过一组状态，而是帮助用户从持续盯守、重复确认和不可预期的等待中释放出来，同时保留对成本、进度和启动时机的掌控。 执行任何状态变更前，先以终为始地确认： 1. 用户最终想获得的结果和工作状态是什么，而不只是当前说出的流程动作。 2. 当前状态能为用户减少什么负担，提供什么新的确定性。 3. 接下来是否存在昂贵的时间、注意力、额度或外部副作用；用户是否已经看见并接受。 4. 是否存在更便宜、更快、同样能推进最终目标的路径。 5. 当前动作是在推进用户的终局，还是只是在完成 Skill 自己的流程。 决策优先级固定为： ```text 用户终局 → 时间与注意力 → 成本与风险透明 → 用户掌控点 → 最小流程 → 工具 ``` 流程、状态和工具都只是手段。一旦它们与用户希望“减少等待、释放注意力、把控整体进度”的核心诉求冲突，必须调整手段，不能以“已经严格执行流程”为完成依据。 ## 硬约束 1. **禁止直接编辑任务文件、YAML、`index.md` 或归档目录。** 2. 新增、修改、查询、移动、归档和正文更新都必须调用 CLI。 3. 未明确指定范围时始终使用全局 `~/.agent-tasks/`，即使当前位于 Git 仓库。 4. 只有用户明确说“当前项目”或提供项目路径时才使用项目级目录。 5. 用户只要求记录、查看或修改任务时，不得执行任务本身。 6. `list` 只查询，不调研、不实现、不创建额外上下文文件。 7. `index.md` 是生成视图，`tasks/*.md` 是唯一数据源。 ## CLI 调用 Skill 内调用： ```bash node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" <command> [options] ``` 如果宿主没有注入 `CLAUDE_SKILL_DIR`，使用当前 `SKILL.md` 所在目录的绝对路径。不要假设系统已经存在全局 `todo` 命令。 人工安装全局命令、依赖检查和 Web 启动方法见 [`references/setup-guide.md`](references/setup-guide.md)。 ## 作用域 | 用户表达 | CLI 参数 | 存储位置 | |---|---|---| | “添加待办”“全局待办”或未说明 | 无 | `~/.agent-tasks/` | | “当前项目待办” | `--current-project` | `{当前 git-root}/.agent-tasks/` | | “某项目待办”并提供路径 | `--project <path>` | `{指定 git-root}/.agent-tasks/` | 明确项目无法解析时报告错误，不静默写入全局。 ## 意图映射 ### 新增任务 ```bash node "${CLAUDE_SKILL_DIR}/bin/todo.mjs" add "<标题>" \ --status idea \ --json ``` 添加当前项目任务时追加 `--current-project`。添加指定项目任务时追加 `--project <git-root>`。 创建后向用户