Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(web): the Telegram binding's links lead where their labels promise (#506)

Yaowei Zheng8c93148fdf51
diff --git a/changelog/unreleased/2026-08-27-telegram-botfather-link.md b/changelog/unreleased/2026-08-27-telegram-botfather-link.md
new file mode 100644
index 00000000..b111b7ea
--- /dev/null
+++ b/changelog/unreleased/2026-08-27-telegram-botfather-link.md
@@ -0,0 +1,37 @@
+# The Telegram binding's links lead where their labels promise
+
+- **Date:** 2026-08-27
+- **Type:** fix
+- **Scope:** `web`
+- **PR:** [#506](https://github.com/Prism-Shadow/penguin-harness/pull/506)
+
+[中文版](2026-08-27-telegram-botfather-link.zh.md)
+
+The Bot Token field's corner link was labelled "open developer console" and pointed at
+`core.telegram.org/bots/api`, the Bot API reference. Telegram has no developer console, and
+that page does not issue tokens — so a user standing on the one field that needs a token,
+following the one link that offers to supply it, landed in an 860KB API manual. The link was
+repointed at `@BotFather`, where the token actually comes from, and the label was reworded to
+name it.
+
+## Details
+
+- Telegram's corner link was repointed at `https://t.me/BotFather`. Telegram's own page for it
+ is titled "Launch @BotFather" and describes it as the bot "to create new bot accounts and
+ manage your existing bots".
+- The label was made to follow the target rather than the other way round: this channel took
+ its own `openBotFather` string instead of the shared "open developer console" wording, which
+ stayed in place for the channels that have one.
+- The link table's key was renamed `console` → `credentialSource`, and the comments around it
+ stopped calling that slot a console — the next channel added to the table reads a name and a
+ description that fit a credential issued from a chat as readily as one issued from a page.
+- The setup fold's companion link was moved from `https://core.telegram.org/bots/tutorial` to
+ `https://core.telegram.org/bots/features#botfather`. The former is "From BotFather to
+ 'Hello World'", which past its token section is about downloading an IDE and picking a
+ framework — writing a bot, which nobody doing this is doing. The latter is the BotFather
+ guide itself, opening on `/newbot` and the token it returns, which is what the fold's steps
+ already say.
+- Tests were extended to pin both halves — the corner link's target, and that its label and
+ its target name the same thing, asserted as one anchor — and to run over both dictionaries,
+ so the label cannot regress in the locale the suite does not activate.
+- The design spec was updated to match ([penguin-harness-design #70](https://github.com/Prism-Shadow/penguin-harness-design/pull/70)).
diff --git a/changelog/unreleased/2026-08-27-telegram-botfather-link.zh.md b/changelog/unreleased/2026-08-27-telegram-botfather-link.zh.md
new file mode 100644
index 00000000..463c24f7
--- /dev/null
+++ b/changelog/unreleased/2026-08-27-telegram-botfather-link.zh.md
@@ -0,0 +1,30 @@
+# Telegram 绑定的链接指向其文案承诺的地方
+
+- **Date:** 2026-08-27
+- **Type:** fix
+- **Scope:** `web`
+- **PR:** [#506](https://github.com/Prism-Shadow/penguin-harness/pull/506)
+
+[English](2026-08-27-telegram-botfather-link.md)
+
+Bot Token 字段角上的链接文案是「前往开发者后台」,指向的却是 Bot API 参考文档
+`core.telegram.org/bots/api`。Telegram 根本没有开发者后台,那个页面也不签发 Token——于是用户
+站在唯一需要 Token 的字段上,点开唯一承诺提供它的链接,落进了一份 860KB 的 API 手册。该链接
+改为打开 `@BotFather`,也就是 Token 真正的来源,文案也改为照实说明。
+
+## 细节
+
+- Telegram 角上链接改指向 `https://t.me/BotFather`。Telegram 自己给这个页面的标题就是
+ 「Launch @BotFather」,并说明它用于「创建新的机器人账号并管理已有机器人」。
+- 改成文案跟随目标,而不是反过来:该渠道改用自己的 `openBotFather` 文案,而共享的「前往开发者
+ 后台」留给确实有后台的渠道。
+- 链接表的键由 `console` 改名为 `credentialSource`,周边注释也不再把这一槽位称作后台——下一个
+ 被加进这张表的渠道,读到的键名与说明适用于「凭据由聊天而非网页签发」的情形。
+- 创建步骤折叠区的配套链接由 `https://core.telegram.org/bots/tutorial` 改为
+ `https://core.telegram.org/bots/features#botfather`。前者是「From BotFather to 'Hello
+ World'」,在讲完取 Token 之后就转去下载 IDE、挑选框架——那是在写一个机器人,而这里没有人在写
+ 机器人。后者正是 BotFather 指南本身,开篇即 `/newbot` 与它返回的 Token,与折叠区里已有的步骤
+ 一致。
+- 测试补齐了两处锁定:角上链接的目标,以及它的文案与目标指的是同一件事——两者在同一条断言里
+ 一起校验;并改为遍历两套词典,使该文案无法在测试未激活的那种语言里悄悄回退。
+- 设计规格已同步改写([penguin-harness-design #70](https://github.com/Prism-Shadow/penguin-harness-design/pull/70))。
diff --git a/packages/web/src/features/messaging/messaging-binding-editor.tsx b/packages/web/src/features/messaging/messaging-binding-editor.tsx
index 0ed099c7..5e5d30a7 100644
--- a/packages/web/src/features/messaging/messaging-binding-editor.tsx
+++ b/packages/web/src/features/messaging/messaging-binding-editor.tsx
@@ -14,12 +14,12 @@
* channels' field lists differ in length, so controls placed under the fields would sit at
* a different height in each channel and move on every switch. The explanation lives in
* collapsed FAQ folds below the save area (`MessagingBindingHelp`), and the channel's
- * leading credential field — where the console values start being pasted — carries the
- * developer-console link at its label's top-right corner (the models-page "get API key"
- * idiom, which puts the link on the field, not in a row of its own). Secrets follow that
- * page's interaction: the field always starts empty, a stored secret shows as a masked
- * line under it with a "clear stored …" checkbox (typing unchecks it; applied on Save),
- * blank keeps the stored value — and clearing requires the channel's connection to be
+ * leading credential field — where the value starts being pasted — carries at its label's
+ * top-right corner a link to wherever that channel issues the credential (the models-page
+ * "get API key" idiom, which puts the link on the field, not in a row of its own). Secrets
+ * follow that page's interaction: the field always starts empty, a stored secret shows as a
+ * masked line under it with a "clear stored …" checkbox (typing unchecks it; applied on
+ * Save), blank keeps the stored value — and clearing requires the channel's connection to be
* disabled first. The connection switch IS the bind/unbind control — enabling binds the
* bot to this conversation, turning it off releases it, and the credentials stay saved
* through both, so several conversations may keep one bot saved and take turns holding it
@@ -66,16 +66,30 @@ import {
/** How often the visible editor refreshes the runtime status (connects settle within a poll or two). */
const STATUS_POLL_MS = 3000;
-/** Per-channel external links: the walkthrough (setup FAQ fold) and the console where the credential is fetched (field corner). */
-const CHANNEL_LINKS: Record<MessagingChannel, { tutorial: string; console: string }> = {
+/**
+ * Per-channel external links: the walkthrough (setup FAQ fold) and where the channel issues
+ * the credential (field corner). The second is a developer console for some channels and a
+ * chat with a bot for others, so its label belongs to the channel — only the ones that do
+ * have a console reach for the shared `S.messaging.console` wording.
+ */
+const CHANNEL_LINKS: Record<MessagingChannel, { tutorial: string; credentialSource: string }> = {
feishu: {
// Feishu's own echo-bot walkthrough: creating a self-built app and its long connection.
tutorial: "https://open.feishu.cn/document/develop-an-echo-bot/introduction",
- console: "https://open.feishu.cn/app",
+ credentialSource: "https://open.feishu.cn/app",
},
telegram: {
- tutorial: "https://core.telegram.org/bots/tutorial",
- console: "https://core.telegram.org/bots/api",
+ // The BotFather section of the bot-features page: "a detailed guide to using
+ // @BotFather", opening on /newbot and the token it returns — which is this fold's
+ // steps, one level deeper. NOT /bots/tutorial: that one is "From BotFather to 'Hello
+ // World'", and past its token section it is about downloading an IDE and picking a
+ // framework, i.e. about WRITING a bot. Nobody here is writing one — PenguinHarness is
+ // the bot. The fragment is a plain document anchor present in the served HTML, so it
+ // lands where it says (unlike a hash route, which the server never sees).
+ tutorial: "https://core.telegram.org/bots/features#botfather",
+ // Where the credential is actually issued. Telegram has no web console: the token comes
+ // from @BotFather inside the app, and this link is the one that leads there.
+ credentialSource: "https://t.me/BotFather",
},
};
@@ -476,8 +490,8 @@ function StoredSecretRow({
/**
* The editor's body, top to bottom: the channel selector, the connection controls (enable
* toggle + live status, then the two probes, then the hint naming what gates the switch),
- * then the selected channel's credential fields (console link at the credential field's
- * corner, models-style stored-secret row), and last the one saved field that is not a
+ * then the selected channel's credential fields (credential-source link at the credential
+ * field's corner, models-style stored-secret row), and last the one saved field that is not a
* credential — the one-message-per-line delivery option, which Save persists like the rest. Only the selector and the controls sit above the
* fields, and everything above the fields is channel-independent in height, so the toggle
* and the probes hold one vertical position no matter which channel is selected. Hosts
@@ -585,7 +599,12 @@ export function MessagingBindingBody({ b }: { b: MessagingBindingEditorState })
<CornerLinkedField
label={S.telegram.botToken}
required={!facts.secretConfigured}
- link={<ExternalLink href={links.console} label={S.messaging.console} />}
+ // Not the shared "developer console" label: this one opens @BotFather in the
+ // Telegram app, and a corner link promising a console that does not exist sends
+ // the reader looking for a web page Telegram has never had. The label names the
+ // thing the click actually reaches — Telegram's own page for it is titled
+ // "Launch @BotFather".
+ link={<ExternalLink href={links.credentialSource} label={S.telegram.openBotFather} />}
>
<PasswordInput
size="sm"
@@ -618,7 +637,7 @@ export function MessagingBindingBody({ b }: { b: MessagingBindingEditorState })
<CornerLinkedField
label={S.feishu.appId}
required
- link={<ExternalLink href={links.console} label={S.messaging.console} />}
+ link={<ExternalLink href={links.credentialSource} label={S.messaging.console} />}
>
<Input
size="sm"
diff --git a/packages/web/src/features/messaging/messaging-panel.tsx b/packages/web/src/features/messaging/messaging-panel.tsx
index 8a00ed4f..089c284b 100644
--- a/packages/web/src/features/messaging/messaging-panel.tsx
+++ b/packages/web/src/features/messaging/messaging-panel.tsx
@@ -5,10 +5,10 @@
* channel selector switching between the two channels' forms (each independently
* savable), then the connection controls — the enable/disable toggle (one enabled channel
* per conversation) with the live status line, both probes, and the hint naming what gates
- * the switch — then the per-channel credential fields with the console link at the field
- * corner and the models-style stored-secret row, and the collapsed FAQ folds below the
- * Save area. There is no unbind action — removing a credential is the secret field's clear
- * checkbox.
+ * the switch — then the per-channel credential fields with the credential-source link at
+ * the field corner and the models-style stored-secret row, and the collapsed FAQ folds
+ * below the Save area. There is no unbind action — removing a credential is the secret
+ * field's clear checkbox.
*
* Status polling is gated on `active` (the dock keeps hidden tabs mounted): a hidden tab
* neither polls nor loses the form state it accumulated.
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index ffb44e05..c12baa32 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -1798,6 +1798,12 @@ Scenarios:
botTokenKeepHint: "Leave empty to keep the saved Bot Token",
/** The stored-token row's clear checkbox (the models-page clear idiom). */
clearToken: "Clear stored Bot Token",
+ /**
+ * The Bot Token field's corner link. Telegram has no developer console — the token is
+ * issued by @BotFather inside the app — so this channel names the destination instead
+ * of borrowing the shared "open developer console" label.
+ */
+ openBotFather: "Open @BotFather",
invalidToken: "The Bot Token looks like <digits>:<secret>, as issued by @BotFather",
/** Why "send test message" is disabled before the bot has ever been messaged. */
testMessageNoChat: "Message the bot once in Telegram first, so it knows which chat to send to",
@@ -1824,7 +1830,12 @@ Scenarios:
feishu: "Feishu",
telegram: "Telegram",
},
- /** Per-channel external links: the tutorial (in the setup FAQ fold) and the console (at the credential field's corner). */
+ /**
+ * Shared link labels: the tutorial (in the setup FAQ fold) and, at the credential field's
+ * corner, the developer console — the latter only for the channels that have one. A
+ * channel whose credential is issued elsewhere names that destination itself (Telegram's
+ * `telegram.openBotFather`).
+ */
tutorial: "Open tutorial",
console: "Open developer console",
/** The connection toggle (flips immediately, using the stored credentials). */
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index 13442395..3db82c16 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -1760,6 +1760,12 @@ Benchmark:
botTokenKeepHint: "留空保持已保存的 Bot Token 不变",
/** The stored-token row's clear checkbox (the models-page clear idiom). */
clearToken: "清除已存 Bot Token",
+ /**
+ * The Bot Token field's corner link. Telegram has no developer console — the token is
+ * issued by @BotFather inside the app — so this channel names the destination instead
+ * of borrowing the shared "open developer console" label.
+ */
+ openBotFather: "打开 @BotFather",
invalidToken: "Bot Token 形如「数字:密钥」,由 @BotFather 签发",
/** Why "send test message" is disabled before the bot has ever been messaged. */
testMessageNoChat: "先在 Telegram 中给机器人发一条消息,机器人才知道要发到哪个会话",
@@ -1786,7 +1792,12 @@ Benchmark:
feishu: "飞书",
telegram: "Telegram",
},
- /** Per-channel external links: the tutorial (in the setup FAQ fold) and the console (at the credential field's corner). */
+ /**
+ * Shared link labels: the tutorial (in the setup FAQ fold) and, at the credential field's
+ * corner, the developer console — the latter only for the channels that have one. A
+ * channel whose credential is issued elsewhere names that destination itself (Telegram's
+ * `telegram.openBotFather`).
+ */
tutorial: "前往教程",
console: "前往开发者后台",
/** The connection toggle (flips immediately, using the stored credentials). */
diff --git a/packages/web/test/messaging-binding-editor.test.ts b/packages/web/test/messaging-binding-editor.test.ts
index ffc8b157..7632d850 100644
--- a/packages/web/test/messaging-binding-editor.test.ts
+++ b/packages/web/test/messaging-binding-editor.test.ts
@@ -3,14 +3,15 @@
*
* Six rules this pins, all of which are invisible to a type checker: the form opens on its
* FIELDS (the explanation lives in the collapsed FAQ under the save area, not above the first
- * input), each channel's developer-console link rides the credential field's corner, the
- * connection switch — which IS the bind/unbind — carries that sentence as its own tooltip
- * rather than as a line the form would have to make room for, a stored secret is removed by
- * the models-page clear checkbox and that checkbox is gated, on screen, while the channel
- * holds the connection, and a connection error's detail reaches the reader whole rather than
- * as a few words of a shared row.
+ * input), each channel's credential-source link rides the credential field's corner, that
+ * link's label names the place it actually opens, the connection switch — which IS the
+ * bind/unbind — carries that sentence as its own tooltip rather than as a line the form
+ * would have to make room for, a stored secret is removed by the models-page clear checkbox
+ * and that checkbox is gated, on screen, while the channel holds the connection, and a
+ * connection error's detail reaches the reader whole rather than as a few words of a shared
+ * row.
*/
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
import { createElement } from "react";
import { renderToStaticMarkup } from "react-dom/server";
import type { MessagingChannel } from "@prismshadow/penguin-server/api";
@@ -21,7 +22,10 @@ import {
type MessagingChannelFacts,
} from "../src/features/messaging/messaging-binding-editor";
import { emptyMessagingForm } from "../src/features/messaging/messaging-binding-form";
-import { S } from "../src/lib/strings";
+import { S, setActiveStrings, zh } from "../src/lib/strings";
+import { en } from "../src/lib/strings-en";
+
+afterEach(() => setActiveStrings(zh));
const DARK: MessagingChannelFacts = {
secretConfigured: false,
@@ -72,11 +76,33 @@ describe("MessagingBindingBody", () => {
expect(render(stateOf("telegram"))).not.toContain(S.telegram.intro);
});
- it("hangs each channel's developer-console link on its credential field's corner", () => {
+ it("hangs each channel's credential source on its credential field's corner", () => {
// The models dialog's "get API key" idiom: the link sits where the value is pasted, so the
// reader never has to leave the field to find out where the value comes from.
expect(render(stateOf("feishu"))).toContain('href="https://open.feishu.cn/app"');
- expect(render(stateOf("telegram"))).toContain('href="https://core.telegram.org/bots/api"');
+ // Telegram's Bot Token is issued by @BotFather in the app, not by a web console — the
+ // corner link goes there rather than into the API reference it used to point at.
+ const telegram = render(stateOf("telegram"));
+ expect(telegram).toContain('href="https://t.me/BotFather"');
+ expect(telegram).not.toContain("core.telegram.org/bots/api");
+ });
+
+ it("labels that corner link with what it opens, never with a console Telegram has not got", () => {
+ // The defect this pins: a link labelled "open developer console" that landed in the API
+ // manual. Both dictionaries, because the label is per-locale and `S` is zh until a test
+ // says otherwise — an assertion against the active dictionary alone would leave English
+ // free to carry the very wording this fixed.
+ for (const dict of [zh, en]) {
+ setActiveStrings(dict);
+ // Label and target in ONE assertion: pinned apart, they pass just as happily with the
+ // right href on the wrong anchor.
+ const telegram = render(stateOf("telegram"));
+ const corner = /<a href="https:\/\/t\.me\/BotFather"[^>]*>([^<]*)<\/a>/.exec(telegram);
+ expect(corner?.[1]).toBe(`${dict.telegram.openBotFather} ↗`);
+ expect(telegram).not.toContain(dict.messaging.console);
+ // ...and the channels that do have a console keep it.
+ expect(render(stateOf("feishu"))).toContain(dict.messaging.console);
+ }
});
it("offers a stored secret's removal as the clear checkbox, gated on screen while enabled", () => {
@@ -201,7 +227,9 @@ describe("MessagingBindingHelp", () => {
const telegram = renderToStaticMarkup(
createElement(MessagingBindingHelp, { channel: "telegram" as MessagingChannel }),
);
- expect(telegram).toContain('href="https://core.telegram.org/bots/tutorial"');
+ // The BotFather guide, not "From BotFather to 'Hello World'": the reader of this fold is
+ // creating a bot to paste a token from, not writing one.
+ expect(telegram).toContain('href="https://core.telegram.org/bots/features#botfather"');
expect(telegram).toContain(S.telegram.setupSteps[0]);
});
});