如何科学地提问
这篇文档写给所有使用 MoteOS 的人：无论你是第一次把它移植到新芯片，还是在串口丢字时一筹莫展。 在向作者提问之前，请先花几分钟读完本文——它不教你"不许问"，而是教你"怎么问，才能真正帮到自己"。
信息框说明
本文档（以及《移植教程》《使用教程》）中会出现一些信息框，根据其颜色和左上角的图标可以得知信息的类别：
提示
本信息框是一些提示相关的内容。
扩展阅读
这类信息框是补充阅读材料，不影响主线操作，但读完会有更深的理解。
需要动手验证的内容
这类信息框要求你上板实测、动手操作，光看不练等于没看。
必读信息
这类信息框非常重要，跳过它大概率会在后面踩坑。
思考题
这类信息框是需要你停下来想一想的问题。答案不唯一，重点是思考的过程。
提问前的三件套：STFW、RTFM、RTFSC
MoteOS 是个人维护的项目，作者的精力和时间有限。正因为如此，每一位提问者在按下"提问"按钮之前， 都应该先完成这三件事：
- STFW（Search The Friendly Web）：把报错信息原文丢进搜索引擎。像
multiply defined、cannot open source input file这类报错，网上有大量现成答案——而且大部分问题的根源并不是 MoteOS， 而是你的 IDE 配置或工具链本身。 - RTFM（Read The Friendly Manual）：读文档。本项目的两份文档就是为此而写的：
- 《移植教程》：第 0 章术语表、第 1/2 章对应 IDE 的步骤、第 6 章 FAQ、第 7 章检查清单；
- 《使用教程》：第 0 章术语表、第 8 章排查表、第 9 章 FAQ、附录 A/B。
- RTFSC（Read The Friendly Source Code）：读源码。MoteOS 的内核刻意做得足够小
（内核三件套 text 不到 3KB），
mote.c、mote_task.c、mote_mail.c和 port 目录下的 移植层就是全部答案——直接读，比任何二手解释都准。
MoteOS 专属自查顺序
按这个顺序来，能过滤掉 90% 的问题：
- 报错先看头文件路径（《移植教程》1.4 说这是最常见的报错根源）；
- 查《使用教程》第 8 章排查表，对号入座；
- 翻两份文档的 FAQ（《移植教程》第 6 章、《使用教程》第 9 章）；
- 读
mote_port.c与你芯片对应的 port 头文件； - 还不行？——现在再提问，你已经能问出一个高质量的问题了。
与其说是学会提问，倒不如说是学会不提问
很多同学多少抱有这样的观点：
我向大佬请教，大佬告诉我答案，我就学习了。
但请想一想：MoteOS 是一个人的项目，没有专职客服，也没有轮班待命的助教。 将来你进入公司，同事要完成自己的 KPI；进入课题组，师兄师姐有自己的课题。 总有一天没有大佬告诉你答案，你要如何完成任务？
如果你觉得自己搞不定，你缺少的很可能是独立解决问题的能力——而这种能力是可以训练的。 所谓大佬之所以是大佬，是因为他们比你更早练出了这种能力：当你还在问一个"很傻的问题"时， 他们已经独立解决过无数个奇葩问题了。
大佬告诉你答案，展示的是大佬的能力，不是你的能力。
所以，来用 MoteOS，就请尽自己最大的努力独立解决问题。 把提问当成最后的武器，而不是第一反应。
提问模板：一次说清楚五件事
一个好的提问，让作者 30 秒就能看懂、5 分钟就能复现。请按下面的模板组织你的 issue：
## 环境
- 芯片型号 / 内核：例如 STM32F103C8（Cortex-M3）
- IDE 与编译器：例如 Keil µVision5（AC5）
- MoteOS 版本：例如 v1.2.0 / commit 8f3a1c
- 关键配置：`MOTE_TICK_MS`、`MOTE_TICKLESS`、`MOTE_PORT_HCLK_HZ` 等
## 现象
- 预期：LED 每 500ms 翻转一次
- 实际：LED 完全不闪 / 周期约 2 倍 / 上电后卡死
- 实测数据：示波器波形、电流值、map 文件体积
## 复现步骤
- 最小工程：只保留 mote.c / mote.h / mote_config.h / mote_port.c / mote_port.h + 一个 main.c
- 关键代码片段（直接贴，不要描述）
## 已尝试
- 查过哪些文档章节、改过哪些配置、换过哪些库版本
## 报错 / 日志
- 编译输出原文（0 error 了吗？warning 原文是什么？）
- map 文件片段、串口输出、中断频率实测必读：本仓库没有任何官方板级实测数据
MoteOS 的文档反复强调这一点：所有功耗、延迟、体积数据都需要你在自己的板子上实测。 因此提问时，请务必带上你自己的实测数据（电流、波形、周期）—— "我实测空闲电流没降" 比 "感觉没省电" 有用一百倍。
提问渠道
- GitHub Issues（推荐）：https://github.com/Lioyae/MoteOS/issues
- 提问前先搜索有没有同类问题（开新 issue 时套用上面的模板）；
- bug 类问题请提供最小复现工程；
- 文档勘误、新芯片移植方案征集也欢迎开 issue。
- 提 Pull Request：如果你已经找到答案并修复了问题，直接把修复提交上来， 比任何提问都更有价值。
这是一份个人项目，作者还有自己的工作和生活，回复可能不会很及时。 但请放心：信息完整的 issue 会被优先处理——按上面的模板写，就是对自己问题的负责。
AI 时代下的学习
AI 工具能瞬间生成"看起来能跑"的代码，但你仍然需要理解 MoteOS 的模型——事件、队列、 临界区、睡眠契约——否则出了问题，你连问 AI 都问不到点上。
- 用 AI 加速学习：让它解释
mote_mail_send为什么要"先入队、后入箱"； - 不要用 AI 代替学习：把报错原封不动丢给它再抄回来，你永远不知道自己抄的是什么。
前者让你成为工程师，后者让你成为传声筒。
最后：把坑回馈给项目
MoteOS 的文档里写着"欢迎把实测数据回馈给仓库，让下一颗芯片的移植者少踩一个坑"。 你解决了一个问题之后，欢迎：
- 把实测数据、排查过程补充到文档里（提 PR）；
- 把你新移植的芯片 port 贡献出来；
- 在 issue 里分享你的踩坑记录，让搜索到它的人少走弯路。
提问是最好的学习，回馈是最好的提问。