feat: add help links for message platform adapters in YAML and update documentation retrieval logic

2026-06-02 03:55:55 +00:00 · 2026-03-31 00:29:24 +08:00
parent 7129dd536e
commit ea638cab80
20 changed files with 94 additions and 31 deletions
--- a/src/langbot/pkg/platform/sources/aiocqhttp.yaml
+++ b/src/langbot/pkg/platform/sources/aiocqhttp.yaml
@@ -14,6 +14,10 @@ metadata:
 spec:
  categories:
    - protocol
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/aiocqhttp
+    en: https://link.langbot.app/en/platforms/aiocqhttp
+    ja: https://link.langbot.app/ja/platforms/aiocqhttp
  config:
    - name: host
      label:
--- a/src/langbot/pkg/platform/sources/dingtalk.yaml
+++ b/src/langbot/pkg/platform/sources/dingtalk.yaml
@@ -14,6 +14,10 @@ metadata:
 spec:
  categories:
    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/dingtalk
+    en: https://link.langbot.app/en/platforms/dingtalk
+    ja: https://link.langbot.app/ja/platforms/dingtalk
  config:
    - name: client_id
      label:
--- a/src/langbot/pkg/platform/sources/discord.yaml
+++ b/src/langbot/pkg/platform/sources/discord.yaml
@@ -23,6 +23,10 @@ spec:
  categories:
    - popular
    - global
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/discord
+    en: https://link.langbot.app/en/platforms/discord
+    ja: https://link.langbot.app/ja/platforms/discord
  config:
    - name: client_id
      label:
--- a/src/langbot/pkg/platform/sources/kook.yaml
+++ b/src/langbot/pkg/platform/sources/kook.yaml
@@ -14,6 +14,10 @@ metadata:
 spec:
  categories:
    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/kook
+    en: https://link.langbot.app/en/platforms/kook
+    ja: https://link.langbot.app/ja/platforms/kook
  config:
    - name: token
      label:
--- a/src/langbot/pkg/platform/sources/lark.yaml
+++ b/src/langbot/pkg/platform/sources/lark.yaml
@@ -18,6 +18,10 @@ spec:
    - popular
    - china
    - global
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/lark
+    en: https://link.langbot.app/en/platforms/lark
+    ja: https://link.langbot.app/ja/platforms/lark
  config:
    - name: app_id
      label:
--- a/src/langbot/pkg/platform/sources/line.yaml
+++ b/src/langbot/pkg/platform/sources/line.yaml
@@ -21,6 +21,10 @@ metadata:
 spec:
  categories:
    - global
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/line
+    en: https://link.langbot.app/en/platforms/line
+    ja: https://link.langbot.app/ja/platforms/line
  config:
    - name: webhook_url
      label:
--- a/src/langbot/pkg/platform/sources/officialaccount.yaml
+++ b/src/langbot/pkg/platform/sources/officialaccount.yaml
@@ -14,6 +14,10 @@ metadata:
 spec:
  categories:
    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/officialaccount
+    en: https://link.langbot.app/en/platforms/officialaccount
+    ja: https://link.langbot.app/ja/platforms/officialaccount
  config:
    - name: webhook_url
      label:
--- a/src/langbot/pkg/platform/sources/openclaw_weixin.yaml
+++ b/src/langbot/pkg/platform/sources/openclaw_weixin.yaml
@@ -15,6 +15,10 @@ spec:
  categories:
    - popular
    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/openclaw_weixin
+    en: https://link.langbot.app/en/platforms/openclaw_weixin
+    ja: https://link.langbot.app/ja/platforms/openclaw_weixin
  config:
    - name: base_url
      label:
--- a/src/langbot/pkg/platform/sources/qqofficial.yaml
+++ b/src/langbot/pkg/platform/sources/qqofficial.yaml
@@ -14,6 +14,10 @@ metadata:
 spec:
  categories:
    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/qqofficial
+    en: https://link.langbot.app/en/platforms/qqofficial
+    ja: https://link.langbot.app/ja/platforms/qqofficial
  config:
    - name: webhook_url
      label:
--- a/src/langbot/pkg/platform/sources/satori.yaml
+++ b/src/langbot/pkg/platform/sources/satori.yaml
@@ -20,6 +20,10 @@ metadata:
 spec:
  categories:
    - protocol
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/satori
+    en: https://link.langbot.app/en/platforms/satori
+    ja: https://link.langbot.app/ja/platforms/satori
  config:
    - name: platform
      label:
--- a/src/langbot/pkg/platform/sources/slack.yaml
+++ b/src/langbot/pkg/platform/sources/slack.yaml
@@ -23,6 +23,10 @@ spec:
  categories:
    - popular
    - global
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/slack
+    en: https://link.langbot.app/en/platforms/slack
+    ja: https://link.langbot.app/ja/platforms/slack
  config:
    - name: webhook_url
      label:
--- a/src/langbot/pkg/platform/sources/telegram.yaml
+++ b/src/langbot/pkg/platform/sources/telegram.yaml
@@ -23,6 +23,10 @@ spec:
  categories:
    - popular
    - global
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/telegram
+    en: https://link.langbot.app/en/platforms/telegram
+    ja: https://link.langbot.app/ja/platforms/telegram
  config:
    - name: token
      label:
--- a/src/langbot/pkg/platform/sources/wechatpad.yaml
+++ b/src/langbot/pkg/platform/sources/wechatpad.yaml
@@ -14,6 +14,10 @@ metadata:
 spec:
  categories:
    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/wechatpad
+    en: https://link.langbot.app/en/platforms/wechatpad
+    ja: https://link.langbot.app/ja/platforms/wechatpad
  config:
    - name: wechatpad_url
      label:
