dsh-fingerprint 0.5.1 → 0.6.0

package/README.md

@@ -16,12 +16,12 @@ dsh-fingerprint 把 DSH 里已经配置好的 `provider/model` 路由当作审
 
 插件不保存 provider API key；认证和请求路由由 DSH 的 `llm` 服务处理。无法关闭 reasoning 的模型会被硬拦截，因为论文协议需要一次直接的单次 completion。
 
-这是一个手动使用的插件：正常操作都在 Web 面板里完成，默认不向 agent 注册工具，因此不占用模型上下文。需要让 agent 驱动采集做调试或自动化时，在面板底部的“设置”里把 Agent 工具开关打开即可，即时生效，不需要改配置文件。
+这是一个手动使用的插件：正常操作都在 Web 面板里完成，默认不向 agent 注册工具，因此不占用模型上下文。需要让 agent 驱动采集做调试或自动化时，在面板底部的“设置”里把 Agent 工具开关打开即可，即时生效。开关的值是插件 row 的 `config.tools`，存在 profile 的 `cordis.patch.yml`。
 
 ## 要求
 
-- 一个启用 Web GUI 的 DSH profile（需要 `llm`、`webServer` 服务；开启 agent 工具时还需要 `tools`）。
-- DSH 0.2 系列：安装、面板、API 与端到端采集已在 `0.2.1-rc.2`、`0.2.1-rc.4` 和 `0.2.2-rc.1` 上验证；面板的 Agent 工具开关和 settings API 在 `0.2.1-rc.5` 与 `0.2.2-rc.1` 上实测。`engines.dsh` 限定 `>=0.2.1-rc.2 <0.3.0-0`。DSH 0.2.2 起按 `engines.dsh` 判定插件兼容性，范围不覆盖当前运行时会拒绝安装，并在启动时跳过该 bundle（面板、API 和工具都不挂载）。
+- 一个启用 Web GUI 的 DSH profile（需要 `llm`、`webServer` 服务；开启 agent 工具时还需要 `tools`）。面板开关通过 profile 的 `configEditor` 写入 row config；profile 没有这个服务时开关只读，直接改 `cordis.patch.yml` 后重启生效。
+- DSH 0.2 系列：安装、面板、API 与端到端采集已在 `0.2.1-rc.2`、`0.2.1-rc.4` 和 `0.2.2-rc.1` 上验证；settings API 在 `0.2.1-rc.5` 与 `0.2.2-rc.1` 上实测。开关改为写 row config 之后，这条写入路径只在单元测试和 `0.2.1-rc.5` 的组合 schema 上验证过，尚未在 rc.2/rc.4/`0.2.2-rc.1` 上实跑。`engines.dsh` 限定 `>=0.2.1-rc.2 <0.3.0-0`。DSH 0.2.2 起按 `engines.dsh` 判定插件兼容性，范围不覆盖当前运行时会拒绝安装，并在启动时跳过该 bundle（面板、API 和工具都不挂载）。
 - 至少一个配置好的、能关闭 reasoning（`off` / `none`）或本身不推理的 provider/model。
 - Node.js（由 DSH 自带，无需单独安装）。
 
@@ -56,7 +56,7 @@ dsh plugin --profile web add github:Jerry2262/dsh-fingerprint
 5. 在“对比记录”里选两条记录，点“对比记录”。比较方式只有一种，结果会标注两边是否同一目标。
 6. 结果包含差异分数、判定线、结论、关系、cell 级差异和警告。低于判定线只说明差异小，不等于 100% 是同一个模型。
 7. 行内垃圾桶可以删除记录；删除前会二次确认。运行中的记录不能删除。
