todo-archive

TODO 归档

如果斜杠命令或美元符号调用已将这些说明添加到对话中，请直接遵循。此时，不要再通过技能工具调用此技能。

参数

• path（可选）：仓库根目录或仓库内的任意路径。默认为当前目录。
• --hint TEXT（可选）：仅归档标题包含 TEXT（不区分大小写的子字符串）的章节及其子章节。未提供时，归档整个文件中已勾选的任务。匹配章节以外的已勾选任务会保留在 .ai/TODO.md 中。
• --date YYYY-MM-DD|YYYY_MM_DD（可选）：归档日期。默认为今天的本地日期。
• --dry-run（可选）：预览目标路径和呈现内容，但不写入。

工作流

1. 解析提供的 path；若未提供，则使用当前目录。若路径指向现有文件，则使用其所在目录；若指向目录，则使用该目录。将绝对目录存储为 start_dir，然后解析其 Git 根目录：

   git -C "$start_dir" rev-parse --show-toplevel
   

   将结果存储为 repo_root。当 start_dir 不在 Git 仓库中时，将其用作 repo_root。若输入路径不存在或发生其他解析错误，则停止。

2. 确认根目录下存在 .ai/TODO.md。若不存在，则停止并报告检查过的路径。

3. 解析技能目录并运行其辅助脚本：

   uv run python "<skill-dir>/scripts/archive_todo.py" --root "$repo_root"
   

   若用户指定了 --hint、--date 或 --dry-run，则传递相应参数。

4. 报告已重写的 .ai/TODO.md、新建或合并的归档路径、匹配的章节（指定了 --hint 时），以及已归档/剩余任务数。若该日期的归档文件已存在，辅助脚本会将新批次追加到其中，并保留一个匹配的顶级标题。若辅助脚本报告没有已勾选的任务，则视为无操作。若 --hint 未匹配任何标题，辅助脚本会以非零状态退出并列出可用章节。此时请转达这些章节。

5. 如有必要，仅检查 <repo_root>/.ai/TODO.md 和辅助脚本返回的确切归档路径。若 Git 忽略了这些文件，请比较文件系统快照，而不要依赖 git diff。

辅助脚本行为

scripts/archive_todo.py 会读取 <root>/.ai/TODO.md 及该日期已有的归档文件，将已归档任务写入 <root>/.ai/todos/YYYY-MM/DD.md，并以剩余任务重写 <root>/.ai/TODO.md。它会原样保留没有任务的章节和说明（仅当所有任务都已归档时，才会保留一个最简占位内容：源文件的首个标题，或 # TODO）。使用 --hint 时，只会在匹配标题的子树中归档；若没有匹配项，则会以非零状态退出并列出可用标题。同一天重新运行时，会将新批次追加到当天的文件；仅当新内容开头的 H1 与现有归档的开头 H1 完全一致时，才会移除这个 H1。

完成

完成凭据为辅助脚本返回的归档路径及已归档和剩余任务数。没有已勾选任务时，结果为成功的无操作。试运行完成时，需提供呈现后的路径/内容且不产生文件系统更改；但最终消息仍须采用以下单行格式。报告结果时，归档路径须相对于仓库根目录（仅当指定了 --hint 时，才追加 (scope: "<hint>")）：

• 成功：📦 Archived <n> → <archive path> (created|merged) · <remaining> remaining
• 无操作：✅ Nothing to archive · <remaining> remaining
• 试运行：🔎 Would archive <n> → <archive path> (would create|would merge) · <remaining> would remain

不要在最终消息中重复完整的试运行文档内容，也不要在 TODO/归档文件、路径、命令或辅助脚本诊断信息中添加修饰内容。