[objectstack-fleet]

Requested by Tesla · project thread

Part of #26702

Clause-②: no
Metadata-protocol: none
Skills-docs: the skills half (skills/objectstack-automation/references/integration-recipes.md) is #28299, the skills lane's card; this PR touches no skills/** file.

维护者速读

• 改了什么：只改文档 content/docs/automation/connectors.mdx，把连接器页面里已经过时的说法改正：rest 和 openapi 现在会使用凭证句柄，飞书、钉钉、企业微信的应用凭证换取也已经在运行；只有 mcp 仍列为暂不支持。
• 为什么改：feat(connectors): rest and openapi serve oauth2 and app-credential instances through the credential handle; Feishu, DingTalk and WeCom exchanges (ADR-0143 S2) #28399 合入后，页面仍写着「应用凭证的厂商换取尚未运行」「内置 rest / openapi 不使用凭证句柄」，这两句现在是错的，会误导作者把实例声明成静态凭证。
• 风险与回滚：纯文档，不发布任何包，不影响运行时；回滚即还原本 PR。
• 先看：「How the server serves them」开头新增的应用凭证段落和三家厂商的表格，以及下方「What is not served yet」段落。
• 两分钟验证：pnpm check:doc-authoring && pnpm check:doc-anchors，预期退出码 0。
• 需要你做的：无，席位审阅并落地（本 PR 需要 skip-changeset 标签）。

What changes

content/docs/automation/connectors.mdx, three places, all in the grant-bearing auth section and the failure table:

• "How the server serves them" now opens with what serves both grant-bearing kinds: the credential handle the built-in rest and openapi providers ask on every request (registerConnectorProvider(…, { credentialHandle: true })), and what an openapi document's security decides for such an instance (security: [] is anonymous; an apiKey scheme's parameter is filled by the platform and left out of the input schema).
• New app-credential paragraph and table: the fixed per-vendor exchange (Feishu, DingTalk v1.0, WeCom) and where each token rides on a call; the token belongs to the app and nothing is connected; it is held in memory only and obtained afresh inside the 30 s skew or once on a 401; one exchange is shared by concurrent requests; WeCom's in-answer errcode 40014 / 42001 obtains the token afresh once and repeats the call once, and a second such answer fails it; no redirect is followed; no answer / 429 / 5xx is CONNECTOR_UPSTREAM_UNAVAILABLE, a refused app id or secret is a 503 naming the instance and at most the vendor's error code. The existing oauth2 text follows unchanged, now introduced as "An oauth2 instance's access token is …".
• "What is not served yet is held degraded" no longer lists app-credential or the rest / openapi providers. It now lists a grant-bearing instance on a provider that does not ask the handle (the built-in mcp provider, or a plugin provider registered without the option), the mcp instance that leaves its endpoints to discovery, and the non-https oauth2 endpoint rule, as before.
• Failure-modes table: the grant-bearing row now reads "on a provider that does not ask the credential handle (the built-in mcp provider, for now)".

Untouched by design: the (404) hunk near line 404 that draft #28346 edits, and every skills/** file.

Every fact was read from the merged code: packages/services/service-automation/src/oauth2-grant/app-credential.ts (exchanges, present, skew via BORROWED_CREDENTIAL_SKEW_MS = 30_000, retryOnVendorTokenRefusal), plugin.ts (credentialHandleNotAppliedReason), connector-openapi/src/openapi-connector.ts (the security rules), and connector-credential-source.ts (datasource lending still 422).

Tests

None: a docs-only change. The docs gates below judge it.

Verification

• dispatch-gates --commands: 43 families derived for this one path; all exit 0. check:docs and check:skill-examples exited 1 / 3 at first because packages/spec/json-schema was older than src in this worktree (a build prerequisite, not a finding); after pnpm --filter @objectstack/spec build both exit 0.
• --ran reconcile: 43 derived, 43 run, 0 NOT-MEASURED, 0 unrun.
• No changeset: nothing published changes, so the PR carries skip-changeset.

Acceptance notes

