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

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

@@ -174,46 +174,61 @@ docker exec 1Panel-openresty-ih7J nginx -t
 
 4. 确认 `ls /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles` 只有 `*.zip`（无残留临时目录）。
 
-## 反馈与用量日志（P1-5，0.1.3+）
+## 反馈与用量日志（P1-5，0.2.0+）
 
-两条通道写入同一目录、按 UTC 日期分文件（JSON Lines）：
+> **与 ht32-wiki-mcp 统一**：两服务使用同一套实现（`usage.py`，两仓库逐字节
+> 相同的副本）、同一套目录约定（同根 + 服务子目录）、同一套字段。
+> 本服务写 `<FEEDBACK_ROOT>/code/`，wiki 写 `<FEEDBACK_ROOT>/wiki/`。
 
-| 通道 | 触发 | 记录内容 |
-|------|------|----------|
-| `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` |
+两条通道，按 UTC 日期分文件（JSON Lines）：
+
+| 通道 | 文件 | 触发 | 记录内容 |
+|------|------|------|----------|
+| 用量日志 | `usage_*.jsonl` | **服务端自动**（middleware 拦截所有工具调用） | 工具名、参数原文（剔除 `limit`/`max_length`/`out_dir`）、耗时、成败、错误、客户端 session |
+| 反馈 | `feedback_*.jsonl` | **Agent 主动**（`submit_feedback` 工具） | 语义性问题：API 错 / 缺口 / 路径错 / 模板缺陷 |
 
-自动通道保证调用事实完整（不依赖 Agent 配合）；反馈通道补 middleware
-判断不了的语义问题。`issue_type` 枚举：`wrong_api` / `missing_info` /
-`wrong_path` / `export_defect` / `unclear` / `other`。
+自动通道保证调用事实完整（不依赖 Agent 配合），用于追踪用户需求与生成的模板；
+反馈通道补 middleware 判断不了的语义问题。每条记录都带 `service` 字段
+（`code`），便于两服务日志合并分析。
+
+### 目录布局
+
+```
+/opt/ht32-mcp-feedback/          ← 宿主机单一入口，两个容器挂同一卷
+  ├─ wiki/                       ← ht32-wiki 容器写这里
+  └─ code/                       ← ht32-code 容器写这里（本服务）
+      ├─ usage_2026-09-21.jsonl
+      └─ feedback_2026-09-21.jsonl
+```
 
 ### 环境变量
 
 | 变量 | 默认 | 说明 |
 |------|------|------|
-| `CODE_LOG_DIR` | 空（= **整体关闭**，本地开发默认不落盘） | 日志写入目录，须可写 |
+| `FEEDBACK_ROOT` | 空（= **关闭**，本地开发默认不落盘） | 日志根目录，服务名子目录自动拼接 |
+| `CODE_LOG_DIR` | — | 已废弃，改用 `FEEDBACK_ROOT` |
 
-> **隐私**：参数按原文记录，`query`/`question` 可能含用户项目信息。
+> **隐私**：参数按原文记录，`query` / `question` 可能含用户项目信息。
 > 该目录只应挂在受控服务器上，**不要提交进仓库**（定时脚本是
 > `git reset --hard` 镜像模式，写进仓库也会被覆盖丢失）。
 
-### 服务器侧落地（2 步）
+### 服务器侧落地
 
-**第 1 步：宿主机建日志目录**
+**第 1 步：宿主机建目录**
 
 ```bash
-mkdir -p /opt/ht32-code-logs
-chmod 755 /opt/ht32-code-logs
+mkdir -p /opt/ht32-mcp-feedback
+chmod 755 /opt/ht32-mcp-feedback
 ```
 
-**第 2 步：1Panel 给 code-mcp 容器补挂载与环境变量**
+**第 2 步：两个 MCP 容器都挂同一卷**
 
