Files
marqdo/doc/design/binding.md
T
cflmyandCursor 687c168014 feat(parse): use nested YAML import: maps instead of one-liner binds
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>
2026-10-23 19:33:58 +08:00

5.3 KiB
Raw Blame History

Marqdo Binding · Artifact Metadata

状态 Accepted · Phase 1 + Phase 2(scope lift)
日期 2026-09-24
ADR 0006-artifact-metadata-binding.md
讨论稿 doc/next/006.md
实现 src/binding/ · Module.metadata · entry env lift · sys.meta / sys.meta_get · marqdo run --bind

边界:核心负责「声明与解析配置」;扩展负责「解释配置的语义」。
${…} 只出现在文件头 Artifact Metadata——正文 / 粗体 / 调用 / 表 永不写 ${env…}(否决讨论稿 §17)。正文使用已绑定的普通名字。


1. Artifact Metadata

文件开头成对 --- 之间为 Artifact Metadata(声明式元信息环境),不是「随便贴的 YAML」。

.mq.md
├── Metadata   ← Identity / Configuration / Dependencies / Bindings
└── Executable Body
  • import bind:… / 导入 行:模块依赖(既有语义不变)。
  • 其它 key: value 行:元信息;值可为字面量或 Binding Expression。
  • Phase 1 仅支持 flat 键(同级 key: value);块标量 > / | 收成 Text。

例:

---
title: demo
type: llm
model: ${env.OPENAI_MODEL ?? "gpt-4o-mini"}
api_key: ${secret.OPENAI_API_KEY!}
base_url: ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}
import:
  sys: lib/sys.mq.md
---

加载后内部为已绑定的 Module.metadata(确定性快照),执行期不再对同一键反复 getenv。


2. Binding Expression

外形:

${expression}

2.1 路径

${namespace.name}
Namespace 意义 Phase 1
env 进程环境变量 ✅
arg CLI / Runtime 绑定(marqdo run --bind KEY=VALUE) ✅
sys 系统信息:cwd · platform ✅
secret 敏感环境变量 → Value::Secret ✅
config 配置 Artifact 推迟
file 外部文件内容 推迟

2.2 默认与必需

${env.OPENAI_MODEL ?? "gpt-4o-mini"}
${secret.OPENAI_API_KEY!}
  • A ?? B:A 缺失(未设置 / 空)则用 B。
  • A!:A 必须存在,否则加载失败(config.required_binding_missing)。

2.3 类型转换

${int(env.MAX_TOKENS ?? "4096")}
${float(env.TEMPERATURE ?? "0.2")}
${bool(env.STREAM ?? "false")}

2.4 独占 value vs 插值

形态 语义
model: ${env.OPENAI_MODEL} Value binding — 保留解析后的类型(含 Secret)
title: "Hello ${env.USER}" Interpolation — 结果为 Text
model: gpt-4o-mini Literal — 字面量;不会被环境变量静默覆盖

3. Resolution Policy

对每个 metadata 键:

  1. 解析该键的字面量 / Binding / 插值(字面量定稿后不受 env 覆盖)。
  2. 若 CLI 提供了同名 --bind KEY=VALUE,覆盖该键的最终值(Text)。
  3. Binding 内部查找顺序(仅当表达式写出时):arg / env / secret / sys 按表达式 namespace;?? 链从左到右。

推荐作者意图:

CLI --bind
  → Artifact 字面量 / 已写死的 Binding 结果
  → Binding 源(env / secret / …)
  → ?? 默认

4. Secret

${secret.NAME} → Value::Secret。

  • print / str / Display → <secret>(不泄露)。
  • type → secret。
  • 与 Text 拼接(如 bearer + api_key)时揭示明文,供 HTTP Authorization。
  • 不得进入普通 episode / 错误信息明文(扩展作者责任;核心 Display 已遮掩)。

5. Runtime API

API 语义
sys.meta / 系统.元信息 入口模块已绑定 metadata(map)
sys.meta_get / 系统.取元信息 key= → 值或 None
marqdo run FILE --bind KEY=VALUE 可重复;写入 arg 并覆盖同名 metadata 键
sys.env_get 保留逃逸口;新代码优先 Metadata Binding

6. 错误

code 何时
config.required_binding_missing ${ns.name!} 且源缺失
config.unknown_binding_ns 未知 namespace
config.bad_binding 表达式非法 / cast 失败

诊断尽量带 frontmatter 行号。


7. 与扩展的分工

  • 核心:解析 Metadata、resolve Binding、暴露 Module.metadata / sys.meta*,并在入口把 metadata 提升为普通变量。
  • ext/ai/llm:构造次序为 显式实参 → 入口作用域同名变量 / sys.meta_get → sys.env_get 回退 → 默认。

8. Phase 2 · Metadata scope lift(Accepted)

加载期绑定完成后,入口执行(# main 或唯一无参顶层对象)前,把 Module.metadata 的每个键注入 entry 环境,成为普通变量:

---
model: ${env.ModelName ?? "gpt-4o-mini"}
---
# main

> print text=`model`

规则

  1. 注入时机:进入入口函数之前。
  2. 冲突:形参 / 调用实参 覆盖 同名 metadata;程序内赋值亦然。metadata 不覆盖已存在的绑定。
  3. sys.meta / sys.meta_get 仍可用(显式通道)。
  4. 拒绝 正文 / 粗体 / 表 / 叙述中的 ${…}(讨论稿 006 §17 否决)。普通语言也不在语句里 ${ENV}。

仍推迟(P3+)

  • config / file namespace
  • 嵌套 YAML map
  • 显式 override: 糖
  • 计入 CORE_CONSTRUCTS