docs(protocol/kernel): config-resolution 的 email 示例改用真实存在的键与取值 (#5105)

[os-zhuang]

Fixes #5105

纯文档单,只改一个文件面:content/docs/protocol/kernel/config-resolution.mdx(外加一份 changeset)。未碰 content/docs/releases/,未碰 packages/spec。

问题

「Example 3: Development Overrides」的示例有三处不对应任何真实配置面。对照 packages/spec/src/system/email-config.zod.ts(origin/main 实读):

示例里写的	真实情况
provider: 'sendgrid'	EmailProviderSchema = z.enum(['log','resend','postmark']),无 sendgrid
fromAddress: 'noreply@company.com'	键叫 defaultFrom,且是 { name?, address } 对象(EmailAddressConfigSchema),不是字符串
开发覆盖 provider: 'console'	无 console
OS_EMAIL_PROVIDER=mailhog	无 mailhog

后果是错误全部推迟到运行时:fromAddress 被静默丢弃,未知 provider 要到 makeTransport 才抛 unknown provider。属 Prime Directive #10 的「advertise a capability the runtime doesn't deliver」。

值得说明的是这一页的 warn callout 救不了它:那条 callout 只把 database / http / secrets.provider 列为意图示意,email 不在豁免名单里,而且它是真实配置面 —— packages/cli/src/commands/serve.ts 的 cap === 'email' 分支实打实读 config.email.{provider,apiKey,defaultFrom,retries} 并按 OS_EMAIL_* 覆盖。所以这段示例不该靠「示意」免责,它应当是真的。

改法

保留原来的载体(email)与原来的层叠要点,只把取值换成今天在 main 上就成立的:

• 生产段:provider: 'resend' + defaultFrom: { name, address },并补上 apiKey —— 非 log 的 provider 缺 key 时 serve.ts 会打 warning 并回落到 LogTransport,示例不写它等于示范一份「看着配好了、其实没发出去」的配置,是同一个缺陷换个方向再犯。
• 开发覆盖:provider: 'log'。
• env 覆盖:OS_EMAIL_PROVIDER=log。

刻意没有写 smtp。 EmailProviderSchema 目前仍是三值枚举,把 smtp 加进去是 #5104 的工作、尚未落地;此刻写它就是把本单刚修掉的 declared ≠ implemented 重新引入一遍。

一处超出「逐字替换」的改动,理由

原文 env 层只有一行。若单纯把 mailhog 改成 log,而开发配置段已经选了 log,这一层就退化成一条无效果的示例,「Developer can further override」讲不通 —— 取值修对了,机制却讲丢了,而 PM 分诊明确要求保住层叠要点。

故按本页 §Merge Strategies 自己教的「对象深合并、原始值替换」把语义补全:开发文件只替换了 provider,apiKey / defaultFrom 仍从生产配置继承,于是再加一行 OS_EMAIL_FROM 覆盖 defaultFrom。该变量是真实的(content/docs/deployment/environment-variables.mdx 有登记),serve.ts 也确实解析 addr 与 Name < addr > 两种写法。结果是「生产 → 开发 → env」三层优先级比改之前更完整。

未加 os:check

该代码块把 shell 赋值行混在 typescript 围栏里,是伪代码片段、本就不可编译;加 {/* os:check */} 只会让 check:skill-examples 变红。这也是它当年能悄悄烂掉的原因,但让它可编译需要重写整块(加 imports / defineStack 包装),超出本单范围。

验证

纯文档改动,按 PM 指示跑该页相关的 docs 门禁,未跑全仓构建/测试:

$ node scripts/check-doc-authoring.mjs --self-test
✓ check-doc-authoring self-test: scope wiring (...) all hold.
$ node scripts/check-doc-authoring.mjs
✓ doc authoring guard: 362 files clean — no bare metadata literals.

$ node scripts/docs-audit/check-audit-scope.mjs
✓ docs-accuracy-audit scope is in sync with content/docs/: 178 hand-written doc(s).
✓ release-owned pages are in scope and read-only: 9 page(s) under content/docs/releases/ review-only.

changeset:按 #5023(同类纯文档纠正)的先例给了一份空 frontmatter 的 changeset —— 不 bump 任何包,只进 release notes 编译。

🤖 Generated with Claude Code

https://claude.ai/code/session_017MCKJaEomEqg4tvz4SzdNd

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 4, 2026 5:06am