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

{ht32_code_mcp-0.1.3 → ht32_code_mcp-0.2.0}/DEPLOY.md

@@ -290,9 +290,9 @@ uv lock && uv build && uv publish
 
 | # | 任务 | 说明 | 状态 |
 |---|------|------|------|
-| 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.1 | MCP 工具实现（7 检索/导出 + 1 反馈） | `.work/mcp-server/src/ht32_code_mcp/`（FastMCP） | ✅ |
+| 3.2 | 工具级测试 | `pytest` 42 用例全绿 | ✅ |
+| 3.3 | PyPI 发布（hatchling） | `ht32-code-mcp` 0.1.3（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 回退 | ✅ |

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

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

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

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

{ht32_code_mcp-0.1.3 → ht32_code_mcp-0.2.0}/src/ht32_code_mcp/server.py

@@ -21,7 +21,7 @@ from .exporter import (
 )
 from .index import CodeIndex, normalize_series
 from .knowledge import KnowledgeSearch
-from .usage import UsageMiddleware, record_feedback
+from .usage import SERVICE_CODE, UsageMiddleware, record_feedback, resolve_log_dir
 
 # 知识库根目录（ht32-code 仓库根；src/ht32_code_mcp → 上溯 4 级）
 DEFAULT_CODE_ROOT = Path(__file__).resolve().parents[4]
@@ -43,9 +43,11 @@ 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)
 
-# 用量日志与反馈目录（1Panel 挂载可写卷到 /app/logs）。为空则整体关闭——
-# 本地开发默认不落盘。注意：日志含 query 原文，勿提交进仓库。
-LOG_DIR = os.environ.get("CODE_LOG_DIR", "").strip()
+# 反馈与用量日志：FEEDBACK_ROOT（宿主机挂载的可写卷，与 wiki 同一套约定）
+# 下按服务名分子目录，本服务写 <FEEDBACK_ROOT>/code/。
+# 为空则整体关闭——本地开发默认不落盘。注意：日志含 query 原文，勿提交进仓库。
+FEEDBACK_ROOT = os.environ.get("FEEDBACK_ROOT", "").strip()
+LOG_DIR = resolve_log_dir(FEEDBACK_ROOT, SERVICE_CODE)
 
 index = CodeIndex(CODE_ROOT).load()
 knowledge = KnowledgeSearch(CODE_ROOT)
