cmshoppe/docs/tasks/T-551.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-551	脚本从 docs/tasks/ frontmatter 生成任务看板	8		TODO	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。

执行记录

（做完在此记录：改了哪些文件、跑的验证命令与结果、决策）