ht32-code-mcp 0.1.1__tar.gz → 0.1.2__tar.gz

ht32_code_mcp-0.1.2/DEPLOY.md

@@ -0,0 +1,198 @@
+# MCP Server 部署指南（ht32-code）
+
+HT32 Code MCP Server 的部署、配置与排错。代码在 `.work/mcp-server/`，已发布到 PyPI（`ht32-code-mcp`）。
+
+## 部署信息
+
+```
+MCP Server 地址（Streamable HTTP）: https://mcp.s621.work/ht32-code
+PyPI 包:              https://pypi.org/project/ht32-code-mcp/（uvx ht32-code-mcp 即可运行）
+Bundle 下载地址:       https://mcp.s621.work/ht32-bundles/<token>.zip
+本地 Gitea:            http://100.66.1.6:3000/S621/ht32-code.git
+MCP Server 代码:       .work/mcp-server/
+```
+
+## 部署链路
+
+```
+PyPI 发布包 → 1Panel 原生 MCP 管理（类型 uvx，启动命令 uvx ht32-code-mcp，输出类型 streamableHttp）
+            → supergateway 包装 stdio 为 Streamable HTTP（stateful）
+            → OpenResty 暴露公网
+              ├─ /ht32-code/*      → MCP 协议端点（反向代理到容器）
+              └─ /ht32-bundles/*   → bundle zip 静态目录（P1-3）
+```
+
+代码默认走 `stdio`（`MCP_TRANSPORT` 未设置时），supergateway 负责 stdio→Streamable HTTP 转换。
+与 ht32-wiki 同构：SSE 无心跳会被 OpenResty 空闲切断，故走 streamableHttp stateful。
+
+## 关键配置
+
+1Panel MCP 表单：
+
+- 类型：`uvx`
+- 启动命令：`uvx ht32-code-mcp`（**必须带 uvx 前缀**，容器里没装裸命令）
+- 输出类型：`streamableHttp`
+- 流式传输路径：`/ht32-code`（切输出类型后是**新字段**，默认空，必须手填；必填校验）
+- 协议版本：`2025-06-18`（1Panel 预填默认值，勿动；仅用于 supergateway 对下游 stdio 的 auto-init）
+- 镜像：`supercorp/supergateway:next-uvx`（**必须覆盖默认的 `:uvx`**——见下方踩坑）
+- 参数：`--stateful --sessionTimeout 3600000`
+- 环境变量：`CODE_ROOT=/app/code`
+- 挂载：`/opt/ht32-code:/app/code`（**不用加 `:ro`**——`index/code_index.json`
+  已 gitignore 且容器内可能需重建，只读会阻断；容器路径不能有前导空格，否则 `invalid mount path`）
+
+### 镜像 tag 踩坑（2026-09-20）
+
+默认镜像 `supercorp/supergateway:uvx` 构建时解析到旧版
+`@modelcontextprotocol/sdk`（LATEST_PROTOCOL_VERSION=2025-06-18），新版客户端
+（Trae 发 `2025-11-25`）initialize 直接被拒：`Bad Request: Unsupported protocol
+version`。根因是 supergateway 3.4.3 对 SDK 声明的是浮动依赖 `^1.18.2`，镜像构建
+日期决定行为；`next-uvx`（4.0.0-rc.4）将 SDK **精确锁定 1.30.0**，无此问题。
+
+## 云端 zip 下载通道（P1-3，0.1.2+）
+
+`export_project_bundle` 有两种交付形态，**由服务端环境变量决定，调用方无需判断**：
+
+| 模式 | 触发条件 | 行为 |
+|---|---|---|
+| 云端 zip | `BUNDLE_DIR` 与 `BUNDLE_BASE_URL` **同时非空** | 打包到 `BUNDLE_DIR`，返回 `<BUNDLE_BASE_URL>/<token>.zip` + SHA256 + 过期时间 |
+| 本地目录 | 二者任一为空（默认） | 物化到 `out_dir`（须为空目录/不存在） |
+
+### 环境变量
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `BUNDLE_DIR` | 空（= 关闭云端模式） | 容器内 bundle 输出目录，须可写 |
+| `BUNDLE_BASE_URL` | 空（= 关闭云端模式） | 公网下载前缀，如 `https://mcp.s621.work/ht32-bundles` |
+| `BUNDLE_TTL_SECONDS` | `3600` | zip 有效期；每次 export 前顺带清理过期 zip |
+
+非数字的 `BUNDLE_TTL_SECONDS` 会静默回退默认值，不报错。
+
+### 实现要点
+
+- **token**：`secrets.token_urlsafe(24)`（192 bit 熵），文件名即 token；不可枚举、不可猜测
+- **物化在系统临时目录**（`tempfile.mkdtemp`）而非 bundle 目录——bundle 目录里只出现
+  最终 zip，中途失败的半成品不会暴露成可下载文件
+- **清理**：`sweep_expired()` 在每次 export 时按 mtime 删除超期 `*.zip`；
+  进程崩溃遗留的临时目录不影响交付（不在 bundle 目录内）
+- **TTL 到点不主动删**：靠下次 export 的 sweep 或 P1-2 定时脚本清理；过期后
+  重新调用工具即可拿新 URL
+
+### 服务器侧落地（3 步）
+
+**第 1 步：宿主机建 bundle 目录**
+
+```bash
+mkdir -p /opt/ht32-bundles
+```
+
+**第 2 步：1Panel 补挂载与环境变量**
+
+| 配置项 | 值 |
+|--------|-----|
+| 挂载 | `/opt/ht32-bundles:/app/bundles`（**不要加 `:ro`，需可写**） |
+| 环境变量 | `BUNDLE_DIR=/app/bundles` |
+| 环境变量 | `BUNDLE_BASE_URL=https://mcp.s621.work/ht32-bundles` |
+| 环境变量 | `BUNDLE_TTL_SECONDS=3600`（可选，默认即 3600） |
+
+完整配置（含现有项）：
+
+```
+类型：        uvx
+启动命令：    uvx ht32-code-mcp
+输出类型：    streamableHttp
+流式传输路径：/ht32-code
+协议版本：    2025-06-18
+镜像：        supercorp/supergateway:next-uvx
+参数：        --stateful --sessionTimeout 3600000
+环境变量：    CODE_ROOT=/app/code
+            BUNDLE_DIR=/app/bundles
+            BUNDLE_BASE_URL=https://mcp.s621.work/ht32-bundles
+挂载：        /opt/ht32-code:/app/code
+            /opt/ht32-bundles:/app/bundles
+```
+
+**第 3 步：OpenResty 加静态 location**
+
+配置里已有 `include /www/sites/mcp.s621.work/proxy/*.conf;`（server 级），
+在该目录下新建 `bundles.conf`：
+
+```nginx
+location ^~ /ht32-bundles/ {
+    alias /opt/ht32-bundles/;
+    autoindex off;                 # 禁止目录列举（防 token 泄露面扩大）
+    add_header Cache-Control "no-store";
+    types { application/zip zip; }
+    default_type application/zip;
+}
+```
+
+改完 `nginx -t && nginx -s reload`。
+
+> **注意（容器化 OpenResty）**：若 OpenResty 跑在容器里而非宿主机原生进程，
+> `/opt/ht32-bundles` 还必须**同时挂进 OpenResty 容器**（同一宿主机路径），
+> 否则 nginx 读到的是容器内空目录，下载必然 404。
+> 现有 `proxy_pass http://127.0.0.1:8001/ht32-code` 能通，说明二者网络可达；
+> 但「可达」不等于「文件系统共享」，这一条需按实际部署形态确认。
+
+### 验证生效
+
+1. 调 `get_code_version`，应出现：
+
+   ```
+   云端 zip 下载：启用（TTL 3600s，https://mcp.s621.work/ht32-bundles）
+   ```
+
+   仍显示「未配置」→ 环境变量没注入成功（查变量名 / 容器是否重建）。
+
+2. 调 `export_project_bundle(chip="HT32F52352")`，应返回：
+
+   ```
+   下载 URL：https://mcp.s621.work/ht32-bundles/<token>.zip
+   有效期：3600 秒（至 ...）
+   大小：1.53 MB（455 文件）
+   SHA256：...
+   ```
+
+3. 浏览器/curl 拉该 URL：应得约 1.5 MB zip；`sha256sum` 与报告一致；
+   解压后 455 文件、`project/MDK_ARMv5/ht32f5-template.uvprojx` 在，UV4 编译 0E0W。
+
+4. 确认 `ls /opt/ht32-bundles` 只有 `*.zip`（无残留临时目录）。
+
+## PyPI 包发布流程
+
+```bash
+# token 在 ht32-code 根目录 .env 的 UV_PUBLISH_TOKEN
+uv lock && uv build && uv publish
+```
+
+发布后同步 `VERSION` 文件末行：`MCP Server: <版本>（deployed, PyPI, <日期>）`。
+
+## 踩过的坑
+
+### 1. 云端跑的是 PyPI 包，不是 /opt 仓库（P0-1）
+
+- **症状**：改了仓库代码、云端 MCP 行为不变
+- **根因**：`uvx ht32-code-mcp` 从 PyPI 拉包，`/opt/ht32-code` 只是被检索的数据源
+- **修复**：改代码必须**发版 + 重建容器**，改仓库文件本身不生效
+
+### 2. 索引只读挂载
+
+- **症状**：容器启动报索引无法写入/重建失败
+- **根因**：`/opt/ht32-code:/app/code:ro` 时 `index/code_index.json` 不可写
+- **修复**：挂载去掉 `:ro`
+
+### 3. 镜像 tag 导致协议版本被拒
+
+见上方「镜像 tag 踩坑」。
+
+## 当前部署状态
+
+| # | 任务 | 说明 | 状态 |
+|---|------|------|------|
+| 3.1 | 7 个 MCP 工具实现 | `.work/mcp-server/src/ht32_code_mcp/`（FastMCP） | ✅ |
+| 3.2 | 工具级测试 | `pytest` 36 用例全绿 | ✅ |
+| 3.3 | PyPI 发布（hatchling） | `ht32-code-mcp` 0.1.1（2026-09-20）；0.1.2 为 bundle 通道版本 | ✅ |
+| 3.4 | 云端 git clone + 挂载 | `/opt/ht32-code:/app/code` | ✅ |
+| 3.5 | 1Panel 部署（uvx + supergateway → streamableHttp stateful，镜像 next-uvx） | `https://mcp.s621.work/ht32-code` | ✅ |
+| 3.6 | OpenResty 超时修复（`proxy_read_timeout 3600s`） | 修复 60s 空闲断连 | ✅ |
+| 3.7 | 云端 zip 下载通道（P1-3） | 代码就绪并端到端验证；**服务器侧 3 步待执行** | ⏳ |

