Document workspace ownership, resource semantics and agent lifecycle
This commit is contained in:
@@ -34,7 +34,7 @@
|
||||
|
||||
## 示例与状态
|
||||
|
||||
- key 采用用户名:namespace路径，用户名唯一，路径至少一级；各层 namespace 语义一致。
|
||||
- key 采用 workspace handle:namespace路径，workspace handle 在平台内唯一，路径至少一级；资源归属 workspace，用户承担操作与作者身份，各层 namespace 语义一致。
|
||||
- 归属通过外部 key 与索引提供，正文不声明自身 namespace。
|
||||
- use 只引用完整 key，不附加选择性名称列表。
|
||||
- 官方 UI 组件不列为示例用户库的内容；未定的官方引用方式不可写成免导入默认能力。
|
||||
|
||||
@@ -1,28 +1,28 @@
|
||||
# Endorphin 语言文档
|
||||
|
||||
Endorphin 是一门面向云原生应用的编程语言，使用统一的语言模型描述前端界面、数据结构和后端业务逻辑。开发者编写声明、表达式与调用关系，平台解释执行代码，客户端根据资源或调用结果的类型呈现内容。
|
||||
Endorphin 是一门面向云原生应用的编程语言，使用统一的资源与语言模型描述前端界面、数据结构、后端逻辑和 agent。基础内容由平台管理，变量引用资源，开发者和 agent 编写声明、表达式与调用关系，平台解释执行代码，客户端根据资源或结果的类型呈现内容。
|
||||
|
||||
## 阅读指南
|
||||
|
||||
正文按概念的依赖顺序编排。首次阅读从第 1 章开始；查询具体写法时，可以直接进入相应章节。每章包含概念定义、语法、示例和行为说明。
|
||||
|
||||
本书为语言设计稿。用户身份、namespace key、use 形式和阶段命名等基础约定已经确定；函数、类型、数据读取与 UI 的具体写法以本文收录的草案为准。各主题的确定程度统一记录在[规范状态](appendices/specification-status.md)，正文不反复叙述设计过程。
|
||||
本书为语言设计稿。资源归属 workspace，key 使用 workspace handle 与 namespace 路径；用户以成员角色参与协作。use 形式、整体授权边界和阶段命名等基础约定已经确定。权限操作区分资源编辑与程序使用，函数、类型、数据读取与 UI 的具体写法以本文收录的草案为准。各主题的确定程度统一记录在[规范状态](appendices/specification-status.md)，正文不反复叙述设计过程。
|
||||
|
||||
## 正文
|
||||
|
||||
### 第一部分：语言与程序模型
|
||||
|
||||
1. [语言概览](guide/01-overview.md) — 语言用途、核心概念与应用模型。
|
||||
2. [用户身份](guide/02-user-identity.md) — 唯一用户名、显示名、代码归属与访问身份。
|
||||
3. [namespace](guide/03-namespaces.md) — key、层级和可见代码视图。
|
||||
4. [程序结构与导入](guide/04-program-structure.md) — 声明组织、外部上下文和 use。
|
||||
5. [Preflight 与 inflight](guide/05-preflight-and-inflight.md) — 执行准备、检查与解释执行的职责。
|
||||
2. [用户身份与 workspace 权限](guide/02-user-identity.md) — 用户、workspace、成员角色、rwx 与代码可视域。
|
||||
3. [namespace](guide/03-namespaces.md) — Workspace key、层级、归属与视图。
|
||||
4. [程序结构与导入](guide/04-program-structure.md) — 三类声明的组合、内部成员、use 与可视域。
|
||||
5. [Preflight 与 inflight](guide/05-preflight-and-inflight.md) — 定义与运行时生命周期、检查及解释执行的职责。
|
||||
|
||||
### 第二部分：基础语法
|
||||
|
||||
6. [词法结构](guide/06-lexical-structure.md) — 标识符、字面量、符号、标点和注释。
|
||||
7. [类型与类](guide/07-types-and-classes.md) — 类型标注、class 与字段。
|
||||
8. [表达式与绑定](guide/08-expressions-and-bindings.md) — 求值、运算、成员访问和 let。
|
||||
7. [资源、类型与类](guide/07-types-and-classes.md) — 基础常量、统一数值、媒体归一化、类型与 class。
|
||||
8. [表达式与绑定](guide/08-expressions-and-bindings.md) — 求值、运算、成员访问、let 与可变资源引用。
|
||||
9. [函数与调用](guide/09-functions-and-calls.md) — 函数声明、返回值和跨 namespace 组合。
|
||||
|
||||
### 第三部分：应用用法
|
||||
@@ -30,6 +30,7 @@ Endorphin 是一门面向云原生应用的编程语言，使用统一的语言
|
||||
10. [数据读取](guide/10-data-access.md) — 通过类型取得数据及结果状态。
|
||||
11. [资源访问与呈现](guide/11-resource-access-and-presentation.md) — 查看函数、参数就绪、调用结果与按类型呈现。
|
||||
12. [UI 组件](guide/12-ui-components.md) — Column、Row、Spacer 和 Text 的参数与效果。
|
||||
13. [Agent](guide/13-agents.md) — 共有成员、tools、memory、state、路由、中断与上下文管理。
|
||||
|
||||
## 附录
|
||||
|
||||
@@ -45,7 +46,7 @@ Endorphin 是一门面向云原生应用的编程语言，使用统一的语言
|
||||
|
||||
“代码归属”写在代码块之前，用于说明外部上下文，不属于源码。函数体片段会注明使用位置，资源访问与界面结构示意使用 `text` 代码块，不表示新增源码语法。示例中的用户和 namespace 为示意名称。
|
||||
|
||||
正文的函数示例围绕商品定价展开：`alice:shop.pricing` 提供定价逻辑，`bob:shop.checkout` 组合它，`bob:shop.ui` 表达界面；数据读取示例使用 `alice:shop.data`。这些路径表示代码组织，不指定执行位置。
|
||||
正文的函数示例围绕商品定价展开：`atelier:shop.pricing` 提供定价逻辑，`market:shop.checkout` 组合它，`market:shop.ui` 表达界面；数据读取示例使用 `atelier:shop.data`。atelier 与 market 是 workspace handle，后面的路径表示代码组织，不指定执行位置。
|
||||
|
||||
## 文档维护入口
|
||||
|
||||
|
||||
@@ -7,24 +7,25 @@
|
||||
| UI | 函数返回的可渲染值、组件及展示效果 | [资源访问与呈现](../guide/11-resource-access-and-presentation.md)、[UI 组件](../guide/12-ui-components.md) |
|
||||
| 业务逻辑 | 函数、结果、调用组合及业务效果 | [函数与调用](../guide/09-functions-and-calls.md) |
|
||||
| 数据结构与访问 | class、共享类型、读取与字段使用 | [类型与类](../guide/07-types-and-classes.md)、[数据读取](../guide/10-data-access.md) |
|
||||
| Agent | 后续的能力、上下文、任务及行为模型 | [规范状态](specification-status.md#agent) |
|
||||
| 媒体与空间内容 | 图片、视频、音频和 GIS 资源，统一导入表示与导出编码 | [资源、类型与类](../guide/07-types-and-classes.md) |
|
||||
| Agent | agent 声明、工具实现、记忆、状态及运行控制 | [Agent](../guide/13-agents.md) |
|
||||
|
||||
## 跨领域调用
|
||||
|
||||
普通调用是共有语义。UI、业务逻辑或后续 Agent 代码可以在允许访问的前提下使用相应逻辑，而不为跨领域调用建立独立的 RPC 协议声明。
|
||||
普通调用是共有语义。UI、业务逻辑或 agent 代码可以在允许访问的前提下使用相应逻辑，而不为跨领域调用建立独立的 RPC 协议声明。
|
||||
|
||||
类似 RPC 的体验指“调用逻辑并取得结果”。输入、输出、依赖和失败需要在语言中明确，传输客户端、连接方式和缓存由系统承担。
|
||||
|
||||
## 领域与 namespace
|
||||
|
||||
`alice:shop.ui`、`alice:shop.pricing`、`alice:shop.data` 和 `alice:shop.agents` 是组织示例，不是强制目录或具有特殊行为的保留路径。
|
||||
`atelier:shop.ui`、`atelier:shop.pricing`、`atelier:shop.data` 和 `atelier:shop.agents` 是 workspace 内的组织示例，不是强制目录或具有特殊行为的保留路径。
|
||||
|
||||
namespace 的名称不自动决定逻辑在何处执行。一个 namespace 也不必只包含一种声明类别。
|
||||
|
||||
## Agent 范围
|
||||
|
||||
Agent 尚无具体源码语法。需要独立定义的内容包括能力、工具、上下文、任务、生命周期、权限，以及确定性代码和模型驱动行为的边界。
|
||||
agent 是语言资源声明，可以在内部实现函数，也可以引用外部函数；其成员共用 Endorphin 的变量、类型和调用模型，并具有 agent 内部作用域及运行关联。
|
||||
|
||||
本书不为尚未定义的领域提供虚构关键字或 API；其扩展仍应共用语言已有的组织与调用模型。
|
||||
工具、记忆、状态、路由、人工中断和上下文管理的职责见[Agent](../guide/13-agents.md)。声明骨架为提案，具体成员关联、任务入口、模型配置和权限语法仍按[规范状态](specification-status.md#agent)记录。
|
||||
|
||||
[目录](../README.md)
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## 独立代码段
|
||||
|
||||
代码分别存储为独立代码段，每段关联一个唯一用户和至少一级 namespace。S3 承担代码内容的存储职责，索引维护 namespace key 与代码段的成员关系。
|
||||
代码分别存储为独立代码段，每段关联一个归属 workspace 和至少一级 namespace。S3 承担代码内容的存储职责，索引维护 namespace key 与代码段的成员关系；编写或修改代码的用户身份另行记录。
|
||||
|
||||
源码文件不作为代码身份或 module 边界。本书中的 Markdown 文件是文档章节，不对应语言中的源码组织单位。
|
||||
|
||||
@@ -31,7 +31,9 @@ S3 对象键不是语言中的 namespace key。bucket 名、对象键和存储
|
||||
|
||||
## namespace 制
|
||||
|
||||
namespace 同时表达归属与查找位置，使业务函数、类型、界面逻辑和后续 Agent 代码遵循一致的组织模型。第一级与后续层级具有相同语义。
|
||||
namespace 同时表达归属与查找位置，使业务函数、类型、界面逻辑和 agent 定义遵循一致的组织模型。第一级与后续层级具有相同语义。
|
||||
|
||||
基础内容也纳入资源归属方向，但本附录的 S3 代码段约定不自动规定媒体、GIS 数据、对象或 agent 记忆的存储后端。代码视图与完整资源集合的区别见[namespace](../guide/03-namespaces.md)。
|
||||
|
||||
这一组织选择不自动决定检查边界、执行位置、权限继承或业务数据存储。相关语义需要由各自规则定义，而不是从 S3 物理布局推导。
|
||||
|
||||
|
||||
@@ -21,27 +21,46 @@
|
||||
|
||||
```ebnf
|
||||
program = { use-decl }, declaration, { declaration }, EOF ;
|
||||
declaration = class-decl | function-decl ;
|
||||
declaration = class-decl | function-decl | agent-decl ;
|
||||
|
||||
use-decl = "use", namespace-key ;
|
||||
namespace-key = user-handle, ":", namespace-path ;
|
||||
namespace-key = workspace-handle, ":", namespace-path ;
|
||||
namespace-path = identifier, { ".", identifier } ;
|
||||
```
|
||||
|
||||
user-handle 是系统认可的唯一用户名，由身份规则提供，不等同于源码 identifier。代码自身的归属通过外部上下文提供，程序文法中没有自身 namespace 声明。
|
||||
workspace-handle 是系统认可的唯一 workspace 名称，由平台命名规则提供，不等同于源码 identifier 或操作用户的登录标识。代码自身的归属通过外部上下文提供，程序文法中没有自身 namespace 声明。
|
||||
|
||||
相关说明：[namespace](../guide/03-namespaces.md)、[程序结构与导入](../guide/04-program-structure.md)。
|
||||
|
||||
角色和 r／w／x 是平台授权模型，不增加 use 参数、源码权限位或逐函数的权限声明。代码可视域的具体语法另行定义，见[用户身份与 workspace 权限](../guide/02-user-identity.md)。
|
||||
|
||||
## 类与类型
|
||||
|
||||
```ebnf
|
||||
class-decl = "class", identifier, "{", { field-decl }, "}" ;
|
||||
class-decl = "class", identifier, "{", { class-member }, "}" ;
|
||||
class-member = field-decl | function-decl ;
|
||||
field-decl = identifier, ":", type-name ;
|
||||
type-name = identifier ;
|
||||
```
|
||||
|
||||
相关说明：[类型与类](../guide/07-types-and-classes.md)。
|
||||
|
||||
成员函数沿用 function 声明骨架；接收者、实例关联和类内名称查找未由这条产生式确定。
|
||||
|
||||
## Agent 声明骨架
|
||||
|
||||
```ebnf
|
||||
agent-decl = "agent", identifier, "{", { agent-member }, "}" ;
|
||||
agent-member = field-decl | binding | function-decl
|
||||
| class-decl | agent-decl ;
|
||||
```
|
||||
|
||||
此骨架是复用共有成员的语法提案，不是完整 agent 文法。工具关联、memory、state、路由、中断和上下文处理的专门关系尚未定义，不将这些职责名自动列为关键字或固定字段。成员中的表达式通过绑定或函数体出现，不能从允许共有成员推导任意语句可出现在任意位置。
|
||||
|
||||
agent 和 class 内部的名称查找、可见性、成员初始化及实例关联另行定义。骨架能表达成员函数，但未决定工具暴露范围；binding 仍只说明初始绑定，不决定重新赋值或共享状态。
|
||||
|
||||
相关说明：[Agent](../guide/13-agents.md)、[规范状态](specification-status.md#agent)。
|
||||
|
||||
## 函数与绑定
|
||||
|
||||
```ebnf
|
||||
@@ -57,6 +76,8 @@ return-stmt = "return", expression ;
|
||||
|
||||
本基本函数体文法只包含绑定和末尾返回，不覆盖完整控制流或独立表达式语句。
|
||||
|
||||
变量可以改变引用目标的语言模型已经确定，但可变变量声明、重新赋值和 let 可重绑性尚未确定，故不在此添加赋值产生式。
|
||||
|
||||
相关说明：[表达式与绑定](../guide/08-expressions-and-bindings.md)、[函数与调用](../guide/09-functions-and-calls.md)。
|
||||
|
||||
## 表达式
|
||||
|
||||
+24
-9
@@ -3,24 +3,39 @@
|
||||
| 术语 | 定义 | 详见 |
|
||||
| --- | --- | --- |
|
||||
| Endorphin | 用统一声明与调用模型描述前后端应用的云原生编程语言 | [语言概览](../guide/01-overview.md) |
|
||||
| 用户名 / handle | 在系统内唯一标识用户并参与代码定位的名称 | [用户身份](../guide/02-user-identity.md) |
|
||||
| 显示名 | 用于界面展示、可重复的姓名或昵称 | [用户身份](../guide/02-user-identity.md) |
|
||||
| 归属用户 | namespace key 指定的代码所属用户 | [用户身份](../guide/02-user-identity.md) |
|
||||
| 用户账号 | 用于登录、判断操作身份与记录作者的用户身份；不作为资源 key 前缀 | [用户身份与 workspace 权限](../guide/02-user-identity.md) |
|
||||
| Workspace 显示名 | 用于界面展示、可重复的 workspace 名称 | [Workspace handle 与显示名](../guide/02-user-identity.md#21-workspace-handle-与显示名) |
|
||||
| 归属 workspace | namespace key 指定的资源所属 workspace | [归属与操作身份](../guide/02-user-identity.md#24-归属-workspace操作用户与作者) |
|
||||
| 操作用户 | 发起本次读取、修改或执行的身份 | [用户身份](../guide/02-user-identity.md) |
|
||||
| namespace | 代码归属、组织与检索的单位 | [namespace](../guide/03-namespaces.md) |
|
||||
| namespace key | 用户名与非空 namespace 路径组成的定位标识 | [namespace](../guide/03-namespaces.md) |
|
||||
| workspace | 整体资源归属、协作与授权边界，内部通过 namespace 组织资源 | [Workspace 与平台用户系统](../guide/02-user-identity.md#25-workspace-与平台用户系统) |
|
||||
| workspace handle | 在平台内唯一定位 workspace 的名称，作为 key 冒号前的部分 | [Workspace handle 与显示名](../guide/02-user-identity.md#21-workspace-handle-与显示名) |
|
||||
| r／w／x | 读取、编辑资源与使用程序的操作类别；业务写入不自动要求调用者拥有编辑权 | [操作分工](../guide/02-user-identity.md#26-rwx-的操作分工) |
|
||||
| workspace 角色 | 在 workspace 范围授予常用权限组合与管理能力的成员角色 | [Workspace 角色与授权](../guide/02-user-identity.md#27-workspace-角色与授权) |
|
||||
| 代码可视域 | 声明可在什么程序位置被引用的范围，区别于平台用户权限 | [平台权限与代码可视域](../guide/02-user-identity.md#29-平台权限与代码可视域) |
|
||||
| namespace | 资源归属、组织与检索的单位；代码资源形成可见代码视图 | [namespace](../guide/03-namespaces.md) |
|
||||
| namespace key | workspace handle 与非空 namespace 路径组成的定位标识 | [namespace](../guide/03-namespaces.md) |
|
||||
| 代码段 | 独立存储、具有明确归属的代码内容单位 | [代码存储与视图](code-storage-and-views.md) |
|
||||
| 可见代码视图 | 由索引成员关系获得的 namespace 逻辑代码集合 | [代码存储与视图](code-storage-and-views.md) |
|
||||
| use | 引用完整 namespace key 的声明 | [程序结构与导入](../guide/04-program-structure.md) |
|
||||
| Preflight | 理解声明、检查程序并建立关联索引的执行准备阶段 | [Preflight 与 inflight](../guide/05-preflight-and-inflight.md) |
|
||||
| inflight | 使用实际输入执行逻辑并产生可观察结果的运行阶段 | [Preflight 与 inflight](../guide/05-preflight-and-inflight.md) |
|
||||
| 类型 | 描述值的结构及其允许用法的定义 | [类型与类](../guide/07-types-and-classes.md) |
|
||||
| Preflight | 定义准备与检查阶段；定义生命周期覆盖创建、准备、持续可引用、更新与退出 | [Preflight 与 inflight](../guide/05-preflight-and-inflight.md) |
|
||||
| inflight | 实际执行阶段；运行时生命周期覆盖调用、实例、任务及保存的运行状态 | [Preflight 与 inflight](../guide/05-preflight-and-inflight.md) |
|
||||
| 基础常量资源 | 数值、文本、媒体和 GIS 等不可原地修改的基础内容 | [资源、类型与类](../guide/07-types-and-classes.md#71-类型标注) |
|
||||
| 统一数值 | 不按整数位宽或浮点编码分型的数值类别；本文暂用 Number 命名 | [资源、类型与类](../guide/07-types-and-classes.md#71-类型标注) |
|
||||
| 格式归一化 | 接受的媒体和 GIS 格式导入后转写为内部标准格式，导出时再编码 | [资源、类型与类](../guide/07-types-and-classes.md#71-类型标注) |
|
||||
| 类型 | 描述资源或值的结构及其允许用法的定义 | [资源、类型与类](../guide/07-types-and-classes.md) |
|
||||
| 类型身份 | 由具体类型声明确定的身份；成员相同不自动使不同声明兼容 | [类型身份与兼容](../guide/07-types-and-classes.md#76-类型身份与兼容) |
|
||||
| class | 数据结构声明 | [类型与类](../guide/07-types-and-classes.md) |
|
||||
| class | 组织数据结构、字段和成员函数的声明 | [资源、类型与类](../guide/07-types-and-classes.md) |
|
||||
| 表达式 | 描述计算并产生值的源码形式 | [表达式与绑定](../guide/08-expressions-and-bindings.md) |
|
||||
| 绑定 | 将表达式结果关联到局部名称 | [表达式与绑定](../guide/08-expressions-and-bindings.md) |
|
||||
| 变量 | 可改变目标的资源引用；具体声明和赋值形式待定 | [变量与资源引用](../guide/08-expressions-and-bindings.md#86-变量与资源引用) |
|
||||
| 函数 | 定义输入、结果和执行逻辑的可调用声明 | [函数与调用](../guide/09-functions-and-calls.md) |
|
||||
| 数据依赖 | 后续计算需要前一计算结果的关系 | [函数与调用](../guide/09-functions-and-calls.md) |
|
||||
| agent | 复用共有成员并建立模型驱动执行与状态关联的语言资源声明 | [Agent](../guide/13-agents.md) |
|
||||
| tool | 关联为模型可选能力的函数，可以是外部引用或内部成员函数 | [Tools 与逻辑实现](../guide/13-agents.md#133-tools-与逻辑实现) |
|
||||
| memory | 信息保留与恢复的职责，包含会话记忆、检查点和长期记忆 | [Memory 与保存恢复](../guide/13-agents.md#134-memory-与保存恢复) |
|
||||
| state | 当前业务及执行状态，可用于有限状态机与条件路由 | [State、有限状态机与路由](../guide/13-agents.md#135-state有限状态机与路由) |
|
||||
| 执行检查点 | 保存恢复任务所需的状态、位置和待处理操作的运行时数据 | [Memory 与保存恢复](../guide/13-agents.md#134-memory-与保存恢复) |
|
||||
| 人工在环 | 在指定操作前暂停，等待人类确认或修改后再恢复 | [人工在环与中断](../guide/13-agents.md#136-人工在环与中断) |
|
||||
| 资源访问 | 定位并查看 namespace、声明或结果，或在输入就绪后发起调用的客户端行为 | [资源访问与呈现](../guide/11-resource-access-and-presentation.md) |
|
||||
| 按类型呈现 | 客户端依据当前资源或结果的类型选择处理方式；顶级类型及契约待定 | [资源访问与呈现](../guide/11-resource-access-and-presentation.md) |
|
||||
| 可渲染值 | 可由客户端作为界面呈现的结果值；正式类型及构造形式待定 | [资源访问与呈现](../guide/11-resource-access-and-presentation.md) |
|
||||
|
||||
@@ -7,18 +7,31 @@
|
||||
| 主题 | 已确定内容 |
|
||||
| --- | --- |
|
||||
| 语言定位 | 前后端共用的云原生编程语言，UI 是应用领域之一 |
|
||||
| 代码归属 | 每段代码属于唯一用户名和至少一级 namespace |
|
||||
| 用户身份 | 使用唯一 handle 定位，不用显示名替代 |
|
||||
| namespace | 各层语义一致；以外部 key 检索，不在正文声明自身归属 |
|
||||
| key 形式 | `用户名:namespace路径`，冒号分隔用户与路径，点号分隔层级 |
|
||||
| 资源归属 | 每项独立登记的资源属于一个 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 块 |
|
||||
| 资源访问 | 客户端可查看获准访问的资源，依据当前资源或调用结果的类型选择呈现方式 |
|
||||
| 函数查看与调用 | 必填参数未就绪时查看函数本身；输入满足调用要求后可调用并呈现结果；执行等待不退回为定义查看 |
|
||||
@@ -29,25 +42,44 @@
|
||||
| 提案 | 正文位置 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 词法与字面量 | [第 6 章](../guide/06-lexical-structure.md) | 本书统一采用的标识符、字符串、数字和符号形式 |
|
||||
| 类字段与类型标注 | [第 7 章](../guide/07-types-and-classes.md) | class 目标已确定，字段和类型体系仍为具体写法提案 |
|
||||
| 类字段、成员与类型标注 | [第 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 表示使用程序及其契约允许的业务效果。
|
||||
|
||||
尚未定义：
|
||||
|
||||
- 用户名的字符、长度、大小写、Unicode 归一化及身份范围扩展。
|
||||
- handle 改名、旧名称复用、历史引用稳定性及账号生命周期。
|
||||
- 代码的默认公开性、读取与执行权限，以及 namespace 权限继承。
|
||||
- 协作、Agent 委托、操作身份记录与归属转移。
|
||||
- 用户的登录标识、认证方式、展示名称及账号生命周期；这些信息不充当资源 key 前缀。
|
||||
- 资源的默认公开性、匿名访问、读取与执行授权的具体授予方式。
|
||||
- 操作身份、业务执行能力绑定、Agent 委托、操作记录与归属转移。
|
||||
- 入口的授权操作范围和业务效果约束；x 不自动提供任意直接资源编辑或管理员能力。
|
||||
|
||||
定位信息不构成授权，是这些规则必须保留的边界。
|
||||
|
||||
## Workspace 名称与生命周期
|
||||
|
||||
workspace 归属、key 前缀和整体授权模型已确定。名称细节、配额及运行授权的具体机制仍需定义。
|
||||
|
||||
尚未确定：
|
||||
|
||||
- 默认 workspace handle 的生成，以及历史用户名 key 的迁移或兼容规则。
|
||||
- workspace handle 的字符、大小写、唯一性比较、改名与复用、展示名称及稳定身份。
|
||||
- workspace 的创建数量上限、计数归属、加入与创建的区别、停用和删除后的额度处理。
|
||||
- 角色的正式名称、Reader 是否具有 x、仅执行授权的授予形式、公开或匿名访问及成员移除规则。
|
||||
- 管理员交接、workspace 停用、账号注销后的归属与资源保留，以及管理操作的完整范围。
|
||||
- 仅具有 x 时的调用接口信息范围，以及程序运行能力与资源编辑权限之间的具体执行机制。
|
||||
- 角色变更和授权撤销对正在执行、暂停或恢复中的调用、实例与任务的影响。
|
||||
|
||||
正文的 atelier、market key 前缀均解释为 workspace handle；alice、bob 仅在成员和作者示意中代表用户。
|
||||
|
||||
## 引用与代码视图
|
||||
|
||||
尚未定义：
|
||||
@@ -65,21 +97,50 @@
|
||||
|
||||
- 程序入口、空代码视图、客户端访问所用的定位形式与顶层绑定。
|
||||
- 函数本身的完整类型表达、值形式与查看信息范围。
|
||||
- 完整基础类型、数值范围、可选值、泛型及类型转换。
|
||||
- 类构造、方法、默认值、继承和字段可见性。
|
||||
- 完整类型命名、可选值、泛型及类型转换；基础资源的具体边界见下一节。
|
||||
- 类构造、成员函数的接收者与实例关联、默认值、继承和字段可见性。
|
||||
- 显式能力实现、类型兼容与转换关系的声明形式，以及类型推断规则。
|
||||
- 代码更新和不同版本之间的类型身份比较规则。
|
||||
- 重复声明、完整控制流、可变性、赋值和作用域细节。
|
||||
- 重复声明、完整控制流、实例及字段可变性、赋值和作用域细节。
|
||||
|
||||
本文简单函数体仅收录 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 版本与字符类别边界。
|
||||
- 换行字符、字符串扩展转义、更多字面量和运算符。
|
||||
- 数值溢出、除法、隐式转换与所有调用参数的求值顺序。
|
||||
- 数值精度与舍入、除法、隐式转换与所有调用参数的求值顺序；不按固定机器位宽定义数值溢出。
|
||||
|
||||
正文中同级二元算术运算的组合顺序属于表达式提案，不规定所有调用的执行顺序。
|
||||
|
||||
@@ -115,19 +176,36 @@
|
||||
|
||||
保留待讨论：
|
||||
|
||||
- 顶级类型的名称、集合，以及界面、数据、代码与媒体的类别边界。
|
||||
- 完整顶级类型的名称、集合及关系；已确定基础数值、文本、媒体和 GIS 类别，不代表完整类型层次已经确定。
|
||||
- 顶级类型采用继承、接口、协议或其他机制的关系与声明形式。
|
||||
- 可渲染类型的契约、普通类型的默认展示方式及自定义呈现。
|
||||
- 同一资源具有多种呈现能力时的选择规则及未知类型的处理方式。
|
||||
- 参数填写、默认或可省略参数、平台提供参数与访问触发调用的具体规则。
|
||||
- 资源查看、显式调用、可执行入口与具有业务修改效果的操作之间的界限。
|
||||
- 图片、字体等资源的标识、归属与类型约定。
|
||||
- 图片、字体等资源的具体标识、正式类型名与登记形式；独立保存的基础资源已纳入 namespace 归属方向。
|
||||
|
||||
顶级类型尚未纳入基础类型表或形式文法；其定义待定不影响已确定的访问与结果呈现方向。
|
||||
基础资源类别已在第 7 章说明；完整类型层次、展示契约和媒体构造形式仍待定，不因此向形式文法补写专用资源语法。
|
||||
|
||||
## Agent
|
||||
|
||||
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 整体管理。此决定替换原用户名归属模型；名称细节、迁移和仅执行授权等未定项不随之确定。
|
||||
|
||||
## 规范范围
|
||||
|
||||
|
||||
+11
-12
@@ -1,6 +1,6 @@
|
||||
# EX-01 把对话说明改成概念指南
|
||||
|
||||
读者目标：区分用户名与显示名，并判断哪个值用于 namespace key。依据是当前 guide/02-user-identity.md；以下成稿用于说明写作方法。
|
||||
读者目标：区分 workspace handle、显示名与用户身份，并判断哪个值用于 namespace key。依据是当前 guide/02-user-identity.md；以下成稿用于说明写作方法。
|
||||
|
||||
## 原稿
|
||||
|
||||
@@ -10,28 +10,28 @@
|
||||
|
||||
## 写作判断
|
||||
|
||||
先保留已确定的核心：handle 唯一；显示名用于展示；key 使用 handle。将未定义的字符、大小写和改名细节放入准确的边界说明。社交平台类比只用于辅助理解。
|
||||
原稿混合了用户身份与资源定位。按当前主定义改写：workspace handle 唯一；workspace 显示名用于展示；key 使用 workspace handle；用户负责操作和作者身份。将未定义的字符、大小写和改名细节放入准确的边界说明。
|
||||
|
||||
此处适合定义、两个对象的对照和一个 key 例子，不需要编造注册代码或身份认证 API。采用 DOC-001、004、013、015、018。
|
||||
|
||||
## 成稿示范
|
||||
|
||||
### 用户名与显示名
|
||||
### Workspace handle 与显示名
|
||||
|
||||
用户名（handle）用于唯一定位用户及其 namespace。显示名用于展示姓名或昵称，不承担唯一定位职责。
|
||||
Workspace handle 用于唯一定位 workspace 及其 namespace。workspace 显示名用于展示名称，不承担唯一定位职责。用户作为 workspace 成员参与协作，用户身份不充当资源 key 前缀。
|
||||
|
||||
两个用户可以使用相同的显示名“林”，但必须使用不同的用户名。例如，用户名为 alice 和 bob 的两位用户都可以将显示名设为“林”。
|
||||
两个 workspace 可以使用相同的显示名“工作室”，但必须使用不同的 handle。例如 atelier 与 market 都可以将显示名设为“工作室”。
|
||||
|
||||
| key | 定位的用户 | namespace 路径 |
|
||||
| key | 定位的 workspace | namespace 路径 |
|
||||
| --- | --- | --- |
|
||||
| `alice:shop` | alice | shop |
|
||||
| `bob:shop` | bob | shop |
|
||||
| `atelier:shop` | atelier | shop |
|
||||
| `market:shop` | market | shop |
|
||||
|
||||
这两个 key 指向不同的 namespace。查询时使用用户名，不能用相同的显示名替代冒号前的部分。
|
||||
这两个 key 指向不同的 namespace。查询时使用 workspace handle，不能用相同的显示名或某位成员的名字替代冒号前的部分。
|
||||
|
||||
代码归属使用完整 key，除用户名外还需要至少一级 namespace 路径。知道 key 只说明能够标识目标，不等于获得读取或执行权限。
|
||||
资源归属使用完整 key，除 workspace handle 外还需要至少一级 namespace 路径。成员变动不改变资源归属；知道 key 只说明能够标识目标，不等于获得读取或执行权限。
|
||||
|
||||
用户名的字符规则、大小写比较和改名行为尚未定义，参见语言文档中的“规范状态—身份与权限”。
|
||||
workspace handle 的字符规则、大小写比较和改名行为尚未定义，参见语言文档中的“规范状态—Workspace 名称与生命周期”。
|
||||
|
||||
## 为什么这样安排
|
||||
|
||||
@@ -47,4 +47,3 @@
|
||||
- 验证：这是基于当前文本规则的作者推演，没有调用身份系统。
|
||||
|
||||
[对应任务](../tasks/TASK-02.md) · [示例目录](README.md)
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
以下是故意包含错误的反例：
|
||||
|
||||
```text
|
||||
use alice.shop.ui::{Column, Text}
|
||||
use atelier.shop.ui::{Column, Text}
|
||||
```
|
||||
|
||||
> 导入后就能直接调用所有组件了。
|
||||
@@ -26,19 +26,19 @@ use alice.shop.ui::{Column, Text}
|
||||
|
||||
use 指定当前代码依赖的 namespace。它引用一个完整 namespace key。
|
||||
|
||||
代码归属：`bob:shop.checkout`。以下是该代码视图中的导入声明：
|
||||
代码归属：`market:shop.checkout`。以下是该代码视图中的导入声明：
|
||||
|
||||
```endorphin
|
||||
use alice:shop.pricing
|
||||
use atelier:shop.pricing
|
||||
```
|
||||
|
||||
| 部分 | 含义 |
|
||||
| --- | --- |
|
||||
| `alice` | 依赖来源的用户名 |
|
||||
| `:` | 用户名与 namespace 路径的分隔符 |
|
||||
| `atelier` | 依赖来源的 workspace handle |
|
||||
| `:` | workspace handle 与 namespace 路径的分隔符 |
|
||||
| `shop.pricing` | namespace 路径，点号分隔层级 |
|
||||
|
||||
该声明引用 alice 的定价 namespace。当前代码仍属于 bob:shop.checkout；引用目标不会改变自身归属。
|
||||
该声明引用 atelier workspace 的定价 namespace。当前代码仍属于 market:shop.checkout；引用目标不会改变自身归属。
|
||||
|
||||
每个 use 引用一个 namespace，不附加类名、函数名或选择性名称列表。引用用于指定依赖来源，不会自动执行其中的函数，也不构成访问授权。
|
||||
|
||||
@@ -46,11 +46,10 @@ use alice:shop.pricing
|
||||
|
||||
## 必须保留的区别
|
||||
|
||||
“完整 namespace 引用”不意味着“所有成员都自动可见”。官方 UI 组件来源尚未定义，也不能因为例子需要显示界面就将 Column 或 Text 放到 alice 的库名下。
|
||||
“完整 namespace 引用”不意味着“所有成员都自动可见”。官方 UI 组件来源尚未定义，也不能因为例子需要显示界面就将 Column 或 Text 放到 atelier 的库名下。
|
||||
|
||||
## 验收
|
||||
|
||||
读者可回答三件事：key 如何分解；当前代码属于谁；导入是否授予访问权。源码形状可由现有检查工具辅助检查，归属、授权和可见性说明需人工核对。
|
||||
|
||||
[对应任务](../tasks/TASK-03.md) · [示例目录](README.md)
|
||||
|
||||
|
||||
@@ -23,22 +23,22 @@ return discountedPrice(amount, 5)
|
||||
|
||||
下面采用本书的函数语法提案，展示成功调用的结果依赖。跨 namespace 引用采用目标函数可见、名称无冲突的条件。
|
||||
|
||||
代码归属：`alice:shop.pricing`。函数声明：
|
||||
代码归属：`atelier:shop.pricing`。函数声明：
|
||||
|
||||
```endorphin
|
||||
function discountedPrice(price: Int, discount: Int): Int {
|
||||
function discountedPrice(price: Number, discount: Number): Number {
|
||||
return price - discount
|
||||
}
|
||||
```
|
||||
|
||||
该函数从 price 中扣除 discount，并返回整数结果。
|
||||
该函数从 price 中扣除 discount，并返回数值结果；Number 沿用第 7 章的统一数值类型名提案。
|
||||
|
||||
代码归属：`bob:shop.checkout`。导入与调用方声明：
|
||||
代码归属：`market:shop.checkout`。导入与调用方声明：
|
||||
|
||||
```endorphin
|
||||
use alice:shop.pricing
|
||||
use atelier:shop.pricing
|
||||
|
||||
function payable(price: Int, discount: Int): Int {
|
||||
function payable(price: Number, discount: Number): Number {
|
||||
let amount = discountedPrice(price, discount)
|
||||
return discountedPrice(amount, 5)
|
||||
}
|
||||
@@ -53,7 +53,7 @@ function payable(price: Int, discount: Int): Int {
|
||||
|
||||
第二次调用使用第一次的结果。因此，在 amount 的成功结果可用前，后续调用不能把它当作已取得的值使用。上述语义在 inflight 中体现；Preflight 检查调用目标、参数和返回类型等可静态判断的约束。
|
||||
|
||||
这里展示成功路径。失败、缺失、未就绪的具体处理语法仍按规范状态记录，不能将它们当作整数 0。仅凭这段数据依赖也不能推出所有函数参数的求值顺序。
|
||||
这里展示成功路径。失败、缺失、未就绪的具体处理语法仍按规范状态记录，不能将它们当作数值 0。仅凭这段数据依赖也不能推出所有函数参数的求值顺序。
|
||||
|
||||
## 反向验证
|
||||
|
||||
@@ -66,4 +66,3 @@ function payable(price: Int, discount: Int): Int {
|
||||
DOC-004、009、010、011、013、015。代码、说明和结果表共同承担上下文与解释；不要求每个项目都单独显示一段“规则检查”。
|
||||
|
||||
[对应任务](../tasks/TASK-04.md) · [示例目录](README.md)
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
|
||||
## 建立有信息量的标题与链接
|
||||
|
||||
标题使用读者可能搜索的词，如“用户名与显示名”“导入后的名称引用”。链接文字指出目标主题，少用“这里”“详情”。同一页多个“注意事项”应改成各自的边界名称。
|
||||
标题使用读者可能搜索的词，如“Workspace handle 与显示名”“导入后的名称引用”。链接文字指出目标主题，少用“这里”“详情”。同一页多个“注意事项”应改成各自的边界名称。
|
||||
|
||||
跨章链接定位真正支持当前断言的页或小节。频繁相互跳转说明正文可能缺少一句局部定义，或章节职责需要重排。
|
||||
|
||||
@@ -39,4 +39,3 @@
|
||||
提示框保留会影响例子合法性或结果判断的信息。跨多页相同的设计稿声明保留统一入口；具体未定成员的局部假设仍放在例子旁。
|
||||
|
||||
[指南改写示例](../examples/EX-01.md) · [DOC-017](../rules/DOC-017.md) · [DOC-018](../rules/DOC-018.md) · [DOC-019](../rules/DOC-019.md)
|
||||
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
|
||||
先确定单一目标，再列以下字段：归属 key；依赖 key 与声明；片段位置；输入；成功结果；为什么产生该结果；相关边界；验证方式。
|
||||
|
||||
例如跨 namespace 的定价例子中，归属是 bob:shop.checkout，依赖是 alice:shop.pricing。discountedPrice 必须有声明依据，直接名称查找需有局部假设。输入 100 与 10 时，两次扣减得到 90 和 85。这个结果说明数据依赖，不证明远端执行顺序的全部规则。
|
||||
例如跨 namespace 的定价例子中，归属是 market:shop.checkout，依赖是 atelier:shop.pricing。market 与 atelier 都是 workspace handle。discountedPrice 必须有声明依据，直接名称查找需有局部假设。输入 100 与 10 时，两次扣减得到 90 和 85。这个结果说明数据依赖，不证明远端执行顺序的全部规则。
|
||||
|
||||
说明单可放在作者工作记录中；成稿将字段融入自然段、代码和结果表，不要求每个例子都显示八项元数据。
|
||||
|
||||
|
||||
@@ -19,17 +19,17 @@
|
||||
| 主题 | 应读取的文件 | 特别核对 |
|
||||
| --- | --- | --- |
|
||||
| 定位 | guide/01-overview.md；appendices/application-domains.md | 前后端与 Agent 的统一语言定位；不要写成只服务界面的 DSL |
|
||||
| 身份 | guide/02-user-identity.md | handle 唯一、显示名可重复；归属、操作身份与作者有区别；唯一不等于永久不变 |
|
||||
| namespace | guide/03-namespaces.md；appendices/code-storage-and-views.md | 用户名加至少一级路径；层级语义一致；归属来自外部索引，不从源码文件目录推导 |
|
||||
| 身份与权限 | guide/02-user-identity.md | workspace 是整体归属与授权边界，注册创建默认个人 workspace；用户承担操作与作者身份；w 编辑资源，x 使用程序及其业务效果，Reader 的执行权与具体授权机制未定 |
|
||||
| namespace | guide/03-namespaces.md；appendices/code-storage-and-views.md | workspace handle 加至少一级路径；各层语义一致；整体权限、视图成员和语言可视域分别判断，成员变化不自动改变 key |
|
||||
| 导入 | guide/04-program-structure.md | use 后是完整 key；导入不改变归属，不授予权限，不自动执行 |
|
||||
| 阶段 | guide/05-preflight-and-inflight.md | Preflight 与 inflight 大小写；阶段不等于前后端位置，也不是新增关键字 |
|
||||
| 阶段与生命周期 | guide/05-preflight-and-inflight.md | Preflight 与 inflight 大小写；定义长期存续归入 Preflight，调用与实例存续归入 inflight；长期保存的运行状态不是定义；阶段不等于执行位置 |
|
||||
| 词法 | guide/06-lexical-structure.md；appendices/formal-grammar.md | 草案中的标识符与字面量，不外推完整 Unicode、关键字或转义规则 |
|
||||
| 类型 | guide/07-types-and-classes.md | 用户声明的类型按声明身份区分，不凭成员相同自动兼容；class 不等于持久化实体、自动建表或自动具有 get |
|
||||
| 表达式 | guide/08-expressions-and-bindings.md | 结合与优先级不自动决定所有调用的求值顺序 |
|
||||
| 资源与类型 | guide/07-types-and-classes.md | 基础常量、统一数值和媒体/GIS 归一化已确定，具体数值精度与编码未定；Number 为类型名提案；名义类型不凭成员相同兼容，class 不自动建表或具有 get |
|
||||
| 表达式与变量 | guide/08-expressions-and-bindings.md | 变量可改变资源引用目标，不原地修改基础常量；let 可重绑性与赋值形式未定；结合与优先级不决定所有调用的求值顺序 |
|
||||
| 调用 | guide/09-functions-and-calls.md | 普通调用保留值、类型、依赖和业务效果；不能擅自并行、重试或假定纯函数 |
|
||||
| 数据 | guide/10-data-access.md | Product.get 是提案；业务 id 与 namespace key 不同；成功、缺失、失败、未就绪不能混写 |
|
||||
| 资源呈现与 UI | guide/11-resource-access-and-presentation.md；guide/12-ui-components.md | 普通函数返回可渲染值；函数查看、输入就绪与执行等待分别处理；顶级类型和构造形式未定，不补写专用 UI 文法或单根限制；官方组件来源未定 |
|
||||
| Agent | appendices/application-domains.md；appendices/specification-status.md | 应用方向不代表声明、工具、委托或权限语法已确定 |
|
||||
| Agent | guide/13-agents.md；appendices/specification-status.md | agent 已确认为语言资源；内部复用共有成员并承担工具、记忆、状态、路由、中断和上下文职责；骨架不代表成员关联、默认 API、委托或权限语法已确定 |
|
||||
|
||||
所有主题同时核对 appendices/specification-status.md。涉及词形、产生式或组合约束时再核对 appendices/formal-grammar.md；纯措辞修改不必重读全书。
|
||||
|
||||
@@ -45,6 +45,6 @@
|
||||
|
||||
先抄出两处冲突的具体断言，分别找到状态或用户决定依据。若只是旧写法残留，按明确决定修正并搜索同类残留；若实际需要新语义，完成不依赖该选择的部分，向用户提出最小必要决定。
|
||||
|
||||
例如，将错误的 use 点号分隔改回冒号是落实已确定规则；决定用户名是否大小写敏感则是新增语言决定。两者不应采用同一种处理方式。
|
||||
例如，将错误的 use 点号分隔改回冒号是落实已确定规则；决定 workspace handle 是否大小写敏感则是新增语言决定。两者不应采用同一种处理方式。
|
||||
|
||||
[语义契约](semantic-contracts.md) · [语义变更任务](../tasks/TASK-06.md)
|
||||
|
||||
@@ -30,7 +30,7 @@
|
||||
|
||||
**定位任务**：从目录或直接落到页中，找到一个具体约束。例如“use 会不会改变当前归属？”记录路径和最终依据；没有真人参与时只称作者走查。
|
||||
|
||||
**预测任务**：改变例子中的一个条件，预测结果或合法性。例如将 `alice:shop` 换成 `bob:shop` 后是否仍为同一 namespace；为什么？
|
||||
**预测任务**：改变例子中的一个条件，预测结果或合法性。例如将 `atelier:shop` 换成 `market:shop` 后是否仍为同一 namespace；或者 workspace 更换管理员后 key 是否变化；为什么？
|
||||
|
||||
检查针对本次改动选择，微小错字无需重新评估全书。结构、语义或示例改动要执行相关任务。真实读者测试需要记录任务、参与者背景和实际反馈，不能用作者自查代替。
|
||||
|
||||
@@ -45,4 +45,3 @@
|
||||
结构工具通过是最低的机械核对。具体改动还需有相应语义、读者任务或执行证据。报告中写明检查对象与限制，例如“走查导入参考的直接访问路径，已能在本页找到归属区别；未进行真人测试”。
|
||||
|
||||
[审查示例](../examples/EX-04.md) · [检查清单](../checklist.md) · [TPL-06](../templates/TPL-06.md)
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@
|
||||
|
||||
区分结构层和语义层。EBNF 能表达某个参数存在，不自动说明它的含义、范围和权限。同样，文字声称允许多个声明时，产生式也应允许；两者冲突时不能只改示例使检查通过。
|
||||
|
||||
对尚未定义的范围，不写“任意”“始终”“自动”“所有”这类全称断言。例如，简单用户名样例不证明全部用户名只能包含小写字母；namespace 层级不自动决定访问继承。
|
||||
对尚未定义的范围，不写“任意”“始终”“自动”“所有”这类全称断言。例如，简单 workspace handle 样例不证明全部 handle 只能包含小写字母；namespace 层级不自动决定视图成员范围。
|
||||
|
||||
## Preflight 与 inflight 的表达
|
||||
|
||||
@@ -42,9 +42,8 @@
|
||||
|
||||
从每条文字规则找到支持它的形式或例子；再从例子中的每个名称、调用和关键效果回到规则或明确假设。
|
||||
|
||||
例如 `use alice:shop.pricing` 支持“完整 key”这一形式，但不证明所有成员自动进入作用域。跨 namespace 调用例子还需说明目标可见、无名称冲突的局部条件。
|
||||
例如 `use atelier:shop.pricing` 支持“完整 key”这一形式，但不证明所有成员自动进入作用域。跨 namespace 调用例子还需说明目标可见、无名称冲突的局部条件。
|
||||
|
||||
核对详情记录在[TPL-05 变更工作单](../templates/TPL-05.md)即可，不必把作者的所有分析附在读者正文中。
|
||||
|
||||
[语言核对地图](language-map.md) · [参考成稿示例](../examples/EX-02.md) · [DOC-013](../rules/DOC-013.md)
|
||||
|
||||
|
||||
@@ -8,9 +8,9 @@
|
||||
|
||||
把主题拆成读者需要作出的判断。例如用户身份章节可让读者：
|
||||
|
||||
- 分辨 handle 和显示名，知道哪个进入 key。
|
||||
- 从同名路径识别不同用户的 namespace。
|
||||
- 区分归属用户、操作用户和作者。
|
||||
- 分辨 workspace handle 和显示名，知道哪个进入 key。
|
||||
- 从同名路径识别不同 workspace 的 namespace。
|
||||
- 区分归属 workspace、操作用户和作者。
|
||||
- 理解定位与访问权限的关系。
|
||||
|
||||
这些目标导出内容深度。账号认证协议、数据库身份表等不由“详细”一词自动纳入。
|
||||
@@ -42,4 +42,3 @@
|
||||
成稿示范见[EX-01](../examples/EX-01.md)。若改变章节位置，同时执行 TASK-05；若发现需要确认新语义，按 TASK-06 处理受影响部分。
|
||||
|
||||
[任务入口](../SKILL.md)
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
## 确定决定的准确边界
|
||||
|
||||
用一句话复述已获得的决定，列出它改变的断言和没有随之确定的维度。例如“use 使用 alice:shop.ui”确定用户与路径的分隔形式；不会同时确定用户名字符集、别名或冲突规则。
|
||||
用一句话复述已获得的决定，列出它改变的断言和没有随之确定的维度。例如“use 使用 atelier:shop.ui，atelier 是 workspace handle”确定 workspace 与路径的分隔形式；不会同时确定 handle 字符集、别名或冲突规则。
|
||||
|
||||
若用户只是要求解释得更清楚，先按现有规则改善文档。无法决定的新增语义保持具体未定状态，完成独立部分；仅当目标确实依赖新决定时请求最小必要澄清。
|
||||
|
||||
@@ -35,4 +35,3 @@
|
||||
若发现已有规则互相冲突却没有决定依据，交付具体冲突与候选影响，不能凭写作偏好确认语义。
|
||||
|
||||
[任务入口](../SKILL.md)
|
||||
|
||||
|
||||
+13
-12
@@ -6,35 +6,36 @@ Endorphin 是一门兼顾前端与后端的云原生编程语言。它用共享
|
||||
|
||||
## 1.1 应用模型
|
||||
|
||||
Endorphin 应用由相互引用的声明组成：
|
||||
Endorphin 应用由基础资源、变量引用和相互引用的声明组成。数值、文本、图片、视频、音频和 GIS 数据等基础内容由平台统一保存，变量指向这些资源，class 与 agent 组织更高级的结构。
|
||||
|
||||
| 声明 | 描述的内容 | 典型用途 |
|
||||
| --- | --- | --- |
|
||||
| 类 | 数据结构与字段类型 | 前后端共同理解商品数据 |
|
||||
| 函数 | 输入、计算和输出 | 计算价格、组合业务步骤、返回界面值 |
|
||||
| agent | 共有成员与模型驱动的执行规则 | 使用和实现工具、保留记忆、组织状态与控制流 |
|
||||
|
||||
客户端可以查看获准访问的资源，并按资源或函数结果的类型呈现内容。界面使用普通函数返回可渲染值表达，具体访问行为见[资源访问与呈现](11-resource-access-and-presentation.md)。
|
||||
|
||||
Agent 是后续扩展的应用领域；其声明与行为语法尚未定义，见[应用领域](../appendices/application-domains.md)。
|
||||
Agent 作为语言声明纳入 namespace，可以实现新逻辑并引用已有函数；其工具、记忆、状态及运行控制见[Agent](13-agents.md)。基础资源与变量引用模型见[资源、类型与类](07-types-and-classes.md)。
|
||||
|
||||
## 1.2 代码组织
|
||||
|
||||
每段代码属于一个用户和至少一级 namespace。用户通过唯一用户名标识，namespace 通过完整 key 定位，例如：
|
||||
每项独立登记的资源属于一个 workspace 和至少一级 namespace。workspace 通过唯一 handle 标识，namespace 通过完整 key 定位，例如：
|
||||
|
||||
```text
|
||||
alice:shop.pricing
|
||||
atelier:shop.pricing
|
||||
```
|
||||
|
||||
`alice` 是用户名，`shop.pricing` 是 namespace 路径。代码归属保存在外部上下文与索引中，正文无需声明自己的 namespace。
|
||||
`atelier` 是 workspace handle，`shop.pricing` 是 namespace 路径。用户以成员角色操作 workspace 中的资源；作者身份与资源归属分开记录。代码归属保存在外部上下文与索引中，正文无需声明自己的 namespace。
|
||||
|
||||
代码以独立代码段存储，通过索引形成 namespace 的可见代码视图。namespace 是语言的代码组织单位，源码文件不承担这一职责。
|
||||
|
||||
## 1.3 声明与调用
|
||||
|
||||
代码归属：`alice:shop.pricing`。该 namespace 定义价格计算函数：
|
||||
代码归属：`atelier:shop.pricing`。该 namespace 定义价格计算函数：
|
||||
|
||||
```endorphin
|
||||
function discountedPrice(price: Int, discount: Int): Int {
|
||||
function discountedPrice(price: Number, discount: Number): Number {
|
||||
return price - discount
|
||||
}
|
||||
```
|
||||
@@ -51,8 +52,8 @@ discountedPrice(100, 10) → 90
|
||||
|
||||
Endorphin 将程序处理划分为两个阶段：
|
||||
|
||||
- **Preflight**：理解声明与引用，检查名称、类型和程序结构，建立关联索引，准备执行。
|
||||
- **inflight**：使用实际输入解释执行逻辑，交付结果，并产生界面或其他业务效果。
|
||||
- **Preflight**：理解声明与引用，检查名称、类型和程序结构，建立关联索引；定义生命周期还覆盖准备后的持续可引用、更新与退出。
|
||||
- **inflight**：使用实际输入解释执行逻辑，交付结果；管理调用、实例和任务的存续、暂停与恢复，并产生界面或其他业务效果。
|
||||
|
||||
平台承担代码的解释执行；程序处理不要求开发者先完成独立构建，也不要求字节码转译。完整阶段职责见[Preflight 与 inflight](05-preflight-and-inflight.md)。
|
||||
|
||||
@@ -60,8 +61,8 @@ Endorphin 将程序处理划分为两个阶段：
|
||||
|
||||
## 1.5 本书范围
|
||||
|
||||
本书描述源码写法及其可观察行为，包括代码归属、声明、类型、表达式、调用、数据读取和 UI。通信协议、数据库绑定、缓存、部署和编排机制属于系统实现，不在语言介绍中展开。
|
||||
本书描述源码写法及其可观察行为，包括资源、代码归属、声明、类型、变量引用、调用、数据读取、UI 和 agent。通信协议、数据库绑定、缓存、部署和编排机制属于系统实现，不在语言介绍中展开。
|
||||
|
||||
下一章首先说明参与代码定位的用户身份，再介绍 namespace 与程序结构。
|
||||
下一章首先说明用户、workspace 与权限的关系，再介绍 namespace 与程序结构。
|
||||
|
||||
[下一章：用户身份](02-user-identity.md) · [目录](../README.md)
|
||||
[下一章：用户身份与 workspace 权限](02-user-identity.md) · [目录](../README.md)
|
||||
|
||||
+148
-37
@@ -1,77 +1,188 @@
|
||||
# 2. 用户身份
|
||||
# 2. 用户身份与 workspace 权限
|
||||
|
||||
用户身份是代码归属与 namespace 定位的基础。每个代码段必须关联一个归属用户，该用户以系统内唯一的用户名标识。
|
||||
用户身份确定谁在操作，资源归属确定操作的目标，权限确定允许进行哪些操作。平台用同一套身份与权限模型处理代码、基础内容和 agent；代码可视域另行决定声明在程序中的引用范围。
|
||||
|
||||
## 2.1 用户名与显示名
|
||||
workspace 是资源的整体归属、协作和授权边界。namespace key 使用 workspace handle 定位这一边界，用户身份用于登录、判断操作权限和记录作者。`w` 表示编辑资源，`x` 表示使用已定义的程序能力，程序产生业务写入不要求调用者因此成为 Editor。
|
||||
|
||||
用户名（handle）是用于定位用户的唯一名称，其作用类似社交平台的 `@` 名。显示名是用于界面展示的姓名或昵称，不承担唯一定位职责。
|
||||
## 2.1 Workspace handle 与显示名
|
||||
|
||||
| 属性 | 用户名 | 显示名 |
|
||||
| ---------------- | ------------------ | -------- |
|
||||
| 用途 | 唯一定位用户及其 namespace | 面向读者展示名称 |
|
||||
| 唯一性 | 在本系统内唯一 | 可以重复 |
|
||||
| 参与 namespace key | 是 | 否 |
|
||||
| 示例 | `alice` | `林` |
|
||||
Workspace handle 是在平台内唯一定位 workspace 的名称，参与 namespace key。workspace 显示名用于界面展示，可以重复，不承担唯一定位职责。
|
||||
|
||||
两个用户可以同时使用显示名“林”，但其用户名必须不同。检索代码时使用用户名，不能以显示名替代。
|
||||
| 属性 | Workspace handle | Workspace 显示名 |
|
||||
| --- | --- | --- |
|
||||
| 用途 | 唯一定位 workspace 及其 namespace | 面向用户展示名称 |
|
||||
| 唯一性 | 在本平台内唯一 | 可以重复 |
|
||||
| 参与 namespace key | 是 | 否 |
|
||||
| 示例 | `atelier` | `工作室` |
|
||||
|
||||
用户名的唯一性限定在本系统的身份范围内。其他系统中相同的用户名不自动表示同一用户。
|
||||
两个 workspace 可以都叫“工作室”，但其 handle 必须不同。例如 atelier 和 market 是两个 workspace；即使它们的显示名相同，其资源也分别定位。
|
||||
|
||||
## 2.2 key 中的用户部分
|
||||
用户账号与 workspace 是不同对象。一个用户可以参与多个 workspace，一个 workspace 可以有多个用户；资源地址不使用当前用户、管理员或作者的名字作为归属前缀。用户的登录标识及展示名称不决定资源 key，其具体形式见[规范状态](../appendices/specification-status.md#身份与权限)。
|
||||
|
||||
完整 namespace key 由用户名与非空 namespace 路径组成：
|
||||
## 2.2 key 中的 workspace 部分
|
||||
|
||||
namespace key 由 workspace handle 与非空 namespace 路径组成：
|
||||
|
||||
```text
|
||||
用户名:namespace路径
|
||||
alice:shop.ui
|
||||
workspace handle:namespace路径
|
||||
atelier:shop.ui
|
||||
```
|
||||
|
||||
冒号前的 `alice` 是用户名，不带 `@` 前缀；冒号后的 `shop.ui` 定位该用户名下的 namespace。
|
||||
冒号前的 `atelier` 是 workspace handle，不带 `@` 前缀；冒号后的 `shop.ui` 定位该 workspace 内的 namespace。
|
||||
|
||||
| key | 归属用户 | namespace 路径 |
|
||||
| key | 归属 workspace | namespace 路径 |
|
||||
| --- | --- | --- |
|
||||
| `alice:shop` | `alice` | `shop` |
|
||||
| `bob:shop` | `bob` | `shop` |
|
||||
| `alice:shop.ui` | `alice` | `shop.ui` |
|
||||
| `atelier:shop` | `atelier` | `shop` |
|
||||
| `market:shop` | `market` | `shop` |
|
||||
| `atelier:shop.ui` | `atelier` | `shop.ui` |
|
||||
|
||||
`alice:shop` 与 `bob:shop` 是不同的 namespace，即使它们具有相同的路径或相同的代码内容。
|
||||
`atelier:shop` 与 `market:shop` 是不同的 namespace，即使它们具有相同的路径或相同的代码内容。
|
||||
|
||||
只有用户名不能构成代码归属地址。代码必须同时属于至少一级 namespace，完整格式见[namespace](03-namespaces.md)。
|
||||
只有 workspace handle 不能构成 namespace key。独立登记的资源还需要至少一级 namespace，完整格式见[namespace](03-namespaces.md)。workspace 本身的管理入口不由 namespace key 文法定义。
|
||||
|
||||
## 2.3 归属上下文
|
||||
|
||||
用户身份通过代码之外的 key 与索引成员关系关联。读取、编辑和处理代码时，系统使用该归属上下文。
|
||||
资源与 workspace 的归属通过代码之外的 key 与索引成员关系关联。读取、编辑和处理代码时，系统使用该归属上下文。
|
||||
|
||||
函数名、变量名、注释、字符串和存储对象名均不定义归属用户。两段内容相同的代码分别关联不同用户时，其归属上下文仍然不同。
|
||||
函数名、变量名、注释、字符串和存储对象名均不定义归属 workspace。两段内容相同的代码分别关联不同 workspace 时，其归属上下文仍然不同。
|
||||
|
||||
正文中的 `use alice:shop.pricing` 表示引用目标，不表示当前代码属于 alice。例如，`bob:shop.checkout` 可以引用 alice 的逻辑，其自身归属仍是 bob。
|
||||
正文中的 `use atelier:shop.pricing` 表示引用目标，不表示当前代码属于 atelier。例如，`market:shop.checkout` 可以引用 atelier 的逻辑，其自身归属仍是 market。
|
||||
|
||||
## 2.4 归属用户、操作用户与作者
|
||||
## 2.4 归属 workspace、操作用户与作者
|
||||
|
||||
三种身份承担不同职责：
|
||||
归属主体与用户身份承担不同职责：
|
||||
|
||||
| 身份 | 含义 | 关联对象 |
|
||||
| --- | --- | --- |
|
||||
| 归属用户 | 代码位于谁的 namespace | namespace key 与代码成员关系 |
|
||||
| 归属 workspace | 资源位于哪个整体归属与授权范围 | namespace key 与资源成员关系 |
|
||||
| 操作用户 | 谁发起读取、修改或执行 | 本次操作的身份上下文 |
|
||||
| 作者或修改者 | 谁编写或修改了代码 | 编辑或历史记录 |
|
||||
|
||||
在协作授权存在的情况下，操作用户可以与归属用户不同。例如 bob 获得修改 `alice:shop` 的权限后，修改行为不会将目标自动改归 `bob:shop`。
|
||||
例如 alice 与 bob 同属 atelier，bob 修改 `atelier:shop` 的代码时，操作用户和修改者都是 bob，资源仍归属 atelier。退出成员关系或更换管理员不会把资源自动转移到某个用户的个人 workspace。
|
||||
|
||||
Agent 或服务代用户操作时同样需要区分操作身份与目标归属。协作、委托和历史记录的具体规则参见[规范状态](../appendices/specification-status.md#身份与权限)。
|
||||
|
||||
## 2.5 身份与访问权限
|
||||
## 2.5 Workspace 与平台用户系统
|
||||
|
||||
namespace key 是定位信息，不是访问凭据。知道用户名或 key，不等于获得读取、修改或调用其中声明的权限。
|
||||
workspace 是一组资源共同归属、协作和授权的整体，包含 namespace、函数、class、agent 及独立保存的基础内容。用户拥有自己的账号，可以创建 workspace，也可以加入其他 workspace；成员关系不改变用户身份。
|
||||
|
||||
代码归属与访问控制分别处理：归属确定目标，授权确定本次操作是否允许。代码默认公开性、跨用户可见性及权限继承规则不由 key 的结构推导。
|
||||
注册时创建用户账号，同时创建一个默认个人 workspace，并将注册用户设为该 workspace 的管理员。个人 workspace 和多人 workspace 使用同一模型，差别在于成员数量及其角色；个人 workspace 也可以邀请其他用户加入。
|
||||
|
||||
## 2.6 名称比较与生命周期
|
||||
平台可以限制每个用户创建 workspace 的数量。加入已有 workspace 与创建新 workspace 是不同操作，数量上限、计数归属和删除后的额度恢复规则待定。
|
||||
|
||||
注册、检索与改名必须使用一致的用户名相等判定。两个被判定为相同的用户名不能同时指向不同用户。
|
||||
| 概念 | 职责 | 是否随协作者变化而变化 |
|
||||
| --- | --- | --- |
|
||||
| 用户身份 | 认证操作用户、记录作者与修改者 | 每位用户独立存在 |
|
||||
| workspace | 承担整体资源归属与权限边界 | 成员变动不改变资源归属 |
|
||||
| workspace handle | 唯一定位 workspace | 改名与历史引用规则需单独定义 |
|
||||
| namespace | 在归属范围内组织和检索资源 | 不因加入一名成员自动增加一层路径 |
|
||||
|
||||
显示名不参与 key，修改显示名不改变代码归属。handle 的变更涉及既有 key 与引用的定位；旧名称复用还涉及历史引用是否继续指向原用户。
|
||||
同一 workspace 中可以包含多组 namespace，各组共享 workspace 的授权边界。成员与资源的关系示意如下：
|
||||
|
||||
用户名字符集合、大小写、Unicode 处理、改名、名称复用、账号停用和归属转移的具体规则集中列于[规范状态](../appendices/specification-status.md#身份与权限)。本书示例使用简单的小写用户名说明结构，不据此限定最终字符集。
|
||||
```text
|
||||
workspace：atelier
|
||||
成员：alice、bob
|
||||
|
||||
atelier:shop.pricing
|
||||
atelier:shop.data
|
||||
atelier:shop.agents
|
||||
```
|
||||
|
||||
alice 和 bob 编辑同一 workspace 的资源，作者记录各自的用户身份，资源仍归属 atelier。管理员变化或成员退出不要求重写 namespace 引用。默认 workspace 的 handle 如何生成、已有用户名 key 如何迁移，见[规范状态](../appendices/specification-status.md#workspace-名称与生命周期)。
|
||||
|
||||
## 2.6 r、w、x 的操作分工
|
||||
|
||||
三个权限字母表达资源操作的类别；具体角色及其授予范围在 2.7 的 workspace 模型中定义。
|
||||
|
||||
| 权限 | 允许的操作 | 不由该权限单独授予的能力 |
|
||||
| --- | --- | --- |
|
||||
| `r`：读取 | 浏览获准读取的代码、内容和资源视图 | 编辑资源、执行程序 |
|
||||
| `w`：编辑 | 创建、修改、删除资源内容或代码定义 | 修改成员角色、扩大授权 |
|
||||
| `x`：执行 | 调用已定义并允许外部使用的程序入口，取得契约允许的结果 | 任意改写实现源码或直接管理全部业务数据 |
|
||||
|
||||
`w` 与 `x` 的区别是编辑资源和使用程序。修改“提交订单”函数的定义需要 `w`；使用已经定义好的提交订单能力需要 `x`。该调用按业务契约保存订单，不要求调用用户获得函数源码的编辑权限。
|
||||
|
||||
同样，agent 在既定任务内执行获准业务操作与提交新的代码定义分别处理：使用 agent 的入口需要相应执行授权，向 namespace 保存或修改代码需要目标范围的 `w`。
|
||||
|
||||
程序的业务效果需要受定义好的操作范围、输入、业务条件及调用授权约束。`x` 不等于调用者获得管理员身份，也不表示能越过入口直接编辑任意资源。具体执行身份和运行能力如何关联仍待定义，不能用“有 x”推导出平台范围的无限授权。
|
||||
|
||||
读源码与使用软件可以分别授权。只有 `x` 的用户可以使用获准入口及调用所需的接口信息，而不因此获得完整实现源码的 `r`；接口信息的可见范围另行定义。读取函数不会自动运行它，执行后也只取得契约允许交付的结果。
|
||||
|
||||
高风险操作仍遵守[人工在环](13-agents.md#136-人工在环与中断)等既定执行条件。执行授权与人类确认承担不同职责。
|
||||
|
||||
## 2.7 Workspace 角色与授权
|
||||
|
||||
平台按 workspace 记录用户的角色，用角色提供常用权限组合。角色只在对应 workspace 生效，用户在一个 workspace 是管理员，不表示其在其他 workspace 也拥有管理能力。
|
||||
|
||||
| 角色或访问状态 | 权限基线 | 管理能力 |
|
||||
| --- | --- | --- |
|
||||
| 管理员 | `rwx` | 管理成员、角色及 workspace 设置 |
|
||||
| Editor | `rwx` | 编辑和使用资源，不管理授权 |
|
||||
| Reader | `r--` | 浏览资源，不修改资源 |
|
||||
| 无访问权限 | `---` | 无 |
|
||||
|
||||
管理员与 Editor 的资源权限相同，但管理成员和授权属于管理员角色的管理能力，不增加第四个资源权限位。Editor 不能通过修改普通资源或编写函数为自己授予管理员角色。
|
||||
|
||||
Reader 是否附带 `x`，以及如何向不读源码的用户授予 `--x`，保留为 workspace 层面的共享与运行授权选择，不为每个函数增加一份独立权限表。未获得 `r` 与完全无访问权限是不同状态；执行用户可以具有 `x` 而不具有 `r`。
|
||||
|
||||
角色作用于整个 workspace 的资源，不为每个 namespace、class、字段或函数分别维护访问名单。需要不同协作和授权边界的资源放入不同 workspace，workspace 内通过 namespace 与代码可视域组织结构。
|
||||
|
||||
公开或未加入 workspace 的用户也不能仅凭 key 获得访问权。默认公开性、匿名访问以及运行授权的授予方式仍待定义。
|
||||
|
||||
## 2.8 权限边界与 namespace
|
||||
|
||||
workspace 是整体授权边界，namespace 是内部组织与检索范围。一个用户获得 workspace 的读取权限，可以在该范围内读取资源；读取某个 namespace 时包含哪些成员，仍由视图成员规则决定。
|
||||
|
||||
```text
|
||||
用户在 workspace 中的角色与授权
|
||||
→ 允许的 r、w、x 操作
|
||||
→ 定位目标 namespace 与资源
|
||||
→ 按该操作和资源契约使用
|
||||
```
|
||||
|
||||
第一级和后续 namespace 层级具有相同语义，不在每层重新配置权限。权限适用整个 workspace 不等于每次读取父 namespace 都自动合并全部下级内容；授权范围与视图成员范围是两个维度。
|
||||
|
||||
namespace key 是定位信息，不是访问凭据。知道 workspace handle 或 key，不等于获得读取、修改或调用其中声明的权限。
|
||||
|
||||
## 2.9 平台权限与代码可视域
|
||||
|
||||
平台权限回答“这个操作用户能对目标资源做什么”，代码可视域回答“这个声明能否在当前代码位置被引用”。程序引用或调用需要分别满足对应的可视域与操作权限；查看实现源码则依据读取授权判断。
|
||||
|
||||
| 情况 | 需要判断的规则 |
|
||||
| ------------- | ------------------ |
|
||||
| 查看一个内部成员的源码 | 是否具有对应资源的读取权限 |
|
||||
| 外部函数直接引用该内部成员 | 是否满足声明可见性和名称查找规则 |
|
||||
| 导入并调用一个外部入口 | 是否可解析该入口，并具有对应执行授权 |
|
||||
| 修改入口或内部成员实现 | 是否具有目标范围的编辑权限 |
|
||||
|
||||
允许阅读源码不自动允许外部代码引用全部内部成员；声明允许外部引用也不自动向所有平台用户授予权限。use 指定依赖来源，不产生授权。
|
||||
|
||||
可视域可以在 namespace、class 或 agent 等程序结构中定义，不要求为每个内部声明建立用户权限表。具体可见性关键字、默认可视域和跨 namespace 名称查找见[程序结构与导入](04-program-structure.md#44-名称引用)。
|
||||
|
||||
## 2.10 操作身份、作者与 Agent
|
||||
|
||||
归属主体是 workspace，操作用户和作者是用户身份。作者记录表达谁编写或修改资源，不决定本次操作的权限。
|
||||
|
||||
agent 声明位于哪个 workspace，不直接决定本次运行以谁的权限执行。agent 引用一段代码、由管理员编写，或作为某个 workspace 的成员资源存在，都不自动获得管理员的管理能力。
|
||||
|
||||
编辑操作检查目标范围的 `w`；入口调用检查对应的 `x` 及业务契约。跨 workspace 调用分别判断目标范围的执行授权。角色或授权信息不要求写进每个函数的参数，也不因 use 改变。
|
||||
|
||||
程序如何取得操作身份、业务执行能力的绑定和委托、agent 生成代码的提交接口，以及异步任务恢复时的授权检查，仍待定义。
|
||||
|
||||
## 2.11 名称比较与生命周期
|
||||
|
||||
创建、检索与改名必须使用一致的 workspace handle 相等判定。两个被判定为相同的 handle 不能同时指向不同 workspace。
|
||||
|
||||
workspace 显示名不参与 key，修改显示名不改变资源归属。handle 的变更涉及既有 key 与引用的定位；旧名称复用还涉及历史引用是否继续指向原 workspace。
|
||||
|
||||
workspace handle 的字符集合、大小写、Unicode 处理、改名、名称复用和归属转移的具体规则集中列于[规范状态](../appendices/specification-status.md#workspace-名称与生命周期)。本书示例使用简单的小写 handle 说明结构，不据此限定最终字符集。
|
||||
|
||||
管理员交接、成员移除、workspace 停用，以及账号注销后的资源保留仍需明确。成员变化与资源归属分开处理；新请求按当前授权判断，已经运行的调用、实例或任务如何受到授权变化影响另行定义。
|
||||
|
||||
## 2.12 外部模型参考
|
||||
|
||||
Linux 文件权限使用所有者、组及其他用户的读、写、执行位，提供了操作类别的参考；本章的 workspace 角色及 `x` 的程序入口语义由 Endorphin 自行定义。[Linux inode 权限说明](https://man7.org/linux/man-pages/man7/inode.7.html)
|
||||
|
||||
Notion 将 workspace 成员关系与页面共享关联起来，提供了协作身份的参考。Endorphin 使用 workspace 整体授权，内部 namespace 负责组织资源。[Notion 成员与访客说明](https://www.notion.com/help/add-members-admins-guests-and-groups)
|
||||
|
||||
[上一章：语言概览](01-overview.md) · [下一章：namespace](03-namespaces.md) · [目录](../README.md)
|
||||
|
||||
+45
-19
@@ -1,38 +1,42 @@
|
||||
# 3. namespace
|
||||
|
||||
namespace 是代码归属、组织与检索的单位。系统使用 namespace key 查找索引，取得对应代码段，并形成可见代码视图。
|
||||
namespace 是资源归属、组织与检索的单位。对代码资源，系统使用 namespace key 查找索引，取得对应代码段，并形成可见代码视图。
|
||||
|
||||
函数、class 和 agent 定义，以及需要独立保存和引用的基础内容，都纳入这一组织体系。资源类别与变量引用见[资源、类型与类](07-types-and-classes.md)；非代码资源的登记和成员定位形式仍待定义，不由代码视图的语法推导。
|
||||
|
||||
workspace 确定资源的整体归属与授权边界，namespace 组织其内部资源。用户、角色及 r／w／x 分工的主定义见[用户身份与 workspace 权限](02-user-identity.md)。
|
||||
|
||||
## 3.1 key 格式
|
||||
|
||||
```text
|
||||
用户名:第一级namespace.后续namespace
|
||||
workspace handle:第一级namespace.后续namespace
|
||||
```
|
||||
|
||||
key 由一个用户名、一个冒号和至少一个 namespace 路径段组成。路径段之间用点号连接：
|
||||
key 由一个 workspace handle、一个冒号和至少一个 namespace 路径段组成。路径段之间用点号连接：
|
||||
|
||||
| key | 结构 |
|
||||
| --- | --- |
|
||||
| `alice:shop` | 用户名与一级 namespace |
|
||||
| `alice:shop.pricing` | 用户名与两级 namespace |
|
||||
| `alice:shop.backend.orders` | 用户名与三级 namespace |
|
||||
| `atelier:shop` | workspace handle 与一级 namespace |
|
||||
| `atelier:shop.pricing` | workspace handle 与两级 namespace |
|
||||
| `atelier:shop.backend.orders` | workspace handle 与三级 namespace |
|
||||
|
||||
key 中的用户名规则见[用户身份](02-user-identity.md)。namespace 路径段在本文词法草案中使用标识符，详见[词法结构](06-lexical-structure.md)。
|
||||
key 中的 handle 规则见[Workspace handle 与显示名](02-user-identity.md#21-workspace-handle-与显示名)。namespace 路径段在本文词法草案中使用标识符，详见[词法结构](06-lexical-structure.md)。
|
||||
|
||||
## 3.2 最小归属
|
||||
|
||||
代码必须同时具有用户和非空 namespace 路径。下列形式缺少必要信息：
|
||||
独立登记的资源必须同时具有归属 workspace 和非空 namespace 路径。下列形式缺少必要信息：
|
||||
|
||||
| 形式 | 缺少的内容 |
|
||||
| --- | --- |
|
||||
| `alice` 或 `alice:` | namespace 路径 |
|
||||
| `:shop` | 用户名 |
|
||||
| `alice.shop.ui` | 用户名与 namespace 的分隔冒号 |
|
||||
| 形式 | 缺少的内容 |
|
||||
| ---------------------- | ---------------------------------- |
|
||||
| `atelier` 或 `atelier:` | namespace 路径 |
|
||||
| `:shop` | workspace handle |
|
||||
| `atelier.shop.ui` | workspace handle 与 namespace 的分隔冒号 |
|
||||
|
||||
显示名不能替代用户名。代码也不能直接归属于没有 namespace 的用户根层级。
|
||||
workspace 显示名不能替代 handle。只有 workspace handle 不是完整 namespace key；workspace 本身的管理入口另行定义。
|
||||
|
||||
## 3.3 层级语义
|
||||
|
||||
用户之下的第一级 namespace 与所有后续层级具有相同语义。`shop` 在位置上类似 repository 那一层，但不构成独立的 repository 或特殊 module 类型。
|
||||
workspace 承担类似 repository 的整体资源与授权边界。其下第一级 namespace 与所有后续层级具有相同语义，`shop` 不构成额外权限边界或特殊 module 类型。
|
||||
|
||||
namespace 路径表示组织关系。路径段名 `ui`、`backend`、`data` 或 `agents` 不自动决定执行位置、数据存储、通信方式或语言阶段。
|
||||
|
||||
@@ -43,7 +47,7 @@ namespace 路径表示组织关系。路径段名 `ui`、`backend`、`data` 或
|
||||
代码以独立代码段存储，索引关联完整 key 与代码段。可见代码视图是根据这些成员关系获得的逻辑代码集合：
|
||||
|
||||
```text
|
||||
alice:shop.pricing
|
||||
atelier:shop.pricing
|
||||
→ namespace 索引
|
||||
→ 对应的独立代码段
|
||||
→ 可见代码视图
|
||||
@@ -56,10 +60,32 @@ alice:shop.pricing
|
||||
归属 key 定位当前代码，use key 定位它引用的代码。两者使用同一 key 格式，但承担不同职责：
|
||||
|
||||
```text
|
||||
当前代码：bob:shop.checkout
|
||||
引用目标：alice:shop.pricing
|
||||
当前代码：market:shop.checkout
|
||||
引用目标：atelier:shop.pricing
|
||||
```
|
||||
|
||||
当前代码的 key 由外部上下文提供；引用目标写入正文的 `use` 声明。引用不改变归属，也不自动授予访问权限。下一章说明声明与导入的组织方式。
|
||||
|
||||
[上一章：用户身份](02-user-identity.md) · [下一章：程序结构与导入](04-program-structure.md) · [目录](../README.md)
|
||||
## 3.6 Workspace 与资源成员
|
||||
|
||||
`atelier:pricing` 与 `atelier:shop.pricing` 都属于 atelier workspace。pricing 与 shop.pricing 是不同的内部路径，增加一层 namespace 不要求额外创建 workspace。
|
||||
|
||||
| 定位部分 | 职责 |
|
||||
| --- | --- |
|
||||
| workspace handle | 找到整体归属与授权边界 |
|
||||
| namespace 路径 | 找到内部资源组织与检索范围 |
|
||||
| 声明名或资源成员标识 | 在该范围内选择具体资源，成员定位形式仍待定义 |
|
||||
|
||||
成员加入、退出或管理员更换不改变 workspace 中资源的 key；handle 改名与资源迁移是独立操作。历史用户名 key 的迁移与默认 workspace 命名见[规范状态](../appendices/specification-status.md#workspace-名称与生命周期)。
|
||||
|
||||
## 3.7 整体权限与内部可视域
|
||||
|
||||
workspace 统一授予资源的 r、w、x 操作权限，不为每个 namespace 或其下级重复配置访问名单。namespace 层级组织内容，读取某层时的视图成员规则仍独立适用；权限覆盖整个 workspace 不表示父级视图自动包含所有下级内容。
|
||||
|
||||
类型和声明可视域决定程序能否引用一个成员，不代替平台授权。跨 workspace 调用要同时满足目标的语言可见性和执行授权；有权查看源码不自动允许外部程序引用内部成员。
|
||||
|
||||
`w` 用于编辑代码和资源内容，`x` 用于执行定义好的入口及其业务效果。调用产生业务数据不因此要求调用者取得整个 workspace 的编辑权限。图片等基础内容具有自己的类型用法，workspace 的 `x` 不将它们变成可调用函数。
|
||||
|
||||
具体角色、执行授权及其与管理能力的关系见[Workspace 角色与授权](02-user-identity.md#27-workspace-角色与授权)。use 的名称引入、声明组合与可视域见下一章。
|
||||
|
||||
[上一章：用户身份与 workspace 权限](02-user-identity.md) · [下一章：程序结构与导入](04-program-structure.md) · [目录](../README.md)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 4. 程序结构与导入
|
||||
|
||||
一个 namespace 的代码视图由导入和声明组成。声明描述类型、逻辑或界面；导入使代码能够引用其他 namespace 中允许使用的声明。
|
||||
一个 namespace 的代码视图由导入和声明组成。声明描述类型、逻辑、agent 或界面；导入使代码能够引用其他 namespace 中允许使用的声明。基础内容也可作为资源归属到 namespace，但其登记方式不由代码视图文法定义。
|
||||
|
||||
## 4.1 正文结构
|
||||
|
||||
@@ -8,55 +8,93 @@
|
||||
|
||||
```text
|
||||
零个或多个 use 声明
|
||||
一个或多个 class 或 function 声明
|
||||
一个或多个 class、function 或 agent 声明
|
||||
```
|
||||
|
||||
声明之间不使用逗号或分号。正文不含自身 namespace 声明，其归属来自外部 key 与索引。
|
||||
|
||||
“一个或多个”表示同一代码视图可以包含任意数量的这三类顶层声明，至少包含一个；不要求每类各出现一次，也不要求一个 namespace 只保存一个定义。
|
||||
|
||||
| 声明组合 | 表达的内容 |
|
||||
| -------------- | --------------------- |
|
||||
| 一个或多个 function | 一组可组合的逻辑入口或辅助计算 |
|
||||
| 一个或多个 class | 一组共享数据结构及其成员定义 |
|
||||
| 一个或多个 agent | 一组模型驱动的行为定义 |
|
||||
| 三类声明混合 | 类型、普通逻辑和 agent 共同组成程序 |
|
||||
|
||||
顶层声明与内部成员是不同位置。class 内的成员函数仍是 function，但属于类的成员作用域；agent 内的变量、函数或类型也保留其共有语义，并与 agent 实例或运行职责关联。内部成员不会仅因使用相同关键字自动成为 namespace 的顶层成员。
|
||||
|
||||
这里描述代码视图中的声明结构，不表示查看视图就实例化全部 class、启动全部 agent 或执行全部函数。函数体里的 let 和 return 仍遵守函数体规则，图片、文本等非代码资源的登记也不靠增加占位 class 或 function 表达。
|
||||
|
||||
agent 是语言声明，内部复用共有成员结构并增加 agent 作用域及运行关联。声明骨架仍为提案；工具、记忆和控制关联的具体写法见[Agent](13-agents.md)。
|
||||
|
||||
这是一份逻辑代码视图的语法结构，不规定独立代码段的存储粒度或物理排列。代码段边界及视图组装规则见[代码存储与视图](../appendices/code-storage-and-views.md)。
|
||||
|
||||
## 4.2 use 声明
|
||||
|
||||
代码归属：`bob:shop.checkout`。导入声明：
|
||||
代码归属：`market:shop.checkout`。导入声明：
|
||||
|
||||
```endorphin
|
||||
use alice:shop.pricing
|
||||
use atelier:shop.pricing
|
||||
```
|
||||
|
||||
`use` 后跟一个完整 namespace key。用户名与路径用冒号分隔，路径层级用点号分隔。每个 `use` 引用一个 namespace，不附加类名、函数名或选择性名称列表。
|
||||
`use` 后跟一个完整 namespace key。workspace handle 与路径用冒号分隔，路径层级用点号分隔。每个 `use` 引用一个 namespace，不附加类名、函数名或选择性名称列表。
|
||||
|
||||
引用整个 namespace 表示指定依赖来源，不表示获得访问权限或自动执行其中的函数。
|
||||
|
||||
## 4.3 声明组合
|
||||
|
||||
代码归属：`alice:shop.data`。
|
||||
代码归属：`atelier:shop.data`。
|
||||
|
||||
```endorphin
|
||||
class Product {
|
||||
name: String
|
||||
price: Int
|
||||
price: Number
|
||||
}
|
||||
|
||||
function listedPrice(product: Product): Int {
|
||||
function listedPrice(product: Product): Number {
|
||||
return product.price
|
||||
}
|
||||
```
|
||||
|
||||
同一视图可以同时包含类和函数。界面逻辑通过普通函数及其结果表达，与业务逻辑共用声明和表达式规则。
|
||||
同一视图可以同时包含类、函数和 agent。界面逻辑通过普通函数及其结果表达，与业务逻辑共用声明和表达式规则。
|
||||
|
||||
类与函数的内部结构分别在[类型与类](07-types-and-classes.md)和[函数与调用](09-functions-and-calls.md)中定义。查看资源和呈现界面结果见[资源访问与呈现](11-resource-access-and-presentation.md)。
|
||||
|
||||
以下是同一视图中的声明关系示意，不是完整源码。沿用 Product 与 listedPrice，agent 的工具关联形式尚未定义：
|
||||
|
||||
```text
|
||||
namespace 代码视图
|
||||
Product：class 定义
|
||||
listedPrice：function 定义，使用 Product
|
||||
定价 agent：agent 定义
|
||||
内部变量与辅助函数
|
||||
引用 listedPrice，或在内部实现其他工具逻辑
|
||||
```
|
||||
|
||||
这三项可以共同存在，但拥有各自的声明身份。agent 引用 listedPrice 不改变函数归属，也不把该函数自动变为 agent 的内部成员。类、函数或 agent 的声明先进入 Preflight 准备，其调用或实例使用属于 inflight。
|
||||
|
||||
声明之间的依赖不要求按执行顺序将所有代码写在一个文件里；视图顺序、前向引用与名称冲突仍按各自的规则确定。独立代码段是否与一条顶层声明对应，也不由此示意规定。
|
||||
|
||||
## 4.4 名称引用
|
||||
|
||||
导入后的声明必须依据可见性和名称查找规则使用。跨 namespace 示例采用“导入的名称可直接查找且没有冲突”的简化条件，用于展示调用含义；这不是对全部声明自动进入作用域的承诺。
|
||||
|
||||
名称限定、别名、同名冲突与可见性规则列于[规范状态](../appendices/specification-status.md#引用与代码视图)。官方 UI 组件的来源单独说明，不属于示例用户库。
|
||||
|
||||
名称解析、代码可视域和平台权限分别承担三个判断：找到哪个声明、当前代码位置能否引用它、操作身份能否对它进行本次操作。use 完成依赖表达，不替代后两个判断。
|
||||
|
||||
按已确定的操作分工，阅读源码使用 `r`，编辑定义使用 `w`，调用程序入口使用 `x`。业务调用可以按入口契约产生数据写入，不需要因为这一效果给调用用户整个归属范围的编辑权。只具有 `x` 时所需签名与接口信息如何提供，仍待定义，不能据此承诺全部源码可见。
|
||||
|
||||
平台权限统一放在 workspace 层，内部声明仍可以具有自己的语言可视域。一个用户即使拥有整个 workspace 的 `r`，外部函数也不能绕过成员可见性；允许外部引用的声明也不会自动向无授权用户开放。主定义见[平台权限与代码可视域](02-user-identity.md#29-平台权限与代码可视域)。
|
||||
|
||||
本文的 atelier 与 market 都是 workspace handle。编写、修改或调用代码的用户可以不同；成员变化不改变 use 中引用的 workspace。
|
||||
|
||||
## 4.5 程序与局部片段
|
||||
|
||||
本书区分三类示例：
|
||||
|
||||
- 声明示例：展示可以出现在代码视图中的类或函数。
|
||||
- 声明示例：展示可以出现在代码视图中的类、函数或 agent；未定关联形式采用结构示意。
|
||||
- 函数体片段：展示 let、return 或局部表达式。
|
||||
- 结构与访问示意：展示界面组成或资源访问行为，不表示源码。
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 5. Preflight 与 inflight
|
||||
|
||||
Endorphin 将执行准备与检查阶段称为 **Preflight**，将运行阶段称为 **inflight**。这两个名称表示程序处理职责，不是源码关键字。
|
||||
Endorphin 将定义准备与检查阶段称为 **Preflight**，将实际运行阶段称为 **inflight**。这两个名称同时用于区分定义的生命周期和运行时活动、实例的生命周期，不是源码关键字。
|
||||
|
||||
代码由平台解释执行，不要求开发者先执行独立构建步骤，也不要求将源码转换成字节码或另一种语言。Preflight 的检查与索引准备不等同于生成编译产物。
|
||||
|
||||
@@ -10,14 +10,14 @@ Preflight 读取代码视图及其归属上下文，理解声明和引用，并
|
||||
|
||||
其语言职责包括：
|
||||
|
||||
- 按词法和语法规则理解类、函数与表达式。
|
||||
- 按词法和语法规则理解类、函数、agent 与表达式。
|
||||
- 解析 use 指向的 namespace 及允许使用的声明。
|
||||
- 检查名称、字段、参数与返回类型。
|
||||
- 依据已定义的规则检查结果类型与组件用法。
|
||||
- 识别逻辑调用与结果使用之间的依赖。
|
||||
- 报告可以静态确定的错误。
|
||||
|
||||
声明函数不表示在 Preflight 中执行函数体，声明类也不表示读取业务数据。导入 namespace 用于理解依赖，而不是执行其所有逻辑。
|
||||
声明函数不表示在 Preflight 中执行函数体，声明类也不表示读取业务数据；声明 agent 不启动模型循环或调用工具。导入 namespace 用于理解依赖，而不是执行其所有逻辑。
|
||||
|
||||
## 5.2 inflight
|
||||
|
||||
@@ -31,6 +31,7 @@ inflight 使用实际输入执行程序，产生程序可以观察到的结果
|
||||
- 保持代码定义的数据依赖与业务效果。
|
||||
- 解释执行实际调用，并根据资源或结果类型产生界面等呈现效果。
|
||||
- 表达执行中出现的失败或其他结果状态。
|
||||
- 管理变量引用、对象和 agent 实例的存续，以及 agent 任务的状态迁移、暂停与恢复。
|
||||
|
||||
通信、缓存和执行组织方式可以由系统安排，但必须保持语言定义的值、类型、依赖和效果。
|
||||
|
||||
@@ -40,6 +41,7 @@ inflight 使用实际输入执行程序，产生程序可以观察到的结果
|
||||
| --- | --- | --- |
|
||||
| class 声明 | 理解字段及类型 | 在数据使用中遵守该结构 |
|
||||
| function 声明 | 检查参数、函数体与返回类型 | 调用发生时执行逻辑 |
|
||||
| agent 声明 | 理解成员、工具关联及状态与路由约束 | 创建实例，驱动任务、工具调用和状态迁移 |
|
||||
| use 声明 | 理解依赖并解析可用声明 | 在调用中使用相应逻辑 |
|
||||
| 调用表达式 | 检查目标与输入类型 | 使用实际输入并取得结果 |
|
||||
| 界面结果 | 依据已定义的类型与组件规则检查用法 | 取得可渲染值后呈现内容和排列关系 |
|
||||
@@ -56,10 +58,42 @@ inflight 使用实际输入执行程序，产生程序可以观察到的结果
|
||||
|
||||
阶段、应用角色和代码归属是不同维度：
|
||||
|
||||
- Preflight 与 inflight 表示处理阶段。
|
||||
- 前端、后端与 Agent 表示应用角色。
|
||||
- Preflight 与 inflight 表示处理阶段及相应的生命周期层次。
|
||||
- 前端、后端与 Agent 可表示应用角色；agent 同时具有独立的语言声明形式。
|
||||
- namespace key 表示代码归属与引用位置。
|
||||
|
||||
它们不要求一一对应，也不要求位于不同进程或机器。`alice:shop.ui` 的名称不会自动将其中所有代码限定在某个阶段或某类设备。
|
||||
它们不要求一一对应，也不要求位于不同进程或机器。`atelier:shop.ui` 的名称不会自动将其中所有代码限定在某个阶段或某类设备。
|
||||
|
||||
## 5.6 定义与运行时生命周期
|
||||
|
||||
**Preflight 生命周期**描述一个定义从创建、检查、建立引用关系，到持续可引用、更新或退出可用范围的存续。一次检查是其中的动作；检查完成不表示定义的生命周期结束。已保存的定义可以长期存在，并供多次 inflight 执行使用。
|
||||
|
||||
**inflight 生命周期**描述实际输入参与计算后，调用、对象、agent 实例和任务从产生、使用，到完成、释放或删除的存续。暂停或被保存的运行时状态仍属于这个层次，不因暂时没有代码执行而变成定义。
|
||||
|
||||
| 资源 | Preflight 生命周期中的定义 | inflight 生命周期中的实体或活动 |
|
||||
| --- | --- | --- |
|
||||
| function | 签名、函数体及引用关系的存续 | 每次调用的开始、执行、完成或失败 |
|
||||
| class | 类型、字段及成员定义的存续 | 每个对象实例的创建、使用、释放或删除 |
|
||||
| agent | 成员、工具、记忆和控制规则的定义存续 | 实例、上下文与任务的运行、等待、恢复和结束 |
|
||||
|
||||
函数调用结束不要求返回值同时消失。返回值可以继续被引用或保存；对象也不因创建它的调用结束而必然被回收。需要长期保留的实例、agent 记忆和任务检查点仍是 inflight 数据，其保留与删除规则需单独定义。
|
||||
|
||||
定义的退出、运行时实例的删除和底层内存回收是不同事件。删除定义是否影响已有调用或实例，以及不可达值何时回收，见[规范状态](../appendices/specification-status.md#生命周期与定义更新)。
|
||||
|
||||
传统 build time 常指构建发生的时段。这里的 Preflight 生命周期还覆盖准备后的定义存续，且不要求构建产物；不能把“定义长期存在”理解为平台一直在执行检查。
|
||||
|
||||
## 5.7 运行中产生新定义
|
||||
|
||||
两个生命周期可以交错。agent 可以在 inflight 中编写代码，将新定义提交到获准修改的 namespace；新定义经过 Preflight 的检查和引用准备后，才能用于后续执行。
|
||||
|
||||
```text
|
||||
agent 的 inflight 任务
|
||||
→ 编写并提交代码
|
||||
→ 新定义的 Preflight 检查与准备
|
||||
→ 定义成为可引用资源
|
||||
→ 后续 inflight 调用
|
||||
```
|
||||
|
||||
提交修改的行为属于正在运行的任务，新定义的检查属于 Preflight，新函数的执行属于下一次 inflight 调用。检查未通过的修改不能作为已就绪定义使用；版本选择、提交接口和协作冲突处理仍需独立规则。
|
||||
|
||||
[上一章：程序结构与导入](04-program-structure.md) · [下一章：词法结构](06-lexical-structure.md) · [目录](../README.md)
|
||||
|
||||
@@ -15,7 +15,7 @@ price
|
||||
product_1
|
||||
```
|
||||
|
||||
namespace 路径段使用标识符。用户名属于系统身份规则，不直接使用源码标识符的定义。
|
||||
namespace 路径段使用标识符。workspace handle 属于平台命名规则，不直接使用源码标识符的定义。
|
||||
|
||||
## 6.2 关键字
|
||||
|
||||
@@ -25,6 +25,7 @@ namespace 路径段使用标识符。用户名属于系统身份规则，不直
|
||||
| --- | --- |
|
||||
| `use` | 引用 namespace |
|
||||
| `class` | 声明数据结构 |
|
||||
| `agent` | agent 声明骨架使用的关键字提案 |
|
||||
| `function` | 声明函数 |
|
||||
| `let` | 绑定局部结果 |
|
||||
| `return` | 返回函数结果 |
|
||||
@@ -88,7 +89,7 @@ namespace 路径段使用标识符。用户名属于系统身份规则，不直
|
||||
| `=` | let 绑定 |
|
||||
| `+`、`-`、`*`、`/` | 算术运算 |
|
||||
|
||||
冒号的含义由语法位置确定：`alice:shop.data` 中分隔用户与路径，`price: Int` 中标注类型。组件参数的源码传入方式尚未定义，见[规范状态](../appendices/specification-status.md#ui)。
|
||||
冒号的含义由语法位置确定：`atelier:shop.data` 中分隔 workspace handle 与路径，`price: Number` 中标注类型。组件参数的源码传入方式尚未定义，见[规范状态](../appendices/specification-status.md#ui)。
|
||||
|
||||
## 6.7 空白与注释
|
||||
|
||||
@@ -106,4 +107,4 @@ return amount
|
||||
|
||||
词法产生式集中列于[形式文法](../appendices/formal-grammar.md#词法)。
|
||||
|
||||
[上一章：Preflight 与 inflight](05-preflight-and-inflight.md) · [下一章：类型与类](07-types-and-classes.md) · [目录](../README.md)
|
||||
[上一章：Preflight 与 inflight](05-preflight-and-inflight.md) · [下一章：资源、类型与类](07-types-and-classes.md) · [目录](../README.md)
|
||||
|
||||
@@ -1,40 +1,69 @@
|
||||
# 7. 类型与类
|
||||
# 7. 资源、类型与类
|
||||
|
||||
类型描述值的结构及其允许的用法。类型标注用于字段、函数参数和返回值，使不同应用部分能够依据同一声明理解数据。
|
||||
Endorphin 的资源模型从基础常量值开始：数值、文本以及图片、视频、音频和 GIS 数据等内容由平台统一保存和解释。变量保存对资源的引用；class 与 agent 在这些基础上组织更高级的结构。
|
||||
|
||||
类型描述资源或值的结构及其允许的用法。类型标注用于字段、函数参数和返回值，使不同应用部分能够依据同一声明理解数据。
|
||||
|
||||
## 7.1 类型标注
|
||||
|
||||
类型标注采用 `名称: 类型` 的形式：
|
||||
|
||||
```text
|
||||
price: Int
|
||||
price: Number
|
||||
name: String
|
||||
```
|
||||
|
||||
本文示例使用：
|
||||
|
||||
| 类型名 | 表达的值 |
|
||||
| --- | --- |
|
||||
| `Int` | 整数 |
|
||||
| `String` | 字符串 |
|
||||
| 用户声明的类名 | 属于该声明类型并满足字段约束的数据 |
|
||||
| 类型名 | 表达的值 |
|
||||
| -------- | ------------------------------ |
|
||||
| `Number` | 统一数值，包含整数与小数，不按机器位宽或浮点表示分成语言类型 |
|
||||
| `String` | 文本内容 |
|
||||
| 用户声明的类名 | 属于该声明类型并满足字段约束的数据 |
|
||||
|
||||
数值范围、其他基础类型、可选类型和转换规则尚未构成完整类型体系，范围见[规范状态](../appendices/specification-status.md#声明与类型)。
|
||||
`Number` 是本书采用的统一数值类型名提案，`String` 沿用文本类型名提案。基础资源类别已经确定，完整类型命名、精度和转换规则见[规范状态](../appendices/specification-status.md#基础资源与变量)。`String` 表示文本值，与第 12 章的 Text 界面组件不同。
|
||||
|
||||
### 基础常量资源
|
||||
|
||||
基础常量资源的内容不可原地修改。数字和文本可以通过字面量表达，媒体和 GIS 数据由平台接收并转换成类型化资源；它们不要求用户先声明 class。
|
||||
|
||||
| 基础类别 | 语言层面的内容 | 平台承担的表示工作 |
|
||||
| --- | --- | --- |
|
||||
| 数值 | 数字及其运算 | 选择可保存该数值的表示，不要求调用者选择 int32、float 等机器类型 |
|
||||
| 文本 | 字符与文本内容 | 保存和提供统一文本值 |
|
||||
| 图片 | 图像内容 | 导入转换、内部标准表示与导出编码 |
|
||||
| 视频 | 随时间变化的影像内容 | 导入转换、内部标准表示与导出编码 |
|
||||
| 音频 | 声音内容 | 导入转换、内部标准表示与导出编码 |
|
||||
| GIS 数据 | 地理空间内容 | 导入转换、统一空间数据表示与导出编码 |
|
||||
|
||||
数值表示以可表达和保存为优先目标，平台可以使用大数或其他可扩展表示，接受由此产生的性能成本。`100` 与 `1.5` 都属于统一数值类别，不因是否包含小数点而选择不同的机器类型。大数表示本身不决定除法、舍入或任意实数的精确性，这些算术规则仍需明确。
|
||||
|
||||
平台接受的媒体与 GIS 格式在导入后转写为各自的内部标准格式，导出时再编码为受支持的目标格式。业务代码面对图片、视频、音频或 GIS 数据的类型语义，无需为每种输入编码自行解析句柄和 buffer。修改基础内容产生新的内容值；变量可以改为引用新值。
|
||||
|
||||
具体标准格式、支持的导入与导出格式，以及转换中的精度、元数据和坐标系统规则另行定义。格式归一化不直接规定所有类别具有同一种文件编码，也不要求源码暴露平台内部的缓冲区。
|
||||
|
||||
### 资源与引用
|
||||
|
||||
基础值可以作为表达式结果、函数参数或返回值。变量是一项可改变目标的语言引用，可以指向基础常量资源，也可以指向函数、class 或 agent 定义及其可用实例；引用与实例的具体类型表达仍待定义。
|
||||
|
||||
这里的“指向”表达语言语义，不要求开发者处理裸内存地址、手动分配或释放。变量改变引用目标与修改基础常量内容是不同操作，详见[变量与资源引用](08-expressions-and-bindings.md#86-变量与资源引用)。
|
||||
|
||||
资源需要独立保存、分享或再次引用时，纳入用户与 namespace 的归属和检索体系。namespace 中资源的登记形式、资源成员定位和实例标识待定；临时值不因此自动获得永久名称。
|
||||
|
||||
## 7.2 class 声明
|
||||
|
||||
代码归属：`alice:shop.data`。
|
||||
代码归属：`atelier:shop.data`。
|
||||
|
||||
```endorphin
|
||||
class Product {
|
||||
name: String
|
||||
price: Int
|
||||
price: Number
|
||||
}
|
||||
```
|
||||
|
||||
该声明定义名为 `Product` 的数据结构，含有两个字段：`name` 为字符串，`price` 为整数。使用 Product 数据的代码依据同一结构读取字段，不需要为前端另写一份对应结构。
|
||||
该声明定义名为 `Product` 的数据结构，含有两个字段：`name` 为文本，`price` 为数值。使用 Product 数据的代码依据同一结构读取字段，不需要为前端另写一份对应结构。
|
||||
|
||||
类名是标识符。类体由字段声明组成，每个字段写出名称和类型，字段之间不使用逗号或分号。
|
||||
类名是标识符。本文最小示例展示字段声明，每个字段写出名称和类型，字段之间不使用逗号或分号。class 也可以组织成员函数；函数作为成员时需要类内作用域和实例关联规则，具体形式见[规范状态](../appendices/specification-status.md#声明与类型)。
|
||||
|
||||
## 7.3 类型与值
|
||||
|
||||
@@ -51,7 +80,7 @@ let name = product.name
|
||||
let price = product.price
|
||||
```
|
||||
|
||||
成员访问使用点号。第一行取得字符串字段，第二行取得整数字段。字段使用的类型由声明决定；读取不存在的字段不是有效的 Product 用法。
|
||||
成员访问使用点号。第一行取得文本字段，第二行取得数值字段。字段使用的类型由声明决定；读取不存在的字段不是有效的 Product 用法。
|
||||
|
||||
成员访问和 let 的表达式规则见下一章。
|
||||
|
||||
@@ -67,12 +96,12 @@ Endorphin 不采用仅依据成员结构判断兼容的结构类型规则。用
|
||||
|
||||
类型声明通过所属 namespace 与声明定位。引用同一个声明不创建新类型；不同声明不能仅凭名称或成员相同被认定为同一类型。
|
||||
|
||||
代码归属：`alice:shop.data`。沿用本章 Product 声明，并增加以下类声明：
|
||||
代码归属：`atelier:shop.data`。沿用本章 Product 声明，并增加以下类声明：
|
||||
|
||||
```endorphin
|
||||
class ListedProduct {
|
||||
name: String
|
||||
price: Int
|
||||
price: Number
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -32,7 +32,7 @@
|
||||
|
||||
同级二元算术运算在本文草案中按从左到右组合。`100 - 10 * 2` 先做乘法，结果为 `80`；`(100 - 10) * 2` 的结果为 `180`。
|
||||
|
||||
数值溢出、除法、隐式转换和其他运算符的规则见[规范状态](../appendices/specification-status.md#词法与表达式)。
|
||||
数值采用统一类别，不按固定机器位宽定义溢出；精度、除法、舍入、隐式转换和其他运算符的规则见[规范状态](../appendices/specification-status.md#词法与表达式)。
|
||||
|
||||
## 8.3 let 绑定
|
||||
|
||||
@@ -45,7 +45,7 @@ let payable = amount - 5
|
||||
|
||||
第一行将结果 `90` 绑定到 amount，第二行使用它得到 `85`。每个绑定包含关键字 `let`、局部名称、等号和表达式。
|
||||
|
||||
let 是结果绑定，不是 namespace 声明。本文函数文法将绑定放在函数体内；顶层绑定、重新赋值与可变性不由该语句推导。
|
||||
let 是结果绑定，不是 namespace 声明。变量可以改变引用目标的模型见 8.6；本节 let 示例只展示初始绑定，不据此决定 let 是否允许重绑、重新赋值的源码形式或顶层绑定规则。
|
||||
|
||||
## 8.4 成员访问
|
||||
|
||||
@@ -65,4 +65,28 @@ inflight 必须在结果可用后使用它，不能将未就绪状态替换为
|
||||
|
||||
表达式是否带有业务修改效果，以及失败、等待与取消的表示方式，由调用语义定义。算术的组合顺序不自动确定所有调用参数的求值顺序。
|
||||
|
||||
[上一章：类型与类](07-types-and-classes.md) · [下一章：函数与调用](09-functions-and-calls.md) · [目录](../README.md)
|
||||
## 8.6 变量与资源引用
|
||||
|
||||
变量保存对资源的引用，并可以在类型和作用域规则允许时改变引用目标。它可以引用数值、文本或媒体等基础常量，也可以引用函数、class、agent 及其可用实例。引用声明不会自动调用函数或创建实例。
|
||||
|
||||
下面是语义示意，不是赋值语法：
|
||||
|
||||
```text
|
||||
价格变量 → 数值常量 100
|
||||
改变引用目标
|
||||
价格变量 → 数值常量 90
|
||||
|
||||
图片变量 → 原图片资源
|
||||
改变引用目标
|
||||
图片变量 → 处理后产生的新图片资源
|
||||
```
|
||||
|
||||
这里变化的是变量的目标，原数值和原图片内容没有被原地修改。多个变量引用同一常量时，一个变量改指新值不要求其他变量同时改变目标。
|
||||
|
||||
高级结构可以通过成员变量组织资源引用；实例状态的变化与基础内容的不可变性可以同时成立。实例整体的可变性、字段更新、引用别名和相等性仍需明确规则，不由“变量类似指针”推导出裸地址或指针算术。
|
||||
|
||||
变量的创建、使用和引用更新属于 inflight。类型与作用域的准备属于 Preflight；变量或实例不再需要时的回收，以及保存后如何删除，见[生命周期](05-preflight-and-inflight.md#56-定义与运行时生命周期)。
|
||||
|
||||
可变变量的声明关键字、重新赋值、引用类型和 let 的可重绑性，见[规范状态](../appendices/specification-status.md#基础资源与变量)。本节确定引用模型，不补写尚未确认的赋值产生式。
|
||||
|
||||
[上一章：资源、类型与类](07-types-and-classes.md) · [下一章：函数与调用](09-functions-and-calls.md) · [目录](../README.md)
|
||||
|
||||
@@ -4,10 +4,10 @@
|
||||
|
||||
## 9.1 函数声明
|
||||
|
||||
代码归属：`alice:shop.pricing`。
|
||||
代码归属：`atelier:shop.pricing`。
|
||||
|
||||
```endorphin
|
||||
function discountedPrice(price: Int, discount: Int): Int {
|
||||
function discountedPrice(price: Number, discount: Number): Number {
|
||||
return price - discount
|
||||
}
|
||||
```
|
||||
@@ -18,8 +18,8 @@ function discountedPrice(price: Int, discount: Int): Int {
|
||||
| --- | --- |
|
||||
| `function` | 函数声明关键字 |
|
||||
| `discountedPrice` | 函数名 |
|
||||
| `price: Int, discount: Int` | 两个输入参数及其类型 |
|
||||
| 参数列表后的 `: Int` | 返回类型 |
|
||||
| `price: Number, discount: Number` | 两个输入参数及其类型 |
|
||||
| 参数列表后的 `: Number` | 返回类型 |
|
||||
| 花括号内的内容 | 函数体 |
|
||||
|
||||
参数按逗号分隔，每个参数都有名称与类型。本文基本函数体由零个或多个 let 绑定和一个末尾 return 组成；完整控制流另列于[规范状态](../appendices/specification-status.md#声明与类型)。
|
||||
@@ -28,16 +28,16 @@ function discountedPrice(price: Int, discount: Int): Int {
|
||||
|
||||
`return 表达式` 产生函数结果。表达式的类型必须符合返回类型。
|
||||
|
||||
discountedPrice 返回两个整数的差值。对于输入 `100` 与 `10`，成功结果为 `90`。定义函数不立即执行它；执行发生在 inflight 调用中。
|
||||
discountedPrice 返回两个数值的差值。对于输入 `100` 与 `10`，成功结果为 `90`。定义函数不立即执行它；执行发生在 inflight 调用中。
|
||||
|
||||
## 9.3 跨 namespace 调用
|
||||
|
||||
代码归属：`bob:shop.checkout`。
|
||||
代码归属：`market:shop.checkout`。
|
||||
|
||||
```endorphin
|
||||
use alice:shop.pricing
|
||||
use atelier:shop.pricing
|
||||
|
||||
function payable(price: Int, discount: Int): Int {
|
||||
function payable(price: Number, discount: Number): Number {
|
||||
let amount = discountedPrice(price, discount)
|
||||
return discountedPrice(amount, 5)
|
||||
}
|
||||
@@ -49,12 +49,12 @@ payable 引用定价 namespace，先使用原价与优惠额计算 amount，再
|
||||
|
||||
## 9.4 调用组合
|
||||
|
||||
代码归属：`bob:shop.ui`。业务函数声明：
|
||||
代码归属：`market:shop.ui`。业务函数声明：
|
||||
|
||||
```endorphin
|
||||
use bob:shop.checkout
|
||||
use market:shop.checkout
|
||||
|
||||
function checkoutAmount(): Int {
|
||||
function checkoutAmount(): Number {
|
||||
return payable(100, 10)
|
||||
}
|
||||
```
|
||||
@@ -72,7 +72,7 @@ checkoutAmount 的成功结果为 `85`。它不需要重复实现价格计算，
|
||||
- return 表达式是否符合返回类型。
|
||||
- 使用调用结果的后续表达式是否合法。
|
||||
|
||||
例如，discountedPrice 需要两个整数参数。`discountedPrice(100)` 数量不符；`discountedPrice("100", 10)` 在本文不进行隐式字符串到整数转换的示例条件下类型不符。
|
||||
例如，discountedPrice 需要两个数值参数。`discountedPrice(100)` 数量不符；`discountedPrice("100", 10)` 在本文不进行隐式文本到数值转换的示例条件下类型不符。
|
||||
|
||||
## 9.6 inflight 行为
|
||||
|
||||
|
||||
@@ -4,12 +4,12 @@
|
||||
|
||||
## 10.1 数据结构
|
||||
|
||||
代码归属：`alice:shop.data`。商品结构沿用第 7 章的 Product：
|
||||
代码归属：`atelier:shop.data`。商品结构沿用第 7 章的 Product：
|
||||
|
||||
```endorphin
|
||||
class Product {
|
||||
name: String
|
||||
price: Int
|
||||
price: Number
|
||||
}
|
||||
```
|
||||
|
||||
@@ -19,18 +19,18 @@ class Product {
|
||||
|
||||
> 语法提案：本节用 `Product.get(...)` 表达“通过类取得数据”。get 的存在与声明方式尚未定义，该写法不是所有 class 自动拥有的成员。
|
||||
|
||||
代码归属：`bob:shop.checkout`。读取函数示例，采用 Product 与读取成员均可访问的条件；成功路径中，读取成员接收一个 String 标识并返回 Product，其正式声明语法仍未定义：
|
||||
代码归属：`market:shop.checkout`。读取函数示例，采用 Product 与读取成员均可访问的条件；成功路径中，读取成员接收一个 String 标识并返回 Product，其正式声明语法仍未定义：
|
||||
|
||||
```endorphin
|
||||
use alice:shop.data
|
||||
use atelier:shop.data
|
||||
|
||||
function productPrice(id: String): Int {
|
||||
function productPrice(id: String): Number {
|
||||
let product = Product.get(id)
|
||||
return product.price
|
||||
}
|
||||
```
|
||||
|
||||
调用参数 id 表达所需数据的标识，不是 namespace key。`alice:shop.data` 定位数据结构与逻辑来源，id 指定本次业务对象。
|
||||
调用参数 id 表达所需数据的标识，不是 namespace key。`atelier:shop.data` 定位数据结构与逻辑来源，id 指定本次业务对象。
|
||||
|
||||
成功调用 productPrice 后，返回值应为取得商品的 price 字段。结果已经具有 Product 结构，调用方无需先解析 HTTP 响应或手动转换传输数据。
|
||||
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
# 11. 资源访问与呈现
|
||||
|
||||
客户端是 Endorphin 资源的查看与运行环境。它可以访问获准查看的 namespace、函数、类和结果值，并根据当前资源的类型及访问状态选择呈现方式。
|
||||
客户端是 Endorphin 资源的查看与运行环境。它可以访问获准查看的 namespace、函数、类、agent、基础内容和结果值，并根据当前资源的类型及访问状态选择呈现方式。
|
||||
|
||||
界面由普通函数返回的可渲染值表达，不使用独立的 scene 声明或 render 块。本章定义资源定位、函数查看、调用与结果呈现之间的关系；顶级类型及其契约仍待定义，见[规范状态](../appendices/specification-status.md#资源访问与呈现)。
|
||||
|
||||
## 11.1 资源定位与访问
|
||||
|
||||
namespace key 定位代码归属及检索范围，函数名或类名选择其中的声明。定位声明、查看定义与发起调用是不同的访问行为。
|
||||
namespace key 定位资源归属及检索范围，函数名、类名或 agent 名选择其中的声明。定位声明、查看定义与发起调用是不同的访问行为；基础内容和实例的成员标识形式仍待定义。
|
||||
|
||||
```text
|
||||
namespace：alice:shop.pricing
|
||||
namespace：atelier:shop.pricing
|
||||
声明：discountedPrice
|
||||
|
||||
namespace：alice:shop.data
|
||||
namespace：atelier:shop.data
|
||||
声明：Product
|
||||
```
|
||||
|
||||
@@ -20,13 +20,17 @@ namespace：alice:shop.data
|
||||
|
||||
| 访问对象 | 当前资源的含义 | 呈现或使用方式 |
|
||||
| --- | --- | --- |
|
||||
| namespace | 获准访问的逻辑代码集合 | 查看代码视图及其成员 |
|
||||
| namespace | 获准访问的资源组织范围 | 查看允许访问的成员；代码成员形成代码视图 |
|
||||
| 函数定义 | 参数、返回类型与函数体 | 查看定义，或准备相应调用 |
|
||||
| 类定义 | 类型及其结构 | 查看类型定义，不自动取得业务对象 |
|
||||
| agent 定义 | 成员、工具及运行控制规则 | 查看定义，不自动创建实例或启动任务 |
|
||||
| 基础内容 | 数值、文本、媒体或 GIS 数据的类型化内容 | 按内容类型使用或呈现，导入编码不直接决定语言类型 |
|
||||
| 函数调用结果 | 本次执行产生的值 | 按结果类型呈现，或供后续程序使用 |
|
||||
|
||||
查看 namespace 不表示执行其中全部函数，也不保证包含全部下级 namespace。查看定义的权限与调用权限分别适用；代码定位本身不授予权限。
|
||||
|
||||
读取实现源码使用 r，编辑资源使用 w，使用已定义的程序能力使用 x。调用按业务契约产生写入不因此要求调用者获得整个归属范围的编辑权；只有 x 时的接口信息范围和执行身份仍待定义，见[用户身份与 workspace 权限](02-user-identity.md#26-rwx-的操作分工)。
|
||||
|
||||
## 11.2 函数本身与返回值
|
||||
|
||||
函数本身具有可调用的类型，调用完成后取得的值具有结果类型。二者不能混同；尚未调用时，返回类型描述结果约束，不表示结果已经存在。
|
||||
@@ -34,14 +38,14 @@ namespace：alice:shop.data
|
||||
以下示例使用[函数与调用](09-functions-and-calls.md)中的声明，假定 discountedPrice 可查看且可调用：
|
||||
|
||||
```text
|
||||
查看 alice:shop.pricing 中的 discountedPrice
|
||||
查看 atelier:shop.pricing 中的 discountedPrice
|
||||
→ 取得函数定义
|
||||
|
||||
提供 price = 100、discount = 10 并调用
|
||||
→ 取得结果 90
|
||||
```
|
||||
|
||||
前一种访问查看函数本身，后一种访问处理整数结果。函数没有因为参数未填写而改变类型。
|
||||
前一种访问查看函数本身，后一种访问处理数值结果。函数没有因为参数未填写而改变类型。
|
||||
|
||||
## 11.3 参数就绪与调用状态
|
||||
|
||||
@@ -64,7 +68,7 @@ namespace：alice:shop.data
|
||||
|
||||
函数使用普通参数、表达式、调用与 return 表达界面逻辑。客户端取得可渲染类型的结果后渲染界面；其他结果依据相应类型的呈现约定处理。界面构造表达式与可渲染类型的正式名称尚未定义，本章不引入占位类型或专用 UI 文法。
|
||||
|
||||
下面是访问行为示意，不是源码。假定 `bob:shop.ui` 中存在可访问的 productPage，接收一个商品编号，并返回可渲染值：
|
||||
下面是访问行为示意，不是源码。假定 `market:shop.ui` 中存在可访问的 productPage，接收一个商品编号，并返回可渲染值：
|
||||
|
||||
```text
|
||||
打开 productPage，尚未提供商品编号
|
||||
@@ -96,7 +100,7 @@ namespace：alice:shop.data
|
||||
|
||||
## 11.6 按类型呈现的边界
|
||||
|
||||
按资源类型选择处理方式是客户端的呈现方向。顶级类型的名称、集合、继承或协议关系，以及不同类型对应的展示契约，统一保留在[规范状态](../appendices/specification-status.md#资源访问与呈现)中。
|
||||
按资源类型选择处理方式是客户端的呈现方向。基础数值、文本、媒体与 GIS 类别及其格式归一化见[资源、类型与类](07-types-and-classes.md)；agent 的使用语义见[Agent](13-agents.md)。完整顶级类型名称、继承或协议关系，以及不同类型对应的展示契约，统一保留在[规范状态](../appendices/specification-status.md#资源访问与呈现)中。
|
||||
|
||||
平台不能仅凭对象字段或方法的结构认定其属于可渲染类型或实现了展示能力。类型身份与兼容规则见[类型与类](07-types-and-classes.md#76-类型身份与兼容)；具体展示能力关系仍待定义。
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
本章保留官方基础组件的参数、默认值和展示效果提案。组件用于组成普通函数返回的界面值，资源与结果的呈现方式见[资源访问与呈现](11-resource-access-and-presentation.md)。
|
||||
|
||||
官方库的 key、引用形式、组件构造表达式和界面类型尚未定义。本章示例是 `bob:shop.ui` 的界面结构示意，不是源码，也不表示官方组件属于该用户库或必然免导入可用。用户库提供的组件以其实际声明为准。
|
||||
官方库的 key、引用形式、组件构造表达式和界面类型尚未定义。本章示例是 `market:shop.ui` 的界面结构示意，不是源码，也不表示官方组件属于该 workspace 的库或必然免导入可用。用户编写的组件以其实际声明为准。
|
||||
|
||||
## 12.1 Column
|
||||
|
||||
@@ -84,4 +84,4 @@ Text：内容为 Shop，role 为 .title
|
||||
|
||||
本章组件参数与默认值属于 UI 提案，确定程度与其他语言主题一起记录在规范状态附录。
|
||||
|
||||
[上一章：资源访问与呈现](11-resource-access-and-presentation.md) · [附录：形式文法](../appendices/formal-grammar.md) · [目录](../README.md)
|
||||
[上一章：资源访问与呈现](11-resource-access-and-presentation.md) · [下一章：Agent](13-agents.md) · [目录](../README.md)
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
# 13. Agent
|
||||
|
||||
agent 是与 class、function 并列、可归属于 namespace 的语言资源声明。它为共有的变量、函数和其他合法结构建立 agent 内部作用域，并将这些成员与模型驱动的执行、工具使用、记忆、状态和控制流关联起来。
|
||||
|
||||
agent 的语言地位和本章各项职责已经确定；声明骨架及成员关联的具体写法仍是设计稿，见[规范状态](../appendices/specification-status.md#agent)。这些能力由语言与平台共同提供，不以安装某个宿主语言的 Agent 包作为声明前提。
|
||||
|
||||
## 13.1 声明、成员与作用域
|
||||
|
||||
agent 声明拥有名称和 namespace 归属。内部使用 Endorphin 共有的变量、函数、class 和其他允许的声明或表达式；每种结构仍遵守自身的语法位置与类型规则。允许共有结构不表示可以在任意位置直接使用 return 等语句。
|
||||
|
||||
基本结构示意，不是可执行源码：
|
||||
|
||||
```text
|
||||
agent 名称 {
|
||||
成员变量与资源引用
|
||||
成员函数
|
||||
成员类型或其他合法声明
|
||||
工具、记忆、状态及控制规则的关联
|
||||
}
|
||||
```
|
||||
|
||||
同一个 function 定义在 agent 内部时仍是函数；区别在于它的名称查找、可见范围以及与所属 agent 实例的关联。变量同样保留引用资源的语义，但实例成员需要明确状态归属和存续范围。内部作用域与 namespace 路径及成员定位的对应关系仍待定义。
|
||||
|
||||
成员可以服务于普通计算、工具实现、状态迁移或上下文处理。哪些成员函数向模型暴露为工具，以及是否存在默认暴露规则，仍需定义；声明骨架本身不决定这个范围。成员可见性、实例成员与共享成员的区分、嵌套声明和接收者引用形式也需明确。
|
||||
|
||||
Agent 的输入与结果需要类型契约，可以通过入口或成员函数表达，具体形式待定；声明体不预设固定的 input、output、instructions、environment 字段表。模型配置和行为指令可以参与声明，但不替代工具及运行控制语义。
|
||||
|
||||
## 13.2 运行职责
|
||||
|
||||
| 职责 | 使用的共有资源或结构 | agent 内部需要建立的关系 |
|
||||
| --- | --- | --- |
|
||||
| tools | 外部函数引用或内部成员函数 | 哪些函数向模型提供工具能力，以及怎样调用它们 |
|
||||
| memory | 记忆内容、读写函数及保存策略 | 内容如何保留、检索，以及运行状态如何保存和恢复 |
|
||||
| state | 类型化变量与数据结构 | 当前业务状态、执行位置及允许的迁移 |
|
||||
| 控制流与路由 | 函数、条件逻辑及节点关联 | 下一步执行工具、继续模型计算、等待输入或终止 |
|
||||
| 人工在环 | 待执行操作、暂停状态及人类输入 | 哪些操作需要确认，以及确认后如何恢复 |
|
||||
| 上下文管理 | 文本、资源引用及处理函数 | 每次模型调用前如何选择、裁剪或总结输入 |
|
||||
|
||||
这些名称首先表示职责，不自动成为保留字、固定字段或新的资源类型。职责如何通过普通成员和语言关联结构表达，需与完整文法一起确定；本章不规定全部职责必须以同一种声明形式出现。
|
||||
|
||||
## 13.3 Tools 与逻辑实现
|
||||
|
||||
工具以函数为基础。agent 可以引用其他 namespace 中获准使用的函数，也可以在内部实现成员函数，再将其关联为可供模型选择的工具。内部工具仍使用普通表达式、调用和类型规则，不要求另一套工具函数语言。
|
||||
|
||||
每个关联工具应有可检查的目标、参数和结果类型，并使模型能够理解其用途。工具描述、关联形式和模型参数到类型化实参的转换规则待定；仅有名称或描述文本不足以替代真实函数定义。
|
||||
|
||||
```text
|
||||
外部函数引用或内部成员函数
|
||||
→ 关联为工具
|
||||
→ 模型提出工具选择及参数
|
||||
→ 平台检查目标、实参与执行条件
|
||||
→ inflight 函数调用
|
||||
→ 类型化结果进入后续逻辑
|
||||
```
|
||||
|
||||
模型提出调用意图不表示函数已经执行。参数或执行条件不满足时，不能将调用描述当作成功结果；关联为工具也不增加函数的访问权限。
|
||||
|
||||
agent 还可以编写一套新的逻辑，在其中组合已有函数，执行临时代码，或将定义提交到获准修改的 namespace。新的可执行定义必须经过 Preflight；生成、提交和执行之间的生命周期见[运行中产生新定义](05-preflight-and-inflight.md#57-运行中产生新定义)。工具使用不限制 agent 只能选择现成函数。
|
||||
|
||||
## 13.4 Memory 与保存恢复
|
||||
|
||||
memory 承担信息保留与恢复，至少需要区分三种用途：
|
||||
|
||||
| 用途 | 保存的内容 | 使用时机 |
|
||||
| ----- | ------------------ | ----------- |
|
||||
| 会话记忆 | 消息、工具结果及本次任务上下文 | 同一会话继续工作 |
|
||||
| 执行检查点 | 恢复所需的状态、执行位置和待处理操作 | 暂停后恢复或故障后继续 |
|
||||
| 长期记忆 | 需要跨任务使用的事实、偏好或知识 | 后续任务检索并使用 |
|
||||
|
||||
memory 的声明与保存策略属于定义层；实际消息、检查点和记忆内容属于 inflight。保存后的运行状态不会因此变成 Preflight 定义，任务完成也不自动删除全部记忆。
|
||||
|
||||
外部术语参考：LangGraph 将检查点和跨会话的长期存储分开；其 MemorySaver／InMemorySaver 在内存中保存检查点，本身不保证进程重启后的保留。Endorphin 应明确保存范围、保留时长和恢复能力，而不是直接照搬这个构造器名称。[LangGraph 持久化说明](https://docs.langchain.com/oss/python/langgraph/persistence)
|
||||
|
||||
平台承担底层保存与读取，agent 使用类型化的记忆内容和操作。实例隔离、共享记忆、检查点粒度、保留策略、删除与恢复一致性尚待定义。
|
||||
|
||||
## 13.5 State、有限状态机与路由
|
||||
|
||||
state 表达当前业务与执行状态，memory 表达如何保留和恢复信息。state 可以被保存进 memory，但二者不是同一种职责。
|
||||
|
||||
有限状态机需要定义状态集合、当前状态、迁移条件及迁移效果。控制流与路由依据当前状态、函数结果或外部输入，决定下一步。函数可以承担节点逻辑或路由计算，节点如何声明和关联仍需定义。
|
||||
|
||||
```text
|
||||
当前状态与节点输入
|
||||
→ 执行本节点逻辑
|
||||
→ 取得结果并更新状态
|
||||
→ 按条件选择下一步
|
||||
→ 工具调用
|
||||
→ 下一次模型计算或其他节点
|
||||
→ 等待用户输入
|
||||
→ 终止本次任务
|
||||
```
|
||||
|
||||
模型的建议需要经过已声明的路由和迁移规则才能改变执行位置。等待输入不等于成功完成；任务终止与整个 agent 实例结束也分别处理。
|
||||
|
||||
完整条件、循环、状态类型、迁移与节点关联语法待定。有限状态机是 agent 应支持的控制形式，不要求每个普通成员变量都成为一个状态机节点。
|
||||
|
||||
## 13.6 人工在环与中断
|
||||
|
||||
涉及发邮件、扣款、删除数据库等高风险操作时，agent 必须在操作发生前暂停，等待人类确认或修改意见。中断需要保存待执行操作、相关参数、当前状态和恢复所需的位置，并将请求交付给用户。
|
||||
|
||||
```text
|
||||
形成待执行操作
|
||||
→ 保存恢复所需的状态
|
||||
→ 暂停并请求人类决定
|
||||
→ 确认、拒绝或修改
|
||||
→ 检查恢复输入与操作条件
|
||||
→ 继续执行、重新规划或结束
|
||||
```
|
||||
|
||||
等待期间不得执行待确认的操作。确认应对应具体操作及参数；参数改变时，原确认不能直接覆盖新操作。恢复不能任意重复已经完成的业务修改。
|
||||
|
||||
LangGraph 的中断机制提供“保存状态、等待外部输入、恢复执行”的参考，但其具体 API 和节点重启规则不自动成为 Endorphin 语义。[LangGraph 中断说明](https://docs.langchain.com/oss/python/langgraph/interrupts)
|
||||
|
||||
风险判定、审批关联、确认有效期、恢复接口及重复效果控制的具体规则见[规范状态](../appendices/specification-status.md#agent)。
|
||||
|
||||
## 13.7 上下文选择、裁剪与总结
|
||||
|
||||
每次模型调用前，上下文管理逻辑从指令、消息、state、memory、工具结果及其他资源中构造输入，并按所用模型的输入容量进行检查。
|
||||
|
||||
超出容量时，可以选择相关内容、裁剪历史或进行增量总结。完整保存的记忆与本次送入模型的上下文是不同集合；裁剪模型输入不自动删除原始记忆或待审批操作。
|
||||
|
||||
裁剪和总结策略可以由 agent 内的函数实现，也可以引用已有能力。处理后仍应保留当前任务、必要的工具契约、关键状态及待处理控制信息；具体保留规则、预算计算、摘要类型和失败处理待定。输入长度控制不单独保证模型输出的事实正确性。
|
||||
|
||||
## 13.8 定义、实例与任务的生命周期
|
||||
|
||||
| 层次 | 所属生命周期 | 含义 |
|
||||
| --- | --- | --- |
|
||||
| agent 声明 | Preflight | 定义成员、工具关联、记忆与控制规则，并供引用 |
|
||||
| agent 实例 | inflight | 持有具体状态和上下文，执行或等待任务 |
|
||||
| 一次任务 | inflight | 具有本次输入、执行过程、暂停或完成状态及结果 |
|
||||
|
||||
引用 agent 声明不自动创建实例或启动任务。一个定义可用于多个实例；实例之间的状态归属与共享必须明确。任务完成后，实例可以继续存在；长期记忆的保留由其自身规则决定。
|
||||
|
||||
Preflight 检查可静态确定的成员、函数类型、引用关系和控制约束；inflight 执行实际模型交互、函数调用、状态迁移、记忆读写及中断恢复。模型选择和业务调用仍可能在运行时失败，检查通过不能替代结果与状态检查。
|
||||
|
||||
实例化、任务交付、对外入口、实例标识和版本更新的具体形式仍待定义。本章不为它们补造 start、run 或 submit 等默认 API。
|
||||
|
||||
[上一章：UI 组件](12-ui-components.md) · [附录：形式文法](../appendices/formal-grammar.md) · [目录](../README.md)
|
||||
+1
-1
@@ -30,7 +30,7 @@ git diff --check
|
||||
|
||||
不抓取外部链接，不校验完整 Markdown 标准、引用式链接、HTML 链接或所有渲染器的扩展语法。不解析完整 Endorphin 文法、不执行类型检查或程序，也不检验自然语言正确性和真实可用性。
|
||||
|
||||
use 检查只判断基本结构，不制定用户名字符规范。词法与源码语义仍需按正文和文法人工核对。
|
||||
use 检查只判断基本结构，不制定 workspace handle 字符规范。词法与源码语义仍需按正文和文法人工核对。
|
||||
|
||||
## 退出状态
|
||||
|
||||
|
||||
Reference in New Issue
Block a user