add PostgreSQL

Author: Eternally72

examples/skills_code_review_agent/.env.example

@@ -18,6 +18,12 @@ CODE_REVIEW_STORAGE_BACKEND=sqlite
 CODE_REVIEW_SQLITE_PATH=storage/reviews.sqlite3
 # Optional compatible SQLite schema override
 CODE_REVIEW_SQLITE_SCHEMA_PATH=storage/schema.sql
+# PostgreSQL alternative (uncomment all fields and set backend=postgresql).
+# CODE_REVIEW_STORAGE_BACKEND=postgresql
+# CODE_REVIEW_POSTGRES_DSN=postgresql://review_agent:replace-me@127.0.0.1:5432/code_reviews
+# CODE_REVIEW_POSTGRES_SCHEMA_PATH=storage/postgres_schema.sql
+# CODE_REVIEW_POSTGRES_CONNECT_TIMEOUT_SECONDS=5
+# CODE_REVIEW_POSTGRES_STATEMENT_TIMEOUT_SECONDS=15
 
 # Sandbox policy ceilings; values may be tightened but not raised above defaults
 CODE_REVIEW_MAX_TIMEOUT_SECONDS=120

examples/skills_code_review_agent/README.md

@@ -35,13 +35,17 @@ skills_code_review_agent/
 │   ├── base.py                   # BaseReviewStore 抽象基类
 │   ├── factory.py                # 环境变量驱动的实现选择
 │   ├── schema.sql                # 显式 SQLite schema
-│   └── sqlite.py                 # SQLite 实现
+│   ├── sqlite.py                 # SQLite 实现
+│   ├── postgres_schema.sql       # PostgreSQL 初始化/迁移 schema
+│   ├── postgresql.py             # PostgreSQL 实现
+│   └── schema_loader.py          # 受限 schema 文件加载
 ├── reports/
 │   ├── models.py                 # 结构化审查模型
 │   └── writers.py                # JSON/Markdown 输出
 ├── tests/fixtures/               # 8 条要求样本及超时补充样本
 ├── tests/run_tests.py            # 非 Docker 验收测试入口
 ├── tests/run_docker_tests.py     # tRPC Container runtime 集成测试
+├── tests/run_postgres_tests.py   # PostgreSQL 存储契约集成测试
 ├── tests/evaluate_fixtures.py    # 公开 fixture 指标评测
 └── examples/review_report.*      # 示例报告
 ```
@@ -116,10 +120,22 @@ CODE_REVIEW_SQLITE_PATH=storage/reviews.sqlite3
 CODE_REVIEW_SQLITE_SCHEMA_PATH=storage/schema.sql
 ```
 
-当前只实现 `sqlite`；新增后端应继承 `BaseReviewStore` 并在 `storage/factory.py` 注册。`--database` 的优先级高于 `CODE_REVIEW_SQLITE_PATH`。
+PostgreSQL 使用可选驱动，启用前安装本示例的 `postgresql` extra，并仅通过环境变量传递 DSN，避免凭据出现在命令行进程列表中：
+
+```bash
+uv sync --project examples/skills_code_review_agent --extra postgresql
+
+CODE_REVIEW_STORAGE_BACKEND=postgresql
+CODE_REVIEW_POSTGRES_DSN=postgresql://review_agent:<password>@127.0.0.1:5432/code_reviews
+CODE_REVIEW_POSTGRES_SCHEMA_PATH=storage/postgres_schema.sql
+CODE_REVIEW_POSTGRES_CONNECT_TIMEOUT_SECONDS=5
+CODE_REVIEW_POSTGRES_STATEMENT_TIMEOUT_SECONDS=15
+```
+
+远程 PostgreSQL DSN 必须设置 `sslmode=require`、`verify-ca` 或 `verify-full`，生产环境推荐 `verify-full`；本地 loopback 联调可不启用 TLS。数据库账号只需目标 schema 的建表/迁移和表读写权限，不应授予超级用户权限。`--database` 仅用于 SQLite，且优先级高于 `CODE_REVIEW_SQLITE_PATH`。
 `CODE_REVIEW_SQLITE_SCHEMA_PATH` 可选择兼容的 SQLite 初始化 schema；替换文件必须保留存储实现使用的表和字段契约，并且只能使用 `storage/` 下的普通文件。schema 有大小限制，初始化时禁止 attach、trigger、view、虚拟表、删除对象和业务数据写入。
 
