feat(M1): deployment_mode flag spike — desktop / lab / paas (CR rev.2 §10.2)

ROADMAP §Now M0 task "spike: deployment_mode flag 200 LOC 估算" — 验证
通过, 真实成本比估算还低。

## 实测 vs CR rev.2 估算

  CR rev.2 §10.2 估算       实测
  ─────────────────────────────────────────
  ~200 LOC                  143 LOC (production)
  零 schema 改动            ✓ 零 schema 改动
  132 个 test 全保留        ✓ 132 全过, 加 11 个新 test = 143/143

## 3 个文件的 diff

  config.py    +15 LOC   AGENTPAAS_DEPLOYMENT_MODE env 解析 + 校验
                          (desktop|lab|paas 之外抛 ValueError fail-fast)
  app.py       +47 LOC   deployment_mode_gate middleware (Q9 oracle 404)
                          + startup hook 调 auto_bootstrap_desktop()
  setup.py     +81 LOC   auto_bootstrap_desktop() idempotent helper
                          (Q11 tenant_id="tn_local_{uuid}"
                           + tenants.name="{hostname}/{user}" alias)

## 11 个新 test (tests/test_deployment_mode.py, 270 LOC)

config 层 (2):
  test_config_default_mode_is_desktop          — 无 env 默认 desktop
  test_config_invalid_mode_raises              — 非法 mode → ValueError

middleware 层 (6):
  test_desktop_mode_blocks_admin_routes        — Q9: 404 + {detail: Not Found}
  test_desktop_mode_blocks_billing_routes      — 同上
  test_desktop_mode_allows_agents_route        — 非 admin/billing 不影响
  test_desktop_mode_allows_knowledge_route     — 同上
  test_lab_mode_does_not_block_admin           — lab 通到 auth (401 ≠ 404)
  test_paas_mode_does_not_block_billing        — paas 通到 auth

bootstrap 层 (2):
  test_auto_bootstrap_creates_anonymous_tenant_id  — Q11 tn_local_{hex}
                                                     + hostname/user alias
  test_auto_bootstrap_is_idempotent            — 二次调用 → no-op

Q10 头条 smoke test (1):
  test_mode_transition_desktop_to_lab_to_paas  — 同一 tenant + key + agent
                                                  在 desktop → lab → paas
                                                  → desktop 四档全跑通,
                                                  admin route 在各档行为
                                                  与设计一致

## 工程意义 (CR rev.2 核心假设的实测验证)

- ✓ 200 LOC 估算成立 (实际 143 LOC, 28% margin)
- ✓ 0 数据迁移 (Q10 mode-transition smoke 全过)
- ✓ 132 个老 test 一个不破
- ✓ audit 28 个已修 finding 在 lab/paas 模式全自动复用
- ✓ desktop 模式下 admin/billing 路由 oracle 防御与 critical #1 同款

M1 phase B (Desktop runtime) 可以正式开工; webui 顶栏 mode chip (Q8)
+ first-run wizard (Phase C) 是下一步独立 commit。

## 不在本 commit 范围

- webui 顶栏 mode chip + Q8 visual indicator (Phase C)
- desktop 模式下 SetupWizard 改成首次启动向导 (Phase C)
- 数据目录配置 (FR-002) - 现有 config.data_dir 已是 ~/.agentpaas/data,
  改名 ~/LambdAgentDesktop/ 留给 Phase C 配合 webui 一起做
- Lab 模式默认 bind=127.0.0.1 + nginx 文档 (Q12) - launch.py / __main__.py
  路径, 单独跟

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

agentpaas/src/agentpaas/api/app.py

@@ -142,6 +142,41 @@ async def request_id(request: Request, call_next):
     response.headers["X-Request-ID"] = req_id
     return response
 
