@dsh-ft/dsh-fft-settings 0.0.0-stage → 0.5.0

package/src/default-preset.ts

@@ -0,0 +1,151 @@
+/**
+ * Claim the finance preset as the default once per installation.
+ *
+ * The bundle patch already carries `default: ft-finance` on the preset
+ * registry row, which decides every session on a machine that never chose a
+ * default. A machine whose user *did* choose one keeps that choice, because
+ * `selectedDefault` outranks `default` — this module overrides it exactly once,
+ * then records the claim so a later user choice is never touched again.
+ *
+ * The write goes through the settings service, the same path the settings page
+ * uses: only volatile fields are writable there, so the patch this module hands
+ * over carries `selectedDefault` and nothing else. The row it lands in is wider
+ * than that patch — the service writes the effective config's non-volatile keys
+ * alongside the volatile change, so `default: ft-finance` is copied into the
+ * profile row too. Because it is still the one change this plugin ever makes to
+ * the user's own profile patch, the file is copied into this plugin's data
+ * directory first, and a claim without that copy never happens.
+ * @module @dsh-ft/dsh-fft-settings/default-preset
+ */
+
+import { existsSync } from 'node:fs'
+import { copyFile, mkdir, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { resolveDshHome } from './features/logs/home.js'
+
+/** The preset this bundle wants as the default. */
+export const DEFAULT_PRESET_ID = 'ft-finance'
+
+/** Id of the profile entry that owns the preset registry's config. */
+export const REGISTRY_ENTRY_ID = 'agent-preset-registry'
+
+/** Data directory this plugin owns under the DSH home. */
+export const DATA_DIR_NAME = '.dsh-fft-settings'
+
+/** File whose presence means the claim already happened on this machine. */
+export const CLAIM_FILE_NAME = 'default-preset.json'
+
+/** Snapshot of the profile patch, taken before this module's single write. */
+export const BACKUP_FILE_NAME = 'cordis.patch.yml.bak'
+
+/** The registry's two calls this module makes, declared structurally so the package keeps no harness dependency. */
+interface PresetRegistry {
+  /** Effective default preset id for a new session. */
+  readonly defaultId: string
+  /** Every registered preset. */
+  list(): Promise<readonly { readonly id: string }[]>
+}
+
+/** The settings service's single write this module makes. */
+interface SettingsWriter {
+  update(ns: string, patch: Record<string, unknown>, expectedRevision?: number): Promise<void>
+}
+
+/** The boot context that owns the profile patch the settings write lands in. */
+interface ProfileContext {
+  /** Path of the profile's own `cordis.patch.yml`. */
+  readonly patchPath: string
+}
+
+/**
+ * Record that this installation claimed the default, once.
+ * @param home - the DSH home the plugin writes its own data into.
+ * @returns the claim file path.
+ */
+export function claimFilePath(home = resolveDshHome()): string {
+  return join(home, DATA_DIR_NAME, CLAIM_FILE_NAME)
+}
+
+/**
+ * Snapshot path for the profile patch.
+ * @param home - the DSH home the plugin writes its own data into.
+ * @returns the snapshot file path.
+ */
+export function backupFilePath(home = resolveDshHome()): string {
+  return join(home, DATA_DIR_NAME, BACKUP_FILE_NAME)
+}
+
+/**
+ * Make `ft-finance` the default unless this machine already made a claim.
+ *
+ * Every step that cannot complete skips silently and retries on the next start:
+ * a missing registry or settings service, a preset that is not registered yet,
+ * and a failed write all leave no claim file behind. Nothing here may fail the
+ * plugin's activation.
+ * @param ctx - the plugin's host context.
+ */
+export function installDefaultPresetOnce(ctx: Context): void {
+  ctx.inject(['settings', 'agentPresets'], (scope) => {
+    const registry = scope.get('agentPresets') as PresetRegistry | undefined
+    const settings = scope.get('settings') as SettingsWriter | undefined
+    if (registry === undefined || settings === undefined) return
+    const profile = scope.get('profileContext') as ProfileContext | undefined
+    void claimDefaultPreset(registry, settings, profile, ctx)
+      .catch((error: unknown) => {
+        ctx.logger.warn('dsh-fft-settings: could not claim the default preset', error)
+      })
+  })
+}
+
+/**
+ * Perform the one-time claim, snapshotting the file it is about to change.
+ * @param registry - the live preset registry.
+ * @param settings - the settings writer.
+ * @param profile - the profile context, absent in a context that has no patch file.
+ * @param ctx - the plugin context, used for the claim log line.
+ */
+async function claimDefaultPreset(
+  registry: PresetRegistry,
+  settings: SettingsWriter,
+  profile: ProfileContext | undefined,
+  ctx: Context,
+): Promise<void> {
+  const file = claimFilePath()
+  if (existsSync(file)) return
+  // An unregistered preset would pin an id that resolves to nothing, so the
+  // claim waits for the composition that defines it.
+  const presets = await registry.list()
+  if (!presets.some(preset => preset.id === DEFAULT_PRESET_ID)) return
+  let backup: string | undefined
+  if (registry.defaultId !== DEFAULT_PRESET_ID) {
+    // Insurance first: the editor writes atomically and rolls back a failed
+    // reconcile, but this write still lands in the user's own profile patch, so
+    // a claim is only recorded once the snapshot exists.
+    if (profile !== undefined) backup = await snapshotProfilePatch(profile.patchPath)
+    await settings.update(REGISTRY_ENTRY_ID, { selectedDefault: DEFAULT_PRESET_ID })
+    ctx.logger.info(`dsh-fft-settings: ${DEFAULT_PRESET_ID} is now the default preset`)
+  }
+  await mkdir(dirname(file), { recursive: true })
+  const claim = { preset: DEFAULT_PRESET_ID, at: new Date().toISOString(), ...(backup === undefined ? {} : { backup }) }
+  await writeFile(file, `${JSON.stringify(claim, null, 2)}\n`)
+}
+
+/**
+ * Copy the profile patch into this plugin's data directory, once.
+ *
+ * A failed copy throws, and the caller aborts the claim: the write must not
+ * happen without its snapshot. The first copy wins, so a retry after a failed
+ * write still holds the state from before the very first attempt. A missing
+ * patch file — a profile that never wrote anything — needs no copy.
+ * @param patchPath - the profile's own `cordis.patch.yml`.
+ * @returns the snapshot path, or `undefined` when there was nothing to copy.
+ */
+async function snapshotProfilePatch(patchPath: string): Promise<string | undefined> {
+  if (!existsSync(patchPath)) return undefined
+  const snapshot = backupFilePath()
+  if (existsSync(snapshot)) return snapshot
+  await mkdir(dirname(snapshot), { recursive: true })
+  await copyFile(patchPath, snapshot)
+  return snapshot
+}

package/src/features/api-key/card.tsx

@@ -0,0 +1,77 @@
+import { useEffect, useMemo, useState, useSyncExternalStore, type ReactNode } from 'react'
+import { FTSHARE_API_KEY_REF, FTSHARE_CREDENTIAL_EVENTS, type SubscribeChanges, type ApiKeyPublicApi } from './contract.js'
+import { FTSHARE_SETTINGS_CARD_SLOT } from '../../core/contract.js'
+import { FtshareSettingsModel } from './model.js'
+import { createApiKeyClient } from './client-api.js'
+import { createSettingsTransport } from '../../core/client-transport.js'
+import type { FtshareSettingsShellContext } from '../../core/shell.js'
+import { API_KEY_CARD_CSS } from './styles.js'
+
+/**
+ * Browser context this card requires: the shell's slots service plus the
+ * invalidations that make a cached credential status stale.
+ */
+export interface ApiKeyCardContext extends FtshareSettingsShellContext {
+  remote: { $on(event: string, listener: (ref: string) => void): () => void }
+  on(event: 'connection/reset', listener: () => void): () => void
+}
+
+/**
+ * Contribute the built-in API Key card through the same slot a third-party
+ * card uses. Nothing about it is privileged: same declaration, same options.
+ * @param ctx - client context carrying the renderer's slots service.
+ * @returns idempotent disposer for the card registration.
+ */
+export function registerApiKeyCard(ctx: ApiKeyCardContext): () => void {
+  return ctx.slots.inject(FTSHARE_SETTINGS_CARD_SLOT, () => ctx.slots.register(
+    { name: FTSHARE_SETTINGS_CARD_SLOT, id: 'apiKey', order: 10 },
+    createApiKeyCard(ctx),
+  ))
+}
+
+/** Bind the card's adapters; subscriptions are acquired in the component's effect. */
+function createApiKeyCard(ctx: ApiKeyCardContext): () => ReactNode {
+  const api = createApiKeyClient(createSettingsTransport())
+  const subscribeChanges: SubscribeChanges = listener => {
+    const disposers = FTSHARE_CREDENTIAL_EVENTS.map(event => ctx.remote.$on(event, ref => { if (ref === FTSHARE_API_KEY_REF) listener() }))
+    disposers.push(ctx.on('connection/reset', listener))
+    return () => { for (const dispose of disposers) dispose() }
+  }
+  return () => <ApiKeyCard api={api} subscribeChanges={subscribeChanges} />
+}
+
+export function ApiKeyCard({ api, subscribeChanges }: { readonly api: ApiKeyPublicApi; readonly subscribeChanges?: SubscribeChanges }): ReactNode {
+  const model = useMemo(() => new FtshareSettingsModel(api), [api])
+  const { status, busy, message, statusError, save } = useSyncExternalStore(model.subscribe, model.getSnapshot, model.getSnapshot)
+  const [draft, setDraft] = useState('')
+  useEffect(() => model.connect(subscribeChanges), [model, subscribeChanges])
+  const disabled = busy || !status?.writable
+  const configure = async () => { if (await model.configureAndTest(draft)) setDraft('') }
+  return <>
+    <style>{API_KEY_CARD_CSS}</style>
+    <section className="ftshare-settings" aria-label="FTShare 设置" aria-busy={busy}>
+    <header><div><span className="ftshare-eyebrow">FTSHARE / API KEY</span><h2>访问凭据</h2></div></header>
+    <p>目前集成 FTShare 数据源。</p>
+    {status && !status.writable && <p>当前来源为只读，可测试连接；修改密钥请到对应来源操作。</p>}
+    <div className="ftshare-card"><label htmlFor="ftshare-api-key">FTShare API Key</label>
+      <input id="ftshare-api-key" type="password" value={draft} placeholder={status?.configured ? status.maskedValue ?? '••••••••' : '请输入 API Key'} onChange={e => setDraft(e.target.value)} disabled={disabled} autoComplete="new-password" maxLength={512} />
+      <div className="ftshare-actions">
+        <button className="primary" type="button" onClick={() => void configure()} disabled={disabled || !draft.trim()}>配置并测试</button>
+        <button type="button" onClick={() => void model.testConnection()} disabled={busy || !status}>测试当前连接</button>
+        <button type="button" onClick={() => void model.clear()} disabled={disabled || !status?.configured}>清除已保存密钥</button>
+        <button type="button" onClick={() => void model.refresh()} disabled={busy} title="重新读取已保存的配置和上次检测结果，不会发起联网检测">重新读取状态</button>
+        <a href="https://ftai.chat/me/profile?tab=api-key" target="_blank" rel="noreferrer">获取 API Key ↗</a>
+      </div>
+      {draft && <small>“测试当前连接”使用已生效的密钥，不测试输入框内尚未保存的内容。</small>}
+      {busy && <p role="status">正在处理，请稍候…</p>}
+    </div>
+    <div className="ftshare-card" aria-live="polite"><h3>验证结果</h3><dl>
+      {save && <div className="ftshare-result"><dt>本次保存</dt><dd>{save.message}</dd></div>}
+      <div className="ftshare-result"><dt>远端服务</dt><dd>{status?.validation.remote.message ?? '状态待确认'}</dd></div>
+      <div className="ftshare-result"><dt>API Key</dt><dd>{status?.validation.apiKey.message ?? '状态待确认'}</dd></div>
+      {status?.validation.testedAt && <div className="ftshare-result"><dt>测试时间</dt><dd>{new Date(status.validation.testedAt).toLocaleString()}</dd></div>}
+    </dl><small>节假日或收盘后的空数据不影响验证。</small></div>
+    {message && <p role="status">{message}</p>}{statusError && <p className="ftshare-error" role="alert">{statusError}</p>}
+    </section>
+  </>
+}

package/src/features/api-key/client-api.ts

@@ -0,0 +1,12 @@
+import type { ApiKeyPublicApi, ApiKeyMethod } from './contract.js'
+import { callSettingsRpc, type ClientTransport } from '../../core/rpc-core.js'
+/** Browser adapter deliberately has no resolve/createEnvironment method. */
+export function createApiKeyClient(transport: ClientTransport): ApiKeyPublicApi {
+  async function call<T>(method: ApiKeyMethod, payload: unknown = {}): Promise<T> {
+    return callSettingsRpc<T>(transport, 'apiKey', method, payload)
+  }
+  return {
+    describe: () => call('describe'), set: value => call('set', { value }), clear: () => call('clear'),
+    configureAndTest: value => call('configureAndTest', { value }), testConnection: () => call('testConnection'), getValidationStatus: () => call('getValidationStatus'),
+  }
+}

package/src/features/api-key/contract.ts

@@ -0,0 +1,63 @@
+/**
+ * API Key namespace contract: the credential reference and lifecycle events,
+ * the status/validation vocabulary, and the two faces the namespace exposes
+ * (the browser-safe subset and the host-only superset).
+ *
+ * It merges its own line into the generic {@link FtshareSettingsNamespaces}
+ * merge point, so `ctx.ftshareSettings.apiKey` keeps its existing type for
+ * every consumer.
+ */
+export const FTSHARE_API_KEY_REF = 'FTSHARE_API_KEY' as const
+export const FTSHARE_CREDENTIAL_EVENTS = ['credentials/reference-updated'] as const
+export const API_KEY_METHODS = ['describe', 'set', 'clear', 'configureAndTest', 'testConnection', 'getValidationStatus'] as const
+export type ApiKeyMethod = typeof API_KEY_METHODS[number]
+export type SubscribeChanges = (listener: () => void) => () => void
+export interface CredentialStatus { configured: boolean; writable: boolean; source?: string }
+export type ProbeState = 'available' | 'auth_required' | 'auth_failed' | 'permission_denied' | 'quota_exceeded' | 'rate_limited' | 'network_error' | 'timeout' | 'upstream_error' | 'invalid_response' | 'not_run'
+export interface ProbeResult { status: ProbeState; message: string }
+export interface ValidationResult {
+  status: 'not_tested' | 'not_run' | 'passed' | 'partial' | 'failed' | 'superseded'
+  remote: ProbeResult
+  apiKey: ProbeResult
+  testedAt?: string
+}
+export interface ApiKeyStatus extends CredentialStatus {
+  /** Display only. Fixed mask plus last four characters; never submit as a Key. */
+  maskedValue?: string
+  revision: number
+  validation: ValidationResult
+}
+export interface ConfigureResult {
+  save: { status: 'saved' | 'failed'; code?: 'invalid_input' | 'read_only' | 'save_failed'; message: string }
+  validation: ValidationResult
+}
+/** Local syntax validation, never an assertion of upstream validity. */
+export function normalizeApiKey(input: string): string {
+  const value = input.trim()
+  if (!value) throw new Error('请输入 API Key')
+  if (value.length > 512 || /[\x00-\x1f\x7f]/.test(value)) throw new Error('API Key 长度不能超过 512 个字符，且不能包含控制字符')
+  return value
+}
+export function untested(status: 'not_tested' | 'not_run' | 'superseded' = 'not_tested', message = '尚未测试'): ValidationResult {
+  return { status, remote: { status: 'not_run', message }, apiKey: { status: 'not_run', message } }
+}
+/** Everything the browser adapter may call; `resolve`/`createEnvironment` are not here. */
+export interface ApiKeyPublicApi {
+  describe(): Promise<ApiKeyStatus>
+  set(value: string): Promise<void>
+  clear(): Promise<void>
+  configureAndTest(value: string): Promise<ConfigureResult>
+  testConnection(): Promise<ValidationResult>
+  getValidationStatus(): Promise<ValidationResult>
+}
+/** The host namespace object: the public API plus the secret-bearing host methods. */
+export interface ApiKeySettings extends ApiKeyPublicApi {
+  readonly credentialRef: typeof FTSHARE_API_KEY_REF
+  /** Host only. Re-resolve per operation; never send this value to browsers. */
+  resolve(): Promise<string | undefined>
+  createEnvironment(base?: Readonly<Record<string, string | undefined>>): Promise<Record<string, string | undefined>>
+  subscribe: SubscribeChanges
+}
+declare module '../../core/contract.js' {
+  interface FtshareSettingsNamespaces { apiKey: ApiKeySettings }
+}

package/src/features/api-key/host.ts

@@ -0,0 +1,36 @@
+import { credentialRef, type CredentialRef } from '@deepseek-ai/dsh-credentials'
+import { FTSHARE_API_KEY_REF, FTSHARE_CREDENTIAL_EVENTS, type ApiKeySettings } from './contract.js'
+import type { FeatureLogger } from './logging.js'
+import { createApiKeySettings } from './service.js'
+import { defineSettingsModule } from '../../core/module-registry.js'
+import { createApiKeyRpcMethods } from './rpc.js'
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    'credentials/reference-updated'(ref: CredentialRef): void
+  }
+}
+/**
+ * Build the `apiKey` module, closing over the plugin's named logger.
+ *
+ * 工厂化与 `createLogsModule` 一致：插件入口在 `apply` 里取一次 `ctx.logger()`
+ * （无参 = 插件名）再传进来，因此 feature 不依赖模块级单例，也不认识 cordis。
+ * @param logger - 可选具名 logger；省略时本模块不写任何日志（既有调用方不变）。
+ * @returns 可交给 `ctx.ftshareSettings.modules.register` 的模块。
+ */
+export function createApiKeyModule(logger?: FeatureLogger) {
+  return defineSettingsModule<'apiKey', ApiKeySettings>({
+    namespace: 'apiKey', inject: ['credentials'],
+    create(ctx) {
+      const ref = credentialRef(FTSHARE_API_KEY_REF)
+      const owner = createApiKeySettings({
+        resolve: async () => (await ctx.credentials.resolve(ref))?.value,
+        describe: () => ctx.credentials.describe(ref),
+        set: value => ctx.credentials.set(ref, value),
+        clear: () => ctx.credentials.unset(ref),
+      }, undefined, logger)
+      for (const event of FTSHARE_CREDENTIAL_EVENTS) ctx.on(event, changed => { if (changed === ref) owner.invalidate() })
+      ctx.effect(() => () => owner.dispose(), 'ftshare-settings: API key lifecycle')
+      return { service: owner.api, rpcMethods: createApiKeyRpcMethods(owner.api) }
+    },
+  })
+}

