51 lines
5.0 KiB
Markdown
51 lines
5.0 KiB
Markdown
# 语言核对地图
|
||
|
||
本页帮助作者定位当前语言规则。每次新增或改动语言断言，读取相关主定义及规范状态；此表不是另一份语言规范。下面的文件位置以文档仓库根目录为基准，直接按主题查阅。
|
||
|
||
## 断言从哪里来
|
||
|
||
| 证据 | 可以据此写什么 | 需要注意 |
|
||
| --- | --- | --- |
|
||
| 用户本次明确确认的语言决定 | 将决定落实为主定义、例子、文法与状态 | 只落实明确决定的范围，相关未定项仍保持未定 |
|
||
| 当前规范状态与主要定义 | 重述已确定约定，解释已收录提案 | 两者冲突时先定位，不选择更方便写例子的版本 |
|
||
| 一个源码示例 | 说明该例在明确条件下的预期效果 | 示例本身不证明全语言默认值或完整规则 |
|
||
| 软件实现行为 | 在用户要求的范围报告观测事实 | 本阶段文档不据此自动确定语言语义 |
|
||
| 外部语言或文档 | 研究解释方法，或说明显式提出的候选设计 | 相似语言的能力不自动属于本语言 |
|
||
|
||
用户授权改文与用户确认语言设计是两件事。可以直接改善清晰度、目录和例子解释；新增名称规则、API、权限或结果状态需要具体依据。
|
||
|
||
## 主题、主定义与易错推断
|
||
|
||
| 主题 | 应读取的文件 | 特别核对 |
|
||
| --- | --- | --- |
|
||
| 定位 | guide/01-overview.md；appendices/application-domains.md | 前后端与 Agent 的统一语言定位；不要写成只服务界面的 DSL |
|
||
| 身份与权限 | 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 大小写；定义长期存续归入 Preflight，调用与实例存续归入 inflight；长期保存的运行状态不是定义；阶段不等于执行位置 |
|
||
| 词法 | guide/06-lexical-structure.md；appendices/formal-grammar.md | 草案中的标识符与字面量，不外推完整 Unicode、关键字或转义规则 |
|
||
| 资源与类型 | 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 | guide/13-agents.md；appendices/specification-status.md | agent 已确认为语言资源；内部复用共有成员并承担工具、记忆、状态、路由、中断和上下文职责；骨架不代表成员关联、默认 API、委托或权限语法已确定 |
|
||
|
||
所有主题同时核对 appendices/specification-status.md。涉及词形、产生式或组合约束时再核对 appendices/formal-grammar.md；纯措辞修改不必重读全书。
|
||
|
||
## 三种状态如何落笔
|
||
|
||
**已确定约定**直接陈述事实，例如“use 引用一个完整 namespace key”。精确链接指向主定义，其他页按需要作短说明。
|
||
|
||
**已收录提案**可以清楚说明提案内部的规则。在章节入口或第一次关键例子旁标明状态，不把每句都改成“可能”“也许”。
|
||
|
||
**未定义边界**写明缺少的维度，例如“别名和同名冲突的名称查找形式尚未定义”，并链接状态位置。不要用含糊的“待完善”遮住会影响例子合法性的缺口。
|
||
|
||
## 处理冲突
|
||
|
||
先抄出两处冲突的具体断言，分别找到状态或用户决定依据。若只是旧写法残留，按明确决定修正并搜索同类残留；若实际需要新语义，完成不依赖该选择的部分，向用户提出最小必要决定。
|
||
|
||
例如，将错误的 use 点号分隔改回冒号是落实已确定规则；决定 workspace handle 是否大小写敏感则是新增语言决定。两者不应采用同一种处理方式。
|
||
|
||
[语义契约](semantic-contracts.md) · [语义变更任务](../tasks/TASK-06.md)
|