feat(spec,automation): graduate the seven flow-node config aliases into the protocol-17 conversion layer (#3796) - #3976
Merged
Conversation
…to the protocol-17 conversion layer (#3796) FlowNodeSchema.config is an unconstrained record, so the executors were the only statement of which config key is canonical — and seven deprecated aliases lived there: object→objectName behind the readAliasedConfig shim, plus six open-coded ?? fallbacks (notify to/subject/body/url, script functionName/input) with no warning, no ledger, and no retirement path. All seven graduate into the ADR-0087 D2 conversion layer as protocol-17 live-window entries (flow-node-crud-object-alias, flow-node-notify-config-aliases, flow-node-script-config-aliases): a stored flow authored with an alias is rewritten to the canonical key at load — normalizeStackInput and the AutomationEngine.registerFlow rehydration seam alike — with a structured ConversionNotice per rewrite. The executors read canonical keys only, and the emptied readAliasedConfig shim is deleted. actionUrl (not url) is the deliberate canonical of its pair, resolving the contradiction where the notify descriptor documented url as canonical while the executor precedence, tests, and examples all preferred actionUrl: the whole downstream chain already uses that name (sys_notification.action_url, the channel contract, the REST read model), and url elsewhere means an HTTP endpoint to call. The choice is behaviour-preserving. Also: step-17 migration chain + regenerated spec-changes.json / protocol-upgrade-guide.md carry the new entries; PD #12 records the endgame; common-patterns.mdx now authors canonical keys; lint comments updated to reference the conversions instead of the deleted shim. Refs #3796, #3713, #3742, #3754, #3795, ADR-0087. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFnoExtwnGhNDWXNvn7RKN
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 3 package(s): 107 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
…uations (#3796) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFnoExtwnGhNDWXNvn7RKN
os-zhuang
marked this pull request as ready for review
July 30, 2026 01:09
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
关闭 #3796。
做了什么
FlowNodeSchema.config是无约束 record，"哪个键是规范键"过去只存在于执行器的读取代码里——七个废弃别名以两种形态藏在那里：object→objectName在readAliasedConfigshim 后面（有警告、有台账），另外六个是裸??兜底（无警告、无台账、无退役路径）。按 issue 讨论的结论（当前正处 protocol 17 大版本关口，跳过 shim 过渡阶段），七个别名全部直接毕业进 ADR-0087 D2 转换层，作为 protocol-17 live-window 条目：
flow-node-crud-object-aliasget_record/create_record/update_record/delete_recordobject→objectNameflow-node-notify-config-aliasesnotifyto→recipients、subject→title、body→message、url→actionUrlflow-node-script-config-aliasesscriptfunctionName→function、input→inputs存量流程在加载时（
normalizeStackInput与AutomationEngine.registerFlow再水化缝）被改写为规范键并发出结构化ConversionNotice，零消费者动作；window 于 protocol 18 退役。执行器只读规范键，清空后的config-aliases.tsshim 随之删除。actionUrl规范键决定url/actionUrl这对存在真实矛盾：notify descriptor 的configSchema文档写url是规范键，而执行器优先级、测试、示例全部偏向actionUrl。本 PR 定actionUrl为规范：下游全链路已用此名（sys_notification.action_url、渠道分发契约、REST 读模型），且url在平台词汇里已有"要调用的 HTTP 端点"（http节点、webhook）的既定含义。执行器原本就是actionUrl优先，选它是零行为变化；descriptor 已修正。连带变更
step17.conversionIds登记三个条目 + rationale 扩写；spec-changes.json/docs/protocol-upgrade-guide.md重新生成（drift 检查通过）crud-config-aliases.test.ts改写为转换缝回归测试；notify/screen 的别名测试改为断言加载层转换packages/lint两处注释更新为指向转换条目（行为保留：window 期内 lint 可能跑在未转换的原始源上，继续两个键都认是正确的）common-patterns.mdx两处示例改用规范键（作者侧只发规范键）语义保持验证
renameConfigKey在 canonical 已有值时不改写（canonical wins），与被替换的cfg.canonical ?? cfg.alias逐位一致；CRUD fixture 显式覆盖双键并存场景map/subflow/connector_action的input（各自的规范键）不受影响——转换按node.type限定作用域registerFlow直接把 config 递给执行器的调用方不再有别名解析（changeset 已注明）测试
pnpm test：132/132 任务通过check:spec-changes/check:upgrade-guide通过Refs #3713 #3742 #3754 #3795, ADR-0087.
🤖 Generated with Claude Code
https://claude.ai/code/session_01MFnoExtwnGhNDWXNvn7RKN
Generated by Claude Code