-SQLite 分表保存 `review_tasks`、`review_inputs`、`sandbox_runs`、`filter_decisions`、`findings`、`monitoring_summaries` 和 `review_reports`，`get_task_details(task_id)` 可查询完整审计记录。任务在 Agent 启动前以 `running` 状态落库，异常终止会更新为 `failed`。SQLite 启用 WAL、等待锁和 digest/profile 索引。对于内容不可变的 diff/fixture，缓存必须同时匹配输入摘要、规则、Skill、模式、模型和审查范围；是否复用仍由 Agent 决定。
+SQLite 与 PostgreSQL 均通过 `BaseReviewStore` 分表保存 `review_tasks`、`review_inputs`、`sandbox_runs`、`filter_decisions`、`findings`、`monitoring_summaries` 和 `review_reports`，`get_task_details(task_id)` 可查询完整审计记录。任务在 Agent 启动前以 `running` 状态落库，异常终止会更新为 `failed`。SQLite 启用 WAL 和等待锁；PostgreSQL 使用短事务、连接/语句/锁超时、参数化 SQL 和 JSONB。两者均提供 digest/profile 索引。对于内容不可变的 diff/fixture，缓存必须同时匹配输入摘要、规则、Skill、模式、模型和审查范围；是否复用仍由 Agent 决定。
 
 沙箱实现由 `CODE_REVIEW_SANDBOX_BACKEND=docker` 选择，当前仅提供 Docker；新增实现需满足 `SandboxProvider` 并在 `sandbox/factory.py` 注册。可通过 `--output-dir` 和 `--docker-image` 覆盖输出目录和镜像。Docker runtime 按 Agent 的 workspace 工具调用惰性创建；代码只读挂载，diff/fixture 仅挂载任务级副本。容器禁网、非 root、删除 capabilities、启用 `no-new-privileges` 和只读根文件系统，并限制 CPU、内存、PID 与 tmpfs。模型服务仍由宿主进程调用，因此应使用符合代码数据策略的模型服务。
 
@@ -133,7 +149,7 @@ SQLite 分表保存 `review_tasks`、`review_inputs`、`sandbox_runs`、`filter_
 - 单次 Skill run 默认 30 秒；整次 review 默认 110 秒、30 次工具调用和 12 次 sandbox run。所有限制均可通过 `.env` 中的 `CODE_REVIEW_*` 字段收紧。
 - Workflow 可信地记录每个脚本的 cursor；缺少必需的 staged、unstaged、文件枚举或受控读取证据，或者任一 `next_cursor` 未读完时，报告会强制加入人工复核项。
 - 代码、注释和工具输出均按不可信数据处理；Filter 阻止外部 diff helper、敏感路径和跨输入模式读取。
-- 输入预览、finding、Filter、sandbox 输出、数据库和报告写入前执行敏感信息脱敏。
+- 输入预览、finding、Filter、sandbox 输出、数据库和报告写入前执行敏感信息脱敏；PostgreSQL DSN 不进入报告、数据库字段或 CLI 参数。
 - 容器进程由容器内 `timeout` 终止；stdout/stderr 在返回模型前按 `CODE_REVIEW_MAX_OUTPUT_BYTES` 硬限制并脱敏。受 Skill 工具 16 KiB inline 契约约束，Docker 传输的两路输出合计还会取配置值与 15 KiB 的较小者，避免 Docker Desktop 在 64 KiB socket 边界产生长时间等待。
 - findings 按 `(file, line, category)` 去重，置信度低于 `0.70` 自动进入 warnings。
 
@@ -165,6 +181,16 @@ uv run --project examples/skills_code_review_agent --with-editable . \
 
 测试覆盖：无问题、安全问题、异步任务泄漏、资源生命周期、数据库连接生命周期、测试缺失、重复 finding、sandbox 失败/超时、敏感信息脱敏、六类独立规则、配置工厂、分页、挂载最小化和报告注入。Docker 集成脚本验证 Skill 加载、规则执行、Filter、只读输入、禁网、真实超时、分页以及容器资源安全配置；模型效果仍取决于所配置模型，隐藏样本指标不能由公开 fixture 证明。
 
+对已授权的独立 PostgreSQL 测试库执行完整存储契约（会创建本示例的表并写入带随机 ID 的测试行）：
+
+```bash
+CODE_REVIEW_POSTGRES_DSN='postgresql://review_agent:<password>@127.0.0.1:5432/code_reviews' \
+uv run --project examples/skills_code_review_agent --extra postgresql --with-editable . \
+  python examples/skills_code_review_agent/tests/run_postgres_tests.py
+```
+
+该脚本验证 schema 初始化、task/report 往返、幂等保存、规范化明细查询、缓存查询、失败审计和落库前脱敏。只应对专用测试数据库执行。
+
 使用 `.env` 中的真实模型做完整联调：
 
 ```bash

