docs(spec): connector.zod.ts 模块 JSDoc 停止宣传已退役的出站限流与映射转换 - #6473
Merged
qq9340100 merged 2 commits intoAug 8, 2026
Conversation
模块级 JSDoc 有四处措辞比它描述的 schema 晚了两次退役,而这段 JSDoc 被 gen:docs 逐字生成进 content/docs/references/integration/connector.mdx ——同一页 L171/L486 的属性表已写着「已移除」,散文却还承诺 「comprehensive rate limiting」。 收敛四处:SCOPE 行的 rate limiting、「comprehensive rate limiting」、 「Bidirectional sync with field mapping and transformations」(#5552)、 「Webhook management and rate limiting required」。 新增 "What this layer does NOT provide" 一节,措辞复用 #4911 / #5552 墓碑与 SYNC_ARCHITECTURE.md(#5554)现成句,一次退役只保留一种说法。 参考文档由 gen:docs 随动重生成(未手改)。仅注释与生成文档变化, schema 形状与运行时行为不变。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011M7UwH25Unfi73UHim7ajY
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 112 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
github-actions
Bot
added
documentation
qq9340100
marked this pull request as ready for review
August 8, 2026 01:23
qq9340100
deleted the
claude/issue-6383-connector-jsdoc-retirement-drift
branch
August 8, 2026 01:38
This was referenced Aug 8, 2026
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 #6383
问题
packages/spec/src/integration/connector.zod.ts的模块级 JSDoc 有四处措辞比它所描述的 schema 晚了两次退役。这段 JSDoc 被pnpm --filter @objectstack/spec gen:docs逐字生成进content/docs/references/integration/connector.mdx,于是同一页自相矛盾:属性表(旧 L139/L454,现 L171/L486)的墓碑行说rateLimitConfig已移除且从未存在,上方散文却承诺 comprehensive rate limiting。读者相信哪一个,取决于他先读到哪一段。伤害有两级:作者照着散文去写
rateLimitConfig,拿到strictObject的退役报错(响亮、可诊断);更糟的是他因此相信「平台替我节流出站调用」成立——而平台唯一的令牌桶packages/runtime/src/security/rate-limit.ts是入站的,没有任何东西节流连接器发出的调用。#4911 的墓碑专门点名这是连接器最像安全承诺的一面。变更(四处,一次改动 + 一次
gen:docs)Includes authentication, webhooks,rate limiting, field mapping, …… webhooks, and comprehensiverate limiting.- Bidirectional sync with field mappingand transformations- Webhook managementand rate limitingrequired三处正面承诺删除、第四处收窄之外,JSDoc 新增一节 「What this layer does NOT provide」,把两条否定连同处方写明,而不是只做减法——否则下一位作者只会再问一遍「那出站限流在哪」:
shared的RateLimitConfig顶替(方向相反);在 connector provider 或上游网关做;L3 为「上游限了流」真正声明的是retryConfig(retryableStatusCodes默认[408, 429, 500, 502, 503, 504]含429)与health.circuitBreaker。ConnectorFieldMappingSchema只扩了dataType/required/syncMode三个键;取值转换请用会真正执行它的面(import mapping 的mapping.fieldMapping[].transform,或 L2 的 ETL 转换步骤);已写了退役键的用os migrate meta --from 16。措辞直接复用 #4911 / #5552 墓碑与
packages/spec/docs/SYNC_ARCHITECTURE.md(#5554)的现成句,不另造一套——一次退役出现两种说法,就是它们日后互相矛盾的起点。改完后同一页的散文与两处墓碑行说的是同一件事。有一处刻意改写:JSDoc 里指向完整理由的锚点没写成「本文件下方那一段」。那段是
//行注释、不进gen:docs,对.mdx读者是悬空指路——正是本单要修的那类漂移。改为点名文件:integration/connector.zod.ts的REMOVED: outbound rate limiting块 +SYNC_ARCHITECTURE.md,两侧读者都走得通。交付物与 changeset 取舍
content/docs/references/integration/connector.mdx由gen:docs随动重生成(⛔ 未手改一个字节;check:docs已绿)。本单带 changeset(
patch)而非skip-changeset:改动虽只落在注释,但它有读者可见的产物——发布的参考文档页从「宣传一个不存在的能力」变成「写明它不存在并给出处方」,是使用者会读到的契约面澄清。skip-changeset的适用面是 test-only / workflow-only /.claude/-only 这类什么都不发布的 PR,本单不属于。schema 形状、类型与运行时行为零变化。验证(全部前台执行,持容器级
flock锁,--filter限定范围)check:generated首跑曾报api-surface/陈旧——那是新 worktree 未 build 的假红(该产物按其自身说明「Reads the BUILTdist/*.d.ts」,而gen:api-surface直接以Could not resolve module symbol … Is the package built?失败)。pnpm --filter @objectstack/spec build后复跑 10 项全绿,且api-surface/一个字节未变——它只存name (kind),不含任何文档文本,JSDoc 改动在结构上不可能影响它。基线纪律(分诊条件 3)
本分支基点
eb7613c79就是 #6466 的合并提交本身,开工即已跟上;gen:docs在该树上整体重跑,git status只吐出connector.mdx一个文件,证明无 #6224 式陈旧组合。飞行中 main 又前进到82bf47b0b(#6471),增量仅动scripts/,不触content/docs/references/**与packages/spec/src,已git merge origin/main(⛔ 未 rebase)并复跑check:docs确认仍绿,无需再次重生成。Generated by Claude Code