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

package/lib/types/settings-volatile.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 declare function volatileFields<T extends Record<string, Schemastery>>(fields: T): 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 declare function unwrapVolatile<T>(value: unknown): T | undefined;
+/**
+ * 解一个**设置组**：组里的每个字段都过一次 `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 declare function unwrapGroup<T>(group: unknown): Partial<T>;
+/** 把一份可能带 volatile 引用的配置解成普通值。 */
+export declare function unwrapKnowledge(next: Partial<KnowledgeConfig> | undefined): Partial<KnowledgeConfig>;
+//# sourceMappingURL=settings-volatile.d.ts.map

package/lib/types/settings-volatile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-volatile.d.ts","sourceRoot":"","sources":["../../src/settings-volatile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,WAAW,MAAM,0BAA0B,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAIlF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,GAAG,SAAS,CAI/D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAMzD;AAED,kCAAkC;AAClC,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC,CAEpG"}

package/lib/types/settings-volatile.js

@@ -0,0 +1,114 @@
+/**
+ * 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
+ */
+/**
+ * 把一组字段全部标成 volatile。返回值仍是同一个对象形状，可以直接交给 `z.object()`。
+ *
+ * @param fields - 一个 schema 对象的字段表：`{ 字段名: schemastery schema }`。
+ * @returns 每个字段都调用过 `.volatile()` 的字段表。
+ */
+export function volatileFields(fields) {
+    return Object.fromEntries(Object.entries(fields).map(([key, schema]) => [key, schema.volatile()]));
+}
+/**
+ * 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(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    const ref = value;
+    return typeof ref.get === 'function' ? ref.get() : value;
+}
+/**
+ * 解一个**设置组**：组里的每个字段都过一次 `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(group) {
+    const plain = unwrapVolatile(group);
+    if (plain === null || typeof plain !== 'object')
+        return {};
+    return Object.fromEntries(Object.entries(plain).map(([key, value]) => [key, unwrapVolatile(value)]));
+}
+/** 把一份可能带 volatile 引用的配置解成普通值。 */
+export function unwrapKnowledge(next) {
+    return unwrapGroup(next);
+}
+//# sourceMappingURL=settings-volatile.js.map

package/lib/types/settings-volatile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-volatile.js","sourceRoot":"","sources":["../../src/settings-volatile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAKH;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAwC,MAAS;IAC7E,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CACnE,CAAA;AACR,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAI,KAAc;IAC9C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAsB,CAAA;IAC9E,MAAM,GAAG,GAAG,KAA0B,CAAA;IACtC,OAAO,OAAO,GAAG,CAAC,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAE,KAAW,CAAA;AACjE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,WAAW,CAAI,KAAc;IAC3C,MAAM,KAAK,GAAG,cAAc,CAA0B,KAAK,CAAC,CAAA;IAC5D,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAA;IAC1D,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAC5D,CAAA;AACjB,CAAC;AAED,kCAAkC;AAClC,MAAM,UAAU,eAAe,CAAC,IAA0C;IACxE,OAAO,WAAW,CAAkB,IAAI,CAAC,CAAA;AAC3C,CAAC"}