ht32-code-mcp 0.5.1__tar.gz → 0.5.3__tar.gz

{ht32_code_mcp-0.5.1 → ht32_code_mcp-0.5.3}/DEPLOY.md

@@ -42,15 +42,14 @@ PyPI 包 → FastMCP 直接提供 Streamable HTTP（常驻单进程）
 
 ### 镜像与端点
 
-- 镜像 `ht32-code-mcp:0.5.0`：`ghcr.io/astral-sh/uv:python3.12-bookworm-slim` +
-  `git/curl/ca-certificates`，`uv tool install ht32-code-mcp==0.5.0`，入口直跑
+- 镜像 `ht32-code-mcp:0.5.1`：`ghcr.io/astral-sh/uv:python3.12-bookworm-slim` +
+  `git/curl/ca-certificates`，`uv tool install ht32-code-mcp==0.5.1`，入口直跑
   `ht32-code-mcp`（私有组件能力仍需服务端 git）。由 `.work/docker/Dockerfile` 构建。
 - 传输：生产 `MCP_TRANSPORT=streamable-http`，`path=/ht32-code`（`MCP_PATH` 注入）；
   本地调试保持默认 `/mcp`。`stdio` 仅供冒烟测试。
 - `MCP_JSON_RESPONSE=0`：保持 SSE，兼容现有客户端。
 - 健康检查：`GET /health` → `{"status":"ok","version":"<包版本>"}`，不触发检索。
-- 资源：`mem_limit: 1g` / `cpus: 1.0` / `pids_limit: 512`（常驻单进程与多会话对象）；
-  不再使用 V1 按「一会话一进程」算出的 `4g` / `1024` 熔断值。
+- 资源：`mem_limit: 1g` / `cpus: 1.0` / `pids_limit: 512`（常驻单进程与多会话对象）。
 
 ## compose 关键配置
 
@@ -66,7 +65,7 @@ PyPI 包 → FastMCP 直接提供 Streamable HTTP（常驻单进程）
 | `COMPONENTS_CONFIG` | `/app/code/.work/components/components.json` |
 | `COMPONENTS_STATE_FILE` | `/app/feedback/component-tag-lock.json` |
 | 凭据 | `.work/docker/.env` 的 `COMPONENTS_GIT_AUTH`（base64 用户名:只读 token），已 gitignore |
-| `MCP_TRANSPORT` | `streamable-http`（不经 supergateway） |
+| `MCP_TRANSPORT` | `streamable-http`（容器直跑，无中间网关） |
 | `MCP_HOST` / `MCP_PORT` | `0.0.0.0` / `8001` |
 | `MCP_PATH` | `/ht32-code`（须与反代 location 一致） |
 | `MCP_STATELESS_HTTP` | `0`（P0 保留进程内有状态会话） |
