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

package/lib/features/logs/host.js

@@ -0,0 +1,139 @@
+/**
+ * `logs` 命名空间 Host 半边：常驻采集器 + 导出器。
+ *
+ * 采集器在 `create()` 里**无条件启动**（`apply()` 期注册即执行，与设置页是否渲染无关）；
+ * exporter 由 cordis 绑定当前 fiber，另用 `ctx.effect` 明确关闭文件句柄与队列。
+ *
+ * 工厂化：dev 的接缝里 `create(ctx)` 不再收配置，模块由 `apply()` 用一个闭包把
+ * 已解析的 `logs` 配置带进来（`createLogsModule(logsConfig)`）。这样采集器仍然在
+ * 注册期、而不是等到设置页打开才启动。
+ */
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { FTSHARE_API_KEY_REF } from '../api-key/contract.js';
+import { defineSettingsModule } from '../../core/module-registry.js';
+import { createLogsArchiveRoute } from './archive.js';
+import { FtLogCollector } from './collector.js';
+import { LOGS_DEFAULT_PREVIEW_LINES, LOGS_MAX_PREVIEW_LINES, LOGS_PREVIEW_MAX_BYTES, } from './contract.js';
+import { buildLogExport, describeSources, readTailLines } from './export.js';
+import { formatLogTimestamp } from './format.js';
+import { displayDshHome, logsDirectory, resolveDshHome } from './home.js';
+import { createLogsRpcMethods } from './rpc.js';
+/** 从本包 `package.json` 读版本；读不到时退回 `unknown`，不影响导出。 */
+async function readPluginVersion() {
+    try {
+        const url = new URL('../../../package.json', import.meta.url);
+        const { readFile } = await import('node:fs/promises');
+        const parsed = JSON.parse(await readFile(url, 'utf8'));
+        return typeof parsed.version === 'string' ? parsed.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * 运行时描述串：header 与 manifest 共用一个口径。
+ * @returns 形如 `node v22.19.0 darwin arm64`。
+ */
+function runtimeDescription() {
+    return `node ${process.version} ${process.platform} ${process.arch}`;
+}
+/**
+ * 构建 `logs` 模块：把已解析的配置闭包进 `create`。
+ * @param config - 本 feature 的 `logs` 配置（`resolveLogsConfig` 的输出，永远完整）。
+ * @returns 可交给 `ctx.ftshareSettings.modules.register` 的模块。
+ */
+export function createLogsModule(config) {
+    return defineSettingsModule({
+        namespace: 'logs',
+        inject: ['credentials'],
+        create(ctx) {
+            const home = resolveDshHome();
+            const directory = logsDirectory(home);
+            const collector = new FtLogCollector({
+                directory,
+                level: config.level,
+                maxBytes: config.maxBytes,
+                keep: config.keep,
+                // 当前 FTShare Key 的精确值替换：取不到就退化为纯模式脱敏。
+                secrets: async () => {
+                    const ref = credentialRef(FTSHARE_API_KEY_REF);
+                    const resolved = await ctx.credentials.resolve(ref);
+                    return resolved?.value === undefined ? [] : [resolved.value];
+                },
+            });
+            const version = readPluginVersion();
+            const service = {
+                filePath: collector.filePath,
+                flush: () => collector.flush(),
+                dispose: () => collector.dispose(),
+                stats: async () => {
+                    const snapshot = collector.stats();
+                    return {
+                        file: snapshot.filePath,
+                        fileBytes: snapshot.fileBytes,
+                        level: config.level,
+                        maxBytes: config.maxBytes,
+                        keep: config.keep,
+                        records: snapshot.records,
+                        dropped: snapshot.dropped,
+                        rotations: snapshot.rotations,
+                        writeFailures: snapshot.writeFailures,
+                        firstAt: snapshot.firstTs === undefined ? undefined : formatLogTimestamp(snapshot.firstTs),
+                        lastAt: snapshot.lastTs === undefined ? undefined : formatLogTimestamp(snapshot.lastTs),
+                        byName: snapshot.byName,
+                        sources: await describeSources(config.sources),
+                    };
+                },
+                preview: async (lines = LOGS_DEFAULT_PREVIEW_LINES) => {
+                    await collector.flush();
+                    const wanted = Math.min(LOGS_MAX_PREVIEW_LINES, Math.max(1, Math.trunc(lines)));
+                    try {
+                        const tail = await readTailLines(collector.filePath, wanted, LOGS_PREVIEW_MAX_BYTES);
+                        return { lines: tail.lines, bytes: tail.bytes, truncated: tail.truncated, fileBytes: tail.fileBytes };
+                    }
+                    catch {
+                        // 还没有任何日志时不是错误：返回空预览。
+                        return { lines: [], bytes: 0, truncated: false, fileBytes: 0 };
+                    }
+                },
+                export: async () => {
+                    await collector.flush();
+                    const result = await buildLogExport({
+                        filePath: collector.filePath,
+                        sources: config.sources,
+                        homeDisplay: displayDshHome(home),
+                        pluginVersion: await version,
+                        environment: runtimeDescription(),
+                    });
+                    return { fileName: result.fileName, text: result.text, bytes: result.bytes, truncated: result.truncated, sources: result.summaries };
+                },
+            };
+            // 诊断包由本 feature 自己挂路由（core 不认识 /logs.zip）：与插件入口同一条惯用法，
+            // register 返回的 disposer 交给 scoped.effect，owner fiber 释放时路由随之撤销。
+            ctx.inject(['connection'], scoped => {
+                const connection = scoped.get('connection');
+                scoped.effect(() => connection.fetch.register(createLogsArchiveRoute({
+                    filePath: collector.filePath,
+                    sources: config.sources,
+                    homeDisplay: displayDshHome(home),
+                    pluginVersion: version,
+                    environment: runtimeDescription(),
+                    flush: () => collector.flush(),
+                })), 'ftshare-settings: /logs.zip route');
+            });
+            const disposeExporter = ctx.logger.exporter({
+                // levels 是接收上限：warn=2 收 error/info/warn，debug=3 全收。
+                levels: { default: collector.threshold },
+                export: message => collector.append(message),
+            });
+            ctx.effect(() => () => {
+                disposeExporter();
+                void collector.dispose();
+            }, 'ftshare-settings: FT 日志采集器');
+            // 回填内置缓冲里残留的 error/info（warn/debug 已被默认门槛丢弃，不可恢复）。
+            const buffered = ctx.logger.buffer.filter(message => message.type === 'error' || message.type === 'info');
+            void collector.backfill(buffered);
+            return { service, rpcMethods: createLogsRpcMethods(service) };
+        },
+    });
+}

package/lib/features/logs/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Host half of the `logs` feature: the entry a host assembly imports.
+ *
+ * Like every feature directory, this file is the host entry, `./contract.js`
+ * its shared contract, and `./card.js` the browser entry browser code imports
+ * directly instead of going through here (a browser half must never pull the
+ * collector, the file system or the config schema).
+ */
+export * from './contract.js';
+export { buildLogArchive, createLogsArchiveRoute, type LogsArchive, type LogsArchiveManifest, type LogsArchiveOptions, type LogsArchiveRoute } from './archive.js';
+export { createLogsModule } from './host.js';
+export { createLogsRpcMethods } from './rpc.js';

package/lib/features/logs/index.js

@@ -0,0 +1,12 @@
+/**
+ * Host half of the `logs` feature: the entry a host assembly imports.
+ *
+ * Like every feature directory, this file is the host entry, `./contract.js`
+ * its shared contract, and `./card.js` the browser entry browser code imports
+ * directly instead of going through here (a browser half must never pull the
+ * collector, the file system or the config schema).
+ */
+export * from './contract.js';
+export { buildLogArchive, createLogsArchiveRoute } from './archive.js';
+export { createLogsModule } from './host.js';
+export { createLogsRpcMethods } from './rpc.js';

package/lib/features/logs/rpc.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `logs` 命名空间的 RPC 方法：只暴露显式登记的三个只读方法，沿用严格 payload 校验。
+ */
+import { type LogsSettings } from './contract.js';
+import type { SettingsRpcMethods } from '../../core/rpc-core.js';
+export declare function createLogsRpcMethods(service: LogsSettings): SettingsRpcMethods;

package/lib/features/logs/rpc.js

@@ -0,0 +1,27 @@
+/**
+ * `logs` 命名空间的 RPC 方法：只暴露显式登记的三个只读方法，沿用严格 payload 校验。
+ */
+import { LOGS_DEFAULT_PREVIEW_LINES, LOGS_MAX_PREVIEW_LINES } from './contract.js';
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const empty = (value) => record(value) && Object.keys(value).length === 0;
+/** 只允许 `{ lines?: number }`，且值必须落在预览上限内。 */
+const previewPayload = (value) => {
+    if (!record(value))
+        return false;
+    const keys = Object.keys(value);
+    if (keys.some(key => key !== 'lines'))
+        return false;
+    if (value.lines === undefined)
+        return true;
+    return typeof value.lines === 'number' && Number.isInteger(value.lines) && value.lines >= 1 && value.lines <= LOGS_MAX_PREVIEW_LINES;
+};
+export function createLogsRpcMethods(service) {
+    return {
+        stats: { validate: empty, invoke: () => service.stats() },
+        preview: {
+            validate: previewPayload,
+            invoke: payload => service.preview(payload.lines ?? LOGS_DEFAULT_PREVIEW_LINES),
+        },
+        export: { validate: empty, invoke: () => service.export() },
+    };
+}

package/lib/features/logs/styles.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The `logs` card's own styles, rendered by the card component's `<style>`.
+ *
+ * These two rules used to live in the core section stylesheet; a card owns
+ * everything past the section shell, so they moved here with the card. Every
+ * selector stays scoped under `.ftshare-settings`, so a card never styles
+ * another card's markup.
+ */
+export declare const LOGS_CARD_CSS = "\n.ftshare-settings select { height:32px; border:0.5px solid var(--ftshare-control); border-radius:var(--dsw-radius-md); padding:0 10px; background:var(--ftshare-input); color:inherit; font:inherit; }\n.ftshare-settings .ftshare-download { display:inline-flex; align-items:center; min-height:32px; padding:0 14px; border:0.5px solid var(--ftshare-control); border-radius:var(--dsw-radius-md); color:inherit; text-decoration:none; cursor:pointer; }\n.ftshare-settings .ftshare-log-preview { max-height:320px; overflow:auto; margin:0 0 12px; padding:12px; background:var(--ftshare-input); border:0.5px solid var(--ftshare-border); border-radius:var(--dsw-radius-lg); font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; line-height:1.5; white-space:pre-wrap; overflow-wrap:anywhere; }\n";

package/lib/features/logs/styles.js

@@ -0,0 +1,13 @@
+/**
+ * The `logs` card's own styles, rendered by the card component's `<style>`.
+ *
+ * These two rules used to live in the core section stylesheet; a card owns
+ * everything past the section shell, so they moved here with the card. Every
+ * selector stays scoped under `.ftshare-settings`, so a card never styles
+ * another card's markup.
+ */
+export const LOGS_CARD_CSS = `
+.ftshare-settings select { height:32px; border:0.5px solid var(--ftshare-control); border-radius:var(--dsw-radius-md); padding:0 10px; background:var(--ftshare-input); color:inherit; font:inherit; }
+.ftshare-settings .ftshare-download { display:inline-flex; align-items:center; min-height:32px; padding:0 14px; border:0.5px solid var(--ftshare-control); border-radius:var(--dsw-radius-md); color:inherit; text-decoration:none; cursor:pointer; }
+.ftshare-settings .ftshare-log-preview { max-height:320px; overflow:auto; margin:0 0 12px; padding:12px; background:var(--ftshare-input); border:0.5px solid var(--ftshare-border); border-radius:var(--dsw-radius-lg); font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; line-height:1.5; white-space:pre-wrap; overflow-wrap:anywhere; }
+`;

package/lib/guidance.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The FT prompt contract: two ordered system sections and one runtime fact.
+ *
+ * The identity is not here: the preset that mounts this entry states it in its own
+ * `persona` row (order 0), and repeating it as a section would render it twice.
+ *
+ * Registration is a single {@link installGuidance} call so the text and the
+ * mount point stay independent — moving these registrations into an agent preset
+ * later changes only the row that calls this module.
+ *
+ * A section is paid for on every request and any edit invalidates the prompt's
+ * KV-cache prefix, so the contract stays short; methodology that needs examples,
+ * checklists, or branch flow belongs in a skill instead.
+ * @module @dsh-ft/dsh-fft-settings/guidance
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Section name of the capability list. */
+export declare const FT_SERVICES_SECTION = "ft:services";
+/** Section name of the financial-data discipline. */
+export declare const FT_DATA_POLICY_SECTION = "ft:data-policy";
+/** Runtime-context name of the FTShare credential fact. */
+export declare const FT_CREDENTIALS_CONTEXT = "ft:credentials";
+/**
+ * Section orders. Consecutive integers keep a third-party section from sorting
+ * between two of ours (`1`–`499` is the shared free band), while `6` still lands
+ * after the deployment persona (`0`) and before core's plan policy (`500`).
+ */
+export declare const FT_SECTION_ORDERS: {
+    readonly services: 6;
+    readonly dataPolicy: 7;
+};
+/** Order of the credential fact — `getContextOrder` owns only three named positions. */
+export declare const FT_CREDENTIALS_ORDER = 130;
+export declare const FT_SERVICES_TEXT = "\u884C\u60C5\u3001K\u7EBF\u4E0E\u6307\u6807\u7528 dsh-kline \u5DE5\u5177\uFF08\u4EE3\u7801\u5148\u7528 search_symbols \u89E3\u6790\uFF09\uFF1B\u6295\u7814\u62A5\u544A\u4E0E\u7EC4\u5408\u63A8\u8350\u7528 cockpit_* \u5DE5\u5177\uFF1B\u56E0\u5B50\u5165\u5E93\u4E0E\u8BC4\u4EF7\u7528 factor-intake-standard \u6280\u80FD\uFF1BFTShare API Key \u5728\u8BBE\u7F6E\u9875\u7EF4\u62A4\u3002";
+export declare const FT_DATA_POLICY_TEXT = "\u91D1\u878D\u6570\u636E\u4F18\u5148\u53D6 FTShare\uFF0C\u5176\u6B21\u624D\u7528\u8054\u7F51\u68C0\u7D22\u8865\u5145\uFF1B\u5F15\u7528\u5FC5\u987B\u7ED9\u51FA\u5904\u4E0E\u65F6\u70B9\uFF1B\u4E25\u683C\u533A\u5206\u5DF2\u62AB\u9732\u4E8B\u5B9E\u3001\u673A\u6784\u5224\u65AD\u4E0E\u5F85\u9A8C\u8BC1\u4FE1\u606F\uFF1B\u4E0D\u7F16\u9020\u6570\u5B57\uFF0C\u4E5F\u4E0D\u6784\u6210\u6295\u8D44\u5EFA\u8BAE\u3002";
+export declare const FT_CREDENTIALS_MISSING_TEXT = "FTShare \u51ED\u636E\u672A\u914D\u7F6E\uFF1A\u884C\u60C5\u53EF\u80FD\u9000\u5316\u4E3A\u514D\u8D39\u515C\u5E95\u6E90\uFF0C\u8986\u76D6\u6709\u9650\uFF0C\u5F15\u7528\u65F6\u5FC5\u987B\u6807\u660E\u6765\u6E90\uFF1B\u9700\u8981\u5B8C\u6574\u6570\u636E\u65F6\u5F15\u5BFC\u7528\u6237\u5728\u8BBE\u7F6E\u9875\u586B\u5199 API Key\u3002";
+/**
+ * Register the FT prompt contract for every agent the calling context reaches.
+ * @param ctx - the plugin's host context; an unscoped context registers globally.
+ */
+export declare function installGuidance(ctx: Context): void;

package/lib/guidance.js

@@ -0,0 +1,88 @@
+/**
+ * The FT prompt contract: two ordered system sections and one runtime fact.
+ *
+ * The identity is not here: the preset that mounts this entry states it in its own
+ * `persona` row (order 0), and repeating it as a section would render it twice.
+ *
+ * Registration is a single {@link installGuidance} call so the text and the
+ * mount point stay independent — moving these registrations into an agent preset
+ * later changes only the row that calls this module.
+ *
+ * A section is paid for on every request and any edit invalidates the prompt's
+ * KV-cache prefix, so the contract stays short; methodology that needs examples,
+ * checklists, or branch flow belongs in a skill instead.
+ * @module @dsh-ft/dsh-fft-settings/guidance
+ */
+/** Section name of the capability list. */
+export const FT_SERVICES_SECTION = 'ft:services';
+/** Section name of the financial-data discipline. */
+export const FT_DATA_POLICY_SECTION = 'ft:data-policy';
+/** Runtime-context name of the FTShare credential fact. */
+export const FT_CREDENTIALS_CONTEXT = 'ft:credentials';
+/**
+ * Section orders. Consecutive integers keep a third-party section from sorting
+ * between two of ours (`1`–`499` is the shared free band), while `6` still lands
+ * after the deployment persona (`0`) and before core's plan policy (`500`).
+ */
+export const FT_SECTION_ORDERS = { services: 6, dataPolicy: 7 };
+/** 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 在设置页维护。';
+export const FT_DATA_POLICY_TEXT = '金融数据优先取 FTShare，其次才用联网检索补充；引用必须给出处与时点；严格区分已披露事实、机构判断与待验证信息；不编造数字，也不构成投资建议。';
+export const FT_CREDENTIALS_MISSING_TEXT = 'FTShare 凭据未配置：行情可能退化为免费兜底源，覆盖有限，引用时必须标明来源；需要完整数据时引导用户在设置页填写 API Key。';
+/**
+ * Resolve the host prompt registry.
+ * @param ctx - the plugin context whose `inject` declared `systemPrompt`.
+ * @returns the registry, typed by this module's structural declaration.
+ */
+function promptRegistry(ctx) {
+    const registry = ctx.get('systemPrompt');
+    if (registry === undefined) {
+        throw new Error('dsh-fft-settings: the systemPrompt service is missing although inject declared it');
+    }
+    return registry;
+}
+/**
+ * Keep one boolean for the credential fact, because a prompt provider is
+ * synchronous while the settings service answers asynchronously.
+ * @param ctx - the plugin context.
+ */
+function installCredentialFact(ctx) {
+    const apiKey = ctx.ftshareSettings.apiKey;
+    // `undefined` is "not known yet" and renders nothing: an unresolved fact must
+    // not tell the model the credential is missing.
+    let configured;
+    const refresh = () => {
+        void apiKey.describe().then((status) => { configured = status.configured; }, (error) => {
+            configured = undefined;
+            ctx.logger.debug('dsh-fft-settings: credential status unavailable', error);
+        });
+    };
+    refresh();
+    ctx.effect(() => apiKey.subscribe(refresh), 'dsh-fft-settings: credential fact refresh');
+    ctx.effect(() => promptRegistry(ctx).context({
+        name: FT_CREDENTIALS_CONTEXT,
+        order: FT_CREDENTIALS_ORDER,
+        text: () => configured === false ? FT_CREDENTIALS_MISSING_TEXT : '',
+    }), 'dsh-fft-settings: ft:credentials');
+}
+/**
+ * Register the FT prompt contract for every agent the calling context reaches.
+ * @param ctx - the plugin's host context; an unscoped context registers globally.
+ */
+export function installGuidance(ctx) {
+    const prompt = promptRegistry(ctx);
+    ctx.effect(() => prompt.section({
+        name: FT_SERVICES_SECTION,
+        order: FT_SECTION_ORDERS.services,
+        text: FT_SERVICES_TEXT,
+    }), 'dsh-fft-settings: ft:services');
+    ctx.effect(() => prompt.section({
+        name: FT_DATA_POLICY_SECTION,
+        order: FT_SECTION_ORDERS.dataPolicy,
+        text: FT_DATA_POLICY_TEXT,
+    }), 'dsh-fft-settings: ft:data-policy');
+    // Optional service: the three sections never depend on the settings row, and
+    // a missing provider only means the credential fact renders nothing.
+    ctx.inject(['ftshareSettings'], scope => installCredentialFact(scope));
+}

package/lib/index.d.ts

@@ -0,0 +1,67 @@
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type FtshareSettingsService } from './contract.js';
+import { DEFAULT_LOGS_CONFIG, type LogsConfig } from './features/logs/config.js';
+export * from './contract.js';
+export { defineSettingsModule } from './core/module-registry.js';
+export declare const name = "@dsh-ft/dsh-fft-settings";
+/**
+ * Host services this plugin's own built-in modules resolve at registration.
+ * A consuming plugin declares its own requirement; settings never declares
+ * services on a module's behalf. The FT prompt contract lives in the `./agent`
+ * entry, which only an agent preset mounts.
+ */
+export declare const inject: string[];
+export declare const provide: string[];
+/** Plugin config, assembled from each feature's own slice schema. */
+export interface FtshareSettingsConfig {
+    logs: LogsConfig;
+}
+/**
+ * Native Schemastery schema of the whole plugin config: the features own their
+ * slices, this entry only composes them. DSH's config collector accepts
+ * nothing but a native Schemastery schema.
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    logs: z<Schemastery.ObjectS<NoInfer<{
+        level: z<"warn" | "debug", "warn" | "debug", "defined">;
+        maxBytes: z<number, number, "defined">;
+        keep: z<number, number, "defined">;
+        sources: z<string[], string[], "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        level: z<"warn" | "debug", "warn" | "debug", "defined">;
+        maxBytes: z<number, number, "defined">;
+        keep: z<number, number, "defined">;
+        sources: z<string[], string[], "defined">;
+    }>>, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    logs: z<Schemastery.ObjectS<NoInfer<{
+        level: z<"warn" | "debug", "warn" | "debug", "defined">;
+        maxBytes: z<number, number, "defined">;
+        keep: z<number, number, "defined">;
+        sources: z<string[], string[], "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        level: z<"warn" | "debug", "warn" | "debug", "defined">;
+        maxBytes: z<number, number, "defined">;
+        keep: z<number, number, "defined">;
+        sources: z<string[], string[], "defined">;
+    }>>, "defined">;
+}>>, "plain">;
+export { DEFAULT_LOGS_CONFIG };
+export type { LogsConfig };
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        ftshareSettings: FtshareSettingsService;
+    }
+}
+/**
+ * @param config - validated plugin config. Each built-in module is registered
+ * eagerly, so the log collector starts here, unconditionally, instead of
+ * waiting for a settings-page render.
+ *
+ * The parameter default is deliberately **not** relied on: cordis validates the
+ * raw row through {@link Config} before this call, and a direct `apply(ctx)`
+ * call (tests, hand-built contexts) never triggers one — so the fallback parse
+ * happens in the body and every feature slice is always defined.
+ */
+export declare function apply(ctx: Context, config?: FtshareSettingsConfig): void;

package/lib/index.js

@@ -0,0 +1,50 @@
+import z from '@deepseek-ai/schemastery';
+import { createSettingsHost } from './core/module-registry.js';
+import { createApiKeyModule } from './features/api-key/index.js';
+import { DEFAULT_LOGS_CONFIG, logsConfigSchema, resolveLogsConfig } from './features/logs/config.js';
+import { createLogsModule } from './features/logs/index.js';
+import { createSettingsRoute } from './core/transport.js';
+import { installDefaultPresetOnce } from './default-preset.js';
+export * from './contract.js';
+export { defineSettingsModule } from './core/module-registry.js';
+export const name = '@dsh-ft/dsh-fft-settings';
+/**
+ * Host services this plugin's own built-in modules resolve at registration.
+ * A consuming plugin declares its own requirement; settings never declares
+ * services on a module's behalf. The FT prompt contract lives in the `./agent`
+ * entry, which only an agent preset mounts.
+ */
+export const inject = ['credentials'];
+export const provide = ['ftshareSettings'];
+/**
+ * Native Schemastery schema of the whole plugin config: the features own their
+ * slices, this entry only composes them. DSH's config collector accepts
+ * nothing but a native Schemastery schema.
+ */
+export const Config = z.object({ logs: logsConfigSchema });
+export { DEFAULT_LOGS_CONFIG };
+/**
+ * @param config - validated plugin config. Each built-in module is registered
+ * eagerly, so the log collector starts here, unconditionally, instead of
+ * waiting for a settings-page render.
+ *
+ * The parameter default is deliberately **not** relied on: cordis validates the
+ * raw row through {@link Config} before this call, and a direct `apply(ctx)`
+ * call (tests, hand-built contexts) never triggers one — so the fallback parse
+ * happens in the body and every feature slice is always defined.
+ */
+export function apply(ctx, config) {
+    const { service, handler } = createSettingsHost();
+    ctx.provide('ftshareSettings', service);
+    // 具名 logger：`ctx.logger()` 无参调用时 logger name = 插件名（cordis 既有语义），
+    // 采集器据此把「是哪个包打的」自动带上。feature 不接受模块级单例。
+    const logger = ctx.logger();
+    // Built-in namespaces take the same path a third-party module would take.
+    service.modules.register(createApiKeyModule(logger), ctx);
+    service.modules.register(createLogsModule(resolveLogsConfig(config)), ctx);
+    installDefaultPresetOnce(ctx);
+    ctx.inject(['connection'], scoped => {
+        const connection = scoped.get('connection');
+        scoped.effect(() => connection.fetch.register(createSettingsRoute({ handler })), 'dsh-fft-settings: /api route');
+    });
+}

package/lib/rpc.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@dsh-ft/dsh-fft-settings/client-api` — the generic browser caller entry.
+ *
+ * Transport plus envelope helpers and their types, nothing feature-specific: a
+ * card for any namespace uses `callSettingsRpc` against the namespace and
+ * method its own host module registered. A feature's browser adapter lives
+ * beside that feature instead of growing this entry.
+ */
+export * from './core/rpc-core.js';
+export { createSettingsTransport } from './core/client-transport.js';

package/lib/rpc.js

@@ -0,0 +1,10 @@
+/**
+ * `@dsh-ft/dsh-fft-settings/client-api` — the generic browser caller entry.
+ *
+ * Transport plus envelope helpers and their types, nothing feature-specific: a
+ * card for any namespace uses `callSettingsRpc` against the namespace and
+ * method its own host module registered. A feature's browser adapter lives
+ * beside that feature instead of growing this entry.
+ */
+export * from './core/rpc-core.js';
+export { createSettingsTransport } from './core/client-transport.js';

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "FT Settings",
+    "description": "Shared plugin pages for the financial workbench."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "FT 设置",
+    "description": "金融工作台共享插件页"
+  }
+}

package/package.json

@@ -1,6 +1,110 @@
 {
   "name": "@dsh-ft/dsh-fft-settings",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.1",
+  "description": "FT 设置与凭据底座：FTShare API Key、设置页卡片、运行日志与品牌主题层，供 FT 系列插件共享。",
+  "license": "MIT",
+  "homepage": "https://github.com/gigaflw/dsh-fft-base/tree/dev/packages/dsh-fft-settings#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gigaflw/dsh-fft-base.git",
+    "directory": "packages/dsh-fft-settings"
+  },
+  "bugs": {
+    "url": "https://github.com/gigaflw/dsh-fft-base/issues"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "ftshare",
+    "settings"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsdown --config tsdown.config.ts",
+    "prepare": "pnpm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test tests/*.test.mjs",
+    "theme:preview": "pnpm run build && node tools/theme-preview.mjs"
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE",
+    "docs",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "package.json"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-api-remotes"
+      ]
+    },
+    "engines": {
+      "dsh": ">=0.2.0-rc.2"
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./contract": {
+      "types": "./lib/contract.d.ts",
+      "default": "./lib/contract.js"
+    },
+    "./agent": {
+      "types": "./lib/agent.d.ts",
+      "default": "./lib/agent.js"
+    },
+    "./client": {
+      "types": "./lib/client.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./client-api": {
+      "types": "./lib/rpc.d.ts",
+      "default": "./lib/rpc.js"
+    },
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "dependencies": {
+    "fflate": ">=0.8.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-api-remotes": ">=0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.2.0-rc.2",
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-credentials": ">=0.2.0-rc.2",
+    "@deepseek-ai/schemastery": ">=3.18.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@types/react": "^18.3.24",
+    "react": "^18.3.1",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.8.3",
+    "@deepseek-ai/cordis": "catalog:",
+    "@deepseek-ai/dsh-client-ui-settings": "catalog:",
+    "@deepseek-ai/dsh-client-ui-slots": "catalog:",
+    "@deepseek-ai/dsh-credentials": "catalog:",
+    "@deepseek-ai/schemastery": "catalog:"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}