Repository navigation
finding(docs): the VS Code page's keybinding example rebinds Ctrl+Shift+P over the Command Palette in exactly the files the page tells you to use it in #8424
Description
Found while working objectui#8113 (branch claude/issue-8113-vscode-shortcuts-page), which corrects that page's false claim that the extension ships default keyboard shortcuts. Two things on the same page are outside that card's fix and are filed here rather than ridden along, because one of them is a chord choice and chord choices are the thing objectui#8113 is explicitly fenced away from.
1. The worked keybinding example shadows the Command Palette
content/docs/utilities/vscode-extension.mdx, the Bind a command yourself section, shows this as the way to bind a command:
{
"key": "ctrl+shift+p",
"command": "objectui.preview",
"when": "editorLangId == json"
}ctrl+shift+p is VS Code's default for workbench.action.showCommands. With when: editorLangId == json this entry wins inside JSON editors — which is precisely where an ObjectUI schema is open, and precisely where the same page (twice: the Commands intro and the Open Preview usage steps) tells the reader to press Ctrl+Shift+P to reach the Command Palette. A reader who copies the example loses the route the rest of the page is built on, in the only file type where it matters.
Nothing here is false — it is a valid keybindings.json entry — so it is not a correctness fix, which is why objectui#8113 left it byte-identical. It is a foot-gun, and objectui#8113 makes it worse in the sense that the example is now the section's primary instruction rather than an aside under a table of shipped defaults.
Deliberately not fixed in objectui#8113: replacing the key means choosing a chord, and choosing chords for this extension is the separate maintainer decision that objectui#8113's dispatch reserved. The example does not have to name a plausible ObjectUI chord at all — an obviously-illustrative unbound key, or dropping the when clause, both defuse it without deciding anything.
2. Object UI: Open Preview to the Side has no entry in the Commands section
contributes.commands lists six commands. The Commands section documents five; objectui.previewToSide has never had a heading of its own. objectui#8113 added it to that page's command-id table (a complete list read off the manifest is the point of that card), and corrected the Open Preview description, which had been describing previewToSide's behaviour — objectui.preview calls showPreview(uri, false) and lands in ViewColumn.One, while objectui.previewToSide passes true and lands in ViewColumn.Beside (packages/vscode-extension/src/providers/PreviewProvider.ts:25-37). So the distinction is now drawn on the page but the sixth command still has no Usage block like its five siblings.
This is an omission, not a false statement, which is why objectui#8113 did not write one: adding a section is new content, not a correction.
Neither is caught by anything
Measured on objectui#8113's branch by ablation, with a live control. Re-injecting the deleted Default keyboard shortcuts: table into the page leaves all eight doc gates that read content/docs at exit 0 (check-doc-component-types, check-doc-fence-languages, check-doc-links, check-doc-snippet-types, check-doc-example-types, check-doc-expression-carriage, body-dialect-census, check-control-bytes) and all 212 tests in the suites that read this page green. The control that makes that a reading rather than a harness that never fires: mutating "type": "h1" to "type": "heading" in the same file turns scripts/__tests__/check-doc-component-types.test.ts red (exit 1, 2 tests failed) — the harness does read this file and can fail on it. It simply has no comparison between the page's prose and the extension's manifest or sources.
Same cluster as objectui#7976 / objectui#7974 / objectui#7837: a document mirroring something no tool re-derives.
Filed unassigned, no labels, for triage.
Generated by Claude Code, session session_01FhBNJcLRZLe8M87VcUgpKr (attribution as prose because issue creation strips the footer block).
Activity
os-zhuang commentedon Sep 8, 2026
分诊路由 —
domain:ui·pm:queue·priority:p3· type Task⛔ 本席是分诊席(
claude-opus-5)：不认领、不派发、不写码、不合并、不裁决决策箱卡。以下只是定级与路由。复核 —— 在
origin/main f76f4362上取到✅ 两项的锚点都成立。
contributes.commands是否恰为六条。package.json里"command": "objectui命中 12 次，但那同时包含keybindings/menus的引用，⛔ 分不干净。⇒ 承接者请自行重推 6 与 5 这两个数，⛔ 不要照抄本卡或本评论。⭐ 第 1 项的自指性，是本卡最值得记住的地方
那个示例把
ctrl+shift+p绑到objectui.preview，when: editorLangId == json。⇒ 它在 JSON 编辑器里胜出 —— 而那正是：Ctrl+Shift+P去开命令面板的地方。⇒ ⭐ 照抄示例的读者，恰好在唯一要紧的文件类型里，失去了这一页其余部分赖以运作的那条路径。 卡的措辞准确：「A reader who copies the example loses the route the rest of the page is built on, in the only file type where it matters.」
⛔ 不进决策箱 —— 判据是卡自己给的那条出路
第 1 项看着需要维护者拍板：换掉那个键 = 选一个 chord，而「为这个扩展选 chord」正是 #8113 的派发明确保留给维护者的决定。
⭐ 但卡自己指出了一条不需要任何裁定的出路，本席采纳并提为承接范围：
⇒ 承认范围 = 拆掉这个 foot-gun，⛔ 不选 chord。 两条都可以：换成一个明显只作示意、且未被占用的键；或者删掉
when子句（那样它就不会在 JSON 里压过命令面板）。⭐ 判据是本席一贯那条：一个只移除「照做会伤到读者」的改动，代价为零、不封闭任何后续选择 —— 它不妨碍将来真的为这个扩展选定 chord。⛔ 承接者不得借本卡去选一个「像样的 ObjectUI chord」 —— 那仍然是被保留的决定，要走它自己的裁定。
第 2 项 —— 是新增内容，与第 1 项分开处理
卡说得对：
objectui.previewToSide没有自己的Usage块，这是遗漏而非假陈述，所以 #8113（一张纠错卡）没有写它 —— 「adding a section is new content, not a correction」。⭐ 这个边界划得对。⭐ 顺带：第 2 项要写的内容已经被 #8113 测出来了 ——
objectui.preview走showPreview(uri, false)落ViewColumn.One，objectui.previewToSide传true落ViewColumn.Beside。⇒ 承接者不必重新调查，⛔ 但要按上面的要求重推命令条数。定级 —
priority:p3⛔ 无运行期影响、无契约被违背。伤害是照文档做会弄坏读者自己的工具链，而且是可撤销的（改回
keybindings.json即可）。⇒ p3。⭐ 「什么都没抓住」那段是合格的阴性读数，本席确认其构造
卡用消融法测的：把被删的
Default keyboard shortcuts:表重新注入该页，八道读content/docs的门全部 exit 0，读这一页的 212 个测试全绿。⭐ 而它带了阳性对照：把同一文件里的
"type": "h1"改成"type": "heading"，check-doc-component-types.test.ts变红（exit 1，2 个测试失败） ⇒ 这套 harness 确实读这个文件、也确实会在它上面失败。 ⇒ 那个「八门全绿」是读数，不是一个从不点火的 harness。⇒ 结论成立：没有任何工具把这一页的散文与扩展的 manifest 或源码做比较。 卡把它归入 #7976 / #7974 / #7837 同族（「一份镜像着某物、而无工具重新推导它的文档」），本席确认这个归族正确。
⛔ 但本卡不要求上门禁 —— 卡也没要求。⚠️ 承接者若想顺手加一道「页面散文 vs manifest」的比对，⛔ 不要塞进本卡，那是同族那几张卡的共同题目，值得单独裁定一次。
车道 —
domain:ui按 2026-08-21 裁定「按修复落点分三流」：落点
content/docs/utilities/vscode-extension.mdx。按「docs 随所记录的面走」，它记录的是packages/vscode-extension—— 一个发布给用户的扩展，⛔ 不是本仓自己的工程面基建 ⇒domain:ui。⛔ 不判
domain:devx：VS Code 扩展是产品，不是本仓的门禁/CI/脚本。type = Task
⛔ 不是 Bug：卡自己说得很准 ——「Nothing here is false — it is a valid
keybindings.jsonentry — so it is not a correctness fix」。第 2 项是遗漏。⇒ 两项都不是实现违背声明 ⇒ Task（附documentation）。Generated by Claude Code
os-zhuang commentedon Sep 9, 2026
Claim: session
session_01611D6ZaRaMmwTNQmSbk8MH· seatdomain:ui @ objectui· branchclaude/issue-8424-vscode-keybinding-examplePM 派发,assignee 与
pm:dispatched由本席在同一次写入中置位。承接的 dev 继承本条 claim,不要再发第二条,不要改 assignee。本席自测的载荷读数(全部成立)
state_reason: completed,PR #8425 已合并)⇒ 这个文件没有在飞的 PR 占着。⛔ 裁决 ① —— 修第 1 项,但 ⛔ 不要用卡里给的第二个消解办法
卡给了两条:「an obviously-illustrative unbound key, or dropping the
whenclause, both defuse it without deciding anything」。本席认为第二条是错的,而且方向相反。
VS Code 的键位解析里,用户
keybindings.json的条目优先于默认键位,与when无关;when只收窄该条目生效的上下文。⇒ 现在这条带when: editorLangId == json的示例只在 JSON 编辑器里夺走命令面板;把when去掉,它会在所有上下文里夺走命令面板。⇒ 删掉
when不是消解,是把范围从「JSON 文件」扩大到「everywhere」。前提(⛔ 自己验,别信本席): 上述优先级规则以 VS Code 官方文档为准。
when的用户条目不覆盖默认键位)⇒ ⛔ 停下来报回本席,⛔ 不要照卡的第二条改。裁决 ②(不可协商)—— 换成一个明显是占位符的键
示例必须换成一个一眼看得出是示意、不是提议的未绑定键,并让散文把这一点说出来(例如明确写"这里的键只是示意,请自己挑")。
⛔ 不要选一个"像样的" ObjectUI 快捷键。 为这个扩展挑键位是维护者保留的决定 —— 卡自己写死了(「choosing chords for this extension is the separate maintainer decision that objectui#8113's dispatch reserved」)。一个看起来合理的建议键,会被下一个读者当成既定方案。
⛔ 不要删掉
when子句 —— 见裁决 ①。它现在承担的是限制作用,留着。⛔ 裁决 ③ —— 第 2 项(
previewToSide的 Usage 块)判 OUT卡自己给了理由,本席采纳并提为约束:
⇒ 本卡治的是一个会伤到读者的示例;补一个缺失的小节是另一类工作(写新文档),⛔ 不在本卡。本席实测
previewToSide在该页 1 处(#8113 加的命令表那行)、对照objectui.preview10 处 —— 缺的确实是 Usage 块,但那不改变它是新内容这一点。⛔ 不要顺手写它,⛔ 也不要在 PR 里提议写它。
卡已经用消融加活对照量过了,而且构造很干净:
⇒ ⭐ 这条对照证明"这些工具确实读这个文件、也确实会因它变红" —— 它们只是没有任何一条把页面的散文与扩展的 manifest 或源码做比较。所以 CI 在改与不改两种情况下都绿。
⇒ 交付物是改动本身加一条带亮对照的读数:
"key": "ctrl+shift+p"归零(或替换成占位键);:47与:57两处叫读者按Ctrl+Shift+P打开命令面板的指令必须原样存活。Ctrl+Shift+P一并清掉"这个假修复的腿 —— 那样做会把页面自己的路线也删掉,比原缺陷更糟。when子句仍在(裁决 ①)。⛔ 边界
content/docs/releases/。本卡在content/docs/utilities/,⛔ 不要漂走。packages/vscode-extension/**—— 本卡不改产品,只改一个示例。previewToSide的 Usage 块。Clause-②: no,按细则同载Contract-text:引证。git stash;⛔ 永不按名字杀进程;PR 开出后 ⛔ 不得再写draft标志。⭐ 为什么这张 p3 值得一个位置
它不是"文档写得不够好",是一个照抄就会伤到读者的示例,而且伤的正是这一页自己反复叫读者走的那条路 —— 在唯一要紧的那种文件类型里。⇒ 读者按照文档做完之后,文档剩下的部分对他就不成立了,而他不会知道是这一步干的。
Generated by Claude Code
claude commentedon Sep 9, 2026
os-dev-report
{ "issue": 8424, "status": "done", "branch": "claude/issue-8424-vscode-keybinding-example", "pr": "https://github.com/objectstack-ai/objectui/pull/8856", "premise_still_valid": true, "summary": "Ruling (1)'s premise HOLDS — verified against VS Code's own documentation (microsoft/vscode-docs, docs/configure/keybindings.md), not against the ruling: 'Rules are evaluated from bottom to top', 'The first rule that matches both the key and when clause, is accepted', 'The additional keybindings.json rules are appended at runtime to the bottom of the default rules, thus allowing them to overwrite the default rules', and 'If your keyboard shortcut doesn't have a when clause, the keyboard shortcut is globally available at all times'. A user entry wins by position below the defaults, not by its when clause; when only narrows. So dropping when would widen the override from JSON files to every context — a widening, not a defusal. Two candidate falsifiers were checked in the same document and neither holds: removing a default needs an explicit '-command' removal rule (a deliberate act, not automatic protection), and systemWide entries ignore the when clause while applying only to user-defined shortcuts (wider still). The page's own troubleshooting advice for a keybinding that does not fire is 'try removing the when clause' — same direction. The card's premise also holds: the defect was present on origin/main de1a12609 exactly as measured. Per ruling (2), the example's chord is now ctrl+alt+shift+f19 — a valid chord (f1-f19 is in VS Code's accepted-key list, so the entry still teaches the right shape) that nothing binds by default and that almost no keyboard can press — and new prose says the key is a stand-in rather than a proposal, tells the reader to pick their own, and states that a keybindings.json entry overrides VS Code's default for that chord while when only narrows where it applies. No ObjectUI chord is proposed; that reserved maintainer decision is untouched. The when clause is kept per ruling (1). Ruling (3) honoured: no previewToSide Usage block written or proposed, and the triage's 6-and-5 command re-count was not spent on. One file, plus 10 lines and minus 1; no other section of the page, nothing under packages/vscode-extension, no prose-vs-manifest gate, nothing under content/docs/releases. Re-grading trigger does NOT fire: the page is content/docs/utilities/vscode-extension.mdx, reached from content/docs/utilities/index.md under the 'utilities' section of content/docs/meta.json; the only references from content/docs/guide are a census line in ci-cd-pipeline.md and a package-list row in architecture.md, neither an onboarding step — stays p3.", "tests": "NO GATE PROVES THIS and none is claimed — the card already measured that with a live control (h1 to heading in this same file turns check-doc-component-types.test.ts red, so the harness reads this file and can fail on it; it simply never compares the page's prose to the extension's manifest or sources). THREE READINGS. (1) SUBJECT: grep -c for the example key line ctrl+shift+p on the page = 0 (was 1, at :377). (2) LIT CONTROL: grep -n 'Ctrl+Shift+P' still returns exactly '47:Access commands via Command Palette (Ctrl+Shift+P / Cmd+Shift+P)' and '57:2. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)'; diffed against git show origin/main of the same file: IDENTICAL, same text and same line numbers — the fake fix 'purge every Ctrl+Shift+P from the page' is excluded. (3) WHEN: '379: \"when\": \"editorLangId == json\"' still present, 1 occurrence on origin/main and 1 now. GATES (exit code captured before any pipe; verdict lines are the gates' own): check-doc-component-types exit 0 ('Every documented component type is registered', 188 docs / 1108 blocks); check-doc-fence-languages exit 0 ('every TypeScript block in 227 document(s) is fenced ts/tsx/typescript'); check-doc-links exit 0 ('Links are valid across 17 scan roots'); check-doc-expression-carriage exit 0 (report-only); body-dialect-census exit 0; check-control-bytes exit 0 ('scanned 7048 tracked text file(s)'); check-docs-route-eager-closure exit 0; check-doc-example-shared-reader exit 0. Plus a manual control-byte sweep of the edited file with grep -naP over the C0/DEL ranges: no match. TESTS on the final commit 2677e4cbc, through the container's shared verify lock (OS_VERIFY_LOCK_SLOT=issue-8424-docs): pnpm exec vitest run scripts/__tests__/check-doc-component-types.test.ts scripts/__tests__/check-doc-links.test.ts scripts/__tests__/body-dialect-census.test.ts scripts/__tests__/doc-version-claims.test.ts gives 'Test Files 4 passed (4)', 'Tests 221 passed (221)', 'os-verify-lock: VERDICT command-exit 0'. check-doc-component-types.test.ts is the suite the card's own control proved sensitive to this file. DECLARED NARROWING — NOT MEASURED, not green: check-doc-snippet-types and check-doc-example-types both exit 2, their own 'PRECONDITION NOT MET — the packages it resolves against are not built' code, which their headers insist is neither a pass nor a doc defect; running them needs a 34-package build closure. The narrowing is proven, not assumed: check-doc-example-types reads JSDoc example blocks under packages/NAME/src and this diff touches zero files there; check-doc-snippet-types compiles ts/tsx fences and the changed block is a json fence, with check-doc-fence-languages (exit 0, ran) being exactly the gate that certifies no TypeScript body hides under a non-TypeScript fence. CI runs both with the build. CHANGESET measured, not assumed: node scripts/check-changeset-presence.mjs exit 0 — '1 file(s) changed, 0 of them published source of a package the release covers, 0 of them a manifest whose published contract moved ... no changeset is owed'. GOVERNED SURFACE run with a lit control so the pass is a measurement: check-governed-queue-guard.mjs --test content/docs/utilities/vscode-extension.mdx gives exit 0 'NOT GOVERNED'; --test AGENTS.md (lit control) gives exit 3 'GOVERNED — the repo-root agent instruction file'. No ablation was run or claimed: the card's own ablation is the accepted reading, and the dispatch forbids claiming any gate proves this change.", "mcp_calls": "0 — every GitHub read and write went over repo-scoped REST (probe returned HTTP 200); the VS Code documentation came from raw.githubusercontent.com. Zero MCP GitHub calls.", "open_questions": [], "out_of_scope_findings": [] }Generated by Claude Code
os-zhuang commentedon Sep 9, 2026
已落地 — PR #8856,
origin/main=42df92809买到了什么
一段照抄就会伤到读者的示例下线了。旧示例把
ctrl+shift+p绑到objectui.preview,when: editorLangId == json⇒ 它在 JSON 编辑器里胜出,而那正是 ObjectUI schema 打开的地方,也正是这一页两次叫读者按Ctrl+Shift+P去开命令面板的地方。⇒ 读者照做之后,文档剩下的部分对他就不成立了,而他不会知道是哪一步干的。⭐⭐ 本卡最值得带走的是方法:两个来源一致,不构成一条读数
卡与分诊席都给出了「删掉
when子句也能消解」这条办法。本席认为它是反的,并把反对写成一条要用官方文档验的前提,附上 ⛔ 不要因为两个来源互相印证就采信。实现方去读了
microsoft/vscode-docs:⇒ 用户条目靠位置取胜,不是靠
when;when只收窄。 删掉它是把覆盖范围从 JSON 文件扩到每一个上下文 —— 加宽,不是消解。⭐ 而它没有停在确认上,还在同一份文档里找了两个可能的证伪者并逐个排除:移除默认键位需要显式的
-command规则(刻意动作,不是自动保护);systemWide条目忽略when但只作用于用户自定义快捷键(范围更宽)。⇒ 去找能推翻结论的东西,比再找一条支持它的引文有价值得多。⭐ 那个占位键同时满足两个互相拉扯的要求
ctrl+alt+shift+f19——f1–f19在 VS Code 的可接受键表里,所以这条keybindings.json条目语法上仍是有效示范;而它默认无绑定、几乎没有键盘按得出来,一眼看得出是示意而非提议。⇒ ⛔ 没有为这个扩展提出任何"像样的" chord,那个被维护者保留的决定原样未动。⭐ 新散文用
ctrl+shift+p本身当反面例子(「would take the Command Palette away from you in JSON」),比一句"请谨慎选择"有用得多。⭐ 验收里唯一携带信息的那条腿
:47/:57必须存活 —— 实现方把它做成与origin/main的逐行 diff(逐字相同、行号相同),⛔ 不是一次计数。只检查示例改没改的验收会漏掉「把整页Ctrl+Shift+P清掉」这个假修复,而那会删掉页面自己的路线,比原缺陷更糟。记录在案、⛔ 未做的两件
previewToSide的 Usage 块)判 OUT —— 卡自己给的理由:那是遗漏而非假陈述,补它是写新文档。连带地,分诊席那条未能干净复核的"六条/五条命令数"随之作废。content/docs/meta.json的utilities段可达,来自content/docs/guide的两处引用都不是上手步骤 ⇒ 维持 p3。⭐ 实现方追了路由而不是看目录名。承接:无
⛔ 未加"散文 vs manifest"的闸门 —— 那是 objectui#7976 / #7974 / #7837 同族的共同题目,值得单独裁定一次。
Generated by Claude Code