- 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。
1336 lines
17 KiB
Markdown
Executable File
1336 lines
17 KiB
Markdown
Executable File
---
|
||
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` 都能统一使用同一套核心语法,而不会每个扩展自己发明一套环境变量读取方式。
|