Endorphin-Document/appendices/specification-status.md

规范状态

本附录记录语言设计的确定程度与尚未定义的边界。它用于理解设计稿，不代表软件实现进度或可执行性保证。

已确定约定

主题	已确定内容
语言定位	前后端共用的云原生编程语言，UI 是应用领域之一
资源归属	每项独立登记的资源属于一个 workspace 和至少一级 namespace；用户是操作与作者身份
Workspace 命名	workspace handle 在平台内唯一并参与 key，workspace 显示名可以重复；用户登录标识不作为资源归属前缀
namespace	各层语义一致；以外部 key 检索，不在正文声明自身归属；函数、class、agent 和独立保存的基础内容共用资源归属体系
key 形式	workspace handle:namespace路径，冒号分隔 workspace 与路径，点号分隔层级
用户与 workspace	注册时创建默认个人 workspace，创建用户成为管理员；用户可以参与多个 workspace，workspace 可以包含多个用户
授权边界	workspace 整体授权，内部 namespace、class 和函数不各自维护用户访问名单；代码可视域独立处理
角色基线	管理员与 Editor 具有 rwx，管理员另管理成员和授权；Reader 具有读取权，是否附带 x 仍待定
use	引用完整 namespace，不附加选择性名称列表
代码组织	独立代码段存储在 S3，由索引组装可见代码视图，不采用源码文件 module 制
数据结构目标	用 class 表达共享结构，通过类取得数据的具体形式另行定义
基础资源	数值、文本、图片、视频、音频和 GIS 数据等基础内容作为常量资源；完整类别与类型名另行定义
数值模型	统一数值类别，不区分 int32、float 等机器表示类型；平台选择可保存该数值的表示，允许使用大数并接受性能成本
媒体与 GIS	接受的格式导入后转写为各自内部标准格式，导出时再编码；业务代码使用类型化内容，不按输入编码手动解析 buffer
变量模型	变量是可改变目标的资源引用，可引用基础常量及高级结构；不要求裸指针和手动内存管理
Agent 声明	agent 是与 class、function 并列的语言资源，内部复用共有语法并建立成员作用域和运行关联
Agent 职责	tools 引用外部函数或内部实现；memory、state、条件路由、人工中断和上下文管理纳入语言模型
Agent 编程	agent 可以实现新逻辑并引用已有函数；提交新定义后须经过 Preflight 才能作为已就绪定义执行
人工在环	高风险操作执行前暂停，等待人类确认或修改意见，并保留恢复所需状态
类型兼容	用户声明的类型按声明身份区分，不仅凭字段或方法相同建立兼容或能力实现关系；不采用结构类型兼容
调用目标	普通逻辑调用表达输入、结果与依赖，系统组织执行
权限操作分工	r 读取、w 编辑资源内容或定义、x 使用已定义的程序能力；程序按业务契约产生写入不要求调用者因此成为 Editor；执行不自动授予管理能力
官方组件	官方 UI 组件与用户库内容分别定义
阶段命名	执行准备与检查阶段为 Preflight，运行阶段为 inflight；名称本身不增加源码关键字
执行方向	平台解释执行代码，不要求独立构建步骤或字节码转译；Preflight 检查并建立关联索引
生命周期	Preflight 生命周期覆盖定义的创建、检查、持续可引用、更新与退出；inflight 生命周期覆盖实际调用、实例、任务和运行状态的存续
界面表达	普通函数返回可渲染值表达界面，不采用独立 scene 声明或 render 块
资源访问	客户端可查看获准访问的资源，依据当前资源或调用结果的类型选择呈现方式
函数查看与调用	必填参数未就绪时查看函数本身；输入满足调用要求后可调用并呈现结果；执行等待不退回为定义查看
跨端使用	函数调用与 hook 关联由平台组织执行和通信，应用直接使用符合声明类型的结果与更新

收录的语法提案

提案	正文位置	说明
词法与字面量	第 6 章	本书统一采用的标识符、字符串、数字和符号形式
类字段、成员与类型标注	第 7 章	统一数值暂用 Number，文本沿用 String；类字段与成员函数的具体形式仍为提案
表达式与 let	第 8 章	基础运算、成员访问与局部绑定
function 与 return	第 9 章	函数签名、基本函数体与调用组合
Product.get	第 10 章	读取体验提案，不是 class 自动附带的 API
组件效果	第 12 章	参数、布局与默认值的效果提案；构造表达式尚未定义
agent 声明骨架	第 13 章	agent 语言地位已确定；共有成员骨架为提案，职责关联形式尚未定义

