codebee 0.1.101 → 0.1.103

package/app/core/repeat_guard.py

@@ -1,129 +1,129 @@
-# -*- coding: utf-8 -*-
-"""重复 CLI 调用检测：防止编排者用同一份 prompt 反复调同一 CLI 死循环。
-
-设计稿：docs/migration/01-defense-patterns.md §5C。
-参考 dsh packages/guard/repeat-tool-reminder/src/index.ts：
-  监听 tools/post-execute，按 (tool, canonical_args) 跟踪，3/5/8 阈值注入 user-message 提醒。
-
-Tutti 的 "tool" 对应到 step role + 执行者身份，"canonical_args" 对应到 prompt
-模板指纹。不同 CLI 间的换将是有效的回退，不能共享同一个重复预算。步骤级调用
-代价远高于普通工具调用，因此第 3 次提醒、第 5 次强制停止。
-"""
-from __future__ import annotations
-
-import hashlib
-import logging
-import threading
-import time
-
-log = logging.getLogger(__name__)
-
-# 渐进阈值：第 N 次命中时给提醒；最后一次及以上时强制停止。
-DEFAULT_THRESHOLDS = (3, 5)
-
-REMINDER_TEMPLATE = (
-    "⚠️ 提醒：上一步使用了几乎相同的输入（已连续 {count} 次调用 {role}）。"
-    "请换一种方法：读不同的文件、用更具体的指令、或明确询问用户澄清。"
-)
-
-STOP_TEMPLATE = (
-    "已连续 {count} 次使用相同输入调用 {role}，超过 {last_thr} 次阈值，"
-    "强制停止本 step 以防止无限循环。请用户检查输入或调整 prompt 模板。"
-)
-
-
-def _prompt_fingerprint(prompt: str, identity: str = "") -> str:
-    """prompt 指纹：用前 200 字符 + 总长度（CLI prompt 头几行通常是模板部分）。
-
-    不做严格 canonical args 比对（CLI prompt 通常很长，且 dsh 也用 JSON.stringify）；
-    指纹命中说明是同一个模板路径走过多次，已经够分辨。
-
-    用 SHA-256 取前 12 字符（96 bit）：48 亿分之一碰撞概率对去重足够；不追求密码学强度。
-    """
-    head = (prompt or "")[:200]
-    return hashlib.sha256(
-        f"{identity}\0{head}|{len(prompt or '')}".encode("utf-8")).hexdigest()[:12]
-
-
-class RepeatGuard:
-    """每 (run_id, step_role) 的最近执行链独立计数；指纹包含执行者身份。
-
-    计数仅统计相同 key 连续出现；新 prompt 会重置。
-    """
-
-    def __init__(self, thresholds=DEFAULT_THRESHOLDS, *, max_history=50):
-        self.thresholds = tuple(sorted(set(thresholds)))
-        self.max_history = max_history
-        self._lock = threading.Lock()
-        # chain[(run_id, role)] = [(ts, fingerprint)]
-        self._chains: dict = {}
-
-    def check(self, run_id: str, role: str, prompt: str, *, identity: str = "") -> dict:
-        """检查并更新 (run_id, role) 的连续计数。
-
-        identity 标识实际执行 CLI/agent。相同 prompt 换到其他执行者属于回退，
-        会从新的连续链计数；同一执行者重复相同调用仍按阈值停止。
-
-        Returns:
-            {"count": int, "reminder": str | None, "should_stop": bool}
-        """
-        fp = _prompt_fingerprint(prompt, str(identity or ""))
-        chain_key = (run_id, role)
-        with self._lock:
-            chain = self._chains.setdefault(chain_key, [])
-            chain.append((time.time(), fp))
-            # 仅统计相同 fp 连续出现
-            count = 1
-            for _, prev_fp in reversed(chain[:-1]):
-                if prev_fp == fp:
-                    count += 1
-                else:
-                    break
-            # 截尾避免内存膨胀
-            if len(chain) > self.max_history:
-                self._chains[chain_key] = chain[-self.max_history:]
-
-        reminder = None
-        stop = False
-        last_thr = self.thresholds[-1]
-        if count >= last_thr:
-            stop = True
-            reminder = STOP_TEMPLATE.format(count=count, role=role, last_thr=last_thr)
-        elif count in self.thresholds:
-            reminder = REMINDER_TEMPLATE.format(count=count, role=role)
-
-        if reminder:
-            log.warning("repeat-guard %s/%s count=%d stop=%s reminder=%s",
-                        run_id, role, count, stop, reminder[:80])
-        return {"count": count, "reminder": reminder, "should_stop": stop}
-
-    def reset(self, run_id: str) -> int:
-        """重置某 run_id 的所有 (run_id, *) 链。返回清除的链条数。"""
-        with self._lock:
-            cleared = 0
-            for k in list(self._chains.keys()):
-                if k[0] == run_id:
-                    del self._chains[k]
-                    cleared += 1
-            return cleared
-
-    def stats(self, run_id: str, role: str) -> dict:
-        """读取 (run_id, role) 当前状态（不更新）。用于 UI 调试。"""
-        chain_key = (run_id, role)
-        with self._lock:
-            chain = self._chains.get(chain_key, [])
-            if not chain:
-                return {"chain_len": 0, "last_fp": ""}
-            # 当前连续计数
-            last_fp = chain[-1][1]
-            count = 1
-            for _, fp in reversed(chain[:-1]):
-                if fp == last_fp:
-                    count += 1
-                else:
-                    break
-            return {"chain_len": len(chain), "last_fp": last_fp, "count": count}
-
-
-# 模块级默认实例（pipeline 接线用；run_id 入键天然隔离多任务，测试无需替换）
-guard = RepeatGuard()
+# -*- coding: utf-8 -*-
+"""重复 CLI 调用检测：防止编排者用同一份 prompt 反复调同一 CLI 死循环。
+
+设计稿：docs/migration/01-defense-patterns.md §5C。
+参考 dsh packages/guard/repeat-tool-reminder/src/index.ts：
+  监听 tools/post-execute，按 (tool, canonical_args) 跟踪，3/5/8 阈值注入 user-message 提醒。
+
+Tutti 的 "tool" 对应到 step role + 执行者身份，"canonical_args" 对应到 prompt
+模板指纹。不同 CLI 间的换将是有效的回退，不能共享同一个重复预算。步骤级调用
+代价远高于普通工具调用，因此第 3 次提醒、第 5 次强制停止。
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+import threading
+import time
+
+log = logging.getLogger(__name__)
+
+# 渐进阈值：第 N 次命中时给提醒；最后一次及以上时强制停止。
+DEFAULT_THRESHOLDS = (3, 5)
+
+REMINDER_TEMPLATE = (
+    "⚠️ 提醒：上一步使用了几乎相同的输入（已连续 {count} 次调用 {role}）。"
+    "请换一种方法：读不同的文件、用更具体的指令、或明确询问用户澄清。"
+)
+
+STOP_TEMPLATE = (
+    "已连续 {count} 次使用相同输入调用 {role}，超过 {last_thr} 次阈值，"
+    "强制停止本 step 以防止无限循环。请用户检查输入或调整 prompt 模板。"
+)
+
+
+def _prompt_fingerprint(prompt: str, identity: str = "") -> str:
+    """prompt 指纹：用前 200 字符 + 总长度（CLI prompt 头几行通常是模板部分）。
+
+    不做严格 canonical args 比对（CLI prompt 通常很长，且 dsh 也用 JSON.stringify）；
+    指纹命中说明是同一个模板路径走过多次，已经够分辨。
+
+    用 SHA-256 取前 12 字符（96 bit）：48 亿分之一碰撞概率对去重足够；不追求密码学强度。
+    """
+    head = (prompt or "")[:200]
+    return hashlib.sha256(
+        f"{identity}\0{head}|{len(prompt or '')}".encode("utf-8")).hexdigest()[:12]
+
+
+class RepeatGuard:
+    """每 (run_id, step_role) 的最近执行链独立计数；指纹包含执行者身份。
+
+    计数仅统计相同 key 连续出现；新 prompt 会重置。
+    """
+
+    def __init__(self, thresholds=DEFAULT_THRESHOLDS, *, max_history=50):
+        self.thresholds = tuple(sorted(set(thresholds)))
+        self.max_history = max_history
+        self._lock = threading.Lock()
+        # chain[(run_id, role)] = [(ts, fingerprint)]
+        self._chains: dict = {}
+
+    def check(self, run_id: str, role: str, prompt: str, *, identity: str = "") -> dict:
+        """检查并更新 (run_id, role) 的连续计数。
+
+        identity 标识实际执行 CLI/agent。相同 prompt 换到其他执行者属于回退，
+        会从新的连续链计数；同一执行者重复相同调用仍按阈值停止。
+
+        Returns:
+            {"count": int, "reminder": str | None, "should_stop": bool}
+        """
+        fp = _prompt_fingerprint(prompt, str(identity or ""))
+        chain_key = (run_id, role)
+        with self._lock:
+            chain = self._chains.setdefault(chain_key, [])
+            chain.append((time.time(), fp))
+            # 仅统计相同 fp 连续出现
+            count = 1
+            for _, prev_fp in reversed(chain[:-1]):
+                if prev_fp == fp:
+                    count += 1
+                else:
+                    break
+            # 截尾避免内存膨胀
+            if len(chain) > self.max_history:
+                self._chains[chain_key] = chain[-self.max_history:]
+
+        reminder = None
+        stop = False
+        last_thr = self.thresholds[-1]
+        if count >= last_thr:
+            stop = True
+            reminder = STOP_TEMPLATE.format(count=count, role=role, last_thr=last_thr)
+        elif count in self.thresholds:
+            reminder = REMINDER_TEMPLATE.format(count=count, role=role)
+
+        if reminder:
+            log.warning("repeat-guard %s/%s count=%d stop=%s reminder=%s",
+                        run_id, role, count, stop, reminder[:80])
+        return {"count": count, "reminder": reminder, "should_stop": stop}
+
+    def reset(self, run_id: str) -> int:
+        """重置某 run_id 的所有 (run_id, *) 链。返回清除的链条数。"""
+        with self._lock:
+            cleared = 0
+            for k in list(self._chains.keys()):
+                if k[0] == run_id:
+                    del self._chains[k]
+                    cleared += 1
+            return cleared
+
+    def stats(self, run_id: str, role: str) -> dict:
+        """读取 (run_id, role) 当前状态（不更新）。用于 UI 调试。"""
+        chain_key = (run_id, role)
+        with self._lock:
+            chain = self._chains.get(chain_key, [])
+            if not chain:
+                return {"chain_len": 0, "last_fp": ""}
+            # 当前连续计数
+            last_fp = chain[-1][1]
+            count = 1
+            for _, fp in reversed(chain[:-1]):
+                if fp == last_fp:
+                    count += 1
+                else:
+                    break
+            return {"chain_len": len(chain), "last_fp": last_fp, "count": count}
+
+
+# 模块级默认实例（pipeline 接线用；run_id 入键天然隔离多任务，测试无需替换）
+guard = RepeatGuard()

package/app/core/retrieval.py

@@ -1,137 +1,137 @@
-"""Dependency-free retrieval index with traceable keyword scoring.
-
-This is intentionally a RAG-lite layer: SQLite/vector backends can be added
-later without changing the API contract. Every hit carries its source and the
-terms that caused the match.
-"""
-from __future__ import annotations
-
-import hashlib
-import json
-import re
-import threading
-from pathlib import Path
-
-from . import paths
-
-_LOCK = threading.RLock()
-_FILE = paths.DATA_DIR / "retrieval_index.json"
-_WORD_RE = re.compile(r"[A-Za-z0-9_]+|[\u4e00-\u9fff]")
-_MAX_FILES = 500
-_MAX_BYTES = 20 * 1024 * 1024
-_SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", ".idea", ".vscode"}
-
-
-def _terms(text):
-    return [x.lower() for x in _WORD_RE.findall(str(text or ""))]
-
-
-def _load():
-    try:
-        value = json.loads(_FILE.read_text(encoding="utf-8"))
-        return value if isinstance(value, dict) else {"documents": {}}
-    except Exception:
-        return {"version": 1, "documents": {}}
-
-
-def _save(value):
-    _FILE.parent.mkdir(parents=True, exist_ok=True)
-    tmp = _FILE.with_suffix(".tmp")
-    tmp.write_text(json.dumps(value, ensure_ascii=False, indent=1), encoding="utf-8")
-    tmp.replace(_FILE)
-
-
-def upsert(source, text, metadata=None, doc_id=""):
-    source = str(source or "").strip()[:500]
-    text = str(text or "").strip()
-    if not source or not text:
-        raise ValueError("source 和 text 不能为空")
-    root_hint = ""
-    if isinstance(metadata, dict):
-        root_hint = str(metadata.get("root") or "")[:500]
-    did = str(doc_id or hashlib.sha256((root_hint + "\0" + source).encode("utf-8")).hexdigest()[:20])[:100]
-    meta = metadata if isinstance(metadata, dict) else {}
-    meta = {str(k)[:80]: str(v)[:1000] for k, v in list(meta.items())[:30]}
-    row = {"id": did, "source": source, "text": text[:200000],
-           "terms": sorted(set(_terms(text))),
-           "metadata": meta}
-    with _LOCK:
-        data = _load()
-        data.setdefault("version", 1)
-        documents = data.setdefault("documents", {})
-        # Explicit IDs are client supplied; avoid silently replacing an
-        # unrelated document when two sources reuse the same short ID.
-        if did in documents and documents[did].get("source") != source:
-            suffix = hashlib.sha256((source + "\0" + text).encode("utf-8")).hexdigest()[:12]
-            did = (did[:87] + "-" + suffix)[:100]
-            row["id"] = did
-        documents[did] = row
-        _save(data)
-    return row
-
-
-def index_directory(root, extensions=(".md", ".txt", ".json"), limit=500,
-                    allowed_roots=None, max_bytes=_MAX_BYTES):
-    root = Path(root).expanduser().resolve()
-    if not root.is_dir():
-        raise ValueError("目录不存在")
-    if allowed_roots is not None:
-        roots = [Path(p).expanduser().resolve() for p in allowed_roots if p]
-        if not any(root == p or p in root.parents for p in roots):
-            raise ValueError("只能索引任务工作目录范围内的文件")
-    try:
-        file_limit = max(1, min(_MAX_FILES, int(limit)))
-    except (TypeError, ValueError):
-        raise ValueError("limit 必须是整数")
-    try:
-        byte_limit = max(1, min(_MAX_BYTES, int(max_bytes)))
-    except (TypeError, ValueError):
-        raise ValueError("max_bytes 必须是整数")
-    count = 0
-    total_bytes = 0
-    for path in root.rglob("*"):
-        if count >= file_limit or total_bytes >= byte_limit:
-            break
-        # Never follow a symlink while indexing user-controlled trees.
-        if path.is_symlink() or any(part in _SKIP_DIRS for part in path.relative_to(root).parts):
-            continue
-        if path.is_file() and path.suffix.lower() in extensions:
-            try:
-                resolved = path.resolve()
-                if resolved != root and root not in resolved.parents:
-                    continue
-                size = path.stat().st_size
-                if size > byte_limit - total_bytes:
-                    continue
-                upsert(str(path.relative_to(root)), path.read_text(encoding="utf-8", errors="replace"),
-                       {"root": str(root)})
-                count += 1
-                total_bytes += size
-            except OSError:
-                pass
-    return {"indexed": count, "bytes": total_bytes,
-            "total": len(_load().get("documents") or {})}
-
-
-def search(query, limit=10):
-    try:
-        n = max(1, min(50, int(limit or 10)))
-    except (TypeError, ValueError):
-        raise ValueError("limit 必须是整数")
-    terms = set(_terms(str(query or "")[:500]))
-    if not terms:
-        return []
-    with _LOCK:
-        docs = list((_load().get("documents") or {}).values())
-    rows = []
-    for doc in docs:
-        matched = sorted(terms.intersection(doc.get("terms") or []))
-        if not matched:
-            continue
-        score = len(matched) / max(1, len(terms))
-        rows.append({"id": doc.get("id"), "source": doc.get("source"),
-                     "score": round(score, 4), "matched_terms": matched,
-                     "snippet": str(doc.get("text") or "")[:600],
-                     "metadata": doc.get("metadata") or {}})
-    rows.sort(key=lambda x: (-x["score"], x["source"] or ""))
-    return rows[:n]
+"""Dependency-free retrieval index with traceable keyword scoring.
+
+This is intentionally a RAG-lite layer: SQLite/vector backends can be added
+later without changing the API contract. Every hit carries its source and the
+terms that caused the match.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import threading
+from pathlib import Path
+
+from . import paths
+
+_LOCK = threading.RLock()
+_FILE = paths.DATA_DIR / "retrieval_index.json"
+_WORD_RE = re.compile(r"[A-Za-z0-9_]+|[\u4e00-\u9fff]")
+_MAX_FILES = 500
+_MAX_BYTES = 20 * 1024 * 1024
+_SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", ".idea", ".vscode"}
+
+
+def _terms(text):
+    return [x.lower() for x in _WORD_RE.findall(str(text or ""))]
+
+
+def _load():
+    try:
+        value = json.loads(_FILE.read_text(encoding="utf-8"))
+        return value if isinstance(value, dict) else {"documents": {}}
+    except Exception:
+        return {"version": 1, "documents": {}}
+
+
+def _save(value):
+    _FILE.parent.mkdir(parents=True, exist_ok=True)
+    tmp = _FILE.with_suffix(".tmp")
+    tmp.write_text(json.dumps(value, ensure_ascii=False, indent=1), encoding="utf-8")
+    tmp.replace(_FILE)
+
+
+def upsert(source, text, metadata=None, doc_id=""):
+    source = str(source or "").strip()[:500]
+    text = str(text or "").strip()
+    if not source or not text:
+        raise ValueError("source 和 text 不能为空")
+    root_hint = ""
+    if isinstance(metadata, dict):
+        root_hint = str(metadata.get("root") or "")[:500]
+    did = str(doc_id or hashlib.sha256((root_hint + "\0" + source).encode("utf-8")).hexdigest()[:20])[:100]
+    meta = metadata if isinstance(metadata, dict) else {}
+    meta = {str(k)[:80]: str(v)[:1000] for k, v in list(meta.items())[:30]}
+    row = {"id": did, "source": source, "text": text[:200000],
+           "terms": sorted(set(_terms(text))),
+           "metadata": meta}
+    with _LOCK:
+        data = _load()
+        data.setdefault("version", 1)
+        documents = data.setdefault("documents", {})
+        # Explicit IDs are client supplied; avoid silently replacing an
+        # unrelated document when two sources reuse the same short ID.
+        if did in documents and documents[did].get("source") != source:
+            suffix = hashlib.sha256((source + "\0" + text).encode("utf-8")).hexdigest()[:12]
+            did = (did[:87] + "-" + suffix)[:100]
+            row["id"] = did
+        documents[did] = row
+        _save(data)
+    return row
+
+
+def index_directory(root, extensions=(".md", ".txt", ".json"), limit=500,
+                    allowed_roots=None, max_bytes=_MAX_BYTES):
+    root = Path(root).expanduser().resolve()
+    if not root.is_dir():
+        raise ValueError("目录不存在")
+    if allowed_roots is not None:
+        roots = [Path(p).expanduser().resolve() for p in allowed_roots if p]
+        if not any(root == p or p in root.parents for p in roots):
+            raise ValueError("只能索引任务工作目录范围内的文件")
+    try:
+        file_limit = max(1, min(_MAX_FILES, int(limit)))
+    except (TypeError, ValueError):
+        raise ValueError("limit 必须是整数")
+    try:
+        byte_limit = max(1, min(_MAX_BYTES, int(max_bytes)))
+    except (TypeError, ValueError):
+        raise ValueError("max_bytes 必须是整数")
+    count = 0
+    total_bytes = 0
+    for path in root.rglob("*"):
+        if count >= file_limit or total_bytes >= byte_limit:
+            break
+        # Never follow a symlink while indexing user-controlled trees.
+        if path.is_symlink() or any(part in _SKIP_DIRS for part in path.relative_to(root).parts):
+            continue
+        if path.is_file() and path.suffix.lower() in extensions:
+            try:
+                resolved = path.resolve()
+                if resolved != root and root not in resolved.parents:
+                    continue
+                size = path.stat().st_size
+                if size > byte_limit - total_bytes:
+                    continue
+                upsert(str(path.relative_to(root)), path.read_text(encoding="utf-8", errors="replace"),
+                       {"root": str(root)})
+                count += 1
+                total_bytes += size
+            except OSError:
+                pass
+    return {"indexed": count, "bytes": total_bytes,
+            "total": len(_load().get("documents") or {})}
+
+
+def search(query, limit=10):
+    try:
+        n = max(1, min(50, int(limit or 10)))
+    except (TypeError, ValueError):
+        raise ValueError("limit 必须是整数")
+    terms = set(_terms(str(query or "")[:500]))
+    if not terms:
+        return []
+    with _LOCK:
+        docs = list((_load().get("documents") or {}).values())
+    rows = []
+    for doc in docs:
+        matched = sorted(terms.intersection(doc.get("terms") or []))
+        if not matched:
+            continue
+        score = len(matched) / max(1, len(terms))
+        rows.append({"id": doc.get("id"), "source": doc.get("source"),
+                     "score": round(score, 4), "matched_terms": matched,
+                     "snippet": str(doc.get("text") or "")[:600],
+                     "metadata": doc.get("metadata") or {}})
+    rows.sort(key=lambda x: (-x["score"], x["source"] or ""))
+    return rows[:n]

