bd-dxg/my-pi/todo-list

todo-list（个人待办清单）

管理用户的个人待办事项，数据持久化在 ~/.todo/todo.json（跨会话、跨项目）。支持多级父子嵌套（项目→子任务→子子任务）、父级自动汇总子任务进度、软删除回收站（可还原/彻底清空）。

关键：统一入口 ta#

用户会用 `ta#` 开头的自然语言发起 todolist 操作，例如：

• ta#加个任务：写周报
• ta#看看我有哪些没做完的
• ta#在 学习编程 下建个子任务 掌握基础语法
• ta#把第 2 条标记完成
• ta#删除第 3 条
• ta#看看回收站
• ta#还原第 2 条
• ta#清空回收站

只要消息以 ta# 开头（即使用户没明说"待办/todo"），一律进入本 skill：解析 ta# 后面的自然语言 → 确定意图和参数 → 调用脚本执行 → 把脚本的中文输出原样汇报给用户。非 ta# 开头的内容不要触发。

执行入口

脚本固定在 C:/Users/bddxg/.agents/skills/todo-list/scripts/todo.js（字符集 UTF-8。若移动了 skill，按当前 skill 目录下的 scripts/todo.js 找）。

统一调用方式（Windows 下用反斜杠分隔亦可）：

node <skill目录>/scripts/todo.js <命令> <参数>

务必调用脚本执行，不要用 `node -e` 临场改 JSON——所有逻辑（id 分配、父子汇总、软删除、原子写入）都已在脚本内实现，临场重写既慢又易错。

脚本执行后，把它 stdout 的中文结果直接读给/展示给用户即可（脚本已处理所有回显和提示，无需二次加工）。

脚本内置交互自足能力：node todo.js help（或 -h/无参数）可查看完整用法与示例；数据文件 ~/.todo/todo.json 不存在时，脚本会自动创建并在首次操作时输出提示。当解析的脚本命令遇到困惑时，可先跑 help 确认正确写法。

意图 → 命令映射

把 ta# 后的自然语言按上表解析成脚本命令。识别序号时，用户说的「第 N 条 / N 号 / #N」对应列表里显示的层级序号（如 4.1、4.2），脚本会自动解析为内部 id。若用户用标题/描述指代某条，先跑 list 找到对应层级序号再操作。

循环任务自动生成下一周期：标记完成一个循环任务时，脚本自动创建下一个周期副本，旧副本在 list 中隐藏。用 show 可查看历史副本。

批量创建子任务务必使用 `batch-add`：一条命令一次 load/save，避免并发冲突和顺序错乱。

示例：todo.js batch-add --parent 4 --title "子任务A" --title "子任务B" --title "子任务C" 会按参数顺序依次分配 id 并追加，保证顺序正确。

批量完成用 `batch-done`：todo.js batch-done 4.1 4.2 4.3 一次性完成多条。

所有操作命令均支持层级序号：done 4.1、del 4.10、show 4.5 等，无需查内部 id。

多条并列意图（ta#加一个打包上线，顺便看看今天的）可顺序执行多个脚本调用。

数据模型与规则

~/.todo/todo.json 结构（扁平数组 + parent_id 形成树，deleted 实现软删除）：

{ "next_id": 5, "items": [
  { "id": 1, "title": "学习编程", "done": false, "parent_id": null,
    "created_at": "...", "deleted": false, "priority": null, "due_date": null },
  { "id": 2, "title": "写日报", "done": false, "parent_id": null,
    "created_at": "...", "deleted": false, "priority": null, "due_date": "2026-03-18",
    "recurrence": { "type": "daily" },
    "recurrence_group_id": "rec_xx_xxxx" }
] }

需要遵循的约束（脚本已内置，但理解它们有助于正确引导用户、准确把自然语言映射到命令）：

• 优先级 `priority`：高 / 中 / 低 / null（未设置）。
• 截止 `due_date`：YYYY-MM-DD 或 null（未设置）。
• 循环 `recurrence`：{ type: "daily" } / { type: "weekly", day: 1-7 } / { type: "monthly", date: 1-31 } / null。
• 循环分组 `recurrence_group_id`：同一循环任务的不同实例共享此 id，用于关联和隐藏历史副本。
• 父级自动汇总：有子任务的条目不能手动 done/undo，其完成状态由「所有直接子任务是否完成」自动推出，list 会显示 子任务 x/y 与完成符号。想让父级"完成"，去完成它的子任务即可。
• 已完成条目默认隐藏：list 只展示未完成的条目（含部分完成的父级）；已完成的叶子及整棵已完成子树不显示，但序号位置保留（如 1.1 完成后仍从 1.2 开始显示），确保 done 1.2 等序号操作不受影响。全部完成时输出 🎉 全部完成！。
• 软删除：del 只是标记 deleted=true（连带其整个子树）；trash 看回收站，restore 还原（连带子树），empty-trash 才物理删除。
• 循环任务规则：
• 标记完成时自动生成下一周期副本（旧副本在 list 中隐藏，show 仍可查看）。
• 生成副本时复制标题、优先级、父级关系、循环配置。
• 未指定 --due 时，脚本自动计算第一个截止日期（每日→今天，每周→最近的目标日，每月→最近的目标日）。
• undo 一个循环任务时，如果同组已有更新的副本会被拒绝，提示用户操作新副本。
• id 自动分配、不复用；显示按创建顺序。

输出铁律（硬规则，违反 = 不合格）

1. 原样输出，绝不二次加工

脚本 stdout 的结果原样展示给用户，不得做任何重新排版、格式化、换表格、加表格、摘要、精简、美化。脚本已经精心设计了输出格式，不需要也不允许再加工。

禁止行为：

• ✗ 把 list 的文本输出改成 Markdown 表格
• ✗ 把脚本输出摘要成几句话
• ✗ 给输出加上额外的 emoji、分隔线、标题
• ✗ 对完成度做二次计算再展示

正确做法：脚本返回什么 → 用户看到什么，一字不差。

2. 简单操作零冗余

对于 list、trash、show 这类纯查询操作：

• 不要重新读取 SKILL.md——你已经在执行上下文里了，规则你已经知道
• 不要解析意图——看看/查看/列一下 就是 list，直接执行
• 不要多余步骤——一条 node todo.js list 直接跑，跑完原样展示，结束

查询类操作的目标耗时：脚本执行 + 原样回显 = 结束，不做任何其他事。

3. 速度优先

用户的待办数据就在那，脚本跑一下只要几百毫秒。任何不必要的额外工具调用（重读 skill、查文档、做分析）都是浪费时间。每次操作只调用一个脚本命令，不要做多个无关调用。

边界处理

• 用户省略优先级/截止日期 → 不传参数，保持留空，不要替用户假设默认值。
• 用户对一个有子任务的条目说"完成" → 按脚本提示，引导其完成子任务，父级自动更新。
• 对已删除条目再 del / 已还原条目再 restore → 脚本会给出友好报错，把报错原样汇报即可。
• 识别到的 id 不存在 → 先 list 让用户确认编号，避免误删。