217 lines
15 KiB
Markdown
217 lines
15 KiB
Markdown
# 规范状态
|
||
|
||
本附录记录语言设计的确定程度与尚未定义的边界。它用于理解设计稿，不代表软件实现进度或可执行性保证。
|
||
|
||
## 已确定约定
|
||
|
||
| 主题 | 已确定内容 |
|
||
| --- | --- |
|
||
| 语言定位 | 前后端共用的云原生编程语言，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 章](../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) | 函数签名、基本函数体与调用组合 |
|
||
| Product.get | [第 10 章](../guide/10-data-access.md) | 读取体验提案，不是 class 自动附带的 API |
|
||
| 组件效果 | [第 12 章](../guide/12-ui-components.md) | 参数、布局与默认值的效果提案；构造表达式尚未定义 |
|
||
| agent 声明骨架 | [第 13 章](../guide/13-agents.md) | agent 语言地位已确定；共有成员骨架为提案，职责关联形式尚未定义 |
|
||
|
||
程序声明组合与[形式文法](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 示例采用目标声明可见、名称可直接解析且无冲突的条件；该条件不代替正式名称查找规则。
|
||
|
||
## 声明与类型
|
||
|
||
尚未定义：
|
||
|
||
- 程序入口、空代码视图、客户端访问所用的定位形式与顶层绑定。
|
||
- 函数本身的完整类型表达、值形式与查看信息范围。
|
||
- 完整类型命名、可选值、泛型及类型转换；基础资源的具体边界见下一节。
|
||
- 类构造、成员函数的接收者与实例关联、默认值、继承和字段可见性。
|
||
- 显式能力实现、类型兼容与转换关系的声明形式，以及类型推断规则。
|
||
- 代码更新和不同版本之间的类型身份比较规则。
|
||
- 重复声明、完整控制流、实例及字段可变性、赋值和作用域细节。
|
||
|
||
本文简单函数体仅收录 let 与末尾 return，不意味着整门语言只允许这两种语句。
|
||
|
||
## 基础资源与变量
|
||
|
||
基础常量、统一数值、格式归一化和变量引用的主要定义见[资源、类型与类](../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 示例只展示成功路径。
|
||
|
||
## UI
|
||
|
||
尚未定义：
|
||
|
||
- 官方组件库的 key、显式引用形式与名称可见性。
|
||
- 普通表达式中构造界面值的形式、参数传入方式及子节点组合。
|
||
- 界面结果的根结构、集合形式和类型约束；不沿用 render 单根文法。
|
||
- 界面计算中的调用、状态、数据绑定、事件与更新。
|
||
- 布局单位、参数范围、负数、显式尺寸、约束与溢出。
|
||
- 主题、样式、文字测量和其他组件。
|
||
|
||
正文的官方组件示例使用结构示意，不定义调用语法，也不承诺免导入使用。
|
||
|
||
## 资源访问与呈现
|
||
|
||
资源定位、函数本身与调用结果的区别，以及参数就绪和执行等待的边界，主要定义见[资源访问与呈现](../guide/11-resource-access-and-presentation.md)。
|
||
|
||
保留待讨论：
|
||
|
||
- 完整顶级类型的名称、集合及关系；已确定基础数值、文本、媒体和 GIS 类别，不代表完整类型层次已经确定。
|
||
- 顶级类型采用继承、接口、协议或其他机制的关系与声明形式。
|
||
- 可渲染类型的契约、普通类型的默认展示方式及自定义呈现。
|
||
- 同一资源具有多种呈现能力时的选择规则及未知类型的处理方式。
|
||
- 参数填写、默认或可省略参数、平台提供参数与访问触发调用的具体规则。
|
||
- 资源查看、显式调用、可执行入口与具有业务修改效果的操作之间的界限。
|
||
- 图片、字体等资源的具体标识、正式类型名与登记形式；独立保存的基础资源已纳入 namespace 归属方向。
|
||
|
||
基础资源类别已在第 7 章说明；完整类型层次、展示契约和媒体构造形式仍待定，不因此向形式文法补写专用资源语法。
|
||
|
||
## Agent
|
||
|
||
Agent 的语言资源地位、共有成员模型和核心职责已确定，主要定义见[Agent](../guide/13-agents.md)。具体保留的边界包括：
|
||
|
||
- agent 声明和职责关联的完整语法、成员可见性、名称查找、嵌套声明，以及共享成员与实例成员的区分。
|
||
- 内部成员函数与外部函数引用的工具关联、默认暴露范围、工具描述、参数转换及结果处理。
|
||
- memory 的类型、会话与长期记忆范围、检查点粒度、持久性、隔离、共享、保留和恢复规则。
|
||
- state 的类型表达、有限状态机、节点、迁移条件和条件路由语法，以及并发更新规则。
|
||
- 高风险操作的判定、审批关联、确认有效期、恢复接口和重复效果控制。
|
||
- 上下文预算、裁剪、增量总结、必须保留的信息、模型配置与失败处理。
|
||
- agent 的实例化、任务交付、对外入口、输入与结果契约、实例及任务标识。
|
||
- agent 修改 namespace 的授权、代码提交接口和生成代码的版本与依赖一致性。
|
||
|
||
成员函数是否默认向模型暴露为工具仍待定义；引用定义不自动启动实例或任务。MemorySaver 等外部库 API 不成为语言关键字或默认成员。
|
||
|
||
## 设计决定记录
|
||
|
||
2026-10-08 的用户设计决定明确了定义与运行时的 Preflight／inflight 生命周期、agent 作为语言结构及其核心职责，以及基础常量资源、统一数值、格式归一化和变量引用模型。未明确的关键字、成员关联、算术和编码选择继续保留为提案或未定义项。
|
||
|
||
同日确认 w 用于资源编辑，x 用于使用定义好的程序能力，业务调用产生写入不要求调用者成为 Editor。随后明确采用 workspace 归属模型：key 使用 workspace handle，注册创建默认个人 workspace，用户作为成员、操作用户及作者，权限按 workspace 整体管理。此决定替换原用户名归属模型；名称细节、迁移和仅执行授权等未定项不随之确定。
|
||
|
||
## 规范范围
|
||
|
||
本文定义源码及应有的语言效果。云端实体、持久化类、自动建表、通信、缓存、部署和编排实现不在本阶段规范中。
|
||
|
||
S3 约定仅用于代码存储，不规定业务数据后端。平台负责跨端执行与通信的约定不指定传输协议、类型编码、调度算法或部署产物。
|
||
|
||
[目录](../README.md)
|