docs(releases): v17 升级指南补 objectui#3203 作者破坏性迁移,console 段区间更新到 785b8a5d432c

[os-zhuang]

Fixes #4733

这是 PR #4732 的 PM 裁定(选项 B,#4732 (comment) )的第二半:changeset 保留在 #4732(A 半,已合并),v17 升级指南走这个独立的 docs-only PR。

为什么走 docs-only PR

objectui#3203 从公共 ActionParam 移除九个 resolved-only picker 键,对作者破坏性。迁移处方已经进了 #4732 的 pin changeset —— 发布说明的法定输入层,该做的做了。但 RC 期间正在升级的作者读的是文档站:一条只活在 .changeset/ 里的破坏性迁移,对他们等于不存在。

CLAUDE.md 禁的是「代码 PR 顺手改 releases 页」,同时明文留了正门 —— 「dedicated docs-only PR, never a rider on code changes」。本 PR 就是那扇门,不是例外。

改了什么(零代码)

1. ## Breaking changes & migration 新增一条,插在 ADR-0104 D2 的 An action's declared params are enforced at dispatch (#3438) 之后 —— 同一主题相邻,读者一眼看到全貌。条目含:

• 九个键全名:referenceTo / displayField / idField / descriptionField / titleFormat / lookupColumns / lookupFilters / lookupPageSize / dependsOn
• 处方一(内联 picker 目标),按本页既有的 ```diff 版式:
  { name: 'account_id', type: 'lookup', referenceTo: 'account' } → `{ name: 'account_id', type: 'lookup', reference: 'account' }`
• 处方二(其余八个):改 field-backed({ field: 'account_id' }),整组从被引字段继承
• 理由(说明这不是能力回退):九个键从来就存不进去 —— ActionParamSchema 是 .strict(),authorable 键表只有 reference,别名表点名 referenceto → reference,服务端一直硬性 parse 拒绝,只是 tsc 放行。移除的是从未生效的编译期假象。

2. console 段标题区间更新:4a4829d0ef39 → 7d9734d5e321 改为 4a4829d0ef39 → 785b8a5d432c。#4732 已合并,origin/main 上 .objectui-sha 现为 785b8a5d432cf009389a1a9180fdac2a8297543f,旧区间已失真。

处方与 spec 逐条核对过

写错迁移处方比不写更糟,所以落笔前读了 packages/spec/src/ui/action.zod.ts 和 packages/spec/src/data/field.zod.ts:

• ACTION_PARAM_KEYS 确实只有 reference,九个键一个都不在(action.zod.ts:61-64)
• ACTION_PARAM_KEY_ALIASES 确实手写点名 referenceto: 'reference'(同文件 :78-82)
• schema 确实 .strict(),且 .refine() 在 parse 时就拒绝无 target 的内联 lookup
• displayField / descriptionField / lookupColumns / lookupFilters / lookupPageSize / dependsOn 确为 FieldSchema 键(field.zod.ts:534-570)—— 这六个 field-backed 参数真的继承得到

核对中发现 changeset 的「其余八个整组继承」有半格不精确,已在文档里补齐:idField 和 titleFormat 两侧都从来不可作者化 —— 记录标识由 picker 自解,候选标题取被引对象的 nameField(ADR-0079,object.titleFormat 本身已经退役)。所以文档写的是「六个从字段元数据继承 + 两个本来就不是作者的键」,而不是笼统的八个。

约束遵守情况

• 全 diff 仅 content/docs/releases/v17.mdx,38 增 1 删,零代码。
• 不发版、不 bump 任何包版本。docs-only 不需要 changeset —— 请给本 PR 打 skip-changeset 标签(仓里该标签的描述正是「PR has no user-facing published change; bypasses the changeset gate」)。走标签而不是空 frontmatter changeset,是为了守住「全 diff 只有一个文件」这条验收线;两者在 pr-automation.yml 的注释里被明确写成对等(「on par with the skip-changeset label」)。
• 冲突纪律:这个文件是全仓最热的冲突磁铁,所以只做了「一个新条目 + 一处区间替换」,不重排既有内容、不顺手修别的段落。
• 文风照该页既有 "Breaking changes & migration" 条目写(粗体导语 + 处方列表 + 理由段),没有发明新版式。

一处刻意没改的地方(留给维护者裁定)

console 段正文下一句仍是「143 objectui commits across five pin moves」。本 PR 只按 issue 要求换了标题里的区间,没动这个计数:该计数不是 git rev-list 的字面结果(本地 objectui 克隆里 4a4829d0ef39 甚至不是 7d9734d5e321 的祖先,区间数对不上),复不出原作者的口径,凭空改成「six pin moves / 某个新数字」风险比留着更大。如果维护者认为该跟着更新,我按指定口径另开一单改 —— 不在本 PR 里猜。

验证

• node scripts/check-doc-authoring.mjs → ✓ doc authoring guard: 216 files clean
• 代码围栏配平检查通过(20 个 fence 标记行,偶数);无重复 h3 标题;新增内容只用行内代码承载泛型,与本页既有的 Record< string, string > 同款(MDX 行内代码不解析 JSX),不引入新的解析风险
• 文档站构建依赖 CI(docs-only,未在本地跑整仓构建)

---

🤖 Generated with Claude Code

https://claude.ai/code/session_015Br2xsJsczFsTR9bvbh2Ny

---

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 3, 2026 1:25am