程序声明组合与形式文法同样属于设计稿。正文中的陈述定义这些提案内部的用法，不将其确定程度提升为最终规范。

身份与权限

workspace 是资源归属与整体授权边界，用户负责操作和作者身份。主要定义见用户身份与 workspace 权限。w 表示资源编辑，x 表示使用程序及其契约允许的业务效果。

尚未定义：

• 用户的登录标识、认证方式、展示名称及账号生命周期；这些信息不充当资源 key 前缀。
• 资源的默认公开性、匿名访问、读取与执行授权的具体授予方式。
• 操作身份、业务执行能力绑定、Agent 委托、操作记录与归属转移。
• 入口的授权操作范围和业务效果约束；x 不自动提供任意直接资源编辑或管理员能力。

定位信息不构成授权，是这些规则必须保留的边界。

Workspace 名称与生命周期

workspace 归属、key 前缀和整体授权模型已确定。名称细节、配额及运行授权的具体机制仍需定义。

尚未确定：

• 默认 workspace handle 的生成，以及历史用户名 key 的迁移或兼容规则。
• workspace handle 的字符、大小写、唯一性比较、改名与复用、展示名称及稳定身份。
• workspace 的创建数量上限、计数归属、加入与创建的区别、停用和删除后的额度处理。
• 角色的正式名称、Reader 是否具有 x、仅执行授权的授予形式、公开或匿名访问及成员移除规则。
• 管理员交接、workspace 停用、账号注销后的归属与资源保留，以及管理操作的完整范围。
• 仅具有 x 时的调用接口信息范围，以及程序运行能力与资源编辑权限之间的具体执行机制。
• 角色变更和授权撤销对正在执行、暂停或恢复中的调用、实例与任务的影响。

正文的 atelier、market key 前缀均解释为 workspace handle；alice、bob 仅在成员和作者示意中代表用户。

引用与代码视图

尚未定义：

• 代码段的语法边界、视图成员范围和下级 namespace 的纳入方式。
• use 的作用范围、声明可见性、限定名、别名与同名冲突。
• 视图顺序、版本选择、成员一致性及编辑操作映射。
• key 的传递编码和索引关联机制。

正文跨 namespace 示例采用目标声明可见、名称可直接解析且无冲突的条件；该条件不代替正式名称查找规则。

声明与类型

尚未定义：

• 程序入口、空代码视图、客户端访问所用的定位形式与顶层绑定。
• 函数本身的完整类型表达、值形式与查看信息范围。
• 完整类型命名、可选值、泛型及类型转换；基础资源的具体边界见下一节。
• 类构造、成员函数的接收者与实例关联、默认值、继承和字段可见性。
• 显式能力实现、类型兼容与转换关系的声明形式，以及类型推断规则。
• 代码更新和不同版本之间的类型身份比较规则。
• 重复声明、完整控制流、实例及字段可变性、赋值和作用域细节。

本文简单函数体仅收录 let 与末尾 return，不意味着整门语言只允许这两种语句。

基础资源与变量

基础常量、统一数值、格式归一化和变量引用的主要定义见资源、类型与类及变量与资源引用。

尚未定义：

• 基础类型的完整集合与正式名称；Number、String 为本文采用的类型名提案，媒体和 GIS 不补造正式名称。
• 数值精度、舍入、除法、特殊值、算术资源限制和数值相等性；使用大数不自动决定任意实数的精确表示。
• 每类媒体或 GIS 数据的内部标准格式、可接收和可导出的编码，以及精度、元数据、坐标系统和转换规则。
• 非代码资源的注册、导入、导出、成员定位及保存版本的源码或平台接口。
• 可变变量声明、重新赋值、let 可重绑性，以及变量引用的类型表达和可指向范围检查。
• 资源、引用和实例的相等性、别名关系、成员更新，以及常量去重或共享规则。

基础内容不可原地修改，变量可以改变引用目标；这不自动决定高级实例整体不可变，也不自动为所有临时值生成永久 namespace 名称。

生命周期与定义更新

主要定义见Preflight 与 inflight。生命周期按定义与运行时实体区分，不能按保存时长区分。

尚未定义：

• 定义创建、更新与退出可用范围的接口，以及已有调用或实例对版本的选择。
• 多定义修改的一致性、协作冲突处理和运行中提交代码的可见时机。
• 定义删除对已有引用、对象和 agent 实例的影响。
• 临时值、不可达值与实例的回收时机，持久保存的数据及记忆的保留、归档与删除规则。
• 运行状态暂停、保存和恢复时引用与版本的一致性。

长期保存的对象、记忆和检查点仍属于 inflight；一次 Preflight 检查结束不终止定义的存续。

