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

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

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

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

{ht32_code_mcp-0.3.2 → ht32_code_mcp-0.4.1}/src/ht32_code_mcp/exporter.py

@@ -69,7 +69,7 @@ class ProjectExporter:
     def export_dir(self, *, out_dir: str, project_name: str = "", config_id: str = "",
                    chip: str = "", device: str = "", board: str = "",
                    clock_profile: str = "", retarget_profile: str = "",
-                   include_host_tools: bool = False) -> ExportResult:
+                   include_host_tools: bool = True) -> ExportResult:
         r = self.resolve(config_id=config_id, chip=chip, device=device, board=board,
                          clock_profile=clock_profile, retarget_profile=retarget_profile)
         res = self.materializer.materialize(
@@ -81,7 +81,7 @@ class ProjectExporter:
                    project_name: str = "", config_id: str = "", chip: str = "",
                    device: str = "", board: str = "", clock_profile: str = "",
                    retarget_profile: str = "",
-                   include_host_tools: bool = False) -> ExportResult:
+                   include_host_tools: bool = True) -> ExportResult:
         r = self.resolve(config_id=config_id, chip=chip, device=device, board=board,
                          clock_profile=clock_profile, retarget_profile=retarget_profile)
         bdir = Path(bundle_dir).expanduser().resolve()
@@ -111,7 +111,9 @@ class ProjectExporter:
         lock = res.out_dir / "manifest" / "project-lock.json"
         manifest_rel = "manifest/project-lock.json"
         requires = {
-            "pack": r.recipe["pack"]["id"],
+            "pack": res.pack["id"],
+            "pack_min_version": res.pack["min_version"],
+            "pack_file": res.pack["rel"],
             "pack_note": r.recipe["pack"]["device_macro_note"],
             "keil": "MDK-ARM 5.x (AC5)",
         }
@@ -151,7 +153,9 @@ class ProjectExporter:
             + (f"；冲突记录 {len(mem['conflicts'])} 条" if mem["conflicts"] else ""),
             f"- 文件数/字节: {res.files} / {res.bytes}",
             f"- 树 SHA256: {res.sha256}",
-            f"- 前置: {r.recipe['pack']['device_macro_note']}",
+            f"- 前置 DFP: 随包携带 `{res.pack['rel']}`（{res.pack['id']} v{res.pack['version']}，"
+            f"SHA256 {res.pack['sha256'][:16]}…）；本机已装同名 DFP 且版本 "
+            f">= {res.pack['min_version']} 可跳过安装",
         ]
         if r.retarget_profile == "retarget":
             claims = cfg["retarget"]["uart_pin_claims"]

{ht32_code_mcp-0.3.2 → ht32_code_mcp-0.4.1}/src/ht32_code_mcp/materializer.py

@@ -35,7 +35,13 @@ PACK_REQUIRED = "PACK_REQUIRED"
 CONFIG_CLOSURE_FAILED = "CONFIG_CLOSURE_FAILED"
 RECIPE_MISMATCH = "RECIPE_MISMATCH"
 
