Keil

{
  "uv4_exe": "C:\\Keil_v5\\UV4\\UV4.exe",
  "operation_mode": 1
}


# keil

Claude Code skill，驱动 Keil MDK 进行工程扫描、Target 枚举、编译构建，并返回可交给 `jlink/openocd` 的产物路径。`flash` 保留为兼容入口。

## 功能

- 扫描目录下的 .uvprojx / .uvmpw 工程文件
- 枚举工程中的 Target
- 增量编译 / 全量重建 / 清理
- 返回 `flash_file` / `debug_file` 等产物路径，便于继续交给 `jlink/openocd`
- 通过 Keil 下载固件到目标板（兼容入口）
- 解析构建日志，输出结构化错误/警告信息

## 环境要求

- [Keil MDK](https://www.keil.com/mdk5/) — 提供 UV4.exe
- Python 3.x（仅标准库，无额外依赖）

## 配置

### 环境级配置（skill/config.json）

复制 `config.example.json` 为 `config.json`，根据实际安装路径修改：

```json
{
  "uv4_exe": "C:\\Keil_v5\\UV4\\UV4.exe",
  "operation_mode": 1
}
```

| 字段 | 必填 | 说明 |
|------|------|------|
| `uv4_exe` | 是 | UV4.exe 完整路径 |
| `operation_mode` | 否 | `1` 直接执行 / `2` 输出风险摘要 / `3` 执行前确认 |

### 工程级配置（workspace/.embeddedskills/config.json）

工程级共享配置保存在工作区的 `.embeddedskills/config.json` 中：

```json
{
  "keil": {
    "project": "",
    "target": "",
    "log_dir": ".embeddedskills/build"
  }
}
```

| 字段 | 说明 |
|------|------|
| `project` | 默认工程路径（相对 workspace） |
| `target` | 默认 Target 名称 |
| `log_dir` | 构建日志输出目录，默认 `.embeddedskills/build` |

### 参数解析优先级

参数解析顺序（从高到低）：
1. CLI 显式参数
2. 环境级配置（skill/config.json）
3. 工程级配置（.embeddedskills/config.json）
4. state.json（上次构建记录）
5. 搜索/询问


# Keil MDK 编译器参考

## UV4.exe 命令行参数

| 参数 | 说明 |
|------|------|
| `-b <project>` | 增量编译 |
| `-r <project>` | 全量重建 |
| `-c <project>` | 清理 |
| `-cr <project>` | 先清理再重建 |
| `-f <project>` | 烧录（Flash Download） |
| `-t <target>` | 指定 Target 名称 |
| `-j0` | 不显示 UV4 GUI 窗口 |
| `-o <logfile>` | 输出日志到文件 |

## ERRORLEVEL 返回码

| 返回码 | 含义 |
|--------|------|
| 0 | 无错误，无警告 |
| 1 | 有警告 |
| 2 | 有错误 |
| 3 | 致命错误（license / 工程损坏等） |
| 11 | 无法打开工程文件 |
| 12 | 设备数据库缺失 |
| 13 | 写入错误 |
| 15 | UV4 访问错误（被占用等） |
| 20 | 未知错误 |

## 日志中常见摘要行格式

```
".\Objects\project.axf" - 0 Error(s), 3 Warning(s).
Program Size: Code=12345 RO-data=678 RW-data=90 ZI-data=1234
```

- **Flash 占用** = Code + RO-data + RW-data
- **RAM 占用** = RW-data + ZI-data

## 常见编译错误排查

| 错误类型 | 可能原因 |
|----------|----------|
| `error: #5: cannot open source input file` | 文件路径不存在或包含配置缺少 include 路径 |
| `Error: L6218E: Undefined symbol` | 链接阶段缺少源文件或库 |
| `*** TOOLS.INI: TOOLCHAIN NOT INSTALLED` | Keil 工具链未安装或 license 异常 |
| `*** error 65: access violation` | Flash 算法不匹配目标芯片 |
| `No Algorithm found for` | 工程配置中未选择 Flash 算法 |


"""Keil MDK 构建 / 重建 / 清理 / 烧录。"""

from __future__ import annotations

import argparse
import os
import re
import subprocess
import sys
import time
import xml.etree.ElementTree as ET
from pathlib import Path


ROOT_DIR = Path(__file__).resolve().parents[2]
if str(ROOT_DIR) not in sys.path:
    sys.path.insert(0, str(ROOT_DIR))

from keil_runtime import (  # noqa: E402
    build_artifacts,
    default_config_path,
    get_state_entry,
    hidden_subprocess_kwargs,
    is_missing,
    load_json_file,
    load_local_config,
    load_project_config,
    load_workspace_state,
    make_result,
    make_timing,
    normalize_path,
    now_iso,
    output_json,
    parameter_context,
    resolve_param,
    save_project_config,
    update_state_entry,
    workspace_root,
)


ERRORLEVEL_MAP = {
    0: ("ok", "无错误或警告"),
    1: ("ok", "有警告"),
    2: ("error", "有错误"),
    3: ("error", "致命错误"),
    11: ("error", "无法打开工程文件"),
    12: ("error", "设备数据库缺失"),
    13: ("error", "写入错误"),
    15: ("error", "UV4 访问错误"),
    20: ("error", "未知错误"),
}

ACTION_FLAG = {
    "build": "-b",
    "rebuild": "-r",
    "clean": "-c",
    "flash": "-f",
}

UV4_TIMEOUT_SEC = 1800

GENERATED_OUTPUT_SUFFIXES = {
    ".axf",
    ".elf",
    ".hex",
    ".bin",
    ".o",
    ".d",
    ".crf",
    ".dep",
    ".htm",
    ".lnp",
    ".iex",
}


def parse_log(log_path: str) -> dict:
    metrics = {"errors": 0, "warnings": 0, "flash_bytes": 0, "ram_bytes": 0}
    if not os.path.isfile(log_path):
        return metrics

    with open(log_path, "r", encoding="utf-8", errors="replace") as file_obj:
        content = file_obj.read()

    error_match = re.search(r"(\d+)\s+Error\(s\)\s*,\s*(\d+