Files
STM32F4-Base/AGENTS.md
T
wandering1 ab20302999 refactor(agents): split entry file from role knowledge, add orchestration role
The entry file had grown to 194 lines, of which a large part duplicated
knowledge that already lived in skills, docs or role files. Worse, three
pieces of project knowledge existed only there, and ten roles were all
module implementers or reviewers: no role carried the Lead side
collaboration protocol, so "Lead only orchestrates, never implements" and
"the reviewer must not be the implementer" had no home anywhere.

AGENTS.md 194 lines / 13908 B -> 121 lines / 12283 B, 13 sections -> 9.
- Dropped four sections whole, each with an existing landing point:
  build and verify (keil-build / serial-boot-test skills), Python env
  (new-machine-setup skill), hardware pins (hardware spec doc section 2),
  docs and diagrams (writing standard plus draw-diagram skill).
- Compressed project overview, iron rules, pre-commit, platform
  constraints and module conventions into pointers plus the few facts that
  must be seen every turn.
- The directory map changes from "directory | responsibility | can I
  modify it" to "directory | can I modify it" and hands the detail to the
  architecture overview section 7. The value of this table on the entry
  file is the permission semantics, not a second copy of the tree.
- Delegation policy is the one section that grows in substance: four
  always-present rules, reviewer is not implementer, rework needs fresh
  evidence, the gate flow, three measured limits of the ledger plugin and
  member revive/rebind.

Three machine anchors are untouched: the TASK_TABLE comment pair and its
body, the BOM list line (one line, four paths, the bom-drift checker
concatenates every line containing BOM), and the hook count sentence.
Line endings stay CRLF.

New roles:
- .dsh/roles/lead-orchestrator.md: the Lead collaboration protocol in two
  parts, generic methodology and this project's specifics. Twelve
  anti-patterns with the case behind each, an eleven-role split table
  (what it owns, what it must not touch, when to call it), and ten
  documented gaps between what the entry file claimed and what
  dsh-plugin-team-ledger v0.2.0 actually does.
- .dsh/roles/bench-runner.md: bench execution and evidence collection, an
  execution layer and explicitly not a decision layer. It has no write
  tools and no gate submit/accept, because the person who reads the log
  must not also judge the run.

Existing roles:
- mcu-specialist gains the kernel-before-start rule, including the legal
  counterexample vTaskDelete(testTaskHandle) in Src/freertos.c. The
  criterion is not "create or delete" but whether the call waits for the
  scheduler or for time.
- algo-specialist gains the RS-485 wiring gate with the two contract
  defects it stands on: a weak rx hook with a single 256 byte buffer, and
  a direction switch back to RX that does not wait for TC.
- storage-specialist's owner statement is rewritten rather than appended:
  defaultTask owns the config engine because its static state is unlocked,
  and reading still advances the poll baseline and the debounce counters.
- README: eleven roles, order unified across the overview table, the
  detailed sections and the selection guide.

Verified: gen_task_table --check, bom drift, mojibake, generated fresh and
doc links all clean, and doc links report the same six pre-existing
findings as before this change. Role files are CRLF free, no BOM.
2026-11-16 19:37:15 +08:00

12 KiB
Raw Blame History

STM32F4-Base

工业级嵌入式 DTU 平台固件:STM32F407ZGTx @168MHz,集成以太网(CH395F)、SPI NAND 存储(GD5F)、电气量采集(TPAFE5160 + 片内 ADC)、RS-485、FTP 文件服务,自带远程显示(UI 推流)、墙钟对时、看门狗自恢复、运行/自检记录——既是可独立部署的现场设备,也是可复用的平台底座。产品基线 → docs/产品需求/产品需求设计文档.md §2.1。

仅 Keil MDK-ARM v5 (ARMCC, C99);FreeRTOS V10.3.1 / CMSIS-RTOS2;192KB SRAM / 1MB Flash。任何代码修改后必须先 /keil-build 验证(0 错误 0 警告)再提交;硬件闭环用 /serial-boot-test。

