From af814fe95c2217ba69abbc242d5baf8ae56372d3 Mon Sep 17 00:00:00 2001 From: chengma Date: Wed, 8 Jul 2026 10:35:48 +0800 Subject: [PATCH] docs(tasks): add T-551 generate task board from docs/tasks frontmatter Co-Authored-By: Claude Opus 4.8 --- docs/tasks/T-551.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/tasks/T-551.md diff --git a/docs/tasks/T-551.md b/docs/tasks/T-551.md new file mode 100644 index 0000000..2cbd4f1 --- /dev/null +++ b/docs/tasks/T-551.md @@ -0,0 +1,42 @@ +--- +id: T-551 +title: 脚本从 docs/tasks/ frontmatter 生成任务看板 +phase: 8 +deps: [] +status: TODO +created: 2026-07-08 +--- + +## 问题 / 背景 + +采用"一任务一文件 `docs/tasks/T-<编号>.md`"后（见 `docs/tasks/README.md`），`docs/current-state.md` 已改为"不逐任务手动覆盖"，当前状态以各任务文件的 frontmatter 为准。但**目前还没有一个汇总视图**——要看"有哪些任务、各自 status/phase/依赖、下一个可领取的是哪个"，得手动 `ls` + 逐个翻文件。 + +需要一个脚本把 `docs/tasks/` 的 frontmatter 汇总成**只读的看板视图**，agent/人都从生成结果查询，不手改 → 不引入新的共享写入抢占点。 + +> 说明：若后续改用 Gitea/GitHub Issues 管任务（见相关讨论），本脚本的数据源改为 issue API，但"生成只读看板、不手改"的目标不变；本任务先服务当前 `docs/tasks/` 方案。 + +## 方案 + +新增脚本（如 `scripts/gen_task_board.py`）： + +- 扫描 `docs/tasks/T-*.md`（排除 `_template.md` 和 `README.md`），解析每个文件的 YAML frontmatter（`id/title/phase/deps/status/created`）。 +- 用**极简手写解析**读取这段简单 frontmatter（不新增 PyYAML 依赖）；字段缺失/格式错要跳过并提示，不崩。 +- 生成一张看板表写入**专用生成文件** `docs/tasks-board.md`（文件顶部标注"本文件由脚本生成，请勿手改"）：按 `phase` 分组，列出 `id / title / deps / status`；可附一段汇总（各 status 计数、"下一个可领取"=status=TODO 且 deps 全 DONE 的最靠前 id）。 +- 只读输出，agent 不手改；需要刷新时重跑脚本。 +- 归档 `docs/06-tasks.md`（T-000~T-549）不纳入生成范围，保持冻结。 + +## 验收要点 + +- 跑 `python scripts/gen_task_board.py` 生成/更新 `docs/tasks-board.md`，内容与 `docs/tasks/` 现有任务文件一致（含 T-550/T-551）。 +- frontmatter 缺字段/格式异常的文件不导致脚本崩溃，只跳过并提示。 +- 生成文件顶部有"勿手改、由脚本生成"标注。 +- 不依赖第三方库（用标准库 + 手写 frontmatter 解析）。 +- `tests/` 加脚本单测：给一个临时 `tasks/` 目录，断言生成的看板包含各任务的 id/status、"下一个可领取"计算正确。 + +## 边界（不改什么） + +只加生成脚本 + 生成的 `docs/tasks-board.md` + 脚本单测；不改任务文件内容、不改 `06-tasks.md` 归档、不改业务代码、DB、CDP/Shopee。 + +## 执行记录 + +（做完在此记录：改了哪些文件、跑的验证命令与结果、决策）