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

{ht32_code_mcp-0.4.5 → ht32_code_mcp-0.4.6}/DEPLOY.md

@@ -350,10 +350,63 @@ MCP 服务端 → 仓库内登记表（默认 .work/components/components.json
 | `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，不受影响。
+**运行时依赖 `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`（路径 + 原因），便于审计。
 
 ### 组件登记表放在哪里
 
@@ -491,4 +544,4 @@ uv lock && uv build && uv publish
 | 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` | ⏳ 待用户部署 |
+| 3.10 | 私有组件（0.4.5） | 登记表随仓库版本化；镜像 `ht32-code-mcp:0.4.5-git`（内置 git）+ 只读凭据注入；2026-11-02 线上验收：2 组件真实 tag、读/搜、导出 601 条目 / 组件 94 文件 / 无 `.git` | ✅ |

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ht32-code-mcp
-Version: 0.4.5
+Version: 0.4.6
 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.4.6}/components.example.json

@@ -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.4.6}/pyproject.toml

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

{ht32_code_mcp-0.4.5 → ht32_code_mcp-0.4.6}/src/ht32_code_mcp/component_exporter.py

@@ -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.4.6}/src/ht32_code_mcp/component_source.py

@@ -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.4.6}/src/ht32_code_mcp/components.py

@@ -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.4.6}/src/ht32_code_mcp/server.py

@@ -702,6 +702,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 '.'}）",

ht32_code_mcp-0.4.6/tests/test_component_redact.py

@@ -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.4.6}/uv.lock

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