foliko 2.0.2 → 2.0.3

package/src/framework/loader.js

@@ -6,60 +6,6 @@
  */
 
 const path = require('path');
-const fs = require('fs');
-
-/**
- * Load agent config from .foliko/ directory
- * @param {Framework} framework
- * @param {string} agentDir
- * @returns {Object}
- */
-function loadAgentConfig(framework, agentDir = '.foliko') {
-  const cwd = framework.getCwd ? framework.getCwd() : process.cwd();
-  const folikoDir = path.resolve(cwd, agentDir);
-  const config = {
-    plugins: [],
-    skills: [],
-    ai: {},
-  };
-
-  // Load plugins.json
-  const pluginsPath = path.join(folikoDir, 'plugins.json');
-  if (fs.existsSync(pluginsPath)) {
-    try {
-      const pluginsConfig = JSON.parse(fs.readFileSync(pluginsPath, 'utf-8'));
-      if (Array.isArray(pluginsConfig)) {
-        config.plugins = pluginsConfig;
-      } else if (pluginsConfig.plugins) {
-        config.plugins = pluginsConfig.plugins;
-      }
-      if (pluginsConfig.ai) config.ai = { ...config.ai, ...pluginsConfig.ai };
-      if (pluginsConfig.skillsDirs) config.skillsDirs = pluginsConfig.skillsDirs;
-    } catch (err) {
-      framework.logger?.warn?.('Failed to load plugins.json:', err.message);
-    }
-  }
-
-  // Load agent configs from agents/ directory
-  const agentsDir = path.join(folikoDir, 'agents');
-  if (fs.existsSync(agentsDir)) {
-    try {
-      const files = fs.readdirSync(agentsDir).filter(f => f.endsWith('.json'));
-      config.agentFiles = files.map(f => path.join(agentsDir, f));
-    } catch { /* ignore */ }
-  }
-
-  // Load skills config
-  const skillsDir = path.join(folikoDir, 'skills');
-  if (fs.existsSync(skillsDir)) {
-    try {
-      config.skillsDirs = config.skillsDirs || [];
-      config.skillsDirs.push(skillsDir);
-    } catch { /* ignore */ }
-  }
-
-  return config;
-}
 
 /**
  * Load default plugins based on config
@@ -75,4 +21,4 @@ async function loadDefaultPlugins(framework, config = {}) {
   return framework.pluginManager.getAll().map(p => p.name);
 }
 
-module.exports = { loadAgentConfig, loadDefaultPlugins };
+module.exports = { loadDefaultPlugins };

package/src/index.js

@@ -15,12 +15,12 @@ require('dotenv').config({ override: true });
 // Framework
 // ============================================================
 const { Framework } = require('./framework/framework');
-const { bootstrap, ready, destroy } = require('./framework/lifecycle');
+const { bootstrap, ready, destroy, setCwd, rescanProject, reloadAll } = require('./framework/lifecycle');
 
 // ============================================================
 // Agent
 // ============================================================
-const { createAgent, MainAgent, SubAgent, WorkerAgent } = require('./agent');
+const { createAgent, MainAgent, SubAgent, WorkerAgent, PromptRegistry } = require('./agent');
 
 // ============================================================
 // Plugin
@@ -70,6 +70,9 @@ exports.createAgent = createAgent;
 
 exports.ready = ready;
 exports.destroy = destroy;
+exports.setCwd = setCwd;
+exports.rescanProject = rescanProject;
+exports.reloadAll = reloadAll;
 
 // --- 上下文管理 ---
 
@@ -113,6 +116,11 @@ exports.withPython = (config = {}) => {
 exports.z = require('zod');
 exports.LLM = llm;
 
+// --- 常量 ---
+exports.PROMPT_SLOT = require('./common/constants').PROMPT_SLOT;
+exports.PROMPT_PRIORITY = require('./common/constants').PROMPT_PRIORITY;
+exports.PROMPT_PRIORITY_TO_SLOT = require('./common/constants').PROMPT_PRIORITY_TO_SLOT;
+
 // --- 框架核心类（用于扩展） ---
 
 exports.Framework = Framework;
@@ -123,6 +131,7 @@ exports.ToolRegistry = ToolRegistry;
 exports.ToolExecutor = ToolExecutor;
 exports.Plugin = Plugin;
 exports.PluginManager = PluginManager;
+exports.PromptRegistry = PromptRegistry;
 exports.EventEmitter = EventEmitter;
 exports.Logger = Logger;
 

package/src/plugin/base.js

@@ -20,10 +20,30 @@ class Plugin {
 
   _framework = null;
   _subAgents = [];
-  _promptParts = [];
-  _deferredPromptParts = null;
   tools = {};
 
+  /**
+   * 声明式 prompt parts（推荐使用，替代 start() 中的 registerPromptPart 调用）
+   *
+   * 用法：
+   *   prompts = [
+   *     {
+   *       name: 'my-part',
+   *       slot: 'BEHAVIOR',       // 可选，PROMPT_SLOT 中的一个；默认 CUSTOM
+   *       order: 50,              // 可选，覆盖 slot 默认 order
+   *       description: '描述',     // 可选
+   *       provider() {            // 'this' 绑定到 plugin 实例；不要用箭头函数
+   *         return this._buildSomething();
+   *       },
+   *     },
+   *   ];
+   *
+   * 生命周期：
+   *   - Plugin.start() 时自动注册到 framework.prompts
+   *   - Plugin.uninstall() / Plugin.reload() 时自动清理（clearOwner(this.name)）
+   */
+  prompts = [];
+
   install(framework) {
     this._framework = framework;
     return this;
@@ -56,9 +76,51 @@ class Plugin {
 
   start(framework) {
     this._autoRegisterSubAgents();
+    this._autoRegisterPrompts();
     return this;
   }
 
+  /**
+   * 自动注册 this.prompts 声明的所有 part 到 framework.prompts
+   * - 失败一个不影响其他
+   * - 'this' 在 provider 中绑定到 plugin 实例（必须用普通 function，箭头函数的 this 是词法的）
+   */
+  _autoRegisterPrompts() {
+    const reg = this._framework?.prompts;
+    if (!reg) return;
+    if (!Array.isArray(this.prompts) || this.prompts.length === 0) return;
+
+    for (const entry of this.prompts) {
+      if (!entry || !entry.name || typeof entry.provider !== 'function') {
+        log.warn(`[${this.name}] Invalid prompt entry: missing name or provider`);
+        continue;
+      }
+      try {
+        // bind 让 provider 中的 this 指向 plugin 实例
+        const boundProvider = entry.provider.bind(this);
+        reg.register(this.name, entry.name, boundProvider, {
+          slot: entry.slot,
+          order: entry.order,
+          description: entry.description,
+        });
+      } catch (err) {
+        log.error(`[${this.name}] Failed to register prompt part "${entry.name}":`, err.message);
+      }
+    }
+  }
+
+  /**
+   * 清理当前 plugin 在 framework.prompts 中注册的所有 part
+   */
+  _cleanupPrompts() {
+    const reg = this._framework?.prompts;
+    if (!reg) return;
+    const removed = reg.clearOwner(this.name);
+    if (removed > 0) {
+      log.debug(`[${this.name}] cleared ${removed} prompt part(s)`);
+    }
+  }
+
   _autoRegisterSubAgents() {
     const agentsToRegister = this._deferredSubAgents || this.agents;
     if (!agentsToRegister || !Array.isArray(agentsToRegister) || agentsToRegister.length === 0) {
@@ -139,15 +201,10 @@ class Plugin {
   reload(framework) {
     this._framework = framework;
     this._deferredSubAgents = null;
-    this._deferredPromptParts = null;
 
-    for (const part of this._promptParts) {
-      try {
-        framework._mainAgent?.registerPromptPart(part.name, part.priority, part.provider);
-      } catch (err) {
-        log.error(` Failed to re-register prompt part ${part.name}:`, err.message);
-      }
-    }
+    // 先清理旧的，再重新注册 declarative prompts
+    this._cleanupPrompts();
+    this._autoRegisterPrompts();
 
     this._autoRegisterSubAgents();
   }
@@ -157,15 +214,8 @@ class Plugin {
   }
 
   uninstall(framework) {
-    for (const part of this._promptParts) {
-      try {
-        framework._mainAgent?.unregisterPromptPart(part.name);
-      } catch (err) {
-        // ignore
-      }
-    }
-    this._promptParts = [];
-    this._deferredPromptParts = null;
+    // 清理 framework.prompts 中该插件注册的所有 part
+    this._cleanupPrompts();
 
     for (const plugin of this._subAgents) {
       try {
@@ -178,42 +228,6 @@ class Plugin {
     this._framework = null;
   }
 
-  registerPromptPart(name, priority = 100, provider) {
-    if (!this._framework) return;
-
-    this._promptParts.push({ name, priority, provider });
-
-    const mainAgent = this._framework.getMainAgent();
-    if (mainAgent) {
-      mainAgent.registerPromptPart(name, priority, provider);
-      this._framework.syncPromptPartsToSubagents();
-      return;
-    }
-
-    if (!this._deferredPromptParts) {
-      this._deferredPromptParts = [];
-    }
-    this._deferredPromptParts.push({ name, priority, provider });
-
-    const alreadyListening = this._framework._events?.['framework:ready']?.length > 0;
-    this._framework.once('framework:ready', () => {
-      setTimeout(() => {
-        if (this._deferredPromptParts) {
-          for (const part of this._deferredPromptParts) {
-            try {
-              const mainAgent = this._framework.getMainAgent();
-              mainAgent?.registerPromptPart(part.name, part.priority, part.provider);
-            } catch (err) {
-              log.error(` Failed to register prompt part ${part.name}:`, err.message);
-            }
-          }
-          this._deferredPromptParts = null;
-          this._framework.syncPromptPartsToSubagents();
-        }
-      }, 100);
-    });
-  }
-
   getInfo() {
     return {
       name: this.name,

package/src/plugin/loader.js

@@ -5,66 +5,10 @@
  */
 
 const path = require('path');
-const fs = require('fs');
+const { resolvePluginPath, scanPluginNames } = require('../utils/plugin-helpers');
 const { logger } = require('../common/logger');
 const log = logger.child('plugin-loader');
 
-/**
- * Resolve plugin path from name
- * @param {string} pluginName
- * @param {Object} options
- * @returns {string|null}
- */
-function resolvePluginPath(pluginName, options = {}) {
-  const { pluginDirs = [], searchPaths = [] } = options;
-
-  // Check explicit paths first
-  const allPaths = [...pluginDirs, ...searchPaths];
-  for (const dir of allPaths) {
-    const fullPath = path.resolve(dir, pluginName);
-    if (fs.existsSync(fullPath)) {
-      return fullPath;
-    }
-    const indexJs = path.join(fullPath, 'index.js');
-    if (fs.existsSync(indexJs)) {
-      return fullPath;
-    }
-  }
-
-  // Check node_modules
-  try {
-    const resolved = require.resolve(pluginName);
-    return resolved;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Scan directory for plugin names
- * @param {string} dir
- * @returns {string[]}
- */
-function scanPluginNames(dir) {
-  if (!fs.existsSync(dir)) return [];
-
-  try {
-    return fs.readdirSync(dir)
-      .filter(f => {
-        const fullPath = path.join(dir, f);
-        const stat = fs.statSync(fullPath);
-        if (stat.isDirectory()) {
-          return fs.existsSync(path.join(fullPath, 'index.js'));
-        }
-        return f.endsWith('.js');
-      })
-      .map(f => f.replace(/\.js$/, ''));
-  } catch (err) {
-    log.warn(`Failed to scan plugin directory ${dir}: ${err.message}`);
-    return [];
-  }
-}
-
 /**
  * Load a plugin from a file path
  * @param {string} pluginPath

package/src/session/entry.js

@@ -4,6 +4,7 @@
  */
 
 const { randomUUID } = require('crypto');
+const { generateEntryId } = require('../common/id');
 
 /**
  * Entry types for session tree entries
@@ -21,17 +22,6 @@ const EntryTypes = {
   LEAF: 'leaf'
 };
 
-/**
- * Generate a unique short ID (8 hex chars, collision-checked)
- */
-function generateEntryId(byId) {
-  for (let i = 0; i < 100; i++) {
-    const id = randomUUID().slice(0, 8);
-    if (!byId.has(id)) return id;
-  }
-  return randomUUID();
-}
-
 /**
  * Generate UUID v7 for session IDs
  */

package/src/storage/manager.js

@@ -5,18 +5,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { randomUUID } = require('crypto');
-
-/**
- * Generate unique entry ID
- */
-function generateEntryId(existingIds) {
-  for (let i = 0; i < 100; i++) {
-    const id = randomUUID().slice(0, 8);
-    if (!existingIds.has(id)) return id;
-  }
-  return randomUUID();
-}
+const { generateEntryId } = require('../common/id');
 
 class StorageEntry {
   constructor(key, value, timestamp) {

package/src/tool/executor.js

@@ -71,7 +71,8 @@ class ToolExecutor extends EventEmitter {
   }
 
   validateToolCalls(messages) {
-    return validateToolCalls(messages);
+    const registeredTools = new Set(this._tools.keys());
+    return validateToolCalls(messages, { availableTools: registeredTools });
   }
 
   getStats() {

package/src/tool/router.js

@@ -23,7 +23,7 @@ const INTENT_PATTERNS = {
       '写代码', '开发', '编程', '创建插件', '编写函数',
       'code', 'develop', 'plugin', '编程',
     ],
-    tools: ['loadSkill', 'read_file', 'write_file', 'execute_command', 'shell'],
+    tools: ['skill_load', 'read_file', 'write_file', 'execute_command', 'shell_exec'],
   },
   system_info: {
     keywords: [
@@ -34,19 +34,19 @@ const INTENT_PATTERNS = {
   },
   data_analysis: {
     keywords: ['分析', '数据', '统计', '查询', 'analyze', 'data', 'statistics', 'query'],
-    tools: ['execute_command', 'python', 'search_file'],
+    tools: ['execute_command', 'py_execute', 'search_file'],
   },
   plugin_management: {
     keywords: ['插件', '重载', '加载插件', 'plugin', 'reload', 'load plugin'],
-    tools: ['reload_plugins', 'list_plugins', 'loadSkill'],
+    tools: ['reload_plugins', 'list_plugins', 'skill_load'],
   },
   shell_command: {
     keywords: ['命令', '终端', 'shell', '执行', 'command', 'terminal', 'bash', 'cmd'],
-    tools: ['shell', 'powershell', 'execute_command'],
+    tools: ['shell_exec', 'powershell', 'execute_command'],
   },
   skill_usage: {
     keywords: ['技能', 'skill', '使用技能', '加载技能'],
-    tools: ['loadSkill'],
+    tools: ['skill_load'],
   },
   scheduling: {
     keywords: [

package/src/utils/data-splitter.js

@@ -168,13 +168,14 @@ class DataSplitter {
     const processChunk = async (chunk) => {
       const chunkIndex = chunk.index;
 
-      // 为当前块创建子 Agent
+      // 为当前块创建子 Agent（隐藏，不在指令系统中显示）
       const subagent = this.framework.createSubAgent({
         name: `${agentName}-chunk-${chunkIndex}`,
         role: agentRole,
         systemPrompt: `你是${agentRole}，负责处理大数据中的第 ${chunkIndex + 1}/${totalChunks} 块。`,
         maxRetries: this.maxRetries,
         disableTools: true, // 分拆处理只做文本分析，不需要额外工具
+        hidden: true, // 隐藏子Agent，不在指令系统中显示
       });
 
       try {

package/src/utils/index.js

@@ -47,6 +47,80 @@ const {
   combineBoundaries,
 } = require('../common/errors');
 
+/**
+ * 解析 YAML frontmatter
+ * @param {string} content
+ * @returns {Object|null}
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+
+  const frontmatter = {};
+  const lines = match[1].split('\n');
+  let currentKey = null;
+
+  for (const line of lines) {
+    // 处理 metadata 嵌套
+    if (currentKey === 'metadata') {
+      if (line.match(/^ {2}[a-zA-Z]/)) {
+        const colonIndex = line.indexOf(':');
+        if (colonIndex > 0) {
+          const key = line.substring(2, colonIndex).trim();
+          const value = line
+            .substring(colonIndex + 1)
+            .trim()
+            .replace(/^["']|["']$/g, '');
+          frontmatter[currentKey][key] = value;
+          continue;
+        }
+      } else if (line.match(/^[a-zA-Z]/)) {
+        currentKey = null;
+        continue;
+      }
+    }
+
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = line.substring(0, colonIndex).trim();
+    let value = line.substring(colonIndex + 1).trim();
+
+    // 移除引号
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    if (key === 'metadata') {
+      currentKey = 'metadata';
+      frontmatter.metadata = {};
+    } else if (key === 'allowed-tools' || key === 'skills' || key === 'tools' || key === 'tags') {
+      // 去除首尾空白和方括号
+      value = value.trim().replace(/^\[|\]$/g, '');
+      frontmatter[key] = value
+        .split(',')
+        .map((v) => v.trim().replace(/^["']|["']$/g, ''))
+        .filter(Boolean);
+    } else {
+      frontmatter[key] = value;
+    }
+  }
+
+  return frontmatter;
+}
+
+/**
+ * 移除 frontmatter，只保留正文内容
+ * @param {string} content
+ * @returns {string}
+ */
+function stripFrontmatter(content) {
+  return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+}
+
 /**
  * 清理 LLM 回复中的思考标记
  * @param {string} text
@@ -530,6 +604,8 @@ module.exports = {
   // 工具函数
   cleanResponse,
   safeJsonParse,
+  parseFrontmatter,
+  stripFrontmatter,
   deepClone,
   debounce,
   throttle,
@@ -539,4 +615,78 @@ module.exports = {
 
   // Edit/Diff
   editDiff: require('../common/diff'),
+
+  // 插件发布/安装相关
+  DEFAULT_REPO: 'https://github.com/chnak/foliko-plugins.git',
+
+  IGNORE_PATTERNS: [
+    'node_modules',
+    '.git',
+    '.env',
+    '.DS_Store',
+    'Thumbs.db',
+    '*.log',
+    '*.lock',
+    '*.bak',
+    '.claude',
+    '.foliko',
+    'examples',
+    'dist',
+    'build',
+    'coverage',
+    'tests',
+    '__tests__',
+    '*.test.js',
+    '*.spec.js',
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+  ],
+
+  shouldIgnore(name) {
+    return this.IGNORE_PATTERNS.some((pattern) => {
+      if (pattern.startsWith('*.')) {
+        return name.endsWith(pattern.slice(1));
+      }
+      return name === pattern;
+    });
+  },
+
+  copyDirRecursive(src, dest) {
+    const fs = require('fs');
+    if (!fs.existsSync(src)) return;
+    fs.mkdirSync(dest, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      if (this.shouldIgnore(entry.name)) continue;
+      if (entry.isDirectory()) {
+        this.copyDirRecursive(srcPath, destPath);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  },
+
+  parseGitUrl(url) {
+    const patterns = [
+      /^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/,
+      /^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/,
+    ];
+    for (const pattern of patterns) {
+      const match = url.match(pattern);
+      if (match) return { owner: match[1], repo: match[2] };
+    }
+    return null;
+  },
+
+  gitCommand(args, cwd) {
+    const { execSync } = require('child_process');
+    try {
+      return execSync(`git ${args}`, { cwd, encoding: 'utf-8', stdio: 'pipe' });
+    } catch (err) {
+      return err.stdout || err.stderr || '';
+    }
+  },
 };

package/src/utils/message-validator.js

@@ -53,24 +53,28 @@ function validateMessagesPairing(messages, options = {}) {
   let removedToolResultCount = 0;
 
   for (const msg of messages) {
-    if (msg.role !== 'tool' || !Array.isArray(msg.content)) continue;
+    if (msg.role !== 'tool') continue;
 
-    const originalLength = msg.content.length;
-    msg.content = msg.content.filter((item) => {
-      if (
-        item &&
-        (item.type === 'tool-result' || item.type === 'tool_result') &&
-        item.toolCallId &&
-        !validToolCallIds.has(item.toolCallId)
-      ) {
-        removedToolResultCount++;
-        return false;
+    if (Array.isArray(msg.content)) {
+      const originalLength = msg.content.length;
+      msg.content = msg.content.filter((item) => {
+        if (
+          item &&
+          (item.type === 'tool-result' || item.type === 'tool_result') &&
+          item.toolCallId &&
+          !validToolCallIds.has(item.toolCallId)
+        ) {
+          removedToolResultCount++;
+          return false;
+        }
+        return true;
+      });
+      // content 全被删除了，标记整个消息待删除
+      if (msg.content.length === 0 && originalLength > 0) {
+        msg._orphaned = true;
       }
-      return true;
-    });
-
-    // content 全被删除了，标记整个消息待删除
-    if (msg.content.length === 0 && originalLength > 0) {
+    } else if (msg.tool_call_id && !validToolCallIds.has(msg.tool_call_id)) {
+      // OpenAI 兼容格式：整条消息无对应 tool_calls，标记为 orphaned
       msg._orphaned = true;
     }
   }
@@ -280,4 +284,4 @@ module.exports = {
   validateToolCalls,
   validateAll,
   filterPairedMessages,
-};
+};