# eai-templates **Repository Path**: eai-code/eai-templates ## Basic Information - **Project Name**: eai-templates - **Description**: 项目模板层 | STM32F103 · GD32F1 · ESP32 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-23 - **Last Updated**: 2026-07-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # eai-templates > **嵌入式可复用代码库仓库**：面向 AI 协作时代的标签池架构，`git clone` 即可用。 `eai-templates` 是 [eai-code](https://gitee.com/eai-code) 生态中的**嵌入式代码模板层**。它把嵌入式工程里可复用的���动、算法、协议栈、工具函数等沉淀成一个个独立的"库"（variant），每个库自带结构化元数据（`meta.yml`）+ 11 段中文说明书（`README.md`），让人与 AI 都能精准检索、按需复用。 - **状态**：v1.0（2026-07-26），P0-2 已完成（9 工具 + 3 variant + 自动视图 + CI 雏形） - **License**：MIT（默认；个别 GPL 库放 `pool/_gpl/`） - **关联生态**：[eai-coder](https://gitee.com/eai-code/eai-coder) / [eai-rag](https://gitee.com/eai-code/eai-rag) / [eai-spec](https://gitee.com/eai-code/eai-spec) --- ## 这是什么 `eai-templates` 是一个**独立的嵌入式代码可复用库仓库**： - **独立**：不依赖 eai-code 其他仓库也能用。`git clone` 后直接 `cp pool//*.{c,h} your-project/` 即可。 - **工具是可选增强**：`tools/` 提供 query / lint / index 等命令行工具，但**不跑工具也能用**——`ls pool/` 就能找库。 - **面向 AI 协作**：每个库的 `meta.yml` 是分布式 manifest（Git diff 友好，无中心数据库），让弱 AI / 强 AI 都能精准检索，节省 token。 物理布局是 **flat 标签池**：`pool//` 一库一文件夹，多维检索（按架构 / 类型 / 用例 / canonical_id 等）走自动生成的 JSON 索引。 --- ## 核心特性 1. **独立系统**：库本身零外部依赖（C 代码靠标准库），`git clone` 即可离线使用。 2. **AI 友好 + 模糊检索**：`query.js` 是公共 API，CLI（人类可读）+ `--json`（AI 调用）双输出，支持 fuzzy 关键词 + 自然语言查询。 3. **标签化 + canonical_id 归一**：同功能多 variant（如 SPI 在 STM32 上的 reg/hal/ll 三种实现）共享同一 `canonical_id`，drift 检测自动同步。 4. **可成长迭代**：单库按 `maturity`（experimental → stable → mature）分级，不同档要求不同最小内容，逐步沉淀。 5. **工具链零依赖**：`tools/` 仅用 Node.js 内置模块，无需 `npm install`。 6. **资源占用透明**：driver/bsp 类强制声明 `requires_resources`（中断/DMA/外设），`eai-coder` 在选库时自动检测冲突。 --- ## 快速开始 ```bash # 1. 克隆仓库 git clone https://gitee.com/eai-code/eai-templates.git cd eai-templates # 2. 看现有库（无需 Node 也能用：ls pool/） ls pool/ # 3. 模糊查询（任意关键字） node tools/query.js spi node tools/query.js type:driver arch:arm-cortex-m3 # 4. 自然语言查询（弱 AI 友好） node tools/query.js --natural "我要做串口环形缓冲" # 5. 选中后，复制代码到你的工程 cp pool/ringbuffer/ringbuffer.{c,h} your-project/core/ ``` 无 Node.js 环境也能用：直接 `cat pool//README.md` 看 11 段说明书，按"文件清单"段手动复制文件即可。 --- ## 仓库结构 ``` eai-templates/ ├── pool/ # ★ 标签池：一库一文件夹（pool//） │ ├── spi-stm32f1-hal-dma/ # STM32F1 HAL SPI 驱动（DMA） │ ├── pid-f32/ # 单精度浮点 PID 控制器 │ ├── ringbuffer/ # 无锁 SPSC 环形缓冲 │ └── ... ├── schema/ # 受控词表 + meta schema（人工维护） │ ├── tags.yml # 23 命名空间 enum（arch / type / maturity ...） │ └── meta-schema.yml # meta.yml 字段定义 + 完整性约束 ├── tools/ # 工具链（Node.js 零依赖） │ ├── query.js # ★ 公共查询 API（人类 CLI + AI JSON） │ ├── lint.js # meta.yml schema + drift + 资源冲突校验 │ ├── index.js # 重建 index/*.json 索引 │ ├── view.js # 重建 views/*.md 视图（人类浏览入口） │ ├── template.js # 生成新库骨架 │ ├── tag.js / link.js # 标签 / 库间关系管理 │ └── migrate-v2-to-v3.js # schema 迁移 ├── index/ # 自动生成的 JSON 索引（禁止手改） ├── views/ # 自动生成的 Markdown 视图（禁止手改） ├── docs/ # 调研报告 + 用例索引 │ ├── research/ # 01-04 调研报告（14 维分类 / 工具链影响 / 可成长 / 标签池架构） │ └── use-case-index.md # 50+ 嵌入式常见用例 → 库映射 ├── CONSTITUTION.md # 仓库宪法（7 哲学 + 14 决策） ├── CONTRIBUTING.md # 贡献指南 └── README.md # 本文档 ``` **数据流**：人工维护 `pool//meta.yml` + `schema/tags.yml` → `lint.js` 校验 → `index.js` 生成索引 → `view.js` 生成视图 → 用户/AI 通过 `query.js` 检索。 **关键约束**：`index/` 和 `views/` 是衍生品，永远不手改。不跑工具时，`pool/` 本身就是完整可用的代码库。 --- ## 给开发者（找库 / 用库） | 想做的事 | 入口 | |---|---| | 浏览所有库 | [`views/README.md`](views/README.md)（按 type 分组的 MOC） | | 按架构 / 类型 / 成熟度筛选 | [`views/by-arch.md`](views/by-arch.md) / [`by-type.md`](views/by-type.md) / [`by-maturity.md`](views/by-maturity.md) | | 按用例找 | [`views/by-use-case.md`](views/by-use-case.md) | | 同功能多 variant 对比 | [`views/by-canonical.md`](views/by-canonical.md) | | 命令行模糊查询 | `node tools/query.js spi` | | 程序化查询（AI 调用） | `node tools/query.js --json type:driver` | | 看某个库怎么用 | `cat pool//README.md`（11 段中文说明书） | 每个库的 README 包含：30 秒读懂 / 功能定位 / API 参考 / 使用方法完整步骤 / 文件清单 / 兼容性矩阵 / 资源占用 / 已知问题 / 替代方案 / Changelog。 --- ## 给贡献者（加库 / 改库） 新增一个库的最小流程（5 步）： ```bash # 1. 用脚手架生成骨架（自动填 meta.yml + README + 测试目录） node tools/template.js new my-driver \ --type driver --arch arm-cortex-m3 \ --vendor st --peripheral spi --hal cube-hal # 2. 编辑 pool/my-driver/meta.yml，填入字段值 # 3. 实现 pool/my-driver/*.c 与 *.h # 4. 写 README 11 段（至少段 1-5） # 5. 校验 + 重建索引 node tools/lint.js my-driver node tools/lint-readme.js my-driver node tools/index.js && node tools/view.js ``` 完整贡献流程（maturity 分级、命名规范、PR checklist、老库宽限期、重命名/废弃流程）见 [CONTRIBUTING.md](CONTRIBUTING.md)。 --- ## 设计哲学 仓库的 7 条哲学与 14 条核心决策记录在 [CONSTITUTION.md](CONSTITUTION.md)。要点： - **T1 标签池**：物理布局 flat，多维检索走 JSON 索引 - **T2 slug 永久 ID**：一库一 slug，PR 合并即不变 - **T7 工具可选**：不跑工具也能 git clone 复制代码用 - **T9 canonical_id 归一**：同功能多 variant 共享同一 ID - **T12 README 11 段**：人类可读说���书，前 30 行必含核心信息 理论根基详见 [`docs/research/`](docs/research/)： - [01-dimension-taxonomy.md](docs/research/01-dimension-taxonomy.md)：14 维分类 + meta 字段集 - [02-toolchain-impact.md](docs/research/02-toolchain-impact.md)：编译器 × 架构差异详表 - [03-growth-and-retrieval.md](docs/research/03-growth-and-retrieval.md)：可成长 + AI 检索 - [04-tag-pool-architecture.md](docs/research/04-tag-pool-architecture.md)：标签池架构落地详案 --- ## 关联生态 | 仓库 | 角色 | 关系 | |---|---|---| | **eai-templates**（本仓库） | 代码模板层 | 提供可复用 variant 库 | | [eai-coder](https://gitee.com/eai-code/eai-coder) | AI 编码代理 | 用 `query.js` 检索本仓库，把代码生成进用户工程 | | [eai-rag](https://gitee.com/eai-code/eai-rag) | 检索增强 | 用 `index/embeddings-input.jsonl` 做 RAG 索引 | | [eai-spec](https://gitee.com/eai-code/eai-spec) | 规范层 | 维护跨仓库版本兼容矩阵 | 三者通过 `canonical_id` 与 `meta.yml` schema 协同。`eai-templates` 自身可独立运行，不强制依赖其他仓库。 --- ## License MIT。每个库的具体 License 在其 `meta.yml:license` 字段标注（默认 MIT；GPL 库放 `pool/_gpl/` 隔离）。 --- *v1.0 (2026-07-26) 首版，由 software-architect 起草。*