简体中文

English

简体中文

English

外观

常见问题 ​

本页汇总使用天巧星 Skill 过程中高频出现的问题及解决方案。按问题类型分为五类：安装配置、编译错误、烧录调试、引脚封装、SDK 版本。

遇到问题时建议先在本页搜索关键词。如果未找到对应条目，可在 openkits-skills 仓库提交 Issue。

1. 安装与环境配置 ​

Claude Code CLI 安装失败：npm 权限错误（EACCES / EPERM）

现象： 执行 npm install -g @anthropic-ai/claude-code 时报 EACCES 或 EPERM 错误。

原因： npm 全局安装目录位于系统保护路径（Windows 的 C:\Program Files、macOS/Linux 的 /usr/local/lib），当前用户无写入权限。

解决方案：

  • Windows：以管理员身份运行终端（右键 PowerShell →"以管理员身份运行"），重新执行安装命令。
  • macOS / Linux：在命令前加 sudo：
    bash
    sudo npm install -g @anthropic-ai/claude-code

永久方案（macOS / Linux）： 将 npm 全局目录配置到用户空间，避免后续每次都需要 sudo：

bash
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# 将以下行添加到 ~/.bashrc 或 ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

参考：npm 官方权限问题指南

Trae 安装后闪退或无法启动

现象： 安装完成后双击启动，窗口闪现后消失，或完全无响应。

排查步骤：

  1. 系统配置检查：Trae 基于 VS Code 内核（Electron），建议内存 ≥ 8GB。4GB 内存的机器可能无法正常运行。
  2. 重新下载安装：从 Trae 官网 重新下载安装包覆盖安装，排除下载过程中的文件损坏。
  3. 权限问题：Windows 下右键 →"以管理员身份运行"。
  4. 安全软件干扰：检查是否被杀毒软件拦截，将 Trae 安装目录加入白名单。
  5. GPU 加速冲突：部分集成显卡驱动与 Electron 的 GPU 加速存在兼容性问题，尝试在快捷方式的目标后添加 --disable-gpu 参数启动。
setup.py 提示找不到 CCS 目录

现象： 运行 python setup.py 时报错 "CCS directory not found" 或类似信息。

原因： 配置脚本按输入的路径查找 CCS 安装，路径不正确则报错。

排查步骤：

  1. 确认安装路径：CCS Theia 默认安装路径：

    平台默认路径
    WindowsC:/ti/ccstheia140
    macOS/Applications/ti/ccstheia140
    Linux~/ti/ccstheia140

  2. 路径格式：Windows 下使用正斜杠 / 而非反斜杠 \。

  3. 路径中不能包含中文或空格：CCS 对路径中的非 ASCII 字符和空格处理存在已知问题。如果 CCS 安装在包含中文或空格的路径下，需要重新安装到纯 ASCII 路径。

  4. 验证目录内容：打开你输入的路径，确认其中存在 ccs 子目录和相关可执行文件。

2. 编译错误 ​

编译报错 "device_linker.cmd not found"

现象： build.py 运行时链接阶段报错，提示找不到 device_linker.cmd。

原因： 工程目录下残留了上次编译的产物（特别是 ticlang/ 目录），导致编译系统跳过了 linker 文件的生成步骤。

解决方案：

bash
python scripts/cleanup.py ./workspace/<工程名>
python scripts/build.py ./workspace/<工程名>

注意： 不要手动创建 ticlang/ 目录或 device_linker.cmd 文件。这些文件由编译工具链自动生成，手动创建会干扰正常的构建流程。

编译报错 "Duplicate symbol" 重复定义

现象： 链接阶段报错，提示某个函数或变量被重复定义。

原因： 工程中存在重复的 .c 源文件。常见于封装适配后未清理旧文件，或手动复制文件时引入了重复。

解决方案：

bash
python scripts/cleanup.py ./workspace/<工程名>
python scripts/build.py ./workspace/<工程名>

cleanup.py 会识别并删除封装适配产生的冗余源文件。清理后重新编译即可。

SysConfig 生成的代码编译报错

现象： ti_msp_dl_config.c 或 ti_msp_dl_config.h 相关的编译错误。

