PyPI - ht32-code-mcp - Versions diffs - 0.4.5__tar.gz → 0.5.0__tar.gz - Mend

ht32-code-mcp 0.4.5tar.gz → 0.5.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (36) hide show

ht32_code_mcp-0.5.0/DEPLOY.md ADDED Viewed

@@ -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.5 → ht32_code_mcp-0.5.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ht32-code-mcp
-Version: 0.4.5
+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.5 → ht32_code_mcp-0.5.0}/components.example.json RENAMED Viewed

@@ -54,6 +54,13 @@
         "exclude": ["docs/", "tests/"],
         // 非空时只允许这些后缀，如 [".c", ".h"]；空 = 不限
         "allowed_suffixes": [],
+        // 源码裁剪（不执行仓库脚本）：none / auto / lib-only
+        //   none    = 不裁剪（默认）
+        //   auto    = 仅当仓库含 script/submodule.bat 时按下面的内置规则裁剪
+        //   lib-only= 无条件裁剪：移除 project/、删除有同名 lib/*.lib 的 src/*.c、
+        //             删除与 tools/InfoProcess.exe 同名的 .c；script/ 保留
+        // 裁剪在快照层生效，read/search/export 都看不到被移除的源码
+        "redact": "none",
         // 容量上限：文件数 / 单文件字节 / 总字节
         "max_files": 2000,
         "max_file_bytes": 2097152,

{ht32_code_mcp-0.4.5 → ht32_code_mcp-0.5.0}/pyproject.toml RENAMED Viewed

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

{ht32_code_mcp-0.4.5 → ht32_code_mcp-0.5.0}/src/ht32_code_mcp/component_exporter.py RENAMED Viewed

@@ -64,6 +64,7 @@ class PreparedComponents:
                 "files": [{"path": f.rel, "bytes": f.size, "sha256": f.sha256}
                           for f in snap.files],
                 "excluded": snap.excluded,
+                "redaction": {"mode": snap.redact_mode, "removed": snap.redacted},
                 "license": item.entry.license,
                 "maintainer": item.entry.maintainer,
             })

{ht32_code_mcp-0.4.5 → ht32_code_mcp-0.5.0}/src/ht32_code_mcp/component_source.py RENAMED Viewed

@@ -72,7 +72,8 @@ class Snapshot:
     def __init__(self, entry: ComponentEntry, tag: str, commit: str,
                  workdir: Path, archive: Path, files: list[SnapshotFile],
-                 excluded: list[dict]) -> None:
+                 excluded: list[dict], redact_mode: str = "none",
+                 redacted: list[dict] | None = None) -> None:
         self.entry = entry
         self.tag = tag
         self.commit = commit
@@ -80,6 +81,8 @@ class Snapshot:
         self.archive = archive
         self.files = files
         self.excluded = excluded
+        self.redact_mode = redact_mode
+        self.redacted = redacted or []
     @property
     def total_bytes(self) -> int:
@@ -285,19 +288,20 @@ class ComponentSource:
                     "只接受发布 tag 指向的提交")
             archive = workdir / "tree.zip"
             self._git(["archive", "--format=zip", f"--output={archive}", head], cwd=repo)
-            files, excluded = self._plan(archive, info.tag)
-            return Snapshot(self.entry, info.tag, info.commit, workdir, archive, files, excluded)
+            files, excluded, redact_mode, redacted = self._plan(archive, info.tag)
+            return Snapshot(self.entry, info.tag, info.commit, workdir, archive,
+                            files, excluded, redact_mode, redacted)
         except BaseException:
             _rmtree(workdir)
             raise
     # ---------------------------------------------------------- 文件计划
-    def _plan(self, archive: Path, tag: str) -> tuple[list[SnapshotFile], list[dict]]:
+    def _plan(self, archive: Path, tag: str
+              ) -> tuple[list[SnapshotFile], list[dict], str, list[dict]]:
         export = self.entry.export
         root_prefix = f"{export.root}/" if export.root else ""
-        files: list[SnapshotFile] = []
+        candidates: list[SnapshotFile] = []
         excluded: list[dict] = []
-        total = 0
         with zipfile.ZipFile(archive) as zf:
             for info in zf.infolist():
                 if info.is_dir():
@@ -323,20 +327,39 @@ class ComponentSource:
                 if export.allowed_suffixes and not name.lower().endswith(export.allowed_suffixes):
                     raise _path_rejected(
                         f"组件文件类型不在登记允许列表（{list(export.allowed_suffixes)}）：{name}")
