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

{ht32_code_mcp-0.2.0 → 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 包发布流程
 
@@ -291,8 +305,8 @@ uv lock && uv build && uv publish
 | # | 任务 | 说明 | 状态 |
 |---|------|------|------|
 | 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.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.2.0 → ht32_code_mcp-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ht32-code-mcp
-Version: 0.2.0
+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.2.0 → 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.2.0 → ht32_code_mcp-0.2.1}/pyproject.toml

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

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

@@ -38,7 +38,7 @@ from typing import Any
 from fastmcp.server.middleware import Middleware, MiddlewareContext
 
 # 实现版本号：两仓库副本必须一致（各仓测试会校验，防止只改一边造成漂移）
-_IMPL_VERSION = "1.0.0"
+_IMPL_VERSION = "1.1.0"
 
 # 服务名 → 子目录名。新增服务在此登记。
 SERVICE_WIKI = "wiki"
@@ -47,10 +47,49 @@ 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()
 
@@ -121,9 +160,14 @@ class UsageMiddleware(Middleware):
         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}"  # 异常上抛，但不能漏记

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

@@ -307,13 +307,45 @@ 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._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
     # 同根 + 服务子目录
@@ -409,6 +441,42 @@ def test_usage_middleware_records_calls(tmp_path):
     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

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

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