Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 17 additions & 12 deletions docs/public-site-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,18 +29,23 @@ must not influence Agent rank, compatibility conclusions, default selection, or
tests. That boundary belongs to this repository; the site only displays the result.

**Those fields are not read by the application, and that is enforced by omission.**
`relationship`, `disclosure`, `referral_url`, `order`, and `protocols` have no counterpart
in `providerFileEntry` (`internal/catalog/providers.go`), so `json.Unmarshal` discards
them. Filling in `referral_url` therefore changes nothing in the desktop app or the CLI —
it is published for the site to render, and the "get a key" button will keep opening
`key_management_url` (falling back to `home`) regardless. Routing users through a referral
link would be a product decision requiring the field to be parsed and given an explicit
precedence, not a matter of setting a value here.

The reverse also holds: `key_management_url` and `default_model` are read by the app. They
are not disclosure fields and are not subject to the paragraph above; `default_model` is
the model pre-filled for a user who has not chosen one, so changing it changes what gets
written into a real Agent configuration.
`relationship`, `disclosure`, and `referral_url` have no counterpart in `providerFileEntry`
(`internal/catalog/providers.go`), so `json.Unmarshal` discards them. Filling in
`referral_url` therefore changes nothing in the desktop app or the CLI — it is published
for the site to render, and the "get a key" button will keep opening `key_management_url`
(falling back to `home`) regardless. Routing users through a referral link would be a
product decision requiring the field to be parsed and given an explicit precedence, not a
matter of setting a value here.

The reverse also holds: `key_management_url`, `default_model`, `order`, and `protocols` are
read by the app. They are not disclosure fields and are not subject to the paragraph above;
`default_model` is the model pre-filled for a user who has not chosen one, so changing it
changes what gets written into a real Agent configuration. `order` is the display order of
the built-in Providers. `protocols` records how far each protocol has been confirmed on a
Provider's endpoint: when the protocol an Agent needs is anything other than
`implementation-supported` while `openai` is, the setup wizard offers compatibility mode
before any request is sent. It only ever adds that optional hint; it never hides a Provider,
and connection tests still decide what actually works.

**Changing a lock file does not change the site.** The site vendors `agents.lock.json`
and `providers.lock.json` into its own `data/` directory, refreshed from release tags
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,13 @@ export interface Provider {
* custom Provider, which the frontend sorts by creation time instead.
*/
"order"?: number;

/**
* Protocol ID -> confirmed support level on a built-in Provider's endpoint,
* from providers.lock.json. Absent for a custom Provider, whose endpoint
* nothing is known about.
*/
"protocols"?: { [_ in string]?: string } | null;
"custom"?: boolean;
"has_key"?: boolean;
"created_at"?: string;
Expand Down
30 changes: 30 additions & 0 deletions frontend/e2e/wails.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,36 @@ test("a machine with no BootAgent state opens onboarding from the landing route"
await expect(page.getByRole("heading", { name: "选择 Agent", level: 1 })).toBeVisible();
});

// A first-time user is not required to test the connection, so the step itself
// has to say when the Agent's format is unconfirmed on the chosen service. This
// runs against the real status binding: the protocol table comes from
// providers.lock.json through Go, which a unit-test fixture cannot show.
test("the Provider step suggests compatibility mode without a connection test", async ({ page }) => {
await page.goto("/#/");
await expect(page.getByRole("heading", { name: "选择 Agent", level: 1 })).toBeVisible();
await page.getByRole("tab", { name: "命令行 Agent" }).click();
await page.getByLabel("选择 Codex").check();
await page.getByRole("button", { name: "继续" }).click();

await expect(page.getByRole("heading", { name: "连接模型服务" })).toBeVisible();
// JieKou.AI ships first and has not confirmed OpenAI Responses.
await expect(page.getByRole("combobox", { name: "模型服务" })).toHaveText("JieKou.AI");
const suggestion = page.getByText("尚未确认 JieKou.AI 支持 Codex 的请求格式(OpenAI Responses),可以改用兼容模式,由 BootAgent 在本机转换");
await expect(suggestion).toBeVisible();

await page.getByRole("button", { name: "使用兼容模式" }).click();
await expect(page.getByText("已选择兼容模式,使用 Codex 时需要保持 BootAgent 运行")).toBeVisible();
await page.getByRole("button", { name: "不用兼容模式" }).click();
await expect(suggestion).toBeVisible();

// DeepSeek has confirmed it, so there is nothing to suggest.
await page.getByRole("combobox", { name: "模型服务" }).click();
await page.getByRole("option", { name: "DeepSeek" }).click();
await expect(page.getByRole("combobox", { name: "模型服务" })).toHaveText("DeepSeek");
await expect(page.getByText(/尚未确认/)).toHaveCount(0);
await expect(page.getByRole("button", { name: "使用兼容模式" })).toHaveCount(0);
});

