豫言操作系统公共接口

状态：源级接口草案 0.1。这里是仓库根目录下的独立规范树，仅含接口包、纯声明和规范文字；浏览器、CF Worker、V8/Node.js 与裸机实现均在别处。

文件与身份

每个能力组是独立的包。名称。包。豫 使用现有包语法写所有者、名称、版本与直接依赖；接口文件使用豫言现有类型声明及函数签名，不写函数体、C调用 或宿主私有对象。名称。接口。豫 中的函数由宿主提供，名称。应用接口。豫 中的函数由应用提供，方向直接由后缀确定。包身份为所有者／名称／完整版本。应用依赖的每个接口包及其传递依赖均为必需；宿主缺少对应实现时构建或装载失败。接口实现与本次运行的资源授权须分别检查。

本目录根的 豫言操作系统接口。包。豫 是全部接口包的父包，说明文件就是本总纲。它用「包含包」按下文“首批能力组”表格的顺序登记每个接口包，各接口包用「包含在」指回本包（规则见[包系统](../应用/豫构/包系统.汉语.md)“层级包”一节）。父包不含模块，用于按层级发现接口。应用直接依赖所需的接口包：依赖父包等于依赖全部接口包，每个接口都会成为必需能力。新增接口包时，在表格与父包「包含包」的相同位置登记，并在新包写「包含在」。接口包描述参与接口清单摘要，改动后须重生成各适配的 宿主提供.json 与节点宿主的 启动接口.json。

接口模块的逻辑名称去掉 。接口。豫 后缀。现有普通豫言模块解析器只把 名称。豫 当模块文件，而且普通源码要求函数签名后紧跟定义；所以这些纯声明文件仍是规范输入，不能直接当普通程序编译。yy豫言操作系统绑定 已能对单模块宿主接口核对规范和实现，在临时构建目录用接口身份生成可编译绑定包；官网首页与 Worker 已通过该步骤编译同一接口名。yy豫言操作系统装载包 及浏览器、云工入口已核对格式 4 的应用要求与独立宿主清单。多模块绑定、应用提供接口和编译器直接解析纯接口文件仍待完成；当前 Wasm 通用宿主导入也不能证明逐函数连通。规范树不加入空实现。

首批能力组

