ht32-code-mcp 0.4.1__tar.gz → 0.4.3__tar.gz

{ht32_code_mcp-0.4.1 → ht32_code_mcp-0.4.3}/PKG-INFO

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

{ht32_code_mcp-0.4.1 → ht32_code_mcp-0.4.3}/pyproject.toml

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

{ht32_code_mcp-0.4.1 → ht32_code_mcp-0.4.3}/src/ht32_code_mcp/materializer.py

@@ -95,6 +95,28 @@ def pack_release_version(pack_path: Path) -> str:
     return m.group(1).decode()
 
 
+def pack_device_algorithm(pack_path: Path, device: str) -> str | None:
+    """DFP pdsc 中该 device 的首个 Flash 算法路径（如 `Flash/HT32F490x1_64.FLM`）。
+
+    只从随包 DFP 取，不按型号猜：M4 同一子系列不同容量用的是不同 FLM
+    （F49041=_64、F49031=_32；F49153=_128、F49163=_256；F49365=_256、F49395=_1024）。
+    """
+    try:
+        with zipfile.ZipFile(pack_path) as z:
+            names = [n for n in z.namelist() if n.lower().endswith(".pdsc")]
+            if not names:
+                return None
+            data = z.read(names[0]).decode("utf-8", errors="replace")
+    except zipfile.BadZipFile:
+        return None
+    m = re.search(r'<device[^>]*Dname="' + re.escape(device) + r'"[^>]*>(.*?)</device>',
+                  data, re.S)
+    if not m:
+        return None
+    alg = re.search(r'<algorithm[^>]*name="([^"]+\.FLM)"', m.group(1))
+    return alg.group(1) if alg else None
+
+
 # ------------------------------------------------------------------ recipe 装载
 def load_recipes(recipes_dir: Path) -> dict[str, dict]:
     recipes: dict[str, dict] = {}
@@ -752,12 +774,7 @@ class Materializer:
         # uvoptx（受控调试配置；M4 用官方侧车，f5 用净化后的用户侧车，l5/f1 不提供）
         uvoptx_src = self._controlled_uvoptx(r)
         if uvoptx_src is not None:
-            data = uvoptx_src.read_bytes()
-            data, n = re.subn(rb"(<TargetName>)[^<]*(</TargetName>)",
-                              lambda m: m.group(1) + stem.encode() + m.group(2), data, count=1)
-            if n == 1:
-                deviations.append(dict(kind="uvoptx-targetname", file=uvprojx.name,
-                                       reason="受控 .uvoptx 的 TargetName 与工程名同步"))
+            data = self._render_uvoptx(r, uvprojx, uvoptx_src, pack, stem, deviations)
             target = proj_dir / f"{stem}.uvoptx"
             target.write_bytes(data)
             manifest_files.append(dict(
@@ -884,6 +901,23 @@ class Materializer:
             if f"<{tag}>" in text:
                 text = rewrite_tag_value(text, tag, stem, what)
                 edits.append(f"{tag} -> {stem}")
+        # e2) 声明式 uvprojx 选项编辑（如 M4 统一 -O2；命中数必须精确）
+        for e in cfg.get("project_edits", []):
+            tag = e["tag"]
+            old = f"<{tag}>{e['old_value']}</{tag}>"
+            new = f"<{tag}>{e['new_value']}</{tag}>"
+            hits = text.count(old)
+            if hits != e["expected_matches"]:
+                raise ContractError(
+                    RECIPE_MISMATCH,
+                    f"{what}: <{tag}>{e['old_value']}</{tag}> 预期命中 "
+                    f"{e['expected_matches']} 次，实际 {hits}")
+            text = text.replace(old, new)
+            edits.append(f"{tag} {e['old_value']} -> {e['new_value']}")
+            deviations.append(dict(
+                kind="project-option-edit", file=f"{stem}.uvprojx", tag=tag,
+                old=e["old_value"], new=e["new_value"],
+                reason=e.get("reason") or "声明式项目选项编辑"))
         # f) PackID -> recipe 锁定版本（声明式）
         pack_id = r.recipe["pack"]["id"]
         if f"<PackID>{pack_id}</PackID>" not in text and "<PackID>" in text:
@@ -918,6 +952,92 @@ class Materializer:
             f"{r.series}-controlled.uvoptx"
         return asset if asset.is_file() else None
 
+    def _render_uvoptx(self, r: Resolved, uvprojx: Path, src: Path, pack: dict,
+                       stem: str, deviations: list[dict]) -> bytes:
+        """把受控 .uvoptx 渲染成该 config 的调试侧车。
+
+        受控资产只保留骨架与占位符；芯片相关值全部来自**已裁决的 recipe.memory +
+        随包 DFP 的 Flash 算法**，不按型号猜：
+        - device / FLM：`pack_device_algorithm()`（M4 同子系列不同容量 FLM 不同）；
+        - Flash 基址/容量：`memory.flash[0]`；
+        - SW-DP ID：M4=2BA01477，M0+/M3=0BC11477；
+        - ListingPath：与 uvprojx 同步（uVision 以 uvoptx 为准）；
+        - CMSIS_AGDI 注册项含 `-FO15`（Reset and Run），与 M0+ 对齐。
+        """
+        cfg = r.config
+        what = cfg["config_id"]
+        device = cfg["device"]
+        flash = cfg["memory"]["flash"][0]
+        flash_base = int(flash["base"], 16)
+        flash_size = int(flash["size"], 16)
+        uv_text = uvprojx.read_text(encoding="utf-8", errors="replace")
+        m = re.search(r"<ListingPath>([^<]*)</ListingPath>", uv_text)
+        if not m:
+            raise ContractError(RECIPE_MISMATCH, f"{what}: uvprojx 缺 <ListingPath>")
+        listing = m.group(1)
+        m4 = r.series in ("ht32f490x1", "ht32f491x3", "ht32f493x5")
+        ram_alg = "1000"
+        if m4:
+            alg = pack_device_algorithm(pack["asset"], device)
+            if not alg:
+                raise ContractError(
+                    RECIPE_MISMATCH,
+                    f"{what}: 随包 DFP 未给出 {device} 的 Flash 算法（pdsc 无 algorithm）")
+            flm_path = alg.replace("/", "\\")
+            flm_base = Path(alg).stem
+            cmsis = (
+                '-X"Any" -UAny -O206 -S0 -C0 -P00 -N00("ARM CoreSight SW-DP") '
+                '-D00(2BA01477) -L00(0) -TO18 -TC10000000 -TP20 -TDS8007 -TDT0 -TDC1F '
+                '-TIEFFFFFFFF -TIP8 -FO15 -FD20000000 '
+                f"-FC{ram_alg} -FN1 -FF0{flm_base}.FLM "
+                f"-FS0{flash_base:X} -FL0{flash_size:X} "
+                f"-FP0($$Device:{device}${flm_path})")
+            ul2 = (
+                f"UL2CM3(-S0 -C0 -P0 -FD20000000 -FC{ram_alg} -FN1 -FF0{flm_base} "
+                f"-FS0{flash_base:X} -FL0{flash_size:X} "
+                f"-FP0($$Device:{device}${flm_path}))")
+        else:
+            cmsis = (
+                '-X"Any" -UAny -O206 -S0 -C0 -P00 -N00("ARM CoreSight SW-DP") '
+                '-D00(0BC11477) -L00(0) -TO18 -TC1000000 -TP20 -TDS8007 -TDT0 -TDC1F '
+                '-TIEFFFFFFFF -TIP8 -FO15 -FD20000000 '
+                f"-FC{ram_alg} -FN2 -FF0HT32F.FLM "
+                f"-FS0{flash_base:X} -FL0{flash_size:X} "
+                f"-FP0($$Device:{device}$ARM\\Flash\\HT32F.FLM) "
+                "-FF1HT32F_OPT.FLM -FS11FF00000 -FL11000 "
+                f"-FP1($$Device:{device}$ARM\\Flash\\HT32F_OPT.FLM)")
+            ul2 = (
+                f"UL2CM3(-S0 -C0 -P0 -FD20000000 -FC{ram_alg} -FN2 -FF0HT32F "
+                f"-FS0{flash_base:X} -FL0{flash_size:X} "
+                "-FF1HT32F_OPT -FS11FF00000 -FL11000 "
+                f"-FP0($$Device:{device}$ARM\\Flash\\HT32F.FLM) "
+                f"-FP1($$Device:{device}$ARM\\Flash\\HT32F_OPT.FLM))")
+        data = src.read_bytes()
+        edits: list[str] = []
+        for token, value in (
+                (b"__HT32_LISTING__", listing),
+                (b"__HT32_CMSIS_AGDI_NAME__", cmsis),
+                (b"__HT32_UL2CM3_NAME__", ul2)):
+            hits = data.count(token)
+            if hits != 1:
+                raise ContractError(
+                    RECIPE_MISMATCH,
+                    f"{what}: 受控 uvoptx 占位符 {token.decode()} 预期 1 次，实际 {hits}")
+            data = data.replace(token, value.encode())
+            edits.append(f"{token.decode()} -> {value[:60]}...")
+        data, n = re.subn(rb"(<TargetName>)[^<]*(</TargetName>)",
+                          lambda mm: mm.group(1) + stem.encode() + mm.group(2),
+                          data, count=1)
+        if n == 1:
+            edits.append(f"TargetName -> {stem}")
+        if b"__HT32_" in data:
+            raise ContractError(RECIPE_MISMATCH, f"{what}: uvoptx 仍有未替换占位符")
+        deviations.append(dict(
+            kind="uvoptx-materialized", file=f"{stem}.uvoptx", edits=edits,
+            reason="受控 uvoptx 按 device/FLM/memory/uvprojx ListingPath 参数化"
+                   "（含 CMSIS_AGDI -FO15 = Reset and Run）"))
+        return data
+
     # ------------------------------------------------------------ manifest
     def _write_manifests(self, r: Resolved, mdir: Path, stem: str, files: list[dict],
                          deviations: list[dict], notes: list[str], total_bytes: int,

{ht32_code_mcp-0.4.1 → ht32_code_mcp-0.4.3}/src/ht32_code_mcp/server.py

@@ -98,7 +98,8 @@ M0+（HT32F5 / L5）、M3（HT32F1 / F175x-275x）、M4（F490x1 / F491x3 / F493
 - 知识库缺了用户需要的内容，你只能用推测回答
 - 导出工程有缺陷（编译失败、型号参数错、缺文件）
 - **ht32-skills（编排层：流程/脚本/模板/环境检测）本身有缺陷**，用 issue_type=skill_defect
-  上报（本渠道是 skill 问题的统一入口），details 里附 ht32-skills 版本号与现象
+  上报（本渠道是 skill 问题的统一入口），`skill_version` 传本机 `ht32.py version` 的版本号，
+  details 里附现象与日志路径
 务必附 model_id；submit_feedback 之外的调用已由服务端自动记入用量日志，无需你重复上报。
 """
 
@@ -561,6 +562,7 @@ def submit_feedback(
     details: str = "",
     model_id: str = "",
     tools_called: list[str] | None = None,
+    skill_version: str = "",
 ) -> str:
     """提交纠正反馈，改进 HT32 代码知识库 / ht32-skills 编排层。
 
@@ -576,9 +578,12 @@ def submit_feedback(
         issue_type: 问题类型，枚举上述其一（skill_defect = ht32-skills 编排层缺陷）
         answer: 你给出的回答原文
         correction: 你认为正确的信息或用户指出的正确内容
-        details: 补充上下文（如编译报错原文；skill_defect 请附 ht32-skills 版本号与现象）
+        details: 补充上下文（如编译报错原文、复现步骤、日志路径）
         model_id: 你的模型标识，如 deepseek-v4-flash
         tools_called: 本次调过的查询工具列表（不含 submit_feedback 自身）
+        skill_version: 本机 ht32-skills 版本，取 `ht32.py version` 的 skill_version
+            （如 "v0.1.19"）。服务端跨进程拿不到客户端 skill 版本，**skill_defect 必填**，
+            否则无从判断缺陷属于哪个版本
     """
     if not question or not question.strip():
         return "错误：question 参数不能为空，请提供用户原始需求。"
@@ -595,6 +600,7 @@ def submit_feedback(
         tools_called=tools_called,
         mcp_version=_MCP_VERSION,
         kb_version=index.data.get("code_version", ""),
+        skill_version=skill_version,
     )
     if path is None:
         return ("错误：反馈未能写入。服务端可能未配置 FEEDBACK_ROOT，"

{ht32_code_mcp-0.4.1 → ht32_code_mcp-0.4.3}/src/ht32_code_mcp/usage.py

@@ -9,7 +9,8 @@
 - **tool_call**（`UsageMiddleware`，服务端自动）：拦截所有工具调用，
   记录工具名、参数原文、耗时、成败。不依赖 Agent 配合，数据完整。
 - **feedback**（`record_feedback`，由各 server 的 `submit_feedback` 工具调用）：
-  记录 Agent 主动上报的语义性问题，middleware 无法判断这些。
+  记录 Agent 主动上报的语义性问题，middleware 无法判断这些。其中 `skill_version`
+  由 Agent 自报（服务端跨进程拿不到客户端 skill 版本），用于定位 ht32-skills 缺陷版本。
 
 目录布局（同根 + 服务子目录）：
 
@@ -38,7 +39,7 @@ from typing import Any
 from fastmcp.server.middleware import Middleware, MiddlewareContext
 
 # 实现版本号：两仓库副本必须一致（各仓测试会校验，防止只改一边造成漂移）
-_IMPL_VERSION = "1.1.0"
+_IMPL_VERSION = "1.2.0"
 
 # 服务名 → 子目录名。新增服务在此登记。
 SERVICE_WIKI = "wiki"
@@ -203,6 +204,7 @@ def record_feedback(
     tools_called: list[str] | None = None,
     mcp_version: str = "",
     kb_version: str = "",
+    skill_version: str = "",
 ) -> Path | None:
     """记录一条 Agent 主动提交的反馈。"""
     record = {
@@ -219,5 +221,6 @@ def record_feedback(
         "tools_called": [t for t in (tools_called or []) if t and t != "submit_feedback"],
         "mcp_version": mcp_version,
         "kb_version": kb_version,
+        "skill_version": skill_version.strip(),
     }
     return write_record(log_dir, FEEDBACK_PREFIX, record)

ht32_code_mcp-0.4.3/tests/test_recipe_claims.py

@@ -0,0 +1,92 @@
+"""回归测试：retarget 串口声明（uart_pin_claims）的文案与真实头文件/宏一致。
+
+两个已实测的缺陷（都在 build_recipes.py 的 com1_claim() 里把宏名直接拼字符串）：
+1. 版级头文件名：README 写 `per utilities/HT32_Board/ht32f50241-sk.h`，实际文件是
+   `ht32f50241_sk.h`（板名 id 用连字符、头文件名用下划线）。从 recipe 数据侧兜底：
+   每条 claim 里的头文件名都必须能在官方包 `utilities/HT32_Board/` 下找到。
+2. 引脚宏粘连：README 写 `TX=GPIO_PAAFIO_PIN_4`，实际是「端口宏 GPIO_PA + 引脚宏
+   AFIO_PIN_4」两个独立宏，应为 `TX=GPIO_PA/AFIO_PIN_4`。
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[3]  # tests -> mcp-server -> .work -> ht32-code
+RECIPES = REPO / ".work" / "template-recipes" / "recipes"
+CLAIM_HEADER = re.compile(r"utilities/HT32_Board/([^)\s]+\.h)")
+# 引脚 = 端口宏 GPIO_Px + 引脚宏 AFIO_PIN_n，中间必须有一个 '/'
+CLAIM_PIN = re.compile(r"GPIO_P[A-H]?/AFIO_PIN_\d+")
+CLAIM_PIN_VALUE = re.compile(r"(?:TX|RX)=([^\s,)]+)")
+
+
+def _recipes() -> list[dict]:
+    return [json.loads(p.read_text(encoding="utf-8")) for p in sorted(RECIPES.glob("*.json"))]
+
+
+def test_claim_board_headers_exist_in_official_package():
+    missing: list[str] = []
+    checked = 0
+    for recipe in _recipes():
+        for cfg in recipe["configs"]:
+            for claim in (cfg.get("retarget") or {}).get("uart_pin_claims") or []:
+                m = CLAIM_HEADER.search(claim)
+                if not m:
+                    continue
+                checked += 1
+                header = REPO / "raw" / cfg["origin"]["package"] / "utilities" / "HT32_Board" / m.group(1)
+                if not header.is_file():
+                    missing.append(f"{cfg['config_id']}: {m.group(1)}")
+    assert checked > 0, "recipe 里没有可校验的板级头文件声明"
+    assert not missing, "claim 引用了不存在的板级头文件：\n" + "\n".join(missing)
+
+
+def test_claim_board_headers_use_real_file_names_not_board_ids():
+    """板名 id（连字符）不能直接当文件名；下划线才是官方文件名的分隔符。"""
+    wrong: list[str] = []
+    for recipe in _recipes():
+        for cfg in recipe["configs"]:
+            for claim in (cfg.get("retarget") or {}).get("uart_pin_claims") or []:
+                m = CLAIM_HEADER.search(claim)
+                if m and ("-sk.h" in m.group(1) or "-dvb.h" in m.group(1)):
+                    wrong.append(f"{cfg['config_id']}: {m.group(1)}")
+    assert not wrong, "claim 头文件名仍用板名 id 的连字符：\n" + "\n".join(wrong)
+
+
+def test_claim_pins_use_port_macro_slash_pin_macro():
+    """7 份 recipe 的 TX=/RX= 引脚都必须是 GPIO_Px/AFIO_PIN_n 形态。
+
+    端口宏（GPIO_PA）与引脚宏（AFIO_PIN_4）是两个独立宏；拼成 GPIO_PAAFIO_PIN_4
+    会被用户当成宏名照抄，编译不过。
+    """
+    bad: list[str] = []
+    checked = 0
+    for recipe in _recipes():
+        for cfg in recipe["configs"]:
+            for claim in (cfg.get("retarget") or {}).get("uart_pin_claims") or []:
+                for m in CLAIM_PIN_VALUE.finditer(claim):
+                    checked += 1
+                    if not CLAIM_PIN.fullmatch(m.group(1)):
+                        bad.append(f"{cfg['config_id']}: {m.group(0)}  <- {claim}")
+    assert checked >= 80, f"recipe 里可校验的 TX/RX 引脚过少（{checked}），疑似数据缺失"
+    assert not bad, ("claim 引脚宏形态不对（应为 GPIO_Px/AFIO_PIN_n，不能写成 "
+                     "GPIO_PAAFIO_PIN_n）：\n" + "\n".join(bad))
+
+
+def test_exported_readme_points_at_real_board_header(tmp_path):
+    """导出工程 README 的串口占用应指向真实板级头文件（下划线）、引脚宏用 '/' 分隔。"""
+    from ht32_code_mcp import server as srv
+
+    out = tmp_path / "bundle_f50241"
+    text = srv.export_project_bundle("HT32F50241", str(out))
+    assert "导出失败" not in text, text
+    readme = (out / "README.md").read_text(encoding="utf-8")
+    assert "ht32f50241_sk.h" in readme, readme
+    assert "ht32f50241-sk.h" not in readme, readme
+    # README「占用」行必须给出 GPIO_PA/AFIO_PIN_4（板级头：TX=PA4 / RX=PA5）
+    claim_line = next((ln for ln in readme.splitlines() if "占用" in ln), "")
+    assert "TX=GPIO_PA/AFIO_PIN_4" in claim_line, claim_line
+    assert "RX=GPIO_PA/AFIO_PIN_5" in claim_line, claim_line
+    assert "GPIO_PAAFIO" not in readme, readme
+

{ht32_code_mcp-0.4.1 → ht32_code_mcp-0.4.3}/tests/test_tools.py

@@ -478,6 +478,55 @@ def test_export_target_name_custom(tmp_path):
     assert (out / "README.md").read_text(encoding="utf-8").startswith("# F52352_UART_Printf")
 
 
+@pytest.mark.parametrize("config_id,device,flm", [
+    ("ht32f49041-20tssop.ht32f49041-sk.ac5.hick-safe.retarget",
+     "HT32F49041_20TSSOP", "HT32F490x1_64"),
+    ("ht32f49153-48lqfp.ht32f49163-sk.ac5.hick-safe.retarget",
+     "HT32F49153_48LQFP", "HT32F491x3_128"),
+    ("ht32f49365-64lqfp.ht32f49395-sk.ac5.hick-safe.retarget",
+     "HT32F49365_64LQFP", "HT32F493x5_256"),
+])
+def test_export_m4_debug_options_and_optimization(tmp_path, config_id, device, flm):
+    """M4：-O2、CMSIS_AGDI（-FO15）、FLM/device 按芯片参数化、ListingPath 同步。"""
+    out = tmp_path / config_id.split(".")[0]
+    srv.exporter.export_dir(out_dir=str(out), project_name="verify_proj", config_id=config_id)
+    uv = next((out / "project" / "MDK_ARMv5").glob("*.uvprojx"))
+    text = uv.read_text(encoding="utf-8")
+    assert "<Optim>3</Optim>" in text
+    listing = re.search(r"<ListingPath>([^<]*)</ListingPath>", text).group(1)
+    side = uv.with_suffix(".uvoptx")
+    side_text = side.read_text(encoding="utf-8")
+    assert "<Key>CMSIS_AGDI</Key>" in side_text
+    assert "<Key>UL2CM3</Key>" in side_text
+    assert "-FO15" in side_text
+    assert re.search(r"<ListingPath>" + re.escape(listing) + "</ListingPath>", side_text)
+    assert f"$$Device:{device}$" in side_text
+    assert flm in side_text
+    dev = json.loads((out / "manifest" / "deviations.json").read_text(encoding="utf-8"))
+    kinds = [d["kind"] for d in dev["deviations"]]
+    assert "project-option-edit" in kinds
+    assert "uvoptx-materialized" in kinds
+
+
+def test_export_m0_debug_sidecar_is_parameterized(tmp_path):
+    """M0+：uvoptx 的 device/Flash 容量与 uvprojx ListingPath 同步（不再固定 F52352）。"""
+    out = tmp_path / "f50030"
+    srv.exporter.export_dir(
+        out_dir=str(out), project_name="verify_proj",
+        config_id="ht32f50030.ht32f50030-sk.ac5.hsi-safe.retarget")
+    uv = next((out / "project" / "MDK_ARMv5").glob("*.uvprojx"))
+    text = uv.read_text(encoding="utf-8")
+    listing = re.search(r"<ListingPath>([^<]*)</ListingPath>", text).group(1)
+    output_dir = re.search(r"<OutputDirectory>([^<]*)</OutputDirectory>", text).group(1)
+    # obj 与 list 是同一芯片目录下的两个并列子目录；list 不得再落回工程根 .\List\
+    assert "HT32\\50030\\Obj\\" in output_dir
+    assert "HT32\\50030\\List\\" in listing
+    side_text = uv.with_suffix(".uvoptx").read_text(encoding="utf-8")
+    assert re.search(r"<ListingPath>" + re.escape(listing) + "</ListingPath>", side_text)
+    assert "$$Device:HT32F50030$" in side_text
+    assert "$$Device:HT32F52352$" not in side_text
+
+
 def test_export_unknown_chip(tmp_path):
     result = srv.export_project_bundle("HT32F99999", str(tmp_path / "nope"))
     assert "UNKNOWN_DEVICE" in result and "不在契约" in result
@@ -628,7 +677,7 @@ 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.1.0"
+    assert usage._IMPL_VERSION == "1.2.0"
     assert usage.SERVICE_CODE == "code"
     assert usage.SERVICE_WIKI == "wiki"
     # 噪声参数含 out_dir（code 特有：可能含用户本地路径）
@@ -686,6 +735,7 @@ def test_submit_feedback_writes_jsonl(tmp_path, monkeypatch):
         details="编译报错 too few arguments",
         model_id="deepseek-v4-flash",
         tools_called=["search_code_knowledge", "submit_feedback", "get_file"],
+        skill_version="v0.1.19",
     )
     assert "反馈已记录" in out
     f = next((tmp_path / "logs").glob("feedback_*.jsonl"))
@@ -698,6 +748,8 @@ def test_submit_feedback_writes_jsonl(tmp_path, monkeypatch):
     # submit_feedback 自身被过滤，只留查询类工具
     assert rec["tools_called"] == ["search_code_knowledge", "get_file"]
     assert rec["mcp_version"] and rec["kb_version"]
+    # 客户端 skill 版本是结构化字段（不再靠 details 散文），未传时为空串而非缺键
+    assert rec["skill_version"] == "v0.1.19"
 
 
 def test_submit_feedback_accepts_skill_defect(tmp_path, monkeypatch):
@@ -708,11 +760,22 @@ def test_submit_feedback_accepts_skill_defect(tmp_path, monkeypatch):
         issue_type="skill_defect",
         details="ht32-skills v0.1.0；导出后 uvprojx 未按工程名重命名",
         model_id="deepseek-v4-flash",
+        skill_version="v0.1.0",
     )
     assert "skill_defect" in out
     f = next((tmp_path / "logs").glob("feedback_*.jsonl"))
     rec = json.loads(f.read_text(encoding="utf-8").splitlines()[0])
     assert rec["issue_type"] == "skill_defect"
+    assert rec["skill_version"] == "v0.1.0"
+
+
+def test_feedback_skill_version_key_always_present(tmp_path, monkeypatch):
+    """没传 skill_version 时字段仍存在（空串），日志消费方不必分支判键。"""
+    monkeypatch.setattr(srv, "LOG_DIR", str(tmp_path / "logs"))
+    srv.submit_feedback(question="x", issue_type="other")
+    f = next((tmp_path / "logs").glob("feedback_*.jsonl"))
+    rec = json.loads(f.read_text(encoding="utf-8").splitlines()[0])
+    assert rec["skill_version"] == ""
 
 
 def test_submit_feedback_empty_question(tmp_path, monkeypatch):

{ht32_code_mcp-0.4.1 → ht32_code_mcp-0.4.3}/uv.lock

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