@@ -83,10 +85,11 @@ _INSTRUCTIONS = """HT32 代码知识库（函数库/例程/工程模板），当
 
 mcp = FastMCP("ht32-code", instructions=_INSTRUCTIONS)
 
-# 用量日志：服务端自动记录所有工具调用（CODE_LOG_DIR 为空则不启用）
+# 用量日志：服务端自动记录所有工具调用（FEEDBACK_ROOT 为空则不启用）
 if LOG_DIR:
     mcp.add_middleware(UsageMiddleware(
-        LOG_DIR, mcp_version=_MCP_VERSION, code_version=index.data.get("code_version", "")))
+        LOG_DIR, SERVICE_CODE,
+        mcp_version=_MCP_VERSION, kb_version=index.data.get("code_version", "")))
 
 
 # ================================================================ MCP Tools
@@ -118,8 +121,8 @@ def get_code_version() -> str:
         ("云端 zip 下载：启用（TTL "
          f"{BUNDLE_TTL}s，{BUNDLE_BASE_URL}）" if CLOUD_BUNDLE
          else "云端 zip 下载：未配置（本地目录模式，export 需提供 out_dir）"),
-        (f"用量日志：启用（{LOG_DIR}）" if LOG_DIR
-         else "用量日志：未配置（CODE_LOG_DIR 为空，不落盘）"),
+        (f"反馈与用量日志：启用（{LOG_DIR}）" if LOG_DIR
+         else "反馈与用量日志：未配置（FEEDBACK_ROOT 为空，不落盘）"),
         "",
         "VERSION 文件内容：",
         version_text,
@@ -403,6 +406,7 @@ def submit_feedback(
 
     path = record_feedback(
         LOG_DIR,
+        SERVICE_CODE,
         question=question,
         issue_type=issue_type,
         answer=answer,
@@ -411,10 +415,10 @@ def submit_feedback(
         model_id=model_id,
         tools_called=tools_called,
         mcp_version=_MCP_VERSION,
-        code_version=index.data.get("code_version", ""),
+        kb_version=index.data.get("code_version", ""),
     )
     if path is None:
-        return ("错误：反馈未能写入。服务端可能未配置 CODE_LOG_DIR，"
+        return ("错误：反馈未能写入。服务端可能未配置 FEEDBACK_ROOT，"
                 "或该目录不可写——请联系管理员。")
     return f"反馈已记录，感谢！问题类型：{issue_type}，文件：{path.name}"
 

{ht32_code_mcp-0.1.3 → ht32_code_mcp-0.2.0}/src/ht32_code_mcp/usage.py

@@ -1,16 +1,31 @@
-"""用量日志与反馈落盘。
+"""反馈与用量日志：统一实现（ht32-wiki-mcp / ht32-code-mcp 共用同一份代码）。
 
-两条采集通道，写入同一目录、按 UTC 日期分文件（JSON Lines）：
+> **本文件在两个仓库存有逐字节相同的副本**（`ht32-wiki` 与 `ht32-code` 各一份）。
+> 修改时**必须同步另一仓库的同名文件**，并同步更新下方的 `_IMPL_VERSION`；
+> 两仓各有一条测试校验该版本号与目录布局，防止只改一边造成漂移。
 
-- **tool_call**（服务端自动，`UsageMiddleware` 拦截所有工具调用）：
+两条采集通道，写入同一目录树：
+
+- **tool_call**（`UsageMiddleware`，服务端自动）：拦截所有工具调用，
   记录工具名、参数原文、耗时、成败。不依赖 Agent 配合，数据完整。
-- **feedback**（Agent 主动，`submit_feedback` 工具）：
-  记录语义性问题（答错 / 知识库缺口 / 模板缺陷），中间件无法判断这些。
+- **feedback**（`record_feedback`，由各 server 的 `submit_feedback` 工具调用）：
+  记录 Agent 主动上报的语义性问题，middleware 无法判断这些。
+
+目录布局（同根 + 服务子目录）：
 
-目录由 `CODE_LOG_DIR` 指定，为空则整体关闭（本地开发默认关）。
+    <FEEDBACK_ROOT>/
+      ├─ wiki/
+      │   ├─ usage_YYYY-MM-DD.jsonl
+      │   └─ feedback_YYYY-MM-DD.jsonl
+      └─ code/
+          ├─ usage_YYYY-MM-DD.jsonl
+          └─ feedback_YYYY-MM-DD.jsonl
 
-隐私：参数按原文记录（`query` 可能含用户项目信息），故日志目录只应挂在
-受控服务器上，不要提交进仓库。
+两个服务挂同一个宿主机目录，各写自己的子目录——清理、备份、查看都是
+单一入口。每条记录另带 `service` 字段作双保险。
+
+隐私：参数按原文记录（`query` / `question` 可能含用户项目信息），目录只应
+挂在受控服务器上，不要提交进仓库。
 """
 from __future__ import annotations
 
@@ -22,8 +37,15 @@ from typing import Any
 
 from fastmcp.server.middleware import Middleware, MiddlewareContext
 
-# 不记录的参数：分页/长度控制项无分析价值；out_dir 可能含用户本地路径
-ARG_NOISE = frozenset({"max_length", "limit", "out_dir"})
+# 实现版本号：两仓库副本必须一致（各仓测试会校验，防止只改一边造成漂移）
+_IMPL_VERSION = "1.0.0"
+
+# 服务名 → 子目录名。新增服务在此登记。
+SERVICE_WIKI = "wiki"
+SERVICE_CODE = "code"
+
+# 不记录的工具参数：分页/长度控制项无分析价值；out_dir 可能含用户本地路径
+ARG_NOISE = frozenset({"limit", "max_length", "out_dir"})
 
 USAGE_PREFIX = "usage"
 FEEDBACK_PREFIX = "feedback"
@@ -33,6 +55,20 @@ def _now() -> str:
     return datetime.now(timezone.utc).isoformat()
 
 