| 包 | 语义范围 | 首批目标 | | --- | --- | --- | | 豫言操作系统基础 | 系统错误、诊断、单调时钟 | 浏览器、CF Worker、Node.js | | 豫言操作系统文件 | 被授予目录内的文件读写 | 具备并获授文件能力的目标 | | 豫言操作系统网络 | 整体 HTTP 请求与响应 | 具备并获授出站网络能力的目标 | | 豫言操作系统显示 | 可见画面及输入事件 | 有显示面的目标 | | 豫言操作系统启动 | 应用提供的通用启动入口 | 浏览器、Node.js | | 豫言操作系统网页服务 | 应用提供的入站 HTTP 入口 | CF Worker、Node.js 服务 | | 豫言操作系统网页入站 | 当前请求的方法、路径、标头（含存在性与合法名校验）、查询参数、有限字节/严格文字/JSON 正文、事件种类（含 queue、scheduled）与同源 URL 改写，带字节上限的 JSON 正文读取（宿主校验并规范化，失败以状态返回，0.8.0） | CF Worker、具备同义入站请求的宿主 | | 豫言操作系统网页界面 | 已有元素的文字与受限属性、界面事件，控件读回、焦点、光标、滚动、模态框与页面状态，属性读回与移除、程序性点击、位置与矩形（0.3.0） | 浏览器及能提供同义页面的宿主 | | 豫言操作系统网页文树 | 受限节点创建与一次建树、组合与句柄释放、查询参数、同源文字资源、iframe 地址与模板装入，选择器查询、节点读回、子树导出、替换与受限超文本（0.3.0） | 浏览器及能提供同义文树的宿主 | | 豫言操作系统网页消息 | 当前文档带 JSON 详情的应用消息，并入统一事件队列 | 浏览器及能提供同义事件队列的宿主 | | 豫言操作系统网页事件 | 统一事件队列与等待点（界面、消息、定时、事件流、请求、编译、可见性、联机、历史、关闭）、界面事件订阅（委托、操作键、同步键规则、选择器与排除选择器过滤、目标属性与矩形载荷）、每类型背压与丢弃计数 | 浏览器及能提供同义事件队列的宿主 | | 豫言操作系统网页定时 | 一次与周期定时、取消；到期事件进入统一事件队列（周期不积压、取消后保证不再收到该号事件） | 浏览器及能提供同义事件队列的宿主 | | 豫言操作系统网页储存 | 会话与本地两个区域的键值文字读、写、删；配额与禁用等失败以返回值表示 | 浏览器 | | 豫言操作系统网页导航 | 前往与替换网址（http/https）、重载、同源历史压入与替换、按步移动 | 浏览器 | | 豫言操作系统网页环境 | 本地时区偏移分钟（东为正）与当前页面可见的饼（只读） | 浏览器 | | 豫言操作系统网页请求 | 同源非阻塞请求：请求 JSON、完成／失败事件进入统一事件队列、取消保证、并发 32、正文严格 UTF-8 与上限；另附阻塞变体 | 浏览器 | | 豫言操作系统网页事件源 | 同源 SSE 客户端：自动重连并带 Last-Event-ID、事件成批进入统一事件队列、宿主按队列余量控速而不丢事件 | 浏览器 | | 豫言操作系统网页编译 | 浏览器里本地编译一组豫言源文件：能力检查、启动、停止，成批进度与完成事件 | 浏览器（JSPI、Worker） | | 豫言操作系统网页应用 | 启动同源的另一个豫言浏览器应用并等它就绪（路径规则、每页 8 个、随父应用关闭） | 浏览器 | | 豫言操作系统剪贴板 | 授权后写入用户剪贴板纯文本 | 有剪贴板写入能力且获授权的宿主 | | 豫言操作系统网址 | UTF-8 网址成分严格编解码 | 浏览器、Node.js、CF Worker、原生 | | 豫言操作系统网页转发 | 同源改址、授权服务与 Assets 原流转发、筛标头转发、静态资源答复，拒绝点段路径 | CF Worker、具备同义服务绑定的宿主 | | 豫言操作系统关系查询 | 授权关系库预备 SQL 首行的 JSON 文字及文字参数绑定 | CF Worker D1、具备同义关系库的宿主 | | 豫言操作系统关系数据库 | 授权关系库的带类型参数语句、多行读取、执行结果与原子批量写入 | CF Worker D1、具备同义关系库的宿主 | | 豫言操作系统网页答复 | 当前入站请求的带标头 JSON（宿主校验）、文字、字节、空正文、多个 Set-Cookie 与改址答复 | CF Worker、具备同义入站响应的宿主 | | 豫言操作系统服务状态 | 向授权内部服务发 GET，仅读取状态码；服务绑定缺失或调用失败抛可捕获异常 | CF Worker、具备同义服务绑定的宿主 | | 豫言操作系统环境文字 | 按资源许可读取环境配置文字，并判断已授权绑定是否存在 | CF Worker、Node.js、原生及获授权宿主 | | 豫言操作系统时间 | 同刻读取 UTC 日与 Unix 分钟、Unix 毫秒及 ISO 文字转换 | 具备墙上时钟的宿主 | | 豫言操作系统持久事务 | 授权持久仓的原子键值事务（0.2.0 增事务内删除、列举、回滚，及事务外直接读写、列举、清空） | CF Worker Durable Object、具备同义事务仓的宿主 | | 豫言操作系统持久告警 | 当前持久对象唯一告警的读取、设置、删除与重试次数 | CF Worker Durable Object、具备同义告警的宿主 | | 豫言操作系统持久独占 | 并发独占区：区内可等待外部输入输出，其他事件排队，失败不重置对象 | CF Worker Durable Object、具备同义并发独占的宿主 | | 豫言操作系统秘密文字 | 按资源许可读取 Secret 并区分缺失与空值 | CF Worker、具备同义密钥仓的宿主 | | 豫言操作系统网页上游 | 授权与公网 HTTPS 上游请求、文字块增量读取、有限整读、取消及入站原流回应 | CF Worker、具备同义出入站网页能力的宿主 | | 豫言操作系统网址定位 | 按 URL 标准解析绝对与相对地址的部件（64 KiB 上限，可捕获失败） | 浏览器、CF Worker、Node.js 及具备 URL 实现的宿主 | | 豫言操作系统网址查询 | 表单编码查询串、解析表单键值（至多 1024 项）、设置网址查询参数 | CF Worker、具备 URLSearchParams 的宿主 | | 豫言操作系统命名持久服务 | 向获授权命名持久对象（对象名可含「/」，0.3.0）发有限文字或流式请求、增量读取、作最终响应并转发入站请求 | CF Worker Durable Object、具备同义命名服务的宿主 | | 豫言操作系统授权服务 | 向获授权内部服务发白名单或带正文请求、增量读取流式响应并保留原始响应流；服务绑定缺失或调用失败抛可捕获异常 | CF Worker、具备同义内部服务绑定的宿主 | | 豫言操作系统密码摘要 | UTF-8 文字与任意字节的 SHA-256 小写十六进制摘要，及尽力恒时的文字比较 | 浏览器、CF Worker、Node.js、原生 | | 豫言操作系统对象存储 | 授权 R2 桶的元数据、严格 UTF-8 文字读取（至多 2 MiB）与字节读取（至多 16 MiB）、带条件与 SHA-256 校验的写入、删除、列举，及对象正文流直通入站响应 | CF Worker R2、具备同义对象存储的宿主 | | 豫言操作系统压缩 | raw deflate 限量解压与原生 CRC-32/大小校验的 ZIP 条目解压 | CF Worker、具备同义原生解压流的宿主 | | 豫言操作系统口令派生 | 口令与盐的 PBKDF2-HMAC-SHA-256 小写十六进制派生 | CF Worker、具备同义原生密钥派生的宿主 | | 豫言操作系统随机数 | 密码学安全随机十六进制文字与 UUID v4 | 浏览器、CF Worker、Node.js、原生 | | 豫言操作系统消息队列 | 授权队列的单条与批量 JSON 投递；队列事件里读取批次、逐条确认与延后重试 | CF Worker Queues、具备同义队列的宿主 | | 豫言操作系统定时事件 | 定时事件里读取 cron 表达式与计划时刻（Unix 毫秒） | CF Worker 定时触发、具备同义定时器的宿主 | | 豫言操作系统邮件发送 | 经授权邮件绑定寄出单个收件人的纯文字邮件，校验注入与长度，成败以返回值表示且原因不含地址 | CF Worker Send Email、具备同义邮件服务的宿主 | | 豫言操作系统文字规整 | 与 ECMAScript trim、toLowerCase、length 逐字符相同的去首尾空白、完整 Unicode 转小写与 UTF-16 长度，以及“全为 Unicode 字母或数字”判断（等同 /^[\p{L}\p{N}]+$/u，0.2.0） | 能提供 ECMAScript 字符串语义的宿主 | | 豫言操作系统日志 | 错误、警告、信息三级单条日志，超过 8 KiB 截断 | CF Worker、Node.js、浏览器、原生 | | 豫言操作系统网页事件流 | 立即提交事件流响应头，逐块写入 UTF-8 文字（受背压），感知客户端断开，正常或异常终止 | CF Worker（含 Durable Object）、具备同义流式响应的宿主 | | 豫言操作系统持久频道 | 同一持久对象实例内跨事件的具名文字频道：订阅、保序发布、限时等待、关闭、订阅数 | CF Worker Durable Object、具备同义实例内共享状态的宿主 | | 豫言操作系统隔离运行 | 把已编译的文件式豫言程序放进无网络、无绑定、限 CPU 的隔离环境运行一次，取回标准输出与 /数据/、/响应/ 下的输出文件 | CF Worker Dynamic Worker Loader、具备同义隔离能力的宿主 | | 豫言操作系统编译运行 | 在宿主的隔离编译环境里把多文件豫言项目编译为 WasmGC 程序：拉取式取回阶段与编译器输出事件，再取产物字节或 Base64（可直接交给隔离运行） | CF Worker（内存文件系统里运行编译器 Wasm 与静态 Binaryen）、具备同义能力的宿主 | | 豫言操作系统平台资料 | 读取平台按名提供的只读资料集：列出键（可带前缀）与读取文字，宿主取回、解压、筛键并缓存，应用不必解析整包 JSON | CF Worker、具备同义资料集的宿主 |