-HOST_TOOL_DIRS = {"gsar", "gsars", "elink", "elink32pro", "pack"}
+# host 组件目录（官方包 utilities/ 下）：独立 host 工具，opt-out 时排除。
+# pack/ 不在此列——DFP 安装包由 recipe 的 pack.asset 显式物化锁定版本，
+# 官方包内那份未必是锁定版本（L5 包内为 1.0.77），故一律不直接拷贝。
+HOST_TOOL_DIRS = {"gsar", "gsars", "elink", "elink32pro"}
+
+# <Vendor>.<Name>.<Major.Minor.Patch>；版本号取末尾三段，故不能用 rsplit(".", 1)
+PACK_ID_RE = re.compile(r"^(?P<vendor>[^.]+)\.(?P<name>.+?)\.(?P<version>\d+\.\d+\.\d+)$")
 
 # 不得外发的文件/目录（隐私与卫生，W4；由 manifest 驱动而非目录黑名单）
 FORBIDDEN_PATTERNS = [
@@ -67,6 +73,28 @@ def sha256_file(path: Path) -> str:
     return h.hexdigest()
 
 
+def parse_version(text: str) -> tuple[int, ...]:
+    """"1.0.78" -> (1, 0, 78)；DFP 版本只做数字段比较（用户口径：相同或更高即可）。"""
+    return tuple(int(x) for x in re.findall(r"\d+", text or "")[:3]) or (0,)
+
+
+def pack_release_version(pack_path: Path) -> str:
+    """读 .pack（zip）内 pdsc 的首个 <release> 版本号 = 该安装包提供的 DFP 版本。"""
+    try:
+        with zipfile.ZipFile(pack_path) as z:
+            names = [n for n in z.namelist() if n.lower().endswith(".pdsc")]
+            if not names:
+                raise ContractError(PACK_REQUIRED,
+                                    f"{pack_path.name} 内不含 pdsc，无法确认 DFP 版本")
+            data = z.read(names[0])
+    except zipfile.BadZipFile as e:  # 截断/损坏的 pack 不能被当成有效资产
+        raise ContractError(PACK_REQUIRED, f"{pack_path.name} 不是有效的 pack（zip）: {e}")
+    m = re.search(rb'<release version="([0-9]+\.[0-9]+\.[0-9]+)"', data)
+    if not m:
+        raise ContractError(PACK_REQUIRED, f"{pack_path.name} 的 pdsc 未声明 release 版本")
+    return m.group(1).decode()
+
+
 # ------------------------------------------------------------------ recipe 装载
 def load_recipes(recipes_dir: Path) -> dict[str, dict]:
     recipes: dict[str, dict] = {}
@@ -374,6 +402,7 @@ class MaterialResult:
     manifest_dir: str
     warnings: list[str]
     deviations: list[dict]
+    pack: dict
 
 
 class Materializer:
@@ -426,14 +455,63 @@ class Materializer:
         notes.append(f"origin={origin['kind']} package={origin['package']}")
         return notes
 
+    # ------------------------------------------------------------ 随包 DFP（存在性检查）
+    def _resolve_pack(self, r: Resolved) -> dict:
+        """解析并校验 recipe 声明的 DFP 安装包资产（导出工程默认随包携带）。
+
+        三项机器校验缺一不可，任一不成立即 PACK_REQUIRED（不静默降级、不跳过）：
+        1. 资产存在（仓库内 .pack 文件，随仓库检出）；
+        2. 资产 SHA256 == recipe 的 asset_sha256（来源锁未破）；
+        3. pack 内 pdsc 声明的 DFP 版本 >= 要求版本，且与锁定 id 的版本段一致
+           （保证工程 <PackID> 与随包安装的 DFP 版本对得上）。
+        """
+        spec = r.recipe["pack"]
+        if spec.get("install_policy") != "bundled":
+            raise ContractError(
+                PACK_REQUIRED,
+                f"{r.config_id}: pack.install_policy={spec.get('install_policy')!r} 不支持"
+                "（本契约只接受 bundled：DFP 必须随包携带）")
+        asset_rel = spec.get("asset") or ""
+        asset = (self.root / asset_rel).resolve() if asset_rel else None
+        if not asset_rel or not asset or not asset.is_file():
+            raise ContractError(
+                PACK_REQUIRED,
+                f"{r.config_id}: 随包 DFP 资产缺失（recipe pack.asset={asset_rel or '未声明'}）；"
+                "确认 .work/template-recipes/assets/packs/ 已随仓库检入")
+        digest = sha256_file(asset)
+        if spec.get("asset_sha256") and digest != spec["asset_sha256"]:
+            raise ContractError(
+                PACK_REQUIRED,
+                f"{r.config_id}: 随包 DFP 资产 SHA256 不符：{asset.name} 实测 {digest[:16]}…，"
+                f"recipe 锁 {spec['asset_sha256'][:16]}…（资产被替换或损坏）")
+        version = pack_release_version(asset)
+        min_version = spec.get("min_version") or ""
+        if parse_version(version) < parse_version(min_version):
+            raise ContractError(
+                PACK_REQUIRED,
+                f"{r.config_id}: 随包 DFP 版本 {version} 低于要求 {min_version}")
+        pid = PACK_ID_RE.match(spec["id"])
+        if not pid or pid.group("version") != version:
+            raise ContractError(
+                PACK_REQUIRED,
+                f"{r.config_id}: 随包 DFP 版本 {version} 与锁定 id {spec['id']} 不一致"
+                "（工程 <PackID> 将指向未随包的版本）")
+        return dict(id=spec["id"], version=version, min_version=min_version,
+                    asset=asset, rel=f"utilities/pack/{asset.name}",
+                    sha256=digest, bytes=asset.stat().st_size)
+
     # ------------------------------------------------------------ 文件计划
     def _copy_official_tree(self, src: Path, dst: Path, manifest_files: list[dict],
-                            pkg_name: str, *, skip_host_tools: bool = True) -> None:
+                            pkg_name: str, *, skip_host_tools: bool = True,
+                            skip_top: set[str] | None = None) -> None:
         for p in sorted(src.rglob("*")):
             if not p.is_file():
                 continue
             rel = p.relative_to(src).as_posix()
