feat(extensions): add ZIP installation and unify action dialogs

backend/app/extensions/archive.py

@@ -0,0 +1,99 @@
+"""Bounded ZIP extraction for packages uploaded to the AI Core host."""
+from __future__ import annotations
+
+import io
+import re
+import shutil
+import stat
+import tempfile
+import zipfile
+import zlib
+from pathlib import Path
+from collections.abc import Callable
+from typing import TypeVar
+
+from app.errors import ApiError
+from app.extensions.errors import ExtensionError
+
+MAX_ZIP_BYTES = 10 * 1024 * 1024
+MAX_EXPANDED_BYTES = 50 * 1024 * 1024
+MAX_ENTRIES = 2048
+T = TypeVar('T')
+
+
+def invalid(message: str) -> ApiError:
+    return ApiError(422, 'EXTENSION_ZIP_INVALID', message)
+
+
+def install_zip(data: bytes, kind: str, storage: Path, install: Callable[[Path], T]) -> T:
+    if len(data) > MAX_ZIP_BYTES:
+        raise ApiError(413, 'EXTENSION_ZIP_TOO_LARGE', 'ZIP 文件不能超过 10 MiB。')
+    if kind not in ('skill', 'plugin'):
+        raise ValueError('Unknown extension kind')
+    storage.mkdir(parents=True, exist_ok=True)
+    # Retain successful extraction: Plugin commands and resources use this directory.
+    destination = Path(tempfile.mkdtemp(prefix=f'{kind}-', dir=storage))
+    try:
+        with zipfile.ZipFile(io.BytesIO(data)) as archive:
+            entries = archive.infolist()
+            if not entries or len(entries) > MAX_ENTRIES:
+                raise invalid('ZIP 为空或文件条目超过 2048 个。')
+            seen: set[str] = set()
+            spellings: dict[str, str] = {}
+            total = 0
+            for entry in entries:
+                name = entry.filename.rstrip('/')
+                parts = name.split('/')
+                if (entry.orig_filename != entry.filename or '\\' in name
+                    or any(not p or p in ('.', '..') or any(c in p for c in ':*?<>|"') or p.endswith((' ', '.'))
+                           or any(ord(c) < 32 for c in p)
+                           or re.match(r'^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)', p, re.I)
+                           for p in parts)):
+                    raise invalid('ZIP 包含不安全的文件路径。')
+                mode = stat.S_IFMT(entry.external_attr >> 16)
+                if mode not in (0, stat.S_IFREG, stat.S_IFDIR) or entry.flag_bits & 1:
+                    raise invalid('ZIP 不支持链接、特殊文件或加密条目。')
+                if entry.compress_type not in (zipfile.ZIP_STORED, zipfile.ZIP_DEFLATED):
+                    raise invalid('ZIP 仅支持 stored/deflate 压缩。')
+                key = name.casefold()
+                if key in seen:
+                    raise invalid('ZIP 包含重复或大小写冲突的路径。')
+                seen.add(key)
+                for index in range(1, len(parts) + 1):
+                    prefix = '/'.join(parts[:index])
+                    if spellings.setdefault(prefix.casefold(), prefix) != prefix:
+                        raise invalid('ZIP 包含大小写冲突的目录。')
+                total += entry.file_size
+                if total > MAX_EXPANDED_BYTES:
+                    raise ApiError(413, 'EXTENSION_ZIP_TOO_LARGE', 'ZIP 解压后不能超过 50 MiB。')
+                target = destination.joinpath(*parts)
+                if not target.resolve().is_relative_to(destination.resolve()):
+                    raise invalid('ZIP 路径超出包目录。')
+            written = 0
+            for entry in entries:
+                target = destination.joinpath(*entry.filename.rstrip('/').split('/'))
+                if entry.is_dir():
+                    target.mkdir(parents=True, exist_ok=True)
+                    continue
+                target.parent.mkdir(parents=True, exist_ok=True)
+                with archive.open(entry) as source, target.open('xb') as output:
+                    while chunk := source.read(64 * 1024):
+                        written += len(chunk)
+                        if written > MAX_EXPANDED_BYTES:
+                            raise ApiError(413, 'EXTENSION_ZIP_TOO_LARGE', 'ZIP 解压后不能超过 50 MiB。')
+                        output.write(chunk)
+            manifest = f'{kind}.yaml'
+            root = destination
+            if not (root / manifest).is_file():
+                children = list(root.iterdir())
+                if len(children) != 1 or not children[0].is_dir() or not (children[0] / manifest).is_file():
+                    raise invalid(f'ZIP 根目录或唯一顶层文件夹中须包含 {manifest}。')
+                root = children[0]
+            return install(root)
+    except BaseException as error:
+        shutil.rmtree(destination)
+        if isinstance(error, ExtensionError):
+            raise
+        if isinstance(error, (zipfile.BadZipFile, OSError, RuntimeError, NotImplementedError, zlib.error, EOFError, UnicodeError)):
+            raise invalid('ZIP 损坏、路径冲突或无法解压。') from error
+        raise

backend/app/routes.py

@@ -5,11 +5,13 @@ from contextlib import aclosing
 from datetime import datetime, timezone
 from uuid import uuid4
 
-from fastapi import APIRouter, Header, Query
+from fastapi import APIRouter, Header, Query, Request
 from fastapi.responses import StreamingResponse
 
 from app.agent import AgentCapacityError, AgentRunNotFoundError
 from app.container import container
