--- 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 ``` 而: ```text HTTP Authorization ``` 可以正常得到真正值。 这实际上可以成为 Marqdo 类型系统的一部分: ```text String Secret Number Boolean Table Document ... ``` --- # 10. Metadata 本身也应该支持类型 我建议不要把 front matter 看成: ```text YAML → Map ``` 而是: ```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` 都能统一使用同一套核心语法,而不会每个扩展自己发明一套环境变量读取方式。