docs(ui): 给 apps.mdx 补 contextSelectors / defaultAgent 两个作者面键 (#5891) - #5984
Merged
Conversation
`content/docs/ui/apps.mdx` 的 App Properties 表读起来像 App 作者面的全集,
但 `APP_KEYS` 里的 `contextSelectors` 与 `defaultAgent` 两键既不在表里,
也在整个手写文档树零覆盖(此前只存在于生成的 content/docs/references/)。
对作者而言这不是"少写一行",而是把键变成不可发现。
- App Properties 表补两行,各自链到自己的小节;
- 新增 `## Context Selectors`:模板变量注入语义(值以 `id` 命名注入,
与 `{current_user_id}` 同一套替换)、`optionsSource` 子表、
"强制作用域、无 All 行、首项自动选中"、以及 17.0.0 退休的
`includeAll` / `placement` 两键;例子取平台自身 Studio 的 package scope,
带 `os:check` 标记,由 check:skill-examples 对着真实 spec 编译;
- 新增 `## Default Agent`:可解析值只有 `ask` / `build` 两个平台 agent
(ADR-0063 撤回租户自定义 agent,表外的名字解析不到,回落平台默认)。
`hidden` 按分诊裁定不在本单范围(语义正由 #4829 争议中)。
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
hotlong
added
the
skip-changeset
Claude
github-actions
Bot
added
documentation
hotlong
added
the
skip-changeset
Claude
hotlong
marked this pull request as ready for review
August 6, 2026 14:07
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.
Fixes #5891
为什么
content/docs/ui/apps.mdx的 App Properties 表是作者写 app 的唯一手写入口,读起来像作者面的全集;而packages/spec/src/ui/app.zod.ts的APP_KEYS里的contextSelectors与defaultAgent既不在这张表里,也在整个手写文档树零覆盖(此前只存在于生成的content/docs/references/ui/app.mdx)。对作者来说这不是「少写一行」,而是把两个键变成不可发现 —— 与 #4880 / PR #5890 处理的areas[]完全同一形状的缺口。改了什么
只动
content/docs/ui/apps.mdx一个文件,体例照 PR #5890(## Areas)的先例:表格行 + 需要展开的键单独小节。contextSelectors(排在areas之后)、defaultAgent(排在requiredPermissions之后)。## Context Selectorsid命名发布,按模板变量注入导航项 —— 与current_user_id/current_org_id同一套替换。recordId与filters各值、page/component项的字符串params值;解析不到的变量整条从 URL 里丢掉,而不是留空。optionsSource子表(endpoint/valueKey默认id/labelKey默认name/filter),以及filter谓词的eq(默认)neinnin。allValue是「尚未具体选中」的哨兵值而不是 All 选项。includeAll/placement,连同各自的处方 —— 与页面既有的 app 级 / area 级退休 callout 同体例。packages/platform-objects/src/apps/studio.app.ts的真实形状),带{/* os:check */}标记。## Default Agent:可解析值只有ask/build两个平台 agent —— 数据类 app 省略即得ask,授权类(authoring)surface 写'build';ADR-0063 撤回了租户/包级自定义 agent,所以表外的名字(如sales_copilot)parse 得过但绑不上,解析时回落平台默认。附一条 callout 说明它绑的 in-product chat runtime 属 ObjectOS,开源版没有可绑的 chat surface。事实来源(每条断言都在 origin/main 上核过)
packages/spec/src/ui/app.zod.tsAppContextSelectorSchema(idlabeloptionsSource必填;allValue默认''、persist默认'query';valueKey/labelKey默认id/name)AppContextSelectorSchema的 JSDoc +AppSchema.contextSelectors的.describepackages/layout/src/NavigationRenderer.tsx的applyNavTemplate与resolveHref(objectrecordId、objectfilters、pageparams、componentparams)packages/app-shell/src/layout/ContextSelectors.tsx(useAppContextSelectors/SelectorControl),挂载点见AppSidebar.tsx/UnifiedSidebar.tsxincludeAll/placement退休处方app.zod.ts的CONTEXT_SELECTOR_RETIRED_KEY_GUIDANCEpackages/platform-objects/src/apps/studio.app.tsdefaultAgent绑定语义与可解析集合app.zod.tsdefaultAgent的 JSDoc/.describe(ADR-0063 §1/§2);解析链见 cloudpackages/service-ai/src/agent-runtime.tsresolveDefaultAgent(app.defaultAgent →ask→ 首个 active);「表外名字回落平台默认」另有 cloud 用例agent-load-platform-gate.test.ts直接盯住content/docs/ai/agents.mdx既有 callout新增的「One scope per app today」callout 同样是核过的实现事实,不是推测:
ContextSelectors.tsx把选中值反射到 URL 上一个固定 query key,而每个声明的 selector 都从同一个 key 读回(contextValues[sel.id] = (params.get('package') ?? saved) || …),所以第二个 selector 会镜像第一个而不是独立作用域。写进文档是为了不让作者照着数组类型声明出一份静默失效的元数据;objectui 侧的实现缺陷另行归档,不在本 PR 修。自验
node scripts/check-doc-authoring.mjs --self-test && node scripts/check-doc-authoring.mjs→✓ doc authoring guard: 362 files cleanpnpm --filter @objectstack/spec run check:skill-examples→✅ 208 prose examples type-check against @objectstack/spec;抽取清单里本页从 3 块变 4 块(新增content/docs/ui/apps.mdx:512),即新例子确实被对着真实 spec 的 d.ts 编译过placement: 'topbar',门禁如期转红,并且报错把 selector 的合法键集原样列了出来 ——error TS2353: … 'placement' does not exist in type '{ id: string; label: string; optionsSource: {…}; icon?…; allValue?…; persist?… }',反过来证实了本 PR 表格里的键集与「退休键在 parse 期被拒」的说法;移除探针后复跑回绿node scripts/docs-audit/check-audit-scope.mjs→✓ docs-accuracy-audit scope is in sync with content/docs/: 178 hand-written doc(s)@mdx-js/mdx@3.1.1的compile()单独编译本页通过(并用一份故意写坏的 MDX 验证过该 harness 不是空跑)node scripts/check-nul-bytes.mjs通过;另按控制字节纪律对本文件跑了grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]',零命中Changeset
不带 changeset,按 PM 裁定走
skip-changeset标签路线:本 PR 只改手写文档页,不发布任何包(空 changeset 会滞留发布,#4898,所以不提交空文件)。标签已在 PR 建好后由本 agent 补上(读回既有标签后写并集,避免覆盖 bot 刚打的size/*等)。范围
严格按分诊裁定只做
contextSelectors/defaultAgent两键。⛔hidden没有写 —— 其语义正由 #4829 争议中(filterAppForUser当 builder-only 访问闸门 vs spec.describe的「只从 App Switcher 隐藏」),先定语义再写散文。⛔ 未碰packages/spec/**、未碰content/docs/releases/。🤖 Generated with Claude Code
https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3
Generated by Claude Code