From 8bd12c0aa8c9dc412b27fdd7343f749a45eb3ccf Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Tue, 17 Nov 2026 00:05:34 +0800 Subject: [PATCH] docs(roles): record the traps the agents actually fell into Each of these four role files was changed only where this session produced evidence that the existing wording was not enough. The MCU specialist had no clause at all saying a task brief is not a source of fact, yet twice in this session it overrode a brief by checking the code and was right both times. The new section states the two ways a brief goes wrong (reading a function without reading its caller; inventing a convention that conflicts with the repository's existing ones) and the rule that matters: report the conflict, keep working on whatever is not blocked, do not silently comply. The reviewer role said "read only, do not modify" and stopped there. Verification often needs a mutation test to prove an assertion can fail at all, and the reviewer did exactly that by editing a tracked file in place. Restored byte for byte, but the evidence chain had a gap while it was in flight. The clause now says read-only does not mean unable to verify, mutation tests happen on a copy, and git stash or git checkout of a single file is forbidden because the tree may hold other people's uncommitted work. The UI role said BOM is stripped by Edit and must be put back. True but too weak: it reads as one cleanup at the end, when every single edit drops it. One agent measured four edits, four losses. Rewritten as put it back N times for N edits, with the check right after each one, and with what the failure actually looks like: eleven compiler errors pointing at perfectly good Chinese lines, because ARMCC stops treating the file as UTF-8 and the first multibyte line takes every diagnostic with it. The lead role already said briefs are unverified until checked, but that only holds the reading side. Added the writing side: before stating something as fact, ask whether it was measured or inferred, and label it accordingly. The real failure was a brief claiming a generator preserves the input file, inferred from one branch inside a function while the caller rewrote the file every run. Only these four were touched. The algorithm-specialist role owns the ui_data work landed in 2b466b85 (frame fields, feed, host tests) and has real gaps of its own, but this pass did not cover it. --- .dsh/roles/code-reviewer.md | 14 ++++++++++++++ .dsh/roles/lead-orchestrator.md | 14 ++++++++++++++ .dsh/roles/mcu-specialist.md | 13 +++++++++++++ .dsh/roles/ui-specialist.md | 13 ++++++++++++- 4 files changed, 53 insertions(+), 1 deletion(-) 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` 门禁通过(逐字节比对)。