dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/settings-schema.ts

@@ -0,0 +1,94 @@
+/**
+ * 知识库的设置 schema 与命名空间（0029 / 0031）。
+ *
+ * ## 为什么单独一个模块
+ *
+ * 它以前内联在 `index.ts` 里，于是**没有任何测试能碰到它** —— 而它恰恰是一个
+ * 「写错一个字符、整个设置分区就静默消失」的东西。抽出来之后
+ * `tests/settings-schema.test.mjs` 能用设置层真实的解析路径跑一遍。
+ *
+ * ## 空串必须被 schema 接受（v0.7.5 的真实故障）
+ *
+ * schemastery 与 zod 在这一点上**不一样**：zod 的 `.default()` 短路，缺字段时直接返回
+ * 默认值、不校验；schemastery 会**校验默认值本身**。所以
+ *
+ * ```ts
+ * z.string().min(1).default('')     // 自己和自己矛盾
+ * ```
+ *
+ * 在解析时直接抛 `$.python expected string length >= 1 but got 0`。
+ *
+ * 而 0029 之后 `python` / `embeddingModel` / `rerankModel` 的语义正是「**空串 = 自动**」
+ * （跟着 `<agentRoot>/resource/` 走，见 `runtime.ts` 的 `resolveResources`）。
+ * 两者相撞的后果不是「这三个设置项失效」，而是 `settings.installSection()` 在
+ * **注册命名空间**那一步就抛异常（`register` 先 `resolve` 再登记）：
+ *
+ * - 命名空间从未注册 → 面板上整个知识库设置显示「设置服务不可用」；
+ * - `swap()` 永远不被调用 → `migrateLegacyResources` 从不执行（家当一直留在旧位置）；
+ * - `settings.yaml` 里存的值一个都不生效。
+ *
+ * 而且是**全量**失效，不是只有这三个字段 —— 所以这三个字段只约束「是字符串」，
+ * 不约束长度，空串的含义交给 `resolveResources()` 解释。
+ *
+ * @module
+ */
+
+import z from '@deepseek-ai/schemastery'
+import { volatileFields } from './settings-volatile.js'
+import { DEFAULT_KNOWLEDGE_CONFIG } from './types.js'
+import { defaultAgentRoot } from './layout.js'
+import { DIAGNOSIS_ENTITY_TYPES } from './diagnosis/schema.js'
+
+/** 设置命名空间。命名规则是 `^[a-z][a-z0-9-]*$`（dsh-settings 的 `parseSettingsNamespace`）。 */
+export const SETTINGS_NAMESPACE = 'tita-data-agent-knowledge'
+
+export const KNOWLEDGE_SETTINGS_SCHEMA = z.object(volatileFields({
+  /**
+   * **用户唯一要设的路径**（0029）。四段布局由它推出来，见 `layout.ts`。
+   */
+  agentRoot: z.string().min(1).default(defaultAgentRoot()),
+  /**
+   * @deprecated 0029：旧布局的知识树根。**只作为一次性迁移的来源**保留 ——
+   * 它不再出现在设置面板里，也不再决定任何路径。留一个宽松的字符串默认值，
+   * 是为了让老用户的 settings JSON 还能被解析出来，从而知道旧树在哪。
+   */
+  rootDir: z.string().default(''),
+  schemaTypes: z.array(z.union(['concept', 'metric', 'table', 'event', 'playbook', 'case', ...DIAGNOSIS_ENTITY_TYPES] as const)).default(DEFAULT_KNOWLEDGE_CONFIG.schemaTypes),
+  /**
+   * @deprecated 0013：来源分类改为按知识库持久化的注册表。这里保留一个**宽松**
+   * 的历史字段（旧的 zod union 会把自定义分类直接判为非法，等于把配置入口焊死），
+   * 它不再参与任何校验，也不再出现在设置面板里。
+   */
+  sourceAppendTypes: z.array(z.string()).default(DEFAULT_KNOWLEDGE_CONFIG.sourceAppendTypes),
+  allowSourceTruth: z.boolean().default(DEFAULT_KNOWLEDGE_CONFIG.allowSourceTruth),
+  extractCandidates: z.boolean().default(DEFAULT_KNOWLEDGE_CONFIG.extractCandidates),
+  // #3b：模型抽取与归并。默认关 —— 它会真花钱、也依赖模型可用，所以由用户显式打开。
+  extractWithModel: z.boolean().default(DEFAULT_KNOWLEDGE_CONFIG.extractWithModel),
+  // 下面三个是「空串 = 自动」的字段，**不能加 .min(1)**：默认值就是空串，而
+  // schemastery 会校验默认值 —— 加了会让整个命名空间注册失败（见文件头注释）。
+  python: z.string().default(DEFAULT_KNOWLEDGE_CONFIG.python),
+  embeddingProvider: z.union(['wemm-python', 'ollama', 'none'] as const).default(DEFAULT_KNOWLEDGE_CONFIG.embeddingProvider),
+  embeddingBaseUrl: z.string().min(1).default(DEFAULT_KNOWLEDGE_CONFIG.embeddingBaseUrl),
+  embeddingModel: z.string().default(DEFAULT_KNOWLEDGE_CONFIG.embeddingModel),
+  embeddingDimension: z.number().step(1).min(1).default(DEFAULT_KNOWLEDGE_CONFIG.embeddingDimension),
+  embeddingBatchSize: z.number().step(1).min(1).max(64).default(DEFAULT_KNOWLEDGE_CONFIG.embeddingBatchSize),
+  embeddingTimeoutMs: z.number().step(1).min(1000).max(600000).default(DEFAULT_KNOWLEDGE_CONFIG.embeddingTimeoutMs),
+  embeddingDevice: z.union(['auto', 'mps', 'cpu'] as const).default(DEFAULT_KNOWLEDGE_CONFIG.embeddingDevice),
+  recallTopK: z.number().step(1).min(1).max(50).default(DEFAULT_KNOWLEDGE_CONFIG.recallTopK),
+  // 0031：候选池与最终条数彻底分开。上限 200 是因为再深也只是把噪声往后排，
+  // 而重排的代价随候选数线性增长。
+  recallCandidatePool: z.number().step(1).min(1).max(200).default(DEFAULT_KNOWLEDGE_CONFIG.recallCandidatePool),
+  recallMode: z.union(['fts', 'vector', 'graph', 'hybrid'] as const).default(DEFAULT_KNOWLEDGE_CONFIG.recallMode),
+  // 阈值区间都开满：初值取 WeKnora 的出厂值，但校准要能自由调。
+  // 关键词是归一化 BM25（0..1，相对），向量是原始余弦（−1..1，绝对）。
+  keywordThreshold: z.number().min(0).max(1).default(DEFAULT_KNOWLEDGE_CONFIG.keywordThreshold),
+  vectorThreshold: z.number().min(-1).max(1).default(DEFAULT_KNOWLEDGE_CONFIG.vectorThreshold),
+  contextTopN: z.number().step(1).min(1).max(50).default(DEFAULT_KNOWLEDGE_CONFIG.contextTopN),
+  // 重排阈值与 WeKnora 同刻度：**原始 cross-encoder logit**（−10..10，默认 0.2）。
+  // 展示用的 `rerankScore` 是它的 sigmoid，两者单调等价 —— 但阈值留在原始刻度上，
+  // 这样「0.2」这个数与参照实现的配置可以直接对照。
+  rerankThreshold: z.number().min(-10).max(10).default(DEFAULT_KNOWLEDGE_CONFIG.rerankThreshold),
+  rerankProvider: z.union(['bert-python', 'none'] as const).default(DEFAULT_KNOWLEDGE_CONFIG.rerankProvider),
+  rerankModel: z.string().default(DEFAULT_KNOWLEDGE_CONFIG.rerankModel),
+  rerankTimeoutMs: z.number().step(1).min(1000).max(600000).default(DEFAULT_KNOWLEDGE_CONFIG.rerankTimeoutMs),
+}))

