dsh-qqbot-guard 1.0.0 → 1.1.0

package/README.md

@@ -50,8 +50,9 @@ mentions 后从正文摘掉。
 2. 装本插件：市场安装，或 `dsh plugin --profile web add dsh-qqbot-guard`；
 3. 本包自带 `dsh.bundle.patch`（`cordis.patch.yml`，用 `- insert:` 插入 `qqbot-guard` 行），
    被列入 `dsh.profile.bundles` 后会自动生效——**不要**在 profile 的 `cordis.patch.yml` 里再写一条同 id 的新行；
-4. 需要改参数时，二选一：
-   - **JSON 后门（手机端推荐）**：编辑 `$DSH_HOME/qqbot-guard.json`
+4. 需要改参数时，三选一（最终都落到同一个 `$DSH_HOME/qqbot-guard.json`）：
+   - **设置页（推荐，手机端也能用）**：DSH 里打开「设置 → QQ 守护」，改完点保存，**立即生效、不用重启**；
+   - **JSON 后门**：编辑 `$DSH_HOME/qqbot-guard.json`
      （App 里是 `/root/.dsh/qqbot-guard.json`，首次启动由 `PluginSeed` 生成）；
    - **profile patch 覆盖**（能写 YAML 时）：
 
@@ -120,6 +121,20 @@ mentions 后从正文摘掉。
 配置优先级：`DEFAULT_CONFIG` < 外部 JSON 文件 < cordis 里的 `config`。JSON 解析失败只会打一条
 warn 然后忽略，不会让插件挂掉——手机上手改坏了不会变砖。
 