@@ -140,7 +139,7 @@ location ^~ /ht32-bundles {
 
 | 通道 | 文件 | 触发 | 内容 |
 |------|------|------|------|
-| 用量日志 | `usage_*.jsonl` | 服务端自动（middleware） | 工具名、参数原文、耗时、成败、session |
+| 用量日志 | `usage_*.jsonl` | 服务端自动（middleware） | 工具名、参数原文、耗时、成败、session、客户端身份（`client_name`/`client_version`，取自 initialize 的 `clientInfo`） |
 | 反馈 | `feedback_*.jsonl` | Agent 主动（`submit_feedback`） | 语义性问题 |
 
 - `FEEDBACK_ROOT` 为空 = 整体关闭（本地开发默认不落盘）；必须填**绝对路径**。
@@ -272,8 +271,8 @@ curl -s -o /dev/null -w "%{http_code}" https://mcp.s621.work/ht32-code   # 400 =
 ```
 
 - 启动日志应含 `启动服务: Streamable HTTP 0.0.0.0:8001/ht32-code（stateless=False, json=False）`；
-  若仍见 supergateway / `--stateful`，说明服务器 compose 未同步或镜像未重建
-- 协议版本被拒 → 旧镜像或旧客户端；本版直接由 FastMCP 4.x 提供，不再经 supergateway
+  否则检查服务器 compose 与镜像是否已同步
+- 协议版本被拒 → 检查镜像版本与客户端协议版本
 - `/health` 404 → 进程是旧版（`MCP_PATH` 之前的版本没有该路由）
 - 容器 126 退出 → 旧 compose 的 `$$(...)` 命令替换被吃掉；新版无 `command`，重新 `git pull` 即可
 - 首会话超时 → 冷启动（索引加载）；容器健康检查 `start_period: 60s` 已留余量

{ht32_code_mcp-0.5.1 → ht32_code_mcp-0.5.3}/PKG-INFO

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

{ht32_code_mcp-0.5.1 → ht32_code_mcp-0.5.3}/README.md

@@ -1,8 +1,8 @@
 # .work/mcp-server/
 
-MCP server 代码目录（Python + FastMCP），实现 11 个检索/导出工具 + 版本检查 + 1 个反馈工具。
+MCP server 代码目录（Python + FastMCP），实现 **13 个工具**（检索/导出/组件/版本检查/反馈）。
 
-传输由 `MCP_TRANSPORT` 决定：`stdio`（默认，供 supergateway 包装）/ `streamable-http` / `sse`。
+传输由 `MCP_TRANSPORT` 决定：`stdio`（本地调试/冒烟）/ `streamable-http`（线上，FastMCP 常驻单进程）/ `sse`（旧客户端兼容）。
 部署与排错见 [DEPLOY.md](DEPLOY.md)。
 
 ## 私有组件（0.4.5+）

{ht32_code_mcp-0.5.1 → ht32_code_mcp-0.5.3}/pyproject.toml

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

{ht32_code_mcp-0.5.1 → ht32_code_mcp-0.5.3}/src/ht32_code_mcp/server.py

@@ -138,7 +138,8 @@ M0+（HT32F5 / L5）、M3（HT32F1 / F175x-275x）、M4（F490x1 / F491x3 / F493
 
 ## 按需求选工具
 - 确认版本/覆盖范围 → get_code_version
-- 问"某外设库怎么用/有哪些模块" → list_libraries → search_code_knowledge(模块名)
+- 问"某外设库怎么用/有哪些模块" → list_libraries(compact=True) 或 list_libraries(module="gpio")
+  → search_code_knowledge(模块名)；需要 raw 路径时用 list_libraries(module="<模块名>") 取，不要猜路径
 - 找官方例程（按外设/系列/芯片） → find_example → get_file(例程路径) 看原码
 - 取 raw/ 真实源文件（驱动 .c/.h、例程、devices.json 等） → get_file
 - 检索知识页（初始化套路/易错点/子系列差异） → search_code_knowledge
@@ -304,32 +305,59 @@ def get_code_version() -> str:
 
 
 @mcp.tool()
-def list_libraries() -> str:
+def list_libraries(series: str = "", module: str = "", compact: bool = False) -> str:
     """枚举函数库模块与覆盖系列。
 
     返回每个库模块的驱动源码/头文件路径（raw/）、变体数、
     对应官方例程数与知识页路径（entities/libraries/）。
+
+    Args:
+        series: 系列或内核家族过滤（f5 / l5 / F493x5 / M0+ / M3 / M4），默认不过滤
+        module: 模块名子串过滤（如 gpio / usart），只列命中模块并保留完整路径
+        compact: True 时每包一行只给模块名清单（省 token）；需要路径时用
+            module= 或 compact=False
     """
     fwlibs = index.data.get("fwlibs", [])
     families: dict[str, list[str]] = {}
     for p in fwlibs:
         families.setdefault(p.get("family") or "?", []).append(
             "/".join(p.get("series") or ["?"]))
+    # 表头始终按全量固件库计算：migrate 靠「包 → 系列」判定同系列，过滤后不能丢
     lines = ["库模块清单（模块名按官方驱动 .c 文件名归一）：",
              f"覆盖 {len(fwlibs)} 个固件库包 / {len(families)} 个内核家族："
              + "；".join(f"{k}（{'、'.join(v)}）" for k, v in sorted(families.items()))]
+    pool = fwlibs
+    if series:
+        pool = _filter_by_series(pool, series)
+        if not pool:
+            return (f"系列 '{series}' 不在覆盖范围。当前覆盖："
+                    + "、".join(
+                        f"{p['name']}（{'/'.join(p.get('series') or ['?'])}，"
+                        f"{p.get('family') or '?'}）" for p in fwlibs))
+        lines.append(f"（已按系列 '{series}' 过滤，命中 {len(pool)} 个包）")
     page_paths = {p["path"] for p in index.data.get("knowledge_pages", [])}
-    for pkg in fwlibs:
-        series = "/".join(pkg.get("series") or ["?"]) + (f"（{pkg['family']}）" if pkg.get("family") else "")
+    want = module.strip().lower()
+    matched = False
+    for pkg in pool:
+        series_label = "/".join(pkg.get("series") or ["?"]) + (
+            f"（{pkg['family']}）" if pkg.get("family") else "")
         ex_counts: dict[str, int] = {}
         for ex in pkg.get("examples", []):
             ex_counts[ex["peripheral"].lower()] = ex_counts.get(ex["peripheral"].lower(), 0) + 1
         modules: dict[str, list[dict]] = {}
         for m in pkg.get("modules", []):
             modules.setdefault(m["module"], []).append(m)
+        if want:
+            modules = {k: v for k, v in modules.items() if want in k.lower()}
+            if not modules:
+                continue
+            matched = True
         lines.append("")
-        lines.append(f"== 固件库 {pkg['name']}（系列 {series}）== "
+        lines.append(f"== 固件库 {pkg['name']}（系列 {series_label}）== "
                      f"共 {len(modules)} 个模块")
+        if compact:
+            lines.append("、".join(sorted(modules)))
+            continue
         for mod in sorted(modules):
             variants = modules[mod]
             srcs = "、".join(v["src"] for v in variants)
@@ -339,8 +367,17 @@ def list_libraries() -> str:
                 f"- {mod}：{len(variants)} 个驱动变体 | {srcs}"
                 f" | 例程 {ex_counts.get(mod, 0)} 个 | 知识页 {page_note}"
             )
+    if want and not matched:
+        # 模块名按驱动文件名归一（usart 而非 uart），查不到时回退列全部模块名
+        all_mods = sorted({m["module"] for p in fwlibs for m in p.get("modules", [])})
+        return (f"未找到模块 '{module}'。可用模块（{len(all_mods)} 个）："
+                + "、".join(all_mods))
     lines.append("")
-    lines.append("用法：模块详情查 search_code_knowledge(模块名)；原码用 get_file(路径)。")
+    if compact:
+        lines.append("需要路径/例程数/知识页：list_libraries(module=\"<模块名>\") "
+                     "或 list_libraries(compact=False)。")
+    else:
+        lines.append("用法：模块详情查 search_code_knowledge(模块名)；原码用 get_file(路径)。")
     lines.append("注：模块名按驱动文件名归一，跨包同名模块（如 gpio）在各包下独立列出，"
                  "选型时以目标芯片所属系列为准。")
     return "\n".join(lines)

{ht32_code_mcp-0.5.1 → ht32_code_mcp-0.5.3}/src/ht32_code_mcp/usage.py

@@ -7,7 +7,9 @@
 两条采集通道，写入同一目录树：
 
 - **tool_call**（`UsageMiddleware`，服务端自动）：拦截所有工具调用，
-  记录工具名、参数原文、耗时、成败。不依赖 Agent 配合，数据完整。
+  记录工具名、参数原文、耗时、成败，以及 MCP `initialize` 请求里的客户端身份
+  （`client_info.name` / `client_info.version` → 日志字段 `client_name` /
+  `client_version`，老客户端未上报时为空串）。不依赖 Agent 配合，数据完整。
 - **feedback**（`record_feedback`，由各 server 的 `submit_feedback` 工具调用）：
   记录 Agent 主动上报的语义性问题，middleware 无法判断这些。其中 `skill_version`
   由 Agent 自报（服务端跨进程拿不到客户端 skill 版本），用于定位 ht32-skills 缺陷版本。
@@ -41,7 +43,7 @@ from typing import Any
 from fastmcp.server.middleware import Middleware, MiddlewareContext
 
 # 实现版本号：两仓库副本必须一致（各仓测试会校验，防止只改一边造成漂移）
-_IMPL_VERSION = "1.3.0"
+_IMPL_VERSION = "1.4.0"
 
 # 服务名 → 子目录名。新增服务在此登记。
 SERVICE_WIKI = "wiki"
@@ -126,12 +128,35 @@ def write_record(log_dir: str, prefix: str, record: dict[str, Any]) -> Path | No
         return None
 
 
+def _initialize_client(ctx: Any) -> tuple[str, str]:
+    """从 MCP `initialize` 的 `clientInfo` 取客户端名与版本。
+
+    FastMCP 4 / MCP SDK 2 把 initialize 参数常驻在会话底层 Connection 上
+    （`session.client_params.client_info`），initialize 时写一次、整段会话只读，
+    因此工具调用阶段可直接读取，无需另建缓存，也就不存在并发写竞态。
+    取不到（无会话 / 客户端未上报 / 字段缺失 / 访问抛错）一律返回空串。
+    """
+    try:
+        session = getattr(ctx, "session", None)
+        params = getattr(session, "client_params", None) if session is not None else None
+        info = getattr(params, "client_info", None) if params is not None else None
+        if info is None:
+            return "", ""
+        return str(getattr(info, "name", "") or ""), str(getattr(info, "version", "") or "")
+    except Exception:  # noqa: BLE001 - 采集失败绝不能影响工具调用本身
+        return "", ""
+
+
 def _client_info(context: MiddlewareContext) -> dict[str, str]:
-    """取客户端标识（内存调用等无 session 的场景返回空值）。"""
+    """取客户端标识（内存调用等无 session 的场景返回空值）。
+
+    `client_name` / `client_version` 恒定存在：老客户端未上报 clientInfo 时为空串，
+    保证日志行字段结构不变形。
+    """
+    out: dict[str, str] = {"client_name": "", "client_version": ""}
     ctx = getattr(context, "fastmcp_context", None)
     if ctx is None:
-        return {}
-    out: dict[str, str] = {}
+        return out
     for key in ("client_id", "session_id"):
         val = getattr(ctx, key, None)
         if val:
@@ -139,6 +164,7 @@ def _client_info(context: MiddlewareContext) -> dict[str, str]:
     transport = getattr(ctx, "transport", None)
     if transport:
         out["transport"] = str(transport)
+    out["client_name"], out["client_version"] = _initialize_client(ctx)
     return out
 
 

ht32_code_mcp-0.5.3/tests/test_tool_output_budget.py

@@ -0,0 +1,78 @@
+"""工具输出体积预算 + list_libraries 过滤行为门禁。
+
+目的：`list_libraries` 全量输出曾达 28.5k 字符（~12–14k token），是单次调用最大开销。
+本文件把 compact / module 过滤的收益钉住，同时守住三条准确度约束：
+  1. 表头「包 → 系列」始终按全量固件库计算（migrate 靠它判定同系列）
+  2. module 无命中时回退列出全部模块名（模块名按驱动文件名归一，uart≠usart）
+  3. compact 输出带「怎么取路径」的指引
+
+运行（从 .work/mcp-server/）：pytest tests/test_tool_output_budget.py
+"""
+from __future__ import annotations
+
+from ht32_code_mcp import server as srv
+
+
+# ---------------------------------------------------------------- 体积预算
+def test_list_libraries_compact_budget():
+    out = srv.list_libraries(compact=True)
+    assert len(out) <= 4000, f"compact 全量 {len(out)} 字符，超出 4000 预算"
+
+
+def test_list_libraries_module_budget():
+    out = srv.list_libraries(module="gpio")
+    assert len(out) <= 2000, f"module=gpio {len(out)} 字符，超出 2000 预算"
+
+
+def test_list_libraries_full_budget():
+    out = srv.list_libraries()
+    assert len(out) <= 30000, f"全量 {len(out)} 字符，超出 30000 预算（防回涨）"
+
+
+def test_get_code_version_budget():
+    out = srv.get_code_version()
+    assert len(out) <= 1500, f"get_code_version {len(out)} 字符，超出 1500 预算"
+
+
+# ---------------------------------------------------------------- 准确度约束
+def test_compact_keeps_package_series_header():
+    """约束 1：过滤后表头仍列全部固件库包与内核家族。"""
+    full = srv.list_libraries(compact=True)
+    filtered = srv.list_libraries(series="f5", compact=True)
+    header = full.splitlines()[1]
+    assert header in filtered, "按系列过滤后表头丢失了全量包/家族信息"
+    assert "覆盖" in header and "内核家族" in header
+
+
+def test_series_filter_narrows_packages():
+    out = srv.list_libraries(series="f5", compact=True)
+    assert "已按系列 'f5' 过滤" in out
+    assert "HT32_STD_5xxxx_FWLib" in out
+    assert "HT32F493x5_FWLib" not in out
+
+
+def test_unknown_series_lists_coverage():
+    out = srv.list_libraries(series="f9")
+    assert "不在覆盖范围" in out
+    assert "HT32_STD_5xxxx_FWLib" in out
+
+
+def test_module_filter_keeps_paths():
+    out = srv.list_libraries(module="gpio")
+    assert "gpio" in out
+    assert "raw/" in out, "module 过滤必须保留 raw 路径，否则 agent 只能猜路径"
+    assert "entities/libraries/gpio.md" in out
+
+
+def test_unknown_module_falls_back_to_all_names():
+    """约束 2：查不到时回退列全部模块名，避免 agent 误判模块不存在。"""
+    out = srv.list_libraries(module="uart")
+    assert "未找到模块 'uart'" in out
+    assert "可用模块" in out
+    assert "usart" in out
+
+
+def test_compact_has_path_hint():
+    """约束 3：compact 输出必须告诉 agent 怎么取路径。"""
+    out = srv.list_libraries(compact=True)
+    assert 'list_libraries(module="<模块名>")' in out

{ht32_code_mcp-0.5.1 → ht32_code_mcp-0.5.3}/tests/test_tools.py

@@ -679,13 +679,43 @@ def test_version_reports_skill_latest(monkeypatch):
 def test_usage_impl_version_pinned():
     """两仓库的 usage.py 是逐字节相同副本，实现版本号用于防止只改一边。"""
     from ht32_code_mcp import usage
-    assert usage._IMPL_VERSION == "1.3.0"
+    assert usage._IMPL_VERSION == "1.4.0"
     assert usage.SERVICE_CODE == "code"
     assert usage.SERVICE_WIKI == "wiki"
     # 噪声参数含 out_dir（code 特有：可能含用户本地路径）
     assert {"limit", "max_length", "out_dir"} <= usage.ARG_NOISE
 
 
+def test_usage_client_info_from_initialize():
+    """initialize 的 clientInfo 落到 client_name/client_version；缺失时不报错且为空串。"""
+    from types import SimpleNamespace
+
+    from fastmcp.server.middleware import MiddlewareContext
+
+    from ht32_code_mcp.usage import _client_info
+
+    def fake_ctx(**kwargs):
+        return MiddlewareContext(message=None, fastmcp_context=SimpleNamespace(**kwargs))
+
+    with_info = fake_ctx(
+        transport="streamable-http", session_id="s1", client_id=None,
+        session=SimpleNamespace(client_params=SimpleNamespace(
+            client_info=SimpleNamespace(name="Trae", version="3.4.15"))))
+    info = _client_info(with_info)
+    assert info["client_name"] == "Trae"
+    assert info["client_version"] == "3.4.15"
+
+    # 老客户端 / 现代协议未带 clientInfo：字段仍在，值为空串，且不抛错
+    for no_info in (
+        fake_ctx(transport="stdio", session_id="s2", client_id=None,
+                 session=SimpleNamespace(client_params=None)),
+        fake_ctx(transport="stdio", session_id="s3", client_id=None,
+                 session=SimpleNamespace(client_params=SimpleNamespace(client_info=None))),
+    ):
+        out = _client_info(no_info)
+        assert out["client_name"] == "" and out["client_version"] == ""
+
+
 def test_soft_failure_marker_semantics():
     """软失败判定口径 = 工具是否完成工作。
 
@@ -838,6 +868,9 @@ def test_usage_middleware_records_calls(tmp_path):
     assert ok_rec["duration_ms"] >= 0
     assert ok_rec["mcp_version"] == "0.1.4"
     assert ok_rec["kb_version"] == "v0.1.0"
+    # 客户端身份字段恒定存在（内存客户端可能未上报 clientInfo → 空串）
+    assert isinstance(ok_rec["client_name"], str)
+    assert isinstance(ok_rec["client_version"], str)
     assert fail_rec["tool"] == "boom" and fail_rec["ok"] is False
     assert "deliberate" in fail_rec["error"]
 

ht32_code_mcp-0.5.3/tests/test_version_file.py

@@ -0,0 +1,110 @@
+"""VERSION 文件格式门禁：固定 6 行，禁止回涨成变更日志。
+
+为什么需要这道门禁
+------------------
+`get_code_version` 会把 VERSION **全文**回显给 agent，VERSION 每多写一段变更说明，
+每次版本查询就多烧一份 token。历史上这份文件长成了「多版本并列 + run-on 变更史」
+（1.3 KB），靠人自觉守不住，用测试钉死格式。
+
+格式（见 AGENTS.md 核心规则 10）：
+    vX.Y.Z
+    Date: YYYY-MM-DD
+    Pages: N（可选括号细分）
+    Sources: <官方固件库包目录名> / ...      ← 与 raw/ 目录名一致
+    Components: <组件 id> <默认 tag> / ...   ← 与 .work/components/components.json 一致
+    MCP Server: X.Y.Z
+"""
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+
+import pytest
+
+from ht32_code_mcp import server as srv
+
+MAX_LINES = 6
+MAX_BYTES = 400
+MAX_LINE_CHARS = 120
+MAX_SOURCES_CHARS = 240   # 官方包全名较长，单独放宽
+
+_FIRST_LINE = re.compile(r"^v\d+\.\d+\.\d+$")
+_DATE_LINE = re.compile(r"^Date:\s*\d{4}-\d{2}-\d{2}$")
+_PAGES_LINE = re.compile(r"^Pages:\s*\d+")
+_SOURCES_LINE = re.compile(r"^Sources:\s*\S")
+_COMPONENTS_LINE = re.compile(r"^Components:\s*\S")
+_MCP_LINE = re.compile(r"^MCP Server:\s*(\d+\.\d+\.\d+)$")
+
+
+def _lines() -> list[str]:
+    text = (srv.CODE_ROOT / "VERSION").read_text(encoding="utf-8")
+    return [ln for ln in text.splitlines() if ln.strip()]
+
+
+def _segments(line: str) -> list[str]:
+    return [seg.strip() for seg in line.split(":", 1)[1].split(" / ") if seg.strip()]
+
+
+def test_version_file_line_count_and_size():
+    text = (srv.CODE_ROOT / "VERSION").read_text(encoding="utf-8")
+    lines = _lines()
+    assert len(lines) <= MAX_LINES, (
+        f"VERSION 最多 {MAX_LINES} 行，实际 {len(lines)} 行：{lines}\n"
+        "变更说明请写进 log.md，不要写进 VERSION")
+    assert len(text.encode("utf-8")) <= MAX_BYTES, (
+        f"VERSION 体积 {len(text.encode('utf-8'))} 字节，超过 {MAX_BYTES} 字节上限")
+    for line in lines:
+        limit = MAX_SOURCES_CHARS if line.startswith("Sources:") else MAX_LINE_CHARS
+        assert len(line) <= limit, f"VERSION 单行超过 {limit} 字符：{line}"
+
+
+def test_version_file_fields():
+    lines = _lines()
+    assert len(lines) == MAX_LINES, f"VERSION 应为 {MAX_LINES} 行，实际 {len(lines)} 行：{lines}"
+    assert _FIRST_LINE.match(lines[0]), f"首行必须是纯版本号（vX.Y.Z）：{lines[0]}"
+    assert _DATE_LINE.match(lines[1]), f"第 2 行必须是 'Date: YYYY-MM-DD'：{lines[1]}"
+    assert _PAGES_LINE.match(lines[2]), f"第 3 行必须是 'Pages: N'：{lines[2]}"
+    assert _SOURCES_LINE.match(lines[3]), (
+        f"第 4 行必须是 'Sources: <官方包目录名> / ...'：{lines[3]}")
+    assert _COMPONENTS_LINE.match(lines[4]), (
+        f"第 5 行必须是 'Components: <id> <tag> / ...'：{lines[4]}")
+    assert _MCP_LINE.match(lines[5]), (
+        f"末行必须是 'MCP Server: X.Y.Z'（只写版本号，不写 deployed/日期/变更说明）：{lines[5]}")
+
+
+def test_version_sources_are_real_raw_packages():
+    """Sources 的每一项必须是 raw/ 下真实存在的官方包目录，且包数与索引一致。"""
+    segments = _segments(_lines()[3])
+    raw = srv.CODE_ROOT / "raw"
+    for seg in segments:
+        assert (raw / seg).is_dir(), f"Sources 里的 '{seg}' 不是 raw/ 下的真实目录"
+    packages = srv.index.data.get("fwlibs", [])
+    assert len(segments) == len(packages), (
+        f"Sources 登记 {len(segments)} 个官方包，索引里有 {len(packages)} 个：{segments}")
+
+
+def test_version_components_match_catalog():
+    """Components 的每一项必须与私有组件登记表的 id + 默认 tag 一致。"""
+    catalog_path = srv.CODE_ROOT / ".work" / "components" / "components.json"
+    if not catalog_path.is_file():
+        pytest.skip("未配置私有组件登记表")
+    catalog = json.loads(catalog_path.read_text(encoding="utf-8"))
+    expected = {c["id"]: c.get("default_tag", "") for c in catalog.get("components", [])}
+    actual = {}
+    for seg in _segments(_lines()[4]):
+        parts = seg.split()
+        assert len(parts) == 2, f"Components 项格式应为 '<id> <tag>'：{seg}"
+        actual[parts[0]] = parts[1]
+    assert actual == expected, f"Components {actual} 与登记表 {expected} 不一致"
+
+
+def test_version_mcp_line_matches_pyproject():
+    """VERSION 末行与 pyproject.toml 的 version 必须一致（发布流程的硬约束）。"""
+    pyproject = srv.CODE_ROOT / ".work" / "mcp-server" / "pyproject.toml"
+    with pyproject.open("rb") as fh:
+        pkg_version = tomllib.load(fh)["project"]["version"]
+    match = _MCP_LINE.match(_lines()[-1])
+    assert match, "VERSION 末行格式不对，无法比对 pyproject 版本"
+    assert match.group(1) == pkg_version, (
+        f"VERSION 末行 {match.group(1)} != pyproject.toml {pkg_version}")

{ht32_code_mcp-0.5.1 → ht32_code_mcp-0.5.3}/uv.lock

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

ht32_code_mcp-0.5.1/.pytest_base_final_run.log

@@ -1,4 +0,0 @@
-........................................................................ [ 93%]
-.....                                                                    [100%]
-77 passed in 271.49s (0:04:31)
-EXIT=0