chore(全仓): @build/@test 旧文档别名清退为技能调用名
现状口径：/keil-build 与 /serial-boot-test 是 DSH 会话的技能调用名， 不是 shell 命令；「名 + 命令行参数」的命令形态改为可执行体 run_boot_test.py 的真实调用。 - AGENTS.md：别名说明重写为「技能调用名不是 shell 命令」，两条目改 「编译（/keil-build）」「串口回归（/serial-boot-test）」 - keil-build / serial-boot-test 两 skill 调用名与示例同步；task-worktree 方案文档去掉 @build/@test 惯例从句；@task 保留（不在点名范围） - 123 文件现状陈述全改；台架捕获、变更记录/时间线、rename 映射输入 等 41 行历史证据保留旧名 - gen_memory_svg.py 6 处措辞随改，3 张 SVG 产物同批重跑 - 顺手补并行方案同行漏网计数 51→52 钩子 验证：提交期快钩子对 123 文件实跑全 Passed；check_doc_links --all rc=0（3038 处、无法判定 0）；check_mermaid --all rc=0；YAML 解析 52 钩子不变；skill-size rc=0；py_compile 全过；字节卫生零漂移。
This commit is contained in:
@@ -4,7 +4,7 @@
|
||||
|
||||
**仅 Keil MDK-ARM v5 (ARMCC, C99) 工具链**；FreeRTOS V10.3.1 / CMSIS-RTOS2；192KB SRAM / 1MB Flash。
|
||||
|
||||
**任何代码修改后必须先 `@build` 验证（0 错误 0 警告）再提交；硬件闭环用 `@test`。**
|
||||
**任何代码修改后必须先 `/keil-build` 验证（0 错误 0 警告）再提交；硬件闭环用 `/serial-boot-test`。**
|
||||
|
||||
> 本文件 = agent 入口：宏观概况 + 每次都在场的铁律在这里，细节在 `docs/` 与 skills（文末索引）。同一事实只在一处详述（`docs/文档规范.md` 同此要求）。
|
||||
|
||||
@@ -78,10 +78,10 @@
|
||||
|
||||
## 构建与验证
|
||||
|
||||
- **门禁时机（用户裁定 2026-10-13）**：`@build` / `scripts/ci_local.py` / `check_doc_links.py` **只在准备提交时跑**（用户让 commit 后统一跑一遍），**不是每次中间改动后都跑**——多步改动期间直接改即可，验证集中在提交门禁；`@test` 硬件闭环仍按任务需要跑
|
||||
- **`@build` / `@test` / `@task` 都是本仓库的文档别名，不是 shell 命令**（2026-10-30 实测：bash 里直接敲 `@task` / `@build` 是 command not found，`dsh task` 会被解析成 profile 名报错）——下面 `=` 后的命令行才是可执行形态（PowerShell 形态，bash 下路径正斜杠）；DSH 会话显式调用 skill 用 `/keil-build`、`/serial-boot-test`、`/task-worktree`
|
||||
- `@build` = `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`（仓库根执行）。退出码 **0=PASS / 1=构建失败 / 2=环境错误（UV4/工程/档案）/ 3=用法 / 4=build 锁被占用**；日志 `MDK-ARM/build_log.txt`；换机必设 `DTU_KEIL_UV4` → 细节 **`keil-build` skill** + `docs/环境与部署/本地工具路径环境变量方案.md`
|
||||
- `@test` = `& '.venv\Scripts\python.exe' .dsh\skills\serial-boot-test\scripts\run_boot_test.py`：开串口+清日志 → 烧录（**固件身份戳**保证烧进去的就是这份构建、**回读校验**）→ wait-idle → 采日志 → 标记校验（含启动锚点计数）。退出码 **0=PASS / 1=FAIL / 2=采集或烧录错误 / 3=用法**；戳提取规则、锚点计数判据与按模块定制标记见 `docs/测试说明/流程与规范/自动化测试流程.md`
|
||||
- **门禁时机（用户裁定 2026-10-13）**：`/keil-build` / `scripts/ci_local.py` / `check_doc_links.py` **只在准备提交时跑**（用户让 commit 后统一跑一遍），**不是每次中间改动后都跑**——多步改动期间直接改即可，验证集中在提交门禁；`/serial-boot-test` 硬件闭环仍按任务需要跑
|
||||
- **`/keil-build` / `/serial-boot-test` / `/task-worktree` 是 DSH 会话的技能调用名、不是 shell 命令**（bash 里直接敲是 command not found / syntax error）——下面 `=` 后的命令行才是可执行形态（PowerShell 形态，bash 下路径正斜杠）
|
||||
- **编译**（`/keil-build`）= `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`（仓库根执行）。退出码 **0=PASS / 1=构建失败 / 2=环境错误（UV4/工程/档案）/ 3=用法 / 4=build 锁被占用**；日志 `MDK-ARM/build_log.txt`；换机必设 `DTU_KEIL_UV4` → 细节 **`keil-build` skill** + `docs/环境与部署/本地工具路径环境变量方案.md`
|
||||
- **串口回归**（`/serial-boot-test`）= `& '.venv\Scripts\python.exe' .dsh\skills\serial-boot-test\scripts\run_boot_test.py`：开串口+清日志 → 烧录（**固件身份戳**保证烧进去的就是这份构建、**回读校验**）→ wait-idle → 采日志 → 标记校验（含启动锚点计数）。退出码 **0=PASS / 1=FAIL / 2=采集或烧录错误 / 3=用法**；戳提取规则、锚点计数判据与按模块定制标记见 `docs/测试说明/流程与规范/自动化测试流程.md`
|
||||
- Forbidden 标记含 `[ERR]`：**四个 Fault 的崩溃日志都以 `[ERR]` 开头 → 出现 Fault 即本次不通过**（刻意）
|
||||
- **烧录必须 `-Rst -Run`**（`stlink-flash` skill 的 `flash`）：裸 `-P` 会报 `Programming Complete`，但目标核处于死循环/异常时写入并不落地（"反复重下载、芯片一直是旧镜像、二分法失效"的根因）。**烧后必须回读校验**（`stlink_flash.py cmp` = `-CmpFile`，`No difference found` 才算真正写入）；⚠ `-CmpFile` 连接时会**复位目标** → 必须排在**采日志之后** → `docs/测试说明/测试工具/ST-LINK_CLI_复位使用说明.md`
|
||||
- ⚠️ 旧绝对路径 `D:\Code\DTU 程序\...` 出现即失效（仓库已搬迁），一律改用仓库相对路径
|
||||
@@ -99,7 +99,7 @@
|
||||
- ⚠ **pre-commit 4.x 已移除 `always: true`**（实测对 `local` 钩子只告警 `Unexpected key(s)` 并跳过）→ 想"总是跑"的钩子**必须让 `files:` 覆盖到所有会触发它的文件**，没有兜底开关
|
||||
- **改写型钩子（`trailing-whitespace` + `end-of-file-fixer`）豁免 CubeMX/Keil 生成文件**（配置里 YAML 锚点 `&cubemx-generated`）；⚠ **只读检查不受影响**：`cppcheck` / 乱码 / `cubemx-survival` / `task-table` / `mem-numbers` 仍覆盖 `Src/`、`Inc/`
|
||||
- 提交信息：标题 ≤100 字符、**正文每行 ≤80**（`.gitlint` + gitlint 默认）→ 长说明一律用**短标题 + `git commit -F <UTF-8 无 BOM 文件>` 多行正文**（中文长标题极易超限，且 `-m` 会被终端代码页转码破坏）
|
||||
- **CI**（`.gitea/workflows/ci.yml`）只跑静态门禁 + 主机侧纯逻辑单测，**刻意不跑 `@build`**（需 Keil 授权）、不含采集链分层（需真机）。**远程 CI 的全部资料（服务端开关 / runner 部署与保活 / workflow / 排障 / 实测坑）集中在 [`docs/CI/README.md`](docs/CI/README.md)，不放本节**——它**只跑在本机一台 runner `win-stm32-ci` 上**，其他机器与项目都不涉及。日常改代码的等价自查是 `& '.venv\Scripts\python.exe' scripts/ci_local.py`（静态门禁 + 提交信息门禁 + 主机侧纯逻辑单测）——**runner 不在线也不影响本地门禁，不能因"已配 CI"放宽本地要求**
|
||||
- **CI**（`.gitea/workflows/ci.yml`）只跑静态门禁 + 主机侧纯逻辑单测，**刻意不跑 `/keil-build`**（需 Keil 授权）、不含采集链分层（需真机）。**远程 CI 的全部资料（服务端开关 / runner 部署与保活 / workflow / 排障 / 实测坑）集中在 [`docs/CI/README.md`](docs/CI/README.md)，不放本节**——它**只跑在本机一台 runner `win-stm32-ci` 上**，其他机器与项目都不涉及。日常改代码的等价自查是 `& '.venv\Scripts\python.exe' scripts/ci_local.py`（静态门禁 + 提交信息门禁 + 主机侧纯逻辑单测）——**runner 不在线也不影响本地门禁，不能因"已配 CI"放宽本地要求**
|
||||
|
||||
## 平台约束
|
||||
|
||||
@@ -115,7 +115,7 @@
|
||||
- **`osKernelStart` 之前禁止任何 FreeRTOS/CMSIS-RTOS 创建类 API**（`osMessageQueueNew` 等会杀死启动，2026-09-20 实证根因）→ 内核前标准模式（纯寄存器/HAL 轮询 + **无锁静态缓冲** + 内核启动后**惰性创建**真队列）见 `docs/架构设计/项目启动顺序管理.md`
|
||||
- **就绪屏障位必须 `osFlagsNoClear`**：`osEventFlagsWait` **默认消费**所等位，就绪位被先消费掉 → `ftpTask` 的 `WaitAll` 永不成立 → **FTP 21 端口静默不监听**（无日志无报错）。命令位（`SYS_EVT_CFG_SAVE`/`NET_RECONFIG`）保持消费型
|
||||
- **自研代码禁用 C 库堆分配**（`malloc/calloc/realloc/strdup/free`）：**2026-10-23 起由提交门禁机器拦截**（`coding-standard` 的 CODE-RULE-20，唯一豁免 = 平台分配后端的宿主侧实现，见 `docs/门禁说明/coding-standard.md` §7）：MicroLIB 的 C 堆由 `startup_stm32f407xx.s` 的 `Heap_Size EQU 0x200` 限定为 **512 B**，KB 级分配必然返回 NULL，而**模拟器（宿主 CRT 堆）完全正常、照不出来** → 只用 `pvPortMalloc/vPortFree`，或把分配收进平台后端 → `docs/内存管理/RAM使用分析与优化方案.md`
|
||||
- **内存预算紧张**：新增任何任务/缓冲/栈前先核算 RAM 余量；改栈或加大局部变量**前后各跑一次** `scripts/stack_report.py`（静态最坏链 + 串口 `[STACK]` 水位）与 `scripts/ram_report.py`（.map 静态占用）；**总量红线已机械化**：`mem-budget` 钩子拦 RW_IRAM1/RW_CCM >92%，子系统配额 / CCM 台账 / 趋势见 `docs/内存管理/RAM预算台账.md`（**每次 `@build` 后跑 `scripts/ram_baseline.py --update`**）→ `docs/内存管理/`
|
||||
- **内存预算紧张**：新增任何任务/缓冲/栈前先核算 RAM 余量；改栈或加大局部变量**前后各跑一次** `scripts/stack_report.py`（静态最坏链 + 串口 `[STACK]` 水位）与 `scripts/ram_report.py`（.map 静态占用）；**总量红线已机械化**：`mem-budget` 钩子拦 RW_IRAM1/RW_CCM >92%，子系统配额 / CCM 台账 / 趋势见 `docs/内存管理/RAM预算台账.md`（**每次 `/keil-build` 后跑 `scripts/ram_baseline.py --update`**）→ `docs/内存管理/`
|
||||
- FreeRTOS V10.3.1（CMSIS-RTOS V2）；HAL 时基 = **TIM7**（非 SysTick），tick = 1ms；NVIC 4 位优先级分组，**外设中断优先级 ≥ 5**
|
||||
|
||||
**采集链（ADC / RS-485）**
|
||||
@@ -133,7 +133,7 @@
|
||||
**日志与工具链**
|
||||
|
||||
- **`DBG_*` 每条日志约 90 B Flash + 216 B 栈**（每个调用点内联行缓冲 + 时间戳缓冲）→ 日志不是免费的，已覆盖的步骤别加重复锚点，只在原先静默返回的黑洞处补；**深调用链模块在 `#include "dbg_log.h"` 之前 `#define DBG_LINE_BUF_MAX 128U`**（取值必须 ≥ 该模块最长日志行，否则该行被截断）
|
||||
- **`MDK-ARM/*.uvprojx` 每次 `@build` 后被 UV4 自动改写，改动一律不入库**（XML 归一化 + `PackID` 降到本机 DFP 版本）；判据与例外（真的增删源文件才提交）→ **`keil-build` skill**
|
||||
- **`MDK-ARM/*.uvprojx` 每次 `/keil-build` 后被 UV4 自动改写，改动一律不入库**（XML 归一化 + `PackID` 降到本机 DFP 版本）；判据与例外（真的增删源文件才提交）→ **`keil-build` skill**
|
||||
|
||||
## 硬件引脚
|
||||
|
||||
|
||||
Reference in New Issue
Block a user