console preview-samples: 除 tool 外还有 11 个样例过不了对应的 spec schema(其中 4 个同样带已退役的键)

[xuyushun441-sys]

在做 objectui#3257(清 tool 样例的三个已退役键)时,按派发要求逐个核对了 apps/console/src/preview-samples.ts 里全部 20 个样例。结论:tool 远不是唯一一个,11 个样例当前过不了 spec 的 .parse(),其中 4 个带的是和 #3257 完全同型的已退役键。

#3257 已落地一条机器守卫(apps/console/src/__tests__/preview-samples-spec-valid.test.ts),把每个样例塞进整个 stack 交给 ObjectStackSchema.safeParse() 校验。本单列的 11 个当时没有一并修,而是进了该测试里的 KNOWN_STALE 台账 —— 台账带反向断言(某个样例一旦开始通过就报红,要求把它提升到 SPEC_CLEAN),所以这个列表只会缩短,不会烂掉。本单就是把它清空。

核对结论(spec 17.0.0-rc.1,本仓 lockfile 里装着的版本)

校验方式:ObjectStackSchema.safeParse({ tools: [SAMPLES.tool] }) 之类,即「作者把这份样例发布进真实 stack 会怎样」。

✅ 合法(6,已被守卫钉住)

view、job、tool(#3257 修完后)、permission、position、email_template

❌ 过不了(11,本单范围)

样例	问题	是否含已退役键
action	bulkEnabled 已退役;type: 'server' / variant: 'default' / locations: ['record','list'] 都不在 17 的枚举里	✅ objectstack#3896
agent	tools 已退役(改用 skills)、knowledge 已退役	✅ objectstack#3894 / #3896
skill	triggerPhrases 已退役;triggerConditions 需要 field/operator/value	✅ objectstack#3896
flow	waitEventConfig.onTimeout 已退役;type: 'scheduled' 不在枚举;variables[].description 不认;13 条 edge 都缺 id	✅ objectstack#4158
object	fields 是数组,ObjectSchema 要 record(见下方注意)	—
page	region 里的 component 带 props,PageComponentSchema 拒收(ADR-0089 D3a)	—
report	columns 是对象数组,ReportSchema 要列名字符串	—
dashboard	widget 缺 dataset/values,带不认的 value/format;chart 不是合法 widget type	—
app	navigation 各项缺 type 判别键;landing 已被 objectstack#4001 移除	—
datasource	type/isDefault 拒收;ssl 要对象不要布尔;capabilities 要对象;healthCheck.interval → intervalMs	—
validation	events 用的是 17 之前的 beforeInsert/beforeUpdate,枚举现在是 insert/update	—

⚪ spec 里没有对应 schema(2,守卫豁免)

workflow(没有 workflows 集合,也没有 WorkflowSchema)、approval(只有 ApprovalNodeConfigSchema,那是 flow 节点配置,不是审批流程元数据)

⚠️ 映射本身存疑(1)

translation:ObjectStackSchema.translations 是 Array< Record< locale, TranslationData > >,而 console 这份样例是 { name, label, locale, language, description, data } 的元数据记录形态。也就是说这里更可能是映射选错了,而不是样例过期。修之前需要先定这个样例到底对应哪个契约。

为什么没在 #3257 里一起修

不是懒 —— 其中几项不是机械替换,动之前需要判断:

1. object.fields 的数组形态是被 app-shell 有意支持的,不是笔误。packages/app-shell/src/views/metadata-admin/previews/object-fields-io.ts 的 readFields() 显式分支 shape: 'array' | 'record' 并原样保留。把样例改成 record 会让画廊不再覆盖 array 那条分支。真正的问题其实更深:设计器编辑的是一个 spec 会拒收的形态(AGENTS.md #0.1 的典型场景),该先裁决 readFields 的双形态要不要留,而不是先改样例。
2. 改 dashboard / app / flow 样例会改变画廊渲染出来的东西,而预览画廊是本仓共用的浏览器验证台(verify skill),并行 agent 正拿它验证别的改动。
3. console preview-samples 的 tool 样例仍带三个已退役的 ToolSchema 键(category / active / requiresConfirmation) #3257 的 scope fence 是「tool 样例 + 审计 + 守卫」,PD#3 要求越界发现另立单。

建议做法

• 4 个带退役键的(action/agent/skill/flow)可以先删键,和 console preview-samples 的 tool 样例仍带三个已退役的 ToolSchema 键(category / active / requiresConfirmation) #3257 同一性质、同一裁决依据,风险最低;agent 只有这两个问题,删完即可提升进 SPEC_CLEAN。
• report / validation / datasource / app 基本是机械改写。
• object / page / dashboard / translation 建议单独裁决后再动。
• 每修好一个,把它从测试里的 KNOWN_STALE 移进 SPEC_CLEAN —— 反向断言会强制你这么做(样例一开始通过,那条「仍然如实失败」的用例就会报红)。

附带观察(spec 侧,不在本仓)

守卫的强度取决于 spec 的严格度:tools/apps/flows/permissions/positions/datasources 的元素 schema 是 .strict(),而 views/jobs/emailTemplates 不是 —— 后者会把未知键悄悄剥掉而不是报错。也就是说这三类样例即便哪天混进一个已退役的键,守卫也照样绿。这是 spec 仓的事(objectstack#4001 / #3896 同一条线),记在这里备查。

相关

• objectui#3257(本单的来源;tool 样例 + 守卫)
• objectui#3236 / PR fix(app-shell): ToolPreview 不再渲染已退役的 ToolSchema 标记徽标 (#3236) #3258(ToolPreview 不再渲染这三个徽标)
• objectstack#3896、objectstack#3894、objectstack#3715 / ADR-0033 §2、objectstack#4158、objectstack#4001(各键的退役裁决)

[xuyushun441-sys]

认领:PM 循环第 4 轮
会话:session_01NVPjPzmmAJ2Ngtvgg5MSRa(objectui 分片 PM,账号 xuyushun441-sys)
分支:claude/issue-3266-preview-samples-spec-conformance
Worktree:objectui-issue-3266

前置已解除

#3257 的守卫(preview-samples-spec-valid.test.ts 含 KNOWN_STALE 台账 + 反向断言)已随 PR #3269 落在 main(e0f23caf7),本单可以开工。

派发范围:清 7 个,留 4 个

本单自己已经把难易分好了,我按它的分组划线:

要修(7)

• 4 个带退役键:action(bulkEnabled)、agent(tools/knowledge)、skill(triggerPhrases)、flow(waitEventConfig.onTimeout)。与 console preview-samples 的 tool 样例仍带三个已退役的 ToolSchema 键(category / active / requiresConfirmation) #3257 同性质、同裁决依据(objectstack#3896 / fix(plugin-detail): 相关列表的 Add 门改问 add.picker.object,漏写 picker 不再把整块换成红卡 (#3838) #3894 / [gantt] Illegal dependency link (cycle/self/locked/group) is silently discarded — no toast, no cursor, no reason shown #4158),风险最低,优先做。
• 3 个机械改写:report(列名字符串)、validation(insert/update 枚举)、datasource(ssl/capabilities 对象化、intervalMs)。

app 你自己判断:若能确信地按 17 的 navigation 判别键改写(并处理 objectstack#4001 移除的 landing),就一并做;不确信就留在台账里并写明理由。

不要动(4),留在 KNOWN_STALE 并保留理由
object、page、dashboard、translation —— 本单正文已论证它们各自需要先裁决:

• object.fields 数组形态是 app-shell 的 object-fields-io.ts readFields() 有意支持的分支,改样例会让画廊不再覆盖 array 那条路;真正要裁的是设计器该不该继续编辑一个 ObjectSchema 拒收的形态(AGENTS.md #0.1),那是 app-shell 那头的事;
• translation 更可能是映射选错而不是样例过期,先定契约再动;
• page / dashboard 牵涉画廊渲染结果。

三条硬要求

1. 每修好一个,必须从 KNOWN_STALE 移进 SPEC_CLEAN。 反向断言会强制你这么做 —— 样例一旦开始通过,那条「仍然如实失败」的用例就报红。收工时台账应当只剩你没修的那几个,且每条都带理由。
2. 改的是样例内容,不是守卫的判定标准。 ⛔ 不许为了让样例通过而放宽守卫、给 schema 加豁免、或把某项挪进 NO_AUTHORING_SCHEMA。若你认为某个样例其实无法在不损失展示价值的前提下修正,留在台账里说明,不要改判定。
3. 预览画廊是本仓共用的浏览器验证台(verify skill,并行 agent 在用)。凡是会改变画廊渲染结果的样例,在 PR 正文里逐条列出「改前 → 改后」的可见变化,别让别人第二天发现验证台变了却不知为何。

⚠️ scope fence:apps/console。本轮同批占用 packages/components(#3263)与 .github/workflows(#3261)。

---

Generated by Claude Code

[xuyushun441-sys]

PM 验收:ACCEPT — PR #3277,已入合并队列

项	结果
PR targets main、Fixes objectstack-ai/objectui#3266	✅
范围内 8 个样例	✅ 全修,全部从 KNOWN_STALE 提升进 SPEC_CLEAN
台账剩余	✅ 只剩我裁定不动的 4 个,且理由被**重写成"为什么需要裁决"**而不是"还没轮到"
守卫判定标准	✅ 零放宽 —— 没有豁免、没有挪进 NO_AUTHORING_SCHEMA
CI	12 项完成、零失败;3 个 test shard 在跑,已开 auto-merge

守卫不但没被放宽,还被收紧了

我把「只许修样例、不许改判定标准」列为本单最重要的约束。它不仅遵守了,还反向加强:退役键的钉扎从「tool 的 3 个键」扩成一张 9 行 RETIRED_KEYS 表、按任意深度匹配 —— 因为 waitEventConfig.onTimeout 是嵌在 flow 节点里的,浅层匹配抓不到。

两处它的实测推翻了本单正文的描述

这两条比修好样例本身更有价值,因为照着 issue 写的描述做会做错:

1. report 不是"把列改成字符串"就能修的。 ADR-0021 要求绑定的 dataset + values;而且它原来的 pre-9.0 object / groupBy 是被非严格 schema 静默剥掉之后才在别处失败的 —— 也就是说本单正文里那条"columns 要列名字符串"只说中了表层。
2. action 的 type: 'script' 还需要 target —— ActionSchema 拒收既无 body 又无 target 的脚本动作。

浏览器验证是真跑了的

我要求"凡改变画廊渲染结果的样例,逐条列改前 → 改后"。它没有靠推断:起了自己的 vite(:5233,没碰 :3000/:5180),用 ?only=<type> 逐个隔离设计器,带着修复截一次、把 preview-samples.ts stash 掉再截一次,PR 正文里的每一行 before→after 都是实测文本/截图。收尾也干净(按记录的 PID 停服,父进程被 kill 后 node 子进程仍在,单独按 PID 27651 杀掉并用 kill -0 确认;worktree 移除并 prune)。

⚠️ 由此挖出的两条,都已入队

#3275(bug + pm:queue)—— 这是"画廊改后反而显示更少"的根因。 AgentPreview / SkillPreview / AppPreview / DatasourcePreview 仍在读 spec 已拒收的键(tools、knowledge、triggerPhrases、landing、逐项的 path/object/dashboard,以及只当数组处理的 capabilities)。样例改对之后,这些预览就没东西可读了 —— 也就是说预览组件和样例此前是"一起错"才看起来正常的。这与 #3236 / PR #3258 在 ToolPreview 上修的是同一类缺陷,只是这次是四个组件。它在 packages/app-shell,在本单围栏外,没有顺手做,对。

#3276(bug + pm:queue)—— 守卫抓不到的一类错。 validation 样例的 condition: 'amount > 0' 语义是反的:ScriptValidationSchema 的契约是「condition 为 TRUE 时校验失败」,所以这条规则写成了"拒绝所有金额大于 0 的订单"。

这条特别值得记:spec 守卫只问"这份草稿能不能 parse",不问"它说的是不是作者想说的"。#3257 建的守卫再严也抓不到它。一个能 parse 但语义反了的范本,危害不比一个 parse 失败的小 —— 照抄的人得到的是一条会拒绝正常数据的校验规则。

它只按派发范围改了 events,没有顺手改 condition,并把这条连同另外几个被非严格 schema 静默剥掉的键(expression、object、skill.type)一并记进了 #3276。

changeset:不加,判断正确

复核了 apps/console/vite.config.ts 确实没有 rollupOptions.input,默认入口只有 index.html,preview-gallery.html → preview-samples.ts 不是生产构建输入 —— 与 #3269 当时的结论一致,而且它是重新验证而不是照抄。

---

Generated by Claude Code