- 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。
5.3 KiB
Executable File
5.3 KiB
Executable File
Marqdo Binding · Artifact Metadata
| 状态 | Accepted · Phase 1 + Phase 2(scope lift) |
| 日期 | 2026-09-24 |
| ADR | 0006-artifact-metadata-binding.md |
| 讨论稿 | doc/next/006.md |
| 实现 | src/binding/ · Module.metadata · entry env lift · sys.meta / sys.meta_get · marqdo run --bind |
边界:核心负责「声明与解析配置」;扩展负责「解释配置的语义」。
${…}只出现在文件头 Artifact Metadata——正文 / 粗体 / 调用 / 表 永不写${env…}(否决讨论稿 §17)。正文使用已绑定的普通名字。
1. Artifact Metadata
文件开头成对 --- 之间为 Artifact Metadata(声明式元信息环境),不是「随便贴的 YAML」。
.mq.md
├── Metadata ← Identity / Configuration / Dependencies / Bindings
└── Executable Body
import bind:…/导入行:模块依赖(既有语义不变)。- 其它
key: value行:元信息;值可为字面量或 Binding Expression。 - Phase 1 仅支持 flat 键(同级
key: value);块标量>/|收成 Text。
例:
---
title: demo
type: llm
model: ${env.OPENAI_MODEL ?? "gpt-4o-mini"}
api_key: ${secret.OPENAI_API_KEY!}
base_url: ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}
import:
sys: lib/sys.mq.md
---
加载后内部为已绑定的 Module.metadata(确定性快照),执行期不再对同一键反复 getenv。
2. Binding Expression
外形:
${expression}
2.1 路径
${namespace.name}
| Namespace | 意义 | Phase 1 |
|---|---|---|
env |
进程环境变量 | ✅ |
arg |
CLI / Runtime 绑定(marqdo run --bind KEY=VALUE) |
✅ |
sys |
系统信息:cwd · platform |
✅ |
secret |
敏感环境变量 → Value::Secret |
✅ |
config |
配置 Artifact | 推迟 |
file |
外部文件内容 | 推迟 |
2.2 默认与必需
${env.OPENAI_MODEL ?? "gpt-4o-mini"}
${secret.OPENAI_API_KEY!}
A ?? B:A 缺失(未设置 / 空)则用 B。A!:A 必须存在,否则加载失败(config.required_binding_missing)。
2.3 类型转换
${int(env.MAX_TOKENS ?? "4096")}
${float(env.TEMPERATURE ?? "0.2")}
${bool(env.STREAM ?? "false")}
2.4 独占 value vs 插值
| 形态 | 语义 |
|---|---|
model: ${env.OPENAI_MODEL} |
Value binding — 保留解析后的类型(含 Secret) |
title: "Hello ${env.USER}" |
Interpolation — 结果为 Text |
model: gpt-4o-mini |
Literal — 字面量;不会被环境变量静默覆盖 |
3. Resolution Policy
对每个 metadata 键:
- 解析该键的字面量 / Binding / 插值(字面量定稿后不受 env 覆盖)。
- 若 CLI 提供了同名
--bind KEY=VALUE,覆盖该键的最终值(Text)。 - Binding 内部查找顺序(仅当表达式写出时):
arg/env/secret/sys按表达式 namespace;??链从左到右。
推荐作者意图:
CLI --bind
→ Artifact 字面量 / 已写死的 Binding 结果
→ Binding 源(env / secret / …)
→ ?? 默认
4. Secret
${secret.NAME} → Value::Secret。
print/str/ Display →<secret>(不泄露)。type→secret。- 与 Text 拼接(如
bearer + api_key)时揭示明文,供 HTTP Authorization。 - 不得进入普通 episode / 错误信息明文(扩展作者责任;核心 Display 已遮掩)。
5. Runtime API
| API | 语义 |
|---|---|
sys.meta / 系统.元信息 |
入口模块已绑定 metadata(map) |
sys.meta_get / 系统.取元信息 |
key= → 值或 None |
marqdo run FILE --bind KEY=VALUE |
可重复;写入 arg 并覆盖同名 metadata 键 |
sys.env_get |
保留逃逸口;新代码优先 Metadata Binding |
6. 错误
| code | 何时 |
|---|---|
config.required_binding_missing |
${ns.name!} 且源缺失 |
config.unknown_binding_ns |
未知 namespace |
config.bad_binding |
表达式非法 / cast 失败 |
诊断尽量带 frontmatter 行号。
7. 与扩展的分工
- 核心:解析 Metadata、resolve Binding、暴露
Module.metadata/sys.meta*,并在入口把 metadata 提升为普通变量。 ext/ai/llm:构造次序为 显式实参 → 入口作用域同名变量 /sys.meta_get→sys.env_get回退 → 默认。
8. Phase 2 · Metadata scope lift(Accepted)
加载期绑定完成后,入口执行(# main 或唯一无参顶层对象)前,把 Module.metadata 的每个键注入 entry 环境,成为普通变量:
---
model: ${env.ModelName ?? "gpt-4o-mini"}
---
# main
> print text=`model`
规则
- 注入时机:进入入口函数之前。
- 冲突:形参 / 调用实参 覆盖 同名 metadata;程序内赋值亦然。metadata 不覆盖已存在的绑定。
sys.meta/sys.meta_get仍可用(显式通道)。- 拒绝 正文 / 粗体 / 表 / 叙述中的
${…}(讨论稿 006 §17 否决)。普通语言也不在语句里${ENV}。
仍推迟(P3+)
config/filenamespace- 嵌套 YAML map
- 显式
override:糖 - 计入
CORE_CONSTRUCTS