-            if skip_host_tools and rel.split("/")[0] in HOST_TOOL_DIRS:
+            top = rel.split("/")[0]
+            if top in (skip_top or set()):
+                continue
+            if skip_host_tools and top in HOST_TOOL_DIRS:
                 continue
             target = dst / rel
             target.parent.mkdir(parents=True, exist_ok=True)
@@ -444,11 +522,13 @@ class Materializer:
                 origin=f"{pkg_name}/{src.relative_to(self.raw / pkg_name).as_posix()}/{rel}"))
 
     def materialize(self, r: Resolved, out_dir: str | Path, *, project_name: str = "",
-                    include_host_tools: bool = False, verify_pack: bool = False) -> MaterialResult:
+                    include_host_tools: bool = True) -> MaterialResult:
         out = Path(out_dir).expanduser().resolve()
         if out.exists() and any(out.iterdir()):
             raise ContractError("TARGET_EXISTS", f"目标目录非空，拒绝覆盖：{out}")
         notes = self.preflight(r)
+        # 随包 DFP：存在性 / 资产 SHA256 / 版本 >= min_version 三项校验，先于 staging
+        pack = self._resolve_pack(r)
         cfg = r.config
         origin = cfg["origin"]
         pkg = self.raw / origin["package"]
@@ -466,7 +546,7 @@ class Materializer:
         deviations: list[dict] = []
         try:
             self._build_tree(r, stage, stem, kernel, board_dir, manifest_files,
-                             deviations, include_host_tools)
+                             deviations, include_host_tools, pack)
             # 产物卫生终检（W4）：不得外发的模式
             bad = [f["path"] for f in manifest_files
                    if any(re.search(p, f["path"]) for p in FORBIDDEN_PATTERNS)]
@@ -481,7 +561,7 @@ class Materializer:
             mdir = stage / "manifest"
             mdir.mkdir(parents=True, exist_ok=True)
             self._write_manifests(r, mdir, stem, manifest_files, deviations, notes,
-                                  total_bytes, tree_hash, len(manifest_files))
+                                  total_bytes, tree_hash, len(manifest_files), pack)
             # 原子发布（Windows 上目录重命名可能被 AV/索引器瞬态拒绝，长退避重试）
             last_err = None
             for attempt in range(10):
@@ -505,12 +585,12 @@ class Materializer:
         return MaterialResult(out_dir=out, project_file=self._local.project_rel,
                               files=len(manifest_files), bytes=total_bytes,
                               sha256=tree_hash, manifest_dir="manifest",
-                              warnings=r.warnings, deviations=deviations)
+                              warnings=r.warnings, deviations=deviations, pack=pack)
 
     # ------------------------------------------------------------ 树构建
     def _build_tree(self, r: Resolved, stage: Path, stem: str, kernel: str,
                     board_dir: str, manifest_files: list[dict], deviations: list[dict],
-                    include_host_tools: bool) -> None:
+                    include_host_tools: bool, pack: dict) -> None:
         cfg = r.config
         origin = cfg["origin"]
         pkg = self.raw / origin["package"]
@@ -520,7 +600,7 @@ class Materializer:
         lib_src = pkg / ("libraries" if kernel == "m4" else "library")
         lib_dst = stage / "library"
         self._copy_official_tree(lib_src, lib_dst, manifest_files, origin["package"])
-        # 2) utilities：官方构建资产；host 工具默认排除（D2 已授权，opt-in 携带）
+        # 2) utilities：官方构建资产；host 工具（gsar/eLink32pro）默认随包
         if kernel == "m4":
             board_asset = r.recipe.get("board_asset_dir") or board_dir
             util_src = pkg / "project" / board_asset
