dsh-fingerprint 0.3.1 → 0.5.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 自带，无需单独安装）。
 
@@ -48,24 +50,13 @@ dsh plugin --profile web add github:Jerry2262/dsh-fingerprint
 ## 使用
 
 1. 选择服务商和模型。不能关闭 reasoning 的模型会置灰、不可选，并标注原因。
-2. 设置每个 cell 的重复次数（默认 30，UI 最低 10），点“开始采集”。
-3. 运行中的记录显示进度；完成后显示有效率、分半 JSD、纳入 cell 数。插件被卸载或进程重启时，未完成的记录会标为失败（保留已抓到的响应），可以直接删除，不会自动续跑。
-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 服务，不维护第二套逻辑。
+2. 点“检测可行性”。它用 2 个 cell × 3 次（6 个请求）实际发一次，确认这条路由能给出单词答案且不带 reasoning trace；通过后“开始采集”才可用，换服务商或模型会要求重新检测。模型元数据说支持 `off` 不代表服务商真的照做，这一步是唯一能提前发现的地方。
+3. 设置每个 cell 的重复次数（默认 30，UI 最低 10），点“开始采集”。
+4. 运行中的记录显示进度；完成后显示有效率、分半 JSD、纳入 cell 数。插件被卸载或进程重启时，未完成的记录会标为失败（保留已抓到的响应），可以直接删除，不会自动续跑。
+5. 在“对比记录”里选两条记录，点“对比记录”。比较方式只有一种，结果会标注两边是否同一目标。
+6. 结果包含差异分数、判定线、结论、关系、cell 级差异和警告。低于判定线只说明差异小，不等于 100% 是同一个模型。
+7. 行内垃圾桶可以删除记录；删除前会二次确认。运行中的记录不能删除。
+8. 面板底部的“设置”里有 Agent 工具开关，默认关闭。开启后把 6 个 `llm_fingerprint_*` 工具暴露给 agent（每个请求多约 4.3 KB 工具 schema），关闭后立即从后续请求里移除；选择保存在数据目录的 `settings.json`，删掉这个文件即回到默认关闭。
 
 ## 工作原理
 
@@ -79,6 +70,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 +85,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

