Skip to content

GitLab

Open
Created by fengjun.shi@fengjun.shi

20260518 LKShalconfig_MCP_Requirements

LKShalconfig MCP Requirements for LKS_AI_AutoPin

本文档定义 LKS_AI_AutoPin 对 LKShalconfig MCP 的最小真实需求。核心目标是：让 Agent 从 LKShalconfig 获取芯片、封装、引脚复用、外设配置字段，并进行写入和代码生成，而不是读取整本芯片手册。

基本原则

  • LKShalconfig 是引脚复用、外设配置字段、校验规则和代码生成规则的权威来源。
  • 能够支持调用 MCP、记录证据和对照结果。
  • MCP 返回机器可读结构。
  • 写入类操作必须能校验并返回明确错误，不能静默失败。

.halconfig 对象模型

MCP 至少应能查询、校验、修改和保存这些对象：

  • mcu: MCU 系列和具体型号，例如 series=lks32mc07x、name=LKS32MC071CBT8。
  • gen: 生成选项，例如 projDir、projName、ide、genPlatform、copyProj、copyLib、genExample。
  • edit: 全局编辑选项，例如 clock、eraseAll、link。
  • gpios: 引脚配置，例如 name=P1_4、af=MCPWM_CH0P、mode、userLabel。
  • periphs: 外设实例及参数，例如 HAL_ADC_0、HAL_OPA_1、HAL_MCPWM_0。
  • midwares: 中间件及平台参数，例如 RTT、RTOS、PLATFORM.m0_periphs。

应支持的外设类型包括：CLK、DSP、DAC、OPA、CMP、ADC、UART、TIMER、QEP、HALL、TMP、MCPWM、SPI、I2C、CAN、IWDG、GPIO。

必要服务

1. 查询性服务

用于让 Agent 读取 LKShalconfig 已知的芯片、工程、引脚和配置字段信息，不修改工程。

服务能力查询

  • 查询 LKShalconfig 版本、MCP/API 版本。
  • 查询支持的 MCU 系列、工程格式、IDE 选项。
  • 查询当前 MCP 支持的能力：新建/加载工程、引脚表查询、schema 查询、配置校验、批量应用、保存、代码生成。

当前工程查询

  • 查询当前工程信息：mcu、gen、edit、已启用中间件、是否有未保存修改。
  • 查询完整工程配置，覆盖 mcu、gen、edit、gpios、periphs、midwares。
  • 支持按对象查询，避免一次返回过大数据，例如只查 gpios 或 HAL_MCPWM_0。

芯片与引脚能力查询

用于替代手册中的封装和复用功能查表。

  • 查询支持的 MCU 型号列表。
  • 查询指定 MCU 的封装列表；若工程已加载，返回当前封装。
  • 查询当前 MCU/封装的完整引脚复用表：
    • 物理脚号
    • 端口名，例如 P1_4
    • 特殊属性，例如电源、地、复位、SWD、晶振
    • 可选复用功能，例如 MCPWM_CH0P、ADC0_CH12
    • 每个功能所属外设、通道和必要约束

配置 Schema 查询

用于让 Agent 不硬编码 LKShalconfig 表单字段。

  • 查询配置 schema：
    • 对象路径，例如 gpios[].af、periphs.HAL_ADC_0.samp_seq0
    • 当前值、默认值、可选值
    • 是否可写、是否必填
    • 依赖关系和冲突规则

2. 写入性服务

用于把 AutoPin 的结构化配置写入当前工程。写入前必须支持校验，写入后必须可回读确认。

  • 支持 dry-run 校验，不修改工程。
  • 支持实际应用一组配置变更，至少覆盖：
    • GPIO/引脚复用、模式、用户标签
    • 外设启用状态和参数
    • 中间件/平台参数
    • gen 和 edit 参数
  • 校验结果应指出：
    • 非法字段或非法枚举值
    • 引脚复用不支持
    • 引脚/外设/中间件冲突
    • 缺失依赖配置
    • SWD、复位、晶振等特殊脚风险
    • LKShalconfig 自动调整过的字段

3. 工程操作服务

用于管理工程生命周期、持久化配置和触发代码生成。

工程生命周期

  • 新建工程：输入 MCU 系列、具体型号、工程保存路径，必要时输入 gen 默认值。
  • 加载工程：输入 .halconfig 路径。
  • 保存、另存为、关闭工程。

保存与代码生成

用于生成目标工程代码。

  • 保存当前 .halconfig。
  • 执行代码生成。
  • 返回生成状态、日志、错误、警告和变更文件列表。
  • 生成失败时返回可定位原因，例如字段缺失、引脚冲突、输出路径不可写。
  • 明确说明用户代码区是否被保留。

诊断与导出

用于 Agent 记录和复核。

  • 导出当前工程配置为机器可读结构。
  • 导出错误/警告列表。
  • 导出配置摘要，便于写入 autopin_lkshalconfig_session.md。

推荐调用顺序

下面是建议流程，方法名仅表达能力，不强制 LKShalconfig 使用这些名字。

  1. 查询服务能力。
  2. 新建或加载工程。
  3. 查询工程信息。
  4. 查询 MCU/封装引脚复用表。
  5. 查询配置 schema 和当前配置。
  6. dry-run 校验 AutoPin 配置。
  7. 应用配置并回读工程配置。
  8. 保存 .halconfig。
  9. 生成代码。
  10. 导出诊断和配置摘要。