docs(integrations): narrow the "no Setup → Integrations menu" claims to what is measured (#800)

[yinlianghui]

Fixes #800

把 content/docs/guides/integrations.mdx(en / zh-Hans / zh-Hant)里两句绝对语气收成范围语气:设置 → 集成 这个分组在平台 Setup 应用里真实存在,今天没有的是「本应用启用了、并且会往它下面挂厂商连接器条目」的能力。PR #762 的核心主张一条没动。

前提复核(origin/main = 90686a4,@objectstack/* 17.0.0-rc.2)

1. 两句在最新 main 上的位置(与 issue 给的行号有出入)

issue 写的是 :19 与 :106,实测两句分别在 :23 与 :82(三个 locale 文件一致)。#762 之后该页只被 #843 动过一次(导出那一条 bullet,:15),行号自 #762 起未变 —— 也就是说 :19/:106 是 issue 正文的近似行号,不是漂移。引文本身逐字对得上,定位无歧义。

另有第三处同一断言:该页导语 :8 也写着「也不存在可用来配置连接器的 设置 → 集成 菜单」。issue 的实测段没有引到它。只改 :23 会让同一页的导语和正文互相矛盾,故一并纳入(同一句话、同一个事实,不是范围扩张;#762 的其它主张仍零回退)。

2. 九个导航分组(SETUP_APP,@objectstack/platform-objects@17.0.0-rc.2)

node_modules/@objectstack/platform-objects/dist/apps/index.mjs 只读复测,九个 group 依次是:

group_overview / group_apps / group_people_org / group_access_control /
group_approvals / group_configuration / group_diagnostics /
group_integrations / group_advanced

group_integrations(label Integrations,icon plug,requiredPermissions: ["manage_platform_settings"])自身 children: [] —— 条目全部来自外部贡献。把 node_modules/@objectstack 里所有 app: "setup" 的贡献目标扫一遍,只落在这九个 group 上,没有第十个分组:

12 group_access_control   4 group_advanced        2 group_approvals
 7 group_apps             5 group_configuration   6 group_diagnostics
 3 group_integrations     4 group_overview        4 group_people_org

3. 三个往 group_integrations 挂条目的包(逐个复测到源码行)

包	条目	出处
@objectstack/plugin-webhooks	Webhooks(sys_webhook)、HTTP Deliveries(sys_http_delivery)	dist/index.js:522-532,priority 100
@objectstack/service-datasource	Datasources	dist/index.js:1204-1220,priority 100,在 DatasourceAdminServicePlugin.init() 里无条件注册
@objectstack/mcp	Connect an Agent	dist/index.js:991-1006(CONNECT_AGENT_UI_BUNDLE),priority 110,kernel:ready 时注册

4. requires 与平台常开清单复测

objectstack.config.ts:84 → requires: ['automation', 'triggers', 'analytics', 'auth', 'ui', 'approvals', 'sharing'](与页面里印的一致)。

PLATFORM_ALWAYS_ON_CAPABILITIES(@objectstack/spec/kernel,实跑):

["queue","job","cache","settings","email","storage","sms","sharing","messaging","analytics"]

webhooks 两处都不在 —— 且 serve.js 的能力→插件表里 webhooks 只有「requires 命中才加载」这一条路径,没有任何默认加载分支。webhooks 确实未启用,issue 这一半成立。

5. 复核中发现 issue 的一处论据不成立(如实报,未写进文档)

issue 说「这三个能力一个都没加载……分组因此是空的」。实测 mcp 与 datasource 这两项在默认部署里是加载的:

• @objectstack/cli/dist/commands/serve.js:768 —— if (isMcpServerEnabled() && !requires.includes('mcp')) requires.push('mcp');isMcpServerEnabled() 在 OS_MCP_SERVER_ENABLED 未设时返回 true(@objectstack/types :124-130),本仓没有任何 .env 关掉它,而 pnpm dev / pnpm start 都走 objectstack dev|start → serve。
• serve.js:2277 起无条件挂载 DatasourceAdminServicePlugin(注释原文:"Mounted by default so a self-host runtime is a complete low-code platform out of the box"),datasource 根本不是 PLATFORM_CAPABILITY_TOKENS 里的能力词条,不受 requires 约束。

也就是说 HotCRM 今天的 设置 → 集成 下大概率有 Datasources 与 Connect an Agent 两个平台条目,分组并不空 —— 这只让原句「没有这个菜单」错得更明确,不改变本单的修法。改写措辞按「没有任何厂商连接器条目」写,不写「分组是空的」,因此文档不依赖这条未经浏览器实测的推断;该发现另行归档(见文末)。

两句(实为三句)改文,三语对照

A. 导语 :8

• en 改前:「…and there is no Setup → Integrations menu to configure one under.」
• en 改后:「…and nothing this app installs puts a connector under Setup → Integrations.」
• zh-Hans:「也不存在可用来配置连接器的 设置 → 集成 菜单」→「本应用装上的东西也没有一样会往 设置 → 集成 下面挂连接器」
• zh-Hant:「也不存在可用來設定連接器的 設定 → 整合 選單」→「本應用裝上的東西也沒有一樣會往 設定 → 整合 底下掛連接器」

B. 内置连接器段 :23(issue 的第 1 条)

• en 改前:「…no connector plugin among the platform packages, and no Setup → Integrations menu.」
• en 改后:「…and no connector plugin among the platform packages. The Setup → Integrations group itself does exist — it is one of the nine navigation groups the platform's Setup app declares, alongside Overview, Apps, People & Organization, Access Control, Approvals, Configuration, Diagnostics and Advanced — but not one of the vendors below mounts anything under it.」
• zh-Hans:「更没有 设置 → 集成 菜单」→「设置 → 集成 这个分组本身是存在的——它是平台 Setup 应用声明的九个导航分组之一,另外八个是概览、应用、人员与组织、访问控制、审批、配置、诊断与高级——但下面这张表里的厂商,没有一家会往它下面挂条目」
• zh-Hant:「更沒有 設定 → 整合 選單」→「設定 → 整合 這個分組本身是存在的……但下面這張表裡的廠商,沒有一家會往它底下掛項目」(术语按该 locale 既有写法:導覽 / 分組 / 外掛 / 中繼資料;九个分组的译名沿用 import-and-export.zh-Hant.mdx:10 已有的那一套)

后半句「照着走的人,去找的是一个并不存在的界面」原样保留 —— 那十条 Setup → Integrations → X 路径今天依然指向不存在的界面。

C. Webhooks 段 :82(issue 的第 2 条)

• en 改前:「…there is no webhook surface in HotCRM today, and no Setup → Integrations → Webhooks screen to find one under.」
• en 改后:「…there is no webhook surface in HotCRM today: with @objectstack/plugin-webhooks unloaded, the two Setup entries it contributes — Webhooks and HTTP Deliveries — do not appear under Setup → Integrations. That is not enabled here, not not built: turn the capability on as the note below describes and the plugin mounts them itself.」
• zh-Hans:「因此 HotCRM 今天没有任何 webhook 界面,也没有 设置 → 集成 → Webhooks 这样一个页面可去」→「……@objectstack/plugin-webhooks 没有被加载,它贡献的两个 Setup 条目——Webhooks 与 HTTP Deliveries——也就不会出现在 设置 → 集成 下面。这是本应用没启用,不是平台没做:按下面那段提示把这项能力打开,插件自己就会把它们挂上去。」
• zh-Hant:同构 —— 「沒有被載入 / 兩個 Setup 項目 / 外掛自己就會把它們掛上去」。

这一句是本单的实际收益:紧接其后的提示框写着「把 webhooks 加进 requires,声明你的订阅」,读者照做后 设置 → 集成 → Webhooks 就会出现 —— 页面自己的操作建议与页面自己的绝对断言在同一次部署里对撞的休眠矛盾,到此消除。

三态区分(issue 的判据)

改写后这三种状态在页面上各说各的,不再混成一句「不存在」:

状态	对象	页面现在怎么说
未落地	十类厂商连接器、事件总线、密钥存储、*.connector.ts	「不在盒子里」「尚未落地」——src/ 无连接器元数据,平台包无对应插件(#762 主张,零改动)
未启用	webhooks	平台确实提供了这项服务,是本应用没有把它加进 requires;启用即由 plugin-webhooks 自己挂进 设置 → 集成
存在但没有连接器条目	设置 → 集成 分组	分组是平台 Setup 应用九组之一,真实存在;今天没有任何厂商连接器往它下面挂条目

PR #762 零回退核对

• 十类厂商连接器不存在:表格、三列结构、(not shipped yet) 标注、「设计意图 / 需求规格」的读法说明 —— 全部未动。
• 十条 Setup → Integrations → X 配置路径指向不存在的界面:该结论句保留(:23 后半句原文)。
• src/ 无连接器元数据 / 平台包无连接器插件:两条原文保留,只删掉了并列在后面的「更没有菜单」那一个从句。
• GraphQL、事件总线、密钥存储、*.connector.ts 各段:未动。

验证(共享锁 + NODE_OPTIONS=--max-old-space-size=4096)

命令	退出码	关键行
pnpm validate	0	✓ Validation passed (1342ms);5 条 author-time warning 与 main 同
pnpm typecheck	0	tsc --noEmit 无输出
pnpm build	0	✓ Build complete (1602ms) / Artifact: dist/objectstack.json (1921.4 KB)
pnpm test -- --maxWorkers=2	0	Test Files 66 passed (66) / Tests 1587 passed | 1 skipped (1588)(source-hygiene 元测试的 ✗ … stderr 为预期)
pnpm lint	0	13 warning(s), 14 suggestion(s) —— 与 main 同
pnpm hygiene	0	✓ no raw control bytes in first-party files / ✓ source hygiene clean(扫描面含 content、.changeset,共 409 个文本文件)

控制字节自扫(改动的三个 mdx + changeset):grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' 零命中。

changeset:.changeset/integrations-scope-wording.md('hotcrm': patch)。

场外发现

第 5 节那条(mcp / datasource 默认加载,设置 → 集成 今天并不空,而整个 content/docs 从未提到 MCP 端点与 Datasources 这两个真实存在的对外 / 管理面)不在本单文件面内,按 Prime Directive #10 单独立项,不在本 PR 修。

---

Generated by Claude Code

[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 5:49am