Document workspace ownership, resource semantics and agent lifecycle

guide/01-overview.md

@@ -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)

guide/02-user-identity.md

@@ -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)

guide/03-namespaces.md

@@ -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)

guide/04-program-structure.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 或局部表达式。
 - 结构与访问示意：展示界面组成或资源访问行为，不表示源码。
 

guide/05-preflight-and-inflight.md

@@ -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)

guide/06-lexical-structure.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)

guide/07-types-and-classes.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
 }
 ```
 

guide/08-expressions-and-bindings.md

@@ -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)

guide/09-functions-and-calls.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 行为
 

guide/10-data-access.md

@@ -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 响应或手动转换传输数据。
 

guide/11-resource-access-and-presentation.md

@@ -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-类型身份与兼容)；具体展示能力关系仍待定义。
 

guide/12-ui-components.md

@@ -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)

guide/13-agents.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)