docs: develop task-guided Endor authoring skill and detailed handbook
This commit is contained in:
@@ -0,0 +1,50 @@
|
||||
# EX-01 把对话说明改成概念指南
|
||||
|
||||
读者目标:区分用户名与显示名,并判断哪个值用于 namespace key。依据是当前 guide/02-user-identity.md;以下成稿用于说明写作方法。
|
||||
|
||||
## 原稿
|
||||
|
||||
> 用户就是我们之前说的那个意思,有点像推特。你可以叫任何名字,但是查的时候肯定不能都一样。所以我们还是用一个唯一名字吧,具体之后再考虑。
|
||||
|
||||
问题不在使用口语本身,而在读者无法知道“任何名字”指哪个字段、“唯一”约束谁、查询使用什么,以及哪些部分已经确定。
|
||||
|
||||
## 写作判断
|
||||
|
||||
先保留已确定的核心:handle 唯一;显示名用于展示;key 使用 handle。将未定义的字符、大小写和改名细节放入准确的边界说明。社交平台类比只用于辅助理解。
|
||||
|
||||
此处适合定义、两个对象的对照和一个 key 例子,不需要编造注册代码或身份认证 API。采用 DOC-001、004、013、015、018。
|
||||
|
||||
## 成稿示范
|
||||
|
||||
### 用户名与显示名
|
||||
|
||||
用户名(handle)用于唯一定位用户及其 namespace。显示名用于展示姓名或昵称,不承担唯一定位职责。
|
||||
|
||||
两个用户可以使用相同的显示名“林”,但必须使用不同的用户名。例如,用户名为 alice 和 bob 的两位用户都可以将显示名设为“林”。
|
||||
|
||||
| key | 定位的用户 | namespace 路径 |
|
||||
| --- | --- | --- |
|
||||
| `alice:shop` | alice | shop |
|
||||
| `bob:shop` | bob | shop |
|
||||
|
||||
这两个 key 指向不同的 namespace。查询时使用用户名,不能用相同的显示名替代冒号前的部分。
|
||||
|
||||
代码归属使用完整 key,除用户名外还需要至少一级 namespace 路径。知道 key 只说明能够标识目标,不等于获得读取或执行权限。
|
||||
|
||||
用户名的字符规则、大小写比较和改名行为尚未定义,参见语言文档中的“规范状态—身份与权限”。
|
||||
|
||||
## 为什么这样安排
|
||||
|
||||
首段给出两个定义,第二段用重复显示名解释唯一性,表格把概念落到定位结果,最后限定归属和权限的关系。未定义细节被准确命名,读者仍能理解当前已确定的模型。
|
||||
|
||||
真正放回正文时应把状态主题写成仓库内实际链接;此页刻意使用标题定位,以保持示范可随 skill 包迁移。
|
||||
|
||||
## 验收
|
||||
|
||||
- 复述:读者应指出 handle 负责定位,显示名负责展示。
|
||||
- 预测:相同显示名不使两个 key 指向同一 namespace。
|
||||
- 边界:本例不支持“handle 永久不变”或“key 公开可调用”的结论。
|
||||
- 验证:这是基于当前文本规则的作者推演,没有调用身份系统。
|
||||
|
||||
[对应任务](../tasks/TASK-02.md) · [示例目录](README.md)
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
# EX-02 为 use 编写可独立查询的参考
|
||||
|
||||
读者目标:写出完整引用,并区分当前归属与引用来源。依据是当前 guide/04-program-structure.md 和规范状态。
|
||||
|
||||
## 原稿
|
||||
|
||||
以下是故意包含错误的反例:
|
||||
|
||||
```text
|
||||
use alice.shop.ui::{Column, Text}
|
||||
```
|
||||
|
||||
> 导入后就能直接调用所有组件了。
|
||||
|
||||
这段同时混淆 key 分隔符、选择性导入、官方组件归属和名称可见性。仅把点号改成冒号仍不能修复其余断言。
|
||||
|
||||
## 写作判断
|
||||
|
||||
先确定 use 的职责:指定依赖 namespace。选择已经用于用户逻辑的 pricing 例子,交代使用方的外部归属。把官方组件引用、权限、别名和冲突等不同问题分开说明。
|
||||
|
||||
采用 DOC-008、009、012、013、015。成稿不需要返回类型表;它需要结构、上下文和引用效果。
|
||||
|
||||
## 成稿示范
|
||||
|
||||
### use 声明
|
||||
|
||||
use 指定当前代码依赖的 namespace。它引用一个完整 namespace key。
|
||||
|
||||
代码归属:`bob:shop.checkout`。以下是该代码视图中的导入声明:
|
||||
|
||||
```endorphin
|
||||
use alice:shop.pricing
|
||||
```
|
||||
|
||||
| 部分 | 含义 |
|
||||
| --- | --- |
|
||||
| `alice` | 依赖来源的用户名 |
|
||||
| `:` | 用户名与 namespace 路径的分隔符 |
|
||||
| `shop.pricing` | namespace 路径,点号分隔层级 |
|
||||
|
||||
该声明引用 alice 的定价 namespace。当前代码仍属于 bob:shop.checkout;引用目标不会改变自身归属。
|
||||
|
||||
每个 use 引用一个 namespace,不附加类名、函数名或选择性名称列表。引用用于指定依赖来源,不会自动执行其中的函数,也不构成访问授权。
|
||||
|
||||
导入后的名称使用还受可见性与名称查找规则约束。当前跨 namespace 调用例子采用目标声明可见、无名称冲突的条件;别名、限定名和同名冲突规则仍列在规范状态的“引用与代码视图”中。
|
||||
|
||||
## 必须保留的区别
|
||||
|
||||
“完整 namespace 引用”不意味着“所有成员都自动可见”。官方 UI 组件来源尚未定义,也不能因为例子需要显示界面就将 Column 或 Text 放到 alice 的库名下。
|
||||
|
||||
## 验收
|
||||
|
||||
读者可回答三件事:key 如何分解;当前代码属于谁;导入是否授予访问权。源码形状可由现有检查工具辅助检查,归属、授权和可见性说明需人工核对。
|
||||
|
||||
[对应任务](../tasks/TASK-03.md) · [示例目录](README.md)
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# EX-03 补全调用例子的上下文与结果
|
||||
|
||||
读者目标:理解后续调用如何使用前一次的结果。依据是当前 guide/09-functions-and-calls.md。函数与类型写法仍采用本书收录提案。
|
||||
|
||||
## 原稿
|
||||
|
||||
```text
|
||||
let amount = discountedPrice(price, discount)
|
||||
return discountedPrice(amount, 5)
|
||||
```
|
||||
|
||||
> 系统会自动搞定,最后拿到结果。
|
||||
|
||||
原稿缺少片段位置、函数声明、输入和结果,也没有指出读者应观察的数据依赖。
|
||||
|
||||
## 写作判断
|
||||
|
||||
先给依赖方函数声明,再给调用方归属与导入,最后用确定输入推演。无需介绍传输协议;需要保留名称可见性假设和提案状态。
|
||||
|
||||
## 成稿示范
|
||||
|
||||
### 组合两次定价调用
|
||||
|
||||
下面采用本书的函数语法提案,展示成功调用的结果依赖。跨 namespace 引用采用目标函数可见、名称无冲突的条件。
|
||||
|
||||
代码归属:`alice:shop.pricing`。函数声明:
|
||||
|
||||
```endorphin
|
||||
function discountedPrice(price: Int, discount: Int): Int {
|
||||
return price - discount
|
||||
}
|
||||
```
|
||||
|
||||
该函数从 price 中扣除 discount,并返回整数结果。
|
||||
|
||||
代码归属:`bob:shop.checkout`。导入与调用方声明:
|
||||
|
||||
```endorphin
|
||||
use alice:shop.pricing
|
||||
|
||||
function payable(price: Int, discount: Int): Int {
|
||||
let amount = discountedPrice(price, discount)
|
||||
return discountedPrice(amount, 5)
|
||||
}
|
||||
```
|
||||
|
||||
对于 payable 的输入 100 和 10,预期计算如下:
|
||||
|
||||
| 步骤 | 输入 | 成功结果 |
|
||||
| --- | --- | --- |
|
||||
| 第一次 discountedPrice | 100、10 | 90,绑定到 amount |
|
||||
| 第二次 discountedPrice | amount 为 90、优惠为 5 | 85,作为 payable 的返回值 |
|
||||
|
||||
第二次调用使用第一次的结果。因此,在 amount 的成功结果可用前,后续调用不能把它当作已取得的值使用。上述语义在 inflight 中体现;Preflight 检查调用目标、参数和返回类型等可静态判断的约束。
|
||||
|
||||
这里展示成功路径。失败、缺失、未就绪的具体处理语法仍按规范状态记录,不能将它们当作整数 0。仅凭这段数据依赖也不能推出所有函数参数的求值顺序。
|
||||
|
||||
## 反向验证
|
||||
|
||||
把输入换成 80 与 7:第一次得到 73,第二次得到 68。如果解释仍声称第一次固定返回 90,说明文字与规则没有连通。
|
||||
|
||||
检查例子没有为 Product 或其他 class 增加 get,没有使用未定义的 await、client 或官方导入路径。验证方式是按当前规则手算,未运行 Endorphin 程序。
|
||||
|
||||
## 采用的规则
|
||||
|
||||
DOC-004、009、010、011、013、015。代码、说明和结果表共同承担上下文与解释;不要求每个项目都单独显示一段“规则检查”。
|
||||
|
||||
[对应任务](../tasks/TASK-04.md) · [示例目录](README.md)
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
# EX-04 写出可以直接实施的审查意见
|
||||
|
||||
读者目标:区分确定的文档缺陷与需要确认的语言设计。下列原稿是用于审稿训练的合成材料,不是语言规范。
|
||||
|
||||
## 待审原稿
|
||||
|
||||
> class 声明会自动创建数据库表。任何类都可以直接调用 get;数据不存在时得到空对象。use 会授权调用目标 namespace 的全部函数,所以只要知道用户名就可以读取数据。这些例子都已通过运行测试。
|
||||
|
||||
只提供这段文字,没有执行记录,也没有新的语言决定。
|
||||
|
||||
## 审查发现示范
|
||||
|
||||
| 优先级 | 位置与断言 | 依据和读者影响 | 最小修正 |
|
||||
| --- | --- | --- | --- |
|
||||
| 阻断 | “自动创建数据库表” | 类型结构被写成持久化规则,超出当前规范范围 | 删除自动建表主张,说明 class 表达结构 |
|
||||
| 阻断 | “任何类都可以直接调用 get” | 读取例子中的成员假设被扩大为内置 API | 恢复 Product.get 提案及成员声明未定说明 |
|
||||
| 阻断 | “不存在时得到空对象” | 未定义的缺失处理被伪装成成功值 | 说明缺失须可观察,类型与处理形式仍待定义 |
|
||||
| 阻断 | “use 会授权” | key 定位与访问授权被混为一谈 | 明确 use 指定依赖,授权另行决定 |
|
||||
| 阻断 | “已通过运行测试” | 没有测试环境与执行证据 | 改为实际完成的验证等级,未执行则明确未执行 |
|
||||
|
||||
依据分别来自类型、数据读取、身份、程序结构和规范状态的主定义。正式报告应给出对应文件与位置,避免仅写“违反本手册”。
|
||||
|
||||
## 不应额外下的结论
|
||||
|
||||
不能因为 get 尚未定义,就决定采用新的 query 关键字;不能因为授权未定,就补一套权限装饰器;也不能把“作者更喜欢另一种标题”列为阻断。
|
||||
|
||||
## 若用户只要求审查
|
||||
|
||||
交付上述问题及修正建议,保留原文件。若用户要求修复,依据已确定范围落实文字并核对相关例子,最后只列仍需决定的部分。
|
||||
|
||||
## 验收
|
||||
|
||||
另一作者应能根据报告找到原句、理解错误影响并完成最小修正。没有代码执行或真实用户参与时,不声称经过运行或用户测试。
|
||||
|
||||
[对应任务](../tasks/TASK-07.md) · [示例目录](README.md)
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
# EX-05 让章节顺序服从理解依赖
|
||||
|
||||
读者目标:从目录设计推导移动范围,保留定义与导航。下列结构是教学样例,不是本次对正文的实际重组。
|
||||
|
||||
## 原结构
|
||||
|
||||
| 旧位置 | 内容 |
|
||||
| --- | --- |
|
||||
| guide/01-calls.md | 跨 namespace 调用和 use |
|
||||
| guide/02-notes.md | handle、显示名、注册讨论、key、归属 |
|
||||
| guide/03-ui.md | 组件与一个数据调用例子 |
|
||||
| guide/04-runtime.md | Preflight、inflight 与通信方案 |
|
||||
|
||||
新读者在第一章就需要 namespace 和归属概念;notes 难以检索;阶段与通信方案混合;数据调用隐藏在 UI 页中。
|
||||
|
||||
## 目标职责
|
||||
|
||||
先建立语言整体模型,然后说明身份、namespace、程序结构和阶段,再进入基础语法及应用。类型与调用为数据读取提供前提,UI 是应用领域之一。
|
||||
|
||||
这不要求无限增加文件。身份和 key 具有不同查询任务时可以独立成章;一个只解释两句话的边界可以留在原主题中。
|
||||
|
||||
## 移动映射示范
|
||||
|
||||
| 原内容 | 新的主要位置 | 需要同步 |
|
||||
| --- | --- | --- |
|
||||
| handle 与显示名 | 身份章 | 术语、key 的前提链接 |
|
||||
| key 与归属 | namespace 章 | use、调用例子的外部上下文 |
|
||||
| use 基本形式 | 程序结构章 | EBNF、调用章节短引用 |
|
||||
| Preflight / inflight | 阶段章 | 函数、数据和 UI 的行为说明 |
|
||||
| 数据调用 | 数据读取章 | 类型、调用与 UI 的相关链接 |
|
||||
| 注册讨论和通信方案 | 按当前任务范围单独处理 | 不将讨论过程当成已确定语言规则 |
|
||||
|
||||
表中使用主题名说明方法。真实任务必须补齐具体目标文件与锚点,再实施移动。
|
||||
|
||||
## 重组后的检查
|
||||
|
||||
从首页进入调用章前,身份和引用已能被理解;直接从搜索进入 use 小节,也能看到本地归属与依赖 key 的区别。术语链接指向唯一主定义,形式文法保留集中入口。
|
||||
|
||||
搜索旧路径与旧标题,更新有效入站链接。对无法控制的外部地址,记录兼容措施或已知影响。重组完成不代表原有语法提案被确认。
|
||||
|
||||
[对应任务](../tasks/TASK-05.md) · [示例目录](README.md)
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
# 完整改写示例
|
||||
|
||||
这些页面用于演示写作决策,成稿样例不替代语言正文的主定义,也不确认新语义。例子依据当前设计稿;今后语言决定变化时,与对应主题一起检查。
|
||||
|
||||
| 页面 | 能学到的判断 |
|
||||
| --- | --- |
|
||||
| [EX-01 概念指南](EX-01.md) | 从聊天式说明提取定义、区别与边界 |
|
||||
| [EX-02 导入参考](EX-02.md) | 为跳转读者提供形式、归属、效果和状态 |
|
||||
| [EX-03 调用示例](EX-03.md) | 补齐跨 namespace 声明、假设、输入及结果 |
|
||||
| [EX-04 审查报告](EX-04.md) | 用证据区分语义缺陷、设计缺口与文风偏好 |
|
||||
| [EX-05 章节重组](EX-05.md) | 按依赖移动内容并同步查询入口 |
|
||||
|
||||
使用时先读对应任务页,再检查案例中的判断如何适用于当前页面。不要把成稿原样复制到多个章节,造成主定义重复。
|
||||
|
||||
[手册入口](../README.md)
|
||||
|
||||
Reference in New Issue
Block a user