keil

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Keil MDK 工程构建

Keil MDK Project Build

本 skill 提供 Keil MDK 工程的发现、Target 枚举、构建、重建、清理能力，并返回可供

jlink/openocd

继续使用的固件产物路径。

flash

仅作为兼容入口保留。

This skill provides discovery, Target enumeration, build, rebuild, and clean capabilities for Keil MDK projects, and returns firmware artifact paths that can be used by

jlink/openocd

flash

is only retained as a compatibility entry.

配置

Configuration

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

Environment-level Configuration (skill/config.json)

skill 目录下的

config.json

包含环境级配置，首次使用前确认

uv4_exe

路径正确：

json

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

```
uv4_exe
```
：UV4.exe 完整路径（必填）
```
operation_mode
```
：
```
1
```
直接执行 /
```
2
```
输出风险摘要但不阻塞 /
```
3
```
执行前确认

The

config.json

in the skill directory contains environment-level configurations. Before first use, confirm that the

uv4_exe

path is correct:

json

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

```
uv4_exe
```
: Full path of UV4.exe (required)
```
operation_mode
```
:
```
1
```
Execute directly /
```
2
```
Output risk summary without blocking /
```
3
```
Confirm before execution

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

Project-level Configuration (workspace/.embeddedskills/config.json)

工程级共享配置统一保存在工作区的

.embeddedskills/config.json

中：

json

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

```
project
```
：默认工程路径（相对 workspace），构建成功后会自动更新
```
target
```
：默认 Target 名称，构建成功后会自动更新
```
log_dir
```
：构建日志输出目录，默认
```
.embeddedskills/build
```

Project-level shared configurations are uniformly stored in

.embeddedskills/config.json

in the workspace:

json

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

```
project
```
: Default project path (relative to workspace), which will be automatically updated after successful build
```
target
```
: Default Target name, which will be automatically updated after successful build
```
log_dir
```
: Build log output directory, default is
```
.embeddedskills/build
```

参数解析优先级

Parameter Parsing Priority

参数解析顺序（从高到低）：

CLI 显式参数
环境级配置（skill/config.json）
工程级配置（.embeddedskills/config.json）
```
.embeddedskills/state.json
```
（上次构建记录）
搜索/询问

Parameter parsing order (from highest to lowest):

Explicit CLI parameters
Environment-level configuration (skill/config.json)
Project-level configuration (.embeddedskills/config.json)
```
.embeddedskills/state.json
```
(last build record)
Search/query

子命令

Subcommands

子命令	用途	风险
`scan`	搜索当前目录下的 .uvprojx/.uvmpw 工程	低
`targets`	枚举工程中的 Target	低
`build`	增量编译	中
`rebuild`	全量重建	中
`clean`	清理工程	高
`flash`	通过 Keil 烧录固件（兼容入口，优先建议使用 jlink/openocd）	高

Subcommand	Purpose	Risk
`scan`	Search for .uvprojx/.uvmpw projects in the current directory	Low
`targets`	Enumerate Targets in the project	Low
`build`	Incremental compilation	Medium
`rebuild`	Full rebuild	Medium
`clean`	Clean the project	High
`flash`	Flash firmware via Keil (compatibility entry, priority recommendation to use jlink/openocd)	High

执行流程

Execution Flow

读取
```
config.json
```
，确认
```
uv4_exe
```
路径有效
未指定子命令时默认执行
```
scan
```
未提供工程路径时先执行
```
scan
```
搜索工程
同时发现多个工程或多个 Target 时，列出选项让用户选择，绝不自动猜测
```
build/rebuild/clean
```
按
```
operation_mode
```
决定是否需要确认
```
build/rebuild
```
成功后，尽量从工程配置中解析
```
flash_file
```
/
```
debug_file
```
等产物路径
```
flash
```
仅在最近一次构建成功时允许执行
所有构建命令输出到日志文件后解析，返回结构化结果

Read
```
config.json
```
and confirm that the
```
uv4_exe
```
path is valid
Default to executing
```
scan
```
when no subcommand is specified
Execute
```
scan
```
to search for projects first if no project path is provided
List options for users to choose when multiple projects or multiple Targets are found simultaneously, never guess automatically
```
build/rebuild/clean
```
decide whether confirmation is needed according to
```
operation_mode
```
After successful
```
build/rebuild
```
, try to parse artifact paths such as
```
flash_file
```
/
```
debug_file
```
from project configurations as much as possible
```
flash
```
is only allowed to execute when the last build was successful
All build commands are output to log files and then parsed, returning structured results

脚本调用

Script Invocation

