@dsh-plugin/dsh-synapse 0.0.0-stage → 0.1.0-dev.41044228975

package/vendor/gugle-chat-bot/src/features/hermes/config.ts

@@ -0,0 +1,210 @@
+import { ConfigStore } from '@/config/manager';
+import { isOperator } from '@/config/features';
+
+/**
+ * Hermes Agent 桥接配置（移植自 qq-hermes-bridge 的 .env 配置，MIT 协议，原作者 Amorter）。
+ *
+ * 配置文件：configs/features/hermes.json（v1，ConfigStore 热重载）：
+ * ```json
+ * {
+ *   "version": 1,
+ *   "apiUrl": "http://127.0.0.1:8642",
+ *   "apiKey": "",
+ *   "botName": "小喵",
+ *   "groups": [659356928],
+ *   "admins": [],
+ *   "requireMention": true,
+ *   "keywordTriggers": ["小喵"],
+ *   "replyPerSentence": true,
+ *   "compactMaxChars": 300,
+ *   "compactMaxLines": 5,
+ *   "privateReactionFallbackText": true,
+ *   "privateReceiptText": "🤔 收到，正在思考…"
+ * }
+ * ```
+ * - `groups`：启用 AI 对话的 QQ 群（空=群聊不启用）；互通的 Discord 频道能否触发 AI
+ *   也由其桥接的 QQ 群是否在此列表决定；私聊始终启用（受用户黑白名单约束）；
+ * - `replyPerSentence`：QQ 群聊 AI 回复逐句发送；单条超过 compactMaxChars 字或
+ *   compactMaxLines 行时改用聊天记录（合并转发）发送，任一项填 0 关闭该维度；
+ * - `privateReactionFallbackText`：私聊贴表情失败时改发文字回执（NapCat 对私聊
+ *   消息通常不支持 set_msg_emoji_like），AI 首条回复发出后自动撤回；
+ * - Bot QQ 号无需配置，取 bot.getLoginInfoSync().user_id（@提及判定）；
+ * - 系统提示词优先级：configs/SOUL.md > systemPrompt > 空。
+ */
+
+export interface HermesBridgeConfig {
+  version: number;
+  /** Hermes API Server 地址 */
+  apiUrl: string;
+  /** API Key（Hermes 配置了认证时填） */
+  apiKey: string;
+  /** Bot 名称（卡片落款、合并转发署名等展示用） */
+  botName: string;
+  /** 启用 AI 对话的 QQ 群（空数组=群聊不启用） */
+  groups: number[];
+  /** 管理员 QQ 号（与 management operators 合并生效） */
+  admins: number[];
+  /** 允许私聊/对话的用户（空=全部允许） */
+  allowedUsers: number[];
+  /** 屏蔽的用户 */
+  blockedUsers: number[];
+  /** 群聊中是否需要 @bot 才触发 */
+  requireMention: boolean;
+  /** 关键词触发列表（小写匹配） */
+  keywordTriggers: string[];
+  /** 进度卡片发送最小间隔（秒） */
+  progressRateLimitSec: number;
+  /** 是否以图片形式发送进度 */
+  progressAsImage: boolean;
+  /** 进度卡片最多显示的工具数量 */
+  progressMaxTools: number;
+  /** 单条消息最大长度（超出切分发送） */
+  maxMessageLength: number;
+  /** 是否将消息中的图片原图转发给 Hermes（多模态识别） */
+  forwardImages: boolean;
+  /** 是否按句拆分 AI 回复逐条发送（关闭则整段一次发出） */
+  replyPerSentence: boolean;
+  /** 单条回复超过该字数改用聊天记录（合并转发）发送；0=关闭该维度 */
+  compactMaxChars: number;
+  /** 单条回复超过该行数改用聊天记录（合并转发）发送；0=关闭该维度 */
+  compactMaxLines: number;
+  /** 系统提示词（被 configs/SOUL.md 覆盖） */
+  systemPrompt: string;
+  /** 保留的历史消息轮数 */
+  localHistoryMaxMessages: number;
+  /** 是否启用对话历史持久化存储 */
+  persistHistoryEnabled: boolean;
+  /** 持久化保留的最大消息数 */
+  persistHistoryMax: number;
+  /** 是否启用命令审批 */
+  approvalEnabled: boolean;
+  /** 审批超时自动拒绝（秒），0=不超时 */
+  approvalTimeoutSec: number;
+  /** 是否启用「AI 处理中」表情回应（QQ 贴表情 / Discord reaction，完成后摘除） */
+  reactionEnabled: boolean;
+  /** QQ 表情回应的 emoji_id（NapCat set_msg_emoji_like；76=👍 强） */
+  reactionEmojiQq: string;
+  /** Discord 表情回应（unicode emoji） */
+  reactionEmojiDiscord: string;
+  /**
+   * 私聊贴表情失败时改用文字回执（默认 true）。
+   * NapCat 对私聊消息通常不支持 set_msg_emoji_like，贴表情会失败；
+   * 开启后改发一条简短提示，让用户知道 AI 已收到（群聊不受影响）。
+   */
+  privateReactionFallbackText: boolean;
+  /** 私聊文字回执内容（privateReactionFallbackText 开启且贴表情失败时发送） */
+  privateReceiptText: string;
+}
+
+export function hermesConfigFactory(): HermesBridgeConfig {
+  return {
+    version: 1,
+    apiUrl: 'http://127.0.0.1:8642',
+    apiKey: '',
+    botName: '小喵',
+    groups: [],
+    admins: [],
+    allowedUsers: [],
+    blockedUsers: [],
+    requireMention: true,
+    keywordTriggers: [],
+    progressRateLimitSec: 15,
+    progressAsImage: true,
+    progressMaxTools: 12,
+    maxMessageLength: 1200,
+    forwardImages: true,
+    replyPerSentence: true,
+    compactMaxChars: 300,
+    compactMaxLines: 5,
+    systemPrompt: '',
+    localHistoryMaxMessages: 24,
+    persistHistoryEnabled: true,
+    persistHistoryMax: 100,
+    approvalEnabled: true,
+    approvalTimeoutSec: 300,
+    reactionEnabled: true,
+    reactionEmojiQq: '76',
+    reactionEmojiDiscord: '👀',
+    privateReactionFallbackText: true,
+    privateReceiptText: '🤔 收到，正在思考…'
+  };
+}
+
+function asString(raw: unknown, fallback: string): string {
+  return typeof raw === 'string' ? raw : fallback;
+}
+
+function asBool(raw: unknown, fallback: boolean): boolean {
+  return typeof raw === 'boolean' ? raw : fallback;
+}
+
+function asPositiveNumber(raw: unknown, fallback: number): number {
+  return typeof raw === 'number' && Number.isFinite(raw) && raw >= 0 ? raw : fallback;
+}
+
+function asQqList(raw: unknown): number[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((item): item is number => typeof item === 'number' && Number.isSafeInteger(item) && item > 0);
+}
+
+function asStringList(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((item): item is string => typeof item === 'string' && item.length > 0);
+}
+
+export function normalizeHermesConfig(raw: unknown): HermesBridgeConfig | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const record = raw as Record<string, unknown>;
+  const fallback = hermesConfigFactory();
+  return {
+    version: 1,
+    apiUrl: asString(record.apiUrl, fallback.apiUrl),
+    apiKey: asString(record.apiKey, fallback.apiKey),
+    botName: asString(record.botName, fallback.botName),
+    groups: asQqList(record.groups),
+    admins: asQqList(record.admins),
+    allowedUsers: asQqList(record.allowedUsers),
+    blockedUsers: asQqList(record.blockedUsers),
+    requireMention: asBool(record.requireMention, fallback.requireMention),
+    keywordTriggers: asStringList(record.keywordTriggers).map(keyword => keyword.toLowerCase()),
+    progressRateLimitSec: asPositiveNumber(record.progressRateLimitSec, fallback.progressRateLimitSec),
+    progressAsImage: asBool(record.progressAsImage, fallback.progressAsImage),
+    progressMaxTools: asPositiveNumber(record.progressMaxTools, fallback.progressMaxTools),
+    maxMessageLength: asPositiveNumber(record.maxMessageLength, fallback.maxMessageLength),
+    forwardImages: asBool(record.forwardImages, fallback.forwardImages),
+    replyPerSentence: asBool(record.replyPerSentence, fallback.replyPerSentence),
+    compactMaxChars: asPositiveNumber(record.compactMaxChars, fallback.compactMaxChars),
+    compactMaxLines: asPositiveNumber(record.compactMaxLines, fallback.compactMaxLines),
+    systemPrompt: asString(record.systemPrompt, fallback.systemPrompt),
+    localHistoryMaxMessages: asPositiveNumber(record.localHistoryMaxMessages, fallback.localHistoryMaxMessages),
+    persistHistoryEnabled: asBool(record.persistHistoryEnabled, fallback.persistHistoryEnabled),
+    persistHistoryMax: asPositiveNumber(record.persistHistoryMax, fallback.persistHistoryMax),
+    approvalEnabled: asBool(record.approvalEnabled, fallback.approvalEnabled),
+    approvalTimeoutSec: asPositiveNumber(record.approvalTimeoutSec, fallback.approvalTimeoutSec),
+    reactionEnabled: asBool(record.reactionEnabled, fallback.reactionEnabled),
+    reactionEmojiQq: asString(record.reactionEmojiQq, fallback.reactionEmojiQq),
+    reactionEmojiDiscord: asString(record.reactionEmojiDiscord, fallback.reactionEmojiDiscord),
+    privateReactionFallbackText: asBool(record.privateReactionFallbackText, fallback.privateReactionFallbackText),
+    privateReceiptText: asString(record.privateReceiptText, fallback.privateReceiptText)
+  };
+}
+
+const hermesStore = new ConfigStore<HermesBridgeConfig>({
+  path: 'configs/features/hermes.json',
+  version: 1,
+  factory: hermesConfigFactory,
+  normalize: normalizeHermesConfig
+});
+
+/** 读取 Hermes 桥接生效配置（热重载） */
+export function getHermesConfig(): HermesBridgeConfig {
+  return hermesStore.get();
+}
+
+/**
+ * 有效管理员判定：hermes 自有 admins ∪ management operators。
+ * 与 /pardon、/github allow 等管理命令保持「谁是管理员」口径一致。
+ */
+export function isHermesAdmin(qqUserId: number): boolean {
+  return getHermesConfig().admins.includes(qqUserId) || isOperator(qqUserId);
+}

