docs(customization): 按实况重画 customization/index 的 src/ 目录树并纳入 docs-drift 守卫 (#988)

[yinlianghui]

Fixes #988

customization/index 三语页是 #984 的同型孪生：同一棵 src/ 树、同一个已被 #512 删除的 agents/ 分支、同一行 *.agent.ts 后缀。#984 的边界只覆盖 getting-started/for-developers，本页与它行集互斥，故按 Prime Directive #10 另立本单。

排版说明：下文凡写 src/< dir >/ 处，尖括号后的空格是为绕开 GitHub 正文消毒器——它把左尖括号紧跟字母当 HTML 标签整段吞掉。本 PR 正文初版没加空格，占位符被吞得只剩两条斜杠，故此处一律留空格。守卫与测试输出里没有这个空格。

前提复核

先对 origin/main 验证 issue 正文的每一条，全部成立：

• ls src/ 实有 18 个目录，其中没有 agents/；
• find src -name '*.agent.ts' 零命中；
• 三语页 :28 的树逐行画着 agents/，:50 的后缀表列着 *.agent.ts，:15 的表格把 AI skills 一节描述为 “Copilot skills and agent wiring”。

改了什么

整树逐目录对账（沿 PR #991 全套口径，不止剪掉死分支）。树上现有 18 项，与 ls src/ 精确一一对应：删 agents/，补真实存在却缺席的 hooks/、datasets/、mappings/、docs/、interfaces/，每条注释按实况写——objects/ 同时装 *.object.ts 模型与 *.hook.ts 生命周期逻辑；hooks/ 是把它们汇总交给 stack 的 barrel；interfaces/index.ts 目前只有版权头，如实写作“空 barrel”。docs/ 的注释写作“陈述流程所实现业务规则的应用文档”，依据是 test/docs-drift.test.ts 本身就拿这批 src/docs/*.md 与 flows 对账。

后缀表清掉 *.agent.ts 一行；:15 表格按 skills barrel 实况改写为“面向平台助手的 skills，以及注册它们的 barrel”——src/skills/index.ts 导出 6 个 skill 汇成 allSkills，没有任何 agent 接线。树下新增一段落地文本，与 #991 同型。

守卫扩面：两条轴，一处登记

三语页加入 PRODUCT_TREE_DOCS。TREE_DIAGRAM_DOCS 本身就是 ['README.md', 'AGENTS.md', 'docs/README.md', ...PRODUCT_TREE_DOCS] 展开而来，故这一处登记同时覆盖 inline 与目录树两条轴；若再往 TREE_DIAGRAM_DOCS 里重复列一遍，只会得到重名用例与重复执行。既有断言零改动。

入列是有门槛的，本页得先挣到：inline 检查拒绝空转，而本页此前一条 inline src/< dir >/ 都没有——唯一的候选是黄金法则里的 `src/**/index.ts`，那是 glob，正则不匹配。使这三页够格入列的，正是新增落地文本里那句 src/skills/index.ts。这一层已写进守卫注释，免得后来者以为“会画树就能进 PRODUCT_TREE_DOCS”。

同理，落地文本刻意写作“及其所在目录已被移除”而不写 src/agents/ 字面量：本页现已入列，任何 inline 形式的 src/agents/（哪怕是否定式）都会被判为“指向不存在的目录”。#991 的措辞正是为此，本页照搬。

红→绿两阶段验证

红（旧文档 + 扩面守卫）——6 条失败，方向与事先预判完全一致，且分属两种不同断言：

FAIL  product docs do not point at directories that no longer exist
      content/docs/customization/index.mdx: every src/< dir >/ it names exists
AssertionError: content/docs/customization/index.mdx names no src/< dir >/ at all — this
guard has gone vacuous over it. ...: expected 0 to be greater than 0

FAIL  docs that draw the src/ tree only draw directories that exist
      content/docs/customization/index.mdx: every directory under its src/ node exists
AssertionError: content/docs/customization/index.mdx draws src/ directories that do not
exist: agents. ...: expected [ 'agents' ] to deeply equal []

三语各两条。值得记一笔：inline 那三条红的是空转断言（expected 0 to be greater than 0），不是“列了不存在的目录”——因为旧文档压根没有 inline 路径。派单模板预设的是后者；实际触发的是前者，如实照录。目录树那三条才是 agents 直中。

绿（修好后）：Test Files 75 passed (75)，Tests 1772 passed | 1 skipped (1773)——恰好是红阶段 1766 passed | 6 failed 的那 6 条转绿。

六道门（flock 内串行，--max-old-space-size=4096，--maxWorkers=2）

门	退出码
validate	0
typecheck	0
lint	0（13 warning / 14 suggestion，均为既有审批与关系告警）
hygiene	0（no raw control bytes in first-party files，扫描面含 content 与 .changeset）
build	0
test	0（75 files / 1772 passed）

push 前另做一次控制字节自扫（grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]'），无命中。