{ht32_code_mcp-0.1.1 → ht32_code_mcp-0.1.2}/PKG-INFO

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

{ht32_code_mcp-0.1.1 → ht32_code_mcp-0.1.2}/pyproject.toml

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

ht32_code_mcp-0.1.2/src/ht32_code_mcp/exporter.py

@@ -0,0 +1,277 @@
+"""export_project_bundle：从模板组装自包含可编译 Keil 工程（本地目录 / 云端 zip）。
+
+模板自带全量官方库树（library/），因此导出只需复制模板 + 按 devices.json
+参数化 uvprojx（Device / C 宏 / 汇编宏 / system / startup 文件指向）。
+
+两种交付形态：
+- 本地目录模式：物化到 out_dir（本地 stdio 调试用）。
+- 云端 zip 模式：物化到临时目录 → 打包成 <token>.zip 放进 bundle 目录 →
+  由 nginx 静态目录按随机 token + TTL 提供下载（服务器与用户电脑解耦）。
+
+参数化依据：raw/templates/ht32f5-keil/devices.json（device/cdef/adef/sys/startup）。
+"""
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+import re
+import secrets
+import shutil
+import tempfile
+import time
+import zipfile
+from datetime import datetime
+from pathlib import Path
+
+# 模板中默认型号（HT32F52352）的 system / startup 文件名主干，导出时按目标型号替换
+_TEMPLATE_SYS_STEM = "system_ht32f5xxxx_01"
+_TEMPLATE_STARTUP_STEM = "startup_ht32f5xxxx_01"
+
+# 云端 zip 产物默认有效期（秒）
+DEFAULT_BUNDLE_TTL = 3600
+
+
+class ExportError(Exception):
+    """导出失败（型号未知 / 源文件缺失 / 目标目录非空等）。"""
+
+
+@dataclasses.dataclass
+class Materialized:
+    """一次物化的结果（本地/云端共用）。"""
+
+    device: str
+    entry: dict
+    sys_c: Path
+    sys_h: Path
+    startup: Path
+    files: int
+
+
+@dataclasses.dataclass
+class Bundle:
+    """云端 zip 产物信息。"""
+
+    token: str
+    path: Path
+    size: int
+    sha256: str
+    expires_at: float
+    materialized: Materialized
+
+
+def _read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _fmt_time(ts: float) -> str:
+    return datetime.fromtimestamp(ts).astimezone().strftime("%Y-%m-%d %H:%M:%S %z")
+
+
+def _rmtree(path: Path) -> None:
+    """删除目录树；Windows 上句柄释放有延迟，失败重试几次后再放弃。
+
+    放弃也无害：临时目录在系统 temp 下，容器重启即清空。
+    """
+    for attempt in range(3):
+        if not path.exists():
+            return
+        try:
+            shutil.rmtree(path)
+            return
+        except OSError:
+            if attempt == 2:
+                shutil.rmtree(path, ignore_errors=True)
+            else:
+                time.sleep(0.2 * (attempt + 1))
+
+
+def sweep_expired(bundle_dir: Path, ttl_seconds: int) -> int:
+    """清理过期 zip 产物，返回清理条数。
+
+    惰性清理：每次打包前扫一遍即可，无需常驻定时任务。
+    """
+    if not bundle_dir.is_dir():
+        return 0
+    now = time.time()
+    swept = 0
+    for p in bundle_dir.glob("*.zip"):
+        try:
+            if now - p.stat().st_mtime > ttl_seconds:
+                p.unlink()
+                swept += 1
+        except OSError:
+            continue  # 并发/权限竞争时跳过，不影响本次打包
+    return swept
+
+
+class ProjectExporter:
+    def __init__(self, code_root: Path) -> None:
+        self.root = Path(code_root)
+        self.template_dir = self.root / "raw" / "templates" / "ht32f5-keil"
+        # 模板自带全量官方库树，system/startup 在此校验
+        self.lib_device = (self.template_dir / "library" / "Device"
+                           / "Holtek" / "HT32F5xxxx" / "Source")
+
+    # ------------------------------------------------------- 本地目录模式
+    def export(self, chip: str, out_dir: str) -> str:
+        out = Path(out_dir).expanduser().resolve()
+        if out.exists() and any(out.iterdir()):
+            raise ExportError(f"目标目录非空，拒绝覆盖：{out}（请指定新目录或先清空）")
+        m = self._materialize(chip, out)
+        return dir_report(out, m)
+
+    # ------------------------------------------------------- 云端 zip 模式
+    def export_zip(self, chip: str, bundle_dir: str, ttl_seconds: int) -> Bundle:
+        bdir = Path(bundle_dir).expanduser().resolve()
+        bdir.mkdir(parents=True, exist_ok=True)
+        sweep_expired(bdir, ttl_seconds)
+
+        token = secrets.token_urlsafe(24)
+        # 物化在系统临时目录：bundle 目录只暴露最终 zip，不半成品公开
+        tmp = Path(tempfile.mkdtemp(prefix="ht32-bundle-"))
+        try:
+            m = self._materialize(chip, tmp)
+            zip_path = bdir / f"{token}.zip"
+            _zip_tree(tmp, zip_path)
+        finally:
+            _rmtree(tmp)
+        return Bundle(token=token, path=zip_path, size=zip_path.stat().st_size,
+                      sha256=_sha256(zip_path),
+                      expires_at=time.time() + ttl_seconds, materialized=m)
+
+    # ------------------------------------------------------------ 物化
+    def _materialize(self, chip: str, out: Path) -> Materialized:
+        if not self.template_dir.is_dir():
+            raise ExportError(f"模板目录不存在：{self.template_dir}")
+        device, entry = self._resolve_device(chip)
+
+        # 预检模板内目标型号所需源文件（先验证后落盘，失败不产生半成品）
+        sys_c = self.lib_device / entry["sys"]
+        sys_h = sys_c.parent.parent / "Include" / (sys_c.stem + ".h")
+        startup = self.lib_device / "ARM" / entry["startup"]
+        missing = [str(p) for p in (sys_c, sys_h, startup) if not p.is_file()]
+        if missing:
+            raise ExportError("模板 library/ 缺少所需源文件：\n- " + "\n- ".join(missing))
+
+        # 复制模板树（含全量官方库，导出即自包含）
+        out.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(self.template_dir, out, dirs_exist_ok=True)
+
+        # 参数化 uvprojx：Device / C 宏 / 汇编宏 / system / startup 指向
+        uvprojx = out / "project" / "MDK_ARMv5" / "ht32f5-template.uvprojx"
+        text = _read_text(uvprojx)
+        text = re.sub(r"(<Device>)[^<]*(</Device>)", rf"\g<1>{device}\g<2>", text, count=1)
+        text = _replace_define(text, "USE_HT32_DRIVER", entry["cdef"])
+        text = _replace_define(text, "USE_HT32_CHIP", entry["adef"])
+        text = text.replace(_TEMPLATE_SYS_STEM, sys_c.stem)
+        text = text.replace(_TEMPLATE_STARTUP_STEM, startup.stem)
+        with open(uvprojx, "w", encoding="utf-8", newline="") as f:
+            f.write(text)
+
+        files = sum(1 for p in out.rglob("*") if p.is_file())
+        return Materialized(device=device, entry=entry, sys_c=sys_c, sys_h=sys_h,
+                            startup=startup, files=files)
+
+    # ------------------------------------------------------------ 辅助
+    def _resolve_device(self, chip: str) -> tuple[str, dict]:
+        dj = self.template_dir / "devices.json"
+        if not dj.is_file():
+            raise ExportError(f"模板型号参数表缺失：{dj}")
+        meta = json.loads(dj.read_text(encoding="utf-8"))
+        want = chip.strip().upper()
+        for d in meta.get("devices", []):
+            if d.get("device", "").upper() == want:
+                return d["device"], d          # 重名取首条（官方板级变体）
+        # 宽松匹配：型号主体包含（HT32F52352 含于 HT32F52352_SK 场景已由上面精确处理）
+        for d in meta.get("devices", []):
+            if want in d.get("device", "").upper():
+                return d["device"], d
+        names = [d.get("device", "") for d in meta.get("devices", [])][:20]
+        raise ExportError(
+            f"型号 '{chip}' 不在模板参数表（共 {meta.get('count', '?')} 个型号）。\n"
+            f"可用型号（前 20）：{', '.join(names)}…\n"
+            "完整清单：get_file('raw/templates/ht32f5-keil/devices.json') 或 get_project_manifest()"
+        )
+
+
+def _zip_tree(src: Path, zip_path: Path) -> None:
+    """把 src 下整棵树打成 zip（文件相对 src 定位，故解压即得工程根结构）。"""
+    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED, compresslevel=6) as zf:
+        for p in sorted(src.rglob("*")):
+            if p.is_file():
+                zf.write(p, p.relative_to(src).as_posix())
+
+
+def _spec_lines(m: Materialized) -> list[str]:
+    """两种模式共用的工程参数说明行。"""
+    return [
+        f"目标芯片：{m.device}",
+        "工程文件：project/MDK_ARMv5/ht32f5-template.uvprojx（已按型号参数化）",
+        f"C 宏（Cads）：{m.entry['cdef']}",
+        f"汇编宏（Aads）：{m.entry['adef']}",
+        f"system：library/Device/Holtek/HT32F5xxxx/Source/{m.sys_c.name}"
+        f"（+ Include/{m.sys_h.name}）",
+        f"startup：library/Device/Holtek/HT32F5xxxx/Source/ARM/{m.startup.name}",
+        "libcfg：library/HT32F5xxxx_Driver/inc/（ht32f5xxxx_lib.h 按 C 宏自动引入）",
+    ]
+
+
+_FOLLOWUP = [
+    "1. Keil MDK 打开 project/MDK_ARMv5/ht32f5-template.uvprojx"
+    "（需 Holtek HT32_DFP pack ≥1.0.67）",
+    "2. 如需精确 IROM/IRAM 内存布局，在 Options → Device 重新选择该型号由 DFP 刷新",
+    "3. 基线编译验证（UV4 命令行复核 0 Error 0 Warning）",
+]
+
+
+def dir_report(out: Path, m: Materialized) -> str:
+    lines = [
+        f"自包含 Keil 工程已导出：{out}",
+        *_spec_lines(m),
+        f"文件总数：{m.files}",
+        "",
+        "目录结构：",
+        "  component/  共享组件层（基础模板为空，按项目增补）",
+        "  library/    CMSIS / Device / Driver / USBD（全量官方库，模板自带）",
+        "  utilities/  ht32_board 板级支持",
+        "  project/    MDK_ARMv5（Keil 工程文件）+ Src_USER（用户文件）",
+        "",
+        "后续步骤：",
+        *_FOLLOWUP,
+    ]
+    return "\n".join(lines)
+
+
+def bundle_report(b: Bundle, base_url: str, ttl_seconds: int) -> str:
+    url = f"{base_url.rstrip('/')}/{b.path.name}"
+    lines = [
+        "自包含 Keil 工程已打包（云端 zip 下载）：",
+        f"下载 URL：{url}",
+        f"有效期：{ttl_seconds} 秒（至 {_fmt_time(b.expires_at)}）",
+        f"大小：{b.size / 1048576:.2f} MB（{b.materialized.files} 文件）",
+        f"SHA256：{b.sha256}",
+        *_spec_lines(b.materialized),
+        "",
+        "下载解压：zip 内文件直接位于根（project/ library/ utilities/ component/），"
+        "解压到目标工程目录即可；过期后重新调用本工具获取新 URL。",
+        "后续步骤：",
+        *_FOLLOWUP,
+    ]
+    return "\n".join(lines)
+
+
+def _replace_define(text: str, anchor: str, new_value: str) -> str:
+    """替换 uvprojx 中包含 anchor 的 <Define> 行内容（Cads/Aads 各一条）。"""
+    pattern = re.compile(r"(<Define>)[^<]*" + re.escape(anchor) + r"[^<]*(</Define>)")
+    if not pattern.search(text):
+        raise ExportError(f"uvprojx 中未找到含 {anchor} 的 <Define>，模板结构可能已变化")
+    return pattern.sub(rf"\g<1>{new_value}\g<2>", text, count=1)

