项目上手指南：fe-chengjiao-python-faas

##1. 项目整体与功能概述 (Overview)

项目定位：这是一个基于 Flask 框架的 Python FaaS（函数即服务）项目。主要用于提供大语言模型驱动的浏览器自动化智能体（Browser Agent）服务。

核心功能：

• 浏览器自动化执行：接收来自前端或外部系统的自然语言任务（例如"帮我搜索某个商品并截图"），大模型（Agent）会自行规划步骤，控制远程浏览器完成各种交互动作（点击、输入、导航等）。
• 隔离的 Sandbox 沙盒环境：每次任务启动独立的远程浏览器 Sandbox 环境（services/agent/sandbox.py），不仅提供 CDP (Chrome DevTools Protocol) 供 Agent 控制，还会快速返回 VNC 连接（vnc_url），供前端通过画布（Canvas）实时展示浏览器的运行录像。
• 多模型无缝切换：项目抽象了 model_config 概念，支持使用和调配不同的基座大模型（如 doubao-1.8, doubao-2.0, gemini-3-flash, kimi-k2.5 等）。
• 外插拔式的"技能中心" (Skill)：除了模型泛化的浏览器操作能力外，Agent 也可以调用被定义的离散"技能"。（在 services/skill/skills 目录下可见 .yaml 配置好的预设技能模块）

---

##2. 核心模块与目录结构明细

2.1 整体架构导览 (MindMap)

mermaid[copy]
mindmap
  root((fe-chengjiao-python-faas))
    app.py [FaaS的入口文件，拉起 Flask 实例]
    ecop_fe_ai [🍎 核心业务目录，开发主战场]
      api [接口层，定义路由与入参出参格式]
        routes.py [对外暴露 /run-agent 等接口逻辑]
      services [业务控制层，内部逻辑封装]
        agent [智能体核心域]
          run_agent.py [多进程任务流控制、状态机的中心]
          agent.py [AgentService 定义，对底层 browser_use 库的封装与调用]
          sandbox.py [通过内部基建获取远端浏览器实例的方法]
        skill [技能定义系统目录，处理如 YAML 外挂技能等]
      core [公共核心设置]
        config.py / env.py [启动参数、环境变量、鉴权等配置]
      utils [通用工具]
        sse.py [封装流式编码]
        log_bridge.py [解决多进程架构下日志重定向的机制]
    pyproject.toml / uv.lock [现代 Python 的依赖配置]

2.2 详细目录及文件作用描述

text[copy]
fe-chengjiao-python-faas/
├── 根目录核心文件
│   ├── app.py                  # 根启动入口，仅用于转发 ecop_fe_ai 内部真正的 Flask app 实例，适配 FaaS 部署寻找入口的需求。
│   ├── pyproject.toml          # 项目依赖与 Python 现代构建配置文件（uv 依赖和指令入口在这里配置）。
│   ├── uv.lock                 # uv 包管理器的锁文件，确保所有开发团队和线上执行环境使用完全一致的依赖版本。
│   ├── requirements.txt        # 兼容传统 pip 环境的依赖列表，供不支持 uv 的 FaaS 打包时回退使用。
│   ├── build.sh & run.sh       # FaaS 容器执行的构建(build)与运行(run)脚本。
│   ├── bytefaas.yml            # 字节跳动 FaaS 平台部署核心配置文件（声明运行时环境、协议、超时等）。
│   ├── .env / .env.example     # 环境变量及模板，用于存放大模型 API Key（OPENAI_API_KEY）、Base URL 等机密与环境差异配置。
│   └── README.md & PROJECT_OVERVIEW.md # 包含快速开始开发指南和本项目深度架构导览的文档。
│
├── ecop_fe_ai/                 # 🍎 核心业务目录，开发主战场
│   ├── __init__.py
│   ├── app.py                  # 实际的 Flask 应用装配入口（初始化环境变量、日志设置、CORS，以及最重要的挂载注册蓝图路由）。
│   │
│   ├── api/                    # 接口层
│   │   └── routes.py           # HTTP 路由文件，对外暴露 `/api/ecop-fe-ai/run-agent` 等 JSON 与 SSE (流式) 接口。
│   │
│   ├── core/                   # 核心配置系统
│   │   ├── config.py           # 集中管理整个应用的配置（集成环境变量及预设默认参数）。
│   │   ├── constants.py        # 全局静态常量定义。
│   │   ├── env.py              # 基于 Pydantic 的配置映射，用于强类型校验并解析 `.env` 或环境变量输入。
│   │   └── model_config.py     # 各类大模型（豆包、Gemini、Kimi 等）连接客户端及 Provider 的初始配置映射与适配层。
│   │
│   ├── services/               # 业务控制层
│   │   ├── agent/              # 智能体能力核心域
│   │   │   ├── run_agent.py    # 基于 multiprocess(spawn) 的多进程任务流控制中心，管理 Agent 异步生命周期及处理跨进程通信。
│   │   │   ├── agent.py        # 封装 browser-use 库的核心 AgentService，负责拼装模型、动作集并向外暴露最终运行能力。
│   │   │   ├── sandbox.py      # 沙盒模块，封装与基础支撑架构交互逻辑，用于每次运行前请求、保活并拉起远端的无头浏览器。
│   │   │   ├── debug.py        # 离线与在线的 Agent 调试工具（含抓取模型感知到的 DOM 日志、生成 Debug Context 以便于排查问题）。
│   │   │   ├── patches.py      # 补丁模块，内部用于对第三方库（browser-use 或 playwright）做定制化的 Hack 与覆盖修改以适配业务。
│   │   │   └── tools.py        # 注入给大模型的动作工具函数集（Action 定义），比如操作 DOM 外额外执行 Python 逻辑或其他外部任务。
│   │   │
│   │   ├── skill/              # 离散技能外挂模块
│   │   │   ├── service.py      # 读取和执行外挂技能（Skill）的业务代码。
│   │   │   ├── skills/         # 存放以 YAML 格式描述的具体技能文件配置（如判断标准、固定任务流等）。
│   │   │   └── knowledge/      # 为特定垂类技能执行提供固化知识规则的数据源（例如 FAQ 的 JSON 配置）。
│   │   │
│   │   └── tos/                # 对象存储(TOS)服务相关域
│   │       └── uploader.py     # 专门负责上传运行时验证的截图、录屏等媒体文件到 TOS 并返回 CDN URL 的上传组件类。
│   │
│   └── utils/                  # 全局通用工具集
│       ├── sse.py              # SSE 通信底层协议封装，生成器模式，将任务执行步骤实时推送给发起请求的客户端。
│       ├── log_bridge.py       # 日志桥接工具，解决多进程下子进程（跑大模型时）的标准输出丢失问题，将 stdout 路由透传到主进程或磁盘文件。
│       └── jwt.py              # JWT 验证工具包，提供面向前端请求的轻量级身份验证及 Token 解析解析功能。
│
└── tests/                      # 测试模块目录
    ├── test_config_and_sse.py  # 验证环境变量加载逻辑以及 SSE 数据推流格式规范的测试套件。
    ├── test_dynamic_model.py   # 验证大模型动态切流机制等相关模型实例化逻辑的单元测试。
    ├── test_screenshot_tools.py# 检查浏览器截图或图片处理与内部 TOS 上传交互逻辑。
    └── ...                     # 其他特定边界及功能测试用例。