-| 配置项 | 值 |
-|--------|-----|
-| 挂载 | `/opt/ht32-code-logs:/app/logs`（**不要加 `:ro`，需可写**） |
-| 环境变量 | `CODE_LOG_DIR=/app/logs` |
+| 服务 | 挂载 | 环境变量 |
+|------|------|----------|
+| ht32-wiki-mcp | `/opt/ht32-mcp-feedback:/app/feedback` | `FEEDBACK_ROOT=/app/feedback` |
+| ht32-code-mcp | `/opt/ht32-mcp-feedback:/app/feedback` | `FEEDBACK_ROOT=/app/feedback` |
 
-完整配置（含现有项）：
+完整配置（code 侧，含现有项）：
 
 ```
 类型：        uvx
@@ -226,38 +241,37 @@ chmod 755 /opt/ht32-code-logs
 环境变量：    CODE_ROOT=/app/code
             BUNDLE_DIR=/app/bundles
             BUNDLE_BASE_URL=https://mcp.s621.work/ht32-bundles
-            CODE_LOG_DIR=/app/logs
+            FEEDBACK_ROOT=/app/feedback
 挂载：        /opt/ht32-code:/app/code
             /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles:/app/bundles
-            /opt/ht32-code-logs:/app/logs
+            /opt/ht32-mcp-feedback:/app/feedback
 ```
 
-### 验证生效
+### 验证
 
-1. 调 `get_code_version`，应出现 `用量日志：启用（/app/logs）`。
+1. 调 `get_code_version`，应出现
+   `反馈与用量日志：启用（/app/feedback/code）`。
    仍显示「未配置」→ 环境变量没注入（查变量名 / 容器是否重建）。
 
 2. 随便调几个工具，然后看日志：
 
    ```bash
-   tail -3 /opt/ht32-code-logs/usage_$(date -u +%Y-%m-%d).jsonl
+   tail -3 /opt/ht32-mcp-feedback/code/usage_$(date -u +%Y-%m-%d).jsonl
    ```
 
-3. 按日期分析需求分布（示例：统计被请求的芯片型号，指导 P2-1 排优先级）：
+3. 统计被请求的芯片型号（指导 P2-1 排优先级）——用 ht32-skills 的分析工具：
 
    ```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}')
-   "
+   # 克隆 ht32-skills 后（或用本地副本）
+   python ht32-skills/scripts/analyze_feedback.py /opt/ht32-mcp-feedback
    ```
 
-4. 清理策略由定时同步脚本第 7 步负责（`LOG_KEEP_DAYS=30`，与同步日志同口径）。
+   该工具（零依赖，仅标准库）合并 wiki + code 两服务日志，输出需求信号、
+   调用分布与失败、反馈类型、耗时 p50/p95、最近失败与反馈明细；支持
+   `--days N` / `--service` / `--json`。详见 ht32-skills 的 README。
+
+4. 清理策略由定时同步脚本第 7 步负责（`LOG_KEEP_DAYS=30`，与同步日志同口径，
+   目录变量为 `FEEDBACK_ROOT`）。
 
 ## PyPI 包发布流程
 