@@ -64,6 +64,12 @@ window.__ModuleLoader__.load({
       noCompatibleModels: 'This provider has no model that can disable reasoning.',
       noCompatibleModelsShort: 'No models eligible for capture',
       offAvailable: 'Reasoning will be disabled (off) for capture.',
+      checkTitle: 'Check feasibility',
+      checking: 'Checking…',
+      checkHint: 'Sends 2 cells × 3 samples (6 requests) to confirm this route answers in one word without a reasoning trace.',
+      checkRequired: 'Run the feasibility check first: it confirms the route satisfies the protocol in 6 requests instead of discovering it after the full battery.',
+      checkPassed: 'Feasibility check passed: {valid}/{responses} one-word answers, {leak} with a reasoning trace.',
+      checkFailed: 'Feasibility check failed: {valid}/{responses} one-word answers, {leak} with a reasoning trace, {errors} failed requests.',
       effort: 'Reasoning effort',
       started: 'Capture started:',
       error: 'Error',
@@ -120,6 +126,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 = {
@@ -178,6 +189,12 @@ window.__ModuleLoader__.load({
       noCompatibleModels: '该服务商没有支持关闭推理的模型，不能用于论文协议。',
       noCompatibleModelsShort: '无符合采集条件的模型',
       offAvailable: '采集时将关闭推理（off）。',
+      checkTitle: '检测可行性',
+      checking: '检测中…',
+      checkHint: '先用 2 个 cell × 3 次（6 个请求）确认这条路由能给出单词答案，且不带 reasoning trace。',
+      checkRequired: '请先检测可行性：用 6 个请求确认这条路由满足论文协议，避免跑完 1200 个请求才发现结果无效。',
+      checkPassed: '可行性检测通过：{valid}/{responses} 个单词答案，{leak} 个带 reasoning trace。',
+      checkFailed: '可行性检测未通过：{valid}/{responses} 个单词答案，{leak} 个带 reasoning trace，{errors} 个请求失败。',
       effort: '推理档位',
       started: '指纹采集已开始：',
       error: '错误',
@@ -234,6 +251,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) {
@@ -299,6 +321,16 @@ window.__ModuleLoader__.load({
       return text;
     }
 
+    /** One line describing the last feasibility check for the selected target. */
+    function checkMessage(check, passed, t) {
+      const fill = (text) => text
+        .replace('{valid}', String(check.valid))
+        .replace('{responses}', String(check.responses))
+        .replace('{leak}', String(check.reasoningLeak))
+        .replace('{errors}', String(check.errors));
+      return check.error ? `${fill(t('checkFailed'))} ${check.error}` : fill(t(passed ? 'checkPassed' : 'checkFailed'));
+    }
+
     function friendlyError(message, t) {
       const text = String(message ?? '');
       if (/cannot disable reasoning/i.test(text)) return t('errorNoReasoning');
@@ -307,6 +339,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;
     }
 
@@ -336,7 +369,7 @@ window.__ModuleLoader__.load({
     function visibleWarnings(comparison) {
       return (comparison.warnings || []).filter((item) => {
         if (comparison.verdictReason === 'partial_battery' && /full battery/i.test(item)) return false;
-        if (comparison.verdictReason === 'repetitions' && /threshold needs 30/i.test(item)) return false;
+        if (comparison.verdictReason === 'repetitions' && /cutoff needs 30/i.test(item)) return false;
         return true;
       });
     }
@@ -444,6 +477,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',
@@ -619,6 +685,48 @@ window.__ModuleLoader__.load({
       );
     }
 
+    /**
+     * Sidebar glyph: the fingerprint mark drawn to the same optical spec as the
+     * built-in panel icons — 16 viewBox, 1.33 stroke, currentColor, artwork in
+     * the 1.3–14.7 box — so it matches their visual size. The sidebar row owns
+     * the edge and passes it as `size`.
+     */
+    function PanelIcon({ size }) {
+      return h('svg', {
+        viewBox: '0 0 16 16',
+        width: size,
+        height: size,
+        fill: 'none',
+        'aria-hidden': true,
+        strokeWidth: 1.33,
+        style: { display: 'block', flex: 'none' },
+      },
+        h('rect', {
+          x: 1.97,
+          y: 1.97,
+          width: 12.06,
+          height: 12.06,
+          rx: 3.1,
+          stroke: 'currentColor',
+        }),
+        h('path', {
+          d: 'M4.84 9.57c0-1.83 1.15-3.15 3.16-3.15s3.16 1.32 3.16 3.15',
+          stroke: 'currentColor',
+          strokeLinecap: 'round',
+        }),
+        h('path', {
+          d: 'M6.27 10.35c0-1.05.58-1.83 1.73-1.83s1.73.78 1.73 1.83',
+          stroke: 'currentColor',
+          strokeLinecap: 'round',
+        }),
+        h('path', {
+          d: 'M8 11.4v-1.3',
+          stroke: 'currentColor',
+          strokeLinecap: 'round',
+        }),
+      );
+    }
+
     function TrashIcon({ size = 14 }) {
       return h('svg', {
         viewBox: '0 0 24 24',
@@ -693,6 +801,8 @@ window.__ModuleLoader__.load({
       const [modelId, setModelId] = useState('');
       const [reps, setReps] = useState(30);
       const [starting, setStarting] = useState(false);
+      const [checking, setChecking] = useState(false);
+      const [check, setCheck] = useState(null);
       const [comparing, setComparing] = useState(false);
       const [deleting, setDeleting] = useState(false);
       const [pendingDelete, setPendingDelete] = useState(null);
@@ -707,6 +817,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 +850,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 || []);
@@ -788,6 +905,9 @@ window.__ModuleLoader__.load({
       const hasIncompatible = models.some((entry) => entry.paperCompatible === false);
       const noCompatibleModels = models.length > 0 && compatibleModels.length === 0;
       const modelCompatible = model ? model.paperCompatible !== false : false;
+      /** A feasibility check only counts for the target it ran against. */
+      const checkMatches = Boolean(check && check.provider === providerId && check.model === modelId);
+      const checkPassed = checkMatches && check.passed === true;
       const completed = checkpoints.filter((entry) => entry.status === 'completed' || entry.status === 'completed_with_failures');
       const bOptions = completed.filter((entry) => entry.id !== a);
 
@@ -799,10 +919,54 @@ window.__ModuleLoader__.load({
         setModelId(nextModel ? nextModel.id : '');
         setWarning('');
         setNotice('');
+        setCheck(null);
+      }
+
+      async function runCheck() {
+        if (!providerId || !modelId || !modelCompatible) return;
+        setChecking(true);
+        setError('');
+        setWarning('');
+        setNotice('');
+        try {
+          const result = await api('/probe', {
+            method: 'POST',
+            body: JSON.stringify({ provider: providerId, model: modelId }),
+          });
+          const summary = result.summary || {};
+          setCheck({
+            provider: providerId,
+            model: modelId,
+            passed: summary.protocolCompliant === true,
+            responses: Number(summary.responses ?? 0),
+            valid: Number(summary.valid ?? 0),
+            reasoningLeak: Number(summary.reasoningLeak ?? 0),
+            errors: Number(summary.errors ?? 0),
+            probeId: result.probeId ?? null,
+          });
+        } catch (cause) {
+          setCheck({
+            provider: providerId,
+            model: modelId,
+            passed: false,
+            responses: 0,
+            valid: 0,
+            reasoningLeak: 0,
+            errors: 1,
+            error: friendlyError(cause.message || cause, t),
+            probeId: null,
+          });
+        } finally {
+          setChecking(false);
+        }
       }
 
       async function start() {
         if (!providerId || !modelId) return;
+        if (!checkPassed) {
+          setError(t('checkRequired'));
+          return;
+        }
         if (!modelCompatible) {
           setError(noCompatibleModels ? t('noCompatibleModels') : t('noOff'));
           return;
@@ -814,7 +978,12 @@ window.__ModuleLoader__.load({
         try {
           const created = await api('/checkpoints', {
             method: 'POST',
-            body: JSON.stringify({ provider: providerId, model: modelId, reps: Number(reps) }),
+            body: JSON.stringify({
+              provider: providerId,
+              model: modelId,
+              reps: Number(reps),
+              ...(checkPassed && check.probeId ? { probeId: check.probeId } : {}),
+            }),
           });
           const recordId = created.recordId ?? created.checkpointId;
           setNotice(`${t('started')} ${recordId}`);
@@ -894,6 +1063,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 },
@@ -934,7 +1122,10 @@ window.__ModuleLoader__.load({
                 h('select', {
                   style: S.input,
                   value: modelId,
-                  onChange: (event) => setModelId(event.target.value),
+                  onChange: (event) => {
+                    setModelId(event.target.value);
+                    setCheck(null);
+                  },
                   disabled: models.length === 0 || noCompatibleModels,
                 },
                   h('option', { value: '' }, models.length === 0 ? t('noModels') : noCompatibleModels ? t('noCompatibleModelsShort') : '—'),
@@ -958,11 +1149,19 @@ window.__ModuleLoader__.load({
                   onChange: (event) => setReps(Math.max(10, Math.min(100, Number(event.target.value) || 30))),
                 }),
               ),
-              h('button', {
-                style: { ...S.button, ...(starting || !modelCompatible ? S.disabled : {}) },
-                disabled: starting || !providerId || !modelId || !modelCompatible,
-                onClick: start,
-              }, starting ? t('starting') : t('start')),
+              h('div', { style: { display: 'flex', gap: '8px', flex: '1 1 auto', justifyContent: 'flex-end' } },
+                h('button', {
+                  style: { ...S.buttonSecondary, ...(checking || !modelCompatible || !providerId || !modelId ? S.disabled : {}) },
+                  disabled: checking || starting || !providerId || !modelId || !modelCompatible,
+                  onClick: runCheck,
+                }, checking ? t('checking') : t('checkTitle')),
+                h('button', {
+                  style: { ...S.button, ...(starting || !modelCompatible || !checkPassed ? S.disabled : {}) },
+                  disabled: starting || !providerId || !modelId || !modelCompatible || !checkPassed,
+                  title: checkPassed ? undefined : t('checkRequired'),
+                  onClick: start,
+                }, starting ? t('starting') : t('start')),
+              ),
             ),
             h('div', { style: { ...S.hint, marginTop: '10px' } },
               `${t('estimated')}: ${estimate} ${t('requests')} (40 ${t('cellsUnit')} × ${reps})`,
@@ -982,6 +1181,16 @@ window.__ModuleLoader__.load({
                 ? h('div', { style: { ...S.hint, color: 'var(--dsw-alias-state-warn-primary)' } }, t('noCompatibleModels'))
                 : null,
             hasIncompatible ? h('div', { style: S.hint }, t('incompatibleHint')) : null,
+            model
+              ? h('div', {
+                style: {
+                  ...S.hint,
+                  color: checkMatches
+                    ? (checkPassed ? 'var(--dsw-alias-state-success-primary)' : 'var(--dsw-alias-state-error-primary)')
+                    : 'var(--dsw-alias-label-secondary)',
+                },
+              }, checkMatches ? checkMessage(check, checkPassed, t) : t('checkHint'))
+              : null,
           ),
 
           h(Section, {
@@ -1144,6 +1353,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,
@@ -1276,7 +1515,7 @@ window.__ModuleLoader__.load({
           order: 30,
           locale: NS,
           label: () => t('title'),
-        }, ({ label }) => h(Mark, { size: 18 })));
+        }, PanelIcon));
       },
     };
   },

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`，插件重载后恢复。
 
 目标发现：
 
@@ -75,6 +78,14 @@ llm-fingerprint/
 
 遇到 `MissingSessionID` 时停止调度后续采样，等待已经发出的并发请求结束后将记录标为失败，保留原始错误，不继续发完整批次。
 
+### 采集前的可行性检测
+
+面板选完服务商和模型后必须先点“检测可行性”：它调用 `POST /probe`（2 个 cell × 3 次，共 6 个请求），只有返回的 `summary.protocolCompliant` 为真时“开始采集”才可用；换服务商或模型会清掉结果，要求重新检测。
+
+原因是元数据里的 `off` 只说明适配器愿意请求关闭档位，不保证服务商真的照做。路由把 `off` 翻成“不发送 reasoning 参数”时，服务商可能仍按默认推理，`max_tokens=16` 全被推理吃光，整批响应都会变成 `post_reasoning`：`command-goat` 的 `openai-completions` 路由就这样跑完 1200 个请求才暴露 0 有效。这种失败只有在真的发一次请求后才看得见，所以检测放在采集之前，用 6 个请求代替 1200 个。
+
+检测只拦面板入口：HTTP API 和 agent 工具仍然可以直接 `POST /checkpoints`（`startCheckpoint` 只做元数据层面的 `supportsPaperProtocol` 检查），这条路径留给诊断和自动化。通过检测后再采集时，面板把 `probeId` 一并提交，记录到 `meta.probeId`，事后可以把记录和当次检测对上。检测日志按时间保留最近 `PROBE_LOG_RETENTION`（20）条，其余在写入时删除。
+
 ## 5. 兼容性硬拦截
 
 `supportsPaperProtocol(info)` 的规则：
@@ -87,7 +98,7 @@ llm-fingerprint/
 
 - UI 模型下拉里仍然列出，但 `disabled`，文本标注“不可关闭推理”；
 - 服务商下所有模型都不可用时，服务商选项标注“无可用模型”，模型选择禁用，Start 禁用，并显示原因；
-- Host `startCheckpoint` 再检查一次，API 和 agent 工具都无法绕过；
+- Host `startCheckpoint` 再检查一次，HTTP API 和 agent 工具都无法绕过；
 - `probe` 仍然可以用于诊断，但不会创建记录。
 
 这套判断完全由运行时配置/适配器元数据计算，不维护模型名黑名单。给某个模型在 DSH 配置里加上 `off` 映射后，它会自动变为可用，不需要改插件代码。
@@ -124,11 +135,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 +148,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;
@@ -46,6 +47,8 @@ const MAX_TOKENS = 16;
 const TEMPERATURE = 1.0;
 const DEFAULT_REPS = 30;
 const API_PREFIX = '/llm-fingerprint/api';
+/** Feasibility checks are cheap and disposable: keep the newest logs only. */
+const PROBE_LOG_RETENTION = 20;
 
 function resolveDataDir(config) {
   const configured = config && typeof config.dataDir === 'string' && config.dataDir.trim();
@@ -475,6 +478,18 @@ function recoverInterruptedRecords(root) {
   return recovered;
 }
 
+/** Keep the probe directory bounded: probe ids start with a timestamp, so name order is age order. */
+function pruneProbeLogs(dir) {
+  const names = readdirSync(dir).filter((name) => /^probe-.+\.json$/.test(name)).sort();
+  for (const name of names.slice(0, Math.max(0, names.length - PROBE_LOG_RETENTION))) {
+    try {
+      rmSync(path.join(dir, name), { force: true });
+    } catch {
+      // A log that cannot be removed is not worth failing a diagnostic check over.
+    }
+  }
+}
+
 function checkpointSummary(meta) {
   return {
     id: meta.id,
@@ -649,6 +664,7 @@ function createService(ctx, root, lifetimeSignal) {
       summary,
       responses,
     }, null, 2)}\n`);
+    pruneProbeLogs(probeDir);
     return {
       probeId,
       provider: args.provider,
@@ -680,6 +696,10 @@ function createService(ctx, root, lifetimeSignal) {
       if (!cellById(cellId)) throw new Error(`unknown cell "${cellId}"`);
     }
     const reps = Math.max(1, Math.min(100, Number(args.reps ?? DEFAULT_REPS)));
+    const probeId = args.probeId == null ? null : String(args.probeId);
+    if (probeId !== null && !/^probe-[0-9A-Za-z-]+$/.test(probeId)) {
+      throw new Error('invalid probe id');
+    }
     const id = `cp-${nowUtc().replace(/[-:.]/g, '').slice(0, 15)}-${randomUUID().slice(0, 8)}`;
     const provider = await providerInfo(ctx, args.provider);
     const warnings = [];
@@ -701,6 +721,7 @@ function createService(ctx, root, lifetimeSignal) {
       reasoningEffort: effort,
       reasoningPolicy: effort == null ? 'none' : effortIsDisabled(effort) ? 'disabled' : 'least-available',
       reasoningLeakResponses: 0,
+      ...probeId === null ? {} : { probeId },
       modelInfo: adapterMetadata(info),
       request: { temperature: TEMPERATURE, maxTokens: MAX_TOKENS, systemPrompt: 'per-cell', sessionPolicy: 'new-per-sample-reuse-on-retry' },
       usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0 },
@@ -926,6 +947,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 +1053,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 +1084,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 +1118,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,12 +1,12 @@
 {
   "name": "dsh-fingerprint",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "Paper-protocol fingerprint records and comparison panel for configured DSH provider/model routes.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Jerry2262/dsh-fingerprint.git"
+    "url": "git+https://github.com/Jerry2262/dsh-fingerprint.git"
   },
   "homepage": "https://github.com/Jerry2262/dsh-fingerprint",
   "bugs": {
@@ -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": {