examples/skills_code_review_agent/docs/design.md

@@ -1,3 +1,3 @@
 # 方案设计
 
-本原型采用 workflow-shaped、agent-driven 架构。Workflow 负责输入、校验、落库和报告；Agent 决定复用历史证据，还是加载 `code-review` Skill 进入沙箱。Skill 将安全、异步、资源、数据库、测试和敏感信息检查拆成六个脚本，diff 与文件读取均分页返回证据。输入支持 diff、文件列表、Git 工作区和 fixture，并保留 hunk、上下文和行号。检查运行在禁网 Docker workspace；代码只读，外部 diff 仅挂载私有副本，容器采用非 root、只读根文件系统、无 capability 及资源限制。超时进程在容器内终止，输出进入模型前限量脱敏。Filter 按输入类型限制命令、Skill 参数、路径、网络、环境变量和预算，拒绝项不执行。SQLite 通过可替换基类保存任务、输入、执行、拦截、finding、监控和报告。结果按文件、行号、类别去重，低置信项进入 warnings。监控记录总耗时、沙箱耗时、工具调用、拦截、严重级别和异常；失败转人工复核并保留审计记录。
+本原型采用 workflow-shaped、agent-driven 架构。Workflow 负责输入、校验、落库和报告；Agent 决定复用历史证据，还是加载 `code-review` Skill 进入沙箱。Skill 将安全、异步、资源、数据库、测试和敏感信息检查拆成六个脚本，diff 与文件读取均分页返回证据。输入支持 diff、文件列表、Git 工作区和 fixture，并保留 hunk、上下文和行号。检查运行在禁网 Docker workspace；代码只读，外部 diff 仅挂载私有副本，容器采用非 root、只读根文件系统、无 capability 及资源限制。超时进程在容器内终止，输出进入模型前限量脱敏。Filter 按输入类型限制命令、Skill 参数、路径、网络、环境变量和预算，拒绝项不执行。可替换存储接口默认使用 SQLite，也可由环境变量切换 PostgreSQL；两种实现均分表保存任务、输入、执行、拦截、finding、监控和报告，PostgreSQL 另有短事务、参数化 SQL、TLS 与连接/语句超时边界，并限制凭据暴露。结果按文件、行号、类别去重，低置信项进入 warnings。监控记录总耗时、沙箱耗时、工具调用、拦截、严重级别和异常；失败转人工复核并保留审计记录。

examples/skills_code_review_agent/pyproject.toml

@@ -1,7 +1,10 @@
 [project]
 name = "skills-code-review-agent"
 version = "0.1.0"
-description = "A skill-based code review agent using Docker and SQLite"
+description = "A skill-based code review agent using Docker and SQL persistence"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = []
+
+[project.optional-dependencies]
+postgresql = ["psycopg[binary]>=3.2,<4"]

examples/skills_code_review_agent/run_agent.py

@@ -84,7 +84,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--database",
         type=Path,
         default=None,
