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

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

@@ -79,17 +79,33 @@ version`。根因是 supergateway 3.4.3 对 SDK 声明的是浮动依赖 `^1.18.
 
 ### 服务器侧落地（3 步）
 
+本部署的 OpenResty 是**容器化**的（容器名 `1Panel-openresty-ih7J`），
+已挂载 `WEBSITE_DIR=/opt/1panel/www` → 容器内 `/www`。
+因此 bundle 目录直接落在网站根目录树下，**OpenResty 的 volumes 一行都不用改**——
+两个容器通过宿主机上的同一目录交换文件：
+
+```
+宿主机 /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles/   （站点 root 目录下 + /ht32-bundles）
+  ├─ code-mcp 容器看到  /app/bundles
+  └─ OpenResty 容器看到 /www/sites/mcp.s621.work/index/ht32-bundles
+  公网 URL             https://mcp.s621.work/ht32-bundles/<token>.zip
+```
+
+站点「网站目录」显示 root = `/opt/1panel/www/sites/mcp.s621.work/index`，
+bundle 放其下子目录即被当作静态文件直接访问。
+
 **第 1 步：宿主机建 bundle 目录**
 
 ```bash
-mkdir -p /opt/ht32-bundles
+mkdir -p /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles
+chmod 755 /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles
 ```
 
-**第 2 步：1Panel 补挂载与环境变量**
+**第 2 步：1Panel 给 code-mcp 容器补挂载与环境变量**
 
 | 配置项 | 值 |
 |--------|-----|
-| 挂载 | `/opt/ht32-bundles:/app/bundles`（**不要加 `:ro`，需可写**） |
+| 挂载 | `/opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles:/app/bundles`（**不要加 `:ro`，需可写**） |
 | 环境变量 | `BUNDLE_DIR=/app/bundles` |
 | 环境变量 | `BUNDLE_BASE_URL=https://mcp.s621.work/ht32-bundles` |
 | 环境变量 | `BUNDLE_TTL_SECONDS=3600`（可选，默认即 3600） |
@@ -108,31 +124,31 @@ mkdir -p /opt/ht32-bundles
             BUNDLE_DIR=/app/bundles
             BUNDLE_BASE_URL=https://mcp.s621.work/ht32-bundles
 挂载：        /opt/ht32-code:/app/code
