Files
marqdo/doc/next/006.md
cflmyandCursor 46d78c6e15 feat(core): Phase 2 Metadata scope lift (no body ${})
Inject bound frontmatter keys into the entry env as ordinary variables.
Reject body ${env…}; bytecode entry prologue seeds the same locals.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:05:25 +08:00

17 KiB
Raw Permalink Blame History

type, status, formal, adr
type status formal adr
discussion superseded-by-design doc/design/binding.md doc/adr/0006-artifact-metadata-binding.md

正式规范已落地:讨论收敛见 doc/design/binding.md(Phase 1 Metadata Binding + Phase 2 scope lift)与 ADR 0006。
否决:下文 §17「正文也写 ${…}」——${} 只留在 Metadata;正文用已提升的普通名字。

你的这个设计我觉得不错,配置信息写进元信息,能够自动的处理一些从环境变量中得到的变量,我觉得这个可以写进核心的语法之中,你认为呢?如果可以给我详细的设计方案

我认为非常可以,而且我会进一步建议:把“环境变量 / 外部配置解析”提升为 Marqdo 核心语法的一部分,而不是 ext/ai/llm 自己实现的功能。

但有一个关键边界:

核心语法负责“声明与解析配置”,具体扩展负责“解释配置的语义”。

这样它不会变成“为了 LLM 发明的配置语法”,而会成为 Marqdo 作为 Executable Document 的基础能力。


1. 我建议把它定义成:Artifact Metadata Binding

你现在有:

---
type: llm
backend: openai-compatible
model: gpt-5.6
---

我建议正式把 --- 这一块定义为:

Artifact Metadata

它不只是 YAML front matter,而是 Marqdo 文档的声明式元信息环境。

完整模型:

.mq.md
│
├── Metadata
│   ├── Identity
│   ├── Configuration
│   ├── Dependencies
│   └── Bindings
│
└── Executable Body

于是:

---
type: llm
backend: openai-compatible
model: gpt-5.6
---

实际上是在声明:

这个 Document 是一个 LLM Artifact
它使用 openai-compatible backend
默认 model 是 gpt-5.6

2. 最重要的设计:Metadata 可以引用外部环境

我建议引入一个核心语法:

${...}

例如:

---
type: llm
backend: openai-compatible
model: ${OPENAI_MODEL}
api_key: ${OPENAI_API_KEY}
base_url: ${OPENAI_BASE_URL}
---

这样:

${OPENAI_MODEL}

不是 YAML 的语法,而是:

Marqdo Binding Expression

也就是说:

Metadata
   ↓
Binding
   ↓
Environment / Secret / File / Argument / System

3. 但是不要只设计 ${ENV_VAR}

如果现在只支持:

${OPENAI_API_KEY}

几年以后你一定会发现不够。

我建议一开始就设计成命名空间式 Binding。

例如:

${env.OPENAI_API_KEY}
${arg.model}
${sys.cwd}
${file.config.model}
${secret.OPENAI_API_KEY}

这样 Marqdo 的配置系统可以形成:

binding
├── env
├── arg
├── sys
├── file
├── secret
└── artifact

4. 最基础的语法

我建议:

${namespace.name}

例如:

---
type: llm
model: ${env.OPENAI_MODEL}
api_key: ${env.OPENAI_API_KEY}
base_url: ${env.OPENAI_BASE_URL}
---

这比:

model: ${OPENAI_MODEL}

更值得作为长期语言设计。

因为它避免了未来命名冲突。


5. 默认值必须支持

这是非常重要的。

例如:

---
model: ${env.OPENAI_MODEL | "gpt-5.6"}
base_url: ${env.OPENAI_BASE_URL | "https://api.openai.com/v1"}
---

意思是:

如果 OPENAI_MODEL 存在
    使用它

否则
    使用 gpt-5.6

我甚至建议允许更明确的:

${env.OPENAI_MODEL ?? "gpt-5.6"}

也就是:

A ?? B

代表:

如果 A 不存在,则使用 B。


6. Secret 应该和普通 Environment 区分

这是我非常建议你现在就设计进去的。

不要让:

api_key: ${env.OPENAI_API_KEY}

成为唯一方式。

应该支持:

api_key: ${secret.OPENAI_API_KEY}

