为自建代码目录补齐 README，建立目录级导航体系

- 新增 26 份目录 README：App/(+log,task,util,protocol)、Drivers/BSP/(+8子系统)、 Src/、Inc/、scripts/、tools/(+6子工具)、test/、MDK-ARM/、simulator/(+sim,tests) - 每份含：定位、文件清单表、关键约束/陷阱、指向 docs 权威文档 - 第三方库与生成代码目录排除（CMSIS/HAL/Middlewares/Lib/SDL2） - docs/文档规范.md 新增 §1.1b 代码目录 README 约定；根 README 目录结构加入说明
2026-09-26 12:25:36 +08:00
parent 8d86fb1149
commit 39bd06adea
31 changed files with 1149 additions and 0 deletions
@@ -0,0 +1,44 @@
+# tools/ — 开发工具
+
+> 面向开发者的**功能性工具**（生成器 / 转换器 / 交互工具）。
+> 与 `scripts/`（质量门禁与度量）分工不同：本目录产出**资产**（图、字体、代码、知识库）。
+
+## 工具一览
+
+| 目录 | 工具 | 产物 | 文档 |
+|---|---|---|---|
+| `arch_diagram/` | 架构图 SVG 生成器 | `docs/images/*.svg` | `docs/架构设计/图形绘制流程.md` |
+| `font_gen/` | 中文字库生成 | `Drivers/BSP/UI/ui_font_cn_12.c` | `docs/UI设计/UI_中文字体生成与配置.md` |
+| `menu_gen/` | 菜单树代码生成 | UI 菜单代码 | `docs/UI设计/菜单页面设计.md` |
+| `netlist_semantics/` | 网表语义分析 | 引脚知识库 JSON + 网表报告 | `docs/硬件平台/` |
+| `refgraph/` | 文件引用关系图 | `docs/images/引用关系图.*` | `docs/架构设计/引用关系图说明.md` |
+| `serial_tool/` | Python 串口助手 | 日志状态（`state/`） | `docs/测试说明/串口助手使用指南.md` |
+
+## 使用方式
+
+```bash
+# 架构图（精确布局）
+& '.venv\Scripts\python.exe' tools/arch_diagram/gen_memory_svg.py
+
+# 中文字体（含新汉字文案后必须重跑）
+& '.venv\Scripts\python.exe' tools/font_gen/make_font.py
+
+# 引用关系图
+& 'tools\refgraph\gen_refgraph.bat'
+
+# 串口助手（常驻 daemon）
+& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py
+```
+
+## ⚠️ 约定
+
+- **生成器的产物与脚本一并提交**（如 SVG）；本地预览产物（如 PNG）不提交
+- 图表选型：精确布局图用 `arch_diagram/` 生成器；拓扑图（流程/时序/状态机）用 Mermaid；
+  **勿手绘 ASCII 框图**（见 `docs/架构设计/图形绘制流程.md`）
+- 涉及 UI 改动：走 `ui-verify` skill 五步门禁；涉及字体：走 `font-regen` skill
+
+## 相关文档
+
+- `docs/架构设计/图形绘制流程.md` — 配图规范与选型
+- `docs/架构设计/引用关系图说明.md`
+- `docs/测试说明/串口助手使用指南.md`、`docs/测试说明/串口助手设计说明.md`
@@ -0,0 +1,35 @@
+# tools/arch_diagram/ — 架构图 SVG 生成器
+
+> 用 Python 脚本**精确生成**架构类 SVG 图（分层、内存布局、协议帧、屏障等），
+> 产物放 `docs/images/`。用于"必须精确布局"的图；拓扑图（流程/时序/状态机）改用 Mermaid。
+
+## 脚本一览
+
+| 脚本 | 产物 | 用途 |
+|---|---|---|
+| `gen_arch_svg.py` | 架构分层图 | 六层分层结构 |
+| `gen_memory_svg.py` | 内存布局图 | RAM / Flash 分区 |
+| `gen_storage_stack_svg.py` | 存储栈图 | FTL / dhara / FatFs 三层栈 |
+| `gen_net_stack_svg.py` | 网络栈图 | BSD 网络栈分层 |
+| `gen_barrier_svg.py` | 就绪屏障图 | Event Flags 屏障模型 |
+| `gen_frame_svg.py` | 协议帧格式图 | RemoDispBus 帧结构 |
+| `gen_cfg_arch_svg.py` | 配置引擎架构图 | 配置分层与持久化 |
+| `gen_partition_svg.py` | 分区图 | 存储分区 |
+
+## 使用方式
+
+```bash
+& '.venv\Scripts\python.exe' tools/arch_diagram/gen_memory_svg.py
+```
+
+产物统一输出到 `docs/images/`；**脚本与生成的 `.svg` 一并提交**。
+
+## ⚠️ 约定
+
+- 颜色/字体遵循 `docs/架构设计/图形绘制流程.md` 的规范
+- 中文用 SVG `<text>` 直接写（需注意字体族声明）
+- 改图**改脚本再重跑**，不手改 SVG（保证可复现）
+
+## 相关文档
+
+- `docs/架构设计/图形绘制流程.md` — 配图规范、选型与检查清单
@@ -0,0 +1,30 @@
+# tools/font_gen/ — 中文字库生成
+
+> 从**字符集清单**生成 LVGL 用的中文字库 C 文件（子集化，只嵌入用到的汉字以节省 Flash）。
+
+## 脚本一览
+
+| 脚本 | 作用 |
+|---|---|
+| `extract_cn.py` | **提取汉字**：扫描 UI 源码的字符串字面量，输出字符集清单 `ui_cn_chars.txt` |
+| `make_font.py` | **生成字库**：按字符集从 TTF 生成 `Drivers/BSP/UI/ui_font_cn_12.c` |
+
+## 使用方式
+
+```bash
+# 新增含汉字的 UI 文案后：先提取字符集，再生成字库
+& '.venv\Scripts\python.exe' tools/font_gen/extract_cn.py
+& '.venv\Scripts\python.exe' tools/font_gen/make_font.py
+```
+
+## ⚠️ 注意
+
+- **含新汉字的 UI 文案提交前必须重跑**（走 `font-regen` skill）——否则新字显示为空白/方块
+- 产物 `ui_font_cn_12.c` **带 UTF-8 BOM**，勿手改（由脚本生成）
+- 字库大小直接影响 Flash 占用，只嵌入实际使用的字符
+- 依赖 `fontTools` / `Pillow`（已装在 `.venv`）
+
+## 相关文档
+
+- `docs/UI设计/UI_中文字体生成与配置.md`
+- `docs/UI设计/UI_设计架构.md`
@@ -0,0 +1,28 @@
+# tools/menu_gen/ — 菜单代码生成
+
+> 从**菜单树定义**生成 UI 菜单的 C 代码，保证菜单结构与页面注册一致、避免手写遗漏。
+
+## 脚本一览
+
+| 脚本 | 作用 |
+|---|---|
+| `gen_menu.py` | 读取菜单树定义（见 `ui_menu_tree.txt`）→ 生成菜单代码 |
+
+## 使用方式
+
+```bash
+& '.venv\Scripts\python.exe' tools/menu_gen/gen_menu.py
+```
+
+菜单树输入的权威副本：仓库根 `ui_menu_tree.txt`。
+
+## ⚠️ 注意
+
+- 生成产物**勿手改**（会被下次生成覆盖）；要改菜单结构改**定义源**后重跑
+- 中文字符串字面量须为**纯 ASCII 安全**（见 `AGENTS.md` 编码铁律）——生成后的文案
+  如需汉字，须配套重跑字体生成（`tools/font_gen/`）
+
+## 相关文档
+
+- `docs/UI设计/菜单页面设计.md`
+- `docs/UI设计/内容页架构.md`
@@ -0,0 +1,29 @@
+# tools/netlist_semantics/ — 网表语义分析
+
+> 把电路**网表文件**（`.tel`）解析成"有语义的引脚知识库"，供生成引脚表与网表分析报告。
+
+## 脚本一览
+
+| 脚本 | 作用 |
+|---|---|
+| `netlist_sem.py` | 网表解析核心（把 `.tel` 网表 → 结构化的网络/引脚连接） |
+| `gen_kb.py` | 生成**引脚知识库** `pinout_kb.json` |
+| `pinout_kb.json` | 引脚知识库产物（MCU 引脚 ↔ 网络 ↔ 外设的映射） |
+
+## 使用方式
+
+```bash
+& '.venv\Scripts\python.exe' tools/netlist_semantics/netlist_sem.py <网表.tel>
+& '.venv\Scripts\python.exe' tools/netlist_semantics/gen_kb.py
+```
+
+## 输入 / 产物
+
+- **输入**：硬件网表 `.tel`（位于 `docs/硬件平台/`，如 `V0.0.tel`、`V0.1.tel`）
+- **产物**：`pinout_kb.json` + `docs/硬件平台/V0.0_网表详细分析报告.md`、`docs/硬件平台/V0.0_网表语义图.md`
+
+## 相关文档
+
+- `docs/硬件平台/V0.0_网表详细分析报告.md`
+- `docs/硬件平台/V0.0_网表语义图.md`
+- 硬件引脚表：根 `README.md`「外设接口」
@@ -0,0 +1,35 @@
+# tools/refgraph/ — 文件引用关系图
+
+> 扫描全仓库 `.c/.h` 的 `#include` 关系，生成**文件级 + 模块级引用关系图**（Graphviz）。
+
+## 文件一览
+
+| 文件 | 作用 |
+|---|---|
+| `gen_refgraph.bat` | 一键入口（调用 `gen_refgraph.py` + Graphviz 渲染） |
+| `gen_refgraph.py` | 扫描 `#include` → 生成 `.dot` → 渲染 `.svg` / `.json` |
+
+## 使用方式
+
+```bash
+& 'tools\refgraph\gen_refgraph.bat'
+```
+
+## 产物（放 `docs/images/`）
+
+| 产物 | 内容 |
+|---|---|
+| `引用关系图.dot` | Graphviz 源 |
+| `引用关系图.svg` / `.png` | 渲染图（`.svg` 提交，`.png` 本地预览不提交） |
+| `引用关系图.json` | 结构化引用数据 |
+
+## ⚠️ 注意
+
+- **项目文件变化后重跑**更新（新增/删除源文件、改 include 关系）
+- 渲染依赖 **Graphviz**（`winget install graphviz` 可装）
+- 脚本与 `.dot`/`.svg`/`.json` **一并提交**
+
+## 相关文档
+
+- `docs/架构设计/引用关系图说明.md`
+- `docs/架构设计/项目架构总览.md`
@@ -0,0 +1,41 @@
+# tools/serial_tool/ — Python 串口助手
+
+> **常驻 daemon + CLI** 架构的串口工具：后台持续收串口日志，CLI 按需查询/发送，
+> 避免反复开关串口导致日志丢失（台架与测试的主力观测工具）。
+
+## 文件一览
+
+| 文件/目录 | 作用 |
+|---|---|
+| `serial_tool.py` | 串口助手主程序（daemon 与 CLI 合一） |
+| `state/` | **运行时状态目录** |
+| `state/serial.log` | 串口原始日志（`stack_report.py -s` 的输入之一） |
+| `state/daemon.log` | daemon 自身运行日志 |
+| `state/meta.json` | daemon 元数据（端口、状态等） |
+
+## 使用方式
+
+```bash
+# 启动 daemon / 打开串口
+& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py open COM6
+
+# 查询日志 / 发送命令
+& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py tail
+& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py send "<命令>"
+
+# 关闭
+& '.venv\Scripts\python.exe' tools/serial_tool/serial_tool.py close
+```
+
+> 具体子命令以 `--help` 为准。
+
+## ⚠️ 注意
+
+- **单写者**：串口同一时刻只能被一个进程占用——别同时用本工具和其它串口程序
+- `state/serial.log` 是 `[STACK]` 运行时水位的来源，`scripts/stack_report.py -s` 直接读它
+- `state/` 是运行时数据，**不入库**
+
+## 相关文档
+
+- `docs/测试说明/串口助手使用指南.md` — 命令用法 / 工作流 / 排障
+- `docs/测试说明/串口助手设计说明.md` — 契约 / daemon 行为 / 陷阱