本文件 = agent 入口:概况 + 每次都在场的铁律 + 团队分工 + 索引。操作细节不在本文,在 docs/、skills 与 .dsh/roles/——同一事实只在一处详述。

项目概况

现状一句话:平台能力(网络/存储/时间/UI/日志/看门狗/FTP/配置)已实现并台架验收;采集主线已闭环到业务消费者(UA/IA 两路已由 5 点最小二乘标定落盘,见 docs/硬件平台/ADC通道映射说明.md §7.5);⚠ 保护判据现处于「未标定闭锁」态——adc_cal_prot_blocked() 要求 UA/UN/IA 三路 VALID 齐,UN 通道在本台架永久无数据(台架无接线、该端子只读噪声底,用户裁定 2026-11-13 不再测),故保护永久闭锁、不许伪造 VALID;RS-485 采集尚未接线(按用户决策冻结)。

数据主线(分层图与跨层依赖表 → docs/架构设计/项目架构总览.md):采集 TPAFE5160 + ADC1 → TIM3 1kHz → adcTask → 语义取数 → 傅氏相量 → 测频/遥测快照 + 保护判据 → 104 上送;存储 GD5F → dhara FTL → FatFs → 日志/配置/FTP;网络 CH395F → netTask 串行 socket → FTP/RemoDispBus/IEC 60870-5-104 + SNTP 对时;人机 LVGL 160×160 单色菜单,与 PC 模拟器同一份 UI 源码。

目录地图(只列顶层;细结构 → docs/架构设计/项目架构总览.md §7;仓库根不放一次性产物,进 ci-artifacts/):

目录 我能改吗
Src/ Inc/ 只写 USER CODE 区
App/ 手写(应用层 task/algo/cfg/log/fs/sync/util)
Drivers/BSP/ 手写(芯片驱动与服务)
Drivers/STM32F4xx_HAL_Driver/ CMSIS/ Middlewares/ Lib/ 只读(第三方:HAL/FreeRTOS/LVGL/FatFs/dhara)
MDK-ARM/ Keil 工程,UV4 抖动不入库
simulator/ test/ scripts/ tools/ 手写(模拟器/测试/门禁/生成器)
docs/ .dsh/ 手写(文档索引 docs/README.md;skills · roles · plugins)

分层边界:上层只依赖相邻下层(单向);新算法进 App/algo/,勿塞 App/task/;新 .c 必须双端注册(new-source-file skill)。

架构要点

启动流程与任务详情 → docs/架构设计/项目架构总览.md、docs/架构设计/项目启动顺序管理.md

Task 栈 (words) 优先级
defaultTask 1280 Normal
netTask 960 Normal
ftpTask 1024 Normal
testTask 2048 BelowNormal
uiTask 4096 BelowNormal
timeSyncTask 640 Normal
adcTask 640 AboveNormal
iec104Task 640 Normal
protectTask 512 Normal

(实际值以 Src/freertos.c 为准;RAM 台账 → docs/内存管理/RAM预算台账.md)

铁律:源码编辑与编码

  • 改代码只用 Edit 工具;绝不用 shell 重写含中文的文件(乱码不可逆);字符串字面量必须纯 ASCII,中文只写注释。
  • Edit 会剥 BOM:带 BOM 文件编辑后须补回 → bom-guard 钩子自动拦截。带 BOM 名单(三处互指:本行、钩子 files 正则、scripts/check_bom_drift.py 的 BOM_LIST):Drivers/BSP/UI/(整目录)、App/task/ui_task.c、App/cfg/cfg_file.c、Lib/lv_conf.h
  • 行尾由 .gitattributes 写死 LF,不依赖 core.autocrlf;注释里别写星号形态的路径(ARMCC 9-D)→ nested-comment 钩子;SKILL.md 有 65536 字节写侧上限 → skill-size 钩子,深规程写进 reference/。规范全文 → docs/代码规范/。

提交门禁(pre-commit)

