Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the old one-liner form, and migrate lib/ext/examples/tests/docs accordingly. Co-authored-by: Cursor <cursoragent@cursor.com>
7.1 KiB
7.1 KiB
模块命名空间(import / 点号寻址)
| 状态 | Accepted;嵌套 YAML import: / 导入: 映射已锁定 |
| 日期 | 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 bind:target在 YAML 里会变成带空格的键,与正规元信息不兼容。
结论:模块命名空间 + 点号寻址;frontmatter 导入统一为嵌套 YAML 映射 import:\n 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(不变)。键为合法 YAML:import: / 导入:,值为嵌套映射。
---
import:
utils: utils.mq.md
json: lib/json.mq.md
fmt: time.format
---
| 含义 | 英文 | 中文 |
|---|---|---|
| 导入文件 | import: → utils: utils.mq.md |
导入: → utils: utils.mq.md |
| 标准库 | json: lib/json.mq.md |
同左(或中文库路径) |
| 短名(成员) | fmt: time.format |
fmt: 时间.格式化 |
规则:
- 绑定名必填,为映射键(裸名,无反引号);冒号后须有空格(正规 YAML)。
- 映射值
target:- 以
.mq.md结尾 → 文件导入; - 否则为 点号路径(≥2 段),把该成员绑为本地短名(须先有对应文件导入)。
- 以
- 同一文件内绑定名不得冲突(文件库名与短名共用命名空间)→ 硬错误。
- 同一文件不得同时出现
import:与导入:。 - 旧写法一行式
import bind:target、> ….mq.md、> use …→ 硬错误;可用marqdo migrate imports --write迁移。
3.3 废除的旧规则
不再支持:
- 一行式
import bind:target/导入 bind:target; - 省略绑定名时用文件名茎作库名;
- 导入侧
as/作为; - 独立关键字
use/使用。
3.4 调用解析顺序
- 点号路径 callee(§4)→ 按段在导入库 / 类型树上寻址。
- 当前文件顶层
#/##与 frontmatter 短名绑定。 - L0 内置。
- 插件注册名。
- 否则 → 未知 callee。
4. 点号寻址(核心外形)
4.1 文法
path_callee ::= ident ('.' ident)+
4.2 二段:库.成员
---
import:
time: lib/time.mq.md
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
fmt: time.format
---
# main
*t = > time.now_unix*
*s = > fmt unix=`t` pattern="%Y-%m-%d"*
4.6 应用侧完整示例
---
import:
time: lib/time.mq.md
writeback: lib/writeback.mq.md
agent: ext/ai/agent.mq.md
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 fmt:time.format |
import: → fmt: time.format |
| 茎名默认库名 | 绑定名始终显式 |
| 扁平合并进全局 | 仅库绑定 + 可选短名 |
不提供旧一行式 / > 导入过渡开关;marqdo migrate imports --write 可机械迁移。
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 句法 | 嵌套 YAML import: — 本波次 |
9. 决议摘要
- 导入 = 嵌套
import:/导入:映射(bind: target)。 - target =
.mq.md文件 或库.成员点号路径。 - 调用以裸名点号路径寻址;实例方法用反引号接收者(仅独立
>调用;*…*/**…**段内接收者不加反引号)。 - 裸点号
a.b:a为局部变量 → 方法调用,否则 → 库路径(Python 统一命名空间)。