| name | support-new-llm |
| description | 为 MNN 框架添加新的 LLM 模型支持。支持从 HuggingFace/ModelScope 下载模型，分析架构，添加映射，Hook 对齐测试，导出 MNN 模型。采用 TDD 模式，分 6 步执行，每步有独立测试标准。 |
MNN LLM 新模型支持 SKILL
触发条件：当用户请求支持/添加/适配一个新的 LLM 模型时触发。常见表述包括："支持xxx模型"、"添加xxx模型支持"、"适配xxx"、"导出xxx模型"等。
概述
本 SKILL 指导 AI Agent 为 MNN 框架添加新的 LLM 模型支持。整个流程采用 TDD（测试驱动）模式，每一步都有明确的测试标准，必须通过当前步骤的测试后才能进入下一步。
核心思路
MNN 的模型导出本质上是对照 HuggingFace transformers 库中原始模型的实现代码，将其计算逻辑映射到 MNN 的统一框架中。核心步骤是：
- 读懂 HF 模型的
config.json 和 modeling_*.py
- 在
model_mapper.py 中注册字段映射
- 用 Python
--test 验证映射正确性
- 导出 MNN 模型并用 C++ 引擎验证
注意事项
🚨 严禁将输出错误归因于"量化精度不够"：4bit 量化的 0.5B 小模型都能正确输出。如果 C++ 输出完全不对（如图片识别不出、输出乱码），一定是实现细节没有与 HF 对齐，必须逐步 dump 数据对比定位，不要靠猜。
🚨 测试标准要有定力：每步的通过标准是明确的（如"C++ 能正确描述图片内容"），不能因为"差不多能跑"就跳过。"能感知到一些信号但描述不准确"不等于通过，必须达到与 HF 模型相当的输出质量才算完成。
🚨 多模态/embedding 对齐先看 C++ 端真实输入输出：不要只比 Python 导出逻辑。先直接打印并比对 C++ 运行时的 chat template、token ids、以及必要时的中间输入，确认 runtime tokenizer/Jinja/post_processor 与 HuggingFace 完全一致，再继续看视觉或量化路径。
🚨 改导出模板先做“临时 config 覆盖”验证：当修改 llm_config.json / config.json 里的 jinja.chat_template 时，不要一上来全量重导出模型。先用现有 MNN 模型目录配一个临时 config.json 覆盖 base_dir + jinja/context，直接跑 C++ llm_demo/embedding_demo 验证 prompt token 数、构造出的语义和最终结果是否与基线一致，再决定是否全量 re-export。
