ht32-code-mcp 0.2.6__tar.gz → 0.3.0__tar.gz

{ht32_code_mcp-0.2.6 → ht32_code_mcp-0.3.0}/PKG-INFO

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

{ht32_code_mcp-0.2.6 → ht32_code_mcp-0.3.0}/e2e_scenario_a.py

@@ -69,8 +69,8 @@ def wiki_transport() -> StdioTransport:
 
 
 def devices_entry(chip: str) -> dict:
-    """该型号在 raw/templates/*/devices.json 中的参数条目（用于核对导出产物）。"""
-    for dj in sorted((CODE_ROOT / "raw" / "templates").glob("*/devices.json")):
+    """该型号在 templates/*/devices.json 中的参数条目（用于核对导出产物）。"""
+    for dj in sorted((CODE_ROOT / "templates").glob("*/devices.json")):
         for d in json.loads(dj.read_text(encoding="utf-8")).get("devices", []):
             if d.get("device", "").upper() == chip.upper():
                 return d

{ht32_code_mcp-0.2.6 → ht32_code_mcp-0.3.0}/pyproject.toml

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

ht32_code_mcp-0.3.0/src/ht32_code_mcp/exporter.py

@@ -0,0 +1,181 @@
+"""export_project_bundle：v2 契约导出（recipe 物化 + 原子发布 + manifest）。
+
+v2 变更（相对旧"复制模板 + 改少量字段"的实现）：
+- 入口支持显式 config_id / device+board / clock_profile / retarget_profile；
+  旧 chip 参数走只读适配层（v1-adapter.json），保持旧默认并给弃用警告；
+- 物化由 materializer.py 完成：先校验后 staging、XML 声明式改写（命中数约束）、
+  内存一处裁决多处一致、manifest 四件套、staging 原子重命名、ZIP .part 原子发布；
+- 响应字段：contract_version/config_id/recipe_revision/device/board/compiler/
+  profiles/project_relative_path/manifest_relative_path/artifact_sha256/
+  artifact_size/requires/warnings/validation。
+
+模板（templates/）是派生快照（replay_templates.py 可重建）；唯一事实源是
+.work/template-recipes/（schema + recipes + mapping + inventory）。
+"""
+from __future__ import annotations
+
+import dataclasses
+import shutil
+import tempfile
+import time
+from pathlib import Path
+
+from .materializer import (CONTRACT_VERSION, ContractError, Materializer, Resolved,
+                           zip_tree_atomic)
+
+DEFAULT_BUNDLE_TTL = 3600
+
+
+@dataclasses.dataclass
+class ExportResult:
+    """一次导出的结果（本地目录/云端 zip 共用）。"""
+
+    text: str
+    config_id: str
+    device: str
+    board: str
+    compiler: str
+    profiles: dict
+    project_relative_path: str
+    manifest_relative_path: str
+    artifact_sha256: str
+    artifact_size: int
+    requires: dict
+    warnings: list
+    validation: dict
+    out_dir: Path | None = None
+    zip_path: Path | None = None
+    download_url: str = ""
+    expires_at: float = 0.0
+
+
+class ProjectExporter:
+    """v2 导出器：recipe 选择 -> 物化 -> 原子发布。"""
+
+    def __init__(self, code_root: Path) -> None:
+        self.root = Path(code_root)
+        recipes_dir = self.root / ".work" / "template-recipes" / "recipes"
+        self.materializer = Materializer(self.root, recipes_dir)
+
+    # ------------------------------------------------------------ 解析
+    def resolve(self, *, config_id: str = "", chip: str = "", device: str = "",
+                board: str = "", clock_profile: str = "",
+                retarget_profile: str = "") -> Resolved:
+        return self.materializer.resolve(
+            config_id=config_id, chip=chip, device=device,
+            board=board, clock_profile=clock_profile, retarget_profile=retarget_profile)
+
+    # ------------------------------------------------------------ 本地目录
+    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:
+        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(
+            r, out_dir, project_name=project_name, include_host_tools=include_host_tools)
+        return self._result(r, res, artifact_kind="directory")
+
+    # ------------------------------------------------------------ 云端 zip
+    def export_zip(self, *, bundle_dir: str, ttl_seconds: int = DEFAULT_BUNDLE_TTL,
+                   project_name: str = "", config_id: str = "", chip: str = "",
+                   device: str = "", board: str = "", clock_profile: str = "",
+                   retarget_profile: str = "",
+                   include_host_tools: bool = False) -> 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()
+        bdir.mkdir(parents=True, exist_ok=True)
+        tmp = Path(tempfile.mkdtemp(prefix="ht32-bundle-", dir=str(bdir)))
+        try:
+            res = self.materializer.materialize(
+                r, tmp / "bundle", project_name=project_name,
+                include_host_tools=include_host_tools)
+            import secrets
+            token = secrets.token_urlsafe(24)
+            zip_path = bdir / f"{token}.zip"
+            size, digest = zip_tree_atomic(tmp / "bundle", zip_path)
+            result = self._result(r, res, artifact_kind="zip")
+            result.zip_path = zip_path
+            result.artifact_sha256 = digest
+            result.artifact_size = size
+            result.expires_at = time.time() + ttl_seconds
+            return result
+        finally:
+            if tmp.exists():
+                shutil.rmtree(tmp, ignore_errors=True)
+
+    # ------------------------------------------------------------ 结果文本
+    def _result(self, r: Resolved, res, *, artifact_kind: str) -> ExportResult:
+        cfg = r.config
+        lock = res.out_dir / "manifest" / "project-lock.json"
+        manifest_rel = "manifest/project-lock.json"
+        requires = {
+            "pack": r.recipe["pack"]["id"],
+            "pack_note": r.recipe["pack"]["device_macro_note"],
+            "keil": "MDK-ARM 5.x (AC5)",
+        }
+        validation = dict(cfg["validation"])
+        validation["static"] = "pass"
+        result = ExportResult(
+            text="", config_id=r.config_id, device=cfg["device"],
+            board=cfg["board"]["id"], compiler=cfg["compiler"]["id"],
+            profiles={"clock": r.clock_profile, "retarget": r.retarget_profile},
+            project_relative_path=res.project_file,
+            manifest_relative_path=manifest_rel,
+            artifact_sha256=res.sha256, artifact_size=res.bytes,
+            requires=requires, warnings=list(r.warnings), validation=validation,
+            out_dir=res.out_dir)
+        result.text = self._report(r, res, artifact_kind)
+        return result
+
+    def _report(self, r: Resolved, res, artifact_kind: str) -> str:
+        cfg = r.config
+        mem = cfg["memory"]
+        lines = [
+            f"自包含 Keil 工程已导出（v2 契约，{artifact_kind}）：",
+            f"- contract_version: {CONTRACT_VERSION}",
+            f"- config_id: {r.config_id}"
+            + ("（非默认 profile 组合的派生 id）" if r.derived_config_id else ""),
+            f"- recipe_revision: {r.recipe['recipe_revision']}"
+            f"（materializer {r.recipe['materializer']['id']}"
+            f" r{r.recipe['materializer']['revision']}）",
+            f"- device: {cfg['device']}｜board: {cfg['board']['id']}"
+            f"｜compiler: {cfg['compiler']['id']}",
+            f"- profiles: clock={r.clock_profile}, retarget={r.retarget_profile}",
+            f"- 工程文件: {res.project_file}",
+            f"- manifest: manifest/project-lock.json（另有 files/deviations/validation）",
+            f"- 内存（一处裁决）: Flash {mem['flash'][0]['size']}"
+            f" @ {mem['flash'][0]['base']}；RAM {mem['ram'][0]['size']}"
+            f" @ {mem['ram'][0]['base']}"
+            + (f"；冲突记录 {len(mem['conflicts'])} 条" if mem["conflicts"] else ""),
+            f"- 文件数/字节: {res.files} / {res.bytes}",
+            f"- 树 SHA256: {res.sha256}",
+            f"- 前置: {r.recipe['pack']['device_macro_note']}",
+        ]
+        if r.retarget_profile == "retarget":
+            claims = cfg["retarget"]["uart_pin_claims"]
+            lines.append(f"- 串口占用: {claims[0] if claims else 'COM1'}")
+        if r.warnings:
+            lines.append("- 警告:")
+            lines.extend(f"  - {w}" for w in r.warnings)
+        v = cfg["validation"]
+        lines.append(f"- validation: static=pass, compile={v['compile']}, "
+                     f"gui={v['gui']}, hardware={v['hardware']}"
+                     "（gui/hardware 未验证项以 not-tested 明示）")
+        lines.append("")
+        lines.append("后续：UV4 -b 基线编译（目标 0 Error 0 Warning）；"
+                     "换芯片请用显式 config_id 重新导出，不要手改 Device/Cpu/宏。")
+        return "\n".join(lines)
+
+
+# 旧兼容入口（v1 chip 参数只读适配；调用方逐步迁移到 config_id）
+def export_project_bundle_legacy(exporter: ProjectExporter, chip: str, out_dir: str,
+                                 project_name: str = "") -> str:
+    try:
+        result = exporter.export_dir(out_dir=out_dir, project_name=project_name, chip=chip)
+    except ContractError as e:
+        return f"导出失败：[{e.code}] {e.message}"
+    except OSError as e:
+        return f"导出失败（写盘/打包失败，检查目录权限与空间）：{e}"
+    return result.text

{ht32_code_mcp-0.2.6 → ht32_code_mcp-0.3.0}/src/ht32_code_mcp/index.py

@@ -166,14 +166,15 @@ class CodeIndex:
         raw_dir = self.root / "raw"
         if raw_dir.is_dir():
             data["fwlibs"] = [self._scan_fwlib(p) for p in sorted(raw_dir.iterdir())
-                              if p.is_dir() and p.name != "templates"]
-            templates_dir = raw_dir / "templates"
-            data["templates"] = [self._scan_template(p) for p in sorted(templates_dir.iterdir())
-                                 if p.is_dir()] if templates_dir.is_dir() else []
+                              if p.is_dir()]
             data["files"] = sorted(
                 _rel(f.relative_to(self.root).as_posix())
                 for f in raw_dir.rglob("*") if f.is_file()
             )
+        templates_dir = self.root / "templates"
+        if templates_dir.is_dir():
+            data["templates"] = [self._scan_template(p) for p in sorted(templates_dir.iterdir())
+                                 if p.is_dir()]
         data["knowledge_pages"] = self._scan_knowledge()
         fw = data["fwlibs"]
         data["stats"] = {