package/src/features/api-key/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Host half of the API Key feature: the entry a host assembly imports.
+ *
+ * The directory is written to be liftable into its own package (§10.4): this
+ * file is the host entry, `./contract.js` its contract, and `./card.js` the
+ * browser entry that browser code imports directly instead of going through
+ * here (a browser half must never pull credential or probe code).
+ */
+export * from './contract.js'
+export { createApiKeyModule } from './host.js'
+export type { FeatureLogger } from './logging.js'
+export { createApiKeySettings, type CredentialStore, type Validator } from './service.js'
+export { createApiKeyRpcMethods, createApiKeyRpcHandler } from './rpc.js'

package/src/features/api-key/logging.ts

@@ -0,0 +1,15 @@
+/**
+ * 本 feature 写日志用的最小接口（规格 §6/§7：失败不低于 `warn`，可变值放字段）。
+ *
+ * 只声明用得到的 `warn`，因此 cordis 的具名 logger（`ctx.logger()` 无参 = 插件名）
+ * 可以结构化地传进来，而单元测试直接构造 service 时不传 logger 也就保持静默——
+ * 日志是**可选依赖**，不是必需接线。
+ *
+ * 约定：
+ * - 第二参数字段化，绝不放 API Key/token 的值；
+ * - 消息文本保持稳定（采集器按 `(插件, 级别, 消息, 稳定字段)` 在 10 秒窗口内合并）；
+ * - 失败级别不低于 `warn`，不用 `debug`。
+ */
+export interface FeatureLogger {
+  warn(message: string, fields?: Record<string, unknown>): void
+}

