koishi-plugin-dify-ai 0.1.4 → 0.1.6

package/lib/api/client.d.ts

@@ -18,7 +18,6 @@ export declare class DifyClient {
     /** blocking JSON 请求（本插件只用 blocking 模式） */
     private request;
     getAppInfo(): Promise<DifyAppInfo>;
-    getParameters(): Promise<any>;
     /** chat / agent-chat / advanced-chat（conversation_id 传空串表示新建会话） */
     runChat(body: {
         inputs: Record<string, any>;

package/lib/config.d.ts

@@ -1,5 +1,5 @@
 import { Schema } from 'koishi';
-import { DifyRule } from './types';
+import { CooldownSetting, DifyRule } from './types';
 export type AppTypeSetting = 'auto' | 'chat' | 'agent-chat' | 'advanced-chat' | 'workflow' | 'completion';
 export interface AppConfigEntry {
     name: string;
@@ -48,6 +48,10 @@ export type VariableEntry = {
     source: 'meta';
     field: string;
     key: string;
+} | {
+    source: 'constant';
+    field: string;
+    value: string;
 };
 /** 作用域的一行：维度 + 值 */
 export interface ScopeRow {
@@ -64,23 +68,72 @@ export interface RuleEntry {
     scope: ScopeRow[];
     variables: VariableEntry[];
 }
+/** 引用触发消息的条件分支形态：关闭时空分支，开启时按耗时阈值决定是否引用 */
+export type QuoteEntry = {
+    mode: 'off';
+} | {
+    mode: 'on';
+    minElapsedSeconds: number;
+};
+/** 触发后冷却的条件分支形态 */
+export type CooldownEntry = {
+    mode: 'off';
+} | {
+    mode: 'fixed';
+    seconds?: number;
+} | {
+    mode: 'sliding';
+    minSeconds?: number;
+    maxSeconds?: number;
+};
+/** 上传消息文件的条件分支形态：关闭时空分支，开启时限制数量与单文件大小 */
+export type UploadEntry = {
+    mode: 'off';
+} | {
+    mode: 'on';
+    maxCount?: number;
+    maxSizeMb?: number;
+};
 export interface Config {
     apps: AppConfigEntry[];
     rules: RuleEntry[];
     parseElements: boolean;
-    quoteTrigger: boolean;
+    quote: QuoteEntry;
     maxSegmentLength: number;
-    uploadFiles: boolean;
+    /** boolean 是 0.1.x 的遗留形态，仅迁移读取（true → 开启不限，false → 关闭） */
+    uploadFiles: UploadEntry | boolean;
+    /** 0.1.x 的布尔开关，仅用于迁移读取（true → 总是引用，false → 关闭） */
+    quoteTrigger?: boolean;
     requestTimeout: number;
     historyLimit: number;
     sendErrors: boolean;
+    cooldown: CooldownEntry;
 }
 export declare const Config: Schema<Config>;
 /**
- * 配置规范化：应用表 + 按优先级降序的规则列表。
+ * 上传消息文件配置（含 0.1.x 布尔遗留形态迁移）：
+ * 数量与单文件大小 0 均为不限，大小仍与 Dify 各类型上限取较小值。
+ */
+export declare function resolveUploadConfig(config: Config): {
+    enabled: boolean;
+    maxCount: number;
+    maxMb: number;
+};
+/**
+ * 引用触发消息配置（含 0.1.x 布尔开关迁移）：schema 会给旧配置填默认 quote 对象，
+ * 因此迁移判据是「旧布尔被配置层透传保留 且 quote 仍是默认形态（用户未在新表单改过）」——
+ * 此时以旧布尔为准；用户改过新表单（quote 非默认）则新值优先。
+ */
+export declare function resolveQuoteConfig(config: Config): {
+    enabled: boolean;
+    minElapsedSeconds: number;
+};
+/**
+ * 配置规范化：应用表 + 按优先级降序的规则列表 + 冷却设置。
  * 坏条件/无名变量直接丢弃；引用不存在应用的规则保留但运行时会 warn 跳过。
  */
 export declare function normalizeConfig(config: Config): {
     apps: Map<string, AppConfigEntry>;
     rules: DifyRule[];
+    cooldown: CooldownSetting | null;
 };

package/lib/history.d.ts

@@ -11,8 +11,12 @@ export interface HistoryEntry {
     userId: string;
     username: string;
     messageId?: string;
-    /** 纯文本 + 图片占位符 */
+    /** 原貌（含 @bot 渲染与图片占位）：统一格式行（query/历史变量）用 */
     content: string;
+    /** 剔除 @bot 的原貌：content 变量与精简行用 */
+    contentText: string;
+    /** 图片元素 URL（按元素序，与 content 中 [image:摘要] 序一致）：窗口类触发的上传依据 */
+    imageUrls?: string[];
     timestamp: number;
     quote?: QuotedMessage;
 }
@@ -24,6 +28,8 @@ export interface HistoryEntry {
 export declare function formatHistoryEntry(entry: HistoryEntry): string;
 /** 多条消息逐行拼接 */
 export declare function formatHistoryEntries(entries: HistoryEntry[]): string;
+/** 精简行：只记消息 ID 与剔除 @bot 的原貌内容，不带时间与作者前缀——窗口触发的 content 变量用 */
+export declare function formatHistoryBrief(entries: HistoryEntry[]): string;
 /** 从会话消息构造记录条目（历史缓冲 / 消息池共用）；assistant 行标注为机器人自己的发言 */
 export declare function buildHistoryEntry(session: Session, role?: 'user' | 'assistant'): HistoryEntry | null;
 /**

package/lib/index.js

@@ -92,6 +92,7 @@ var conditionSchema = import_koishi.Schema.union([
   }).default({ type: "density", densityCount: 5, densityWindowSeconds: 60 }).description("消息密度")
 ]);
 var sessionKeySchema = import_koishi.Schema.union([
+  import_koishi.Schema.const("none").description("无"),
   import_koishi.Schema.const("userId").description("用户 ID"),
   import_koishi.Schema.const("botId").description("Bot ID"),
   import_koishi.Schema.const("guildId").description("群聊 ID"),
@@ -106,6 +107,7 @@ var sessionKeySchema = import_koishi.Schema.union([
   import_koishi.Schema.const("isDirect").description("是否私聊")
 ]);
 var metaKeySchema = import_koishi.Schema.union([
+  import_koishi.Schema.const("none").description("无"),
   import_koishi.Schema.const("triggerType").description("触发类型"),
   import_koishi.Schema.const("ruleName").description("规则名"),
   import_koishi.Schema.const("triggerTime").description("触发时间")
@@ -114,8 +116,8 @@ var variableSchema = import_koishi.Schema.union([
   import_koishi.Schema.object({
     source: import_koishi.Schema.const("session").required(),
     field: import_koishi.Schema.string().required().description("字段名"),
-    key: sessionKeySchema.default("content").description("变量")
-  }).default({ source: "session", field: "", key: "content" }).description("会话字段"),
+    key: sessionKeySchema.default("none").description("变量")
+  }).default({ source: "session", field: "", key: "none" }).description("会话字段"),
   import_koishi.Schema.object({
     source: import_koishi.Schema.const("history").required(),
     field: import_koishi.Schema.string().required().description("字段名"),
@@ -124,8 +126,46 @@ var variableSchema = import_koishi.Schema.union([
   import_koishi.Schema.object({
     source: import_koishi.Schema.const("meta").required(),
     field: import_koishi.Schema.string().required().description("字段名"),
-    key: metaKeySchema.default("triggerType").description("变量")
-  }).default({ source: "meta", field: "", key: "triggerType" }).description("触发元信息")
+    key: metaKeySchema.default("none").description("变量")
+  }).default({ source: "meta", field: "", key: "none" }).description("触发元信息"),
+  import_koishi.Schema.object({
+    source: import_koishi.Schema.const("constant").required(),
+    field: import_koishi.Schema.string().required().description("字段名"),
+    value: import_koishi.Schema.string().role("textarea").required().description("固定文本")
+  }).default({ source: "constant", field: "", value: "" }).description("常量文本")
+]);
+var quoteSchema = import_koishi.Schema.union([
+  import_koishi.Schema.object({
+    mode: import_koishi.Schema.const("off").required()
+  }).default({ mode: "off" }).description("关闭"),
+  import_koishi.Schema.object({
+    mode: import_koishi.Schema.const("on").required(),
+    minElapsedSeconds: import_koishi.Schema.natural().default(0).description("回复耗时多少秒才引用，0 总是引用")
+  }).default({ mode: "on", minElapsedSeconds: 0 }).description("开启")
+]);
+var cooldownSchema = import_koishi.Schema.union([
+  import_koishi.Schema.object({
+    mode: import_koishi.Schema.const("off").required()
+  }).default({ mode: "off" }).description("关闭"),
+  import_koishi.Schema.object({
+    mode: import_koishi.Schema.const("fixed").required(),
+    seconds: import_koishi.Schema.natural().default(30).min(1).description("冷却秒数")
+  }).default({ mode: "fixed", seconds: 30 }).description("固定窗口"),
+  import_koishi.Schema.object({
+    mode: import_koishi.Schema.const("sliding").required(),
+    minSeconds: import_koishi.Schema.natural().default(30).min(1).description("最小冷却秒数"),
+    maxSeconds: import_koishi.Schema.natural().default(120).min(1).description("最大冷却秒数")
+  }).default({ mode: "sliding", minSeconds: 30, maxSeconds: 120 }).description("滑动窗口")
+]);
+var uploadSchema = import_koishi.Schema.union([
+  import_koishi.Schema.object({
+    mode: import_koishi.Schema.const("off").required()
+  }).default({ mode: "off" }).description("关闭"),
+  import_koishi.Schema.object({
+    mode: import_koishi.Schema.const("on").required(),
+    maxCount: import_koishi.Schema.natural().default(0).description("数量上限，0 不限"),
+    maxSizeMb: import_koishi.Schema.natural().default(0).description("单文件大小上限 MB，0 不限")
+  }).default({ mode: "on", maxCount: 0, maxSizeMb: 0 }).description("开启")
 ]);
 var Config = import_koishi.Schema.intersect([
   import_koishi.Schema.object({
@@ -173,14 +213,15 @@ var Config = import_koishi.Schema.intersect([
   }).description("触发规则"),
   import_koishi.Schema.object({
     parseElements: import_koishi.Schema.boolean().default(false).description("解析回复中的消息元素"),
-    quoteTrigger: import_koishi.Schema.boolean().default(true).description("引用触发消息"),
+    quote: quoteSchema.default({ mode: "on", minElapsedSeconds: 0 }).description("引用触发消息"),
     maxSegmentLength: import_koishi.Schema.natural().default(0).description("分段长度，0 不分段"),
-    uploadFiles: import_koishi.Schema.boolean().default(true).description("上传消息中的文件")
+    uploadFiles: uploadSchema.default({ mode: "on", maxCount: 0, maxSizeMb: 0 }).description("上传消息中的文件")
   }).description("回复行为"),
   import_koishi.Schema.object({
     requestTimeout: import_koishi.Schema.natural().role("ms").default(3e5).description("请求超时"),
     historyLimit: import_koishi.Schema.natural().default(20).min(1).description("历史消息条数"),
-    sendErrors: import_koishi.Schema.boolean().default(false).description("失败时提示错误")
+    sendErrors: import_koishi.Schema.boolean().default(false).description("失败时提示错误"),
+    cooldown: cooldownSchema.default({ mode: "off" }).description("触发后冷却")
   }).description("运行参数")
 ]);
 var CONVERSATION_SCOPES = ["per-user", "per-guild", "per-channel", "global"];
@@ -269,17 +310,61 @@ __name(toScope, "toScope");
 function toVariable(entry) {
   const field = entry.field?.trim();
   if (!field) return null;
+  if (entry.source === "constant") {
+    if (!entry.value) return null;
+    return { field, source: { type: "constant", value: entry.value } };
+  }
   if (entry.source === "meta") {
+    if (entry.key === "none") return null;
     return { field, source: { type: "meta", key: entry.key || "triggerType" } };
   }
   if (entry.source === "history") {
     const limit = Number(entry.limit);
     return { field, source: { type: "history", ...limit > 0 ? { limit } : {} } };
   }
-  if (entry.key === "history") return null;
+  if (entry.key === "none" || entry.key === "history") return null;
   return { field, source: { type: "session", key: entry.key || "content" } };
 }
 __name(toVariable, "toVariable");
+function resolveUploadConfig(config) {
+  if (typeof config.uploadFiles === "boolean") {
+    return config.uploadFiles ? { enabled: true, maxCount: 0, maxMb: 0 } : { enabled: false, maxCount: 0, maxMb: 0 };
+  }
+  if (config.uploadFiles?.mode === "off") return { enabled: false, maxCount: 0, maxMb: 0 };
+  return {
+    enabled: true,
+    maxCount: Math.max(0, Number(config.uploadFiles?.maxCount) || 0),
+    maxMb: Math.max(0, Number(config.uploadFiles?.maxSizeMb) || 0)
+  };
+}
+__name(resolveUploadConfig, "resolveUploadConfig");
+function resolveQuoteConfig(config) {
+  if (config.quote?.mode === "off") return { enabled: false, minElapsedSeconds: 0 };
+  if (config.quote?.mode === "on") {
+    return { enabled: true, minElapsedSeconds: Math.max(0, Number(config.quote.minElapsedSeconds) || 0) };
+  }
+  if (config.quoteTrigger === false) return { enabled: false, minElapsedSeconds: 0 };
+  return { enabled: true, minElapsedSeconds: 0 };
+}
+__name(resolveQuoteConfig, "resolveQuoteConfig");
+function toCooldown(entry) {
+  if (entry?.mode === "fixed") {
+    const seconds = Number(entry.seconds);
+    return seconds > 0 ? { mode: "fixed", ms: seconds * 1e3 } : null;
+  }
+  if (entry?.mode === "sliding") {
+    const minSeconds = Number(entry.minSeconds);
+    const maxSeconds = Number(entry.maxSeconds);
+    if (!(minSeconds > 0) || !(maxSeconds > 0)) return null;
+    return {
+      mode: "sliding",
+      minMs: minSeconds * 1e3,
+      maxMs: Math.max(minSeconds, maxSeconds) * 1e3
+    };
+  }
+  return null;
+}
+__name(toCooldown, "toCooldown");
 function normalizeConfig(config) {
   const apps = /* @__PURE__ */ new Map();
   for (const app of config.apps ?? []) {
@@ -302,7 +387,7 @@ function normalizeConfig(config) {
     });
   }
   rules.sort((a, b) => b.priority - a.priority);
-  return { apps, rules };
+  return { apps, rules, cooldown: toCooldown(config.cooldown) };
 }
 __name(normalizeConfig, "normalizeConfig");
 
@@ -413,6 +498,7 @@ function createDifyClient(ctx, app, timeout) {
 __name(createDifyClient, "createDifyClient");
 
 // src/utils/session-text.ts
+var import_crypto = require("crypto");
 var import_koishi2 = require("koishi");
 function parseTextSafe(content) {
   if (!content) return "";
@@ -423,15 +509,28 @@ function parseTextSafe(content) {
   }
 }
 __name(parseTextSafe, "parseTextSafe");
-function extractText(session, options = {}) {
+function extractText(session) {
   if (session.elements?.length) {
-    const elements = options.excludeAt ? session.elements.filter((element) => element.type !== "at") : session.elements;
-    return import_koishi2.h.select(elements, "text").join("").trim();
+    return import_koishi2.h.select(session.elements, "text").join("").trim();
   }
   return parseTextSafe(session.content);
 }
 __name(extractText, "extractText");
 var IMAGE_PLACEHOLDER = "[图片]";
+function imagePlaceholder(url) {
+  if (!url) return IMAGE_PLACEHOLDER;
+  return `[image:${(0, import_crypto.createHash)("sha1").update(url).digest("hex").slice(0, 8)}]`;
+}
+__name(imagePlaceholder, "imagePlaceholder");
+function annotateDroppedPlaceholders(text, droppedUrls) {
+  let result = text;
+  for (const url of droppedUrls) {
+    const placeholder = imagePlaceholder(url);
+    result = result.split(placeholder).join(`${placeholder}（已丢弃）`);
+  }
+  return result;
+}
+__name(annotateDroppedPlaceholders, "annotateDroppedPlaceholders");
 function extractTextWithPlaceholders(session) {
   const elements = session.elements?.length ? session.elements : (() => {
     try {
@@ -445,8 +544,11 @@ function extractTextWithPlaceholders(session) {
     if (element.type === "text") {
       const text = element.attrs?.["content"] ?? "";
       if (text) parts.push(text);
+    } else if (element.type === "at") {
+      const name2 = element.attrs?.["name"] ?? element.attrs?.["id"];
+      if (name2) parts.push(`@${name2}`);
     } else if (element.type === "img" || element.type === "image") {
-      parts.push(IMAGE_PLACEHOLDER);
+      parts.push(imagePlaceholder(element.attrs?.["url"] ?? element.attrs?.["src"]));
     }
   }
   return parts.join(" ").replace(/\s+/g, " ").trim();
@@ -472,6 +574,10 @@ function formatHistoryEntries(entries) {
   return entries.map(formatHistoryEntry).join("\n");
 }
 __name(formatHistoryEntries, "formatHistoryEntries");
+function formatHistoryBrief(entries) {
+  return entries.map((entry) => entry.messageId ? `[msg:${entry.messageId}] ${entry.content}` : entry.content).join("\n");
+}
+__name(formatHistoryBrief, "formatHistoryBrief");
 function buildQuote(session) {
   const quote = session.quote;
   if (!quote?.user?.id) return void 0;
@@ -531,38 +637,39 @@ function hasAt(session, id) {
 __name(hasAt, "hasAt");
 function evaluateCondition(condition, session) {
   const text = extractText(session);
+  const verbatim = extractTextWithPlaceholders(session);
   switch (condition.type) {
     case "keyword-prefix": {
       const keyword = condition.keywords.find((k) => k && text.startsWith(k));
       if (!keyword) return null;
       const rest = text.slice(keyword.length).trim();
-      return { type: "keyword-prefix", queryText: rest || text };
+      return { type: "keyword-prefix", queryText: rest || verbatim };
     }
     case "keyword-contains": {
       const keyword = condition.keywords.find((k) => k && text.includes(k));
       if (!keyword) return null;
-      return { type: "keyword-contains", queryText: text };
+      return { type: "keyword-contains", queryText: verbatim };
     }
     case "at-bot": {
       const botId = session.bot?.userId;
       if (!botId) return null;
       if (!session.stripped?.atSelf && !hasAt(session, botId)) return null;
-      return { type: "at-bot", queryText: extractText(session, { excludeAt: true }) };
+      return { type: "at-bot", queryText: verbatim };
     }
     case "at-user": {
       const isAtAnyUser = condition.userIds.some((id) => hasAt(session, id));
       if (!isAtAnyUser) return null;
-      return { type: "at-user", queryText: text };
+      return { type: "at-user", queryText: verbatim };
     }
     case "quote-bot": {
       const botId = session.bot?.userId;
       if (!botId || session.quote?.user?.id !== botId) return null;
-      return { type: "quote-bot", queryText: extractText(session, { excludeAt: true }) };
+      return { type: "quote-bot", queryText: verbatim };
     }
     case "quote-user": {
       const author = session.quote?.user?.id;
       if (!author || !condition.userIds.includes(author)) return null;
-      return { type: "quote-user", queryText: extractText(session, { excludeAt: true }) };
+      return { type: "quote-user", queryText: verbatim };
     }
     default:
       return null;
@@ -597,7 +704,7 @@ function guildKeyOf(platform, guildId, channelId) {
 __name(guildKeyOf, "guildKeyOf");
 
 // src/trigger/pool.ts
-var POOL_CAPACITY = 256;
+var POOL_CAPACITY = 1024;
 function scopeSessionOf(pool, entry) {
   return {
     platform: pool.platform,
@@ -637,30 +744,44 @@ var MessagePool = class {
       pool.entries.splice(0, pool.entries.length - POOL_CAPACITY);
     }
   }
+  /** 时效内且通过规则作用域的真人条数（bot 行不推高密度，防自激励） */
+  countQualified(pool, rule, condition, now) {
+    const windowMs = condition.densityWindowSeconds * 1e3;
+    return pool.entries.filter(
+      (item) => item.role === "user" && now - item.timestamp <= windowMs && matchScope(rule.scope, scopeSessionOf(pool, item))
+    ).length;
+  }
   /**
    * 新消息入池后的密度评估：时效内（相对触发消息）且通过规则作用域的真人条数达到阈值。
    * 触发即取走并清空该频道全池（bot 行不推高密度，防自激励）；池清空后其余规则无从触发。
+   * skip 返回 true 的条件（冷却中的密度条件）不参与判定。
    */
-  checkDensity(rules, session) {
+  checkDensity(rules, session, skip) {
     const key = channelKeyOf(session.platform, session.channelId);
     const pool = this.channels.get(key);
     if (!pool) return [];
     const now = session.timestamp ?? Date.now();
     for (const rule of rules) {
-      for (const condition of rule.conditions) {
+      for (let index = 0; index < rule.conditions.length; index++) {
+        const condition = rule.conditions[index];
         if (condition.type !== "density") continue;
-        const windowMs = condition.densityWindowSeconds * 1e3;
-        const count = pool.entries.filter(
-          (item) => item.role === "user" && now - item.timestamp <= windowMs && matchScope(rule.scope, scopeSessionOf(pool, item))
-        ).length;
-        if (count >= condition.densityCount) {
+        if (skip?.(rule, condition, index)) continue;
+        if (this.countQualified(pool, rule, condition, now) >= condition.densityCount) {
           this.channels.delete(key);
-          return [{ rule, entries: pool.entries }];
+          return [{ rule, condition, conditionIndex: index, entries: pool.entries }];
         }
       }
     }
     return [];
   }
+  /** 冷却到期复查：按条件参数统计该频道池（now 为复查时刻），达标即取走整池，未达标返回 null */
+  takeDensityChannel(rule, condition, channelKey, now) {
+    const pool = this.channels.get(channelKey);
+    if (!pool) return null;
+    if (this.countQualified(pool, rule, condition, now) < condition.densityCount) return null;
+    this.channels.delete(channelKey);
+    return pool;
+  }
   /** 定时到点：取走该规则作用域内有消息的所有频道（整池清空，含未过作用域的条目） */
   takeSchedule(rule) {
     const taken = [];
@@ -741,25 +862,128 @@ var RuleScheduler = class {
   }
 };
 
+// src/trigger/cooldown.ts
+var BUFFER_CAPACITY = 1024;
+function densityLane(index) {
+  return `density:${index}`;
+}
+__name(densityLane, "densityLane");
+function laneKeyOf(ruleName, lane) {
+  return `${ruleName}
+${lane}`;
+}
+__name(laneKeyOf, "laneKeyOf");
+var TriggerCooldown = class {
+  constructor(setting) {
+    this.setting = setting;
+  }
+  static {
+    __name(this, "TriggerCooldown");
+  }
+  /** channelKey → (规则名+通道 → 冷却态) */
+  channels = /* @__PURE__ */ new Map();
+  get enabled() {
+    return this.setting != null;
+  }
+  /** 触发发起时登记冷却 */
+  begin(channelKey, ruleName, lane, now) {
+    if (!this.setting) return;
+    const ms = this.setting.mode === "fixed" ? this.setting.ms : this.setting.minMs;
+    this.lanesOf(channelKey).set(laneKeyOf(ruleName, lane), {
+      fireAt: now,
+      deadline: now + ms,
+      buffer: []
+    });
+  }
+  isCooling(channelKey, ruleName, lane, now) {
+    const state = this.lanesOf(channelKey).get(laneKeyOf(ruleName, lane));
+    return state != null && now < state.deadline;
+  }
+  /** 滑动窗口顺延：截止时间顺延到「now + 最小窗口」，不超过「触发时刻 + 最大窗口」 */
+  extend(channelKey, ruleName, lane, now) {
+    if (this.setting?.mode !== "sliding") return;
+    const state = this.lanesOf(channelKey).get(laneKeyOf(ruleName, lane));
+    if (!state) return;
+    state.deadline = Math.min(
+      Math.max(state.deadline, now + this.setting.minMs),
+      state.fireAt + this.setting.maxMs
+    );
+  }
+  /** 该频道所有密度通道由一条过路消息顺延（密度冷却期内的消息积攒驱动窗口滑动） */
+  extendDensityLanes(channelKey, now) {
+    if (this.setting?.mode !== "sliding") return;
+    const lanes = this.channels.get(channelKey);
+    if (!lanes) return;
+    for (const [key, state] of lanes) {
+      if (!key.includes("\ndensity:")) continue;
+      state.deadline = Math.min(
+        Math.max(state.deadline, now + this.setting.minMs),
+        state.fireAt + this.setting.maxMs
+      );
+    }
+  }
+  /** 冷却期内缓存一条命中消息（仅消息通道） */
+  bufferMessage(channelKey, ruleName, message) {
+    const state = this.lanesOf(channelKey).get(laneKeyOf(ruleName, "message"));
+    if (!state) return;
+    state.buffer.push(message);
+    if (state.buffer.length > BUFFER_CAPACITY) {
+      state.buffer.splice(0, state.buffer.length - BUFFER_CAPACITY);
+    }
+  }
+  /** 到期扫描：取走全部到期通道（连缓冲一并交出），由调用方决定是否重新登记 */
+  collectExpired(now) {
+    const expired = [];
+    for (const [channelKey, lanes] of this.channels) {
+      for (const [key, state] of lanes) {
+        if (now < state.deadline) continue;
+        const separator = key.indexOf("\n");
+        lanes.delete(key);
+        expired.push({
+          channelKey,
+          ruleName: key.slice(0, separator),
+          lane: key.slice(separator + 1),
+          buffer: state.buffer
+        });
+      }
+      if (!lanes.size) this.channels.delete(channelKey);
+    }
+    return expired;
+  }
+  lanesOf(channelKey) {
+    let lanes = this.channels.get(channelKey);
+    if (!lanes) {
+      lanes = /* @__PURE__ */ new Map();
+      this.channels.set(channelKey, lanes);
+    }
+    return lanes;
+  }
+};
+
 // src/trigger/engine.ts
 var SCHEDULER_TICK_MS = 1e3;
 var TriggerEngine = class {
-  constructor(ctx, runner, history, rules) {
+  constructor(ctx, runner, history, rules, cooldown) {
     this.ctx = ctx;
     this.runner = runner;
     this.history = history;
     this.rules = rules;
     this.scheduler = new RuleScheduler(ctx, (rule) => this.fireSchedule(rule));
     this.pool = new MessagePool();
+    this.cooldown = new TriggerCooldown(cooldown);
   }
   static {
     __name(this, "TriggerEngine");
   }
   scheduler;
   pool;
+  cooldown;
   start() {
     this.ctx.middleware((session, next) => this.handleMessage(session, next));
-    this.ctx.setInterval(() => this.scheduler.tick(), SCHEDULER_TICK_MS);
+    this.ctx.setInterval(() => {
+      this.scheduler.tick();
+      this.tickCooldown();
+    }, SCHEDULER_TICK_MS);
     this.ctx.on("send", (session) => {
       const entry = session.channelId ? buildHistoryEntry(session, "assistant") : null;
       if (!entry) return;
@@ -773,17 +997,33 @@ var TriggerEngine = class {
   handleMessage(session, next) {
     if (this.ctx.bots[session.uid]) return next();
     if (!session.channelId) return next();
+    const channelKey = channelKeyOf(session.platform, session.channelId);
     const entry = buildHistoryEntry(session);
     if (entry) {
-      this.history.recordEntry(channelKeyOf(session.platform, session.channelId), entry);
+      this.history.recordEntry(channelKey, entry);
       this.pool.record(session, entry);
-      for (const fire of this.pool.checkDensity(this.rules, session)) {
-        this.fireDensity(fire.rule, session, fire.entries);
+      const now = session.timestamp ?? Date.now();
+      this.cooldown.extendDensityLanes(channelKey, now);
+      for (const fire of this.pool.checkDensity(
+        this.rules,
+        session,
+        (rule, _condition, index) => this.cooldown.isCooling(channelKey, rule.name, densityLane(index), now)
+      )) {
+        this.fireDensity(fire, session);
       }
     }
     return next(async (nextMiddleware) => {
       const matched = this.matchRule(session);
       if (!matched) return nextMiddleware();
+      if (this.cooldown.isCooling(channelKey, matched.rule.name, "message", Date.now())) {
+        this.cooldown.bufferMessage(channelKey, matched.rule.name, {
+          session,
+          entry,
+          contentText: matched.condition.queryText
+        });
+        this.cooldown.extend(channelKey, matched.rule.name, "message", Date.now());
+        return;
+      }
       this.fireMessage(matched.rule, session, matched.condition, entry);
     });
   }
@@ -802,7 +1042,12 @@ var TriggerEngine = class {
   run(fireCtx) {
     void this.runner.run(fireCtx).catch((error) => this.ctx.logger.warn(error));
   }
+  /** 登记冷却（定时触发不调用；冷却关闭时零开销直退） */
+  beginCooldown(channelKey, ruleName, lane) {
+    this.cooldown.begin(channelKey, ruleName, lane, Date.now());
+  }
   fireMessage(rule, session, condition, entry) {
+    this.beginCooldown(channelKeyOf(session.platform, session.channelId), rule.name, "message");
     this.run({
       session,
       platform: session.platform,
@@ -817,8 +1062,8 @@ var TriggerEngine = class {
       contentText: condition.queryText
     });
   }
-  fireDensity(rule, session, entries) {
-    const windowText = formatHistoryEntries(entries);
+  fireDensity(fire, session) {
+    this.beginCooldown(channelKeyOf(session.platform, session.channelId), fire.rule.name, densityLane(fire.conditionIndex));
     this.run({
       session,
       platform: session.platform,
@@ -827,18 +1072,50 @@ var TriggerEngine = class {
       guildId: session.guildId ?? session.channelId,
       userId: session.userId,
       triggerType: "density",
+      rule: fire.rule,
+      queryText: formatHistoryEntries(fire.entries),
+      contentText: formatHistoryBrief(fire.entries)
+    });
+  }
+  /** 冷却到期：把缓冲内的触发消息合并为一次触发，session 取首条（供投递与文件上传） */
+  fireMerged(rule, buffer) {
+    const first = buffer[0];
+    const queryText = buffer.map((item) => item.entry ? formatHistoryEntry(item.entry) : "").filter(Boolean).join("\n");
+    const contentText = buffer.map((item) => item.contentText).filter(Boolean).join("\n");
+    this.beginCooldown(channelKeyOf(first.session.platform, first.session.channelId), rule.name, "message");
+    this.run({
+      session: first.session,
+      platform: first.session.platform,
+      selfId: first.session.selfId,
+      channelId: first.session.channelId,
+      guildId: first.session.guildId ?? first.session.channelId,
+      userId: first.session.userId,
+      triggerType: "merged",
       rule,
-      queryText: windowText,
-      contentText: windowText
+      queryText,
+      contentText
+    });
+  }
+  /** 密度冷却到期复查达标：无当前消息，用池身份构造上下文（投递同定时路径） */
+  fireDensityExpiry(rule, conditionIndex, channel) {
+    this.beginCooldown(channelKeyOf(channel.platform, channel.channelId), rule.name, densityLane(conditionIndex));
+    this.run({
+      platform: channel.platform,
+      selfId: channel.selfId,
+      channelId: channel.channelId,
+      guildId: channel.guildId,
+      triggerType: "density",
+      rule,
+      queryText: formatHistoryEntries(channel.entries),
+      contentText: formatHistoryBrief(channel.entries)
     });
   }
   /**
    * 定时触发（消息摘要）：把消息池内该规则作用域有消息的每个频道各发一次请求（取走即清空全池）。
-   * 频道身份取自池内最近一条消息；无消息的频道自然跳过。
+   * 频道身份取自池内最近一条消息；无消息的频道自然跳过。定时不受冷却影响。
    */
   fireSchedule(rule) {
     for (const channel of this.pool.takeSchedule(rule)) {
-      const windowText = formatHistoryEntries(channel.entries);
       this.run({
         platform: channel.platform,
         selfId: channel.selfId,
@@ -846,13 +1123,40 @@ var TriggerEngine = class {
         guildId: channel.guildId,
         triggerType: "schedule",
         rule,
-        queryText: windowText,
-        contentText: windowText
+        queryText: formatHistoryEntries(channel.entries),
+        contentText: formatHistoryBrief(channel.entries)
       });
     }
   }
+  /** 每秒扫描冷却到期：消息通道合并触发，密度通道复查池 */
+  tickCooldown() {
+    if (!this.cooldown.enabled) return;
+    const now = Date.now();
+    for (const expired of this.cooldown.collectExpired(now)) {
+      this.onCooldownExpired(expired, now);
+    }
+  }
+  onCooldownExpired(expired, now) {
+    const rule = this.rules.find((item) => item.name === expired.ruleName);
+    if (!rule) return;
+    if (expired.lane === "message") {
+      if (expired.buffer.length) this.fireMerged(rule, expired.buffer);
+      return;
+    }
+    const index = Number(expired.lane.slice("density:".length));
+    const condition = rule.conditions[index];
+    if (condition?.type !== "density") return;
+    const channel = this.pool.takeDensityChannel(rule, condition, expired.channelKey, now);
+    if (channel) this.fireDensityExpiry(rule, index, channel);
+  }
 };
 
+// src/types.ts
+function isMessageTrigger(type) {
+  return type !== "schedule" && type !== "density";
+}
+__name(isMessageTrigger, "isMessageTrigger");
+
 // src/requester/files.ts
 var import_promises = require("fs/promises");
 var import_fs = require("fs");
@@ -986,19 +1290,19 @@ function resolveFileType(mimeType, elementType) {
   return mime === "custom" && elementType !== "custom" ? elementType : mime;
 }
 __name(resolveFileType, "resolveFileType");
-async function uploadOne(ctx, client, candidate, difyUser) {
+async function uploadOne(ctx, client, candidate, difyUser, limit) {
   try {
     const payload = await resolveFilePayload(ctx, candidate);
     if (!payload) return null;
     const type = resolveFileType(payload.mimeType, candidate.type);
-    const limit = SIZE_LIMITS[type];
-    if (payload.buffer.length > limit) {
+    const maxBytes = limit.maxSizeMb > 0 ? limit.maxSizeMb * MB : Infinity;
+    const sizeLimit = Math.min(SIZE_LIMITS[type], maxBytes);
+    if (payload.buffer.length > sizeLimit) {
       ctx.logger.warn(
-        "文件 %s (%dMB) 超过 %s 类型上限 %dMB，跳过",
+        "文件 %s (%dMB) 超过上限 %dMB，跳过",
         payload.fileName,
         Math.round(payload.buffer.length / MB),
-        type,
-        Math.round(limit / MB)
+        Math.round(sizeLimit / MB)
       );
       return null;
     }
@@ -1013,14 +1317,17 @@ async function uploadOne(ctx, client, candidate, difyUser) {
   }
 }
 __name(uploadOne, "uploadOne");
-async function uploadMessageFiles(ctx, client, session, difyUser) {
+async function uploadMessageFiles(ctx, client, session, difyUser, limit) {
   const candidates = extractFileCandidates(session);
+  const limited = limit.maxCount > 0 ? candidates.slice(0, limit.maxCount) : candidates;
+  const dropped = candidates.slice(limited.length).map((candidate) => candidate.source);
   const files = [];
-  for (const candidate of candidates) {
-    const uploaded = await uploadOne(ctx, client, candidate, difyUser);
+  for (const candidate of limited) {
+    const uploaded = await uploadOne(ctx, client, candidate, difyUser, limit);
     if (uploaded) files.push(uploaded);
+    else dropped.push(candidate.source);
   }
-  return files;
+  return { files, dropped };
 }
 __name(uploadMessageFiles, "uploadMessageFiles");
 
@@ -1076,6 +1383,8 @@ function resolveSource(source, fireCtx, history, now) {
       return resolveSessionField(source.key, fireCtx, now);
     case "meta":
       return resolveMetaField(source.key, fireCtx, now);
+    case "constant":
+      return source.value;
     case "history": {
       const channelKey = channelKeyOf(fireCtx.platform, fireCtx.channelId);
       const limit = source.limit ?? history.limit;
@@ -1134,7 +1443,7 @@ function renderReply(input) {
   const segments = splitText(input.text, input.config.maxSegmentLength ?? 0);
   segments.forEach((segment, index) => {
     const elements = [];
-    if (index === 0 && input.config.quoteTrigger && input.quoteMessageId) {
+    if (index === 0 && input.quoteMessageId) {
       elements.push(import_koishi3.h.quote(input.quoteMessageId));
     }
     if (input.config.parseElements) {
@@ -1213,6 +1522,7 @@ var RequestRunner = class {
     return app.appType !== "auto" ? app.appType : this.appTypes.get(app.name) ?? FALLBACK_APP_TYPE;
   }
   async run(fireCtx) {
+    const startedAt = Date.now();
     const { rule } = fireCtx;
     const app = this.apps.get(rule.app);
     if (!app) {
@@ -1227,8 +1537,19 @@ var RequestRunner = class {
       inputs: resolveVariables(rule, fireCtx, this.history),
       uploadedFiles: []
     };
-    if (this.config.uploadFiles !== false && fireCtx.session) {
-      requestCtx.uploadedFiles = await uploadMessageFiles(this.ctx, client, fireCtx.session, requestCtx.difyUser);
+    const upload = resolveUploadConfig(this.config);
+    if (upload.enabled && fireCtx.session) {
+      const { files, dropped } = await uploadMessageFiles(
+        this.ctx,
+        client,
+        fireCtx.session,
+        requestCtx.difyUser,
+        { maxCount: upload.maxCount, maxSizeMb: upload.maxMb }
+      );
+      requestCtx.uploadedFiles = files;
+      if (dropped.length) {
+        fireCtx.queryText = annotateDroppedPlaceholders(fireCtx.queryText, dropped);
+      }
     }
     let reply;
     try {
@@ -1245,10 +1566,13 @@ var RequestRunner = class {
       this.ctx.logger.warn("规则 %s 的请求未返回任何内容", rule.name);
       return;
     }
+    const quote = resolveQuoteConfig(this.config);
+    const elapsedSeconds = (Date.now() - startedAt) / 1e3;
+    const shouldQuote = quote.enabled && elapsedSeconds >= quote.minElapsedSeconds && isMessageTrigger(fireCtx.triggerType);
     const messages = renderReply({
       text: reply.text,
       files: reply.files,
-      quoteMessageId: fireCtx.session?.messageId,
+      quoteMessageId: shouldQuote ? fireCtx.session?.messageId : void 0,
       config: this.config
     });
     await this.deliver(fireCtx, messages);
@@ -1452,12 +1776,12 @@ function apply(ctx, config) {
   ctx.i18n.define("zh-CN", zh_CN_default);
   ctx.i18n.define("en-US", en_US_default);
   defineTables(ctx);
-  const { apps, rules } = normalizeConfig(config);
+  const { apps, rules, cooldown } = normalizeConfig(config);
   const appTypes = /* @__PURE__ */ new Map();
   const history = new MessageHistory(config.historyLimit);
   const conversationStore = new ConversationStore(ctx, apps);
   const runner = new RequestRunner(ctx, config, conversationStore, history, apps, appTypes);
-  const engine = new TriggerEngine(ctx, runner, history, rules);
+  const engine = new TriggerEngine(ctx, runner, history, rules, cooldown);
   ctx.on("ready", async () => {
     await probeAppTypes(ctx, config, apps, appTypes);
     engine.start();

package/lib/requester/files.d.ts

@@ -17,6 +17,16 @@ export declare function mimeToFileType(mimeType?: string): DifyFileType;
 export declare function extractFileCandidates(session: Session): FileCandidate[];
 /** 三源归一：data URL / 远程 URL / 本地路径 → {buffer, fileName, mimeType}（冒烟测试直测） */
 export declare function resolveFilePayload(ctx: Context, candidate: FileCandidate): Promise<FilePayload | null>;
-/** 提取并上传消息中的文件，返回可附加到请求体的 files 数组 */
-export declare function uploadMessageFiles(ctx: Context, client: DifyClient, session: Session, difyUser: string): Promise<DifyInputFileObject[]>;
+/** 上传数量与单文件大小限制（0 不限；大小与 Dify 各类型上限取较小值） */
+export interface UploadLimit {
+    maxCount: number;
+    maxSizeMb: number;
+}
+/** 一次上传的产物：成功的 files 载荷 + 被丢弃候选的来源 URL（截断/超限/失败统一记录，供占位符注记） */
+export interface UploadResult {
+    files: DifyInputFileObject[];
+    dropped: string[];
+}
+/** 上传一批候选（入口按 type:source 去重，再按数量上限截断、逐个上传） */
+export declare function uploadCandidates(ctx: Context, client: DifyClient, candidates: FileCandidate[], difyUser: string, limit: UploadLimit): Promise<UploadResult>;
 export {};

package/lib/requester/render.d.ts

@@ -4,6 +4,7 @@ import { DifyFilePayload } from '../api/types';
 export interface RenderInput {
     text: string;
     files: DifyFilePayload[];
+    /** 引用哪条消息；调用方完成开关与耗时判定，未达标传空即不引用 */
     quoteMessageId?: string;
     /** 回复行为配置（koishi schema「回复行为」组） */
     config: Config;

package/lib/requester/runner.d.ts

@@ -28,6 +28,8 @@ export declare class RequestRunner {
     /** 应用类型：schema 显式指定优先，auto 时用探测结果（未探测到回退 chat） */
     private appTypeOf;
     run(fireCtx: FireContext): Promise<void>;
+    /** 引用判定：开关开启、回复耗时达到阈值、且由消息触发（定时与密度没有单一触发消息） */
+    private shouldQuoteReply;
     /** 按应用类型分流：workflow/completion 无会话，chat 系续接 conversation_id */
     private dispatch;
     private deliver;

package/lib/state/conversation.d.ts

@@ -15,6 +15,8 @@ export declare class ConversationStore {
     apps: Map<string, AppConfigEntry>);
     /** 粒度归一：bindingKey 与 difyUser 共用，保证两者始终对齐 */
     private resolveScopeDimension;
+    /** 私聊判定：有 session 读 session，无 session 的主动触发读池透传的标记 */
+    private isDirectOf;
     /** bindingKey = 应用 ID + 粒度 + 平台身份 */
     computeBindingKey(appId: string, rule: DifyRule, fireCtx: FireContext): string;
     /**
@@ -32,10 +34,15 @@ export declare class ConversationStore {
     /**
      * 重置匹配的绑定：本地删行 + 尽力删除 Dify 侧会话（失败仅记录）。
      * 表已无 guildKey 列，按频道匹配时全表读回后解析 bindingKey 过滤（行数量级很小）。
+     * 覆盖 guild / user（群内）/ channel 段与私聊执行时的 private 段；
+     * global 段跨频道，不随单频道重置。
      */
     resetWhere(filter: {
         bindingKey?: string;
         guildKey?: string;
+        channelKey?: string;
+        isDirect?: boolean;
+        userId?: string;
     }): Promise<number>;
     /** 按应用 ID（apps 配置的 appId 字段）反查应用 */
     private findByAppId;

package/lib/trigger/conditions.d.ts

@@ -2,10 +2,10 @@ import { Session } from 'koishi';
 import { MessageTriggerType, TriggerCondition, TriggerScope } from '../types';
 export interface ConditionMatched {
     type: MessageTriggerType;
-    /** 触发后用作 content 变量的剥离文本（query 由引擎按统一消息格式另行构造） */
-    queryText: string;
+    /** content 变量的剥离文本，保留 @ 与图片占位（query 由引擎按统一消息格式另行构造） */
+    contentText: string;
 }
-/** 评估单个消息条件；返回 null 表示未命中 */
+/** 评估单个消息条件；返回 null 表示未命中（匹配基于纯文本，@ 元素不参与判定） */
 export declare function evaluateCondition(condition: TriggerCondition, session: Session): ConditionMatched | null;
 /** 作用域过滤：留空的维度不做限制 */
 export declare function matchScope(scope: TriggerScope, session: Session): boolean;

package/lib/trigger/cooldown.d.ts

@@ -0,0 +1,50 @@
+import { Session } from 'koishi';
+import { CooldownSetting } from '../types';
+import { HistoryEntry } from '../history';
+/** 冷却期内缓存的一条触发消息（entry 供统一格式渲染，纯 @ 等无文本消息为空） */
+export interface PendingMessage {
+    session: Session;
+    entry: HistoryEntry | null;
+    /** 该条消息命中条件时剥离出的文本（contentText 用） */
+    contentText: string;
+}
+/** 冷却通道：message = 规则内全部消息类条件共享；density:N = 第 N 个密度条件独立 */
+export type CooldownLane = 'message' | `density:${number}`;
+/** 密度通道名的下标前缀 */
+export declare const DENSITY_LANE_PREFIX = "density:";
+/** 密度条件的通道名 */
+export declare function densityLane(index: number): CooldownLane;
+/** 到期扫描交出的通道产物 */
+export interface ExpiredCooldown {
+    channelKey: string;
+    ruleName: string;
+    lane: CooldownLane;
+    buffer: PendingMessage[];
+}
+/**
+ * 触发后冷却：从触发发起时刻计时（请求耗时计入冷却）。
+ * 消息通道冷却期内命中消息进缓冲并顺延滑动窗口，到期合并为一次触发；
+ * 密度通道冷却期即积攒期（池照常记录），全部过路消息顺延，到期复查达标才触发。
+ * 定时触发不参与冷却。配置关闭时所有方法零开销直退。
+ */
+export declare class TriggerCooldown {
+    private setting;
+    /** channelKey → (规则名+通道 → 冷却态) */
+    private channels;
+    constructor(setting: CooldownSetting | null);
+    get enabled(): boolean;
+    /** 触发发起时登记冷却 */
+    begin(channelKey: string, ruleName: string, lane: CooldownLane, now: number): void;
+    isCooling(channelKey: string, ruleName: string, lane: CooldownLane, now: number): boolean;
+    /** 滑动窗口顺延：截止推到「now + 最小窗口」，不超过「触发时刻 + 最大窗口」 */
+    private slide;
+    /** 滑动窗口顺延：已到期的通道不复活 */
+    extend(channelKey: string, ruleName: string, lane: CooldownLane, now: number): void;
+    /** 该频道所有密度通道由一条过路消息顺延（密度冷却期内的消息积攒驱动窗口滑动）；已到期的不复活 */
+    extendDensityLanes(channelKey: string, now: number): void;
+    /** 冷却期内缓存一条命中消息（仅消息通道） */
+    bufferMessage(channelKey: string, ruleName: string, message: PendingMessage): void;
+    /** 到期扫描：取走到期通道（连缓冲一并交出），由调用方决定是否重新登记；限定频道时只扫该频道 */
+    collectExpired(now: number, channelKey?: string): ExpiredCooldown[];
+    private lanesOf;
+}

package/lib/trigger/engine.d.ts

@@ -1,5 +1,5 @@
 import { Context } from 'koishi';
-import { DifyRule } from '../types';
+import { CooldownSetting, DifyRule } from '../types';
 import { MessageHistory } from '../history';
 import { RequestRunner } from '../requester/runner';
 /**
@@ -13,17 +13,27 @@ export declare class TriggerEngine {
     private rules;
     private scheduler;
     private pool;
-    constructor(ctx: Context, runner: RequestRunner, history: MessageHistory, rules: DifyRule[]);
+    private cooldown;
+    constructor(ctx: Context, runner: RequestRunner, history: MessageHistory, rules: DifyRule[], cooldown: CooldownSetting | null);
     start(): void;
     private handleMessage;
     private matchRule;
     /** 异步执行一次请求；错误由请求器与这里的兜底记录 */
     private run;
+    /** 登记冷却（定时触发不调用；冷却关闭时零开销直退） */
+    private beginCooldown;
     private fireMessage;
     private fireDensity;
+    /** 冷却到期：把缓冲内的触发消息合并为一次触发，session 取首条（供投递与文件上传） */
+    private fireMerged;
+    /** 密度冷却到期复查达标：无当前消息，用池身份构造上下文（投递同定时路径） */
+    private fireDensityExpiry;
     /**
      * 定时触发（消息摘要）：把消息池内该规则作用域有消息的每个频道各发一次请求（取走即清空全池）。
-     * 频道身份取自池内最近一条消息；无消息的频道自然跳过。
+     * 频道身份取自池内最近一条消息；无消息的频道自然跳过。定时不受冷却影响。
      */
     private fireSchedule;
+    /** 扫描冷却到期（带频道只扫该频道，消息路径用；每秒 interval 全量扫描）：消息通道合并触发，密度通道复查池 */
+    private tickCooldown;
+    private onCooldownExpired;
 }

package/lib/trigger/pool.d.ts

@@ -1,5 +1,5 @@
 import { Session } from 'koishi';
-import { DifyRule } from '../types';
+import { DensityCondition, DifyRule } from '../types';
 import { HistoryEntry } from '../history';
 /** 一个频道的缓冲池：密度与定时共用，谁先触发谁取走清空 */
 export interface ChannelPool {
@@ -13,6 +13,9 @@ export interface ChannelPool {
 }
 export interface DensityFire {
     rule: DifyRule;
+    /** 命中的密度条件与其在规则内的下标（密度冷却通道键） */
+    condition: DensityCondition;
+    conditionIndex: number;
     /** 触发时取走的该频道全池消息（含 bot 行与时效外条目） */
     entries: HistoryEntry[];
 }
@@ -25,11 +28,16 @@ export declare class MessagePool {
     private channels;
     /** 一条消息（含 bot 自己的发言）入池，全量记录不做规则过滤 */
     record(session: Session, entry: HistoryEntry): void;
+    /** 时效内且通过规则作用域的真人条数（bot 行不推高密度，防自激励） */
+    private countQualified;
     /**
      * 新消息入池后的密度评估：时效内（相对触发消息）且通过规则作用域的真人条数达到阈值。
      * 触发即取走并清空该频道全池（bot 行不推高密度，防自激励）；池清空后其余规则无从触发。
+     * skip 返回 true 的条件（冷却中的密度条件）不参与判定。
      */
-    checkDensity(rules: DifyRule[], session: Session): DensityFire[];
+    checkDensity(rules: DifyRule[], session: Session, skip?: (rule: DifyRule, condition: DensityCondition, index: number) => boolean): DensityFire[];
+    /** 冷却到期复查：按条件参数统计该频道池（now 为复查时刻），达标即取走整池，未达标返回 null */
+    takeDensityChannel(rule: DifyRule, condition: DensityCondition, channelKey: string, now: number): ChannelPool | null;
     /** 定时到点：取走该规则作用域内有消息的所有频道（整池清空，含未过作用域的条目） */
     takeSchedule(rule: DifyRule): ChannelPool[];
 }

package/lib/types.d.ts

@@ -1,9 +1,11 @@
 import type { Session } from 'koishi';
-/** 消息驱动的触发原因 */
-export type MessageTriggerType = 'keyword-prefix' | 'keyword-contains' | 'at-bot' | 'at-user' | 'quote-bot' | 'quote-user';
+/** 消息驱动的触发原因（merged = 冷却期内多条触发消息合并为一次触发） */
+export type MessageTriggerType = 'keyword-prefix' | 'keyword-contains' | 'at-bot' | 'at-user' | 'quote-bot' | 'quote-user' | 'merged';
 /** 非消息驱动的触发原因 */
 export type ProactiveTriggerType = 'schedule' | 'density';
 export type TriggerType = MessageTriggerType | ProactiveTriggerType;
+/** 是否由消息触发（合并触发也算）：定时与密度触发没有单一触发消息 */
+export declare function isMessageTrigger(type: TriggerType): boolean;
 /** 关键词条件（prefix 触发时剥离关键词作为 query，contains 保留全文） */
 export interface KeywordCondition {
     type: 'keyword-prefix' | 'keyword-contains';
@@ -63,6 +65,9 @@ export type VariableSource = {
 } | {
     type: 'meta';
     key: MetaField;
+} | {
+    type: 'constant';
+    value: string;
 };
 /** 一条变量映射：Dify inputs 字段名 ← 来源 */
 export interface VariableBinding {
@@ -71,6 +76,15 @@ export interface VariableBinding {
 }
 /** Dify 会话绑定粒度 */
 export type ConversationScope = 'per-user' | 'per-guild' | 'per-channel' | 'global';
+/** 触发后冷却设置（schema 规范化后的内部形态；null 表示关闭） */
+export type CooldownSetting = {
+    mode: 'fixed';
+    ms: number;
+} | {
+    mode: 'sliding';
+    minMs: number;
+    maxMs: number;
+};
 /** 触发规则（配置页 schema 规范化后的内部形态；身份即 name，按优先级降序排列） */
 export interface DifyRule {
     name: string;
@@ -96,6 +110,10 @@ export interface FireContext {
     rule: DifyRule;
     /** 发给 Dify 的 query：统一消息格式（消息触发为单行，窗口触发为逐行拼接） */
     queryText: string;
-    /** content 变量的值：消息触发为剥离文本，窗口触发为统一格式拼接 */
+    /** content 变量的值：消息触发为剥离文本（剔除 @bot），窗口触发为精简行拼接 */
     contentText: string;
+    /** 本次触发相关消息的图片 URL（合并/密度/定时的池或缓冲条目合集）：供上传管线补齐非首条消息的图片 */
+    imageUrls?: string[];
+    /** 无 session 的主动触发（定时/密度到期）从消息池透传的私聊标记：会话绑定与 isDirect 变量用 */
+    isDirect?: boolean;
 }

package/lib/utils/session-text.d.ts

@@ -1,4 +1,6 @@
 import { Session } from 'koishi';
+/** 图片占位符携带的 URL 摘要长度（hex 位） */
+export declare const IMAGE_HASH_LENGTH = 8;
 /**
  * 会话文本提取的统一入口。此前有四个变体（条件匹配、历史记录、变量、@ 剥离）
  * 各自实现「elements 有则取 text 元素，否则解析 content」，trim 与解析行为已经漂移，
@@ -6,17 +8,24 @@ import { Session } from 'koishi';
  */
 /** 把可解析的消息文本（含元素标记）转纯文本；解析失败回退原文 */
 export declare function parseTextSafe(content: string | undefined): string;
-interface ExtractTextOptions {
-    /** 去掉 @ 元素（at-bot 触发的 query 语义） */
-    excludeAt?: boolean;
-}
-/** 会话消息纯文本：优先 elements，退回 content 解析；统一 trim */
-export declare function extractText(session: Session, options?: ExtractTextOptions): string;
-/** 消息中的图片元素在文本形态里的占位符 */
+/** 会话消息纯文本：优先 elements，退回 content 解析；统一 trim（@ 元素不产生文本，仅供条件匹配） */
+export declare function extractText(session: Session): string;
+/** 消息中的图片元素在文本形态里的占位符（图片无 URL 时的兜底形态） */
 export declare const IMAGE_PLACEHOLDER = "[\u56FE\u7247]";
+/** 图片占位符带 URL 摘要：同 URL 同标识，query 里的占位符与上传文件可全局对应 */
+export declare function imagePlaceholder(url?: string): string;
+/** 给被丢弃图片的占位符追加已丢弃注记：按 URL 摘要全局定位，无需与元素顺序对齐 */
+export declare function annotateDroppedPlaceholders(text: string, droppedUrls: string[]): string;
+interface ExtractVerbatimOptions {
+    /** 跳过 @ 机器人自身的渲染（content 变量语义：@bot 是触发结构而非消息内容） */
+    excludeBotAt?: boolean;
+}
 /**
- * 带媒体占位符的消息文本：text 元素按序拼接，img/image 元素渲染为 [图片]，
- * 供聊天记录呈现（历史消息变量 / 定时摘要 / 密度触发共用）。
+ * 消息原貌文本：text 元素按序拼接，@ 元素渲染为 @名字（缺名字用 ID），
+ * img/image 元素渲染为 [image:URL摘要]——统一格式行（query/池/历史）用默认形态，
+ * content 变量通道用 excludeBotAt 形态剔除 @bot。
  */
-export declare function extractTextWithPlaceholders(session: Session): string;
+export declare function extractTextWithPlaceholders(session: Session, options?: ExtractVerbatimOptions): string;
+/** 消息中图片元素的 URL 列表（按元素序，与原貌文本中 [image:摘要] 的出现序一致） */
+export declare function extractImageUrls(session: Session): string[];
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-dify-ai",
   "description": "Invoke Dify apps (chatflow / workflow / completion) in Koishi with triggers and conversation bindings",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "author": "PinkElysia",
   "license": "MIT",
   "homepage": "https://github.com/PinkElysiaDev/dify-ai-plugin-for-Koishi#readme",