Files
Endorphin-Document/authoring/examples/EX-01.md
T

2.6 KiB

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 公开可调用”的结论。
  • 验证:这是基于当前文本规则的作者推演,没有调用身份系统。

对应任务 · 示例目录