hunjing/backend/app/api/v1/endpoints/sandbox_files.py

"""沙箱文件预览 API。

通过此端点，前端可以读取沙箱中由工具写入的文件内容，实现源码/渲染双模式预览。

使用场景：
- write_file 写入 HTML 文件 → 前端 iframe 渲染预览
- write_file 写入 SVG → 前端 img 展示
- shell 生成图片/文档 → 前端按 MIME 类型渲染
- 任何工具的 stdout 生成的文件

安全约束：
- 用户必须经过 JWT 鉴权
- 路径由沙箱端校验（防逃逸）
- 可选 run_id/character_id 绑定授权上下文
"""

from __future__ import annotations

import base64
import mimetypes

from fastapi import APIRouter, Depends, HTTPException, Query
from starlette.responses import Response

from app.api.v1.deps import get_current_user, get_sandbox_client
from app.domains.baigong import files as baigong_files
from app.integrations.sandbox.client import SandboxClient
from app.integrations.sandbox.exceptions import SandboxError, SandboxNotFound
from app.schemas.auth import CurrentUser

router = APIRouter(prefix="/sandbox", tags=["sandbox"])


@router.get("/file")
async def read_sandbox_file(
    path: str = Query(
        ...,
        description="文件路径。isolated=True 时视为工作区相对路径"
        "（如 write_file 传入的 ``path`` 参数）；"
        "isolated=False 时作为沙箱 base 下的完整相对路径。",
    ),
    run_id: str | None = Query(
        None,
        description="关联的 run_id（可选，写入授权上下文）。仅用于审计链路，不影响文件可读性。",
    ),
    character_id: str | None = Query(
        None,
        description="人物 ID。提供时自动构造隔离工作区路径"
        "（``workspace/<character_id>/<path>``），"
        "与 write_file/shell 等工具的 isolated_workspace 路径一致。",
    ),
    isolated: bool = Query(
        True,
        description="是否自动按 isolated_workspace 规则补全路径前缀。"
        "write_file 写入的文件在 workspace/<character_id>/ 下，"
        "传递 write_file 的 path 时保持 True 即可。",
    ),
    sandbox: SandboxClient = Depends(get_sandbox_client),
    _current_user: CurrentUser = Depends(get_current_user),
) -> Response:
    """读取沙箱内文件，以原始字节返回（MIME 类型由路径扩展名推导）。

    前端根据 MIME 类型自行决定展示方式：
    - ``text/html`` → iframe sandbox 渲染预览
    - ``image/*`` → img 标签展示
    - ``text/*`` → 源码高亮
    - ``application/pdf`` → PDF 内嵌展示
    - 其他 → 下载

    路径安全：沙箱端会对路径做 canonicalize + starts_with(base) 校验，
    防止目录穿越到沙箱 base 之外。
    """
    # 1) 推导 MIME 类型
    mime_type, _ = mimetypes.guess_type(path)
    if mime_type is None:
        mime_type = "application/octet-stream"

    # 2) 从沙箱读取
    try:
        result = await baigong_files.read_sandbox_file(
            sandbox,
            path,
            run_id=run_id,
            character_id=character_id,
            isolated=isolated,
        )
    except SandboxNotFound:
        raise HTTPException(
            status_code=404,
            detail={"error": {"code": "file_not_found", "message": f"文件不存在: {path}"}},
        ) from None
    except SandboxError as exc:
        raise HTTPException(
            status_code=502,
            detail={
                "error": {
                    "code": "sandbox_error",
                    "message": f"沙箱文件读取失败: {exc}",
                }
            },
        ) from None

    # 3) base64url-no-pad → raw bytes
    pad_len = -len(result.content_b64) % 4
    content = base64.urlsafe_b64decode(result.content_b64 + "=" * pad_len)

    return Response(content=content, media_type=mime_type)


@router.get("/files")
async def list_sandbox_files(
    path: str = Query(
        ".",
        description="目录路径。默认工作区根。",
    ),
    run_id: str | None = Query(None, description="关联的 run_id（可选）"),
    character_id: str | None = Query(
        None,
        description="人物 ID。提供时自动应用 isolated_workspace 隔离前缀。",
    ),
    isolated: bool = Query(True, description="是否自动补全隔离前缀"),
    sandbox: SandboxClient = Depends(get_sandbox_client),
    _current_user: CurrentUser = Depends(get_current_user),
) -> list[dict[str, object]]:
    """列出沙箱工作区目录内容。

    返回有序列表，每个条目含 ``name`` / ``kind``（``"file"`` | ``"dir"``）/ ``size``。
    适用于前端文件浏览器导航。
    """
    try:
        entries = await baigong_files.list_sandbox_dir(
            sandbox,
            path,
            run_id=run_id,
            character_id=character_id,
            isolated=isolated,
        )
    except SandboxNotFound:
        raise HTTPException(
            status_code=404,
            detail={"error": {"code": "dir_not_found", "message": f"目录不存在: {path}"}},
        ) from None
    except SandboxError as exc:
        raise HTTPException(
            status_code=502,
            detail={
                "error": {
                    "code": "sandbox_error",
                    "message": f"沙箱目录读取失败: {exc}",
                }
            },
        ) from None

    return [{"name": e.name, "kind": e.kind, "size": e.size} for e in entries]