+def resolve_log_dir(feedback_root: str, service: str) -> str:
+    """由反馈根目录 + 服务名算出该服务的日志目录。
+
+    feedback_root 为空时返回空字符串 = 关闭（本地开发默认不落盘）。
+    始终用 '/' 拼接（Windows 亦接受正斜杠），避免同一条配置在不同平台
+    产生不同字符串、影响日志路径的可比对性。
+    """
+    root = (feedback_root or "").strip().rstrip("/")
+    svc = (service or "").strip().strip("/")
+    if not root:
+        return ""
+    return f"{root}/{svc}" if svc else root
+
+
 def write_record(log_dir: str, prefix: str, record: dict[str, Any]) -> Path | None:
     """追加一条 JSONL 记录。log_dir 为空或写盘失败时返回 None（绝不因日志中断服务）。"""
     if not log_dir:
@@ -67,10 +103,12 @@ def _client_info(context: MiddlewareContext) -> dict[str, str]:
 class UsageMiddleware(Middleware):
     """把所有工具调用落成 JSONL（服务端自动采集）。"""
 
-    def __init__(self, log_dir: str, mcp_version: str = "", code_version: str = "") -> None:
+    def __init__(self, log_dir: str, service: str,
+                 mcp_version: str = "", kb_version: str = "") -> None:
         self.log_dir = log_dir
+        self.service = service
         self.mcp_version = mcp_version
-        self.code_version = code_version
+        self.kb_version = kb_version
 
     async def on_call_tool(self, context: MiddlewareContext, call_next):
         if not self.log_dir:
@@ -95,13 +133,14 @@ class UsageMiddleware(Middleware):
             record = {
                 "timestamp": _now(),
                 "kind": "tool_call",
+                "service": self.service,
                 "tool": context.message.name,
                 "args": recorded,
                 "ok": ok,
                 "duration_ms": round((time.perf_counter() - started) * 1000),
                 "error": error,
                 "mcp_version": self.mcp_version,
-                "code_version": self.code_version,
+                "kb_version": self.kb_version,
                 **_client_info(context),
             }
             write_record(self.log_dir, USAGE_PREFIX, record)