package/app/core/sandbox_runtime.py

@@ -0,0 +1,95 @@
+"""Optional process sandbox launchers.
+
+The default CodeBee install has no container dependency. Docker is an explicit
+opt-in backend selected by a task policy and a configured image; this module
+only builds argv and never silently falls back to a weaker backend.
+"""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+from pathlib import Path
+
+
+class SandboxUnavailable(RuntimeError):
+    pass
+
+
+def requested_backend(sandbox):
+    value = str((sandbox or {}).get("backend") or "native").strip().lower()
+    return value or "native"
+
+
+def docker_argv(command, *, sandbox, workdir, image=None, extra_args=(),
+                container_workdir=None,
+                container_command=("/bin/sh", "-lc")):
+    """Build a restricted ``docker run`` argv for a command or stdio server."""
+    if requested_backend(sandbox) != "docker":
+        raise SandboxUnavailable("Docker 后端未被任务策略启用")
+    docker = shutil.which("docker")
+    if not docker:
+        raise SandboxUnavailable("当前系统没有可用的 Docker CLI")
+    root = Path(workdir or ".").expanduser().resolve(strict=True)
+    image = str(image or (sandbox or {}).get("docker_image") or "").strip()
+    if not image or len(image) > 240 or not re.match(r"^[A-Za-z0-9][A-Za-z0-9._/:@-]*$", image):
+        raise SandboxUnavailable("Docker 后端必须配置可信镜像")
+    roots = []
+    for value in (sandbox or {}).get("allowed_roots") or [str(root)]:
+        candidate = Path(value).expanduser().resolve(strict=True)
+        # Docker currently mounts exactly one root. Require the task workspace
+        # itself; narrower roots need a separately resolved container cwd and
+        # must never accidentally broaden into an ancestor mount.
+        if candidate != root:
+            raise SandboxUnavailable("Docker 目前只支持挂载任务工作目录")
+        if candidate not in roots:
+            roots.append(candidate)
+    if not roots:
+        raise SandboxUnavailable("Docker 后端没有允许目录")
+    selected_root = next((candidate for candidate in roots
+                          if candidate == root or candidate in root.parents
+                          or root in candidate.parents), None)
+    if selected_root is None:
+        raise SandboxUnavailable("当前工作目录不在 Docker 允许目录内")
+    if len(roots) != 1:
+        raise SandboxUnavailable("Docker 暂只支持一个明确的允许目录")
+    argv = [docker, "run", "--rm", "--init", "--read-only",
+            "--security-opt", "no-new-privileges", "--cap-drop=ALL",
+            "--ipc=none", "--pids-limit", "256", "--memory", "2g", "--cpus", "2",
+            "--tmpfs", "/tmp:rw,noexec,nosuid,size=64m"]
+    if hasattr(os, "getuid") and hasattr(os, "getgid"):
+        argv += ["--user", "%d:%d" % (os.getuid(), os.getgid())]
+    else:
+        argv += ["--user", "65534:65534"]
+    argv += ["--network", "none" if not bool((sandbox or {}).get("network", True)) else "bridge"]
+    for name in (sandbox or {}).get("env_allowlist") or []:
+        name = str(name)
+        if name and name in os.environ:
+            # Value is supplied through the filtered Docker client environment;
+            # never place credentials in argv, where process/log inspection sees them.
+            argv += ["--env", name]
+    for candidate in roots:
+        if "," in str(candidate):
+            raise SandboxUnavailable("Docker 允许目录包含不支持的逗号")
+        argv += ["--mount", "type=bind,src=%s,dst=/workspace" % str(candidate)]
+    if container_workdir is None:
+        rel_workdir = root.relative_to(selected_root).as_posix()
+        container_workdir = "/workspace" + ("/" + rel_workdir if rel_workdir != "." else "")
+    if not str(container_workdir).startswith("/") or ".." in Path(container_workdir).parts:
+        raise SandboxUnavailable("Docker 容器工作目录无效")
+    argv += ["--workdir", str(container_workdir), *list(extra_args), image]
+    if isinstance(command, (list, tuple)):
+        argv += [str(x) for x in command]
+    else:
+        argv += list(container_command) + [str(command)]
+    return argv
+
+
+def docker_env(sandbox):
+    """Docker receives only explicitly allowed host environment values."""
+    out = {"PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+           "HOME": "/tmp", "TMPDIR": "/tmp"}
+    for name in (sandbox or {}).get("env_allowlist") or []:
+        if name in os.environ:
+            out[str(name)] = os.environ[str(name)]
+    return out