gov-agents-portal 是 Day 01 讲的 L2.5 DevX（研发体验）层。它经历过一次明确的定位转向，值得了解——因为这解释了为什么代码里有个 _legacy_v01/ 目录：

层	选型
前端框架	Next.js 14 App Router，output: "standalone"（next.config.mjs:10，L04 会读）
UI	React + TypeScript + Tailwind CSS
数据获取	SWR（带 60s 轮询，L04 会读真实 useSWR 调用）
流式	fetch + ReadableStream 手工解 SSE（lib/sse.ts，L05 走读）
测试	Storybook、Playwright（e2e + a11y）、Vitest
后端	FastAPI + LDAP SSO + JWT，MySQL 存调用历史（portal_backend/server.py，L07 走读）
沙箱	独立包 ai-trust-toolkit-sandbox，子进程隔离跑生成的 agent（L08 走读）

侧边栏分组，每个页面（app/<route>/page.tsx）= 一个视角：

SWR 需要你给它一个 fetcher 函数——它负责"真正去发 HTTP 请求"。门户所有页面共用这一个（lib/fetcher.ts:18）：

export async function fetcher<T>(url: string): Promise<T> {
    // ① dev 态从 sessionStorage 读当前用户（AuthGuard 登录时写进去的）
    const userId =
        typeof window !== "undefined"
            ? sessionStorage.getItem("portal_user_id") || ""
            : "";                                    // SSR 时没有 window → 空

    const headers: HeadersInit = { "Content-Type": "application/json" };
    // ② 有用户就拼一个 Bearer token 塞进 Authorization 头
    if (userId) {
        headers["Authorization"] = `Bearer dev-${encodeURIComponent(userId)}`;   // fetcher.ts:28
    }

    const res = await fetch(url, { headers });       // ③ 真正发请求
    if (!res.ok) {
        // ④ 失败：先 text() 再试 JSON.parse —— 防 body 被读两次报 "already read"
        const body = await res.text();
        let info: unknown = body;
        try { info = JSON.parse(body); } catch { /* 不是 JSON 就留字符串 */ }
        throw new FetcherError(`Fetch ${url} failed: ${res.status}`, res.status, info);
    }
    return res.json() as Promise<T>;
}

逐行大白话：① 先判断 typeof window !== "undefined"——因为 Next.js 会在服务器端也执行这段代码（SSR），那时没有浏览器的 sessionStorage，硬读会崩，所以先兜一层。② 把用户 id 拼成 Bearer dev-alice 这种形状塞进 Authorization 头——这就是"每个请求都带上我是谁"的实现，就一行。③ 用浏览器原生 fetch 发出去。④ 失败时的处理藏着一个真实的坑（见下）。

fetcher 里那个 fetch("/portal/dashboard") 打的是相对路径——前端跑在 3000 端口，后端在 8080，它怎么找到后端？靠 next.config.mjs 的 rewrites 反向代理（next.config.mjs:18）：

const nextConfig = {
    reactStrictMode: true,
    output: "standalone",                    // next.config.mjs:10 · Docker 只带 server.js + 必要依赖
    transpilePackages: ["@portal/design-tokens"],   // workspace 内部包走 TS 源码
    async rewrites() {
        return [
            {   // 开发态把 /portal/* 反代到 platform server（默认 :8080）
                source: '/portal/:path*',
                destination: `${process.env.PORTAL_BACKEND_URL || 'http://localhost:8080'}/portal/:path*`,
            },
            {   source: '/v1/:path*',
                destination: `${process.env.PORTAL_BACKEND_URL || 'http://localhost:8080'}/v1/:path*`,
            },
        ];
    },
};