package/src/settings-volatile.ts

@@ -0,0 +1,122 @@
+/**
+ * 0.1.7 的一条硬规矩：**设置界面只暴露 volatile 字段。**
+ *
+ * ## 现象与原因
+ *
+ * 面板上一直显示「设置服务不可用」，客户端拿到的快照状态是 `unavailable`。原因不在
+ * 客户端、也不在 entry 能不能被寻址 —— 我们实测过，`configEditor.configuration()`
+ * 里**有**这条 entry（187 条可寻址行里有它）。真正的关卡在 `SettingsForms.describe()`
+ * 里那一步 schema 投影：
+ *
+ * ```js
+ * // dsh-settings
+ * function volatileForm(schema) {
+ *   if (schema.meta.volatile) return plainSchema(schema);      // ① 标了 volatile → 当成叶子字段
+ *   if (schema.type === "object") { …递归，子字段一个都投影不出来就 undefined… }  // ② object → 下钻
+ *   // ③ 其它一切（string / number / boolean / array / union…）→ undefined
+ * }
+ * ```
+ *
+ * 然后：
+ *
+ * ```js
+ * const form = volatileForm(schema);
+ * if (form === void 0) return [];        // ← 一个字段都投影不出来，整条 entry 不会进 describe()
+ * ```
+ *
+ * 我们的字段全是普通的 `.default(...)`，既不是 object 也不是 volatile，于是全部落到
+ * 出口 ③，整条 entry 被丢掉，客户端就只剩下 `unavailable`。核心插件的写法都带
+ * `.volatile()`（`z.string().volatile()`、`z.number().default(10).volatile()`），
+ * 这就是那条约定。
+ *
+ * ## 为什么这里统一标，而不是逐个手写
+ *
+ * 三个设置 schema 一共 40 多个字段；逐个加 `.volatile()` 既啰嗦，又会漏 —— 而**漏一个
+ * 字段的后果是那个设置项在界面上直接消失**，属于沉默的失败。统一包一层让「新增字段
+ * 默认可见」成为默认行为，想让它不可见才需要显式说明。
+ *
+ * 嵌套对象**不**在这里递归：本项目里唯一的内嵌结构在数组里面（`categories` / `acts`），
+ * 而数组本来就无法被表单下钻，标成 volatile 让它按整块编辑才是可用形态。
+ *
+ * ## 标了 volatile 就必须自己应用
+ *
+ * 这是成对的两件事，只做一半就是「假的设置」。volatile 改动**不会重载插件**
+ * （`Entry._commitVolatile()` 只调 `updateVolatile()` 就地改引用，再发一个
+ * `loader/volatile-update` 事件）。所以插件必须监听那个事件，把新配置读回来并用上去 ——
+ * 见 `index.ts` 里 `applyVolatile()` 的说明。
+ *
+ * @module
+ */
+
+import type Schemastery from '@deepseek-ai/schemastery'
+import type { KnowledgeConfig } from './types.js'
+
+/**
+ * 把一组字段全部标成 volatile。返回值仍是同一个对象形状，可以直接交给 `z.object()`。
+ *
+ * @param fields - 一个 schema 对象的字段表：`{ 字段名: schemastery schema }`。
+ * @returns 每个字段都调用过 `.volatile()` 的字段表。
+ */
+export function volatileFields<T extends Record<string, Schemastery>>(fields: T): T {
+  return Object.fromEntries(
+    Object.entries(fields).map(([key, schema]) => [key, schema.volatile()]),
+  ) as T
+}
+
+/**
+ * volatile 字段解包。
+ *
+ * 0.1.7 的设置字段**全部标了 `.volatile()`**（理由见 `settings-volatile.ts`），而
+ * schemastery 对 volatile 字段解析出来的**不是值，是一个引用** —— `{ get(), set() }`。
+ * 核心插件也是这么用的：`dsh-agent-default-model` 读的是 `this.config.provider.get()`。
+ *
+ * 于是「配置解析出来是什么形状」在 0.1.7 变了：**schema 产出引用，解包这一层的责任
+ * 落在插件身上**。统一在这里解开一次，下游（迁移、runtime、路由）拿到的仍然是一份
+ * 普通值的 `KnowledgeConfig`；否则 `config.agentRoot` 会是一个对象，而它会一路传进
+ * `path.join()`。
+ *
+ * 普通值原样返回 —— 所以单元测试直接塞普通对象、或配置来自非 volatile 来源时，
+ * 行为都不变。
+ */
+export function unwrapVolatile<T>(value: unknown): T | undefined {
+  if (value === null || typeof value !== 'object') return value as T | undefined
+  const ref = value as { get?: () => T }
+  return typeof ref.get === 'function' ? ref.get() : (value as T)
+}
+
+/**
+ * 解一个**设置组**：组里的每个字段都过一次 `unwrapVolatile`。
+ *
+ * ## 为什么需要两层
+ *
+ * entry config 的形状是固定的 `{ 组名: { 字段: 引用 } }`（见 `config-schema.ts` 的
+ * `knowledge` / `intent` / `convert` 三组），而只解一层的结果是「组本身还是原始对象、
+ * 组里的字段还是引用」。
+ *
+ * 0029 实测到的故障就是这样来的：`intent` 组被原样交给 `applyIntent`，于是
+ * `engine.settings.predicates` 是一个 `{get, write}` 引用而不是字符串数组，
+ * `routingPrompt()` 里那句 `predicates.join('、')` 抛
+ * `this.settings.predicates.join is not a function`。抛出点在 **preset 的挂载行**上，
+ * 所以整个 preset 组合不出会话 —— 宿主平面没事（它在 apply 时不读谓词），一个字段
+ * 的类型错误把 preset 打挂。
+ *
+ * ## 为什么是两层而不是把 `unwrapVolatile` 写成递归
+ *
+ * 多出来的那一层是**已知的、唯一的一层**：组 → 字段。递归会把「数组里的对象恰好
+ * 有个 `get` 方法」也当成引用来解开 —— 那是猜，不是契约。
+ *
+ * @param group - schema 解析出来的一个设置组（字段可能是引用，也可能是普通值）。
+ * @returns 解包后的组；给 `undefined` 或非对象时返回 `{}`。
+ */
+export function unwrapGroup<T>(group: unknown): Partial<T> {
+  const plain = unwrapVolatile<Record<string, unknown>>(group)
+  if (plain === null || typeof plain !== 'object') return {}
+  return Object.fromEntries(
+    Object.entries(plain).map(([key, value]) => [key, unwrapVolatile(value)]),
+  ) as Partial<T>
+}
+
+/** 把一份可能带 volatile 引用的配置解成普通值。 */
+export function unwrapKnowledge(next: Partial<KnowledgeConfig> | undefined): Partial<KnowledgeConfig> {
+  return unwrapGroup<KnowledgeConfig>(next)
+}