ht32-code-mcp 0.5.2__tar.gz → 0.5.4__tar.gz

{ht32_code_mcp-0.5.2 → ht32_code_mcp-0.5.4}/PKG-INFO

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

{ht32_code_mcp-0.5.2 → ht32_code_mcp-0.5.4}/pyproject.toml

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

{ht32_code_mcp-0.5.2 → ht32_code_mcp-0.5.4}/src/ht32_code_mcp/server.py

@@ -132,13 +132,20 @@ try:
 except PackageNotFoundError:
     _MCP_VERSION = "unknown (开发模式)"
 
-_INSTRUCTIONS = """HT32 代码知识库（函数库/例程/工程模板），当前覆盖 7 个官方固件库包：
+_INSTRUCTIONS = """## 入口前置（最高优先）
+本服务是 ht32 编排 Skill 的知识后端。凡涉及 HT32 开发任务（写码/建工程/编译/烧录/调试/排障），
+先调用宿主 Skill `ht32`，由它决定调用顺序与本地执行；不要用本服务工具自行拼流程。
+仅纯知识查询（查 API/例程/规格）可直接使用本服务。
+若宿主未安装 ht32 Skill，提示用户按 ht32-skills README 安装后再继续。
+
+HT32 代码知识库（函数库/例程/工程模板），当前覆盖 7 个官方固件库包：
 M0+（HT32F5 / L5）、M3（HT32F1 / F175x-275x）、M4（F490x1 / F491x3 / F493x5）。
 写 HT32 代码必须基于本库真实函数库知识，不要编造 API/宏/路径。
 
 ## 按需求选工具
 - 确认版本/覆盖范围 → 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 +311,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 +373,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.4/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.4/tests/test_version_file.py

@@ -0,0 +1,148 @@
+"""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}")
+
+
+def test_release_version_pins_match():
+    """发布版本四处必须一致：pyproject / VERSION 末行 / Dockerfile ARG / compose 镜像 tag。
+
+    历史问题：0.5.3 发布时只改了 pyproject 与 VERSION，Dockerfile 与 compose 仍钉在
+    0.5.2，线上容器装的是旧包，`get_code_version` 头部与 VERSION 回显不一致。
+    """
+    pyproject = srv.CODE_ROOT / ".work" / "mcp-server" / "pyproject.toml"
+    with pyproject.open("rb") as fh:
+        pyproject_version = tomllib.load(fh)["project"]["version"]
+
+    match = _MCP_LINE.match(_lines()[-1])
+    assert match, "VERSION 末行格式不对，无法比对版本"
+    version_line = match.group(1)
+
+    dockerfile = srv.CODE_ROOT / ".work" / "docker" / "Dockerfile"
+    docker_match = re.search(
+        r"^ARG\s+HT32_CODE_MCP_VERSION=(\d+\.\d+\.\d+)\s*$",
+        dockerfile.read_text(encoding="utf-8"), re.MULTILINE)
+    assert docker_match, "Dockerfile 缺少 'ARG HT32_CODE_MCP_VERSION=X.Y.Z'"
+    docker_version = docker_match.group(1)
+
+    compose = srv.CODE_ROOT / ".work" / "docker" / "docker-compose.yml"
+    compose_match = re.search(
+        r"image:\s*ht32-code-mcp:(\d+\.\d+\.\d+)",
+        compose.read_text(encoding="utf-8"))
+    assert compose_match, "docker-compose.yml 缺少 'image: ht32-code-mcp:X.Y.Z'"
+    compose_version = compose_match.group(1)
+
+    versions = {
+        "pyproject.toml": pyproject_version,
+        "VERSION": version_line,
+        "Dockerfile": docker_version,
+        "docker-compose.yml": compose_version,
+    }
+    assert len(set(versions.values())) == 1, (
+        "发布版本四处必须一致，当前：" + ", ".join(f"{k}={v}" for k, v in versions.items()))

{ht32_code_mcp-0.5.2 → ht32_code_mcp-0.5.4}/uv.lock

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