@@ -529,14 +609,33 @@ class Materializer:
             util_src = pkg / "utilities"
             util_dst = stage / "utilities"
         if util_src.is_dir():
+            # 官方包内的 DFP 安装包（utilities/pack/）不直接拷：L5 包内是 1.0.77，
+            # 与锁定版本不符；统一由 recipe 的 pack.asset 物化锁定版本（见 2b）
             self._copy_official_tree(util_src, util_dst, manifest_files, origin["package"],
-                                     skip_host_tools=not include_host_tools)
+                                     skip_host_tools=not include_host_tools,
+                                     skip_top={"pack"})
             if not include_host_tools and kernel != "m4":
                 deviations.append(dict(
                     kind="host-tools-excluded",
-                    detail="utilities/{gsar,elink32pro,pack} 为独立 host 组件，默认 profile 不分发"
-                           "（D2 已授权可分发；opt-in include_host_tools 携带）",
+                    detail="utilities/{gsar,elink32pro} 为独立 host 组件，本 profile 不分发"
+                           "（D2 已授权可分发；include_host_tools=true 时携带）",
                     reason="report section 4.7 project boundary; licensing approved (D2)"))
+        # 2b) 随包 DFP 安装包（已通过存在性/SHA256/版本三项校验）
+        pack_dst = stage / pack["rel"]
+        pack_dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(pack["asset"], pack_dst)
+        manifest_files.append(dict(
+            path=pack["rel"], bytes=pack["bytes"], sha256=pack["sha256"],
+            classification="official",
+            origin=f"vendor-pack:{pack['id']}（Holtek 官方 DFP 安装包，"
+                   "https://www.holtek.com.tw/pack）"))
+        deviations.append(dict(
+            kind="dfp-pack-bundled",
+            file=pack["rel"],
+            detail=f"{pack['id']} v{pack['version']}，{pack['bytes']} B，"
+                   f"SHA256 {pack['sha256'][:16]}…（源 holtek.com.tw/pack，资产冻结在仓库）",
+            reason="用户决策 2026-10-18：DFP 默认随范例工程携带，免去用户自行寻找安装包；"
+                   f"本机已装同名 DFP 且版本 >= {pack['min_version']} 时可跳过安装"))
         # 3) licenses：官方许可文件
         lic_dst = stage / "licenses"
         lic_dst.mkdir(parents=True, exist_ok=True)
@@ -553,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:]
@@ -564,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}")
 
@@ -576,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
@@ -585,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
@@ -602,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="")
@@ -646,7 +766,7 @@ class Materializer:
                 origin=str(uvoptx_src.relative_to(self.root).as_posix())))
 
         # 6) README（用户工程说明，与真实策略一致）
-        readme = self._readme(r, stem)
+        readme = self._readme(r, stem, pack)
         (stage / "README.md").write_text(readme, encoding="utf-8")
         manifest_files.append(dict(path="README.md", bytes=len(readme.encode()),
                                    sha256=sha256_bytes(readme.encode()),
@@ -801,7 +921,7 @@ class Materializer:
     # ------------------------------------------------------------ manifest
     def _write_manifests(self, r: Resolved, mdir: Path, stem: str, files: list[dict],
                          deviations: list[dict], notes: list[str], total_bytes: int,
-                         tree_hash: str, file_count: int) -> None:
+                         tree_hash: str, file_count: int, pack: dict) -> None:
         cfg = r.config
         lock = {
             "contract_version": CONTRACT_VERSION,
@@ -814,8 +934,14 @@ class Materializer:
             "profiles": {"clock": r.clock_profile, "retarget": r.retarget_profile},
             "origin": cfg["origin"],
             "memory": cfg["memory"],
-            "pack": r.recipe["pack"],
-            "requires": {"pack": r.recipe["pack"]["id"],
+            "pack": {"id": pack["id"], "version": pack["version"],
+                     "min_version": pack["min_version"], "file": pack["rel"],
+                     "sha256": pack["sha256"], "bytes": pack["bytes"],
+                     "source": "Holtek 官方 pack（https://www.holtek.com.tw/pack）",
+                     "install_hint": "首次使用在本工程内双击安装；"
+                                     f"本机已装同名 DFP 且版本 >= {pack['min_version']} 时可跳过"},
+            "requires": {"pack": pack["id"],
+                         "pack_min_version": pack["min_version"],
                          "pack_note": r.recipe["pack"]["device_macro_note"],
                          "keil": "MDK-ARM 5.x (AC5), UV4 command line verified"},
             "licensing": cfg["licensing"],
@@ -839,7 +965,7 @@ class Materializer:
             "compile_command": f'UV4 -b "{self._local.project_rel}" -j0 -o build.log',
         }, ensure_ascii=False, indent=1), encoding="utf-8")
 