-            /opt/ht32-bundles:/app/bundles
+            /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles:/app/bundles   ← 宿主机路径，非容器内路径
 ```
 
-**第 3 步：OpenResty 加静态 location**
+**第 3 步：OpenResty 无需任何配置**
 
-配置里已有 `include /www/sites/mcp.s621.work/proxy/*.conf;`（server 级），
-在该目录下新建 `bundles.conf`：
+站点 root = `/opt/1panel/www/sites/mcp.s621.work/index`，映射到容器内
+`/www/sites/mcp.s621.work/index`。bundle 目录落在这个 root 之下子目录，
+静态文件天然可访问，**不用建反向代理、不用手写 location、不用改 compose**。
 
-```nginx
-location ^~ /ht32-bundles/ {
-    alias /opt/ht32-bundles/;
-    autoindex off;                 # 禁止目录列举（防 token 泄露面扩大）
-    add_header Cache-Control "no-store";
-    types { application/zip zip; }
-    default_type application/zip;
-}
-```
+> **不要为 bundles 建反向代理条目**：1Panel 反代 UI 表达不了静态 location
+> （后端代理地址必填，而静态目录没有后端）。若建了且后端留空，1Panel 生成的
+> location 会抢走 `/ht32-bundles/` 却不知从哪读文件 → 404。已有此类条目请删除。
+
+> **静态 location 无需 `proxy_*` 指令**：文件由 nginx 读盘直接返回，不用
+> `proxy_pass`，也不用 `proxy_read_timeout`——这与 code 的代理 location 形态不同属正常。
 
-改完 `nginx -t && nginx -s reload`。
+> **权限**：1Panel 站点要求 `index` 目录下所有文件/目录属主与属组为 `1000`（见
+> 「网站目录」页提示，PHP 容器环境）。nginx worker 需可读该目录；zip 文件 644 /
+> 目录 755 正常可读。若验证时拿 403，先查属主属组与 SELinux 上下文。
 
-> **注意（容器化 OpenResty）**：若 OpenResty 跑在容器里而非宿主机原生进程，
-> `/opt/ht32-bundles` 还必须**同时挂进 OpenResty 容器**（同一宿主机路径），
-> 否则 nginx 读到的是容器内空目录，下载必然 404。
-> 现有 `proxy_pass http://127.0.0.1:8001/ht32-code` 能通，说明二者网络可达；
-> 但「可达」不等于「文件系统共享」，这一条需按实际部署形态确认。
+重载（改了容器挂载或环境变量时需重建 code-mcp；仅改文件无需重载 nginx）：
+
+```bash
+docker exec 1Panel-openresty-ih7J nginx -t
+```
 
 ### 验证生效
 
@@ -156,7 +172,92 @@ location ^~ /ht32-bundles/ {
 3. 浏览器/curl 拉该 URL：应得约 1.5 MB zip；`sha256sum` 与报告一致；
    解压后 455 文件、`project/MDK_ARMv5/ht32f5-template.uvprojx` 在，UV4 编译 0E0W。
 
-4. 确认 `ls /opt/ht32-bundles` 只有 `*.zip`（无残留临时目录）。
+4. 确认 `ls /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles` 只有 `*.zip`（无残留临时目录）。
+
+## 反馈与用量日志（P1-5，0.1.3+）
+
+两条通道写入同一目录、按 UTC 日期分文件（JSON Lines）：
+
+| 通道 | 触发 | 记录内容 |
+|------|------|----------|
+| `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` |
+
+自动通道保证调用事实完整（不依赖 Agent 配合）；反馈通道补 middleware
+判断不了的语义问题。`issue_type` 枚举：`wrong_api` / `missing_info` /
+`wrong_path` / `export_defect` / `unclear` / `other`。
+
+### 环境变量
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `CODE_LOG_DIR` | 空（= **整体关闭**，本地开发默认不落盘） | 日志写入目录，须可写 |
+
+> **隐私**：参数按原文记录，`query`/`question` 可能含用户项目信息。
+> 该目录只应挂在受控服务器上，**不要提交进仓库**（定时脚本是
+> `git reset --hard` 镜像模式，写进仓库也会被覆盖丢失）。
+
+### 服务器侧落地（2 步）
+
+**第 1 步：宿主机建日志目录**
+
+```bash
+mkdir -p /opt/ht32-code-logs
+chmod 755 /opt/ht32-code-logs
+```
+
+**第 2 步：1Panel 给 code-mcp 容器补挂载与环境变量**
+
+| 配置项 | 值 |
+|--------|-----|
+| 挂载 | `/opt/ht32-code-logs:/app/logs`（**不要加 `:ro`，需可写**） |
+| 环境变量 | `CODE_LOG_DIR=/app/logs` |
+
+完整配置（含现有项）：
+
+```
+类型：        uvx
+启动命令：    uvx ht32-code-mcp
+输出类型：    streamableHttp
+流式传输路径：/ht32-code
+协议版本：    2025-06-18
+镜像：        supercorp/supergateway:next-uvx
+参数：        --stateful --sessionTimeout 3600000
+环境变量：    CODE_ROOT=/app/code
+            BUNDLE_DIR=/app/bundles
+            BUNDLE_BASE_URL=https://mcp.s621.work/ht32-bundles
+            CODE_LOG_DIR=/app/logs
+挂载：        /opt/ht32-code:/app/code
+            /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles:/app/bundles
+            /opt/ht32-code-logs:/app/logs
+```
+
+### 验证生效
+
+1. 调 `get_code_version`，应出现 `用量日志：启用（/app/logs）`。
+   仍显示「未配置」→ 环境变量没注入（查变量名 / 容器是否重建）。
+
+2. 随便调几个工具，然后看日志：
+
+   ```bash
+   tail -3 /opt/ht32-code-logs/usage_$(date -u +%Y-%m-%d).jsonl
+   ```
+
+3. 按日期分析需求分布（示例：统计被请求的芯片型号，指导 P2-1 排优先级）：
+
+   ```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}')
+   "
+   ```
+
+4. 清理策略由定时同步脚本第 7 步负责（`LOG_KEEP_DAYS=30`，与同步日志同口径）。
 
 ## PyPI 包发布流程
 
@@ -189,10 +290,11 @@ 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.1（2026-09-20）；0.1.2 为 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 空闲断连 | ✅ |
-| 3.7 | 云端 zip 下载通道（P1-3） | 代码就绪并端到端验证；**服务器侧 3 步待执行** | ⏳ |
+| 3.6 | OpenResty 超时修复（`proxy_read_timeout 3600s`） | 修复 60s 空闲断连；2026-09-21 复核两端空闲 100s 后调用仍 200，未被 1Panel 回退 | ✅ |
+| 3.7 | 云端 zip 下载通道（P1-3） | 服务器侧已上线：下载 1608157 字节 / SHA256 一致 / 解压 455 文件 / UV4 0E0W | ✅ |
+| 3.8 | 定时同步脚本含 bundle 清理（P1-2） | `ht32-code-mcp-update.md` 第 6 步 `find … -mmin +60 -delete` | ✅ |

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ht32-code-mcp
-Version: 0.1.2
+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.2 → ht32_code_mcp-0.2.0}/ht32-code-mcp-update.md

@@ -26,6 +26,16 @@
 
 # 日志：按天归档 /opt/ht32-code-sync/ht32-code-sync-YYYYMMDD.log，自动清理 30 天前的旧日志
 
+# - 顺带清理 bundle 下载目录的过期 zip（P1-3）
+
+# （server 每次 export 前也会 sweep 一次，此处为兜底：
+
+#  若一段时间无人调用 export，TTL 过期的 zip 不会被那次 sweep 清掉）
+
+# - 顺带清理超期的用量日志 / 反馈 JSONL（P1-5）
+
+# （保留 LOG_KEEP_DAYS 天，与同步日志同口径）
+
 # ============================================================
 
 set -e
@@ -37,6 +47,15 @@ LOG_FILE="$LOG_DIR/ht32-code-sync-$(date '+%Y%m%d').log"
 LOG_KEEP_DAYS=30
 INDEX_FILE="$CODE_DIR/.work/mcp-server/index/code_index.json"
 
+# bundle 目录（站点 root 下子目录，OpenResty 直接静态提供）与保留时长
+
+BUNDLE_DIR="/opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles"
+BUNDLE_TTL_MIN=60
+
+# 用量日志 / 反馈目录（1Panel 挂载到容器 /app/logs）
+
+CODE_LOG_DIR="/opt/ht32-code-logs"
+
 # 日志目录（不存在则创建）
 
 mkdir -p "$LOG_DIR"
@@ -101,4 +120,22 @@ fi
 
 find "$LOG_DIR" -name "ht32-code-sync-*.log" -mtime +$LOG_KEEP_DAYS -delete 2>/dev/null || true
 
+# 6. 清理 bundle 目录中超过 TTL 的 zip（兜底，与 BUNDLE_TTL_SECONDS 保持一致）
+
+if [ -d "$BUNDLE_DIR" ]; then
+    SWEPT=$(find "$BUNDLE_DIR" -maxdepth 1 -name "*.zip" -mmin +$BUNDLE_TTL_MIN -print -delete 2>/dev/null | wc -l)
+    log "bundle 清理：删除 $SWEPT 个过期 zip"
+else
+    log "bundle 目录不存在，跳过清理：$BUNDLE_DIR"
+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)
+    log "用量日志清理：删除 $OLD_LOGS 个过期文件"
+else
+    log "用量日志目录不存在，跳过清理：$CODE_LOG_DIR"
+fi
+
 log "本次同步完成"

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

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

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

@@ -9,6 +9,7 @@ import os
 import sys
 from importlib.metadata import PackageNotFoundError, version as pkg_version
 from pathlib import Path
+from typing import Literal
 
 from fastmcp import FastMCP
 
@@ -20,6 +21,7 @@ from .exporter import (
 )
 from .index import CodeIndex, normalize_series
 from .knowledge import KnowledgeSearch
+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]
@@ -41,6 +43,12 @@ 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)
 
+# 反馈与用量日志：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)
 exporter = ProjectExporter(CODE_ROOT)
@@ -66,10 +74,23 @@ _INSTRUCTIONS = """HT32 代码知识库（函数库/例程/工程模板），当
 - 路径一律为仓库相对 posix 路径（raw/... 开头），get_file 直接可用
 - 型号大小写自动归一（ht32f52352 = HT32F52352）
 - 知识页查不到时不要编造，改查 list_libraries + get_file 原码
+
+## 反馈
+出现以下情况调 submit_feedback 记录，帮助改进本知识库：
+- 你给的 API/宏/路径与实际编译结果矛盾，或用户指出你答案有误
+- 知识库缺了用户需要的内容，你只能用推测回答
+- 导出工程有缺陷（编译失败、型号参数错、缺文件）
+务必附 model_id；submit_feedback 之外的调用已由服务端自动记入用量日志，无需你重复上报。
 """
 
 mcp = FastMCP("ht32-code", instructions=_INSTRUCTIONS)
 
+# 用量日志：服务端自动记录所有工具调用（FEEDBACK_ROOT 为空则不启用）
+if LOG_DIR:
+    mcp.add_middleware(UsageMiddleware(
+        LOG_DIR, SERVICE_CODE,
+        mcp_version=_MCP_VERSION, kb_version=index.data.get("code_version", "")))
+
 
 # ================================================================ MCP Tools
 
@@ -100,6 +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 "反馈与用量日志：未配置（FEEDBACK_ROOT 为空，不落盘）"),
         "",
         "VERSION 文件内容：",
         version_text,
@@ -346,6 +369,60 @@ def export_project_bundle(chip: str, out_dir: str = "") -> str:
         return f"导出失败：{e}"
 
 
+# ================================================================ Feedback
+
+
+@mcp.tool()
+def submit_feedback(
+    question: str,
+    issue_type: Literal[
+        "wrong_api", "missing_info", "wrong_path", "export_defect", "unclear", "other"
+    ] = "wrong_api",
+    answer: str = "",
+    correction: str = "",
+    details: str = "",
+    model_id: str = "",
+    tools_called: list[str] | None = None,
+) -> str:
+    """提交纠正反馈，改进 HT32 代码知识库。
+
+    何时调：你给的 API/宏/路径与实际编译矛盾、用户指出你答错、
+    知识库缺了用户需要的内容、导出工程有缺陷（编译失败/型号参数错/缺文件）。
+
+    注意：工具调用已由服务端自动记入用量日志，本工具只用于记录
+    上述**语义性问题**，不需要为每次调用提交。
+
+    Args:
+        question: 用户原始需求/问题（必填，尽量完整抄录）
+        issue_type: 问题类型，枚举上述其一
+        answer: 你给出的回答原文
+        correction: 你认为正确的信息或用户指出的正确内容
+        details: 补充上下文（如编译报错原文）
+        model_id: 你的模型标识，如 deepseek-v4-flash
+        tools_called: 本次调过的查询工具列表（不含 submit_feedback 自身）
+    """
+    if not question or not question.strip():
+        return "错误：question 参数不能为空，请提供用户原始需求。"
+
+    path = record_feedback(
+        LOG_DIR,
+        SERVICE_CODE,
+        question=question,
+        issue_type=issue_type,
+        answer=answer,
+        correction=correction,
+        details=details,
+        model_id=model_id,
+        tools_called=tools_called,
+        mcp_version=_MCP_VERSION,
+        kb_version=index.data.get("code_version", ""),
+    )
+    if path is None:
+        return ("错误：反馈未能写入。服务端可能未配置 FEEDBACK_ROOT，"
+                "或该目录不可写——请联系管理员。")
+    return f"反馈已记录，感谢！问题类型：{issue_type}，文件：{path.name}"
+
+
 # ================================================================ 入口
 
 

ht32_code_mcp-0.2.0/src/ht32_code_mcp/usage.py

@@ -0,0 +1,179 @@
+"""反馈与用量日志：统一实现（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.0.0"
+
+# 服务名 → 子目录名。新增服务在此登记。
+SERVICE_WIKI = "wiki"
+SERVICE_CODE = "code"
+
+# 不记录的工具参数：分页/长度控制项无分析价值；out_dir 可能含用户本地路径
+ARG_NOISE = frozenset({"limit", "max_length", "out_dir"})
+
+USAGE_PREFIX = "usage"
+FEEDBACK_PREFIX = "feedback"
+
+
+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
+            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.2 → ht32_code_mcp-0.2.0}/tests/test_tools.py

@@ -4,6 +4,7 @@
 """
 from __future__ import annotations
 
+import json
 import os
 import re
 import time
@@ -13,6 +14,7 @@ from pathlib import Path
 import pytest
 
 from ht32_code_mcp import server as srv
+from ht32_code_mcp.usage import UsageMiddleware
 
 FWLIB = "raw/HT32_STD_5xxxx_FWLib_V1.21.1"
 
@@ -301,6 +303,140 @@ def test_version_reports_bundle_mode(monkeypatch):
     assert "云端 zip 下载：启用" in srv.get_code_version()
 
 
+# ---------------------------------------------------------------- 反馈与用量日志
+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(
+        question="HT32F52352 怎么配 GPIO 输出？",
+        issue_type="wrong_api",
+        answer="我给的 GPIO_DirectionConfig 参数顺序错了",
+        correction="应为 GPIO_DirectionConfig(GPIO_PORT, GPIO_PIN, GPIO_DIR)",
+        details="编译报错 too few arguments",
+        model_id="deepseek-v4-flash",
+        tools_called=["search_code_knowledge", "submit_feedback", "get_file"],
+    )
+    assert "反馈已记录" in out
+    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["kb_version"]
+
+
+def test_submit_feedback_empty_question(tmp_path, monkeypatch):
+    monkeypatch.setattr(srv, "LOG_DIR", str(tmp_path / "logs"))
+    assert "不能为空" in srv.submit_feedback(question="   ")
+    assert not (tmp_path / "logs").exists()  # 未落盘
+
+
+def test_submit_feedback_without_log_dir(monkeypatch):
+    monkeypatch.setattr(srv, "LOG_DIR", "")
+    out = srv.submit_feedback(question="x")
+    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/feedback/code")
+    assert "反馈与用量日志：启用（/app/feedback/code）" in srv.get_code_version()
+
+
+def test_usage_middleware_records_calls(tmp_path):
+    """服务端自动采集：成功与失败调用都落盘，噪声参数被剔除。"""
+    import asyncio
+
+    from fastmcp import Client, FastMCP
+
+    app = FastMCP("mw-test")
+    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:
+        return "ok:" + chip
+
+    @app.tool()
+    def boom() -> str:
+        raise ValueError("deliberate")
+
+    async def run():
+        async with Client(app) as c:
+            await c.call_tool("probe", {"chip": "HT32F52352", "limit": 9,
+                                        "out_dir": "D:/x"})
+            with pytest.raises(Exception):
+                await c.call_tool("boom", {})
+
+    asyncio.run(run())
+    recs = [json.loads(l) for l in
+            next((tmp_path / "logs").glob("usage_*.jsonl"))
+            .read_text(encoding="utf-8").splitlines()]
+    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.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_log_disabled_and_resilient(tmp_path):
+    """log_dir 为空不落盘；目录不可写时调用仍成功（日志绝不中断服务）。"""
+    import asyncio
+
+    from fastmcp import Client, FastMCP
+
+    from ht32_code_mcp.usage import write_record
+
+    assert write_record("", "usage", {"x": 1}) is None
+
+    # 用一个"父路径是文件"的 log_dir 制造 mkdir 失败
+    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"), "code"))
+
+    @app.tool()
+    def probe() -> str:
+        return "ok"
+
+    async def run():
+        async with Client(app) as c:
+            r = await c.call_tool("probe", {})
+            assert not r.is_error
+
+    asyncio.run(run())  # 写盘失败不抛异常
+
+
 # ---------------------------------------------------------------- 索引可重复构建
 def test_index_rebuild_deterministic():
     from ht32_code_mcp.index import CodeIndex

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

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