-8. 面板底部的“设置”里有 Agent 工具开关，默认关闭。开启后把 6 个 `llm_fingerprint_*` 工具暴露给 agent（每个请求多约 4.3 KB 工具 schema），关闭后立即从后续请求里移除；选择保存在数据目录的 `settings.json`，删掉这个文件即回到默认关闭。
+8. 面板底部的“设置”里有 Agent 工具开关，默认关闭。开启后把 6 个 `llm_fingerprint_*` 工具暴露给 agent（每个请求多约 4.3 KB 工具 schema），关闭后立即从后续请求里移除。开关的值是插件 row 的 `config.tools`，存在 profile 的 `cordis.patch.yml`；`tools` 是 volatile 字段，切换不会重载插件。
 
 ## 工作原理
 
@@ -70,7 +70,7 @@ dsh plugin --profile web add github:Jerry2262/dsh-fingerprint
 
 - 插件不保存 API key；key 留在 DSH 的 provider/credential 层。
 - 原始响应和指纹默认写到 `$DSH_HOME/llm-fingerprint/`，也可以由插件 row 的 `dataDir` 覆盖。
-- 面板设置（目前只有 Agent 工具开关）存在同一数据目录的 `settings.json`。
+- 面板设置（目前只有 Agent 工具开关）不在数据目录，它存在 profile 的 `cordis.patch.yml`（插件 row 的 `config.tools`）。
 - 删除记录会删除该目录下的 `meta.json`、`responses.jsonl` 和 `fingerprint.json`。
 - 无法关闭 reasoning 的模型不会被静默采集。
 

package/client.js

