docs(skills): objectstack-ui 的 App 例子不再教 defaultAgent: 'sales_copilot' (#5985)

[hotlong]

Fixes #5985

问题

skills/objectstack-ui/SKILL.md 的 App 例子(带 os:check 标记)教:

defaultAgent: 'sales_copilot',          // optional AI copilot binding

ADR-0063 §2 撤回了租户 / 应用包级自定义 agent,app.defaultAgent 的可解析集合
收窄到两个平台 agent(ask / build,别名可解析)。这行 parse 得过、build 得过、
os:check 也过 —— 因为 defaultAgent 的类型就是 string,字符串就是字符串 ——
运行期却绑不上任何东西,静默回落平台默认。

skills/ 随 npx skills add objectstack-ai/objectstack/skills 原样发给第三方,
是 AI 写元数据时第一个读的语料;sales_copilot 这种「像真的一样」的名字被逐字
抄进业务包的概率很高。

前提已对 origin/main 复核成立,三处独立佐证均为仓内实测而非推断:

• packages/spec/src/ui/app.zod.ts 的 defaultAgent JSDoc:「the resolvable
  values are the two platform agents… a name that is not a platform agent will
  not resolve at chat time」;
• packages/lint/src/validate-ai-agent-authoring.ts 头注释:stack-authored
  agent 在 chat 上 404,且不能经 app.defaultAgent 钉住;
• objectui packages/app-shell/src/hooks/surfaceAgent.ts:82
  —— const bounded = isBuiltinAgentName(appDefaultAgent) ? appDefaultAgent : undefined;
  表外的名字是拒收(丢弃)而不是透传,注释写明「so a roster cannot be
  smuggled in via app metadata」。

选的路线:删掉该行(数据类 app)

按 PM 分诊给的两个合法方向,判断依据是该示例 App 本身的性质。例子里的
crm_enterprise / 'Enterprise CRM' 是标准的数据类 app —— leads、opportunities、
saved view、dashboard、report、approval requests,整棵导航树没有一处 authoring
语境。故按 ADR-0063 它本就该省掉这个 key:ask 是隐式默认。

这与 #5891 / PR #5984 刚落地的 content/docs/ui/apps.mdx 「Default Agent」一节
逐条对齐(同一发现的来源),该节写的就是:

• Omit it on a data app —— ask is the implicit default;
• Set 'build' on an authoring surface(Studio 是内置例子)。

改法上没有直接删空,而是照同块 hidden: 的既有写法留一条注释掉的示例 ——
因为 PM 分诊要求「注释『optional AI copilot binding』必须跟着改(说明可解析集合
只有 ask/build)」,而整行删空就没有落点承载这条语义了。同时这样保留了 key 在语料
里的可发现性:AI 仍知道 defaultAgent 存在,但读到的是收窄后的真语义。

  // defaultAgent: 'build',                // ADR-0063 §2 — the resolvable set is exactly two
                                           // platform agents: `ask` (data surface) / `build`
                                           // (authoring, e.g. Studio). Any other name parses
                                           // but binds nothing at chat time. A data app like
                                           // this one omits the key — `ask` is the default.

原注释「optional AI copilot binding」正是让人以为可以随便起名的那句,已整句替换。
三条事实写进注释:可解析集合恰好是两个平台 agent、表外名字 parse 得过但绑不上、
数据类 app 省掉此 key。

sales_copilot 这个字面量不再出现在 skills/ 任何位置
(git grep -n "sales_copilot" -- skills/ 空)。刻意没有把它作为反例写进注释:
文档正文里点名它是安全的(apps.mdx 就那么做),但 skill 的代码块里出现该字面量,
恰好是本单要消除的复制粘贴风险。

反向验证:方向是「绿 → 绿」,不是「绿 → 红」

先声明预期方向再跑的:本单不可能出现「还原缺陷 → 门禁转红」。defaultAgent
的类型是 string,'sales_copilot' 与 'build' 一样类型检查通过;缺陷是运行期
解析事实,不是类型事实。若还原后能转红,issue 正文「parse 得过、build 得过、
os:check 也过」这一核心论断就是假的,这个坏例子当初也就进不了仓。

实测确认了这个预期:把 defaultAgent: 'sales_copilot' 原样放回后重跑

✅ 208 prose examples type-check against @objectstack/spec
EXIT=0

门禁对这一类缺陷结构性失明 —— 这正是它当初得以发布的原因,也正是 issue 正文
建议 2(给取值加 lint)想补的那一层。按分诊裁定,建议 2 是新门禁面,不在本单
范围,未夹带。

Changeset:按 skills/** 先例走 skip-changeset

skills/ 是已发布内容但不经 changeset 发版。查同类先例,今日 skills/** 的 PR
一律 skip-changeset 标签、无 changeset:

• docs(skills): 九份已发布 skill 的 compatibility 声明由 16.x 更正为 17.x (#5245) #5937(0d1bc15,今日碰过本文件的那一笔,九份 SKILL.md 的 compatibility
  声明改 17.x)—— 实测其提交文件清单零个 .changeset/ 条目;
• docs(skills,docs): 三处 hook 文档不再教「批量写的行级谓词在 ctx.input.ast」(#5670) #5901(三处 hook 文档)、docs(skills): data-hooks 的 condition 一节按 before/after 拆开重述批量写绑定 (#5900) #5989(data-hooks 的 condition 一节)同样。

照抄该先例:本 PR 不提交 changeset,建 PR 后立即打 skip-changeset 标签。

自验(全部前台阻塞执行,build/test 持 flock /tmp/os-heavy-verify.lock)

基线 rebase 到当时的 origin/main(b5bdf48),本文件上游无并发改动。
先 pnpm --filter '@objectstack/spec^...' --filter @objectstack/spec build
(check:skill-examples 读的是构建出的 dist/*.d.ts),再逐条跑覆盖 skills/
的五道门禁:

门禁	结果
check:skill-examples	✅ 208 prose examples type-check against @objectstack/spec(含本例 skills/objectstack-ui/SKILL.md:472)
check:doc-authoring	✓ 362 files clean — no bare metadata literals(自检 + 全量)
check:skill-frame-sync	✓ 12 cases pass;4 copies structurally isomorphic
check:skill-docs	✅ Skill docs in sync(skills/README.md、content/docs/ai/skills-reference.mdx)
check:skill-refs	✅ 9 generated files in sync with packages/spec

字节纪律:node scripts/check-nul-bytes.mjs → OK(5778 tracked text files);
对本文件另做定向自扫 grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' → 无命中。

改动面严格等于申报文件面:skills/objectstack-ui/SKILL.md 一个文件,+5/-1。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3

---

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 6, 2026 3:13pm

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 31116189642 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Temporal Conformance (live PG + MySQL) — 失败步骤: Set up job（日志不可读，点进 job 看）

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 19 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 在其他 PR 的同类评论里搜同名测试；出现过 ⇒ flaky 实锤，开 issue 修/隔离那条测试。修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)