dsh-diary-memory 0.1.0 → 0.1.1

package/src/config.ts

@@ -1,13 +1,17 @@
 import z from '@deepseek-ai/schemastery'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
+import { validateModelParameters } from './model-parameters.js'
+import type { ModelParameters } from './model-parameters.js'
 
 export interface DiaryConfig {
   apiKey: string
   baseUrl: string
   embeddingModel: string
   embeddingDimensions: number
+  embeddingParameters: ModelParameters
   rerankModel: string
+  rerankParameters: ModelParameters
   compressionRounds: number
   retainRounds: number
   namespace: string
@@ -30,7 +34,9 @@ export const defaults = Object.freeze({
   baseUrl: 'https://dashscope.aliyuncs.com',
   embeddingModel: 'text-embedding-v4',
   embeddingDimensions: 1024,
+  embeddingParameters: Object.freeze({}),
   rerankModel: 'gte-rerank-v2',
+  rerankParameters: Object.freeze({}),
   compressionRounds: 20,
   retainRounds: 2,
   namespace: 'companion',
@@ -47,13 +53,14 @@ export const defaults = Object.freeze({
   autoRecall: true,
 })
 
-// DSH reads this schema for its native plugin configuration form.
-export const Config: z<DiaryConfig> = z.object({
+const fields = {
   apiKey: z.string().role('secret').default('').description('百炼 API Key；留空读取 DSH_DIARY_BAILIAN_API_KEY 或 DASHSCOPE_API_KEY。'),
   baseUrl: z.string().default(defaults.baseUrl).description('百炼地域端点；须与 API Key 的地域一致。'),
   embeddingModel: z.string().default(defaults.embeddingModel),
   embeddingDimensions: z.number().step(1).min(1).max(4096).default(defaults.embeddingDimensions),
+  embeddingParameters: z.dict(z.any()).default({}).description('Embedding API 的额外 parameters JSON；dimension 和 text_type 由插件设置。'),
   rerankModel: z.string().default(defaults.rerankModel),
+  rerankParameters: z.dict(z.any()).default({}).description('Rerank API 的额外 parameters JSON；top_n 由召回条数设置。'),
   compressionRounds: z.number().step(1).min(2).default(defaults.compressionRounds).description('累计完成多少个会话轮次后，在下一次安全的 pre-step 压缩。工具调用不额外计轮次。'),
   retainRounds: z.number().step(1).min(1).default(defaults.retainRounds).description('至少保留最近多少个用户输入及其后续消息。'),
   namespace: z.string().default(defaults.namespace).description('数字分身的记忆空间。只有使用同一空间的会话共享日记与自我演化。'),
@@ -67,14 +74,36 @@ export const Config: z<DiaryConfig> = z.object({
   diaryMaxTokens: z.number().step(1).min(256).max(16000).default(defaults.diaryMaxTokens),
   diaryInputMaxChars: z.number().step(1).min(1000).default(defaults.diaryInputMaxChars),
   recentDiaryCount: z.number().step(1).min(0).max(10).default(defaults.recentDiaryCount),
-  autoRecall: z.boolean().default(true).description('每个新用户输入自动检索日记，并通过 agent.inject 写入可重放的上下文。'),
+  autoRecall: z.boolean().default(true).description('每个新用户输入自动检索日记，接纳到当前步骤并写入可重放的上下文。'),
+}
+
+const ValueConfig: z<DiaryConfig> = z.object(fields)
+export const liveConfigFields = ['apiKey', 'baseUrl', 'embeddingModel', 'embeddingDimensions', 'embeddingParameters', 'rerankModel', 'rerankParameters', 'compressionRounds', 'retainRounds', 'candidateCount', 'recallCount', 'autoRecall'] as const
+export type LiveConfigField = typeof liveConfigFields[number]
+export type PluginConfig = { [K in keyof DiaryConfig]: K extends LiveConfigField ? DiaryConfig[K] | { get(): DiaryConfig[K] | undefined } : DiaryConfig[K] }
+
+/** DSH only exposes volatile fields to its settings transport. */
+export const Config = z.object({
+  ...fields,
+  ...Object.fromEntries(liveConfigFields.map(key => [key, fields[key].volatile()])),
+  // No empty default on the write-only credential: the secret sidecar can report absence.
+  apiKey: z.string().role('secret').volatile().description('百炼 API Key；留空保留当前密钥。'),
 })
 
+export function resolvePluginConfig(input: Partial<PluginConfig> = {}, env: NodeJS.ProcessEnv = process.env): ResolvedConfig {
+  const values = Object.fromEntries(Object.entries(input).map(([key, value]) => [key,
+    liveConfigFields.includes(key as LiveConfigField) && value !== null && typeof value === 'object' && 'get' in value && typeof value.get === 'function' ? value.get() : value,
+  ]))
+  // Missing optional volatile values inherit the ordinary defaults.
+  return resolveConfig(Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined)), env)
+}
+
 export function resolveConfig(input: Partial<DiaryConfig> = {}, env: NodeJS.ProcessEnv = process.env): ResolvedConfig {
   for (const key of Object.keys(input)) {
     if (!(key in defaults)) throw new Error(`未知日记配置项：${key}`)
   }
-  const config = Config({ ...defaults, ...input })
+  // Schemastery normalizes dictionaries in place; live references are immutable.
+  const config = ValueConfig(structuredClone({ ...defaults, ...input }))
   const ranges: [keyof Pick<DiaryConfig, 'embeddingDimensions' | 'compressionRounds' | 'retainRounds' | 'candidateCount' | 'recallCount' | 'timeoutMs' | 'retries' | 'diaryMaxTokens' | 'diaryInputMaxChars' | 'recentDiaryCount'>, number, number][] = [
     ['embeddingDimensions', 1, 4096], ['compressionRounds', 2, 1000000],
     ['retainRounds', 1, 1000000], ['candidateCount', 1, 100], ['recallCount', 1, 100],
@@ -99,6 +128,8 @@ export function resolveConfig(input: Partial<DiaryConfig> = {}, env: NodeJS.Proc
   if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash || endpoint.pathname !== '/') throw new Error('baseUrl 必须是无路径、凭据和查询参数的百炼 origin')
   if (endpoint.protocol !== 'https:' && !(endpoint.protocol === 'http:' && ['127.0.0.1', '[::1]', 'localhost'].includes(endpoint.hostname))) throw new Error('baseUrl 需要 HTTPS；本地测试可以使用 loopback HTTP')
   config.baseUrl = endpoint.origin
+  config.embeddingParameters = validateModelParameters(config.embeddingParameters, 'embedding')
+  config.rerankParameters = validateModelParameters(config.rerankParameters, 'rerank')
   config.apiKey = config.apiKey.trim() || env.DSH_DIARY_BAILIAN_API_KEY?.trim() || env.DASHSCOPE_API_KEY?.trim() || ''
   const profileDir = env.DSH_PROFILE_DIR?.trim() || join(env.DSH_HOME?.trim() || join(homedir(), '.dsh'), 'profiles', env.DSH_PROFILE?.trim() || 'default')
   config.databasePath = config.databasePath || join(profileDir, 'diary-memory', 'memories.sqlite3')

package/src/index.ts

@@ -1,10 +1,11 @@
 import type { Context } from '@deepseek-ai/cordis'
-import { resolveConfig } from './config.js'
-import type { DiaryConfig } from './config.js'
+import { resolvePluginConfig } from './config.js'
+import type { PluginConfig } from './config.js'
 import { RetrievalService } from './retrieval-service.js'
+import type {} from '@deepseek-ai/dsh-settings'
 
 export { Config, defaults, resolveConfig } from './config.js'
-export type { DiaryConfig, ResolvedConfig } from './config.js'
+export type { DiaryConfig, PluginConfig, ResolvedConfig } from './config.js'
 export { BailianClient, BailianError } from './bailian-client.js'
 export { MemoryStore } from './memory-store.js'
 export { RetrievalService } from './retrieval-service.js'
@@ -15,7 +16,10 @@ export type { Diary } from './diary.js'
 export const name = 'diary-memory'
 export const inject = ['sessions', 'sessionProjections']
 
-export async function apply(ctx: Context, input: Partial<DiaryConfig> = {}): Promise<void> {
-  const memory = new RetrievalService(ctx, resolveConfig(input))
+export async function apply(ctx: Context, input: Partial<PluginConfig> = {}): Promise<void> {
+  const memory = new RetrievalService(ctx, () => resolvePluginConfig(input))
   await memory.initialize()
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.effect(() => settingsCtx.settings.configure({ auto: false }, ctx.fiber), 'diary-memory: custom settings page')
+  })
 }

package/src/model-parameters.ts

@@ -0,0 +1,32 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }
+export type ModelParameters = Readonly<Record<string, JsonValue>>
+
+/** Shared by the native configuration reader and the browser parameter editors. */
+export function validateModelParameters(value: unknown, kind: 'embedding' | 'rerank'): ModelParameters {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new Error(`${kind} 参数必须为 JSON 对象`)
+  const visit = (item: unknown, depth = 0): JsonValue => {
+    if (depth > 16) throw new Error(`${kind} 参数嵌套过深`)
+    if (item === null || typeof item === 'boolean' || typeof item === 'string') return item
+    if (typeof item === 'number' && Number.isFinite(item)) return item
+    if (Array.isArray(item)) return Object.freeze(item.map(child => visit(child, depth + 1))) as unknown as JsonValue[]
+    if (item && typeof item === 'object' && [Object.prototype, null].includes(Object.getPrototypeOf(item))) {
+      return Object.freeze(Object.fromEntries(Object.entries(item).map(([key, child]) => [key, visit(child, depth + 1)])))
+    }
+    throw new Error(`${kind} 参数只能包含 JSON 值`)
+  }
+  const parameters = visit(value) as ModelParameters
+  if (JSON.stringify(parameters).length > 16000) throw new Error(`${kind} 参数不能超过 16000 字符`)
+  const reserved = kind === 'embedding' ? ['dimension', 'text_type'] : ['top_n']
+  if (reserved.some(key => Object.hasOwn(parameters, key))) throw new Error(kind === 'embedding'
+    ? 'dimension 请在向量维度中填写；text_type 由入库和召回自动设置'
+    : 'top_n 请在召回条数中填写')
+  if (kind === 'embedding' && parameters.output_type !== undefined && parameters.output_type !== 'dense') throw new Error('本地向量检索需要 dense 向量，output_type 仅支持 dense')
+  if (kind === 'rerank' && parameters.return_documents !== undefined && typeof parameters.return_documents !== 'boolean') throw new Error('return_documents 必须是布尔值')
+  return parameters
+}
+
+export function stableParameters(value: ModelParameters): string {
+  const ordered = (item: JsonValue): JsonValue => Array.isArray(item) ? item.map(ordered)
+    : item !== null && typeof item === 'object' ? Object.fromEntries(Object.keys(item).sort().map(key => [key, ordered(item[key])])) : item
+  return JSON.stringify(ordered(value as JsonValue))
+}

package/src/orchestrator.ts

@@ -79,7 +79,7 @@ export class DiaryOrchestrator extends BasicCompactionEngine {
     // stores, so the local prepared journal is a recoverable publication barrier.
     if (!await this.ctx.sessions.flush(agent.session)) throw new Error('缺少会话持久化提供方，拒绝压缩')
     const span = captureSpan(agent.session, input.messages)
-    const { config, store, client } = this.memory
+    const { config, store, client } = this.memory.snapshot()
     if (!config.apiKey) throw new Error('请先配置百炼 apiKey；原会话上下文已保留')
     const existing = store.findSource(config.namespace, agent.session.id, span.sourceHash, client.embeddingKey)
     if (existing?.state === 'committed') throw new Error('日记片段已经提交，拒绝重复压缩')

package/src/retrieval-service.ts

@@ -29,23 +29,35 @@ export interface RecallHit {
 }
 
 export class RetrievalService extends Service {
-  readonly config: ResolvedConfig
-  readonly client: BailianClient
   readonly store: MemoryStore
   readonly lifetime = new AbortController()
   private readonly jobs = new Set<Promise<unknown>>()
   private readonly recovery = new WeakMap<Session, Promise<void>>()
+  private readonly configuration: () => ResolvedConfig
+  private readonly fixedClient?: BailianClient
+  private cachedClient?: { key: string; client: BailianClient }
 
-  constructor(ctx: Context, config: ResolvedConfig, dependencies: { store?: MemoryStore; client?: BailianClient } = {}) {
+  constructor(ctx: Context, config: ResolvedConfig | (() => ResolvedConfig), dependencies: { store?: MemoryStore; client?: BailianClient } = {}) {
     super(ctx, 'diaryMemory')
-    this.config = config
-    this.store = dependencies.store ?? new MemoryStore(config.databasePath)
-    this.client = dependencies.client ?? new BailianClient(config, { signal: this.lifetime.signal })
+    this.configuration = typeof config === 'function' ? config : () => config
+    this.store = dependencies.store ?? new MemoryStore(this.config.databasePath)
+    this.fixedClient = dependencies.client
     ctx.effect(() => () => this.dispose(), 'diaryMemory.lifecycle()')
   }
 
+  get config(): ResolvedConfig { return this.configuration() }
+  get client(): BailianClient { return this.snapshot().client }
+
+  /** One operation keeps its route and vector space even if settings change in flight. */
+  snapshot(): { config: ResolvedConfig; client: BailianClient; store: MemoryStore } {
+    const config = this.config
+    const key = JSON.stringify([config.apiKey, config.baseUrl, config.embeddingModel, config.embeddingDimensions, config.embeddingParameters, config.rerankModel, config.rerankParameters, config.timeoutMs, config.retries])
+    if (!this.fixedClient && this.cachedClient?.key !== key) this.cachedClient = { key, client: new BailianClient(config, { signal: this.lifetime.signal }) }
+    return { config, client: this.fixedClient ?? this.cachedClient!.client, store: this.store }
+  }
+
   async initialize(): Promise<void> {
-    this.ctx.sessionProjections.register(diaryProjection)
+    await this.ctx.sessionProjections.register(diaryProjection)
     this.ctx.on('session/created', session => {
       void this.track(() => this.reconcile(session)).catch(() => this.ctx.logger.warn('日记恢复未完成；保留待提交记录，下次使用时重试'))
     })
@@ -76,21 +88,22 @@ export class RetrievalService extends Service {
 
   recall(query: string, options: RecallOptions = {}): Promise<RecallHit[]> {
     return this.track(async () => {
+      const { config, client } = this.snapshot()
       const text = query.trim()
       if (!text || text.length > 8000) throw new TypeError('recall query 必须为 1–8000 字符')
-      const limit = options.limit ?? this.config.recallCount
-      if (!Number.isInteger(limit) || limit < 1 || limit > this.config.candidateCount) throw new TypeError('recall limit 超出候选数量')
+      const limit = options.limit ?? config.recallCount
+      if (!Number.isInteger(limit) || limit < 1 || limit > config.candidateCount) throw new TypeError('recall limit 超出候选数量')
       const signal = AbortSignal.any([this.lifetime.signal, ...options.signal ? [options.signal] : []])
       signal.throwIfAborted()
-      const namespace = this.config.namespace
-      if (!this.store.count(namespace, this.client.embeddingKey)) {
+      const namespace = config.namespace
+      if (!this.store.count(namespace, client.embeddingKey)) {
         if (this.store.count(namespace)) throw new Error('已有日记使用不同的 embedding 模型、维度或端点，请使用原向量配置或重新索引')
         return []
       }
-      const vector = await this.client.embed(text, { textType: 'query', signal })
-      const candidates = this.store.search(vector, { namespace, embeddingKey: this.client.embeddingKey, limit: this.config.candidateCount, sessionId: options.sessionId })
+      const vector = await client.embed(text, { textType: 'query', signal })
+      const candidates = this.store.search(vector, { namespace, embeddingKey: client.embeddingKey, limit: config.candidateCount, sessionId: options.sessionId })
       if (!candidates.length) return []
-      const ranking = await this.client.rerank(text, candidates.map(item => item.search_text), { topN: Math.min(limit, candidates.length), signal })
+      const ranking = await client.rerank(text, candidates.map(item => item.search_text), { topN: Math.min(limit, candidates.length), signal })
       signal.throwIfAborted()
       return ranking.map(item => {
         const match = candidates[item.index]