xs3

xs 是 xrt 的落地化部署工具。 它把 xrt 的网络、协议、TLS、并发、数据能力装配成一个由配置文件驱动的可执行程序，并在运行时把 C 脚本编译进进程。xrt 才是主要的那个；xs 只负责部署，不提供框架、不提供治理、不教应用怎么做事。

当前状态：生产就绪——五大协议（http(+https)/ws(+wss)/tcp(+tcps)/udp/custom）、期望状态热重载（latest-wins/整代候选/原子发布/自动排空回收）、可选库门控（sqlite、xtp、xllm、xmail 系列、md4c、xacme，可组合、支持依赖自动展开与 all 全选）、dev_inc/dev_lib 应用 SDK 目录、静态层四旋钮、Windows/Linux 双平台回归与四层测试体系（冒烟/功能/压力/攻防演练 6h 704 轮 0 失败）。遗留：xadmin 试点。

• 协议：HTTP 每请求虚拟主机路由（脚本+静态根）、WS 握手期路由并固定 host/脚本、TCP/TCP+TLS、UDP、custom 手动装配
• 热重载：独立 controller、提交前 latest-wins ticket、reload-all 共享不可变配置 revision、候选 listener 先 bind 但不接入、host/server/all 均以完整 server generation 原子发布；旧代停止新接入后由终态引用自然排空，协议回调以连接记录和具体流的临时引用抵御同步 Close 重入，ServiceUnit 与最终析构交给专用 reaper，无泄漏、无宽限/超时强拆
• 可选库：build.bat all（全部可选库）/ bash build.sh sqlite xtp xllm xsmtp ...，参数可组合、可去重，邮件协议库自动携带 xmail 基础库；同一扩展清单控制原生编译、VFS 头文件和 TCC 符号导入
• 测试：test.bat / bash test.sh（正式构建、动态端口冒烟、功能边界、generation 生命周期、明文/TLS reload 矩阵与失败清理）、tools/func_test.py（配置失败清理、监听半启动回滚、虚拟主机/静态根、header/chunked 边界、静态发送中断、嵌套 TCC 并发、ticket 环碰撞）、tools/lifecycle_reload_test.py（旧 keep-alive、初始化发布屏障、拓扑 lease 与 Root 换代）、tools/reload_matrix_test.py（HTTP(S)/TCP(S)/UDP/WS(S) 同端点换代及跨服务 lease 回收）、tools/pressure_test.py、tools/drill.py；全部使用动态端口和临时配置，压力/演练进程会等待回收，重载破坏样本只操作临时脚本副本。

热换安全边界：绑定端点改变时候选可先 bind，但在拓扑事务提交前拒绝接入；同一端点由稳定 listener 槽位转交给新 generation。所有 Accept 与拓扑写锁线性化，TLS 还把 ClientHello 选中的 generation cookie 带到 Accept，reload-all 不会暴露半新半旧状态。旧连接继续持有旧代，最后一个终态引用归零后自动释放。协议类型、TLS 形态、backlog、recv_limit 等 listener 固化字段若在同端点改变会明确拒绝并要求重启。xsReloadHost* 是指定 host 的管理面入口，内部也重建并发布它所属的完整 server generation，不原地改指针；custom 因裸资源无统一终态 lease，不支持在线卸载。公开 server 查找返回显式 lease，必须 xsServerRelease。

TCC 宿主吸收了 xlang（demo6）的成熟经验并推进到单文件交付：res/tcc（VFS 构建目录）在构建期整体 LZMA 打包进二进制（SDK 头 + 精简 winapi/linux 头 + libtcc1.a + 导入库，7.3MB → 1.0MB），运行时从内置 VFS 读取——xs 不附带任何磁盘 TCC 环境。新增内置库 = 放入 res/tcc 重新构建。中文路径由 UTF-8 宽字符 IO 全链路保障。

xs 做什么

1. 五个协议入口：http / ws / tcp / udp / custom（custom 全手动）
2. xrt 环境导入 TCC（脚本直接调用 xrt API）
3. 内置编译可选的扩展库（sqlite、libtcc 等，宏门控），一并导入 TCC
4. 协议初始化能力：除 custom 外，握手、解析、分帧由 xs + xrt 完成
5. 基于配置文件提供服务（xs.json，预设字段进结构体，其余全归应用）

xs 不做什么

