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

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

@@ -25,6 +25,44 @@ PyPI 发布包 → 1Panel 原生 MCP 管理（类型 uvx，启动命令 uvx ht32
 代码默认走 `stdio`（`MCP_TRANSPORT` 未设置时），supergateway 负责 stdio→Streamable HTTP 转换。
 与 ht32-wiki 同构：SSE 无心跳会被 OpenResty 空闲切断，故走 streamableHttp stateful。
 
+## 传输模式（0.2.2+ 支持原生 HTTP）
+
+`server.py` 按 `MCP_TRANSPORT` 分派三种传输，**与 ht32-wiki 同构**：
+
+| `MCP_TRANSPORT` | 行为 | 典型用途 |
+|---|---|---|
+| `stdio`（默认） | 标准输入输出 | 本地开发；或供 supergateway 包装为 Streamable HTTP |
+| `streamable-http` | 单端点 HTTP，**默认有状态会话**（FastMCP `stateless_http=False`） | 直接对外暴露，无需 supergateway 这一层 |
+| `sse` | 旧式 SSE（无心跳，易被反代空闲切断） | 兼容旧客户端，不推荐 |
+
+HTTP 模式监听地址由 `MCP_HOST`（默认 `0.0.0.0`）/ `MCP_PORT`（默认 `8101`，
+**避开 wiki 的 8100**）控制；端点路径为 FastMCP 默认的 `/mcp`。
+
+```bash
+# 原生 Streamable HTTP（stateful），供反代直连
+MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8101 uvx ht32-code-mcp
+```
+
+> **stateful 是默认值而非开关**：FastMCP 4.0.5 的 `stateless_http` 默认 `False`，
+> 即同一 `mcp-session-id` 复用同一会话，子进程/进程内状态不每次 POST 重建——
+> 与 supergateway 的 `--stateful --sessionTimeout 3600000` 语义一致。
+> 若将来需要 stateless，须显式改 FastMCP 设置，届时 Wiki/Code 两端要一起对照。
+
+### 生产接线：一律用 supergateway 包装（2026-09-23 定）
+
+两个 MCP（wiki 与 code）**统一由 supergateway 包装**，不接受「服务自身原生 HTTP」形态：
+
+- 容器里 `uvx ht32-code-mcp` 保持 stdio，由网关转 Streamable HTTP + stateful
+- 好处：**网关这一层统一管协议版本与会话**（`--protocolVersion 2025-06-18`
+  `--stateful --sessionTimeout 3600000`），云端反代只认固定的容器端口/路径，
+  换服务或改内部实现时反代无需跟着动
+
+原生 `streamable-http` / `sse` 保留为**能力**（本地直跑、调试、将来去网关时可用），
+但**当前生产不启用**；本地 compose 部署方案见本仓库 `.work/docker/docker-compose.yml`（按此约定编写）。
+
+无论走哪种，**监听端口必须绑 `0.0.0.0`**（默认值），否则网关/反代从容器外连不上。
+验证：`ss -ltnp | grep -E '1808[0-2]'` 应显示 `0.0.0.0`，而非 `127.0.0.1`。
+
 ## 关键配置
 
 1Panel MCP 表单：
@@ -174,46 +212,80 @@ 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 判断不了的语义问题。每条记录都带 `service` 字段
+（`code`），便于两服务日志合并分析。
 
-自动通道保证调用事实完整（不依赖 Agent 配合）；反馈通道补 middleware
-判断不了的语义问题。`issue_type` 枚举：`wrong_api` / `missing_info` /
-`wrong_path` / `export_defect` / `unclear` / `other`。
+### `ok` 字段的口径（0.2.1+）
+
+工具用**字符串**返回错误而不抛异常，middleware 拿不到协议级 `is_error`，
+故靠返回值文本判断。口径是**工具是否完成了它的工作**：
+
+| 返回值 | `ok` | 说明 |
+|---|---|---|
+| `错误：…` / `导出失败…` | `false` | 参数校验、路径越界、IO 失败、无法产出工程 |
+| `未找到…` / `不在支持列表` / `不在覆盖范围` / `暂无模板` | `true` | **"无数据"≠失败** |
+
+"无数据"刻意记为成功：`用户搜 BLDC 但知识库没有` 正是指导 P2-1 补内容的
+最强信号，若标成失败会被分析工具当作噪声剔除。标记表在 `usage.py` 的
+`SOFT_FAILURE_MARKERS`，**改动工具返回值文案时需同步维护**。
+
+### 目录布局
+
+```
+/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` | 空（= **关闭**，本地开发默认不落盘） | 日志根目录，服务名子目录自动拼接；**必须填绝对路径**（如 `/app/feedback`，不要写 `app/feedback`） |
+| `CODE_LOG_DIR` | — | 已废弃，改用 `FEEDBACK_ROOT` |
 
