examples: complete spec requirements (runtime default, env, file-list, diff-summary)

Default runtime is now auto: the CLI uses the container sandbox when
Docker is available, else the local subprocess sandbox — in-process is
an explicit --runtime inprocess dev opt-in (requirement 2: local is a
fallback, not the default production path).
Sandbox env whitelist: only ENV_ALLOWLIST vars reach the sandbox, so
parent-process secrets never leak in (requirement 7).
File-path-list input: --files a.py,b.py / run_review(files=[...])
via pipeline.diff_parser.parse_file_list (requirement 3).
Persist the input-diff summary on the review task (requirement 5's
fifth saved entity), queryable by task id.

Updates #92

RELEASE NOTES: NONE

Author: Acture

examples/skills_code_review_agent/pipeline/diff_parser.py

@@ -3,7 +3,6 @@
 # Copyright (C) 2026 Tencent. All rights reserved.
 #
 # tRPC-Agent-Python is licensed under Apache-2.0.
-
 """Parse review inputs into a ``DiffSummary`` (issue #92, requirement 3).
 
 Plumbing only — wraps the mature ``unidiff`` parser. Three input kinds:
@@ -91,6 +90,28 @@ def parse_git_worktree(repo_path: str, base_ref: str | None = None) -> DiffSumma
     return parse_unified_diff(proc.stdout)
 
 
+def parse_file_list(paths: list[str], repo_root: str = ".") -> DiffSummary:
+    """Treat a list of file paths as fully-added files (issue #92, requirement 3 input mode)."""
+    files: list[ChangedFile] = []
+    languages: dict[str, int] = {}
+    added = 0
+    for rel in paths:
+        try:
+            n = len((Path(repo_root) / rel).read_text(encoding="utf-8", errors="replace").splitlines())
+        except OSError:
+            n = 0
+        lang = _language(rel)
+        if lang:
+            languages[lang] = languages.get(lang, 0) + 1
+        added += n
+        files.append(
+            ChangedFile(path=rel,
+                        change_type="added",
+                        language=lang,
+                        hunks=[Hunk(new_start=1, new_len=n, candidate_lines=list(range(1, n + 1)))]))
+    return DiffSummary(files=files, files_changed=len(files), added=added, removed=0, languages=languages)
+
+
 def materialize_new_files(text: str) -> dict[str, str]:
     """Reconstruct the post-change (target-side) content of each changed file from a diff.
 

examples/skills_code_review_agent/pipeline/engine.py

@@ -53,11 +53,26 @@ def _materialize(diff_text: str) -> tuple[DiffSummary, str]:
     return summary, tmp
 
 
+def _materialize_files(paths: list[str], repo_root: str) -> str:
+    """Copy a list of files into a temp dir for scanning (the --files / file-list input mode)."""
+    tmp = tempfile.mkdtemp(prefix="cr_scan_")
+    for rel in paths:
+        dest = Path(tmp) / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            dest.write_text((Path(repo_root) / rel).read_text(encoding="utf-8", errors="replace"), encoding="utf-8")
+        except OSError:
+            continue
+    return tmp
+
+
 def run_review(
     *,
     task_id: Optional[str] = None,
     diff_text: Optional[str] = None,
     repo_path: Optional[str] = None,
+    files: Optional[list[str]] = None,
+    repo_root: str = ".",
     runtime: str = "inprocess",
     sandbox_timeout: float | None = None,
     max_output_bytes: int | None = None,
@@ -81,12 +96,16 @@ def run_review(
     if diff_text is not None:
         summary, scan_dir = _materialize(diff_text)
         source_type, source_ref = "diff_file", "<diff>"
+    elif files is not None:
+        summary = diff_parser.parse_file_list(files, repo_root)
+        scan_dir = _materialize_files(files, repo_root)
+        source_type, source_ref = "file_list", ",".join(files)[:200]
     elif repo_path is not None:
         summary = diff_parser.parse_git_worktree(repo_path)
         scan_dir = repo_path
         source_type, source_ref = "repo_path", repo_path
     else:
-        raise ValueError("run_review requires diff_text or repo_path")
+        raise ValueError("run_review requires diff_text, files, or repo_path")
 
     sandbox_runs: list = []
     if runtime == "local":

examples/skills_code_review_agent/pipeline/policy.py

@@ -3,7 +3,6 @@
 # Copyright (C) 2026 Tencent. All rights reserved.
 #
 # tRPC-Agent-Python is licensed under Apache-2.0.
-
 """Review policy — the Filter decision logic (issue #92, requirement 7 & 8).
 
 Shared by two enforcement sites (plan decision #5): the framework ``ReviewGuardFilter`` on the agent
@@ -33,6 +32,14 @@
 # Sensitive roots a review must never touch (temp dirs under /var/folders are intentionally allowed).
 _FORBIDDEN_PATHS = ("/etc", "/root", "/boot", os.path.expanduser("~/.ssh"))
 
+# Only these env vars are passed into the sandbox — parent-process secrets never leak in (要求7).
+ENV_ALLOWLIST = ("PATH", "HOME", "LANG", "LC_ALL", "TMPDIR", "TEMP", "TMP", "SYSTEMROOT")
+
+
+def sandbox_env(allowlist: Iterable[str] = ENV_ALLOWLIST) -> dict[str, str]:
+    """Return the minimal whitelisted environment for a sandbox run."""
+    return {k: os.environ[k] for k in allowlist if k in os.environ}
+
 
 @dataclass
 class PolicyDecision:

examples/skills_code_review_agent/pipeline/sandbox.py

@@ -110,7 +110,8 @@ def run_local(
     stdout: str | bytes | None = ""
     stderr: str | bytes | None = ""
     try:
-        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=False)
+        from .policy import sandbox_env
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=False, env=sandbox_env())
         exit_code, stdout, stderr = proc.returncode, proc.stdout, proc.stderr
     except subprocess.TimeoutExpired as exc:
         timed_out, exit_code = True, -1
@@ -164,10 +165,12 @@ async def run_container(
             for p in Path(scan_dir).rglob("*") if p.is_file()
         ]
         await fs.put_files(ws, files)
+        from .policy import sandbox_env
         run = await runner.run_program(
             ws,
             WorkspaceRunProgramSpec(cmd="python",
                                     args=["/opt/skill/run_checks.py", "--target", ".", "--out", "findings.json"],
+                                    env=sandbox_env(),
                                     timeout=timeout,
                                     limits=WorkspaceResourceLimits(memory_mb=memory_mb)))
         collected = await fs.collect_outputs(ws, WorkspaceOutputSpec(globs=["findings.json"]))

examples/skills_code_review_agent/run_review.py

@@ -18,6 +18,8 @@
 
 import argparse
 import asyncio
+import shutil
+import subprocess
 from pathlib import Path
 
 from pipeline import report as report_mod
@@ -26,16 +28,34 @@
 HERE = Path(__file__).parent
 
 
+def _docker_available() -> bool:
+    if not shutil.which("docker"):
+        return False
+    try:
+        return subprocess.run(["docker", "info"], capture_output=True, timeout=5).returncode == 0
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _resolve_runtime(runtime: str) -> str:
+    """`auto` -> container when Docker is up (production default), else the local subprocess sandbox."""
+    if runtime != "auto":
+        return runtime
+    return "container" if _docker_available() else "local"
+
+
 def _parse_args() -> argparse.Namespace:
     ap = argparse.ArgumentParser(description="Automated code-review agent (Skills + sandbox + DB).")
     src = ap.add_mutually_exclusive_group(required=True)
     src.add_argument("--diff-file", help="path to a unified-diff file")
     src.add_argument("--repo-path", help="path to a git worktree (reviews `git diff`)")
+    src.add_argument("--files", help="comma-separated list of file paths to review as fully-added")
     src.add_argument("--fixture", help="name of a bundled fixture under fixtures/diffs/")
     ap.add_argument("--runtime",
-                    choices=["inprocess", "local", "container"],
-                    default="inprocess",
-                    help="scanner runtime: inprocess (fast), local (subprocess sandbox), container (Docker)")
+                    choices=["auto", "inprocess", "local", "container"],
+                    default="auto",
+                    help="scanner runtime: auto (sandbox: container if Docker, else local), "
+                    "inprocess (fast dev), local (subprocess sandbox), container (Docker)")
     ap.add_argument("--sandbox-timeout", type=float, default=None, help="sandbox timeout in seconds")
     ap.add_argument("--out-dir", default=".", help="where to write review_report.json/.md")
     ap.add_argument("--db-url", default="sqlite+aiosqlite:///./code_review.db")
@@ -44,13 +64,18 @@ def _parse_args() -> argparse.Namespace:
 
 
 def _run(args: argparse.Namespace) -> ReviewResult:
+    runtime = _resolve_runtime(args.runtime)
     if args.repo_path:
-        return run_review(repo_path=args.repo_path, runtime=args.runtime, sandbox_timeout=args.sandbox_timeout)
+        return run_review(repo_path=args.repo_path, runtime=runtime, sandbox_timeout=args.sandbox_timeout)
+    if args.files:
+        return run_review(files=[p.strip() for p in args.files.split(",") if p.strip()],
+                          runtime=runtime,
+                          sandbox_timeout=args.sandbox_timeout)
     path = Path(args.diff_file) if args.diff_file else HERE / "fixtures" / "diffs" / args.fixture
     diff_text = path.read_text(encoding="utf-8")
-    if args.runtime == "container":
+    if runtime == "container":
         return asyncio.run(run_review_container(diff_text=diff_text, sandbox_timeout=args.sandbox_timeout))
-    return run_review(diff_text=diff_text, runtime=args.runtime, sandbox_timeout=args.sandbox_timeout)
+    return run_review(diff_text=diff_text, runtime=runtime, sandbox_timeout=args.sandbox_timeout)
 
 
 async def _persist(result: ReviewResult, db_url: str) -> None:

examples/skills_code_review_agent/storage/dao.py

@@ -3,7 +3,6 @@
 # Copyright (C) 2026 Tencent. All rights reserved.
 #
 # tRPC-Agent-Python is licensed under Apache-2.0.
-
 """Persistence for reviews (issue #92, requirements 3 & 5).
 
 Wraps the framework's ``SqlStorage`` so the schema is portable (SQLite default, PostgreSQL/MySQL
@@ -53,6 +52,13 @@ async def persist(self, result: ReviewResult) -> None:
                 finding_count=int(mon.get("finding_count", 0)),
                 severity_dist=mon.get("severity_dist", {}),
                 exception_dist=mon.get("exception_dist", {}),
+                diff_summary={
+                    "files_changed": result.summary.files_changed,
+                    "added": result.summary.added,
+                    "removed": result.summary.removed,
+                    "languages": result.summary.languages,
+                    "changed_files": [f.path for f in result.summary.files],
+                },
             )
             await self._storage.add(db, task)
 

examples/skills_code_review_agent/storage/models.py

@@ -3,7 +3,6 @@
 # Copyright (C) 2026 Tencent. All rights reserved.
 #
 # tRPC-Agent-Python is licensed under Apache-2.0.
-
 """SQLAlchemy ORM models for code-review persistence (issue #92, requirement 5).
 
 Mirrors the framework's own SQL pattern (``trpc_agent_sdk/sessions/_sql_session_service.py``):
@@ -48,6 +47,7 @@ class ReviewTaskORM(CodeReviewBase):
     finding_count: Mapped[int] = mapped_column(Integer, default=0)
     severity_dist: Mapped[dict[str, Any]] = mapped_column(DynamicJSON, default=dict)
     exception_dist: Mapped[dict[str, Any]] = mapped_column(DynamicJSON, default=dict)
+    diff_summary: Mapped[dict[str, Any]] = mapped_column(DynamicJSON, default=dict)  # input-diff summary (要求5)
     create_time: Mapped[datetime] = mapped_column(PreciseTimestamp, default=func.now())
     update_time: Mapped[datetime] = mapped_column(PreciseTimestamp, default=func.now(), onupdate=func.now())
 

tests/examples/test_skills_code_review_agent.py

@@ -265,6 +265,45 @@ def test_all_six_rule_categories_reachable() -> None:
         assert required in cats, f"category {required} not produced"
 
 
+# --- spec-alignment: input modes, env whitelist, diff-summary persistence -----------------------
+
+
+def test_file_list_input_mode() -> None:
+    result = run_review(files=["pipeline/policy.py"], repo_root=str(_EXAMPLE_DIR))
+    assert result.source_type == "file_list"
+    assert result.summary.files_changed == 1
+
+
+def test_sandbox_env_is_whitelisted() -> None:
+    import os
+
+    from pipeline.policy import ENV_ALLOWLIST, sandbox_env
+
+    os.environ["CR_LEAK_TEST"] = "should-not-pass"
+    try:
+        env = sandbox_env()
+        assert "CR_LEAK_TEST" not in env
+        assert set(env).issubset(set(ENV_ALLOWLIST))
+    finally:
+        del os.environ["CR_LEAK_TEST"]
+
+
+@pytest.mark.asyncio
+async def test_diff_summary_persisted(tmp_path) -> None:
+    from storage.dao import ReviewStore
+
+    result = run_review(diff_text=(_FIXTURES / "security.diff").read_text())
+    store = ReviewStore(f"sqlite+aiosqlite:///{tmp_path / 'cr.db'}")
+    await store.init()
+    try:
+        await store.persist(result)
+        got = await store.get_by_task_id(result.task_id)
+        assert got["task"].diff_summary.get("files_changed") == 1
+        assert got["task"].diff_summary.get("changed_files") == ["security.py"]
+    finally:
+        await store.close()
+
+
 # (text containing a secret, the raw secret that must not survive redaction) — the leak-test corpus.
 _LEAK_CORPUS = [
     ('password = "hunter2supersecret"', "hunter2supersecret"),