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

1336 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
type: discussion
status: superseded-by-design
formal: doc/design/binding.md
adr: doc/adr/0006-artifact-metadata-binding.md
---
> **正式规范已落地**:讨论收敛见 [doc/design/binding.md](../design/binding.md)(Phase 1 Metadata Binding + Phase 2 scope lift)与 [ADR 0006](../adr/0006-artifact-metadata-binding.md)。
> **否决**:下文 §17「正文也写 `${…}`」——`${}` 只留在 Metadata;正文用已提升的普通名字。
你的这个设计我觉得不错,配置信息写进元信息,能够自动的处理一些从环境变量中得到的变量,我觉得这个可以写进核心的语法之中,你认为呢?如果可以给我详细的设计方案
我认为**非常可以,而且我会进一步建议:把“环境变量 / 外部配置解析”提升为 Marqdo 核心语法的一部分,而不是 `ext/ai/llm` 自己实现的功能。**
但有一个关键边界:
> **核心语法负责“声明与解析配置”,具体扩展负责“解释配置的语义”。**
这样它不会变成“为了 LLM 发明的配置语法”,而会成为 Marqdo 作为 **Executable Document** 的基础能力。
---
# 1. 我建议把它定义成:Artifact Metadata Binding
你现在有:
```yaml
---
type: llm
backend: openai-compatible
model: gpt-5.6
---
```
我建议正式把 `---` 这一块定义为:
> **Artifact Metadata**
它不只是 YAML front matter,而是 Marqdo 文档的**声明式元信息环境**。
完整模型:
```text
.mq.md
│
├── Metadata
│ ├── Identity
│ ├── Configuration
│ ├── Dependencies
│ └── Bindings
│
└── Executable Body
```
于是:
```yaml
---
type: llm
backend: openai-compatible
model: gpt-5.6
---
```
实际上是在声明:
```text
这个 Document 是一个 LLM Artifact
它使用 openai-compatible backend
默认 model 是 gpt-5.6
```
---
# 2. 最重要的设计:Metadata 可以引用外部环境
我建议引入一个核心语法:
```text
${...}
```
例如:
```yaml
---
type: llm
backend: openai-compatible
model: ${OPENAI_MODEL}
api_key: ${OPENAI_API_KEY}
base_url: ${OPENAI_BASE_URL}
---
```
这样:
```text
${OPENAI_MODEL}
```
不是 YAML 的语法,而是:
> **Marqdo Binding Expression**
也就是说:
```text
Metadata
↓
Binding
↓
Environment / Secret / File / Argument / System
```
---
# 3. 但是不要只设计 `${ENV_VAR}`
如果现在只支持:
```text
${OPENAI_API_KEY}
```
几年以后你一定会发现不够。
我建议一开始就设计成**命名空间式 Binding**。
例如:
```text
${env.OPENAI_API_KEY}
${arg.model}
${sys.cwd}
${file.config.model}
${secret.OPENAI_API_KEY}
```
这样 Marqdo 的配置系统可以形成:
```text
binding
├── env
├── arg
├── sys
├── file
├── secret
└── artifact
```
---
# 4. 最基础的语法
我建议:
```text
${namespace.name}
```
例如:
```yaml
---
type: llm
model: ${env.OPENAI_MODEL}
api_key: ${env.OPENAI_API_KEY}
base_url: ${env.OPENAI_BASE_URL}
---
```
这比:
```yaml
model: ${OPENAI_MODEL}
```
更值得作为长期语言设计。
因为它避免了未来命名冲突。
---
# 5. 默认值必须支持
这是非常重要的。
例如:
```yaml
---
model: ${env.OPENAI_MODEL | "gpt-5.6"}
base_url: ${env.OPENAI_BASE_URL | "https://api.openai.com/v1"}
---
```
意思是:
```text
如果 OPENAI_MODEL 存在
使用它
否则
使用 gpt-5.6
```
我甚至建议允许更明确的:
```text
${env.OPENAI_MODEL ?? "gpt-5.6"}
```
也就是:
```text
A ?? B
```
代表:
> 如果 A 不存在,则使用 B。
---
# 6. Secret 应该和普通 Environment 区分
这是我非常建议你现在就设计进去的。
不要让:
```yaml
api_key: ${env.OPENAI_API_KEY}
```
成为唯一方式。
应该支持:
```yaml
api_key: ${secret.OPENAI_API_KEY}
```
语义上:
```text
env
普通运行环境
secret
敏感运行环境
```
这样以后 Marqdo Runtime 可以控制:
```text
secret
├── 不写入 episode
├── 不进入普通 trace
├── 不显示在 echo
├── 不进入错误信息
└── 不进入生成的 knowledge artifact
```
这对你未来 Agent Framework 非常重要。
---
# 7. 我建议增加“必需配置”的语法
比如:
```yaml
---
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"}
---
```
这里:
```text
${secret.OPENAI_API_KEY!}
```
表示:
> 这个值必须存在。
如果没有:
```text
ConfigurationError:
required binding secret.OPENAI_API_KEY is missing
```
而不是运行到 HTTP 请求才发现:
```text
401 Unauthorized
```
这会让 Marqdo 的错误体验好很多。
---
# 8. Binding 应该在执行前完成
这是一个非常重要的架构决定。
不要:
```text
执行程序
↓
遇到 ${env.X}
↓
临时解析
```
而应该:
```text
Load Artifact
↓
Parse Metadata
↓
Resolve Bindings
↓
Validate Metadata
↓
Create Runtime Object
↓
Execute
```
也就是说:
```text
.mq.md
↓
Artifact
↓
Bound Artifact
```
例如:
```yaml
---
type: llm
model: ${env.OPENAI_MODEL ?? "gpt-5.6"}
---
```
加载以后内部应该变成:
```text
model = "gpt-5.6"
```
而不是每次访问:
```text
model
↓
去环境变量查询
```
这样有三个好处:
1. 配置确定性更强
2. 性能更好
3. Debug 可以知道最终配置是什么
---
# 9. 但是 Secret 不应该真的被普通内部结构展开
这里可以做得非常漂亮。
普通变量:
```text
${env.OPENAI_MODEL}
```
解析成:
```text
Value("gpt-5.6")
```
Secret:
```text
${secret.OPENAI_API_KEY}
```
解析成:
```text
SecretValue(...)
```
而不是普通 String。
于是 Runtime 可以知道:
```text
Value
SecretValue
```
是两种不同类型。
例如:
```text
print(api_key)
```
自动输出:
```text
<secret>
```
而:
```text
HTTP Authorization
```
可以正常得到真正值。
这实际上可以成为 Marqdo 类型系统的一部分:
```text
String
Secret
Number
Boolean
Table
Document
...
```
---
# 10. Metadata 本身也应该支持类型
我建议不要把 front matter 看成:
```text
YAML → Map<String,String>
```
而是:
```text
Metadata → Marqdo Value
```
所以:
```yaml
---
type: llm
temperature: 0.2
stream: false
max_tokens: 2048
tags:
- ai
- llm
---
```
应该保留类型:
```text
type String
temperature Number
stream Boolean
max_tokens Number
tags List
```
而:
```yaml
model: ${env.OPENAI_MODEL}
```
解析之后也是:
```text
String
```
---
# 11. 更进一步:Binding 应该允许转换
例如:
```yaml
---
max_tokens: ${env.MAX_TOKENS}
temperature: ${env.TEMPERATURE}
stream: ${env.STREAM}
---
```
环境变量天然都是字符串。
但 Marqdo 应该允许:
```text
${env.MAX_TOKENS -> int}
${env.TEMPERATURE -> float}
${env.STREAM -> bool}
```
或者更简洁:
```text
${int(env.MAX_TOKENS)}
${float(env.TEMPERATURE)}
${bool(env.STREAM)}
```
我个人更倾向后者:
```text
${int(...)}
```
因为它以后可以扩展。
---
# 12. 这实际上可以成为 Marqdo 的 Configuration Language
例如:
```yaml
---
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` 共享配置。
例如:
```text
config.mq.md
```
```yaml
---
type: config
llm:
model: ${env.OPENAI_MODEL ?? "gpt-5.6"}
base_url: ${env.OPENAI_BASE_URL ?? "..."}
---
```
其他文件:
```yaml
---
type: llm
config: ./config.mq.md
---
```
或者:
```yaml
---
type: llm
model: ${config.llm.model}
base_url: ${config.llm.base_url}
---
```
于是:
```text
Environment
↓
Config
↓
Artifact
```
形成配置层级。
---
# 14. 我甚至建议支持配置覆盖
这是 Agent Framework 非常需要的。
例如:
```yaml
---
type: llm
model: ${config.llm.model ?? "gpt-5.6"}
---
```
运行:
```text
marqdo run task.mq.md --model=gpt-5.6-mini
```
那么:
```text
arg.model
```
可以覆盖:
```text
config.llm.model
```
形成:
```text
Priority
explicit argument
↓
artifact metadata
↓
config
↓
environment
↓
default
```
但这里我要特别建议:
> **不要让环境变量静默覆盖 Artifact 明确写出的配置。**
否则:
```yaml
model: gpt-5.6
```
用户看到的是 gpt-5.6,
机器却因为:
```text
OPENAI_MODEL=gpt-5-mini
```
实际运行了另一个模型。
这是非常危险的可复现性问题。
---
# 15. 所以我建议明确一个 Resolution Policy
例如:
```text
explicit metadata
>
argument
>
config
>
environment
>
default
```
或者如果 CLI 参数需要最高优先级:
```text
CLI argument
>
explicit metadata
>
config
>
environment
>
default
```
我更推荐:
```text
CLI
↓
Artifact
↓
Config
↓
Environment
↓
Default
```
因为:
```text
Artifact = 文档作者意图
Environment = 运行环境
```
这符合“代码即文档”的哲学。
---
# 16. 但环境变量应该允许显式 opt-in 覆盖
有时候部署环境确实需要:
```text
production
↓
覆盖 model
```
所以可以提供:
```yaml
---
type: llm
model:
value: gpt-5.6
override: env.OPENAI_MODEL
---
```
或者更简单:
```yaml
---
type: llm
model: gpt-5.6
model_override: ${env.OPENAI_MODEL}
---
```
这样**覆盖是显式的**,而不是隐式的。
---
# 17. 一个非常重要的设计:Binding 不应该只能出现在 Metadata
既然这是核心语言能力,我建议:
```text
${...}
```
可以在整个 Marqdo 中出现。
例如:
```markdown
# Hello ${env.USER_NAME}
Current model: ${config.llm.model}
```
代码中:
```marqdo
**path = ${env.DATA_PATH}**
```
参数中:
```marqdo
**answer = > llm.ask prompt=${file.prompt}**
```
表格中:
```markdown
| model | ${env.OPENAI_MODEL} |
```
所以它真正是:
> **Marqdo Interpolation / Binding**
而不是:
> YAML Environment Variable Feature。
---
# 18. 但要区分「文本插值」和「值绑定」
这是语言设计中很容易踩坑的地方。
例如:
```text
"model=${env.OPENAI_MODEL}"
```
这是:
```text
String interpolation
```
而:
```yaml
model: ${env.OPENAI_MODEL}
```
应该是:
```text
Value binding
```
两者不能完全一样。
比如:
```yaml
temperature: ${env.TEMPERATURE}
```
如果环境变量是:
```text
0.2
```
应该得到:
```text
Number(0.2)
```
而不是:
```text
String("0.2")
```
因此我建议:
```text
${...}
```
本身是一个 **Expression**。
当它独占一个 value 时:
```text
Value Binding
```
当它出现在字符串内部:
```text
Interpolation
```
例如:
```text
${env.USER}
```
→ 原始值
而:
```text
"Hello ${env.USER}"
```
→ String
这会非常干净。
---
# 19. Binding 可以进一步支持文件
这对于 `.mq.md` 非常有意义。
例如:
```yaml
---
system_prompt: ${file.system_prompt}
knowledge: ${file.knowledge}
---
```
甚至:
```text
${file("./knowledge.md")}
```
这样:
```text
Document
↓
Metadata
↓
External Artifact
```
天然形成知识组合。
这和你:
> Executable Documents → Executable Knowledge Bases
的研究方向又连接起来了。
---
# 20. 我建议最终定义 6 个核心 Binding Source
第一版其实不用太多:
```text
env
arg
sys
file
config
secret
```
分别:
| Namespace | 意义 |
| --------- | ---------------- |
| `env` | 环境变量 |
| `arg` | CLI / Runtime 参数 |
| `sys` | Runtime 系统信息 |
| `file` | 外部文件 |
| `config` | 配置 Artifact |
| `secret` | Secret Provider |
以后再扩展:
```text
artifact
context
memory
agent
```
但第一版不要过度设计。
---
# 21. 我还建议把环境变量的“读取”从 `sys` 中移出来
你现在:
```marqdo
sys.env_get
```
这是我认为非常值得改的地方。
`sys` 应该是:
```text
sys.cwd
sys.platform
sys.time
sys.argv
```
而:
```text
env
```
应该成为语言 Runtime 的 Binding Source。
于是用户不应该写:
```marqdo
**api_key = > sys.env_get name="OPENAI_API_KEY"**
```
而应该:
```yaml
api_key: ${secret.OPENAI_API_KEY!}
```
甚至程序里:
```marqdo
**path = ${env.DATA_PATH}**
```
这会让代码明显干净很多。
---
# 22. 对你的 `llm.mq.md`,最终可以简化成非常漂亮的东西
例如:
```yaml
---
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!}
---
```
然后下面:
```marqdo
**## ask**
Ask the configured language model.
+ `prompt`
**result = > self.complete prompt=`prompt`**
*[text](result)*
```
这里 `complete` 只是 backend implementation。
用户层:
```marqdo
**answer = > llm.ask**
```
就已经足够。
---
# 23. 最关键的是:Metadata 本身可以成为可执行配置
这一步我认为特别适合 Marqdo。
例如:
```yaml
---
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!}
---
```
这已经具备:
```text
Declaration
+
Configuration
+
Binding
+
Default
+
Type conversion
```
因此 `.mq.md` 不再只是:
```text
Markdown + YAML
```
而是:
> **Self-contained Executable Artifact**
---
# 24. 我建议给这个机制一个正式名字
不要叫:
> Environment Variables
太窄。
我比较推荐:
### **Marqdo Binding**
语法:
```text
${expression}
```
文档里可以称:
> **Binding Expression**
例如:
```text
${env.OPENAI_API_KEY}
```
是:
> Environment Binding
```text
${config.llm.model}
```
是:
> Configuration Binding
```text
${secret.OPENAI_API_KEY}
```
是:
> Secret Binding
这套命名以后非常容易扩展。
---
# 25. 最终 Runtime 架构
我建议把它设计成:
```text
.mq.md
│
▼
┌──────────────┐
│ Metadata │
│ + Body │
└──────┬───────┘
│
▼
Binding Resolver
│
┌──────────────┼──────────────┐
▼ ▼ ▼
env config secret
│ │ │
└──────────────┼──────────────┘
▼
Bound Artifact
│
┌───────┴────────┐
▼ ▼
Runtime Document
│
▼
Execution
```
然后最重要的一条:
```text
Artifact Source
↓
Binding Resolution
↓
Execution
```
而不是:
```text
Execution
↓
到处 getenv()
```
---
# 26. 这甚至可以成为 Marqdo 的一个语言卖点
如果未来论文里描述,我会把它归到:
> **Executable Configuration**
而不是简单的:
> Environment Variable Support
因为传统配置通常是:
```text
Code
+
Config
+
Environment
```
三套东西。
Marqdo 可以变成:
```text
Executable Artifact
│
├── Logic
├── Knowledge
├── Configuration
└── Environment Bindings
```
所以一个 `.mq.md` 可以真正做到:
> **携带自己的执行语义,同时声明自己依赖哪些外部运行时资源。**
这和你整个“Executable Document → Executable Knowledge Base”的方向是高度一致的。
---
## 我会把第一版核心规范收敛成这 7 条
```text
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
```
然后再加:
```text
${expr ?? default}
${expr!}
${int(expr)}
${float(expr)}
${bool(expr)}
```
这就已经是一套相当完整的语言特性了。
而且我认为**最值得做的不是“让 LLM 配置更方便”,而是把它正式确立为 Marqdo 的 `Binding` 机制**。这样未来 `llm`、`agent`、`database`、`network`、`skill`、`knowledge` 都能统一使用同一套核心语法,而不会每个扩展自己发明一套环境变量读取方式。