语义上:

env
    普通运行环境

secret
    敏感运行环境

这样以后 Marqdo Runtime 可以控制:

secret
├── 不写入 episode
├── 不进入普通 trace
├── 不显示在 echo
├── 不进入错误信息
└── 不进入生成的 knowledge artifact

这对你未来 Agent Framework 非常重要。


7. 我建议增加“必需配置”的语法

比如:

---
type: llm
backend: openai-compatible
model: ${env.OPENAI_MODEL ?? "gpt-5.6"}
api_key: ${secret.OPENAI_API_KEY!}
base_url: ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}
---

这里:

${secret.OPENAI_API_KEY!}

表示:

这个值必须存在。

如果没有:

ConfigurationError:
required binding secret.OPENAI_API_KEY is missing

而不是运行到 HTTP 请求才发现:

401 Unauthorized

这会让 Marqdo 的错误体验好很多。


8. Binding 应该在执行前完成

这是一个非常重要的架构决定。

不要:

执行程序
 ↓
遇到 ${env.X}
 ↓
临时解析

而应该:

Load Artifact
      ↓
Parse Metadata
      ↓
Resolve Bindings
      ↓
Validate Metadata
      ↓
Create Runtime Object
      ↓
Execute

也就是说:

.mq.md
  ↓
Artifact
  ↓
Bound Artifact

例如:

---
type: llm
model: ${env.OPENAI_MODEL ?? "gpt-5.6"}
---

加载以后内部应该变成:

model = "gpt-5.6"

而不是每次访问:

model
 ↓
去环境变量查询

这样有三个好处:

  1. 配置确定性更强
  2. 性能更好
  3. Debug 可以知道最终配置是什么

9. 但是 Secret 不应该真的被普通内部结构展开

这里可以做得非常漂亮。

普通变量:

${env.OPENAI_MODEL}

解析成:

Value("gpt-5.6")

Secret:

${secret.OPENAI_API_KEY}

解析成:

SecretValue(...)

而不是普通 String。

于是 Runtime 可以知道:

Value
SecretValue

是两种不同类型。

例如:

print(api_key)

自动输出:

<secret>

而:

HTTP Authorization

可以正常得到真正值。

这实际上可以成为 Marqdo 类型系统的一部分:

String
Secret
Number
Boolean
Table
Document
...

10. Metadata 本身也应该支持类型

我建议不要把 front matter 看成:

YAML → Map<String,String>

而是:

Metadata → Marqdo Value

所以:

---
type: llm
temperature: 0.2
stream: false
max_tokens: 2048
tags:
  - ai
  - llm
---

应该保留类型:

type        String
temperature Number
stream      Boolean
max_tokens  Number
tags        List

而:

model: ${env.OPENAI_MODEL}

解析之后也是:

String

11. 更进一步:Binding 应该允许转换

例如:

---
max_tokens: ${env.MAX_TOKENS}
temperature: ${env.TEMPERATURE}
stream: ${env.STREAM}
---

环境变量天然都是字符串。

但 Marqdo 应该允许:

${env.MAX_TOKENS -> int}
${env.TEMPERATURE -> float}
${env.STREAM -> bool}

或者更简洁:

${int(env.MAX_TOKENS)}
${float(env.TEMPERATURE)}
${bool(env.STREAM)}

我个人更倾向后者:

${int(...)}

因为它以后可以扩展。


12. 这实际上可以成为 Marqdo 的 Configuration Language

例如:

---
type: llm

backend: openai-compatible

model: ${env.OPENAI_MODEL ?? "gpt-5.6"}

base_url:
  ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}

api_key:
  ${secret.OPENAI_API_KEY!}

temperature:
  ${float(env.OPENAI_TEMPERATURE ?? "0.2")}

max_tokens:
  ${int(env.OPENAI_MAX_TOKENS ?? "4096")}
---

这已经不是简单的 YAML 了。

它实际上是:

Marqdo Artifact Declaration Language


13. 我建议增加 config 命名空间

还有一个很重要的场景:

多个 .mq.md 共享配置。

例如:

config.mq.md
---
type: config

llm:
  model: ${env.OPENAI_MODEL ?? "gpt-5.6"}
  base_url: ${env.OPENAI_BASE_URL ?? "..."}
