Files
marqdo/doc/design/module-namespace.md
T
cflmyandCursor d1b33c78c6 Make file subtasks return #main value and expose it as plan.result.
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>
2026-08-07 17:53:14 +08:00

9.6 KiB
Raw Blame History

模块命名空间(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 目标

  1. 导入绑定库名:导入一个 .mq.md 得到一个库(模块)绑定,成员不倒进全局。
  2. 点号寻址调用:库.成员、并预留 库.对象.成员 等多段路径;. 表示在定义树上的寻址,不是字段运算。
  3. 库名不是变量:寻址段为裸标识符,不加反引号。反引号只用于值槽位(变量 / 形参 / 实例句柄)。
  4. 模块内名字默认不进全局;需要本地短名时必须显式 use,且冲突报错。
  5. 中英对等:路径中英分文件;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 调用解析顺序

  1. 点号路径 callee(§4)→ 按段在导入库 / 类型树上寻址。
  2. 当前文件顶层 # / ##(无点号的短名)。
  3. L0 内置。
  4. 插件注册名(lib/plugin 加载后的全局表)。
  5. 否则 → 未知 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          # 库 → 类型:构造
> 某库.某对象.某函数    # 库 → 类型 → 该类型下的 ## 成员

解析规则(锁定):

  1. 第一段必须是已导入库名。
  2. 第二段起在上一段节点的子表中查找:类型节点或函数节点。
  3. 若最终落在函数上则发起调用;若落在类型上则发起构造。
  4. 路径中任一段缺失 → 硬错误(禁止模糊回落到全局短名)。

实例方法若需要接收者,仍走 §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. 实现要点

  1. 加载返回模块树(库 → 类型 → 成员);取消跨文件 merge_top_level 泼洒。
  2. 调用方解析 path_callee:按 . 分段,自导入表下行。
  3. 区分路径 callee 与 `变量`.方法(词法:首段是否反引号 / 是否含裸点号路径)。
  4. 金样例与 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. 决议摘要

  1. 导入绑定库名;成员不进全局。
  2. 调用以裸名点号路径寻址:库.成员,并支持 库.对象.成员;. = 定义树寻址。
  3. 库名 / 路径段不加反引号;反引号只用于值变量与实例接收者。
  4. 拒绝扁平合并与裸名双轨兼容;短名仅显式单成员 use。
  5. M1/M2 已实现;M3 另开。