+## 设置页（可视化配置）
+
+包导出 `./client`（`dsh.client.platform = web`），在 DSH 里注册一个设置板块「QQ 守护」：
+
+- 顶部状态行：qqbot 是否定位到、装在哪、SDK 版本、history 补丁是否生效——`找不到 qqbot` 这类
+  故障不用再翻 App 日志；
+- 关键词用每行一个的 textarea 编辑（空行忽略、自动去重），开关直接点；
+- 保存写的还是 `$DSH_HOME/qqbot-guard.json`（原子写：临时文件 + rename，不会写坏）；
+- guard 每收一条消息前检查文件指纹（mtime + size），变了就重新读——**保存即生效**，
+  在设置页和手改 JSON 之间来回切换也不会打架。
+
+接口是同源的 `GET/PUT /qqbot-guard/config`：只接受回环地址的 Host、拒绝跨站 Origin，
+请求体上限 64 KB，未知字段直接 400（防止手滑写进错字段还静默忽略）。
+
 ## 自检
 
 ```bash

package/client/client.js

@@ -0,0 +1,482 @@
+/**
+ * qqbot-guard 的客户端半侧：在 DSH「设置」里加一个「QQ 守护」板块。
+ *
+ * 手写、不打包：DSH 的模块加载器按约定加载 `client.js`（package.json 的 `exports["./client"]`），
+ * 内容就是 `window.__ModuleLoader__.load({ id, factory })` 包一层 CJS 工厂；
+ * React 由宿主通过 `require('react')` 提供，所以这里不需要 node_modules。
+ *
+ * 数据全部走宿主同源的 `/qqbot-guard/config`（服务端在 index.js 的 installConfigApi 里注册），
+ * 保存后 guard 端会按文件 mtime 热重载，下一条群消息就生效；只有「总开关」与附件下载相关
+ * 的项需要重启插件才生效，UI 上会单独提示。
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-qqbot-guard',
+  factory: (require) => {
+    const React = require('react');
+    const h = React.createElement;
+    const { useCallback, useEffect, useMemo, useState } = React;
+
+    const NS = 'qqbot-guard';
+    const API = '/qqbot-guard/config';
+
+    const zh = {
+      nav: 'QQ 守护',
+      title: 'QQ 守护',
+      intro: '群消息不 @ 也能触发 QQ 机器人：正文命中关键词时自动补一条「被 @」标记，并顺带带上群历史。',
+      keywords: '关键词',
+      keywordsHint: '一行一个；正文包含任一词就当作在跟你说话。留空表示关闭关键词放行。',
+      switches: '开关',
+      enabled: '启用守护',
+      enabledHint: '关掉后 qqbot 恢复原样。修改后需要重启插件才生效。',
+      faces: '表情转文字',
+      facesHint: '把新版表情标签换成 emoji，历史里不再是一串标签。',
+      historyAttachments: '历史附件摘要',
+      historyAttachmentsHint: '群历史只存正文，开启后补一句附件说明。',
+      historyMedia: '预下载历史附件',
+      historyMediaHint: '没触发关键词的群消息也把图片/文件落盘；重启后生效。',
+      ignoreCase: '忽略大小写',
+      verbose: '诊断日志',
+      advanced: '高级',
+      qqbotPackage: 'qqbot 安装目录',
+      qqbotPackageHint: '留空自动探测；一般不用填。',
+      maxMB: '预下载上限（MB）',
+      save: '保存',
+      saving: '保存中…',
+      saved: '已保存，下一条消息生效',
+      reload: '重新加载',
+      loading: '读取配置中…',
+      failed: '读取失败',
+      status: '运行状态',
+      location: 'qqbot 位置',
+      notFound: '没找到',
+      installed: '补丁已挂载',
+      notInstalled: '补丁未挂载',
+      restartNeeded: '总开关/预下载的改动需要重启插件才生效。',
+      overridden: '这些字段被 cordis 配置覆盖，改这里不会生效：',
+      file: '配置文件',
+    };
+
+    const en = {
+      nav: 'QQ Guard',
+      title: 'QQ Guard',
+      intro: 'Let group messages reach the QQ bot without an @ mention: keyword hits get a synthetic mention and pull in group history.',
+      keywords: 'Keywords',
+      keywordsHint: 'One per line. Any hit counts as talking to you. Leave empty to disable keyword gating.',
+      switches: 'Switches',
+      enabled: 'Enable guard',
+      enabledHint: 'When off, qqbot behaves as stock. Takes effect after the plugin restarts.',
+      faces: 'Emoji tags to text',
+      facesHint: 'Rewrite <faceType=…> tags into emoji in history.',
+      historyAttachments: 'History attachment notes',
+      historyAttachmentsHint: 'Append a short attachment note when reading group history.',
+      historyMedia: 'Prefetch history media',
+      historyMediaHint: 'Download media for messages that never triggered a keyword.',
+      ignoreCase: 'Ignore case',
+      verbose: 'Diagnostic logs',
+      advanced: 'Advanced',
+      qqbotPackage: 'qqbot install dir',
+      qqbotPackageHint: 'Leave empty to auto-detect.',
+      maxMB: 'Prefetch limit (MB)',
+      save: 'Save',
+      saving: 'Saving…',
+      saved: 'Saved — applies to the next message',
+      reload: 'Reload',
+      loading: 'Loading…',
+      failed: 'Failed to load',
+      status: 'Status',
+      location: 'qqbot location',
+      notFound: 'not found',
+      installed: 'Patch mounted',
+      notInstalled: 'Patch not mounted',
+      restartNeeded: 'Changes to the master switch or prefetch need a plugin restart.',
+      overridden: 'These fields are set by the cordis config and ignore this page:',
+      file: 'Config file',
+    };
+
+    const S = {
+      root: { display: 'flex', flexDirection: 'column', gap: 18, padding: '4px 2px 28px' },
+      intro: { margin: 0, fontSize: 13, lineHeight: 1.7, opacity: 0.86 },
+      card: {
+        border: '1px solid var(--dsh-border, rgba(127,127,127,.28))',
+        borderRadius: 12,
+        padding: '14px 16px',
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 12,
+      },
+      cardTitle: {
+        fontSize: 12,
+        fontWeight: 600,
+        letterSpacing: '.08em',
+        textTransform: 'uppercase',
+        opacity: 0.62,
+        margin: 0,
+      },
+      field: { display: 'flex', flexDirection: 'column', gap: 6 },
+      label: { fontSize: 13, fontWeight: 600 },
+      hint: { fontSize: 12, lineHeight: 1.6, opacity: 0.68, margin: 0 },
+      textarea: {
+        width: '100%',
+        minHeight: 96,
+        boxSizing: 'border-box',
+        padding: '10px 12px',
+        borderRadius: 10,
+        border: '1px solid var(--dsh-border, rgba(127,127,127,.32))',
+        background: 'var(--dsh-surface, transparent)',
+        color: 'inherit',
+        font: 'inherit',
+        fontSize: 13,
+        lineHeight: 1.6,
+        resize: 'vertical',
+      },
+      input: {
+        width: '100%',
+        boxSizing: 'border-box',
+        padding: '8px 12px',
+        borderRadius: 10,
+        border: '1px solid var(--dsh-border, rgba(127,127,127,.32))',
+        background: 'var(--dsh-surface, transparent)',
+        color: 'inherit',
+        font: 'inherit',
+        fontSize: 13,
+      },
+      row: {
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        gap: 12,
+        padding: '6px 0',
+        borderTop: '1px solid var(--dsh-border, rgba(127,127,127,.16))',
+      },
+      rowText: { display: 'flex', flexDirection: 'column', gap: 2 },
+      switchWrap: { display: 'flex', alignItems: 'center', gap: 8, flex: '0 0 auto' },
+      footer: { display: 'flex', alignItems: 'center', gap: 12, flexWrap: 'wrap' },
+      button: {
+        padding: '8px 18px',
+        borderRadius: 10,
+        border: '1px solid var(--dsh-border, rgba(127,127,127,.32))',
+        background: 'var(--dsh-accent, #4c6ef5)',
+        color: '#fff',
+        font: 'inherit',
+        fontSize: 13,
+        fontWeight: 600,
+        cursor: 'pointer',
+      },
+      buttonGhost: {
+        padding: '8px 14px',
+        borderRadius: 10,
+        border: '1px solid var(--dsh-border, rgba(127,127,127,.32))',
+        background: 'transparent',
+        color: 'inherit',
+        font: 'inherit',
+        fontSize: 13,
+        cursor: 'pointer',
+      },
+      badge: {
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 6,
+        padding: '2px 9px',
+        borderRadius: 999,
+        fontSize: 12,
+        border: '1px solid var(--dsh-border, rgba(127,127,127,.32))',
+        opacity: 0.9,
+      },
+      notice: { fontSize: 12.5, lineHeight: 1.6, margin: 0 },
+      mono: { fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace', fontSize: 12, wordBreak: 'break-all' },
+    };
+
+    const TOGGLE_ROWS = [
+      ['faces', 'faces', 'facesHint', false],
+      ['historyAttachments', 'historyAttachments', 'historyAttachmentsHint', false],
+      ['historyMedia', 'historyMedia', 'historyMediaHint', true],
+      ['ignoreCase', 'ignoreCase', null, false],
+      ['verbose', 'verbose', null, false],
+    ];
+
+    function Toggle({ id, checked, onChange, disabled }) {
+      return h('input', {
+        id,
+        type: 'checkbox',
+        checked,
+        disabled,
+        onChange: (event) => onChange(event.target.checked),
+        style: { width: 16, height: 16, cursor: disabled ? 'default' : 'pointer' },
+      });
+    }
+
+    function Section({ t }) {
+      const [loading, setLoading] = useState(true);
+      const [saving, setSaving] = useState(false);
+      const [error, setError] = useState('');
+      const [notice, setNotice] = useState('');
+      const [file, setFile] = useState('');
+      const [status, setStatus] = useState({});
+      const [config, setConfig] = useState(null);
+      const [keywords, setKeywords] = useState('');
+      const [overridden, setOverridden] = useState([]);
+
+      const applyPayload = useCallback((payload) => {
+        const cfg = payload?.config ?? {};
+        setConfig(cfg);
+        setFile(payload?.file ?? '');
+        setStatus(payload?.status ?? {});
+        setOverridden(Array.isArray(payload?.overridden) ? payload.overridden : []);
+        setKeywords(Array.isArray(cfg.triggers) ? cfg.triggers.join('\n') : '');
+      }, []);
+
+      const load = useCallback(async () => {
+        setError('');
+        try {
+          const response = await fetch(API, { headers: { accept: 'application/json' } });
+          const payload = await response.json().catch(() => ({}));
+          if (!response.ok) throw new Error(payload?.error || `HTTP ${response.status}`);
+          applyPayload(payload);
+        } catch (err) {
+          setError(String(err?.message ?? err));
+        } finally {
+          setLoading(false);
+        }
+      }, [applyPayload]);
+
+      useEffect(() => {
+        void load();
+      }, [load]);
+
+      const patch = useCallback((key, value) => {
+        setConfig((prev) => ({ ...(prev ?? {}), [key]: value }));
+        setNotice('');
+      }, []);
+
+      const save = useCallback(async () => {
+        if (!config) return;
+        setSaving(true);
+        setError('');
+        setNotice('');
+        try {
+          const body = {
+            triggers: keywords
+              .split(/\r?\n|,|，/)
+              .map((s) => s.trim())
+              .filter(Boolean),
+          };
+          for (const key of [
+            'enabled',
+            'ignoreCase',
+            'faces',
+            'historyAttachments',
+            'historyMedia',
+            'verbose',
+            'strictVersion',
+          ]) {
+            if (typeof config[key] === 'boolean') body[key] = config[key];
+          }
+          if (config.historyMediaMaxMB !== undefined) body.historyMediaMaxMB = config.historyMediaMaxMB;
+          if (typeof config.qqbotPackage === 'string') body.qqbotPackage = config.qqbotPackage;
+          const response = await fetch(API, {
+            method: 'PUT',
+            headers: { 'content-type': 'application/json', accept: 'application/json' },
+            body: JSON.stringify(body),
+          });
+          const payload = await response.json().catch(() => ({}));
+          if (!response.ok) throw new Error(payload?.error || `HTTP ${response.status}`);
+          applyPayload(payload);
+          setNotice(t('saved'));
+        } catch (err) {
+          setError(String(err?.message ?? err));
+        } finally {
+          setSaving(false);
+        }
+      }, [applyPayload, config, keywords, t]);
+
+      const statusBits = useMemo(() => {
+        if (!status) return [];
+        const bits = [];
+        if (status.installed) bits.push({ key: 'installed', text: t('installed'), tone: 'ok' });
+        else if (status.reason) bits.push({ key: 'idle', text: status.reason, tone: 'warn' });
+        return bits;
+      }, [status, t]);
+
+      if (loading) {
+        return h('div', { style: S.root }, h('p', { style: S.hint }, t('loading')));
+      }
+
+      if (!config) {
+        return h(
+          'div',
+          { style: S.root },
+          h('p', { style: S.notice, role: 'alert' }, `${t('failed')}: ${error || 'unknown'}`),
+          h('button', { type: 'button', style: S.buttonGhost, onClick: () => void load() }, t('reload')),
+        );
+      }
+
+      return h(
+        'div',
+        { style: S.root },
+        h('p', { style: S.intro }, t('intro')),
+
+        h(
+          'section',
+          { style: S.card },
+          h('h3', { style: S.cardTitle }, t('status')),
+          h(
+            'div',
+            { style: { display: 'flex', gap: 8, flexWrap: 'wrap' } },
+            statusBits.map((bit) =>
+              h('span', {
+                key: bit.key,
+                style: { ...S.badge, borderColor: bit.tone === 'ok' ? 'rgba(64,160,96,.55)' : 'rgba(214,140,60,.55)' },
+              }, bit.text),
+            ),
+          ),
+          h(
+            'p',
+            { style: S.hint },
+            h('span', null, `${t('location')}: `),
+            h('span', { style: S.mono }, status?.qqbot || t('notFound')),
+          ),
+          file
+            ? h(
+                'p',
+                { style: S.hint },
+                h('span', null, `${t('file')}: `),
+                h('span', { style: S.mono }, file),
+              )
+            : null,
+        ),
+
+        h(
+          'section',
+          { style: S.card },
+          h('h3', { style: S.cardTitle }, t('keywords')),
+          h('textarea', {
+            style: S.textarea,
+            value: keywords,
+            spellCheck: false,
+            placeholder: '大肥鱼\n肥鱼\n鱼鱼',
+            onChange: (event) => {
+              setKeywords(event.target.value);
+              setNotice('');
+            },
+          }),
+          h('p', { style: S.hint }, t('keywordsHint')),
+        ),
+
+        h(
+          'section',
+          { style: S.card },
+          h('h3', { style: S.cardTitle }, t('switches')),
+          h(
+            'div',
+            { style: { ...S.row, borderTop: 'none' } },
+            h(
+              'label',
+              { htmlFor: 'qqbot-guard-enabled', style: S.rowText },
+              h('span', { style: S.label }, t('enabled')),
+              h('span', { style: S.hint }, t('enabledHint')),
+            ),
+            h(Toggle, {
+              id: 'qqbot-guard-enabled',
+              checked: config.enabled !== false,
+              onChange: (value) => patch('enabled', value),
+            }),
+          ),
+          TOGGLE_ROWS.map(([key, labelKey, hintKey]) =>
+            h(
+              'div',
+              { key, style: S.row },
+              h(
+                'label',
+                { htmlFor: `qqbot-guard-${key}`, style: S.rowText },
+                h('span', { style: S.label }, t(labelKey)),
+                hintKey ? h('span', { style: S.hint }, t(hintKey)) : null,
+              ),
+              h(Toggle, {
+                id: `qqbot-guard-${key}`,
+                checked: config[key] !== false,
+                onChange: (value) => patch(key, value),
+              }),
+            ),
+          ),
+        ),
+
+        h(
+          'section',
+          { style: S.card },
+          h('h3', { style: S.cardTitle }, t('advanced')),
+          h(
+            'div',
+            { style: S.field },
+            h('label', { style: S.label, htmlFor: 'qqbot-guard-pkg' }, t('qqbotPackage')),
+            h('input', {
+              id: 'qqbot-guard-pkg',
+              style: S.input,
+              value: config.qqbotPackage ?? '',
+              placeholder: 'auto',
+              onChange: (event) => patch('qqbotPackage', event.target.value),
+            }),
+            h('p', { style: S.hint }, t('qqbotPackageHint')),
+          ),
+          h(
+            'div',
+            { style: S.field },
+            h('label', { style: S.label, htmlFor: 'qqbot-guard-maxmb' }, t('maxMB')),
+            h('input', {
+              id: 'qqbot-guard-maxmb',
+              type: 'number',
+              min: 1,
+              max: 1024,
+              style: S.input,
+              value: config.historyMediaMaxMB ?? 20,
+              onChange: (event) => patch('historyMediaMaxMB', Number(event.target.value)),
+            }),
+          ),
+        ),
+
+        h(
+          'div',
+          { style: S.footer },
+          h(
+            'button',
+            { type: 'button', style: { ...S.button, opacity: saving ? 0.6 : 1 }, disabled: saving, onClick: () => void save() },
+            saving ? t('saving') : t('save'),
+          ),
+          h('button', { type: 'button', style: S.buttonGhost, onClick: () => void load() }, t('reload')),
+          notice ? h('span', { style: { ...S.notice, color: 'rgba(64,160,96,.95)' } }, notice) : null,
+          error ? h('span', { style: { ...S.notice, color: 'rgba(214,80,80,.95)' }, role: 'alert' }, error) : null,
+        ),
+        h('p', { style: S.hint }, t('restartNeeded')),
+        overridden.length > 0
+          ? h(
+              'p',
+              { style: { ...S.notice, color: 'rgba(214,140,60,.95)' } },
+              `${t('overridden')} ${overridden.join(', ')}`,
+            )
+          : null,
+      );
+    }
+
+    const name = 'dsh-qqbot-guard';
+    const inject = ['slots', 'locale'];
+
+    function apply(ctx) {
+      ctx.effect(() => ctx.locale.register(NS, { zh, en }), `${NS}: dictionaries`);
+      const t = ctx.locale.bind(NS);
+      ctx.slots.inject('settings.section', () =>
+        ctx.slots.register(
+          {
+            name: 'settings.section',
+            id: NS,
+            order: 65,
+            label: () => t('nav'),
+            locale: NS,
+            inject: () => ({ t, locale: ctx.locale }),
+          },
+          () => h(Section, { t }),
+        ),
+      );
+    }
+
+    return { name, inject, apply };
+  },
+});

package/cordis.patch.yml

@@ -1,8 +1,11 @@
 # qqbot-guard bundle patch
 #
 # 本包被列入 profile 的 dsh.profile.bundles 后，dsh 启动时自动应用此 patch，
-# 把下面这一行插进插件树。真正的门禁参数请在 profile 的 cordis.patch.yml 里覆盖
-# （同 id 的普通 patch 会覆盖这里的默认值）。
+# 把下面这一行插进插件树。
+#
+# 故意不带 config：所有参数都由 $DSH_HOME/qqbot-guard.json（设置页写的就是它）
+# 或 DEFAULT_CONFIG 决定。cordis 的 config 优先级高于 JSON 文件——这里写一个键，
+# 设置页里对应的开关就再也改不动了，所以默认一个都不写。
 #
 # 注意：profile 的 cordis.patch.yml 只能改「已存在的 id」，新增插件行必须写在
 # bundle patch（本文件）里，或者用 `- insert:` 形式手动插入。
@@ -10,13 +13,3 @@
 - insert:
     - id: qqbot-guard
       name: 'dsh-qqbot-guard'
-      config:
-        # triggers 故意不写：由 $DSH_HOME/qqbot-guard.json 或 DEFAULT_CONFIG（大肥鱼/肥鱼/鱼鱼）决定，
-        # 手机端改关键词不用碰 YAML。要在这里写死也行，会盖过 JSON 文件。
-        ignoreCase: true
-        # 留空则自动探测：先看本插件自己所在的 node_modules（也就是 profile 布局
-        # <home>/profiles/<name>/node_modules），再看 <home>/profiles/*、<home>/plugins/*，
-        # 最后从 cwd 按 Node 规则向上找。只有自动探测落空时才需要在这里写死路径。
-        qqbotPackage: ''
-        strictVersion: false
-        verbose: true

package/index.js

@@ -21,7 +21,7 @@
  *     （含本地路径——落盘名带随机后缀，只能读的时候按前缀去 media 目录里找）。
  */
 import { pathToFileURL, fileURLToPath } from 'node:url';
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 
@@ -142,6 +142,244 @@ export function mergeConfig(config = {}, logger = console) {
   return { ...DEFAULT_CONFIG, ...file, ...explicit };
 }
 
+/** 设置页可以改的布尔开关。`configFile` 不在此列：让 UI 改自己的配置路径容易把用户锁死。 */
+const BOOLEAN_KEYS = [
+  'enabled',
+  'ignoreCase',
+  'faces',
+  'historyAttachments',
+  'historyMedia',
+  'verbose',
+  'strictVersion',
+];
+
+/**
+ * 归一化设置页提交的配置片段：只接受已知字段，字段值不合法时抛出带说明的错误。
+ * @param {unknown} input 请求体里的 JSON
+ * @returns {object} 只含已知字段的配置片段
+ */
+export function sanitizeConfigPatch(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('配置必须是一个 JSON 对象');
+  }
+  const out = {};
+  for (const key of BOOLEAN_KEYS) {
+    if (Object.hasOwn(input, key)) out[key] = Boolean(input[key]);
+  }
+  if (Object.hasOwn(input, 'triggers')) {
+    if (!Array.isArray(input.triggers)) throw new Error('triggers 必须是字符串数组');
+    const list = input.triggers.map((t) => String(t ?? '').trim()).filter(Boolean);
+    out.triggers = [...new Set(list)];
+  }
+  if (Object.hasOwn(input, 'historyMediaMaxMB')) {
+    const mb = Number(input.historyMediaMaxMB);
+    if (!Number.isFinite(mb) || mb <= 0 || mb > 1024) {
+      throw new Error('historyMediaMaxMB 需要 0~1024 之间的数字');
+    }
+    out.historyMediaMaxMB = mb;
+  }
+  if (Object.hasOwn(input, 'qqbotPackage')) {
+    out.qqbotPackage = String(input.qqbotPackage ?? '').trim();
+  }
+  return out;
+}
+
+/** 原子写 JSON：先写临时文件再 rename，写一半断电也不会留下半个配置文件。 */
+export function writeConfigFile(file, data) {
+  if (!file) throw new Error('没有可写的配置文件路径');
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+  renameSync(tmp, file);
+}
+
+/** 读一个纯 JSON 文件；不存在或损坏返回 null。 */
+function readJsonFile(file) {
+  if (!file || !existsSync(file)) return null;
+  try {
+    const data = JSON.parse(readFileSync(file, 'utf8'));
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 文件指纹：mtime + 大小。只改内容不改大小的情况极少，够用。 */
+function configStamp(file) {
+  if (!file) return 'missing';
+  try {
+    const s = statSync(file);
+    return `${s.mtimeMs}:${s.size}`;
+  } catch {
+    return 'missing';
+  }
+}
+
+/**
+ * 配置来源：cordis 之后还能被 JSON 文件覆盖，文件改了要能重读（设置页保存后即时生效）。
+ * @param {object} config cordis 里的 config
+ * @param {object} logger
+ */
+export function createConfigSource(config = {}, logger = console) {
+  const file = resolveConfigFile(config);
+  let stamp = configStamp(file);
+  let merged = mergeConfig(config, logger);
+  return {
+    /** 写回到哪个文件；没有可写路径时为 null */
+    file,
+    /** 当前生效的配置；文件 mtime/大小变了就重新合并 */
+    get() {
+      const next = configStamp(file);
+      if (next !== stamp) {
+        stamp = next;
+        merged = mergeConfig(config, logger);
+        logger.info?.(`[qqbot-guard] 配置已重新加载：${file}`);
+      }
+      return merged;
+    },
+    /** 强制重读（设置页保存后调用，省得等下一次轮询） */
+    reload() {
+      stamp = configStamp(file);
+      merged = mergeConfig(config, logger);
+      return merged;
+    },
+  };
+}
+
+/** 本机回环地址的「主机名:端口」；不认识的写法则返回 null。 */
+function loopbackAuthority(authority) {
+  if (typeof authority !== 'string' || authority === '') return null;
+  let url;
+  try {
+    url = new URL(`http://${authority}`);
+  } catch {
+    return null;
+  }
+  const host = url.hostname.toLowerCase();
+  if (host !== 'localhost' && host !== '127.0.0.1' && host !== '[::1]' && host !== '::1') return null;
+  return `${host}:${url.port}`;
+}
+
+/**
+ * 只允许本机回环来源改配置：Host 必须是回环（挡 DNS rebinding），
+ * 带 Origin 时还要求同源（挡别的网页用表单 POST 改配置）。
+ * 桌面端页面跑在 `dsh-app://` 下，必须显式放行。
+ * @param {object} request Node 的 IncomingMessage
+ */
+export function isSameOrigin(request) {
+  const hostKey = loopbackAuthority(request?.headers?.host);
+  if (hostKey === null) return false;
+  const origin = request?.headers?.origin;
+  if (origin === undefined || origin === '') return true;
+  try {
+    const url = new URL(origin);
+    if (url.protocol === 'dsh-app:') return true;
+    return loopbackAuthority(url.host) === hostKey;
+  } catch {
+    return false;
+  }
+}
+
+const CONFIG_PATH = '/qqbot-guard/config';
+const BODY_LIMIT_BYTES = 64 * 1024;
+
+function sendJson(response, status, value) {
+  response.writeHead(status, {
+    'cache-control': 'no-store',
+    'content-type': 'application/json; charset=utf-8',
+  });
+  response.end(JSON.stringify(value));
+}
+
+/** 读请求体并按上限保护；超过上限直接断开连接。 */
+function readBody(request, limit = BODY_LIMIT_BYTES) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    request.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > limit) {
+        reject(new Error('请求体过大'));
+        request.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    request.on('error', reject);
+  });
+}
+
+/** 设置页要的全部状态：配置、默认值、qqbot 定位结果。 */
+function configSnapshot(source, status, explicit = {}) {
+  return {
+    file: source.file ?? '',
+    config: source.get(),
+    defaults: DEFAULT_CONFIG,
+    status: { ...status },
+    // cordis 里的 config 优先级高于 JSON 文件；这些字段改设置页不会生效，得让 UI 说清楚
+    overridden: Object.keys(explicit ?? {}),
+  };
+}
+
+async function handleConfigRequest(request, response, source, log, status, explicit = {}) {
+  if (!isSameOrigin(request)) {
+    return sendJson(response, 403, { error: '来源不被信任（只允许本机回环地址）' });
+  }
+  const method = String(request?.method ?? 'GET').toUpperCase();
+  try {
+    if (method === 'GET') return sendJson(response, 200, configSnapshot(source, status, explicit));
+    if (method === 'PUT' || method === 'POST') {
+      if (!source.file) return sendJson(response, 400, { error: '没有可写的配置文件（缺少 DSH_HOME）' });
+      const patch = sanitizeConfigPatch(JSON.parse(await readBody(request)));
+      const next = { ...(readJsonFile(source.file) ?? {}), ...patch };
+      writeConfigFile(source.file, next);
+      source.reload();
+      log.info?.(`[qqbot-guard] 设置页已保存：${source.file}（${Object.keys(patch).join(', ') || '无改动'}）`);
+      return sendJson(response, 200, configSnapshot(source, status, explicit));
+    }
+    return sendJson(response, 405, { error: '不支持的方法' });
+  } catch (err) {
+    const message = String(err?.message ?? err);
+    log.warn?.(`[qqbot-guard] 配置请求失败：${message}`);
+    return sendJson(response, 400, { error: message });
+  }
+}
+
+/**
+ * 注册设置页用到的 HTTP 接口。
+ * qqbot 没装也要能打开设置页，所以调用点在 `findQqbotPackage` 之前。
+ * @returns {boolean} 宿主是否提供了 `inject`（有 webServer 时再异步挂载）
+ */
+export function installConfigApi(ctx, source, log, status = {}, explicit = {}) {
+  if (typeof ctx?.inject !== 'function') return false;
+  ctx.inject(['webServer'], (host) => {
+    const server = host?.webServer;
+    if (!server || typeof server.register !== 'function') {
+      log.warn?.('[qqbot-guard] webServer 不可用，设置页接口未注册');
+      return;
+    }
+    const mount = () => {
+      const dispose = server.register({
+        kind: 'exact',
+        path: CONFIG_PATH,
+        handler: (request, response) =>
+          handleConfigRequest(request, response, source, log, status, explicit),
+      });
+      return () => {
+        try {
+          dispose?.();
+        } catch {
+          /* 宿主已经在卸载路由了 */
+        }
+      };
+    };
+    if (typeof host.effect === 'function') host.effect(mount, 'qqbot-guard: config api');
+    else mount();
+  });
+  return true;
+}
+
 function parseVersion(v) {  const m = String(v ?? '').trim().match(/^(\d+)\.(\d+)\.(\d+)/);
   return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
 }