---

其他文件:

---
type: llm
config: ./config.mq.md
---

或者:

---
type: llm
model: ${config.llm.model}
base_url: ${config.llm.base_url}
---

于是:

Environment
      ↓
Config
      ↓
Artifact

形成配置层级。


14. 我甚至建议支持配置覆盖

这是 Agent Framework 非常需要的。

例如:

---
type: llm
model: ${config.llm.model ?? "gpt-5.6"}
---

运行:

marqdo run task.mq.md --model=gpt-5.6-mini

那么:

arg.model

可以覆盖:

config.llm.model

形成:

Priority

explicit argument
       ↓
artifact metadata
       ↓
config
       ↓
environment
       ↓
default

但这里我要特别建议:

不要让环境变量静默覆盖 Artifact 明确写出的配置。

否则:

model: gpt-5.6

用户看到的是 gpt-5.6,

机器却因为:

OPENAI_MODEL=gpt-5-mini

实际运行了另一个模型。

这是非常危险的可复现性问题。


15. 所以我建议明确一个 Resolution Policy

例如:

explicit metadata
    >
argument
    >
config
    >
environment
    >
default

或者如果 CLI 参数需要最高优先级:

CLI argument
    >
explicit metadata
    >
config
    >
environment
    >
default

我更推荐:

CLI
 ↓
Artifact
 ↓
Config
 ↓
Environment
 ↓
Default

因为:

Artifact = 文档作者意图
Environment = 运行环境

这符合“代码即文档”的哲学。


16. 但环境变量应该允许显式 opt-in 覆盖

有时候部署环境确实需要:

production
 ↓
覆盖 model

所以可以提供:

---
type: llm

model:
  value: gpt-5.6
  override: env.OPENAI_MODEL
---

或者更简单:

---
type: llm
model: gpt-5.6
model_override: ${env.OPENAI_MODEL}
---

这样覆盖是显式的,而不是隐式的。


17. 一个非常重要的设计:Binding 不应该只能出现在 Metadata

既然这是核心语言能力,我建议:

${...}

可以在整个 Marqdo 中出现。

例如:

# Hello ${env.USER_NAME}

Current model: ${config.llm.model}

代码中:

**path = ${env.DATA_PATH}**

参数中:

**answer = > llm.ask prompt=${file.prompt}**

表格中:

| model | ${env.OPENAI_MODEL} |

所以它真正是:

Marqdo Interpolation / Binding

而不是:

YAML Environment Variable Feature。


18. 但要区分「文本插值」和「值绑定」

这是语言设计中很容易踩坑的地方。

例如:

"model=${env.OPENAI_MODEL}"

这是:

String interpolation

而:

model: ${env.OPENAI_MODEL}

应该是:

Value binding

两者不能完全一样。

比如:

temperature: ${env.TEMPERATURE}

如果环境变量是:

0.2

应该得到:

Number(0.2)

而不是:

String("0.2")

因此我建议:

${...}

本身是一个 Expression。

当它独占一个 value 时:

Value Binding

当它出现在字符串内部:

Interpolation

例如:

${env.USER}

→ 原始值

而:

"Hello ${env.USER}"

→ String

这会非常干净。


19. Binding 可以进一步支持文件

这对于 .mq.md 非常有意义。

例如:

---
system_prompt: ${file.system_prompt}
knowledge: ${file.knowledge}
---

甚至:

${file("./knowledge.md")}

这样:

Document
   ↓
Metadata
   ↓
External Artifact

天然形成知识组合。

这和你:

Executable Documents → Executable Knowledge Bases

的研究方向又连接起来了。


20. 我建议最终定义 6 个核心 Binding Source

第一版其实不用太多:

env
arg
sys
file
config
secret

分别:

Namespace 意义
env 环境变量
arg CLI / Runtime 参数
sys Runtime 系统信息
file 外部文件
config 配置 Artifact
secret Secret Provider

以后再扩展:

artifact
context
memory
agent

但第一版不要过度设计。


21. 我还建议把环境变量的“读取”从 sys 中移出来

你现在:

sys.env_get

这是我认为非常值得改的地方。

sys 应该是:

sys.cwd
sys.platform
sys.time
sys.argv

而:

env

