hyacinth-ai 0.9.6

package/dist/provider/user-id.js

@@ -0,0 +1,53 @@
+// ============================================================
+// provider/user-id — 集中管理 DeepSeek KVCache 隔离 ID
+// ============================================================
+//
+// DeepSeek API 通过 user_id 字段隔离不同调用方的 KV 缓存池。
+// 不同角色/模式应使用不同的 userId，避免缓存互相污染。
+//
+// 命名规范：
+//   {prefix}-{role}              静态角色（旁路、压缩器等单实例）
+//   {prefix}-{role}-{tag}        动态角色（主Agent、子Agent 等多实例）
+//
+// 前缀默认 'hyacinth'，可通过 setUserIdPrefix() 在启动时覆盖
+//（同步 config.provider.userId）。
+//
+// 6 个 LLM 调用点：
+//   1. 主Agent（普通模式） → {prefix}-main-{sessionTag}
+//   2. 旁路Agent（普通模式） → {prefix}-orchestrator
+//   3. 主Agent（陪伴模式） → {prefix}-companion-{characterName}
+//   4. 旁路Agent（陪伴模式） → {prefix}-narration
+//   5. 压缩器               → {prefix}-compressor
+//   6. 子Agent              → {prefix}-sub-{name}-{instanceId}
+// ============================================================
+// ── 默认（唯一硬编码兜底值） ─────────────────────────────────
+export const DEFAULT_USER_ID = 'hyacinth';
+let _prefix = DEFAULT_USER_ID;
+// ── 前缀管理 ────────────────────────────────────────────────
+/** 启动时调用，将前缀同步为配置中的 provider.userId */
+export function setUserIdPrefix(prefix) {
+    _prefix = prefix;
+}
+function make(role, tag) {
+    return tag ? `${_prefix}-${role}-${tag}` : `${_prefix}-${role}`;
+}
+// ── 主Agent ──────────────────────────────────────────────────
+/** 主Agent 普通模式 */
+export function mainUserId(sessionTag) {
+    return make('main', sessionTag);
+}
+/** 主Agent 陪伴模式 */
+export function companionUserId(characterName) {
+    return make('companion', characterName);
+}
+// ── 旁路Agent ───────────────────────────────────────────────
+export function orchestratorUserId() { return make('orchestrator'); }
+export function narrationUserId() { return make('narration'); }
+// ── 压缩器 ──────────────────────────────────────────────────
+export function compressorUserId() { return make('compressor'); }
+// ── 子Agent ─────────────────────────────────────────────────
+/** 子Agent（按名称 + 实例ID 隔离） */
+export function subAgentUserId(agentName, instanceId) {
+    return make('sub', `${agentName}-${instanceId}`);
+}
+//# sourceMappingURL=user-id.js.map

package/dist/provider/zhipu.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Zhipu (智谱 / BigModel) Provider — OpenAI 兼容协议。
+ *
+ * GLM-4.6V 支持多模态视觉输入，格式与 OpenAI Chat Completions 完全一致。
+ *
+ * 端点: https://open.bigmodel.cn/api/paas/v4
+ * 认证: Authorization: Bearer $ZHIPU_API_KEY
+ */
+import { OpenAICompatibleProvider } from './compatible.js';
+import type { ProviderConfig } from '../types.js';
+export declare function createZhipuProvider(config?: {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+    maxOutputTokens?: number;
+    userId?: string;
+}): OpenAICompatibleProvider;
+export declare function createZhipuFromConfig(config: ProviderConfig): OpenAICompatibleProvider;
+//# sourceMappingURL=zhipu.d.ts.map

package/dist/provider/zhipu.js

