API 参考

契约符号

宿主在 TCC 编译产物中按符号名查找回调（xsbase.h），全部可选导出。符号名即协议 —— 没有注册函数、没有基类。

RequestProc 返回三态：XS_OK（已响应，继续 keep-alive）/ XS_FALLBACK（落入静态层或 404）/ XS_TAKEOVER（应用接管连接）。语义详见指南 · 脚本契约。逐条参考（签名/时机/线程/范例）→

XServer 层 API（23 个）

进程内直连：宿主单进程实现，脚本经 tcc_add_symbol 按地址解析，无导出修饰。其余一切能力皆为 xrt 或扩展符号。逐条参考（签名/所有权/范例）→

拓扑查询

热重载

定时器 · 部署 · 交接

xrt 运行时（3,030 符号按域索引）

脚本对 xrt 是全量可见的：91 个模块的公共 API 经符号表按地址直调，与宿主自身调用零差别。常用域速查（完整原型见 VFS 内置的 /xs/xrt_decl.h；卡片直链 xrt 官网 API 参考，或看本站逐域索引页）：

域计数含前缀家族聚合（如 xrtTcp 并入网络核心），未列小域（Time / Atomic / Math / Random / Html / Codec …）合计补足 3,030。

扩展 · sqlite（272 符号）

构建变体 build.bat sqlite 编入。完整 SQLite 引擎静态链接进宿主，脚本侧 #include <sqlite3.h>（VFS 提供），FULLMUTEX 模式适配多 worker。逐族参考（连接/语句五步/事务）→

/* demo-single/modules/database.h 的真实用法 */
iResult = sqlite3_open_v2(sDBFile, &G_DB,
    SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, NULL);
(void)sqlite3_exec(G_DB, "CREATE TABLE IF NOT EXISTS ...", NULL, NULL, NULL);

sqlite3_prepare_v2(G_DB, sSQL, -1, & pStatement, NULL);   /* prepared statement */
sqlite3_bind_text(pStatement, 1, sName, -1, SQLITE_TRANSIENT);
sqlite3_step(pStatement);
sqlite3_finalize(pStatement);

导出面为 SQLite 原生 API 全集（open/exec/prepare/step/bind/finalize/backup/…，共 272 符号）——五族分组与语句五步详解见sqlite 参考页；完整实战在第 32 章。

扩展 · xtp2（13 函数）

构建变体 build.bat xtp 编入。有序字节流上的二进制应用层协议帧库：32 字节头、REQUEST / RESPONSE / PUSH / EVENT 四型、流式增量解析、完整 limits 体系。libFuzzer 验证往返一致性与流式状态机。

xtp2_processor* pRx;
if ( xtp2_create(NULL, &pRx) != XTP2_OK ) { ... }

/* 每个 TCP / TLS 明文读循环内： */
while ( iSize ) {
    size_t iUsed;
    xtp2_message tMsg;
    xtp2_result r = xtp2_feed(pRx, pBytes, iSize, &iUsed, &tMsg);
    pBytes += iUsed; iSize -= iUsed;
    if ( r < 0 ) break;              /* 粘性错误 */
    if ( r == XTP2_MESSAGE ) { ... }  /* 用毕/拷贝 tMsg 再继续 feed */
    if ( r == XTP2_MORE ) break;        /* 数据不足，等下一轮 */
}
/* 读到 EOF 时 xtp2_finish(pRx) 检查半包，然后 xtp2_destroy */

扩展 · xllm（68 函数）

构建变体 build.bat xllm 编入。大模型服务调用核心库（vendored 自 xrt extlibs，v3.0.0 核心层）：一次调用、一套 API、三种服务商线上方言（Chat Completions / OpenAI Responses / Anthropic Messages）。网络、TLS、JSON 与取消等运行时依赖全部由宿主内建的全量 xrt 提供，脚本只需 #include <xllm.h>。

xllm_client_config tConf;
xllm_client* pClient;
xllm_request tReq;
xllm_response* pResp = NULL;
xllm_error tErr;

xllmClientConfigInit(&tConf);
tConf.sBaseUrl   = "https://open.bigmodel.cn/api/paas/v4";
tConf.sApiKey    = sKey;                    /* 借用指针，库不复制 */
tConf.sModel     = "glm-5.2";
tConf.eProvider  = XLLM_PROVIDER_GLM;
pClient = xllmClientCreate(&tConf, &tErr);  /* 引擎缺省自持 */

xllmRequestInit(&tReq);
xllmRequestAddTextMessage(&tReq, XLLM_ROLE_USER, "用一句话介绍 XServer");
if ( xllmClientComplete(pClient, &tReq, NULL, &pResp, &tErr) == XLLM_RESULT_OK ) {
    /* 读文本块 / finish 原因 / 用量，然后 xllmResponseDestroy(pResp) */
}
xllmRequestUnit(&tReq);
xllmClientDestroy(pClient);

扩展 · 邮件全家（283 函数）

