feat(plugins): add managed runtime SDK and release 2.4.5

DESIGN.md

@@ -64,6 +64,8 @@ ARTEMIS 面向使用自然语言执行、探索和复跑测试的人。当前产
 | 插件与证据 | `artemis/plugins` 管理安装、会话、版本固定、来源、截图、录像和附件；插件执行工具动作，宿主管理任务生命周期和最终验收 |
 | 配置与交付 | `artemis/config`、两份 `artemis.jsonc` 和环境配置提供默认值；`scripts` 负责启动、镜像、独立升级和源码打包 |
 
+插件运行辅助接口见 [SDK 与市场材料](docs/plugin-sdk.md)：已批准文件用不可变快照绑定实际消费字节，受管外部工具在返回前回收后代。宿主负责 MCP 总预算，插件负责内部超时和取消。开发检查保持轻量；市场材料使用独立内容指纹与验收记录校验，不代替源码、权利来源或真实业务审查。
+
 请求重试、业务执行与最终验收分别处理。提交使用稳定标识；创建批次或探索草稿不自动执行，查询不产生设备动作。执行准入和恢复遵守现有资源锁，任务固定所用插件版本，不能通过另建队列绕开互斥。
 
 设备保活是辅助服务。保活所属锁或旧保活清理目录不可访问时记录警告，不使设备连接、恢复或监控退出；未取得保活所属锁时不发送保活动作，也不创建替代锁绕过所属权。执行资源锁、主服务注册锁和队列写锁仍须成功取得。

README.md

