- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
17 KiB
Executable File
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
↓
去环境变量查询
这样有三个好处:
- 配置确定性更强
- 性能更好
- 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 都能统一使用同一套核心语法,而不会每个扩展自己发明一套环境变量读取方式。