@@ -130,6 +130,7 @@ window.__ModuleLoader__.load({
       toolsTitle: 'Agent tools',
       toolsHint: 'Expose the six capture and compare tools to agents. Adds about 4.3 KB of tool schema to every request; useful for debugging or automation.',
       toolsUnavailable: 'This profile does not provide the tools service, so the switch cannot be turned on.',
+      toolsReadOnly: 'This profile does not expose the config editor, so change this switch in cordis.patch.yml.',
       toolsUpdated: 'Agent tool visibility updated.',
     };
 
@@ -255,6 +256,7 @@ window.__ModuleLoader__.load({
       toolsTitle: 'Agent 工具',
       toolsHint: '把 6 个采集、对比工具暴露给 agent。每个请求会多约 4.3 KB 工具 schema，适合调试或自动化。',
       toolsUnavailable: '当前 profile 没有 tools 服务，无法开启这个开关。',
+      toolsReadOnly: '当前 profile 没有 configEditor 服务，这个开关只能在 cordis.patch.yml 里改。',
       toolsUpdated: 'agent 工具开关已更新。',
     };
 
@@ -340,6 +342,7 @@ window.__ModuleLoader__.load({
       if (/unknown fingerprint record/i.test(text)) return t('errorRecordNotFound');
       if (/no completed fingerprint|two record ids|record id is required/i.test(text)) return t('errorRecordNeedsFingerprint');
       if (/tools service is unavailable/i.test(text)) return t('toolsUnavailable');
+      if (/configEditor service is unavailable/i.test(text)) return t('toolsReadOnly');
       return text;
     }
 
@@ -1083,6 +1086,7 @@ window.__ModuleLoader__.load({
       }
 
       const estimate = 40 * Math.max(10, Math.min(100, Number(reps) || 30));
+      const toolsLocked = !toolsSetting || savingTools || !toolsSetting.available || toolsSetting.editable === false;
 
       return h('div', { style: S.page },
         h('div', { style: S.inner, ref: pageRef },
@@ -1361,18 +1365,20 @@ window.__ModuleLoader__.load({
                 h('p', { style: { ...S.hint, margin: '4px 0 0' } }, t('toolsHint')),
                 toolsSetting && !toolsSetting.available
                   ? h('p', { style: { ...S.hint, margin: '4px 0 0', color: 'var(--dsw-alias-state-warn-primary)' } }, t('toolsUnavailable'))
-                  : null,
+                  : toolsSetting && toolsSetting.editable === false
+                    ? h('p', { style: { ...S.hint, margin: '4px 0 0', color: 'var(--dsw-alias-state-warn-primary)' } }, t('toolsReadOnly'))
+                    : null,
               ),
               h('button', {
                 type: 'button',
                 role: 'switch',
                 'aria-checked': Boolean(toolsSetting && toolsSetting.enabled),
                 'aria-label': t('toolsTitle'),
-                disabled: !toolsSetting || savingTools || !toolsSetting.available,
+                disabled: toolsLocked,
                 style: {
                   ...S.switch,
                   ...(toolsSetting && toolsSetting.enabled ? S.switchOn : {}),
-                  ...(!toolsSetting || savingTools || !toolsSetting.available ? S.disabled : {}),
+                  ...(toolsLocked ? S.disabled : {}),
                 },
                 onClick: toggleTools,
               }, h('span', {

package/docs/DESIGN.md

@@ -8,7 +8,7 @@
 - **指纹记录**：对某个目标在某一时刻做一次完整采集的结果。记录本身就是指纹，包含 40 个 cell 的经验答案分布和派生统计。
 - **对比**：任意两条记录之间的同一个操作。跨模型、跨服务商、同一目标的前后两次，都是同一个比较操作，只有 `relation` 标签不同。
 - **单一实现**：Host service 是唯一操作层；Web 面板通过 HTTP API 调用，可选的 agent 工具调用同一组方法。
-- **默认手动**：插件默认不向 agent 注册工具，所有操作在面板里完成，因此不占用模型上下文；面板“设置”里的开关打开时才注册 6 个 agent 工具，选择持久化在数据目录的 `settings.json`。
+- **默认手动**：插件默认不向 agent 注册工具，所有操作在面板里完成，因此不占用模型上下文；面板“设置”里的开关打开时才注册 6 个 agent 工具。开关对应 volatile 的 `tools` row config，值存在 profile 的 `cordis.patch.yml`。
 
 ## 2. 协议常量
 
@@ -37,7 +37,6 @@ llm-fingerprint/
     responses.jsonl    # 每条成功请求一行，append-only
     fingerprint.json   # 派生分布、valid rate、分半一致性、cell 明细
   probes/<probe-id>.json
-  settings.json        # 面板设置（目前只有 agent 工具开关）
 ```
 
 - 记录 id 形如 `cp-20261020T034450-59c80896`，服务端用严格格式校验，防止路径穿越。
@@ -62,7 +61,7 @@ llm-fingerprint/
 - `GET /settings`
 - `POST /settings/tools`
 
-所有操作都在 `createService(ctx, root)` 返回的同一组方法里实现。面板“设置”里的 Agent 工具开关调用 `POST /settings/tools`：Host 按需通过 `ctx.inject(['tools'], ...)` 注册 6 个 agent 工具（`llm_fingerprint_list_models` / `probe` / `capture` / `get_record` / `compare` / `delete_record`），关闭时 dispose 该子 fiber 立即注销；默认关闭，因此不要求 profile 提供 `tools` 服务。开关选择持久化在数据目录的 `settings.json`，插件重载后恢复。
+所有操作都在 `createService(ctx, root)` 返回的同一组方法里实现。面板“设置”里的 Agent 工具开关调用 `POST /settings/tools`，Host 通过 `ctx.configEditor.edit()` 把 `config.tools` 写回 profile 的 `cordis.patch.yml`。`tools` 在 `Config` 里声明为 `.volatile()`：Loader 对这类变更不重载插件，只更新运行中的配置引用并发 `loader/volatile-update`，插件据此注册 6 个 agent 工具（`llm_fingerprint_list_models` / `probe` / `capture` / `get_record` / `compare` / `delete_record`）或 dispose 注册它们的子 fiber。默认关闭，因此不要求 profile 提供 `tools` 服务；profile 没有 `configEditor` 时开关只读，直接改 patch 后重启生效。
 
 目标发现：
 
@@ -148,5 +147,6 @@ llm-fingerprint/
 - 提示词版本写在 `prompts.json` 的 `version` 和每条记录的 `promptVersion`；改提示词需要重新采集，旧记录不能直接和新记录混比。
 - 判定线常量在 `core.js` 的 `CUTOFF`；修改时需要同步 README/DESIGN 并说明校准来源。
 - 数据目录 append-only；分析产物可以删除后从 `responses.jsonl` 重新计算。
-- 面板设置只有 agent 工具开关，写在数据目录的 `settings.json`；删除该文件即恢复默认关闭，不影响记录数据。
+- 面板设置只有 agent 工具开关，写在 profile 的 `cordis.patch.yml` 里插件 row 的 `config.tools`；删掉该字段即恢复默认关闭，不影响记录数据。
 - 代码无构建步骤；`npm run check` 做三个 JS 文件的语法检查，`npm test` 跑核心与插件注册回归测试。
+- 唯一的运行时依赖是 `@deepseek-ai/schemastery`，用于声明 `Config`；其余只用 Node 内置模块。

package/index.js

@@ -9,7 +9,8 @@
  * The service methods back the HTTP API that the Web panel calls; there is one
  * implementation of every operation. The panel is the normal surface; its
  * settings section can optionally expose the six agent tools, which stay out of
- * the model context while the toggle is off (the default).
+ * the model context unless the volatile `tools` row config is on (off by
+ * default, and always reachable from the panel).
  */
 import { randomUUID } from 'node:crypto';
 import {
@@ -25,6 +26,8 @@ import {
 import os from 'node:os';
 import path from 'node:path';
 
+import Schema from '@deepseek-ai/schemastery';
+
 import {
   CELLS,
   CUTOFF,
@@ -41,6 +44,20 @@ import {
 
 export const inject = ['llm', 'webServer'];
 
+/**
+ * The plugin's row config. `tools` is volatile: the panel switch and the
+ * Settings form edit the value stored in the profile patch, and a volatile-only
+ * change updates this running config reference and emits
+ * `loader/volatile-update` instead of reloading the plugin.
+ */
+export const Config = Schema.object({
+  dataDir: Schema.string().default('').description('记录和探测日志的数据目录，默认 $DSH_HOME/llm-fingerprint。'),
+  tools: Schema.boolean()
+    .default(false)
+    .description('把 6 个采集、对比工具（llm_fingerprint_*）暴露给 agent。每个请求会多约 4.3 KB 工具 schema，适合调试或自动化。')
+    .volatile(),
+});
+
 const CONCURRENCY = 8;
 const REQUEST_TIMEOUT_MS = 90_000;
 const MAX_TOKENS = 16;
@@ -947,39 +964,20 @@ function toolDefinitions(service) {
   ];
 }
 
-const AGENT_TOOLS_SETTINGS_FILE = 'settings.json';
-
-/** Read the persisted panel preferences; unreadable or malformed files fall back to the defaults. */
-function readSettings(file) {
-  try {
-    const value = JSON.parse(readFileSync(file, 'utf8'));
-    return { tools: value?.tools === true };
-  } catch {
-    return { tools: false };
-  }
-}
-
-/** Persist the panel preferences. Write failures surface to the caller instead of being swallowed. */
-function writeSettings(file, settings) {
-  writeFileSync(file, `${JSON.stringify({ tools: settings.tools === true }, null, 2)}\n`);
-}
-
 /**
  * Own the optional agent tool surface: the six tools are registered exactly
- * while the Web panel's toggle is on.
+ * while the `tools` row config is on.
  *
- * The setting persists in the plugin's data directory (`settings.json`) and
- * defaults to off, so a fresh install adds no tool definitions to the model
- * context. Registration waits for the `tools` service through `ctx.inject`;
- * turning the toggle off disposes that child fiber, which unregisters the tools
- * immediately — no profile reload or DSH restart involved.
+ * The value lives in the profile patch and defaults to off, so a fresh install
+ * adds no tool definitions to the model context. Registration waits for the
+ * `tools` service through `ctx.inject`; turning the switch off disposes that
+ * child fiber, which unregisters the tools immediately.
  */
-function createAgentTools(ctx, service, root) {
-  const file = path.join(root, AGENT_TOOLS_SETTINGS_FILE);
-  let settings = readSettings(file);
+function createAgentTools(ctx, service, config) {
   let fiber;
 
-  const status = () => ({ enabled: settings.tools, available: Boolean(ctx.get('tools')) });
+  const enabled = () => config.tools?.get?.() === true;
+  const status = () => ({ enabled: enabled(), available: Boolean(ctx.get('tools')) });
   const start = () => {
     if (fiber !== undefined) return;
     fiber = ctx.inject(['tools'], function registerFingerprintTools(toolCtx) {
@@ -993,20 +991,25 @@ function createAgentTools(ctx, service, root) {
     fiber = undefined;
     if (current !== undefined) await current.dispose();
   };
-  const setEnabled = async (enabled) => {
-    if (enabled === true && !ctx.get('tools')) {
-      throw new Error('the tools service is unavailable in this profile, so agent tools cannot be enabled');
-    }
-    const next = { tools: enabled === true };
-    writeSettings(file, next);
-    settings = next;
-    if (settings.tools) start();
+  const sync = async () => {
+    if (enabled()) start();
     else await stop();
-    return status();
   };
 
-  if (settings.tools) start();
-  return { status, setEnabled };
+  if (enabled()) start();
+  return { status, sync };
+}
+
+/**
+ * The profile row that owns this plugin instance, when the active profile
+ * exposes the config editor. The panel switch writes the row config through it;
+ * without it the switch stays read-only and `cordis.patch.yml` is the way in.
+ */
+function ownConfigEntry(ctx) {
+  const editor = ctx.get('configEditor');
+  const uid = ctx.fiber?.uid;
+  if (!editor || uid === undefined) return undefined;
+  return editor.entries().find((entry) => entry.fiber?.uid === uid);
 }
 
 function sendJson(res, status, value) {
@@ -1085,13 +1088,22 @@ async function handleApi(ctx, req, res, service, agentTools) {
       return;
     }
     if (req.method === 'GET' && pathname === '/settings') {
-      sendJson(res, 200, { tools: agentTools.status() });
+      sendJson(res, 200, { tools: { ...agentTools.status(), editable: ownConfigEntry(ctx) !== undefined } });
       return;
     }
     if (req.method === 'POST' && pathname === '/settings/tools') {
       const body = await readRequestBody(req);
       if (typeof body.enabled !== 'boolean') throw new Error('enabled must be a boolean');
-      sendJson(res, 200, { tools: await agentTools.setEnabled(body.enabled) });
+      if (body.enabled === true && !ctx.get('tools')) {
+        throw new Error('the tools service is unavailable in this profile, so agent tools cannot be enabled');
+      }
+      const editor = ctx.get('configEditor');
+      const entry = ownConfigEntry(ctx);
+      if (!editor || entry === undefined) {
+        throw new Error('the configEditor service is unavailable in this profile, so the switch can only be changed in cordis.patch.yml');
+      }
+      await editor.edit(entry, (current) => ({ ...current, tools: body.enabled }));
+      sendJson(res, 200, { tools: { ...agentTools.status(), editable: true } });
       return;
     }
     const match = pathname.match(/^\/checkpoints\/([^/]+)$/);
@@ -1118,7 +1130,10 @@ export function apply(ctx, config = {}) {
   const lifetime = new AbortController();
   ctx.effect(() => () => { lifetime.abort(); }, 'llm-fingerprint: abort running captures');
   const service = createService(ctx, root, lifetime.signal);
-  const agentTools = createAgentTools(ctx, service, root);
+  const agentTools = createAgentTools(ctx, service, config);
+  ctx.on('loader/volatile-update', () => {
+    agentTools.sync().catch((error) => ctx.logger?.warn?.(error));
+  });
   ctx.effect(
     () => ctx.webServer.register({
       kind: 'prefix',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-fingerprint",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
   "description": "Paper-protocol fingerprint records and comparison panel for configured DSH provider/model routes.",
   "license": "MIT",
@@ -60,5 +60,8 @@
   },
   "engines": {
     "dsh": ">=0.2.1-rc.2 <0.3.0-0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.5"
   }
 }