mycohive-claw 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MycoHive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# MycoHive-Claw
+
+> OpenClaw Plugin for Multi-Agent Orchestration with LLM Intent Routing
+
+[English](#english) | [中文](#中文)
+
+---
+
+## English
+
+### Overview
+
+MycoHive-Claw is an OpenClaw plugin that implements a **corporate-style multi-agent collaboration system** with 24 specialized agents. It features **LLM-driven intent analysis** that automatically routes user requests to the appropriate agents — no manual `@agent` or `!!` prefixes needed.
+
+### Architecture
+
+```
+Entry Layer → Router (LLM Intent Analysis)
+                    ↓
+              Coordinator (Task Decomposition)
+                    ↓
+        ┌──────────┴──────────┐
+        ↓         ↓         ↓
+  Management   Execution    Review
+  (planner,   (coder,      (reviewer,
+   observer)   frontend,     qa,
+               backend...)   security)
+```
+
+**24 Agents** organized in 7 categories:
+- **Entry**: `front_director`, `router`
+- **Management**: `coordinator`, `planner`, `observer`
+- **Architecture**: `architect`
+- **Execution**: `coder`, `frontend_dev`, `backend_dev`, `api_dev`, `data_engineer`, `scripter`, `researcher`, `writer`, `translator`
+- **Review**: `reviewer`, `qa`, `security`, `evaluator`
+- **Tool**: `browser`, `scraper`, `deployer`
+- **Autonomous**: `builder`, `dreamer`
+
+### Key Features
+
+- **LLM Intent Routing** — Natural language auto-routing without `@xxx` / `!!` prefixes
+- **Context Tree** — WAL-based incremental persistence with crash recovery and CRC validation
+- **Event Bus** — Trie-prefix subscription matching + DLQ retry with exponential backoff
+- **Circuit Breaker** — Failure protection for dispatch pipeline
+- **Workspace Loader** — Dynamic agent capability discovery from filesystem
+- **Review Agent Isolation** — `session_mode: isolated` for reviewer/qa/security/evaluator
+
+### Requirements
+
+- **OpenClaw** (Plugin SDK compatible version)
+- **Node.js 18+** (for building)
+- **TypeScript 5.x** (dev dependency included)
+
+### Installation
+
+```bash
+# Install via npm (recommended)
+npm install mycohive-claw
+
+# Or install from GitHub directly
+npm install github:LiamLucas-m/MycoHive-Claw
+
+# Install to OpenClaw
+openclaw plugins install ./mycohive-claw
+
+# Restart OpenClaw
+openclaw restart
+```
+
+### Update
+
+```bash
+# Pull latest changes
+git pull
+
+# Rebuild
+npm run build
+
+# Restart OpenClaw
+openclaw restart
+```
+
+### Uninstall
+
+```bash
+openclaw plugins uninstall mycohive-claw
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts              # Plugin entry (createExtension)
+├── setup-entry.ts        # Setup entry (setup)
+├── router.ts             # Intent routing + dispatch with circuit breaker
+├── intent-analyzer.ts    # LLM + keyword dual-engine intent analysis
+├── context-tree.ts       # WAL-based incremental persistence + CRC
+├── event-bus.ts         # Pub/sub + Trie matching + DLQ retry
+├── circuit-breaker.ts   # Failure protection
+├── tool-handlers.ts     # mycohive_* tool handlers
+├── tools/mycohive-tools.ts  # Tool registration
+├── workspace-loader.ts  # Agent workspace loader (SOUL/SKILL/RULES/CONFIG)
+├── metrics.ts           # Metrics collection
+├── rate-limiter.ts      # Rate limiting
+├── result-cache.ts      # Result caching
+├── token-counter.ts     # Token counting
+├── logger.ts            # Logging
+├── i18n.ts             # Internationalization
+└── types.ts            # Shared type definitions
+
+workspaces/              # 24 Agent workspace definitions (SOUL.md + SKILL.md + RULES.md + CONFIG.md)
+```
+
+### License
+
+MIT
+
+---
+
+## 中文
+
+### 概述
+
+MycoHive-Claw 是一个 OpenClaw 插件，实现了**企业级多 Agent 协作系统**，包含 **24 个专业 Agent**。通过 **LLM 驱动的意图分析**自动将用户请求路由到合适的 Agent，无需手动指定 `@agent` 或 `!!` 前缀。
+
+### 架构
+
+```
+入口层 → 路由器（LLM 意图分析）
+                ↓
+          协调者（任务分解）
+                ↓
+    ┌───────────┴───────────┐
+    ↓           ↓           ↓
+  管理       执行         审查
+(planner,  (coder,      (reviewer,
+ observer)  frontend,    qa,
+             backend...)  security)
+```
+
+### 24 个 Agent
+
+- **入口层**: front_director, router
+- **管理类**: coordinator, planner, observer
+- **架构类**: architect
+- **执行类**: coder, frontend_dev, backend_dev, api_dev, data_engineer, scripter, researcher, writer, translator
+- **审查类**: reviewer, qa, security, evaluator
+- **工具类**: browser, scraper, deployer
+- **自主产出类**: builder, dreamer
+
+### 核心特性
+
+- **LLM 意图路由** — 自然语言自动路由，无需 `@xxx` / `!!` 前缀
+- **Context Tree** — WAL 增量持久化 + CRC 校验 + 崩溃恢复
+- **Event Bus** — 前缀树订阅匹配 + DLQ 重试（指数退避）
+- **熔断器** — 派发管道故障保护
+- **Workspace Loader** — 文件系统动态 Agent 能力发现
+- **审查类 Agent 隔离** — reviewer/qa/security/evaluator 使用独立 Session
+
+### 系统要求
+
+- **OpenClaw**（兼容 Plugin SDK 版本）
+- **Node.js 18+**
+- **TypeScript 5.x**
+
+### 安装
+
+```bash
+# 通过 npm 安装（推荐）
+npm install mycohive-claw
+
+# 或从 GitHub 直接安装
+npm install github:LiamLucas-m/MycoHive-Claw
+
+# 安装到 OpenClaw
+openclaw plugins install ./mycohive-claw
+
+# 重启 OpenClaw
+openclaw restart
+```
+
+### 更新
+
+```bash
+npm install mycohive-claw@latest
+openclaw restart
+```
+
+### 卸载
+
+```bash
+openclaw plugins uninstall mycohive-claw
+```
+
+### 目录结构
+
+```
+src/                     # TypeScript 源码
+├── index.ts             # 插件入口
+├── setup-entry.ts       # 安装入口
+├── router.ts            # 意图路由（含熔断器）
+├── intent-analyzer.ts   # LLM + 关键词双引擎意图分析
+├── context-tree.ts      # WAL 增量持久化 + CRC 校验
+├── event-bus.ts         # 事件总线（前缀树 + DLQ 重试）
+├── circuit-breaker.ts  # 熔断器
+├── tool-handlers.ts     # mycohive_* 工具处理
+├── tools/mycohive-tools.ts  # 工具注册
+├── workspace-loader.ts  # Agent workspace 加载器
+├── metrics.ts           # 指标收集
+├── rate-limiter.ts      # 限流
+├── result-cache.ts      # 结果缓存
+├── token-counter.ts     # Token 计数
+├── logger.ts            # 日志
+├── i18n.ts              # 国际化
+└── types.ts            # 类型定义
+
+workspaces/              # 24 个 Agent 工作区定义（SOUL.md + SKILL.md + RULES.md + CONFIG.md）
+```
+
+### License
+
+MIT

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Circuit Breaker 模块
+ * 版本: v4.0.0
+ *
+ * 熔断机制：连续失败超过阈值时暂停路由，防止雪崩
+ */
+export declare enum CircuitState {
+    CLOSED = "closed",// 正常，允许请求
+    OPEN = "open",// 熔断，拒绝请求
+    HALF_OPEN = "half_open"
+}
+export interface CircuitBreakerConfig {
+    failureThreshold: number;
+    successThreshold: number;
+    timeoutMs: number;
+    monitorIntervalMs: number;
+}
+export interface CircuitBreakerStats {
+    state: CircuitState;
+    failures: number;
+    successes: number;
+    lastFailureTime: number | null;
+    lastSuccessTime: number | null;
+    totalRequests: number;
+    totalFailures: number;
+}
+export declare class CircuitBreaker {
+    private config;
+    private state;
+    private failures;
+    private successes;
+    private lastFailureTime;
+    private lastSuccessTime;
+    private totalRequests;
+    private totalFailures;
+    private monitorTimer;
+    private logger;
+    constructor(name: string, config?: Partial<CircuitBreakerConfig>);
+    /**
+     * 执行请求，自动处理熔断
+     * 返回 { success: true, result } 或 { success: false, error, rejected: true }
+     */
+    execute<T>(operation: () => Promise<T>, fallback?: () => Promise<T>): Promise<{
+        success: boolean;
+        result?: T;
+        error?: Error;
+        rejected?: boolean;
+    }>;
+    /**
+     * 手动记录成功
+     */
+    recordSuccess(): void;
+    /**
+     * 手动记录失败
+     */
+    recordFailure(): void;
+    /**
+     * 获取当前状态
+     */
+    getState(): CircuitState;
+    /**
+     * 获取统计数据
+     */
+    getStats(): CircuitBreakerStats;
+    /**
+     * 重置熔断器
+     */
+    reset(): void;
+    /**
+     * 停止监控
+     */
+    dispose(): void;
+    private transitionToOpen;
+    private transitionToHalfOpen;
+    private transitionToClosed;
+    private checkStateTransition;
+    private startMonitor;
+}
+export declare function getCircuitBreaker(name: string, config?: CircuitBreakerConfig): CircuitBreaker;
+export declare function resetAllCircuitBreakers(): void;
+export declare function disposeCircuitBreakers(): void;
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,oBAAY,YAAY;IACtB,MAAM,WAAW,CAAM,UAAU;IACjC,IAAI,SAAS,CAAU,UAAU;IACjC,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AASD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,MAAM,CAAe;gBAEjB,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC;IAKhE;;;OAGG;IACG,OAAO,CAAC,CAAC,EACb,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAuC/E;;OAEG;IACH,aAAa,IAAI,IAAI;IAYrB;;OAEG;IACH,aAAa,IAAI,IAAI;IAerB;;OAEG;IACH,QAAQ,IAAI,YAAY;IAIxB;;OAEG;IACH,QAAQ,IAAI,mBAAmB;IAY/B;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,OAAO,IAAI,IAAI;IAOf,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,oBAAoB;IAM5B,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,YAAY;CAQrB;AAsCD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,oBAAoB,GAAG,cAAc,CAE7F;AAED,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/circuit-breaker.js

@@ -0,0 +1,214 @@
+/**
+ * Circuit Breaker 模块
+ * 版本: v4.0.0
+ *
+ * 熔断机制：连续失败超过阈值时暂停路由，防止雪崩
+ */
+import { getLogger } from "./logger.js";
+export var CircuitState;
+(function (CircuitState) {
+    CircuitState["CLOSED"] = "closed";
+    CircuitState["OPEN"] = "open";
+    CircuitState["HALF_OPEN"] = "half_open";
+})(CircuitState || (CircuitState = {}));
+const DEFAULT_CONFIG = {
+    failureThreshold: 5,
+    successThreshold: 3,
+    timeoutMs: 30000, // 30秒
+    monitorIntervalMs: 1000,
+};
+export class CircuitBreaker {
+    config;
+    state = CircuitState.CLOSED;
+    failures = 0;
+    successes = 0;
+    lastFailureTime = null;
+    lastSuccessTime = null;
+    totalRequests = 0;
+    totalFailures = 0;
+    monitorTimer = null;
+    logger = getLogger();
+    constructor(name, config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.startMonitor(name);
+    }
+    /**
+     * 执行请求，自动处理熔断
+     * 返回 { success: true, result } 或 { success: false, error, rejected: true }
+     */
+    async execute(operation, fallback) {
+        this.totalRequests++;
+        // 检查是否应该转换状态
+        this.checkStateTransition();
+        // OPEN 状态时拒绝请求
+        if (this.state === CircuitState.OPEN) {
+            this.logger.warn(`Circuit breaker OPEN, rejecting request`);
+            if (fallback) {
+                try {
+                    const result = await fallback();
+                    return { success: true, result };
+                }
+                catch (fbError) {
+                    return { success: false, error: fbError, rejected: true };
+                }
+            }
+            return {
+                success: false,
+                error: new Error("Circuit breaker is open"),
+                rejected: true,
+            };
+        }
+        // HALF_OPEN 状态时只允许一个请求
+        // （通过 success/failure 计数来控制）
+        try {
+            const result = await operation();
+            this.recordSuccess();
+            return { success: true, result };
+        }
+        catch (error) {
+            this.recordFailure();
+            return { success: false, error: error };
+        }
+    }
+    /**
+     * 手动记录成功
+     */
+    recordSuccess() {
+        this.successes++;
+        this.lastSuccessTime = Date.now();
+        this.totalRequests++;
+        if (this.state === CircuitState.HALF_OPEN) {
+            if (this.successes >= this.config.successThreshold) {
+                this.transitionToClosed();
+            }
+        }
+    }
+    /**
+     * 手动记录失败
+     */
+    recordFailure() {
+        this.failures++;
+        this.lastFailureTime = Date.now();
+        this.totalFailures++;
+        if (this.state === CircuitState.CLOSED) {
+            if (this.failures >= this.config.failureThreshold) {
+                this.transitionToOpen();
+            }
+        }
+        else if (this.state === CircuitState.HALF_OPEN) {
+            // 半开状态失败，立即重新打开
+            this.transitionToOpen();
+        }
+    }
+    /**
+     * 获取当前状态
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * 获取统计数据
+     */
+    getStats() {
+        return {
+            state: this.state,
+            failures: this.failures,
+            successes: this.successes,
+            lastFailureTime: this.lastFailureTime,
+            lastSuccessTime: this.lastSuccessTime,
+            totalRequests: this.totalRequests,
+            totalFailures: this.totalFailures,
+        };
+    }
+    /**
+     * 重置熔断器
+     */
+    reset() {
+        this.transitionToClosed();
+        this.totalRequests = 0;
+        this.totalFailures = 0;
+    }
+    /**
+     * 停止监控
+     */
+    dispose() {
+        if (this.monitorTimer) {
+            clearInterval(this.monitorTimer);
+            this.monitorTimer = null;
+        }
+    }
+    transitionToOpen() {
+        this.state = CircuitState.OPEN;
+        this.logger.warn(`Circuit breaker opened after ${this.failures} failures`);
+    }
+    transitionToHalfOpen() {
+        this.state = CircuitState.HALF_OPEN;
+        this.successes = 0;
+        this.logger.info(`Circuit breaker half-open`);
+    }
+    transitionToClosed() {
+        this.state = CircuitState.CLOSED;
+        this.failures = 0;
+        this.successes = 0;
+        this.logger.info(`Circuit breaker closed`);
+    }
+    checkStateTransition() {
+        if (this.state === CircuitState.OPEN) {
+            if (this.lastFailureTime) {
+                const elapsed = Date.now() - this.lastFailureTime;
+                if (elapsed >= this.config.timeoutMs) {
+                    this.transitionToHalfOpen();
+                }
+            }
+        }
+    }
+    startMonitor(name) {
+        // 定期记录状态
+        this.monitorTimer = setInterval(() => {
+            if (this.state !== CircuitState.CLOSED) {
+                this.logger.info(`Circuit breaker [${name}] state: ${this.state}`, this.getStats());
+            }
+        }, this.config.monitorIntervalMs * 10);
+    }
+}
+// 熔断器管理器
+class CircuitBreakerManager {
+    breakers = new Map();
+    logger = getLogger();
+    get(name, config) {
+        if (!this.breakers.has(name)) {
+            this.breakers.set(name, new CircuitBreaker(name, config));
+        }
+        return this.breakers.get(name);
+    }
+    getAll() {
+        return new Map(this.breakers);
+    }
+    reset(name) {
+        if (name) {
+            this.breakers.get(name)?.reset();
+        }
+        else {
+            for (const breaker of this.breakers.values()) {
+                breaker.reset();
+            }
+        }
+    }
+    dispose() {
+        for (const breaker of this.breakers.values()) {
+            breaker.dispose();
+        }
+        this.breakers.clear();
+    }
+}
+const globalManager = new CircuitBreakerManager();
+export function getCircuitBreaker(name, config) {
+    return globalManager.get(name, config);
+}
+export function resetAllCircuitBreakers() {
+    globalManager.reset();
+}
+export function disposeCircuitBreakers() {
+    globalManager.dispose();
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

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

package/dist/context-tree.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Context Tree 实现
+ * 版本: v4.0.0
+ *
+ * 全局共享上下文树，支持惰性加载，修复内存泄漏风险。
+ * 增量持久化：WAL（Write-Ahead Log）+ 定期 checkpoint + 批量写入
+ */
+import { ContextNode, NodeState, TaskStatus, ProgressStep } from "./types.js";
+export declare class ContextTree {
+    private storagePath;
+    private root;
+    private loadedNodes;
+    private dirtyNodes;
+    private wal;
+    private walFlushTimer;
+    private writeCountSinceCheckpoint;
+    private pendingWrites;
+    constructor(storagePath?: string);
+    private startWalFlushTimer;
+    private stopWalFlushTimer;
+    /**
+     * 刷新 WAL 到磁盘（增量写）
+     */
+    private flushWal;
+    /**
+     * 执行全量 checkpoint（合并 WAL 到主文件）
+     */
+    private performCheckpoint;
+    /**
+     * 从 checkpoint 恢复
+     */
+    private restoreFromCheckpoint;
+    /**
+     * 将待写入操作加入 pending WAL（用于批量合并）
+     */
+    private queueWalEntry;
+    /**
+     * 标记节点为脏
+     */
+    private markDirty;
+    /**
+     * 移除脏标记
+     */
+    private clearDirty;
+    private createRoot;
+    private load;
+    /**
+     * 应用 WAL 条目到内存树
+     */
+    private applyWalEntries;
+    private isMemoryMode;
+    /**
+     * 增量保存（仅保存脏节点，不保存整个树）
+     * 注意：为了兼容性，仍然提供全量保存方法 saveFull()
+     */
+    save(): void;
+    /**
+     * 全量保存（强制保存整个树，用于 shutdown 等场景）
+     */
+    saveFull(): void;
+    private findNode;
+    getNode(nodeId: string): ContextNode | null;
+    getTopic(topicId: string): ContextNode | null;
+    getActiveTopics(): ContextNode[];
+    getTasks(topicId: string): ContextNode[];
+    getArtifacts(taskId: string): ContextNode[];
+    getArtifact(artifactId: string): ContextNode | null;
+    getMessages(topicId: string): ContextNode[];
+    addTopic(topicId: string, label: string): ContextNode;
+    addTask(topicId: string, taskId: string, agent: string, taskDesc: string): ContextNode;
+    addArtifact(taskId: string, artifactId: string, artifactData: Record<string, unknown>): ContextNode;
+    addMessage(topicId: string, messageId: string, role: string, content: string, contextAnnotation?: Record<string, unknown>): ContextNode;
+    updateTopicState(topicId: string, state: NodeState, updates?: Partial<ContextNode>): void;
+    updateTaskState(taskId: string, state: NodeState, updates?: Partial<ContextNode> & {
+        task_status?: TaskStatus;
+    }): void;
+    addProgressStep(taskId: string, step: ProgressStep): void;
+    findTasksByState(state: NodeState): ContextNode[];
+    private findTasksRecursive;
+    findTopicsByState(state: NodeState): ContextNode[];
+    getStats(): {
+        topics: number;
+        tasks: number;
+        activeTopics: number;
+        activeTasks: number;
+    };
+    /**
+     * 销毁实例（清理定时器，强制刷盘）
+     */
+    dispose(): void;
+}
+export declare function getContextTree(storagePath?: string): ContextTree;
+export declare function resetContextTree(): void;
+//# sourceMappingURL=context-tree.d.ts.map

package/dist/context-tree.d.ts.map

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