@@ -561,12 +799,15 @@ export function createGuard(
   notes = new Map(),
   mediaDownloader = null,
 ) {
-  const triggers = (config.triggers ?? []).filter((t) => typeof t === 'string' && t.length > 0);
-  const ignoreCase = config.ignoreCase !== false;
-  const faces = config.faces !== false;
-  const historyAttachments = config.historyAttachments !== false;
+  // 设置页保存后要即时生效：每处理一条消息都读一次最新配置（数组很小，开销可以忽略）。
+  const read = typeof config === 'function' ? config : () => config;
 
   return async function qqbotGuard(ctx, next) {
+    const current = read() ?? DEFAULT_CONFIG;
+    const triggers = (current.triggers ?? []).filter((t) => typeof t === 'string' && t.length > 0);
+    const ignoreCase = current.ignoreCase !== false;
+    const faces = current.faces !== false;
+    const historyAttachments = current.historyAttachments !== false;
     try {
       const msg = ctx?.message;
       if (faces && typeof msg?.content === 'string') {
@@ -778,15 +1019,34 @@ export function installGuard(QQBot, guard, logger = console) {
 
 export async function apply(ctx, config) {
   const log = pickLogger(ctx);
-  const cfg = mergeConfig(config, log);
+  const source = createConfigSource(config, log);
+  const cfg = source.get();
+
+  /** 设置页显示的运行状态：qqbot 装在哪、补丁有没有生效。 */
+  const status = {
+    qqbot: '',
+    qqbotVersion: '',
+    sdk: '',
+    installed: false,
+    historyAttachments: false,
+    reason: '',
+  };
+  // 先挂配置接口：qqbot 没装、甚至 enabled=false 时，用户仍然要能打开设置页改配置。
+  installConfigApi(ctx, source, log, status, config);
 
   if (cfg.enabled === false) {
+    status.reason = 'enabled=false';
     log.info('[qqbot-guard] enabled=false，跳过（qqbot 行为保持原样）');
     return;
   }
 
   const qqbot = findQqbotPackage(cfg, log);
-  if (!qqbot) return;
+  if (!qqbot) {
+    status.reason = '没找到 @tencent-connect/dsh-qqbot';
+    return;
+  }
+  status.qqbot = qqbot.dir;
+  status.qqbotVersion = qqbot.pkg?.version ?? '';
 
   let sdkInfo;
   try {
@@ -824,12 +1084,15 @@ export async function apply(ctx, config) {
 
   const notes = new Map();
   const mediaDownloader = makeMediaDownloader(qqbot.dir, cfg, log);
-  const guard = createGuard(cfg, log, notes, mediaDownloader);
+  const guard = createGuard(() => source.get(), log, notes, mediaDownloader);
   const result = installGuard(sdk.QQBot, guard, log);
   if (!result.installed) {
+    status.reason = `补丁未安装：${result.reason}`;
     log.error(`[qqbot-guard] 补丁未安装：${result.reason}`);
     return;
   }
+  status.installed = true;
+  status.sdk = sdkInfo.version ?? '';
 
   let historyPatched = false;
   let mediaRoot = '';
@@ -854,6 +1117,7 @@ export async function apply(ctx, config) {
       log.warn(`[qqbot-guard] 历史附件摘要未启用: ${err?.message ?? err}`);
     }
   }
+  status.historyAttachments = historyPatched;
 
   if (cfg.verbose) {
     const cfgFile = resolveConfigFile(cfg);

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "dsh-qqbot-guard",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
-  "description": "qqbot 增强层：群聊关键词放行 + 历史上下文 + 进程内补丁（不改 qqbot 文件）",
+  "description": "qqbot 增强层：群聊关键词放行 + 历史上下文 + 设置页可视化配置（进程内补丁，不改 qqbot 文件）",
   "license": "MIT",
   "main": "./index.js",
   "exports": {
-    ".": "./index.js"
+    ".": "./index.js",
+    "./client": "./client/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
   },
   "files": [
     "index.js",
+    "client",
     "cordis.patch.yml",
     "README.md"
   ],
@@ -39,6 +43,13 @@
     "manifestVersion": 1,
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
     }
   },
   "peerDependencies": {