docs: 添加 main 分支索引

Co-authored-by: Cursor <cursoragent@cursor.com>

.gitignore

@@ -0,0 +1,69 @@
+# =============================================================================
+# PY32F040 OTA 开发框架 — Git 忽略规则
+# 原则：只跟踪源码/工程/契约/文档；编译产物与 IDE 个人配置不入库
+# =============================================================================
+
+# ── Keil MDK 编译产物（App / Bootloader 两工程）────────────────────────────
+**/MDK-ARM/Objects/
+**/MDK-ARM/Listings/
+**/MDK-ARM/Output/
+
+# App 侧历史 hex 输出目录
+App/Output/
+
+# ── 顶层构建输出（build_all.py / merge_hex.py / pack.py）────────────────────
+Output/
+
+# ── Keil 个人/本地 IDE 配置 ─────────────────────────────────────────────────
+*.uvguix*
+*.uvoptx
+*.scvd
+**/MDK-ARM/Prg_Output.txt
+**/MDK-ARM/Build_Output.txt
+**/MDK-ARM/JLinkLog.txt
+
+# DebugConfig/*.dbgconf 建议保留入库（芯片调试配置，团队可共享）
+
+# ── 中间文件扩展名（散落于工程目录时兜底）──────────────────────────────────
+*.o
+*.d
+*.crf
+*.axf
+*.lnp
+*.dep
+*.htm
+*.map
+*.lst
+*.iex
+*.sct.bak
+*_sct.Bak
+*.bak
+
+# ── 固件二进制（应由 CI/本地构建生成，不入库）──────────────────────────────
+*.hex
+*.bin
+*.elf
+*.zip
+
+# 例外：若需跟踪某份参考 hex，可用 git add -f 强制加入
+
+# ── 日志与临时文件 ─────────────────────────────────────────────────────────
+Log/
+*.log
+
+# ── 编辑器 / Agent / Python ─────────────────────────────────────────────────
+.vscode/
+.cursor/
+.idea/
+*.swp
+*~
+__pycache__/
+*.py[cod]
+.Python
+*.egg-info/
+.eggs/
+
+# ── OS 杂项 ─────────────────────────────────────────────────────────────────
+Thumbs.db
+Desktop.ini
+.DS_Store

README.md

@@ -0,0 +1,61 @@
+# mcu-codegen-template
+
+见宝科技 **MCU 代码生成模板仓库**。见宝工具箱生成/分发 MCU 工程时，从此仓库按分支拉取对应芯片模板。
+
+**远程地址：** https://git.jianbao-tech.com/pets-device/mcu-codegen-template.git
+
+---
+
+## 分支说明
+
+本仓库 **`main` 分支仅作索引**，不含具体芯片工程。
+
+每个 MCU 模板对应一个独立分支，命名规则：**`厂商-型号`**（默认含 OTA）。
+
+| 分支 | 说明 |
+|------|------|
+| **`main`** | 本页：分支索引与使用说明 |
+| **`Puya-PY32F040`** | 普冉 PY32F040 · OTA 双工程框架（Bootloader + App + jb_protocol） |
+
+完整分支表见 [`docs/branch-index.md`](docs/branch-index.md)。
+
+---
+
+## 快速使用
+
+```bash
+# 克隆并切换到 PY32F040 模板
+git clone https://git.jianbao-tech.com/pets-device/mcu-codegen-template.git
+cd mcu-codegen-template
+git checkout Puya-PY32F040
+```
+
+切换后阅读该分支根目录 **`README.md`** 了解构建、OTA 配置与打包方式。
+
+---
+
+## 仓库结构（MCU 分支通用）
+
+```
+<MCU分支>/
+├── App/           APP Keil 工程
+├── Bootloader/    Bootloader Keil 工程
+├── Shared/        OTA 契约（ota_config.h 等，单一真源）
+├── Drivers/       厂商 HAL/CMSIS
+├── tools/         构建与打包脚本
+└── Doc/           设计文档
+```
+
+---
+
+## 维护者
+
+- 新增 MCU：新建 `厂商-型号` 分支，更新 `docs/branch-index.md` 与本 README 表格
+- 模板发版：在对应 MCU 分支打 tag，如 `Puya-PY32F040/v1.0.0`
+
+---
+
+## 相关链接
+
+- [分支索引详情](docs/branch-index.md)
+- [Gitea 仓库](https://git.jianbao-tech.com/pets-device/mcu-codegen-template)

docs/branch-index.md

@@ -0,0 +1,63 @@
+# MCU 代码生成模板 — 分支索引
+
+本仓库按 **「厂商-型号」** 组织分支，每个分支是一套完整的 MCU 工程模板（默认含 OTA + Bootloader）。
+
+远程仓库：[mcu-codegen-template](https://git.jianbao-tech.com/pets-device/mcu-codegen-template)
+
+---
+
+## 分支列表
+
+| 分支 | 厂商 | 型号 | Flash | 默认能力 | 状态 |
+|------|------|------|-------|----------|------|
+| [`Puya-PY32F040`](https://git.jianbao-tech.com/pets-device/mcu-codegen-template/src/branch/Puya-PY32F040) | 普冉 Puya | PY32F040 | 128KB | OTA 三模式 + Bootloader + jb_protocol | ✅ 可用 |
+
+> 新模板上线后在此表追加一行即可。
+
+---
+
+## 如何获取某 MCU 模板
+
+### 见宝工具箱 / 自动化脚本
+
+```bash
+git clone https://git.jianbao-tech.com/pets-device/mcu-codegen-template.git
+cd mcu-codegen-template
+git checkout Puya-PY32F040
+```
+
+### 仅下载指定分支（浅克隆）
+
+```bash
+git clone --branch Puya-PY32F040 --single-branch \
+  https://git.jianbao-tech.com/pets-device/mcu-codegen-template.git py32f040-template
+```
+
+---
+
+## 分支命名规范
+
+```
+<厂商>-<型号>
+```
+
+示例：`Puya-PY32F040`、`ST-STM32F103C8`
+
+- 默认包含 OTA，分支名**不加** `-ota` 后缀
+- 同一芯片多种工程结构（如裸机 vs OTA）差异过大时，再考虑加后缀：`Puya-PY32F040-bare`
+
+---
+
+## 新增 MCU 模板（维护者）
+
+1. 从 `main` 拉新分支：`git checkout -b <厂商>-<型号> main`
+2. 合入该 MCU 完整工程（App + Bootloader + Shared + Drivers + tools）
+3. 更新本文件分支表 + `main/README.md` 快速索引
+4. 推送分支并在 Gitea 设为受保护分支（可选）
+
+---
+
+## 各分支 README
+
+每个 MCU 分支根目录有独立的 `README.md`（构建、打包、OTA 配置说明）。
+设计细节见各分支 `Doc/` 目录。