-> **隐私**：参数按原文记录，`query`/`question` 可能含用户项目信息。
+> ⚠️ **必须用绝对路径**：`FEEDBACK_ROOT=app/feedback` 会相对容器 WORKDIR
+> 解析。实测云端曾因漏写前导 `/`，`get_code_version` 显示为
+> `反馈与用量日志：启用（app/feedback/code）`——靠 WORKDIR 恰为 `/` 才侥幸
+> 落对位置，改镜像 WORKDIR 后会静默写到别处。验证时看输出路径是否以 `/` 开头。
+
+> **隐私**：参数按原文记录，`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 +298,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,10 +362,11 @@ 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` 46 用例全绿 | ✅ |
+| 3.3 | PyPI 发布（hatchling） | `ht32-code-mcp` 0.2.2（2026-09-23，含 bundle 通道 + 统一反馈/用量日志 + 软失败识别 + 原生 Streamable HTTP） | ✅ |
 | 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 回退 | ✅ |
 | 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` | ✅ |
+| 3.8 | 定时同步脚本含 bundle 清理（P1-2） | `ht32-code-mcp-update.md` 第 6 步 `find … -mmin +60 -delete` | ✅ |
+| 3.9 | 反馈与用量日志（P1-5，与 wiki 统一） | 0.2.1；云端已启用，但 `FEEDBACK_ROOT` 漏写前导 `/`（显示 `app/feedback/code`），需改绝对路径 | ⚠️ |

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

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

ht32_code_mcp-0.2.2/README.md

@@ -0,0 +1,6 @@
+# .work/mcp-server/
+
+MCP server 代码目录（Python + FastMCP），实现 7 个检索/导出工具 + 1 个反馈工具。
+
+传输由 `MCP_TRANSPORT` 决定：`stdio`（默认，供 supergateway 包装）/ `streamable-http` / `sse`。
+部署与排错见 [DEPLOY.md](DEPLOY.md)。

{ht32_code_mcp-0.2.0 → ht32_code_mcp-0.2.2}/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.2}/pyproject.toml

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

ht32_code_mcp-0.2.2/smoke_http.py

@@ -0,0 +1,193 @@
+"""Streamable HTTP 冒烟测试：以子进程起 server（MCP_TRANSPORT=streamable-http），
+用真 HTTP 客户端走 initialize → notifications/initialized → tools/list → tools/call，
+并验证**会话复用**（stateful：同一 mcp-session-id 持续可用）。
+
+为什么必须真起进程 + 真 HTTP：与 smoke_stdio.py 同理——直接 import 调库测不到
+握手时序、传输层会话管理、stdout 洁净度；而这两者正是线上故障的高发面
+（wiki 侧曾因 smoke 缺失漏掉协议层两个缺陷到线上）。
+
+用法（从 .work/mcp-server/ 目录，需已安装依赖）：
+    python smoke_http.py
+"""
+from __future__ import annotations
+
+import json
+import os
+import socket
+import subprocess
+import sys
+import time
+import urllib.request
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+SRC = SCRIPT_DIR / "src"
+sys.path.insert(0, str(SRC))
+
+from fastmcp import Client  # noqa: E402
+
+# server.py 里 FastMCP.run("streamable-http") 的默认端点路径
+MCP_PATH = "/mcp"
+EXPECTED_TOOLS = {
+    "get_code_version", "list_libraries", "find_example", "get_file",
+    "search_code_knowledge", "get_project_manifest", "export_project_bundle",
+}
+START_TIMEOUT = 60.0
+REQUEST_TIMEOUT = 60.0
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return int(s.getsockname()[1])
+
+
+def _wait_port(port: int, proc: subprocess.Popen, deadline: float) -> None:
+    while time.monotonic() < deadline:
+        if proc.poll() is not None:
+            raise RuntimeError(f"服务进程提前退出，退出码 {proc.returncode}")
+        with socket.socket() as s:
+            s.settimeout(0.5)
+            if s.connect_ex(("127.0.0.1", port)) == 0:
+                return
+        time.sleep(0.2)
+
+    raise TimeoutError(f"端口 {port} 在 {START_TIMEOUT}s 内未监听")
+
+
+def _parse_sse(text: str) -> dict:
+    """从 SSE 文本中取第一条 data: 的 JSON（FastMCP 默认 json_response=False）。"""
+    for line in text.splitlines():
+        if line.startswith("data:"):
+            return json.loads(line[len("data:"):].strip())
+
+    raise AssertionError(f"响应中没有 SSE data 行：{text[:300]!r}")
+
+
+def _rpc(url: str, payload: dict, session_id: str | None = None):
+    """POST 一次 JSON-RPC（标准库实现，避免为测试引入 httpx 依赖）。"""
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+    }
+    if session_id:
+        headers["mcp-session-id"] = session_id
+
+    req = urllib.request.Request(
+        url, data=json.dumps(payload).encode("utf-8"), headers=headers, method="POST")
+    with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT) as resp:
+        return resp.status, dict(resp.headers), resp.read().decode("utf-8", "replace")
+
+
+def check_transport_layer(url: str) -> str:
+    """协议层：initialize 拿 session → initialized 通知 → 复用同一 session 调 tools/list。"""
+    status, headers, body = _rpc(url, {
+        "jsonrpc": "2.0", "id": 1, "method": "initialize",
+        "params": {
+            "protocolVersion": "2025-06-18",
+            "capabilities": {},
+            "clientInfo": {"name": "smoke-http", "version": "0"},
+        },
+    })
+    assert status == 200, f"initialize 非 200：{status} {body[:300]}"
+    session_id = headers.get("mcp-session-id")
+    assert session_id, f"initialize 未返回 mcp-session-id（头：{headers}）"
+    print(f"✅ initialize 成功，会话 id = {session_id[:16]}…")
+
+    proto = _parse_sse(body).get("result", {}).get("protocolVersion")
+    assert proto, f"initialize 响应缺少 protocolVersion：{body[:300]}"
+    print(f"✅ 协议版本协商 = {proto}")
+
+    status, _, _ = _rpc(url, {"jsonrpc": "2.0", "method": "notifications/initialized"},
+                        session_id=session_id)
+    assert status in (200, 202), f"initialized 通知非 2xx：{status}"
+
+    status, headers, body = _rpc(
+        url, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session_id=session_id)
+    assert status == 200, f"tools/list 非 200：{status}"
+    assert headers.get("mcp-session-id") == session_id, "tools/list 换用了新会话（非 stateful）"
+
+    tools = {t["name"] for t in _parse_sse(body)["result"]["tools"]}
+    missing = EXPECTED_TOOLS - tools
+    assert not missing, f"缺失工具：{missing}"
+    print(f"✅ 同一会话复用成功（stateful），工具 {len(tools)} 个：{sorted(tools)}")
+
+    return session_id
+
+
+async def check_client_layer(url: str) -> None:
+    """客户端层：用 FastMCP 官方 Client 走完整 tools/call（含结果反序列化）。"""
+    async with Client(url) as client:
+        tools = {t.name for t in await client.list_tools()}
+        missing = EXPECTED_TOOLS - tools
+        assert not missing, f"Client 视角缺失工具：{missing}"
+
+        r = await client.call_tool("get_code_version", {})
+        print("✅ get_code_version:", (r.content[0].text or "").splitlines()[0])
+
+        r = await client.call_tool("find_example", {"peripheral": "GPIO", "limit": 3})
+        text = r.content[0].text or ""
+        assert "example/GPIO" in text, text
+        print(f"✅ find_example(GPIO): {text.splitlines()[0]}")
+
+
+def main() -> int:
+    port = _free_port()
+    url = f"http://127.0.0.1:{port}{MCP_PATH}"
+
+    env = dict(os.environ)
+    env["PYTHONPATH"] = str(SRC) + os.pathsep + env.get("PYTHONPATH", "")
+    env["MCP_TRANSPORT"] = "streamable-http"
+    env["MCP_HOST"] = "127.0.0.1"
+    env["MCP_PORT"] = str(port)
+    env.pop("FEEDBACK_ROOT", None)   # 不带日志落盘，保持测试无副作用
+
+    # stdout 丢弃（HTTP 模式下 uvicorn 访问日志走 stdout，与协议无关）；
+    # 启动与异常信息走 stderr，失败时打印出来供排查
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "ht32_code_mcp"],
+        cwd=str(SCRIPT_DIR),
+        env=env,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+    def stop() -> str:
+        """服务是长驻进程，须先 terminate 再取输出，不能直接 communicate。"""
+        if proc.poll() is None:
+            proc.terminate()
+        try:
+            _, err = proc.communicate(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            _, err = proc.communicate()
+        return err or ""
+
+    try:
+        _wait_port(port, proc, time.monotonic() + START_TIMEOUT)
+        print(f"✅ 服务已监听 http://127.0.0.1:{port}{MCP_PATH}")
+
+        check_transport_layer(url)
+
+        import anyio
+        anyio.run(check_client_layer, url)
+
+        stop()
+
+        print("✅ Streamable HTTP 冒烟全部通过（stateful 会话复用已证实）")
+        return 0
+
+    except Exception:
+        print("❌ 冒烟失败，服务 stderr：", file=sys.stderr)
+        print(stop().strip()[:3000], file=sys.stderr)
+        raise
+
+    finally:
+        stop()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ht32_code_mcp-0.2.2/src/ht32_code_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""ht32-code-mcp：HT32 代码知识库 MCP Server（7 检索/导出工具 + 1 反馈工具）。
+
+传输：stdio（默认）/ streamable-http / sse，由 MCP_TRANSPORT 决定。
+"""

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

@@ -1,7 +1,7 @@
 """HT32 Code MCP Server。
 
 提供函数库/例程/模板检索与工程导出，供 AI Agent 调用。
-传输协议：stdio（P0 本地阶段；云端阶段见总纲 5.3）。
+传输协议：stdio（供 supergateway 包装为 Streamable HTTP）或 Streamable HTTP / SSE。
 """
 from __future__ import annotations
 
@@ -49,6 +49,11 @@ CLOUD_BUNDLE = bool(BUNDLE_DIR and BUNDLE_BASE_URL)
 FEEDBACK_ROOT = os.environ.get("FEEDBACK_ROOT", "").strip()
 LOG_DIR = resolve_log_dir(FEEDBACK_ROOT, SERVICE_CODE)
 
+# HTTP 传输模式监听地址（MCP_TRANSPORT 非 stdio 时生效）
+# 默认 8101 而非 8100：wiki 占用 8100，两服务常同机部署，避开默认端口冲突
+HOST = os.environ.get("MCP_HOST", "0.0.0.0")
+PORT = _env_int("MCP_PORT", 8101)
+
 index = CodeIndex(CODE_ROOT).load()
 knowledge = KnowledgeSearch(CODE_ROOT)
 exporter = ProjectExporter(CODE_ROOT)
@@ -427,7 +432,12 @@ def submit_feedback(
 
 
 def main() -> None:
-    """入口：按 MCP_TRANSPORT 环境变量启动（默认 stdio，P0 本地阶段）。"""
+    """入口：按 MCP_TRANSPORT 环境变量启动对应传输模式的服务器。
+
+    - stdio: 供 supergateway 包装为 Streamable HTTP（默认）
+    - streamable-http: 直接对外暴露的单端点 HTTP（有状态会话）
+    - sse: FastMCP 内置 SSE 服务器（旧式，无心跳易被反代空闲切断）
+    """
     transport = os.environ.get("MCP_TRANSPORT", "stdio").lower()
     stats = index.data.get("stats", {})
     print(f"[ht32-code-mcp] 程序版本: ht32-code-mcp {_MCP_VERSION}", file=sys.stderr)
@@ -437,11 +447,15 @@ def main() -> None:
     print(f"[ht32-code-mcp] 索引就绪: {stats.get('library_modules', 0)} 模块 / "
           f"{stats.get('examples', 0)} 例程 / {stats.get('raw_files', 0)} raw 文件", file=sys.stderr)
     if transport == "stdio":
-        print("[ht32-code-mcp] 启动服务: stdio", file=sys.stderr)
+        print("[ht32-code-mcp] 启动服务: stdio（供 supergateway 包装为 Streamable HTTP）",
+              file=sys.stderr)
         mcp.run(transport="stdio")
+    elif transport == "sse":
+        print(f"[ht32-code-mcp] 启动服务: SSE {HOST}:{PORT}", file=sys.stderr)
+        mcp.run(transport="sse", host=HOST, port=PORT)
     else:
-        print(f"[ht32-code-mcp] 传输模式 '{transport}' 暂未启用（P0 仅 stdio）", file=sys.stderr)
-        sys.exit(2)
+        print(f"[ht32-code-mcp] 启动服务: Streamable HTTP {HOST}:{PORT}", file=sys.stderr)
+        mcp.run(transport="streamable-http", host=HOST, port=PORT)
 
 
 if __name__ == "__main__":

{ht32_code_mcp-0.2.0 → ht32_code_mcp-0.2.2}/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.2}/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.2}/uv.lock

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

ht32_code_mcp-0.2.0/README.md

@@ -1,5 +0,0 @@
-# .work/mcp-server/
-
-MCP server 代码目录（Python/FastMCP），P0-2 在此实现 7 工具（本地 stdio）。
-
-当前为占位：仓库初始化（P0-1）时建立骨架，保证目录结构随 git 入库。

ht32_code_mcp-0.2.0/src/ht32_code_mcp/__init__.py

@@ -1,3 +0,0 @@
-"""ht32-code-mcp：HT32 代码知识库 MCP Server（7 工具，本地 stdio）。"""
-
-__version__ = "0.1.0"