From e95d2be30b994f515806191f92f444ef70d7f8ee Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Wed, 14 Oct 2026 15:56:54 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E4=BB=BB=E5=8A=A1=E8=A7=84=E5=88=92):=20?= =?UTF-8?q?=E6=96=B0=E6=9D=A1=E7=9B=AE=E6=94=B9=E7=94=A8=E8=AF=AD=E4=B9=89?= =?UTF-8?q?=E6=A0=87=E8=AF=86=E2=80=94=E2=80=94"=E7=BC=96=E5=8F=B7?= =?UTF-8?q?=E4=B8=8D=E5=9B=9E=E6=94=B6"=E5=9C=A8=E5=AE=9E=E8=B7=B5?= =?UTF-8?q?=E4=B8=AD=E4=B8=8D=E5=8F=AF=E6=89=A7=E8=A1=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 登记簿原规则写着"编号不回收"（README §0 与 §3 各一处），但销项 = 删行， 删完仓库里就不留任何痕迹 → 该规则要靠人先想起去翻 git log 才成立。 实测撞号：登记簿 N-31（2026-10-11 的 Phase 7 复跑项）销项后，2026-10-14 新建条目按"现存最大值 +1"又取了 N-31，与 CH395F_Test_Guide.md、 自动化测试流程.md 里那两处历史引用同号。 裁定（用户 2026-10-14）：新条目 # 列填语义短语（如 "沉降窗 800ms 上限只留痕"），不再新增字母+数字编号；存量编号冻结沿用， 已随销项消失的号一律永久作废、不得作为新条目候选。语义标识自带唯一性 （重名一眼可见），从结构上消除复用可能。 改动：README §0 表首新增"语义标识"行 + 撞号因果注记；§3 原"编号一律 沿用且不回收"整条重写；AGENTS.md 完成即销项条目追加本裁定。 已确认无门禁校验编号格式（check_doc_links 只校 §N.M 与文档路径， 脚本里的 N-23/T-1 是注释性出处）→ 换标识不破任何钩子。 --- AGENTS.md | 2 +- docs/任务规划/README.md | 16 ++++++++++++++-- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9269c94b..b6640fd7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -151,7 +151,7 @@ ## 文档与图形 -- **登记簿类文档「完成即销项」**：`docs/任务规划/README.md` 这类待办登记簿，事项修复/关闭后**直接从表中删除该行**（不保留"已消化"行）——结论与证据应已沉淀进对应模块文档/问题记录。销项时必须：① 先核对目标文档确已含完整记录 ② 同步清理其他文档对该编号的引用 ③ 改完跑 `check_doc_links.py --all` + pre-commit +- **登记簿类文档「完成即销项」**：`docs/任务规划/README.md` 这类待办登记簿，事项修复/关闭后**直接从表中删除该行**（不保留"已消化"行）——结论与证据应已沉淀进对应模块文档/问题记录。销项时必须：① 先核对目标文档确已含完整记录 ② 同步清理其他文档对该编号的引用 ③ 改完跑 `check_doc_links.py --all` + pre-commit。**新条目标识（用户裁定 2026-10-14）**：`#` 列填**语义短语**（如 `沉降窗 800ms 上限只留痕`），**不再新增字母+数字编号**——"编号不回收"只写规则却不留痕迹就不可执行（销项删行后仓库无痕迹，实测 `N-31` 于 2026-10-14 被复用撞号），语义标识自带唯一性；存量编号冻结沿用、**已随销项消失的号永久作废** → `docs/任务规划/README.md` §0 - 图形走 **`draw-diagram` skill**：精确布局图用 `tools/arch_diagram/gen_*.py` 生成器（产物放 `docs/images/`，脚本与 .svg 一并提交）；拓扑图用 Mermaid；**勿手绘 ASCII 框图**。文件引用关系图走 `tools/refgraph`（`& 'tools\refgraph\gen_refgraph.bat'`） - **改名 / 挪目录一律走 `scripts/rename_ref.py`（先 dry-run，确认后 `--apply`）**：`git mv` + 自动改写全库引用（反引号引用 / Markdown 链接 / 图片 `../` 层级换算 / `#include` / `uvprojx` `` / `CMakeLists.txt`），落盘后自动跑 `check_doc_links --all` 复核——手工扫引用既慢又漏（一次改名历史上波及 10~30 文件）。引用章节用「`路径.md` §N.M」**紧邻写法**（`doc-links` 校验编号是否还在：紧邻/裸名/前缀/别名/自引用**全部拦提交**（钩子带 `--sections-strict`）；每次跑打印「可判定比例」，`--section-todo` 出待改清单，昵称歧义就登记 `scripts/section_aliases.json` 或写清楚）→ `docs/文档规范.md` §3.5 / §3.6 - 文档写作规范（编码/BOM/链接/表格/一致性钩子）→ `docs/文档规范.md`；全量索引与推荐阅读顺序 → `docs/README.md` diff --git a/docs/任务规划/README.md b/docs/任务规划/README.md index 4f0b2c33..989965e5 100644 --- a/docs/任务规划/README.md +++ b/docs/任务规划/README.md @@ -39,13 +39,21 @@ | 编号 | 含义 | 备注 | |---|---|---| +| **语义标识**（**2026-10-14 起新条目唯一形式**） | `#` 列填一行短语直接说清是什么事，如 `沉降窗 800ms 上限只留痕`、`RS485 采集接线` | **新条目一律用它，不再新增字母+数字编号**；同一表内语义天然不重复 → 结构上防号；引用时带文档名 | | `P0-x`~`P3-x` | 审计缺陷/改进项（2026-09-15/09-21 审计） | P0=功能 bug、P1=疑似 bug/健壮性、P2=改进、P3=卫生 | -| `N-x` / `S-x` / `T-x` | 台架/审计观察登记项 / 存储·日志管线 / 测试与工具链 | 编号**不回收**；`N-x` 含硬件改版项（需下一版硬件，固件侧只记口径，如 N-18） | +| `N-x` / `S-x` / `T-x` | 台架/审计观察登记项 / 存储·日志管线 / 测试与工具链 | **存量冻结沿用、不再新增**（新条目见上一行）；`N-x` 含硬件改版项（需下一版硬件，固件侧只记口径，如 N-18） | | `S1~S14` / `A-1~A-7` | 2026-10-02 复审的测试充分性与架构专项 | 编号**不回收** | | `E-xx` | 错误码传播审计发现 | 独立维护于 `错误码传播审计.md`，**不并入本文件夹**，只交叉引用 | | `B`/`C`/`D` 前缀 | §2 排序条目编号：B=功能主线、C=结构债、D=验证窗口 | 编号不回收，见 §2 | | 报告 `N-x`/`R-x`/`F-x`/`S-x`/`U-x`/`D-x` | `项目审查与优化建议报告.md` **自有编号** | ⚠ **与本登记簿同名不同义**（报告 N-16 = 日志逐条开关，登记簿 N-16 = A2/A4 负向台架）→ **引用一律带文档名**。其未闭环项 2026-10-11 并入本登记簿（新编 `N-19`~`N-29` + U 簇，出处列保留报告编号） | +> ⚠ **为什么 2026-10-14 改用语义标识**（一条实测失效案例）：原规则写着"编号**不回收**"，但 +> 销项 = **删行**，删完仓库里就不留任何痕迹——登记簿 `N-31`（2026-10-11 的 Phase 7 复跑项） +> 销项后，2026-10-14 新建条目按"现存最大值 +1"又取了 `N-31`，与 `CH395F_Test_Guide.md`、 +> `自动化测试流程.md` 里那两处历史引用**撞号**。"不回收"要靠人先想起去翻 `git log` +> = 不可执行的规则。语义标识自带唯一性（重名一眼可见）；**已随销项消失的字母+数字号一律作废**， +> 不得作为新条目候选，历史引用（如上述两处 `N-31`）指向的是当年的旧条目。 + **严重度定义**（沿用审计口径）：P0 = 确认功能 bug｜P1 = 疑似 bug 或健壮性风险｜P2 = 改进｜P3 = 卫生。 **置信度**：high = 代码级确证｜medium = 依赖外部条件（手册/硬件/产品定义）。 @@ -127,7 +135,11 @@ W7 仓库 N-29 .git 149MB（已决策暂不处理） 硬件：N-18 V0.2 - **并行写纪律**：任务分支（worktree）**不改本文件夹任何文件**；任务卡状态列（⬜/🟦）与销项一律由 Lead 在主工作树更新。解耦的收益 = 不同波次 / 不同登记之间互不冲突，**不是**任务分支可以写。 - **任一项完成后直接删除对应条目**（先销本文件夹条目，再清理其它文档对本编号的引用）；**不留变更记录**，历史见 `git log` 与各模块文档。 - 已闭环条目的**结论与证据沉淀进模块文档**，本文件夹不再重复。 -- 编号一律**沿用且不回收**（P-x / N-x / S-x / T-x / S1x / A-x / B·C·D 前缀）；`错误码传播审计.md` 的 E-xx 独立维护。 +- **2026-10-14 起新条目用「语义标识」**：`#` 列填一行短语（如 `沉降窗 800ms 上限只留痕`）， + **不再新增字母+数字编号**（规则见 `docs/任务规划/README.md` §0 表首行）；存量编号 + （P-x / N-x / S-x / T-x / S1x / A-x / B·C·D 前缀）**冻结沿用**，而**已随销项消失的号永久作废**、 + 不得作为新条目候选——"不回收"在只写规则、不留痕迹的情况下不可执行（撞号实测见 + `docs/任务规划/README.md` §0 注）；`错误码传播审计.md` 的 E-xx 独立维护。 - **引用审查报告编号一律带文档名**（报告 N-16 ≠ 登记簿 N-16、报告 S-3 ≠ 登记簿 S-3）； 报告并轨项用本登记簿新编号（N-19~N-29 + U 簇），出处列保留报告编号。 - **§2 是全项目唯一的推进顺序权威**：`产品需求设计文档.md` 等文档中的路线图只留指针，顺序变更只改 §2.0（详表文件跟着挪，不改顺序）。