Files
Endorphin-Document/appendices/specification-status.md

292 lines
25 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 规范状态
本附录记录语言设计的确定程度与尚未定义的边界。它用于理解设计稿,不代表软件实现进度或可执行性保证。
## 已确定约定
| 主题 | 已确定内容 |
| --- | --- |
| 语言定位 | 前后端共用的云原生编程语言,UI 是应用领域之一 |
| 资源归属 | workspace 管理归属与协作,namespace 提供命名入口;用户是操作与作者身份 |
| 资源身份 | 独立 ID 识别资源;多个 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 才能作为已就绪定义执行 |
| 人工在环 | 高风险操作执行前暂停,等待人类确认或修改意见,并保留恢复所需状态 |
| 类型兼容 | 用户声明的类型按声明身份区分,不仅凭字段或方法相同建立兼容或能力实现关系;不采用结构类型兼容 |
| Object 与 Type | Object 是无父类型的继承根;Object 是 Type 的实例,Type 是自己的实例且继承 Object;平台按具体类型管理对象生命周期 |
| 实例化与继承 | 对象的直接实例类型与类型的父类型分别保存和查询;类型对象与运行实例都属于对象体系 |
| 定义构造入口 | class、trait、record、agent 等入口自身也是对象,构造出的类型或定义同样是对象;不预先将入口名称定为保留关键字 |
| Object 与 atom | atom 是对象可独立识别、保存和引用的资源单元,资源 ID 连接对象图;组合对象也可以成为 atom |
| 类型能力 | 在 Object 共同基础上组合多个显式 trait 能力,不要求以一条父子继承链表达全部能力;具体声明规则待定 |
| 类型系统范围 | 基础类型、容器、引用和定义资源共同组织 class、Function、agent 等高级结构;讨论不限于函数签名 |
| Function | 平台原生的函数类型,可扩展行为与生命周期;函数自身类型与调用返回类型分别表达 |
| 调用目标 | 普通逻辑调用表达输入、结果与依赖,系统组织执行 |
| 权限操作分工 | r 读取、w 编辑资源内容或定义、x 使用已定义的程序能力;程序按业务契约产生写入不要求调用者因此成为 Editor;执行不自动授予管理能力 |
| 官方组件 | 官方 UI 组件与用户库内容分别定义 |
| 阶段命名 | 执行准备与检查阶段为 Preflight,运行阶段为 inflight;名称本身不增加源码关键字 |
| 执行方向 | 平台解释执行代码,不要求独立构建步骤或字节码转译;Preflight 检查并建立关联索引 |
| 生命周期 | Preflight 生命周期覆盖定义的创建、检查、持续可引用、更新与退出;inflight 生命周期覆盖实际调用、实例、任务和运行状态的存续 |
| 界面表达 | 普通函数返回可渲染值表达界面,不采用独立 scene 声明或 render 块 |
| 资源访问 | 客户端可查看获准访问的资源,依据当前资源或调用结果的类型选择呈现方式 |
| 函数查看与调用 | 必填参数未就绪时查看函数本身;输入满足调用要求后可调用并呈现结果;执行等待不退回为定义查看 |
| 跨端使用 | 函数调用与 hook 关联由平台组织执行和通信,应用直接使用符合声明类型的结果与更新 |
| 跨端对象 | 对象可由平台管理和存储;客户端建立关联同一资源身份的本地副本,通过网络取得数据并同步后续变化;身份关联不表示共享内存或瞬时一致 |
## 收录的语法提案
| 提案 | 主要说明 | 说明 |
| --- | --- | --- |
| 词法与字面量 | [第 6 章](../guide/06-lexical-structure.md) | 本书统一采用的标识符、字符串、数字和符号形式 |
| 类字段、成员与类型标注 | [第 7 章](../guide/07-types-and-classes.md) | 统一数值暂用 Number,文本沿用 String;类字段与成员函数的具体形式仍为提案 |
| 表达式与 let | [第 8 章](../guide/08-expressions-and-bindings.md) | 基础运算、成员访问与局部绑定 |
| function 与 return | [第 9 章](../guide/09-functions-and-calls.md) | 早期基本调用草案;表达具体函数自身类型的替代声明见第 7 章候选 |
| 顶级类型代码示例 | [第 7 章续篇](../guide/07-top-level-types/README.md) | 七组类型逐项展示候选声明、构造、调用与结果;函数声明同时比较两种形式,未合并进正式 EBNF |
| Product.get | [第 10 章](../guide/10-data-access.md) | 读取体验提案,不是 class 自动附带的 API |
| 组件效果 | [第 12 章](../guide/12-ui-components.md) | 参数、布局与默认值的效果提案;构造表达式尚未定义 |
| agent 声明骨架 | [第 13 章](../guide/13-agents.md) | agent 语言地位已确定;共有成员骨架为提案,职责关联形式尚未定义 |
| REPL 会话行为 | [第 14 章](../guide/14-repl.md) | 会话上下文、输入求值、对象查看、执行记录及同步状态的设计提案,不增加已确定的控制命令或顶层文法 |
程序声明组合与[形式文法](formal-grammar.md)同样属于设计稿。语法提案按其内部规则使用,不等于最终规范。
## 身份与权限
workspace 是资源归属与整体授权边界,用户负责操作和作者身份。主要定义见[用户身份与 workspace 权限](../guide/02-user-identity.md)。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 示例采用目标声明可见、名称可直接解析且无冲突的条件;该条件不代替正式名称查找规则。
## 声明与类型
尚未定义:
- 程序入口、空代码视图、客户端访问所用的定位形式与顶层绑定。
- 函数本身的完整类型表达、值形式与查看信息范围。
- 完整类型命名、可选值、泛型及类型转换;基础资源的具体边界见下一节。
- 类构造、成员函数的接收者与实例关联、默认值、继承和字段可见性。
- 显式能力实现、类型兼容与转换关系的声明形式,以及类型推断规则。
- 代码更新和不同版本之间的类型身份比较规则。
- 重复声明、完整控制流、实例及字段可变性、赋值和作用域细节。
第 9 章的基本调用草案只展示 let 与末尾 return;第 7 章的类型设计另有赋值、等待等候选示例,两者都不穷尽语言语句。
## 顶级类型讨论
[Object 与类型系统](../guide/07-top-level-types/README.md)定义对象、类型对象及其资源关联。Object/Type 闭环、实例化线与继承线、资源 atom 关系和平台生命周期职责已确定;各类型的完整操作、源码接口与能力接入形式仍分别评审。
| 类型组 | 已确定方向 | 候选与待定范围 |
| --- | --- | --- |
| [Object](../guide/07-top-level-types/README.md#object) | Object ∈ Type、Type ∈ Type、Type ⊆ Object;实例化与继承关联接入资源 ID 图 | 共同操作接口、typeOf 与 basesOf 的具体形式、能力分派、继承语法及登记粒度 |
| [Bool、Number、String、Unit、Null](../guide/07-top-level-types/values.md) | 统一数值、文本与基础常量模型 | Bool、Unit、Null 的地位;基础类型怎样约束结构成员、精度与转换 |
| [Tuple、record、List、Map、Set、Option、Result](../guide/07-top-level-types/collections.md) | 需要组合固定成员、容器和分支结构 | 类型构造与参数规则、名义身份、相等性与可变性;Option 和 Result 为候选 |
| [Ref、Cell](../guide/07-top-level-types/references.md) | 独立资源 ID、确定引用与可变目标引用;按保留根可达性回收 | 显式类型与透明引用的关系、解析时机、保留根和状态引用规则 |
| [Type、Trait、Code、class](../guide/07-top-level-types/definitions.md) | 类型本身是 Type 对象,可传递和引用;代码也是对象;名义类型与多个 trait 能力组合 | 构造入口的具体类型和语法、成员组合、反射和生成规则 |
| [Function](../guide/07-top-level-types/functions.md) | 原生函数类型,可扩展行为和生命周期;自身类型与返回类型分别表达 | 完整声明语法、扩展机制、捕获环境、实例状态与调用生命周期 |
| [Task、Stream、State、Session](../guide/07-top-level-types/execution.md) | inflight 管理运行实体及状态 | 是否独立原生化、内容类型参数,以及等待、取消、恢复和共享规则 |
| [Agent、agent](../guide/07-top-level-types/agents.md) | Agent 是 Type 的实例并继承 Object;具体类型对象与运行实例分别保存 | 具体类型继承 Agent 的形式、构造入口、成员组合及运行生命周期 |
资源 ID 独立于命名入口:workspace 管理归属与协作,namespace 管理组织,同一资源可以具有多个命名入口;移除入口不等于清除仍被保留程序引用的资源。namespace key 中的非空路径要求只描述命名入口,不要求资源始终保留一个入口,也不充当资源 ID 的定义。具体登记及名称绑定机制仍待确定。
atom 是 Object 的资源组织视角,不另外引入 Atom 基础类型。定义对象及实例对象分别保留具体身份与生命周期;运行对象的固定 ID 不冻结其合法状态变化。workspace 与 namespace 的管理职责和资源 atom 分开,不因共同对象模型自动把管理记录变成语言资源。
函数构造必须区分自身类型与调用签名,具体简写尚未确定。trait 组合方向不自动引入 Rust 的其他规则。完整泛型与遗传算法设计尚待定义。
候选示例采用类型参数、箭头签名、显式实现、构造器及任务操作,其状态不构成实现或可执行性保证。
## 基础资源与变量
基础常量、统一数值、格式归一化和变量引用的主要定义见[资源、类型与类](../guide/07-types-and-classes.md#71-类型标注)及[变量与资源引用](../guide/08-expressions-and-bindings.md#86-变量与资源引用)。
尚未定义:
- 基础类型的完整集合与正式名称;Number、String 为本文采用的类型名提案,媒体和 GIS 不补造正式名称。
- 数值精度、舍入、除法、特殊值、算术资源限制和数值相等性;使用大数不自动决定任意实数的精确表示。
- 每类媒体或 GIS 数据的内部标准格式、可接收和可导出的编码,以及精度、元数据、坐标系统和转换规则。
- 非代码资源的注册、导入、导出、成员定位及保存版本的源码或平台接口。
- 可变变量声明、重新赋值、let 可重绑性,以及变量引用的类型表达和可指向范围检查。
- 资源、引用和实例的相等性、别名关系、成员更新,以及常量去重或共享规则。
基础内容不可原地修改,变量可以改变引用目标;这不自动决定高级实例整体不可变,也不自动为所有临时值生成永久 namespace 名称。
## 生命周期与定义更新
主要定义见[Preflight 与 inflight](../guide/05-preflight-and-inflight.md#56-定义与运行时生命周期)。生命周期按定义与运行时实体区分,不能按保存时长区分。
尚未定义:
- 定义创建、更新与退出可用范围的接口,以及已有调用或实例对版本的选择。
- 多定义修改的一致性、协作冲突处理和运行中提交代码的可见时机。
- 删除内容、撤销授权与已有对象或 agent 实例的关系;仅移除命名入口不会使保留的确定引用失效。
- 临时值、不可达值与实例的回收时机,持久保存的数据及记忆的保留、归档与删除规则。
- 运行状态暂停、保存和恢复时引用与版本的一致性。
长期保存的对象、记忆和检查点仍属于 inflight;一次 Preflight 检查结束不终止定义的存续。
## 词法与表达式
尚未定义:
- 完整保留字集合、Unicode 版本与字符类别边界。
- 换行字符、字符串扩展转义、更多字面量和运算符。
- 数值精度与舍入、除法、隐式转换与所有调用参数的求值顺序;不按固定机器位宽定义数值溢出。
同级二元算术运算从左到右组合属于表达式提案,不规定所有调用的执行顺序。
## 调用与数据
尚未定义:
- 显式等待、失败处理、缺失值、取消和超时的源码形式。
- 数据读取成员的声明、参数与结果类型。
- 一次读取与持续关联的表达式、结果类型及建立方式;对象同步的具体边界见下一节。
- hook 的源码形式、触发或订阅关系、生命周期、关联解除和更新范围。
- 带业务修改的调用顺序、重复执行限制与失败行为。
- 已有调用继续保留所选定义,切换新定义或迁移运行实例的显式机制仍待定。
正常结果必须符合声明,未就绪或失败不能伪造为成功结果。Product.get 示例只展示成功路径。
## 跨端对象与同步
主要定义见[跨端对象与同步](../guide/11-resource-access-and-presentation.md#117-跨端对象与同步)。平台管理和存储对象、客户端建立本地副本并关联远程对象、通过网络交付数据及后续同步的方向已确定。它沿用 Object、资源 ID、类型及生命周期模型,不另设 PlatformObject 基础类型,也不自动把 class 变成持久化表。
不可变内容或定义更新产生新资源身份,确定引用不因同步而改指新对象;运行对象可以在类型允许的范围内保留身份并改变状态。平台对象、本地副本与同步关联分别具有生命周期,释放副本不等于删除平台对象。
尚未定义:
- 对象的登记与加载范围、本地副本的源码形式,以及完整或部分数据的取得规则。
- 一次读取与持续关联的建立、解除、可写性和结果类型;hook 与对象同步的具体关联方式。
- 状态版本、读取新鲜度、更新顺序及多对象一致性契约;不预先选定服务器权威、版本比较或合并算法。
- 本地修改的提交与保存确认、等待与失败状态,以及是否允许提前展示尚未被平台接受的修改。
- 多端同时修改的冲突处理、重试、去重和重复业务效果限制。
- 离线期间的读写、断线后的恢复、遗漏更新的取得及重新同步规则。
- 授权撤销、目标删除、关联解除与资源回收对已有副本的影响。
- 传输协议、类型编码及对象存储后端;这些实现选择不由逻辑对象身份决定。
## UI
尚未定义:
- 官方组件库的 key、显式引用形式与名称可见性。
- 普通表达式中构造界面值的形式、参数传入方式及子节点组合。
- 界面结果的根结构、集合形式和类型约束;不沿用 render 单根文法。
- 界面计算中的调用、状态、数据绑定、事件与更新。
- 布局单位、参数范围、负数、显式尺寸、约束与溢出。
- 主题、样式、文字测量和其他组件。
官方组件示例使用结构示意,不定义调用语法,也不承诺免导入使用。
## 资源访问与呈现
资源定位、函数本身与调用结果的区别,以及参数就绪和执行等待的边界,主要定义见[资源访问与呈现](../guide/11-resource-access-and-presentation.md)。
保留待讨论:
- 完整顶级类型的名称、集合及关系;已确定基础数值、文本、媒体和 GIS 类别,不代表完整类型层次已经确定。
- trait 能力组合及原生类型扩展的完整关系与声明形式。
- 可渲染类型的契约、普通类型的默认展示方式及自定义呈现。
- 同一资源具有多种呈现能力时的选择规则及未知类型的处理方式。
- 参数填写、默认或可省略参数、平台提供参数与访问触发调用的具体规则。
- 资源查看、显式调用、可执行入口与具有业务修改效果的操作之间的界限。
- 图片、字体等资源的具体标识、正式类型名与登记形式;独立保存的基础资源已纳入 namespace 归属方向。
基础资源类别已在第 7 章说明;完整类型层次、展示契约和媒体构造形式仍待定,不因此向形式文法补写专用资源语法。
## Agent
Agent 的语言资源地位、共有成员模型和核心职责已确定,主要定义见[Agent](../guide/13-agents.md)。具体保留的边界包括:
- agent 声明和职责关联的完整语法、成员可见性、名称查找、嵌套声明,以及共享成员与实例成员的区分。
- 内部成员函数与外部函数引用的工具关联、默认暴露范围、工具描述、参数转换及结果处理。
- memory 的类型、会话与长期记忆范围、检查点粒度、持久性、隔离、共享、保留和恢复规则。
- state 的类型表达、有限状态机、节点、迁移条件和条件路由语法,以及并发更新规则。
- 高风险操作的判定、审批关联、确认有效期、恢复接口和重复效果控制。
- 上下文预算、裁剪、增量总结、必须保留的信息、模型配置与失败处理。
- agent 的实例化、任务交付、对外入口、输入与结果契约、实例及任务标识。
- agent 修改 namespace 的授权、代码提交接口和生成代码的版本与依赖一致性。
成员函数是否默认向模型暴露为工具仍待定义;引用定义不自动启动实例或任务。MemorySaver 等外部库 API 不成为语言关键字或默认成员。
## REPL
[交互式会话(REPL)](../guide/14-repl.md)提出持续输入环境:声明准备定义,表达式检查后求值,结果对象可在后续输入中继续使用,远程等待与同步状态可查看。提案复用已有对象、权限、Preflight/inflight 和资源呈现规则;会话范围绑定、定义暂存、结果保留及交互调度尚未确定为正式契约。
尚未定义:
- 启动入口、控制命令、快捷键、多行输入边界、完整 REPL 文法及顶层绑定的正式形式。
- 会话名称的作用域、重复声明、重新绑定、失败后的环境变更,以及导入与名称冲突处理。
- 临时定义的资源登记、保存范围、共享 namespace 的编辑接口及新旧定义的绑定切换。
- 是否采用原生 Session、身份及权限传播、会话隔离与上下文切换。
- 输入的顺序与并发调度、待完成结果的引用、取消确认及未完成调用的结束行为。
- 结果查看方式、显式结果命名、更新通知与同步状态呈现;不预先引入隐式结果变量。
- 历史与会话状态的保存、对象保留根、恢复规则,以及避免业务调用被自动重放的具体契约。
- 断线、授权变化、客户端退出对平台任务、副本、同步关联及保存结果的影响。
本章的交互示意按文档规则推演,不代表已有启动命令或实际执行结果。REPL 提案不改写函数声明、普通调用和跨端对象的已有语义,也不选择存储后端或调度实现。
## 设计决定记录
2026-10-08 的用户设计决定明确了定义与运行时的 Preflight/inflight 生命周期、agent 作为语言结构及其核心职责,以及基础常量资源、统一数值、格式归一化和变量引用模型。未明确的关键字、成员关联、算术和编码选择继续保留为提案或未定义项。
同日确认 w 用于资源编辑,x 用于使用定义好的程序能力,业务调用产生写入不要求调用者成为 Editor。随后明确采用 workspace 归属模型:key 使用 workspace handle,注册创建默认个人 workspace,用户作为成员、操作用户及作者,权限按 workspace 整体管理。此决定替换原用户名归属模型;名称细节、迁移和仅执行授权等未定项不随之确定。
2026-10-09 的用户决定明确类型系统用于组织高级结构,类型标题使用代码中的名称。Unit、Null、Option、Result、State 等候选是否原生化、各项语法如何表达,仍需分别确定。
同日确定一切皆对象模型及 Object/Type 闭环:Object 是 Type 的实例,Type 是自己的实例并继承 Object,Object 没有父类型。实例化、继承和普通资源引用分别保存;class、trait、record、agent 构造入口自身也是对象。模型与资源 atom、独立 ID、确定引用及可达性保留统一。反射接口、构造入口类型、生命周期接入语法和登记粒度继续待定。
2026-10-13 的用户决定明确了平台管理和存储对象的方向:客户端获取远程数据时建立关联远程对象的本地对象,实际数据通过网络传递,并在后续保持同步。该方向纳入已有对象与资源身份模型;具体源码接口、保存确认、版本、冲突、离线及存储实现继续待定。
## 规范范围
本文定义源码及应有的语言效果,包括平台对象存储、跨端副本关联与同步的概念边界。云端实体的实现、持久化类、自动建表,以及存储、通信、缓存、部署和编排的实现方案不在本阶段规范中。
S3 约定仅用于代码存储,不规定业务数据后端。平台负责跨端执行与通信的约定不指定传输协议、类型编码、调度算法或部署产物。
[目录](../README.md)