skill 目录下有两个 Python 脚本，使用标准库实现，无额外依赖。

There are two Python scripts in the skill directory, implemented using standard libraries with no additional dependencies.

keil_project.py — 工程扫描与 Target 枚举

keil_project.py — Project Scanning and Target Enumeration

bash

undefined

bash

undefined

扫描工程

Scan projects

python <skill-dir>/scripts/keil_project.py scan --root <搜索目录> --json

python <skill-dir>/scripts/keil_project.py scan --root <search directory> --json

枚举 Target

Enumerate Targets

python <skill-dir>/scripts/keil_project.py targets --project <工程路径> --json

undefined

python <skill-dir>/scripts/keil_project.py targets --project <project path> --json

undefined

keil_build.py — 构建 / 重建 / 清理 / 烧录

keil_build.py — Build / Rebuild / Clean / Flash

bash

python <skill-dir>/scripts/keil_build.py <build|rebuild|clean|flash> \
  --uv4 <UV4路径> \
  --project <工程路径> \
  --target <TargetName> \
  --log-dir <日志目录> \
  --json

rebuild

额外支持

--clean-first

使用

-cr

而非

-r

。

bash

python <skill-dir>/scripts/keil_build.py <build|rebuild|clean|flash> \
  --uv4 <UV4 path> \
  --project <project path> \
  --target <TargetName> \
  --log-dir <log directory> \
  --json

rebuild

additionally supports

--clean-first

to use

-cr

instead of

-r

输出格式

Output Format

所有脚本以 JSON 格式返回，基础字段为

status

（ok/error）、

action

、

summary

、

details

，并可能附带

context

、

artifacts

、

metrics

、

state

、

next_actions

、

timing

。

成功示例：

json

{
  "status": "ok",
  "action": "build",
  "summary": "build 成功，errors=0 warnings=2",
  "details": {
    "project": "project.uvprojx",
    "target": "Debug",
    "log_file": ".build/project-Debug-build.log",
    "flash_file": "Objects/project.hex",
    "debug_file": "Objects/project.axf"
  },
  "metrics": { "errors": 0, "warnings": 2, "flash_bytes": 32768, "ram_bytes": 8192 }
}

错误示例：

json

{
  "status": "error",
  "action": "flash",
  "error": { "code": "build_not_clean", "message": "最近一次构建存在错误，禁止继续烧录" }
}

All scripts return results in JSON format. The basic fields are

status

(ok/error),

action

summary

details

, and may also include

context

artifacts

metrics

state

next_actions

timing

Success Example:

json

{
  "status": "ok",
  "action": "build",
  "summary": "build succeeded, errors=0 warnings=2",
  "details": {
    "project": "project.uvprojx",
    "target": "Debug",
    "log_file": ".build/project-Debug-build.log",
    "flash_file": "Objects/project.hex",
    "debug_file": "Objects/project.axf"
  },
  "metrics": { "errors": 0, "warnings": 2, "flash_bytes": 32768, "ram_bytes": 8192 }
}

Error Example:

json

{
  "status": "error",
  "action": "flash",
  "error": { "code": "build_not_clean", "message": "The last build had errors, flashing is prohibited" }
}

核心规则

Core Rules

不修改工程配置文件（.uvprojx / .uvmpw / .uvoptx）
不自动猜测工程路径或 Target，有歧义时必须询问用户
参数解析优先级详见上方"参数解析优先级"章节
构建成功后优先使用返回的
```
flash_file
```
/
```
debug_file
```
与
```
jlink/openocd
```
串联
```
flash
```
前必须确认最近一次构建成功（errors == 0）
```
clean
```
不在自动流程中隐式执行
构建失败时优先展示首个错误和日志文件路径
结果回显中始终包含工程名、Target 名、日志路径；若识别到产物路径也要回显

Do not modify project configuration files (.uvprojx / .uvmpw / .uvoptx)
Do not automatically guess project paths or Targets; must ask users when there is ambiguity
Refer to the "Parameter Parsing Priority" section above for parameter parsing priority
After successful build, prioritize using the returned
```
flash_file
```
/
```
debug_file
```
to integrate with
```
jlink/openocd
```
Must confirm that the last build was successful (errors == 0) before executing
```
flash
```
```
clean
```
is not implicitly executed in automatic processes
When build fails, prioritize displaying the first error and log file path
The result echo always includes the project name, Target name, and log path; if artifact paths are identified, they should also be echoed

参考

References

遇到编译器相关问题时可查阅

references/compiler-notes.md

。

For compiler-related issues, refer to

references/compiler-notes.md