任务管理(task)
任务区的日常操作:看板、归档、校验、归一、统计与导入导出。
常用命令
toolkit task # 待完成总览(默认)
toolkit task --view archived # 仅已归档
toolkit task --view all # 待完成 + 已归档(状态分组,来源可辨)
toolkit task archive # 归档已完成任务
toolkit task archive --task 20261112-唐启云-示例任务 # 只归档指定任务(唯一键)
toolkit task archive --dry-run # 归档预演(只预览,不落盘)
toolkit task check # 校验 active 与变更集写法
toolkit task normalize # 检查归档块(默认只读)
toolkit task normalize --fix # 修复归档问题
toolkit task stats # 周期统计:完成周期 / 滞留 / 吞吐
toolkit task stats --format json # 统计结果 JSON 输出
toolkit task export 报表.xlsx # 导出任务(按扩展名识别 csv / xlsx / json)
toolkit task import 需求清单.csv --dry-run # 导入预演
toolkit task add --title "命令分组" --scope cli --yes # 新建任务档(TTY 无参进入交互;非 TTY 须 --yes)
toolkit task update 命令分组 --status 进行中 --yes # 改状态 / 字段;终态须同时给 --completed
toolkit task --dir <path> # 指定任务目录(CLI 参数 > 配置 task.dir > 默认 .tasks)
toolkit task check --strict # 任务目录不存在时报错退出(默认容错为空结果)任务域选项
| 选项 | 说明 |
|---|---|
--dir <path> | 任务目录(优先级:CLI 参数 > 配置 task.dir > 默认 .tasks) |
--redact / --no-redact | 开启/关闭隐私脱敏(默认开启) |
--warn / --no-warn | 开启/关闭软告警(默认开启;作用于 check 的 warn 输出、归档时的变更集提醒) |
--strict | 任务目录不存在时报错退出(默认容错为空结果) |
子命令
| 子命令 | 一句话 |
|---|---|
list | 待完成看板(等价于裸 task;隐式子命令,帮助中不展示) |
add | 按模板新建任务档;TTY 无参进入交互,非 TTY 须 --title 与 --yes |
update <key> | 改状态 / 负责人 / 范围 / 依赖;终态须提供 --completed,非终态自动清空 |
archive | 把终结态任务按完成日期聚合归档;--task 只归档指定任务,--dry-run 预演 |
check | 校验 active 任务、规范载体、入口壳、变更集与文件卫生(只报不改) |
normalize | 检查并修复归档块;--fix 修复,--check 显式声明只读 |
stats | 周期统计(人用视图,不落盘) |
export <path> | 导出到文件(按扩展名识别 csv / xlsx / json) |
import <file> | 从文件导入任务;--target 指定 active / archive |
不带子命令时输出待完成看板,末尾汇总与 stats 共用同一维度;任务正文的 > 批次:第 N 批(共 M 批) 行会被解析进「按批次」汇总。
机器可读只在 list / stats(--format json)与 export 提供;check / archive / normalize 为文本报告,不支持 --format json。
archive
- 条件:
status为已完成/已放弃且带completed,按完成日期聚合归档 --task <唯一键>只归档指定任务;键不存在或尚未终结时报错退出(退出码 1),不落到全量- 未指定
--task且同时归档多个任务时,stderr 提示建议逐个归档以匹配逐任务提交(不阻断) - 排他锁防并发;缺
completed的终结态任务跳过并提示 - 完成时间晚于当前系统时间超过 14 小时(跨时区容差)或恰为零点整(疑似只填日期被补零)时软告警
- 文件名简述与正文标题不同源时在固化前软告警(归档块标题取自文件名,固化后不再改)
- 已放弃但正文缺
> 放弃原因:时软告警(受--no-warn控制),不阻断归档
check
校验 active 任务与下列形态,只报不改:
- 任务字段:frontmatter 合法性、owner / created / 命名规范、重名、
updated早于created(error 级)、depends_on闭环、未闭合待办与- [ ] - 文件名三段:日期↔
created、用户名↔owner、简述↔正文标题;简述须源出标题(不翻译 / 不音译 / 不缩写),并检查跨平台非法字符、Windows 保留设备名、结尾点或空格、NFC 与长度(均软告警) - 时间:completed 晚于当前系统时间超过 14 小时(跨时区容差)或恰为零点整时软告警
- 范围字段:顿号 / 逗号疑似多值分隔(请改半角加号)、括号疑似注释(请移入正文)、含空格(端名与分类标签不得含空格);取值须在 conventions 端清单内(
common恒合法),载体缺失时跳过 - 词标记:只认正文行首子项形态(列表项或「标记词:」开头),跳过标题、代码块与引用块,叙述性引用不再误报
- 搁置节:
status: 搁置的档须在正文第一个二级标题处有## 搁置节,四行顺序固定(搁置原因 / 重启条件 / 进度锚点 / 搁置日期)、 全角冒号、搁置日期为YYYY-MM-DD;非搁置档残留该节亦提示(转「已放弃」时保留不计)——均软告警 - 放弃理由:
status: 已放弃的档须有非空> 放弃原因:行;其它状态残留该行亦提示——均软告警 - 阻塞节:
status: 阻塞的档须在正文第一个二级标题处有## 阻塞节,三行顺序固定(阻塞原因 / 解除条件 / 阻塞日期)、 全角冒号、阻塞日期为YYYY-MM-DD;解除记录日期晚于阻塞日期时提示转回进行中;非阻塞档保留该节不校验——均软告警 - 文件位置:游离于
active/层级外的日期前缀文件 - 规范载体:旧单文件
conventions.md残留待迁移;conventions/缺index.md;形态异常(形态标记、history.md与索引表首列 ID 三者不一致); v3 索引表列集合偏离五列;history.md/retired.md表头偏离固定列; 载体各文件表头与分隔行列数不等;history.md数据行首列非稳定 ID; 「修订内容」列含禁用语料; 分册内残留「确立来源」子项;索引表单元格形态偏离(单一事实源写成裸文件名或反引号分册名、归属含反引号或链接、当前语义缺全角冒号)—— 前两类可由toolkit convention format机械归一;任务区 md 表格列对齐填充同样由该命令归一 - 技能入口壳:壳标记版本与当前 toolkit 不一致、或被 gitignore 覆盖不会随 git 分发;多落点并存时各合并为一条并内联落点路径
- 变更集写法:扫
.changeset下待发布变更集,缺类型前缀的顶层条目、未加「- 」列表标记的正文行各转一条并内联条数 / 行数 (正文行会被 changesets 并入相邻条目作续行,说明性内容请并入条目写成- 修改:…);正文行阈值 1 行即报(单行段落同样会并入上一条目), 跳过标题 / 引用 / 代码围栏 / HTML 注释;前缀识别取全局表与各配置语言自有前缀的并集,缩进续行随父条目迁属不参与 - 归档块:复用
task normalize的同一检查实现(见下) - 文件卫生:UTF-8 BOM、行尾多余空白、CRLF / LF 混用,统一软告警不阻断
normalize
检查归档块,可选修复:
- 检查项:元数据四字段完整性、疑似任务块、完成时间与归档日期漂移、完成时间晚于当前系统时间超过 14 小时(跨时区容差)或恰为零点整(仅报告,不自动改值)、降序排序、月份目录归属、 范围字段形态(顿号 / 逗号分隔可
--fix归一为半角加号,括号疑似注释仅提示人工)、git 冲突标记、文件 BOM(归档文件亦检查,可--fix去除) --fix:自动补齐 / 迁移 / 重排 / 范围归一 / 按并集去重 + 降序确定性解决冲突标记(多写者同天归档的pull冲突); 同时剥离active/与archive/下任务档的 UTF-8 BOM(只对带 BOM 的文件写回,输出附「去除 BOM N 个文件」)--fix与--check互斥
stats
- 完成周期与分布(仅「已完成」,已归档任务创建日期从块标题恢复,缺失者跳过并计数)
- 活跃任务滞留时长(不含搁置:搁置是有意不投入,计入会把平均滞留长期拉高;搁置项在输出末单列「另有搁置 N 个」)
- 按完成月吞吐汇总
- 汇总块与
toolkit task看板一致:按状态 / 负责人 / 范围 / 批次(范围多值拆段、空值与-归「未标注」;批次解析正文行> 批次:第 N 批(共 M 批),无该行归「未分批」) --format json输出统一信封(schemaVersion/command/ok/data/issues),统计字段位于data; 过滤选项与视图查询一致(--view默认all,含归档);JSON 的byOwner/byScope仍是完成样本吞吐口径,统一分布见summary字段,view记录本次统计视图(all/active/archived)- ⚠️ JSON 的
active.count/avgStay/maxStay均为不含搁置口径(字段名未变、含义变更,新增搁置状态后的口径调整); 搁置项数在active.held中单列,读旧脚本时请据此调整
check / normalize 的问题清单逐条输出为 文件:行号: 描述(有行号时便于编辑器跳转);文件级问题(如重名、游离文件、归档块问题)无对应行,省略行号段,输出为 文件: 描述。
视图与过滤选项
| 选项 | 说明 |
|---|---|
--view <view> | active(默认)/ archived / all |
--owner <name> | 按负责人过滤,逗号分隔多值 |
--scope <scope> | 按范围过滤,逗号分隔多值;任务文件内范围多值以半角加号存储(如 web+server),过滤值命中任一段即中 |
--status <status> | 按状态过滤,逗号分隔多值;部分取值非法时 stderr 告警并剔除(能继续执行),全部取值非法时报错退出(退出码 1) |
--date <date> | 单日过滤(YYYY-MM-DD),与 --since/--until 互斥 |
--since <date> | 起始日期(含当天) |
--until <date> | 结束日期(含当天) |
⚠️ 过滤只作用于所选视图;不指定 --view 时默认只查待完成,过滤落空会附 --view 引导提示。日期口径:待完成看创建/更新,已归档看完成时间。
--view active 包含搁置项(它们仍在 .tasks/active/)。只看真正在推进的任务:
toolkit task --view active --status 待办,进行中,阻塞只盘点搁置项:toolkit task --status 搁置。搁置行附「搁置 N 天」——天数按正文「搁置日期」计算,缺该行回落 updated 并标「近似」; 超 90 天标 ⚠️、超 1 年提示「建议终结」。--format json 的 data.items[] 行对象含 heldDays(无搁置日期为空)与 heldDaysApprox。
导出与导入
| 子命令 | 说明 |
|---|---|
export <path> | 按扩展名驱动:.csv(UTF-8 BOM 超集列)/ .xlsx(三 sheet)/ .json({ schemaVersion: 1, summary, items });目录不存在自动创建;支持 --view 与过滤参数 |
import <file> | 从 .csv/.xlsx/.json 导入;--target active(默认,生成任务文件)/ --target archive(直接写归档块);--dry-run 预演;--owner/--scope 作为导入行缺失字段的默认值 |
--format json 只用于 task 总览与 task stats 的 stdout(报告类走统一信封,数据在 data); 导出文件是数据流例外,格式由 export <path> 的扩展名决定,.json 仍为 { schemaVersion: 1, summary, items }。
导出产物含派生列「搁置天数」(JSON items 为 heldDays / heldDaysApprox,非搁置行为空;归档 sheet 不含):由正文「搁置日期」计算, 导入端不识别该列、按未知列忽略,不写入任何任务字段。
导入细节:兼容本工具三种导出产物(JSON 另兼容裸数组格式);XLSX 自动跳过名为「汇总」的 sheet、支持表头不在首行;表头自动识别中英文别名(不区分大小写), .toolkitrc.json 的 task.importColumns 自定义映射优先级最高; 文件名冲突自动追加序号不覆盖;带完成时间的行状态非终结态时自动置「已完成」并告警; 范围列含顿号/逗号/括号时提示按单值写入、多值请用半角加号(只提示不自动转换)。 --target archive 时,已放弃记录若来源未提供正文或正文缺 > 放弃原因:,合并为一条软告警(受 --no-warn 控制,不阻断导入)。
--target archive 的归档契约:按块标题去重——同名任务以本次导入的内容覆盖同名块,重复导入同一份文件不会产生重复块(幂等); 块内元数据状态取自数据(如源行状态为「已放弃」则写「已放弃」,不强制改写为「已完成」);缺完成时间的行无法直接归档,跳过并提示改用 active 目标。
相关页面
- 参考:完整攻略 · 任务文件规范 · 退出码