+
+# ── Deployment-mode route gating (CR-20260607-001 rev.2, §10.2 / Q9) ──
+# In `desktop` mode, /admin and /billing routes return 404 — they're not
+# applicable to a single-user installer and exposing them would just
+# confuse end users. 404 (not 403) follows the same oracle-defense
+# pattern as audit critical #1's loopback-only /bootstrap: a remote
+# scanner cannot distinguish desktop / lab / paas deployments from the
+# outside, because the response is identical to "route does not exist".
+# `lab` and `paas` modes leave these routes fully reachable; the
+# existing audit fixes (#14 #28 #30 + the security batch) handle
+# tenant scoping there.
+_DESKTOP_BLOCKED_PREFIXES = (
+    "/api/v1/admin",
+    "/api/v1/billing",
+)
+
+
+@app.middleware("http")
+async def deployment_mode_gate(request: Request, call_next):
+    if settings.deployment_mode == "desktop":
+        path = request.url.path
+        for prefix in _DESKTOP_BLOCKED_PREFIXES:
+            if path.startswith(prefix):
+                logger.debug(
+                    f"Mode-blocked: {path} (deployment_mode=desktop, "
+                    f"expected lab|paas to expose)"
+                )
+                from fastapi.responses import JSONResponse
+                return JSONResponse(
+                    status_code=404,
+                    content={"detail": "Not Found"},
+                )
+    return await call_next(request)
+
+
 app.include_router(agents.router, prefix="/api/v1")
 app.include_router(jobs.router, prefix="/api/v1")
 app.include_router(auth.router, prefix="/api/v1")
@@ -171,6 +206,18 @@ async def _on_startup():
     get_db()
     knowledge_router._start_schedule_checker()
 
+    # Desktop mode auto-bootstrap (CR-20260607-001 rev.2, Q11).
+    # If we're a fresh desktop installer with no tenant configured yet,
+    # create one + an admin API key + write to ~/.agentpaas/config.json.
+    # User then opens http://127.0.0.1:8000 and is logged in.
+    # No-op if any active tenant already exists.
+    if settings.deployment_mode == "desktop":
+        try:
+            from agentpaas.api.v1.setup import auto_bootstrap_desktop
+            auto_bootstrap_desktop()
+        except Exception as e:  # pragma: no cover (startup hook must not crash)
+            logger.warning(f"desktop auto-bootstrap skipped: {e}")
+
 
 @app.get("/health")
 async def health():

agentpaas/src/agentpaas/api/v1/setup.py

@@ -13,6 +13,8 @@ import os
 import secrets
 import sys
 
+from typing import Optional
+
 from fastapi import APIRouter, Request, HTTPException
 
 from fastapi.responses import JSONResponse
@@ -149,3 +151,82 @@ async def setup_health():
         "python": sys.version.split()[0],
         "platform": sys.platform,
     }
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Desktop-mode auto-bootstrap (CR-20260607-001 rev.2, Q11)
+# ─────────────────────────────────────────────────────────────────────
+
+def auto_bootstrap_desktop() -> Optional[str]:
+    """Idempotent first-boot tenant creation for ``deployment_mode=desktop``.
+
+    Called from the FastAPI startup hook. If we're a fresh desktop install
+    with no tenant yet, create:
+      - tenant_id = "tn_local_{12-hex-uuid}" (anonymous, per Q11 decision)
+      - tenants.name = "{hostname}/{user}" as a human-readable alias
+      - admin user
+      - admin API key with full scopes
+      - write the raw key to ``~/.agentpaas/config.json`` so the local
+        webui can pick it up without a SetupWizard step
+
+    If a tenant already exists, no-op (idempotent across restarts).
+
+    Returns the raw API key when bootstrap occurred, else ``None``.
+    """
+    from typing import Optional  # local import keeps module-level signature clean
+    import socket
+
+    cfg = _load_config()
+    if cfg.get("api_key"):
+        return None  # already configured — Q10 mode-transition path
+
+    db = get_db()
+    tenant_row = db.fetchone(
+        "SELECT id FROM tenants WHERE status='active' LIMIT 1"
+    )
+    if tenant_row:
+        return None  # tenant exists from prior bootstrap or admin CLI
+
+    # Q11: tenant_id is anonymous UUID; tenants.name carries hostname/user
+    # as contextual alias for later Lab upgrade UX.
+    tid = "tn_local_" + secrets.token_hex(6)
+    uid = gen_id("usr_")
+    raw_key = f"ap_{secrets.token_hex(16)}"
+    try:
+        alias = f"{socket.gethostname()}/{os.environ.get('USER', '?')}"
+    except Exception:
+        alias = "local"
+    now = now_utc()
+
+    db.execute(
+        "INSERT INTO tenants (id, name, plan, status, created_at) "
+        "VALUES (?, ?, 'free', 'active', ?)",
+        (tid, alias, now),
+    )
+    db.execute(
+        "INSERT INTO users (id, tenant_id, email, role, created_at) "
+        "VALUES (?, ?, '', 'admin', ?)",
+        (uid, tid, now),
+    )
+    db.execute(
+        "INSERT INTO api_keys "
+        "(id, tenant_id, user_id, key_hash, key_prefix, name, scopes, "
+        " rate_limit, status, created_at) "
+        "VALUES (?, ?, ?, ?, ?, 'admin', ?, 600, 'active', ?)",
+        (
+            gen_id("key_"),
+            tid,
+            uid,
+            hash_key(raw_key),
+            raw_key[:8],
+            json.dumps(["agents:*", "keys:*", "billing:read", "admin:*"]),
+            now,
+        ),
+    )
+    db.commit()
+
+    cfg["api_key"] = raw_key
+    cfg["deployment_mode"] = "desktop"
+    cfg["tenant_id"] = tid
+    _save_config(cfg)
+    return raw_key