---

##3. 服务端 API 与请求方式说明

(1) 健康检查与探活 (GET)

• /api/ecop-fe-ai/：返回固定文本作为主页占位符。
• /api/ecop-fe-ai/ping：存活探针接口，返回 Ping healthcheck。

(2) JSON 传统请求接口 (POST /api/ecop-fe-ai/run-agent)

适用场景：通过普通的 RESTful API 调用 Agent。

• 参数特性：
  • wait=false（异步运行）：仅负责将任务通过多进程丢到后台跑，接口立即返回 status: started，不等待其运行完毕。
  • wait=true 且 return_on_vnc=true：将一直阻塞（或由于前端超时），直到底层成功拉起 Browser Sandbox，马上将包含 vnc_url 在内的就绪信息使用 JSON 响应打回。适合前端希望尽快呈现黑屏画布并挂载画面的场景；但 Agent 剩下执行的部分是在后端的子进程中自主完成。
  • model：可指定上述的大模型进行驱动。
• 返回结果：返回标准的 JSON 对象 { "status": "ok" / "started" / "error", "vnc_url": "...", "task": "..." }。

(3) SSE 双向流式请求接口 (POST /api/ecop-fe-ai/run-agent/stream)

适用场景：实时反馈感极强的对话流或者任务流。Agent 做任意一个动作（如正在准备浏览器、正在思考、甚至后端的 Debug Log），前端都能通过 EventSource 流畅地拿到变更。

• 参数特性：通过 Body 同样传入 task 和 model。
• 响应机制 (Server-Sent Events)：
  • 这是一个持续保持 HTTP 链接不中断的通道（设置了 text/event-stream 和 Connection: keep-alive）。
  • 所有后端的 queue.put() 事件都会通过对应的 Event Type（如 status, step, ready, log）推送。
  • 前端可以在收到 ready 事件（挂载 vnc_url 视窗面板）后，继续接收 step 事件（更新"模型执行到哪一步了"等 UI 状态）。最后直到后端抛下 done 或 error 来关闭管道。

---

##4. 重点机制解析：基于 Spawn 子进程的沙盒控制调度

不论是 JSON 模式还是流式的 SSE 模式，Agent 的运行并不阻塞当前提供网络服务的 Flask 主进程工作。

原理 (参考 services/agent/run_agent.py)：

1. 每次接到任务，run_agent.py 会使用 multiprocessing.get_context("spawn") 派生一个子进程（之所以使用 Spawn 是因为在 Mac 的 Darwin 底层更为安全，且多进程更能提供强隔离防泄漏）。
2. 在子进程内会依次去请求远端的 Sandbox（取得浏览器和 CDP 端口）并发起 agent_service.run(...)。
3. 如果是 JSON (wait=false)，主进程直接返回 202 销毁当前连接上下文，子进程在操作系统层继续独立运行。
4. 如果是 SSE 模式或等待 vnc_url 的模式，主进程和子进程之间通过 miltiprocessing.Queue 管道进行密集通信（QUEUE_STATUS_* 各种常量），子进程源源不断把消息挤进去，主进程生成器把消息变成 data: 流返回给用户端浏览器。