@@ -2,7 +2,7 @@
 
 基于 [ARTEMIS](https://github.com/google/artemis) 扩展的 Android AI 自动化测试平台。用自然语言描述任务，即可通过简体中文网页或 MCP 驱动真机、模拟器执行操作并收集结果。模型统一使用 **OpenAI Responses API**。
 
-**2.4.4**：任务结束说明默认显示一行摘要，点击展开 Markdown 正文和已记录依据，避免失败长文本占满列表；不新增 AI 复盘请求。见 [2.4.4 发行说明](docs/releases/2.4.4.md)。人工评审插件保持 1.1.0；批次异常隔离见 [2.4.3](docs/releases/2.4.3.md)，列表优化见 [2.4.2](docs/releases/2.4.2.md)，安装修复见 [2.4.1](docs/releases/2.4.1.md)。
+**2.4.5**：补齐插件开发辅助接口与市场材料检查，提供已批准文件快照、受管外部工具、故障自测和可运行模板。新 SDK 需 ARTEMIS 2.4.5；现有插件继续按自身清单兼容旧版本。见 [2.4.5 发行说明](docs/releases/2.4.5.md)与 [SDK 使用说明](docs/plugin-sdk.md)。人工评审插件保持 1.1.0；任务说明折叠见 [2.4.4](docs/releases/2.4.4.md)，批次异常隔离见 [2.4.3](docs/releases/2.4.3.md)。
 
 ## 主要功能
 

apps/showcase_ui/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "artemis-showcase-ui",
-  "version": "2.4.4",
+  "version": "2.4.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "artemis-showcase-ui",
-      "version": "2.4.4",
+      "version": "2.4.5",
       "dependencies": {
         "@angular/cdk": "^22.2.4",
         "@angular/common": "^22.2.3",

apps/showcase_ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artemis-showcase-ui",
-  "version": "2.4.4",
+  "version": "2.4.5",
   "scripts": {
     "ng": "ng",
     "start": "ng serve --proxy-config proxy.conf.json",

artemis/plugins/_process_worker.py

@@ -0,0 +1,57 @@
+"""Private launch barrier for sdk.run_process; stdlib-only under Python -I."""
+
+import json
+import os
+from pathlib import Path
+import signal
+import subprocess
+import sys
+import threading
+import time
+
+
+def watch_parent(expected: int):
+    while True:
+        if os.getppid() != expected:
+            os.killpg(os.getpid(), signal.SIGKILL)
+        time.sleep(0.1)
+
+
+def main():
+    status = Path(sys.argv[1])
+    if os.name != "nt":
+        threading.Thread(target=watch_parent, args=(int(sys.argv[2]),), daemon=True).start()
+    # Until the parent owns our job/session and sends this line, no business
+    # process can start. Buffering is local; tool stdin uses a separate pipe.
+    control = sys.stdin.buffer.readline(1024 * 1024 + 1)
+    if not control.endswith(b"\n") or len(control) > 1024 * 1024:
+        return
+    request = json.loads(control)
+    size = request["input_size"]
+    if type(size) is not int or not 0 <= size <= 64 * 1024 * 1024:
+        return
+    content = sys.stdin.buffer.read(size) if request["has_input"] else None
+    if content is not None and len(content) != size:
+        return
+    try:
+        result = subprocess.run(
+            request["argv"],
+            shell=False,
+            stdin=None if request["has_input"] else subprocess.DEVNULL,
+            input=content,
+            creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0,
+            check=False,
+        )
+        response = {"returncode": result.returncode}
+    except OSError:
+        response = {"launch_failed": True}
+    pending = status.with_suffix(".tmp")
+    pending.write_text(json.dumps(response), encoding="utf-8")
+    pending.replace(status)
+    # Remain the session/group leader until the owner reclaims the whole tree.
+    while True:
+        time.sleep(60)
+
+
+if __name__ == "__main__":
+    main()

artemis/plugins/_sdk_probe.py

@@ -0,0 +1,40 @@
+"""Synthetic tool used only by the opt-in SDK fault suite. No device/network I/O."""
+
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+
+
+def main():
+    mode = sys.argv[1]
+    if mode == "sleep":
+        time.sleep(60)
+    elif mode == "tree":
+        child = subprocess.Popen(
+            [sys.executable, "-I", "-B", __file__, "sleep"],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0,
+        )
+        Path(sys.argv[2]).write_text(json.dumps({"pid": child.pid}), encoding="utf-8")
+        if sys.argv[3] == "linger":
+            time.sleep(60)
+    elif mode == "echo":
+        data = sys.stdin.buffer.read()
+        sys.stdout.buffer.write(data)
+        sys.stderr.buffer.write(b"synthetic-stderr")
+    elif mode == "overflow":
+        while True:
+            os.write(1, b"x" * 65536)
+    elif mode == "failure":
+        raise SystemExit(7)
+    else:
+        raise SystemExit(2)
+
+
+if __name__ == "__main__":
+    main()

artemis/plugins/market.py

@@ -0,0 +1,266 @@
+"""Evidence-bound market materials. Declarations still need source/rights review."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+import hashlib
+import json
+from pathlib import Path, PurePosixPath
+import stat
+import tempfile
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from artemis.config.settings import settings
+from artemis.plugins.installer import _extract
+from artemis.plugins.models import PluginManifest
+
+REPORT_NAME = "MARKET.json"
+CHECKS = (
+    "installation",
+    "tool_contract",
+    "failure_partial",
+    "timeout_cancel",
+    "process_tree",
+    "file_binding",
+    "resource_conflicts",
+    "evidence_export",
+    "history_uninstall",
+    "secret_redaction",
+    "real_task",
+    "source_review",
+)
+FORBIDDEN_DIRECTORIES = {".git", ".ruff_cache", ".pytest_cache", "__pycache__", ".venv"}
+
+
+class SubmissionModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+
+class Component(SubmissionModel):
+    name: str = Field(min_length=1)
+    paths: list[str] = Field(min_length=1)
+    license: str = Field(min_length=1)
+    permission: Literal["permitted", "local_only", "unknown"]
+    license_file: str
+    source_file: str
+
+
+class CheckRecord(SubmissionModel):
+    status: Literal["passed", "failed", "unverified", "not_applicable"]
+    evidence_file: str = ""
+    evidence_sha256: str = ""
+    notes: str = ""
+
+
+class Traits(SubmissionModel):
+    uses_subprocesses: bool | None
+    file_inputs_for_writes: bool | None
+
+
+class MarketSubmission(SubmissionModel):
+    schema_version: Literal[1]
+    plugin_id: str
+    plugin_version: str
+    content_sha256: str = Field(pattern=r"^[a-f0-9]{64}$")
+    traits: Traits
+    components: list[Component] = Field(min_length=1)
+    checks: dict[str, CheckRecord]
+
+
+@contextmanager
+def package_directory(path: Path) -> Iterator[tuple[Path, str | None]]:
+    """Inspect a directory or safely unpack a ZIP without installing or hooks."""
+    path = path.resolve(strict=True)
+    if path.is_dir():
+        yield path, None
+        return
+    if not path.is_file():
+        raise ValueError("检查输入必须是普通插件目录或 ZIP 文件")
+    with path.open("rb") as stream:
+        data = stream.read(settings.ARTEMIS_PLUGIN_DOWNLOAD_MAX_BYTES + 1)
+    if len(data) > settings.ARTEMIS_PLUGIN_DOWNLOAD_MAX_BYTES:
+        raise ValueError("插件 ZIP 超过下载大小限制")
+    with tempfile.TemporaryDirectory(prefix="artemis-plugin-check-") as temporary:
+        directory = Path(temporary)
+        _extract(data, directory)
+        archive_sha256 = hashlib.sha256(data).hexdigest()
+        yield directory, archive_sha256
+        # Re-read only to reject changes; never relabel the inspected snapshot.
+        current_digest = hashlib.sha256()
+        current_size = 0
+        with path.open("rb") as stream:
+            while chunk := stream.read(1024 * 1024):
+                current_size += len(chunk)
+                if current_size > settings.ARTEMIS_PLUGIN_DOWNLOAD_MAX_BYTES:
+                    raise ValueError("检查期间 ZIP 发生变化或超过大小限制")
+                current_digest.update(chunk)
+        if current_digest.hexdigest() != archive_sha256:
+            raise ValueError("检查期间 ZIP 发生变化，检查记录失效")
+
+
+def _relative(value: str, *, root_allowed: bool = False) -> str:
+    if root_allowed and value == ".":
+        return value
+    path = PurePosixPath(value)
+    if (
+        not value
+        or "\\" in value
+        or ":" in value
+        or path.is_absolute()
+        or any(p in {".", ".."} for p in value.split("/"))
+        or any(ord(c) < 32 for c in value)
+        or str(path) != value
+    ):
+        raise ValueError("市场材料必须使用包内普通相对路径")
+    return value
+
+
+def package_files(directory: Path) -> dict[str, str]:
+    """Hash every distributable file, excluding only the self-referential report."""
+    directory = directory.resolve(strict=True)
+    files = {}
+    seen = set()
+    size = 0
+    for path in sorted(directory.rglob("*")):
+        relative = path.relative_to(directory)
+        name = relative.as_posix()
+        if path.is_symlink() or path.is_junction() or not path.resolve().is_relative_to(directory):
+            raise ValueError("市场包不能包含链接")
+        if name.casefold() in seen:
+            raise ValueError("市场包存在大小写冲突的路径")
+        seen.add(name.casefold())
+        if len(seen) > 20000:
+            raise ValueError("市场包超过文件数量限制")
+        if any(p.casefold() in FORBIDDEN_DIRECTORIES for p in relative.parts):
+            raise ValueError(f"市场包包含缓存、依赖环境或版本库目录：{name}")
+        if path.is_dir():
+            continue
+        info = path.stat()
+        if not stat.S_ISREG(info.st_mode):
+            raise ValueError("市场包只能包含普通文件")
+        if name == REPORT_NAME:
+            continue
+        lower = path.name.casefold()
+        if (
+            lower.endswith((".pyc", ".pyo"))
+            or lower == ".env"
+            or (
+                lower.startswith(".env.")
+                and not lower.endswith((".example", ".sample", ".template"))
+            )
+        ):
+            raise ValueError(f"市场包不能包含缓存或个人环境配置：{name}")
+        _relative(name)
+        digest = hashlib.sha256()
+        read = 0
+        with path.open("rb") as handle:
+            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                read += len(chunk)
+                size += len(chunk)
+                if size > settings.ARTEMIS_PLUGIN_EXTRACT_MAX_BYTES:
+                    raise ValueError("市场包超过展开大小或文件数量限制")
+                digest.update(chunk)
+        if read != info.st_size:
+            raise ValueError("文件校验期间大小发生变化")
+        files[name] = digest.hexdigest()
+    return files
+
+
+def content_fingerprint(files: dict[str, str]) -> str:
+    encoded = json.dumps(files, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+
+
+def draft_submission(manifest: PluginManifest, files: dict[str, str]) -> dict:
+    """Drafts never fabricate passed results or distribution permission."""
+    return {
+        "schema_version": 1,
+        "plugin_id": manifest.id,
+        "plugin_version": manifest.version,
+        "content_sha256": content_fingerprint(files),
+        "traits": {"uses_subprocesses": None, "file_inputs_for_writes": None},
+        "components": [
+            {
+                "name": "请拆分原始代码、适配层与第三方资料",
+                "paths": ["."],
+                "license": manifest.license or "待补充",
+                "permission": "unknown",
+                "license_file": "LICENSE",
+                "source_file": "SOURCE.md",
+            }
+        ],
+        "checks": {
+            name: {"status": "unverified", "evidence_file": "", "evidence_sha256": "", "notes": ""}
+            for name in CHECKS
+        },
+    }
+
+
+def _document(directory: Path, files: dict[str, str], value: str) -> str:
+    name = _relative(value)
+    if name not in files or not 0 < (directory / name).stat().st_size <= 1024 * 1024:
+        raise ValueError("许可、来源与验证记录必须是非空包内文档，且不超过 1 MiB")
+    return name
+
+
+def validate_submission(
+    directory: Path, manifest: PluginManifest, files: dict[str, str]
+) -> MarketSubmission:
+    path = directory / REPORT_NAME
+    if not path.is_file() or path.stat().st_size > 1024 * 1024:
+        raise ValueError("市场检查需要包内 MARKET.json；先生成草稿并补充真实记录")
+    report = MarketSubmission.model_validate_json(path.read_text("utf-8"))
+    if (report.plugin_id, report.plugin_version) != (manifest.id, manifest.version):
+        raise ValueError("市场材料的插件 ID/版本与清单不一致")
+    if report.content_sha256 != content_fingerprint(files):
+        raise ValueError("包内容已变化，旧的市场验证记录失效")
+    if not manifest.license.strip():
+        raise ValueError("市场清单必须声明许可证或具体的 LicenseRef")
+    if None in (report.traits.uses_subprocesses, report.traits.file_inputs_for_writes):
+        raise ValueError("必须明确是否使用子进程、是否将文件用于写操作")
+    covered = set()
+    for component in report.components:
+        if component.permission != "permitted" or component.license.strip().casefold() in {
+            "",
+            "unknown",
+            "todo",
+            "待补充",
+        }:
+            raise ValueError(f"组件未明确允许市场分发或未提供许可证：{component.name}")
+        _document(directory, files, component.license_file)
+        _document(directory, files, component.source_file)
+        for scope in component.paths:
+            scope = _relative(scope, root_allowed=True)
+            selected = {
+                name
+                for name in files
+                if scope == "." or name == scope or name.startswith(scope + "/")
+            }
+            if not selected:
+                raise ValueError("来源组件声明了不存在的文件范围")
+            covered.update(selected)
+    if set(files) - covered:
+        raise ValueError("市场包有文件未记录来源与分发许可")
+    if set(report.checks) != set(CHECKS):
+        raise ValueError("市场验证项目缺失或包含未知项目")
+    optional = {
+        "tool_contract": manifest.server is None,
+        "timeout_cancel": manifest.server is None,
+        "process_tree": not report.traits.uses_subprocesses,
+        "file_binding": not report.traits.file_inputs_for_writes,
+        "resource_conflicts": not manifest.resources,
+    }
+    for name, record in report.checks.items():
+        if not record.notes.strip():
+            raise ValueError(f"验证项目必须说明实际范围或不适用原因：{name}")
+        if record.status == "not_applicable" and optional.get(name, False):
+            continue
+        if record.status != "passed":
+            raise ValueError(f"市场验证项目未通过：{name}")
+        evidence = _document(directory, files, record.evidence_file)
+        if files[evidence] != record.evidence_sha256:
+            raise ValueError(f"验证记录 SHA256 不一致：{name}")
+    return report

artemis/plugins/recording_process.py

@@ -4,8 +4,8 @@ import ctypes
 from ctypes import wintypes
 
 
-class CaptureProcessJob:
+class ProcessJob:
-    """A non-inheritable job handle: Windows kills captures when its owner exits."""
+    """A non-inheritable job handle that owns a Windows process tree."""
 
     def __init__(self):
         class BasicLimits(ctypes.Structure):
@@ -54,6 +54,12 @@ class CaptureProcessJob:
             ),
             ("OpenProcess", [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD], wintypes.HANDLE),
             ("AssignProcessToJobObject", [wintypes.HANDLE, wintypes.HANDLE], wintypes.BOOL),
+            ("TerminateJobObject", [wintypes.HANDLE, wintypes.UINT], wintypes.BOOL),
+            (
+                "QueryInformationJobObject",
+                [wintypes.HANDLE, ctypes.c_int, wintypes.LPVOID, wintypes.DWORD, wintypes.LPVOID],
+                wintypes.BOOL,
+            ),
             ("CloseHandle", [wintypes.HANDLE], wintypes.BOOL),
         ):
             function = getattr(self._api, name)
@@ -84,3 +90,34 @@ class CaptureProcessJob:
         if self._handle:
             self._api.CloseHandle(self._handle)
             self._handle = None
+
+    def terminate(self):
+        if self._handle and not self._api.TerminateJobObject(self._handle, 1):
+            raise ctypes.WinError(ctypes.get_last_error())
+
+    def active_processes(self) -> int:
+        if not self._handle:
+            return 0
+
+        class Accounting(ctypes.Structure):
+            _fields_ = [
+                ("user_time", ctypes.c_int64),
+                ("kernel_time", ctypes.c_int64),
+                ("period_user_time", ctypes.c_int64),
+                ("period_kernel_time", ctypes.c_int64),
+                ("page_faults", wintypes.DWORD),
+                ("total", wintypes.DWORD),
+                ("active", wintypes.DWORD),
+                ("terminated", wintypes.DWORD),
+            ]
+
+        accounting = Accounting()
+        if not self._api.QueryInformationJobObject(
+            self._handle, 1, ctypes.byref(accounting), ctypes.sizeof(accounting), None
+        ):
+            raise ctypes.WinError(ctypes.get_last_error())
+        return accounting.active
+
+
+# Keep the recording implementation and its callers on the same ownership primitive.
+CaptureProcessJob = ProcessJob

artemis/plugins/sdk.py

@@ -0,0 +1,347 @@
+"""Plugin author helpers; no scheduler, device actions or implicit retries.
+
+Use snapshot_file before approving a write and consume its immutable bytes, not the
+original pathname. run_process owns the tool and its descendants on every exit.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass, field
+import hashlib
+import json
+import math
+import os
+from pathlib import Path
+import re
+import signal
+import stat
+import subprocess
+import sys
+import tempfile
+
+from artemis.plugins.recording_process import ProcessJob
+
+MAX_INPUT_BYTES = 64 * 1024 * 1024
+DEFAULT_OUTPUT_BYTES = 4 * 1024 * 1024
+
+
+class FileVerificationError(ValueError):
+    """The input cannot be bound to its explicitly approved digest."""
+
+
+@dataclass(frozen=True)
+class VerifiedFile:
+    """Bounded, immutable input. No original path is exposed for reopening."""
+
+    data: bytes = field(repr=False)
+    sha256: str = field(init=False)
+
+    def __post_init__(self):
+        if not isinstance(self.data, bytes):
+            raise TypeError("快照内容必须是不可变 bytes")
+        object.__setattr__(self, "sha256", hashlib.sha256(self.data).hexdigest())
+
+    @property
+    def size(self) -> int:
+        return len(self.data)
+
+    def chunks(self, size: int = 256 * 1024) -> Iterator[memoryview]:
+        if type(size) is not int or size <= 0:
+            raise ValueError("分块大小必须是正整数")
+        content = memoryview(self.data)
+        for offset in range(0, len(content), size):
+            yield content[offset : offset + size]
+
+
+def snapshot_file(
+    path: Path | str, expected_sha256: str, *, max_bytes: int = MAX_INPUT_BYTES
+) -> VerifiedFile:
+    """Copy once, then verify the exact bytes that will be consumed by the caller.
+
+    The source must already be authorized by the plugin. This is not a path or
+    permission sandbox. Memory use is bounded by max_bytes plus one read byte.
+    """
+    if type(max_bytes) is not int or max_bytes <= 0:
+        raise ValueError("文件大小上限必须是正整数")
+    if not isinstance(expected_sha256, str) or not re.fullmatch(
+        r"[a-fA-F0-9]{64}", expected_sha256
+    ):
+        raise FileVerificationError("必须明确提供已批准的 SHA256")
+    source = Path(path)
+    if source.is_symlink() or not stat.S_ISREG(source.lstat().st_mode):
+        raise FileVerificationError("输入必须是普通文件，不能是链接或设备")
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+    descriptor = os.open(source, flags)
+    with os.fdopen(descriptor, "rb") as handle:
+        info = os.fstat(handle.fileno())
+        if not stat.S_ISREG(info.st_mode) or info.st_size > max_bytes:
+            raise FileVerificationError("输入不是普通文件或超过大小上限")
+        data = handle.read(max_bytes + 1)
+    if len(data) > max_bytes:
+        raise FileVerificationError("输入超过大小上限")
+    snapshot = VerifiedFile(data)
+    if snapshot.sha256 != expected_sha256.lower():
+        raise FileVerificationError("输入 SHA256 与批准值不一致；不得开始写操作")
+    return snapshot
+
+
+class ManagedProcessError(RuntimeError):
+    """Stable failure metadata. Do not infer a business verdict or retry a write."""
+
+    def __init__(self, code: str, *, may_have_started: bool = True):
+        super().__init__(code)
+        self.error_code = code
+        self.may_have_started = may_have_started
+
+
+class ProcessTimedOut(ManagedProcessError, TimeoutError):
+    pass
+
+
+@dataclass(frozen=True)
+class ProcessResult:
+    returncode: int
+    stdout: bytes = field(repr=False)
+    stderr: bytes = field(repr=False)
+
+
+async def _cleanup(process: asyncio.subprocess.Process, job: ProcessJob | None) -> None:
+    error = None
+    try:
+        if job is not None:
+            job.terminate()
+            async with asyncio.timeout(5):
+                while job.active_processes():
+                    await asyncio.sleep(0.02)
+        elif os.name != "nt":
+            # The bootstrap stays alive until cleanup, pinning the owned PGID.
+            try:
+                os.killpg(process.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+    except (OSError, TimeoutError) as exc:
+        error = exc
+    finally:
+        if job is not None:
+            job.close()
+        if process.returncode is None:
+            try:
+                process.kill()
+            except ProcessLookupError:
+                pass
+    # Process.wait also waits for pipe EOF. A paused, full output reader must be
+    # drained separately; it cannot serve as evidence that the OS process lives.
+    try:
+        async with asyncio.timeout(5):
+            while process.returncode is None:
+                await asyncio.sleep(0.02)
+    except TimeoutError as exc:
+        error = exc
+    if error is not None:
+        raise ManagedProcessError("process_cleanup_unconfirmed") from error
+
+
+async def _finish_cleanup(task: asyncio.Task[None]) -> None:
+    cancelled = False
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            cancelled = True
+    task.result()
+    if cancelled:
+        raise asyncio.CancelledError
+
+
+async def _read_output(stream: asyncio.StreamReader, consumed: list[int], limit: int) -> bytes:
+    chunks = []
+    while chunk := await stream.read(65536):
+        consumed[0] += len(chunk)
+        if consumed[0] > limit:
+            raise ManagedProcessError("process_output_limit")
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+async def _drain(stream: asyncio.StreamReader | None) -> None:
+    if stream is not None:
+        while await stream.read(65536):
+            pass
+
+
+async def _wait_result(process: asyncio.subprocess.Process, path: Path) -> int:
+    while not path.exists():
+        if process.returncode is not None:
+            raise ManagedProcessError("process_worker_interrupted")
+        await asyncio.sleep(0.02)
+    if path.stat().st_size > 4096:
+        raise ManagedProcessError("process_invalid_status")
+    try:
+        result = json.loads(path.read_text("utf-8"))
+        if not isinstance(result, dict):
+            raise ValueError
+    except (OSError, ValueError) as exc:
+        raise ManagedProcessError("process_invalid_status") from exc
+    if result.get("launch_failed") is True:
+        raise ManagedProcessError("process_launch_failed", may_have_started=False)
+    if type(result.get("returncode")) is not int:
+        raise ManagedProcessError("process_invalid_status")
+    return result["returncode"]
+
+
+async def run_process(
+    argv: Sequence[str],
+    *,
+    cwd: Path | str,
+    timeout: float,
+    env: Mapping[str, str] | None = None,
+    input_data: bytes | None = None,
+    max_output_bytes: int = DEFAULT_OUTPUT_BYTES,
+) -> ProcessResult:
+    """Run one fixed argv without a shell; reclaim descendants even on normal exit.
+
+    Windows assigns a waiting bootstrap to a Job Object *before* it can start the
+    tool. POSIX uses a dedicated session. Cancellation completes cleanup before
+    propagating. Inputs are at most 64 MiB; stdout+stderr share a bounded budget.
+    Return codes/output are tool results, never a test verdict. No retries occur.
+    """
+    if (
+        not isinstance(argv, Sequence)
+        or isinstance(argv, (str, bytes))
+        or not argv
+        or any(not isinstance(arg, str) or "\0" in arg for arg in argv)
+    ):
+        raise ValueError("必须提供固定的 argv 字符串列表，不能使用 shell 命令文本")
+    if not argv[0] or isinstance(timeout, bool) or not math.isfinite(timeout) or timeout <= 0:
+        raise ValueError("启动程序和有限正数超时是必填项")
+    if type(max_output_bytes) is not int or max_output_bytes <= 0:
+        raise ValueError("输出上限必须是正整数")
+    if input_data is not None and (
+        not isinstance(input_data, bytes) or len(input_data) > MAX_INPUT_BYTES
+    ):
+        raise ValueError("标准输入必须是至多 64 MiB 的 bytes")
+    directory = Path(cwd).resolve(strict=True)
+    if not directory.is_dir():
+        raise ValueError("工作目录必须是已存在的目录")
+    control = (
+        json.dumps(
+            {
+                "argv": list(argv),
+                "has_input": input_data is not None,
+                "input_size": len(input_data or b""),
+            }
+        ).encode()
+        + b"\n"
+    )
+    if len(control) > 1024 * 1024:
+        raise ValueError("启动参数超过大小上限")
+    job = None
+    process: asyncio.subprocess.Process | None = None
+    cleanup: asyncio.Task[None] | None = None
+    tasks: list[asyncio.Task] = []
+
+    async def reclaim():
+        nonlocal cleanup
+        if process is None:
+            if job is not None:
+                job.close()
+            return
+        if cleanup is None:
+            cleanup = asyncio.create_task(_cleanup(process, job))
+        await _finish_cleanup(cleanup)
+
+    with tempfile.TemporaryDirectory(prefix="artemis-plugin-process-") as temporary:
+        status = Path(temporary) / "status.json"
+        try:
+            job = ProcessJob() if os.name == "nt" else None
+        except OSError as exc:
+            raise ManagedProcessError("process_ownership_failed", may_have_started=False) from exc
+        launch = asyncio.create_task(
+            asyncio.create_subprocess_exec(
+                sys.executable,
+                "-I",
+                "-B",
+                str(Path(__file__).with_name("_process_worker.py")),
+                str(status),
+                str(os.getpid()),
+                cwd=str(directory),
+                env=dict(env) if env is not None else None,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0,
+                start_new_session=os.name != "nt",
+            )
+        )
+        try:
+            cancelled = False
+            while process is None:
+                try:
+                    process = await asyncio.shield(launch)
+                except asyncio.CancelledError:
+                    cancelled = True
+                except OSError as exc:
+                    raise ManagedProcessError(
+                        "process_launch_failed", may_have_started=False
+                    ) from exc
+            if cancelled:
+                raise asyncio.CancelledError
+            if job is not None:
+                try:
+                    job.assign(process.pid)
+                except OSError as exc:
+                    raise ManagedProcessError(
+                        "process_ownership_failed", may_have_started=False
+                    ) from exc
+            stdin, stdout, stderr = process.stdin, process.stdout, process.stderr
+            assert stdin is not None and stdout is not None and stderr is not None
+            consumed = [0]
+
+            async def feed():
+                try:
+                    stdin.write(control)
+                    await stdin.drain()
+                    if input_data:
+                        stdin.write(input_data)
+                        await stdin.drain()
+                except (BrokenPipeError, ConnectionResetError):
+                    pass
+                finally:
+                    stdin.close()
+
+            async def wait_tool():
+                code = await _wait_result(process, status)
+                await reclaim()
+                return code
+
+            tasks = [
+                asyncio.create_task(feed()),
+                asyncio.create_task(_read_output(stdout, consumed, max_output_bytes)),
+                asyncio.create_task(_read_output(stderr, consumed, max_output_bytes)),
+                asyncio.create_task(wait_tool()),
+            ]
+            try:
+                _, stdout, stderr, code = await asyncio.wait_for(asyncio.gather(*tasks), timeout)
+            except TimeoutError as exc:
+                raise ProcessTimedOut("process_timeout") from exc
+            return ProcessResult(code, stdout, stderr)
+        finally:
+            for task in tasks:
+                task.cancel()
+
+            async def finalize():
+                try:
+                    await reclaim()
+                finally:
+                    await asyncio.gather(*tasks, return_exceptions=True)
+                    if process is not None:
+                        try:
+                            async with asyncio.timeout(5):
+                                await asyncio.gather(_drain(process.stdout), _drain(process.stderr))
+                                await process.wait()
+                        except TimeoutError as exc:
+                            raise ManagedProcessError("process_cleanup_unconfirmed") from exc
+
+            await _finish_cleanup(asyncio.create_task(finalize()))

artemis/plugins/sdk_checks.py

@@ -0,0 +1,212 @@
+"""Run opt-in, offline SDK fault regressions in temporary directories only."""
+
+import argparse
+import asyncio
+from contextlib import suppress
+import hashlib
+import json
+from pathlib import Path
+import sys
+import tempfile
+import time
+
+import psutil
+
+from artemis.plugins.evidence import decode_receipt, persist_attachments
+from artemis.plugins.models import PluginCallResult
+from artemis.plugins.sdk import (
+    FileVerificationError,
+    ManagedProcessError,
+    ProcessTimedOut,
+    run_process,
+    snapshot_file,
+)
+
+PROBE = Path(__file__).with_name("_sdk_probe.py").resolve()
+
+
+def _require(condition, message):
+    if not condition:
+        raise AssertionError(message)
+
+
+def _owned_process(marker: Path, started: float):
+    if not marker.exists():
+        return None
+    pid = json.loads(marker.read_text("utf-8"))["pid"]
+    try:
+        process = psutil.Process(pid)
+        if process.status() == psutil.STATUS_ZOMBIE:
+            return None
+        _require(process.create_time() >= started - 1, "测试 PID 的启动时间不匹配")
+        _require(str(PROBE) in process.cmdline(), "测试 PID 的脚本身份不匹配")
+        return process
+    except psutil.NoSuchProcess:
+        return None
+
+
+async def _tree_case(root: Path, mode: str):
+    marker = root / f"{mode}.json"
+    started = time.time()
+    task = asyncio.create_task(
+        run_process(
+            [
+                sys.executable,
+                "-I",
+                "-B",
+                str(PROBE),
+                "tree",
+                str(marker),
+                "exit" if mode == "normal" else "linger",
+            ],
+            cwd=root,
+            timeout=2 if mode == "timeout" else 10,
+        )
+    )
+    try:
+        if mode == "cancel":
+            async with asyncio.timeout(5):
+                while not marker.exists() and not task.done():
+                    await asyncio.sleep(0.02)
+            _require(marker.exists(), "取消探针没有启动")
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+            else:
+                raise AssertionError("取消没有传播")
+        elif mode == "timeout":
+            try:
+                await task
+            except ProcessTimedOut:
+                pass
+            else:
+                raise AssertionError("超时没有生效")
+        else:
+            result = await task
+            _require(result.returncode == 0, "模拟工具异常退出")
+        _require(marker.exists(), "后代进程探针没有启动")
+        async with asyncio.timeout(3):
+            while _owned_process(marker, started) is not None:
+                await asyncio.sleep(0.02)
+    finally:
+        if not task.done():
+            task.cancel()
+        with suppress(asyncio.CancelledError, ManagedProcessError):
+            await task
+        # Failing implementations must not leave the fault suite's own sleeper alive.
+        process = _owned_process(marker, started)
+        if process is not None:
+            process.kill()
+            process.wait(timeout=5)
+
+
+async def run_checks() -> dict:
+    checks = []
+    with tempfile.TemporaryDirectory(prefix="artemis-sdk-faults-") as temporary:
+        root = Path(temporary)
+        source = root / "synthetic.rom"
+        approved = b"approved firmware bytes\x00\xff"
+        source.write_bytes(approved)
+        digest = hashlib.sha256(approved).hexdigest()
+        snapshot = snapshot_file(source, digest)
+        for replacement in (b"X" * len(approved), b"", b"Y" * (len(approved) + 10)):
+            source.write_bytes(replacement)
+            _require(b"".join(snapshot.chunks(3)) == approved, "快照受原文件修改影响")
+            try:
+                snapshot_file(source, digest)
+            except FileVerificationError:
+                pass
+            else:
+                raise AssertionError("摘要不符仍被接收")
+        _require(all(part.readonly for part in snapshot.chunks()), "分块内容可被修改")
+        checks.append("file_replacement_truncation_growth_and_digest")
+        result = await run_process(
+            [sys.executable, "-I", "-B", str(PROBE), "echo"],
+            cwd=root,
+            timeout=5,
+            input_data=snapshot.data,
+        )
+        _require(
+            result.stdout == approved and result.stderr == b"synthetic-stderr",
+            "二进制输入输出不一致",
+        )
+        checks.append("binary_input_and_separate_output")
+        failed = await run_process(
+            [sys.executable, "-I", "-B", str(PROBE), "failure"], cwd=root, timeout=5
+        )
+        _require(failed.returncode == 7, "非零退出码被隐藏")
+        checks.append("nonzero_returncode")
+        for mode in ("normal", "timeout", "cancel"):
+            await _tree_case(root, mode)
+            checks.append(f"descendants_reclaimed_on_{mode}")
+        try:
+            await run_process(
+                [sys.executable, "-I", "-B", str(PROBE), "overflow"],
+                cwd=root,
+                timeout=5,
+                max_output_bytes=1024,
+            )
+        except ManagedProcessError as exc:
+            _require(exc.error_code == "process_output_limit", "输出超限错误类型不正确")
+        else:
+            raise AssertionError("输出超限没有停止")
+        checks.append("output_limit_stops_process")
+        trace = root / "synthetic-trace"
+        artifacts = trace / "artifacts/plugins/sdk-faults"
+        artifacts.mkdir(parents=True)
+        sample = artifacts / "sample.txt"
+        sample.write_bytes(b"synthetic evidence")
+        receipt = {"name": sample.name, "sha256": hashlib.sha256(sample.read_bytes()).hexdigest()}
+        _require(len(persist_attachments(trace, "sdk-faults", [receipt])) == 1, "附件未被回读")
+        for invalid in ({**receipt, "sha256": "0" * 64}, {**receipt, "name": "../outside.txt"}):
+            try:
+                persist_attachments(trace, "sdk-faults", [invalid])
+            except ValueError:
+                pass
+            else:
+                raise AssertionError("证据摘要不符或路径穿越未拒绝")
+        checks.append("evidence_hash_and_path_rejection")
+        for execution in ("partial", "unknown"):
+            outcome = PluginCallResult(
+                status="success",
+                structured_content={
+                    "artemis": {
+                        "version": 1,
+                        "execution": execution,
+                        "side_effect": "possible",
+                        "retryable": True,
+                    }
+                },
+            )
+            decode_receipt(outcome)
+            _require(
+                not outcome.retryable and outcome.requires_observation, "不确定写操作被允许重试"
+            )
+        checks.append("partial_unknown_never_authorize_retries")
+    return {
+        "status": "passed",
+        "scope": "sdk_faults_only",
+        "python": sys.version.split()[0],
+        "platform": sys.platform,
+        "checks": checks,
+        "real_device_actions": False,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--json-output", type=Path)
+    args = parser.parse_args()
+    result = asyncio.run(run_checks())
+    if args.json_output:
+        args.json_output.write_text(
+            json.dumps(result, ensure_ascii=False, indent=2) + "\n", "utf-8"
+        )
+    print(json.dumps(result, ensure_ascii=False))
+    print("仅验证 SDK 自身；插件仍需对真实入口做故障注入、证据与任务验收。")
+
+
+if __name__ == "__main__":
+    main()

artemis/plugins/validation.py

@@ -0,0 +1,157 @@
+"""Plugin development checks and a separate market materials gate."""
+
+import argparse
+import asyncio
+import json
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from artemis.plugins.evidence import validate_tools
+from artemis.plugins.market import (
+    REPORT_NAME,
+    content_fingerprint,
+    draft_submission,
+    package_directory,
+    package_files,
+    validate_submission,
+)
+from artemis.plugins.models import PluginManifest, PluginProfile
+from artemis.plugins.session import PluginSession, resolve_server
+from artemis.plugins.store import contained_path
+
+
+async def check(
+    directory: Path,
+    live: bool,
+    values: dict[str, str],
+    *,
+    market: bool = False,
+    fingerprint: bool = False,
+    prepare_market: bool = False,
+) -> dict:
+    if prepare_market and not directory.is_dir():
+        raise ValueError("请在插件目录生成市场草稿，再打包 ZIP")
+    with package_directory(directory) as (root, archive_sha256):
+        manifest = PluginManifest.model_validate_json((root / "plugin.json").read_text("utf-8"))
+        manifest.check_compatible()
+        if manifest.skill:
+            skill = contained_path(root, manifest.skill)
+            if (
+                not skill.is_file()
+                or skill.stat().st_size > 256 * 1024
+                or not skill.read_text("utf-8").strip()
+            ):
+                raise ValueError("缺少有效的 Skill 或超过大小限制")
+        if manifest.schema_version not in {2, 3}:
+            raise ValueError("新市场插件必须适配 schema_version=2 或 3")
+        if any(name not in manifest.config or manifest.config[name].secret for name in values):
+            raise ValueError("--values 只能包含清单中声明的普通配置，不得包含密钥")
+        files = package_files(root) if market or fingerprint or prepare_market else None
+        if prepare_market:
+            assert files is not None
+            draft = draft_submission(manifest, files)
+            with (root / REPORT_NAME).open("x", encoding="utf-8") as handle:
+                handle.write(json.dumps(draft, ensure_ascii=False, indent=2) + "\n")
+            return {
+                "status": "draft",
+                "plugin_id": manifest.id,
+                "version": manifest.version,
+                "content_sha256": draft["content_sha256"],
+            }
+        submission = None
+        if market:
+            assert files is not None
+            submission = validate_submission(root, manifest, files)
+        handshake = bool((live or market) and manifest.server)
+        if handshake:
+            server = resolve_server(manifest, PluginProfile(values=values), root)
+            server.env["PYTHONDONTWRITEBYTECODE"] = "1"
+            session = await PluginSession(server, root).start()
+            try:
+                validate_tools(manifest, session.tools)
+            finally:
+                await session.aclose()
+            if files is not None and package_files(root) != files:
+                raise ValueError("MCP 握手期间包内容发生变化，检查记录失效")
+            if market:
+                assert files is not None
+                if validate_submission(root, manifest, files) != submission:
+                    raise ValueError("MCP 握手期间市场记录发生变化，检查记录失效")
+        result = {
+            "status": "passed",
+            "plugin_id": manifest.id,
+            "version": manifest.version,
+            "scope": "market_materials" if market else "development",
+            "mcp_handshake": handshake,
+        }
+        if files is not None:
+            result["content_sha256"] = content_fingerprint(files)
+        if archive_sha256 is not None:
+            result["archive_sha256"] = archive_sha256
+        return result
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("directory", type=Path, help="插件目录或 ZIP；不会安装到现有插件库")
+    parser.add_argument(
+        "--live", action="store_true", help="仅启动/关闭 MCP 并核对声明，不调用工具"
+    )
+    parser.add_argument("--values", default="{}", help="普通配置 JSON；不得包含密钥")
+    modes = parser.add_mutually_exclusive_group()
+    modes.add_argument(
+        "--market", action="store_true", help="核对市场分发、内容绑定和验收材料，含 MCP 握手"
+    )
+    modes.add_argument(
+        "--prepare-market", action="store_true", help="创建未验证的 MARKET.json 草稿，不覆盖旧文件"
+    )
+    modes.add_argument(
+        "--fingerprint", action="store_true", help="输出包内容摘要；不宣称市场验收通过"
+    )
+    parser.add_argument("--json-output", type=Path, help="将检查结果写到包外 JSON 文件")
+    args = parser.parse_args()
+    result = {}
+    can_write = True
+    try:
+        if args.json_output and (
+            args.json_output.resolve() == args.directory.resolve()
+            or (
+                args.directory.is_dir()
+                and args.json_output.resolve().is_relative_to(args.directory.resolve())
+            )
+        ):
+            can_write = False
+            raise ValueError("检查输出必须在插件包之外，不能覆盖输入包")
+        values = json.loads(args.values)
+        if not isinstance(values, dict) or any(not isinstance(v, str) for v in values.values()):
+            raise ValueError("--values 必须是字符串值的 JSON 对象")
+        result = asyncio.run(
+            check(
+                args.directory.resolve(),
+                args.live,
+                values,
+                market=args.market,
+                fingerprint=args.fingerprint,
+                prepare_market=args.prepare_market,
+            )
+        )
+    except (ValueError, OSError, RuntimeError) as exc:
+        message = (
+            "输入格式或清单/市场材料字段不合法"
+            if isinstance(exc, (json.JSONDecodeError, ValidationError))
+            else str(exc)
+        )
+        result = {"status": "failed", "error": message}
+    if args.json_output and can_write:
+        args.json_output.write_text(
+            json.dumps(result, ensure_ascii=False, indent=2) + "\n", "utf-8"
+        )
+    print(json.dumps(result, ensure_ascii=False))
+    print("检查范围不包括源码正确性与真实业务通过；市场材料仍需来源审查和真实任务验收。")
+    if result["status"] == "failed":
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

docs/plugin-development.md

@@ -1,6 +1,6 @@
-# 插件开发 SDK 与证据协议（ARTEMIS 2.3.0）
+# 插件开发 SDK 与证据协议（ARTEMIS 2.4.5）
 
-新插件必须适配本文规则，再通过实测进入市场。旧 `schema_version: 1` 仍可读取；执行插件使用版本 2，并声明 `capabilities`。需要回放面板、人工表单和报告字段时使用版本 3，见[工作区插件接口](workspace-plugins.md)。模型执行、任务队列、资源锁、超时和报告由 ARTEMIS 管理，插件不另建任务调度器，也不替用户决定用例通过。
+新插件必须适配本文规则，再通过实测进入市场。旧 `schema_version: 1` 仍可读取；执行插件使用版本 2，并声明 `capabilities`。需要回放面板、人工表单和报告字段时使用版本 3，见[工作区插件接口](workspace-plugins.md)。模型执行、任务队列、资源锁、整体调用预算和报告由 ARTEMIS 管理；插件负责内部工具的超时、取消与子进程收尾，不另建任务调度器，也不替用户决定用例通过。
 
 ## 从可运行模板开始
 
@@ -23,6 +23,8 @@ uv run python -c "import shutil; shutil.make_archive('evidence-demo', 'zip', 'ex
 
 静态检查通过不等于市场准入，也不表示业务测试通过。需按下面清单提交实际验证记录。
 
+涉及外部程序或已批准文件输入时，从 [managed-tool-demo](../examples/plugins/managed-tool-demo/README.md) 开始；它提供真实 MCP 离线回归。通用接口、故障自测和独立 `--market` 检查见[运行辅助接口与市场材料](plugin-sdk.md)。SDK 自测在临时目录运行，不访问真实设备。
+
 ## 清单与工具能力
 
 `plugin.json` 的安装、版本约束、资源、权限设置沿用 [插件说明](plugins.md)。版本 2 增加：
@@ -87,3 +89,5 @@ stdio 宿主注入 `ARTEMIS_ARTIFACTS_DIR`，插件默认把生成文件写入
 - 视觉：截图来源、遮挡、DPI、窗口切换、坐标一致、无图时拒绝盲点；录屏启动/结束/暂停恢复、编码回退、磁盘不足、时间缺口、关键节点、播放状态、中文可读性及长程体积。
 - 文件：中文文件名、覆盖保护、校验失败；终端/API：退出码、业务结果和不确定副作用。
 - Skill 必须只描述真实存在且已适配的能力，不绕过权限、调度和证据协议。保留来源和必要许可证，版本与实测范围明确；未测平台/场景不能写成已通过。
+- 外部程序验证正常退出、内部超时、取消和输出超限后的整个进程树回收；不能只确认 MCP/直接子进程退出。写操作消费文件时，批准摘要必须绑定实际消费的不可变内容，覆盖校验后替换、截断与增长。
+- 市场提交须附 [MARKET.json](plugin-sdk.md#marketjson)，绑定候选内容、组件分发授权和验收证据；对最终 ZIP 运行 `--market`。本地开发检查不强制公开许可，市场材料检查不替代源码和业务审查。

docs/plugin-sdk.md

@@ -0,0 +1,121 @@
+# 插件运行辅助接口与市场检查
+
+这些接口从 ARTEMIS **2.4.5** 开始提供，位于 `artemis.plugins.sdk`；使用 ARTEMIS 2.4.5 或更新版本的 Python，并在插件清单中声明 `artemis_version: ">=2.4.5,<3.0.0"`。它们不属于远程薄客户端 `artemis-client`，不启动后台、模型或第二套任务队列。现有不依赖这些辅助接口的插件仍按自身清单兼容旧宿主；采用这些接口才需要提高最低版本。
+
+## 已批准文件必须绑定实际使用的字节
+
+```python
+from artemis.plugins.sdk import snapshot_file
+
+snapshot = snapshot_file(authorized_path, approved_sha256)
+# 此后只消费快照。连接建立、预检或等待期间原文件发生变化，也不会改变快照。
+for chunk in snapshot.chunks():
+    transport.sendall(chunk)
+```
+
+`approved_sha256` 必须来自已批准的内容身份，不能在执行时把新文件的摘要自动当作新的批准。制作快照、验证设备身份和写入授权都应在真正写操作前完成。使用 `.data` 或只读的 `.chunks()`，不要校验之后重新打开原路径；传输后才发现摘要不符不能撤销已经发生的写入。
+
+`snapshot_file` 一次读取授权的普通文件并核对 SHA256，拒绝链接、特殊文件、大小超限和摘要不符。默认上限 64 MiB，副本是不可变内存 bytes；参数 `max_bytes` 仅作用于本次调用，选择更大上限须评估内存。它不负责用户授权或路径沙箱，插件仍要限制允许读取的范围。大文件如采用磁盘快照或流式方案，应提供等价的防修改保证并另行验证，不能恢复到“检查后重开路径”。
+
+`VerifiedFile.size`、`.sha256` 对应快照本身。原路径同长度覆盖、替换、增长或截断后，快照仍保持原内容。对写入端到端的回归必须检查实际发送字节，不能只断言预检函数被调用。
+
+## 外部工具的生命周期
+
+```python
+from artemis.plugins.sdk import ManagedProcessError, run_process
+
+try:
+    result = await run_process(
+        fixed_argv,
+        cwd=authorized_directory,
+        timeout=20,
+        input_data=snapshot.data,
+    )
+except ManagedProcessError as exc:
+    # 用稳定的 error_code 返回部分执行/未知；不回显命令或原始敏感输出，不自动重试。
+    ...
+```
+
+`fixed_argv` 必须是业务层构造的固定参数列表，不能向模型暴露任意 shell；`cwd` 为明确的现有目录。可通过 `env` 提供所需的环境白名单；未提供时继承当前插件环境，插件应自行排除不需要的密钥和工具日志变量。宿主的凭据管理不会自动证明外部程序的输出安全。
+
+`timeout` 必须为有限正数，作用于本次工具运行；标准输入最多 64 MiB。stdout、stderr 分别返回 bytes，共用默认 4 MiB 上限，可通过本次调用的 `max_output_bytes` 调整。输出超限立即停止；部分输出不作有效结果返回。`ProcessResult.returncode` 保留非零退出码，不据此生成业务用例通过结论。
+
+运行器在 Windows 先将等待启动的引导进程加入不可继承的 Job Object，再允许启动实际工具，防止快速派生后代漏出归属；父进程退出时 Job Object 同样回收其树。POSIX 使用独立会话，正常退出、超时、取消和输出超限均回收所属进程组。它是生命周期辅助，不是恶意程序沙箱，不能承诺回收主动逃离会话的程序。
+
+调用结束后不保留后台子进程。需要常驻驱动的插件应实现会话级归属、关闭与验证，不借本接口后台化工具。取消在清理后继续传播，不能吞掉 `CancelledError`。清理另有固定的有界等待；未确认完成时抛出 `process_cleanup_unconfirmed`，插件必须返回未知状态并核对资源，不声明已全部停止。
+
+常见错误码：`process_timeout`、`process_output_limit`、`process_launch_failed`、`process_ownership_failed`、`process_worker_interrupted`、`process_invalid_status`、`process_cleanup_unconfirmed`。`may_have_started=false` 只表示已知工具尚未启动；其余情况不能授权重发写操作。运行器从不重试。原始输出可能包含密钥，返回给模型前按业务字段白名单处理。
+
+宿主负责整体任务与 MCP 调用预算，插件负责内部操作及其后代。内部超时先发生时，必须在向宿主返回前收尾；宿主未超时、或只关闭 MCP 连接，都不能替代这一步。
+
+## 可运行回归
+
+```sh
+<ARTEMIS_PYTHON> -B -m artemis.plugins.sdk_checks --json-output sdk-faults.json
+<ARTEMIS_PYTHON> -B <受管工具模板目录>/test_contract.py
+```
+
+模板目录在源码仓库的 `examples/plugins/managed-tool-demo`，或本 Skill 的 `assets/managed-tool-demo`；先复制到用户指定开发目录。以下检查均使用 ARTEMIS 2.4.5 或更新版本的 Python。
+
+第一条只在临时目录创建合成文件和自己的测试进程，覆盖文件同长度覆盖、截断/增长、错误摘要、二进制 stdin、非零退出码、正常结束/超时/取消后的后代回收、输出超限、附件摘要与路径拒绝，以及部分/未知执行不能授权重试。它不连接设备、不调用模型、不修改现有任务或配置。结果明确标为 `sdk_faults_only`。
+
+第二条额外通过真实 stdio MCP 调用模板工具，核对有效输入、错误摘要、目录穿越拒绝及宿主附件回读，结果标为 `template_offline_contract`。模板见插件开发文档的受管工具示例。
+
+改写插件后，必须扩展模板测试到自己的实际入口：在最后一次预检与真正消费文件之间替换输入、让实际工具创建后代再超时/取消，并检查实际传输和进程存活。SDK 自测通过不能证明插件调用正确。还需覆盖错误/部分执行、证据丢失或摘要不符、权限、资源互斥以及真实任务时间线。
+
+## 开发检查与市场材料检查
+
+统一入口为仓库/Skill 的 `check_plugin.py`，也可执行 `python -m artemis.plugins.validation`。两处脚本调用同一个实现，不单独维护规则。
+
+```sh
+# 日常本地开发，无需公开分发许可；--live 只握手，不派发工具。
+<ARTEMIS_PYTHON> <检查脚本> <插件目录或ZIP> --live --values '{"python":"ARTEMIS解释器绝对路径"}'
+
+# 在清洁候选目录生成草稿；所有结论未验证、许可未知，不覆盖已有 MARKET.json。
+<ARTEMIS_PYTHON> <检查脚本> <插件目录> --prepare-market
+
+# 对最终候选 ZIP 检查市场材料；包含只读 MCP 声明握手，不调用业务工具。
+<ARTEMIS_PYTHON> <检查脚本> <最终ZIP> --market --values '{"python":"ARTEMIS解释器绝对路径"}' --json-output market-check.json
+```
+
+路径与 JSON 按当前 Shell 引用；密钥不放进 `--values`。`--json-output` 必须在候选目录外，不能覆盖输入 ZIP。ZIP 沿用宿主的安全解压和大小限制，检查不向已有插件库安装。`--market` 先核对材料，再握手，普通开发检查仍保持轻量。
+
+市场检查拒绝缓存、`.pyc`、虚拟环境、版本库目录、个人 `.env` 配置、链接和冲突路径。环境样例可保留 `.env.example`。不要为通过检查而清理用户运行目录；从可分发输入构建独立候选。
+
+## MARKET.json
+
+此文件随包提交，版本固定为 1，不增加 `plugin.json` 字段，旧宿主仍可安装符合其能力的插件。草稿由检查脚本生成，包含：
+
+| 字段 | 要求 |
+| --- | --- |
+| `plugin_id`、`plugin_version` | 与候选清单完全一致 |
+| `content_sha256` | 全部包内文件路径及 SHA256 的确定性摘要，只排除根层 `MARKET.json` 自身 |
+| `traits.uses_subprocesses` | 明确 true/false，不能保留 null |
+| `traits.file_inputs_for_writes` | 是否消费文件执行写操作，明确 true/false |
+| `components` | 分开列原始实现、适配层、第三方依赖/参考资料的许可和来源 |
+| `checks` | 下表全部验收项目，保留实际范围和证据 |
+
+每个组件包含 `name`、`paths`、`license`、`permission`、`license_file`、`source_file`。`paths` 为精确包内相对路径或目录前缀，`.` 表示整个包；全部可分发文件须被覆盖。只有明确的 `permission: "permitted"` 才接受，`local_only` 和 `unknown` 均阻止市场提交。许可和来源文件必须实际在包内；适配层开源许可不会重新许可原始代码、用例、协议或内部资料。可使用合适的 LicenseRef，不强制统一开源，但具体分发授权必须可审查。
+
+每条验收记录包含 `status`、`evidence_file`、`evidence_sha256`、`notes`。`passed` 必须指向真实的非空包内文档及其正确摘要，notes 说明验证环境、范围与结果；缺失、失败和未验证均拒绝。不能把历史记录、SDK 自测或模拟设备改写为本次真实业务通过。
+
+| 验收项目 | 要记录的内容 |
+| --- | --- |
+| `installation` | 安装、升级、平台和依赖兼容 |
+| `tool_contract` | 实际 MCP Schema、能力和参数限制 |
+| `failure_partial` | 错误、部分执行、未知副作用与不盲目重试 |
+| `timeout_cancel` | 实际工具入口超时与取消 |
+| `process_tree` | 工具创建后代后，正常/超时/取消的回收验证 |
+| `file_binding` | 已批准文件被替换、截断、增长时的实际消费字节 |
+| `resource_conflicts` | 同设备/桌面资源互斥 |
+| `evidence_export` | 导出索引、中文路径、摘要不符与缺失附件 |
+| `history_uninstall` | 卸载/升级后历史仍可读 |
+| `secret_redaction` | 配置、命令、输出和回执脱敏 |
+| `real_task` | 经宿主正常任务的操作、时间线、暂停/恢复、证据和报告 |
+| `source_review` | 对本次包的源码审查、来源与分发授权核对 |
+
+仅在声明无相应行为时，`process_tree`、`file_binding` 可 `not_applicable`；无 MCP 时 `tool_contract`、`timeout_cancel` 可不适用；无声明资源时 `resource_conflicts` 可不适用。仍须在 notes 中给出理由，不能把未测写成不适用。其他项目须有真实通过记录。
+
+更新任何文件后，旧材料会失效。先重跑受影响验证，再用 `--fingerprint` 查看新的内容摘要，并更新记录；不要只刷新摘要来沿用过期结论。握手结束后重新核对内容与市场记录，检查期间改动会使检查失败。最终 ZIP 检查结果另包含实际解压检查的同一份字节的 SHA256，不重新打开原路径来记录替换文件；公开发布时仍需核对固定附件、市场索引与无认证下载字节。
+
+市场材料检查验证字段、覆盖范围、摘要和证据存在性，不证明声明真实、不替作者确认权利归属，也不自动发布。源码审查和实际业务验收仍由发布方核对；文档、静态检查、握手、SDK 故障自测与真实业务结论分别记录。

docs/releases/2.4.5.md

@@ -0,0 +1,29 @@
+# ARTEMIS 2.4.5
+
+本版基于 2.4.4，补齐插件作者管理外部工具、已批准文件与市场审查材料的公共能力。远程客户端 `artemis-client`、市场插件及第三方依赖独立版本化，本次不升版。
+
+## 更新
+
+- 新增 `artemis.plugins.sdk.snapshot_file`：按明确批准的 SHA256 读取不可变快照，实际工具消费快照字节，避免校验后原文件被替换、覆盖或截断；默认输入上限 64 MiB。
+- 新增 `run_process`：固定 argv、工作目录和超时，限制 stdout/stderr 总量，在正常结束、超时与取消后回收自己启动的后代。Windows 先取得 Job Object 归属再启动实际工具；提供稳定错误码，执行结果不明时不声称尚未执行，也不自动重试。
+- 新增可独立运行的 SDK 故障检查，以及受管工具模板。模板覆盖真实 stdio MCP 调用和宿主附件回读，随源码与官方 Skill 同步分发。
+- 开发与市场检查共用一份实现。`check_plugin.py --prepare-market` 生成未验证的 `MARKET.json` 草稿；`--market` 检查来源许可、验收材料、候选内容指纹和 MCP 工具声明，并拒绝缓存、私密环境文件及握手期间包内容变化。
+- 补充模板的 LICENSE、SOURCE.md 和开发说明。市场材料检查仍需结合源码、分发权利与真实业务审查；检查命令通过不会自动发布插件。
+
+这些辅助接口管理工具生命周期和文件内容绑定；插件仍负责权限范围、业务验收、写操作状态及敏感信息处理。POSIX 使用独立进程组，不将运行器作为恶意程序沙箱。
+
+## 兼容性
+
+采用新增 SDK 的插件须声明 `artemis_version: ">=2.4.5,<3.0.0"`，并使用 ARTEMIS 2.4.5 或更新版本的 Python。正式 2.4.4 包不包含该 SDK。
+
+插件清单和证据协议保持兼容，`MARKET.json` 是独立的审查材料。未使用新增 SDK 的现有插件继续按自身最低版本运行。已独立发布的设备测试插件 `0.5.0+artemis.6` 将修复包含在插件自身，仍可用于正式 ARTEMIS 2.4.4；主程序升级不会自动更新或授权插件。
+
+## 验证
+
+Python 默认确定性回归、Ruff 格式与静态检查、质量基线、核心类型检查，以及最终源码 ZIP 的官方源和国内镜像全新安装、生产构建结果，随发布附件 `INSTALL-VERIFICATION.md` 提供。验证记录注明实际 Python、Node/npm、源码提交及 ZIP SHA256。
+
+SDK 故障检查与模板契约使用合成文件及测试进程，不替代设备、固件升级或用户业务验收。Windows 为本次实际验证环境，POSIX 分支未实测。
+
+## 升级
+
+已有安装请等待任务结束，运行 `update-cn.bat` 或 `update.bat` 后重启。新安装下载 `artemis-2.4.5-source.zip`，按 `SHA256SUMS.txt` 校验后启动。请勿直接覆盖旧安装目录。

examples/plugins/evidence-demo/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Google LLC.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

examples/plugins/evidence-demo/SOURCE.md

@@ -0,0 +1,5 @@
+# 模板来源
+
+本目录为 ARTEMIS 主程序仓库提供的文件证据开发模板，适用本目录 LICENSE 的 Apache-2.0，来源以随模板交付的主程序源码提交为准。没有包含厂商协议、内部资料或用户测试数据。
+
+复制模板后，新增代码、资料和第三方依赖需要分别记录实际来源与分发许可，并为本次候选包保存真实验证结果。模板许可不重新许可新增内容。

examples/plugins/evidence-demo/plugin.json

@@ -7,7 +7,8 @@
   "artemis_version": ">=2.0.0,<3.0.0",
   "platforms": ["win32", "linux", "darwin"],
   "architectures": ["amd64", "arm64"],
-  "server": {"command": "${config.python}", "args": ["${plugin_dir}/server.py"]},
+  "license": "Apache-2.0",
+  "server": {"command": "${config.python}", "args": ["-B", "${plugin_dir}/server.py"]},
   "config": {"python": {"label": "含 MCP 依赖的 Python", "default": "python"}},
   "skill": "SKILL.md",
   "targets": ["mixed", "computer"],

examples/plugins/managed-tool-demo/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Google LLC.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

examples/plugins/managed-tool-demo/README.md

@@ -0,0 +1,19 @@
+# 受管工具与文件快照模板
+
+本模板使用 ARTEMIS 2.4.5 新增的 `artemis.plugins.sdk`，最低宿主版本为 2.4.5。复制模板后使用该版本或更新版本的 ARTEMIS Python；正式的 2.4.4 包不提供这些接口。模板随源码和 Skill 分发，尚未发布到市场。纯文件写入可用相邻 evidence-demo，本模板用于需要外部工具或已批准文件输入的插件。
+
+复制整个目录，使用 ARTEMIS 自己的 Python：
+
+```sh
+<ARTEMIS_PYTHON> -B test_contract.py
+```
+
+测试只在临时目录创建样例和休眠进程，验证 SDK 的文件替换、超时、取消、后代回收、输出上限，以及真实 stdio MCP 调用、错误输入拒绝和宿主附件回读。结果分为 SDK 自测与本模板离线契约，不证明改写后的插件、设备或业务通过。
+
+扩展时保持固定 argv 和工作目录。先用 `snapshot_file(path, approved_sha256)` 得到不可变 bytes，再将 `snapshot.data` 或 `snapshot.chunks()` 交给实际消费者；不要重新打开原路径。默认内存输入上限 64 MiB，按明确需求选择上限；超大固件需要另外实现有等价保护的流式存储，并单独验证。
+
+`await run_process(argv, cwd=..., timeout=..., input_data=...)` 不执行 shell、不重试，返回原始退出码与 stdout/stderr。标准输入最多 64 MiB，stdout/stderr 共用默认 4 MiB 上限。它在正常退出、超时、取消、输出超限时回收后代；Windows 先将等待启动的引导进程加入 Job Object，再运行工具。POSIX 使用独立会话；这些是生命周期管理，不是恶意程序沙箱，不能托管主动逃离进程组的程序。
+
+宿主负责整个 MCP 调用的期限；插件负责内部操作和子进程。内部超时先发生时，插件必须在返回前完成回收。取消会在回收后传播，不能吞掉 `CancelledError` 后声称完成。`ManagedProcessError.error_code` 稳定且不回显命令，`may_have_started` 决定能否声明尚未执行；`process_cleanup_unconfirmed` 必须按未知处理。命令输出可能包含敏感数据，按业务白名单转换后再返回。
+
+本工具只处理已有任务文件，不提供观察或任意命令能力。保留模板 LICENSE、SOURCE.md，并补充新增代码、协议、资料与依赖的来源和业务回归。在副本中执行 `check_plugin.py --prepare-market` 生成全部未验证的市场记录；本模板自身的离线通过不能填作真实业务验收。

examples/plugins/managed-tool-demo/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: managed-tool-demo
+description: 对任务目录中已明确批准的文件制作不可变快照，并通过固定工具校验、保存回执。
+---
+
+调用 plugin_load 返回映射后的 verify_note。name 只允许任务目录内的普通文件名，sha256 必须是用户明确批准的内容摘要；不要临时计算另一份内容的摘要来绕过批准。
+
+固定工具只读取快照并计算摘要，不提供任意命令、不访问设备或网络。校验与回执保存成功不等于业务测试通过。超时、取消或结果不明时先观察实际状态，不自动重试写操作。没有视觉能力，不能独立承担纯电脑任务。

examples/plugins/managed-tool-demo/SOURCE.md

@@ -0,0 +1,5 @@
+# 模板来源
+
+本目录为 ARTEMIS 主程序仓库提供的插件开发模板，适用本目录 LICENSE 的 Apache-2.0。来源为主程序仓库中随该模板交付的对应源码提交；模板使用主程序的 `artemis.plugins.sdk`，不另行分发设备协议、厂商资料或用户用例。
+
+复制后应记录自己的代码、所适配上游、第三方依赖、协议资料和用例的实际来源与许可证；新增内容的分发范围需要分别确认。模板的许可不会重新许可这些新增材料。运行记录须使用自己的实际候选版本和验证结果，不能沿用模板演示结论。

examples/plugins/managed-tool-demo/plugin.json

@@ -0,0 +1,23 @@
+{
+  "schema_version": 2,
+  "id": "managed-tool-demo",
+  "name": "受管工具与文件快照示例",
+  "version": "1.0.0",
+  "description": "开发模板：读取已批准的任务文件快照，调用固定校验程序并保存真实回执。",
+  "artemis_version": ">=2.4.5,<3.0.0",
+  "platforms": ["win32", "linux", "darwin"],
+  "architectures": ["amd64", "arm64"],
+  "license": "Apache-2.0",
+  "server": {"command": "${config.python}", "args": ["-B", "${plugin_dir}/server.py"]},
+  "config": {"python": {"label": "当前 ARTEMIS 环境的 Python", "default": "python"}},
+  "skill": "SKILL.md",
+  "targets": ["android", "mixed", "computer"],
+  "resources": [],
+  "capabilities": {
+    "kind": "file", "recording": "none", "required_tools": ["verify_note"],
+    "tools": {"verify_note": {
+      "effect": "read", "observation": false, "idempotent": false,
+      "cancellation": "confirmed", "evidence": ["text", "file"]
+    }}
+  }
+}

examples/plugins/managed-tool-demo/server.py

@@ -0,0 +1,128 @@
+"""A fixed checksum tool using the installed ARTEMIS authoring SDK."""
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import sys
+from typing import Annotated
+import uuid
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import CallToolResult, TextContent, ToolAnnotations
+from pydantic import Field
+
+from artemis.plugins.sdk import ManagedProcessError, run_process, snapshot_file
+
+mcp = FastMCP("managed-tool-demo")
+CHECKSUM = "import hashlib,sys; print(hashlib.sha256(sys.stdin.buffer.read()).hexdigest())"
+
+
+def failure(code: str, *, execution: str = "not_started") -> CallToolResult:
+    return CallToolResult(
+        isError=True,
+        content=[TextContent(type="text", text=code)],
+        structuredContent={
+            "artemis": {
+                "version": 1,
+                "execution": execution,
+                "side_effect": "none",
+                "error_code": code,
+                "retryable": False,
+            }
+        },
+    )
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=False)
+)
+async def verify_note(
+    name: Annotated[str, Field(min_length=1, max_length=180)],
+    sha256: Annotated[str, Field(pattern=r"^[a-fA-F0-9]{64}$")],
+) -> CallToolResult:
+    """Verify a task-owned file of at most 64 MiB against its explicitly approved SHA256."""
+    location = os.environ.get("ARTEMIS_ARTIFACTS_DIR")
+    if (
+        not location
+        or name in {".", ".."}
+        or Path(name).name != name
+        or any(c in name for c in '/\\:*?"<>|')
+        or name.rstrip(" .") != name
+        or any(ord(c) < 32 for c in name)
+    ):
+        return failure("invalid_task_filename")
+    root = Path(location)
+    try:
+        if root.is_symlink() or root.is_junction() or root.resolve() != root.absolute():
+            return failure("invalid_task_directory")
+        snapshot = snapshot_file(root / name, sha256)
+    except (OSError, ValueError):
+        return failure("input_not_bound_to_approved_digest")
+    try:
+        # Never reopen the original pathname after verification. The fixed tool
+        # receives the same immutable bytes even if the source file changes.
+        result = await run_process(
+            [sys.executable, "-I", "-B", "-c", CHECKSUM],
+            cwd=root,
+            timeout=5,
+            input_data=snapshot.data,
+        )
+    except ManagedProcessError as exc:
+        return failure(
+            exc.error_code,
+            execution="unknown"
+            if exc.error_code == "process_cleanup_unconfirmed"
+            else "partial"
+            if exc.may_have_started
+            else "not_started",
+        )
+    if (
+        result.returncode != 0
+        or result.stdout.strip().decode("ascii", errors="replace") != snapshot.sha256
+    ):
+        return failure("checksum_tool_result_invalid", execution="partial")
+    content = json.dumps(
+        {
+            "source_name": name,
+            "snapshot_sha256": snapshot.sha256,
+            "snapshot_bytes": snapshot.size,
+            "tool_returncode": result.returncode,
+            "test_verdict": "not_evaluated",
+        },
+        ensure_ascii=False,
+    ).encode("utf-8")
+    receipt_name = f"verified-{uuid.uuid4().hex}.json"
+    try:
+        with (root / receipt_name).open("xb") as handle:
+            handle.write(content)
+    except OSError:
+        return failure("receipt_write_failed", execution="partial")
+    return CallToolResult(
+        content=[TextContent(type="text", text="已核对批准的文件快照，回执已保存。")],
+        structuredContent={
+            "snapshot_sha256": snapshot.sha256,
+            "artemis": {
+                "version": 1,
+                "execution": "completed",
+                "side_effect": "none",
+                "retryable": False,
+                "source": {
+                    "kind": "file",
+                    "target_id": "task-artifacts",
+                    "label": "已批准文件快照",
+                },
+                "attachments": [
+                    {
+                        "name": receipt_name,
+                        "media_type": "application/json",
+                        "sha256": hashlib.sha256(content).hexdigest(),
+                    }
+                ],
+            },
+        },
+    )
+
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")

examples/plugins/managed-tool-demo/test_contract.py

@@ -0,0 +1,69 @@
+"""Run with the current ARTEMIS Python; no pytest/device/service/config needed."""
+
+import asyncio
+import hashlib
+import json
+from pathlib import Path
+import sys
+import tempfile
+
+from artemis.plugins.evidence import persist_attachments, validate_tools
+from artemis.plugins.models import PluginManifest, PluginProfile
+from artemis.plugins.sdk_checks import run_checks
+from artemis.plugins.session import PluginSession, resolve_server
+
+
+async def run_contract():
+    directory = Path(__file__).resolve().parent
+    manifest = PluginManifest.model_validate_json((directory / "plugin.json").read_text("utf-8"))
+    with tempfile.TemporaryDirectory(prefix="artemis-template-contract-") as temporary:
+        trace = Path(temporary).resolve()
+        artifacts = trace / "artifacts" / "plugins" / manifest.id
+        artifacts.mkdir(parents=True)
+        content = "synthetic local sample\n中文\x00".encode()
+        (artifacts / "样例.txt").write_bytes(content)
+        server = resolve_server(
+            manifest, PluginProfile(values={"python": sys.executable}), directory
+        )
+        server.env["ARTEMIS_ARTIFACTS_DIR"] = str(artifacts)
+        server.env["PYTHONDONTWRITEBYTECODE"] = "1"
+        session = await PluginSession(server, directory).start()
+        try:
+            validate_tools(manifest, session.tools)
+            success = await session.call(
+                "verify_note", {"name": "样例.txt", "sha256": hashlib.sha256(content).hexdigest()}
+            )
+            if success.isError:
+                raise AssertionError("MCP 校验入口失败")
+            receipt = success.structuredContent["artemis"]
+            attachments = persist_attachments(trace, manifest.id, receipt["attachments"])
+            if len(attachments) != 1:
+                raise AssertionError("宿主未回读到校验回执")
+            for name, digest in (("样例.txt", "0" * 64), ("../outside.txt", "0" * 64)):
+                denied = await session.call("verify_note", {"name": name, "sha256": digest})
+                if (
+                    not denied.isError
+                    or denied.structuredContent["artemis"]["execution"] != "not_started"
+                ):
+                    raise AssertionError("无效输入没有在工具启动前拒绝")
+        finally:
+            await session.aclose()
+    return {
+        "status": "passed",
+        "scope": "template_offline_contract",
+        "mcp_calls": 3,
+        "host_attachments_verified": 1,
+        "real_device_actions": False,
+    }
+
+
+async def main():
+    print(
+        json.dumps(
+            {"sdk": await run_checks(), "template": await run_contract()}, ensure_ascii=False
+        )
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pyproject.toml

@@ -14,7 +14,7 @@
 
 [project]
 name = "artemis"
-version = "2.4.4"
+version = "2.4.5"
 description = "Autonomous AI Assistant for Mobile Automation"
 
 authors = [

pyright-core.json

@@ -6,6 +6,10 @@
     "artemis/graph/visibility.py",
     "artemis/runtime/adb_endpoint.py",
     "artemis/runtime/process_probe.py",
+    "artemis/plugins/sdk.py",
+    "artemis/plugins/market.py",
+    "artemis/plugins/validation.py",
+    "artemis/plugins/sdk_checks.py",
     "artemis/mcp/action_types.py",
     "artemis/data_engine/models.py",
     "artemis/agents/explorer/perception_tools.py",

scripts/check_plugin.py

@@ -1,46 +1,6 @@
-"""Validate a plugin package; --live checks MCP declarations without executing actions."""
+"""Shared plugin development and market-materials checker; no tool actions."""
 
-import argparse
+from artemis.plugins.validation import check as check, main
-import asyncio
-import json
-from pathlib import Path
-
-from artemis.plugins.evidence import validate_tools
-from artemis.plugins.models import PluginManifest, PluginProfile
-from artemis.plugins.session import PluginSession, resolve_server
-from artemis.plugins.store import contained_path
-
-
-async def check(directory: Path, live: bool, values: dict[str, str]) -> None:
-    manifest = PluginManifest.model_validate_json((directory / "plugin.json").read_text("utf-8"))
-    manifest.check_compatible()
-    if manifest.skill:
-        skill = contained_path(directory, manifest.skill)
-        if not skill.is_file() or not skill.read_text("utf-8").strip():
-            raise ValueError("缺少有效的 Skill")
-    if manifest.schema_version not in {2, 3}:
-        raise ValueError("新市场插件必须适配 schema_version=2 或 3")
-    if live and manifest.server:
-        server = resolve_server(manifest, PluginProfile(values=values), directory)
-        session = await PluginSession(server, directory).start()
-        try:
-            validate_tools(manifest, session.tools)
-        finally:
-            await session.aclose()
-    print(
-        f"PASS {manifest.id} {manifest.version}: 清单/兼容性/Skill"
-        + ("/MCP 工具声明" if live and manifest.server else "")
-    )
-    print("此检查不代替实际执行、超时取消、证据导出和视觉能力验收。")
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("directory", type=Path)
-    parser.add_argument("--live", action="store_true")
-    parser.add_argument("--values", default="{}", help="普通配置 JSON；不得包含密钥")
-    args = parser.parse_args()
-    asyncio.run(check(args.directory.resolve(), args.live, json.loads(args.values)))
 
 
 if __name__ == "__main__":

skills/artemis-use/SKILL.md

@@ -17,6 +17,7 @@ ARTEMIS 自己编排手机和已授权插件，共用网页的任务队列、历
 | 给出任务编号，问失败原因、token、缓存、录像或最终结论 | [诊断与复盘](references/diagnostics.md) |
 | 使用电脑、路由器、终端等已安装能力 | [插件任务参数](references/plugins.md) |
 | 编写、适配、验证或发布 ARTEMIS 插件 | [插件开发规范](references/plugin-development.md)，按需读取 [清单与市场协议](references/plugin-manifest.md) |
+| 插件调用外部程序、消费已批准文件或准备市场材料 | [运行辅助接口、故障自测与市场检查](references/plugin-sdk.md) |
 | 开发回放侧栏、人工表单或扩展报告字段 | [工作区插件接口（ARTEMIS 2.3.0+）](references/workspace-plugins.md) |
 
 只读当前任务相关参考。普通执行不加载插件开发文档。

skills/artemis-use/assets/evidence-demo/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Google LLC.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

skills/artemis-use/assets/evidence-demo/SOURCE.md

@@ -0,0 +1,5 @@
+# 模板来源
+
+本目录为 ARTEMIS 主程序仓库提供的文件证据开发模板，适用本目录 LICENSE 的 Apache-2.0，来源以随模板交付的主程序源码提交为准。没有包含厂商协议、内部资料或用户测试数据。
+
+复制模板后，新增代码、资料和第三方依赖需要分别记录实际来源与分发许可，并为本次候选包保存真实验证结果。模板许可不重新许可新增内容。

skills/artemis-use/assets/evidence-demo/plugin.json

@@ -7,7 +7,8 @@
   "artemis_version": ">=2.0.0,<3.0.0",
   "platforms": ["win32", "linux", "darwin"],
   "architectures": ["amd64", "arm64"],
-  "server": {"command": "${config.python}", "args": ["${plugin_dir}/server.py"]},
+  "license": "Apache-2.0",
+  "server": {"command": "${config.python}", "args": ["-B", "${plugin_dir}/server.py"]},
   "config": {"python": {"label": "含 MCP 依赖的 Python", "default": "python"}},
   "skill": "SKILL.md",
   "targets": ["mixed", "computer"],

skills/artemis-use/assets/managed-tool-demo/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Google LLC.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

skills/artemis-use/assets/managed-tool-demo/README.md

@@ -0,0 +1,19 @@
+# 受管工具与文件快照模板
+
+本模板使用 ARTEMIS 2.4.5 新增的 `artemis.plugins.sdk`，最低宿主版本为 2.4.5。复制模板后使用该版本或更新版本的 ARTEMIS Python；正式的 2.4.4 包不提供这些接口。模板随源码和 Skill 分发，尚未发布到市场。纯文件写入可用相邻 evidence-demo，本模板用于需要外部工具或已批准文件输入的插件。
+
+复制整个目录，使用 ARTEMIS 自己的 Python：
+
+```sh
+<ARTEMIS_PYTHON> -B test_contract.py
+```
+
+测试只在临时目录创建样例和休眠进程，验证 SDK 的文件替换、超时、取消、后代回收、输出上限，以及真实 stdio MCP 调用、错误输入拒绝和宿主附件回读。结果分为 SDK 自测与本模板离线契约，不证明改写后的插件、设备或业务通过。
+
+扩展时保持固定 argv 和工作目录。先用 `snapshot_file(path, approved_sha256)` 得到不可变 bytes，再将 `snapshot.data` 或 `snapshot.chunks()` 交给实际消费者；不要重新打开原路径。默认内存输入上限 64 MiB，按明确需求选择上限；超大固件需要另外实现有等价保护的流式存储，并单独验证。
+
+`await run_process(argv, cwd=..., timeout=..., input_data=...)` 不执行 shell、不重试，返回原始退出码与 stdout/stderr。标准输入最多 64 MiB，stdout/stderr 共用默认 4 MiB 上限。它在正常退出、超时、取消、输出超限时回收后代；Windows 先将等待启动的引导进程加入 Job Object，再运行工具。POSIX 使用独立会话；这些是生命周期管理，不是恶意程序沙箱，不能托管主动逃离进程组的程序。
+
+宿主负责整个 MCP 调用的期限；插件负责内部操作和子进程。内部超时先发生时，插件必须在返回前完成回收。取消会在回收后传播，不能吞掉 `CancelledError` 后声称完成。`ManagedProcessError.error_code` 稳定且不回显命令，`may_have_started` 决定能否声明尚未执行；`process_cleanup_unconfirmed` 必须按未知处理。命令输出可能包含敏感数据，按业务白名单转换后再返回。
+
+本工具只处理已有任务文件，不提供观察或任意命令能力。保留模板 LICENSE、SOURCE.md，并补充新增代码、协议、资料与依赖的来源和业务回归。在副本中执行 `check_plugin.py --prepare-market` 生成全部未验证的市场记录；本模板自身的离线通过不能填作真实业务验收。

skills/artemis-use/assets/managed-tool-demo/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: managed-tool-demo
+description: 对任务目录中已明确批准的文件制作不可变快照，并通过固定工具校验、保存回执。
+---
+
+调用 plugin_load 返回映射后的 verify_note。name 只允许任务目录内的普通文件名，sha256 必须是用户明确批准的内容摘要；不要临时计算另一份内容的摘要来绕过批准。
+
+固定工具只读取快照并计算摘要，不提供任意命令、不访问设备或网络。校验与回执保存成功不等于业务测试通过。超时、取消或结果不明时先观察实际状态，不自动重试写操作。没有视觉能力，不能独立承担纯电脑任务。

skills/artemis-use/assets/managed-tool-demo/SOURCE.md

@@ -0,0 +1,5 @@
+# 模板来源
+
+本目录为 ARTEMIS 主程序仓库提供的插件开发模板，适用本目录 LICENSE 的 Apache-2.0。来源为主程序仓库中随该模板交付的对应源码提交；模板使用主程序的 `artemis.plugins.sdk`，不另行分发设备协议、厂商资料或用户用例。
+
+复制后应记录自己的代码、所适配上游、第三方依赖、协议资料和用例的实际来源与许可证；新增内容的分发范围需要分别确认。模板的许可不会重新许可这些新增材料。运行记录须使用自己的实际候选版本和验证结果，不能沿用模板演示结论。

skills/artemis-use/assets/managed-tool-demo/plugin.json

@@ -0,0 +1,23 @@
+{
+  "schema_version": 2,
+  "id": "managed-tool-demo",
+  "name": "受管工具与文件快照示例",
+  "version": "1.0.0",
+  "description": "开发模板：读取已批准的任务文件快照，调用固定校验程序并保存真实回执。",
+  "artemis_version": ">=2.4.5,<3.0.0",
+  "platforms": ["win32", "linux", "darwin"],
+  "architectures": ["amd64", "arm64"],
+  "license": "Apache-2.0",
+  "server": {"command": "${config.python}", "args": ["-B", "${plugin_dir}/server.py"]},
+  "config": {"python": {"label": "当前 ARTEMIS 环境的 Python", "default": "python"}},
+  "skill": "SKILL.md",
+  "targets": ["android", "mixed", "computer"],
+  "resources": [],
+  "capabilities": {
+    "kind": "file", "recording": "none", "required_tools": ["verify_note"],
+    "tools": {"verify_note": {
+      "effect": "read", "observation": false, "idempotent": false,
+      "cancellation": "confirmed", "evidence": ["text", "file"]
+    }}
+  }
+}

skills/artemis-use/assets/managed-tool-demo/server.py

@@ -0,0 +1,128 @@
+"""A fixed checksum tool using the installed ARTEMIS authoring SDK."""
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import sys
+from typing import Annotated
+import uuid
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import CallToolResult, TextContent, ToolAnnotations
+from pydantic import Field
+
+from artemis.plugins.sdk import ManagedProcessError, run_process, snapshot_file
+
+mcp = FastMCP("managed-tool-demo")
+CHECKSUM = "import hashlib,sys; print(hashlib.sha256(sys.stdin.buffer.read()).hexdigest())"
+
+
+def failure(code: str, *, execution: str = "not_started") -> CallToolResult:
+    return CallToolResult(
+        isError=True,
+        content=[TextContent(type="text", text=code)],
+        structuredContent={
+            "artemis": {
+                "version": 1,
+                "execution": execution,
+                "side_effect": "none",
+                "error_code": code,
+                "retryable": False,
+            }
+        },
+    )
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=False)
+)
+async def verify_note(
+    name: Annotated[str, Field(min_length=1, max_length=180)],
+    sha256: Annotated[str, Field(pattern=r"^[a-fA-F0-9]{64}$")],
+) -> CallToolResult:
+    """Verify a task-owned file of at most 64 MiB against its explicitly approved SHA256."""
+    location = os.environ.get("ARTEMIS_ARTIFACTS_DIR")
+    if (
+        not location
+        or name in {".", ".."}
+        or Path(name).name != name
+        or any(c in name for c in '/\\:*?"<>|')
+        or name.rstrip(" .") != name
+        or any(ord(c) < 32 for c in name)
+    ):
+        return failure("invalid_task_filename")
+    root = Path(location)
+    try:
+        if root.is_symlink() or root.is_junction() or root.resolve() != root.absolute():
+            return failure("invalid_task_directory")
+        snapshot = snapshot_file(root / name, sha256)
+    except (OSError, ValueError):
+        return failure("input_not_bound_to_approved_digest")
+    try:
+        # Never reopen the original pathname after verification. The fixed tool
+        # receives the same immutable bytes even if the source file changes.
+        result = await run_process(
+            [sys.executable, "-I", "-B", "-c", CHECKSUM],
+            cwd=root,
+            timeout=5,
+            input_data=snapshot.data,
+        )
+    except ManagedProcessError as exc:
+        return failure(
+            exc.error_code,
+            execution="unknown"
+            if exc.error_code == "process_cleanup_unconfirmed"
+            else "partial"
+            if exc.may_have_started
+            else "not_started",
+        )
+    if (
+        result.returncode != 0
+        or result.stdout.strip().decode("ascii", errors="replace") != snapshot.sha256
+    ):
+        return failure("checksum_tool_result_invalid", execution="partial")
+    content = json.dumps(
+        {
+            "source_name": name,
+            "snapshot_sha256": snapshot.sha256,
+            "snapshot_bytes": snapshot.size,
+            "tool_returncode": result.returncode,
+            "test_verdict": "not_evaluated",
+        },
+        ensure_ascii=False,
+    ).encode("utf-8")
+    receipt_name = f"verified-{uuid.uuid4().hex}.json"
+    try:
+        with (root / receipt_name).open("xb") as handle:
+            handle.write(content)
+    except OSError:
+        return failure("receipt_write_failed", execution="partial")
+    return CallToolResult(
+        content=[TextContent(type="text", text="已核对批准的文件快照，回执已保存。")],
+        structuredContent={
+            "snapshot_sha256": snapshot.sha256,
+            "artemis": {
+                "version": 1,
+                "execution": "completed",
+                "side_effect": "none",
+                "retryable": False,
+                "source": {
+                    "kind": "file",
+                    "target_id": "task-artifacts",
+                    "label": "已批准文件快照",
+                },
+                "attachments": [
+                    {
+                        "name": receipt_name,
+                        "media_type": "application/json",
+                        "sha256": hashlib.sha256(content).hexdigest(),
+                    }
+                ],
+            },
+        },
+    )
+
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")

skills/artemis-use/assets/managed-tool-demo/test_contract.py

@@ -0,0 +1,69 @@
+"""Run with the current ARTEMIS Python; no pytest/device/service/config needed."""
+
+import asyncio
+import hashlib
+import json
+from pathlib import Path
+import sys
+import tempfile
+
+from artemis.plugins.evidence import persist_attachments, validate_tools
+from artemis.plugins.models import PluginManifest, PluginProfile
+from artemis.plugins.sdk_checks import run_checks
+from artemis.plugins.session import PluginSession, resolve_server
+
+
+async def run_contract():
+    directory = Path(__file__).resolve().parent
+    manifest = PluginManifest.model_validate_json((directory / "plugin.json").read_text("utf-8"))
+    with tempfile.TemporaryDirectory(prefix="artemis-template-contract-") as temporary:
+        trace = Path(temporary).resolve()
+        artifacts = trace / "artifacts" / "plugins" / manifest.id
+        artifacts.mkdir(parents=True)
+        content = "synthetic local sample\n中文\x00".encode()
+        (artifacts / "样例.txt").write_bytes(content)
+        server = resolve_server(
+            manifest, PluginProfile(values={"python": sys.executable}), directory
+        )
+        server.env["ARTEMIS_ARTIFACTS_DIR"] = str(artifacts)
+        server.env["PYTHONDONTWRITEBYTECODE"] = "1"
+        session = await PluginSession(server, directory).start()
+        try:
+            validate_tools(manifest, session.tools)
+            success = await session.call(
+                "verify_note", {"name": "样例.txt", "sha256": hashlib.sha256(content).hexdigest()}
+            )
+            if success.isError:
+                raise AssertionError("MCP 校验入口失败")
+            receipt = success.structuredContent["artemis"]
+            attachments = persist_attachments(trace, manifest.id, receipt["attachments"])
+            if len(attachments) != 1:
+                raise AssertionError("宿主未回读到校验回执")
+            for name, digest in (("样例.txt", "0" * 64), ("../outside.txt", "0" * 64)):
+                denied = await session.call("verify_note", {"name": name, "sha256": digest})
+                if (
+                    not denied.isError
+                    or denied.structuredContent["artemis"]["execution"] != "not_started"
+                ):
+                    raise AssertionError("无效输入没有在工具启动前拒绝")
+        finally:
+            await session.aclose()
+    return {
+        "status": "passed",
+        "scope": "template_offline_contract",
+        "mcp_calls": 3,
+        "host_attachments_verified": 1,
+        "real_device_actions": False,
+    }
+
+
+async def main():
+    print(
+        json.dumps(
+            {"sdk": await run_checks(), "template": await run_contract()}, ensure_ascii=False
+        )
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

skills/artemis-use/references/plugin-development.md

@@ -1,6 +1,6 @@
-# 插件开发 SDK 与证据协议（ARTEMIS 2.3.0）
+# 插件开发 SDK 与证据协议（ARTEMIS 2.4.5）
 
-新插件必须适配本文规则，再通过实测进入市场。旧 `schema_version: 1` 仍可读取；执行插件使用版本 2，并声明 `capabilities`。工作区面板和人工表单使用版本 3，详见[工作区插件接口](workspace-plugins.md)。纯工作区插件不加入任务执行选择，不向模型开放人工评审写入工具。模型执行、任务队列、资源锁、超时和报告由 ARTEMIS 管理，插件不另建任务调度器，也不替用户决定用例通过。
+新插件必须适配本文规则，再通过实测进入市场。旧 `schema_version: 1` 仍可读取；执行插件使用版本 2，并声明 `capabilities`。工作区面板和人工表单使用版本 3，详见[工作区插件接口](workspace-plugins.md)。纯工作区插件不加入任务执行选择，不向模型开放人工评审写入工具。模型执行、任务队列、资源锁、整体调用预算和报告由 ARTEMIS 管理；插件负责内部工具的超时、取消与子进程收尾，不另建任务调度器，也不替用户决定用例通过。
 
 ## 从可运行模板开始
 
@@ -25,6 +25,12 @@
 
 静态检查通过不等于市场准入，也不表示业务测试通过。需按下面清单提交实际验证记录。
 
+## 运行辅助接口与市场材料
+
+涉及外部程序或已批准文件输入时，复制 [managed-tool-demo](../assets/managed-tool-demo/README.md) 整个目录开始；最低宿主为 ARTEMIS 2.4.5，使用该版本或更新版本的 Python。固定 argv 和工作目录，用 `snapshot_file` 取得已批准的不可变字节并交给工具，不重新打开原路径。内部超时、取消和正常结束都要回收自己启动的后代；无法确认收尾时如实返回未知状态，不自动重发写操作。SDK 故障检查与模板离线通过不能替代真实任务。
+
+接口与命令见 [SDK 与市场材料](plugin-sdk.md)。在用户插件目录的副本中，使用 `<ARTEMIS_PYTHON> <本Skill目录>/scripts/check_plugin.py <插件目录> --prepare-market` 生成未验证的 `MARKET.json`，再补全来源许可、组件分发授权与实际验收证据。对最终 ZIP 使用同一脚本的 `--market` 核对内容摘要与材料；它只握手核对 MCP 声明，不执行业务工具，也不自动发布。
+
 ## 清单与工具能力
 
 `plugin.json` 的安装、版本约束、资源、权限设置沿用 [插件说明](plugin-manifest.md)。版本 2 增加：

skills/artemis-use/references/plugin-sdk.md

@@ -0,0 +1,121 @@
+# 插件运行辅助接口与市场检查
+
+这些接口从 ARTEMIS **2.4.5** 开始提供，位于 `artemis.plugins.sdk`；使用 ARTEMIS 2.4.5 或更新版本的 Python，并在插件清单中声明 `artemis_version: ">=2.4.5,<3.0.0"`。它们不属于远程薄客户端 `artemis-client`，不启动后台、模型或第二套任务队列。现有不依赖这些辅助接口的插件仍按自身清单兼容旧宿主；采用这些接口才需要提高最低版本。
+
+## 已批准文件必须绑定实际使用的字节
+
+```python
+from artemis.plugins.sdk import snapshot_file
+
+snapshot = snapshot_file(authorized_path, approved_sha256)
+# 此后只消费快照。连接建立、预检或等待期间原文件发生变化，也不会改变快照。
+for chunk in snapshot.chunks():
+    transport.sendall(chunk)
+```
+
+`approved_sha256` 必须来自已批准的内容身份，不能在执行时把新文件的摘要自动当作新的批准。制作快照、验证设备身份和写入授权都应在真正写操作前完成。使用 `.data` 或只读的 `.chunks()`，不要校验之后重新打开原路径；传输后才发现摘要不符不能撤销已经发生的写入。
+
+`snapshot_file` 一次读取授权的普通文件并核对 SHA256，拒绝链接、特殊文件、大小超限和摘要不符。默认上限 64 MiB，副本是不可变内存 bytes；参数 `max_bytes` 仅作用于本次调用，选择更大上限须评估内存。它不负责用户授权或路径沙箱，插件仍要限制允许读取的范围。大文件如采用磁盘快照或流式方案，应提供等价的防修改保证并另行验证，不能恢复到“检查后重开路径”。
+
+`VerifiedFile.size`、`.sha256` 对应快照本身。原路径同长度覆盖、替换、增长或截断后，快照仍保持原内容。对写入端到端的回归必须检查实际发送字节，不能只断言预检函数被调用。
+
+## 外部工具的生命周期
+
+```python
+from artemis.plugins.sdk import ManagedProcessError, run_process
+
+try:
+    result = await run_process(
+        fixed_argv,
+        cwd=authorized_directory,
+        timeout=20,
+        input_data=snapshot.data,
+    )
+except ManagedProcessError as exc:
+    # 用稳定的 error_code 返回部分执行/未知；不回显命令或原始敏感输出，不自动重试。
+    ...
+```
+
+`fixed_argv` 必须是业务层构造的固定参数列表，不能向模型暴露任意 shell；`cwd` 为明确的现有目录。可通过 `env` 提供所需的环境白名单；未提供时继承当前插件环境，插件应自行排除不需要的密钥和工具日志变量。宿主的凭据管理不会自动证明外部程序的输出安全。
+
+`timeout` 必须为有限正数，作用于本次工具运行；标准输入最多 64 MiB。stdout、stderr 分别返回 bytes，共用默认 4 MiB 上限，可通过本次调用的 `max_output_bytes` 调整。输出超限立即停止；部分输出不作有效结果返回。`ProcessResult.returncode` 保留非零退出码，不据此生成业务用例通过结论。
+
+运行器在 Windows 先将等待启动的引导进程加入不可继承的 Job Object，再允许启动实际工具，防止快速派生后代漏出归属；父进程退出时 Job Object 同样回收其树。POSIX 使用独立会话，正常退出、超时、取消和输出超限均回收所属进程组。它是生命周期辅助，不是恶意程序沙箱，不能承诺回收主动逃离会话的程序。
+
+调用结束后不保留后台子进程。需要常驻驱动的插件应实现会话级归属、关闭与验证，不借本接口后台化工具。取消在清理后继续传播，不能吞掉 `CancelledError`。清理另有固定的有界等待；未确认完成时抛出 `process_cleanup_unconfirmed`，插件必须返回未知状态并核对资源，不声明已全部停止。
+
+常见错误码：`process_timeout`、`process_output_limit`、`process_launch_failed`、`process_ownership_failed`、`process_worker_interrupted`、`process_invalid_status`、`process_cleanup_unconfirmed`。`may_have_started=false` 只表示已知工具尚未启动；其余情况不能授权重发写操作。运行器从不重试。原始输出可能包含密钥，返回给模型前按业务字段白名单处理。
+
+宿主负责整体任务与 MCP 调用预算，插件负责内部操作及其后代。内部超时先发生时，必须在向宿主返回前收尾；宿主未超时、或只关闭 MCP 连接，都不能替代这一步。
+
+## 可运行回归
+
+```sh
+<ARTEMIS_PYTHON> -B -m artemis.plugins.sdk_checks --json-output sdk-faults.json
+<ARTEMIS_PYTHON> -B <受管工具模板目录>/test_contract.py
+```
+
+模板目录在源码仓库的 `examples/plugins/managed-tool-demo`，或本 Skill 的 `assets/managed-tool-demo`；先复制到用户指定开发目录。以下检查均使用 ARTEMIS 2.4.5 或更新版本的 Python。
+
+第一条只在临时目录创建合成文件和自己的测试进程，覆盖文件同长度覆盖、截断/增长、错误摘要、二进制 stdin、非零退出码、正常结束/超时/取消后的后代回收、输出超限、附件摘要与路径拒绝，以及部分/未知执行不能授权重试。它不连接设备、不调用模型、不修改现有任务或配置。结果明确标为 `sdk_faults_only`。
+
+第二条额外通过真实 stdio MCP 调用模板工具，核对有效输入、错误摘要、目录穿越拒绝及宿主附件回读，结果标为 `template_offline_contract`。模板见插件开发文档的受管工具示例。
+
+改写插件后，必须扩展模板测试到自己的实际入口：在最后一次预检与真正消费文件之间替换输入、让实际工具创建后代再超时/取消，并检查实际传输和进程存活。SDK 自测通过不能证明插件调用正确。还需覆盖错误/部分执行、证据丢失或摘要不符、权限、资源互斥以及真实任务时间线。
+
+## 开发检查与市场材料检查
+
+统一入口为仓库/Skill 的 `check_plugin.py`，也可执行 `python -m artemis.plugins.validation`。两处脚本调用同一个实现，不单独维护规则。
+
+```sh
+# 日常本地开发，无需公开分发许可；--live 只握手，不派发工具。
+<ARTEMIS_PYTHON> <检查脚本> <插件目录或ZIP> --live --values '{"python":"ARTEMIS解释器绝对路径"}'
+
+# 在清洁候选目录生成草稿；所有结论未验证、许可未知，不覆盖已有 MARKET.json。
+<ARTEMIS_PYTHON> <检查脚本> <插件目录> --prepare-market
+
+# 对最终候选 ZIP 检查市场材料；包含只读 MCP 声明握手，不调用业务工具。
+<ARTEMIS_PYTHON> <检查脚本> <最终ZIP> --market --values '{"python":"ARTEMIS解释器绝对路径"}' --json-output market-check.json
+```
+
+路径与 JSON 按当前 Shell 引用；密钥不放进 `--values`。`--json-output` 必须在候选目录外，不能覆盖输入 ZIP。ZIP 沿用宿主的安全解压和大小限制，检查不向已有插件库安装。`--market` 先核对材料，再握手，普通开发检查仍保持轻量。
+
+市场检查拒绝缓存、`.pyc`、虚拟环境、版本库目录、个人 `.env` 配置、链接和冲突路径。环境样例可保留 `.env.example`。不要为通过检查而清理用户运行目录；从可分发输入构建独立候选。
+
+## MARKET.json
+
+此文件随包提交，版本固定为 1，不增加 `plugin.json` 字段，旧宿主仍可安装符合其能力的插件。草稿由检查脚本生成，包含：
+
+| 字段 | 要求 |
+| --- | --- |
+| `plugin_id`、`plugin_version` | 与候选清单完全一致 |
+| `content_sha256` | 全部包内文件路径及 SHA256 的确定性摘要，只排除根层 `MARKET.json` 自身 |
+| `traits.uses_subprocesses` | 明确 true/false，不能保留 null |
+| `traits.file_inputs_for_writes` | 是否消费文件执行写操作，明确 true/false |
+| `components` | 分开列原始实现、适配层、第三方依赖/参考资料的许可和来源 |
+| `checks` | 下表全部验收项目，保留实际范围和证据 |
+
+每个组件包含 `name`、`paths`、`license`、`permission`、`license_file`、`source_file`。`paths` 为精确包内相对路径或目录前缀，`.` 表示整个包；全部可分发文件须被覆盖。只有明确的 `permission: "permitted"` 才接受，`local_only` 和 `unknown` 均阻止市场提交。许可和来源文件必须实际在包内；适配层开源许可不会重新许可原始代码、用例、协议或内部资料。可使用合适的 LicenseRef，不强制统一开源，但具体分发授权必须可审查。
+
+每条验收记录包含 `status`、`evidence_file`、`evidence_sha256`、`notes`。`passed` 必须指向真实的非空包内文档及其正确摘要，notes 说明验证环境、范围与结果；缺失、失败和未验证均拒绝。不能把历史记录、SDK 自测或模拟设备改写为本次真实业务通过。
+
+| 验收项目 | 要记录的内容 |
+| --- | --- |
+| `installation` | 安装、升级、平台和依赖兼容 |
+| `tool_contract` | 实际 MCP Schema、能力和参数限制 |
+| `failure_partial` | 错误、部分执行、未知副作用与不盲目重试 |
+| `timeout_cancel` | 实际工具入口超时与取消 |
+| `process_tree` | 工具创建后代后，正常/超时/取消的回收验证 |
+| `file_binding` | 已批准文件被替换、截断、增长时的实际消费字节 |
+| `resource_conflicts` | 同设备/桌面资源互斥 |
+| `evidence_export` | 导出索引、中文路径、摘要不符与缺失附件 |
+| `history_uninstall` | 卸载/升级后历史仍可读 |
+| `secret_redaction` | 配置、命令、输出和回执脱敏 |
+| `real_task` | 经宿主正常任务的操作、时间线、暂停/恢复、证据和报告 |
+| `source_review` | 对本次包的源码审查、来源与分发授权核对 |
+
+仅在声明无相应行为时，`process_tree`、`file_binding` 可 `not_applicable`；无 MCP 时 `tool_contract`、`timeout_cancel` 可不适用；无声明资源时 `resource_conflicts` 可不适用。仍须在 notes 中给出理由，不能把未测写成不适用。其他项目须有真实通过记录。
+
+更新任何文件后，旧材料会失效。先重跑受影响验证，再用 `--fingerprint` 查看新的内容摘要，并更新记录；不要只刷新摘要来沿用过期结论。握手结束后重新核对内容与市场记录，检查期间改动会使检查失败。最终 ZIP 检查结果另包含实际解压检查的同一份字节的 SHA256，不重新打开原路径来记录替换文件；公开发布时仍需核对固定附件、市场索引与无认证下载字节。
+
+市场材料检查验证字段、覆盖范围、摘要和证据存在性，不证明声明真实、不替作者确认权利归属，也不自动发布。源码审查和实际业务验收仍由发布方核对；文档、静态检查、握手、SDK 故障自测与真实业务结论分别记录。

skills/artemis-use/scripts/check_plugin.py

@@ -1,46 +1,6 @@
-"""Validate a plugin package; --live checks MCP declarations without executing actions."""
+"""Shared plugin development and market-materials checker; no tool actions."""
 
-import argparse
+from artemis.plugins.validation import check as check, main
-import asyncio
-import json
-from pathlib import Path
-
-from artemis.plugins.evidence import validate_tools
-from artemis.plugins.models import PluginManifest, PluginProfile
-from artemis.plugins.session import PluginSession, resolve_server
-from artemis.plugins.store import contained_path
-
-
-async def check(directory: Path, live: bool, values: dict[str, str]) -> None:
-    manifest = PluginManifest.model_validate_json((directory / "plugin.json").read_text("utf-8"))
-    manifest.check_compatible()
-    if manifest.skill:
-        skill = contained_path(directory, manifest.skill)
-        if not skill.is_file() or not skill.read_text("utf-8").strip():
-            raise ValueError("缺少有效的 Skill")
-    if manifest.schema_version not in {2, 3}:
-        raise ValueError("新市场插件必须适配 schema_version=2 或 3")
-    if live and manifest.server:
-        server = resolve_server(manifest, PluginProfile(values=values), directory)
-        session = await PluginSession(server, directory).start()
-        try:
-            validate_tools(manifest, session.tools)
-        finally:
-            await session.aclose()
-    print(
-        f"PASS {manifest.id} {manifest.version}: 清单/兼容性/Skill"
-        + ("/MCP 工具声明" if live and manifest.server else "")
-    )
-    print("此检查不代替实际执行、超时取消、证据导出和视觉能力验收。")
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("directory", type=Path)
-    parser.add_argument("--live", action="store_true")
-    parser.add_argument("--values", default="{}", help="普通配置 JSON；不得包含密钥")
-    args = parser.parse_args()
-    asyncio.run(check(args.directory.resolve(), args.live, json.loads(args.values)))
 
 
 if __name__ == "__main__":

tests/unit/admin_console/test_server_lifecycle.py

@@ -202,10 +202,12 @@ async def test_shutdown_marks_only_ui_owned_running_sessions():
             "apps.admin_console.server.ipc_service.stop_server",
             new=AsyncMock(),
         ),
+        patch("apps.admin_console.server.DeviceExecutionLock.cleanup_stale_locks") as cleanup_locks,
     ):
         await on_shutdown()
 
     update_status.assert_called_once_with("ui-running", "interrupted")
+    cleanup_locks.assert_called_once_with()
     assert state.queue_items == []
     state.active_session_id = None
     state.is_shutting_down = False

tests/unit/test_plugin_market.py

@@ -0,0 +1,326 @@
+"""Market validation uses synthetic packages/evidence, never a real release."""
+
+import hashlib
+import io
+import json
+from pathlib import Path
+import sys
+import zipfile
+
+import pytest
+
+from artemis.plugins.market import (
+    CHECKS,
+    REPORT_NAME,
+    content_fingerprint,
+    draft_submission,
+    package_files,
+    package_directory,
+    validate_submission,
+)
+from artemis.plugins.models import PluginManifest
+from artemis.plugins.validation import check, main
+from artemis.plugins import validation
+
+
+@pytest.fixture
+def candidate(tmp_path):
+    manifest = PluginManifest.model_validate(
+        {
+            "schema_version": 2,
+            "id": "synthetic-market-test",
+            "name": "Synthetic",
+            "version": "1.0.0",
+            "platforms": [sys.platform],
+            "skill": "SKILL.md",
+            "license": "Apache-2.0",
+            "capabilities": {"kind": "file", "tools": {}},
+        }
+    )
+    (tmp_path / "plugin.json").write_text(manifest.model_dump_json(), encoding="utf-8")
+    for name in ("SKILL.md", "LICENSE", "SOURCE.md", "VERIFICATION.md"):
+        (tmp_path / name).write_text(
+            "Synthetic test fixture, not a published claim.\n", encoding="utf-8"
+        )
+    return tmp_path, manifest
+
+
+def submitted(candidate):
+    root, manifest = candidate
+    files = package_files(root)
+    report = draft_submission(manifest, files)
+    report["traits"] = {"uses_subprocesses": False, "file_inputs_for_writes": False}
+    report["components"] = [
+        {
+            "name": "synthetic fixture",
+            "paths": ["."],
+            "license": "Apache-2.0",
+            "permission": "permitted",
+            "license_file": "LICENSE",
+            "source_file": "SOURCE.md",
+        }
+    ]
+    for record in report["checks"].values():
+        record.update(
+            status="passed",
+            evidence_file="VERIFICATION.md",
+            evidence_sha256=files["VERIFICATION.md"],
+            notes="Synthetic validation record for unit testing only.",
+        )
+    write_report(root, report)
+    return root, manifest, report
+
+
+def write_report(root, report):
+    (root / REPORT_NAME).write_text(json.dumps(report), encoding="utf-8")
+
+
+def validate(root, manifest):
+    return validate_submission(root, manifest, package_files(root))
+
+
+@pytest.mark.asyncio
+async def test_local_development_does_not_require_public_distribution(candidate):
+    root, _ = candidate
+    result = await check(root, False, {})
+    assert result["scope"] == "development"
+    assert not (root / REPORT_NAME).exists()
+    with pytest.raises(ValueError, match="MARKET.json"):
+        await check(root, False, {}, market=True)
+
+
+@pytest.mark.asyncio
+async def test_generated_market_draft_is_unverified_and_never_overwrites(candidate):
+    root, _ = candidate
+    result = await check(root, False, {}, prepare_market=True)
+    assert result["status"] == "draft"
+    report = json.loads((root / REPORT_NAME).read_text("utf-8"))
+    assert all(record["status"] == "unverified" for record in report["checks"].values())
+    assert report["components"][0]["permission"] == "unknown"
+    assert report["traits"]["uses_subprocesses"] is None
+    before = (root / REPORT_NAME).read_bytes()
+    with pytest.raises(FileExistsError):
+        await check(root, False, {}, prepare_market=True)
+    assert (root / REPORT_NAME).read_bytes() == before
+    with pytest.raises(ValueError):
+        await check(root, False, {}, market=True)
+
+
+@pytest.mark.asyncio
+async def test_valid_market_materials_report_and_zip_have_same_content_hash(
+    candidate, tmp_path_factory
+):
+    root, manifest, report = submitted(candidate)
+    checked = await check(root, False, {}, market=True)
+    assert checked["scope"] == "market_materials"
+    archive = tmp_path_factory.mktemp("market-zip") / "candidate.zip"
+    with zipfile.ZipFile(archive, "w") as output:
+        for path in root.iterdir():
+            output.write(path, path.name)
+    zipped = await check(archive, False, {}, market=True)
+    assert zipped["content_sha256"] == checked["content_sha256"] == report["content_sha256"]
+    assert zipped["archive_sha256"] == hashlib.sha256(archive.read_bytes()).hexdigest()
+
+
+@pytest.mark.parametrize("permission", ["unknown", "local_only"])
+def test_market_rejects_components_without_public_distribution(candidate, permission):
+    root, manifest, report = submitted(candidate)
+    report["components"][0]["permission"] = permission
+    write_report(root, report)
+    with pytest.raises(ValueError, match="市场分发"):
+        validate(root, manifest)
+
+
+def test_market_rejects_changed_payload_and_forged_evidence(candidate):
+    root, manifest, report = submitted(candidate)
+    report["checks"]["source_review"]["evidence_sha256"] = "0" * 64
+    write_report(root, report)
+    with pytest.raises(ValueError, match="记录 SHA256"):
+        validate(root, manifest)
+    (root / "SKILL.md").write_text("different bytes", encoding="utf-8")
+    with pytest.raises(ValueError, match="旧的市场验证记录失效"):
+        validate(root, manifest)
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        "version",
+        "missing_check",
+        "unverified",
+        "no_notes",
+        "uncovered",
+        "source_escape",
+        "license_missing",
+        "na_required",
+        "process_na",
+        "binding_na",
+    ],
+)
+def test_market_blocks_incomplete_or_inapplicable_claims(candidate, change):
+    root, manifest, report = submitted(candidate)
+    if change == "version":
+        report["plugin_version"] = "2.0.0"
+    elif change == "missing_check":
+        del report["checks"]["real_task"]
+    elif change == "unverified":
+        report["checks"]["real_task"]["status"] = "unverified"
+    elif change == "no_notes":
+        report["checks"]["source_review"]["notes"] = " "
+    elif change == "uncovered":
+        report["components"][0]["paths"] = ["LICENSE"]
+    elif change == "source_escape":
+        report["components"][0]["source_file"] = "../outside"
+    elif change == "license_missing":
+        report["components"][0]["license_file"] = "missing.txt"
+    elif change == "na_required":
+        report["checks"]["real_task"]["status"] = "not_applicable"
+    elif change == "process_na":
+        report["traits"]["uses_subprocesses"] = True
+        report["checks"]["process_tree"]["status"] = "not_applicable"
+    elif change == "binding_na":
+        report["traits"]["file_inputs_for_writes"] = True
+        report["checks"]["file_binding"]["status"] = "not_applicable"
+    write_report(root, report)
+    with pytest.raises(ValueError):
+        validate(root, manifest)
+
+
+@pytest.mark.parametrize(
+    "name", [".ruff_cache/entry", "__pycache__/x", "module.pyc", ".env", ".env.local"]
+)
+def test_market_blocks_cache_and_personal_configuration(candidate, name):
+    root, _ = candidate
+    path = root / name
+    path.parent.mkdir(exist_ok=True)
+    path.write_text("synthetic only", encoding="utf-8")
+    with pytest.raises(ValueError, match="市场包"):
+        package_files(root)
+
+
+def test_fingerprint_is_order_independent_but_binds_paths_and_bytes():
+    assert content_fingerprint({"b": "2", "a": "1"}) == content_fingerprint({"a": "1", "b": "2"})
+    assert content_fingerprint({"a": "1"}) != content_fingerprint({"a": "2"})
+    assert content_fingerprint({"a": "1"}) != content_fingerprint({"b": "1"})
+
+
+@pytest.mark.asyncio
+async def test_zip_path_traversal_cannot_escape_inspection(candidate, tmp_path_factory):
+    root, _ = candidate
+    archive = tmp_path_factory.mktemp("bad-market-zip") / "bad.zip"
+    with zipfile.ZipFile(archive, "w") as output:
+        output.writestr("../outside.txt", "synthetic")
+    with pytest.raises(ValueError):
+        await check(archive, False, {})
+    assert not (archive.parent / "outside.txt").exists()
+
+
+def test_json_output_must_not_modify_candidate_or_overwrite_zip(candidate, monkeypatch, capsys):
+    root, _ = candidate
+    target = root / "report.json"
+    monkeypatch.setattr(sys, "argv", ["check_plugin", str(root), "--json-output", str(target)])
+    with pytest.raises(SystemExit):
+        main()
+    assert not target.exists()
+    archive = root / "original.zip"
+    archive.write_bytes(b"original immutable zip placeholder")
+    monkeypatch.setattr(sys, "argv", ["check_plugin", str(archive), "--json-output", str(archive)])
+    with pytest.raises(SystemExit):
+        main()
+    assert archive.read_bytes() == b"original immutable zip placeholder"
+
+
+def test_invalid_values_are_not_echoed(candidate, monkeypatch, capsys):
+    root, _ = candidate
+    private_marker = "SYNTHETIC-DO-NOT-ECHO"
+    monkeypatch.setattr(
+        sys, "argv", ["check_plugin", str(root), "--values", '{"key":"' + private_marker]
+    )
+    with pytest.raises(SystemExit):
+        main()
+    assert private_marker not in capsys.readouterr().out
+
+
+def add_synthetic_server(candidate):
+    root, manifest = candidate
+    data = manifest.model_dump(mode="json")
+    data["server"] = {"command": sys.executable, "args": ["synthetic-unused-server.py"]}
+    manifest = PluginManifest.model_validate(data)
+    (root / "plugin.json").write_text(manifest.model_dump_json(), encoding="utf-8")
+    return root, manifest
+
+
+def handshake_fixture(monkeypatch, action):
+    class FakeSession:
+        tools = []
+
+        def __init__(self, server, root):
+            self.root = root
+
+        async def start(self):
+            action(self.root)
+            return self
+
+        async def aclose(self):
+            pass
+
+    monkeypatch.setattr(validation, "PluginSession", FakeSession)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("changed", ["payload", "submission"])
+async def test_market_rejects_changes_during_handshake(candidate, monkeypatch, changed):
+    root, manifest, report = submitted(add_synthetic_server(candidate))
+
+    def change(directory):
+        if changed == "payload":
+            (directory / "SKILL.md").write_text("changed during handshake", encoding="utf-8")
+        else:
+            report["checks"]["real_task"]["notes"] = "A different synthetic claim."
+            write_report(directory, report)
+
+    handshake_fixture(monkeypatch, change)
+    with pytest.raises(ValueError, match="发生变化"):
+        await check(root, False, {}, market=True)
+
+
+@pytest.mark.asyncio
+async def test_zip_digest_is_bound_to_bytes_actually_inspected(
+    candidate, tmp_path_factory, monkeypatch
+):
+    root, _, report = submitted(add_synthetic_server(candidate))
+    archive = tmp_path_factory.mktemp("changing-zip") / "candidate.zip"
+    with zipfile.ZipFile(archive, "w") as output:
+        for path in root.iterdir():
+            output.write(path, path.name)
+    approved = hashlib.sha256(archive.read_bytes()).hexdigest()
+    handshake_fixture(monkeypatch, lambda root: archive.write_bytes(b"uninspected replacement"))
+    with pytest.raises(ValueError, match="ZIP 发生变化"):
+        await check(archive, False, {}, market=True)
+    assert approved != hashlib.sha256(archive.read_bytes()).hexdigest()
+
+
+def test_archive_fingerprint_uses_extracted_snapshot(candidate, tmp_path_factory):
+    root, _ = candidate
+    archive = tmp_path_factory.mktemp("zip-snapshot") / "candidate.zip"
+    with zipfile.ZipFile(archive, "w") as output:
+        for path in root.iterdir():
+            output.write(path, path.name)
+    approved = hashlib.sha256(archive.read_bytes()).hexdigest()
+    with pytest.raises(ValueError, match="ZIP 发生变化"):
+        with package_directory(archive) as (extracted, digest):
+            archive.write_bytes(b"uninspected replacement")
+            assert (extracted / "plugin.json").read_bytes() == (root / "plugin.json").read_bytes()
+            assert digest == approved
+
+
+@pytest.mark.asyncio
+async def test_incomplete_materials_never_launch_server(candidate, monkeypatch):
+    root, _ = add_synthetic_server(candidate)
+
+    def never_start(root):
+        raise AssertionError("Incomplete market materials launched a plugin")
+
+    handshake_fixture(monkeypatch, never_start)
+    with pytest.raises(ValueError, match="MARKET.json"):
+        await check(root, False, {}, market=True)

tests/unit/test_plugin_sdk.py

@@ -0,0 +1,274 @@
+"""Real local process fault regressions. No devices, network or user processes."""
+
+import asyncio
+import hashlib
+import importlib.util
+import os
+from pathlib import Path
+import sys
+import subprocess
+from unittest.mock import AsyncMock
+
+import pytest
+import psutil
+
+from artemis.plugins import sdk
+from artemis.plugins.sdk import (
+    FileVerificationError,
+    ManagedProcessError,
+    VerifiedFile,
+    snapshot_file,
+)
+from artemis.plugins.sdk_checks import run_checks
+
+
+@pytest.mark.asyncio
+async def test_standard_sdk_fault_suite():
+    result = await run_checks()
+    assert result["status"] == "passed"
+    assert "descendants_reclaimed_on_cancel" in result["checks"]
+    assert "descendants_reclaimed_on_timeout" in result["checks"]
+    assert result["real_device_actions"] is False
+
+
+@pytest.mark.parametrize("max_bytes", [0, -1, True])
+def test_snapshot_rejects_invalid_limits_before_open(tmp_path, max_bytes):
+    with pytest.raises(ValueError, match="正整数"):
+        snapshot_file(tmp_path / "missing", "0" * 64, max_bytes=max_bytes)
+
+
+def test_snapshot_rejects_wrong_digest_oversized_and_special_input(tmp_path):
+    path = tmp_path / "firmware.bin"
+    path.write_bytes(b"approved")
+    digest = hashlib.sha256(path.read_bytes()).hexdigest()
+    assert snapshot_file(path, digest.upper()).sha256 == digest
+    with pytest.raises(FileVerificationError, match="批准"):
+        snapshot_file(path, "f" * 64)
+    with pytest.raises(FileVerificationError, match="SHA256"):
+        snapshot_file(path, "not-a-sha256")
+    with pytest.raises(FileVerificationError, match="大小"):
+        snapshot_file(path, digest, max_bytes=3)
+    with pytest.raises(FileVerificationError, match="普通文件"):
+        snapshot_file(tmp_path, digest)
+    with pytest.raises(TypeError):
+        VerifiedFile(bytearray(b"mutable"))
+
+
+def test_snapshot_survives_path_replacement(tmp_path):
+    path = tmp_path / "source"
+    path.write_bytes(b"old")
+    snapshot = snapshot_file(path, hashlib.sha256(b"old").hexdigest())
+    replacement = tmp_path / "new"
+    replacement.write_bytes(b"new")
+    replacement.replace(path)
+    assert snapshot.data == b"old"
+    assert b"".join(snapshot.chunks(1)) == b"old"
+    with pytest.raises(TypeError):
+        next(snapshot.chunks())[0] = 9
+    with pytest.raises(ValueError):
+        list(snapshot.chunks(0))
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "updates",
+    [
+        {"argv": "echo hello"},
+        {"argv": []},
+        {"argv": ["bad\x00program"]},
+        {"timeout": 0},
+        {"timeout": float("inf")},
+        {"timeout": True},
+        {"input_data": "not-bytes"},
+        {"max_output_bytes": 0},
+    ],
+)
+async def test_invalid_process_inputs_do_not_launch(monkeypatch, tmp_path, updates):
+    launch = AsyncMock()
+    monkeypatch.setattr(asyncio, "create_subprocess_exec", launch)
+    arguments = {"argv": [sys.executable], "cwd": tmp_path, "timeout": 5, **updates}
+    with pytest.raises(ValueError):
+        await sdk.run_process(**arguments)
+    launch.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_tool_launch_error_does_not_authorize_a_retry(tmp_path):
+    with pytest.raises(ManagedProcessError) as raised:
+        await sdk.run_process([str(tmp_path / "nonexistent-program")], cwd=tmp_path, timeout=5)
+    assert raised.value.error_code == "process_launch_failed"
+    assert raised.value.may_have_started is False
+    assert "nonexistent-program" not in str(raised.value)
+
+
+@pytest.mark.asyncio
+async def test_combined_stderr_limit_is_enforced(tmp_path):
+    with pytest.raises(ManagedProcessError, match="process_output_limit"):
+        await sdk.run_process(
+            [
+                sys.executable,
+                "-I",
+                "-B",
+                "-c",
+                "import os; os.write(1,b'a'*800); os.write(2,b'b'*800)",
+            ],
+            cwd=tmp_path,
+            timeout=5,
+            max_output_bytes=1000,
+        )
+
+
+@pytest.mark.asyncio
+async def test_process_fixed_argv_does_not_invoke_shell_and_has_explicit_environment(tmp_path):
+    result = await sdk.run_process(
+        [
+            sys.executable,
+            "-I",
+            "-B",
+            "-c",
+            "import os,sys; print(sys.argv[1]); print(os.environ.get('ARTEMIS_REVIEW_SYNTHETIC'))",
+            "literal & | ; $(no-command)",
+        ],
+        cwd=tmp_path,
+        timeout=5,
+        env={**os.environ, "ARTEMIS_REVIEW_SYNTHETIC": "explicit"},
+    )
+    assert result.returncode == 0
+    assert b"literal & | ; $(no-command)" in result.stdout
+    assert b"explicit" in result.stdout
+
+
+@pytest.mark.asyncio
+async def test_cleanup_continues_through_repeated_cancellation():
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    async def cleanup():
+        entered.set()
+        await release.wait()
+
+    worker = asyncio.create_task(cleanup())
+    owner = asyncio.create_task(sdk._finish_cleanup(worker))
+    await entered.wait()
+    owner.cancel()
+    await asyncio.sleep(0)
+    owner.cancel()
+    await asyncio.sleep(0)
+    assert not worker.done()
+    release.set()
+    with pytest.raises(asyncio.CancelledError):
+        await owner
+    assert worker.done() and not worker.cancelled()
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(os.name != "nt", reason="Windows Job Object ownership barrier")
+async def test_ownership_failure_never_starts_tool(monkeypatch, tmp_path):
+    marker = tmp_path / "must-not-exist"
+
+    def deny_assignment(self, pid):
+        raise OSError("synthetic assignment failure")
+
+    monkeypatch.setattr(sdk.ProcessJob, "assign", deny_assignment)
+    with pytest.raises(ManagedProcessError, match="process_ownership_failed") as raised:
+        await sdk.run_process(
+            [
+                sys.executable,
+                "-I",
+                "-B",
+                "-c",
+                "from pathlib import Path; import sys; Path(sys.argv[1]).touch()",
+                str(marker),
+            ],
+            cwd=tmp_path,
+            timeout=5,
+        )
+    assert raised.value.may_have_started is False
+    assert not marker.exists()
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(os.name != "nt", reason="Windows owner-death Job Object guarantee")
+async def test_forcibly_killing_sdk_owner_reclaims_its_descendants(tmp_path):
+    from artemis.plugins.sdk_checks import PROBE
+
+    marker = tmp_path / "owned-child.json"
+    owner_script = tmp_path / "owned-sdk-host.py"
+    owner_script.write_text(
+        "import asyncio, sys\nfrom pathlib import Path\n"
+        "from artemis.plugins.sdk import run_process\n"
+        "asyncio.run(run_process([sys.executable, '-I', '-B', sys.argv[1], 'tree', "
+        "sys.argv[2], 'linger'], cwd=Path(sys.argv[2]).parent, timeout=60))\n",
+        encoding="utf-8",
+    )
+    owner = await asyncio.create_subprocess_exec(
+        sys.executable,
+        "-B",
+        str(owner_script),
+        str(PROBE),
+        str(marker),
+        stdin=asyncio.subprocess.DEVNULL,
+        stdout=asyncio.subprocess.DEVNULL,
+        stderr=asyncio.subprocess.DEVNULL,
+        creationflags=subprocess.CREATE_NO_WINDOW,
+    )
+    descendants = []
+    try:
+        async with asyncio.timeout(10):
+            while not marker.exists():
+                assert owner.returncode is None
+                await asyncio.sleep(0.02)
+        descendants = psutil.Process(owner.pid).children(recursive=True)
+        assert len(descendants) >= 3  # bootstrap, synthetic tool, synthetic sleeper
+        owner.kill()
+        await owner.wait()
+        async with asyncio.timeout(3):
+            while any(p.is_running() for p in descendants):
+                await asyncio.sleep(0.02)
+    finally:
+        if owner.returncode is None:
+            owner.kill()
+            await owner.wait()
+        for process in descendants:
+            if process.is_running():
+                process.kill()
+                process.wait(timeout=5)
+
+
+@pytest.mark.asyncio
+async def test_managed_template_real_mcp_and_host_receipts():
+    path = (
+        Path(__file__).resolve().parents[2] / "examples/plugins/managed-tool-demo/test_contract.py"
+    )
+    spec = importlib.util.spec_from_file_location("managed_template_contract", path.resolve())
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    result = await module.run_contract()
+    assert result["mcp_calls"] == 3
+    assert result["host_attachments_verified"] == 1
+
+
+def test_authoring_template_and_checker_copies_stay_identical():
+    root = Path(__file__).resolve().parents[2]
+    for name in (
+        "plugin.json",
+        "server.py",
+        "SKILL.md",
+        "README.md",
+        "test_contract.py",
+        "LICENSE",
+        "SOURCE.md",
+    ):
+        assert (root / "examples/plugins/managed-tool-demo" / name).read_bytes() == (
+            root / "skills/artemis-use/assets/managed-tool-demo" / name
+        ).read_bytes()
+    assert (root / "scripts/check_plugin.py").read_bytes() == (
+        root / "skills/artemis-use/scripts/check_plugin.py"
+    ).read_bytes()
+    for name in ("plugin.json", "server.py", "SKILL.md", "LICENSE", "SOURCE.md"):
+        assert (root / "examples/plugins/evidence-demo" / name).read_bytes() == (
+            root / "skills/artemis-use/assets/evidence-demo" / name
+        ).read_bytes()
+    assert (root / "docs/plugin-sdk.md").read_bytes() == (
+        root / "skills/artemis-use/references/plugin-sdk.md"
+    ).read_bytes()

uv.lock

@@ -248,7 +248,7 @@ wheels = [
 
 [[package]]
 name = "artemis"
-version = "2.4.4"
+version = "2.4.5"
 source = { editable = "." }
 dependencies = [
     { name = "adbutils" },