@@ -0,0 +1,32 @@
+/**
+ * Zhipu (智谱 / BigModel) Provider — OpenAI 兼容协议。
+ *
+ * GLM-4.6V 支持多模态视觉输入，格式与 OpenAI Chat Completions 完全一致。
+ *
+ * 端点: https://open.bigmodel.cn/api/paas/v4
+ * 认证: Authorization: Bearer $ZHIPU_API_KEY
+ */
+import { OpenAICompatibleProvider } from './compatible.js';
+import { getProviderConfigLoader } from './config.js';
+export function createZhipuProvider(config) {
+    const provCfg = getProviderConfigLoader().getProvider('zhipu');
+    return new OpenAICompatibleProvider({
+        apiKey: config?.apiKey,
+        envKey: 'ZHIPU_API_KEY',
+        baseUrl: config?.baseUrl ?? provCfg?.baseUrl ?? 'https://open.bigmodel.cn/api/paas/v4',
+        model: config?.model ?? provCfg?.defaultModel ?? 'glm-4.6v',
+        providerType: 'zhipu',
+        maxOutputTokens: config?.maxOutputTokens,
+        userId: config?.userId,
+    });
+}
+export function createZhipuFromConfig(config) {
+    return createZhipuProvider({
+        apiKey: config.apiKey,
+        model: config.model,
+        baseUrl: config.baseUrl,
+        maxOutputTokens: config.maxOutputTokens,
+        userId: config.userId,
+    });
+}
+//# sourceMappingURL=zhipu.js.map

package/dist/registry/agent.registry.d.ts

@@ -0,0 +1,57 @@
+import { GenericRegistry, type RegistryItem } from './base.js';
+import type { AgentDefinition } from '../types.js';
+interface RegisteredAgent extends AgentDefinition, RegistryItem {
+}
+/**
+ * AgentRegistry — 子 Agent 注册表（支持多实例分身）
+ *
+ * 通过 instanceId 支持同一 name 的多个运行时实例。
+ * 继承自 GenericRegistry，但因多实例语义覆写了大部分方法：
+ * - items 以 instanceId 为键（非 name）
+ * - _disabled 存储禁用的 instanceId
+ * - get(name) 返回该名称下所有启用的实例数组
+ * - enable/disable 作用于该名称下的所有实例
+ */
+export declare class AgentRegistry extends GenericRegistry<RegisteredAgent> {
+    /** 按 name 分组存储 { [name]: RegisteredAgent[] } */
+    private agents;
+    constructor();
+    /** 注册子 Agent 定义（自动分配 instanceId 若未提供） */
+    register(def: RegisteredAgent): RegisteredAgent;
+    /** 基于已有 Agent 创建分身（克隆定义 + 新 instanceId） */
+    spawnInstance(name: string, customName?: string): RegisteredAgent | undefined;
+    /** 按名称获取该名称下所有启用实例（多实例语义，返回数组而非单值） */
+    get(name: string): RegisteredAgent[];
+    /** 按实例 ID 精确查找（不受禁用影响） */
+    getByInstanceId(instanceId: string): RegisteredAgent | undefined;
+    /** 获取所有已注册且启用的实例 */
+    getAll(): RegisteredAgent[];
+    /** 检查给定名称下是否有启用实例 */
+    has(name: string): boolean;
+    /** 启用某个名称下的所有实例 */
+    enable(name: string): void;
+    /** 禁用某个名称下的所有实例 */
+    disable(name: string): void;
+    /** 检查某个名称下是否有启用实例 */
+    isEnabled(name: string): boolean;
+    getEnabled(): RegisteredAgent[];
+    getDisabled(): RegisteredAgent[];
+    isEmpty(): boolean;
+    size(): number;
+    /** 注销某个名称的全部实例 */
+    unregister(name: string): boolean;
+    /** 销毁单个实例 */
+    destroyInstance(instanceId: string): boolean;
+    /** 更新单个实例的配置 */
+    update(instanceId: string, partial: Partial<Omit<AgentDefinition, 'name' | 'instanceId'>>): RegisteredAgent | undefined;
+    /** 生成紧凑索引（名称 + 描述 + instanceId），供 Zone 2 使用 */
+    getIndex(): string;
+    /** 生成完整定义文本，供精确模式展开 */
+    getFullDefinitions(names?: string[]): string;
+    /** @deprecated 使用 enable() 替代 */
+    enableAgent(name: string): void;
+    /** @deprecated 使用 disable() 替代 */
+    disableAgent(name: string): void;
+}
+export {};
+//# sourceMappingURL=agent.registry.d.ts.map