大白话：rewrites 让 Next.js 服务器自己把 /portal/* 的请求转发到 PORTAL_BACKEND_URL（默认 localhost:8080）。于是浏览器眼里所有请求都发给"自己这台 3000"，是同源的——没有跨端口，也就没有 CORS。output: "standalone"（:10）则是给 Day 17 Docker 部署铺路：构建产物只带一个 server.js + 必要的 node_modules 子集，镜像小。

再看 fetcher 被谁调用——真实页面 app/gates/page.tsx（page.tsx:13/36）：

const REFRESH_MS = 60_000;                          // page.tsx:13 · 60 秒轮询

const gates = useSWR<GatesMetricsResponse>(
    "/portal/gates/metrics",                        // key = 后端路径
    fetcher,                                         // 用上面那个共享 fetcher
    {
        refreshInterval: REFRESH_MS,                // 每 60s 自动重拉
        revalidateOnFocus: true,                    // 切回窗口也重拉
        keepPreviousData: true,                     // 拉新期间先展示旧数据（不闪白）
    }
);

// EventSource 仅支持 GET + 无 custom header
// 故必走 fetch + ReadableStream reader 解 SSE。

原因很硬：原生 EventSource 只能发 GET、不能带自定义请求头。但起 agent 要 POST 一个 JSON body，还要带 L03 那个 Authorization: Bearer 头——EventSource 两条都做不到。所以只能用 fetch（能 POST、能带头）拿到响应流，自己手动切分 SSE 事件块（sse.ts:39）：

const res = await fetch(url, {
    method: "POST",                              // ← EventSource 做不到
    headers,                                     // 含 Accept: text/event-stream + Authorization
    body: JSON.stringify(body),                  // ← EventSource 也做不到
});
// 非 SSE 响应（403 关闭 / 400 校验失败）→ 读 body 抛错
const ct = res.headers.get("content-type") || "";
if (!res.ok || !ct.includes("text/event-stream")) {
    const body = await res.text();               // 又是"先 text 再 parse"（同 fetcher）
    let info: unknown = body;
    try { info = JSON.parse(body); } catch { /* 保留 string */ }
    throw ...;
}

const reader = res.body?.getReader();            // sse.ts:74 · 拿到可读流
const decoder = new TextDecoder("utf-8");
let buf = "";
while (true) {
    const { done, value } = await reader.read(); // 读一个 chunk
    if (done) break;
    buf += decoder.decode(value, { stream: true });
    let idx: number;
    while ((idx = buf.indexOf("\n\n")) !== -1) {  // sse.ts:84 · 双换行 = 一个事件块结束
        const block = buf.slice(0, idx);
        buf = buf.slice(idx + 2);                 // 消费掉这一块，剩下的留在 buf
        const event = parseSSEBlock(block);       // 解析 event:/data: 两行
        if (event) onEvent(event);                // 回调给 UI（滚一行输出）
    }
}

逐块讲：网络是一段一段（chunk）到的，一个 chunk 里可能有半个事件、也可能有两个半事件。所以要维护一个缓冲区 buf，不停往里拼；SSE 协议规定两个连续换行 \n\n 表示一个事件块结束，于是循环用 buf.indexOf("\n\n") 找边界、切出完整的块交给 parseSSEBlock，剩下不完整的半块继续留在 buf 里等下一个 chunk。这就是"流式解析"的经典写法。

门户每个页面都遵循同一套健壮性模式。直接读 app/gates/page.tsx 的真实结构（page.tsx:57-96）：

const isLoading = (gates.isLoading && !gates.data) || (cost.isLoading && !cost.data);

return (
  <div>
    {/* ② mock 横幅：诚实告诉用户"这是假数据" */}
    {(gates.data?.data_source === "mock" || cost.data?.data_source === "mock") && (   // page.tsx:67
      <div className="text-amber-400 ..." data-testid="data-source-banner">
        数据源 · mock(toolkit observability / cost / quota 未接通)
      </div>
    )}

    {isLoading ? (
      <PageSkeleton />                            {/* ① 骨架屏，不白屏 */}
    ) : gates.error || cost.error ? (
      <div className="...">                        {/* ③ error 卡 + HTTP 码 + 重试 */}
        Gates / Cost 数据加载失败
        {gates.error instanceof FetcherError ? ` · gates HTTP ${gates.error.status}` : ""}
        <button onClick={() => { void gates.mutate(); void cost.mutate(); }}>重试</button>
      </div>
    ) : (
      gates.data?.metrics && Array.isArray(gates.data.metrics.per_gate_hits)
        ? <ThreeCardRow .../>                     {/* ④ partial-data 防御：字段齐才渲染 */}
        : <div>Gates metrics 不完整 · 缺 per_gate_hits</div>
    )}
  </div>
);