{ht32_code_mcp-0.1.1 → ht32_code_mcp-0.1.2}/src/ht32_code_mcp/server.py

@@ -12,7 +12,12 @@ from pathlib import Path
 
 from fastmcp import FastMCP
 
-from .exporter import ExportError, ProjectExporter
+from .exporter import (
+    DEFAULT_BUNDLE_TTL,
+    ExportError,
+    ProjectExporter,
+    bundle_report,
+)
 from .index import CodeIndex, normalize_series
 from .knowledge import KnowledgeSearch
 
@@ -20,6 +25,22 @@ from .knowledge import KnowledgeSearch
 DEFAULT_CODE_ROOT = Path(__file__).resolve().parents[4]
 CODE_ROOT = Path(os.environ.get("CODE_ROOT", DEFAULT_CODE_ROOT))
 
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.environ.get(name, "").strip()
+    try:
+        return int(raw) if raw else default
+    except ValueError:
+        return default
+
+
+# 云端 bundle 下载通道：BUNDLE_DIR（容器内可写目录，nginx 静态目录同源）+
+# BUNDLE_BASE_URL（公网下载前缀）同时配置才启用；否则回退本地目录导出。
+BUNDLE_DIR = os.environ.get("BUNDLE_DIR", "").strip()
+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)
+
 index = CodeIndex(CODE_ROOT).load()
 knowledge = KnowledgeSearch(CODE_ROOT)
 exporter = ProjectExporter(CODE_ROOT)
