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

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

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

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

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

{ht32_code_mcp-0.3.1 → ht32_code_mcp-0.4.0}/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.1 → ht32_code_mcp-0.4.0}/src/ht32_code_mcp/materializer.py

@@ -20,6 +20,7 @@ import os
 import re
 import shutil
 import tempfile
+import threading
 import time
 import zipfile
 from pathlib import Path
@@ -34,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 = [
@@ -66,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] = {}
@@ -373,6 +402,7 @@ class MaterialResult:
     manifest_dir: str
     warnings: list[str]
     deviations: list[dict]
+    pack: dict
 
 
 class Materializer:
@@ -381,6 +411,10 @@ class Materializer:
         self.raw = self.root / "raw"
         self.recipes = load_recipes(recipes_dir)
         self.recipes["__dir__"] = recipes_dir  # resolve() 需要定位 adapter
+        # 单次调用的中间状态必须放 thread-local：物化器是进程级单例，
+        # 并发导出（MCP 工具在线程池里执行）会互相覆盖 _stage / _project_rel，
+        # 导致 "…is not in the subpath of…" 之类的相对路径串台错误。
+        self._local = threading.local()
 
     def resolve(self, *, config_id: str = "", chip: str = "", device: str = "",
                 board: str = "", variant: str = "", clock_profile: str = "",
@@ -421,29 +455,80 @@ 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)
             shutil.copyfile(p, target)
             manifest_files.append(dict(
-                path=(dst.relative_to(self._stage) / rel).as_posix(), bytes=p.stat().st_size,
+                path=(dst.relative_to(self._local.stage) / rel).as_posix(), bytes=p.stat().st_size,
                 sha256=sha256_file(p), classification="official",
                 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"]
@@ -456,12 +541,12 @@ class Materializer:
         # staging：与目标同文件系统的临时目录（保证原子重命名）
         out.parent.mkdir(parents=True, exist_ok=True)
         stage = Path(tempfile.mkdtemp(prefix=f".ht32-stage-{stem}-", dir=str(out.parent)))
-        self._stage = stage
+        self._local.stage = stage
         manifest_files: list[dict] = []
         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)]
@@ -476,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):
@@ -497,25 +582,25 @@ class Materializer:
                     shutil.rmtree(stage, ignore_errors=True)
                 except BaseException:  # noqa: BLE001 - best-effort cleanup
                     pass
-        return MaterialResult(out_dir=out, project_file=self._project_rel,
+        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"]
-        self._stage = stage
+        self._local.stage = stage
 
         # 1) library：完整官方树（complete-official-tree）
         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
@@ -524,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)
@@ -618,9 +722,9 @@ class Materializer:
         proj_dir = stage / "project" / "MDK_ARMv5"
         proj_dir.mkdir(parents=True, exist_ok=True)
         uvprojx = self._materialize_uvprojx(r, proj_dir, stem, kernel, board_dir, deviations)
-        self._project_rel = uvprojx.relative_to(stage).as_posix()
+        self._local.project_rel = uvprojx.relative_to(stage).as_posix()
         uv_data = uvprojx.read_bytes()
-        manifest_files.append(dict(path=self._project_rel, bytes=len(uv_data),
+        manifest_files.append(dict(path=self._local.project_rel, bytes=len(uv_data),
                                    sha256=sha256_bytes(uv_data),
                                    classification="materialized-project",
                                    origin=f"{origin['package']}/{origin['project']}"))
@@ -641,7 +745,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()),
@@ -796,7 +900,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,
@@ -809,8 +913,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"],
@@ -831,10 +941,10 @@ class Materializer:
         (mdir / "validation.json").write_text(json.dumps({
             "layers": validation,
             "gate_rule": "gui/hardware 未验证项以 not-tested 明示，不得宣称已验证",
-            "compile_command": f'UV4 -b "{self._project_rel}" -j0 -o build.log',
+            "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"
@@ -850,13 +960,15 @@ 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']} 时可跳过安装**",
             "",
             "## 打开与编译",
             "",
-            f"- 打开 `{self._project_rel}`（Target：`{stem}`）",
-            f"- 命令行基线编译：`UV4 -b \"{self._project_rel}\" -j0 -o build.log`",
+            f"- 打开 `{self._local.project_rel}`（Target：`{stem}`）",
+            f"- 命令行基线编译：`UV4 -b \"{self._local.project_rel}\" -j0 -o build.log`",
         ]
         if r.series == "ht32f5":
             lines.append("- 调试：工程自带受控 `.uvoptx`（CMSIS-DAP + Reset and Run 配置；"
@@ -889,7 +1001,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.1 → ht32_code_mcp-0.4.0}/src/ht32_code_mcp/server.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import os
 import sys
+import time
 from importlib.metadata import PackageNotFoundError, version as pkg_version
 from pathlib import Path
 from typing import Literal
@@ -43,6 +44,11 @@ BUNDLE_BASE_URL = os.environ.get("BUNDLE_BASE_URL", "").strip()
 BUNDLE_TTL = _env_int("BUNDLE_TTL_SECONDS", DEFAULT_BUNDLE_TTL)
 CLOUD_BUNDLE = bool(BUNDLE_DIR and BUNDLE_BASE_URL)
 
+
+def _fmt_time(ts: float) -> str:
+    """epoch 秒 → 本地时间字符串（用于云端 zip 下载的有效期提示）。"""
+    return time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(ts))
+
 # 反馈与用量日志：FEEDBACK_ROOT（宿主机挂载的可写卷，与 wiki 同一套约定）
 # 下按服务名分子目录，本服务写 <FEEDBACK_ROOT>/code/。
 # 为空则整体关闭——本地开发默认不落盘。注意：日志含 query 原文，勿提交进仓库。
@@ -435,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 必填）"))
@@ -451,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 + 原子发布）。
 
@@ -461,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（须为空目录或不存在；不会覆盖已有内容）。
@@ -479,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.0/tests/test_export_cloud_mode.py

@@ -0,0 +1,47 @@
+"""回归测试：线上实测暴露的两个导出缺陷。
+
+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}"

{ht32_code_mcp-0.3.1 → ht32_code_mcp-0.4.0}/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.1 → ht32_code_mcp-0.4.0}/uv.lock

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