构建变体 build.bat xsmtp（或 xpop3 / ximap，自动携带 xmail）编入。xmail 是 MIME 基础层：编解码（QP/Base64）、字符集、地址与日期解析、参数与多部分、消息树、构造器与线上格式；三个协议客户端共享其传输与 SASL 实现，TLS 由宿主 xrt 提供。脚本 #include <xsmtp.h> 即拉通全部声明。

扩展 · md4c（2 函数）

构建变体 build.bat md4c 编入。CommonMark Markdown 解析与 HTML 渲染：md_parse 是回调式事件流（块与 span 的进出与文本），md_html 在其上实现一步渲染；表格、删除线、任务列表等经 flag 开启。头自包含、无链接依赖。注意回调指针无空保护——直接驱动 md_parse 必须提供完整回调结构，或改用自带回调的 md_html。

void sink(const MD_CHAR* p, MD_SIZE n, void* u) { buf_append(u, p, n); }
md_html(sMarkdown, iLen, sink, &tBuf, MD_DIALECT_GFM, 0);

扩展 · xacme（20 函数）

构建变体 build.bat xacme 编入。ACME（RFC 8555）证书签发客户端：账户注册、订单、dns-01 挑战与证书获取一站式（xacmeClientIssue）；xacmeClientIssueStored 组合磁盘存储实现"剩余寿命不足才续签"。内建阿里云 DNS provider，宿主可自填 provider 结构接入任意厂商；自带同步 HTTPS 传输与 TXT 传播探测，仅依赖宿主 xrt。

扩展 · qrcodegen（10 函数）

构建变体 build.bat qrcodegen 编入。QR 码生成器（Nayuki，MIT）+ xserver 侧 PNG 输出层：上游 9 个函数（编码三入口 Text/Binary/Segments、数字/字母数字模式探测、缓冲计算、模块矩阵读取 getSize/getModule），加上 qrcodegen_png 一步输出 1-bit 灰度 PNG（IDAT 经 xrt zlib 流压缩，CRC32 本地实现）。典型用途：2FA provisioning（otpauth:// URI 转 QR）、支付/收款码动态生成、GET /qr?text=... API 端点、邮件内嵌二维码（配合 xsmtp）。

扩展 · xjwt（24 函数）

构建变体 build.bat xjwt 编入。JWT (RFC 7519) / JWS (RFC 7515) 签发与验证：HS256/384/512、RS256/384/512（PKCS#8/PKCS#1 双封装私钥）、ES256（DER 编码，与 OpenSSL 双向互认）三族算法；JWKS (RFC 7517) 按 kid 严格匹配选钥；公钥缓存三件套供高频验证。claims 以 xvalue* 承载（脚本层零桥接），错误码 xjwtLastError() 一行读取，aud 支持字符串与数组。历经四轮审计（含 OpenSSL 互操作、fuzz、稳态零泄漏实测）。

扩展 · xoauth2（25 函数）

构建变体 build.bat xoauth2 编入。OAuth 2.0 (RFC 6749) 客户端：授权码流程 + PKCE (RFC 7636) + token 刷新 + 五家 provider 预设（GitHub/Google/WeChat/Microsoft/Custom）；OIDC 辅助（nonce 一次性焚毁、HttpGet 拉 JWKS、GetUserInfo）。传输经 xoauth2httpproc 回调注入（mock 可离线测试全流程），附 xrt net/tls/http1 便捷实现（含堆版 Create/Destroy，脚本层正路）。错误四级分级可直接映射 HTTP 语义。与 xjwt 数据耦合零依赖——OIDC 登录在脚本层 8 行胶水组合，无需 requires。

扩展 · xwork（42 函数）

构建变体 build.bat xwork 编入（自动携带 xllm + xllm-session 依赖链）。AI 应用栈顶石（v2.3.1）：Agent 编排、工具注册与执行（含内建读写集）、工作区策略（read 标记/目录回退/预算接线）、子 Agent 类型系统、任务通知流与压缩调度。仓库 release/agent-demo/ 是四库组合（xwork + xllm + xllm-session + 站点 VFS）的全栈实战——浏览器端审批闸门与执行轨迹验收通过。

扩展 · webview（2 函数）+ app 节点

构建变体 build.bat webview 编入。桌面窗口扩展（WebView2 后端，零运行时 DLL，二进制增量 ~296 KB）：脚本侧仅 2 个可用性探测 API（Available / Version）；窗口控制由 class: "app" 服务节点持有——启动加载窗 → 服务就绪自动开界面 → 关窗优雅停机；无环境自动 headless。与单文件发布（xs pack）组合 = 双击即用的单 exe 桌面应用。

VFS 内置资源

脚本编译所需的一切都在二进制内（LZMA 压缩，all 变体 350 项资源）—— 目标机不需要任何头文件或库：

VFS 资源构成与变体差异详见VFS 参考页。Windows 下 msvcrt 与 kernel32 在内存编译模式中自动挂载；上表 7 个系统库由宿主显式导出 —— 进程、COM、Socket、Shell 等 Win32 API 在脚本中直接可用。sqlite3.h / xtp2.h 仅在对应变体中编入。