ht32-code-mcp 0.4.6__tar.gz → 0.5.0__tar.gz

ht32_code_mcp-0.5.0/DEPLOY.md

@@ -0,0 +1,279 @@
+# MCP Server 部署指南（ht32-code）
+
+> 本文只写**当前**部署形态。历史演进看 git log；文档与 compose 冲突时**以 compose 为准**。
+> 代码在 `.work/mcp-server/`，已发布到 PyPI（`ht32-code-mcp`）。
+
+## 部署信息
+
+```
+MCP Server 地址（Streamable HTTP）: https://mcp.s621.work/ht32-code
+PyPI 包:              https://pypi.org/project/ht32-code-mcp/（uvx ht32-code-mcp）
+Bundle 下载地址:       https://mcp.s621.work/ht32-bundles/<token>.zip
+本地 Gitea:            http://100.66.1.6:3000/S621/ht32-code.git
+MCP Server 代码:       .work/mcp-server/
+```
+
+## 当前拓扑
+
+MCP 与 bundle 都跑在应用机（Linux 本地机），云端 OpenResty 只做反向代理：
+
+```
+客户端 → https://mcp.s621.work（云端 OpenResty）
+       → 节点小宝 P2P 组网（100.66.1.6）
+       → 应用机容器
+            ht32-code-mcp      宿主 18081 → 容器 8001   /ht32-code
+            ht32-bundles-web   宿主 18082 → 容器 80     /ht32-bundles
+```
+
+反代配置原文在**工作区** `maintenance/openresty/`（`ht32-code.conf` / `ht32-bundles.conf` / `default.conf`），
+手工贴进 1Panel 站点 `mcp.s621.work` 的同一个 server 块。`/ht32-bundles` **必须反代**
+到 `100.66.1.6:18082`，且 `proxy_pass` 不能带尾斜杠。
+
+## 运行形态
+
+```
+PyPI 包 → FastMCP 直接提供 Streamable HTTP（常驻单进程）
+```
+
+- 容器直接执行 `ht32-code-mcp`，`MCP_TRANSPORT=streamable-http`。
+- `MCP_STATELESS_HTTP=0`：同一进程内多会话，不再一会话一 Python 子进程。
+- 内存：单进程约 0.1–0.3GB；`export_project_bundle` 并发由应用层信号量限制为 2。
+- 冷启动：进程启动时加载一次代码索引；新会话不再重付。
+
+### 镜像与端点
+
+- 镜像 `ht32-code-mcp:0.5.0`：`ghcr.io/astral-sh/uv:python3.12-bookworm-slim` +
+  `git/curl/ca-certificates`，`uv tool install ht32-code-mcp==0.5.0`，入口直跑
+  `ht32-code-mcp`（私有组件能力仍需服务端 git）。由 `.work/docker/Dockerfile` 构建。
+- 传输：生产 `MCP_TRANSPORT=streamable-http`，`path=/ht32-code`（`MCP_PATH` 注入）；
+  本地调试保持默认 `/mcp`。`stdio` 仅供冒烟测试。
+- `MCP_JSON_RESPONSE=0`：保持 SSE，兼容现有客户端。
+- 健康检查：`GET /health` → `{"status":"ok","version":"<包版本>"}`，不触发检索。
+- 资源：`mem_limit: 1g` / `cpus: 1.0` / `pids_limit: 512`（常驻单进程与多会话对象）；
+  不再使用 V1 按「一会话一进程」算出的 `4g` / `1024` 熔断值。
+
+## compose 关键配置
+
+文件：`.work/docker/docker-compose.yml`（项目名 `ht32-code`）。
+
+| 项 | 值 |
+|---|---|
+| 端口 | `18081:8001` |
+| `CODE_ROOT` | `/app/code`（挂载 `/vol1/1000/SSD/docker/ht32-code`） |
+| `FEEDBACK_ROOT` | `/app/feedback`（挂载 `/vol1/1000/SSD/docker/ht32-mcp-feedback`） |
+| `BUNDLE_DIR` | `/app/bundles`（挂载 `/vol1/1000/SSD/docker/ht32-web/ht32-bundles`） |
+| `BUNDLE_BASE_URL` | `https://mcp.s621.work/ht32-bundles` |
+| `COMPONENTS_CONFIG` | `/app/code/.work/components/components.json` |
+| `COMPONENTS_STATE_FILE` | `/app/feedback/component-tag-lock.json` |
+| 凭据 | `.work/docker/.env` 的 `COMPONENTS_GIT_AUTH`（base64 用户名:只读 token），已 gitignore |
+| `MCP_TRANSPORT` | `streamable-http`（不经 supergateway） |
+| `MCP_HOST` / `MCP_PORT` | `0.0.0.0` / `8001` |
+| `MCP_PATH` | `/ht32-code`（须与反代 location 一致） |
+| `MCP_STATELESS_HTTP` | `0`（P0 保留进程内有状态会话） |
+| `MCP_JSON_RESPONSE` | `0`（保持 SSE 响应） |
+| 资源 | `mem_limit: 1g` / `cpus: 1.0` / `pids_limit: 512` |
+| 健康检查 | `curl -fsS http://127.0.0.1:8001/health`，30s 间隔，`start_period: 60s` |
+
+> `CODE_ROOT` 挂载**不加 `:ro`**：`index/code_index.json` 已 gitignore，容器内可能需重建。
+
+## 云端 zip 下载通道
+
+`export_project_bundle` 有两种交付形态，**由服务端环境变量决定，调用方无需判断**：
+
+| 模式 | 触发条件 | 行为 |
+|---|---|---|
+| 云端 zip | `BUNDLE_DIR` 与 `BUNDLE_BASE_URL` **同时非空** | 打包到 `BUNDLE_DIR`，返回 `<BUNDLE_BASE_URL>/<token>.zip` + SHA256 + 过期时间 |
+| 本地目录 | 二者任一为空（默认） | 物化到 `out_dir`（须为空目录/不存在） |
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `BUNDLE_DIR` | 空（= 关闭云端模式） | 容器内 bundle 输出目录，须可写 |
+| `BUNDLE_BASE_URL` | 空（= 关闭云端模式） | 公网下载前缀 |
+| `BUNDLE_TTL_SECONDS` | `3600` | zip 有效期；每次 export 前顺带清理过期 zip |
+
+实现要点：
+
+- **token**：`secrets.token_urlsafe(24)`（192 bit 熵），文件名即 token，不可枚举
+- **物化在系统临时目录**：bundle 目录里只出现最终 zip，失败不留公开半成品
+- **清理**：每次 export 按 mtime `sweep_expired()`；TTL 到点不主动删，
+  靠下次 export 或同步脚本兜底；过期后重新调用工具即可拿新 URL
+
+### 服务器侧落地
+
+两个容器通过应用机上的同一目录交换文件：
+
+```
+应用机 /vol1/1000/SSD/docker/ht32-web/ht32-bundles/
+  ├─ ht32-code-mcp 容器     看到 /app/bundles（按 TTL 写 zip）
+  └─ ht32-bundles-web 容器  看到 /usr/share/nginx/html/ht32-bundles（18082 → 80）
+云端 OpenResty /ht32-bundles → proxy_pass http://100.66.1.6:18082
+公网 URL https://mcp.s621.work/ht32-bundles/<token>.zip
+```
+
+compose 已包含两个服务，无需界面手工加挂载。云端 OpenResty 必须有：
+
+```nginx
+location ^~ /ht32-bundles {
+    proxy_pass http://100.66.1.6:18082;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_read_timeout 300s;
+    proxy_buffering on;
+}
+```
+
+漏了这条 location，`/ht32-bundles/` 会被 `default.conf` 兜底成 404。
+
+### 验证
+
+1. `get_code_version` 出现
+   `云端 zip 下载：启用（TTL 3600s，https://mcp.s621.work/ht32-bundles）`；
+   仍显示「未配置」→ 环境变量没注入（查变量名 / 容器是否重建）。
+2. `export_project_bundle(chip="HT32F52352")` 返回下载 URL、有效期、大小、SHA256。
+3. curl 拉该 URL：约 1.5 MB zip，`sha256sum` 与报告一致，解压后 UV4 编译 0E0W。
+4. `ls /vol1/1000/SSD/docker/ht32-web/ht32-bundles` 只有 `*.zip`（无残留临时目录）。
+
+## 反馈与用量日志
+
+与 ht32-wiki 使用**同一套实现**（`usage.py`，两仓库逐字节相同）、同一套目录约定
+（同根 + 服务子目录）、同一套字段。本服务写 `<FEEDBACK_ROOT>/code/`。
+
+| 通道 | 文件 | 触发 | 内容 |
+|------|------|------|------|
+| 用量日志 | `usage_*.jsonl` | 服务端自动（middleware） | 工具名、参数原文、耗时、成败、session |
+| 反馈 | `feedback_*.jsonl` | Agent 主动（`submit_feedback`） | 语义性问题 |
+
+- `FEEDBACK_ROOT` 为空 = 整体关闭（本地开发默认不落盘）；必须填**绝对路径**。
+- `ok` 字段口径是「工具是否完成了它的工作」：`错误：` / `导出失败` / `请至少提供` 记失败；
+  `未找到` / `不在支持列表` 记成功（"库里没有"是补内容的最强信号）。
+- 清理由同步脚本负责（`LOG_KEEP_DAYS=30`）。
+
+### 目录布局与验证
+
+```
+/vol1/1000/SSD/docker/ht32-mcp-feedback/   ← 宿主机单一入口，两容器挂同一卷
+  ├─ wiki/    ← ht32-wiki 容器写
+  └─ code/    ← ht32-code 容器写
+```
+
+`get_code_version` 应显示 `反馈与用量日志：启用（/app/feedback/code）`；
+`tail -3 /vol1/1000/SSD/docker/ht32-mcp-feedback/code/usage_$(date -u +%Y-%m-%d).jsonl` 能看到记录。
+合并分析用 ht32-skills 的 `scripts/analyze_feedback.py`。
+
+## 私有组件
+
+让 MCP 用户发现私有 Git 组件（BSP / 中间件 / 驱动包），检索/读取源码，并把选定 tag 的
+源码快照并入导出工程。
+
+```
+用户 → MCP: list_components / get_component_info / search_component_code / read_component_file
+          export_project_bundle(components=["<id>@<tag>"])
+MCP → 仓库内登记表（.work/components/components.json）→ 私有 Git
+```
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `COMPONENTS_CONFIG` | `.work/components/components.json`（文件存在即启用） | 组件目录；配置无效时**服务启动失败**并定位到字段 |
+| `COMPONENTS_STATE_FILE` | `<临时目录>/ht32-component-cache/tag-lock.json` | tag→commit 台账（检测 tag 被强制移动） |
+| `COMPONENT_GIT_TIMEOUT` | `60` | 单次 Git 操作超时（秒） |
+
+运行时依赖 `git` + 私有仓库凭据，缺一即 `[COMPONENT_REMOTE_UNAVAILABLE]`：
+
+1. **镜像**：`ht32-code-mcp:0.4.5-git` 已补 git；`docker exec ht32-code-mcp git --version` 应有输出。
+2. **凭据**：部署机 `.work/docker/.env` 写
+   `COMPONENTS_GIT_AUTH=<base64("用户名:只读token")>`；compose 以
+   `GIT_CONFIG_*` 注入 `http.extraheader`，不写入仓库、日志或 MCP 响应。轮换后改 `.env` 并重建容器。
+3. **验证**：`docker exec ht32-code-mcp git ls-remote http://100.66.1.6:3000/S621/LwFSM.git | tail -2`
+   能列出 `refs/tags/V2.0`。
+
+### 源码裁剪（`export.redact`）
+
+面向"只交付 `.lib`、不给源码"的组件。不执行仓库里的 `script/submodule.bat`，
+改为快照层内置规则：
+
+| 模式 | 行为 |
+|---|---|
+| `none`（默认） | 不裁剪 |
+| `auto` | 仅当仓库含 `script/submodule.bat` 时按 `lib-only` 规则裁剪 |
+| `lib-only` | 无条件裁剪 |
+
+`lib-only` 规则：移除根 `project/`；`lib/<name>.lib` 存在则移除 `src/<name>.c`；
+`tools/InfoProcess.exe` 存在则移除 `tools/InfoProcess.c`；`script/` 保留。
+裁剪发生在快照构建阶段，`read_component_file` / `search_component_code` / 导出均看不到被移除文件；
+`manifest/components-lock.json` 记录 `redaction.mode` 与逐条 `removed`。
+
+### 登记表位置
+
+放在 ht32-code 仓库 `.work/components/components.json`，随仓库版本化：
+
+- 新增组件 = 一次 commit；服务器 `git reset --hard` 后自动生效；**不需要发 MCP 版本**
+- **不进 PyPI**：wheel 只含 `src/`；sdist 已排除 `.work/components`
+- **前提：仓库保持私有**。转公开前必须先把登记表移出
+- `catalog_sha256` / 仓库 `commit` / `catalog_version` 一起出现在
+  `get_code_version` / `list_components` / `components-lock.json`，用于反查登记表版本
+- 字段要点：`series` 按族前缀/通配匹配，`["*"]` 表示覆盖全型号；`chips` 只用于展示已验证型号
+- 加载器支持 `//` 与 `/* */` 注释（不支持尾随逗号），注释计入哈希
+
+### 日常运维
+
+| 操作 | 做法 |
+|---|---|
+| 新增组件 | 改登记表 → commit/push → 同步脚本或手动 reset + 重建 |
+| 刷新可用 tag | 组件维护者打 tag 即可，查询时自动出现 |
+| 下架/暂停 | `"status": "disabled"` → commit → 同步 |
+| 回滚登记表 | `git checkout <commit> -- .work/components/components.json` → commit/push |
+| tag 漂移 | 同 tag 指向新 commit 返回 `[COMPONENT_TAG_DRIFT]`，核实后删台账该行重试 |
+| 查历史 | `git log -p -- .work/components/components.json`；工程侧看 `components-lock.json` |
+| 不要在服务器上直接改 | 更新脚本 `git reset --hard` 会覆盖手改 |
+
+### 隐私检查
+
+```bash
+uv build && tar -tzf dist/*.tar.gz | grep -i "\.work/components" && echo "泄漏！" || echo "OK"
+git grep -nE "PRIVATE-TOKEN|password=|ssh://.*@" -- .work/components
+```
+
+## 更新与发布
+
+**服务器侧更新**（改 compose / 路径 / 端口 push 后，脚本一跑即生效）：
+
+```bash
+cd /vol1/1000/SSD/docker/ht32-code
+git fetch origin && git reset --hard origin/master
+docker compose -f .work/docker/docker-compose.yml up -d --force-recreate --build
+```
+
+或触发 1Panel 计划任务 `ht32-code-mcp-update`（每天 02:30）：同步 → HEAD 变化才删旧索引 →
+重建容器 → 清理过期 bundle / 日志。
+
+**PyPI 发布**（改了 `.work/mcp-server/src/` 就必须发版）：
+
+```bash
+cd .work/mcp-server
+uv run --extra dev pytest
+python smoke_stdio.py
+uv lock && uv build && uv publish     # token 在仓库根 .env 的 UV_PUBLISH_TOKEN
+```
+
+- 两处版本号必须同步：`pyproject.toml` 的 `version` 与 `VERSION` 末行 `MCP Server:`
+- 发布前清理 `dist/`，否则会把旧包一起上传
+- 发布后 `get_code_version` 应返回新版本；仍是旧版则查服务器 `git pull` 与容器重建
+
+> 线上跑的是 **PyPI 包**，`/vol1/1000/SSD/docker/ht32-code` 只是被检索的数据源。
+> 改仓库文件本身不生效——必须发版 + 重建容器。
+
+## 排查
+
+```bash
+docker logs --tail 100 ht32-code-mcp     # 启动参数、组件目录校验、请求日志都在这里
+docker exec -it ht32-code-mcp sh         # 进容器
+curl -s http://127.0.0.1:8001/health     # 容器内健康检查（宿主 18081）
+curl -s -o /dev/null -w "%{http_code}" https://mcp.s621.work/ht32-code   # 400 = 服务在（正常，缺 MCP 头）
+```
+
+- 启动日志应含 `启动服务: Streamable HTTP 0.0.0.0:8001/ht32-code（stateless=False, json=False）`；
+  若仍见 supergateway / `--stateful`，说明服务器 compose 未同步或镜像未重建
+- 协议版本被拒 → 旧镜像或旧客户端；本版直接由 FastMCP 4.x 提供，不再经 supergateway
+- `/health` 404 → 进程是旧版（`MCP_PATH` 之前的版本没有该路由）
+- 容器 126 退出 → 旧 compose 的 `$$(...)` 命令替换被吃掉；新版无 `command`，重新 `git pull` 即可
+- 首会话超时 → 冷启动（索引加载）；容器健康检查 `start_period: 60s` 已留余量