+from app.config import get_settings
+from app.extensions.archive import MAX_ZIP_BYTES, install_zip
 from app.services.persona_settings import PersonaSettings, load_persona, save_persona
 from app.contracts import (
     AgentRun,
@@ -659,6 +661,27 @@ async def install_skill(request: ExtensionInstallRequest) -> Skill:
     return extension_call(lambda: container.skills.install(request.package_path))
 
 
+async def read_extension_zip(request: Request) -> bytes:
+    data = bytearray()
+    async for chunk in request.stream():
+        if len(data) + len(chunk) > MAX_ZIP_BYTES:
+            raise ApiError(413, 'EXTENSION_ZIP_TOO_LARGE', 'ZIP 文件不能超过 10 MiB。')
+        data.extend(chunk)
+    return bytes(data)
+
+
+@router.post('/skills/install-zip', response_model=Skill, status_code=202, tags=['Skills'])
+async def install_skill_zip(request: Request) -> Skill:
+    data = await read_extension_zip(request)
+    return extension_call(lambda: install_zip(data, 'skill', get_settings().data_dir / 'extension-packages', container.skills.install))
+
+
+@router.post('/plugins/install-zip', response_model=Plugin, status_code=202, tags=['Plugins'])
+async def install_plugin_zip(request: Request) -> Plugin:
+    data = await read_extension_zip(request)
+    return extension_call(lambda: install_zip(data, 'plugin', get_settings().data_dir / 'extension-packages', container.plugins.install))
+
+
 @router.post(
     "/skills/{skill_id}/enable",
     response_model=Skill,

backend/tests/test_extension_archive.py

@@ -0,0 +1,87 @@
+import asyncio
+import io
+import stat
+import zipfile
+
+import pytest
+from starlette.requests import Request
+
+from app.errors import ApiError
+from app.extensions import ExtensionError
+from app.extensions.archive import install_zip
+from app.extensions import archive as module
+
+
+def zipped(files):
+    output = io.BytesIO()
+    with zipfile.ZipFile(output, 'w', zipfile.ZIP_DEFLATED) as archive:
+        for name, value in files:
+            if isinstance(name, str) and '\\' in name:
+                entry = zipfile.ZipInfo()
+                entry.filename = name  # Keep malicious separators on Windows too.
+                name = entry
+            archive.writestr(name, value)
+    return output.getvalue()
+
+
+@pytest.mark.parametrize('kind', ['skill', 'plugin'])
+@pytest.mark.parametrize('prefix', ['', 'package/'])
+def test_install_keeps_package_resources(tmp_path, kind, prefix):
+    data = zipped([(prefix + kind + '.yaml', 'name: test'), (prefix + 'assets/说明.txt', 'hello')])
+    root = install_zip(data, kind, tmp_path, lambda root: root)
+    assert (root / 'assets/说明.txt').read_text() == 'hello'
+
+
+@pytest.mark.parametrize('path', ['../outside', '/outside', 'C:/outside', 'a\\b', 'NUL.txt', 'a/../b', 'a./x'])
+def test_unsafe_paths_rejected_and_cleaned(tmp_path, path):
+    with pytest.raises(ApiError):
+        install_zip(zipped([('skill.yaml', 'name: x'), (path, 'x')]), 'skill', tmp_path, lambda _: pytest.fail('must not install'))
+    assert list(tmp_path.iterdir()) == []
+
+
+def test_links_duplicates_and_size_limits(tmp_path, monkeypatch):
+    link = zipfile.ZipInfo('link')
+    link.create_system = 3
+    link.external_attr = (stat.S_IFLNK | 0o777) << 16
+    cases = [zipped([(link, '../outside')]), zipped([('skill.yaml', 'x'), ('SKILL.yaml', 'x')]), b'not a zip']
+    for data in cases:
+        with pytest.raises(ApiError):
+            install_zip(data, 'skill', tmp_path, lambda _: pytest.fail('must not install'))
+        assert list(tmp_path.iterdir()) == []
+    monkeypatch.setattr(module, 'MAX_EXPANDED_BYTES', 3)
+    with pytest.raises(ApiError, match='50 MiB'):
+        install_zip(zipped([('skill.yaml', 'xxxxx')]), 'skill', tmp_path, lambda _: None)
+    assert list(tmp_path.iterdir()) == []
+
+
+def test_manifest_validation_failure_preserved_and_cleaned(tmp_path):
+    def reject(_):
+        raise ExtensionError('BAD_MANIFEST', 'invalid manifest')
+    with pytest.raises(ExtensionError, match='invalid manifest'):
+        install_zip(zipped([('plugin.yaml', 'x')]), 'plugin', tmp_path, reject)
+    assert list(tmp_path.iterdir()) == []
+    with pytest.raises(ApiError, match='plugin.yaml'):
+        install_zip(zipped([('skill.yaml', 'x')]), 'plugin', tmp_path, reject)
+    assert list(tmp_path.iterdir()) == []
+
+
+@pytest.mark.parametrize('kind', ['skill', 'plugin'])
+def test_upload_route_uses_real_manifest_validation(tmp_path, monkeypatch, kind):
+    from app import routes
+    from app.container import build_container
+    runtime = build_container()
+    monkeypatch.setattr(routes, 'container', runtime)
+    data = zipped([(kind + '.yaml', f'id: zip-example\nname: ZIP example\nversion: 1.0.0\ndescription: test\n')])
+    sent = False
+    async def receive():
+        nonlocal sent
+        assert not sent
+        sent = True
+        return {'type': 'http.request', 'body': data, 'more_body': False}
+    request = Request({'type': 'http', 'method': 'POST', 'headers': []}, receive)
+    try:
+        result = asyncio.run(getattr(routes, f'install_{kind}_zip')(request))
+        assert getattr(result.manifest, kind + '_id') == 'zip-example'
+        assert not result.enabled
+    finally:
+        runtime.plugins.shutdown()