foliko 1.1.93 → 2.0.1

package/src/{core/ui-extension-context.js → framework/ui-extension.js}

@@ -3,7 +3,7 @@
  * 允许插件扩展 TUI 界面
  */
 
-const { logger } = require('../utils/logger');
+const { logger } = require('../common/logger');
 
 class ExtensionUIContext {
   /**

package/src/index.js

@@ -1,25 +1,140 @@
 /**
  * Foliko Framework
  * 简约的插件化 Agent 框架
+ *
+ * Public API Facade
+ * 提供简洁的入口函数，覆盖 80% 使用场景
  */
 
-const { Framework, Agent, Plugin, PluginManager, ToolRegistry, EventEmitter } = require('./core');
+'use strict';
 
-const { SkillManagerPlugin, WorkflowPlugin } = require('./capabilities');
+// 加载工作目录 .env 配置（优先于系统环境变量）
+require('dotenv').config({ override: true });
 
-const { MCPExecutorPlugin } = require('./executors/mcp-executor');
+// ============================================================
+// Framework
+// ============================================================
+const { Framework } = require('./framework/framework');
+const { bootstrap, ready, destroy } = require('./framework/lifecycle');
 
-module.exports = {
-  // 核心
-  Framework,
-  Agent,
-  Plugin,
-  PluginManager,
-  ToolRegistry,
-  EventEmitter,
+// ============================================================
+// Agent
+// ============================================================
+const { createAgent, MainAgent, SubAgent, WorkerAgent } = require('./agent');
 
-  // 能力插件
-  SkillManagerPlugin,
-  WorkflowPlugin,
-  MCPExecutorPlugin,
+// ============================================================
+// Plugin
+// ============================================================
+const { Plugin, PluginManager } = require('./plugin');
+
+// ============================================================
+// Tool
+// ============================================================
+const { ToolRegistry, ToolExecutor } = require('./tool');
+
+// ============================================================
+// LLM
+// ============================================================
+const llm = require('./llm');
+
+// ============================================================
+// Common
+// ============================================================
+const { EventEmitter } = require('./common/events');
+const { Logger } = require('./common/logger');
+
+// ============================================================
+// Public API
+// ============================================================
+
+// --- 入门三件套 ---
+
+/** 加载 .foliko 配置并启动框架 */
+exports.bootstrap = async (config = {}) => {
+  const fw = new Framework(config);
+  await bootstrap(fw, config);
+  return fw;
+};
+
+/** 构造一个未启动的 Framework（支持链式 .use()） */
+exports.createApp = (config = {}) => {
+  const fw = new Framework(config);
+  fw.use = (plugin) => { fw.loadPlugin(plugin); return fw; };
+  return fw;
+};
+
+/** 显式构造 Agent */
+exports.createAgent = createAgent;
+
+// --- 框架生命周期 ---
+
+exports.ready = ready;
+exports.destroy = destroy;
+
+// --- 上下文管理 ---
+
+exports.runInSession = (framework, sessionId, options, fn) =>
+  framework.runInSession(sessionId, options, fn);
+
+exports.runInRequest = (framework, context, fn) =>
+  framework.runWithRequestContext(context, fn);
+
+// --- 快捷工具注册 ---
+
+exports.registerTool = (framework, toolDef) => {
+  framework.registerTool(toolDef);
+  return framework;
+};
+
+exports.use = (app, plugin) => {
+  if (app?.loadPlugin) return app.loadPlugin(plugin);
+  throw new Error('use() requires a Framework instance as first argument');
+};
+
+// --- 快捷插件工厂 ---
+
+exports.withAI = (config) => {
+  const AIPlugin = require('../plugins/core/ai');
+  return new AIPlugin(config);
+};
+
+exports.withShell = (config = {}) => {
+  const ShellPlugin = require('../plugins/executors/shell');
+  return new ShellPlugin(config);
 };
+
+exports.withPython = (config = {}) => {
+  const PythonPlugin = require('../plugins/executors/python');
+  return new PythonPlugin(config);
+};
+
+// --- 类型/常量 ---
+
+exports.z = require('zod');
+exports.LLM = llm;
+
+// --- 框架核心类（用于扩展） ---
+
+exports.Framework = Framework;
+exports.MainAgent = MainAgent;
+exports.SubAgent = SubAgent;
+exports.WorkerAgent = WorkerAgent;
+exports.ToolRegistry = ToolRegistry;
+exports.ToolExecutor = ToolExecutor;
+exports.Plugin = Plugin;
+exports.PluginManager = PluginManager;
+exports.EventEmitter = EventEmitter;
+exports.Logger = Logger;
+
+// --- 向后兼容（旧路径转发） ---
+
+const { SkillManagerPlugin, Skill, SkillMetadata } = require('../plugins/core/skill-manager');
+const { WorkflowPlugin, WorkflowEngine, StepExecutor } = require('../plugins/core/workflow');
+exports.SkillManagerPlugin = SkillManagerPlugin;
+exports.Skill = Skill;
+exports.SkillMetadata = SkillMetadata;
+exports.WorkflowPlugin = WorkflowPlugin;
+exports.WorkflowEngine = WorkflowEngine;
+exports.StepExecutor = StepExecutor;
+exports.Agent = MainAgent;
+exports.MCPExecutorPlugin = require('./executors/mcp-executor');

package/src/llm/index.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const {
+  createAI, createModel, getAvailableProviders,
+  DEFAULT_PROVIDERS, isThinkingModel,
+  LLMProvider, ProviderRegistry, getProviderRegistry,
+} = require('./provider');
+const { TokenCounter, encode, estimateTokens, estimateContextTokens, shouldCompact } = require('./tokens');
+
+module.exports = {
+  // Provider
+  LLMProvider,
+  ProviderRegistry,
+  getProviderRegistry,
+  createAI,
+  createModel,
+  getAvailableProviders,
+  DEFAULT_PROVIDERS,
+  isThinkingModel,
+  // Token
+  TokenCounter,
+  encode,
+  estimateTokens,
+  estimateContextTokens,
+  shouldCompact,
+};

package/src/llm/provider.js

@@ -0,0 +1,212 @@
+'use strict';
+
+/**
+ * LLM Provider 系统
+ * 统一管理 Provider 注册、模型创建、thinking mode 判断
+ * 合并自 provider.js + registry.js
+ * 目标 ~300 行
+ */
+
+const { createOpenAICompatible } = require('@ai-sdk/openai-compatible');
+
+// ==================== Provider 默认配置 ====================
+
+const DEFAULT_PROVIDERS = {
+  openai: {
+    name: 'OpenAI',
+    baseURL: 'https://api.openai.com/v1',
+    defaultModel: 'gpt-4o',
+  },
+  ollama: {
+    name: 'Ollama',
+    baseURL: 'http://localhost:11434/v1',
+    defaultModel: 'llama3',
+  },
+  lmstudio: {
+    name: 'LM Studio',
+    baseURL: 'http://localhost:1234/v1',
+    defaultModel: 'local-model',
+  },
+  deepseek: {
+    name: 'DeepSeek',
+    baseURL: 'https://api.deepseek.com/v1',
+    defaultModel: 'deepseek-chat',
+  },
+  anthropic: {
+    name: 'Anthropic',
+    baseURL: 'https://api.anthropic.com/v1',
+    defaultModel: 'claude-sonnet-4-20250514',
+  },
+  minimax: {
+    name: 'MiniMax',
+    baseURL: 'https://api.minimaxi.com/v1',
+    defaultModel: 'MiniMax-M2.7',
+  },
+};
+
+const THINKING_MODELS = [
+  'deepseek-v4-pro',
+  'deepseek-v4-flash',
+  'deepseek-reasoner',
+];
+
+function isThinkingModel(model) {
+  if (!model) return false;
+  const lower = model.toLowerCase();
+  return THINKING_MODELS.some(tm => lower.includes(tm) || lower === tm);
+}
+
+// ==================== LLMProvider ====================
+
+/**
+ * LLMProvider — Provider 配置封装
+ * 将 provider/model/apiKey/baseURL 配置封装为对象，提供 createModel() 工厂
+ */
+class LLMProvider {
+  constructor(config = {}) {
+    this.provider = config.provider || 'deepseek';
+    this.model = config.model || 'deepseek-chat';
+    this.apiKey = config.apiKey;
+    this.baseURL = config.baseURL;
+    this.options = { ...config.options };
+  }
+
+  /** 创建 AI SDK model 实例 */
+  createModel() {
+    return _createAIClient(this.provider, this.model, this.apiKey, this.baseURL)(this.model);
+  }
+
+  /** 当前模型是否 thinking mode */
+  isThinking() { return isThinkingModel(this.model); }
+
+  getConfig() {
+    return {
+      provider: this.provider,
+      model: this.model,
+      apiKey: this.apiKey,
+      baseURL: this.baseURL,
+      options: { ...this.options },
+    };
+  }
+}
+
+// ==================== ProviderRegistry ====================
+
+class ProviderRegistry {
+  constructor() {
+    this._providers = new Map();
+    this._models = new Map();
+  }
+
+  registerProvider(name, config) {
+    this._providers.set(name, {
+      name: config.name || name,
+      baseURL: config.baseURL,
+      apiKey: config.apiKey || '',
+      defaultModel: config.defaultModel || '',
+      headers: config.headers || {},
+    });
+    if (config.defaultModel) this.registerModel(config.defaultModel, name);
+    return this;
+  }
+
+  registerModel(modelId, provider, options = {}) {
+    this._models.set(modelId, { provider, ...options });
+    return this;
+  }
+
+  getProvider(name) { return this._providers.get(name); }
+  getModel(modelId) { return this._models.get(modelId); }
+  getProviderNames() { return Array.from(this._providers.keys()); }
+  hasProvider(name) { return this._providers.has(name); }
+
+  /** 创建 AI SDK model 实例（自动 fallback 到注册的默认值） */
+  createClient(providerName, model, apiKey, baseURL) {
+    const provider = this._providers.get(providerName);
+    if (!provider) throw new Error(`Provider '${providerName}' not registered.`);
+    const finalApiKey = apiKey || provider.apiKey;
+    const finalBaseURL = baseURL || provider.baseURL;
+    const finalModel = model || provider.defaultModel;
+    if (!finalApiKey) throw new Error(`No API key for provider '${providerName}'`);
+    return _createAIClient(providerName, finalModel, finalApiKey, finalBaseURL)(finalModel);
+  }
+
+  unregisterProvider(name) {
+    this._providers.delete(name);
+    for (const [mid, mc] of this._models) {
+      if (mc.provider === name) this._models.delete(mid);
+    }
+    return this;
+  }
+}
+
+// ==================== 模块级单例 ====================
+
+const _registry = new ProviderRegistry();
+
+function getProviderRegistry() { return _registry; }
+
+function _registerDefaultProviders() {
+  for (const [key, cfg] of Object.entries(DEFAULT_PROVIDERS)) {
+    _registry.registerProvider(key, {
+      name: cfg.name, baseURL: cfg.baseURL, defaultModel: cfg.defaultModel,
+    });
+  }
+}
+_registerDefaultProviders();
+
+// ==================== 内部 AI SDK 客户端工厂 ====================
+
+function _createAIClient(provider, model, apiKey, baseURL) {
+  const providerName = (provider || 'deepseek').toLowerCase();
+  const pcfg = DEFAULT_PROVIDERS[providerName];
+
+  if (pcfg) {
+    const streamOptions = { includeUsage: true };
+    if (providerName === 'deepseek') streamOptions.includeReasoningContent = true;
+    return createOpenAICompatible({
+      name: pcfg.name,
+      baseURL: baseURL || pcfg.baseURL,
+      apiKey: apiKey || 'dummy-key',
+      headers: provider === 'anthropic' ? { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' } : undefined,
+      models: { default: { id: model || 'deepseek-chat', streamOptions } },
+    });
+  }
+
+  return createOpenAICompatible({
+    name: providerName || 'Custom',
+    baseURL,
+    apiKey: apiKey || 'dummy-key',
+    models: { default: { id: model || 'gpt-4' } },
+  });
+}
+
+// ==================== 向后兼容 API ====================
+
+function createAI(config) {
+  return _createAIClient(config.provider, config.model, config.apiKey, config.baseURL);
+}
+
+function createModel(model, client) { return client(model); }
+
+function getAvailableProviders() {
+  return Object.entries(DEFAULT_PROVIDERS).map(([k, v]) => ({ id: k, name: v.name, baseURL: v.baseURL }));
+}
+
+function registerProvider(name, config) { _registry.registerProvider(name, config); }
+
+module.exports = {
+  // Class API
+  LLMProvider,
+  ProviderRegistry,
+  getProviderRegistry,
+  // 常量 & 工具函数
+  DEFAULT_PROVIDERS,
+  THINKING_MODELS,
+  isThinkingModel,
+  // 向后兼容
+  createAI,
+  createModel,
+  getAvailableProviders,
+  registerProvider,
+};

package/src/llm/registry.js

@@ -0,0 +1,11 @@
+'use strict';
+
+/**
+ * ProviderRegistry — 向后兼容转发
+ * 实际实现在 provider.js
+ * @deprecated 直接引用 src/llm/provider
+ */
+
+const { ProviderRegistry, getProviderRegistry, registerProvider } = require('./provider');
+
+module.exports = { ProviderRegistry, getProviderRegistry, registerProvider };

package/src/{core/token-counter.js → llm/tokens.js}

@@ -1,33 +1,22 @@
+'use strict';
+
 /**
  * TokenCounter - Token 计算工具
  * Ported from pi's compaction/compaction.ts with enhancements
  */
 
-/**
- * 简单的中英文混合 tokenizer
- * 粗略估计：中文每个字符 2 字节，英文每个单词约 1.5 字节
- * @param {string} text - 文本
- * @param {number} bytesPerToken - 每 token 字节数，默认 4
- * @returns {number} token 数量
- */
 function encode(text, bytesPerToken = 4) {
   if (!text) return 0;
   const bytes = Buffer.byteLength(String(text), 'utf8');
   return Math.ceil(bytes / bytesPerToken);
 }
 
-/**
- * 计算 JSON 字符串的 token 数量
- */
 function encodeForJSON(text) {
   if (!text) return 0;
   const encoded = encode(text);
   return encoded + Math.ceil(Buffer.byteLength(JSON.stringify(text), 'utf8') / 100);
 }
 
-/**
- * Safe JSON stringify that handles unserializable values
- */
 function safeJsonStringify(value) {
   try {
     return JSON.stringify(value) ?? 'undefined';
@@ -36,10 +25,6 @@ function safeJsonStringify(value) {
   }
 }
 
-/**
- * Estimate token count for one message using a conservative character heuristic
- * Ported from pi
- */
 function estimateTokens(message) {
   let chars = 0;
 
@@ -100,16 +85,10 @@ function estimateTokens(message) {
   return 0;
 }
 
-/**
- * Calculate total context tokens from provider usage
- */
 function calculateContextTokens(usage) {
   return usage.totalTokens || (usage.input || 0) + (usage.output || 0) + (usage.cacheRead || 0) + (usage.cacheWrite || 0);
 }
 
-/**
- * Get assistant usage from message
- */
 function getAssistantUsage(msg) {
   if (msg.role === 'assistant' && msg.usage) {
     if (msg.stopReason !== 'aborted' && msg.stopReason !== 'error' && msg.usage) {
@@ -119,9 +98,6 @@ function getAssistantUsage(msg) {
   return undefined;
 }
 
-/**
- * Return usage from the last successful assistant message in session entries
- */
 function getLastAssistantUsage(entries) {
   for (let i = entries.length - 1; i >= 0; i--) {
     const entry = entries[i];
@@ -133,9 +109,6 @@ function getLastAssistantUsage(entries) {
   return undefined;
 }
 
-/**
- * Get last assistant usage info from messages
- */
 function getLastAssistantUsageInfo(messages) {
   for (let i = messages.length - 1; i >= 0; i--) {
     const usage = getAssistantUsage(messages[i]);
@@ -144,9 +117,6 @@ function getLastAssistantUsageInfo(messages) {
   return undefined;
 }
 
-/**
- * Estimate context tokens for messages using provider usage when available
- */
 function estimateContextTokens(messages) {
   const usageInfo = getLastAssistantUsageInfo(messages);
 
@@ -177,9 +147,6 @@ function estimateContextTokens(messages) {
   };
 }
 
-/**
- * Return whether context usage exceeds the configured compaction threshold
- */
 function shouldCompact(contextTokens, contextWindow, settings) {
   if (!settings.enabled) return false;
   return contextTokens > contextWindow - settings.reserveTokens;
@@ -305,5 +272,5 @@ module.exports = {
   getLastAssistantUsage,
   estimateContextTokens,
   shouldCompact,
-  safeJsonStringify
-};
+  safeJsonStringify,
+};