{ht32_code_mcp-0.4.6 → ht32_code_mcp-0.5.0}/PKG-INFO

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

{ht32_code_mcp-0.4.6 → ht32_code_mcp-0.5.0}/pyproject.toml

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

{ht32_code_mcp-0.4.6 → ht32_code_mcp-0.5.0}/src/ht32_code_mcp/server.py

@@ -64,6 +64,11 @@ LOG_DIR = resolve_log_dir(FEEDBACK_ROOT, SERVICE_CODE)
 # 默认 8101 而非 8100：wiki 占用 8100，两服务常同机部署，避开默认端口冲突
 HOST = os.environ.get("MCP_HOST", "0.0.0.0")
 PORT = _env_int("MCP_PORT", 8101)
+# HTTP 端点路径：生产由 compose 注入 /ht32-code；默认 /mcp 保持本地 smoke 测试不变
+MCP_PATH = os.environ.get("MCP_PATH", "/mcp")
+# P0 先保留进程内有状态会话（兼容现有客户端与热身脚本）；要多副本时再开 1
+STATELESS_HTTP = os.environ.get("MCP_STATELESS_HTTP", "0") != "0"
+JSON_RESPONSE = os.environ.get("MCP_JSON_RESPONSE", "0") != "0"
 
 index = CodeIndex(CODE_ROOT).load()
 knowledge = KnowledgeSearch(CODE_ROOT)