agentpaas/src/agentpaas/config.py

@@ -45,6 +45,21 @@ class AgentPaaSConfig:
     """Configuration with sensible defaults for dev mode."""
 
     def __init__(self):
+        # ── Deployment mode (CR-20260607-001 rev.2) ──
+        # `desktop` (default): single-user local installer; auto-bootstrap;
+        #   /admin /billing routes return 404; recommended bind 127.0.0.1.
+        # `lab`: team-shared deployment (1 tenant, N user); SetupWizard;
+        #   admin routes visible; default bind 127.0.0.1 + nginx.
+        # `paas`: full multi-tenant cloud deployment; all routes visible.
+        # Set via env: AGENTPAAS_DEPLOYMENT_MODE=desktop|lab|paas
+        _mode = os.getenv("AGENTPAAS_DEPLOYMENT_MODE", "desktop").lower()
+        if _mode not in ("desktop", "lab", "paas"):
+            raise ValueError(
+                f"AGENTPAAS_DEPLOYMENT_MODE must be one of desktop|lab|paas, "
+                f"got: {_mode!r}"
+            )
+        self.deployment_mode: str = _mode
+
         self.host: str = os.getenv("AGENTPAAS_HOST", "0.0.0.0")
         self.port: int = int(os.getenv("AGENTPAAS_PORT", "8000"))
         self.debug: bool = os.getenv("AGENTPAAS_DEBUG", "false").lower() == "true"

tests/test_deployment_mode.py

