keil

Keil MDK project build

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 for continued use.flash is retained only as a compatibility entry point.

Configuration

Environment-level configuration (skill/config.json)

In the skill directory, config.json contains environment-level configuration; before first use, confirm that the uv4_exe path is correct:

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

• uv4_exe: Full path to UV4.exe (required)
• operation_mode：1 Execute directly / 2 Output a risk summary but do not block / 3 Confirm before execution

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

Project-level shared configuration is stored uniformly in the workspace's .embeddedskills/config.json :

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

• project: Default project path (relative to workspace); automatically updated after a successful build
• target: Default Target name; automatically updated after a successful build
• log_dir: Build log output directory, default .embeddedskills/build

Parameter resolution priority

Parameter resolution order (from high to low):

1. Explicit CLI parameters
2. Environment-level configuration (skill/config.json)
3. Project-level configuration (.embeddedskills/config.json)
4. .embeddedskills/state.json(last build record)
5. Search/ask

Subcommands

Subcommand	Purpose	Risk
scan	Search for .uvprojx/.uvproj/.uvmpw projects in the current directory	Low
targets	Enumerate Targets in the project	Low
build	Incremental build	Medium
rebuild	Full rebuild	Medium
clean	Clean project	High
flash	Flash firmware via Keil (compatibility entry point; jlink/openocd are recommended first)	High

Execution flow

1. Read config.json, confirm that the uv4_exe path is valid
2. When no subcommand is specified, execute by default scan
3. When no project path is provided, first execute scan to search for projects
4. When multiple projects or multiple Targets are discovered at the same time, list the options for the user to choose; never guess automatically
5. build/rebuild/clean According to operation_mode , decide whether confirmation is required
6. build/rebuild After success, try as much as possible to parse from the project configuration flash_file / debug_file and other artifact paths
7. flash Only allowed to execute when the most recent build succeeded
8. All build commands output to a log file and are then parsed, returning structured results

Script invocation

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

keil_project.py — project scanning and Target enumeration

# 扫描工程
python <skill-dir>/scripts/keil_project.py scan --root <搜索目录> --json

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

keil_build.py — build / rebuild / clean / flash

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

rebuild Additionally supports --clean-first Use -cr instead of -r。

Output format

All scripts return in JSON format; the base field is status（ok/error）、action、summary、details, and may also include context、artifacts、metrics、state、next_actions、timing。

Success example:

{
  "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 }
}

Incorrect example:

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

Core rules

• Do not modify project configuration files (.uvprojx / .uvproj / .uvmpw / .uvoptx)
• .uvproj(legacy MDK4 project) and .uvprojx share the same XML structure (Target/TargetOption/TargetCommonOption); artifact parsing, Target enumeration, and scanning all support both suffixes
• Do not automatically guess the project path or Target; when there is ambiguity, you must ask the user
• For parameter parsing priority, see the "Parameter parsing priority" section above
• After a successful build, preferentially use the returned flash_file / debug_file and jlink/openocd in sequence
• flash Before this, you must confirm that the most recent build succeeded (errors == 0)
• clean is not implicitly executed in the automated flow
• When a build fails, preferentially display the first error and the log file path
• The result output always includes the project name, Target name, and log path; if an artifact path is identified, it must also be output

Reference

When encountering compiler-related issues, you can consult references/compiler-notes.md。