refactor(docs): point entry-file references at their new homes
AGENTS.md stopped being the store of record for build steps, Python env, hardware pins, doc conventions, log cost and task ownership. Those facts already live in docs, skills and role files; the entry file now only points at them. This commit moves every reference that used to name the entry file to the authoritative landing point, so a reader who follows a link arrives at the fact instead of at a sentence that no longer exists. What changed is links and prose, not behaviour. Code, scripts and tests only have comment and docstring lines touched; the only non-comment edit in the whole changeset is one note string inside the generated pin table JSON, and its generator was changed in the same step so the two stay byte-identical. New landing points created before the references were retargeted: - The console single-writer log design doc, section 7.1, is now the single authority for log cost: about 90 B flash and 216 B stack per DBG_ line, and the rule that deep call chains must predefine DBG_LINE_BUF_MAX. It also carries the full list of the twelve translation units that have tightened it, plus the grep command that decides the truth if the list and the code ever disagree. - The document writing standard, section 2, now holds the BOM list. - keil-build skill gains an exit code table: 0 success, 1 build failure, 2 BuildEnvError, 3 usage, 4 build lock held. This corrects a belief that was never actually written down anywhere: exit 2 does not simply mean environment error, argparse also exits 2 and the wrapper script was remapped so the two no longer collide. Regenerated and checked byte for byte: - The end-to-end architecture SVG in docs/images from its generator. - tools/netlist_semantics/pinout_kb.json from gen_kb.py. Both are idempotent; running the generators again produces no diff. Deliberately not touched, because machines read them: - scripts/check_bom_drift.py joins every line containing BOM and asserts four paths are present, so the entry file BOM line must stay one line. - scripts/gen_task_table.py reads the TASK_TABLE anchors directly. - scripts/rename_maps and scripts/archive keep their historical wording; they describe what happened, not what is true now. Verified: doc links report the same six pre-existing findings as the base commit and no new ones, generated-fresh passes, bom drift is clean across 101 files, and AGENTS.md itself is unchanged in this commit.
This commit is contained in:
@@ -178,7 +178,7 @@ MCU 端 `Drivers/BSP/dbg_log.h` 会引用 `sys_clock.h`(RTC 时间戳),PC
|
||||
1. **`SDL2/SDL.h` 找不到**:需先执行 3.1 的 `include/SDL2/` 头文件复制步骤。
|
||||
2. **`lv_conf.h` 找不到**:`LV_CONF_DIR` 必须在 `add_subdirectory(lvgl)` **之前**定义(CMake 变量顺序问题)。当前 CMakeLists 已正确处理,勿随意调整顺序。
|
||||
3. **改 CMakeLists.txt 后不生效**:MSVC 生成器可能缓存旧配置,先删 `build/` 重建。
|
||||
4. **中文字符串文件编码**:源码是 UTF-8,CMake 已加 `/utf-8` 编译选项消除 C4819 警告。**不要**用 PowerShell `Set-Content` 等重写含中文的文件(参照 AGENTS.md 编码铁律)。
|
||||
4. **中文字符串文件编码**:源码是 UTF-8,CMake 已加 `/utf-8` 编译选项消除 C4819 警告。**不要**用 PowerShell `Set-Content` 等重写含中文的文件(参照 `docs/文档规范.md` §2 编码铁律)。
|
||||
|
||||
### 6.2 渲染相关
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@
|
||||
|
||||
安装完成后验证可用:`lv_font_conv -h` 能打印用法即成功。
|
||||
|
||||
> **Python 解释器(统一入口)**:用仓库内 `.venv`(已装 fontTools,见 AGENTS.md「Python 环境」):
|
||||
> **Python 解释器(统一入口)**:用仓库内 `.venv`(已装 fontTools,重建见 `new-machine-setup` skill):
|
||||
>
|
||||
> ```powershell
|
||||
> & '.venv\Scripts\python.exe' tools/font_gen/make_font.py
|
||||
|
||||
@@ -51,7 +51,7 @@ flowchart TD
|
||||
| C3 | 字符集 | 子集字体(当前 224 汉字/符号 + ASCII 0x20-0x7E,共 319 字形);**缺字显示空白**;新字必须重生成字体 | `tools/font_gen/` |
|
||||
| C4 | LVGL 内存池 | 16KB(`LV_MEM_SIZE`,2026-10-15 由 40KB 收缩;实测峰值 6,568 B = 池的 40%);任一时刻只放"当前导航路径 + 当前内容页" | `Lib/lv_conf.h` |
|
||||
| C5 | 文本 | 一律静态字符串(`lv_label_set_text_static`),禁止动态字符串/strdup | 架构文档 |
|
||||
| C6 | 编码 | `Drivers/BSP/UI/*`、`ui_task.c`、`Lib/lv_conf.h` 为 **UTF-8 带 BOM**;改动只用 Edit 工具,**禁止** PowerShell/cmd 整文件重写(U+FFFD 不可逆) | AGENTS.md 铁律 |
|
||||
| C6 | 编码 | `Drivers/BSP/UI/*`、`ui_task.c`、`Lib/lv_conf.h` 为 **UTF-8 带 BOM**;改动只用 Edit 工具,**禁止** PowerShell/cmd 整文件重写(U+FFFD 不可逆) | `docs/文档规范.md` §2 |
|
||||
| C7 | 代码共用 | `ui_menu.c` / 字体为 MCU 与模拟器共用源,**禁止**在 `simulator/` 复制副本 | 架构文档 |
|
||||
| C8 | 视觉禁区(1bpp) | 圆角 / 阴影 / 透明度 / 渐变 / 多色 / 抗锯齿 全部禁用;设计与代码都不得引入 | 物理限制 |
|
||||
| C9 | 双端注册 | 新增 `Drivers/BSP/UI/*.c` 必须**两处**手动注册:Keil `.uvprojx` + `simulator/CMakeLists.txt` 的 `UI_SOURCES` 列表(均为显式列表,无通配扫描)。只注册一端 = 另一端静默缺文件 | 实测(2026-09-03) |
|
||||
@@ -187,7 +187,7 @@ flowchart TD
|
||||
3. & '.venv\Scripts\python.exe' tools/font_gen/make_font.py # 宋体 12px 1bpp + ASCII + 字符集 → ui_font_cn_12.c(全量重生成 + 自动补回宋体缺失的 ▶ 箭头,幂等;需 fontTools)
|
||||
4. 生成物 diff 检查:新增字在位、旧字不变、Opts 行字符集与预期一致
|
||||
```
|
||||
- 一次性环境准备:`npm i -g lv_font_conv`;fonttools/pillow 统一装进仓库 `.venv`(`.venv\Scripts\python.exe -m pip install -r requirements.txt`,见 AGENTS.md「Python 环境」)。PATH 默认 python 是 msys64 的、无第三方库,勿用它跑 make_font.py
|
||||
- 一次性环境准备:`npm i -g lv_font_conv`;fonttools/pillow 统一装进仓库 `.venv`(`.venv\Scripts\python.exe -m pip install -r requirements.txt`,重建见 `new-machine-setup` skill)。PATH 默认 python 是 msys64 的、无第三方库,勿用它跑 make_font.py
|
||||
- `ui_cn_chars.txt`(仓库根,受 git 跟踪)与 `ui_font_cn_12.c` **随代码一起提交**
|
||||
- 双端 `LV_FONT_DEFAULT` 均指向 `&ui_font_cn_12` → 重生成后两端自动生效
|
||||
- P0 已知的新增字若含生僻字(宋体可能无此字形)→ 在写码前先手动验证字形,避免"代码写完才发现是空白"
|
||||
@@ -248,7 +248,7 @@ flowchart TD
|
||||
|
||||
## 六、P3:MCU 验证
|
||||
|
||||
1. `/keil-build` → **0 错误 0 警告**(AGENTS.md 强制;有警告看 `MDK-ARM/build_log.txt`)
|
||||
1. `/keil-build` → **0 错误 0 警告**(`keil-build` skill 的判定口径;有警告看 `MDK-ARM/build_log.txt`)
|
||||
2. `/serial-boot-test`(一键 `.dsh/skills/serial-boot-test/scripts/run_boot_test.py`):
|
||||
- 采集窗口**先于烧录武装**(脚本 `--flash-cmd` 已保证顺序)
|
||||
- Required:`UI port init: OK;UI menu init: OK` + 本界面定制标记(按屏增补,如页头标题字样)
|
||||
|
||||
@@ -10,12 +10,12 @@
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 模拟器已构建 | 仓库根目录:`& "simulator\build_sim.bat"`(自动探测本机 VS2019/2022/2026 生成器,见 `simulator/README.md` §3.2) |
|
||||
| Python | 统一入口 `.venv\Scripts\python.exe`(AGENTS.md「Python 环境」);两个回归脚本纯标准库,任意 python3 均可,为保持一致一律用 .venv |
|
||||
| Python | 统一入口 `.venv\Scripts\python.exe`(重建见 `new-machine-setup` skill);两个回归脚本纯标准库,任意 python3 均可,为保持一致一律用 .venv |
|
||||
|
||||
## 二、流程总览
|
||||
|
||||
```powershell
|
||||
# 仓库根目录执行(python 统一用 .venv,见 AGENTS.md「Python 环境」)
|
||||
# 仓库根目录执行(python 统一用 .venv,重建见 new-machine-setup skill)
|
||||
cmake --build simulator/build --config Debug # 0) 构建模拟器(须 0 警告)
|
||||
.venv\Scripts\python.exe simulator/tests/check_menu_rows.py # 1) 菜单 8 状态像素回归 + 池基线门禁
|
||||
.venv\Scripts\python.exe simulator/tests/check_content_pages.py # 2) 内容页黄金参考回归 + 往返池门禁
|
||||
|
||||
@@ -46,7 +46,7 @@ MCU **无物理屏幕**:LVGL 做 160×160 **1bpp 单色离屏渲染**,帧缓
|
||||
1. **RAM 紧张**:新增页面/控件/缓冲前必须核算 LVGL 池(16KB,实测峰值 6,568 B)与任务栈余量(见 `docs/内存管理/RAM预算台账.md`)
|
||||
2. **新增汉字必须重新生成字体**(`tools/font_gen/` 两步),否则显示空白
|
||||
3. 文本一律用静态字符串(`lv_label_set_text_static`),不 strdup
|
||||
4. UI 相关文件为 **UTF-8 带 BOM**(`Drivers/BSP/UI/*`、`ui_task.c`、`Lib/lv_conf.h`),其余源码无 BOM;禁止 PowerShell 整文件重写(编码铁律,见 AGENTS.md)
|
||||
4. UI 相关文件为 **UTF-8 带 BOM**(`Drivers/BSP/UI/*`、`ui_task.c`、`Lib/lv_conf.h`),其余源码无 BOM;禁止 PowerShell 整文件重写(编码铁律,见 `docs/文档规范.md` §2)
|
||||
5. 模拟器与 MCU **共用** UI 源码(`ui_menu*.c` / `ui_font_cn_12.c`),禁止在 `simulator/` 下复制副本;新增文件须同时注册进 Keil `.uvprojx` 与模拟器 CMakeLists(双端注册)
|
||||
6. 验证顺序:模拟器预览 → `/keil-build`(0 错 0 警)→ `/serial-boot-test`(Required 加 `UI port init: OK;UI menu init: OK`)
|
||||
7. **`LV_DRAW_SW_COMPLEX` 必须为 1**(两端均显式声明):主界面顶部"开口浅 V"装饰含斜线,`lv_line` 的斜段仅在复杂渲染器下绘制(`draw_line_skew`),关闭则只画水平线、两腿消失。且 `LV_DRAW_SW_CIRCLE_CACHE_SIZE` 须非零(默认 4),否则零长数组编译报错(C2466)
|
||||
|
||||
+1
-1
@@ -419,7 +419,7 @@ extern const content_page_def_t ui_page_device_info_desc; /* 描述符(Flash
|
||||
- 行表 `s_rows[]` 是模块私有(`static`),只有描述符对象是外部链接
|
||||
- 动态页的差异:`rows = NULL`,改在描述符里给 `refresh`(逐行取数),行数变化再给 `count_cb`
|
||||
- 文件编码:`Drivers/BSP/UI/` 下为 **UTF-8 带 BOM**(中文字面量依赖 BOM 让 MSVC 认 UTF-8,
|
||||
见 AGENTS.md 编码铁律)
|
||||
见 `docs/文档规范.md` §2 编码铁律)
|
||||
|
||||
## 六、执行上下文与内存
|
||||
|
||||
|
||||
Reference in New Issue
Block a user