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

package/lib/features/api-key/host.js

@@ -0,0 +1,32 @@
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { FTSHARE_API_KEY_REF, FTSHARE_CREDENTIAL_EVENTS } from './contract.js';
+import { createApiKeySettings } from './service.js';
+import { defineSettingsModule } from '../../core/module-registry.js';
+import { createApiKeyRpcMethods } from './rpc.js';
+/**
+ * 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) {
+    return defineSettingsModule({
+        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/lib/features/api-key/index.d.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/lib/features/api-key/index.js

@@ -0,0 +1,12 @@
+/**
+ * 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 { createApiKeySettings } from './service.js';
+export { createApiKeyRpcMethods, createApiKeyRpcHandler } from './rpc.js';

package/lib/features/api-key/logging.d.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/lib/features/api-key/logging.js

@@ -0,0 +1 @@
+export {};

package/lib/features/api-key/model.d.ts

@@ -0,0 +1,24 @@
+import { 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 declare class FtshareSettingsModel {
+    private api;
+    private state;
+    private listeners;
+    private request;
+    private lifetime;
+    constructor(api: ApiKeyPublicApi);
+    getSnapshot: () => SettingsState;
+    subscribe: (listener: () => void) => (() => void);
+    private update;
+    connect(subscribe?: SubscribeChanges): () => void;
+    refresh(): Promise<void>;
+    configureAndTest(input: string): Promise<boolean>;
+    testConnection(): Promise<void>;
+    clear(): Promise<void>;
+}

package/lib/features/api-key/model.js

@@ -0,0 +1,105 @@
+import { normalizeApiKey } from './contract.js';
+export class FtshareSettingsModel {
+    api;
+    state = { busy: false, message: '' };
+    listeners = new Set();
+    request = 0;
+    lifetime = 0;
+    constructor(api) {
+        this.api = api;
+    }
+    getSnapshot = () => this.state;
+    subscribe = (listener) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
+    update(patch) { this.state = { ...this.state, ...patch }; for (const listener of this.listeners)
+        listener(); }
+    connect(subscribe) {
+        const dispose = subscribe?.(() => { void this.refresh(); });
+        void this.refresh();
+        return () => { this.request++; this.lifetime++; dispose?.(); };
+    }
+    async refresh() {
+        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) {
+        if (this.state.busy || !this.state.status?.writable)
+            return false;
+        let value;
+        try {
+            value = normalizeApiKey(input);
+        }
+        catch (error) {
+            this.update({ message: 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() {
+        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() {
+        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) {
+    return { passed: '远端服务正常，API Key 验证通过', partial: '远端服务正常，请查看 API Key 检查结果', failed: '测试未通过，请查看分项结果', not_run: '未执行测试，请先确认凭据配置', superseded: '凭据已变化，请重新测试', not_tested: '尚未测试' }[status] ?? '请查看分项结果';
+}

package/lib/features/api-key/probe.d.ts

@@ -0,0 +1,11 @@
+import { type ProbeResult, type ValidationResult } from './contract.js';
+import type { FeatureLogger } from './logging.js';
+export declare const PROBE_TIMEOUT_MS = 8000;
+export declare const PROBE_CONTRACTS: {
+    readonly daily: "api/v1/market/data/stock-candlesticks";
+    readonly historicalMinute: "api/v2/market/data/stock_minutes";
+};
+/** Error text is classified internally and never returned verbatim. */
+export declare function classifyFailure(code: number, text: string): ProbeResult;
+/** Two fixed, bounded requests. No SDK, arbitrary URL, retries or stored rows. */
+export declare function probeApiKey(key: string | undefined, signal: AbortSignal, fetcher?: typeof fetch, now?: number, logger?: FeatureLogger): Promise<ValidationResult>;

package/lib/features/api-key/probe.js