后端入口是 portal_backend/server.py::build_router(case_store, app)（server.py:132），它注册约 30 个 endpoint 子模块（xxx_endpoint.add_routes(router)）。最值得读的是"工程师提交一份 YAML 造 agent"的 POST /portal/agents（server.py:221）——因为它演示了后端怎么做安全校验：

@router.post("/portal/agents")
async def create_agent(body: dict = Body(...), ctx: CallContext = Depends(get_call_context)):
    # ... 先把 config_yaml 解析成 dict（yaml.safe_load，失败 → 422 INVALID_YAML）...

    # ① validate + reject secret
    try:
        from portal_backend.config_parser.schema import scan_for_secrets
        scan_for_secrets(raw)                        # server.py:252 · 扫明文密钥
        cfg = AgentConfigSchema.model_validate(raw)  # Pydantic 校验字段
    except SecretInConfigError as e:                 # server.py:254 · 发现 secret
        raise HTTPException(status_code=422,
            detail={"code": "SecretInConfigError", "message": str(e)}) from e
    except ValidationError as e:                     # 字段不合规
        raise HTTPException(status_code=422,
            detail={"code": "VALIDATION_ERROR", "errors": e.errors()}) from e

    # ② 通过才写盘：configs/business-agents/-.yaml
    out_path = _CONFIGS_DIR / f"{date_prefix}-{cfg.name}.yaml"
    out_path.write_text(yaml.safe_dump(raw, allow_unicode=True), encoding="utf-8")  # server.py:269
    return {"agent_name": f"portal/{cfg.name}", "router_path": f"/v1/agent/portal/{cfg.name}", ...}

逐步讲：① 收到 YAML 先干两件校验——scan_for_secrets 扫有没有把明文密码/API key 写进配置（写了就抛 SecretInConfigError → 422 拒绝），再用 Pydantic 的 AgentConfigSchema.model_validate 校验字段合不合规。两关都过才 ② 把 YAML 写到 configs/business-agents/ 目录（配置即代码，进 git 留痕），返回这个新 agent 的路由路径。

答案在独立包 ai-trust-toolkit-sandbox 的 subprocess_pool.py。它的文件头注释把"为什么用子进程而非 in-process import"讲得很直白（subprocess_pool.py:5-8）：

# 为什么 subprocess 而非 in-process import:
# - 崩溃 / OOM 隔离(跑挂了不拖垮 host)
# - RLIMIT_AS / RLIMIT_CPU 真生效(per-process)· pod cgroup 是全 pod 上限 · 互补
# - env 白名单 · 防 secret 漏到生成 agent 代码

三条隔离手段，全能在真代码里找到。第一：env 白名单（subprocess_pool.py:88）——不是把 host 的全部环境变量传给子进程，而是只显式列几个安全的：

def _build_subprocess_env(*, port, sandbox_id, anthropic_api_key):
    """显式白名单 · 防 secret 漏到子进程."""
    env = {"SANDBOX_PORT": str(port), "SANDBOX_ID": sandbox_id, "PYTHONUNBUFFERED": "1"}
    for key in ("PATH", "HOME", "LANG", "LC_ALL", "TZ"):     # 只放行这 5 个无害变量
        val = os.environ.get(key)
        if val is not None:
            env[key] = val
    if anthropic_api_key:                                    # LLM key 单独、显式传
        env["ANTHROPIC_API_KEY"] = anthropic_api_key
    return env

大白话：子进程拿到的环境变量是从零白名单拼出来的，host 上的数据库密码、其它服务 token 一个都不继承。唯一的 LLM key 也是调用方显式传参进来、单独塞的。第二：RLIMIT 资源限制（subprocess_pool.py:125），用 preexec_fn 在子进程启动前设上限：