-    def _readme(self, r: Resolved, stem: str) -> str:
+    def _readme(self, r: Resolved, stem: str, pack: dict) -> str:
         cfg = r.config
         claims = cfg["retarget"]["uart_pin_claims"]
         kernel = "m4" if r.series in ("ht32f493x5", "ht32f490x1", "ht32f491x3") else "m0m3"
@@ -855,8 +981,10 @@ class Materializer:
             f"- Keil MDK-ARM 5.x，编译器 **AC5（armcc）**（本地以 ARMCC V5.06 update 4/7 实测）"
             f"——**本工程暂不支持 AC6（armclang）**，请在 Options for Target → Target 保持"
             f"编译器版本为 AC5；切到 AC6 可能在编译/链接阶段报错",
-            f"- {r.recipe['pack']['device_macro_note']}（manifest 锁定 "
-            f"`{r.recipe['pack']['id']}`）",
+            f"- DFP（器件支持包）**已随本工程提供**：`{pack['rel']}`"
+            f"（{pack['id']}，版本 {pack['version']}，SHA256 `{pack['sha256'][:16]}…`）"
+            f"——首次使用在本工程内双击该文件安装（或 Keil Pack Installer → File → Import）；"
+            f"**本机已装同名 DFP 且版本 ≥ {pack['min_version']} 时可跳过安装**",
             "",
             "## 打开与编译",
             "",
@@ -872,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":
@@ -894,7 +1026,8 @@ class Materializer:
             "| 目录 | 内容 |",
             "|---|---|",
             "| `library/` | 完整官方库（字节冻结，manifest/files.json 可逐文件核对） |",
-            "| `utilities/` | 官方板级/公共构建资产（默认不含 gsar/eLink32pro/pack 等 host 工具） |",
+            "| `utilities/` | 官方板级/公共构建资产 + host 工具（`gsar/`、`elink32pro/`）"
+            "+ DFP 安装包（`pack/`，见上「前置条件」） |",
             "| `project/MDK_ARMv5/` | 工程文件（由官方逐 IC 工程声明式物化） |",
             "| `project/Src_USER/` | 用户源码：自有 `main.c` + 官方配置/中断文件 |",
             "| `licenses/` | 官方许可文件 |",

{ht32_code_mcp-0.3.2 → ht32_code_mcp-0.4.1}/src/ht32_code_mcp/server.py

@@ -441,6 +441,9 @@ def get_project_manifest() -> str:
                  "工程文件按工程名重命名为 <project_name>.uvprojx，模板自用文件"
                  "（devices.json / 模板维护文档）不外发，根目录改为生成属于用户工程的 README.md；"
                  "project_name 缺省为型号——**应先向用户确认工程名**，用户同意后才用型号兜底。")
+    lines.append("DFP 随包：导出工程 `utilities/pack/` 内即为 recipe 锁定的官方 DFP 安装包"
+                 "（版本与资产 SHA256 在导出前机器校验，不符即报 PACK_REQUIRED），"
+                 "用户首次使用在本工程内安装即可；已装同名 DFP 且版本不低于要求版本时可跳过。")
     lines.append("交付方式：" + (
         f"云端 zip 下载（随机 token + {BUNDLE_TTL}s TTL，返回下载 URL，out_dir 忽略）"
         if CLOUD_BUNDLE else "本地目录导出（out_dir 必填）"))
