@dsh-ft/dsh-fft-settings 0.5.0 → 0.6.0

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

@@ -1,5 +1,5 @@
 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_API_KEY_APPLY_URL, 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'
@@ -60,7 +60,7 @@ export function ApiKeyCard({ api, subscribeChanges }: { readonly api: ApiKeyPubl
         <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>
+        <a href={FTSHARE_API_KEY_APPLY_URL} target="_blank" rel="noreferrer">获取 API Key ↗</a>
       </div>
       {draft && <small>“测试当前连接”使用已生效的密钥，不测试输入框内尚未保存的内容。</small>}
       {busy && <p role="status">正在处理，请稍候…</p>}

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

@@ -8,6 +8,19 @@
  * every consumer.
  */
 export const FTSHARE_API_KEY_REF = 'FTSHARE_API_KEY' as const
+/**
+ * 申请／购买 API Key 的页面。`utm_source=dsh-fft` 标记来源为本插件，站点据此归因；
+ * 卡片与一次性提示共用这一条地址，不要在别处另写一份。
+ */
+export const FTSHARE_API_KEY_APPLY_URL = 'https://ftai.chat/me/profile?tab=api-key&utm_source=dsh-fft' as const
+/**
+ * 设备级「已看过免费 Key 提示」标记的 localStorage 键。
+ *
+ * 带版本号：改一次文案就把版本加一，让所有用户重新看一次，不需要让用户清缓存。
+ * 设备级语义（重启、升级都保留，跨 workspace／窗口共享）由桌面版主窗口的
+ * `dsh-app://app/` origin 私有存储提供，不写宿主的配置文件。
+ */
+export const FREE_KEY_NOTICE_STORAGE_KEY = 'dsh-fft.free-key-notice.v1' 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]

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

@@ -47,12 +47,15 @@ async function readBoundedJson(response: Response): Promise<unknown> {
   return JSON.parse(new TextDecoder().decode(bytes))
 }
 
+/** 日志里的分项：远端服务检查与 Key 验证分开记，不因是否携带 Key 而错位。 */
+type ProbeTarget = 'remote' | 'apiKey'
+
 /**
  * 一次固定探测。失败（发出过请求且没有通过）写一条 `warn`：
- * 字段固定 `{ target, status, durationMs }` —— `target` 由是否携带 Key 决定；
+ * 字段固定 `{ target, status, durationMs }`，`target` 由调用点显式给出；
  * 未发请求的 `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> {
+async function probe(target: ProbeTarget, 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)
@@ -60,7 +63,7 @@ async function probe(path: string, params: Record<string, string>, key: string |
   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 })
+      logger?.warn('FTShare 探测未通过', { target, status: outcome.status, durationMs: Date.now() - started })
     }
     return outcome
   }
@@ -84,7 +87,7 @@ async function probe(path: string, params: Record<string, string>, key: string |
     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 验证通过'))
+    return finish(result('available', target === 'remote' ? '远端服务正常' : 'API Key 验证通过'))
   } catch {
     if (parent.aborted) return finish(result('not_run', '测试已取消或凭据已变化'))
     if (timeout.aborted) return finish(result('timeout', '连接超时，请稍后重试'))
@@ -92,12 +95,18 @@ async function probe(path: string, params: Record<string, string>, key: string |
   }
 }
 
-/** Two fixed, bounded requests. No SDK, arbitrary URL, retries or stored rows. */
+/**
+ * Two fixed, bounded requests. No SDK, arbitrary URL, retries or stored rows.
+ *
+ * 配置了 Key 时两项检查都携带它：匿名额度按出口 IP 计，用尽后未携带 Key 的请求会被
+ * 网关以 429 拒绝，若远端检查仍走匿名就会把「Key 已配置且可用」误报成受限。未配置
+ * Key 时退回匿名远端检查（401/403 不能用来指控 Key）。
+ */
 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, {
+  const remote = await probe('remote', 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)
+  }, key, signal, fetcher, now, logger)
   let apiKey: ProbeResult
   if (!key) {
     apiKey = result('auth_required', '未配置 API Key')
@@ -106,7 +115,7 @@ export async function probeApiKey(key: string | undefined, signal: AbortSignal,
   } 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, {
+    apiKey = await probe('apiKey', 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)

package/src/features/free-key-notice/card.tsx

@@ -0,0 +1,172 @@
+/**
+ * 一次性提示：还没配置 API Key 的用户，去获取免费的 FTShare Key。
+ *
+ * 三个设计决定：
+ *
+ * 1. **左下角、不阻塞**。它是提示，不是必须处理的阻断：不盖遮罩、不抢焦点、
+ *    不打断正在发生的事，12 秒后自己淡出（鼠标悬停时暂停计时）。用 `Modal`
+ *    会遮住整个界面，代价太大。
+ * 2. **只在确认「没配 Key」时出现**。凭据状态异步读来，没读到时一律不出现，
+ *    否则配了 Key 的用户每次启动都会被闪一下。
+ * 3. **设备级只出现一次**。首次出现就写 `localStorage` 标记（见 `./storage.ts`），
+ *    不等用户点按钮——否则自动消失后标记不落盘，下次启动又会打扰。
+ *
+ * 挂载在宿主框架级的 `shell.overlay` 槽上（`ui-layout` 的 AppFrame 常驻渲染），
+ * 不在设置页里：要触达的恰恰是从不打开设置的用户。该图层本身可穿透点击，
+ * 条目只在自己的卡片范围内接收指针事件。
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, type ReactNode } from 'react'
+import { FTSHARE_API_KEY_APPLY_URL, FTSHARE_API_KEY_REF, FTSHARE_CREDENTIAL_EVENTS, FREE_KEY_NOTICE_STORAGE_KEY } from '../api-key/contract.js'
+import type { ApiKeyCardContext } from '../api-key/card.js'
+import { createApiKeyClient } from '../api-key/client-api.js'
+import { createSettingsTransport } from '../../core/client-transport.js'
+import { browserNoticeStorage, readNoticeSeen, writeNoticeSeen, type NoticeFlagStorage } from './storage.js'
+import { FREE_KEY_NOTICE_ID, FREE_KEY_NOTICE_SLOT, isViewIdle, shouldShowNotice, type FreeKeyNoticeSessionState } from './decision.js'
+import { FREE_KEY_NOTICE_CSS } from './styles.js'
+
+/** 停留时长：足够读完一句话并决定要不要去获取，又不至于一直挂在界面上。 */
+export const FREE_KEY_NOTICE_AUTO_DISMISS_MS = 12_000
+
+export { FREE_KEY_NOTICE_ID, FREE_KEY_NOTICE_SLOT }
+
+/** 提示组件依赖的外部输入；全部可注入，测试不需要真实网络与浏览器存储。 */
+export interface FreeKeyNoticeDeps {
+  /** 读当前 Key 是否已配置；reject 表示读不到。 */
+  readConfigured: () => Promise<boolean>
+  /** 订阅「Key 可能变了」，配置好后立即收起。 */
+  subscribeConfigured: (listener: () => void) => () => void
+  storage: NoticeFlagStorage | undefined
+  applyUrl: string
+}
+
+/**
+ * 把异步的 `configured` 摊成 uSES 快照。只在有订阅者时读一次，订阅清理时停止。
+ * @param deps - 读函数与订阅函数。
+ * @returns uSES 快照源。
+ */
+function useConfigured(deps: FreeKeyNoticeDeps): boolean | undefined {
+  const source = useMemo(() => {
+    let value: boolean | undefined
+    let stop: (() => void) | undefined
+    const listeners = new Set<() => void>()
+    const publish = () => { for (const listener of [...listeners]) listener() }
+    const load = () => {
+      deps.readConfigured().then(next => { value = next; publish() }, () => { /* 读失败保持 undefined */ })
+    }
+    return {
+      getSnapshot: () => value,
+      subscribe: (listener: () => void) => {
+        listeners.add(listener)
+        if (stop === undefined) {
+          load()
+          const off = deps.subscribeConfigured(load)
+          stop = () => { off() }
+        }
+        return () => {
+          listeners.delete(listener)
+          if (listeners.size === 0) {
+            stop?.()
+            stop = undefined
+          }
+        }
+      },
+    }
+  }, [deps])
+  return useSyncExternalStore(source.subscribe, source.getSnapshot, source.getSnapshot)
+}
+
+/** 槽位提供的标准份额里，这里只用得到的这一个（由 ui-session 合并进所有槽位）。 */
+type UseSessionsShare = (selector: (state: FreeKeyNoticeSessionState) => boolean) => boolean
+
+/**
+ * 提示本体。
+ * @param props - 依赖注入，以及宿主通过槽位交给每个条目的标准份额。
+ * @returns 左下角卡片，或 null。
+ */
+export function FreeKeyNotice({ deps, useSessions }: {
+  deps: FreeKeyNoticeDeps
+  useSessions: UseSessionsShare
+}): ReactNode {
+  const [seen, setSeen] = useState(() => readNoticeSeen(deps.storage, FREE_KEY_NOTICE_STORAGE_KEY))
+  const [visible, setVisible] = useState(true)
+  const configured = useConfigured(deps)
+  const viewIdle = useSessions(isViewIdle)
+  const show = visible && shouldShowNotice({ seen, configured, viewIdle })
+
+  // 出现即记：自动消失或用户没点时也要落盘，不然下次启动又弹。
+  useEffect(() => {
+    if (!show || seen) return
+    writeNoticeSeen(deps.storage, FREE_KEY_NOTICE_STORAGE_KEY)
+    setSeen(true)
+  }, [show, seen, deps.storage])
+
+  // 自动淡出。悬停时暂停，移开后按剩余时间继续，避免用户正要看就被收走。
+  const deadline = useRef<number | undefined>(undefined)
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const dismiss = useCallback(() => { setVisible(false) }, [])
+  const hold = useCallback(() => {
+    if (timer.current !== undefined) clearTimeout(timer.current)
+    timer.current = undefined
+    deadline.current = undefined
+  }, [])
+  const resume = useCallback(() => {
+    if (deadline.current === undefined) return
+    const remaining = Math.max(0, deadline.current - Date.now())
+    timer.current = setTimeout(dismiss, remaining)
+  }, [dismiss])
+  useEffect(() => {
+    if (!show) return
+    deadline.current = Date.now() + FREE_KEY_NOTICE_AUTO_DISMISS_MS
+    timer.current = setTimeout(dismiss, FREE_KEY_NOTICE_AUTO_DISMISS_MS)
+    return () => {
+      if (timer.current !== undefined) clearTimeout(timer.current)
+      timer.current = undefined
+      deadline.current = undefined
+    }
+  }, [show, dismiss])
+
+  if (!show) return null
+
+  return <>
+    <style>{FREE_KEY_NOTICE_CSS}</style>
+    <aside
+      className="ftshare-free-key-notice"
+      role="status"
+      aria-live="polite"
+      onMouseEnter={hold}
+      onMouseLeave={resume}
+    >
+      <div className="ftshare-free-key-head">
+        <strong>免费获取 Key</strong>
+        <button type="button" className="ftshare-free-key-close" aria-label="关闭" onClick={dismiss}>✕</button>
+      </div>
+      <p>海量金融数据，一次配置长期使用</p>
+      <div className="ftshare-free-key-actions">
+        <a className="primary" href={deps.applyUrl} target="_blank" rel="noreferrer" onClick={dismiss}>去获取</a>
+        <button type="button" onClick={dismiss}>知道了</button>
+      </div>
+    </aside>
+  </>
+}
+
+/**
+ * 浏览器侧装配：把凭据通道、真实 localStorage 接到组件上。
+ * `useSessions` 是宿主交给 `shell.overlay` 条目的标准份额，从 props 透传而不是自造。
+ * @param ctx - 卡片那套上下文（slots + 凭据失效事件）。
+ * @returns 槽位组件工厂。
+ */
+export function createFreeKeyNotice(ctx: ApiKeyCardContext): (props: { useSessions: UseSessionsShare }) => ReactNode {
+  const api = createApiKeyClient(createSettingsTransport())
+  const subscribeConfigured = (listener: () => void) => {
+    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() }
+  }
+  const deps: FreeKeyNoticeDeps = {
+    readConfigured: async () => (await api.describe()).configured,
+    subscribeConfigured,
+    storage: browserNoticeStorage(),
+    applyUrl: FTSHARE_API_KEY_APPLY_URL,
+  }
+  return ({ useSessions }) => <FreeKeyNotice deps={deps} useSessions={useSessions} />
+}

package/src/features/free-key-notice/decision.ts

@@ -0,0 +1,47 @@
+/**
+ * 「这条一次性提示该不该弹」的判定。
+ *
+ * 与渲染分开：判定是纯函数、零依赖，能在 Node 测试里直接钉住；渲染层只管把
+ * 模态框摆出去。三条输入里任何一条没准备好都按「不弹」处理——这是刻意的，
+ * 一次没弹只是少一次提醒，弹错一次就是打扰。
+ */
+
+/** 宿主 `shell.overlay` 槽名；这个 feature 只往这一个座位贡献。 */
+export const FREE_KEY_NOTICE_SLOT = 'shell.overlay' as const
+/** 条目 id：必须自己的，占用宿主的会顶掉别人的浮层。 */
+export const FREE_KEY_NOTICE_ID = 'ftshare.free-key-notice' as const
+
+/** 提示出现前需要的会话事实，只取用得到的字段。 */
+export interface FreeKeyNoticeSessionState {
+  phase: string
+  byId: Record<string, { blank: boolean; retainedBy?: { mainView?: number } }>
+}
+
+/**
+ * 主视图是否停在一个空会话上（没有内容会被弹窗挡住）。
+ * @param state - 会话列表快照。
+ * @returns 是否可以安全地弹出模态框。
+ */
+export function isViewIdle(state: FreeKeyNoticeSessionState): boolean {
+  if (state.phase !== 'ready') return false
+  const main = Object.values(state.byId).find(session => (session.retainedBy?.mainView ?? 0) > 0)
+  return main === undefined || main.blank
+}
+
+/**
+ * 是否应当显示提示。
+ * - 已看过：不弹（设备级一次）；
+ * - Key 已配置、或状态还读不到：不弹（读不到时宁可少弹）；
+ * - 主视图被有内容的会话占着：不弹，等它空下来。
+ * @param facts - 三个输入。
+ * @returns 是否显示。
+ */
+export function shouldShowNotice(facts: {
+  seen: boolean
+  configured: boolean | undefined
+  viewIdle: boolean
+}): boolean {
+  if (facts.seen) return false
+  if (facts.configured !== false) return false
+  return facts.viewIdle
+}

package/src/features/free-key-notice/index.ts

@@ -0,0 +1,30 @@
+/**
+ * 一次性提示的注册入口。
+ *
+ * 它和设置卡片走同一个 `ctx.slots`，但目标是框架级的 `shell.overlay`——
+ * 宿主给「徽标、toast、状态条、对话框」这类全局浮层留的加法槽（`kind: list`,
+ * `scope: root`），`ui-layout` 的 AppFrame 常驻渲染它，不依赖设置面板是否打开。
+ *
+ * 两条注册纪律来自宿主的槽位契约：
+ * 1. `ctx.slots.inject(key, ...)` 等到槽位被声明再注册——启动早期 `shell.overlay`
+ *    可能还不存在，直接 `register` 会抛。
+ * 2. `id` 必须自己的。槽位按 id 去重，复用宿主的 id 会顶掉别人的浮层。
+ */
+import type { ReactNode } from 'react'
+// Type-only: pulls `shell.overlay` 的 SlotMap 声明（含 `useSessions` 这类标准份额）进本程序。
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type { ApiKeyCardContext } from '../api-key/card.js'
+import { createFreeKeyNotice, FREE_KEY_NOTICE_ID, FREE_KEY_NOTICE_SLOT } from './card.js'
+
+/**
+ * 注册一次性提示。
+ * @param ctx - 客户端上下文，需带 `slots` 服务。
+ * @returns 幂等 disposer。
+ */
+export function registerFreeKeyNotice(ctx: ApiKeyCardContext): () => void {
+  const component = createFreeKeyNotice(ctx)
+  return ctx.slots.inject(FREE_KEY_NOTICE_SLOT, () => ctx.slots.register(
+    { name: FREE_KEY_NOTICE_SLOT, id: FREE_KEY_NOTICE_ID, order: 100 },
+    component,
+  ))
+}

package/src/features/free-key-notice/storage.ts

@@ -0,0 +1,62 @@
+/**
+ * 「看过免费 Key 提示」的设备级标记。
+ *
+ * 只有一个事实（看过／没看过），所以不建服务、不建 store：读一次、写一次，
+ * 两个纯函数加一个最小的存储接口。存储接口只声明用到的那两个方法，测试可以传
+ * 一个内存实现，浏览器里传 `window.localStorage`。
+ *
+ * 读失败一律按「没看过」处理：隐私模式或存储被禁用时 `localStorage` 会抛异常，
+ * 这时提示最多多弹一次，比整个设置页崩掉可接受。
+ */
+
+/** 这一层用到的 `localStorage` 子集；隔离出来是为了让测试不碰真实存储。 */
+export interface NoticeFlagStorage {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+}
+
+/**
+ * 取浏览器存储；拿不到（没有 window、被禁用）时返回 undefined。
+ * @returns 可用存储，或 undefined。
+ */
+export function browserNoticeStorage(): NoticeFlagStorage | undefined {
+  try {
+    const storage = globalThis.localStorage
+    return storage === undefined ? undefined : { getItem: key => storage.getItem(key), setItem: (key, value) => { storage.setItem(key, value) } }
+  } catch (_blocked) {
+    // 访问 `localStorage` 本身在受限环境会抛 SecurityError。
+    return undefined
+  }
+}
+
+/**
+ * 读标记。任何异常与空值都算「没看过」。
+ * @param storage - 目标存储；缺失视为没看过。
+ * @param key - 标记键。
+ * @returns 是否已看过。
+ */
+export function readNoticeSeen(storage: NoticeFlagStorage | undefined, key: string): boolean {
+  if (storage === undefined) return false
+  try {
+    return storage.getItem(key) === '1'
+  } catch (_blocked) {
+    return false
+  }
+}
+
+/**
+ * 写标记。写失败不抛：提示已经显示过了，这次没记下来只是下次会再弹一次。
+ * @param storage - 目标存储；缺失时什么都不做。
+ * @param key - 标记键。
+ * @returns 是否写入成功。
+ */
+export function writeNoticeSeen(storage: NoticeFlagStorage | undefined, key: string): boolean {
+  if (storage === undefined) return false
+  try {
+    storage.setItem(key, '1')
+    return true
+  } catch (_blocked) {
+    // 配额满或被禁用：不阻断用户，下次再弹。
+    return false
+  }
+}

package/src/features/free-key-notice/styles.ts

@@ -0,0 +1,27 @@
+/**
+ * 一次性提示的样式：固定在左下角的非阻塞卡片。
+ *
+ * 不盖遮罩、不抢焦点——这一层（宿主的 `shell.overlay`）本身可穿透点击，
+ * 条目只有在这张卡片范围内才接收指针事件，所以卡片以外的界面照常可用。
+ * 位置用 `fixed` 而不是依赖外层布局：浮层是 `inset:0` 的绝对定位层，
+ * 条目自己决定停在哪里。
+ *
+ * 颜色全走 `--dsw-alias-*` 与 `--ft-*` 变量，深色／浅色两套调色板共用一份。
+ */
+export const FREE_KEY_NOTICE_CSS = `
+.ftshare-free-key-notice { position:fixed; left:24px; bottom:24px; z-index:20; box-sizing:border-box; width:min(320px, calc(100vw - 48px)); padding:16px; border:0.5px solid var(--dsw-alias-border-l2,rgba(0,0,0,.1)); border-radius:var(--dsw-radius-xl,20px); background:var(--dsw-alias-bg-layer-2,#fff); color:var(--dsw-alias-label-primary,#0f1115); box-shadow:var(--dsw-elevation-prominent,0 3px 8px rgba(0,0,0,.04), 0 0 20px rgba(0,0,0,.05)); animation:ftshareNoticeIn .2s ease; }
+.ftshare-free-key-notice * { box-sizing:border-box; }
+.ftshare-free-key-notice .ftshare-free-key-head { display:flex; align-items:flex-start; justify-content:space-between; gap:8px; }
+.ftshare-free-key-notice strong { font-size:14px; font-weight:500; line-height:22px; }
+.ftshare-free-key-notice .ftshare-free-key-close { flex:none; width:22px; height:22px; display:inline-flex; align-items:center; justify-content:center; border:none; border-radius:var(--dsw-radius-sm,8px); background:transparent; color:var(--dsw-alias-label-secondary,#61666b); font:inherit; font-size:12px; line-height:1; cursor:pointer; }
+.ftshare-free-key-notice .ftshare-free-key-close:hover { background:var(--dsw-alias-bg-layer-3,#f9fafb); }
+.ftshare-free-key-notice p { margin:6px 0 14px; font-size:13px; line-height:1.6; color:var(--dsw-alias-label-secondary,#61666b); }
+.ftshare-free-key-notice .ftshare-free-key-actions { display:flex; gap:8px; }
+.ftshare-free-key-notice .ftshare-free-key-actions :is(button,a) { min-height:30px; display:inline-flex; align-items:center; justify-content:center; border-radius:var(--dsw-radius-md,12px); border:0.5px solid var(--dsw-alias-border-l4,rgba(0,0,0,.16)); padding:0 12px; font:inherit; font-size:13px; background:transparent; color:inherit; text-decoration:none; cursor:pointer; }
+/* 主入口用品牌黄的半透明底：保留 FT 的色，又不至于在左下角变成一块醒目的亮黄。
+   文字仍取正文主色（不是压在上面的深黑字），70% 在深浅两套调色板下都能读。 */
+.ftshare-free-key-notice .ftshare-free-key-actions .primary { flex:1; background:color-mix(in srgb,var(--ft-accent,#f0c433) 70%,transparent); border-color:var(--ft-accent,#f0c433); color:var(--dsw-alias-label-primary,#0f1115); font-weight:500; }
+.ftshare-free-key-notice .ftshare-free-key-actions .primary:hover { background:color-mix(in srgb,var(--ft-accent,#f0c433) 82%,transparent); }
+@keyframes ftshareNoticeIn { from { opacity:0; transform:translateY(6px); } to { opacity:1; transform:none; } }
+@media (prefers-reduced-motion: reduce) { .ftshare-free-key-notice { animation:none; } }
+`

package/src/guidance.ts

@@ -45,7 +45,12 @@ export const FT_SECTION_ORDERS = { services: 6, dataPolicy: 7 } as const
 /** Order of the credential fact — `getContextOrder` owns only three named positions. */
 export const FT_CREDENTIALS_ORDER = 130
 
-export const FT_SERVICES_TEXT = '行情、K线与指标用 dsh-kline 工具（代码先用 search_symbols 解析）；投研报告与组合推荐用 cockpit_* 工具；因子入库与评价用 factor-intake-standard 技能；FTShare API Key 在设置页维护。'
+/**
+ * The capability list. It may only name tools this base actually ships or that
+ * the FT preset actually mounts: a promise about a tool that is not installed
+ * sends the model hunting for something that does not exist.
+ */
+export const FT_SERVICES_TEXT = '行情、K线与指标用 dsh-kline 工具（代码先用 search_symbols 解析）；FTShare 数据用 ftshare_* 工具，可用接口查 ftshare_status；FTShare API Key 在设置页维护。'
 
 export const FT_DATA_POLICY_TEXT = '金融数据优先取 FTShare，其次才用联网检索补充；引用必须给出处与时点；严格区分已披露事实、机构判断与待验证信息；不编造数字，也不构成投资建议。'