Document workspace ownership, resource semantics and agent lifecycle

This commit is contained in:
2026-10-09 18:06:25 +08:00
parent f7526ab2a0
commit 52f497671e
31 changed files with 748 additions and 232 deletions
+11 -12
View File
@@ -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 -8
View File
@@ -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)
+7 -8
View File
@@ -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)
+1 -2
View File
@@ -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)
+1 -1
View File
@@ -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。这个结果说明数据依赖,不证明远端执行顺序的全部规则。
说明单可放在作者工作记录中;成稿将字段融入自然段、代码和结果表,不要求每个例子都显示八项元数据。
+7 -7
View File
@@ -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)
+1 -2
View File
@@ -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)
+2 -3
View File
@@ -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)
+3 -4
View File
@@ -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)
+1 -2
View File
@@ -6,7 +6,7 @@
## 确定决定的准确边界
用一句话复述已获得的决定,列出它改变的断言和没有随之确定的维度。例如“use 使用 alice:shop.ui”确定用户与路径的分隔形式;不会同时确定用户名字符集、别名或冲突规则。
用一句话复述已获得的决定,列出它改变的断言和没有随之确定的维度。例如“use 使用 atelier:shop.ui,atelier 是 workspace handle”确定 workspace 与路径的分隔形式;不会同时确定 handle 字符集、别名或冲突规则。
若用户只是要求解释得更清楚,先按现有规则改善文档。无法决定的新增语义保持具体未定状态,完成独立部分;仅当目标确实依赖新决定时请求最小必要澄清。
@@ -35,4 +35,3 @@
若发现已有规则互相冲突却没有决定依据,交付具体冲突与候选影响,不能凭写作偏好确认语义。
[任务入口](../SKILL.md)