feat(providers): 支持 StepFun Plan 与 Step 5 Preview

apps/desktop/electron/main/index.ts

@@ -114,7 +114,6 @@ import { registerWindowIpc } from "./ipc/window-ipc";
 import { registerPullsIpc } from "./ipc/pulls-ipc";
 import { registerAgentIpc } from "./ipc/agent-ipc";
 import { registerIpcHandlers } from "./ipc/register";
-import { VoiceService } from "./voice-service";
 import {
   type WindowLifecycleState,
 } from "./bootstrap/window";
@@ -1247,13 +1246,6 @@ runtimeLifecycle = createRuntimeLifecycle({
 });
 const { bootHostStatus, runtimeArch, bootBackends } = runtimeLifecycle;
 
-// Voice service — created lazily on first use, disposed on quit.
-const voiceService = new VoiceService(
-  dataDir + "/voice-models",
-  () => mainWindow,
-);
-app.once("before-quit", () => voiceService.dispose());
-
 function registerIpc() {
   return registerIpcHandlers({
     traySessions: applicationLifecycle!.traySessions,
@@ -1345,7 +1337,6 @@ function registerIpc() {
     getPluginPanelTheme: () => pluginPanelTheme,
     isDeveloperMode: () => developerMode,
     sendToRenderer,
-    voiceService,
   });
 }
 

apps/desktop/electron/main/ipc/provider-ipc.ts

@@ -338,7 +338,9 @@ export function registerProviderIpc({
           // ModelInfo is catalog metadata. Keep its published reasoning fields
           // intact; Composer and runtime resolve the exact user binding when
           // they need effective per-provider capabilities.
-          ...(modelsDevModel ? { catalogSource: "models.dev" as const } : {}),
+          ...(modelsDevModel
+            ? { catalogSource: modelsDevModel.metadataSource ?? "models.dev" as const }
+            : {}),
         };
       };
 

apps/desktop/electron/main/ipc/register.ts

@@ -32,6 +32,7 @@ import { createComposerTemplateLoader, registerWorkspaceIpc } from "./workspace-
 import { registerComposerIpc } from "./composer-ipc";
 import { registerSpeechIpc } from "./speech-ipc";
 import { registerVoiceIpc } from "./voice-ipc";
+import { createVoiceService } from "../voice-service";
 import type { IpcRegistrar } from "./types";
 import type { createTraySessions } from "../tray-sessions";
 
@@ -154,7 +155,7 @@ export function registerIpcHandlers(dependencies: RegisterIpcDependencies) {
     getPluginPanelTheme,
     isDeveloperMode,
     sendToRenderer,
-    voiceService,
+    voiceService = createVoiceService(dataDir, getMainWindow),
   } = dependencies;
 
 

apps/desktop/electron/main/models-dev-catalog.ts

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
-import { MODEL_VENDOR_PREFIXES, catalogModelIdsMatch, stripVariantSuffix } from "@pi-desktop/shared";
+import { stepfunModelSupplement } from "./stepfun-model-metadata.ts";
+import { MODEL_VENDOR_PREFIXES, catalogModelIdsMatch, modelIdsMatch, stripVariantSuffix } from "@pi-desktop/shared";
 import type {
   ModelCost,
   ModelCostTier,
@@ -54,6 +55,8 @@ export type ModelsDevProvider = {
 };
 
 export type ModelsDevModel = {
+  /** Absent for models.dev; explicit for a reviewed first-party supplement. */
+  metadataSource?: "provider";
   providerKey: string;
   providerName: string;
   providerApi?: string;
@@ -695,7 +698,7 @@ export function modelInfoFromModelsDev(
     capabilities: capabilityList(model),
     supportedThinkingLevels: [...model.thinkingLevels],
     source: "discovered",
-    catalogSource: "models.dev",
+    catalogSource: model.metadataSource ?? "models.dev",
   };
 }
 
@@ -720,7 +723,7 @@ export function modelConfigFromModelsDev(
     ...(model.cost?.tiers ? { tiers: model.cost.tiers } : {}),
   };
   const config: ModelConfig = {
-    source: "models.dev",
+    source: model.metadataSource ?? "models.dev",
     name: model.displayName,
     baseUrl: baseUrl ?? model.providerApi ?? "",
     reasoning,
@@ -1030,12 +1033,17 @@ export class ModelsDevCatalog {
     candidates.sort((left, right) =>
       right.score - left.score || left.model.modelId.length - right.model.modelId.length,
     );
+    const supplement = stepfunModelSupplement(input);
+    const firstParty = supplement && preferred.find(({ model, provider }) =>
+      apiMatches(input.baseUrl, provider.api) && modelIdsMatch(model.modelId, requested),
+    )?.model;
     // An unknown endpoint can use a unique catalog match (including supported
     // proxy aliases), but scores are not proof of provider identity. If two
     // providers publish the same ID, do not borrow either one's metadata.
-    const result = preferredProvider || candidates.length === 1
+    const catalogMatch = preferredProvider || candidates.length === 1
       ? candidates[0]?.model
       : undefined;
+    const result = firstParty ?? supplement ?? catalogMatch;
     // Cache the result (a miss included) so a repeated miss is also O(1) and
     // cannot grow the candidate index with query-dependent keys.
     this.lookupMemo.set(memoKey, result);

apps/desktop/electron/main/stepfun-model-metadata.ts

@@ -0,0 +1,46 @@
+import type { ModelsDevModel } from "./models-dev-catalog";
+
+/**
+ * First-party metadata while models.dev has no StepFun Step 5 record.
+ * https://platform.stepfun.com/docs/zh/guides/models/step-5-preview
+ * Verified 2026-09-21: /v1/models publishes max_input_tokens=1024000,
+ * enable_vision_input=true and reasoning_effort_support_list=low/medium/high.
+ * The documented 64k output ceiling is represented conservatively as 64000.
+ * Never infer gateway capabilities from a model name or vendor label alone.
+ */
+export function stepfunModelSupplement(input: {
+  baseUrl?: string;
+  modelId: string;
+}): ModelsDevModel | undefined {
+  if (input.modelId !== "step-5-preview" || !input.baseUrl) return undefined;
+  let endpoint: URL;
+  try {
+    endpoint = new URL(input.baseUrl);
+  } catch {
+    return undefined;
+  }
+  if (
+    endpoint.origin !== "https://api.stepfun.com" ||
+    !["/v1", "/step_plan/v1"].includes(endpoint.pathname.replace(/\/+$/, "")) ||
+    endpoint.username || endpoint.password || endpoint.search || endpoint.hash
+  ) return undefined;
+  return {
+    providerKey: "stepfun",
+    providerName: "StepFun",
+    providerApi: `${endpoint.origin}${endpoint.pathname.replace(/\/+$/, "")}`,
+    metadataSource: "provider",
+    modelId: "step-5-preview",
+    displayName: "Step 5 Preview",
+    reasoning: true,
+    reasoningPublished: true,
+    thinkingLevels: ["low", "medium", "high"],
+    reasoningOptions: [{ type: "effort", values: ["low", "medium", "high"] }],
+    modalities: { input: ["text", "image", "video"], output: ["text"] },
+    modalitiesPublished: true,
+    inputPublished: true,
+    outputPublished: true,
+    toolCall: true,
+    structuredOutput: true,
+    limit: { context: 1_024_000, input: 1_024_000, output: 64_000 },
+  };
+}

apps/desktop/electron/main/voice-service.ts

@@ -5,7 +5,8 @@
  * means zero import overhead at startup.
  */
 
-import { BrowserWindow } from "electron";
+import { app, BrowserWindow } from "electron";
+import { join } from "node:path";
 import { PvRecorderBackend, checkMicrophonePermission, requestMicrophonePermission } from "./audio-backend";
 import type {
   AudioCaptureFactory,
@@ -171,3 +172,10 @@ export class VoiceService {
     }
   }
 }
+
+/** Create the IPC-owned service and release it when Electron quits. */
+export function createVoiceService(dataDir: string, getWindow: () => BrowserWindow | null): VoiceService {
+  const service = new VoiceService(join(dataDir, "voice-models"), getWindow);
+  app.once("before-quit", () => service.dispose());
+  return service;
+}

apps/desktop/src/features/settings/SettingsPage.tsx

@@ -548,7 +548,7 @@ export function SettingsPage() {
           )}
 
           {tab === "voice" && settings && (
-            <VoiceSettingsSection t={t} />
+            <VoiceSettingsSection t={t} settings={settings} saveSettings={saveSettings} />
           )}
 
           {tab === "shortcuts" && settings && (

apps/desktop/src/features/settings/voice/VoiceSettingsSection.tsx

@@ -4,7 +4,7 @@
 
 import { useCallback, useEffect, useState } from "react";
 import type { TFunction } from "i18next";
-import type { AppSettings } from "@pi-desktop/shared";
+import type { AppSettings, VoiceInputSettings } from "@pi-desktop/shared";
 import { cx } from "../../../components/ui";
 import { SettingsRow, SettingsCard } from "../primitives";
 import { voiceIpc } from "../../voice/voice-ipc";
@@ -70,9 +70,9 @@ export function VoiceSettingsSection({
   }, []);
 
   const save = useCallback(
-    (patch: Record<string, unknown>) => {
+    (patch: Partial<VoiceInputSettings>) => {
       const next = { ...voice, ...patch };
-      void saveSettings({ voice: next as any });
+      void saveSettings({ voice: next });
       void voiceIpc.updateSettings(next);
     },
     [voice, saveSettings],
@@ -158,7 +158,12 @@ export function VoiceSettingsSection({
             className="settings-select"
             value={voice.chineseVariant}
             disabled={!voice.enabled}
-            onChange={(e) => save({ chineseVariant: e.target.value })}
+            onChange={(e) => {
+              const chineseVariant = e.target.value;
+              if (chineseVariant === "simplified" || chineseVariant === "traditional-taiwan" || chineseVariant === "traditional-hong-kong") {
+                save({ chineseVariant });
+              }
+            }}
           >
             <option value="simplified">{t("settings.voiceSimplified")}</option>
             <option value="traditional-taiwan">{t("settings.voiceTraditionalTaiwan")}</option>

apps/desktop/src/styles/voice.css

@@ -29,10 +29,10 @@
   align-items: center;
   justify-content: space-between;
   padding: 6px 12px;
-  border-radius: 8px;
+  border-radius: var(--radius-xs);
   background: var(--color-surface-elevated, #1e1e2e);
   border: 1px solid var(--color-border, #333);
-  font-size: 13px;
+  font-size: var(--text-md);
   gap: 12px;
 }
 
@@ -51,7 +51,7 @@
 .voice-recording-dot {
   width: 8px;
   height: 8px;
-  border-radius: 50%;
+  border-radius: var(--radius-round);
   background: var(--color-danger, #ef4444);
   animation: voice-pulse 1.2s ease-in-out infinite;
 }
@@ -66,7 +66,7 @@
   height: 14px;
   border: 2px solid var(--color-border, #555);
   border-top-color: var(--color-primary, #3b82f6);
-  border-radius: 50%;
+  border-radius: var(--radius-round);
   animation: voice-spin 0.8s linear infinite;
 }
 
@@ -77,22 +77,22 @@
 .voice-volume-bar {
   width: 80px;
   height: 4px;
-  border-radius: 2px;
+  border-radius: var(--radius-full);
   background: var(--color-border, #333);
   overflow: hidden;
 }
 
 .voice-volume-fill {
   height: 100%;
   background: var(--color-primary, #3b82f6);
-  border-radius: 2px;
+  border-radius: var(--radius-full);
   transition: width 100ms ease-out;
 }
 
 .voice-cancel-btn {
   padding: 2px 8px;
-  border-radius: 4px;
-  font-size: 12px;
+  border-radius: var(--radius-3xs);
+  font-size: var(--text-sm);
   background: transparent;
   color: var(--color-text-secondary, #999);
   border: 1px solid var(--color-border, #444);

apps/desktop/test/packaging-footprint.test.mjs

@@ -284,7 +284,7 @@ test("macOS DMG is a two-icon install; ZIP keeps the unsigned helper", () => {
 
 test("packaging does not include removed PTY native payload configuration", () => {
   assert.deepEqual(packageJson.build.asar, { smartUnpack: false });
-  assert.equal(packageJson.build.asarUnpack, undefined);
+  assert.doesNotMatch(JSON.stringify(packageJson.build.asarUnpack ?? []), /node-pty/);
   assert.doesNotMatch(JSON.stringify(packageJson.build.files), /node-pty/);
   assert.doesNotMatch(JSON.stringify(packageJson.build.extraResources), /node-pty/);
 });

apps/desktop/test/session-message-presentation.test.mjs

@@ -23,6 +23,7 @@ const shared = {
   FileRefChip: () => null,
   LinkifiedText: ({ text }) => text,
   MessageAttachmentImage: () => null,
+  MessageTimestamp: () => null,
 };
 
 function loadComponent(name, extras = {}) {

docs/adr/0134-models-dev-sole-model-metadata-source.md

@@ -1,6 +1,6 @@
 # ADR 0134: Use models.dev as the sole model metadata source with a local snapshot
 
-- Status: Accepted
+- Status: Accepted; amended by [StepFun first-party metadata](stepfun-first-party-model-metadata.md)
 - Date: 2026-08-29
 - Deciders: PI-Desktop core
 - Amends: ADR 0027, ADR 0133, D136, D266
@@ -22,7 +22,9 @@ cost tiers. Those fields need one stable owner and a local offline snapshot.
 
 ## Decision
 
-`https://models.dev/api.json` is the only model metadata/configuration source.
+`https://models.dev/api.json` is the general model metadata/configuration source.
+The StepFun amendment defines a source-labelled, exact-endpoint exception for
+`step-5-preview` until its first-party record is available.
 
 1. Electron main reads the bundled public document from
    `resources/models.dev/api.json` in development and

docs/adr/README.md

@@ -340,4 +340,6 @@ Each ADR includes:
 | provider-display-order | [Provider display order](provider-display-order.md) | Accepted |
 | registry-header-variable-spelling | [Remote header variables accept the registry's `{name}` spelling](registry-header-variable-spelling.md) | Proposed |
 | provider-system-certificates | [Desktop sidecar uses OS-trusted certificates](provider-system-certificates.md) | Accepted |
+| stepfun-first-party-model-metadata | [First-party StepFun metadata for a newly released model](stepfun-first-party-model-metadata.md) | Accepted (amends ADR 0134) |
+
 | image-generation-capability | [Image generation as a configured Agent capability](image-generation-capability.md) | Accepted |

docs/adr/stepfun-first-party-model-metadata.md

@@ -0,0 +1,62 @@
+# ADR: First-party StepFun metadata for a newly released model
+
+- Status: Accepted
+- Date: 2026-09-21
+- Amends: ADR 0134
+- Related: issue #738
+
+## Context
+
+StepFun serves `step-5-preview` through its authenticated model-list API, but
+models.dev has no record for that model under the first-party StepFun provider.
+Its aggregator records disagree on reasoning, tool support and output limits.
+Falling across providers can therefore misconfigure a real, runnable model.
+The StepFun API publishes a 1,024,000-token input window and low/medium/high
+reasoning; its official model guide documents vision, tools and 64k output.
+
+## Decision
+
+Keep models.dev as the general catalog. Introduce one reviewed, source-labelled
+supplement for exactly `step-5-preview` at `https://api.stepfun.com/v1`
+and the official Step Plan endpoint `https://api.stepfun.com/step_plan/v1`.
+The supplement lives in a separate pure module in Electron main. A first-party
+models.dev record for the same endpoint/model takes precedence as soon as it
+exists; otherwise the supplement precedes cross-provider matches. It is also
+available when the bundled catalog cannot load. No network fetch is added to
+runtime startup or model lookup.
+
+Metadata carries `provider` provenance, never falsely `models.dev`. The existing
+optional model-info catalog-source field and internal runtime source union
+accept this additive value. Existing consumers and stored bindings need no
+migration. Lookup still goes through the same settings/session/subagent path;
+explicit binding overrides remain authoritative.
+
+Only exact HTTPS origin and version path matches qualify. Custom gateways,
+lookalike hosts and other model IDs retain their
+existing behavior. Live discovery remains the authority on availability: the
+supplement does not insert a model into an endpoint's response or claim that
+an API key has access. Video capability metadata does not add video attachment
+transport to the desktop app.
+
+## Alternatives
+
+- Wait for models.dev: leaves a publicly available model misconfigured.
+- Copy a reseller record: repeats inaccurate limits and capabilities.
+- Modify the bundled models.dev document: falsely attributes vendor data to
+  models.dev and loses the change on catalog refresh.
+- Introduce a broad parallel model catalog: unnecessary scope and maintenance.
+
+## Consequences
+
+The exception is narrow and removable once first-party catalog coverage is
+stable. Its source must be rechecked when StepFun changes the model. The 64k
+output ceiling is conservatively represented as 64,000 tokens; no unverified
+pricing is supplied. Existing source values, protocols, persistence and secret
+ownership remain unchanged.
+
+## References
+
+- [Step 5 Preview guide](https://platform.stepfun.com/docs/zh/guides/models/step-5-preview)
+- `GET https://api.stepfun.com/v1/models` (verified 2026-09-21; no credentials
+  or account data are retained in repository fixtures)
+- `apps/desktop/electron/main/stepfun-model-metadata.ts`

docs/guide/index.md

@@ -60,3 +60,7 @@ number; use the sidebar when you are exploring a domain.
 See the [AI development workflow](/spec/06-delivery/03-ai-development-workflow)
 and [change checklist](/spec/06-delivery/05-change-checklist) for the complete
 repository rules.
+
+## StepFun
+
+See [StepFun Step 5 Preview setup](stepfun.md).