共 52 个钩子(提交期实跑 49 根,3 根慢钩子由远端 CI 强制)。任一失败即拦截;提交信息标题 ≤100 字符、正文每行 ≤80,长说明用 git commit -F <文件>。每种门禁一篇详解 → docs/门禁说明/README.md;通用机制 → docs/代码规范/pre-commit使用说明.md;CI 只跑静态门禁 + 主机侧单测、不跑 /keil-build → docs/CI/README.md。

平台约束

详细实现与实测坑 → 各子系统文档(见文末索引),禁令与关键数值按域归口:

  • CubeMX 与 Fault → docs/子系统设计/看门狗设计说明.md §10(USER CODE 区边界、cubemx-survival 钩子、ARMCC __asm 整函数形态、4 个 Fault 采集与 fault_handler_enable() 必须是 app_main_init() 第一行)
  • RTOS 与内存 → docs/架构设计/项目启动顺序管理.md(内核启动前的编码约束);docs/内存管理/(mem-budget 钩子拦 >92%、HAL 时基 TIM7/tick 1ms、NVIC 外设中断优先级 ≥5);自研代码禁用 C 库堆分配(MicroLIB 堆仅 512B)→ coding-standard 钩子拦截
  • 采集链 → docs/子系统设计/ADC采样节拍设计.md(tpafe5160_snapshot() 是唯一许可取数面、ADC1 必须 TIM3 触发 + DMA2 Stream4、CubeMX 不生成自校准);RS-485 接线门禁 → .dsh/roles/algo-specialist.md
  • 存储与网络 → docs/架构设计/STM32F4-Base存储架构说明.md、docs/网络/(FatFs 追加写开标志与写回字节校验、CH395F SPI 分频必须 8);配置引擎唯一属主 → .dsh/roles/storage-specialist.md
  • 日志 → docs/子系统设计/控制台单写者日志设计.md §7.1(权威口径:每条 DBG_* 约 90B Flash + 216B 栈,深链模块必须预定义 DBG_LINE_BUF_MAX)
  • *.uvprojx 每次构建后被 UV4 改写,一律不入库