--- a/src/langbot/pkg/platform/sources/wecom.yaml
+++ b/src/langbot/pkg/platform/sources/wecom.yaml
@@ -15,6 +15,10 @@ spec:
  categories:
    - popular
    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/wecom
+    en: https://link.langbot.app/en/platforms/wecom
+    ja: https://link.langbot.app/ja/platforms/wecom
  config:
    - name: webhook_url
      label:
--- a/src/langbot/pkg/platform/sources/wecombot.yaml
+++ b/src/langbot/pkg/platform/sources/wecombot.yaml
@@ -14,6 +14,10 @@ metadata:
 spec:
  categories:
    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/wecombot
+    en: https://link.langbot.app/en/platforms/wecombot
+    ja: https://link.langbot.app/ja/platforms/wecombot
  config:
    - name: BotId
      label:
--- a/src/langbot/pkg/platform/sources/wecomcs.yaml
+++ b/src/langbot/pkg/platform/sources/wecomcs.yaml
@@ -14,6 +14,10 @@ metadata:
 spec:
  categories:
    - china
+  help_links:
+    zh: https://link.langbot.app/zh/platforms/wecomcs
+    en: https://link.langbot.app/en/platforms/wecomcs
+    ja: https://link.langbot.app/ja/platforms/wecomcs
  config:
    - name: webhook_url
      label:
--- a/web/src/app/home/bots/components/bot-form/BotForm.tsx
+++ b/web/src/app/home/bots/components/bot-form/BotForm.tsx
@@ -105,6 +105,9 @@ export default function BotForm({
  const [adapterDescriptionList, setAdapterDescriptionList] = useState<
    Record<string, string>
  >({});
+  const [adapterHelpLinks, setAdapterHelpLinks] = useState<
+    Record<string, Record<string, string>>
+  >({});

  const [pipelineNameList, setPipelineNameList] = useState<IPipelineEntity[]>(
    [],
@@ -212,6 +215,18 @@ export default function BotForm({
      ),
    );

+    setAdapterHelpLinks(
+      adaptersRes.adapters.reduce(
+        (acc, item) => {
+          if (item.spec.help_links) {
+            acc[item.name] = item.spec.help_links;
+          }
+          return acc;
+        },
+        {} as Record<string, Record<string, string>>,
+      ),
+    );
+
    adaptersRes.adapters.forEach((rawAdapter) => {
      adapterNameToDynamicConfigMap.set(
        rawAdapter.name,
@@ -531,7 +546,7 @@ export default function BotForm({
                      {currentAdapter &&
                        (() => {
                          const docUrl = getAdapterDocUrl(
-                            currentAdapter,
+                            adapterHelpLinks[currentAdapter],
                            i18n.language,
                          );
                          return docUrl ? (
--- a/web/src/app/infra/entities/adapter-docs.ts
+++ b/web/src/app/infra/entities/adapter-docs.ts
@@ -1,12 +1,15 @@
 /**
- * Returns the documentation URL for a given adapter name,
- * using link.langbot.app short links.
+ * Resolves the documentation URL for a given adapter from its
+ * spec.help_links map, selecting the best match for the current locale
+ * with a fallback to English.
 */
 export function getAdapterDocUrl(
-  adapterName: string,
+  helpLinks: Record<string, string> | undefined,
  locale: string,
 ): string | null {
-  // Map locale to doc language prefix
+  if (!helpLinks) return null;
+
+  // Map locale to simplified language key
  let lang: string;
  if (locale.startsWith('zh')) {
    lang = 'zh';
@@ -16,28 +19,5 @@ export function getAdapterDocUrl(
    lang = 'en';
  }

-  // Only adapters with dedicated doc pages
-  const ADAPTER_DOC_SLUGS: Record<string, string> = {
-    telegram: 'telegram',
-    discord: 'discord',
-    slack: 'slack',
-    line: 'line',
-    kook: 'kook',
-    lark: 'lark',
-    dingtalk: 'dingtalk',
-    aiocqhttp: 'aiocqhttp',
-    qqofficial: 'qqofficial',
-    wecom: 'wecom',
-    wecomcs: 'wecomcs',
-    wecombot: 'wecombot',
-    officialaccount: 'officialaccount',
-    wechatpad: 'wechatpad',
-    openclaw_weixin: 'openclaw_weixin',
-    satori: 'satori',
-  };
-
-  const slug = ADAPTER_DOC_SLUGS[adapterName];
-  if (!slug) return null;
-
-  return `https://link.langbot.app/${lang}/platforms/${slug}`;
+  return helpLinks[lang] ?? helpLinks['en'] ?? null;
 }
--- a/web/src/app/infra/entities/api/index.ts
+++ b/web/src/app/infra/entities/api/index.ts
@@ -118,6 +118,7 @@ export interface Adapter {
  icon?: string;
  spec: {
    categories?: string[];
+    help_links?: Record<string, string>;
    config: IDynamicFormItemSchema[];
  };
 }
--- a/web/src/app/wizard/page.tsx
+++ b/web/src/app/wizard/page.tsx
@@ -803,7 +803,7 @@ function StepPlatform({
                  </p>
                  {(() => {
                    const docUrl = getAdapterDocUrl(
-                      adapter.name,
+                      adapter.spec.help_links,
                      i18n.language,
                    );
                    return docUrl ? (
@@ -896,8 +896,11 @@ function StepBotConfig({
                  </CardTitle>
                  {selectedAdapterName &&
                    (() => {
+                      const selectedAdapter = adapters.find(
+                        (a) => a.name === selectedAdapterName,
+                      );
                      const docUrl = getAdapterDocUrl(
-                        selectedAdapterName,
+                        selectedAdapter?.spec.help_links,
                        i18n.language,
                      );
                      return docUrl ? (