package/src/features/api-key/model.ts

@@ -0,0 +1,63 @@
+import { normalizeApiKey, type ApiKeyPublicApi, type ApiKeyStatus, type ConfigureResult, type SubscribeChanges } from './contract.js'
+export interface SettingsState { status?: ApiKeyStatus; busy: boolean; message: string; statusError?: string; save?: ConfigureResult['save'] }
+export class FtshareSettingsModel {
+  private state: SettingsState = { busy: false, message: '' }
+  private listeners = new Set<() => void>()
+  private request = 0
+  private lifetime = 0
+  constructor(private api: ApiKeyPublicApi) {}
+  getSnapshot = (): SettingsState => this.state
+  subscribe = (listener: () => void): (() => void) => { this.listeners.add(listener); return () => { this.listeners.delete(listener) } }
+  private update(patch: Partial<SettingsState>): void { this.state = { ...this.state, ...patch }; for (const listener of this.listeners) listener() }
+  connect(subscribe?: SubscribeChanges): () => void {
+    const dispose = subscribe?.(() => { void this.refresh() })
+    void this.refresh()
+    return () => { this.request++; this.lifetime++; dispose?.() }
+  }
+  async refresh(): Promise<void> {
+    const request = ++this.request
+    try {
+      const status = await this.api.describe()
+      if (!status || typeof status.configured !== 'boolean') throw new Error('missing_status')
+      if (request === this.request) this.update({ status, statusError: undefined })
+    } catch { if (request === this.request) this.update({ status: undefined, statusError: '无法读取设置状态，请刷新重试' }) }
+  }
+  async configureAndTest(input: string): Promise<boolean> {
+    if (this.state.busy || !this.state.status?.writable) return false
+    let value: string
+    try { value = normalizeApiKey(input) } catch (error) { this.update({ message: (error as Error).message }); return false }
+    const lifetime = this.lifetime
+    this.update({ busy: true, save: undefined, message: '正在保存并检查远端服务和 API Key…' })
+    let saved = false
+    try {
+      const result = await this.api.configureAndTest(value)
+      saved = result.save.status === 'saved'
+      if (lifetime === this.lifetime) this.update({ save: result.save, message: saved ? validationMessage(result.validation.status) : result.save.message })
+    } catch { if (lifetime === this.lifetime) this.update({ message: '请求未完成，保存状态待确认；请刷新后测试当前连接' }) }
+    if (lifetime === this.lifetime) { await this.refresh(); this.update({ busy: false }) }
+    return saved
+  }
+  async testConnection(): Promise<void> {
+    if (this.state.busy || !this.state.status) return
+    const lifetime = this.lifetime
+    this.update({ busy: true, message: '正在检查远端服务和当前 API Key…' })
+    try {
+      const result = await this.api.testConnection()
+      if (lifetime === this.lifetime) this.update({ message: validationMessage(result.status) })
+    } catch { if (lifetime === this.lifetime) this.update({ message: '测试请求失败，请重试' }) }
+    if (lifetime === this.lifetime) { await this.refresh(); this.update({ busy: false }) }
+  }
+  async clear(): Promise<void> {
+    if (this.state.busy || !this.state.status?.writable) return
+    const lifetime = this.lifetime
+    this.update({ busy: true, save: undefined, message: '' })
+    try {
+      await this.api.clear()
+      if (lifetime === this.lifetime) this.update({ message: '已清除 DSH 保存的密钥；若有 .env 配置，下方显示其有效状态' })
+    } catch { if (lifetime === this.lifetime) this.update({ message: '清除失败，请刷新状态后重试' }) }
+    if (lifetime === this.lifetime) { await this.refresh(); this.update({ busy: false }) }
+  }
+}
+function validationMessage(status: string): string {
+  return ({ passed: '远端服务正常，API Key 验证通过', partial: '远端服务正常，请查看 API Key 检查结果', failed: '测试未通过，请查看分项结果', not_run: '未执行测试，请先确认凭据配置', superseded: '凭据已变化，请重新测试', not_tested: '尚未测试' } as Record<string, string>)[status] ?? '请查看分项结果'
+}

