Quiet spawn still hides child stdout; workbooks solidify to **returns**, agent-kb lives in the plugin, and multi-step follows OKF file relay rather than print-based answers. Co-authored-by: Cursor <cursoragent@cursor.com>
9.6 KiB
模块命名空间(import / 点号寻址)
| 状态 | Accepted;M1+M2 已落地 |
| 日期 | 2026-08-07 |
| 相关 | stdlib-modules.md · stdlib-i18n.md · markdown-mapping.md · objects.md · call-arguments.md · ext-agent.md |
1. 动机
今日加载器把每个导入文件的顶层 # / ## 扁平合并进同一全局函数表;同名则后导入静默覆盖(merge_top_level)。
后果:
lib/json的parse与lib/time的parse不能共存;import 顺序决定谁赢,错误表现为「缺pattern」这类误导信息。lib/writeback的get盖住lib/json的get。- 官方 ext / 多库编排无法按大型语言习惯书写
time.parse/json.parse。
结论:Marqdo 必须支持模块命名空间与点号寻址。扁平静默覆盖不是可保留的「兼容糖」,而是会掩盖冲突的缺陷行为;本设计予以废除(落地时为破坏性变更,不设双轨裸名回退)。
2. 目标与非目标
2.1 目标
- 导入绑定库名:导入一个
.mq.md得到一个库(模块)绑定,成员不倒进全局。 - 点号寻址调用:
库.成员、并预留库.对象.成员等多段路径;.表示在定义树上的寻址,不是字段运算。 - 库名不是变量:寻址段为裸标识符,不加反引号。反引号只用于值槽位(变量 / 形参 / 实例句柄)。
- 模块内名字默认不进全局;需要本地短名时必须显式
use,且冲突报错。 - 中英对等:路径中英分文件;
as/作为与默认库名规则双语一致。
2.2 非目标
- 第三方包管理 / 版本求解。
- 在兼容期内继续支持扁平合并旧语义。
- 「裸名仍可从最后一次导入解析」——明确拒绝。
- 把库名写成
`time`.parse——明确拒绝(会把库名误当成变量)。
3. 核心语义
3.1 模块 / 库
每个可导入的 .mq.md 文件是一个库模块:
| 内容 | 归属 |
|---|---|
顶层 ## 自由函数 |
库根下的函数 |
顶层 # 对象 |
库根下的类型(对象) |
类型下的 ## 方法 |
该对象节点下的成员函数(可被路径寻址;实例调用见 §4.4) |
被导入文件的 # main |
不作为入口执行 |
3.2 导入句法(frontmatter)
| 英文 | 中文 | 含义 |
|---|---|---|
> lib/time.mq.md |
> lib/时间.mq.md |
导入;默认库名见 §3.3 |
> lib/time.mq.md as time |
> lib/时间.mq.md 作为 时间 |
导入并以给定库名绑定 |
规则:
as/作为后为裸库名(不加反引号)。- 同一文件内两个导入不得绑定同一库名 → 硬错误。
- 禁止「只写路径、成员洒进全局」的旧语义。
3.3 默认库名
省略 as / 作为 时,库名 = 文件名茎(去掉 .mq.md):
| 路径 | 默认库名 |
|---|---|
lib/time.mq.md |
time |
lib/时间.mq.md |
时间 |
ext/ai/agent.mq.md |
agent |
ext/ai/智能体.mq.md |
智能体 |
3.4 调用解析顺序
- 点号路径 callee(§4)→ 按段在导入库 / 类型树上寻址。
- 当前文件顶层
#/##(无点号的短名)。 - L0 内置。
- 插件注册名(
lib/plugin加载后的全局表)。 - 否则 → 未知 callee。
4. 点号寻址(核心外形)
4.1 文法
path_callee ::= ident ('.' ident)+
- 每一段都是裸标识符(库名、类型名、函数名)。
- 整条路径都不使用反引号。
.只表示寻址分隔,与「变量上的方法调用」分流(§4.4)。
4.2 二段:库.成员
---
> lib/time.mq.md
> 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`
| 路径 | 解析 |
|---|---|
time.now_unix |
库 time → 函数 now_unix |
json.parse |
库 json → 函数 parse |
agent.agent |
库 agent → 类型 agent(构造) |
库根下的函数调用不注入 self / 自。
4.3 三段及以上:库.对象.成员(预留并锁定语义)
后续常见形态:
> agent.agent # 库 → 类型:构造
> 某库.某对象.某函数 # 库 → 类型 → 该类型下的 ## 成员
解析规则(锁定):
- 第一段必须是已导入库名。
- 第二段起在上一段节点的子表中查找:类型节点或函数节点。
- 若最终落在函数上则发起调用;若落在类型上则发起构造。
- 路径中任一段缺失 → 硬错误(禁止模糊回落到全局短名)。
实例方法若需要接收者,仍走 §4.4;库.对象.方法 表示定义树上的该成员(无接收者时:仅当该成员可作为无 self 的关联函数调用,否则报错「需要实例」)。这样 . 始终是定义寻址,逻辑一致。
中文库同理:时间.格式化、智能体.智能体、智能体.智能体.单步(若对类型成员做路径调用)。
4.4 变量 / 实例 vs 库路径(反引号分界)
| 写法 | 左侧重 | 是否反引号 |
|---|---|---|
time.parse |
库名(绑定) | 路径段皆裸名 |
agent.agent |
库名.类型名 | 裸名 |
> `助手`.step |
变量(实例句柄) | 接收者必须反引号 |
> `out`.… |
变量 | 反引号 |
原则:
- 名在定义/导入空间里 → 点号路径,无
` `。 - 名在值环境里(绑定结果、形参、
self)→ 反引号标识符;方法调用保持现有> `obj`.method。
禁止混写 > `time`.parse(把库当成变量)。
4.5 应用侧完整示例
---
> lib/time.mq.md
> lib/writeback.mq.md
> ext/ai/agent.mq.md
---
# main
*`助手` = > agent.agent model=… tools=… *
*`out` = > `助手`.step task=… *
*`body` = > json.stringify value=`out` *
> writeback.record value=`body` key=ok
(上例假定 json 已导入;stringify 为该库成员。)
5. 导出面
默认:库内顶层 # / ## 均可被路径访问。
类型下的 ## 挂在该类型节点下,供 库.类型.成员 寻址;实例调用仍用 `变量`.成员。
本版不引入 private。
6. 显式 use(可选短名,非静默兼容)
| 英文 | 中文 |
|---|---|
> use time.format |
> 使用 时间.格式化 |
> use time.format as fmt |
> 使用 时间.格式化 作为 fmt |
use右侧为点号路径(裸名寻址)。- 引入后本地短名可见;与导入库名或当前文件顶层同名 → 硬错误。
- 禁止
use time.*(无通配use)。
7. 与旧行为的关系(破坏性变更)
| 旧 | 新 |
|---|---|
| 导入 = 合并进全局 | 导入 = 绑定库名 |
| 同名后写覆盖 | 无跨库扁平同名 |
> parse 来源不明 |
必须 json.parse 或显式 use |
(若曾设想)`time`.parse |
否;库路径不加反引号 |
不提供扁平合并过渡开关。
8. 对分层与 ext 的影响
| 层 | 影响 |
|---|---|
| L0 内置 | 仍为全局短名 |
| L1 / 官方 ext | 经库路径调用;ext/**/*.mq.md 严禁 host_* |
| ABI 插件 | 插件注册表;agent/OKF 等领域逻辑放这里,不得塞进 HostFn |
硬规则:不得为「方便」把 ext/ai 领域能力写进 src/host/dispatch.rs / src/host/*.rs。标准库可走 lib/* → 薄 host_*;智能体专属走 plugins/agent 注册名(见 ext-agent.md §4)。
9. 实现要点
- 加载返回模块树(库 → 类型 → 成员);取消跨文件
merge_top_level泼洒。 - 调用方解析
path_callee:按.分段,自导入表下行。 - 区分路径 callee 与
`变量`.方法(词法:首段是否反引号 / 是否含裸点号路径)。 - 金样例与 stdlib 文档改为
time.parse形态。
| 阶段 | 内容 |
|---|---|
| M0 | 本文 Accepted(含本修订) |
| M1 | 二段路径 库.成员 + 破坏旧扁平 — 已落地(tree + bytecode;as/作为;stdlib/ext/tests 已迁) |
| M2 | 三段 库.对象.成员;use / 使用 — 已落地(实例方法路径调用报错,须 `var`.method) |
| M3 | 诊断工具(可选) |
双后端:tree 与 bytecode 均支持点号路径调用与 use / 使用(与 M1/M2 同语义)。
金样例:
| 路径 | 测什么 |
|---|---|
tests/structure/ns/ |
二段/三段路径、use、导入 as |
tests/errors/ns-instance-method.mq.md |
库.类型.方法 无接收者 → 硬错误(须 `var`.method) |
L1 薄包装:命名空间下 net.http_post 等解析到 lib/*.mq.md 的 ## 包装,不是宿主别名。包装未声明的可选形参会被静默丢弃(曾导致 live agent 401:headers 未传到 host_http_post)。规则见 stdlib-modules.md §2.1。
10. 决议摘要
- 导入绑定库名;成员不进全局。
- 调用以裸名点号路径寻址:
库.成员,并支持库.对象.成员;.= 定义树寻址。 - 库名 / 路径段不加反引号;反引号只用于值变量与实例接收者。
- 拒绝扁平合并与裸名双轨兼容;短名仅显式单成员
use。 - M1/M2 已实现;M3 另开。