def _make_preexec_fn():
    """Linux RLIMIT_AS + RLIMIT_CPU · macOS 仅 RLIMIT_CPU · Windows None."""
    if sys.platform.startswith("win"):
        return None                                          # Windows 不支持 preexec_fn
    mem_bytes = _default_mem_mb() * 1024 * 1024              # 默认 512MB（env 可调）
    cpu_sec = _default_cpu_sec()                             # 默认 60s
    is_linux = sys.platform.startswith("linux")
    def _setlimits():
        try:
            resource.setrlimit(resource.RLIMIT_CPU, (cpu_sec, cpu_sec))   # 限 CPU 时间
        except (ValueError, OSError) as e:
            print(f"[sandbox preexec] RLIMIT_CPU failed: {e}", file=sys.stderr)
        if is_linux:                                         # RLIMIT_AS 只在 Linux 开
            try:
                resource.setrlimit(resource.RLIMIT_AS, (mem_bytes, mem_bytes))  # 限内存
            except (ValueError, OSError) as e:
                print(f"[sandbox preexec] RLIMIT_AS failed: {e}", file=sys.stderr)
        with contextlib.suppress(OSError):
            os.setpgrp()                                     # 独立进程组，方便整组 kill
    return _setlimits

第三：独立子进程 + 挑空闲端口 + 等就绪（spawn_sandbox，subprocess_pool.py:175）：

port = _pick_free_port()                                     # 让 kernel 分一个空闲端口（bind 0）
env = _build_subprocess_env(port=port, sandbox_id=sandbox_id, anthropic_api_key=...)
preexec = _make_preexec_fn()
popen_kwargs = {
    "args": [sys.executable, "-m", agent_pkg],               # python -m <生成的 agent 包>
    "cwd": str(cwd), "env": env,                             # 白名单 env
    "stdout": stdout_log, "stderr": stderr_log,              # 输出写日志文件
}
if preexec is not None:
    popen_kwargs["preexec_fn"] = preexec                     # 挂上 RLIMIT
proc = subprocess.Popen(**popen_kwargs)                      # subprocess_pool.py:216 · 真正起子进程

起完还会 _wait_for_ready（:152）每 100ms poll 子进程的 /healthz，200 才算就绪，超时就 _force_kill。之后门户通过 proxy.py 的反向代理中间件（server.py:191 挂的 /portal/v1/sandbox/）把请求转发到 127.0.0.1:<port>。

一个容易困惑的点：前端真源码在一个独立 repo（gov-agents-ui），本 monorepo 里的 frontend/web/ 是它的只读镜像（mirror）。next.config.mjs:9 的注释里就留了痕迹：standalone output ... R-PORTAL-FRONTEND-DOCKER-1——前端团队用自己的 repo 迭代，但平台部署又需要前端代码在同一个镜像里构建，于是用"单向同步 + 只读镜像"折中。

Day 18 会看到有两道专门的 CI 闸守着它：ci-gate-frontend-readonly（禁止在 monorepo 里直接改镜像里的 .tsx）和 ci-gate-frontend-sync（检测两仓漂移超过 30 天就 fail）。例外白名单是 Dockerfile / next.config.mjs 这几个"平台侧持有的部署产物"。

✋ 动手：读今天走读过的真代码

# 1. 前端如何带鉴权 + 反代
cat gov-agents-portal/frontend/web/lib/fetcher.ts
sed -n '7,31p' gov-agents-portal/frontend/web/next.config.mjs

# 2. 手写 SSE 流式解析
sed -n '39,95p' gov-agents-portal/frontend/web/lib/sse.ts

# 3. 一个页面的健壮性四件套 + mock 横幅
sed -n '36,96p' gov-agents-portal/frontend/web/app/gates/page.tsx

# 4. 后端 build_router + POST /portal/agents 拒绝 secret
sed -n '132,270p' gov-agents-portal/backend/portal_backend/server.py

# 5. 今日核心：沙箱子进程三道隔离
sed -n '88,146p' packages/ai-trust-toolkit-sandbox/src/ai_trust_toolkit_sandbox/subprocess_pool.py
sed -n '175,216p' packages/ai-trust-toolkit-sandbox/src/ai_trust_toolkit_sandbox/subprocess_pool.py