GPU 计算另立 豫言操作系统图形处理器 包，作为后续规范。CPU 图像绘制属于普通豫言库；画面呈现与 GPU 计算分开，驱动只存在于宿主实现下层。CF Worker 无显示面时不实现显示包。

基础、文件、网络、显示、网页界面、网页文树、网页消息、网页事件、网页定时、网页储存、网页导航、网页环境、网页请求、网页事件源、网页编译、网页应用、剪贴板、网址、网址定位、网页转发、网页入站、关系查询、关系数据库、网页答复、服务状态、环境文字、时间、持久事务、秘密文字、网页上游、命名持久服务和授权服务包规定应用调用宿主的能力；启动和网页服务包还规定宿主调用应用的入口。启动程序 与 处理入站网页请求 是应用导出。网页服务包中的请求读取函数由宿主提供，造出站网页响应 是应用可用的纯构造器。网页入站、关系查询、网页答复、持久事务、网页上游、命名持久服务和授权服务在当前 _start 边界提供过渡调用，待类型化入口可装载时再消除重复的文字传值、临时响应柄与事件重入。各签名方向依接口文件规则逐项确定，不能仅凭 乃 推断方向。

首批可移植程序形态如下；“必需包”指该形态的应用必须声明的依赖，其余包按应用实际使用另加。