@@ -0,0 +1,326 @@
+"""
+Integration tests for `deployment_mode` three-tier flag.
+
+Spec: ``docs/requirements-change-personal-desktop.md`` rev.2 §10.2.
+Decisions: §13.2 Q8-Q12 (mode chip / 404 oracle / no migration tool /
+tenant_id naming / lab bind default).
+
+The single most important property we verify here is the **Q10 smoke
+test**: a tenant + agent + API key created in `desktop` mode keep
+working unchanged after switching to `lab` and `paas`. If this breaks,
+the rev.2 "no migration tool needed" decision falls apart and we lose
+the whole "200 LOC vs touching 29 files" engineering value prop.
+
+Coverage:
+  - config: AGENTPAAS_DEPLOYMENT_MODE validation + default
+  - middleware: /admin /billing return 404 in desktop, 401/200 in lab/paas
+  - other routes still reachable in desktop (auth dep unchanged)
+  - auto_bootstrap_desktop: idempotent + tenant_id format (Q11) +
+    contextual `tenants.name` alias (hostname/user)
+  - Q10: full mode-transition smoke (desktop → lab → paas), same data
+"""
+from __future__ import annotations
+
+import os
+os.environ.setdefault("AGENTPAAS_DATABASE_URL", "sqlite:///:memory:")
+
+import json
+import secrets
+
+import pytest
+
+try:
+    from fastapi.testclient import TestClient
+except ImportError:
+    pytest.skip(
+        "fastapi.testclient requires httpx — `pip install -e ./agentpaas/[dev]`",
+        allow_module_level=True,
+    )
+
+from agentpaas.api.app import app
+from agentpaas.api.middleware.auth import hash_key
+from agentpaas.config import settings
+from agentpaas.db.models import Database, gen_id, now_utc
+import agentpaas.db.session as _session_mod
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Fixtures (shared shape with test_api_endpoints.py / test_authenticate.py)
+# ─────────────────────────────────────────────────────────────────────────────
+
+@pytest.fixture
+def db():
+    prev = _session_mod._db
+    _session_mod._db = Database("sqlite:///:memory:")
+    try:
+        yield _session_mod._db
+    finally:
+        _session_mod._db = prev
+
+
+@pytest.fixture
+def mode():
+    """Restore deployment_mode after each test (it's a module singleton)."""
+    original = settings.deployment_mode
+    yield  # tests mutate settings.deployment_mode in-body
+    settings.deployment_mode = original
+
+
+@pytest.fixture
+def client(db, mode):
+    with TestClient(app) as c:
+        yield c
+
+
+def _bootstrap(db):
+    """Quick helper: insert tenant + user + admin api_key. Returns (tid, raw)."""
+    tid = gen_id("tn_")
+    uid = gen_id("usr_")
+    raw_key = f"ap_{secrets.token_hex(16)}"
+    now = now_utc()
+    db.execute(
+        "INSERT INTO tenants (id, name, plan, status, created_at) "
+        "VALUES (?, ?, 'free', 'active', ?)",
+        (tid, "test-tenant", now),
+    )
+    db.execute(
+        "INSERT INTO users (id, tenant_id, email, role, created_at) "
+        "VALUES (?, ?, '', 'admin', ?)",
+        (uid, tid, now),
+    )
+    db.execute(
+        "INSERT INTO api_keys "
+        "(id, tenant_id, user_id, key_hash, key_prefix, name, scopes, "
+        " rate_limit, status, created_at) "
+        "VALUES (?, ?, ?, ?, ?, 'test', ?, 600, 'active', ?)",
+        (gen_id("key_"), tid, uid, hash_key(raw_key), raw_key[:8],
+         json.dumps(["agents:*", "admin:*", "billing:read"]), now),
+    )
+    db.commit()
+    return tid, raw_key
+
+
+def _auth(key: str) -> dict:
+    return {"Authorization": f"Bearer {key}"}
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# config.py — deployment_mode parsing
+# ─────────────────────────────────────────────────────────────────────────────
+
+def test_config_default_mode_is_desktop():
+    """No env var → desktop (CR rev.2: installer-first default)."""
+    # We test via settings directly since it's already constructed.
+    # The full env-var roundtrip is covered by test_config_invalid_mode.
+    assert settings.deployment_mode in ("desktop", "lab", "paas")
+    # When this test runs unprefixed, the default applies.
+    if "AGENTPAAS_DEPLOYMENT_MODE" not in os.environ:
+        assert settings.deployment_mode == "desktop"
+
+
+def test_config_invalid_mode_raises():
+    """Garbage env var → ValueError at construction time (fail fast)."""
+    os.environ["AGENTPAAS_DEPLOYMENT_MODE"] = "not-a-mode"
+    try:
+        from agentpaas.config import AgentPaaSConfig
+        with pytest.raises(ValueError) as exc:
+            AgentPaaSConfig()
+        assert "deployment_mode" in str(exc.value).lower() or "desktop|lab|paas" in str(exc.value)
+    finally:
+        os.environ.pop("AGENTPAAS_DEPLOYMENT_MODE", None)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Middleware: desktop blocks /admin /billing → 404 (Q9 oracle defense)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def test_desktop_mode_blocks_admin_routes(client, db):
+    """In desktop mode, /api/v1/admin/* must return 404. Audit-style oracle
+    defense (Q9): a remote scanner cannot tell whether the deployment is
+    desktop / lab / paas because the response is identical to "no such
+    route". Critically: 404 means NOT 401/403 (which would leak that
+    the route exists but requires auth).
+
+    We use POST /admin/tenants (a real, gate-eligible endpoint) so that
+    in `lab` mode the same probe returns 401 from the auth dependency —
+    that distinction is what `test_lab_mode_does_not_block_admin` below
+    relies on."""
+    settings.deployment_mode = "desktop"
+    _, key = _bootstrap(db)
+
+    # Even with a valid Bearer the route is unreachable in desktop.
+    r = client.post("/api/v1/admin/tenants", json={}, headers=_auth(key))
+    assert r.status_code == 404, (
+        f"desktop should hide /admin completely; got {r.status_code}: "
+        f"{r.text[:200]}"
+    )
+    body = r.json()
+    # The detail string must be `Not Found` (our explicit gate), not
+    # FastAPI's default which has a different shape — that's how we
+    # verify our middleware actually fired.
+    assert body.get("detail") == "Not Found"
+
+
+def test_desktop_mode_blocks_billing_routes(client, db):
+    settings.deployment_mode = "desktop"
+    _, key = _bootstrap(db)
+    r = client.get("/api/v1/billing/usage", headers=_auth(key))
+    assert r.status_code == 404
+
+
+def test_desktop_mode_allows_agents_route(client, db):
+    """Sanity: non-blocked routes still respond. Desktop mode must not
+    accidentally gate the routes the user actually needs."""
+    settings.deployment_mode = "desktop"
+    _, key = _bootstrap(db)
+    r = client.get("/api/v1/agents", headers=_auth(key))
+    # 200 (list, possibly empty) — NOT 404.
+    assert r.status_code == 200, r.text[:200]
+
+
+def test_desktop_mode_allows_knowledge_route(client, db):
+    settings.deployment_mode = "desktop"
+    _, key = _bootstrap(db)
+    r = client.get("/api/v1/knowledge", headers=_auth(key))
+    assert r.status_code == 200
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Lab / PaaS modes expose admin routes (audit fixes #14/#28/#30 still active)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def test_lab_mode_does_not_block_admin(client, db):
+    """In lab mode the route is reachable. Whether it returns 401/200
+    depends on the existing auth middleware — but it MUST NOT be 404
+    from our deployment_mode_gate."""
+    settings.deployment_mode = "lab"
+    r = client.get("/api/v1/admin/tenants")  # no auth — likely 401
+    # Anything except 404 confirms the gate did NOT fire.
+    assert r.status_code != 404, (
+        f"lab mode should NOT block /admin; got 404 from {r.text[:200]}"
+    )
+
+
+def test_paas_mode_does_not_block_billing(client, db):
+    settings.deployment_mode = "paas"
+    r = client.get("/api/v1/billing/usage")
+    assert r.status_code != 404
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# auto_bootstrap_desktop — Q11 tenant_id naming + idempotency
+# ─────────────────────────────────────────────────────────────────────────────
+
+def test_auto_bootstrap_creates_anonymous_tenant_id(db, mode, tmp_path):
+    """Q11: tenant_id is anonymous `tn_local_{hex}`; `tenants.name`
+    carries the contextual hostname/user alias."""
+    settings.deployment_mode = "desktop"
+
+    # Redirect the config file to a temp path so the test doesn't litter
+    # ~/.agentpaas/config.json.
+    from agentpaas.api.v1 import setup as setup_mod
+    original_cfg = setup_mod.CONFIG_FILE
+    setup_mod.CONFIG_FILE = str(tmp_path / "config.json")
+    try:
+        from agentpaas.api.v1.setup import auto_bootstrap_desktop
+        raw = auto_bootstrap_desktop()
+        assert raw is not None, "expected fresh bootstrap to return a key"
+        assert raw.startswith("ap_")
+
+        # Verify tenant_id format
+        rows = db.fetchall("SELECT id, name FROM tenants")
+        assert len(rows) == 1
+        assert rows[0]["id"].startswith("tn_local_"), rows[0]["id"]
+        # Q11: contextual alias is set
+        assert "/" in rows[0]["name"] or rows[0]["name"] == "local"
+    finally:
+        setup_mod.CONFIG_FILE = original_cfg
+
+
+def test_auto_bootstrap_is_idempotent(db, mode, tmp_path):
+    """Calling twice yields a tenant the second time too (no duplicate),
+    and returns None on the second call (= already configured)."""
+    settings.deployment_mode = "desktop"
+
+    from agentpaas.api.v1 import setup as setup_mod
+    original_cfg = setup_mod.CONFIG_FILE
+    setup_mod.CONFIG_FILE = str(tmp_path / "config.json")
+    try:
+        from agentpaas.api.v1.setup import auto_bootstrap_desktop
+        first = auto_bootstrap_desktop()
+        second = auto_bootstrap_desktop()
+        assert first is not None
+        assert second is None, "second call should be a no-op"
+
+        # Exactly one tenant — bootstrap did not create a duplicate.
+        rows = db.fetchall("SELECT id FROM tenants")
+        assert len(rows) == 1
+    finally:
+        setup_mod.CONFIG_FILE = original_cfg
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Q10 — mode-transition smoke test
+# ─────────────────────────────────────────────────────────────────────────────
+
+def test_mode_transition_desktop_to_lab_to_paas(client, db, mode):
+    """Q10 headline assertion: a tenant + API key + agent created in
+    desktop mode still work after the operator flips to lab and then
+    paas. The whole rev.2 strategy depends on this — if data doesn't
+    carry across mode changes, we'd need a real migration tool and the
+    "200 LOC" engineering claim falls apart.
+
+    We don't restart the test app; the mode flag is module-level and we
+    flip it mid-test. That's functionally equivalent to a process
+    restart because (a) no in-memory state encodes the mode and (b)
+    every request reads settings.deployment_mode fresh."""
+    # ── In desktop mode, bootstrap a tenant + admin key ──
+    settings.deployment_mode = "desktop"
+    tid, key = _bootstrap(db)
+
+    # Create an agent via the public API (verifies the auth + scoping path).
+    # `config` is required by CreateAgentRequest; minimal react skeleton.
+    r = client.post(
+        "/api/v1/agents",
+        json={
+            "name": "transition-test",
+            "description": "Q10 smoke",
+            "config": {
+                "type": "react",
+                "name": "transition-test",
+                "systemPrompt": "Q10 mode-transition smoke test",
+                "model": {"provider": "stub", "name": "stub"},
+            },
+        },
+        headers=_auth(key),
+    )
+    assert r.status_code in (200, 201), r.text[:200]
+    agent = r.json()
+    aid = agent.get("id") or agent.get("agent_id")
+    assert aid
+
+    # ── Flip to lab. Same key must continue to work; admin route now reachable. ──
+    settings.deployment_mode = "lab"
+    r = client.get(f"/api/v1/agents/{aid}", headers=_auth(key))
+    assert r.status_code == 200, r.text[:200]
+
+    # In lab, the previously-blocked /admin is reachable. Without auth
+    # we get 401 (route exists, auth missing) — not 404.
+    r = client.post("/api/v1/admin/tenants", json={})
+    assert r.status_code == 401, (
+        f"lab: expected 401 from auth, got {r.status_code}: {r.text[:120]}"
+    )
+
+    # ── Flip to paas. Same data, all routes still expose. ──
+    settings.deployment_mode = "paas"
+    r = client.get(f"/api/v1/agents/{aid}", headers=_auth(key))
+    assert r.status_code == 200
+
+    # ── Flip back to desktop. Admin route is hidden again, but the
+    # bootstrapped agent is still listable. ──
+    settings.deployment_mode = "desktop"
+    r = client.get(f"/api/v1/agents/{aid}", headers=_auth(key))
+    assert r.status_code == 200
+
+    r = client.post("/api/v1/admin/tenants", json={}, headers=_auth(key))
+    assert r.status_code == 404  # gate fires again