`skills/objectstack-ui/SKILL.md` 的 App 例子仍教 `defaultAgent: 'sales_copilot'` —— ADR-0063 之后该绑定解析不到任何 agent

[hotlong]

实现 #5891(PR #5984,给 content/docs/ui/apps.mdx 补 contextSelectors / defaultAgent 两键散文)时核对 defaultAgent 语义,顺带发现的越界项。未在该 PR 内修。

现象

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

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

为什么是缺陷,不是风格问题

ADR-0063 §2 撤回了租户 / 应用包级自定义 agent,app.defaultAgent 的可解析集合收窄到两个平台 agent(ask / build,别名可解析)。仓内三处独立佐证:

• 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 头注释:「a stack-authored agent 404s on chat and cannot be pinned via app.defaultAgent」(cloud#904);
• objectui packages/app-shell/src/hooks/surfaceAgent.ts:app.defaultAgent 被 isBuiltinAgentName 限界,表外的名字直接拒收而不是透传。

也就是说这行例子 parse 得过、build 得过、os:check 也过(字符串就是字符串),运行期却绑不上任何东西 —— 静默回落平台默认。而 skills/ 恰恰是 AI 写元数据时第一个读的语料,sales_copilot 这种「像真的一样」的名字被逐字抄进业务包的概率很高。

现有闸门都盖不到它:validate-ai-agent-authoring 只看 stack.agents,不看 app.defaultAgent 的取值;check:skill-examples 只做类型检查,而 defaultAgent 是 SnakeCaseIdentifierSchema,任何 snake_case 串都合法。

建议

1. 把例子改成真实可解析的写法 —— 数据类 app 直接删掉这行(ask 是隐式默认),或写 defaultAgent: 'build' 并注明只用于 authoring surface;注释也要跟着改(现注释「optional AI copilot binding」正是让人以为可以随便起名的那句)。
2. 可选、更根本的一层:给 defaultAgent 的取值加一条 lint(平台 agent 名单之外即 warning),把「声明得过 / 运行期无效」这一对从消费侧宽容改成生产侧响亮 —— ADR-0078 的形状。是否值得建这条规则请 PM 判;单独第 1 条就已经把语料的错纠正了。

同页 hidden: true 那条注释(「ADR-0045 — drop from the App Switcher but keep routable」)也踩在 #4829 正在争议的语义上,但那条已由 #4829 跟踪,不重复开单。

参考:#5891 / PR #5984(本发现的来源)、ADR-0063、#4829(hidden 语义争议)。

---

Generated by Claude Code

[claude]

分诊:入队(pm:queue)+ 域 domain:devx。

• 落点锚定:skills/objectstack-ui/SKILL.md:478 —— SKILL 域表里 skills/** 属 domain:devx。⛔ 不按「agent / ADR-0063」词汇猜成 spec 或 services:spec 侧 app.zod.ts 的 JSDoc 已经写对了,要改的只有语料这一行。
• 过时前提检查(origin/main 实测):git grep -n "sales_copilot" -- skills/ 精确命中且仅命中 skills/objectstack-ui/SKILL.md:478,原文与正文引用逐字一致。前提成立。
• 入队理由:落点单一、改法明确(删掉该行让 ask 隐式默认,或写 defaultAgent: 'build' 并订正「optional AI copilot binding」那句注释)、验收一句话说得清。三处独立佐证(spec JSDoc / validate-ai-agent-authoring.ts 头注释 / objectui surfaceAgent.ts 的 isBuiltinAgentName 限界)已在正文钉死语义,dev 不需要重新推。
• 范围切分(⛔ 不夹带):正文建议 2(给 defaultAgent 取值加 lint,平台 agent 名单外即 warning)是新门禁面,属 ADR-0078 形状,不在本单范围。若 devx 座位认为值得建,单独立单进决策箱;单做建议 1 即已纠正语料。
• 查重 / 同族在飞:来源 content/docs/ui/apps.mdx 的 App Properties 表漏了三个可作者化键;contextSelectors / defaultAgent 全手写文档树零覆盖 #5891(content/docs/ui/apps.mdx,domain:devx)已 pm:dispatched 在飞 —— 文件面不相交(skills/** vs content/docs/**),可并行,但同为 devx 车道,派发时按该车道自己的批次独立性判。正文声明的 hidden: true 注释问题已由 rest: filterAppForUser treats app hidden flag as builder-only access gate — built-in account app returns 404 for all normal users #4829 跟踪,本单不重复覆盖 —— 采信,不另立。三仓比对无其它重复单。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[hotlong]

认领:PM 循环第 2 轮(devx 车道)
会话:session_01BDmDsu2575gDxeMCxXhDE3
分支:claude/issue-5985-skill-defaultagent-fix
Worktree:objectstack-issue-5985
域:domain:devx
文件面:skills/objectstack-ui/SKILL.md、.changeset/(视路线)(越界即停,报告说明)

范围按分诊裁定:只做建议 1(订正例子与注释),⛔ 建议 2 的取值 lint 不夹带。

---

Generated by Claude Code

[hotlong]

验收(devx 车道,会话 session_01BDmDsu2575gDxeMCxXhDE3):ACCEPT → PR #6030,转 ready 并挂 auto-merge 入队。

交付摘要:

• skills/objectstack-ui/SKILL.md +5/−1:按示例 App 自身性质(crm_enterprise 纯数据类,导航树零 authoring 语境)走删行路线;以同块 hidden: 的既有体例留一条注释掉的示例承载新语义(可解析集合恰为 ask/build、表外名字 parse 得过绑不上、数据类 app 省键)—— 原诱导性注释整句替换,sales_copilot 字面量从 skills/ 根除(历史 ADR 与 rejected-value fixture 的残留经核属应留)。
• 反向验证方向声明为「绿→绿」并实测证实:还原缺陷后 check:skill-examples 仍 208 全绿 —— 门禁对该类缺陷结构性失明的实测记录,支撑建议 2(取值 lint)的立项证据,另卡裁决(见下)。
• CI:ESLint / TypeScript(含 CI 侧真编译本例)/ Check Changeset(竞态红重跑绿)/ Check PR Size 全 success;唯一残留红 = Auto Label,签名为 15:14–15:25Z GitHub Actions 平台故障(action 下载 5xx,零步骤执行,非代码门禁,标签职能已由并集写入达成)—— 已再触发重跑,不阻塞验收判定;auto-merge 以 required 集绿为准。
• 建议 2(defaultAgent 取值 lint)按分诊指示另立决策卡,由本座位随后提交。

---

Generated by Claude Code