package/vendor/gugle-chat-bot/src/features/hermes/context.ts

@@ -0,0 +1,67 @@
+import { HistoryEntry, RouteInfo } from '@/features/hermes/types';
+
+/**
+ * 会话上下文组装（纯函数）。
+ *
+ * 群聊/互通频道的会话历史是多人共享的，若原样平铺提交，模型分不清「谁在跟我
+ * 说话、哪些是背景闲聊、我之前回复的是谁」，容易串台认错人。这里在提交时按
+ * 当前对话者动态标注归属（存储层保持原样）：
+ * - 当前对话者的消息：保持 `发送者: 内容` 原样（对话主线）；
+ * - 其他成员的消息：加 [群聊背景] 前缀（旁听内容，不是对 AI 说的话）；
+ * - AI 回复过其他成员的话：加 [你回复 xxx 的话] 前缀（避免误认为是对当前
+ *   对话者说的）。
+ */
+
+/** 背景消息前缀：其他成员的闲聊 */
+export const BG_PREFIX = '[群聊背景]';
+
+/** 组装提交给 Hermes 的 conversation_history（按当前对话者标注归属） */
+export function buildConversationHistory(
+  history: HistoryEntry[],
+  currentUserId: string
+): Array<{ role: string; content: string }> {
+  return history.map(entry => {
+    if (entry.role === 'user') {
+      if (entry.userId !== undefined && entry.userId !== currentUserId) {
+        return { role: 'user', content: `${BG_PREFIX} ${entry.content}` };
+      }
+      return { role: 'user', content: entry.content };
+    }
+    if (entry.role === 'assistant') {
+      if (entry.userId !== undefined && entry.userId !== currentUserId) {
+        return { role: 'assistant', content: `[你回复 ${entry.label ?? entry.userId} 的话] ${entry.content}` };
+      }
+      return { role: 'assistant', content: entry.content };
+    }
+    return { role: entry.role, content: entry.content };
+  });
+}
+
+/**
+ * 群聊/互通频道的上下文系统提示（QQ 群与 Discord 路由统一口径）。
+ * 显式声明当前对话者与历史标注约定，配合 buildConversationHistory 使用。
+ */
+export function buildGroupContext(route: RouteInfo, senderLabel: string): string {
+  const where =
+    route.type === 'group'
+      ? `你正在 QQ 群 ${route.groupId} 中（该群与 Discord 频道互通，消息也可能来自 Discord 用户）。`
+      : `你正在 QQ 群 ${route.groupId} 互通的 Discord 频道 #${route.discord?.channelName ?? ''} 中（频道与 QQ 群消息互通）。`;
+  return [
+    where,
+    '群聊有多个成员，发送者标识格式为「昵称 (ID)」：纯数字 ID 是 QQ 号，dc: 前缀的是 Discord 用户，请据此区分不同的人。',
+    `历史消息中带 ${BG_PREFIX} 前缀的是其他成员的闲聊，不是对你说的话，仅供你了解上下文，不要回应、也不要当成你自己的记忆；带 [你回复 xxx 的话] 前缀的是你之前回复其他成员的内容。`,
+    `当前与你对话的是 ${senderLabel}，只需回应 TA 的消息。回复简短口语化，符合聊天风格。`
+  ].join('\n');
+}
+
+/**
+ * 消息中的 Issue/PR 编号会被消息管道自动渲染卡片时，给 AI 输入追加注记，
+ * 避免 AI 再调用查Issue技能重复发同一张卡片（autoCardCount=0 时原样返回）。
+ */
+export function appendAutoCardNote(text: string, autoCardCount: number): string {
+  if (autoCardCount <= 0) return text;
+  return (
+    `${text}\n（系统提示：本条消息中的 ${autoCardCount} 个 Issue/PR 编号已由系统自动生成信息卡片并发出，` +
+    `请直接据此回答，不要再调用查Issue技能重复发送卡片）`
+  );
+}