-                if info.file_size > export.max_file_bytes:
-                    raise ComponentError(
-                        COMPONENT_LIMIT_EXCEEDED,
-                        f"组件 '{self.entry.id}' 的 {name} 为 {info.file_size} 字节，"
-                        f"超过单文件上限 {export.max_file_bytes}")
-                total += info.file_size
-                files.append(SnapshotFile(
+                candidates.append(SnapshotFile(
                     rel=name, size=info.file_size,
                     sha256=hashlib.sha256(zf.read(info)).hexdigest(), zip_name=info.filename))
+        if not candidates:
+            raise ComponentError(
+                COMPONENT_TAG_NOT_FOUND,
+                f"组件 '{self.entry.id}' 在 tag '{tag}' 的导出根 "
+                f"'{export.root or '.'}' 下没有可导出文件")
+        redact_mode, removed = _redaction_plan(export.redact, [f.rel for f in candidates])
+        files: list[SnapshotFile] = []
+        redacted: list[dict] = []
+        for item in candidates:
+            reason = removed.get(item.rel.lower())
+            if reason:
+                redacted.append({"path": item.rel, "reason": reason})
+                excluded.append({"path": item.rel, "reason": reason})
+            else:
+                files.append(item)
         if not files:
             raise ComponentError(
                 COMPONENT_TAG_NOT_FOUND,
                 f"组件 '{self.entry.id}' 在 tag '{tag}' 的导出根 "
                 f"'{export.root or '.'}' 下没有可导出文件")
+        total = 0
+        for item in files:
+            if item.size > export.max_file_bytes:
+                raise ComponentError(
+                    COMPONENT_LIMIT_EXCEEDED,
+                    f"组件 '{self.entry.id}' 的 {item.rel} 为 {item.size} 字节，"
+                    f"超过单文件上限 {export.max_file_bytes}")
+            total += item.size
         if len(files) > export.max_files:
             raise ComponentError(
                 COMPONENT_LIMIT_EXCEEDED,
@@ -345,7 +368,36 @@ class ComponentSource:
             raise ComponentError(
                 COMPONENT_LIMIT_EXCEEDED,
                 f"组件 '{self.entry.id}' 总字节 {total} 超过上限 {export.max_total_bytes}")
-        return sorted(files, key=lambda f: f.rel), excluded
+        return sorted(files, key=lambda f: f.rel), excluded, redact_mode, redacted
+def _redaction_plan(mode: str, names: list[str]) -> tuple[str, dict[str, str]]:
+    """源码裁剪：等价于组件仓库的 `script/submodule.bat`，但**不执行**任何脚本。
+    规则（路径相对组件导出根，大小写不敏感）：
+      - 移除根目录 `project/`（示例/测试工程）；
+      - `lib/<name>.lib` 存在时，移除 `src/<name>.c`；
+      - `tools/InfoProcess.exe` 存在时，移除 `tools/InfoProcess.c`；
+      - `script/` 保留。
+    `auto` 仅当检测到 `script/submodule.bat` 时生效；`lib-only` 无条件生效。
+    返回 (生效模式, {小写路径: 原因})。
+    """
+    if mode == "none":
+        return "none", {}
+    lowered = [n.lower() for n in names]
+    if mode == "auto" and "script/submodule.bat" not in lowered:
+        return "none", {}
+    libs = {Path(n).stem for n in lowered if re.fullmatch(r"lib/[^/]+\.lib", n)}
+    has_tool_exe = "tools/infoprocess.exe" in lowered
+    removed: dict[str, str] = {}
+    for name in lowered:
+        if name.startswith("project/"):
+            removed[name] = "redact:project-dir"
+        elif re.fullmatch(r"src/[^/]+\.c", name) and Path(name).stem in libs:
+            removed[name] = "redact:source-replaced-by-lib"
+        elif has_tool_exe and name == "tools/infoprocess.c":
+            removed[name] = "redact:tool-source"
+    return "lib-only", removed
 def _unsafe_member(name: str) -> bool:

{ht32_code_mcp-0.4.5 → ht32_code_mcp-0.5.0}/src/ht32_code_mcp/components.py RENAMED Viewed

@@ -53,9 +53,11 @@ _COMPONENT_KEYS = {
 _TAGS_KEYS = {"include", "exclude"}
 _EXPORT_KEYS = {
     "root", "target", "exclude", "allowed_suffixes",
-    "max_files", "max_file_bytes", "max_total_bytes",
+    "max_files", "max_file_bytes", "max_total_bytes", "redact",
 }
+REDACT_MODES = ("none", "auto", "lib-only")
 DEFAULT_MAX_FILES = 2000
 DEFAULT_MAX_FILE_BYTES = 2 * 1024 * 1024
 DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024
@@ -82,6 +84,8 @@ class ExportPolicy:
     max_files: int = DEFAULT_MAX_FILES
     max_file_bytes: int = DEFAULT_MAX_FILE_BYTES
     max_total_bytes: int = DEFAULT_MAX_TOTAL_BYTES
+    # 源码裁剪：none / auto（检测到 script/submodule.bat 才裁剪）/ lib-only
+    redact: str = "none"
 @dataclass(frozen=True)
@@ -308,6 +312,10 @@ def _parse_export(data: dict, where: str, component_id: str) -> ExportPolicy:
     else:
         target = f"components/{component_id}"
     excludes = _str_list(block, "exclude", f"{where}.export")
+    redact = (_optional_str(block, "redact", f"{where}.export") or "none").strip().lower()
+    if redact not in REDACT_MODES:
+        raise _fail(f"{where}.export.redact",
+                    f"只支持 {' / '.join(REDACT_MODES)}，当前为 '{redact}'")
     suffixes = tuple(s if s.startswith(".") else "." + s
                      for s in _str_list(block, "allowed_suffixes", f"{where}.export"))
     max_files = _int_field(block, "max_files", f"{where}.export", DEFAULT_MAX_FILES)
@@ -319,7 +327,8 @@ def _parse_export(data: dict, where: str, component_id: str) -> ExportPolicy:
         raise _fail(f"{where}.export", "max_files 超出合理上限（100000）")
     return ExportPolicy(root=root, target=target, exclude=excludes,
                         allowed_suffixes=suffixes, max_files=max_files,
-                        max_file_bytes=max_file, max_total_bytes=max_total)
+                        max_file_bytes=max_file, max_total_bytes=max_total,
+                        redact=redact)
 def _parse_component(raw: object, index: int, remotes: dict[str, str],

{ht32_code_mcp-0.4.5 → ht32_code_mcp-0.5.0}/src/ht32_code_mcp/server.py RENAMED Viewed

@@ -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(
@@ -702,6 +716,9 @@ def get_component_info(component_id: str) -> str:
     lines.append(f"- tag 规则：include={list(entry.tag_include)}，"
                  f"exclude={list(entry.tag_exclude)}")
     lines.extend(describe_tags(tags, err, limit=50))
+    if entry.export.redact != "none":
+        lines.append(f"- 源码裁剪：{entry.export.redact}"
+                     "（移除 project/、有同名 .lib 的 src/*.c、InfoProcess.c；读/搜/导出统一生效）")
     export = entry.export
     lines += [
         f"- 导出落点：{entry.target}/（仓库导出根：{export.root or '.'}）",
@@ -942,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.5.0/tests/test_component_redact.py ADDED Viewed

@@ -0,0 +1,125 @@
+"""组件源码裁剪：等价 `script/submodule.bat`，但不在服务端执行任何脚本。"""
+from __future__ import annotations
+import pytest
+from conftest import catalog_document, commit_all, git, write
+from ht32_code_mcp.component_exporter import ComponentService
+from ht32_code_mcp.component_source import (ComponentSource, TagLockStore,
+                                            _redaction_plan)
+from ht32_code_mcp.components import ComponentError, parse_catalog
+@pytest.fixture
+def redact_repo(tmp_path):
+    if not __import__("shutil").which("git"):
+        pytest.skip("环境无 git，跳过源码裁剪测试")
+    repo = tmp_path / "iap-repo"
+    repo.mkdir()
+    git(repo, "init", "-q")
+    write(repo, "README.md", "# HT32 IAP\n")
+    write(repo, "inc/ht32_iap.h", "void iap_init(void);\n")
+    write(repo, "src/ht32_iap.c", "void iap_init(void) {}\n")
+    write(repo, "src/ht32_iap_cache.c", "void cache_init(void) {}\n")
+    write(repo, "src/extra.c", "void extra(void) {}\n")
+    write(repo, "project/test/main.c", "int main(void) { return 0; }\n")
+    write(repo, "tools/InfoProcess.c", "int main(void) { return 0; }\n")
+    (repo / "tools" / "InfoProcess.exe").write_bytes(b"MZ")
+    (repo / "lib").mkdir()
+    (repo / "lib" / "ht32_iap.lib").write_bytes(b"LIB-1")
+    (repo / "lib" / "ht32_iap_cache.lib").write_bytes(b"LIB-2")
+    write(repo, "script/submodule.bat", "@echo off\r\n")
+    commit = commit_all(repo, "iap v1")
+    git(repo, "tag", "v1.0.0")
+    return {"path": repo, "commit": commit}
+def _catalog(redact: str, remote: str = "https://git.example.invalid/org/iap.git"):
+    doc = catalog_document(remote)
+    doc["components"][0]["export"] = {"target": "", "redact": redact}
+    return parse_catalog(doc)
+def _source(repo, tmp_path, redact: str) -> ComponentSource:
+    catalog = _catalog(redact)
+    return ComponentSource(catalog.get("ht32_bsp"), str(repo),
+                           work_root=tmp_path / "work", timeout=120,
+                           tag_locks=TagLockStore(None))
+def test_redaction_plan_auto_requires_script():
+    names = ["src/a.c", "lib/a.lib", "project/main.c"]
+    assert _redaction_plan("auto", names) == ("none", {})
+def test_redaction_plan_lib_only_rules():
+    names = ["src/a.c", "src/b.c", "lib/a.lib", "project/x/main.c",
+             "tools/InfoProcess.c", "tools/InfoProcess.exe",
+             "script/submodule.bat"]
+    mode, removed = _redaction_plan("lib-only", names)
+    assert mode == "lib-only"
+    assert set(removed) == {"src/a.c", "project/x/main.c", "tools/infoprocess.c"}
+    assert removed["src/a.c"] == "redact:source-replaced-by-lib"
+def test_snapshot_redacts_sources_but_keeps_lib_header_and_script(redact_repo, tmp_path):
+    src = _source(redact_repo["path"], tmp_path, "auto")
+    snap = src.snapshot("v1.0.0")
+    try:
+        rels = {f.rel for f in snap.files}
+        assert snap.redact_mode == "lib-only"
+        assert "project/test/main.c" not in rels
+        assert "src/ht32_iap.c" not in rels
+        assert "src/ht32_iap_cache.c" not in rels
+        assert "tools/InfoProcess.c" not in rels
+        assert "src/extra.c" in rels
+        assert "lib/ht32_iap.lib" in rels
+        assert "inc/ht32_iap.h" in rels
+        assert "tools/InfoProcess.exe" in rels
+        assert "script/submodule.bat" in rels
+        reasons = {r["path"]: r["reason"] for r in snap.redacted}
+        assert reasons["src/ht32_iap.c"] == "redact:source-replaced-by-lib"
+        assert reasons["project/test/main.c"] == "redact:project-dir"
+        assert reasons["tools/InfoProcess.c"] == "redact:tool-source"
+    finally:
+        snap.close()
+def test_snapshot_redact_none_keeps_everything(redact_repo, tmp_path):
+    src = _source(redact_repo["path"], tmp_path, "none")
+    snap = src.snapshot("v1.0.0")
+    try:
+        rels = {f.rel for f in snap.files}
+        assert "project/test/main.c" in rels
+        assert "src/ht32_iap.c" in rels
+        assert snap.redact_mode == "none"
+        assert snap.redacted == []
+    finally:
+        snap.close()
+def test_export_lock_records_redaction(redact_repo, tmp_path):
+    catalog = _catalog("auto", str(redact_repo["path"]))
+    svc = ComponentService(lambda: catalog, work_root=tmp_path / "work", timeout=120)
+    prepared = svc.prepare(["ht32_bsp@v1.0.0"])
+    try:
+        lock = prepared.lock_document()
+        row = lock["components"][0]
+        assert row["redaction"]["mode"] == "lib-only"
+        removed = {r["path"] for r in row["redaction"]["removed"]}
+        assert removed == {"project/test/main.c", "src/ht32_iap.c",
+                           "src/ht32_iap_cache.c", "tools/InfoProcess.c"}
+        exported = {f["path"] for f in row["files"]}
+        assert "src/ht32_iap.c" not in exported
+        assert "lib/ht32_iap.lib" in exported
+    finally:
+        prepared.close()
+def test_registry_rejects_unknown_redact_mode():
+    doc = catalog_document("https://git.example.invalid/org/repo.git")
+    doc["components"][0]["export"]["redact"] = "all"
+    with pytest.raises(ComponentError) as err:
+        parse_catalog(doc)
+    assert err.value.code == "COMPONENTS_CONFIG_INVALID"
+    assert "redact" in err.value.message

{ht32_code_mcp-0.4.5 → ht32_code_mcp-0.5.0}/uv.lock RENAMED Viewed

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

ht32_code_mcp-0.4.5/DEPLOY.md DELETED Viewed

@@ -1,494 +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`**：组件工具通过服务端 `git` 读取远端。部署前先确认容器内可用
-（`docker exec ht32-code-mcp git --version`）；不可用时组件工具返回
-`[COMPONENT_REMOTE_UNAVAILABLE] 服务端未安装 git`，需自建带 git 的镜像或改用带 git 的运行时。
-纯检索/导出模板不依赖 git，不受影响。
-### 组件登记表放在哪里
-**放在 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） | 登记表随仓库版本化（`.work/components/components.json`，无额外挂载）；容器内需有 `git` | ⏳ 待用户部署 |