模块约定

  • 写入者互斥:defaultTask 是配置引擎唯一属主、netTask 独占 CH395F——越界的正面规范与理由见对应角色文件,别靠「我只读不写」开脱。其余硬约束:CH395F 全局中断整体读即清不得在 ISR 单独处理(→ docs/网络/网络自愈架构设计.md §4.10)、net_* 经 netMsgQueue 串行、单连接 socket EOF 时不得 net_close。
  • 动手前先读坑:改驱动前读 docs/问题记录/*_Trap_Records.md;改 UI 前读 I1 palette / 白底白字两条实证坑 → ui-verify skill;测试套件互斥(test_config.h)与破坏性开关 → board-test-suite skill。
  • 改名的唯一路径:改名/挪目录走 scripts/rename_ref.py,编号改名走 scripts/rename_ids.py,绝不全局查找替换;待办「完成即销项」(修复后删行,新条目用语义短语、不发编号)→ docs/任务规划/README.md §0。

委派策略(Agent Teams 优先)

分工规范全文 → .dsh/roles/lead-orchestrator.md(职责边界、何时用团队、任务四要素、三层分离、反模式表、插件实测约束)。以下是每次都在场的四条:

  1. Lead 只调度不执行:拆解、分配、协调、判定、汇总。不直接做模块级实现——一旦自己动手,验收独立性就没了。
  2. 涉及两个以上模块,或需要构建+测试+文档联动 → Agent Teams(spawn_teammate + send_message);单文件小改用 subagent_role 即可,不要为小活开团队。
  3. 角色绑定:spawn_teammate 的 prompt 首行写 @role:<角色id>(如 @role:algo-specialist),插件在子会话首轮请求组装前自动注入 .dsh/roles/<角色id>.md 的 persona 并应用工具白名单——缺首行标记 = 无角色,勿省略。subagent_role 路径同为自动注入。可用角色 → .dsh/roles/README.md(11 个)。
  4. 派活必带验收口径:任务书里写清「怎么算做对了」——可验证的结果定义 + 逐条检查清单 + 写域声明;回报必须附实测证据(命令输出、文件路径与函数名、计数),不采信自述结论。

验收与返工:验收人 ≠ 执行人(自证自验最容易掩盖真问题,文档同理);返工不许只回「收到」,须修正后附新证据重新提交。

门禁与唤醒工具(dsh-plugin-team-ledger v0.2.0,宿主 Agent Teams 的增强层——宿主本身没有验收身份闸与自动唤醒):

  • 流程:team_gate_open(Lead 建闸:逐字匹配的清单 + 执行人 + 独立验收人)→ 执行人 team_gate_submit(附实测证据)→ 验收人 team_gate_accept / team_gate_reject(退回并自动唤醒返工人)→ Lead team_gate_close。账本在 <工作区>/.dsh/team/gate.jsonl,跨重启存活;重启后用 team_gate_list 取回未闭环门禁。
  • 三条实测真话(别当机器保证来用):① 「验收用门禁、不用 team_task_update 裸标」是约定,插件不拦裸标,只保证账本说真话;② open 不校验验收人是否存在、claimHistory 只由执行人初始化,开闸前必须 list_agents 实查双方在线;③ 唤醒失败只落 diag 不返回调用方(~/.dsh/team-ledger-diag.log),open 返回 ok ≠ 被指派的人真会被叫醒。Lead 可代提交(proxy)但不能代验收。
  • 成员运维:死后救活 / 只换模型 → team_member_revive({target, provider?, model?});工具面异常放大或 persona 消失 → team_member_rebind(判据见 .dsh/plugins/dsh-plugin-subagent-roles/docs/子Agent角色自动注入实现说明.md §5.1)。复活风暴由 30 分钟滑动窗口掐住。

边界(Ask first / Never)

Ask first:git commit/push · 开 ENABLE_DESTRUCTIVE_TESTS · CubeMX 重生成 · 待办销项 · 建任务/抬栈/加大缓冲

Never:shell 重写中文文件 · git checkout/reset --hard 丢弃未提交工作 · USER CODE 区外写代码 · C 库堆分配 · 非 defaultTask 碰配置引擎 · 非 netTask 碰 CH395F · 提交 uvprojx 抖动 · 提交 .mnemon/

按主题查哪份文档

主题 去处
全量索引 / 推荐阅读顺序 docs/README.md
架构全景 / 启动时序 docs/架构设计/项目架构总览.md、项目启动顺序管理.md
产品需求基线 docs/产品需求/产品需求设计文档.md
看门狗 + CubeMX + ARMCC __asm docs/子系统设计/看门狗设计说明.md §10
ADC 采样 / 通道映射 / V0.1 缺陷 docs/子系统设计/ADC采样节拍设计.md、docs/硬件平台/ADC通道映射说明.md
存储栈 / FatFs 陷阱 docs/架构设计/STM32F4-Base存储架构说明.md
RAM / 栈预算 docs/内存管理/RAM使用分析与优化方案.md、RAM预算台账.md
每个门禁详解 docs/门禁说明/README.md
编号规范(一律不发编号) docs/文档规范.md §7.1
门禁通用机制 docs/代码规范/pre-commit使用说明.md §2
代码规范 / cppcheck docs/代码规范/嵌入式C语言代码规范_V1.0.md、cppcheck使用说明.md
测试流程 / 板级套件 docs/测试说明/、board-test-suite skill
烧录与复位 docs/测试说明/测试工具/ST-LINK_CLI_复位使用说明.md
串口助手 serial-assistant skill
UI / 模拟器 / 自动化回归 lvgl-simulator skill、ui-verify skill
板端 UI 交互 board-ui-nav skill
待办与推进顺序 docs/任务规划/README.md
并行开发 / worktree task-worktree skill、docs/环境与部署/并行任务工作树方案.md
换机 / 环境变量 docs/环境与部署/
远程 CI docs/CI/README.md