ht32-code-mcp 0.4.0__tar.gz → 0.4.2__tar.gz

{ht32_code_mcp-0.4.0 → ht32_code_mcp-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ht32-code-mcp
-Version: 0.4.0
+Version: 0.4.2
 Summary: HT32 Code MCP Server - 为 AI Agent 提供 HT32 函数库/例程/模板检索与工程导出
 License-Expression: MIT
 Keywords: firmware,holtek,ht32,mcp,mcu

{ht32_code_mcp-0.4.0 → ht32_code_mcp-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ht32-code-mcp"
-version = "0.4.0"
+version = "0.4.2"
 description = "HT32 Code MCP Server - 为 AI Agent 提供 HT32 函数库/例程/模板检索与工程导出"
 requires-python = ">=3.11"
 license = "MIT"

{ht32_code_mcp-0.4.0 → ht32_code_mcp-0.4.2}/src/ht32_code_mcp/materializer.py

@@ -95,6 +95,28 @@ def pack_release_version(pack_path: Path) -> str:
     return m.group(1).decode()
 
 
+def pack_device_algorithm(pack_path: Path, device: str) -> str | None:
+    """DFP pdsc 中该 device 的首个 Flash 算法路径（如 `Flash/HT32F490x1_64.FLM`）。
+
+    只从随包 DFP 取，不按型号猜：M4 同一子系列不同容量用的是不同 FLM
+    （F49041=_64、F49031=_32；F49153=_128、F49163=_256；F49365=_256、F49395=_1024）。
+    """
+    try:
+        with zipfile.ZipFile(pack_path) as z:
+            names = [n for n in z.namelist() if n.lower().endswith(".pdsc")]
+            if not names:
+                return None
+            data = z.read(names[0]).decode("utf-8", errors="replace")
+    except zipfile.BadZipFile:
+        return None
+    m = re.search(r'<device[^>]*Dname="' + re.escape(device) + r'"[^>]*>(.*?)</device>',
+                  data, re.S)
+    if not m:
+        return None
+    alg = re.search(r'<algorithm[^>]*name="([^"]+\.FLM)"', m.group(1))
+    return alg.group(1) if alg else None
+
+
 # ------------------------------------------------------------------ recipe 装载
 def load_recipes(recipes_dir: Path) -> dict[str, dict]:
     recipes: dict[str, dict] = {}
@@ -652,9 +674,11 @@ class Materializer:
         # 4) Src_USER：官方字节 + 声明选项编辑 + 自有 main.c
         src_user = stage / "project" / "Src_USER"
         src_user.mkdir(parents=True, exist_ok=True)
-        def _resolve_target(stage: Path, target_path: str) -> Path | None:
+        def _resolve_target(stage: Path, target_path: str, *,
+                            require_existing: bool = False) -> Path | None:
             """源集目标路径（相对工程文件目录）-> staging 内实际路径；
-            library/utilities 下的文件由完整树整体拷贝负责，不重复复制（返回 None）。"""
+            library/utilities 下的文件由完整树整体拷贝负责，默认返回 None（不重复复制）；
+            require_existing=True 时返回树内路径，供「就地改写已拷贝字节」使用。"""
             tp = target_path.replace("/", "\\")
             if tp.startswith(".\\"):
                 return stage / "project" / "MDK_ARMv5" / tp[2:]
@@ -663,7 +687,7 @@ class Materializer:
             if tp.startswith("..\\..\\"):
                 rest = tp[len("..\\..\\"):]
                 if rest.startswith(("library\\", "utilities\\", "component\\")):
-                    return None  # 完整官方树已拷贝
+                    return stage / rest if require_existing else None
                 return stage / rest
             raise ContractError(RECIPE_MISMATCH, f"无法解析目标路径: {target_path}")
 
@@ -675,8 +699,15 @@ class Materializer:
                                        reason="官方示例文档，非构建资产"))
                 continue
             target_file = _resolve_target(stage, sf["target_path"])
-            if target_file is None:
-                continue  # library/utilities 完整树已覆盖（manifest 由树拷贝登记）
+            in_tree = target_file is None
+            base_name = Path(sf["origin"]).name
+            if in_tree:
+                # library/utilities 下的文件由完整官方树按字节拷贝（manifest 已由树拷贝登记）；
+                # 只有带声明式选项编辑的文件才就地改写，其余保持原样、不重复登记。
+                if not any(Path(e["origin"]).name == base_name
+                           for e in cfg.get("allowed_option_edits", [])):
+                    continue
+                target_file = _resolve_target(stage, sf["target_path"], require_existing=True)
             op = pkg / sf["origin"]
             data = op.read_bytes()
             fname = target_file.name
@@ -684,7 +715,6 @@ class Materializer:
             # retarget 默认开启 = 官方默认值（_RETARGET=1），无需编辑；
             # 非 hsi-safe 时钟 profile 用官方默认选项，不应用时钟编辑。
             applicable = []
-            base_name = Path(sf["origin"]).name
             for e in cfg.get("allowed_option_edits", []):
                 if Path(e["origin"]).name != base_name:
                     continue
@@ -701,13 +731,26 @@ class Materializer:
                     selector=e["selector"]["name"], old=e["old_value"], new=e["new_value"],
                     expected_matches=e["expected_matches"],
                     reason=f"profile {r.clock_profile}/{r.retarget_profile} 声明式官方选项差异"))
-            target_file.parent.mkdir(parents=True, exist_ok=True)
-            target_file.write_bytes(data)
-            manifest_files.append(dict(
-                path=target_file.relative_to(stage).as_posix(), bytes=len(data),
-                sha256=sha256_bytes(data), classification="official",
-                origin=f"{origin['package']}/{sf['origin']}",
-                edited=bool(applicable)))
+            if in_tree:
+                # 就地改写树拷贝字节，并更新树拷贝已登记的那条 manifest（字节/SHA/edited）
+                target_file.write_bytes(data)
+                rel = target_file.relative_to(stage).as_posix()
+                entry = next((m for m in manifest_files if m["path"] == rel), None)
+                if entry is None:
+                    manifest_files.append(dict(
+                        path=rel, bytes=len(data), sha256=sha256_bytes(data),
+                        classification="official",
+                        origin=f"{origin['package']}/{sf['origin']}", edited=True))
+                else:
+                    entry.update(bytes=len(data), sha256=sha256_bytes(data), edited=True)
+            else:
+                target_file.parent.mkdir(parents=True, exist_ok=True)
+                target_file.write_bytes(data)
+                manifest_files.append(dict(
+                    path=target_file.relative_to(stage).as_posix(), bytes=len(data),
+                    sha256=sha256_bytes(data), classification="official",
+                    origin=f"{origin['package']}/{sf['origin']}",
+                    edited=bool(applicable)))
         # 自有 main.c
         main_c = owned_main_source(r, cfg["device"])
         (src_user / "main.c").write_text(main_c, encoding="utf-8", newline="")
@@ -731,12 +774,7 @@ class Materializer:
         # uvoptx（受控调试配置；M4 用官方侧车，f5 用净化后的用户侧车，l5/f1 不提供）
         uvoptx_src = self._controlled_uvoptx(r)
         if uvoptx_src is not None:
-            data = uvoptx_src.read_bytes()
-            data, n = re.subn(rb"(<TargetName>)[^<]*(</TargetName>)",
-                              lambda m: m.group(1) + stem.encode() + m.group(2), data, count=1)
-            if n == 1:
-                deviations.append(dict(kind="uvoptx-targetname", file=uvprojx.name,
-                                       reason="受控 .uvoptx 的 TargetName 与工程名同步"))
+            data = self._render_uvoptx(r, uvprojx, uvoptx_src, pack, stem, deviations)
             target = proj_dir / f"{stem}.uvoptx"
             target.write_bytes(data)
             manifest_files.append(dict(
@@ -863,6 +901,23 @@ class Materializer:
             if f"<{tag}>" in text:
                 text = rewrite_tag_value(text, tag, stem, what)
                 edits.append(f"{tag} -> {stem}")
+        # e2) 声明式 uvprojx 选项编辑（如 M4 统一 -O2；命中数必须精确）
+        for e in cfg.get("project_edits", []):
+            tag = e["tag"]
+            old = f"<{tag}>{e['old_value']}</{tag}>"
+            new = f"<{tag}>{e['new_value']}</{tag}>"
+            hits = text.count(old)
+            if hits != e["expected_matches"]:
+                raise ContractError(
+                    RECIPE_MISMATCH,
+                    f"{what}: <{tag}>{e['old_value']}</{tag}> 预期命中 "
+                    f"{e['expected_matches']} 次，实际 {hits}")
+            text = text.replace(old, new)
+            edits.append(f"{tag} {e['old_value']} -> {e['new_value']}")
+            deviations.append(dict(
+                kind="project-option-edit", file=f"{stem}.uvprojx", tag=tag,
+                old=e["old_value"], new=e["new_value"],
+                reason=e.get("reason") or "声明式项目选项编辑"))
         # f) PackID -> recipe 锁定版本（声明式）
         pack_id = r.recipe["pack"]["id"]
         if f"<PackID>{pack_id}</PackID>" not in text and "<PackID>" in text:
@@ -897,6 +952,92 @@ class Materializer:
             f"{r.series}-controlled.uvoptx"
         return asset if asset.is_file() else None
 
+    def _render_uvoptx(self, r: Resolved, uvprojx: Path, src: Path, pack: dict,
+                       stem: str, deviations: list[dict]) -> bytes:
+        """把受控 .uvoptx 渲染成该 config 的调试侧车。
+
+        受控资产只保留骨架与占位符；芯片相关值全部来自**已裁决的 recipe.memory +
+        随包 DFP 的 Flash 算法**，不按型号猜：
+        - device / FLM：`pack_device_algorithm()`（M4 同子系列不同容量 FLM 不同）；
+        - Flash 基址/容量：`memory.flash[0]`；
+        - SW-DP ID：M4=2BA01477，M0+/M3=0BC11477；
+        - ListingPath：与 uvprojx 同步（uVision 以 uvoptx 为准）；
+        - CMSIS_AGDI 注册项含 `-FO15`（Reset and Run），与 M0+ 对齐。
+        """
+        cfg = r.config
+        what = cfg["config_id"]
+        device = cfg["device"]
+        flash = cfg["memory"]["flash"][0]
+        flash_base = int(flash["base"], 16)
+        flash_size = int(flash["size"], 16)
+        uv_text = uvprojx.read_text(encoding="utf-8", errors="replace")
+        m = re.search(r"<ListingPath>([^<]*)</ListingPath>", uv_text)
+        if not m:
+            raise ContractError(RECIPE_MISMATCH, f"{what}: uvprojx 缺 <ListingPath>")
+        listing = m.group(1)
+        m4 = r.series in ("ht32f490x1", "ht32f491x3", "ht32f493x5")
+        ram_alg = "1000"
+        if m4:
+            alg = pack_device_algorithm(pack["asset"], device)
+            if not alg:
+                raise ContractError(
+                    RECIPE_MISMATCH,
+                    f"{what}: 随包 DFP 未给出 {device} 的 Flash 算法（pdsc 无 algorithm）")
+            flm_path = alg.replace("/", "\\")
+            flm_base = Path(alg).stem
+            cmsis = (
+                '-X"Any" -UAny -O206 -S0 -C0 -P00 -N00("ARM CoreSight SW-DP") '
+                '-D00(2BA01477) -L00(0) -TO18 -TC10000000 -TP20 -TDS8007 -TDT0 -TDC1F '
+                '-TIEFFFFFFFF -TIP8 -FO15 -FD20000000 '
+                f"-FC{ram_alg} -FN1 -FF0{flm_base}.FLM "
+                f"-FS0{flash_base:X} -FL0{flash_size:X} "
+                f"-FP0($$Device:{device}${flm_path})")
+            ul2 = (
+                f"UL2CM3(-S0 -C0 -P0 -FD20000000 -FC{ram_alg} -FN1 -FF0{flm_base} "
+                f"-FS0{flash_base:X} -FL0{flash_size:X} "
+                f"-FP0($$Device:{device}${flm_path}))")
+        else:
+            cmsis = (
+                '-X"Any" -UAny -O206 -S0 -C0 -P00 -N00("ARM CoreSight SW-DP") '
+                '-D00(0BC11477) -L00(0) -TO18 -TC1000000 -TP20 -TDS8007 -TDT0 -TDC1F '
+                '-TIEFFFFFFFF -TIP8 -FO15 -FD20000000 '
+                f"-FC{ram_alg} -FN2 -FF0HT32F.FLM "
+                f"-FS0{flash_base:X} -FL0{flash_size:X} "
+                f"-FP0($$Device:{device}$ARM\\Flash\\HT32F.FLM) "
+                "-FF1HT32F_OPT.FLM -FS11FF00000 -FL11000 "
+                f"-FP1($$Device:{device}$ARM\\Flash\\HT32F_OPT.FLM)")
+            ul2 = (
+                f"UL2CM3(-S0 -C0 -P0 -FD20000000 -FC{ram_alg} -FN2 -FF0HT32F "
+                f"-FS0{flash_base:X} -FL0{flash_size:X} "
+                "-FF1HT32F_OPT -FS11FF00000 -FL11000 "
+                f"-FP0($$Device:{device}$ARM\\Flash\\HT32F.FLM) "
+                f"-FP1($$Device:{device}$ARM\\Flash\\HT32F_OPT.FLM))")
+        data = src.read_bytes()
+        edits: list[str] = []
+        for token, value in (
+                (b"__HT32_LISTING__", listing),
+                (b"__HT32_CMSIS_AGDI_NAME__", cmsis),
+                (b"__HT32_UL2CM3_NAME__", ul2)):
+            hits = data.count(token)
+            if hits != 1:
+                raise ContractError(
+                    RECIPE_MISMATCH,
+                    f"{what}: 受控 uvoptx 占位符 {token.decode()} 预期 1 次，实际 {hits}")
+            data = data.replace(token, value.encode())
+            edits.append(f"{token.decode()} -> {value[:60]}...")
+        data, n = re.subn(rb"(<TargetName>)[^<]*(</TargetName>)",
+                          lambda mm: mm.group(1) + stem.encode() + mm.group(2),
+                          data, count=1)
+        if n == 1:
+            edits.append(f"TargetName -> {stem}")
+        if b"__HT32_" in data:
+            raise ContractError(RECIPE_MISMATCH, f"{what}: uvoptx 仍有未替换占位符")
+        deviations.append(dict(
+            kind="uvoptx-materialized", file=f"{stem}.uvoptx", edits=edits,
+            reason="受控 uvoptx 按 device/FLM/memory/uvprojx ListingPath 参数化"
+                   "（含 CMSIS_AGDI -FO15 = Reset and Run）"))
+        return data
+
     # ------------------------------------------------------------ manifest
     def _write_manifests(self, r: Resolved, mdir: Path, stem: str, files: list[dict],
                          deviations: list[dict], notes: list[str], total_bytes: int,
@@ -979,14 +1120,18 @@ class Materializer:
         else:
             lines.append("- 调试：本系列无受控 `.uvoptx`，首次打开请在 Options for Target → Debug "
                          "选择 `CMSIS-DAP Debugger` 并保存")
+        result_khz = (r.config.get("clock") or {}).get("result_khz")
+        if r.clock_profile in ("hsi-safe", "hick-safe"):
+            clock_detail = ("（内部高速时钟安全配置，不依赖外晶振；"
+                            + (f"HSI 时钟 {result_khz / 1000:g} MHz；" if result_khz else "")
+                            + "官方选项组合）")
+        else:
+            clock_detail = "（官方默认时钟配置，依赖板级外晶振）"
         lines += [
             "",
             "## 导出 profile",
             "",
-            f"- 时钟：`{r.clock_profile}`"
-            + ("（内部高速时钟安全配置，不依赖外晶振；官方选项组合）"
-               if r.clock_profile in ("hsi-safe", "hick-safe")
-               else "（官方默认时钟配置，依赖板级外晶振）"),
+            f"- 时钟：`{r.clock_profile}`{clock_detail}",
             f"- 串口：`{r.retarget_profile}`",
         ]
         if r.retarget_profile == "retarget":

ht32_code_mcp-0.4.2/tests/test_export_cloud_mode.py

@@ -0,0 +1,83 @@
+"""回归测试：导出侧实测暴露的三个缺陷。
+
+1) 云端 zip 模式下响应格式化用了未定义的 `_fmt_time` → 线上 `export_project_bundle`
+   100% 失败（本地模式与直接调 `exporter.export_zip` 都覆盖不到这行）。
+2) 物化器的单次调用状态（`_stage` / `_project_rel`）曾挂在进程级单例实例上，
+   并发导出互相覆盖 → "…is not in the subpath of…" 串台错误。
+3) 默认时钟 profile `hsi-safe` 曾整体失效：官方 system 文件在 `library/` 下，由完整官方树
+   按字节拷贝，而选项编辑只作用于 `_resolve_target` 能定位到 staging 的文件 → 声明式编辑
+   从未落到 system 文件，导出工程仍依赖外部晶振（HSE）。
+"""
+from __future__ import annotations
+
+import concurrent.futures
+import json
+import re
+
+from ht32_code_mcp import server as srv
+
+CFG_F52352 = "ht32f52352.ht32f52352-sk.ac5.hsi-safe.retarget"
+CFG_F50241 = "ht32f50241.ht32f50241-sk.ac5.hsi-safe.retarget"
+CFG_L52241 = "ht32l52241.ht32l52241-sk.ac5.hsi-safe.retarget"
+
+
+def test_cloud_zip_response_formats_expiry(tmp_path, monkeypatch):
+    """云端模式必须能给出下载 URL 与有效期（不得因未定义的 helper 直接抛 NameError）。"""
+    monkeypatch.setattr(srv, "CLOUD_BUNDLE", True)
+    monkeypatch.setattr(srv, "BUNDLE_DIR", str(tmp_path / "bundles"))
+    monkeypatch.setattr(srv, "BUNDLE_BASE_URL", "http://example.test/ht32-bundles")
+    text = srv.export_project_bundle(config_id=CFG_F52352, project_name="CloudMode")
+    assert "导出失败" not in text, text
+    assert "下载 URL" in text and "http://example.test/ht32-bundles/" in text
+    assert "有效期" in text
+    assert list(tmp_path.joinpath("bundles").glob("*.zip")), "未生成 zip 产物"
+
+
+def test_concurrent_exports_do_not_cross_talk(tmp_path):
+    """并发导出必须各自落到自己的目录（不得因共享实例状态串台）。"""
+    jobs = [(CFG_F50241, "ConcA"), (CFG_L52241, "ConcB")]
+
+    def run(item):
+        idx, (cid, name) = item
+        return srv.export_project_bundle(
+            config_id=cid, project_name=name, out_dir=str(tmp_path / f"out{idx}"))
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=2) as pool:
+        texts = list(pool.map(run, enumerate(jobs)))
+
+    for text, (_, name) in zip(texts, jobs):
+        assert "导出失败" not in text, text
+    for idx, (_, name) in enumerate(jobs):
+        proj = tmp_path / f"out{idx}" / "project" / "MDK_ARMv5" / f"{name}.uvprojx"
+        assert proj.is_file(), f"并发导出产物缺失：{proj}"
+
+
+def test_hsi_safe_profile_edits_system_file_in_library_tree(tmp_path):
+    """hsi-safe 默认 profile 必须真正改写官方 system 文件（不得因 tree 拷贝路径整条跳过）。
+
+    F50241 的官方 system 文件属 hse-direct 家族（HCLK_SRC=2/HSE），编辑器应把它改成
+    HSE_ENABLE=0 + HCLK_SRC=3（HSI，20 MHz 满频），并在 deviations 留 option-edit 记录。
+    """
+    out = tmp_path / "out"
+    text = srv.export_project_bundle(config_id=CFG_F50241, project_name="HsiSafe",
+                                     out_dir=str(out))
+    assert "导出失败" not in text, text
+
+    # 完整官方树里有 ~20 个 system_*.c；只有本配置选中的那个应被改写
+    dev = json.loads((out / "manifest" / "deviations.json").read_text(encoding="utf-8"))
+    edits = [d for d in dev["deviations"] if d["kind"] == "option-edit"]
+    assert {d["selector"] for d in edits} >= {"HSE_ENABLE", "HCLK_SRC"}, f"缺 option-edit 记录：{edits}"
+    assert len({d["file"] for d in edits}) == 1, f"option-edit 跨了多个文件：{edits}"
+    sys_name = edits[0]["file"]
+
+    target = next((p for p in out.glob("library/Device/**/system_*.c") if p.name == sys_name), None)
+    assert target is not None, f"导出物里找不到 {sys_name}"
+    code = target.read_text(encoding="utf-8", errors="replace")
+    assert re.search(r"#define\s+HSE_ENABLE\s+\(0\)", code), "HSE_ENABLE 未被改写为 0"
+    assert re.search(r"#define\s+HCLK_SRC\s+\(3\)", code), "HCLK_SRC 未被改写为 3（HSI）"
+
+    files = json.loads((out / "manifest" / "files.json").read_text(encoding="utf-8"))
+    paths = [f["path"] for f in files["files"]]
+    assert len(paths) == len(set(paths)), "同一路径被重复登记（树拷贝 + 源集各一次）"
+    entry = next(f for f in files["files"] if f["path"].endswith("/" + sys_name))
+    assert entry.get("edited") is True, "system 文件的 manifest 条目未标记 edited"

ht32_code_mcp-0.4.2/tests/test_recipe_claims.py

@@ -0,0 +1,92 @@
+"""回归测试：retarget 串口声明（uart_pin_claims）的文案与真实头文件/宏一致。
+
+两个已实测的缺陷（都在 build_recipes.py 的 com1_claim() 里把宏名直接拼字符串）：
+1. 版级头文件名：README 写 `per utilities/HT32_Board/ht32f50241-sk.h`，实际文件是
+   `ht32f50241_sk.h`（板名 id 用连字符、头文件名用下划线）。从 recipe 数据侧兜底：
+   每条 claim 里的头文件名都必须能在官方包 `utilities/HT32_Board/` 下找到。
+2. 引脚宏粘连：README 写 `TX=GPIO_PAAFIO_PIN_4`，实际是「端口宏 GPIO_PA + 引脚宏
+   AFIO_PIN_4」两个独立宏，应为 `TX=GPIO_PA/AFIO_PIN_4`。
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[3]  # tests -> mcp-server -> .work -> ht32-code
+RECIPES = REPO / ".work" / "template-recipes" / "recipes"
+CLAIM_HEADER = re.compile(r"utilities/HT32_Board/([^)\s]+\.h)")
+# 引脚 = 端口宏 GPIO_Px + 引脚宏 AFIO_PIN_n，中间必须有一个 '/'
+CLAIM_PIN = re.compile(r"GPIO_P[A-H]?/AFIO_PIN_\d+")
+CLAIM_PIN_VALUE = re.compile(r"(?:TX|RX)=([^\s,)]+)")
+
+
+def _recipes() -> list[dict]:
+    return [json.loads(p.read_text(encoding="utf-8")) for p in sorted(RECIPES.glob("*.json"))]
+
+
+def test_claim_board_headers_exist_in_official_package():
+    missing: list[str] = []
+    checked = 0
+    for recipe in _recipes():
+        for cfg in recipe["configs"]:
+            for claim in (cfg.get("retarget") or {}).get("uart_pin_claims") or []:
+                m = CLAIM_HEADER.search(claim)
+                if not m:
+                    continue
+                checked += 1
+                header = REPO / "raw" / cfg["origin"]["package"] / "utilities" / "HT32_Board" / m.group(1)
+                if not header.is_file():
+                    missing.append(f"{cfg['config_id']}: {m.group(1)}")
+    assert checked > 0, "recipe 里没有可校验的板级头文件声明"
+    assert not missing, "claim 引用了不存在的板级头文件：\n" + "\n".join(missing)
+
+
+def test_claim_board_headers_use_real_file_names_not_board_ids():
+    """板名 id（连字符）不能直接当文件名；下划线才是官方文件名的分隔符。"""
+    wrong: list[str] = []
+    for recipe in _recipes():
+        for cfg in recipe["configs"]:
+            for claim in (cfg.get("retarget") or {}).get("uart_pin_claims") or []:
+                m = CLAIM_HEADER.search(claim)
+                if m and ("-sk.h" in m.group(1) or "-dvb.h" in m.group(1)):
+                    wrong.append(f"{cfg['config_id']}: {m.group(1)}")
+    assert not wrong, "claim 头文件名仍用板名 id 的连字符：\n" + "\n".join(wrong)
+
+
+def test_claim_pins_use_port_macro_slash_pin_macro():
+    """7 份 recipe 的 TX=/RX= 引脚都必须是 GPIO_Px/AFIO_PIN_n 形态。
+
+    端口宏（GPIO_PA）与引脚宏（AFIO_PIN_4）是两个独立宏；拼成 GPIO_PAAFIO_PIN_4
+    会被用户当成宏名照抄，编译不过。
+    """
+    bad: list[str] = []
+    checked = 0
+    for recipe in _recipes():
+        for cfg in recipe["configs"]:
+            for claim in (cfg.get("retarget") or {}).get("uart_pin_claims") or []:
+                for m in CLAIM_PIN_VALUE.finditer(claim):
+                    checked += 1
+                    if not CLAIM_PIN.fullmatch(m.group(1)):
+                        bad.append(f"{cfg['config_id']}: {m.group(0)}  <- {claim}")
+    assert checked >= 80, f"recipe 里可校验的 TX/RX 引脚过少（{checked}），疑似数据缺失"
+    assert not bad, ("claim 引脚宏形态不对（应为 GPIO_Px/AFIO_PIN_n，不能写成 "
+                     "GPIO_PAAFIO_PIN_n）：\n" + "\n".join(bad))
+
+
+def test_exported_readme_points_at_real_board_header(tmp_path):
+    """导出工程 README 的串口占用应指向真实板级头文件（下划线）、引脚宏用 '/' 分隔。"""
+    from ht32_code_mcp import server as srv
+
+    out = tmp_path / "bundle_f50241"
+    text = srv.export_project_bundle("HT32F50241", str(out))
+    assert "导出失败" not in text, text
+    readme = (out / "README.md").read_text(encoding="utf-8")
+    assert "ht32f50241_sk.h" in readme, readme
+    assert "ht32f50241-sk.h" not in readme, readme
+    # README「占用」行必须给出 GPIO_PA/AFIO_PIN_4（板级头：TX=PA4 / RX=PA5）
+    claim_line = next((ln for ln in readme.splitlines() if "占用" in ln), "")
+    assert "TX=GPIO_PA/AFIO_PIN_4" in claim_line, claim_line
+    assert "RX=GPIO_PA/AFIO_PIN_5" in claim_line, claim_line
+    assert "GPIO_PAAFIO" not in readme, readme
+