@@ -457,7 +460,7 @@ def export_project_bundle(
     board: str = "",
     clock_profile: str = "",
     retarget_profile: str = "",
-    include_host_tools: bool = False,
+    include_host_tools: bool = True,
 ) -> str:
     """导出自包含可编译 Keil 工程（v2 契约：recipe 物化 + manifest + 原子发布）。
 
@@ -467,6 +470,10 @@ def export_project_bundle(
     响应含 contract_version/config_id/recipe_revision/device/board/compiler/
     profiles/工程文件/manifest/树 SHA256/前置依赖/warnings/validation。
 
+    DFP（器件支持包）随包携带：工程 `utilities/pack/` 内即为 recipe 锁定的官方 DFP
+    安装包（资产 SHA256 与版本在物化前机器校验，不符即 PACK_REQUIRED 报错），
+    用户首次使用在本工程内安装即可；本机已装同名 DFP 且版本不低于要求版本时可跳过。
+
     两种交付形态（由服务端环境决定，无需调用方判断）：
     - 云端模式：返回带 TTL 的 zip 下载 URL（含 SHA256 与大小），out_dir 被忽略。
     - 本地模式：物化到 out_dir（须为空目录或不存在；不会覆盖已有内容）。
@@ -485,8 +492,8 @@ def export_project_bundle(
         out_dir: 输出目录（本地模式必填；云端模式忽略）。
         project_name: 工程名（可选）——工程文件名主干、Target 名与输出名；
             缺省取型号；**调用方应先向用户确认工程名**。
-        include_host_tools: 是否随包携带 host 工具（gsar/eLink32pro/pack，
-            默认不携带；D2 已授权可分发）。
+        include_host_tools: 是否随包携带 host 工具（gsar/eLink32pro；默认 True，
+            D2 已授权可分发）。DFP 安装包不受此开关影响——它始终随包携带。
     """
     try:
         if CLOUD_BUNDLE:

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.3.2 → ht32_code_mcp-0.4.1}/tests/test_tools.py