词法与表达式

尚未定义：

• 完整保留字集合、Unicode 版本与字符类别边界。
• 换行字符、字符串扩展转义、更多字面量和运算符。
• 数值精度与舍入、除法、隐式转换与所有调用参数的求值顺序；不按固定机器位宽定义数值溢出。

正文中同级二元算术运算的组合顺序属于表达式提案，不规定所有调用的执行顺序。

调用与数据

尚未定义：

• 显式等待、失败处理、缺失值、取消和超时的源码形式。
• 数据读取成员的声明、参数与结果类型。
• 一次结果、持续结果及其更新语义。
• hook 的源码形式、触发或订阅关系、生命周期、关联解除和更新范围。
• 带业务修改的调用顺序、重复执行限制与失败行为。
• 更新代码时已有调用使用哪个版本。

正常结果必须符合声明，未就绪或失败不能伪造为成功结果。Product.get 示例只展示成功路径。

UI

尚未定义：

• 官方组件库的 key、显式引用形式与名称可见性。
• 普通表达式中构造界面值的形式、参数传入方式及子节点组合。
• 界面结果的根结构、集合形式和类型约束；不沿用 render 单根文法。
• 界面计算中的调用、状态、数据绑定、事件与更新。
• 布局单位、参数范围、负数、显式尺寸、约束与溢出。
• 主题、样式、文字测量和其他组件。

正文的官方组件示例使用结构示意，不定义调用语法，也不承诺免导入使用。

资源访问与呈现

资源定位、函数本身与调用结果的区别，以及参数就绪和执行等待的边界，主要定义见资源访问与呈现。

保留待讨论：

• 完整顶级类型的名称、集合及关系；已确定基础数值、文本、媒体和 GIS 类别，不代表完整类型层次已经确定。
• 顶级类型采用继承、接口、协议或其他机制的关系与声明形式。
• 可渲染类型的契约、普通类型的默认展示方式及自定义呈现。
• 同一资源具有多种呈现能力时的选择规则及未知类型的处理方式。
• 参数填写、默认或可省略参数、平台提供参数与访问触发调用的具体规则。
• 资源查看、显式调用、可执行入口与具有业务修改效果的操作之间的界限。
• 图片、字体等资源的具体标识、正式类型名与登记形式；独立保存的基础资源已纳入 namespace 归属方向。

基础资源类别已在第 7 章说明；完整类型层次、展示契约和媒体构造形式仍待定，不因此向形式文法补写专用资源语法。

Agent

Agent 的语言资源地位、共有成员模型和核心职责已确定，主要定义见Agent。具体保留的边界包括：

• agent 声明和职责关联的完整语法、成员可见性、名称查找、嵌套声明，以及共享成员与实例成员的区分。
• 内部成员函数与外部函数引用的工具关联、默认暴露范围、工具描述、参数转换及结果处理。
• memory 的类型、会话与长期记忆范围、检查点粒度、持久性、隔离、共享、保留和恢复规则。
• state 的类型表达、有限状态机、节点、迁移条件和条件路由语法，以及并发更新规则。
• 高风险操作的判定、审批关联、确认有效期、恢复接口和重复效果控制。
• 上下文预算、裁剪、增量总结、必须保留的信息、模型配置与失败处理。
• agent 的实例化、任务交付、对外入口、输入与结果契约、实例及任务标识。
• agent 修改 namespace 的授权、代码提交接口和生成代码的版本与依赖一致性。

成员函数是否默认向模型暴露为工具仍待定义；引用定义不自动启动实例或任务。MemorySaver 等外部库 API 不成为语言关键字或默认成员。

设计决定记录

2026-10-08 的用户设计决定明确了定义与运行时的 Preflight／inflight 生命周期、agent 作为语言结构及其核心职责，以及基础常量资源、统一数值、格式归一化和变量引用模型。未明确的关键字、成员关联、算术和编码选择继续保留为提案或未定义项。

同日确认 w 用于资源编辑，x 用于使用定义好的程序能力，业务调用产生写入不要求调用者成为 Editor。随后明确采用 workspace 归属模型：key 使用 workspace handle，注册创建默认个人 workspace，用户作为成员、操作用户及作者，权限按 workspace 整体管理。此决定替换原用户名归属模型；名称细节、迁移和仅执行授权等未定项不随之确定。

规范范围

本文定义源码及应有的语言效果。云端实体、持久化类、自动建表、通信、缓存、部署和编排实现不在本阶段规范中。

S3 约定仅用于代码存储，不规定业务数据后端。平台负责跨端执行与通信的约定不指定传输协议、类型编码、调度算法或部署产物。

目录