dsh-fingerprint 0.3.1 → 0.4.0

package/README.md

@@ -16,10 +16,12 @@ dsh-fingerprint 把 DSH 里已经配置好的 `provider/model` 路由当作审
 
 插件不保存 provider API key；认证和请求路由由 DSH 的 `llm` 服务处理。无法关闭 reasoning 的模型会被硬拦截，因为论文协议需要一次直接的单次 completion。
 
+这是一个手动使用的插件：正常操作都在 Web 面板里完成，默认不向 agent 注册工具，因此不占用模型上下文。需要让 agent 驱动采集做调试或自动化时，在面板底部的“设置”里把 Agent 工具开关打开即可，即时生效，不需要改配置文件。
+
 ## 要求
 
-- 一个启用 Web GUI 的 DSH profile（需要 `llm`、`tools`、`webServer` 服务）。
-- DSH 0.2.1 系列：实测 `0.2.1-rc.2` 和 `0.2.1-rc.4`，`engines.dsh` 限定 `>=0.2.1-rc.2 <0.2.2-0`。
+- 一个启用 Web GUI 的 DSH profile（需要 `llm`、`webServer` 服务；开启 agent 工具时还需要 `tools`）。
+- DSH 0.2.1 系列：安装、面板、API 与端到端采集已在 `0.2.1-rc.2` 和 `0.2.1-rc.4` 上验证；面板的 Agent 工具开关和 settings API 在 `0.2.1-rc.5` 上实测。`engines.dsh` 限定 `>=0.2.1-rc.2 <0.2.2-0`。
 - 至少一个配置好的、能关闭 reasoning（`off` / `none`）或本身不推理的 provider/model。
 - Node.js（由 DSH 自带，无需单独安装）。
 
@@ -53,19 +55,7 @@ dsh plugin --profile web add github:Jerry2262/dsh-fingerprint
 4. 在“对比记录”里选两条记录，点“对比记录”。比较方式只有一种，结果会标注两边是否同一目标。
 5. 结果包含差异分数、判定线、结论、关系、cell 级差异和警告。低于判定线只说明差异小，不等于 100% 是同一个模型。
 6. 行内垃圾桶可以删除记录；删除前会二次确认。运行中的记录不能删除。
-
-## Agent 工具
-
-Host 服务同时暴露给 agent：
-
-- `llm_fingerprint_list_models`
-- `llm_fingerprint_probe`
-- `llm_fingerprint_capture`
-- `llm_fingerprint_get_record`
-- `llm_fingerprint_compare`
-- `llm_fingerprint_delete_record`
-
-UI 和工具调用同一个 Host 服务，不维护第二套逻辑。
+7. 面板底部的“设置”里有 Agent 工具开关，默认关闭。开启后把 6 个 `llm_fingerprint_*` 工具暴露给 agent（每个请求多约 4.3 KB 工具 schema），关闭后立即从后续请求里移除；选择保存在数据目录的 `settings.json`，删掉这个文件即回到默认关闭。
 
 ## 工作原理
 
@@ -79,6 +69,7 @@ UI 和工具调用同一个 Host 服务，不维护第二套逻辑。
 
 - 插件不保存 API key；key 留在 DSH 的 provider/credential 层。
 - 原始响应和指纹默认写到 `$DSH_HOME/llm-fingerprint/`，也可以由插件 row 的 `dataDir` 覆盖。
+- 面板设置（目前只有 Agent 工具开关）存在同一数据目录的 `settings.json`。
 - 删除记录会删除该目录下的 `meta.json`、`responses.jsonl` 和 `fingerprint.json`。
 - 无法关闭 reasoning 的模型不会被静默采集。
 
@@ -93,14 +84,14 @@ UI 和工具调用同一个 Host 服务，不维护第二套逻辑。
 
 ## 开发
 
-- `index.js`：Host plugin，`llm` / `webServer` service、agent tools、HTTP API。
+- `index.js`：Host plugin，`llm` / `webServer` service、HTTP API；面板开关开启时另注册 6 个 agent 工具。
 - `core.js`：协议常量、提示词 battery、归一化、JSD、指纹与对比。
 - `client.js`：Web 面板（`main` + `sidebar.panellist`）、详情抽屉、对比与删除确认。
 - `prompts.json`：论文 paper-1 的 10 个任务 × 4 种语言。
 - `locale/`：插件元数据和 UI 文案。
 - `docs/DESIGN.md`：设计细节。
 - `npm run check`：JS 语法检查（无构建步骤）。