{ht32_code_mcp-0.4.0 → ht32_code_mcp-0.4.2}/tests/test_tools.py

@@ -478,6 +478,55 @@ def test_export_target_name_custom(tmp_path):
     assert (out / "README.md").read_text(encoding="utf-8").startswith("# F52352_UART_Printf")
 
 
+@pytest.mark.parametrize("config_id,device,flm", [
+    ("ht32f49041-20tssop.ht32f49041-sk.ac5.hick-safe.retarget",
+     "HT32F49041_20TSSOP", "HT32F490x1_64"),
+    ("ht32f49153-48lqfp.ht32f49163-sk.ac5.hick-safe.retarget",
+     "HT32F49153_48LQFP", "HT32F491x3_128"),
+    ("ht32f49365-64lqfp.ht32f49395-sk.ac5.hick-safe.retarget",
+     "HT32F49365_64LQFP", "HT32F493x5_256"),
+])
+def test_export_m4_debug_options_and_optimization(tmp_path, config_id, device, flm):
+    """M4：-O2、CMSIS_AGDI（-FO15）、FLM/device 按芯片参数化、ListingPath 同步。"""
+    out = tmp_path / config_id.split(".")[0]
+    srv.exporter.export_dir(out_dir=str(out), project_name="verify_proj", config_id=config_id)
+    uv = next((out / "project" / "MDK_ARMv5").glob("*.uvprojx"))
+    text = uv.read_text(encoding="utf-8")
+    assert "<Optim>3</Optim>" in text
+    listing = re.search(r"<ListingPath>([^<]*)</ListingPath>", text).group(1)
+    side = uv.with_suffix(".uvoptx")
+    side_text = side.read_text(encoding="utf-8")
+    assert "<Key>CMSIS_AGDI</Key>" in side_text
+    assert "<Key>UL2CM3</Key>" in side_text
+    assert "-FO15" in side_text
+    assert re.search(r"<ListingPath>" + re.escape(listing) + "</ListingPath>", side_text)
+    assert f"$$Device:{device}$" in side_text
+    assert flm in side_text
+    dev = json.loads((out / "manifest" / "deviations.json").read_text(encoding="utf-8"))
+    kinds = [d["kind"] for d in dev["deviations"]]
+    assert "project-option-edit" in kinds
+    assert "uvoptx-materialized" in kinds
+
+
+def test_export_m0_debug_sidecar_is_parameterized(tmp_path):
+    """M0+：uvoptx 的 device/Flash 容量与 uvprojx ListingPath 同步（不再固定 F52352）。"""
+    out = tmp_path / "f50030"
+    srv.exporter.export_dir(
+        out_dir=str(out), project_name="verify_proj",
+        config_id="ht32f50030.ht32f50030-sk.ac5.hsi-safe.retarget")
+    uv = next((out / "project" / "MDK_ARMv5").glob("*.uvprojx"))
+    text = uv.read_text(encoding="utf-8")
+    listing = re.search(r"<ListingPath>([^<]*)</ListingPath>", text).group(1)
+    output_dir = re.search(r"<OutputDirectory>([^<]*)</OutputDirectory>", text).group(1)
+    # obj 与 list 是同一芯片目录下的两个并列子目录；list 不得再落回工程根 .\List\
+    assert "HT32\\50030\\Obj\\" in output_dir
+    assert "HT32\\50030\\List\\" in listing
+    side_text = uv.with_suffix(".uvoptx").read_text(encoding="utf-8")
+    assert re.search(r"<ListingPath>" + re.escape(listing) + "</ListingPath>", side_text)
+    assert "$$Device:HT32F50030$" in side_text
+    assert "$$Device:HT32F52352$" not in side_text
+
+
 def test_export_unknown_chip(tmp_path):
     result = srv.export_project_bundle("HT32F99999", str(tmp_path / "nope"))
     assert "UNKNOWN_DEVICE" in result and "不在契约" in result