package/src/features/api-key/probe.ts

@@ -0,0 +1,116 @@
+import { type ProbeResult, type ValidationResult } from './contract.js'
+import type { FeatureLogger } from './logging.js'
+
+const ORIGIN = 'https://market.ft.tech/gateway/'
+const MAX_RESPONSE_BYTES = 128 * 1024
+const DAY = 86_400_000
+export const PROBE_TIMEOUT_MS = 8_000
+export const PROBE_CONTRACTS = {
+  daily: 'api/v1/market/data/stock-candlesticks',
+  historicalMinute: 'api/v2/market/data/stock_minutes',
+} as const
+const result = (status: ProbeResult['status'], message: string): ProbeResult => ({ status, message })
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v)
+
+/** Error text is classified internally and never returned verbatim. */
+export function classifyFailure(code: number, text: string): ProbeResult {
+  if (code === 400 || code === 422) return result('invalid_response', `检测请求参数被 FTShare 拒绝（错误码 ${code}），请更新插件；这不代表 Key 无效`)
+  if (code === 429) return result('rate_limited', '请求受限，请稍后重试')
+  if (code >= 500) return result('upstream_error', 'FTShare 服务暂时不可用')
+  if (code === 401 || code === 403) {
+    if (/quota|额度|配额/i.test(text)) return result('quota_exceeded', '接口额度不足，无法完成 Key 验证')
+    if (/permission|权限|订阅|套餐|upgrade|plan/i.test(text)) return result('permission_denied', '接口权限不足，无法完成 Key 验证')
+    if (/missing|required|未携带|缺少/i.test(text)) return result('auth_required', 'FTShare 未收到所需凭据')
+    if (code === 403 && !/invalid|expired|malformed|无效|过期/i.test(text)) return result('permission_denied', '请求被拒绝，请检查 Key 或接口权限')
+    return result('auth_failed', 'API Key 未通过认证')
+  }
+  return result('invalid_response', `检测接口返回未识别的错误（错误码 ${code}），未能完成检测`)
+}
+
+async function readBoundedJson(response: Response): Promise<unknown> {
+  if (!response.body) throw new Error('empty_body')
+  const reader = response.body.getReader()
+  let size = 0
+  const chunks: Uint8Array[] = []
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      size += value.byteLength
+      if (size > MAX_RESPONSE_BYTES) { await reader.cancel(); throw new Error('oversized_body') }
+      chunks.push(value)
+    }
+  } finally { reader.releaseLock() }
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength }
+  return JSON.parse(new TextDecoder().decode(bytes))
+}
+
+/**
+ * 一次固定探测。失败（发出过请求且没有通过）写一条 `warn`：
+ * 字段固定 `{ target, status, durationMs }` —— `target` 由是否携带 Key 决定；
+ * 未发请求的 `not_run` 不是探测失败，成功也不记（规格 §6/§7）。
+ */
+async function probe(path: string, params: Record<string, string>, key: string | undefined, parent: AbortSignal, fetcher: typeof fetch, now: number, logger?: FeatureLogger): Promise<ProbeResult> {
+  const url = new URL(path, ORIGIN)
+  url.search = new URLSearchParams(params).toString()
+  const timeout = AbortSignal.timeout(PROBE_TIMEOUT_MS)
+  const signal = AbortSignal.any([parent, timeout])
+  const started = Date.now()
+  const finish = (outcome: ProbeResult): ProbeResult => {
+    if (outcome.status !== 'available' && outcome.status !== 'not_run') {
+      logger?.warn('FTShare 探测未通过', { target: key === undefined ? 'remote' : 'apiKey', status: outcome.status, durationMs: Date.now() - started })
+    }
+    return outcome
+  }
+  try {
+    // Never forward a credential across a redirect.
+    const headers: Record<string, string> = { Accept: 'application/json' }
+    if (key !== undefined) headers.FTSHARE_API_KEY = key
+    const failure = (code: number, text: string) => key === undefined && (code === 401 || code === 403)
+      ? result('upstream_error', '远端服务拒绝了连通性检查') : classifyFailure(code, text)
+    const response = await fetcher(url, { headers, redirect: 'error', signal })
+    let payload: unknown
+    try { payload = await readBoundedJson(response) } catch (error) {
+      if (signal.aborted) throw error
+      if (!response.ok) return finish(failure(response.status, ''))
+      return finish(result('invalid_response', '接口未返回有效 JSON 数据'))
+    }
+    const text = isRecord(payload) ? String(payload.message ?? payload.msg ?? '') : ''
+    if (!response.ok) return finish(failure(response.status, text))
+    if (!isRecord(payload) || typeof payload.code !== 'number') return finish(result('invalid_response', '接口响应格式异常'))
+    if (payload.code !== 200) return finish(failure(payload.code, text))
+    if (!Array.isArray(payload.data)) return finish(result('invalid_response', '接口未返回 K 线数组'))
+    // This checks service/authentication success, not market-data availability.
+    // Empty holiday or post-close windows are successful responses too.
+    return finish(result('available', key === undefined ? '远端服务正常' : 'API Key 验证通过'))
+  } catch {
+    if (parent.aborted) return finish(result('not_run', '测试已取消或凭据已变化'))
+    if (timeout.aborted) return finish(result('timeout', '连接超时，请稍后重试'))
+    return finish(result('network_error', '连接失败，请检查网络后重试'))
+  }
+}
+
+/** Two fixed, bounded requests. No SDK, arbitrary URL, retries or stored rows. */
+export async function probeApiKey(key: string | undefined, signal: AbortSignal, fetcher: typeof fetch = fetch, now: number = Date.now(), logger?: FeatureLogger): Promise<ValidationResult> {
+  const remote = await probe(PROBE_CONTRACTS.daily, {
+    symbol: '600519.SH', interval_unit: 'day', adjust_kind: 'none',
+    since_ts_millis: String(now - 30 * DAY), until_ts_millis: String(now), limit: '2',
+  }, undefined, signal, fetcher, now, logger)
+  let apiKey: ProbeResult
+  if (!key) {
+    apiKey = result('auth_required', '未配置 API Key')
+  } else if (signal.aborted || remote.status !== 'available') {
+    apiKey = result('not_run', '远端服务检查未通过，未验证 Key')
+  } else {
+    // The server counts inclusive Beijing calendar dates, not elapsed days.
+    // A 24-hour window covers at most two dates; empty data still verifies auth.
+    apiKey = await probe(PROBE_CONTRACTS.historicalMinute, {
+      symbol: '600519.SH', interval_value: '1', adjust_kind: 'none',
+      since_ts_millis: String(now - DAY), until_ts_millis: String(now), limit: '1',
+    }, key, signal, fetcher, now, logger)
+  }
+  const passed = [remote, apiKey].filter(item => item.status === 'available').length
+  return { status: passed === 2 ? 'passed' : passed === 1 ? 'partial' : 'failed', remote, apiKey, testedAt: new Date(now).toISOString() }
+}