@@ -0,0 +1,142 @@
+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',
+};
+const result = (status, message) => ({ status, message });
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Error text is classified internally and never returned verbatim. */
+export function classifyFailure(code, text) {
+    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) {
+    if (!response.body)
+        throw new Error('empty_body');
+    const reader = response.body.getReader();
+    let size = 0;
+    const chunks = [];
+    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, params, key, parent, fetcher, now, logger) {
+    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) => {
+        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 = { Accept: 'application/json' };
+        if (key !== undefined)
+            headers.FTSHARE_API_KEY = key;
+        const failure = (code, text) => key === undefined && (code === 401 || code === 403)
+            ? result('upstream_error', '远端服务拒绝了连通性检查') : classifyFailure(code, text);
+        const response = await fetcher(url, { headers, redirect: 'error', signal });
+        let payload;
+        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, signal, fetcher = fetch, now = Date.now(), logger) {
+    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;
+    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/lib/features/api-key/rpc.d.ts

@@ -0,0 +1,4 @@
+import type { ApiKeyPublicApi } from './contract.js';
+import { type SettingsRpcMethods } from '../../core/rpc-core.js';
+export declare function createApiKeyRpcMethods(api: ApiKeyPublicApi): SettingsRpcMethods;
+export declare function createApiKeyRpcHandler(api: ApiKeyPublicApi): import("../../core/rpc-core.js").SettingsRpcHandler;

package/lib/features/api-key/rpc.js

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

package/lib/features/api-key/service.d.ts

@@ -0,0 +1,21 @@
+import { type ApiKeySettings, type CredentialStatus, type ValidationResult } from './contract.js';
+import type { FeatureLogger } from './logging.js';
+export interface CredentialStore {
+    resolve(): Promise<string | undefined>;
+    describe(): Promise<CredentialStatus>;
+    set(value: string): Promise<void>;
+    clear(): Promise<void>;
+}
+export type Validator = (key: string | undefined, signal: AbortSignal) => Promise<ValidationResult>;
+/**
+ * One Host instance owns validation state; the DSH provider owns all secrets.
+ *
+ * `logger` is optional so a directly constructed instance (tests, embeddings)
+ * stays silent: the plugin entry passes `ctx.logger()` in through
+ * `createApiKeyModule`. Fields never carry the Key or any token value.
+ */
+export declare function createApiKeySettings(store: CredentialStore, validator?: Validator, logger?: FeatureLogger): {
+    api: ApiKeySettings;
+    invalidate: () => void;
+    dispose(): void;
+};

package/lib/features/api-key/service.js

@@ -0,0 +1,181 @@
+import { normalizeApiKey, untested, FTSHARE_API_KEY_REF } from './contract.js';
+import { probeApiKey } from './probe.js';
+/**
+ * One Host instance owns validation state; the DSH provider owns all secrets.
+ *
+ * `logger` is optional so a directly constructed instance (tests, embeddings)
+ * stays silent: the plugin entry passes `ctx.logger()` in through
+ * `createApiKeyModule`. Fields never carry the Key or any token value.
+ */
+export function createApiKeySettings(store, validator, logger) {
+    // 默认校验器 = 真实探测：只有这条路径才需要把 logger 传进 probe 记请求级失败。
+    const validate = validator ?? ((key, signal) => probeApiKey(key, signal, fetch, Date.now(), logger));
+    let revision = 0;
+    let fingerprint;
+    let validation = untested();
+    let active;
+    let writes = Promise.resolve();
+    let reads = Promise.resolve();
+    let disposed = false;
+    const listeners = new Set();
+    function invalidate() {
+        revision++;
+        fingerprint = undefined;
+        validation = untested();
+        active?.controller.abort();
+        active = undefined;
+        for (const listener of listeners) {
+            try {
+                listener();
+            }
+            catch { /* Observers cannot turn a committed write into a failure. */ }
+        }
+    }
+    function current() {
+        const read = reads.then(async () => {
+            while (true) {
+                if (disposed)
+                    throw new Error('FTShare settings service is disposed');
+                const started = revision;
+                const key = await store.resolve();
+                const hash = key === undefined ? 'absent' : Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(key))), b => b.toString(16).padStart(2, '0')).join('');
+                if (started !== revision)
+                    continue;
+                if (fingerprint !== undefined && fingerprint !== hash)
+                    invalidate();
+                fingerprint = hash;
+                return key;
+            }
+        });
+        reads = read.catch(() => { });
+        return read;
+    }
+    function enqueue(operation) {
+        const promise = writes.then(() => {
+            if (disposed)
+                throw new Error('FTShare settings service is disposed');
+            return operation();
+        });
+        writes = promise.catch(() => { });
+        return promise;
+    }
+    async function write(value) {
+        if (!(await store.describe()).writable)
+            throw new Error('当前配置来源为只读');
+        const started = revision;
+        if (value === undefined)
+            await store.clear();
+        else
+            await store.set(value);
+        // Also covers providers without update events.
+        if (started === revision)
+            invalidate();
+    }
+    function testSnapshot(key, expectedRevision) {
+        if (disposed || revision !== expectedRevision)
+            return Promise.resolve(untested('superseded', '凭据已变化，请重新测试'));
+        if (active?.revision === revision)
+            return active.promise.then(value => structuredClone(value));
+        const controller = new AbortController();
+        const run = { revision, controller, promise: Promise.resolve(untested()) };
+        run.promise = (async () => {
+            let result;
+            try {
+                result = await validate(key, controller.signal);
+            }
+            catch {
+                logger?.warn('FTShare 验证服务异常', { stage: 'validate', code: 'validator_failed' });
+                result = { ...untested('not_run', '验证服务异常，请重试'), status: 'failed' };
+            }
+            try {
+                if (!disposed)
+                    await current();
+            }
+            catch {
+                logger?.warn('FTShare 凭据不可确认', { stage: 'resolve', code: 'credential_unavailable' });
+                return { ...untested('not_run', '无法确认当前凭据，请重新测试'), status: 'failed' };
+            }
+            if (disposed || controller.signal.aborted || revision !== run.revision)
+                return untested('superseded', '凭据已变化，旧测试结果已丢弃');
+            validation = structuredClone(result);
+            return structuredClone(result);
+        })().finally(() => { if (active === run)
+            active = undefined; });
+        active = run;
+        return run.promise.then(value => structuredClone(value));
+    }
+    const api = {
+        credentialRef: FTSHARE_API_KEY_REF,
+        async describe() {
+            while (true) {
+                const key = await current();
+                const started = revision;
+                const { configured, writable, source } = await store.describe();
+                if (started !== revision)
+                    continue;
+                const characters = Array.from(key ?? '');
+                // Short/invalid keys must not be exposed in full by the suffix preview.
+                const maskedValue = configured ? '••••••••' + (characters.length > 4 ? characters.slice(-4).join('') : '') : undefined;
+                return { configured, writable, ...(source === undefined ? {} : { source }), ...(maskedValue === undefined ? {} : { maskedValue }), revision, validation: structuredClone(validation) };
+            }
+        },
+        resolve: current,
+        async set(input) { const value = normalizeApiKey(input); await enqueue(() => write(value)); },
+        async clear() { await enqueue(() => write()); },
+        async createEnvironment(base = {}) {
+            const env = { ...base };
+            delete env[FTSHARE_API_KEY_REF];
+            const key = await current();
+            if (key !== undefined)
+                env[FTSHARE_API_KEY_REF] = key;
+            return env;
+        },
+        subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        async getValidationStatus() { await current(); return structuredClone(validation); },
+        async testConnection() {
+            await writes;
+            const key = await current();
+            return testSnapshot(key, revision);
+        },
+        async configureAndTest(input) {
+            let value;
+            try {
+                value = normalizeApiKey(input);
+            }
+            catch {
+                return { save: { status: 'failed', code: 'invalid_input', message: 'API Key 格式不正确' }, validation: untested('not_run', '保存失败，未执行测试') };
+            }
+            const saved = await enqueue(async () => {
+                try {
+                    if (!(await store.describe()).writable)
+                        return { code: 'read_only' };
+                    await write(value);
+                }
+                catch {
+                    logger?.warn('FTShare API Key 保存失败', { code: 'save_failed' });
+                    return { code: 'save_failed' };
+                }
+                // Reading/testing can fail after a committed save. Preserve that fact.
+                try {
+                    const key = await current();
+                    return { revision: key === value ? revision : -1, key };
+                }
+                catch {
+                    return { unavailable: true };
+                }
+            });
+            if ('code' in saved)
+                return {
+                    save: { status: 'failed', code: saved.code, message: saved.code === 'read_only' ? '当前配置来源为只读' : '保存失败，请重试' },
+                    validation: untested('not_run', '保存失败，未执行测试'),
+                };
+            if ('unavailable' in saved)
+                return { save: { status: 'saved', message: '已保存到 DSH 凭据存储' }, validation: untested('not_run', '已保存，但无法读取生效凭据，请重试') };
+            return { save: { status: 'saved', message: '已保存到 DSH 凭据存储' }, validation: await testSnapshot(saved.key, saved.revision) };
+        },
+    };
+    return {
+        api, invalidate,
+        dispose() { disposed = true; active?.controller.abort(); active = undefined; listeners.clear(); },
+    };
+}

