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

ht32_code_mcp-0.1.3/DEPLOY.md

@@ -0,0 +1,300 @@
+# 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 步）
+
+本部署的 OpenResty 是**容器化**的（容器名 `1Panel-openresty-ih7J`），
+已挂载 `WEBSITE_DIR=/opt/1panel/www` → 容器内 `/www`。
+因此 bundle 目录直接落在网站根目录树下，**OpenResty 的 volumes 一行都不用改**——
+两个容器通过宿主机上的同一目录交换文件：
+
+```
+宿主机 /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles/   （站点 root 目录下 + /ht32-bundles）
+  ├─ code-mcp 容器看到  /app/bundles
+  └─ OpenResty 容器看到 /www/sites/mcp.s621.work/index/ht32-bundles
+  公网 URL             https://mcp.s621.work/ht32-bundles/<token>.zip
+```
+
+站点「网站目录」显示 root = `/opt/1panel/www/sites/mcp.s621.work/index`，
+bundle 放其下子目录即被当作静态文件直接访问。
+
+**第 1 步：宿主机建 bundle 目录**
+
+```bash
+mkdir -p /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles
+chmod 755 /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles
+```
+
+**第 2 步：1Panel 给 code-mcp 容器补挂载与环境变量**
+
+| 配置项 | 值 |
+|--------|-----|
+| 挂载 | `/opt/1panel/www/sites/mcp.s621.work/index/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/1panel/www/sites/mcp.s621.work/index/ht32-bundles:/app/bundles   ← 宿主机路径，非容器内路径
+```
+
+**第 3 步：OpenResty 无需任何配置**
+
+站点 root = `/opt/1panel/www/sites/mcp.s621.work/index`，映射到容器内
+`/www/sites/mcp.s621.work/index`。bundle 目录落在这个 root 之下子目录，
+静态文件天然可访问，**不用建反向代理、不用手写 location、不用改 compose**。
+
+> **不要为 bundles 建反向代理条目**：1Panel 反代 UI 表达不了静态 location
+> （后端代理地址必填，而静态目录没有后端）。若建了且后端留空，1Panel 生成的
+> location 会抢走 `/ht32-bundles/` 却不知从哪读文件 → 404。已有此类条目请删除。
+
+> **静态 location 无需 `proxy_*` 指令**：文件由 nginx 读盘直接返回，不用
+> `proxy_pass`，也不用 `proxy_read_timeout`——这与 code 的代理 location 形态不同属正常。
+
+> **权限**：1Panel 站点要求 `index` 目录下所有文件/目录属主与属组为 `1000`（见
+> 「网站目录」页提示，PHP 容器环境）。nginx worker 需可读该目录；zip 文件 644 /
+> 目录 755 正常可读。若验证时拿 403，先查属主属组与 SELinux 上下文。
+
+重载（改了容器挂载或环境变量时需重建 code-mcp；仅改文件无需重载 nginx）：
+
+```bash
+docker exec 1Panel-openresty-ih7J nginx -t
+```
+
+### 验证生效
+
+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/1panel/www/sites/mcp.s621.work/index/ht32-bundles` 只有 `*.zip`（无残留临时目录）。
+
+## 反馈与用量日志（P1-5，0.1.3+）
+
+两条通道写入同一目录、按 UTC 日期分文件（JSON Lines）：
+
+| 通道 | 触发 | 记录内容 |
+|------|------|----------|
+| `usage_YYYY-MM-DD.jsonl` | **服务端自动**（middleware 拦截所有工具调用） | 工具名、参数原文（剔除 `limit`/`max_length`/`out_dir`）、耗时、成败、错误、客户端 session |
+| `feedback_YYYY-MM-DD.jsonl` | **Agent 主动**（`submit_feedback` 工具） | 语义性问题：答错 / 知识库缺口 / 模板缺陷，含 `issue_type`、`model_id`、`tools_called` |
+
+自动通道保证调用事实完整（不依赖 Agent 配合）；反馈通道补 middleware
+判断不了的语义问题。`issue_type` 枚举：`wrong_api` / `missing_info` /
+`wrong_path` / `export_defect` / `unclear` / `other`。
+
+### 环境变量
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `CODE_LOG_DIR` | 空（= **整体关闭**，本地开发默认不落盘） | 日志写入目录，须可写 |
+
+> **隐私**：参数按原文记录，`query`/`question` 可能含用户项目信息。
+> 该目录只应挂在受控服务器上，**不要提交进仓库**（定时脚本是
+> `git reset --hard` 镜像模式，写进仓库也会被覆盖丢失）。
+
+### 服务器侧落地（2 步）
+
+**第 1 步：宿主机建日志目录**
+
+```bash
+mkdir -p /opt/ht32-code-logs
+chmod 755 /opt/ht32-code-logs
+```
+
+**第 2 步：1Panel 给 code-mcp 容器补挂载与环境变量**
+
+| 配置项 | 值 |
+|--------|-----|
+| 挂载 | `/opt/ht32-code-logs:/app/logs`（**不要加 `:ro`，需可写**） |
+| 环境变量 | `CODE_LOG_DIR=/app/logs` |
+
+完整配置（含现有项）：
+
+```
+类型：        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
+            CODE_LOG_DIR=/app/logs
+挂载：        /opt/ht32-code:/app/code
+            /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles:/app/bundles
+            /opt/ht32-code-logs:/app/logs
+```
+
+### 验证生效
+
+1. 调 `get_code_version`，应出现 `用量日志：启用（/app/logs）`。
+   仍显示「未配置」→ 环境变量没注入（查变量名 / 容器是否重建）。
+
+2. 随便调几个工具，然后看日志：
+
+   ```bash
+   tail -3 /opt/ht32-code-logs/usage_$(date -u +%Y-%m-%d).jsonl
+   ```
+
+3. 按日期分析需求分布（示例：统计被请求的芯片型号，指导 P2-1 排优先级）：
+
+   ```bash
+   grep -h export_project_bundle /opt/ht32-code-logs/usage_*.jsonl \
+     | python3 -c "
+   import sys, json, collections
+   c = collections.Counter()
+   for l in sys.stdin:
+       c.update([json.loads(l)['args'].get('chip', '?')])
+   for k, v in c.most_common():
+       print(f'{v:5d}  {k}')
+   "
+   ```
+
+4. 清理策略由定时同步脚本第 7 步负责（`LOG_KEEP_DAYS=30`，与同步日志同口径）。
+
+## 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.2（2026-09-21，含 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 空闲断连；2026-09-21 复核两端空闲 100s 后调用仍 200，未被 1Panel 回退 | ✅ |
+| 3.7 | 云端 zip 下载通道（P1-3） | 服务器侧已上线：下载 1608157 字节 / SHA256 一致 / 解压 455 文件 / UV4 0E0W | ✅ |
+| 3.8 | 定时同步脚本含 bundle 清理（P1-2） | `ht32-code-mcp-update.md` 第 6 步 `find … -mmin +60 -delete` | ✅ |

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ht32-code-mcp
-Version: 0.1.1
+Version: 0.1.3
 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.3}/ht32-code-mcp-update.md

@@ -26,6 +26,16 @@
 
 # 日志：按天归档 /opt/ht32-code-sync/ht32-code-sync-YYYYMMDD.log，自动清理 30 天前的旧日志
 
+# - 顺带清理 bundle 下载目录的过期 zip（P1-3）
+
+# （server 每次 export 前也会 sweep 一次，此处为兜底：
+
+#  若一段时间无人调用 export，TTL 过期的 zip 不会被那次 sweep 清掉）
+
+# - 顺带清理超期的用量日志 / 反馈 JSONL（P1-5）
+
+# （保留 LOG_KEEP_DAYS 天，与同步日志同口径）
+
 # ============================================================
 
 set -e
@@ -37,6 +47,15 @@ LOG_FILE="$LOG_DIR/ht32-code-sync-$(date '+%Y%m%d').log"
 LOG_KEEP_DAYS=30
 INDEX_FILE="$CODE_DIR/.work/mcp-server/index/code_index.json"
 
+# bundle 目录（站点 root 下子目录，OpenResty 直接静态提供）与保留时长
+
+BUNDLE_DIR="/opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles"
+BUNDLE_TTL_MIN=60
+
+# 用量日志 / 反馈目录（1Panel 挂载到容器 /app/logs）
+
+CODE_LOG_DIR="/opt/ht32-code-logs"
+
 # 日志目录（不存在则创建）
 
 mkdir -p "$LOG_DIR"
@@ -101,4 +120,22 @@ fi
 
 find "$LOG_DIR" -name "ht32-code-sync-*.log" -mtime +$LOG_KEEP_DAYS -delete 2>/dev/null || true
 
+# 6. 清理 bundle 目录中超过 TTL 的 zip（兜底，与 BUNDLE_TTL_SECONDS 保持一致）
+
+if [ -d "$BUNDLE_DIR" ]; then
+    SWEPT=$(find "$BUNDLE_DIR" -maxdepth 1 -name "*.zip" -mmin +$BUNDLE_TTL_MIN -print -delete 2>/dev/null | wc -l)
+    log "bundle 清理：删除 $SWEPT 个过期 zip"
+else
+    log "bundle 目录不存在，跳过清理：$BUNDLE_DIR"
+fi
+
+# 7. 清理超期的用量日志 / 反馈（同样保留 LOG_KEEP_DAYS 天）
+
+if [ -d "$CODE_LOG_DIR" ]; then
+    OLD_LOGS=$(find "$CODE_LOG_DIR" -maxdepth 1 \( -name "usage_*.jsonl" -o -name "feedback_*.jsonl" \) -mtime +$LOG_KEEP_DAYS -print -delete 2>/dev/null | wc -l)
+    log "用量日志清理：删除 $OLD_LOGS 个过期文件"
+else
+    log "用量日志目录不存在，跳过清理：$CODE_LOG_DIR"
+fi
+
 log "本次同步完成"

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

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

ht32_code_mcp-0.1.3/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)