{ht32_code_mcp-0.4.0 → ht32_code_mcp-0.4.2}/uv.lock

@@ -440,7 +440,7 @@ wheels = [
 
 [[package]]
 name = "ht32-code-mcp"
-version = "0.4.0"
+version = "0.4.2"
 source = { editable = "." }
 dependencies = [
     { name = "fastmcp" },

ht32_code_mcp-0.4.0/tests/test_export_cloud_mode.py

@@ -1,47 +0,0 @@
-"""回归测试：线上实测暴露的两个导出缺陷。
-
-1) 云端 zip 模式下响应格式化用了未定义的 `_fmt_time` → 线上 `export_project_bundle`
-   100% 失败（本地模式与直接调 `exporter.export_zip` 都覆盖不到这行）。
-2) 物化器的单次调用状态（`_stage` / `_project_rel`）曾挂在进程级单例实例上，
-   并发导出互相覆盖 → "…is not in the subpath of…" 串台错误。
-"""
-from __future__ import annotations
-
-import concurrent.futures
-
-from ht32_code_mcp import server as srv
-
-CFG_F52352 = "ht32f52352.ht32f52352-sk.ac5.hsi-safe.retarget"
-CFG_F50241 = "ht32f50241.ht32f50241-sk.ac5.hsi-safe.retarget"
-CFG_L52241 = "ht32l52241.ht32l52241-sk.ac5.hsi-safe.retarget"
-
-
-def test_cloud_zip_response_formats_expiry(tmp_path, monkeypatch):
-    """云端模式必须能给出下载 URL 与有效期（不得因未定义的 helper 直接抛 NameError）。"""
-    monkeypatch.setattr(srv, "CLOUD_BUNDLE", True)
-    monkeypatch.setattr(srv, "BUNDLE_DIR", str(tmp_path / "bundles"))
-    monkeypatch.setattr(srv, "BUNDLE_BASE_URL", "http://example.test/ht32-bundles")
-    text = srv.export_project_bundle(config_id=CFG_F52352, project_name="CloudMode")
-    assert "导出失败" not in text, text
-    assert "下载 URL" in text and "http://example.test/ht32-bundles/" in text
-    assert "有效期" in text
-    assert list(tmp_path.joinpath("bundles").glob("*.zip")), "未生成 zip 产物"
-
-
-def test_concurrent_exports_do_not_cross_talk(tmp_path):
-    """并发导出必须各自落到自己的目录（不得因共享实例状态串台）。"""
-    jobs = [(CFG_F50241, "ConcA"), (CFG_L52241, "ConcB")]
-
-    def run(item):
-        idx, (cid, name) = item
-        return srv.export_project_bundle(
-            config_id=cid, project_name=name, out_dir=str(tmp_path / f"out{idx}"))
-
-    with concurrent.futures.ThreadPoolExecutor(max_workers=2) as pool:
-        texts = list(pool.map(run, enumerate(jobs)))
-
-    for text, (_, name) in zip(texts, jobs):
-        assert "导出失败" not in text, text
-    for idx, (_, name) in enumerate(jobs):
-        proj = tmp_path / f"out{idx}" / "project" / "MDK_ARMv5" / f"{name}.uvprojx"
-        assert proj.is_file(), f"并发导出产物缺失：{proj}"