package/lib/features/api-key/styles.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The API Key card's own styles, rendered by the card component's `<style>`.
+ *
+ * A card owns everything past the section shell: the core declares the
+ * `--ftshare-*` tokens and the section container, never card internals.
+ * Every selector stays scoped under `.ftshare-settings`, so a card never
+ * styles another card's markup.
+ */
+export declare const API_KEY_CARD_CSS = "\n.ftshare-settings .ftshare-eyebrow { color:var(--ftshare-accent-on-surface); font-size:11px; letter-spacing:.12em; }\n.ftshare-settings .ftshare-card { padding:22px; background:var(--ftshare-panel); border:0.5px solid var(--ftshare-border); border-radius:var(--dsw-radius-xl); margin-top:16px; }\n.ftshare-settings label { display:block; font-weight:500; }\n.ftshare-settings input { width:100%; height:32px; border:0.5px solid var(--ftshare-control); border-radius:var(--dsw-radius-md); padding:0 12px; background:var(--ftshare-input); color:inherit; font:inherit; }\n.ftshare-settings input::placeholder { color:var(--ftshare-muted); opacity:1; }\n.ftshare-settings .ftshare-actions { display:flex; flex-wrap:wrap; gap:10px; align-items:center; margin-top:16px; }\n.ftshare-settings button { min-height:36px; border:0.5px solid var(--ftshare-control); border-radius:var(--dsw-radius-md); padding:0 14px; font:inherit; background:transparent; color:inherit; cursor:pointer; }\n.ftshare-settings button.primary { background:var(--ftshare-accent); color:var(--ftshare-accent-ink); border-color:var(--ftshare-accent); font-weight:500; }\n.ftshare-settings button:disabled { opacity:.5; cursor:not-allowed; }\n.ftshare-settings dl { margin:0; }\n.ftshare-settings .ftshare-result { display:grid; grid-template-columns:130px 1fr; gap:12px; padding:10px 0; border-top:0.5px solid var(--ftshare-border); }\n.ftshare-settings dd { margin:0; overflow-wrap:anywhere; }\n.ftshare-settings .ftshare-error { color:var(--ftshare-error); }\n@media(max-width:540px) { .ftshare-settings .ftshare-card { padding:16px; } .ftshare-settings .ftshare-result { grid-template-columns:1fr; gap:4px; } }\n";