package/dist/registry/agent.registry.js

@@ -0,0 +1,224 @@
+import crypto from 'node:crypto';
+import { GenericRegistry } from './base.js';
+function shortId() {
+    return crypto.randomUUID().split('-')[0];
+}
+/**
+ * AgentRegistry — 子 Agent 注册表（支持多实例分身）
+ *
+ * 通过 instanceId 支持同一 name 的多个运行时实例。
+ * 继承自 GenericRegistry，但因多实例语义覆写了大部分方法：
+ * - items 以 instanceId 为键（非 name）
+ * - _disabled 存储禁用的 instanceId
+ * - get(name) 返回该名称下所有启用的实例数组
+ * - enable/disable 作用于该名称下的所有实例
+ */
+export class AgentRegistry extends GenericRegistry {
+    /** 按 name 分组存储 { [name]: RegisteredAgent[] } */
+    agents = new Map();
+    constructor() {
+        super();
+    }
+    // ── 注册 / 创建 ──────────────────────────────────────────────
+    /** 注册子 Agent 定义（自动分配 instanceId 若未提供） */
+    register(def) {
+        if (!def.instanceId) {
+            def.instanceId = `${def.name}-${shortId()}`;
+        }
+        const list = this.agents.get(def.name) || [];
+        list.push(def);
+        this.agents.set(def.name, list);
+        this.items.set(def.instanceId, def);
+        this.emit('register', def.name);
+        return def;
+    }
+    /** 基于已有 Agent 创建分身（克隆定义 + 新 instanceId） */
+    spawnInstance(name, customName) {
+        const list = this.agents.get(name);
+        if (!list || list.length === 0)
+            return undefined;
+        const template = list[0]; // 取第一个作为模板
+        const clone = {
+            ...template,
+            instanceId: `${name}-${shortId()}`,
+        };
+        if (customName) {
+            clone.name = customName;
+        }
+        return this.register(clone);
+    }
+    // ── 查询 ─────────────────────────────────────────────────────
+    /** 按名称获取该名称下所有启用实例（多实例语义，返回数组而非单值） */
+    // @ts-expect-error: AgentRegistry 多实例语义 — get() 返回数组，与基类返回值不同，这是有意为之
+    get(name) {
+        const list = this.agents.get(name);
+        if (!list)
+            return [];
+        return list.filter(d => !this._disabled.has(d.instanceId));
+    }
+    /** 按实例 ID 精确查找（不受禁用影响） */
+    getByInstanceId(instanceId) {
+        return this.items.get(instanceId);
+    }
+    /** 获取所有已注册且启用的实例 */
+    getAll() {
+        const result = [];
+        for (const list of this.agents.values()) {
+            for (const def of list) {
+                if (!this._disabled.has(def.instanceId)) {
+                    result.push(def);
+                }
+            }
+        }
+        return result;
+    }
+    /** 检查给定名称下是否有启用实例 */
+    has(name) {
+        return this.get(name).length > 0;
+    }
+    // ── 启用 / 禁用 ──────────────────────────────────────────────
+    /** 启用某个名称下的所有实例 */
+    enable(name) {
+        const list = this.agents.get(name);
+        if (!list)
+            return;
+        for (const def of list) {
+            this._disabled.delete(def.instanceId);
+        }
+        this.emit('enable', name);
+    }
+    /** 禁用某个名称下的所有实例 */
+    disable(name) {
+        const list = this.agents.get(name);
+        if (!list)
+            return;
+        const anyNew = list.some(def => !this._disabled.has(def.instanceId));
+        for (const def of list) {
+            this._disabled.add(def.instanceId);
+        }
+        if (anyNew)
+            this.emit('disable', name);
+    }
+    /** 检查某个名称下是否有启用实例 */
+    isEnabled(name) {
+        return this.get(name).length > 0;
+    }
+    // ── 列表 ─────────────────────────────────────────────────────
+    getEnabled() {
+        return this.getAll();
+    }
+    getDisabled() {
+        const result = [];
+        for (const list of this.agents.values()) {
+            for (const def of list) {
+                if (this._disabled.has(def.instanceId)) {
+                    result.push(def);
+                }
+            }
+        }
+        return result;
+    }
+    // ── 统计 ─────────────────────────────────────────────────────
+    isEmpty() {
+        for (const list of this.agents.values()) {
+            if (list.length > 0)
+                return false;
+        }
+        return true;
+    }
+    size() {
+        let count = 0;
+        for (const list of this.agents.values()) {
+            count += list.length;
+        }
+        return count;
+    }
+    // ── 移除 ─────────────────────────────────────────────────────
+    /** 注销某个名称的全部实例 */
+    unregister(name) {
+        const list = this.agents.get(name);
+        if (!list)
+            return false;
+        for (const def of list) {
+            this.items.delete(def.instanceId);
+            this._disabled.delete(def.instanceId);
+        }
+        this.agents.delete(name);
+        this.emit('unregister', name);
+        return true;
+    }
+    /** 销毁单个实例 */
+    destroyInstance(instanceId) {
+        const def = this.items.get(instanceId);
+        if (!def)
+            return false;
+        this.items.delete(instanceId);
+        this._disabled.delete(instanceId);
+        const list = this.agents.get(def.name);
+        if (list) {
+            const idx = list.findIndex(d => d.instanceId === instanceId);
+            if (idx >= 0)
+                list.splice(idx, 1);
+            if (list.length === 0)
+                this.agents.delete(def.name);
+        }
+        return true;
+    }
+    /** 更新单个实例的配置 */
+    update(instanceId, partial) {
+        const def = this.items.get(instanceId);
+        if (!def)
+            return undefined;
+        if (partial.description !== undefined)
+            def.description = partial.description;
+        if (partial.systemPrompt !== undefined)
+            def.systemPrompt = partial.systemPrompt;
+        if (partial.allowedTools !== undefined)
+            def.allowedTools = partial.allowedTools;
+        if (partial.modelPreference !== undefined)
+            def.modelPreference = partial.modelPreference;
+        if (partial.maxTurns !== undefined)
+            def.maxTurns = partial.maxTurns;
+        if (partial.collaborationMode !== undefined)
+            def.collaborationMode = partial.collaborationMode;
+        if (partial.sessionTtlMinutes !== undefined)
+            def.sessionTtlMinutes = partial.sessionTtlMinutes;
+        this.emit('update', instanceId);
+        return def;
+    }
+    // ── 索引（供 prompt 使用） ────────────────────────────────────
+    /** 生成紧凑索引（名称 + 描述 + instanceId），供 Zone 2 使用 */
+    getIndex() {
+        const all = this.getAll();
+        if (all.length === 0)
+            return 'No sub-agents available';
+        return all.map(a => {
+            const extra = all.filter(x => x.name === a.name).length > 1
+                ? ` (id: ${a.instanceId})`
+                : '';
+            return `- ${a.name}${extra}: ${a.description} [${a.collaborationMode}]`;
+        }).join('\n');
+    }
+    /** 生成完整定义文本，供精确模式展开 */
+    getFullDefinitions(names) {
+        const agents = names
+            ? this.getAll().filter(a => names.includes(a.name))
+            : this.getAll();
+        if (agents.length === 0)
+            return '';
+        return agents.map(a => {
+            const tools = a.allowedTools.length > 0 ? a.allowedTools.join(', ') : 'all';
+            return `## Sub-Agent: ${a.name}\nInstance: ${a.instanceId}\nDescription: ${a.description}\nMode: ${a.collaborationMode}\nAllowed Tools: ${tools}\nMax Turns: ${a.maxTurns}\nSystem Prompt: ${a.systemPrompt}`;
+        }).join('\n\n');
+    }
+    // ── 向后兼容别名 ──────────────────────────────────────────────
+    /** @deprecated 使用 enable() 替代 */
+    enableAgent(name) {
+        this.enable(name);
+    }
+    /** @deprecated 使用 disable() 替代 */
+    disableAgent(name) {
+        this.disable(name);
+    }
+}
+//# sourceMappingURL=agent.registry.js.map

