KNOWLEDGE_BASE.md

MetaCore Studio 本地器件知识库

本地器件知识库为芯片、模组、开发板、元器件和驱动提供统一的结构化事实层。它位于 AI 提示词和原始静态数据之间，使关键硬件参数可以被校验、查询、版本化并追溯来源。

v2.6.0 已完成第二阶段本地知识包：除第一阶段 Schema、注册表和兼容适配外，现已内置常用 ESP32、STM32 与教学元器件的正式 metacore.hardware-core@1.0.0。本阶段仍不下载官方文档、不联网更新；官方同步、缓存和按需检索属于后续阶段。

目录结构

src/
├── knowledge/
│   ├── index.ts             # 公共导出
│   ├── schema.ts            # 知识包运行时校验
│   ├── registry.ts          # 安装、查询、解析、统计和快照
│   ├── legacyPack.ts        # 现有静态数据兼容适配器
│   ├── hardwareCorePack.ts  # 8 个 MCU 与 33 个教学器件正式知识包
│   ├── context.ts           # 需求/BOM 匹配和提示词事实选择
│   └── localKnowledge.ts    # 应用内置只读知识库实例
└── types/
    └── knowledge.ts         # Schema v1 类型

核心模型

一个 KnowledgePack 是可以原子安装和替换的版本化单元，包含：

• sources：数据手册、参考手册、勘误、原理图、官方仓库或历史数据来源。
• entities：芯片、模组、开发板、传感器、显示器、执行器、通信器件和驱动。
• dependencies：知识包之间的最低版本依赖。
• priority：当多个实体通过相同别名命中时，决定正式包与兼容包的排序优先级。

一个实体由以下部分组成：

• 身份：厂商、完整型号、别名、封装、类别和标签。
• 事实：电压、容量、主频等键值事实；关键事实必须有证据。
• 引脚：引脚 ID、信号、输入/输出限制、说明和证据。
• 接口：I2C、SPI、UART 等接口、默认引脚、地址和证据。
• 约束：启动、调试、电气或兼容性约束。
• 关系：芯片、模组、开发板和外围之间的包含、派生与兼容关系。
• 驱动：框架、软件包、版本和支持状态。

可信状态

实体使用四级状态：

状态	含义
draft	尚未完成复核，不得作为确定的关键事实
reviewed	已在项目内部检查，但不代表官方资料复核
verified	至少引用一个官方来源并通过 Schema 校验
deprecated	已废弃或被新实体替代

verified 实体如果没有官方来源，知识包会被拒绝。标记为 critical 的事实如果没有证据，同样会被拒绝。

注册表行为

LocalKnowledgeBase 提供：

• 知识包运行时校验和原子安装。
• 显式替换和卸载。
• 实体与来源冲突检测。
• 知识包依赖检查。
• 按 ID、类型、厂商、标签和状态查询。
• 对 UI 使用的模糊搜索。
• 对生成流程使用的严格型号/别名解析。
• 包版本、实体版本和来源版本快照。
• 同分结果按知识包 priority 排序，使正式知识优先于 legacy 兼容数据。

模糊 search() 与严格 resolve() 有意分离。搜索可以返回相似结果；解析只有在 ID、型号、名称或别名精确归一化匹配时才成功，防止未知型号静默落到错误芯片。

现有数据兼容

metacore.legacy-core@1.0.0 将原有 CHIP_SPECS 和 DRIVER_TEMPLATES 注册为兼容知识包，优先级为 0。所有实体均标记为 reviewed，来源类型为 legacy，不会冒充官方验证数据。

metacore.hardware-core@1.0.0 优先级为 100，包含 41 个正式结构化实体：

• ESP32：ESP32、ESP32-S3、ESP32-C3、ESP32-C6、ESP32-S2。
• STM32：STM32F103C8T6、STM32F103RBT6、STM32F407VGT6。
• 教学器件：33 个常用 LED、输入、传感器、显示、执行器、电机驱动、RTC 和存储器件。

芯片 Store 和 AI 方案/代码提示词已经通过本地知识库解析预置芯片。context.ts 会严格解析目标芯片，并从需求、BOM 与方案中匹配器件别名，只输出相关实体的电压、IO、电流、接口、地址、约束、驱动和来源摘要。没有命中时会明确提示本地未收录，不能自行补全。自定义芯片仍然优先于内置知识，现有项目、浏览器存储和生成行为保持兼容。

正式知识包使用独立实体 ID，通过旧目标名别名承接兼容入口，避免与 legacy 实体冲突。查询同分时优先返回正式包。

新知识包要求

新增知识包必须满足：

1. 使用 Schema v1 和 SemVer 包版本。
2. 实体与来源 ID 使用稳定的小写命名空间。
3. 关键电压、电流、封装、引脚和启动约束必须引用证据。
4. verified 只能用于厂商官方资料支持的实体。
5. 不同 SoC、模组、封装和开发板使用不同实体，并通过关系连接。
6. 安装失败不能部分修改当前注册表。
7. 正式发布前为查询、冲突、依赖和快照补充测试。

后续阶段边界

第二阶段本地知识包已在 v2.6.0 完成。后续阶段才引入官方来源注册、文档缓存、版本检测、差异审核和按需检索。

当前知识实体统一标记为 reviewed。虽然来源表已登记厂商或项目资料地址，但在没有完成逐项页面、修订号和摘录复核前，不升级为 verified。

联网同步不得直接覆盖已验证事实。官方文档发生变化时，应先生成差异，再经过规则或人工审核发布新的知识包版本。完整 PDF 不进入 Git 仓库，未来只存放在本地知识缓存目录。