@@ -38,7 +59,8 @@ _INSTRUCTIONS = """HT32 代码知识库（函数库/例程/工程模板），当
 - 找官方例程（按外设/系列/芯片） → find_example → get_file(例程路径) 看原码
 - 取 raw/ 真实源文件（驱动 .c/.h、例程、devices.json 等） → get_file
 - 检索知识页（初始化套路/易错点/子系列差异） → search_code_knowledge
-- 新建工程 → get_project_manifest 看模板 → export_project_bundle(chip, out_dir) 导出自包含工程
+- 新建工程 → get_project_manifest 看模板 → export_project_bundle(chip[, out_dir]) 导出自包含工程
+  （云端返回 zip 下载 URL，本地返回落盘目录）
 
 ## 通用约定
 - 路径一律为仓库相对 posix 路径（raw/... 开头），get_file 直接可用
@@ -75,6 +97,9 @@ def get_code_version() -> str:
     lines = [
         f"ht32-code 知识库版本：{index.data.get('code_version', 'unknown')}",
         f"MCP server：ht32-code-mcp {_MCP_VERSION}",
+        ("云端 zip 下载：启用（TTL "
+         f"{BUNDLE_TTL}s，{BUNDLE_BASE_URL}）" if CLOUD_BUNDLE
+         else "云端 zip 下载：未配置（本地目录模式，export 需提供 out_dir）"),
         "",
         "VERSION 文件内容：",
         version_text,
@@ -277,25 +302,44 @@ def get_project_manifest() -> str:
             "+ utilities/（ht32_board 板级支持）+ project/（MDK_ARMv5 工程文件 + Src_USER 用户文件）"
         )
     lines.append("")
-    lines.append("导出工程：export_project_bundle(chip, out_dir) —— 复制模板（含全量官方库）"
+    lines.append("导出工程：export_project_bundle(chip[, out_dir]) —— 复制模板（含全量官方库）"
                  "并按型号参数化 uvprojx（Device/C 宏/汇编宏/system/startup），"
                  "产出自包含可编译工程。")
+    lines.append("交付方式：" + (
+        f"云端 zip 下载（随机 token + {BUNDLE_TTL}s TTL，返回下载 URL，out_dir 忽略）"
+        if CLOUD_BUNDLE else "本地目录导出（out_dir 必填）"))
     return "\n".join(lines)
 
 
 @mcp.tool()
-def export_project_bundle(chip: str, out_dir: str) -> str:
-    """按芯片型号从模板组装自包含可编译 Keil 工程到本地目录。
+def export_project_bundle(chip: str, out_dir: str = "") -> str:
+    """按芯片型号从模板组装自包含可编译 Keil 工程。
 
     动作：复制 raw/templates/ht32f5-keil 模板（模板自带全量官方库 library/）→
     按 devices.json 参数化 uvprojx（Device、C 宏、汇编宏，以及 system/startup
     文件指向）。产物可直接用 Keil MDK 打开编译（需 HT32_DFP pack）。
-    本阶段为本地目录导出；云端 token 下载 URL 后续阶段扩展。
+
+    两种交付形态（由服务端环境决定，无需调用方判断）：
+    - 云端模式：返回带 TTL 的 zip 下载 URL（含 SHA256 与大小），
+      此时 out_dir 被忽略。
+    - 本地模式：物化到 out_dir（须为空目录或不存在；不会覆盖已有内容）。
 
     Args:
         chip: 芯片型号，如 "HT32F52352"（大小写不敏感）
-        out_dir: 输出目录（须为空目录或不存在；不会覆盖已有内容）
+        out_dir: 输出目录（本地模式必填；云端模式忽略）
     """