@@ -171,6 +176,15 @@ M0+（HT32F5 / L5）、M3（HT32F1 / F175x-275x）、M4（F490x1 / F491x3 / F493
 
 mcp = FastMCP("ht32-code", instructions=_INSTRUCTIONS)
 
+
+@mcp.custom_route("/health", methods=["GET"])
+async def _health(_request):
+    """容器健康检查：不触发检索，不占线程池。"""
+    from starlette.responses import JSONResponse
+
+    return JSONResponse({"status": "ok", "version": _MCP_VERSION})
+
+
 # 用量日志：服务端自动记录所有工具调用（FEEDBACK_ROOT 为空则不启用）
 if LOG_DIR:
     mcp.add_middleware(UsageMiddleware(
@@ -945,8 +959,19 @@ def main() -> None:
         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] 启动服务: Streamable HTTP {HOST}:{PORT}", file=sys.stderr)
-        mcp.run(transport="streamable-http", host=HOST, port=PORT)
+        print(
+            f"[ht32-code-mcp] 启动服务: Streamable HTTP {HOST}:{PORT}{MCP_PATH}"
+            f"（stateless={STATELESS_HTTP}, json={JSON_RESPONSE}）",
+            file=sys.stderr,
+        )
+        mcp.run(
+            transport="streamable-http",
+            host=HOST,
+            port=PORT,
+            path=MCP_PATH,
+            stateless_http=STATELESS_HTTP,
+            json_response=JSON_RESPONSE,
+        )
 
 
 if __name__ == "__main__":

{ht32_code_mcp-0.4.6 → ht32_code_mcp-0.5.0}/uv.lock

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

ht32_code_mcp-0.4.6/DEPLOY.md

@@ -1,547 +0,0 @@
-# MCP Server 部署指南（ht32-code）
-
-HT32 Code MCP Server 的部署、配置与排错。代码在 `.work/mcp-server/`，已发布到 PyPI（`ht32-code-mcp`）。
-
-## 部署信息
-
-```
-MCP Server 地址（Streamable HTTP）: https://mcp.s621.work/ht32-code
-PyPI 包:              https://pypi.org/project/ht32-code-mcp/（uvx ht32-code-mcp 即可运行）
-Bundle 下载地址:       https://mcp.s621.work/ht32-bundles/<token>.zip
-本地 Gitea:            http://100.66.1.6:3000/S621/ht32-code.git
-MCP Server 代码:       .work/mcp-server/
-```
-
-## 部署链路
-
-```
-PyPI 发布包 → 1Panel 原生 MCP 管理（类型 uvx，启动命令 uvx ht32-code-mcp，输出类型 streamableHttp）
-            → supergateway 包装 stdio 为 Streamable HTTP（stateful）
-            → OpenResty 暴露公网
-              ├─ /ht32-code/*      → MCP 协议端点（反向代理到容器）
-              └─ /ht32-bundles/*   → bundle zip 静态目录（P1-3）
-```
-
-代码默认走 `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 1800000` 语义一致。
-> 若将来需要 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 1800000`），云端反代只认固定的容器端口/路径，
-  换服务或改内部实现时反代无需跟着动
-
-原生 `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 表单：
-
-- 类型：`uvx`
-- 启动命令：`uvx ht32-code-mcp`（**必须带 uvx 前缀**，容器里没装裸命令）
-- 输出类型：`streamableHttp`
-- 流式传输路径：`/ht32-code`（切输出类型后是**新字段**，默认空，必须手填；必填校验）
-- 协议版本：`2025-06-18`（1Panel 预填默认值，勿动；仅用于 supergateway 对下游 stdio 的 auto-init）
-- 镜像：`supercorp/supergateway:next-uvx`（**必须覆盖默认的 `:uvx`**——见下方踩坑）
-- 参数：`--stateful --sessionTimeout 1800000`（30 分钟；2026-09-23 由 3600000 下调）
-- 环境变量：`CODE_ROOT=/app/code`
-- 挂载：`/opt/ht32-code:/app/code`（**不用加 `:ro`**——`index/code_index.json`
-  已 gitignore 且容器内可能需重建，只读会阻断；容器路径不能有前导空格，否则 `invalid mount path`）
-
-### 镜像 tag 踩坑（2026-09-20）
-
-默认镜像 `supercorp/supergateway:uvx` 构建时解析到旧版
-`@modelcontextprotocol/sdk`（LATEST_PROTOCOL_VERSION=2025-06-18），新版客户端
-（Trae 发 `2025-11-25`）initialize 直接被拒：`Bad Request: Unsupported protocol
-version`。根因是 supergateway 3.4.3 对 SDK 声明的是浮动依赖 `^1.18.2`，镜像构建
-日期决定行为；`next-uvx`（4.0.0-rc.4）将 SDK **精确锁定 1.30.0**，无此问题。
-
-## 云端 zip 下载通道（P1-3，0.1.2+）
-
-`export_project_bundle` 有两种交付形态，**由服务端环境变量决定，调用方无需判断**：
-
-| 模式 | 触发条件 | 行为 |
-|---|---|---|
-| 云端 zip | `BUNDLE_DIR` 与 `BUNDLE_BASE_URL` **同时非空** | 打包到 `BUNDLE_DIR`，返回 `<BUNDLE_BASE_URL>/<token>.zip` + SHA256 + 过期时间 |
-| 本地目录 | 二者任一为空（默认） | 物化到 `out_dir`（须为空目录/不存在） |
-
-### 环境变量
-
-| 变量 | 默认 | 说明 |
-|------|------|------|
-| `BUNDLE_DIR` | 空（= 关闭云端模式） | 容器内 bundle 输出目录，须可写 |
-| `BUNDLE_BASE_URL` | 空（= 关闭云端模式） | 公网下载前缀，如 `https://mcp.s621.work/ht32-bundles` |
-| `BUNDLE_TTL_SECONDS` | `3600` | zip 有效期；每次 export 前顺带清理过期 zip |
-
-非数字的 `BUNDLE_TTL_SECONDS` 会静默回退默认值，不报错。
-
-### 实现要点
-
-- **token**：`secrets.token_urlsafe(24)`（192 bit 熵），文件名即 token；不可枚举、不可猜测
-- **物化在系统临时目录**（`tempfile.mkdtemp`）而非 bundle 目录——bundle 目录里只出现
-  最终 zip，中途失败的半成品不会暴露成可下载文件
-- **清理**：`sweep_expired()` 在每次 export 时按 mtime 删除超期 `*.zip`；
-  进程崩溃遗留的临时目录不影响交付（不在 bundle 目录内）
-- **TTL 到点不主动删**：靠下次 export 的 sweep 或 P1-2 定时脚本清理；过期后
-  重新调用工具即可拿新 URL
-
-### 服务器侧落地（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/1panel/www/sites/mcp.s621.work/index/ht32-bundles
-chmod 755 /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles
-```
-
-**第 2 步：1Panel 给 code-mcp 容器补挂载与环境变量**
-
-| 配置项 | 值 |
-|--------|-----|
-| 挂载 | `/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） |
-
-完整配置（含现有项）：
-
-```
-类型：        uvx
-启动命令：    uvx ht32-code-mcp
-输出类型：    streamableHttp
-流式传输路径：/ht32-code
-协议版本：    2025-06-18
-镜像：        supercorp/supergateway:next-uvx
-参数：        --stateful --sessionTimeout 1800000
-环境变量：    CODE_ROOT=/app/code
-            BUNDLE_DIR=/app/bundles
-            BUNDLE_BASE_URL=https://mcp.s621.work/ht32-bundles
-挂载：        /opt/ht32-code:/app/code
-            /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles:/app/bundles   ← 宿主机路径，非容器内路径
-```
-
-**第 3 步：OpenResty 无需任何配置**
-
-站点 root = `/opt/1panel/www/sites/mcp.s621.work/index`，映射到容器内
-`/www/sites/mcp.s621.work/index`。bundle 目录落在这个 root 之下子目录，
-静态文件天然可访问，**不用建反向代理、不用手写 location、不用改 compose**。
-
-> **不要为 bundles 建反向代理条目**：1Panel 反代 UI 表达不了静态 location
-> （后端代理地址必填，而静态目录没有后端）。若建了且后端留空，1Panel 生成的
-> location 会抢走 `/ht32-bundles/` 却不知从哪读文件 → 404。已有此类条目请删除。
-
-> **静态 location 无需 `proxy_*` 指令**：文件由 nginx 读盘直接返回，不用
-> `proxy_pass`，也不用 `proxy_read_timeout`——这与 code 的代理 location 形态不同属正常。
-
-> **权限**：1Panel 站点要求 `index` 目录下所有文件/目录属主与属组为 `1000`（见
-> 「网站目录」页提示，PHP 容器环境）。nginx worker 需可读该目录；zip 文件 644 /
-> 目录 755 正常可读。若验证时拿 403，先查属主属组与 SELinux 上下文。
-
-重载（改了容器挂载或环境变量时需重建 code-mcp；仅改文件无需重载 nginx）：
-
-```bash
-docker exec 1Panel-openresty-ih7J nginx -t
-```
-
-### 验证生效
-
-1. 调 `get_code_version`，应出现：
-
-   ```
-   云端 zip 下载：启用（TTL 3600s，https://mcp.s621.work/ht32-bundles）
-   ```
-
-   仍显示「未配置」→ 环境变量没注入成功（查变量名 / 容器是否重建）。
-
-2. 调 `export_project_bundle(chip="HT32F52352")`，应返回：
-
-   ```
-   下载 URL：https://mcp.s621.work/ht32-bundles/<token>.zip
-   有效期：3600 秒（至 ...）
-   大小：1.53 MB（455 文件）
-   SHA256：...
-   ```
-
-3. 浏览器/curl 拉该 URL：应得约 1.5 MB zip；`sha256sum` 与报告一致；
-   解压后 455 文件、`project/MDK_ARMv5/<工程名>.uvprojx` 在，UV4 编译 0E0W。
-
-4. 确认 `ls /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles` 只有 `*.zip`（无残留临时目录）。
-
-## 反馈与用量日志（P1-5，0.2.0+）
-
-> **与 ht32-wiki-mcp 统一**：两服务使用同一套实现（`usage.py`，两仓库逐字节
-> 相同的副本）、同一套目录约定（同根 + 服务子目录）、同一套字段。
-> 本服务写 `<FEEDBACK_ROOT>/code/`，wiki 写 `<FEEDBACK_ROOT>/wiki/`。
-
-两条通道，按 UTC 日期分文件（JSON Lines）：
-
-| 通道 | 文件 | 触发 | 记录内容 |
-|------|------|------|----------|
-| 用量日志 | `usage_*.jsonl` | **服务端自动**（middleware 拦截所有工具调用） | 工具名、参数原文（剔除 `limit`/`max_length`/`out_dir`）、耗时、成败、错误、客户端 session |
-| 反馈 | `feedback_*.jsonl` | **Agent 主动**（`submit_feedback` 工具） | 语义性问题：API 错 / 缺口 / 路径错 / 模板缺陷 |
-
-自动通道保证调用事实完整（不依赖 Agent 配合），用于追踪用户需求与生成的模板；
-反馈通道补 middleware 判断不了的语义问题。每条记录都带 `service` 字段
-（`code`），便于两服务日志合并分析。
-
-### `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
-```
-
-### 环境变量
-
-| 变量 | 默认 | 说明 |
-|------|------|------|
-| `FEEDBACK_ROOT` | 空（= **关闭**，本地开发默认不落盘） | 日志根目录，服务名子目录自动拼接；**必须填绝对路径**（如 `/app/feedback`，不要写 `app/feedback`） |
-| `CODE_LOG_DIR` | — | 已废弃，改用 `FEEDBACK_ROOT` |
-
-> ⚠️ **必须用绝对路径**：`FEEDBACK_ROOT=app/feedback` 会相对容器 WORKDIR
-> 解析。实测云端曾因漏写前导 `/`，`get_code_version` 显示为
-> `反馈与用量日志：启用（app/feedback/code）`——靠 WORKDIR 恰为 `/` 才侥幸
-> 落对位置，改镜像 WORKDIR 后会静默写到别处。验证时看输出路径是否以 `/` 开头。
-
-> **隐私**：参数按原文记录，`query` / `question` 可能含用户项目信息。
-> 该目录只应挂在受控服务器上，**不要提交进仓库**（定时脚本是
-> `git reset --hard` 镜像模式，写进仓库也会被覆盖丢失）。
-
-### 服务器侧落地
-
-**第 1 步：宿主机建目录**
-
-```bash
-mkdir -p /opt/ht32-mcp-feedback
-chmod 755 /opt/ht32-mcp-feedback
-```
-
-**第 2 步：两个 MCP 容器都挂同一卷**
-
-| 服务 | 挂载 | 环境变量 |
-|------|------|----------|
-| 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
-启动命令：    uvx ht32-code-mcp
-输出类型：    streamableHttp
-流式传输路径：/ht32-code
-协议版本：    2025-06-18
-镜像：        supercorp/supergateway:next-uvx
-参数：        --stateful --sessionTimeout 1800000
-环境变量：    CODE_ROOT=/app/code
-            BUNDLE_DIR=/app/bundles
-            BUNDLE_BASE_URL=https://mcp.s621.work/ht32-bundles
-            FEEDBACK_ROOT=/app/feedback
-挂载：        /opt/ht32-code:/app/code
-            /opt/1panel/www/sites/mcp.s621.work/index/ht32-bundles:/app/bundles
-            /opt/ht32-mcp-feedback:/app/feedback
-```
-
-### 验证
-
-1. 调 `get_code_version`，应出现
-   `反馈与用量日志：启用（/app/feedback/code）`。
-   仍显示「未配置」→ 环境变量没注入（查变量名 / 容器是否重建）。
-
-2. 随便调几个工具，然后看日志：
-
-   ```bash
-   tail -3 /opt/ht32-mcp-feedback/code/usage_$(date -u +%Y-%m-%d).jsonl
-   ```
-
-3. 统计被请求的芯片型号（指导 P2-1 排优先级）——用 ht32-skills 的分析工具：
-
-   ```bash
-   # 克隆 ht32-skills 后（或用本地副本）
-   python ht32-skills/scripts/analyze_feedback.py /opt/ht32-mcp-feedback
-   ```
-
-   该工具（零依赖，仅标准库）合并 wiki + code 两服务日志，输出需求信号、
-   调用分布与失败、反馈类型、耗时 p50/p95、最近失败与反馈明细；支持
-   `--days N` / `--service` / `--json`。详见 ht32-skills 的 README。
-
-4. 清理策略由定时同步脚本第 7 步负责（`LOG_KEEP_DAYS=30`，与同步日志同口径，
-   目录变量为 `FEEDBACK_ROOT`）。
-
-## 私有组件（0.4.5+）
-
-让 MCP 用户发现私有 Git 组件（BSP / 中间件 / 驱动包），检索/读取源码，并把**选定 tag 的
-源码快照**并入导出工程。组件对全部 MCP 用户可见、可导出；新增组件只改仓库内登记表，
-不改 MCP 代码或 Skill。
-
-```
-用户 → MCP: list_components / get_component_info / search_component_code / read_component_file
-          export_project_bundle(components=["<id>@<tag>"])
-MCP 服务端 → 仓库内登记表（默认 .work/components/components.json）→ remotes 映射 → 私有 Git（本机路径或私有网络）
-```
-
-### 环境变量
-
-| 变量 | 默认 | 说明 |
-|------|------|------|
-| `COMPONENTS_CONFIG` | `.work/components/components.json`（文件存在即启用） | 组件目录 JSON 路径；显式配置优先。文件存在但配置无效时**服务启动失败**（错误定位到组件 ID/字段） |
-| `COMPONENTS_STATE_FILE` | `<临时目录>/ht32-component-cache/tag-lock.json` | tag→commit 台账（检测 tag 被强制移动）；生产建议放持久卷（compose 已指向 `/app/feedback/component-tag-lock.json`） |
-| `COMPONENT_GIT_TIMEOUT` | `60` | 单次 Git 操作超时（秒） |
-
-**运行时依赖 `git` + 私有仓库凭据**（两者缺一，组件工具都会返回
-`[COMPONENT_REMOTE_UNAVAILABLE]`）：
-
-1. **镜像**：官方 `supercorp/supergateway:next-uvx` 默认不带 git。同目录
-   [`.work/docker/Dockerfile`](../docker/Dockerfile) 在其上补装 git（自动适配
-   apt/apk），compose 已改为 `image: ht32-code-mcp:0.4.5-git` + `build: .`：
-
-   ```bash
-   cd /vol1/1000/SSD/docker/ht32-code/.work/docker
-   docker compose build ht32-code-mcp     # 首次；之后同步脚本带 --build 会自动复用缓存
-   docker compose up -d --force-recreate ht32-code-mcp
-   docker exec ht32-code-mcp git --version     # 必须打印版本
-   ```
-
-2. **凭据**：内网 Gitea 仓库非公开，匿名 `git ls-remote` 返回 **403**（可用
-   `curl -i http://100.66.1.6:3000/api/v1/repos/S621/HT32_BSP/tags` 复核）。在部署机
-   `.work/docker/.env`（已被 `.gitignore` 忽略）写入 Basic 凭据：
-
-   ```bash
-   # Gitea → 设置 → 应用 → 生成令牌，权限只需 read:repository
-   printf 'COMPONENTS_GIT_AUTH=%s\n' \
-     "$(printf '%s:%s' '<Gitea 用户名>' '<只读 token>' | base64 -w0)" > .env
-   chmod 600 .env
-   ```
-
-   compose 以 `GIT_CONFIG_COUNT/KEY_0/VALUE_0` 注入 `http.extraheader`，只存在于
-   容器进程环境；不写入仓库、日志或 MCP 响应。轮换 token 后改 `.env` 并重建容器。
-
-3. **验证**：容器内直接执行（无需再带 `-c`，凭据由环境注入）：
-
-   ```bash
-   docker exec ht32-code-mcp git ls-remote http://100.66.1.6:3000/S621/LwFSM.git | tail -2
-   ```
-
-   能列出 `refs/tags/V2.0` 即表示 git 与凭据都就位。纯检索/导出模板不依赖 git，不受影响。
-
-### 源码裁剪（`export.redact`，0.4.6+）
-
-面向“只交付 `.lib`、不给源码”的组件。**不执行仓库里的 `script/submodule.bat`**
-（Linux 无 cmd，且执行仓库脚本等于远程执行），改为快照层的等价内置规则：
-
-| 模式 | 行为 |
-|---|---|
-| `none`（默认） | 不裁剪 |
-| `auto` | 仅当仓库含 `script/submodule.bat` 时，按下面的规则裁剪 |
-| `lib-only` | 无条件裁剪 |
-
-`lib-only` 规则（路径相对导出根，大小写不敏感）：
-
-1. 移除根目录 `project/`；
-2. `lib/<name>.lib` 存在 → 移除 `src/<name>.c`；
-3. `tools/InfoProcess.exe` 存在 → 移除 `tools/InfoProcess.c`；
-4. `script/` 保留。
-
-裁剪发生在**快照构建阶段**，因此 `read_component_file`、`search_component_code`
-与导出都看不到被移除的源文件；`manifest/components-lock.json` 会记录
-`redaction.mode` 与逐条 `removed`（路径 + 原因），便于审计。
-
-### 组件登记表放在哪里
-
-**放在 ht32-code 仓库里**：`.work/components/components.json`，随仓库提交、回滚、blame。
-
-```
-ht32-code（私有仓库，服务器 /vol1/1000/SSD/docker/ht32-code → 容器 /app/code）
-└─ .work/components/components.json     ← 登记表（真实 remote 地址在这里）
-```
-
-- **好处**：新增组件 = 一次 commit；服务器更新脚本 `git fetch + git reset --hard origin/master`
-  后自动生效；历史用 `git log -p .work/components/components.json` 查，回滚用
-  `git checkout <commit> -- .work/components/components.json`；**不需要发 MCP 版本**。
-- **不进 PyPI**：wheel 只打包 `src/ht32_code_mcp`；sdist 已在
-  `pyproject.toml` 的 `[tool.hatch.build.targets.sdist].exclude` 排除 `.work/components`。
-  发布前可 `uv build` 后检查 `tar -tzf dist/*.tar.gz | grep components` 应为空。
-- **前提：仓库必须保持私有**。若 ht32-code 将来转为公开，必须先把登记表移出仓库
-  （改回私有目录挂载或独立私有配置仓库），否则组件清单与内网地址会随仓库泄露。
-- 登记表可选写 `catalog_version`（人工标签）；服务端另算 `catalog_sha256`（文件内容哈希）
-  与所在仓库 `commit`，三者一起出现在 `get_code_version` / `list_components` /
-  `components-lock.json`，用于反查“这次调用是哪一版登记表”。
-- 登记字段要点：`series` 按**族前缀**匹配（登记 `HT32F5` 即覆盖 `HT32F50241`
-  等同族型号，也支持 `HT32F49*` 通配）；`["*"]` 表示已确认覆盖全部型号；
-  `chips` 只用于展示“已验证型号”，不必穷举同族全部 IC；`list_components(query=...)`
-  也接受型号。
-- 加载器**支持 `//` 与 `/* */` 注释**（字符串里的 `//` 不受影响；不支持尾随逗号）；
-  逐字段说明见带注释的 `components.example.json`，**正式登记表建议保持纯 JSON**。
-  注释计入文件内容哈希——改注释等同于换了一版登记表。
-
-### 服务器侧落地
-
-**第 1 步：在仓库里提交登记表**
-
-```powershell
-# 维护者本地（ht32-code 仓库）
-mkdir -Path .work\components
-# 写入 components.json（结构见 components.example.json）
-git add .work/components/components.json
-git commit -m "feat(components): 登记 HT32_BSP 与 LwFSM"
-git push
-```
-
-**第 2 步：服务器同步 + 重建**
-
-```bash
-# 手动：仓库已挂载到 /app/code，git reset 后重启容器即可
-cd /vol1/1000/SSD/docker/ht32-code && git fetch && git reset --hard origin/master
-docker compose -f .work/docker/docker-compose.yml up -d --force-recreate
-# 或等 1Panel 计划任务里的 ht32-code-mcp-update.md（每天 02:30）自动执行
-```
-
-不需要新建 `/app/components`、不需要额外挂载；`COMPONENTS_CONFIG` 已在 compose 指向
-`/app/code/.work/components/components.json`（即使不配，服务也会在默认位置发现它）。
-
-**第 3 步：验证**
-
-```bash
-docker logs ht32-code-mcp | grep "私有组件目录"
-# [ht32-code-mcp] 私有组件目录: 2 个组件（catalog 3f9a1c2b / commit 7f43dfc4 / tag 台账 ...）
-```
-
-配置无效时进程以退出码 2 结束，日志给出 `[COMPONENTS_CONFIG_INVALID] <字段>`。
-
-**第 4 步：工具验证**
-
-1. `get_code_version` 出现 `私有组件目录：已登记 N 个组件（catalog … / commit …）`。
-2. `list_components()` 列出登记组件与可用 tag（远端不可用时显示
-   `远端不可用（[COMPONENT_REMOTE_UNAVAILABLE] …）`，不回退 branch/HEAD）。
-3. `export_project_bundle(config_id=..., components=["<id>@<tag>"])` 的产物含
-   `components/<id>/` 与 `manifest/components-lock.json`（tag/commit/逐文件 SHA256，
-   以及 `catalog.sha256/commit/version` 登记表来源）。
-
-### 日常运维
-
-| 操作 | 做法 |
-|---|---|
-| 新增组件 | 编辑 `.work/components/components.json` → commit/push → 同步脚本（或手动 reset + 重建）；**不改 Skills、不发 MCP 版本** |
-| 刷新可用 tag | 组件维护者打 tag 即可；登记规则匹配的新 tag 自动出现（`git ls-remote` 每次查询） |
-| 下架/暂停组件 | 该条 `"status": "disabled"` → commit → 同步；列表显示为已停用，读取/导出明确拒绝 |
-| 回滚登记表 | `git checkout <commit> -- .work/components/components.json` → commit/push → 同步；或 `git revert <commit>` |
-| tag 漂移 | 同 tag 指向新 commit 时返回 `[COMPONENT_TAG_DRIFT]`（阻断）；维护者核实后删除台账里该行再重试 |
-| 查历史 | `git log -p -- .work/components/components.json`；工程侧看 `components-lock.json` 的 `catalog.commit` |
-| **不要**在服务器上直接改 | 更新脚本是 `git reset --hard`，手改会被覆盖；所有变更走仓库提交 |
-| 临时目录 | 每次读取/导出的浅克隆在系统临时目录，成功后立即清理 |
-| Git 不可达 | 短超时 + `[COMPONENT_REMOTE_UNAVAILABLE]`（错误信息已脱敏，不含 remote URL） |
-
-### 隐私/安全检查（发布或改配置后）
-
-```bash
-# 1) 公开产物（PyPI 包）不得含登记表
-uv build && tar -tzf dist/*.tar.gz | grep -i "\.work/components" && echo "泄漏！" || echo "OK"
-# wheel 只含 src/，可用 unzip -l dist/*.whl | grep components 复核
-
-# 2) 登记表本身不得含凭据（URL 可以，token/密码不行）
-git grep -nE "PRIVATE-TOKEN|password=|ssh://.*@" -- .work/components
-```
-
-## PyPI 包发布流程
-
-```bash
-# token 在 ht32-code 根目录 .env 的 UV_PUBLISH_TOKEN
-uv lock && uv build && uv publish
-```
-
-发布后同步 `VERSION` 文件末行：`MCP Server: <版本>（deployed, PyPI, <日期>）`。
-
-## 踩过的坑
-
-### 1. 云端跑的是 PyPI 包，不是 /opt 仓库（P0-1）
-
-- **症状**：改了仓库代码、云端 MCP 行为不变
-- **根因**：`uvx ht32-code-mcp` 从 PyPI 拉包，`/opt/ht32-code` 只是被检索的数据源
-- **修复**：改代码必须**发版 + 重建容器**，改仓库文件本身不生效
-
-### 2. 索引只读挂载
-
-- **症状**：容器启动报索引无法写入/重建失败
-- **根因**：`/opt/ht32-code:/app/code:ro` 时 `index/code_index.json` 不可写
-- **修复**：挂载去掉 `:ro`
-
-### 3. 镜像 tag 导致协议版本被拒
-
-见上方「镜像 tag 踩坑」。
-
-## 当前部署状态
-
-| # | 任务 | 说明 | 状态 |
-|---|------|------|------|
-| 3.1 | MCP 工具实现（7 检索/导出 + 4 私有组件 + 版本检查 + 1 反馈） | `.work/mcp-server/src/ht32_code_mcp/`（FastMCP） | ✅ |
-| 3.2 | 工具级测试 | `pytest` 46 用例全绿 | ✅ |
-| 3.3 | PyPI 发布（hatchling） | `ht32-code-mcp` 0.2.3（2026-09-24，含全系列固件库覆盖 + 6 模板多模板导出） | ✅ |
-| 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.9 | 反馈与用量日志（P1-5，与 wiki 统一） | 0.2.1；云端已启用，但 `FEEDBACK_ROOT` 漏写前导 `/`（显示 `app/feedback/code`），需改绝对路径 | ⚠️ |
-| 3.10 | 私有组件（0.4.5） | 登记表随仓库版本化；镜像 `ht32-code-mcp:0.4.5-git`（内置 git）+ 只读凭据注入；2026-11-02 线上验收：2 组件真实 tag、读/搜、导出 601 条目 / 组件 94 文件 / 无 `.git` | ✅ |