@@ -4,6 +4,7 @@
 """
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import re
@@ -15,6 +16,7 @@ from pathlib import Path
 import pytest
 
 from ht32_code_mcp import server as srv
+from ht32_code_mcp.materializer import pack_release_version
 from ht32_code_mcp.usage import UsageMiddleware
 
 FWLIB = "raw/HT32_STD_5xxxx_FWLib_V1.21.1"
@@ -287,12 +289,94 @@ def _bundle_checks_v2(out_dir: Path, device: str, config_id: str = ""):
     official = [f for f in files["files"] if f["classification"] == "official"]
     assert official, "没有任何 official 分类文件"
     assert all(f.get("origin") for f in official), "official 文件缺 origin"
+    # DFP 随包（用户决策 2026-10-18）：安装包在工程内，版本/SHA256/包内 pdsc 三者与 lock 一致
+    pack = lock["pack"]
+    assert lock["requires"]["pack"] == pack["id"]
+    assert lock["requires"]["pack_min_version"] == pack["min_version"]
+    assert pack["version"] == pack["min_version"], "随包 DFP 版本必须等于要求版本（锁定版本）"
+    assert pack["file"].startswith("utilities/pack/")
+    pack_file = out_dir / pack["file"]
+    assert pack_file.is_file(), f"随包 DFP 缺失：{pack['file']}"
+    assert pack_file.stat().st_size == pack["bytes"]
+    assert hashlib.sha256(pack_file.read_bytes()).hexdigest() == pack["sha256"]
+    assert pack_release_version(pack_file) == pack["version"], "包内 pdsc 版本与 lock 不符"
+    devs = json.loads((mdir / "deviations.json").read_text(encoding="utf-8"))["deviations"]
+    assert any(d["kind"] == "dfp-pack-bundled" for d in devs), "deviations 未登记随包 DFP"
+    assert pack["file"] in readme, "导出 README 未指明随包 DFP 安装包"
     # 卫生：不得含 GUI 状态/构建产物/个人痕迹
     for f in files["files"]:
         assert not re.search(r"(^|/)\.uvguix\.|(^|/)Obj/|(^|/)List/", f["path"])
         assert not re.search(r"\.(axf|hex|bin|map|dep|crf|o|bak|iex|lnp)$", f["path"], re.I)
 
 
+def _pack_spec(chip: str = "HT32F52352") -> dict:
+    """取（就地可改的）recipe pack 块：Resolved.recipe 直接引用装载后的 recipe 字典。"""
+    return srv.exporter.materializer.resolve(chip=chip).recipe["pack"]
+
+
+def test_export_l5_ships_locked_dfp_not_package_copy(tmp_path):
+    """L5 官方包内自带的 .pack 是 1.0.77（低于锁定 1.0.78）；随包必须是锁定的 1.0.78。"""
+    out = tmp_path / "l5_pack"
+    srv.export_project_bundle("HT32L52241", str(out))
+    lock = json.loads((out / "manifest" / "project-lock.json").read_text(encoding="utf-8"))
+    assert lock["pack"]["version"] == "1.0.78"
+    assert lock["pack"]["file"] == "utilities/pack/Holtek.HT32_DFP.1.0.78.pack"
+    in_pkg = (REPO / "raw" / "HT32_STD_L5xxxx_FWLib_V1.6.1" / "utilities" / "pack"
+              / "Holtek.HT32_DFP.latest.pack")
+    assert pack_release_version(in_pkg) == "1.0.77"      # 登记事实：官方包内那份低一版
+    shipped = out / lock["pack"]["file"]
+    assert shipped.read_bytes() != in_pkg.read_bytes(), "不得直接沿用官方包内的 1.0.77"
+
+
+def test_export_pack_required_when_asset_missing(tmp_path, monkeypatch):
+    """随包 DFP 资产缺失必须失败（PACK_REQUIRED），且不留半成品目录。"""
+    monkeypatch.setitem(_pack_spec(), "asset",
+                        ".work/template-recipes/assets/packs/missing.pack")
+    out = tmp_path / "missing_pack"
+    text = srv.export_project_bundle("HT32F52352", str(out))
+    assert "[PACK_REQUIRED]" in text and "资产缺失" in text, text
+    assert not out.exists(), "失败不得留下半成品目录"
+
+
+def test_export_pack_required_when_asset_hash_mismatch(tmp_path, monkeypatch):
+    """资产 SHA256 与 recipe 锁不一致必须失败（资产被替换/损坏）。"""
+    monkeypatch.setitem(_pack_spec(), "asset_sha256", "0" * 64)
+    out = tmp_path / "bad_hash"
+    text = srv.export_project_bundle("HT32F52352", str(out))
+    assert "[PACK_REQUIRED]" in text and "SHA256 不符" in text, text
+    assert not out.exists()
+
+
+def test_export_pack_required_when_version_below_or_id_mismatch(tmp_path, monkeypatch):
+    """版本门槛：随包版本低于 min_version、或与锁定 id 版本不一致，都必须失败。"""
+    pack = _pack_spec()
+    with monkeypatch.context() as m:
+        m.setitem(pack, "min_version", "9.9.9")
+        text = srv.export_project_bundle("HT32F52352", str(tmp_path / "low_ver"))
+        assert "[PACK_REQUIRED]" in text and "低于要求" in text, text
+    with monkeypatch.context() as m:
+        m.setitem(pack, "id", "Holtek.HT32_DFP.9.9.9")
+        text = srv.export_project_bundle("HT32F52352", str(tmp_path / "id_mismatch"))
+        assert "[PACK_REQUIRED]" in text and "与锁定 id" in text, text
+    assert not (tmp_path / "low_ver").exists()
+    assert not (tmp_path / "id_mismatch").exists()
+
+
+def test_export_host_tools_default_included(tmp_path):
+    """host 工具（gsar/eLink32pro）默认随包；置 false 时排除并登记 deviations。"""
+    out = tmp_path / "host_default"
+    srv.export_project_bundle("HT32F52352", str(out))
+    assert (out / "utilities" / "gsar").is_dir()
+    assert (out / "utilities" / "elink32pro" / "eLink32pro.exe").is_file()
+    out2 = tmp_path / "host_excluded"
+    srv.export_project_bundle("HT32F52352", str(out2), include_host_tools=False)
+    assert not (out2 / "utilities" / "gsar").exists()
+    assert (out2 / "utilities" / "pack").is_dir(), "host 开关不得影响随包 DFP"
+    devs = json.loads((out2 / "manifest" / "deviations.json")
+                      .read_text(encoding="utf-8"))["deviations"]
+    assert any(d["kind"] == "host-tools-excluded" for d in devs)
+
+
 def test_export_positive_default_chip(tmp_path):
     out = tmp_path / "bundle_default"
     result = srv.export_project_bundle("HT32F52352", str(out))

{ht32_code_mcp-0.3.2 → ht32_code_mcp-0.4.1}/uv.lock

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

ht32_code_mcp-0.3.2/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}"