@@ -109,6 +148,7 @@ class UsageMiddleware(Middleware):
 
 def record_feedback(
     log_dir: str,
+    service: str,
     *,
     question: str,
     issue_type: str,
@@ -118,12 +158,13 @@ def record_feedback(
     model_id: str = "",
     tools_called: list[str] | None = None,
     mcp_version: str = "",
-    code_version: str = "",
+    kb_version: str = "",
 ) -> Path | None:
     """记录一条 Agent 主动提交的反馈。"""
     record = {
         "timestamp": _now(),
         "kind": "feedback",
+        "service": service,
         "question": question.strip(),
         "issue_type": issue_type,
         "answer": answer.strip(),
@@ -133,6 +174,6 @@ def record_feedback(
         # 过滤 submit_feedback 自身，只保留查询类工具
         "tools_called": [t for t in (tools_called or []) if t and t != "submit_feedback"],
         "mcp_version": mcp_version,
-        "code_version": code_version,
+        "kb_version": kb_version,
     }
     return write_record(log_dir, FEEDBACK_PREFIX, record)

{ht32_code_mcp-0.1.3 → ht32_code_mcp-0.2.0}/tests/test_tools.py

@@ -304,6 +304,25 @@ def test_version_reports_bundle_mode(monkeypatch):
 
 
 # ---------------------------------------------------------------- 反馈与用量日志
+def test_usage_impl_version_pinned():
+    """两仓库的 usage.py 是逐字节相同副本，实现版本号用于防止只改一边。"""
+    from ht32_code_mcp import usage
+    assert usage._IMPL_VERSION == "1.0.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_resolve_log_dir_layout():
+    from ht32_code_mcp.usage import resolve_log_dir
+    # 同根 + 服务子目录
+    assert resolve_log_dir("/app/feedback", "code") == "/app/feedback/code"
+    assert resolve_log_dir("/app/feedback/", "code") == "/app/feedback/code"
+    # 根未配置 = 关闭
+    assert resolve_log_dir("", "code") == ""
+
+
 def test_submit_feedback_writes_jsonl(tmp_path, monkeypatch):
     monkeypatch.setattr(srv, "LOG_DIR", str(tmp_path / "logs"))
     out = srv.submit_feedback(
@@ -319,12 +338,13 @@ def test_submit_feedback_writes_jsonl(tmp_path, monkeypatch):
     f = next((tmp_path / "logs").glob("feedback_*.jsonl"))
     rec = json.loads(f.read_text(encoding="utf-8").splitlines()[0])
     assert rec["kind"] == "feedback"
+    assert rec["service"] == "code"
     assert rec["question"] == "HT32F52352 怎么配 GPIO 输出？"
     assert rec["issue_type"] == "wrong_api"
     assert rec["model_id"] == "deepseek-v4-flash"
     # submit_feedback 自身被过滤，只留查询类工具
     assert rec["tools_called"] == ["search_code_knowledge", "get_file"]
-    assert rec["mcp_version"] and rec["code_version"]
+    assert rec["mcp_version"] and rec["kb_version"]
 
 
 def test_submit_feedback_empty_question(tmp_path, monkeypatch):
@@ -336,14 +356,14 @@ def test_submit_feedback_empty_question(tmp_path, monkeypatch):
 def test_submit_feedback_without_log_dir(monkeypatch):
     monkeypatch.setattr(srv, "LOG_DIR", "")
     out = srv.submit_feedback(question="x")
-    assert "错误" in out and "CODE_LOG_DIR" in out
+    assert "错误" in out and "FEEDBACK_ROOT" in out
 
 
 def test_version_reports_log_mode(monkeypatch):
     monkeypatch.setattr(srv, "LOG_DIR", "")
-    assert "用量日志：未配置" in srv.get_code_version()
-    monkeypatch.setattr(srv, "LOG_DIR", "/app/logs")
-    assert "用量日志：启用（/app/logs）" in srv.get_code_version()
+    assert "反馈与用量日志：未配置" in srv.get_code_version()
+    monkeypatch.setattr(srv, "LOG_DIR", "/app/feedback/code")
+    assert "反馈与用量日志：启用（/app/feedback/code）" in srv.get_code_version()
 
 
 def test_usage_middleware_records_calls(tmp_path):
@@ -353,8 +373,8 @@ def test_usage_middleware_records_calls(tmp_path):
     from fastmcp import Client, FastMCP
 
     app = FastMCP("mw-test")
-    app.add_middleware(UsageMiddleware(str(tmp_path / "logs"),
-                                       mcp_version="0.1.3", code_version="v0.1.0"))
+    app.add_middleware(UsageMiddleware(str(tmp_path / "logs"), "code",
+                                       mcp_version="0.1.4", kb_version="v0.1.0"))
 
     @app.tool()
     def probe(chip: str, limit: int = 5, out_dir: str = "") -> str:
@@ -378,11 +398,13 @@ def test_usage_middleware_records_calls(tmp_path):
     assert len(recs) == 2
     ok_rec, fail_rec = recs
     assert ok_rec["kind"] == "tool_call" and ok_rec["tool"] == "probe"
+    assert ok_rec["service"] == "code"
     # limit / out_dir 属噪声被剔除，业务参数保留
     assert ok_rec["args"] == {"chip": "HT32F52352"}
     assert ok_rec["ok"] is True and ok_rec["error"] == ""
     assert ok_rec["duration_ms"] >= 0
-    assert ok_rec["mcp_version"] == "0.1.3"
+    assert ok_rec["mcp_version"] == "0.1.4"
+    assert ok_rec["kb_version"] == "v0.1.0"
     assert fail_rec["tool"] == "boom" and fail_rec["ok"] is False
     assert "deliberate" in fail_rec["error"]
 
@@ -393,7 +415,7 @@ def test_usage_log_disabled_and_resilient(tmp_path):
 
     from fastmcp import Client, FastMCP
 
-    from ht32_code_mcp.usage import UsageMiddleware, write_record
+    from ht32_code_mcp.usage import write_record
 
     assert write_record("", "usage", {"x": 1}) is None
 
@@ -401,7 +423,7 @@ def test_usage_log_disabled_and_resilient(tmp_path):
     blocker = tmp_path / "blocker"
     blocker.write_text("i am a file", encoding="utf-8")
     app = FastMCP("mw-bad")
-    app.add_middleware(UsageMiddleware(str(blocker / "logs")))
+    app.add_middleware(UsageMiddleware(str(blocker / "logs"), "code"))
 
     @app.tool()
     def probe() -> str:

{ht32_code_mcp-0.1.3 → ht32_code_mcp-0.2.0}/uv.lock

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