Skip to content

规范载体(convention) ​

规范载体的结构升级、表格与索引单元格归一、只读体检。

bash
toolkit convention upgrade               # 把 v1 / v2 规范载体升级为 v3(幂等,先判后写)
toolkit convention upgrade --dry-run     # 预演:只预览将执行的动作,不写文件
toolkit convention upgrade --format json # JSON 输出:ID 映射、内部引用改写、结构动作清单
toolkit convention status                # 只读体检:形态 / 索引 / 入口层三块(只报不改,体检不阻断、退出码恒 0;仅 --format 传非法值时按参数错误退出)
toolkit convention status --format json  # JSON 输出:形态、条目数、入口壳现场与逐条体检项
toolkit convention status --dir ./repo/.tasks # 跨仓体检:入口壳与检测入口按该目录所属仓库扫描(父目录含 package.json / .git 即视为仓库根;task check --dir 同口径)
toolkit convention format                # 归一任务区表格形态与索引表单元格:列对齐填充压回紧凑形态,单一事实源链接化、归属裸值、规则去引号
toolkit convention format --dry-run      # 预演:只报告将改动的文件与行数,不写文件
toolkit convention format --format json  # JSON 输出:status、目录、文件数、变更文件数、逐文件变更行号与待人工处理项

裸 toolkit convention 打印本域帮助(列出 3 个子命令)。

convention check 为 convention status 的别名,参数与输出完全一致(补命令名与直觉不一致的入口)。

三者的 --format json 均走统一信封 { schemaVersion, command, ok, data, issues }:下表所列报告字段位于 data; status 的体检项同时映射到顶层 issues(level / scope / message),体检不阻断时 ok 恒为 true。

子命令行为
upgrade把 v1 / v2 载体升为 v3 三分区:v1 输入先升 v2 再升 v3(首行补形态标记、标题归一、「演进记录」节抽为独立 history.md、索引表首列 # → ID、内部引用改写为稳定 ID C-<n>);v2 → v3 再删索引表「状态」「确立来源任务」两列、history.md 表头首格归一为稳定 ID ID(与索引表首列同归一)、把状态为 已废弃 的行迁入按需创建的 retired.md(并从 Z1 索引删除、同步物理删分册内对应小节)、history.md 首列补 C-<n> 与来源列补录(首列已为行内代码包裹的 C-<n> 不误报)、index.md 表外自由文本残留 v2 措辞(「确立来源任务」「状态改为已废弃」等)复核、首行标记升 v3。以上无法机械判定的项列为人工复核项 reviews(只报不改)。幂等——已是 v3 返回 already-v3、不改动;未初始化(缺 index.md)或形态异常(标记 / history.md / 索引表首列三者不一致)在写盘前拒绝执行并给非 0 退出码,不写任何文件。--dry-run 只报告不改动;--format json 在信封 data 内输出 status、idMap、refs、changes、reviews(ID 映射只随报告输出、不落盘);实跑完成后提示随后执行 toolkit convention format 归一索引表单元格
status只读体检、只报不修(无 --fix):形态(v1 / v2 提示可升级、形态异常、旧单文件与目录并存、表格存在列对齐填充可执行 toolkit convention format 归一、v3 载体索引表列集合须恰为 `ID
format归一任务区表格形态与 conventions/index.md 索引表单元格:表格把被格式化器填充的列对齐空白压回紧凑形态(单元格间单空格),分隔行按列宽补长的横线一并压为 ---(保留对齐标记)。范围=任务目录下全部 .md(载体三件 + active + archive),跳过 fenced code block(``` 与 ~~~ 块内的表格样例原样保留);表格只动单元格间距、分隔行横线长度与列对齐填充。索引表另做可确定项的单元格归一——单一事实源中可解析到具体 .md 的路径(含载体外文件,裸写或反引号包裹)转为相对链接,通配与不可解析项保持行内代码;归属去反引号与链接;规则去首尾引号。当前语义不改写:缺全角冒号时只进「待人工处理」清单。目标不在载体内时原样保留并告警,不写死链。幂等——已合规返回 already-compact、不改动;未初始化(任务目录不存在)在写盘前报错并以非 0 退出码终止。--dry-run 只报告不改动;--format json 在信封 data 内输出 status、tasksDir、files、changedFiles、changedLines、changes(逐文件变更行号)、warnings(待人工处理项);文本输出最多列 10 条待处理项,JSON 输出全量

⚠️ upgrade 只做机械结构升级,不改条文语义;索引表单元格沿用原写法,升级后建议跑一次 toolkit convention format 归一。升级过程可中断、重复执行安全。

⚠️ format 只动形态、不改语义(紧凑是规范形态、填充是偏离;链接化只改「写在代码里还是链接里」);当前语义的措辞重写不能机械化,缺全角冒号时只出清单。 task check 与 convention status 会对填充态与单元格形态偏离给软告警、指向本命令,task normalize --fix 不代改空白层。

⚠️ 读取模型由 index.md 路由:按索引行的适用面判断是否命中,命中即读其「归属」分册或「单一事实源」,无命中即止; common.md 不再是恒读面,只是跨面原则所在的一个普通分册。

载体结构(v1 / v2 / v3 形态、三分区、稳定 ID、history.md / retired.md)与读写细则见完整攻略 · conventions/: 规范沉淀地。

存量载体归一 ​

新读取模型下,索引行的「当前语义」承担路由职责:它决定本轮任务要不要读该条分册。 旧载体结构合法,但语义若写成整段要求,路由会退化为「写得含糊 → 漏读」。按四步归一:

  1. 体检:跑 toolkit convention status,先看形态 / 索引 / 入口层的现成告警(含语义超 120 字符的路由提示)
  2. 索引改路由写法:逐行把「当前语义」压成「何时适用 + 一句话要求」,条文细节留在归属分册
  3. 归属纠偏:跨面原则留 common,只适用某端或某主题的移入对应分册,避免 common 成为暂存区
  4. 承载核对:确认每条索引行的「单一事实源」指向真实存在的位置,分册小节 ID 与索引条目一一对应

判定标准:一句话能说清「做什么任务时读它」,即为合格的路由行。 反例是把整段要求塞进索引——读完仍不知道何时适用,等于没有路由。

⚠️ 旧载体不改也能跑:读取侧无兜底,但索引写得含糊只会降低命中率,不会报错。

相关页面 ​

MIT 开源协议