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

package/src/features/logs/rpc.ts

@@ -0,0 +1,29 @@
+/**
+ * `logs` 命名空间的 RPC 方法：只暴露显式登记的三个只读方法，沿用严格 payload 校验。
+ */
+
+import { LOGS_DEFAULT_PREVIEW_LINES, LOGS_MAX_PREVIEW_LINES, type LogsSettings } from './contract.js'
+import 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): boolean => record(value) && Object.keys(value).length === 0
+/** 只允许 `{ lines?: number }`，且值必须落在预览上限内。 */
+const previewPayload = (value: unknown): boolean => {
+  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: LogsSettings): SettingsRpcMethods {
+  return {
+    stats: { validate: empty, invoke: () => service.stats() },
+    preview: {
+      validate: previewPayload,
+      invoke: payload => service.preview((payload as { lines?: number }).lines ?? LOGS_DEFAULT_PREVIEW_LINES),
+    },
+    export: { validate: empty, invoke: () => service.export() },
+  }
+}

package/src/features/logs/styles.ts

@@ -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/src/guidance.ts

@@ -0,0 +1,114 @@
+/**
+ * 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'
+
+/**
+ * The prompt-registry calls this module makes, declared structurally: the host
+ * owns `systemPrompt`, and `inject` guarantees the service exists before `apply`
+ * runs, so the package keeps no harness dependency just to name the type.
+ */
+interface PromptRegistry {
+  section(section: { readonly name: string; readonly order: number; readonly text: string }): () => void
+  context(entry: { readonly name: string; readonly order: number; readonly text: () => string }): () => void
+}
+
+/** 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 } 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 在设置页维护。'
+
+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: Context): PromptRegistry {
+  const registry = ctx.get('systemPrompt') as PromptRegistry | undefined
+  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: Context): void {
+  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: boolean | undefined
+  const refresh = (): void => {
+    void apiKey.describe().then(
+      (status) => { configured = status.configured },
+      (error: unknown) => {
+        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: Context): void {
+  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/src/index.ts

@@ -0,0 +1,59 @@
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { type FtshareSettingsService } from './contract.js'
+import { createSettingsHost } from './core/module-registry.js'
+import { createApiKeyModule } from './features/api-key/index.js'
+import { DEFAULT_LOGS_CONFIG, logsConfigSchema, resolveLogsConfig, type LogsConfig } from './features/logs/config.js'
+import { createLogsModule } from './features/logs/index.js'
+import type { HostFetch } from './core/rpc-core.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']
+/** 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 const Config = z.object({ logs: logsConfigSchema })
+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 function apply(ctx: Context, config?: FtshareSettingsConfig): void {
+  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') as { fetch: HostFetch }
+    scoped.effect(() => connection.fetch.register(createSettingsRoute({ handler })), 'dsh-fft-settings: /api route')
+  })
+}

package/src/rpc.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'