Files
STM32F4-Base/AGENTS.md
T
wandering1 061365e10a feat(roles): 新增技能处理者角色,固化技能主文件只放默认路径的口径
新增 .dsh/roles/skill-custodian.md(双层结构:Agent Skills 三级加载
与官方体积约束 + 本仓 17 个技能现状盘点、12 条可判定审核清单、
改进四步流程、写域边界)。

口径固化三处,同一事实只详述一处:
- AGENTS.md 铁律新增「技能写法」:主文件只放默认可用方案,按本项目
  配好默认参数、一条命令能跑通、给出成功输出样例;失败时由脚本打印
  稳定索引键,主文件按该键指向 reference/ 同名小节;排查细节、边界、
  历史坑、手工兜底一律不进主文件。
- .dsh/roles/README.md:角色总览表、详细说明段、派活速查表各加一行,
  角色计数 11 -> 12,并记录 worktree 新增角色不注入的实测坑。
- .dsh/roles/lead-orchestrator.md:分工表加一行。

实测:subagent_role 探针逐字回读 persona 首行与硬口径小节均命中;
pre_commit 四文件全 Passed 零 Failed;BOM/CR/U+FFFD 均为 0。
2026-11-18 11:11:00 +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 1408 Normal
ftpTask 1024 Normal
testTask 2048 BelowNormal
uiTask 4096 BelowNormal
timeSyncTask 736 Normal
adcTask 640 AboveNormal
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/代码规范/。
  • 技能写法(.dsh/skills/):SKILL.md 主文件只放默认可用方案——按本项目配好默认参数、一条命令能跑通、给出成功输出样例;失败时由脚本打印稳定索引键(阶段名/退出码/报错前缀),主文件按该键指向 reference/ 的同名小节。排查细节、边界、历史坑、手工兜底一律不进主文件。审核与改进 → .dsh/roles/skill-custodian.md。

提交门禁(pre-commit)

共 52 个钩子(提交期实跑 47 根 + gitlint = 一次 commit 48 根,4 根慢钩子由远端 CI 与 ci_local.py 承担)。任一失败即拦截;提交信息标题 ≤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(12 个)。
  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