docs: merge authoring skill with interpreted runtime design
Preserve the task-guided authoring handbook and manual execution policy. Align language-map and semantic-contracts with ordinary function UI results and nominal declaration identity. Manually review phase boundaries, resource access states, grammar, status and navigation; no project tests or hooks executed.
This commit is contained in:
@@ -0,0 +1,42 @@
|
||||
# 中文技术表达与记法
|
||||
|
||||
本页处理会影响理解和检索的表述选择。术语含义以当前主定义为准。
|
||||
|
||||
## 句子要有对象和可判断的含义
|
||||
|
||||
先指出对象，再说明职责或行为。用“use 指定依赖的 namespace”代替“这里可以把那边的东西拿过来”。一个段落说明一个主要关系；第二句解释第一句成立的条件或后果。
|
||||
|
||||
语言文档使用独立陈述。教程中的“你可以”并非错误，但“按我们刚才的讨论”“上面不是说过了吗”依赖聊天背景，应改成具体概念及链接。删去讨好性的评价和无依据的“轻松、自动、强大”。
|
||||
|
||||
## 定义、规则、理由、例子分别起作用
|
||||
|
||||
定义回答对象是什么；规则规定合法性与行为；理由解释规则的用途；例子展示一个具体情况。只给比喻不能代替定义，只给代码不能代替行为说明。
|
||||
|
||||
例如“handle 类似社交平台的 @ 名”可以帮助理解，但仍需明确唯一性、显示名区别及其在 key 中的位置。不能从类比导出 @ 必须写进 key。
|
||||
|
||||
## 建立有信息量的标题与链接
|
||||
|
||||
标题使用读者可能搜索的词，如“用户名与显示名”“导入后的名称引用”。链接文字指出目标主题，少用“这里”“详情”。同一页多个“注意事项”应改成各自的边界名称。
|
||||
|
||||
跨章链接定位真正支持当前断言的页或小节。频繁相互跳转说明正文可能缺少一句局部定义，或章节职责需要重排。
|
||||
|
||||
## 术语表与源码的边界
|
||||
|
||||
普通术语第一次出现可给出中文解释和原词。源码名称、key、关键字使用行内代码；阶段名称严格使用 Preflight 与 inflight。展示文字可以使用中文，不能据此把关键字翻译成中文源码。
|
||||
|
||||
当前正式语言名、源码围栏和 API 大小写保持仓库约定。用户在聊天中使用简称不自动触发全库更名。确需更名时按语义/术语迁移任务核对范围。
|
||||
|
||||
## 标点和强度
|
||||
|
||||
中文叙述使用中文标点，源码保留其规定符号。全角冒号不能代替 key 中的半角冒号。中英文混排以可读性保持一致，不要让格式工具改动代码字符串。
|
||||
|
||||
“必须、不得”须对应明确约束；“建议”表达选择；“例如”不能偷偷定义默认行为。删除“显然”“很容易”等假定读者水平的措辞，直接写出关键理由。
|
||||
|
||||
## 表格、列表和注释
|
||||
|
||||
重复字段适合表格，步骤适合有序列表，依赖关系适合小图。连续论证用段落。一个简单关系不必拆成“背景、问题、方案、总结”四个标题。
|
||||
|
||||
提示框保留会影响例子合法性或结果判断的信息。跨多页相同的设计稿声明保留统一入口；具体未定成员的局部假设仍放在例子旁。
|
||||
|
||||
[指南改写示例](../examples/EX-01.md) · [DOC-017](../rules/DOC-017.md) · [DOC-018](../rules/DOC-018.md) · [DOC-019](../rules/DOC-019.md)
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
# 示例设计与验证
|
||||
|
||||
示例承担一个可检查的教学目标。完整性由这个目标需要的条件决定，不由代码行数决定。
|
||||
|
||||
## 先选择示例等级
|
||||
|
||||
| 等级 | 必须交代 | 合适的效果表述 |
|
||||
| --- | --- | --- |
|
||||
| 概念或 key 示例 | 对象、组成、用于说明的区别 | “该 key 定位……” |
|
||||
| 合法源码片段 | 所在位置、依赖声明、归属、语言状态 | “在这些条件下，预期……” |
|
||||
| 完整逻辑代码视图 | 所有展示的声明与依赖、未定义的外部条件 | “这份视图描述……” |
|
||||
| 实际执行示例 | 真实环境、调用方式、输入和取得的输出 | “在指定环境执行，得到……” |
|
||||
|
||||
本仓库的设计稿常用前三类。缺少运行入口不能靠命令名或启动步骤补造。源码围栏使用仓库约定的 endorphin；无效反例使用 text 并明确标为错误写法，避免复制后被误用。
|
||||
|
||||
## 建立一个实例的说明单
|
||||
|
||||
先确定单一目标，再列以下字段：归属 key；依赖 key 与声明；片段位置；输入；成功结果；为什么产生该结果；相关边界；验证方式。
|
||||
|
||||
例如跨 namespace 的定价例子中，归属是 bob:shop.checkout，依赖是 alice:shop.pricing。discountedPrice 必须有声明依据，直接名称查找需有局部假设。输入 100 与 10 时，两次扣减得到 90 和 85。这个结果说明数据依赖，不证明远端执行顺序的全部规则。
|
||||
|
||||
说明单可放在作者工作记录中；成稿将字段融入自然段、代码和结果表，不要求每个例子都显示八项元数据。
|
||||
|
||||
## 控制新概念
|
||||
|
||||
第一例仅证明主要规则。第二例改变一个有意义的条件，例如从一层路径变为多层路径，或在已有计算结果上继续调用。只有当比较确实需要时才提供第三例。
|
||||
|
||||
“一个例子一个目标”不等于永远只有一个概念。调用必须使用函数、参数、结果；相关概念可通过已有声明和短链接提供，避免为了极简删掉必要条件。
|
||||
|
||||
## 选择反例
|
||||
|
||||
选择读者可能写出的错误，并紧邻关联规则。写清错误原因、出现阶段和最小修正。阶段尚未确定时不能强行归类。
|
||||
|
||||
有教学目的的错误代码要标明无效，并解释怎样修正。不能在正例前只放一个警告、正文仍沿用错误写法。工具用于正例约定检查时，应允许明确标注的反例存在于专门的 text 围栏。
|
||||
|
||||
## 保持业务对象连续
|
||||
|
||||
沿用商品与定价背景有助于减少额外解释。改变名字或数值时核对全文引用和手算结果；引入新领域应服务读者任务。官方组件、用户库、业务数据 id、namespace key 各自承担不同角色。
|
||||
|
||||
## 验证顺序
|
||||
|
||||
先核对关键断言依据，再逐个解析名称和前提，然后计算结果或描述 UI 效果，最后核查代码与文字一致。
|
||||
|
||||
用户明确要求执行验证时，才在对应环境运行程序；平时记录“按文档规则推演”。数值通过其他语言计算出相同结果也不能证明 Endorphin 源码运行通过。
|
||||
|
||||
检查代表性输入之外，再选一个能暴露解释错误的输入。定价例子可把输入换为 80 与 7，预期依次为 73 和 68；不要把这个补充输入自动扩展为负数、溢出、所有整数都已定义。
|
||||
|
||||
[完整示例](../examples/EX-03.md) · [DOC-009](../rules/DOC-009.md) · [DOC-010](../rules/DOC-010.md) · [DOC-012](../rules/DOC-012.md)
|
||||
@@ -0,0 +1,51 @@
|
||||
# 页面与章节的信息架构
|
||||
|
||||
本方法用于新章、首页和目录重组。读者目标决定信息位置，文件长度只是发现问题的线索。
|
||||
|
||||
## 先写一张页面卡
|
||||
|
||||
用一句话填写“已知道什么的读者，在什么情境下，读完能做什么”。再列出主定义、必要前提和可检查结果。
|
||||
|
||||
例如：“知道 key 组成的读者，要引用定价逻辑，读后能写出完整 use，并区分依赖来源与自身归属。”它会导出 use 写法、双方 key、引用效果与可见性边界，不需要先讲网络实现。
|
||||
|
||||
同一页若同时承担“解释为什么使用 namespace”和“查找 use 的精确约束”，可以保留简短背景，但应有清楚的查询小节或互链。只有当两种读者任务互相妨碍时才拆页。
|
||||
|
||||
## 决定信息属于哪里
|
||||
|
||||
| 信息 | 首选位置 | 判断依据 |
|
||||
| --- | --- | --- |
|
||||
| 概念是什么、解决什么问题 | 指南首次介绍处 | 首次读者需要建立模型 |
|
||||
| 完整形式、约束、结果 | 对应参考小节及集中 EBNF | 跳转读者需要精确查询 |
|
||||
| 关键例子成立的假设 | 例子之前或紧邻例子 | 离开此条件会误读合法性 |
|
||||
| 尚未决定的完整清单 | 规范状态附录 | 避免各章多份状态互相漂移 |
|
||||
| 实际影响例子的未定项 | 局部短注并链接状态 | 读者不应读到页末才发现例子有前提 |
|
||||
| 写作讨论、来源研究、审查记录 | authoring | 维护作者需要，语言学习主线通常不需要 |
|
||||
|
||||
## 从提纲判断是否可读
|
||||
|
||||
将所有小节标题连起来读，检查它们是否回答连续的问题。例如“key 是什么 → 如何分解 → 如何确定归属 → 如何引用其他代码 → 哪些规则还未定义”。
|
||||
|
||||
标题应提供信息线索。“其他”“相关说明”“注意事项”通常需要改成具体主题，如“导入不改变代码归属”。章节编号承担顺序，不替代可搜索的主题词。
|
||||
|
||||
先定义再使用不要求所有章节线性展开。概览可以先预览用途，再链接定义；跳转页可以用一句话补足前提。避免通过复制整章解决前置知识问题。
|
||||
|
||||
## 拆分与合并的判断
|
||||
|
||||
满足以下情形时优先考虑拆分：读者目标明显不同；可独立修改与查询；不同前提让一组读者长期跳过大半页面。以下情形通常保留同页：例子离开解释就失去意义；两页必须来回跳转才能理解一个最小规则；拆分后只有标题和链接。
|
||||
|
||||
拆分前制作映射：“旧小节 → 新文件或锚点 → 需要更新的引用”。更新目录、相邻导航、术语、状态和文法引用。文件重命名会影响已分享的地址；需要保留历史访问入口时使用真实可用的重定向或短入口页，并在任务中说明，不能只假设站点会处理。
|
||||
|
||||
## 单页的阅读负担
|
||||
|
||||
第一段回答对象及职责。第一个例子只承担本页的主要目标。正文解释会影响理解的差异，不逐行翻译所有标点。表格适合重复字段对照，段落适合原因和行为关系。
|
||||
|
||||
以段落为单位删除后检查：删去是否让读者无法判断用途、合法性、结果或下一步？若都没有影响，这段可能应删去或移入深读链接。反过来，短文若缺少关键前提仍需补足。
|
||||
|
||||
## 复查三个入口
|
||||
|
||||
1. 从全书目录首次进入：前置概念是否已出现？
|
||||
2. 从搜索直接进入小节：能否识别对象、状态、条件和结果？
|
||||
3. 从相邻概念返回：是否找到唯一主定义，还是读到不同版本？
|
||||
|
||||
[重组示例](../examples/EX-05.md) · [DOC-005](../rules/DOC-005.md) · [DOC-006](../rules/DOC-006.md) · [DOC-007](../rules/DOC-007.md)
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
# 语言核对地图
|
||||
|
||||
本页帮助作者定位当前语言规则。每次新增或改动语言断言，读取相关主定义及规范状态；此表不是另一份语言规范。下面的文件位置以文档仓库根目录为基准，直接按主题查阅。
|
||||
|
||||
## 断言从哪里来
|
||||
|
||||
| 证据 | 可以据此写什么 | 需要注意 |
|
||||
| --- | --- | --- |
|
||||
| 用户本次明确确认的语言决定 | 将决定落实为主定义、例子、文法与状态 | 只落实明确决定的范围，相关未定项仍保持未定 |
|
||||
| 当前规范状态与主要定义 | 重述已确定约定，解释已收录提案 | 两者冲突时先定位，不选择更方便写例子的版本 |
|
||||
| 一个源码示例 | 说明该例在明确条件下的预期效果 | 示例本身不证明全语言默认值或完整规则 |
|
||||
| 软件实现行为 | 在用户要求的范围报告观测事实 | 本阶段文档不据此自动确定语言语义 |
|
||||
| 外部语言或文档 | 研究解释方法，或说明显式提出的候选设计 | 相似语言的能力不自动属于本语言 |
|
||||
|
||||
用户授权改文与用户确认语言设计是两件事。可以直接改善清晰度、目录和例子解释；新增名称规则、API、权限或结果状态需要具体依据。
|
||||
|
||||
## 主题、主定义与易错推断
|
||||
|
||||
| 主题 | 应读取的文件 | 特别核对 |
|
||||
| --- | --- | --- |
|
||||
| 定位 | 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/04-program-structure.md | use 后是完整 key；导入不改变归属，不授予权限，不自动执行 |
|
||||
| 阶段 | guide/05-preflight-and-inflight.md | 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/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 | 应用方向不代表声明、工具、委托或权限语法已确定 |
|
||||
|
||||
所有主题同时核对 appendices/specification-status.md。涉及词形、产生式或组合约束时再核对 appendices/formal-grammar.md；纯措辞修改不必重读全书。
|
||||
|
||||
## 三种状态如何落笔
|
||||
|
||||
**已确定约定**直接陈述事实，例如“use 引用一个完整 namespace key”。精确链接指向主定义，其他页按需要作短说明。
|
||||
|
||||
**已收录提案**可以清楚说明提案内部的规则。在章节入口或第一次关键例子旁标明状态，不把每句都改成“可能”“也许”。
|
||||
|
||||
**未定义边界**写明缺少的维度，例如“别名和同名冲突的名称查找形式尚未定义”，并链接状态位置。不要用含糊的“待完善”遮住会影响例子合法性的缺口。
|
||||
|
||||
## 处理冲突
|
||||
|
||||
先抄出两处冲突的具体断言，分别找到状态或用户决定依据。若只是旧写法残留，按明确决定修正并搜索同类残留；若实际需要新语义，完成不依赖该选择的部分，向用户提出最小必要决定。
|
||||
|
||||
例如，将错误的 use 点号分隔改回冒号是落实已确定规则；决定用户名是否大小写敏感则是新增语言决定。两者不应采用同一种处理方式。
|
||||
|
||||
[语义契约](semantic-contracts.md) · [语义变更任务](../tasks/TASK-06.md)
|
||||
@@ -0,0 +1,48 @@
|
||||
# 文档审查与完成标准
|
||||
|
||||
审查以读者能否完成目标为依据。每个问题给出位置、具体证据、读者影响和建议；只给“太简单”“不够专业”无法指导修改。
|
||||
|
||||
## 问题优先级
|
||||
|
||||
| 级别 | 判断 | 例子 | 处理 |
|
||||
| --- | --- | --- | --- |
|
||||
| 阻断 | 使读者得到错误语言规则、用法或验证结论 | 宣称 get 已内置；把导入写成授权；伪造运行结果 | 修复后才能称为完成 |
|
||||
| 重要 | 缺少完成当前任务所需的信息 | 例子依赖不存在的声明；核心规则无法定位 | 本任务内补足，或准确说明受阻部分 |
|
||||
| 改进 | 内容正确，表达或查找仍可优化 | 链接文案不明确；重复背景 | 按收益修改，不无限扩大任务 |
|
||||
| 偏好 | 多种同样可读的写法 | 无实际效果的标题风格差异 | 不当作缺陷，不强制改写 |
|
||||
|
||||
未定义的语言能力本身不一定是文档缺陷；把它写成已实现或让读者无法识别假设才是缺陷。
|
||||
|
||||
## 六个检查维度
|
||||
|
||||
1. **目标与范围**：页面能否回答一个明确问题？关键前提是否在当前读者可得的位置？
|
||||
2. **正确性与状态**：每条语言断言是否有依据？文字、形式、例子、规范状态是否一致？
|
||||
3. **示例与结果**：名称可追溯吗？条件、输入、效果和失败边界是否足以解释例子？
|
||||
4. **组织与检索**：顺序阅读是否需要未介绍的概念？直接跳入是否能找到主定义和必要上下文？
|
||||
5. **表达与记法**：术语是否统一？语句独立成立？视觉形式是否帮助识别关系？
|
||||
6. **维护与证据**：影响页是否同步？来源可核对？测试等级与实际操作相符？
|
||||
|
||||
不把这些维度打成一个虚假的精确总分。交付记录“通过、发现问题或不适用”的依据；文档质量不能由行数、链接数或规则命中数量代表。
|
||||
|
||||
## 三个读者任务
|
||||
|
||||
**复述任务**：不借助聊天，说明本页对象、职责和一个主要边界。记录在哪个词或段落无法继续。
|
||||
|
||||
**定位任务**：从目录或直接落到页中，找到一个具体约束。例如“use 会不会改变当前归属？”记录路径和最终依据；没有真人参与时只称作者走查。
|
||||
|
||||
**预测任务**：改变例子中的一个条件，预测结果或合法性。例如将 `alice:shop` 换成 `bob:shop` 后是否仍为同一 namespace；为什么？
|
||||
|
||||
检查针对本次改动选择，微小错字无需重新评估全书。结构、语义或示例改动要执行相关任务。真实读者测试需要记录任务、参与者背景和实际反馈，不能用作者自查代替。
|
||||
|
||||
## 审查结果如何写
|
||||
|
||||
用“位置：断言或片段 → 违反的规则/缺少的前提 → 对读者的影响 → 最小修正”表达。区分确定缺陷与待确认问题。只列有证据的问题，不为凑数量虚构发现。
|
||||
|
||||
审查-only 任务到报告为止；带修复的任务先修正，再报告剩余问题。一次工作已满足目标且无未解决的相关阻断/重要问题时即可交付，不为了追求全书完美持续扩张。
|
||||
|
||||
## 完成证据
|
||||
|
||||
结构工具通过是最低的机械核对。具体改动还需有相应语义、读者任务或执行证据。报告中写明检查对象与限制，例如“走查导入参考的直接访问路径，已能在本页找到归属区别；未进行真人测试”。
|
||||
|
||||
[审查示例](../examples/EX-04.md) · [检查清单](../checklist.md) · [TPL-06](../templates/TPL-06.md)
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
# 把语法写成可核对的行为契约
|
||||
|
||||
一段语法说明需要让读者判断“怎样写合法”和“写下后会发生什么”。将已知规则逐项表达，未定项按影响标注；不为了表格完整发明语言能力。
|
||||
|
||||
## 契约字段
|
||||
|
||||
| 维度 | 作者要回答的问题 | 写在何处 |
|
||||
| --- | --- | --- |
|
||||
| 位置 | 声明、表达式还是函数体片段？ | 形式之前 |
|
||||
| 形式 | 哪些部分必选、可选或可重复？ | 签名或语法结构 |
|
||||
| 名称 | 依赖哪些声明，在哪里查找？ | 前提或引用小节 |
|
||||
| 输入 | 参数的意义、数量、类型及适用范围？ | 参数说明 |
|
||||
| 结果 | 成功值、类型、结构或可见 UI 效果？ | 结果小节 |
|
||||
| 依赖与效果 | 哪些值需先得到，是否有业务修改？ | 行为说明 |
|
||||
| 阶段 | 哪些问题可由 Preflight 判断，哪些属于 inflight？ | 相关约束旁 |
|
||||
| 边界 | 缺失、失败、未就绪或非法结构会怎样？ | 约束与失败 |
|
||||
| 状态 | 已确定、收录提案还是未定义？ | 章节入口及关键局部 |
|
||||
|
||||
对于 use，不适合虚构“返回值”，应说明依赖来源与引用效果。对于 UI 参数，说明子节点和排列；没有规定布局单位就不能补像素默认值。字段适配对象，不能机械填表。
|
||||
|
||||
## 规范用语的力度
|
||||
|
||||
“必须”表示文档确实规定的必要条件；“可以”表示允许的用法；“建议”表示作者偏好；“例如”只给出一个实例。“默认”必须有明确依据。
|
||||
|
||||
区分结构层和语义层。EBNF 能表达某个参数存在，不自动说明它的含义、范围和权限。同样，文字声称允许多个声明时，产生式也应允许；两者冲突时不能只改示例使检查通过。
|
||||
|
||||
对尚未定义的范围，不写“任意”“始终”“自动”“所有”这类全称断言。例如，简单用户名样例不证明全部用户名只能包含小写字母；namespace 层级不自动决定访问继承。
|
||||
|
||||
## Preflight 与 inflight 的表达
|
||||
|
||||
参数数量不符等可静态判断的问题，可依现有提案说明为 Preflight 诊断。调用执行中的数据缺失属于 inflight 情况。错误文本、错误码和捕获语法未确定时，只说明可观察问题和已有规则，不虚构诊断输出。
|
||||
|
||||
“第二次调用需要第一次的结果”表达数据依赖；“所有参数严格从左到右执行”是额外的求值顺序规则。前者不能推出后者。普通调用也不能推出自动重试、缓存一致性或无副作用。
|
||||
|
||||
## 状态影响最小示例时
|
||||
|
||||
优先选用已经写明的形式。若目标就是介绍读取提案，则给出提案状态、成员假设和成功路径；把未知的失败处理写成自然语言边界。不得为了演示成功路径而暗示失败时会得到零值。
|
||||
|
||||
如果关键声明根本不存在，不能把完整源码标成可运行。可以提供明确的局部片段或概念用法，并列出缺少的语言决定。
|
||||
|
||||
## 写作完成后的双向核对
|
||||
|
||||
从每条文字规则找到支持它的形式或例子；再从例子中的每个名称、调用和关键效果回到规则或明确假设。
|
||||
|
||||
例如 `use alice:shop.pricing` 支持“完整 key”这一形式，但不证明所有成员自动进入作用域。跨 namespace 调用例子还需说明目标可见、无名称冲突的局部条件。
|
||||
|
||||
核对详情记录在[TPL-05 变更工作单](../templates/TPL-05.md)即可，不必把作者的所有分析附在读者正文中。
|
||||
|
||||
[语言核对地图](language-map.md) · [参考成稿示例](../examples/EX-02.md) · [DOC-013](../rules/DOC-013.md)
|
||||
|
||||
Reference in New Issue
Block a user