docs(automation): 补上声明式 connectors: 的手写授权指南 (#4289) - #4293
Merged
Conversation
…ative `connectors:` path gets its page (#4289) ADR-0097 made connectors tenant-authored metadata, but no hand-written page taught how to write an entry. New content/docs/automation/connectors.mdx covers the three entry shapes, the per-provider `providerConfig` contracts (rest / openapi / mcp — factory-validated at boot, invisible to `os validate`), credentialRef-based auth incl. why `oauth2` is deliberately absent from the declarative shape (enterprise tier, ADR-0015), the configuration-vs-operational failure split, and the showcase as the runnable reference. The two connector-auth exemptions in packages/spec/variant-docs.json flip to governed docs bindings per their own "when one is written, bind it" note, so the #4177 gate now enforces all five auth variants against the guide. Every example parses against the real schemas: the four full examples and the auth fragments via DeclarativeConnectorEntrySchema (including the documented rejections: inline `authentication` on a provider-bound instance, auth / providerConfig without provider, authored actions), the dispatch snippet via defineFlow, and the four marked blocks type-check under check:skill-examples (202 examples). check:variant-docs green at 8 governed / 12 exempt; check-doc-authoring clean. Closes #4289. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 107 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
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
1 participant
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.
Closes #4289(源头:#4287 豁免审计的结论项)。
缺口
ADR-0097 让连接器成为租户手写的声明式元数据——一条
connectors:条目写上provider,启动时被通用执行器物化成可派发的连接器,不用写插件代码。但全仓没有任何一页教怎么写:auth 是密钥面(credentialRef的硬规矩只活在 schema 注释里)、providerConfig是开放面(故意不由 stack schema 校验,写错os validate不报、直接硬启动失败)。人和 AI 作者都只能读 ADR 或读源码。内容
新页
content/docs/automation/connectors.mdx(issue 建议integration/,但 capabilities 页现有链接、物化器归属 service-automation、connector_action都指向 automation 分区,单页新开顶级分区太重):enabled: false惯例),何时用哪种;providerConfig契约(rest 的baseUrl+defaultHeaders→单request动作;openapi 的spec三形态+operationId派生动作;mcp 的transport+include→tools/list 派生动作),并明确写出「工厂在启动时校验、stack schema 故意不管」;credentialRef解析路径(开源层=环境变量、企业层=vault resolver),basic的 username 可留元数据、密码走 ref,api-key的headerName/paramName,以及oauth2在声明式形态里是有意缺席(企业层,ADR-0015)——写明防止作者当成遗漏;declarativeStdioopt-in 写法;导航接线:automation
meta.json/index 卡片与 bullet、flows.mdxconnector_action段落、capabilities/integrations.mdx、ai/connect-mcp.mdx(注明与之相反方向)。Ledger 同步(issue 的「落地时同步做」)
packages/spec/variant-docs.json两条 connector-auth 豁免按其自述「when one is written, bind it and delete this exemption」换成docs:绑定,$comment审计记录补一行闭环说明。check:variant-docs从 6 governed 升到 8 governed / 12 exempt——此后 schema 每加一种 auth 变体,#4177 闸门强制同步本页。验证(#4218 教训:每个示例对着真 schema 验过)
DeclarativeConnectorEntrySchema(比defineConnector更严,含 superRefine)runtime-parse 了页面全部 4 个完整示例 + 5 个 auth 片段,并断言 5 条文档声称的拒绝真的复现(内联authentication、无 provider 的 auth/providerConfig、provider-bound 授权 actions、token字段不存在);派发片段过defineFlow:15/15 ✓{/* os:check */}标记块进入check:skill-examples,对 built dist 类型检查:202 例 ✓check:variant-docs✓、node scripts/check-doc-authoring.mjs✓(215 files clean)GET /api/v1/automation/connectors(注释里的GET /connectors是简写);showcase 只有 rest/mcp 实例有派发流程,openapi 实例没有——页面措辞已按实际写: Hook字面量 (#4274) #4283 惯例)🤖 Generated with Claude Code