OpenWork · 第 3 章 Server 核心:HTTP 中枢与路由引擎

OpenWork · 第 3 章 Server 核心:HTTP 中枢与路由引擎

章节摘要:在第 2 章的三进程模型里,服务端(Server)是那个「唯一中枢」——它承担整个产品的文件系统管理、能力资源增删改查、对底层引擎的反向代理、运行时配置注入。让人意外的是,这个中枢不用任何 Web 框架(没有那些流行的后端框架),而是用一套自研的极简 HTTP 路由——把路径里的 :param 编译成正则来匹配。本章要讲清这套自研路由的工作原理,以及服务端的四件核心工作:路由匹配与分发、能力声明(buildCapabilities,告诉客户端「我能做什么」的契约)、对底层引擎的透明反向代理(剥除敏感头、注入工作区凭据)、静态 UI 兜底与跨域处理。这里最值得讲的工程点是:为什么不用框架? 因为这种「极简 + 正则编译」的路由足够透明、足够好教、也足够快——它是理解整个服务端如何用很少代码做很多事的关键。读完本章,你能解释一次 HTTP 请求在服务端里如何被匹配、鉴权、分发或代理。

学习目标

阅读完本章,你应当能够:

1. 描述自研路由匹配引擎:如何把 :param 编译成正则,如何匹配与提取参数,为什么不用框架。
2. 解释能力声明(buildCapabilities)契约:服务端如何告诉客户端「我能做什么」(技能/插件/MCP/命令/配置的读写、审批模式、沙箱后端、令牌作用域等)。
3. 讲清对底层引擎的反向代理:服务端如何透明地把 /引擎/* 路径代理到工作区配置的引擎,剥除敏感头、注入工作区凭据。
4. 说明静态 UI 兜底与跨域(CORS):未命中路由时如何兜底服务静态 UI,CORS 如何统一处理。
5. 评价「不用框架」的取舍:它换来了什么(透明、轻量、好教),代价是什么(要自己维护中间件)。

核心概念速览

一句话总结:服务端用一个「正则编译式路由 + 四档鉴权 + 引擎反代 + 静态兜底」的极简组合承担整个产品中枢——不用框架不是因为它简单,而是因为这套组合足够透明、足够可控,每一步都能讲清楚。

子章节导航

01 正则编译式路由匹配引擎

讲自研路由的核心::param 如何被编译成正则,如何匹配路径并提取参数,路由如何按模块组织(核心、文件、操作、会话、工作区等)。重点说明「为什么不用框架」的工程理由——透明、轻量、好教。

02 能力声明(buildCapabilities)契约

讲服务端如何声明自己能做什么:技能/插件/MCP/命令/配置的读写、审批模式、沙箱后端、令牌作用域、文件收发、浏览器 provider。重点说明这是客户端发现服务端能力的契约——客户端据此决定 UI 与行为。

03 引擎反向代理与头清理

本章硬核之一。讲服务端如何透明地把 /引擎/* 路径代理到工作区配置的引擎 baseUrl:剥除授权与主机头、注入工作区自己的引擎凭据与目录标识、清理逐跳头。重点说明这种「透明反代」让引擎感觉不到中间层的存在。

04 静态 UI 兜底与跨域处理

讲未命中路由时如何兜底服务静态 UI(让服务端也能独立托管前端),以及 CORS 如何统一处理(预检与实际响应)。这一节解释了服务端如何在「纯 API」之外还能做静态托管。

子章节之间的逻辑关系

本章遵循「匹配 → 声明 → 代理 → 兜底」的服务端请求处理路径:

路由匹配 (01)  ──请求如何被分发
   │
   ▼
能力声明 (02)  ──服务端如何自述能力
   │
   ▼
引擎反代 (03)  ──引擎请求如何被代理
   │
   ▼
静态兜底 (04)  ──未命中如何处理
   │
   ▼
第 4 章:分发前后,鉴权如何介入
​

四节正好是一条请求在服务端里的完整旅程:进来(匹配)、自述(能力)、转发(代理)、兜底(静态)。理解了这四节,你就能解释任何一次 HTTP 请求在服务端里的命运。

前置知识与后续延伸

前置知识:

• 第 2 章三进程模型(理解服务端在中枢位置)
• 对 HTTP 路由、反向代理、CORS 的基本概念
• 正则表达式的基础知识

本章为后续章节奠定的基础:

• 路由匹配是第 4 章鉴权介入点的前提
• 引擎反代是第 5 章引擎托管与配置注入的运行基础
• 能力声明为第 6 章能力体系(服务端能管哪些能力)铺垫