package/dist/registry/base.d.ts

@@ -0,0 +1,54 @@
+/**
+ * GenericRegistry<T> — 统一注册表基类
+ *
+ * 提供所有 Registry 共享的 register/unregister/enable/disable 标准接口。
+ * 子类只需继承并选择性重写特定方法即可。
+ */
+/** 所有可注册对象的基接口 */
+export interface RegistryItem {
+    /** 唯一标识 */
+    name: string;
+    /** 来源标识：'builtin' | 'mcp' | 'plugin' | 'file' | 'user' */
+    source?: string;
+}
+/** GenericRegistry 上的事件类型 */
+export type RegistryEvent = 'register' | 'unregister' | 'enable' | 'disable' | 'update';
+export type RegistryEventListener = (event: RegistryEvent, name: string) => void;
+export declare abstract class GenericRegistry<T extends RegistryItem> {
+    /** 注册条目 */
+    protected items: Map<string, T>;
+    /** 禁用集合 */
+    protected _disabled: Set<string>;
+    /** 事件监听器 */
+    private listeners;
+    /** 注册一个条目（同名覆盖） */
+    register(item: T): void;
+    /** 注销一个条目，返回是否成功 */
+    unregister(name: string): boolean;
+    /** 获取指定条目（禁用的返回 undefined） */
+    get(name: string): T | undefined;
+    /** 获取所有已启用条目 */
+    getAll(): T[];
+    /** 检查条目是否存在（不区分启用/禁用） */
+    has(name: string): boolean;
+    /** 启用一个条目 */
+    enable(name: string): void;
+    /** 禁用一个条目（存在才禁用） */
+    disable(name: string): void;
+    /** 检查是否已启用 */
+    isEnabled(name: string): boolean;
+    /** 获取所有已启用条目（同 getAll） */
+    getEnabled(): T[];
+    /** 获取所有已禁用条目 */
+    getDisabled(): T[];
+    /** 检查注册表是否为空 */
+    isEmpty(): boolean;
+    /** 获取注册条目总数（含禁用） */
+    size(): number;
+    /** 注册事件监听 */
+    onEvent(listener: RegistryEventListener): void;
+    /** 移除事件监听 */
+    offEvent(listener: RegistryEventListener): void;
+    protected emit(event: RegistryEvent, name: string): void;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/registry/base.js

@@ -0,0 +1,99 @@
+/**
+ * GenericRegistry<T> — 统一注册表基类
+ *
+ * 提供所有 Registry 共享的 register/unregister/enable/disable 标准接口。
+ * 子类只需继承并选择性重写特定方法即可。
+ */
+export class GenericRegistry {
+    /** 注册条目 */
+    items = new Map();
+    /** 禁用集合 */
+    _disabled = new Set();
+    /** 事件监听器 */
+    listeners = [];
+    // ── 注册 / 注销 ──────────────────────────────────────────────
+    /** 注册一个条目（同名覆盖） */
+    register(item) {
+        this.items.set(item.name, item);
+        this.emit('register', item.name);
+    }
+    /** 注销一个条目，返回是否成功 */
+    unregister(name) {
+        this._disabled.delete(name);
+        const deleted = this.items.delete(name);
+        if (deleted)
+            this.emit('unregister', name);
+        return deleted;
+    }
+    // ── 查询 ─────────────────────────────────────────────────────
+    /** 获取指定条目（禁用的返回 undefined） */
+    get(name) {
+        if (this._disabled.has(name))
+            return undefined;
+        return this.items.get(name);
+    }
+    /** 获取所有已启用条目 */
+    getAll() {
+        return [...this.items.values()].filter((i) => !this._disabled.has(i.name));
+    }
+    /** 检查条目是否存在（不区分启用/禁用） */
+    has(name) {
+        return this.items.has(name);
+    }
+    // ── 启用 / 禁用 ──────────────────────────────────────────────
+    /** 启用一个条目 */
+    enable(name) {
+        if (this._disabled.has(name)) {
+            this._disabled.delete(name);
+            this.emit('enable', name);
+        }
+    }
+    /** 禁用一个条目（存在才禁用） */
+    disable(name) {
+        if (this.items.has(name) && !this._disabled.has(name)) {
+            this._disabled.add(name);
+            this.emit('disable', name);
+        }
+    }
+    /** 检查是否已启用 */
+    isEnabled(name) {
+        return this.items.has(name) && !this._disabled.has(name);
+    }
+    /** 获取所有已启用条目（同 getAll） */
+    getEnabled() {
+        return this.getAll();
+    }
+    /** 获取所有已禁用条目 */
+    getDisabled() {
+        return [...this.items.values()].filter((i) => this._disabled.has(i.name));
+    }
+    // ── 统计 ─────────────────────────────────────────────────────
+    /** 检查注册表是否为空 */
+    isEmpty() {
+        return this.items.size === 0;
+    }
+    /** 获取注册条目总数（含禁用） */
+    size() {
+        return this.items.size;
+    }
+    // ── 事件 ─────────────────────────────────────────────────────
+    /** 注册事件监听 */
+    onEvent(listener) {
+        this.listeners.push(listener);
+    }
+    /** 移除事件监听 */
+    offEvent(listener) {
+        const idx = this.listeners.indexOf(listener);
+        if (idx >= 0)
+            this.listeners.splice(idx, 1);
+    }
+    emit(event, name) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event, name);
+            }
+            catch { /* 不抛出让调用方崩溃 */ }
+        }
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/registry/channel.registry.d.ts