package/lib/features/api-key/styles.js

@@ -0,0 +1,24 @@
+/**
+ * The API Key card's own styles, rendered by the card component's `<style>`.
+ *
+ * A card owns everything past the section shell: the core declares the
+ * `--ftshare-*` tokens and the section container, never card internals.
+ * Every selector stays scoped under `.ftshare-settings`, so a card never
+ * styles another card's markup.
+ */
+export const API_KEY_CARD_CSS = `
+.ftshare-settings .ftshare-eyebrow { color:var(--ftshare-accent-on-surface); font-size:11px; letter-spacing:.12em; }
+.ftshare-settings .ftshare-card { padding:22px; background:var(--ftshare-panel); border:0.5px solid var(--ftshare-border); border-radius:var(--dsw-radius-xl); margin-top:16px; }
+.ftshare-settings label { display:block; font-weight:500; }
+.ftshare-settings input { width:100%; height:32px; border:0.5px solid var(--ftshare-control); border-radius:var(--dsw-radius-md); padding:0 12px; background:var(--ftshare-input); color:inherit; font:inherit; }
+.ftshare-settings input::placeholder { color:var(--ftshare-muted); opacity:1; }
+.ftshare-settings .ftshare-actions { display:flex; flex-wrap:wrap; gap:10px; align-items:center; margin-top:16px; }
+.ftshare-settings button { min-height:36px; border:0.5px solid var(--ftshare-control); border-radius:var(--dsw-radius-md); padding:0 14px; font:inherit; background:transparent; color:inherit; cursor:pointer; }
+.ftshare-settings button.primary { background:var(--ftshare-accent); color:var(--ftshare-accent-ink); border-color:var(--ftshare-accent); font-weight:500; }
+.ftshare-settings button:disabled { opacity:.5; cursor:not-allowed; }
+.ftshare-settings dl { margin:0; }
+.ftshare-settings .ftshare-result { display:grid; grid-template-columns:130px 1fr; gap:12px; padding:10px 0; border-top:0.5px solid var(--ftshare-border); }
+.ftshare-settings dd { margin:0; overflow-wrap:anywhere; }
+.ftshare-settings .ftshare-error { color:var(--ftshare-error); }
+@media(max-width:540px) { .ftshare-settings .ftshare-card { padding:16px; } .ftshare-settings .ftshare-result { grid-template-columns:1fr; gap:4px; } }
+`;