RT-Thread · silencebadwolf · Jun 3, 2026
diff --git a/README.md b/README.md
@@ -1,2 +1,25 @@
-# rtthread-skills
-SKILLs for RT-Thread &amp; Embedded System Developement
+# rtthread-skills
+
+SKILLs for RT-Thread & Embedded System Development
+
+## 技能列表
+
+| 技能 | 说明 | 适用范围 |
+|------|------|----------|
+| `rtthread-bsp-builder` | 查找官方 RT-Thread BSP 并按 BSP README 推动构建 | 官方 BSP + GCC/MDK/IAR/RT-Studio |
+| `rtconfig-kconfig-sync` | `.config` / `rtconfig.h` / `Kconfig` 同步检查 | RT-Thread 配置系统 |
+
+## 贡献规则
+
+- 一个 PR 只新增或修改一个 skill 主题
+- 通用 RT-Thread skill 不应把产品专属模板或编号项目布局作为默认行为
+- skill 内容应以官方 RT-Thread BSP 布局和 BSP README 为主要依据
+- 提交前请验证：frontmatter 校验、Python 语法检查、helper 脚本 help 输出
+
+## 目录结构
+
+```
+skills/
+├── rtthread-bsp-builder/    # RT-Thread 官方 BSP 构建助手
+└── rtconfig-kconfig-sync/   # rtconfig 与 Kconfig 配置同步
+```
diff --git a/skills/rtconfig-kconfig-sync/SKILL.md b/skills/rtconfig-kconfig-sync/SKILL.md
@@ -0,0 +1,152 @@
+---
+name: rtconfig-kconfig-sync
+description: 当修改 RT-Thread 项目的 rtconfig.h/.config/Kconfig 或执行 scons --menuconfig/defconfig/genconfig 时自动触发，确保配置同步。
+version: 1.2.0
+author: Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: ['embedded', 'mcu', 'rt-thread', 'kconfig', 'scons', 'config-sync']
+    related_skills: ['embedded-mcu', 'embedded-environment-config', 'gcc', 'keil']
+---
+
+# RT-Thread rtconfig.h 与 .config 同步检查
+
+## 触发条件
+
+当执行以下操作时自动触发：
+1. 修改 `rtconfig.h`（手动添加宏）
+2. 修改 `.config`（手动添加选项）
+3. 执行 `scons --menuconfig` / `--defconfig` / `--genconfig`
+4. 编译时出现 `RT_USING_XXX` 未定义错误
+
+## 核心概念
+
+RT-Thread 配置系统基于 Kconfig，核心链路：
+
+1. `Kconfig` 声明配置选项（`config BSP_USING_XXX`）
+2. `scons --menuconfig` 交互式选择，写入 `.config`
+3. `scons --defconfig` 从 `.config` 生成 `rtconfig.h`
+4. `scons --genconfig` 从 `rtconfig.h` 反向同步 `.config`
+
+**关键点**：
+- `.config` 是配置源头（由 menuconfig 或手动编辑产生）
+- `rtconfig.h` 是 C 头文件（由 defconfig 生成，供编译使用）
+- 两者之间的宏映射不是简单的一一对应，涉及前缀转换（`CONFIG_XXX` → `RT_USING_XXX`）
+
+## 检查步骤
+
+### 1. 检查同步状态
+
+```bash
+# 对比 .config 和 rtconfig.h 中的宏
+diff <(grep -E "^CONFIG_" .config | sort) \
+     <(grep -E "^#define RT_USING" rtconfig.h | sed 's/#define //' | sort)
+```
+
+### 2. 如果手动改了 rtconfig.h
+
+**必须执行**：
+```bash
+scons --genconfig  # 反向同步 .config
+```
+
+**验证**：
+```bash
+grep "CONFIG_BSP_USING_XXX" .config  # 应该存在
+```
+
+### 3. 如果手动改了 .config
+
+**必须执行**：
+```bash
+scons --defconfig  # 重新生成 rtconfig.h
+```
+
+**验证**：
+```bash
+grep "RT_USING_XXX" rtconfig.h  # 应该存在
+```
+
+### 4. 如果新增 BSP 选项
+
+**检查 Kconfig**：
+```bash
+# 在 BSP 目录下的 Kconfig 中查找
+find . -name "Kconfig" -exec grep -l "BSP_USING_XXX" {} \;
+```
+
+**如果缺失，添加**：
+```kconfig
+config BSP_USING_XXX
+    bool "Enable XXX"
+    default n
+    select RT_USING_YYY  # 如果有依赖
+```
+
+## 常见错误
+
+### 错误 1：手动改 rtconfig.h 没同步 .config
+
+**症状**：用 `scons --menuconfig` 改选项无效，`.config` 是 `not set`
+
+**修复**：
+```bash
+scons --genconfig  # 同步
+```
+
+### 错误 2：新选项没在 Kconfig 定义
+
+**症状**：`scons --menuconfig` 看不到新选项
+
+**修复**：在 BSP 或相关模块的 `Kconfig` 里添加 `config BSP_USING_XXX`
+
+### 错误 3：编译报宏未定义
+
+**症状**：`error: 'RT_USING_XXX' undeclared`
+
+**修复**：
+1. 检查 `.config` 里是否有 `CONFIG_XXX=y`
+2. 如果没有，用 `scons --menuconfig` 启用
+3. 或手动加到 `.config`，再 `scons --defconfig`
+
+### 错误 4：package 宏消失
+
+**症状**：`scons --defconfig` 后 `PKG_USING_*` 宏在 rtconfig.h 中消失
+
+**修复**：
+1. 确认 package 的 `Kconfig` 中有对应的 `config PKG_USING_XXX`
+2. 确认 `.config` 中有 `CONFIG_PKG_USING_XXX=y`
+3. 执行 `pkgs --update` 确保 package 已下载
+4. 重新 `scons --defconfig`
+
+## 最佳实践
+
+1. **优先用 `scons --menuconfig`**（自动同步，最安全）
+2. **如果 TUI 不可用**：
+   - 编辑 `.config`（源头）
+   - 执行 `scons --defconfig`（重新生成 `rtconfig.h`）
+3. **如果必须手动改 `rtconfig.h`**：
+   - 改完后执行 `scons --genconfig`（反向同步 `.config`）
+4. **新增选项前先查上游/原生开关**：
+   - 先在 RT-Thread、BSP、厂商 SDK、已有 `Kconfig` 中搜索是否已有控制项
+   - 例如 FinSH/MSH 已有 `RT_USING_MSH`、`RT_USING_FINSH`、`FINSH_USING_MSH`
+   - 若已有原生开关能满足需求，直接复用，不要自建重复 wrapper
+5. **新增选项**：
+   - 先在 `Kconfig` 里定义
+   - 再用 `scons --menuconfig` 启用
+6. **导出工程文件**：
+   - `CMakeLists.txt`、MDK/IAR/VS Code 工程文件是 SCons 导出物
+   - 新增/移动源码时先改 `SConscript`，再重新导出
+   - 不要直接手改生成的工程文件
+
+## 注意事项
+
+- 不同 RT-Thread 版本的 Kconfig 结构可能不同，操作前先确认版本
+- BSP 的 Kconfig 路径因芯片厂商而异，用 `find` 命令定位
+- `scons --defconfig` 和 `scons --genconfig` 的行为可能因版本有差异
+- 某些旧版 BSP 可能不支持 `scons --genconfig`
+
+## 参考
+
+- RT-Thread 文档：https://www.rt-thread.io/document/site/programming-manual/basic/basic/#内核配置
diff --git a/skills/rtthread-bsp-builder/README.md b/skills/rtthread-bsp-builder/README.md
@@ -0,0 +1,14 @@
+# rtthread-bsp-builder RT-Thread 官方 BSP 构建
+
+## 作用
+用于拉取或更新官方 RT-Thread 仓库，定位官方 BSP，检查 BSP 构建条件，并按官方 GCC 流程完成构建。
+
+## 何时使用
+当需求涉及确认 RT-Thread 是否官方支持某个芯片或板卡、选择官方 BSP，或让官方 BSP 按文档流程成功编译时使用。
+
+## 主要文件
+- `SKILL.md`：skill 定义、触发条件和完整工作流
+
+## 备注
+这个 README 用来快速说明该 skill 是做什么的，便于在技能工作区里浏览和维护。
+
diff --git a/skills/rtthread-bsp-builder/SKILL.md b/skills/rtthread-bsp-builder/SKILL.md
@@ -0,0 +1,166 @@
+---
+name: rtthread-bsp-builder
+description: 克隆或更新官方 RT-Thread 仓库，可按需让用户选择分支、标签或提交，查找指定芯片或板卡的官方 BSP，检查 BSP 的 README 与 rtconfig，并按官方工作流推动其完成构建（GCC/MDK/IAR/RT-Studio）。当处理 RT-Thread MCU 或嵌入式项目，且需要回答"官方是否支持这个芯片或板卡"、选择版本、设置官方 BSP、运行 menuconfig/pkgs/scons 时使用。如果没有可信的官方 BSP，就明确停止，不要自行虚构或移植。
+version: 1.1.0
+author: Hermes Agent
+license: MIT
+metadata:
+  hermes:
+    tags: ['rt-thread', 'bsp', 'mcu', 'gcc', 'keil', 'iar', 'scons', 'embedded']
+    related_skills: ['embedded-mcu', 'embedded-environment-config', 'gcc', 'keil']
+---
+
+# RT-Thread 官方 BSP 构建助手
+
+这个 skill 只适用于 **官方 `RT-Thread/rt-thread` 仓库中已经存在的官方 BSP**。
+
+不要新建 BSP、不要从零移植芯片、不要克隆第三方 fork，也不要把“看起来差不多”的 BSP 当成可替代方案。如果不存在可信的官方 BSP，就明确说明并停止。
+
+## 范围
+
+本技能覆盖：
+
+- 官方 `RT-Thread/rt-thread`
+- 已存在于 `bsp/` 下的官方 BSP
+- 根据 BSP README 支持的构建目标：GCC、MDK、IAR、RT-Studio
+- 关键选择点上与用户交互确认
+
+当前不在范围内的包括：
+
+- 新 BSP 创建或新芯片移植
+- 厂商 fork 支持
+- 静默替换 BSP
+- 自动烧录
+- 自动安装系统级软件包
+- 自动修改全局环境
+
+## 构建目标选择
+
+**不要假设 GCC 是唯一或优先目标。** 根据 BSP README 和用户需求决定：
+
+| 目标 | scons 命令 | 典型产物 |
+|------|-----------|----------|
+| GCC | `scons` | `rtthread.bin`, `rtthread.elf` |
+| MDK | `scons --target=mdk5` | `project.uvprojx` |
+| IAR | `scons --target=iar` | `project.eww` |
+| RT-Studio | `scons --target=eclipse` | `.cproject` |
+
+如果 BSP README 明确推荐 MDK 或 IAR，不要强行走 GCC。
+
+## 必须交互的节点
+
+不要跳过会影响可复现性的关键决策。
+
+必要时向用户确认：
+
+1. **仓库版本**
+   - 如果用户没有指定版本，要询问是使用：
+     - 默认分支最新版本
+     - 某个分支
+     - 某个标签
+     - 某个具体提交
+   - 需要时可用 `scripts/list_refs.sh` 展示候选分支或标签。
+   - 用 `scripts/ensure_repo.sh --dest <path> --ref <ref>` 检出指定版本。
+
+2. **BSP 选择存在歧义时**
+   - 如果存在多个较强候选 BSP，需要展示出来并让用户选择。
+
+3. **构建目标**
+   - 如果 BSP 支持多个构建目标，让用户选择。
+
+4. **可能影响宿主环境的操作**
+   - 安装 `scons`、`pkgs`、交叉编译工具链或系统软件包前，必须得到用户确认。
+
+## 工作流程
+
+1. **先明确目标**
+   - 如果请求比较模糊，先问清楚具体芯片或板卡。
+   - 如果没有指定 RT-Thread 版本，先问清楚要用哪个版本。
+
+2. **确保官方仓库存在**
+   - 使用 `scripts/ensure_repo.sh --dest <path>`。
+   - 如需固定版本，增加 `--ref <branch|tag|commit>`。
+   - 如果仓库已存在且有未提交改动，不要强行覆盖。
+
+3. **查找 BSP**
+   - 使用 `scripts/find_bsp.py --repo <repo> --query <chip|board>`。
+   - 只有在结果是以下情况时才继续：
+     - `exact`
+     - 或单个 `strong` 官方匹配
+   - 如果结果是 `ambiguous`，让用户选择。
+   - 如果结果是 `none`，明确告诉用户没有官方 BSP，并停止。
+
+4. **构建前先检查**
+   - 使用 `scripts/inspect_bsp.py --repo <repo> --bsp <bsp>`。
+   - 然后自行阅读 BSP README。
+   - 特别关注：
+     - 需要的工具链和前缀
+     - 是否强制要求 `pkgs --update`
+     - 是否必须走 `menuconfig`
+     - 该 BSP 支持哪些构建目标（GCC/MDK/IAR/RT-Studio）
+
+5. **先跑预检查**
+   - 使用 `scripts/build_bsp.sh --repo <repo> --bsp <bsp> --preflight`。
+   - 这一步会检查 BSP 路径、README 提示、`scons`、可选 `pkgs` 以及编译器前缀。
+   - 如果宿主环境缺前置条件，就停止并明确告知缺什么。
+
+7. **按官方顺序构建**
+   - 先阅读 README，再按 README 执行。
+   - 常见顺序是：
+     1. `pkgs --update`，如果 README 或 BSP 要求
+     2. 仅在有要求或用户明确希望改配置时，再执行 `scons --menuconfig` 或 `menuconfig`
+     3. 根据目标执行构建：
+        - GCC: `scons -j$(nproc)`
+        - MDK: `scons --target=mdk5`
+        - IAR: `scons --target=iar`
+   - **Windows 用户**：RT-Thread Env 环境下 `pkgs` 可能是 `pkgs.exe`，不要只依赖 `command -v pkgs`。
+
+8. **只有真实编译成功后才能宣称成功**
+   - “预检查通过” 不等于 “编译通过”。
+   - 汇报时要包含：
+     - 仓库路径与检出版本
+     - BSP 路径
+     - 使用了哪个 README
+     - 使用了哪个构建目标
+     - 实际执行了哪些命令
+     - 产物路径，例如 `rtthread.bin`、`.elf`、`.hex`、`project.uvprojx`
+     - 仍然缺少的工具链或软件包条件
+
+## 安全规则
+
+- 如果 **没有官方 BSP**，必须明确说明并停止。
+- 不要静默替换为别的 BSP。
+- 除非用户明确要求，不要安装系统软件包、烧录硬件或修改全局 shell 启动文件。
+- 更新或检出 RT-Thread 仓库时，不要覆盖脏工作区。
+- 优先使用默认配置，不要随意引入不必要的 `menuconfig` 变更。
+
+## 脚本说明
+
+- `scripts/list_refs.sh`
+  - 列出官方 RT-Thread 分支和标签，便于用户选版本。
+- `scripts/ensure_repo.sh`
+  - 克隆官方 RT-Thread 仓库，或安全地报告/更新已存在仓库。
+  - 支持 `--ref <branch|tag|commit>`。
+- `scripts/find_bsp.py`
+  - 按芯片或板卡关键词搜索官方 BSP，并区分 exact / strong / ambiguous / none。
+- `scripts/inspect_bsp.py`
+  - 解析 BSP 并汇总 README、工具链和构建提示。
+- `scripts/build_bsp.sh`
+  - 执行预检查和默认 GCC 构建流程。
+
+## 参考资料
+
+- `references/common-build-flow.md`
+  - 对澄清目标、选择版本、定位 BSP、预检查、构建和汇报的决策规则说明。
+- `references/common-failures.md`
+  - 常见 RT-Thread BSP 构建失败场景，以及下一步该检查什么。
+
+## 推荐默认做法
+
+- 优先使用官方仓库，而不是镜像或 fork。
+- 优先以 BSP README 为准，而不是泛泛的 RT-Thread 通用建议。
+- 根据 BSP README 推荐的构建目标来选择，不要默认假设 GCC。
+- 如果 README 要求 `pkgs --update`，不要静默跳过。
+- 如果因为缺少工具链而无法继续，要明确告诉用户缺的编译器前缀或环境变量。
+- `pkgs` 检测应支持 Env 下的显式路径（如 `pkgs.exe`），不能只依赖 `command -v pkgs`。
+
diff --git a/skills/rtthread-bsp-builder/capability.json b/skills/rtthread-bsp-builder/capability.json
@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "type": "skill",
+  "id": "rtthread-bsp-builder",
+  "displayName": "rtthread-bsp-builder",
+  "summary": "克隆或更新官方 RT-Thread 仓库，可按需让用户选择分支、标签或提交，查找指定芯片或板卡的官方 BSP，检查 BSP 的 README 与 rtconfig，并按官方工作流推动其完成 GCC 构建。当处理 RT-Thread MCU 或嵌入式项目，且需要回答“官方是否支持这个芯片或板卡”、选择版本、设置官方 BSP、运行 menuconfig/pkgs/scons，或让官方 BSP 编译通过时使用。如果没有可信的官方 BSP，就明确停止，不要自行虚构或移植。",
+  "legacyAliases": [],
+  "status": "migrated"
+}