Skip to content

docs(skills): 把 console-development.md 三处表/节里 13 个符号的路径钉回真实位置 (#3730) - #3734

Merged
yinlianghui merged 1 commit into
mainfrom
claude/issue-3730-guide-symbol-paths
Aug 8, 2026
Merged

docs(skills): 把 console-development.md 三处表/节里 13 个符号的路径钉回真实位置 (#3730)#3734
yinlianghui merged 1 commit into
mainfrom
claude/issue-3730-guide-symbol-paths

Conversation

@yinlianghui

@yinlianghuiyinlianghui commented Aug 8, 2026

Copy link
Copy Markdown
Collaborator

Fixes#3730

单文件改动：skills/objectui/guides/console-development.md。四项路径订正 + 一处授权搭改。
所有替换后的 Location 都由本分支自己在 origin/main 上跑 find/ls 逐条核过，未照抄卡片
（卡片自己也提醒过这个映射不是整体平移一层前缀）。基线 origin/main @ 4e93e40d7（PR #3729
刚重写过本文件，卡内行号已失效，全部按内容锚定）。

一、Key contexts 表（5 行全改）

apps/console/src/context/ 这个目录整个不存在。五个符号都在 @object-ui/app-shell，但
app-shell 内部有 context/ 与 providers/ 两个平级目录，五个符号分散在两边 —— 所以表头
新增一句说明「按行核前缀，不要整表平移」，避免下一位读者把它当成统一前缀。

Context改后 Location
AdapterProviderpackages/app-shell/src/providers/AdapterProvider.tsx
MetadataProviderpackages/app-shell/src/providers/MetadataProvider.tsx
NavigationContextpackages/app-shell/src/context/NavigationContext.tsx
FavoritesProviderpackages/app-shell/src/context/FavoritesProvider.tsx
ExpressionProviderpackages/app-shell/src/providers/ExpressionProvider.tsx

MetadataProvider 是全仓唯一重名的一个，表后加了一句消歧：console 用的是 app-shell 那个
（ConsoleShell / ConnectedShell 挂载它、@object-ui/app-shell 再导出它，已核 import
与 barrel），packages/providers/src/MetadataProvider.tsx 是另一个无关的通用 provider。

二、Key hooks 表（8 行里改 7 行）

useBranding 是 apps/console/src/hooks/ 里唯一一个文件，也恰好是表里唯一正确的一行；
其余七个都在 packages/app-shell/src/hooks/。同样加了一句说明，免得第一行的前缀被外推。

三、UnifiedSidebar / NavigationContext 两个小节的开篇路径

  • ### UnifiedSidebar：apps/console/src/components/UnifiedSidebar.tsx 改为
    packages/app-shell/src/layout/UnifiedSidebar.tsx（并注明与 ConsoleLayout.tsx 同目录）。
    行为描述（persistent / context-aware / app switcher）按派发单只钉路径，未动。
  • ### NavigationContext：同小节群里还有第二处同类死路径
    apps/console/src/context/NavigationContext.tsx，与 Key contexts 表第三行是同一个符号、
    同一个不存在的目录，一并改为 packages/app-shell/src/context/NavigationContext.tsx。
    留着它等于把卡片自己列为错误的那个字符串原样留在文件里，故一并订正并在此单列说明。

改完全文只剩一处 apps/console/src/context/ 字样，且是新写的否定句（「这个目录并不存在」），
是故意的。

四、Registered custom widgets 表补第七行

registerObjectDetailWidgets.ts 实际 ComponentRegistry.register() 七次，表里只列了六个，
缺 object-keys / ObjectKeysWidget。补上该行（用途按 ObjectKeysWidget 实现描述：unique /
id / external-id 字段），并把表头的 "registers" 写成 "registers seven types"，附一句「表与文件
不一致时数 register 调用」。此处原有的文件路径是对的，未动。

五、【授权搭改，单列】permissions 重定向段落已过期

派发单授权的同文件搭改。原文写着该重定向「queued but not yet on main，所以今天 URL 仍会
落到 app-shell 的 tail route」—— PR #3728（commit cc95c2c31）今天已合入 main，这句话现在是假的。
已核 origin/main 的 apps/console/src/AppContent.tsx：

system/permissions -> SystemObjectRedirect objectName="sys_permission_set"

改动两处：

  1. 上方路由清单补第五条 system/permissions -> SystemObjectRedirect -> …/sys_permission_set。
  2. 段落重写：删掉 "Four redirects, not five" 与 "not yet on main" / tail-route 兜底的描述，改成
    「五条腿在 origin/main 上都能解析」，保留 ADR-0066 layer 1 / layer 2 的由来（为什么最终选
    sys_permission_set 而不是 sys_capability），并把自查指针从「引用前先看一眼」改成「理由在
    AppContent.tsx 的路由注释里写全了，去那里读，别自己重推；要加第六条腿时再对一遍清单」。

与卡片事实的一处偏差（不影响本单前提）

卡片（及本 guide 顶部的注记）把这批符号的成因记为 commit cccdf84d7（console 瘦身）。
实测这 13 个符号都不是在 cccdf84d7 里搬走的：

  • AdapterProvider / MetadataProvider / ExpressionProvider —— app-shell 副本由
    c1e105793（04-21）加入，console 副本由 28ffe4033（04-22）删除，两者都早于cccdf84d7。
  • NavigationContext / FavoritesProvider / UnifiedSidebar / 七个 hooks —— app-shell 副本的
    加入与 console 副本的删除都发生在 b279d80d6（04-23），晚于cccdf84d7 一天。

即「路径全错」这个承重前提成立（已逐条复核），只是归因写错了。因此本 PR 的两处新写引言不
提任何成因 commit，只陈述今天的位置事实；顶部注记的归因不在本单文件面授权范围内（派发单明确
不动目录树与 Retired-names 锚点），另立 finding 记账。

验证

改动是纯 markdown 文档，无代码面、无可写的单元测试；相应地跑的是门禁 + 磁盘存在性断言：

  • node scripts/check-control-bytes.mjs → OK (scanned 3686 tracked text file(s))
  • 控制字节自查（超出门禁扫描面）：grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' 本文件 → 无命中
  • CJK 自查：本文件 0 行 CJK（英文正文约定未破）
  • node scripts/check-doc-links.mjs → Links are valid across 7 scan roots.
    （注：SCAN_ROOTS 不含 skills/，本文件不在该门禁覆盖面内，跑它只为确认未连带破坏）
  • 卡片的复核脚本原样重跑，结论与卡片一致：apps/console/src/ 无 context 项、
    apps/console/src/hooks/ 只有 useBranding.ts、apps/console/src/components/ 无
    UnifiedSidebar.tsx、register 调用数 = 7
  • 全文回归断言：抽出文件里所有反引号包裹的仓内路径逐个 existsSync，34 条命中 33 条存在，
    唯一「不存在」的就是第三节末尾说明的那句故意否定句
  • 未改 skills/objectui/evals/console-development.json：已确认该 eval 不 pin 任何被我改动的
    字符串（must_contain 只要求出现 UnifiedSidebar 这个词，改动后仍在）

Changeset

无。已核同类先例：PR #3729（4e93e40d7，本文件今日的重写）、c19ddf027、91e03f466 三个
skills-only 的 docs(skills) 提交都没有 .changeset/ 条目 —— skills/ 不是发布包，按仓内约定
不需要。

Generated by Claude Code

@claude
docs(skills): point console-development.md's 13 relocated symbols at …
2907d03
…their real paths (#3730)
The Key contexts table, the Key hooks table and the UnifiedSidebar /
NavigationContext subsections spelled 13 symbols under `apps/console/src/`
directories that do not exist: `apps/console/src/context/` is absent entirely and
`apps/console/src/hooks/` holds exactly one file (`useBranding.ts`). The symbols
are all real, so the wrong coordinates cost a reader a full locate loop rather
than a compile error.
Every replacement Location is verified against the tree, per row. app-shell
keeps both a `context/` and a `providers/` directory and the five contexts are
split across them, so the mapping is not a uniform prefix shift; lead-ins now
say so, and disambiguate `MetadataProvider` from the unrelated
`packages/providers/src/MetadataProvider.tsx`.
Also: the widget table gained the seventh registration (`object-keys` ->
`ObjectKeysWidget`), and the permissions redirect passage is rewritten to the
post-#3728 reality — the `system/permissions` leg is on `main`, so all five
legs now resolve and the "queued but not yet on main" framing is retired.
Co-Authored-By: Claude <noreply@anthropic.com>
@vercel

vercelBot commented Aug 8, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
ProjectDeploymentActionsUpdated (UTC)
objectuiIgnoredIgnoredAug 8, 2026 10:35am

Request Review

This was referenced Aug 8, 2026
Closed
Closed
Closed
@yinlianghui
yinlianghui marked this pull request as ready for review August 8, 2026 10:59
@yinlianghui
yinlianghui added this pull request to the merge queueAug 8, 2026
Merged via the queue into main with commit 8ad6070Aug 8, 2026
16 checks passed
@yinlianghui
yinlianghui deleted the claude/issue-3730-guide-symbol-paths branch August 8, 2026 10:59
This was referenced Aug 8, 2026
Merged
Merged
akarma-synetal pushed a commit to akarma-synetal/objectui that referenced this pull request Aug 10, 2026
@yinlianghui@claude
docs(skills): console-development.md 顶部注记的搬家归因改成 04-21→04-23 的 commit…
6422aa8
… 链,cccdf84d7 降为其中一步 (objectstack-ai#3737) (objectstack-ai#3856)
顶部引用块把「shell / layouts / home pages / navigation / 整个 metadata admin 迁入
@object-ui/app-shell」整包记在 commit cccdf84 名下,:82 那行又复述一遍「all of it
left apps/console in cccdf84」。按注记去 git show 会拿到一个不含目标符号的 diff ——
cccdf84 在 apps/console 下只删了 16 个文件:四个 designer 页、五个 pages/system/
页、五个测试与两个 view-config 工具,shell / layout / navigation / home / hooks /
providers 一个都不在里面。
实测的真实形态是一条跨三天的链(c1e1057 04-21 → 28ffe40 04-22 → cccdf84 04-22
→ b279d80 04-23),cccdf84d7 只是其中一步:
- providers(AdapterProvider / MetadataProvider / ExpressionProvider):app-shell 副本
在 c1e1057(04-21)加入,apps/console 副本在 28ffe40(04-22)删除 —— 两者都是
cccdf84 的祖先。
- navigation / layout / home / hooks(NavigationContext、FavoritesProvider、
UnifiedSidebar、ConsoleLayout、console/home/*、七个 hooks):apps/console 副本在
b279d80(04-23)删除,比 cccdf84 晚一天,而那个 commit 的标题是「feat: Add
ReportView and SearchResultsPage components」,一个字都没提这批符号 —— 想顺着注记
追溯的人绝不会往那儿找,这也是本次订正把标题原样写进注记的原因。
改法保留 cccdf84 这个名字作纠错锚(不删),明写「早先版本把整包记在它名下」,让照
旧坐标搜索的人落在订正上而不是空手。两处 hooks 细节顺手写准:useObjectActions 与
useRecentItems 的 app-shell 副本其实早在 c1e1057 就落地,只有 console 副本等到
b279d80 才删,与卡片正文把七个 hooks 一律归给 b279d80 略有出入,结论不变。
边界:注记里 metadata admin 与 designer 两半未逐条复核,按 objectstack-ai#3737 卡片边界不动 ——
本次只是把「单一 commit」这个错坐标撤掉,没有替它们另指一个 commit;objectstack-ai#3730/PR objectstack-ai#3734
已修的三处表/节同样未碰。ROADMAP.md:857/871 与 AppContent.tsx:110 对 cccdf84 的引用
经核实是正确用法(PermissionManagementPage 等确实在该 commit 删除),不在改动面内。
复核命令:
git merge-base --is-ancestor 28ffe40cccdf84
git merge-base --is-ancestor cccdf84b279d80
git log --diff-filter=A --format='%h %ad %s' --date=short -- <app-shell 路径>
Co-authored-by: Claude <noreply@anthropic.com>
akarma-synetal pushed a commit to akarma-synetal/objectui that referenced this pull request Aug 10, 2026
@yinlianghui@claude
ci(skills): skills 指南正文反引号里的仓内路径上门禁,豁免走双向陈旧检测的 baseline (objectstack-…
7437064
…ai#3735) (objectstack-ai#3864)
`skills/objectui/**` 的指南是本仓 agent 写代码的直接输入,正文大量用反引号给出
仓内路径当坐标,而此前无任何门禁校验它们存在。`check-doc-links.mjs` 两头都不沾:
它的 SCAN_ROOTS 没有 skills 一行,而且它判的是 markdown 链接,反引号里的裸路径
本来也不在它眼里。代价付过两轮,两轮都靠人肉阅读发现 —— objectstack-ai#3713/PR objectstack-ai#3729 与
objectstack-ai#3730/PR objectstack-ai#3734(同一文件 13 个真实符号指向不存在的目录)。
这类缺陷贵得不成比例:符号通常是真的,只有坐标错了,所以没人拿到编译错误 ——
agent 从 Read 拿到「文件不存在」,以为是自己搜得笨,再花一整圈重新定位指南声称已
经替它定位好的东西。它还天然复发:app-shell 抽取那批 commit 搬走代码时,没有任何
东西提醒指南跟着改。
## 门禁
`scripts/check-skills-paths.mjs` —— 读 `skills/` 下每个 markdown,把正文反引号
span 里以五个顶层目录(apps/ packages/ examples/ scripts/ content/)开头、不含空格
的 token 逐个 existsSync。三条排除都是**规则**而不是豁免,因为它们都不是「某文件
存在」这个断言:
- span 里含空白 —— 散文、命令行或类型,不是路径(PR objectstack-ai#3856 新加的自查命令行正好
是这个形状,凭此一条就出局,不需要任何名单条目);
- 含 glob 元字符或占位段 —— 是形状不是位置,对它 existsSync 无意义;
- 围栏代码块 —— 示例可以合法地写出读者「即将创建」的文件。
main@6422aa891 实测:18 个指南文件、91 个候选 span、其中 5 个是 pattern,86 条
路径断言里 85 条落地。
## 豁免与它为什么不会烂掉
`scripts/skills-path-baseline.json` 只收「指南刻意声明其不存在」的路径,今天恰好
一条:console-development.md 的 Key contexts 一节存在的意义就是纠正那个反复出现的
错猜,原话是根本没有 `apps/console/src/context/` 这个目录。该条目是**双向**红的
棘轮 —— 路径哪天真出现在磁盘上,门禁红并点名(那句话已经变成假的);扫描不再命中
该条目,门禁也红(散文被改写了,条目成了死重)。条目按「文件 + token」定位,刻意
不含行号:指南散文一直在动(PR objectstack-ai#3856 刚搬过这一段),行号定位会在每次无关编辑后
陈旧。
反向验证(方向先判后跑,五个方向全部与预判一致):真实 skills 面绿(85/86 + 1
豁免);fixture 种死路径红并点名 file:line — token;豁免条目满足则绿;豁免路径出现
在磁盘上则红;豁免不再被命中则红。另有空判定护栏:扫到 0 个文件或 0 条断言即红 ——
「什么都没查到」不能算干净。
## 接线
按同族三个门禁(control-bytes.yml、docs-links.yml、changeset-guard.yml)的挂法:
独立 workflow、无任何 paths 过滤、订阅 merge_group、`pnpm check:skills-paths`。
本门禁扫描面全是 markdown,而 ci.yml 的 push 触发器把 `'**/*.md'` 列进
paths-ignore、GitHub 又没有 per-job 路径过滤,放进 ci.yml 等于重建它要堵的洞
(objectstack-ai#3448 的原话)。ci-cd-pipeline.md 的 workflow 清单在两个方向上都被钉住,所以
新 workflow 连带一节文档与一行清单。
扫描面刻意不含 `content/docs/**`:扩面自带一批要清的红,check-doc-links 学过三遍
(objectstack-ai#3479/objectstack-ai#3490/objectstack-ai#3545),先量红再单独落地。五前缀名单同理 —— 补上本仓另外五个顶层
目录实测为 +2 候选、0 新红,便宜,但仍然是一个刻意的决定。
无 changeset:同族三个门禁脚本(check-control-bytes、check-i18n-call-site-keys、
check-changeset-presence)落地时都没带,且本改动不碰任何发版包 src/。
Co-authored-by: Claude <noreply@anthropic.com>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

2 participants

@yinlianghui@claude