-- `npm test`：核心回归测试（判定线、覆盖门槛、协议拒绝、重复 cell 与主要答案）。
+- `npm test`：核心与插件注册回归测试（判定线、覆盖门槛、协议拒绝、重复 cell、主要答案，以及 agent 工具默认关闭/开关注册）。
 
 ## 许可与来源
 

package/client.js

@@ -120,6 +120,11 @@ window.__ModuleLoader__.load({
       referenceValidity: 'valid rate 97.6% overall, per-model median 99.6%',
       referenceSplitHalf: 'split-half JSD 0.140 for the same model, 0.463 for different models',
       referenceScore: 'The cutoff is 0.280, the 1st percentile of different-model distances: in 100 different models, about 1 would still look the same.',
+      settingsTitle: 'Settings',
+      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.',
+      toolsUpdated: 'Agent tool visibility updated.',
     };
 
     const zh = {
@@ -234,6 +239,11 @@ window.__ModuleLoader__.load({
       referenceValidity: '有效率总体 97.6%，模型内中位 99.6%',
       referenceSplitHalf: '同一模型的分半差异通常 0.140，不同模型通常 0.463',
       referenceScore: '判定线是 0.280，取自不同模型距离的 1% 分位：100 个不同模型里，大约只有 1 个会被看成相同。',
+      settingsTitle: '设置',
+      toolsTitle: 'Agent 工具',
+      toolsHint: '把 6 个采集、对比工具暴露给 agent。每个请求会多约 4.3 KB 工具 schema，适合调试或自动化。',
+      toolsUnavailable: '当前 profile 没有 tools 服务，无法开启这个开关。',
+      toolsUpdated: 'agent 工具开关已更新。',
     };
 
     async function api(path, init) {
@@ -307,6 +317,7 @@ window.__ModuleLoader__.load({
       if (/still running/i.test(text)) return t('errorStillRunning');
       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');
       return text;
     }
 
@@ -444,6 +455,39 @@ window.__ModuleLoader__.load({
         fontSize: '11px',
         cursor: 'pointer',
       },
+      settingRow: {
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        gap: '20px',
+      },
+      switch: {
+        position: 'relative',
+        flex: 'none',
+        width: '38px',
+        height: '22px',
+        padding: 0,
+        borderRadius: '999px',
+        border: '1px solid var(--dsw-alias-border-l2)',
+        background: 'var(--dsw-alias-bg-layer-2)',
+        cursor: 'pointer',
+        transition: 'background .15s ease, border-color .15s ease',
+      },
+      switchOn: {
+        background: 'var(--dsw-alias-brand-primary)',
+        borderColor: 'var(--dsw-alias-brand-primary)',
+      },
+      switchKnob: {
+        position: 'absolute',
+        top: '2px',
+        left: '2px',
+        width: '16px',
+        height: '16px',
+        borderRadius: '50%',
+        background: '#fff',
+        boxShadow: '0 1px 2px rgba(0, 0, 0, 0.3)',
+        transition: 'transform .15s ease',
+      },
       iconButton: {
         display: 'inline-flex',
         alignItems: 'center',
@@ -707,6 +751,8 @@ window.__ModuleLoader__.load({
       const [detail, setDetail] = useState(null);
       const [detailId, setDetailId] = useState('');
       const [compact, setCompact] = useState(false);
+      const [toolsSetting, setToolsSetting] = useState(null);
+      const [savingTools, setSavingTools] = useState(false);
       const resultRef = useRef(null);
       const pageRef = useRef(null);
 
@@ -738,8 +784,13 @@ window.__ModuleLoader__.load({
         let cancelled = false;
         (async () => {
           try {
-            const [targetData, checkpointData] = await Promise.all([api('/targets'), api('/checkpoints')]);
+            const [targetData, checkpointData, settingsData] = await Promise.all([
+              api('/targets'),
+              api('/checkpoints'),
+              api('/settings').catch(() => null),
+            ]);
             if (cancelled) return;
+            if (settingsData) setToolsSetting(settingsData.tools || null);
             const providers = (targetData.providers || []).filter((entry) => (entry.models || []).length > 0);
             setTargets(providers);
             setCheckpoints(checkpointData.checkpoints || []);
@@ -894,6 +945,25 @@ window.__ModuleLoader__.load({
         }
       }
 
+      async function toggleTools() {
+        if (!toolsSetting || savingTools) return;
+        setSavingTools(true);
+        setError('');
+        setNotice('');
+        try {
+          const data = await api('/settings/tools', {
+            method: 'POST',
+            body: JSON.stringify({ enabled: !toolsSetting.enabled }),
+          });
+          setToolsSetting(data.tools);
+          setNotice(t('toolsUpdated'));
+        } catch (cause) {
+          setError(friendlyError(cause.message || cause, t));
+        } finally {
+          setSavingTools(false);
+        }
+      }
+
       const estimate = 40 * Math.max(10, Math.min(100, Number(reps) || 30));
 
       return h('div', { style: S.page },
@@ -1144,6 +1214,36 @@ window.__ModuleLoader__.load({
                 : null,
             ) : null,
           ),
+
+          h(Section, { title: t('settingsTitle') },
+            h('div', { style: S.settingRow },
+              h('div', { style: { minWidth: 0 } },
+                h('div', { style: { fontSize: '13px', fontWeight: 600 } }, t('toolsTitle')),
+                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,
+              ),
+              h('button', {
+                type: 'button',
+                role: 'switch',
+                'aria-checked': Boolean(toolsSetting && toolsSetting.enabled),
+                'aria-label': t('toolsTitle'),
+                disabled: !toolsSetting || savingTools || !toolsSetting.available,
+                style: {
+                  ...S.switch,
+                  ...(toolsSetting && toolsSetting.enabled ? S.switchOn : {}),
+                  ...(!toolsSetting || savingTools || !toolsSetting.available ? S.disabled : {}),
+                },
+                onClick: toggleTools,
+              }, h('span', {
+                style: {
+                  ...S.switchKnob,
+                  transform: toolsSetting && toolsSetting.enabled ? 'translateX(16px)' : 'none',
+                },
+              })),
+            ),
+          ),
         ),
         detail ? h('div', {
           style: S.drawerOverlay,

package/docs/DESIGN.md

@@ -7,14 +7,15 @@
 - **审计目标**：DSH 已配置的一条 provider 路由 + 一个 model id。插件不维护自己的端点表，也不保存 API key。
 - **指纹记录**：对某个目标在某一时刻做一次完整采集的结果。记录本身就是指纹，包含 40 个 cell 的经验答案分布和派生统计。
 - **对比**：任意两条记录之间的同一个操作。跨模型、跨服务商、同一目标的前后两次，都是同一个比较操作，只有 `relation` 标签不同。
-- **单一实现**：Host service 是唯一操作层；agent 工具和 Web 面板都是调用方。
+- **单一实现**：Host service 是唯一操作层；Web 面板通过 HTTP API 调用，可选的 agent 工具调用同一组方法。
+- **默认手动**：插件默认不向 agent 注册工具，所有操作在面板里完成，因此不占用模型上下文；面板“设置”里的开关打开时才注册 6 个 agent 工具，选择持久化在数据目录的 `settings.json`。
 
 ## 2. 协议常量
 
 论文：Bruckner, *One Token Is Enough*，arXiv:2607.10252。
 
 - 10 个任务 × 4 种语言（en / ru / zh / ar）= 40 个 cell。
-- 每个 cell 默认 30 次重复；UI 最低 10，API/tool 允许更低用于诊断。
+- 每个 cell 默认 30 次重复；UI 最低 10，HTTP API 和可选的 agent 工具允许更低用于诊断。
 - `temperature=1.0`，`max_tokens=16`，每个 cell 使用对应语言的固定单词 system prompt。
 - reasoning 必须关闭；不能关闭的模型不进入采集。
 - 答案归一化：Unicode NFC、去标点/引号、case fold、阿拉伯-印度数字和中文数字映射、取首个词；每条响应归为 `valid` / `invalid` / `refusal` / `empty`，带 reasoning trace 的标为 `post_reasoning` 并从有效分布中排除。
@@ -36,6 +37,7 @@ llm-fingerprint/
     responses.jsonl    # 每条成功请求一行，append-only
     fingerprint.json   # 派生分布、valid rate、分半一致性、cell 明细
   probes/<probe-id>.json
+  settings.json        # 面板设置（目前只有 agent 工具开关）
 ```
 
 - 记录 id 形如 `cp-20261020T034450-59c80896`，服务端用严格格式校验，防止路径穿越。
@@ -48,18 +50,19 @@ llm-fingerprint/
 
 ## 4. Host 结构
 
-`index.js` 通过 `apply(ctx, config)` 注册：
+`index.js` 通过 `apply(ctx, config)` 注册一个 HTTP API，prefix `/llm-fingerprint/api`，供 Web 面板调用：
 
-- 六个 agent 工具：`llm_fingerprint_list_models`、`probe`、`capture`、`get_record`、`compare`、`delete_record`。
-- 一个 HTTP API，prefix `/llm-fingerprint/api`，供 Web 面板调用：
-  - `GET /targets`
-  - `GET /checkpoints`
-  - `POST /checkpoints`
-  - `GET /checkpoints/:id`
-  - `DELETE /checkpoints/:id`
-  - `POST /compare`
-  - `POST /probe`
-- 所有操作都在 `createService(ctx, root)` 返回的同一组方法里实现。
+- `GET /targets`
+- `GET /checkpoints`
+- `POST /checkpoints`
+- `GET /checkpoints/:id`
+- `DELETE /checkpoints/:id`
+- `POST /compare`
+- `POST /probe`
+- `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`，插件重载后恢复。
 
 目标发现：
 
@@ -87,7 +90,7 @@ llm-fingerprint/
 
 - UI 模型下拉里仍然列出，但 `disabled`，文本标注“不可关闭推理”；
 - 服务商下所有模型都不可用时，服务商选项标注“无可用模型”，模型选择禁用，Start 禁用，并显示原因；
-- Host `startCheckpoint` 再检查一次，API 和 agent 工具都无法绕过；
+- Host `startCheckpoint` 再检查一次，HTTP API 和 agent 工具都无法绕过；
 - `probe` 仍然可以用于诊断，但不会创建记录。
 
 这套判断完全由运行时配置/适配器元数据计算，不维护模型名黑名单。给某个模型在 DSH 配置里加上 `off` 映射后，它会自动变为可用，不需要改插件代码。
@@ -124,11 +127,12 @@ llm-fingerprint/
 
 ## 8. 限制与不做的事
 
-- 兼容范围：`engines.dsh` 限定 DSH 0.2.1 系列（`>=0.2.1-rc.2 <0.2.2-0`）；已在 rc.2 和 rc.4 验证安装、面板、API 与一次端到端采集。0.2.2 及以后需重新测试再放宽。
+- 兼容范围：`engines.dsh` 限定 DSH 0.2.1 系列（`>=0.2.1-rc.2 <0.2.2-0`）；安装、面板、API 与一次端到端采集已在 rc.2 和 rc.4 验证，面板 Agent 工具开关与 settings API 在 rc.5 上实测。0.2.2 及以后需重新测试再放宽。
 - 不做 post-reasoning 指纹模式；只能 reasoning 的模型被拒绝。
 - 不读取/保存 provider key；认证由 DSH 适配器负责。
 - 不读取 provider 返回的 model 字符串或聚合器上游路由；`ctx.llm.stream` 不暴露这些。
 - 不把“分布不一致”解释成“供应商故意掺水”；它只是可观察行为差异。
+- agent 工具默认关闭，由面板“设置”里的开关控制；开启后 6 个工具定义会进入每个请求的上下文（实测约 4.3 KB / 1.2K tokens），这是调试或自动化的成本，不是面板的依赖。
 - 不实现自动定时巡检、多端点距离矩阵、CSV 导出、自定义 battery 编辑器；这些是后续功能。
 
 ## 9. 维护
@@ -136,4 +140,5 @@ llm-fingerprint/
 - 提示词版本写在 `prompts.json` 的 `version` 和每条记录的 `promptVersion`；改提示词需要重新采集，旧记录不能直接和新记录混比。
 - 判定线常量在 `core.js` 的 `CUTOFF`；修改时需要同步 README/DESIGN 并说明校准来源。
 - 数据目录 append-only；分析产物可以删除后从 `responses.jsonl` 重新计算。
-- 代码无构建步骤；`npm run check` 做三个 JS 文件的语法检查，`npm test` 跑核心回归测试。
+- 面板设置只有 agent 工具开关，写在数据目录的 `settings.json`；删除该文件即恢复默认关闭，不影响记录数据。
+- 代码无构建步骤；`npm run check` 做三个 JS 文件的语法检查，`npm test` 跑核心与插件注册回归测试。

package/index.js

@@ -6,9 +6,10 @@
  * the per-cell empirical answer distribution. Any two records compare with the
  * same operation and the same decision cutoff.
  *
- * The same service methods serve three callers: agent tools, the web API used
- * by the panel, and the panel's polling reads. There is one implementation of
- * every operation.
+ * 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).
  */
 import { randomUUID } from 'node:crypto';
 import {
@@ -38,7 +39,7 @@ import {
   topAnswerOf,
 } from './core.js';
 
-export const inject = ['llm', 'tools', 'webServer'];
+export const inject = ['llm', 'webServer'];
 
 const CONCURRENCY = 8;
 const REQUEST_TIMEOUT_MS = 90_000;
@@ -926,6 +927,68 @@ 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.
+ *
+ * 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.
+ */
+function createAgentTools(ctx, service, root) {
+  const file = path.join(root, AGENT_TOOLS_SETTINGS_FILE);
+  let settings = readSettings(file);
+  let fiber;
+
+  const status = () => ({ enabled: settings.tools, available: Boolean(ctx.get('tools')) });
+  const start = () => {
+    if (fiber !== undefined) return;
+    fiber = ctx.inject(['tools'], function registerFingerprintTools(toolCtx) {
+      for (const definition of toolDefinitions(service)) {
+        toolCtx.effect(() => toolCtx.tools.register(definition), `llm-fingerprint: ${definition.name}`);
+      }
+    });
+  };
+  const stop = async () => {
+    const current = fiber;
+    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();
+    else await stop();
+    return status();
+  };
+
+  if (settings.tools) start();
+  return { status, setEnabled };
+}
+
 function sendJson(res, status, value) {
   if (res.headersSent) return;
   res.statusCode = status;
@@ -970,7 +1033,7 @@ function rejectUnauthenticated(ctx, req, res) {
   return true;
 }
 
-async function handleApi(ctx, req, res, service) {
+async function handleApi(ctx, req, res, service, agentTools) {
   if (rejectUnauthenticated(ctx, req, res)) return;
   if (req.method === 'OPTIONS') {
     res.statusCode = 204;
@@ -1001,6 +1064,16 @@ async function handleApi(ctx, req, res, service) {
       sendJson(res, 200, await service.compare(body.a, body.b));
       return;
     }
+    if (req.method === 'GET' && pathname === '/settings') {
+      sendJson(res, 200, { tools: agentTools.status() });
+      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) });
+      return;
+    }
     const match = pathname.match(/^\/checkpoints\/([^/]+)$/);
     if (req.method === 'GET' && match) {
       sendJson(res, 200, await service.getCheckpoint(decodeURIComponent(match[1])));
@@ -1025,14 +1098,12 @@ 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);
-  for (const definition of toolDefinitions(service)) {
-    ctx.effect(() => ctx.tools.register(definition), `llm-fingerprint: ${definition.name}`);
-  }
+  const agentTools = createAgentTools(ctx, service, root);
   ctx.effect(
     () => ctx.webServer.register({
       kind: 'prefix',
       path: API_PREFIX,
-      handler: (req, res) => handleApi(ctx, req, res, service),
+      handler: (req, res) => handleApi(ctx, req, res, service, agentTools),
     }),
     'llm-fingerprint: http api',
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-fingerprint",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Paper-protocol fingerprint records and comparison panel for configured DSH provider/model routes.",
   "license": "MIT",
@@ -40,7 +40,7 @@
   ],
   "scripts": {
     "check": "node --check index.js && node --check core.js && node --check client.js",
-    "test": "node --test test/core.test.js"
+    "test": "node --test test/core.test.js test/plugin.test.js"
   },
   "dsh": {
     "bundle": {