061365e10a
新增 .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。
123 lines
12 KiB
Markdown
123 lines
12 KiB
Markdown
# 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_TABLE:BEGIN generated by scripts/gen_task_table.py -->
|
||
| 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 |
|
||
<!-- TASK_TABLE:END -->
|
||
|
||
(实际值以 `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`](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`](docs/CI/README.md) |
|