wandering1
eddbedeee8
- AGENTS.md 51,067→25,828 B（−50%）：审计→迁移→删除，逐节 diff 零信息损失 - 按调研（agents.md 官方/aihero/airflow）补「项目概况」：一句话定位、 数据主线、顶层目录地图、分层边界；平台约束 17 条分 5 组 - 新增「边界（Ask first / Never）」：git commit/push 须明确指示首次入库 - 串口助手、LVGL 模拟器两节移入 serial-assistant / 新建 lvgl-simulator skill （开关语义按 main.c 实锤）；LVGL 两条实证坑移入 ui-verify skill - 9 条入口独有细节迁移至对应设计文档（存储/看门狗/启动顺序/文档规范/ pre-commit 使用说明/keil-build skill）；@test 细节指向自动化测试流程 - 新增 docs/AGENTS编写指南.md：六原则/模板/反模式/维护纪律 + 本仓案例 - 修正 3 处对 AGENTS 串口节的过时引用；docs/README.md 登记新文档
56 lines
3.3 KiB
Markdown
56 lines
3.3 KiB
Markdown
---
|
||
name: new-machine-setup
|
||
description: 换机/新克隆环境自检与搭建：venv 重建、DTU_* 工具路径环境变量（用户级、无管理员）、驱动确认、验收三连（selftest/build/list）。自带独立自检脚本 env_check.py（纯标准库），含"会话不继承用户级变量"实测坑。任何嵌入式项目通用模式。
|
||
whenToUse: 换新机器/新克隆要把环境搭起来、构建或烧录报"环境变量未设/工具找不到"、CI 之外任何机器第一次跑本项目、或怀疑本机环境缺件时。
|
||
---
|
||
|
||
# new-machine-setup — 换机环境自检与搭建
|
||
|
||
## 先跑自检（只读，不改任何东西）
|
||
|
||
```powershell
|
||
# cwd = 项目根目录
|
||
& <任一 python ≥3.10> ".dsh\skills\new-machine-setup\scripts\env_check.py"
|
||
```
|
||
|
||
逐项 PASS/WARN/FAIL + 缺件时打印**可直接执行的修复命令**；退出码 0=可用 / 1=有 FAIL。
|
||
|
||
## 搭建顺序（自检 FAIL 时的完整路径）
|
||
|
||
1. **venv**：`& <任一 python ≥3.10> -m venv .venv` →
|
||
`& '.venv\Scripts\python.exe' -m pip install -r requirements.txt`
|
||
（含 pyserial/fontTools/pre-commit；`requirements.txt` 必须纯 ASCII）。
|
||
PATH 默认 `python` 可能是 msys64 的——依赖第三方库的脚本一律用 `.venv`。
|
||
2. **工具路径环境变量**（用户级即可，无需管理员；约定见
|
||
`docs/环境与部署/本地工具路径环境变量方案.md`）：
|
||
```powershell
|
||
[Environment]::SetEnvironmentVariable('DTU_KEIL_UV4', '<本机>\UV4.exe', 'User')
|
||
[Environment]::SetEnvironmentVariable('DTU_STLINK_CLI', '<本机>\ST-LINK_CLI.exe', 'User') # 已入 PATH 可不设
|
||
```
|
||
语义统一：**显式设了但路径无效 = 立即报错不回退**；不设则走 PATH/自动发现。
|
||
3. **驱动**：CH340（调试串口）与 ST-Link 的 USB 驱动装好——
|
||
`Get-PnpDevice -Class Ports` 能看到 COMx、`stlink_flash.py list` 能看到探针 SN。
|
||
4. **验收三连**（全绿才算环境就绪）：
|
||
```powershell
|
||
& '.venv\Scripts\python.exe' .dsh/skills/serial-assistant/scripts/serial_tool.py selftest # 23/23 PASS
|
||
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py # exit 0
|
||
& '.venv\Scripts\python.exe' .dsh\skills\stlink-flash\scripts\stlink_flash.py list # 列出探针
|
||
```
|
||
|
||
## 实测坑（本会话两次撞上）
|
||
|
||
- **agent/服务派生的 shell 不继承"服务启动之后"设置的用户级环境变量**：
|
||
`keil_build.py` 报 exit 2 先分清"真没设"还是"没继承"——查
|
||
`[Environment]::GetEnvironmentVariable('DTU_KEIL_UV4','User')`，有值就
|
||
`$env:DTU_KEIL_UV4 = <该值>` 注入当前会话再跑，别急着让用户重设。
|
||
（`env_check.py` 对这种情况报 WARN 并给注入命令。）
|
||
- 换机后 COM 口几乎必变：只改 `.serialtest/config.json` 的 `portName`，
|
||
然后 `serial_tool.py restart`（daemon 启动时缓存配置）。
|
||
- 串口"拒绝访问"先查残留旧 daemon（`serial-assistant` skill「陷阱」节），不是驱动问题。
|
||
|
||
## 其它项目怎么套
|
||
|
||
模式通用：本机差异全部走 `*_TOOL_PATH` 类环境变量（显式无效=硬错）、
|
||
仓库内路径全部相对解析、环境就绪判据 = 三条独立验收命令（工具链构建 /
|
||
烧录器在位 / 采集自检），自检脚本只读不修、FAIL 行自带修复命令。
|