边界

src/ 零改动，只动 content/docs/ 与 test/；未碰 @objectstack/* 版本与 content/docs/releases/。customization/ai-skills.mdx:10 那句合法否定式（“there is no src/agents/ directory”）未受影响——该页没有入列，守卫按页白名单而非遍历 content/docs，这正是白名单存在的理由。#595 不预判。三语同步，zh 内链不带锚。

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 6, 2026 3:36pm

[yinlianghui]

CI 三项红的定案：GitHub Actions 平台故障，非本 PR 改动

head 1104f643 上 link-check、Analyze Code (javascript)、Build and Test (22.x) 三项失败。逐一取日志后，三者失败原因完全相同，且都发生在 Prepare all required actions / Getting action download info 步骤——即 checkout 之前：

15:36:57  Failed to resolve action download info. Error: Internal Server Error
15:38:39  Failed to resolve action download info. Error: Internal Server Error
15:40:14  ##[error]Service Unavailable
15:40:14  ##[error]Failed to resolve action download info.

（link-check job 92667634724；Analyze Code job 92667633042 同形，15:40:15 收尾；Build and Test job 92667633058 同形，15:41:31 收尾。）

这三个 job 从未取到仓库代码，因此本 PR 的任何文件改动都不可能是成因。同一 head 上凡是成功解析到 action 的 job 全绿：Quality Checks、Check Changeset、Label Pull Request、Playwright、Vercel。

逐一排除 PM 提出的两条假设

1. 推送的 commit 与本地验证的树不一致？ 已核对：本地 HEAD 与 origin/claude/issue-988-customization-tree 同为 1104f643，tree 哈希同为 81afd1aa738517d8fa659a004f4611e0f82aca32，worktree git status --porcelain 为空。CI 将要跑的树与我本地跑六道门的树逐字节相同。
2. 新守卫在 CI 工作目录/路径解析上与本地有差异？ 不成立，且与本轮红无关：三个 job 都没走到 checkout。就守卫本身而言，它读文件一律走 join(REPO_ROOT, docFile)，REPO_ROOT 由 test/helpers/repo-root 从文件自身位置解析而非 process.cwd()——该文件的注释正是为这个坑写的。
3. 另：PM 提到的 docs(guides): import-and-export 按实测改写——导入向导在列表视图而非 Setup → Data，Salesforce 迁移标注未落地 (#763) #797 教训（changeset 站内路径未加反引号触发 link-check）在此不适用——本 PR changeset 里 4 处站内路径全部在反引号内，且 link-check 配置只扫改动过的 .md（file-extension: '.md'），本 PR 唯一改动的 .md 就是该 changeset，其中不含任何链接。

处置

三个 run 均已 rerun_failed_jobs 重跑（attempt 2）。重跑一度越过 action 解析进入执行，但随后 Build and Test 在 Set up job 步骤长时间停留，平台侧似仍在波动。本地六道门证据不变，全绿：

门	退出码
validate / typecheck / lint / hygiene / build	0
test	0 —— Test Files 75 passed (75)，`Tests 1772 passed

---

Generated by Claude Code

[yinlianghui]

续：重跑证实了平台故障的判断

Analyze Code (javascript) 重跑（attempt 2）在完全相同的 commit 1104f643、零代码改动的前提下由红转绿（15:44:45 success），CodeQL 亦 success。同一棵树先红后绿，本身即排除了"改动导致失败"的可能——这正是前一条评论所定案的成因。

余下两项 Build and Test (22.x) 与 link-check 的 attempt 2 卡在 Set up job 步骤（自 15:42 起逾 30 分钟无进展，steps 只有 Set up job: in_progress）；随后对两个 run 发出的 cancel_workflow_run 返回 202，但平台侧同样未生效，runner 仍未释放。故障面持续。

当前状态

检查	结论
Quality Checks	success
Check Changeset	success
Playwright	success
Analyze Code (javascript)	success（重跑后）
CodeQL	success
Label Pull Request / Vercel	success
Build and Test (22.x)	attempt 2 卡在 Set up job，平台侧未释放
link-check	同上

代码侧无待办：本地六道门在与 CI 将测同一棵树（81afd1aa）上全绿，其中 Build and Test 所跑的 hygiene / validate / lint / typecheck / build / test 六步与本地逐一对应。待平台恢复后重跑这两项即可，无需改动。

---

Generated by Claude Code

[yinlianghui]

三度重跑仍受阻于平台；代码侧无待办

对 Build and Test / Link Check 两个 run 发起了 attempt 3（rerun_workflow_run，均返回 201）。两者进入 queued 后长时间未被派发到 runner，check run 尚未注册回 PR。至此本 PR 上 GitHub Actions 的状态是：

• 已完成且全绿（7 项）：Quality Checks、Check Changeset、Playwright、CodeQL、Analyze Code (javascript)、Label Pull Request、Vercel Preview Comments。
• 未能跑完（2 项）：Build and Test (22.x)、link-check。三次尝试的失败点始终在 Set up job / Getting action download info，即 checkout 之前。

结论的证据链

1. attempt 1：三项同时 Failed to resolve action download info（Internal Server Error → Service Unavailable），无一取到仓库代码。
2. attempt 2：Analyze Code (javascript) 在同一 commit、零改动下由红转绿——同一棵树先红后绿，直接证伪"改动导致失败"。
3. attempt 2 的另两项卡在 Set up job 逾 30 分钟；cancel 返回 202 后仍需数分钟才生效。
4. attempt 3 排队至今未派发。

因此这两项红与本 PR 的 5 个文件改动无因果关系，平台恢复后重跑即可，不需要任何代码改动。

本地等价证据（与 CI 将测同一棵树 81afd1aa）

Build and Test 工作流的六个步骤与本地逐一对应，均在 flock 内串行跑过，退出码全 0：

CI 步骤	本地对应	退出码
Source hygiene	node scripts/check-source-hygiene.mjs	0
Validate metadata	pnpm validate	0
Lint metadata	pnpm lint	0
TypeScript	pnpm typecheck	0
Build	pnpm build	0
Tests	pnpm test —— 75 files / 1772 passed / 1 skipped	0

link-check 侧：其配置只扫改动过的 .md（file-extension: '.md'，check-modified-files-only: yes）。本 PR 唯一改动的 .md 是 .changeset/docs-customization-index-src-tree.md，其中不含任何链接，4 处站内路径全部在反引号内。三个 .mdx 页不在该 job 的扫描面内。

---

Generated by Claude Code

[yinlianghui]

第 4 次尝试同样受阻——停止重试，交由平台恢复后重跑

Build and Test (22.x)（job 92670524655）与 link-check（job 92670589172）的 attempt 4 已分配到 runner（1000158145 / 1000158150），但两者的 steps 至今仍只有一条：

"steps": [ { "name": "Set up job", "status": "in_progress", "started_at": "2026-08-06T15:48:15Z" } ]

与前三次同一个卡点。四次尝试的行为完全一致，故不再重试，以免持续占用 runner。

汇总：四次尝试

尝试	Build and Test	link-check	Analyze Code
1	Failed to resolve action download info	同左	同左
2	卡 Set up job 逾 30 分钟	同左	success
3	排队未派发	排队未派发	—
4	卡 Set up job	卡 Set up job	—

attempt 2 里 Analyze Code 在同一 commit、零改动下由红转绿，是本轮唯一一次让"同一棵树"跑完的观测，也是判定"红与改动无关"的直接证据。

交接

本 PR 代码侧无待办，平台恢复后直接重跑这两项即可，不需要任何改动：

• 推送树 81afd1aa 与本地跑完六道门的树逐字节相同（git rev-parse HEAD^{tree} 两端一致，worktree 干净）；
• Build and Test 的六个步骤与本地一一对应，退出码全 0，其中 pnpm test 为 75 files / 1772 passed / 1 skipped；
• link-check 在本 PR 的扫描面只有一个不含任何链接的 changeset。

其余 7 项检查（Quality Checks、Check Changeset、Playwright、CodeQL、Analyze Code、Label PR、Vercel）均已 success。

---

Generated by Claude Code