package/src/features/api-key/rpc.ts

@@ -0,0 +1,18 @@
+import type { ApiKeyPublicApi } from './contract.js'
+import { createSettingsRpcHandler, type SettingsRpcMethods } from '../../core/rpc-core.js'
+const record = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value)
+const empty = (value: unknown) => record(value) && Object.keys(value).length === 0
+const keyValue = (value: unknown) => record(value) && Object.keys(value).length === 1 && Object.keys(value)[0] === 'value' && typeof value.value === 'string' && value.value.length <= 1024
+export function createApiKeyRpcMethods(api: ApiKeyPublicApi): SettingsRpcMethods {
+  return {
+    describe: { validate: empty, invoke: () => api.describe() },
+    set: { validate: keyValue, invoke: payload => api.set((payload as { value: string }).value) },
+    clear: { validate: empty, invoke: () => api.clear() },
+    configureAndTest: { validate: keyValue, invoke: payload => api.configureAndTest((payload as { value: string }).value) },
+    testConnection: { validate: empty, invoke: () => api.testConnection() },
+    getValidationStatus: { validate: empty, invoke: () => api.getValidationStatus() },
+  }
+}
+export function createApiKeyRpcHandler(api: ApiKeyPublicApi) {
+  return createSettingsRpcHandler([{ namespace: 'apiKey', rpcMethods: createApiKeyRpcMethods(api) }])
+}