-        help="SQLite path overriding CODE_REVIEW_SQLITE_PATH",
+        help="SQLite path overriding CODE_REVIEW_SQLITE_PATH (SQLite only)",
     )
     parser.add_argument(
         "--output-dir",

examples/skills_code_review_agent/storage/factory.py

@@ -4,33 +4,70 @@
 from pathlib import Path
 
 from .base import BaseReviewStore
+from .postgresql import SCHEMA_PATH as POSTGRES_SCHEMA_PATH
+from .postgresql import PostgreSQLReviewStore
 from .sqlite import SCHEMA_PATH
 from .sqlite import SQLiteReviewStore
 
 EXAMPLE_ROOT = Path(__file__).resolve().parent.parent
 DEFAULT_SQLITE_PATH = EXAMPLE_ROOT / "storage" / "reviews.sqlite3"
 
 
+def _configured_path(name: str, default: Path) -> Path:
+    value = os.getenv(name, "").strip()
+    path = Path(value) if value else default
+    if value and not path.is_absolute():
+        path = EXAMPLE_ROOT / path
+    return path
+
+
+def _bounded_integer(name: str, default: int, maximum: int) -> int:
+    value = os.getenv(name, "").strip()
+    if not value:
+        return default
+    try:
+        parsed = int(value)
+    except ValueError as error:
+        raise ValueError(f"{name} must be an integer") from error
+    if parsed < 1 or parsed > maximum:
+        raise ValueError(f"{name} must be between 1 and {maximum}")
+    return parsed
+
+
 def create_review_store(database_path: Path | None = None) -> BaseReviewStore:
     """Create the configured persistence implementation.
 
-    An explicit CLI path overrides ``CODE_REVIEW_SQLITE_PATH``. The backend is
-    selected with ``CODE_REVIEW_STORAGE_BACKEND`` and currently supports only
-    ``sqlite``.
+    An explicit CLI path overrides ``CODE_REVIEW_SQLITE_PATH``. PostgreSQL is
+    selected entirely through environment configuration so a DSN never appears
+    in command-line process listings.
     """
     backend = os.getenv("CODE_REVIEW_STORAGE_BACKEND", "sqlite").strip().lower()
+    if backend in {"postgres", "postgresql"}:
+        if database_path is not None:
+            raise ValueError("--database can only be used with SQLite storage")
+        return PostgreSQLReviewStore(
+            os.getenv("CODE_REVIEW_POSTGRES_DSN", ""),
+            schema_path=_configured_path(
+                "CODE_REVIEW_POSTGRES_SCHEMA_PATH",
+                POSTGRES_SCHEMA_PATH,
+            ),
+            connect_timeout_seconds=_bounded_integer(
+                "CODE_REVIEW_POSTGRES_CONNECT_TIMEOUT_SECONDS",
+                5,
+                30,
+            ),
+            statement_timeout_seconds=_bounded_integer(
+                "CODE_REVIEW_POSTGRES_STATEMENT_TIMEOUT_SECONDS",
+                15,
+                60,
+            ),
+        )
     if backend != "sqlite":
         raise ValueError(f"Unsupported storage backend: {backend}")
 
     if database_path is not None:
         sqlite_path = database_path
     else:
-        configured_path = os.getenv("CODE_REVIEW_SQLITE_PATH", "").strip()
-        sqlite_path = Path(configured_path) if configured_path else DEFAULT_SQLITE_PATH
-        if configured_path and not sqlite_path.is_absolute():
-            sqlite_path = EXAMPLE_ROOT / sqlite_path
-    configured_schema = os.getenv("CODE_REVIEW_SQLITE_SCHEMA_PATH", "").strip()
-    schema_path = Path(configured_schema) if configured_schema else SCHEMA_PATH
-    if configured_schema and not schema_path.is_absolute():
-        schema_path = EXAMPLE_ROOT / schema_path
+        sqlite_path = _configured_path("CODE_REVIEW_SQLITE_PATH", DEFAULT_SQLITE_PATH)
+    schema_path = _configured_path("CODE_REVIEW_SQLITE_SCHEMA_PATH", SCHEMA_PATH)
     return SQLiteReviewStore(sqlite_path, schema_path=schema_path)

examples/skills_code_review_agent/storage/postgres_schema.sql

@@ -0,0 +1,90 @@
+CREATE TABLE IF NOT EXISTS public.review_tasks (
+    task_id TEXT PRIMARY KEY,
+    created_at TEXT NOT NULL,
+    completed_at TEXT NOT NULL,
+    status TEXT NOT NULL,
+    repository TEXT NOT NULL,
+    scope TEXT NOT NULL,
+    conclusion TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS public.review_inputs (
+    task_id TEXT PRIMARY KEY REFERENCES public.review_tasks(task_id) ON DELETE CASCADE,
+    kind TEXT NOT NULL,
+    source TEXT NOT NULL,
+    digest TEXT NOT NULL,
+    review_profile TEXT NOT NULL DEFAULT 'legacy',
+    file_count INTEGER NOT NULL,
+    hunk_count INTEGER NOT NULL,
+    added_lines INTEGER NOT NULL,
+    removed_lines INTEGER NOT NULL,
+    files_json JSONB NOT NULL,
+    redacted_preview TEXT NOT NULL
+);
+
+ALTER TABLE public.review_inputs
+    ADD COLUMN IF NOT EXISTS review_profile TEXT NOT NULL DEFAULT 'legacy';
+
+CREATE TABLE IF NOT EXISTS public.sandbox_runs (
+    run_id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL REFERENCES public.review_tasks(task_id) ON DELETE CASCADE,
+    command TEXT NOT NULL,
+    status TEXT NOT NULL,
+    duration_ms DOUBLE PRECISION NOT NULL,
+    exit_code INTEGER,
+    timed_out BOOLEAN NOT NULL,
+    output_truncated BOOLEAN NOT NULL,
+    stdout_summary TEXT NOT NULL,
+    stderr_summary TEXT NOT NULL,
+    error_type TEXT
+);
+
+CREATE TABLE IF NOT EXISTS public.filter_decisions (
+    decision_id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL REFERENCES public.review_tasks(task_id) ON DELETE CASCADE,
+    command TEXT NOT NULL,
+    decision TEXT NOT NULL,
+    reason TEXT NOT NULL,
+    created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS public.findings (
+    finding_id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL REFERENCES public.review_tasks(task_id) ON DELETE CASCADE,
+    bucket TEXT NOT NULL,
+    severity TEXT NOT NULL,
+    category TEXT NOT NULL,
+    file TEXT NOT NULL,
+    line INTEGER,
+    title TEXT NOT NULL,
+    evidence TEXT NOT NULL,
+    recommendation TEXT NOT NULL,
+    confidence DOUBLE PRECISION NOT NULL,
+    source TEXT NOT NULL,
+    UNIQUE(task_id, bucket, file, line, category)
+);
+
+CREATE TABLE IF NOT EXISTS public.monitoring_summaries (
+    task_id TEXT PRIMARY KEY REFERENCES public.review_tasks(task_id) ON DELETE CASCADE,
+    total_duration_ms DOUBLE PRECISION NOT NULL,
+    sandbox_duration_ms DOUBLE PRECISION NOT NULL,
+    tool_call_count INTEGER NOT NULL,
+    blocked_count INTEGER NOT NULL,
+    finding_count INTEGER NOT NULL,
+    severity_distribution_json JSONB NOT NULL,
+    exception_distribution_json JSONB NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS public.review_reports (
+    task_id TEXT PRIMARY KEY REFERENCES public.review_tasks(task_id) ON DELETE CASCADE,
+    report_json JSONB NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_review_inputs_digest_profile
+    ON public.review_inputs(digest, review_profile);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_findings_unique_issue
+    ON public.findings(task_id, file, COALESCE(line, -1), category);
+CREATE INDEX IF NOT EXISTS idx_sandbox_runs_task_id
+    ON public.sandbox_runs(task_id);
+CREATE INDEX IF NOT EXISTS idx_filter_decisions_task_id
+    ON public.filter_decisions(task_id);