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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.tsxindex 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 })<CornerLinkedFieldlabel={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} />}><PasswordInputsize="sm"@@ -618,7 +637,7 @@ export function MessagingBindingBody({ b }: { b: MessagingBindingEditorState })<CornerLinkedFieldlabel={S.feishu.appId}required- link={<ExternalLink href={links.console} label={S.messaging.console} />}+ link={<ExternalLink href={links.credentialSource} label={S.messaging.console} />}><Inputsize="sm"diff --git a/packages/web/src/features/messaging/messaging-panel.tsx b/packages/web/src/features/messaging/messaging-panel.tsxindex 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.tsindex 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.tsindex 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.tsindex 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]);});});