排查步骤：

  1. 确认未手动修改：ti_msp_dl_config.c/h 由 SysConfig 自动生成，手动修改会在下次编译时被覆盖且可能引入不一致。所有配置修改应在 .syscfg 文件中进行。

  2. 检查 .syscfg 配置：引脚分配是否存在冲突？外设配置是否合法？

  3. 清理重建：

    bash
    # 删除旧的构建产物
rm -rf ./workspace/<工程名>/Debug/
# 重新编译（自动调用 SysConfig 重新生成）
python scripts/build.py ./workspace/<工程名>

  4. SDK 版本一致性：确认本地 SDK 版本为 2.10.00.04。不同版本的 SysConfig 模板可能存在 API 差异。

3. 烧录与调试 ​

烧录时提示找不到调试器（No debug probe found）

现象： 执行 flash.py 时报错 "No debug probe found" 或 "Unable to connect to XDS110"。

排查步骤：

  1. USB 数据线确认：部分 USB 线仅支持充电不支持数据传输。更换一根确认支持数据传输的线缆。

  2. 设备识别检查：

    • Windows：设备管理器中应出现两个设备：
      • "XDS110 Class Debug Probe"
      • "XDS110 Class Application/User UART"
    • macOS / Linux：lsusb 或 dmesg 中应能看到 XDS110 设备。

  3. 驱动安装：如果设备管理器中设备带黄色感叹号，说明驱动未正确安装。运行 CCS 安装目录下的驱动工具：

    <CCS目录>/ccs/utils/xds110/xds110_cfg.exe

  4. 重新运行 setup.py：确认调试器类型配置正确：

    bash
    python scripts/setup.py

  5. USB 端口问题：尝试换一个 USB 口，避免使用 USB Hub。

烧录成功但程序不运行

现象： flash.py 报告烧录成功，但开发板无任何预期行为。

常见原因及解决方案：

原因 1：需要手动复位

部分情况下烧录完成后 MCU 不会自动从 Flash 重新加载程序。按下板上复位键，或拔插 USB 线重新上电。

原因 2：引脚冲突

生成的代码中某个外设被分配到了已被板载硬件占用的引脚上。检查 Agent 在 Plan 阶段输出的引脚分配表，对照 天巧星引脚占用表 确认无冲突。

特别注意：如果误将 SWD 引脚（PA19/PA20）分配给其他功能，不仅程序会异常，后续烧录也会失败。此时需要通过 BSL 引导模式恢复。

原因 3：程序在运行但行为不可见

如果是 UART 相关工程，程序可能已经在运行，只是没有外部可观察的硬件变化。连接串口监视器检查是否有输出：

bash
python scripts/serial_console.py <串口号> 115200

4. 引脚与封装 ​

PA5 / PA6 无法作为 GPIO 使用

现象： 将 PA5 或 PA6 分配为 GPIO 时，Agent 拒绝或编译后硬件行为异常。

原因： PA5 和 PA6 在天巧星开发板上连接了外部高速晶振（HFXT）。这两个引脚已有确定的硬件用途，不能复用为普通 GPIO。

解决方案： 更换为其他空闲 GPIO 引脚。天巧星 LQFP-64 封装有充足的空闲引脚可供选择。

如果确实需要使用 HFXT 功能（某些场景需要精确时钟基准），在 .syscfg 中配置 HFXT 模块即可——但 PA5/PA6 仍不能作为 GPIO。

引脚分配后编译通过但硬件不工作

现象： 编译零报错，烧录成功，但对应外设功能不正常。

原因： 编译器只检查代码语法和符号引用，不校验引脚分配的物理合理性。如果目标引脚在硬件上已被其他电路驱动（如板载 SPI Flash、LCD），会出现电平竞争，导致双方都无法正常工作。

天巧星高风险引脚：

引脚板载用途误用后果
PA19 / PA20SWD 调试接口无法烧录，需 BSL 恢复
PA10 / PA11USB 转 UART (CH340)板载串口功能失效
PB6 / PB7 / PB8 / PB9SPI Flash (W25Q64)Flash 读写异常
PA0 / PA1OLED + IMU（I2C）屏幕和传感器失效
PA5 / PA6HFXT 晶振晶振失效
PA24 / PB21 / PB24 / PA18用户按键按键检测干扰
PB26WS2812 RGB LEDLED 颜色异常
PB27蜂鸣器蜂鸣器不响