@@ -0,0 +1,53 @@
+import { GenericRegistry, type RegistryItem } from './base.js';
+import { ChannelManager } from '../channels/manager.js';
+import type { ChannelHandler, ChannelConfig, ChannelReply, AgentFactory } from '../channels/interface.js';
+interface RegisteredChannel extends RegistryItem {
+    name: string;
+    handler: ChannelHandler;
+    config: ChannelConfig;
+    source?: string;
+}
+/**
+ * ChannelRegistry — 带 enable/disable 能力的渠道注册表。
+ *
+ * 包装 ChannelManager，在其基础上添加启用/禁用控制：
+ * - 禁用的渠道不会被启动（startAll 时自动过滤）
+ * - 查询接口（getAll / get）仅返回已启用的渠道
+ */
+export declare class ChannelRegistry extends GenericRegistry<RegisteredChannel> {
+    private manager;
+    constructor(manager?: ChannelManager);
+    register(item: RegisteredChannel): void;
+    unregister(name: string): boolean;
+    /** 获取指定渠道（禁用的返回 undefined） */
+    get(name: string): RegisteredChannel | undefined;
+    /** 获取所有已启用的渠道 */
+    getAll(): RegisteredChannel[];
+    disable(name: string): void;
+    enable(name: string): void;
+    /**
+     * 启动所有已启用的渠道。
+     *
+     * 如果提供了 enabledIds，仅启动其中已启用的渠道。
+     * 否则，启动所有本注册表中未禁用的渠道。
+     */
+    startAll(agentFactory: AgentFactory, enabledIds?: string[]): Promise<void>;
+    /** 停止所有渠道 */
+    stopAll(): Promise<void>;
+    /** 重启指定渠道 */
+    restart(id: string, agentFactory: AgentFactory): Promise<void>;
+    /** 通过指定渠道发送回复 */
+    send(channelId: string, sessionId: string, reply: ChannelReply): Promise<void>;
+    /** 获取所有渠道状态摘要 */
+    getStatusSummary(): {
+        id: string;
+        name: string;
+        status: import("../channels/interface.js").ChannelStatus;
+    }[];
+    /** 是否已启动 */
+    isStarted(): boolean;
+    /** 获取内部 ChannelManager */
+    getManager(): ChannelManager;
+}
+export {};
+//# sourceMappingURL=channel.registry.d.ts.map