From d346b50d745289353686560aab093ba3dcd1a56d Mon Sep 17 00:00:00 2001 From: yujiezhang-ops Date: Thu, 19 Nov 2026 16:38:04 +0800 Subject: [PATCH] feat: explain what an API key is on the Provider step The step asked for an API key without saying what one is, where it comes from, or who charges for using it. A Provider with no saved key now shows three lines under the field: what the key is, that "Get an API key" opens the Provider's own page, and that connection tests and Agent calls are real requests billed by the Provider. The billing line gives no amount and no estimate, because the price is the Provider's to state. The second line is dropped when the Provider publishes no key page, since it names a button that is then absent. Nothing is shown once a key is saved. Refs #258 Co-Authored-By: Claude Sonnet 5 --- frontend/src/i18n.tsx | 6 +++ frontend/src/pages/ProviderKeyPage.test.tsx | 42 +++++++++++++++++++++ frontend/src/pages/ProviderKeyPage.tsx | 16 +++++++- frontend/src/styles/app.css | 12 ++++++ 4 files changed, 74 insertions(+), 2 deletions(-) diff --git a/frontend/src/i18n.tsx b/frontend/src/i18n.tsx index 3fa916b..3af19e4 100644 --- a/frontend/src/i18n.tsx +++ b/frontend/src/i18n.tsx @@ -507,6 +507,12 @@ const english = { // the user may not have yet. "Register and get a key" promised the sign-up // flow; this wording covers both arriving signed in and having to sign up. "获取 API Key": "Get an API key", + "关于 API Key": "About API keys", + "API Key 是 {provider} 发给你的访问凭证,Agent 用它调用模型": "An API key is the credential {provider} issues to you. Agents use it to call models", + "还没有的话,点「获取 API Key」打开 {provider} 的官方页面,在那里注册并创建": "If you do not have one, \"Get an API key\" opens {provider}'s own page, where you sign up and create it", + // States who bills and stops there. An amount, or a word like "cheap", would + // be a promise about a price only the Provider sets. + "连通测试和 Agent 的每次调用都是真实请求,由 {provider} 按它的价格计费;BootAgent 不收费,也不预估费用": "Connection tests and every call an Agent makes are real requests, billed by {provider} at its prices. BootAgent charges nothing and does not estimate the cost", "自定义模型名称(可选)": "Custom model name (optional)", // The connection step's model field. It only decides what the probe requests -- // the configured model is chosen on the next step -- and saying so plainly is diff --git a/frontend/src/pages/ProviderKeyPage.test.tsx b/frontend/src/pages/ProviderKeyPage.test.tsx index 18ceb53..e096d4a 100644 --- a/frontend/src/pages/ProviderKeyPage.test.tsx +++ b/frontend/src/pages/ProviderKeyPage.test.tsx @@ -278,4 +278,46 @@ describe("ProviderKeyPage", () => { expect(screen.queryByRole("button", { name: "获取 API Key" })).toBeNull(); }); + + describe("what a key is, for someone who has never had one", () => { + const withoutKey = (provider: Record = {}) => ({ + ...baseState, + status: { + ...status, + providers: { ppio: { ...status.providers.ppio, has_key: false, key_management_url: "https://ppio.com/settings/key-management", ...provider } }, + } as unknown as StatusResponse, + statusState: "success" as const, + }); + const explainer = () => screen.queryByRole("list", { name: "关于 API Key" }); + + it("says what it is, where it comes from and who charges for it", () => { + state = withoutKey(); + render(); + + const lines = [...(explainer()?.children ?? [])].map((line) => line.textContent); + expect(lines).toEqual([ + "API Key 是 PPIO 发给你的访问凭证,Agent 用它调用模型", + "还没有的话,点「获取 API Key」打开 PPIO 的官方页面,在那里注册并创建", + // No amount and no promise: the price is the Provider's to state. + "连通测试和 Agent 的每次调用都是真实请求,由 PPIO 按它的价格计费;BootAgent 不收费,也不预估费用", + ]); + }); + + // The second line names a button. Without a published page there is no + // button, and the sentence would send the user looking for one. + it("does not point at a button that is not there", () => { + state = withoutKey({ key_management_url: "", home: "" }); + render(); + + expect(explainer()?.children).toHaveLength(2); + expect(explainer()?.textContent).not.toContain("获取 API Key"); + }); + + it("stays out of the way once a key is saved", () => { + state = { ...baseState, status, statusState: "success", hasApiKey: true }; + render(); + + expect(explainer()).toBeNull(); + }); + }); }); diff --git a/frontend/src/pages/ProviderKeyPage.tsx b/frontend/src/pages/ProviderKeyPage.tsx index f458712..2eb6faa 100644 --- a/frontend/src/pages/ProviderKeyPage.tsx +++ b/frontend/src/pages/ProviderKeyPage.tsx @@ -27,6 +27,7 @@ export function ProviderKeyPage() { const apiBaseUrl = providerMeta?.base_url || ""; const providerHasKey = Boolean(providerMeta?.has_key); const builtInProvider = Boolean(providerMeta && !providerMeta.custom); + const hasKeyPage = Boolean(providerMeta?.key_management_url || providerMeta?.home); const canProbe = providerHasKey; const desktop = state.setupKind === "desktop" && state.status ? selectedDesktopApp(state.status, state.selectedAgentIds) @@ -163,7 +164,18 @@ export function ProviderKeyPage() {
{!providerHasKey && builtInProvider ? ( - + <> + + {/* Only for someone without a key yet: they are the one who may not + know what is being asked for, or that the Provider is who bills. */} +
    +
  • {t("API Key 是 {provider} 发给你的访问凭证,Agent 用它调用模型", { provider: providerMeta?.name ?? "" })}
  • + {hasKeyPage ? ( +
  • {t("还没有的话,点「获取 API Key」打开 {provider} 的官方页面,在那里注册并创建", { provider: providerMeta?.name ?? "" })}
  • + ) : null} +
  • {t("连通测试和 Agent 的每次调用都是真实请求,由 {provider} 按它的价格计费;BootAgent 不收费,也不预估费用", { provider: providerMeta?.name ?? "" })}
  • +
+ ) : !providerHasKey ? (
{t("这个模型服务还没有 Key,先到模型服务页面填写")} @@ -178,7 +190,7 @@ export function ProviderKeyPage() { {providerMeta?.name} {providerMeta?.base_url}
- {providerMeta?.key_management_url || providerMeta?.home ? ( + {hasKeyPage ? (