避免方法：

  1. 使用 Agent 自动分配引脚时，Skill 会自动规避已占用引脚
  2. 手动指定引脚时，对照上表确认目标引脚未被占用
  3. 不确定时直接问 Agent："天巧星上哪些引脚可以用来做 XX？"

5. SDK 与版本 ​

编译报错提示 SDK 版本不匹配

现象： 编译时出现 API 未定义、头文件缺失、或函数签名不匹配的错误。

原因： 天巧星 Skill 基于 MSPM0 SDK 2.05.01.00 开发。不同 SDK 版本之间的 DriverLib API、头文件路径、工程模板结构可能存在差异。

解决方案：

  1. 下载并安装 SDK 2.10.00.04：TI MSPM0-SDK 下载页
  2. 如果已安装其他版本，建议先卸载再安装目标版本，避免多版本共存导致的路径混淆
  3. 重新运行配置脚本更新 SDK 路径：
    bash
    python scripts/setup.py

版本锁定策略

嵌入式开发中，工具链版本一致性比"使用最新版"更重要。Skill 会跟进 SDK 新版本的适配，但请始终以文档中标注的版本为准。

:::

天巧星 Skill 能否用于其他 MSPM0 开发板

结论：不能直接使用。

天巧星 Skill（mspm0kit-tianqiaoxing）是为 MSPM0G3519 LQFP-64 封装量身定制的，包含该特定封装的引脚映射和天巧星板载外设占用信息。

不同开发板的差异：

开发板MCU封装引脚数
天巧星MSPM0G3519LQFP-6464
天猛星MSPM0G3507LQFP-6464
地猛星MSPM0G3507LQFP-4848
地正星MSPM0L1306LQFP-3232

即使是同一封装，不同 MCU 的外设资源、引脚编号和可用引脚集合也不完全相同。将天巧星的引脚配置直接应用到其他板卡上，轻则编译报错，重则烧录后硬件行为不可预测。

不同板卡的 Skill 可在 openkits-skills 仓库中按需选择安装。如使用自定义板卡，可参考天巧星 Skill 的结构自行适配。

如何确认本地安装的 MSPM0 SDK 版本

方法 1：通过 CCS Theia

Window → Preferences → Code Composer Studio → Products → 查看已安装产品列表中 MSPM0 SDK 的版本号。

方法 2：通过文件系统

进入 SDK 安装目录，查看 manifest.json 或根目录下的版本标识文件。路径示例：

C:/ti/mspm0_sdk_2_10_00_04/manifest.json

文件中的 version 字段即为当前版本。

方法 3：通过目录名

TI SDK 安装目录的命名规则包含版本号：mspm0_sdk_<major>_<minor>_<patch>_<build>。例如 mspm0_sdk_2_10_00_04 对应版本 2.10.00.04。

6. 其他问题 ​

Agent 响应缓慢或超时

可能原因：

  • 网络问题：Claude Code CLI 和 Codex 依赖云端 API，网络延迟或不稳定会导致响应变慢
  • 模型负载：云端 API 在高峰时段可能响应较慢
  • 上下文过长：对话轮次过多时，Agent 需要处理的上下文增大，响应时间相应增加

缓解方法：

  • 网络问题：检查连接稳定性，必要时切换网络
  • 超时后重试：通常重新发送请求即可
  • 长对话：如果对话已经很长，考虑新建一个会话窗口
  • 使用 Trae：国内直连，网络延迟最低
如何更新已安装的 Skill

Claude Code CLI / Codex：

bash
# 卸载旧版本
npx skills remove mspm0kit-tianqiaoxing -a claude-code

# 重新安装（会拉取最新版）
npx skills add https://gitee.com/lcsc/openkits-skills.git -s mspm0kit-tianqiaoxing -a claude-code

Trae：

  1. 在 Skills 面板中移除旧的 Skill
  2. 进入本地 openkits-skills 仓库目录，执行 git pull 拉取最新代码
  3. 重新通过图形界面导入