@@ -290,9 +304,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` 44 用例全绿 | ✅ |
+| 3.3 | PyPI 发布（hatchling） | `ht32-code-mcp` 0.2.0（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.1}/PKG-INFO

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

@@ -52,9 +52,9 @@ INDEX_FILE="$CODE_DIR/.work/mcp-server/index/code_index.json"
 BUNDLE_DIR="/opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles"
 BUNDLE_TTL_MIN=60
 
-# 用量日志 / 反馈目录（1Panel 挂载到容器 /app/logs）
+# 用量日志 / 反馈目录（1Panel 挂载到容器 /app/feedback，与 wiki 同一卷）
 
-CODE_LOG_DIR="/opt/ht32-code-logs"
+FEEDBACK_DIR="/opt/ht32-mcp-feedback"
 
 # 日志目录（不存在则创建）
 
@@ -131,11 +131,13 @@ 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)
+# 目录为同根 + 服务子目录（wiki/ 与 code/），故递归找两层下的 jsonl
+
+if [ -d "$FEEDBACK_DIR" ]; then
+    OLD_LOGS=$(find "$FEEDBACK_DIR" -mindepth 2 -maxdepth 2 \( -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"
+    log "用量日志目录不存在，跳过清理：$FEEDBACK_DIR"
 fi
 
 log "本次同步完成"

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ht32-code-mcp"
-version = "0.1.3"
+version = "0.2.1"
 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.1}/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.2.1/src/ht32_code_mcp/usage.py

@@ -0,0 +1,223 @@
+"""反馈与用量日志：统一实现（ht32-wiki-mcp / ht32-code-mcp 共用同一份代码）。
+
+> **本文件在两个仓库存有逐字节相同的副本**（`ht32-wiki` 与 `ht32-code` 各一份）。
+> 修改时**必须同步另一仓库的同名文件**，并同步更新下方的 `_IMPL_VERSION`；
+> 两仓各有一条测试校验该版本号与目录布局，防止只改一边造成漂移。
+
+两条采集通道，写入同一目录树：
+
+- **tool_call**（`UsageMiddleware`，服务端自动）：拦截所有工具调用，
+  记录工具名、参数原文、耗时、成败。不依赖 Agent 配合，数据完整。
+- **feedback**（`record_feedback`，由各 server 的 `submit_feedback` 工具调用）：
+  记录 Agent 主动上报的语义性问题，middleware 无法判断这些。
+
+目录布局（同根 + 服务子目录）：
+
+    <FEEDBACK_ROOT>/
+      ├─ wiki/
+      │   ├─ usage_YYYY-MM-DD.jsonl
+      │   └─ feedback_YYYY-MM-DD.jsonl
+      └─ code/
+          ├─ usage_YYYY-MM-DD.jsonl
+          └─ feedback_YYYY-MM-DD.jsonl
+
+两个服务挂同一个宿主机目录，各写自己的子目录——清理、备份、查看都是
+单一入口。每条记录另带 `service` 字段作双保险。
+
+隐私：参数按原文记录（`query` / `question` 可能含用户项目信息），目录只应
+挂在受控服务器上，不要提交进仓库。
+"""
+from __future__ import annotations
+
+import json
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from fastmcp.server.middleware import Middleware, MiddlewareContext
+
+# 实现版本号：两仓库副本必须一致（各仓测试会校验，防止只改一边造成漂移）
+_IMPL_VERSION = "1.1.0"
+
+# 服务名 → 子目录名。新增服务在此登记。
+SERVICE_WIKI = "wiki"
+SERVICE_CODE = "code"
+
+# 不记录的工具参数：分页/长度控制项无分析价值；out_dir 可能含用户本地路径
+ARG_NOISE = frozenset({"limit", "max_length", "out_dir"})
+
+# 工具内的"软失败"标记：两服务的工具用**字符串**返回错误而不抛异常，middleware
+# 拿不到协议级 is_error，只能靠返回值文本判断。不识别会让真失败被记成 ok=true，
+# 后果不只是统计失真——分析工具按 ok 过滤"需求信号"，型号打错导致的
+# "导出失败：不在模板参数表"会被当成一次真实的芯片需求，污染选型优先级结论。
+#
+# 判定口径 = **工具是否完成了它的工作**，故只收明确执行失败：
+#   - 错误：      参数校验/路径越界/IO 失败/反馈写盘失败（两服务）
+#   - 导出失败    code: export_project_bundle 无法产出工程
+#   - 请至少提供  wiki: compare_chips 参数校验
+#
+# 刻意**不算**失败的是"无数据"类回答（工具正常跑完，只是没结果）：
+#   - 未找到匹配结果 / 未找到型号 'X' / 未找到外设 'X'
+#   - 不在支持列表 / 不在覆盖范围 / 暂无模板
+# 它们记 ok=true 才能进入需求信号——"用户搜 BLDC 但知识库没有"正是
+# 指导 P2-1 补内容的最强信号，标成失败会被分析工具当作噪声剔除。
+SOFT_FAILURE_MARKERS = (
+    "错误：",
+    "导出失败",
+    "请至少提供",
+)
+# 只在返回值开头这段内匹配，避免正文里偶然出现标记词造成误判
+_FAILURE_SCAN_CHARS = 80
+
+USAGE_PREFIX = "usage"
+FEEDBACK_PREFIX = "feedback"
+
+
+def looks_like_failure(text: str) -> bool:
+    """判断工具返回值是否为"软失败"（字符串形式的错误提示）。"""
+    head = (text or "").lstrip()[:_FAILURE_SCAN_CHARS]
+    return any(m in head for m in SOFT_FAILURE_MARKERS)
+
+
+def _result_text(result: Any) -> str:
+    """取工具返回值中的文本（供软失败判断）。"""
+    parts: list[str] = []
+    for block in getattr(result, "content", None) or []:
+        text = getattr(block, "text", None)
+        if isinstance(text, str):
+            parts.append(text)
+    return "\n".join(parts)
+
+
+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:
+        return None
+    try:
+        d = Path(log_dir)
+        d.mkdir(parents=True, exist_ok=True)
+        path = d / f"{prefix}_{datetime.now(timezone.utc).strftime('%Y-%m-%d')}.jsonl"
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+        return path
+    except OSError:
+        return None
+
+
+def _client_info(context: MiddlewareContext) -> dict[str, str]:
+    """取客户端标识（内存调用等无 session 的场景返回空值）。"""
+    ctx = getattr(context, "fastmcp_context", None)
+    if ctx is None:
+        return {}
+    out: dict[str, str] = {}
+    for key in ("client_id", "session_id"):
+        val = getattr(ctx, key, None)
+        if val:
+            out[key] = str(val)
+    transport = getattr(ctx, "transport", None)
+    if transport:
+        out["transport"] = str(transport)
+    return out
+
+
+class UsageMiddleware(Middleware):
+    """把所有工具调用落成 JSONL（服务端自动采集）。"""
+
+    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.kb_version = kb_version
+
+    async def on_call_tool(self, context: MiddlewareContext, call_next):
+        if not self.log_dir:
+            return await call_next(context)
+
+        args = dict(context.message.arguments or {})
+        recorded = {k: v for k, v in args.items() if k not in ARG_NOISE}
+        started = time.perf_counter()
+        error = ""
+        ok = True
+        try:
+            result = await call_next(context)
+            if getattr(result, "is_error", False):
+                # 协议级错误
+                ok = False
+                error = _result_text(result)[:500]
+            elif looks_like_failure(_result_text(result)):
+                # 工具以字符串返回的软失败（如"导出失败：…"）
+                ok = False
+                error = _result_text(result)[:500]
+            return result
+        except Exception as e:
+            error = f"{type(e).__name__}: {e}"  # 异常上抛，但不能漏记
+            ok = False
+            raise
+        finally:
+            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,
+                "kb_version": self.kb_version,
+                **_client_info(context),
+            }
+            write_record(self.log_dir, USAGE_PREFIX, record)
+
+
+def record_feedback(
+    log_dir: str,
+    service: str,
+    *,
+    question: str,
+    issue_type: str,
+    answer: str = "",
+    correction: str = "",
+    details: str = "",
+    model_id: str = "",
+    tools_called: list[str] | None = None,
+    mcp_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(),
+        "correction": correction.strip(),
+        "details": details.strip(),
+        "model_id": model_id.strip(),
+        # 过滤 submit_feedback 自身，只保留查询类工具
+        "tools_called": [t for t in (tools_called or []) if t and t != "submit_feedback"],
+        "mcp_version": mcp_version,
+        "kb_version": kb_version,
+    }
+    return write_record(log_dir, FEEDBACK_PREFIX, record)

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

@@ -304,6 +304,57 @@ 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.1.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_soft_failure_marker_semantics():
+    """软失败判定口径 = 工具是否完成工作。
+
+    真失败（执行没成功）→ 算失败；"无数据"（正常跑完但没结果）→ 不算失败，
+    否则"用户搜 BLDC 但库里没有"这类最强缺口信号会被当噪声剔除。
+    """
+    from ht32_code_mcp.usage import looks_like_failure as bad
+
+    # 真失败：参数/路径/IO/导出
+    assert bad("错误：path 不能为空。")
+    assert bad("错误：路径越界（只允许 raw/ 下文件）：x")
+    assert bad("导出失败：芯片 'X' 不在模板参数表")
+    assert bad("导出失败（打包或写盘失败，检查 bundle 目录权限/空间）：boom")
+    assert bad("错误：反馈未能写入。服务端可能未配置 FEEDBACK_ROOT，")
+    assert bad("请至少提供两个型号对比。")   # wiki: compare_chips 参数校验
+
+    # 无数据 ≠ 失败：必须记 ok=true 才能进需求信号
+    assert not bad("未找到匹配知识页。建议：换模块官方名小写重试…")
+    assert not bad("未找到外设 'xxx' 的例程。可用外设目录（44 个）：…")
+    assert not bad("芯片 'HT32F99999' 不在支持列表（当前 79 个型号，…")
+    assert not bad("系列 'F9' 不在覆盖范围。当前覆盖：…")
+    assert not bad("raw/templates/ 下暂无模板。")
+    assert not bad("未找到型号 'zzz'。可用型号：…")
+
+    # 正常成功返回值
+    assert not bad("找到 6 个 'gpio' 例程：…")
+    assert not bad("已导出 455 个文件到 …")
+    assert not bad("反馈已记录，感谢！问题类型：other")
+    # 正文后段偶然出现标记词不应误判（只扫开头 80 字符）
+    assert not bad("找到 3 条结果：\n" + "填充" * 60 + "\n注意：错误：的用法见页尾")
+
+
+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 +370,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 +388,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 +405,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,22 +430,60 @@ 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"]
 
 
+def test_usage_middleware_records_soft_failure(tmp_path):
+    """工具返回错误字符串（不抛异常）时，middleware 应记 ok=false 并留错误原文。"""
+    import asyncio
+
+    from fastmcp import Client, FastMCP
+
+    app = FastMCP("mw-soft")
+    app.add_middleware(UsageMiddleware(str(tmp_path / "logs"), "code",
+                                       mcp_version="0.2.1", kb_version="v0.1.0"))
+
+    @app.tool()
+    def soft_fail(chip: str) -> str:
+        return f"导出失败：芯片 '{chip}' 不在模板参数表"
+
+    @app.tool()
+    def no_data(peripheral: str) -> str:
+        return f"未找到外设 '{peripheral}' 的例程。可用外设目录（44 个）：…"
+
+    async def run():
+        async with Client(app) as c:
+            await c.call_tool("soft_fail", {"chip": "HT32F99999"})
+            await c.call_tool("no_data", {"peripheral": "zzz"})
+
+    asyncio.run(run())
+    recs = [json.loads(l) for l in
+            next((tmp_path / "logs").glob("usage_*.jsonl"))
+            .read_text(encoding="utf-8").splitlines()]
+    fail_rec, nodata_rec = recs
+    # 真失败：ok=false 且留下错误原文
+    assert fail_rec["tool"] == "soft_fail" and fail_rec["ok"] is False
+    assert "不在模板参数表" in fail_rec["error"]
+    # 无数据：不算失败，保留在需求信号里
+    assert nodata_rec["tool"] == "no_data" and nodata_rec["ok"] is True
+    assert nodata_rec["error"] == ""
+
+
 def test_usage_log_disabled_and_resilient(tmp_path):
     """log_dir 为空不落盘；目录不可写时调用仍成功（日志绝不中断服务）。"""
     import asyncio
 
     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 +491,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.1}/uv.lock

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

ht32_code_mcp-0.1.3/src/ht32_code_mcp/usage.py

@@ -1,138 +0,0 @@
-"""用量日志与反馈落盘。
-
-两条采集通道，写入同一目录、按 UTC 日期分文件（JSON Lines）：
-
-- **tool_call**（服务端自动，`UsageMiddleware` 拦截所有工具调用）：
-  记录工具名、参数原文、耗时、成败。不依赖 Agent 配合，数据完整。
-- **feedback**（Agent 主动，`submit_feedback` 工具）：
-  记录语义性问题（答错 / 知识库缺口 / 模板缺陷），中间件无法判断这些。
-
-目录由 `CODE_LOG_DIR` 指定，为空则整体关闭（本地开发默认关）。
-
-隐私：参数按原文记录（`query` 可能含用户项目信息），故日志目录只应挂在
-受控服务器上，不要提交进仓库。
-"""
-from __future__ import annotations
-
-import json
-import time
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Any
-
-from fastmcp.server.middleware import Middleware, MiddlewareContext
-
-# 不记录的参数：分页/长度控制项无分析价值；out_dir 可能含用户本地路径
-ARG_NOISE = frozenset({"max_length", "limit", "out_dir"})
-
-USAGE_PREFIX = "usage"
-FEEDBACK_PREFIX = "feedback"
-
-
-def _now() -> str:
-    return datetime.now(timezone.utc).isoformat()
-
-
-def write_record(log_dir: str, prefix: str, record: dict[str, Any]) -> Path | None:
-    """追加一条 JSONL 记录。log_dir 为空或写盘失败时返回 None（绝不因日志中断服务）。"""
-    if not log_dir:
-        return None
-    try:
-        d = Path(log_dir)
-        d.mkdir(parents=True, exist_ok=True)
-        path = d / f"{prefix}_{datetime.now(timezone.utc).strftime('%Y-%m-%d')}.jsonl"
-        with open(path, "a", encoding="utf-8") as f:
-            f.write(json.dumps(record, ensure_ascii=False) + "\n")
-        return path
-    except OSError:
-        return None
-
-
-def _client_info(context: MiddlewareContext) -> dict[str, str]:
-    """取客户端标识（内存调用等无 session 的场景返回空值）。"""
-    ctx = getattr(context, "fastmcp_context", None)
-    if ctx is None:
-        return {}
-    out: dict[str, str] = {}
-    for key in ("client_id", "session_id"):
-        val = getattr(ctx, key, None)
-        if val:
-            out[key] = str(val)
-    transport = getattr(ctx, "transport", None)
-    if transport:
-        out["transport"] = str(transport)
-    return out
-
-
-class UsageMiddleware(Middleware):
-    """把所有工具调用落成 JSONL（服务端自动采集）。"""
-
-    def __init__(self, log_dir: str, mcp_version: str = "", code_version: str = "") -> None:
-        self.log_dir = log_dir
-        self.mcp_version = mcp_version
-        self.code_version = code_version
-
-    async def on_call_tool(self, context: MiddlewareContext, call_next):
-        if not self.log_dir:
-            return await call_next(context)
-
-        args = dict(context.message.arguments or {})
-        recorded = {k: v for k, v in args.items() if k not in ARG_NOISE}
-        started = time.perf_counter()
-        error = ""
-        ok = True
-        try:
-            result = await call_next(context)
-            # 协议级错误标记；工具内以字符串返回的软失败不体现在此
-            if getattr(result, "is_error", False):
-                ok = False
-            return result
-        except Exception as e:
-            error = f"{type(e).__name__}: {e}"  # 异常上抛，但不能漏记
-            ok = False
-            raise
-        finally:
-            record = {
-                "timestamp": _now(),
-                "kind": "tool_call",
-                "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,
-                **_client_info(context),
-            }
-            write_record(self.log_dir, USAGE_PREFIX, record)
-
-
-def record_feedback(
-    log_dir: str,
-    *,
-    question: str,
-    issue_type: str,
-    answer: str = "",
-    correction: str = "",
-    details: str = "",
-    model_id: str = "",
-    tools_called: list[str] | None = None,
-    mcp_version: str = "",
-    code_version: str = "",
-) -> Path | None:
-    """记录一条 Agent 主动提交的反馈。"""
-    record = {
-        "timestamp": _now(),
-        "kind": "feedback",
-        "question": question.strip(),
-        "issue_type": issue_type,
-        "answer": answer.strip(),
-        "correction": correction.strip(),
-        "details": details.strip(),
-        "model_id": model_id.strip(),
-        # 过滤 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,
-    }
-    return write_record(log_dir, FEEDBACK_PREFIX, record)