| 程序形态 | 目标宿主 | 必需包 | | --- | --- | --- | | 无界面启动程序 | 浏览器、Node.js | 基础、启动 | | 像素画面交互程序 | 有显示面的浏览器或 Node.js 适配器 | 基础、启动、显示 | | 入站 HTTP 服务 | CF Worker、Node.js 服务适配器 | 基础、网页服务 |

文件和出站网络均按实际应用依赖另加。Node.js 不因自身有终端就隐式具备显示面；CF Worker 不因可生成图像字节就实现显示包。

这些包仍是源级规范草案。完成规范不等于编译器已识别 .接口。豫，也不等于三个宿主已有符合规范的实现。GPU 的设备、缓冲区、命令与设备失效等接口尚未定稿；本版只规定显示与 GPU 是不同能力边界，不宣称 GPU 接口已完善。

共同检查

接口文件只出现导入、以 立 写的名义类型/构造器声明、以 乃 写的函数签名及双语语义注释；不得出现 者 函数定义或外调。者 仍用于普通 。包。豫 元数据。每项函数的行为、输入范围、返回值、错误、挂起与资源寿命在所属包的 规范.汉语.md、规范.文言.md 中约定。相同应用在不同宿主可以有不同二进制包装，但公开豫言签名和语义须一致。初版要求解析后的完整版本相等；现有 。包。豫 的依赖仅列包名，尚无版本锁文件，接口专用工具须记录并核对解析所得版本。

接口文件准入规则见接口文件规则，跨宿主装载、授权、挂起与资源规则见执行契约，未来共同验收见一致性样例。当前差距逐项列于未决事项。架构与研究背景另见[规范设计背景](../豫言操作系统/文档/豫言操作系统接口规范.汉语.md)。