Inside italic/bold code segments every bare word is a variable — including call arguments and method-call receivers — so text literals must be quoted and receivers no longer need backticks. A bare dotted callee `a.b` resolves as a method call when `a` is a local variable, otherwise as a library path (Python-style unified namespace), in both the tree-walk and bytecode backends. Migrate ~70 tests plus ext/web, ext/quantum, ext/ai and the example projects to the new idiom; update SKILL.md and the design docs; fix the web/quantum example data model (db/index.mq.md). Unit and gold suites pass; only the 3 network-live tests fail offline. Co-authored-by: Cursor <cursoragent@cursor.com>
6.6 KiB
6.6 KiB
模块命名空间(import / 点号寻址)
| 状态 | Accepted;统一 import bind:target 已锁定 |
| 日期 | 2026-08-13 |
| 相关 | stdlib-modules.md · stdlib-i18n.md · markdown-mapping.md · objects.md · call-arguments.md · ext-agent.md |
1. 动机
加载器曾把每个导入文件的顶层 # / ## 扁平合并进同一全局函数表;同名则后导入静默覆盖。
后果:
lib/json的parse与lib/time的parse不能共存。- 官方 ext / 多库编排无法按大型语言习惯书写
time.parse/json.parse。 - 旧 frontmatter
import path:path.mq.md对 Markdown / 编辑器不友好,且与调用标记>抢外形。
结论:模块命名空间 + 点号寻址;frontmatter 导入统一为可读的 import bind:target。
2. 目标与非目标
2.1 目标
- 导入绑定库名:导入一个
.mq.md得到一个库(模块)绑定,成员不倒进全局。 - 点号寻址调用:
库.成员、库.对象.成员;.表示定义树寻址。 - 库名不是变量:路径段为裸标识符,不加反引号。
- 短名与文件导入同形:
import fmt:time.format,废除独立use关键字。 - 中英对等:
import/导入。
2.2 非目标
- 第三方包管理 / 版本求解。
- 旧
> path.mq.md/> use双轨兼容。 `time`.parse(库名加反引号)。import fmt:time.*通配。
3. 核心语义
3.1 模块 / 库
| 内容 | 归属 |
|---|---|
顶层 ## 自由函数 |
库根下的函数 |
顶层 # 对象 |
库根下的类型(对象) |
类型下的 ## 方法 |
该对象节点下的成员函数 |
被导入文件的 # main |
不作为入口执行 |
3.2 导入句法(frontmatter)
仍只出现在文件头成对 --- 内。调用仍用 > print(不变)。
| 含义 | 英文 | 中文 |
|---|---|---|
| 导入文件 | import utils:utils.mq.md |
导入 utils:utils.mq.md |
| 标准库 | import json:lib/json.mq.md |
导入 json:lib/json.mq.md |
| 短名(成员) | import fmt:time.format |
导入 fmt:时间.格式化 |
规则:
- 绑定名必填,在
:左侧(裸名,无反引号)。 :右侧target:- 以
.mq.md结尾 → 文件导入; - 否则为 点号路径(≥2 段),把该成员绑为本地短名(须先有对应文件导入)。
- 以
- 同一文件内绑定名不得冲突(文件库名与短名共用命名空间)→ 硬错误。
- 旧写法
> ….mq.md、> … as …、> use …、> 使用 …→ 硬错误,并提示新句法。
3.3 废除的旧规则
不再支持:
- 省略绑定名时用文件名茎作库名;
- 导入侧
as/作为; - 独立关键字
use/使用。
3.4 调用解析顺序
- 点号路径 callee(§4)→ 按段在导入库 / 类型树上寻址。
- 当前文件顶层
#/##与 frontmatter 短名绑定。 - L0 内置。
- 插件注册名。
- 否则 → 未知 callee。
4. 点号寻址(核心外形)
4.1 文法
path_callee ::= ident ('.' ident)+
4.2 二段:库.成员
---
import time:lib/time.mq.md
import json:lib/json.mq.md
---
# main
*t = > time.now_unix*
*s = > time.format unix=`t` pattern="%Y-%m-%d"*
*obj = > json.parse text={"a":1}*
*a = > json.get value=`obj` key="a"*
> print text=`s`
4.3 三段:库.对象.成员
> agent.agent # 库 → 类型:构造
实例方法须 > `var`.method;无接收者的 库.类型.方法 → 硬错误。
4.4 变量 / 实例 vs 库路径(Python 统一命名空间)
| 写法 | 含义 |
|---|---|
time.parse |
库路径(裸名,第一段非变量) |
> `助手`.step |
独立 > 调用:实例方法(接收者反引号) |
*回复 = > 助手.step …* |
*…* 段内:若 助手 是变量 → 实例方法;否则 → 库路径 |
统一规则(与 Python 一致):对裸点号 a.b,当 a 是当前作用域局部变量时解释为方法调用(a 为接收者);否则解释为库路径(lib.a.b)。此规则同时应用于树遍历与字节码两后端。
- 在独立
>调用中裸词 = 文本,故方法接收者仍须反引号:> `助手`.step。 - 在
*…*/**…**段内裸词 = 变量,接收者不加反引号:*回复 = 助手.step …*。
4.5 短名示例
---
import time:lib/time.mq.md
import fmt:time.format
---
# main
*t = > time.now_unix*
*s = > fmt unix=`t` pattern="%Y-%m-%d"*
4.6 应用侧完整示例
---
import time:lib/time.mq.md
import writeback:lib/writeback.mq.md
import agent:ext/ai/agent.mq.md
import json:lib/json.mq.md
---
# main
*`助手` = > agent.agent model=… tools=… *
*`out` = > `助手`.step task=… *
*`body` = > json.stringify value=`out` *
> writeback.record value=`body` key=ok
5. 导出面
默认:库内顶层 # / ## 均可被路径访问。本版不引入 private。
6. 与旧行为的关系(破坏性变更)
| 旧 | 新 |
|---|---|
import time:lib/time.mq.md |
import time:lib/time.mq.md |
import t:lib/time.mq.md |
import t:lib/time.mq.md |
import fmt:time.format |
|
| 茎名默认库名 | 绑定名始终显式 |
| 扁平合并进全局 | 仅库绑定 + 可选短名 |
不提供旧 > 导入过渡开关。
7. 对分层与 ext 的影响
| 层 | 影响 |
|---|---|
| L0 内置 | 仍为全局短名 |
| L1 / 官方 ext | 经库路径调用;ext/**/*.mq.md 严禁 host_* |
| ABI 插件 | 插件注册表 |
8. 实现要点
- frontmatter 只解析
import/导入行;右侧分流文件 / 成员。 - AST 仍用
Import(文件)与Use(短名)存储,对外无use关键字。 - 金样例:
tests/structure/import/、tests/structure/ns/。
| 阶段 | 内容 |
|---|---|
| M1+M2 | 点号路径 + 短名 — 已落地 |
| Import 句法 | 统一 import bind:target — 本波次 |
9. 决议摘要
- 导入 =
import bind:target(导入等价)。 - target =
.mq.md文件 或库.成员点号路径。 - 调用以裸名点号路径寻址;实例方法用反引号接收者(仅独立
>调用;*…*/**…**段内接收者不加反引号)。 - 裸点号
a.b:a为局部变量 → 方法调用,否则 → 库路径(Python 统一命名空间)。