• 不做 bus、内置 XTP 服务驱动、管理面、调试面、任何治理；XTP2 编解码器作为可选独立库提供，连接由应用管理
• 不做 HTTP 便利封装、路由、session、权限——那是 xadmin 们的事
• 不做沙盒与权限限制——C 语言限制不住，一切对脚本开放
• 本阶段不使用 xhttp / xws（只基于已压实的 xrt http core 与 websocket core）

路线定位

xs3 是 C 语言版 xs 的完全重写，也是双轨（C 版 / xlang 版）中先行定性的技术路线：未来 xlang 版将参照 xs3 沉淀的三样东西——透传契约（回调收 xrt 原生对象）、结构体 ABI + 全开放访问、generation 生命周期——决定自己的形态。

依赖

• xrt：网络 / 协议 / TLS / 并发 / value / JSON / 模板 / 压缩（锁定版本随发）
• TCC 0.9.28rc：运行时 C 编译器（兼容性已验证，见设计文档附录）

构建与可选扩展

Windows（需要 GCC、windres、Python 3.10+）：

build.bat
build.bat sqlite
build.bat xtp
build.bat sqlite xtp
build.bat sqlite xtp xllm
build.bat all

Linux 使用相同参数，例如 bash build.sh sqlite xtp xllm xsmtp；需要 GCC 与 Python 3.10+。不传参数只包含固定的 xrt/libtcc 等基础能力。参数顺序无关、重复自动去重、名称不区分大小写，未知库名报错退出，不会悄悄生成错误变体。

build.bat --list-extensions 查看可选库；build.bat sqlite xtp --dry-run 查看实际构建命令。产物默认仍为 release/xs.exe 或 release/xs，可用 --output 指定其他位置。构建中间文件按平台和库组合隔离到 .build/，不会重写 src/script/tcc_builtin_resources.c 旧快照。

启用后，脚本直接 #include <sqlite3.h> / #include <xtp2.h> / #include <xllm.h>，无需再定义 XTP2_IMPLEMENTATION。脚本可用 XS_USE_SQLITE、XS_USE_XTP2、XS_USE_XLLM 判断当前宿主能力，嵌套 xsCreateTCC() 环境也一致。

后续库在 扩展清单 登记源码、头文件、宏和符号清单，不需要修改两个平台的构建脚本或 TCC 宿主分支。参见可选扩展库说明。

单文件发布（站点 VFS）

把 xs.json 与整个站点（wwwroot、C 源码、TLS 证书）打成一个 LZMA 归档追加到 xs 末尾，得到一个可直接部署的单文件 exe：

release\\xs.exe pack <站点目录> -o app.exe    # 站点目录须含 xs.json；基底 = 当前 xs
app.exe                                      # 无参启动：自动从包内读配置、出文件

• 压缩：逐条 LZMA（无收益自动 STORE）；xs pack --list app.exe 查看条目清单
• 磁盘优先：放同名文件到 exe 旁即覆盖包内版本（热修 CSS/证书免重打包），删除即恢复包内
• xs pack --extract app.exe -d out/ 解包取证；xs pack --strip 还原未打包二进制
• xs --no-vfs 忽略应用包强制目录模式（调试用）
• 归档探测零成本（读自身末尾 24B）；索引启动装载后不可变、内容首次访问惰性解压常驻缓存

格式与设计细节见 docs/站点VFS设计.md；端到端测试 python tools/test_site_vfs.py。

开源许可

本项目自有代码以 MIT 授权（见 LICENSE）。仓库捆绑的第三方组件各自保留原许可：

组件	位置	许可
Tiny C Compiler（mob 快照 + 本地 VFS/UTF-8 IO 修改）	tcc/	LGPL-2.1-or-later，全文见 tcc/COPYING，修改清单见 tcc/README.md
LZMA SDK（Igor Pavlov）	tcc/LzmaDec.c 等	公有领域
SQLite	lib/sqlite3.c	公有领域
MD4C（Martin Mitáš）	lib/md4c/	MIT

TCC 以静态链接编入单一二进制。按 LGPL-2.1 要求，发布二进制时须让接收方能够用修改版 TCC 重新链接出完整程序——本仓库公开全部源码与构建脚本（build.bat / build.sh），即满足该要求；修改过的 TCC 部分保持 LGPL 并随源码提供。项目自有代码与用户脚本的许可均不受 TCC 许可影响。