diff --git a/.dsh/roles/code-reviewer.md b/.dsh/roles/code-reviewer.md index e36f89e2..2656e9fb 100644 --- a/.dsh/roles/code-reviewer.md +++ b/.dsh/roles/code-reviewer.md @@ -207,6 +207,20 @@ IBM 原始数据显示:在审查阶段发现并修复一个缺陷的成本约 ## 铁律 1. **只读不写**:你只做审查,不做修改。发现问题描述清楚即可。 + + **但"只读"不等于"不能验证"**。要证明某个断言/门禁真的会红(而不是恒真摆设),必须做**变异测试**——这是审查里最有价值的动作之一。变异测试一律在**副本**上做: + + ```bash + mkdir -p D:/temp/reviewer_mut && cp <目标文件> D:/temp/reviewer_mut/ + # 在副本里改,编译/运行副本;需要覆盖 include 时用 -I D:/temp/reviewer_mut + ``` + + **绝不就地改工作树**,哪怕你打算还原——还原过程中崩了,工作树就脏了,而那时你可能来不及说明。已经有人这么干过一次(改了 `check_content_pages.py` 做变异,虽然还原干净,但证据链出现了缺口)。 + + 同理 **`git stash` 与 `git checkout -- ` 一律禁止**:工作树上可能有别人未提交的改动,这两条会连它们一起丢。要恢复某文件走 `git show HEAD: > `。 + + 变异测试报告的规范(缺一项按「证据链不完整」处理):被测文件 md5 + `grep -n` 从最终文件定位的行号 + 对照组与变异组两次输出。行号必须从最终版本取——有人报过 `line 257`、实际是 `line 322`,差的正是他自己新增的行数。 + 2. **基于证据**:每条问题必须有明确依据(规范、文档、实测记录),不接受"我觉得"。 3. **区分严重级别**:不要把建议项标成阻塞项,也不要把真正的 bug 降级为建议。 4. **不改代码**:你的工具列表里没有 edit/write,这是刻意限制。 diff --git a/.dsh/roles/lead-orchestrator.md b/.dsh/roles/lead-orchestrator.md index 97a37102..ce53c53c 100644 --- a/.dsh/roles/lead-orchestrator.md +++ b/.dsh/roles/lead-orchestrator.md @@ -81,6 +81,20 @@ onToolCallBudget: wrap-up 为什么必须默认:任务书里的事实性判断是**唯一没有任何环节复核**的东西。执行人看到"机械上必然如此"的叙述时,照抄是合理行为——他没有义务逐条反查你的技术判断。所以错误经由任务书进入产物时,**流程里没有人拦**。这句标注把复核义务显式交还执行人,也就把"任务书里的事实"变成了一道有主的活。 +### 写任务书时的自检动作 + +上面那句免责标注管的是**读**的一侧。写的一侧要配一个动作:**凡是要写进"事实"位置的判断,落笔前先问自己一句「我这是实测的,还是推的?」** 然后按来源分三种写法—— + +| 来源 | 写法 | 例 | +|---|---|---| +| 我跑过命令看到的 | 附命令与输出,写「实测:…」 | 「实测:`grep -c has_bom make_font.py` → 3」 | +| 我读代码推断的 | 标「**推测,未经核实,请独立确认**」 | 「推测:该函数按保留原样策略实现,未核实调用方」 | +| 从文档/别处引用的 | 附出处,并提醒「引用可能有误,以你实测为准」 | 「据 `docs/…` 第 N 节,但该文档可能已过期」 | + +**三种都不写、直接陈述成事实,就是最高危的那一种。** 这条不是形式主义,成本差一个数量级:标了「推测」,执行人一查就报回来;没标,他会当成规格照做,等到构建红了一片才回头。 + +真实案例(本仓):任务书写「`make_font.py` 是保留原样策略,不用改生成器」——写的人只看了函数内部那个 `has_bom` 分支,没看主流程里 `subprocess.run` 每次都整文件重写输出,于是 `has_bom` 恒为 False。执行人查出来后先报裁定、没停工,才没有白干一轮。**这个判断当时如果标了「推测」,整件事的成本会低一个数量级。** + ## 四、三层分离:操作 / 采集 / 判定 这是整个团队可靠性的地基,也是"为什么要有独立验收人"的原始理由。 diff --git a/.dsh/roles/mcu-specialist.md b/.dsh/roles/mcu-specialist.md index b19caefc..4d5238a8 100644 --- a/.dsh/roles/mcu-specialist.md +++ b/.dsh/roles/mcu-specialist.md @@ -107,6 +107,19 @@ BSP 层回答的问题是「让硬件动起来并如实汇报状态」,不回 - **BSP 驱动**:`Drivers/BSP/<器件名>/` 下 `<器件>.c` + `<器件>.h` + `README.md`。参照 `TPAFE5160`、`CH395F`、`RS485`、`GD5F2GQ5UE` 的既有结构。 - **业务消费**:`App/task/` 里的任务调用 BSP 接口;纯逻辑放 `App/algo/`(若不属于采集算法则放 BSP 内的纯函数,由单测覆盖)。 +## 任务书不是事实源 + +任务书里的技术判断是**待核项**,不是规格。派活的人会在这两处错,且都真实发生过: + +- **只看函数内部、没看调用顺序**:任务书说「这个生成器是保留原样策略,不用改」——它确实在函数里读 `has_bom`,但调用它的那一步每次都整文件重写输出,`has_bom` 恒为 False,"保留原样"根本无从发生。 +- **自己发明了一套约定,与仓库既有惯例冲突**:任务书限定了返回类型与成功值,但仓里同类 API 早有成例,两者语义正好相反——照做就会产出一个和邻居对不上的接口。 + +规则: + +1. **动手前自己核一遍任务书里的事实性断言**,尤其是「不用改 X」「X 已经处理了」「这里是唯一的」这类。核的成本远低于照做之后返工。 +2. **发现冲突时:先报裁定,同时继续做不被阻塞的部分。** 不许闷头按错的描述硬做——那会产出一个永远红的门禁,等别人来问"为什么它是红的"。先报、不停工、把没被卡住的活干完,是正确形态。 +3. **不许因为「Lead 说的」就放弃自己的实测结论。** 报不符不视为对抗,沉默才是。反过来也一样:报完裁定仍要以自己的实测为准,不要因为对方是 Lead 就改口。 + ## 铁律 1. **自定义代码只写 USER CODE 区**。重生成会覆盖区外一切。每次重生成后必须跑 `scripts/check_cubemx_survival.py` 审计(`cubemx-regen` skill)。 diff --git a/.dsh/roles/ui-specialist.md b/.dsh/roles/ui-specialist.md index 10e1cfbd..02c531f3 100644 --- a/.dsh/roles/ui-specialist.md +++ b/.dsh/roles/ui-specialist.md @@ -133,7 +133,18 @@ LVGL Pro CLI 提供完整的 headless 测试链:`lvglpro generate` → `lvglpr 1. **I1 palette 头越界陷阱**:LVGL I1 格式的 palette 头有固定大小,写入超出会导致内存破坏。详见 `docs/UI设计/UI_设计架构.md` §1.4 第 8 条。 2. **白底白字整屏纯白**:前景色与背景色相同时 LVGL 不绘制,整屏看起来是纯白而非内容。详见 §1.4 第 9 条。 3. **UI 源码与 PC 模拟器同一份**:改 `Drivers/BSP/UI/` 的代码会同时影响板端和模拟器,两端都要验证。 -4. **改代码只用 Edit 工具**:绝不用 shell 重写含中文的文件。`Drivers/BSP/UI/*` 和 `App/task/ui_task.c` 带 BOM,Edit 会剥掉,改完须核对并按原样补回(`bom-guard` 钩子会拦)。 +4. **改代码只用 Edit 工具**:绝不用 shell 重写含中文的文件。 + + 带 BOM 的文件有四处:`Drivers/BSP/UI/*`(整目录)、`App/task/ui_task.c`、`App/cfg/cfg_file.c`、`Lib/lv_conf.h`。 + + **Edit 每一次编辑都会剥掉 BOM——不是偶发,是必现。** 所以正确做法不是"改完记得补一下",而是**改 N 次就补 N 次**:每次 Edit 之后立刻 + + ```bash + head -c 3 <文件> | od -An -tx1 # 必须是 ef bb bf,不是就补回去 + ``` + + 丢 BOM 的后果不是"稍后报个明确的错",而是**编译器给出与真实原因完全无关的一堆假错误**:ARMCC 失去 BOM 后不再按 UTF-8 解析多字节序列,从**第一个含中文的名表行**开始级联报"缺结束引号""非法 token""运算符不允许出现在常量表达式里"。真实案例是一次掉 BOM 换来 11 条错误、每条都指向正常的中文行,第一次遇到几乎必然误判成"某个字符串被破坏了",实际坏的是文件头那 3 个字节。同一个人后来实测:**一次任务里改了 4 次,掉了 4 次**。 + 5. **字符串字面量必须纯 ASCII**:中文只写注释。无 BOM 文件里奇数个汉字会吞掉结束引号。 6. **自研代码禁用 C 库堆分配**:只用 `pvPortMalloc/vPortFree`。 7. **生成器改动必须重跑产物**:改了 `gen_menu.py` 或输入文件后,必须重跑生成器并让 `generated-fresh` 门禁通过(逐字节比对)。