test("onboarding installs one Agent end to end and writes its Profile", async ({ page }) => {
const bindingMethodIDs = new Set<number>();
page.on("request", (request) => {
Expand Down
1 change: 1 addition & 0 deletions frontend/src/i18n.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -1029,6 +1029,7 @@ const english = {
"Claude Code 看到的模型名": "Model name Claude Code sees",
"Codex 看到的模型名": "Model name Codex sees",
"{agents} 已改用兼容模式": "{agents} now use compatibility mode",
"尚未确认 {provider} 支持 {agent} 的请求格式({protocol}),可以改用兼容模式,由 BootAgent 在本机转换": "{provider} isn't confirmed to support {agent}'s request format ({protocol}); compatibility mode lets BootAgent convert it on this computer",
"{agent} 不能直接使用这个模型服务,BootAgent 可以在本机转换后使用": "{agent} can't use this model service directly, but BootAgent can convert its requests on this computer",
"{agent} 不能直接使用这个模型服务,应用时会开启兼容模式在本机转换,使用期间需要保持 BootAgent 运行": "{agent} can't use this model service directly, so applying turns on compatibility mode, which needs BootAgent to keep running",
"{agent} 不能直接使用这个配置模版,应用时会开启兼容模式在本机转换,使用期间需要保持 BootAgent 运行": "{agent} can't use this profile directly, so applying turns on compatibility mode, which needs BootAgent to keep running",
Expand Down
167 changes: 166 additions & 1 deletion frontend/src/pages/ProviderKeyPage.test.tsx
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { fireEvent, render, screen, waitFor } from "@testing-library/react";
import { MemoryRouter } from "react-router-dom";
import { MemoryRouter, Route, Routes } from "react-router-dom";
import { afterEach, describe, expect, it, vi } from "vitest";

import { api } from "../backend/api";
Expand Down Expand Up @@ -29,6 +29,28 @@ const status = {
catalog: [],
} as unknown as StatusResponse;

// Built-in Providers as the protocol table describes them: Chat Completions is
// confirmed on both, OpenAI Responses (what Codex speaks) only on the second.
const tabledStatus = {
providers: {
jiekou: {
name: "JieKou.AI", home: "", base_url: "https://api.jiekou.test/openai", has_key: true,
protocols: { openai: "implementation-supported", anthropic: "implementation-supported", responses: "route-present-unverified" },
},
deepseek: {
name: "DeepSeek", home: "", base_url: "https://api.deepseek.test", has_key: true,
protocols: { openai: "implementation-supported", anthropic: "implementation-supported", responses: "implementation-supported" },
},
},
catalog: [{ id: "codex", name: "Codex", protocol: "responses", configMode: "auto", selectsModel: true }],
} as unknown as StatusResponse;

const codexOn = (provider: string, patch: Partial<WizardState> = {}): WizardState => ({
...initialWizardState, status: tabledStatus, statusState: "success", setupKind: "cli", selectedAgentIds: ["codex"], provider, ...patch,
});

const SUGGESTION = "尚未确认 JieKou.AI 支持 Codex 的请求格式(OpenAI Responses),可以改用兼容模式,由 BootAgent 在本机转换";

/** Pins the selected Provider to the one this fixture defines. Inheriting the
* wizard's initial Provider instead coupled these cases to whichever Provider
* ships first in providers.lock.json: when that changed, every case here looked
Expand Down Expand Up @@ -100,6 +122,149 @@ describe("ProviderKeyPage", () => {
expect(screen.getByRole("button", { name: "继续选择模型" })).toBeEnabled();
});

// The connection test is optional, so a first-time user who skipped it got no
// word about compatibility mode and installed a Codex that failed on its first
// request. The protocol table answers the same question without a request.
it("suggests compatibility mode from the protocol table, without a connection test", () => {
state = codexOn("jiekou");
keyRef.current = "";
const probe = vi.spyOn(api, "probe");
const models = vi.spyOn(api, "models").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "", error_code: null, retryable: false, models: [] });
const page = render(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);

expect(screen.getByText(SUGGESTION)).toBeTruthy();
// "Not confirmed" is all the table can say; it has not shown a failure.
expect(screen.queryByText(/不能直接使用/)).toBeNull();
expect(screen.queryByRole("alert")).toBeNull();

fireEvent.click(screen.getByRole("button", { name: "使用兼容模式" }));
page.rerender(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);
expect(state.conversion).toBe(true);
expect(screen.getByText("已选择兼容模式,使用 Codex 时需要保持 BootAgent 运行")).toBeTruthy();
expect(screen.queryByText(SUGGESTION)).toBeNull();
expect(screen.getByRole("button", { name: "继续选择模型" })).toBeEnabled();

// Billed requests start from a button the user pressed, never from a guess.
expect(probe).not.toHaveBeenCalled();
// Listing models is the page's existing unbilled lookup, not a probe.
expect(models.mock.calls.length).toBeLessThanOrEqual(1);
});

it("lets the user continue without taking the untested suggestion", async () => {
state = codexOn("jiekou");
keyRef.current = "";
const probe = vi.spyOn(api, "probe");
vi.spyOn(api, "models").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "", error_code: null, retryable: false, models: [] });
render(
<MemoryRouter initialEntries={["/setup/provider"]}>
<Routes>
<Route path="/setup/provider" element={<ProviderKeyPage />} />
<Route path="/setup/model" element={<h1>model step</h1>} />
</Routes>
</MemoryRouter>,
);

expect(screen.getByText(SUGGESTION)).toBeTruthy();
const next = screen.getByRole("button", { name: "继续选择模型" });
expect(next).toBeEnabled();
fireEvent.click(next);

expect(await screen.findByRole("heading", { name: "model step" })).toBeTruthy();
expect(state.conversion).toBe(false);
expect(probe).not.toHaveBeenCalled();
});

it("makes no suggestion when the Provider has confirmed the Agent's format", () => {
state = codexOn("deepseek");
keyRef.current = "";
vi.spyOn(api, "models").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "", error_code: null, retryable: false, models: [] });
render(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);

expect(screen.queryByText(/尚未确认/)).toBeNull();
expect(screen.queryByRole("button", { name: "使用兼容模式" })).toBeNull();
expect(screen.getByRole("button", { name: "继续选择模型" })).toBeEnabled();
});

it("makes no suggestion for a custom Provider, which has no protocol table", () => {
const custom = {
...tabledStatus,
providers: { mine: { name: "Mine", home: "", base_url: "https://api.mine.test/v1", has_key: true, custom: true } },
} as unknown as StatusResponse;
state = codexOn("mine", { status: custom });
keyRef.current = "";
vi.spyOn(api, "models").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "", error_code: null, retryable: false, models: [] });
render(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);

expect(screen.queryByText(/尚未确认/)).toBeNull();
expect(screen.queryByRole("button", { name: "使用兼容模式" })).toBeNull();
});

// Only the untested suggestion is optional. Once a test has shown the Agent's
// format failing while Chat Completions works, the choice is required again.
it("requires the choice once a connection test has actually failed", async () => {
state = codexOn("jiekou");
keyRef.current = "";
vi.spyOn(api, "models").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "", error_code: null, retryable: false, models: [] });
vi.spyOn(api, "probe").mockResolvedValue({
ok: false, reachable: true, status: 404, message: "Model does not support OpenAI Responses.",
error_code: "PROTOCOL_UNSUPPORTED", retryable: false, convertible: ["responses"],
});
const page = render(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);
expect(screen.getByRole("button", { name: "继续选择模型" })).toBeEnabled();

fireEvent.click(screen.getByRole("button", { name: "测试连接" }));
await waitFor(() => expect(state.connectionState).toBe("error"));
page.rerender(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);

expect(screen.queryByText(SUGGESTION)).toBeNull();
expect(screen.getByRole("alert")).toHaveTextContent("Codex 不能直接使用这个模型服务,BootAgent 可以在本机转换后使用");
expect(screen.getAllByRole("button", { name: "使用兼容模式" })).toHaveLength(1);
expect(screen.getByRole("button", { name: "继续选择模型" })).toBeDisabled();
});

it("drops the suggestion once a connection test passes", async () => {
state = codexOn("jiekou");
keyRef.current = "";
vi.spyOn(api, "models").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "", error_code: null, retryable: false, models: [] });
vi.spyOn(api, "probe").mockResolvedValue({ ok: true, reachable: true, status: 200, message: "ok", error_code: null, retryable: false });
const page = render(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);

fireEvent.click(screen.getByRole("button", { name: "测试连接" }));
await waitFor(() => expect(state.connectionState).toBe("success"));
page.rerender(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);

expect(screen.queryByText(SUGGESTION)).toBeNull();
expect(screen.queryByRole("button", { name: "使用兼容模式" })).toBeNull();
});

// A first-time user has no key saved, so the key is typed on this same step
// and cleared again when Continue saves it. Both used to reset the choice.
it("keeps an untested choice while the key is typed and saved", async () => {
const noKey = {
...tabledStatus,
providers: { jiekou: { ...tabledStatus.providers.jiekou, has_key: false } },
} as unknown as StatusResponse;
state = codexOn("jiekou", { status: noKey });
keyRef.current = "";
const save = vi.spyOn(api, "saveProvider").mockResolvedValue({
entry: { id: "jiekou", name: "JieKou.AI", home: "", base_url: "https://api.jiekou.test/openai", anthropic_base_url: "", api_key: "", built_in: true },
reapplied: [],
failures: {},
});
const page = render(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);

fireEvent.click(screen.getByRole("button", { name: "使用兼容模式" }));
page.rerender(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);
fireEvent.change(screen.getByLabelText("API Key"), { target: { value: "new-key" } });
page.rerender(<MemoryRouter><ProviderKeyPage /></MemoryRouter>);
expect(state.conversion).toBe(true);

fireEvent.click(screen.getByRole("button", { name: "继续选择模型" }));
await waitFor(() => expect(save).toHaveBeenCalledWith(expect.objectContaining({ id: "jiekou", api_key: "new-key" })));
await waitFor(() => expect(keyRef.current).toBe(""));
expect(state.conversion).toBe(true);
});

it("uses a custom model name for the connection test", async () => {
state = { ...baseState, status, statusState: "success", hasApiKey: false };
keyRef.current = "test-key";
Expand Down
25 changes: 23 additions & 2 deletions frontend/src/pages/ProviderKeyPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import { ProviderSegment } from "../components/ProviderSegment";
import { SecureKeyField } from "../components/SecureKeyField";
import { useI18n } from "../i18n";
import { useFeedback } from "../state/FeedbackContext";
import { probeOffersConversion } from "../state/conversion";
import { probeOffersConversion, providerSuggestsConversion } from "../state/conversion";
import { desktopProtocol, profileAgentIdForDesktop, selectedDesktopApp } from "../state/desktopSetup";
import { useWizard } from "../state/WizardContext";
import { wizardNeedsModel } from "../state/wizardReducer";
Expand Down Expand Up @@ -51,10 +51,14 @@ export function ProviderKeyPage() {
// Other desktop apps share another Agent's settings and stay as they are.
const conversionProtocol = protocols.length === 1 && (!desktop || desktop.id === "claude-desktop") ? protocols[0] : undefined;
const conversionOffered = state.connectionState === "error" && probeOffersConversion(state.connection, conversionProtocol);
// Read from the Provider's protocol table, with no request sent. It speaks
// only until a connection test has: a test's verdict replaces the guess.
const conversionSuggested = state.connectionState === "idle" && providerSuggestsConversion(providerMeta, conversionProtocol);
const agentName = desktop?.name || state.status?.catalog.find((item) => item.id === state.selectedAgentIds[0])?.name || "";
// A new key is persisted before continuing; probing remains optional. A test
// that found compatibility mode would help is the exception: continuing past
// it unanswered installs an Agent that fails on its first request.
// it unanswered installs an Agent that fails on its first request. The
// untested suggestion is not: nothing has shown the Provider cannot serve it.
const canContinue = (canProbe || (builtInProvider && state.hasApiKey)) && (!conversionOffered || state.conversion);

const endpoint = useMemo(() => {
Expand Down Expand Up @@ -213,6 +217,23 @@ export function ProviderKeyPage() {
beside the one choice that fixes it. */}
{conversionOffered ? null : <ConnectionStatus state={state.connectionState} result={state.connection} />}
</div>
{conversionSuggested && !state.conversion ? (
<div className="notice notice-info conversion-offer">
<span>
{t("尚未确认 {provider} 支持 {agent} 的请求格式({protocol}),可以改用兼容模式,由 BootAgent 在本机转换", {
provider: providerMeta?.name ?? "",
agent: agentName,
protocol: conversionProtocol ? PROTOCOL_LABELS[conversionProtocol] : "",
})}
</span>
<div className="conversion-offer-actions">
<button className="button button-secondary" type="button" onClick={() => dispatch({ type: "SET_CONVERSION", value: true })}>
<ArrowLeftRight size={15} aria-hidden="true" />
{t("使用兼容模式")}
</button>
</div>
</div>
) : null}
{conversionOffered && !state.conversion ? (
<div className="notice notice-warning conversion-offer" role="alert">
<span>{t("{agent} 不能直接使用这个模型服务,BootAgent 可以在本机转换后使用", { agent: agentName })}</span>
Expand Down
Loading
Loading