package/vendor/gugle-chat-bot/src/features/hermes/history.ts

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { HistoryEntry } from '@/features/hermes/types';
+
+/**
+ * 聊天记录持久化存储（移植自 qq-hermes-bridge src/history.ts，MIT 协议，原作者 Amorter）。
+ * 每个会话以 JSON 文件形式存储在 data/hermes-history/，最多保留 N 条消息，
+ * 进程重启后自动恢复。
+ */
+export class ChatHistoryStore {
+  private readonly dir: string;
+  private readonly maxMessages: number;
+  private readonly enabled: boolean;
+
+  /** 内存缓存：key → 历史消息数组 */
+  private readonly cache = new Map<string, HistoryEntry[]>();
+
+  /**
+   * @param maxMessages 每个会话最多保留的消息条数
+   * @param enabled 是否启用持久化
+   */
+  public constructor(maxMessages: number, enabled: boolean) {
+    this.dir = path.resolve(process.cwd(), 'data', 'hermes-history');
+    this.maxMessages = maxMessages;
+    this.enabled = enabled;
+    if (enabled) {
+      fs.mkdirSync(this.dir, { recursive: true });
+    }
+  }
+
+  /**
+   * 加载会话历史。
+   * 优先从内存缓存读取，缓存未命中时从磁盘加载。
+   */
+  public load(key: string): HistoryEntry[] {
+    if (!this.enabled) return [];
+    if (this.cache.has(key)) return this.cache.get(key)!;
+
+    try {
+      const filePath = this.filePath(key);
+      if (fs.existsSync(filePath)) {
+        const data = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as HistoryEntry[];
+        if (Array.isArray(data)) {
+          this.cache.set(key, data);
+          return data;
+        }
+      }
+    } catch {
+      // 文件损坏或格式错误，忽略
+    }
+    return [];
+  }
+
+  /**
+   * 保存会话历史。
+   * 自动裁剪到 maxMessages 条，先写内存缓存再落盘。
+   */
+  public save(key: string, history: HistoryEntry[]): void {
+    if (!this.enabled) return;
+    const trimmed = history.slice(-this.maxMessages);
+    this.cache.set(key, trimmed);
+    try {
+      fs.writeFileSync(this.filePath(key), JSON.stringify(trimmed, null, 2), 'utf-8');
+    } catch {
+      // 写入失败不阻塞主流程（磁盘满等极端情况）
+    }
+  }
+
+  /** 清除会话的持久化历史 */
+  public clear(key: string): void {
+    if (!this.enabled) return;
+    this.cache.delete(key);
+    try {
+      const filePath = this.filePath(key);
+      if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+    } catch {
+      // 忽略
+    }
+  }
+
+  /** 根据会话键生成安全的文件名（group:123456 → group_123456.json） */
+  private filePath(key: string): string {
+    const safe = key.replace(/[<>:"/\\|?*]/g, '_');
+    return path.join(this.dir, `${safe}.json`);
+  }
+}