+    if CLOUD_BUNDLE:
+        try:
+            bundle = exporter.export_zip(chip, BUNDLE_DIR, BUNDLE_TTL)
+        except ExportError as e:
+            return f"导出失败：{e}"
+        except OSError as e:
+            return f"导出失败（打包或写盘失败，检查 bundle 目录权限/空间）：{e}"
+        return bundle_report(bundle, BUNDLE_BASE_URL, BUNDLE_TTL)
+    if not out_dir.strip():
+        return ("导出失败：缺少 out_dir。当前为本地目录模式"
+                "（服务端未配置 BUNDLE_DIR / BUNDLE_BASE_URL），"
+                '请提供输出目录，如 out_dir="D:\\\\proj\\\\HT32_OTA_DEMO"。')
     try:
         return exporter.export(chip, out_dir)
     except ExportError as e:

{ht32_code_mcp-0.1.1 → ht32_code_mcp-0.1.2}/tests/test_tools.py

@@ -4,7 +4,10 @@
 """
 from __future__ import annotations
 
+import os
 import re
+import time
+import zipfile
 from pathlib import Path
 
 import pytest
@@ -225,6 +228,79 @@ def test_export_refuses_nonempty_dir(tmp_path):
     assert (out / "keep.txt").is_file()  # 原有内容未被破坏
 
 
+# ---------------------------------------------------------------- 云端 zip bundle
+def test_export_zip_positive(tmp_path):
+    bdir = tmp_path / "bundles"
+    b = srv.exporter.export_zip("HT32F52352", str(bdir), 3600)
+    assert b.path.is_file() and b.path.name == f"{b.token}.zip"
+    assert b.size > 0 and len(b.sha256) == 64
+    with zipfile.ZipFile(b.path) as zf:
+        names = zf.namelist()
+        assert len(names) == b.materialized.files  # zip 内条目与物化文件数一致
+        for rel in ("project/MDK_ARMv5/ht32f5-template.uvprojx",
+                    "project/Src_USER/main.c", "utilities/ht32_board.c",
+                    "library/HT32F5xxxx_Driver/inc/ht32f5xxxx_lib.h"):
+            assert rel in names, rel
+        # 参数化结果落在 zip 内的工程文件中
+        text = zf.read("project/MDK_ARMv5/ht32f5-template.uvprojx").decode("utf-8")
+        assert "<Device>HT32F52352</Device>" in text
+        assert "USE_HT32F52342_52" in text
+    # 临时物化目录已清理，bundle 目录只剩 zip
+    assert [p.name for p in bdir.iterdir()] == [b.path.name]
+
+
+def test_export_zip_report_cloud_mode(tmp_path, monkeypatch):
+    monkeypatch.setattr(srv, "CLOUD_BUNDLE", True)
+    monkeypatch.setattr(srv, "BUNDLE_DIR", str(tmp_path / "bundles"))
+    monkeypatch.setattr(srv, "BUNDLE_BASE_URL", "https://mcp.s621.work/ht32-bundles")
+    monkeypatch.setattr(srv, "BUNDLE_TTL", 3600)
+    out = srv.export_project_bundle("HT32F52352")  # 云端模式无需 out_dir
+    assert "云端 zip 下载" in out
+    m = re.search(r"下载 URL：(\S+)", out)
+    assert m and m.group(1).startswith("https://mcp.s621.work/ht32-bundles/")
+    assert m.group(1).endswith(".zip")
+    assert "有效期：3600 秒" in out and "SHA256：" in out
+    assert "目标芯片：HT32F52352" in out
+    # 报告中的 URL 真实可指到文件
+    assert (tmp_path / "bundles" / m.group(1).rsplit("/", 1)[-1]).is_file()
+
+
+def test_export_zip_unknown_chip(tmp_path):
+    with pytest.raises(srv.ExportError):
+        srv.exporter.export_zip("HT32F99999", str(tmp_path / "bundles"), 3600)
+    assert not list((tmp_path / "bundles").glob("*.zip"))
+
+
+def test_export_zip_sweep_expired(tmp_path):
+    bdir = tmp_path / "bundles"
+    bdir.mkdir()
+    old = time.time() - 7200
+    stale_zip = bdir / "stale.zip"
+    stale_zip.write_bytes(b"old")
+    fresh_zip = bdir / "fresh.zip"
+    fresh_zip.write_bytes(b"keep")
+    os.utime(stale_zip, (old, old))
+
+    b = srv.exporter.export_zip("HT32F52352", str(bdir), 3600)
+    assert not stale_zip.exists()  # 过期被清理
+    assert fresh_zip.is_file()  # 未过期保留
+    assert b.path.is_file()
+
+
+def test_export_local_mode_requires_out_dir(monkeypatch):
+    monkeypatch.setattr(srv, "CLOUD_BUNDLE", False)
+    out = srv.export_project_bundle("HT32F52352")
+    assert "导出失败" in out and "out_dir" in out
+
+
+def test_version_reports_bundle_mode(monkeypatch):
+    monkeypatch.setattr(srv, "CLOUD_BUNDLE", False)
+    assert "云端 zip 下载：未配置" in srv.get_code_version()
+    monkeypatch.setattr(srv, "CLOUD_BUNDLE", True)
+    monkeypatch.setattr(srv, "BUNDLE_BASE_URL", "https://mcp.s621.work/ht32-bundles")
+    assert "云端 zip 下载：启用" in srv.get_code_version()
+
+
 # ---------------------------------------------------------------- 索引可重复构建
 def test_index_rebuild_deterministic():
     from ht32_code_mcp.index import CodeIndex

{ht32_code_mcp-0.1.1 → ht32_code_mcp-0.1.2}/uv.lock

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

ht32_code_mcp-0.1.1/src/ht32_code_mcp/exporter.py

@@ -1,128 +0,0 @@
-"""export_project_bundle：从模板组装自包含可编译 Keil 工程到本地目录。
-
-模板自带全量官方库树（library/），因此导出只需复制模板 + 按 devices.json
-参数化 uvprojx（Device / C 宏 / 汇编宏 / system / startup 文件指向）。
-本阶段（P0-2）不做 token 下载 URL，云端阶段再扩展。
-参数化依据：raw/templates/ht32f5-keil/devices.json（device/cdef/adef/sys/startup）。
-"""
-from __future__ import annotations
-
-import json
-import re
-import shutil
-from pathlib import Path
-
-# 模板中默认型号（HT32F52352）的 system / startup 文件名主干，导出时按目标型号替换
-_TEMPLATE_SYS_STEM = "system_ht32f5xxxx_01"
-_TEMPLATE_STARTUP_STEM = "startup_ht32f5xxxx_01"
-
-
-class ExportError(Exception):
-    """导出失败（型号未知 / 源文件缺失 / 目标目录非空等）。"""
-
-
-def _read_text(path: Path) -> str:
-    return path.read_text(encoding="utf-8", errors="replace")
-
-
-class ProjectExporter:
-    def __init__(self, code_root: Path) -> None:
-        self.root = Path(code_root)
-        self.template_dir = self.root / "raw" / "templates" / "ht32f5-keil"
-        # 模板自带全量官方库树，system/startup 在此校验
-        self.lib_device = (self.template_dir / "library" / "Device"
-                           / "Holtek" / "HT32F5xxxx" / "Source")
-
-    # ------------------------------------------------------------ 主流程
-    def export(self, chip: str, out_dir: str) -> str:
-        if not self.template_dir.is_dir():
-            raise ExportError(f"模板目录不存在：{self.template_dir}")
-        device, entry = self._resolve_device(chip)
-
-        # 1. 预检目标目录
-        out = Path(out_dir).expanduser().resolve()
-        if out.exists() and any(out.iterdir()):
-            raise ExportError(f"目标目录非空，拒绝覆盖：{out}（请指定新目录或先清空）")
-
-        # 2. 预检模板内目标型号所需源文件（先验证后落盘，失败不产生半成品）
-        sys_c = self.lib_device / entry["sys"]
-        sys_h = sys_c.parent.parent / "Include" / (sys_c.stem + ".h")
-        startup = self.lib_device / "ARM" / entry["startup"]
-        missing = [str(p) for p in (sys_c, sys_h, startup) if not p.is_file()]
-        if missing:
-            raise ExportError("模板 library/ 缺少所需源文件：\n- " + "\n- ".join(missing))
-
-        # 3. 复制模板树（含全量官方库，导出即自包含）
-        out.mkdir(parents=True, exist_ok=True)
-        shutil.copytree(self.template_dir, out, dirs_exist_ok=True)
-
-        # 4. 参数化 uvprojx：Device / C 宏 / 汇编宏 / system / startup 指向
-        uvprojx = out / "project" / "MDK_ARMv5" / "ht32f5-template.uvprojx"
-        text = _read_text(uvprojx)
-        text = re.sub(r"(<Device>)[^<]*(</Device>)", rf"\g<1>{device}\g<2>", text, count=1)
-        text = _replace_define(text, "USE_HT32_DRIVER", entry["cdef"])
-        text = _replace_define(text, "USE_HT32_CHIP", entry["adef"])
-        text = text.replace(_TEMPLATE_SYS_STEM, sys_c.stem)
-        text = text.replace(_TEMPLATE_STARTUP_STEM, startup.stem)
-        with open(uvprojx, "w", encoding="utf-8", newline="") as f:
-            f.write(text)
-
-        return self._report(out, device, entry, sys_c, sys_h, startup)
-
-    # ------------------------------------------------------------ 辅助
-    def _resolve_device(self, chip: str) -> tuple[str, dict]:
-        dj = self.template_dir / "devices.json"
-        if not dj.is_file():
-            raise ExportError(f"模板型号参数表缺失：{dj}")
-        meta = json.loads(dj.read_text(encoding="utf-8"))
-        want = chip.strip().upper()
-        for d in meta.get("devices", []):
-            if d.get("device", "").upper() == want:
-                return d["device"], d          # 重名取首条（官方板级变体）
-        # 宽松匹配：型号主体包含（HT32F52352 含于 HT32F52352_SK 场景已由上面精确处理）
-        for d in meta.get("devices", []):
-            if want in d.get("device", "").upper():
-                return d["device"], d
-        names = [d.get("device", "") for d in meta.get("devices", [])][:20]
-        raise ExportError(
-            f"型号 '{chip}' 不在模板参数表（共 {meta.get('count', '?')} 个型号）。\n"
-            f"可用型号（前 20）：{', '.join(names)}…\n"
-            "完整清单：get_file('raw/templates/ht32f5-keil/devices.json') 或 get_project_manifest()"
-        )
-
-    def _report(self, out: Path, device: str, entry: dict,
-                sys_c: Path, sys_h: Path, startup: Path) -> str:
-        n_files = sum(1 for p in out.rglob("*") if p.is_file())
-        lines = [
-            f"自包含 Keil 工程已导出：{out}",
-            f"目标芯片：{device}",
-            f"工程文件：project/MDK_ARMv5/ht32f5-template.uvprojx（已按型号参数化）",
-            f"C 宏（Cads）：{entry['cdef']}",
-            f"汇编宏（Aads）：{entry['adef']}",
-            f"system：library/Device/Holtek/HT32F5xxxx/Source/{sys_c.name}"
-            f"（+ Include/{sys_h.name}）",
-            f"startup：library/Device/Holtek/HT32F5xxxx/Source/ARM/{startup.name}",
-            f"libcfg：library/HT32F5xxxx_Driver/inc/（ht32f5xxxx_lib.h 按 C 宏自动引入）",
-            f"文件总数：{n_files}",
-            "",
-            "目录结构：",
-            "  component/  共享组件层（基础模板为空，按项目增补）",
-            "  library/    CMSIS / Device / Driver / USBD（全量官方库，模板自带）",
-            "  utilities/  ht32_board 板级支持",
-            "  project/    MDK_ARMv5（Keil 工程文件）+ Src_USER（用户文件）",
-            "",
-            "后续步骤：",
-            "1. Keil MDK 打开 project/MDK_ARMv5/ht32f5-template.uvprojx"
-            "（需 Holtek HT32_DFP pack ≥1.0.67）",
-            "2. 如需精确 IROM/IRAM 内存布局，在 Options → Device 重新选择该型号由 DFP 刷新",
-            "3. 基线编译验证（P0-4.2 将用 UV4 命令行复核 0 Error 0 Warning）",
-        ]
-        return "\n".join(lines)
-
-
-def _replace_define(text: str, anchor: str, new_value: str) -> str:
-    """替换 uvprojx 中包含 anchor 的 <Define> 行内容（Cads/Aads 各一条）。"""
-    pattern = re.compile(r"(<Define>)[^<]*" + re.escape(anchor) + r"[^<]*(</Define>)")
-    if not pattern.search(text):
-        raise ExportError(f"uvprojx 中未找到含 {anchor} 的 <Define>，模板结构可能已变化")
-    return pattern.sub(rf"\g<1>{new_value}\g<2>", text, count=1)