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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ht32-code-mcp
-Version: 0.4.0
+Version: 0.4.1
 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.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ht32-code-mcp"
-version = "0.4.0"
+version = "0.4.1"
 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.1}/src/ht32_code_mcp/materializer.py

@@ -652,9 +652,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 +665,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 +677,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 +693,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 +709,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="")
@@ -979,14 +1000,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.1/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.0 → ht32_code_mcp-0.4.1}/uv.lock

@@ -440,7 +440,7 @@ wheels = [
 
 [[package]]
 name = "ht32-code-mcp"
-version = "0.4.0"
+version = "0.4.1"
 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}"