• mcp stays listed as not served: its half of ADR-0143 S2 is a separate PR that waits on the discovery-organization ruling.
• The oauth2 revoke sentence still says the discovery that would supply a revocation endpoint is ADR-0143 S2; that remains true until the mcp half lands, so it is left as is.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic. (packages/spec is not touched.)
• 2. Every name I added uses the casing for its kind. (No names added.)
• 3. No formatter ran; the docs gates pass.
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset: this one publishes nothing (skip-changeset); both declaration lines are filled in above.
• 6. packages/spec touched: not touched.
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English.
• The Before Submitting list in CONTRIBUTING.md is done.

🤖 Generated with Claude Code

https://claude.ai/code/session_01L9qibwa6RkD7A2gK6rYRNT

[objectstack-fleet]

domain:server#1 · os-tesla · session_01L9qibz3ZUbZ8Qcn1rDw9yc

维护者速读

• 改了什么：只改文档 content/docs/automation/connectors.mdx。feat(connectors): rest and openapi serve oauth2 and app-credential instances through the credential handle; Feishu, DingTalk and WeCom exchanges (ADR-0143 S2) #28399 合入后页面仍说"应用凭证的厂商换取尚未运行""内置 rest / openapi 不使用凭证句柄"，这两句已不成立；本 PR 改正，并补上应用凭证（飞书、钉钉、企业微信）的换取方式、令牌放在哪里、何时刷新、失败如何报。只有 mcp 仍列为暂不支持。
• 为什么改：产品文档说错一句话等于缺陷：作者读到"不支持"会把实例改成静态令牌，绕开平台的刷新。
• 风险与回滚：纯文档，不发布包、不影响运行时；回滚即 revert。
• 先看："How the server serves them"开头的应用凭证段落与三家厂商的表格，以及"What is not served yet"段落。
• 两分钟验证：pnpm check:doc-authoring && pnpm check:doc-anchors，退出码 0。
• 需要你做的：无，席位落地。

席位意见：每条事实都已对照合入的代码核对过，范围只限这一页，与 #28346 草稿改的 §404 不重叠。可以直接落地。

席位核对

ACCEPT · seat domain:server#1 · head 18e9b3f0 · 2026-10-31T12:45Z

1. Shape: Part of #26702, draft, base main, 1 file, +40/−7. The file is content/docs/automation/connectors.mdx, inside claim amendment 6543339271's surface. It touches no skills/** file (that half is skills(automation): teach oauth2 and app-credential as a recipe once a built-in provider takes the grant (S2 of #26702) #28299) and leaves the §404 hunk that draft docs(automation): connector credential texts follow the degrade rule (ADR-0097 note, clearConnectorCredential 503, QA item) #28346 edits alone. skip-changeset is correct because nothing published changes.
2. Facts measured against origin/main:
   • The three vendor token requests (method and URL) and where each token rides match the table in service-automation/src/oauth2-grant/app-credential.ts (:17–19, :112, :136, :166).
   • redirect: 'error' is at :220.
   • The 30 s skew is BORROWED_CREDENTIAL_SKEW_MS (:274).
   • WeCom 40014 / 42001 is at :160.
   • CONNECTOR_UPSTREAM_UNAVAILABLE retried on backoff is at :39.
   • { credentialHandle: true } is registered by connector-rest-plugin.ts:84 and connector-openapi-plugin.ts:96, and by no mcp file.
3. Gates / check-runs: dev ran 43/43 derived docs gates, all exit 0, --ran reconciled (os-dev-report 6543519278). On head 18e9b3f0 at review: 15 success, 19 skipped, 12 running, 0 failed. Auto-merge waits on the required checks.
4. Accepted deviations: the failure-modes table row is narrowed to "the built-in mcp provider, for now". It was the same false sentence in table form, so it belongs to this fix.
5. Out of scope: the oauth2 revoke sentence that names ADR-0143 S2 discovery stays as written; it remains true until the mcp half lands. The mcp PR follows on the same branch after this merges, and it updates the "not served yet" paragraph again. Clause-②: no · Metadata-protocol: none.
6. Landing: check-governed-merges --pr 28419 reports NOT governed, 47 changed lines ≤ 3000. No contract review is owed (docs only, no spec path). The seat readies the PR and arms auto-merge under the maintainer's 「按 pm-dispatch 审过的pr你可以自主落地」.