@cicctencent/agent-server 0.1.2 → 0.2.0

package/dist/cjs/service/cache.service.js

@@ -0,0 +1,243 @@
+"use strict";
+// ============================================================
+// CacheService — TTL 缓存包装器（多进程/多实例场景）
+// ============================================================
+//
+// 问题：上层 Web 项目多进程部署时，每次 getSettings() / getProfile() 都查 DB 会产生大量重复查询。
+// 解决：在 Provider 之上加一层 TTL 缓存，减少 DB 压力；同时支持主动失效。
+//
+// 缓存策略：
+// - TTL 到期自动过期，下次请求重新从底层 Provider 加载
+// - 主动失效通过 invalidate() 清除指定 key 或全部
+// - 跨进程失效通过 CacheInvalidationNotifier 实现（如 Redis pub/sub）
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CachedAgentProfileProvider = exports.CachedSettingsProvider = exports.TTLCache = void 0;
+/**
+ * 通用 TTL 缓存。
+ *
+ * - `ttl > 0`：启用缓存，过期后自动失效
+ * - `ttl === 0`：禁用缓存，get() 永远返回 null（每次直接查 Provider）
+ */
+class TTLCache {
+    cache = new Map();
+    ttl;
+    constructor(ttlMs = 60_000) {
+        this.ttl = ttlMs;
+    }
+    /** 是否启用缓存 */
+    get enabled() {
+        return this.ttl > 0;
+    }
+    /** 更新 TTL（不影响已缓存条目的过期时间） */
+    setTTL(ttlMs) {
+        this.ttl = ttlMs;
+    }
+    /** 获取缓存值（未命中或过期返回 null） */
+    get(key) {
+        if (!this.enabled)
+            return null;
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    /** 设置缓存值 */
+    set(key, value) {
+        if (!this.enabled)
+            return;
+        this.cache.set(key, { value, expiresAt: Date.now() + this.ttl });
+    }
+    /** 清除指定 key 的缓存 */
+    invalidate(key) {
+        if (key !== undefined) {
+            this.cache.delete(key);
+        }
+        else {
+            this.cache.clear();
+        }
+    }
+    /** 清除所有缓存 */
+    clear() {
+        this.cache.clear();
+    }
+    /** 清除已过期的条目 */
+    purgeExpired() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache) {
+            if (now > entry.expiresAt) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    /** 缓存条目数量 */
+    get size() {
+        return this.cache.size;
+    }
+}
+exports.TTLCache = TTLCache;
+// ============================================================
+// CachedSettingsProvider — Settings 缓存包装器
+// ============================================================
+/**
+ * 包装 SettingsProvider，增加 TTL 缓存。
+ *
+ * 多进程部署时，每个进程独立缓存 Settings，TTL 到期后重新从底层 Provider 加载。
+ * 主动失效通过 `invalidate()` 清除缓存，上层可通过 `CacheInvalidationNotifier` 跨进程通知。
+ */
+class CachedSettingsProvider {
+    cache;
+    delegate;
+    constructor(delegate, ttlMs = 60_000) {
+        this.delegate = delegate;
+        this.cache = new TTLCache(ttlMs);
+    }
+    getSettings() {
+        const cached = this.cache.get('settings');
+        if (cached)
+            return cached;
+        const value = this.delegate.getSettings();
+        this.cache.set('settings', value);
+        return value;
+    }
+    updateSettings(updates) {
+        const value = this.delegate.updateSettings(updates);
+        // 更新后立即刷新缓存
+        this.cache.set('settings', value);
+        return value;
+    }
+    resetSettings() {
+        if (this.delegate.resetSettings) {
+            const value = this.delegate.resetSettings();
+            this.cache.set('settings', value);
+            return value;
+        }
+        this.cache.invalidate('settings');
+        return this.getSettings();
+    }
+    /** 清除缓存 */
+    invalidate() {
+        this.cache.invalidate('settings');
+    }
+}
+exports.CachedSettingsProvider = CachedSettingsProvider;
+// ============================================================
+// CachedAgentProfileProvider — Profile 缓存包装器
+// ============================================================
+/**
+ * 包装 AgentProfileProvider，增加 TTL 缓存。
+ *
+ * 多进程部署时，每个进程独立缓存 Profile，TTL 到期后重新从底层 Provider 加载。
+ * 主动失效通过 `invalidate(profileId?)` 清除指定或全部 Profile 缓存。
+ */
+class CachedAgentProfileProvider {
+    cache;
+    listCache;
+    defaultCache;
+    delegate;
+    constructor(delegate, ttlMs = 60_000) {
+        this.delegate = delegate;
+        this.cache = new TTLCache(ttlMs);
+        this.listCache = new TTLCache(ttlMs);
+        this.defaultCache = new TTLCache(ttlMs);
+    }
+    listProfiles() {
+        const cached = this.listCache.get('list');
+        if (cached)
+            return cached;
+        const result = this.delegate.listProfiles();
+        if (result instanceof Promise) {
+            return result.then(value => {
+                this.listCache.set('list', value);
+                // 同时缓存每个 profile
+                for (const p of value)
+                    this.cache.set(`profile:${p.id}`, p);
+                return value;
+            });
+        }
+        this.listCache.set('list', result);
+        for (const p of result)
+            this.cache.set(`profile:${p.id}`, p);
+        return result;
+    }
+    getProfile(id) {
+        const cacheKey = `profile:${id}`;
+        const cached = this.cache.get(cacheKey);
+        if (cached)
+            return cached;
+        const result = this.delegate.getProfile(id);
+        if (result instanceof Promise) {
+            return result.then(value => {
+                if (value)
+                    this.cache.set(cacheKey, value);
+                return value;
+            });
+        }
+        if (result)
+            this.cache.set(cacheKey, result);
+        return result;
+    }
+    getDefaultProfile() {
+        const cached = this.defaultCache.get('default');
+        if (cached !== null)
+            return cached;
+        const result = this.delegate.getDefaultProfile();
+        if (result instanceof Promise) {
+            return result.then(value => {
+                this.defaultCache.set('default', value);
+                return value;
+            });
+        }
+        this.defaultCache.set('default', result);
+        return result;
+    }
+    createProfile(data) {
+        const result = this.delegate.createProfile(data);
+        // 创建后清除列表缓存和默认缓存
+        this.listCache.invalidate('list');
+        this.defaultCache.invalidate('default');
+        return result;
+    }
+    updateProfile(id, data) {
+        const result = this.delegate.updateProfile(id, data);
+        // 更新后清除该 profile 缓存 + 列表缓存
+        this.cache.invalidate(`profile:${id}`);
+        this.listCache.invalidate('list');
+        if (result instanceof Promise) {
+            return result.then(value => {
+                if (value)
+                    this.cache.set(`profile:${id}`, value);
+                return value;
+            });
+        }
+        if (result)
+            this.cache.set(`profile:${id}`, result);
+        return result;
+    }
+    deleteProfile(id) {
+        const result = this.delegate.deleteProfile(id);
+        this.cache.invalidate(`profile:${id}`);
+        this.listCache.invalidate('list');
+        this.defaultCache.invalidate('default');
+        return result;
+    }
+    /**
+     * 清除缓存。
+     * @param profileId 指定 profileId 时仅清除该 profile；不指定时清除全部
+     */
+    invalidate(profileId) {
+        if (profileId !== undefined) {
+            this.cache.invalidate(`profile:${profileId}`);
+        }
+        else {
+            this.cache.clear();
+            this.listCache.clear();
+            this.defaultCache.clear();
+        }
+    }
+}
+exports.CachedAgentProfileProvider = CachedAgentProfileProvider;
+//# sourceMappingURL=cache.service.js.map

package/dist/cjs/service/cache.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.service.js","sourceRoot":"","sources":["../../../src/service/cache.service.ts"],"names":[],"mappings":"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"}

package/dist/cjs/service/engine-pool.d.ts

@@ -1,6 +1,19 @@
 import { EnginePool } from '@cicctencent/agent-core';
 export { EnginePool } from '@cicctencent/agent-core';
-export declare function getEnginePool(): EnginePool;
-/** 重置全局池（测试用） */
+/** EnginePool 初始化配置 */
+export interface EnginePoolConfig {
+    /** TTL（ms），默认 5 分钟 */
+    ttl?: number;
+    /** 最大缓存数量，默认 10 */
+    maxSize?: number;
+}
+/**
+ * 获取全局 Engine 池单例。
+ *
+ * 首次调用时按 config 创建；后续调用忽略 config（已创建的池不会被覆盖）。
+ * 如需重新创建，请先调用 `resetEnginePool()`。
+ */
+export declare function getEnginePool(config?: EnginePoolConfig): EnginePool;
+/** 重置全局池（测试用 / 配置变更后重建） */
 export declare function resetEnginePool(): void;
 //# sourceMappingURL=engine-pool.d.ts.map

package/dist/cjs/service/engine-pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine-pool.d.ts","sourceRoot":"","sources":["../../../src/service/engine-pool.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAKrD,wBAAgB,aAAa,IAAI,UAAU,CAK1C;AAED,iBAAiB;AACjB,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}
+{"version":3,"file":"engine-pool.d.ts","sourceRoot":"","sources":["../../../src/service/engine-pool.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,uBAAuB;AACvB,MAAM,WAAW,gBAAgB;IAC/B,sBAAsB;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAKD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,UAAU,CAOnE;AAED,2BAA2B;AAC3B,wBAAgB,eAAe,IAAI,IAAI,CAKtC"}

package/dist/cjs/service/engine-pool.js

@@ -11,14 +11,25 @@ var agent_core_2 = require("@cicctencent/agent-core");
 Object.defineProperty(exports, "EnginePool", { enumerable: true, get: function () { return agent_core_2.EnginePool; } });
 /** 全局 Engine 池单例 */
 let globalPool = null;
-function getEnginePool() {
+/**
+ * 获取全局 Engine 池单例。
+ *
+ * 首次调用时按 config 创建；后续调用忽略 config（已创建的池不会被覆盖）。
+ * 如需重新创建，请先调用 `resetEnginePool()`。
+ */
+function getEnginePool(config) {
     if (!globalPool) {
-        globalPool = new agent_core_1.EnginePool();
+        const ttl = config?.ttl ?? 5 * 60_000;
+        const maxSize = config?.maxSize ?? 10;
+        globalPool = new agent_core_1.EnginePool(ttl, maxSize);
     }
     return globalPool;
 }
-/** 重置全局池（测试用） */
+/** 重置全局池（测试用 / 配置变更后重建） */
 function resetEnginePool() {
-    globalPool = null;
+    if (globalPool) {
+        globalPool.clear();
+        globalPool = null;
+    }
 }
 //# sourceMappingURL=engine-pool.js.map

package/dist/cjs/service/engine-pool.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine-pool.js","sourceRoot":"","sources":["../../../src/service/engine-pool.ts"],"names":[],"mappings":";AAAA,+DAA+D;AAC/D,gDAAgD;AAChD,+DAA+D;;;AAS/D,sCAKC;AAGD,0CAEC;AAjBD,wDAAqD;AAErD,sDAAqD;AAA5C,wGAAA,UAAU,OAAA;AAEnB,oBAAoB;AACpB,IAAI,UAAU,GAAsB,IAAI,CAAC;AAEzC,SAAgB,aAAa;IAC3B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,UAAU,GAAG,IAAI,uBAAU,EAAE,CAAC;IAChC,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,iBAAiB;AACjB,SAAgB,eAAe;IAC7B,UAAU,GAAG,IAAI,CAAC;AACpB,CAAC"}
+{"version":3,"file":"engine-pool.js","sourceRoot":"","sources":["../../../src/service/engine-pool.ts"],"names":[],"mappings":";AAAA,+DAA+D;AAC/D,gDAAgD;AAChD,+DAA+D;;;AAuB/D,sCAOC;AAGD,0CAKC;AApCD,wDAAqD;AAErD,sDAAqD;AAA5C,wGAAA,UAAU,OAAA;AAUnB,oBAAoB;AACpB,IAAI,UAAU,GAAsB,IAAI,CAAC;AAEzC;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,MAAyB;IACrD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,GAAG,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC;QACtC,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,EAAE,CAAC;QACtC,UAAU,GAAG,IAAI,uBAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,2BAA2B;AAC3B,SAAgB,eAAe;IAC7B,IAAI,UAAU,EAAE,CAAC;QACf,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,UAAU,GAAG,IAAI,CAAC;IACpB,CAAC;AACH,CAAC"}

package/dist/cjs/spi/adapters.d.ts

@@ -1,6 +1,43 @@
+/**
+ * ## 设计原则
+ *
+ * agent-server 核心只定义**接口**（能力契约），不依赖具体框架。
+ *
+ * 以下适配器实现是**可选参考实现**，业务层可以：
+ * 1. 直接使用（如果满足需求）
+ * 2. 参考实现自己定制（如果有特殊需求）
+ * 3. 完全自己实现（如果框架不同）
+ *
+ * ### 使用示例
+ *
+ * ```typescript
+ * // 方式 1：直接使用提供的适配器
+ * import { KoaSSEAdapter } from '@cicctencent/agent-server';
+ * const adapter = new KoaSSEAdapter(ctx);
+ *
+ * // 方式 2：继承并扩展
+ * class MySSEAdapter extends KoaSSEAdapter {
+ *   write(data: string) {
+ *     // 添加自定义逻辑（如日志、监控）
+ *     console.log('[SSE]', data.length, 'bytes');
+ *     super.write(data);
+ *   }
+ * }
+ *
+ * // 方式 3：完全自己实现
+ * class CustomSSEAdapter implements SSEResponseAdapter {
+ *   // 完全自定义实现
+ * }
+ * ```
+ */
 import type { SSEResponseAdapter, RequestContextAdapter } from './types.js';
 /**
- * Express SSE 适配器
+ * Express SSE 适配器（参考实现）
+ *
+ * 业务层可以：
+ * - 直接使用
+ * - 继承扩展
+ * - 参考 implementation 自己实现
  */
 export declare class ExpressSSEAdapter implements SSEResponseAdapter {
     private res;
@@ -14,7 +51,7 @@ export declare class ExpressSSEAdapter implements SSEResponseAdapter {
     json(data: unknown): void;
 }
 /**
- * Koa/MidwayJS SSE 适配器
+ * Koa/MidwayJS SSE 适配器（参考实现）
  */
 export declare class KoaSSEAdapter implements SSEResponseAdapter {
     private ctx;
@@ -28,7 +65,7 @@ export declare class KoaSSEAdapter implements SSEResponseAdapter {
     json(data: unknown): void;
 }
 /**
- * Fastify SSE 适配器
+ * Fastify SSE 适配器（参考实现）
  */
 export declare class FastifySSEAdapter implements SSEResponseAdapter {
     private reply;
@@ -57,6 +94,21 @@ export declare class NativeHttpSSEAdapter implements SSEResponseAdapter {
 }
 /**
  * 自动检测框架类型并创建适配器
+ *
+ * ⚠️ 注意：此函数是便捷工具，但建议业务层显式创建适配器：
+ *
+ * ```typescript
+ * // 推荐：显式创建（更可控）
+ * const adapter = new KoaSSEAdapter(ctx);
+ *
+ * // 不推荐：自动检测（可能误判）
+ * const adapter = adaptSSE(ctx);
+ * ```
+ *
+ * 自动检测可能存在的问题：
+ * - 框架版本差异导致误判
+ * - 自定义响应对象无法识别
+ * - 难以调试
  */
 export declare function adaptSSE(res: unknown): SSEResponseAdapter;
 /**

package/dist/cjs/spi/adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../../src/spi/adapters.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAM5E;;GAEG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAC9C,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,GAAG;IAE5B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIzB,GAAG,IAAI,IAAI;IAIX,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIrD,YAAY,IAAI,IAAI;IAIpB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;CAG1B;AAED;;GAEG;AACH,qBAAa,aAAc,YAAW,kBAAkB;IAC1C,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,GAAG;IAE5B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIzB,GAAG,IAAI,IAAI;IAIX,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIrD,YAAY,IAAI,IAAI;IAIpB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;CAG1B;AAED;;GAEG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAC9C,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,GAAG;IAE9B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIzB,GAAG,IAAI,IAAI;IAIX,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIrD,YAAY,IAAI,IAAI;IAIpB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;CAG1B;AAED;;GAEG;AACH,qBAAa,oBAAqB,YAAW,kBAAkB;IACjD,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,GAAG;IAE5B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIzB,GAAG,IAAI,IAAI;IAIX,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIrD,YAAY,IAAI,IAAI;IAIpB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;CAI1B;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,CA+BzD;AAMD;;GAEG;AACH,qBAAa,qBAAsB,YAAW,qBAAqB;IACrD,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,GAAG;IAE5B,SAAS,IAAI,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxC,cAAc,IAAI,MAAM,GAAG,MAAM,GAAG,SAAS;IAK7C,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI3C,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI1C,aAAa,IAAI,OAAO;IAIxB,cAAc,IAAI,OAAO;CAG1B;AAED;;GAEG;AACH,qBAAa,iBAAkB,YAAW,qBAAqB;IACjD,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,GAAG;IAE5B,SAAS,IAAI,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxC,cAAc,IAAI,MAAM,GAAG,MAAM,GAAG,SAAS;IAK7C,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI3C,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAI1C,aAAa,IAAI,OAAO;IAIxB,cAAc,IAAI,OAAO;CAG1B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,qBAAqB,CAYhE;AAMD;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,kBAAkB;IAKvD,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,OAAO,CAAC;IANlB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,OAAO,CAAkC;gBAGvC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC/B,KAAK,EAAE,MAAM,IAAI,EACjB,OAAO,CAAC,EAAE,MAAM,IAAI;IAG9B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKzB,GAAG,IAAI,IAAI;IAKX,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIrD,YAAY,IAAI,IAAI;IAIpB,gBAAgB;IAChB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAGrC"}
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../../src/spi/adapters.ts"],"names":[],"mappings":"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"}

package/dist/cjs/spi/adapters.js

@@ -2,15 +2,52 @@
 // ============================================================
 // 框架适配器 — 支持不同 Web 框架
 // ============================================================
+/**
+ * ## 设计原则
+ *
+ * agent-server 核心只定义**接口**（能力契约），不依赖具体框架。
+ *
+ * 以下适配器实现是**可选参考实现**，业务层可以：
+ * 1. 直接使用（如果满足需求）
+ * 2. 参考实现自己定制（如果有特殊需求）
+ * 3. 完全自己实现（如果框架不同）
+ *
+ * ### 使用示例
+ *
+ * ```typescript
+ * // 方式 1：直接使用提供的适配器
+ * import { KoaSSEAdapter } from '@cicctencent/agent-server';
+ * const adapter = new KoaSSEAdapter(ctx);
+ *
+ * // 方式 2：继承并扩展
+ * class MySSEAdapter extends KoaSSEAdapter {
+ *   write(data: string) {
+ *     // 添加自定义逻辑（如日志、监控）
+ *     console.log('[SSE]', data.length, 'bytes');
+ *     super.write(data);
+ *   }
+ * }
+ *
+ * // 方式 3：完全自己实现
+ * class CustomSSEAdapter implements SSEResponseAdapter {
+ *   // 完全自定义实现
+ * }
+ * ```
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CustomSSEAdapter = exports.KoaRequestAdapter = exports.ExpressRequestAdapter = exports.NativeHttpSSEAdapter = exports.FastifySSEAdapter = exports.KoaSSEAdapter = exports.ExpressSSEAdapter = void 0;
 exports.adaptSSE = adaptSSE;
 exports.adaptRequest = adaptRequest;
 // ============================================================
-// SSE 响应适配器
+// SSE 响应适配器（参考实现）
 // ============================================================
 /**
- * Express SSE 适配器
+ * Express SSE 适配器（参考实现）
+ *
+ * 业务层可以：
+ * - 直接使用
+ * - 继承扩展
+ * - 参考 implementation 自己实现
  */
 class ExpressSSEAdapter {
     res;
@@ -41,12 +78,16 @@ class ExpressSSEAdapter {
 }
 exports.ExpressSSEAdapter = ExpressSSEAdapter;
 /**
- * Koa/MidwayJS SSE 适配器
+ * Koa/MidwayJS SSE 适配器（参考实现）
  */
 class KoaSSEAdapter {
     ctx;
     constructor(ctx) {
         this.ctx = ctx;
+        // 禁止 Koa 框架自行处理响应，让 SSE 流完全由适配器控制
+        if (this.ctx && 'respond' in this.ctx) {
+            this.ctx.respond = false;
+        }
     }
     write(data) {
         this.ctx.res.write(data);
@@ -61,7 +102,7 @@ class KoaSSEAdapter {
         this.ctx.set(name, String(value));
     }
     flushHeaders() {
-        this.ctx.res.flush?.();
+        this.ctx.res.flushHeaders?.();
     }
     status(code) {
         this.ctx.status = code;
@@ -72,7 +113,7 @@ class KoaSSEAdapter {
 }
 exports.KoaSSEAdapter = KoaSSEAdapter;
 /**
- * Fastify SSE 适配器
+ * Fastify SSE 适配器（参考实现）
  */
 class FastifySSEAdapter {
     reply;
@@ -136,6 +177,21 @@ class NativeHttpSSEAdapter {
 exports.NativeHttpSSEAdapter = NativeHttpSSEAdapter;
 /**
  * 自动检测框架类型并创建适配器
+ *
+ * ⚠️ 注意：此函数是便捷工具，但建议业务层显式创建适配器：
+ *
+ * ```typescript
+ * // 推荐：显式创建（更可控）
+ * const adapter = new KoaSSEAdapter(ctx);
+ *
+ * // 不推荐：自动检测（可能误判）
+ * const adapter = adaptSSE(ctx);
+ * ```
+ *
+ * 自动检测可能存在的问题：
+ * - 框架版本差异导致误判
+ * - 自定义响应对象无法识别
+ * - 难以调试
  */
 function adaptSSE(res) {
     // Express: res.setHeader, res.write, res.end

package/dist/cjs/spi/adapters.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../../../src/spi/adapters.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../../../src/spi/adapters.ts"],"names":[],"mappings":"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"}

package/dist/cjs/spi/index.d.ts

@@ -1,3 +1,87 @@
+/**
+ * # agent-server SPI (Service Provider Interface)
+ *
+ * ## 核心设计原则
+ *
+ * 1. **接口优先**：agent-server 核心只定义能力接口，不依赖具体实现
+ * 2. **参考实现可选**：提供常见框架的参考实现，业务层可选择使用或自己实现
+ * 3. **业务层自主**：完全控制实现细节，不受 agent-server 限制
+ *
+ * ## 使用方式
+ *
+ * ### 方式 1：直接使用参考实现（最简单）
+ *
+ * ```typescript
+ * import { KoaSSEAdapter, createAgentServer } from '@cicctencent/agent-server';
+ *
+ * const server = createAgentServer({ llmProvider: myProvider });
+ *
+ * // MidwayJS/Koa 项目
+ * @Get('/chat/stream')
+ * async chatStream(@Ctx() ctx: Context) {
+ *   const adapter = new KoaSSEAdapter(ctx);
+ *   await server.runAgentStream(adapter, { content: 'Hello' });
+ * }
+ * ```
+ *
+ * ### 方式 2：实现 SPI 接口（自定义存储）
+ *
+ * ```typescript
+ * import {
+ *   createAgentServer,
+ *   type ChatStoreProvider,
+ *   type BaseThreadEntity,
+ *   type BaseMessageEntity,
+ * } from '@cicctencent/agent-server';
+ *
+ * // 定义你的实体类型（可以自定义字段）
+ * interface MyThread extends BaseThreadEntity {
+ *   userId: string;
+ *   applicationId: number;
+ * }
+ *
+ * // 实现 ChatStoreProvider 接口
+ * class MyChatStore implements ChatStoreProvider<MyThread, MyMessage> {
+ *   async getThreads(userId?: string): Promise<MyThread[]> {
+ *     // 使用任意存储技术：TypeORM / Prisma / Mongoose / ...
+ *     return this.database.query('SELECT * FROM threads WHERE userId = ?', [userId]);
+ *   }
+ *
+ *   // ... 实现其他方法
+ * }
+ *
+ * // 注入自定义实现
+ * const server = createAgentServer({
+ *   llmProvider: myProvider,
+ *   chatStoreProvider: new MyChatStore(),
+ * });
+ * ```
+ *
+ * ### 方式 3：只使用组件（不使用工厂）
+ *
+ * ```typescript
+ * import {
+ *   KoaSSEAdapter,
+ *   writeSSE,
+ *   createBuiltinTools,
+ *   MemoryService,
+ * } from '@cicctencent/agent-server';
+ *
+ * // 只使用需要的组件，不依赖 createAgentServer
+ * const tools = createBuiltinTools();
+ * const memoryService = new MemoryService('./data');
+ *
+ * @Get('/stream')
+ * async stream(@Ctx() ctx: Context) {
+ *   const adapter = new KoaSSEAdapter(ctx);
+ *   writeSSE(adapter, 'start', { message: 'Hello' });
+ * }
+ * ```
+ *
+ * ## 完整文档
+ *
+ * 详见 [README.md](./README.md)
+ */
 export type { BaseThreadEntity, BaseMessageEntity, BaseWorkspaceEntity, BaseAgentProfileEntity, BaseSettingsEntity, KVStorageAdapter, ListStorageAdapter, QueryOptions, SettingsProvider, ChatStoreProvider, AgentProfileProvider, PromptBuilderProvider, ModelConfigResolver, SSEResponseAdapter, RequestContextAdapter, AgentServerSPIOptions, ThreadEntity, MessageEntity, WorkspaceEntity, AgentProfileEntity, SettingsEntity, } from './types.js';
 export { JsonFileKVStorage, JsonFileListStorage, InMemoryKVStorage, InMemoryListStorage, DatabaseListStorage, createJsonFileStorage, createInMemoryStorage, } from './storage.js';
 export { ExpressSSEAdapter, KoaSSEAdapter, FastifySSEAdapter, NativeHttpSSEAdapter, adaptSSE, ExpressRequestAdapter, KoaRequestAdapter, adaptRequest, CustomSSEAdapter, } from './adapters.js';

package/dist/cjs/spi/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/spi/index.ts"],"names":[],"mappings":"AAKA,YAAY,EAEV,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAElB,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EAEZ,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EAEnB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EAErB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAEL,iBAAiB,EACjB,mBAAmB,EAEnB,iBAAiB,EACjB,mBAAmB,EAEnB,mBAAmB,EAEnB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAEL,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,oBAAoB,EACpB,QAAQ,EAER,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EAEZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAMvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/spi/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AAGH,YAAY,EAEV,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAGlB,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EAGZ,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EAGnB,kBAAkB,EAClB,qBAAqB,EAGrB,qBAAqB,EAGrB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAEL,iBAAiB,EACjB,mBAAmB,EAGnB,iBAAiB,EACjB,mBAAmB,EAGnB,mBAAmB,EAGnB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAEL,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,oBAAoB,EACpB,QAAQ,EAGR,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,EAGZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAMvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG"}