Agent_Model_Project

Important

这是厂商与芯片型号无关的嵌入式工程模板，不是 STM32 专用工程。 只要提供目标芯片的可靠资料，就可以用同一套事实提取、任务拆分、实现、评审和验证流程启动项目。数据手册可以作为入口；真实驱动和量产级实现通常还需要 Reference Manual、Errata、SDK、原理图及构建工具链，缺失信息必须标记为待确认，不能由 Agent 猜测。

级联 Agent 路由：把推理用在真正需要的地方

本仓库内置项目级多 Agent 规则，并通过真实模型配置完成分工：

层级	配置	负责内容
主 Agent	Sol / high	理解需求、判断风险、拆分任务、选择执行者、整合结果和最终验收
sol_engineer	Sol / xhigh	含糊需求、架构、高风险硬件决策、复杂根因分析、计划和最终评审
luna_worker	Luna / max	边界清楚的实现、测试、文档同步、编译修复和机械性重复工作

Sol/high 主任务
├─ 复杂、高风险、需要取舍 ──> sol_engineer（Sol/xhigh）
└─ 简单、重复、边界明确 ───> luna_worker（Luna/max）
                              ↓
                         主 Agent 验收结果

这种级联方式避免把高强度 xhigh 推理长期消耗在机械工作上，同时保留 Sol 对范围和质量的控制，因此通常能减少不必要的高成本上下文与 Token 消耗。实际消耗仍取决于任务规模、模型可用性和是否发生真实委派；角色名称不能代替模型切换。

详细规则见 AGENTS.md、模型工作流 和 .codex 配置。

工程简介

这是一个用于复用 MCU、SoC 和其他可编程嵌入式目标项目的工程模板，当前内容重点是可审计的 AI 辅助开发流程、任务边界和质量规则。现有编码规则以嵌入式 C 为主，但不绑定特定芯片厂商。仓库尚未导入真实固件、芯片支持包、启动文件、链接脚本或构建配置，因此它不是可直接编译的固件工程。

详细协作规则见 AGENTS.md，项目初始化入口见 AI 开发文档 和 新项目初始化说明。

支持平台

• 目标芯片：尚未指定具体厂商、系列或完整料号。
• SDK / HAL / LL / CMSIS / BSP：尚未指定。
• RTOS：尚未指定，不能假定使用 FreeRTOS。
• IDE / 编译器：尚未指定，导入真实工程后应使用与目标芯片和项目匹配的既有工具链。
• 主机环境：文档和目录模板不依赖特定本机绝对路径。

环境要求

• Git，用于建立可审查的版本基线。
• 与实际芯片工程匹配的编译器、SDK、IDE 和烧录/调试工具。
• Codex 为可选工具；使用时应从仓库根目录启动并信任项目级配置。
• 真实硬件、芯片手册、原理图和调试工具由具体项目提供。

文件结构

.
├─ App/                  应用层占位目录，真实职责需由后续工程确认
├─ Com/                  通用模块占位目录，真实职责需由后续工程确认
├─ LIB/                  库目录占位，第三方许可证需单独核验
├─ .codex/               项目级模型与自定义 Agent 配置
├─ .github/              Pull Request 模板等 GitHub 协作配置
├─ docs/ai/              项目事实、工作流、任务、计划和评审资产
├─ AGENTS.md             项目执行边界与质量规则
├─ CONTRIBUTING.md       分支、提交、PR、验证和安全检查规则
├─ 使用SOP.md            模板复制和日常开发流程
├─ .gitignore            私有配置、IDE 状态和构建产物过滤规则
└─ .gitattributes        跨平台文本换行和二进制文件规则

App/、Com/、LIB/ 当前仅含 .gitkeep，用于让 Git 保留空的模板目录。不要根据目录名编造模块接口。

编译方式

当前没有可执行的构建命令，也未完成编译验证。导入真实固件后应先执行以下步骤：

1. 确认芯片精确料号、SDK/HAL/RTOS、启动文件和链接脚本。
2. 从工程文件或构建脚本确认真实构建入口，不凭经验编造命令。
3. 更新 项目事实，再执行 TASK-001 和 TASK-003。
4. 只有实际构建成功后才能声明“编译通过”；硬件行为仍需真实板卡验证。

用户私有参数

当前模板不包含任何必需的账号、密码、密钥或网络参数。导入真实项目后应遵循以下约定：

1. 真实私有文件使用 .gitignore 中的名称，例如 config_private.h、wifi_config.h 或 .env。
2. 仓库只提交对应的脱敏模板，例如 config_private_template.h 或 wifi_config_template.h。
3. 模板中仅使用 YOUR_WIFI_PASSWORD、YOUR_SERVER_ADDRESS 等占位符，不保存真实值。
4. 日志不得打印密码、Token、密钥、完整认证头、芯片 UID、产品序列号或敏感生产数据。

如果具体项目已经提供模板文件，可按平台复制后填写私有值：

Copy-Item .\config_private_template.h .\config_private.h

cp config_private_template.h config_private.h

不要把真实私有配置强制加入 Git。提交前应再次检查待提交文件和忽略文件，并使用专用密钥扫描工具进行复核。

公开发布边界

• 不提交密钥、密码、Token、账号、私人配置、个人路径或公司内部资料。
• 不提交 IDE 用户状态、调试器缓存、日志和编译产物。
• 第三方源码、二进制库、芯片包和数据手册必须确认许可证及再分发条件。
• 本模板采用 MIT License；后续导入的第三方内容仍需分别核验其许可证和再分发条件。

分支与 Pull Request 规则

• main：只保存稳定、已审查的主线。
• feature/*：新功能。
• fix/*：Bug 修复。
• docs/*：文档和仓库说明。
• refactor/*：不改变功能的重构。

不要长期直接在 main 上开发。每项工作从最新 main 创建独立分支，通过 Pull Request 审查后再 Squash Merge。完整命令和检查清单见 CONTRIBUTING.md，每个 PR 会自动加载 Pull Request 模板。

许可证

本模板采用 MIT License。该许可证只覆盖本仓库有权授权的内容，不自动覆盖后续导入的厂商 SDK、芯片包、第三方库、数据手册或其他受独立条款约束的材料。