应该成为语言 Runtime 的 Binding Source。

于是用户不应该写:

**api_key = > sys.env_get name="OPENAI_API_KEY"**

而应该:

api_key: ${secret.OPENAI_API_KEY!}

甚至程序里:

**path = ${env.DATA_PATH}**

这会让代码明显干净很多。


22. 对你的 llm.mq.md,最终可以简化成非常漂亮的东西

例如:

---
type: llm

backend: openai-compatible

model: ${env.OPENAI_MODEL ?? "gpt-5.6"}

base_url:
  ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}

api_key:
  ${secret.OPENAI_API_KEY!}
---

然后下面:

**## ask**

Ask the configured language model.

+ `prompt`

**result = > self.complete prompt=`prompt`**

*[text](result)*

这里 complete 只是 backend implementation。

用户层:

**answer = > llm.ask**

就已经足够。


23. 最关键的是:Metadata 本身可以成为可执行配置

这一步我认为特别适合 Marqdo。

例如:

---
type: llm

backend: ${config.llm.backend ?? "openai-compatible"}

model: ${arg.model ?? env.OPENAI_MODEL ?? "gpt-5.6"}

temperature: ${float(
  arg.temperature ??
  env.OPENAI_TEMPERATURE ??
  "0.2"
)}

api_key: ${secret.OPENAI_API_KEY!}
---

这已经具备:

Declaration
+
Configuration
+
Binding
+
Default
+
Type conversion

因此 .mq.md 不再只是:

Markdown + YAML

而是:

Self-contained Executable Artifact


24. 我建议给这个机制一个正式名字

不要叫:

Environment Variables

太窄。

我比较推荐:

Marqdo Binding

语法:

${expression}

文档里可以称:

Binding Expression

例如:

${env.OPENAI_API_KEY}

是:

Environment Binding

${config.llm.model}

是:

Configuration Binding

${secret.OPENAI_API_KEY}

是:

Secret Binding

这套命名以后非常容易扩展。


25. 最终 Runtime 架构

我建议把它设计成:

                    .mq.md
                       │
                       ▼
               ┌──────────────┐
               │ Metadata     │
               │ + Body       │
               └──────┬───────┘
                      │
                      ▼
              Binding Resolver
                      │
       ┌──────────────┼──────────────┐
       ▼              ▼              ▼
      env           config         secret
       │              │              │
       └──────────────┼──────────────┘
                      ▼
                Bound Artifact
                      │
              ┌───────┴────────┐
              ▼                ▼
           Runtime          Document
              │
              ▼
          Execution

然后最重要的一条:

Artifact Source
      ↓
Binding Resolution
      ↓
Execution

而不是:

Execution
 ↓
到处 getenv()

26. 这甚至可以成为 Marqdo 的一个语言卖点

如果未来论文里描述,我会把它归到:

Executable Configuration

而不是简单的:

Environment Variable Support

因为传统配置通常是:

Code
 +
Config
 +
Environment

三套东西。

Marqdo 可以变成:

Executable Artifact
       │
       ├── Logic
       ├── Knowledge
       ├── Configuration
       └── Environment Bindings

所以一个 .mq.md 可以真正做到:

携带自己的执行语义,同时声明自己依赖哪些外部运行时资源。

这和你整个“Executable Document → Executable Knowledge Base”的方向是高度一致的。


我会把第一版核心规范收敛成这 7 条

1. --- ... --- 是 Marqdo Artifact Metadata

2. Metadata value 可以包含 ${expression}

3. ${namespace.name} 是 Binding Expression

4. 第一版 namespace:
   env / arg / sys / config / file / secret

5. Binding 在 Artifact Load 阶段统一解析

6. 独占 value 时保留原始类型;
   出现在字符串中时进行 interpolation

7. Resolution:
   CLI → Artifact → Config → Environment → Default

然后再加:

${expr ?? default}
${expr!}
${int(expr)}
${float(expr)}
${bool(expr)}

这就已经是一套相当完整的语言特性了。

而且我认为最值得做的不是“让 LLM 配置更方便”,而是把它正式确立为 Marqdo 的 Binding 机制。这样未来 llm、agent、database、network、skill、knowledge 都能统一使用同一套核心语法,而不会每个扩展自己发明一套环境变量读取方式。