foliko 1.1.93 → 2.0.1

package/docs/architecture.md

@@ -0,0 +1,131 @@
+# Architecture
+
+Foliko — 简约的插件化 Agent 框架。
+
+## 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Foliko Framework                         │
+├─────────────────────────────────────────────────────────────┤
+│  Framework (Container Layer)                                │
+│  ├── pluginManager      — 插件注册/加载/卸载/热重载         │
+│  ├── toolRegistry       — 工具注册/执行/Zod 校验            │
+│  ├── eventEmitter       — 内建事件总线                      │
+│  └── contextManager     — 三层上下文管理                    │
+├─────────────────────────────────────────────────────────────┤
+│  Agent (Dialogue Layer)                                     │
+│  ├── MainAgent          — 主对话代理                        │
+│  ├── SubAgent           — 子代理（隔离执行）                │
+│  ├── WorkerAgent        — 工作代理（协处理器管理）          │
+│  ├── AgentChatHandler   — LLM 通信 + 工具调用循环            │
+│  └── SystemPromptBuilder— 动态系统提示词构建                │
+├─────────────────────────────────────────────────────────────┤
+│  LLM Layer                                                  │
+│  ├── LLMProvider        — AI 供应商封装                     │
+│  ├── ProviderRegistry   — 供应商配置中心                    │
+│  └── Vercel AI SDK      — 底层流式/工具调用                 │
+├─────────────────────────────────────────────────────────────┤
+│  Plugin System                                              │
+│  ├── core/ (ai, storage, skill-manager, etc.)               │
+│  ├── executors/ (shell, python, extension)                  │
+│  ├── messaging/ (email, telegram, weixin, etc.)             │
+│  ├── io/ (file-system)                                      │
+│  └── memory, trading, ambient, install ...                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 三层上下文
+
+```
+┌─────────────────────────────────────────────────┐
+│              Request Context                     │
+│  requestId, traceId, timeout, startTime        │
+│  通过 runWithRequestContext() 设置              │
+└─────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────┐
+│              Session Context                     │
+│  sessionId, variables, messageStore            │
+│  通过 runInSession() 设置                       │
+│  Per-Session 消息隔离                           │
+└─────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌─────────────────────────────────────────────────┐
+│              Agent Context                       │
+│  agentId, tools, skills, systemPrompt          │
+│  由 MainAgent/SubAgent 实例持有                 │
+└─────────────────────────────────────────────────┘
+```
+
+实现: `src/context/manager.js` + AsyncLocalStorage (`src/framework/framework.js`)
+
+## 数据流
+
+```
+User Input
+    │
+    ▼
+MainAgent.chat() / chatStream()
+    │
+    ▼
+AgentChatHandler ──► LLMProvider.createModel() ──► AI API
+    │                                                   │
+    ▼                                                   ▼
+Tool Call Loop  ◄──────────────────────────────  Tool Call Response
+    │
+    ▼
+ToolRegistry.execute(name, args)
+    │
+    ▼
+Plugin Tool Handlers / SubAgent / Workflow
+    │
+    ▼
+Result returned to LLM → Next iteration or final response
+```
+
+## 插件生命周期
+
+```
+Plugin
+  │  constructor(config)
+  │
+  ▼
+install(framework)    — 注册工具、事件监听
+  │
+  ▼
+start(framework)      — 启动长连接/定时任务
+  │
+  ▼
+reload(framework)     — 热重载 (可选)
+  │
+  ▼
+uninstall(framework)  — 清理资源
+```
+
+## 模块大小目标
+
+- 单文件 ≤ 400 行
+- 类 ≤ 8 个 public 方法
+- 插件目录独立 maintain
+
+## 核心文件一览
+
+| 文件 | 职责 |
+|------|------|
+| `src/framework/framework.js` | 容器，管理所有子系统 |
+| `src/framework/lifecycle.js` | bootstrap/ready/destroy |
+| `src/agent/main.js` | 主对话代理 |
+| `src/agent/sub.js` | 子代理隔离执行 |
+| `src/agent/chat.js` | LLM 通信 + 工具循环 |
+| `src/agent/prompt.js` | 系统提示词构建 |
+| `src/llm/provider.js` | AI 供应商抽象 |
+| `src/plugin/manager.js` | 插件生命周期管理 |
+| `src/plugin/base.js` | Plugin 基类 |
+| `src/tool/registry.js` | 工具注册与执行 |
+| `src/tool/executor.js` | 工具执行路由 |
+| `src/tool/schema.js` | JSON Schema → Zod 转换 |
+| `src/context/manager.js` | 三层上下文管理 |
+| `src/session/session.js` | Per-Session 存储 |

package/docs/migration.md

@@ -0,0 +1,57 @@
+# Migration Guide
+
+旧路径 → 新路径迁移对照表。
+
+## 核心模块迁移
+
+| 旧路径 | 新路径 | 说明 |
+|--------|--------|------|
+| `src/core/agent.js` | `src/agent/main.js` | Agent 类 → MainAgent |
+| `src/core/chat.js` | `src/agent/chat.js` | 聊天处理器 |
+| `src/core/prompt.js` | `src/agent/prompt.js` | 系统提示构建 |
+| `src/core/coordinator.js` | `src/agent/coordinator.js` | 协调器 |
+| `src/core/tool.js` | `src/tool/*` | 拆分为 registry/executor/schema |
+| `src/core/llm.js` | `src/llm/provider.js` | LLM provider 层 |
+| `src/core/plugin.js` | `src/plugin/base.js` | Plugin 基类 |
+| `src/core/errors.js` | `src/common/errors.js` | 错误类型 |
+| `src/core/events.js` | `src/common/events.js` | 事件总线 |
+| `src/core/manager.js` | `src/plugin/manager.js` | PluginManager |
+| `src/core/framework.js` | `src/framework/framework.js` | Framework 核心 |
+| `src/core/lifecycle.js` | `src/framework/lifecycle.js` | 生命周期管理 |
+| `src/core/session.js` | `src/session/session.js` | 会话管理 |
+
+## 插件目录迁移
+
+| 旧路径 | 新路径 | 说明 |
+|--------|--------|------|
+| `plugins/email/` | `plugins/messaging/email/` | 邮件插件 |
+| `plugins/ambient-agent/` | `plugins/ambient/` | 自主 Agent |
+| `plugins/default-plugins.js` | `plugins/core/default/` | 拆分为 index.js + config.js + bootstrap.js |
+| `plugins/executors/*` | `plugins/executors/` | 执行器插件保持位置 |
+| `plugins/io/*` | `plugins/io/` | IO 插件保持位置 |
+
+## 符号迁移
+
+| 旧符号 | 新符号 | 位置 |
+|--------|--------|------|
+| `Agent` | `MainAgent` | `src/agent/main.js` |
+| `createAI()` | `new LLMProvider(config)` | `src/llm/provider.js` |
+| `isThinkingModel()` | 同名 | `src/llm/provider.js` |
+| `_jsonSchemaToZod()` | `jsonSchemaToZod()` | `src/tool/schema.js` |
+| `bootstrapDefaults()` | 同名 | `plugins/core/default/bootstrap.js` |
+| `loadAgentConfig()` | 同名 | `plugins/core/default/config.js` |
+
+## PluginManager 新增方法
+
+| 方法 | 说明 |
+|------|------|
+| `isEnabled(name)` | 检查插件是否启用 |
+| `startAll()` | 启动所有已加载插件 |
+| `setBootstrapping(bool)` | 设置引导状态 |
+
+## Framework 新增方法
+
+| 方法 | 说明 |
+|------|------|
+| `_setReady()` | 标记框架就绪并触发 `framework:ready` 事件 |
+| `isEnabled(name)` | 代理到 `pluginManager.isEnabled()` |

package/docs/public-api.md

@@ -0,0 +1,138 @@
+# Public API Reference
+
+Foliko 对外公共 API 速查。
+
+## 入门三件套
+
+```js
+const foliko = require('foliko');
+
+// 1) Bootstrap — 加载配置并启动框架
+const framework = await foliko.bootstrap({
+  _config: { ai: { provider: 'deepseek', model: 'deepseek-chat' } }
+});
+
+// 2) createApp — 构造未启动的 Framework，支持链式 .use()
+const app = foliko.createApp();
+await app.use(foliko.withAI({ provider: 'openai', model: 'gpt-4' }));
+await app.use(foliko.withShell());
+await bootstrap(app, {});
+
+// 3) createAgent — 显式创建 Agent
+const agent = foliko.createAgent(framework, {
+  name: 'MyAgent',
+  systemPrompt: 'You are a helpful assistant.',
+});
+```
+
+## 框架生命周期
+
+```js
+const fw = await foliko.bootstrap(config);
+await foliko.ready(fw);     // 等待框架就绪
+await foliko.destroy(fw);   // 销毁框架
+```
+
+## 上下文管理
+
+```js
+// Session 上下文
+await foliko.runInSession(framework, sessionId, options, async () => {
+  // 在此作用域内可通过 framework.getCurrentSessionContext() 获取 Session
+});
+
+// Request 上下文
+await foliko.runInRequest(framework, { requestId, traceId }, async () => {
+  // 在此作用域内可通过 framework.getRequestContext() 获取 Request
+});
+```
+
+## 工具注册
+
+```js
+const toolDef = {
+  name: 'my_tool',
+  description: 'Does something',
+  inputSchema: z.object({ msg: z.string() }),
+  execute: async (args) => { return { result: args.msg }; },
+};
+
+foliko.registerTool(framework, toolDef);
+```
+
+## 快捷插件工厂
+
+```js
+const aiPlugin = foliko.withAI({ provider: 'deepseek', model: 'deepseek-chat' });
+const shellPlugin = foliko.withShell({ allowedCommands: ['ls', 'cat'] });
+const pythonPlugin = foliko.withPython({ timeout: 30000 });
+```
+
+## 框架实例方法
+
+```js
+// 插件管理
+framework.pluginManager.has(name);
+framework.pluginManager.get(name);
+framework.pluginManager.getAll();
+framework.pluginManager.isEnabled(name);
+framework.pluginManager.getNames();
+
+// Agent 管理
+framework.getMainAgent();
+framework.getAgents();
+framework.createAgent(config);
+framework.createSubAgent(config);
+framework.createSessionAgent(sessionId, config);
+
+// Session 管理
+framework.getOrCreateSessionContext(sessionId, options);
+framework.getCurrentSessionContext();
+framework.getCurrentSessionId();
+framework.listSessionContexts();
+framework.destroySessionContext(sessionId);
+
+// 工具
+framework.registerTool(toolDef);
+framework.getTools();
+framework.executeTool(name, args);
+
+// 事件
+framework.on('email:received', handler);
+framework.on('framework:ready', handler);
+framework.on('tool:call', handler);
+framework.on('session:context-created', handler);
+```
+
+## 导出类型
+
+```js
+const {
+  Framework, MainAgent, SubAgent, WorkerAgent,
+  Plugin, PluginManager,
+  ToolRegistry, ToolExecutor,
+  EventEmitter, Logger,
+  LLM, z,
+  SkillManagerPlugin, Skill, SkillMetadata,
+  WorkflowPlugin, WorkflowEngine, StepExecutor,
+  MCPExecutorPlugin,
+  Agent, // == MainAgent (backward compat)
+} = require('foliko');
+```
+
+## 全部导出速查
+
+| Export | 来源 | 说明 |
+|--------|------|------|
+| `bootstrap` | lifecycle | 加载配置启动框架 |
+| `createApp` | facade | 构造未启动 Framework |
+| `createAgent` | agent/index | 创建 MainAgent |
+| `runInSession` | framework | Session 上下文运行 |
+| `runInRequest` | framework | Request 上下文运行 |
+| `registerTool` | facade | 快速注册工具 |
+| `use` | facade | 加载插件到实例 |
+| `ready` | lifecycle | 等待就绪 |
+| `destroy` | lifecycle | 销毁框架 |
+| `withAI` | facade | 创建 AI 插件 |
+| `withShell` | facade | 创建 Shell 插件 |
+| `withPython` | facade | 创建 Python 插件 |

package/docs/usage.md

@@ -0,0 +1,385 @@
+# Foliko 使用指南
+
+## 目录结构
+
+```
+<project-root>/
+├── .foliko/                    # 项目级配置目录
+│   ├── config                  # 基础配置 (key: value 格式)
+│   ├── ai.json                 # AI 模型配置
+│   ├── plugins.json            # 插件配置 (messaging 等)
+│   ├── weixin.json             # 微信配置
+│   ├── mcp_config.json         # MCP 服务器配置
+│   ├── agents/                 # SubAgent 定义
+│   ├── skills/                 # 项目级技能 (子目录或 .md 文件)
+│   ├── workflows/              # 工作流 (.md 作为 skill, .json/.js 作为 workflow)
+│   ├── rules/                  # 权限规则 (.json 或 .md)
+│   └── sessions/               # 会话数据
+│
+├── skills/                     # 项目根目录技能
+├── plugins/                    # 项目级插件
+│
+├── ~/.foliko/                  # 用户主目录全局配置
+│   ├── config                  # 全局配置 (项目级未设置时生效)
+│   ├── skills/                 # 全局技能 (优先级最高)
+│   ├── workflows/              # 全局工作流
+│   └── rules/                  # 全局规则
+│
+└── src/                        # 框架核心
+```
+
+## 配置
+
+### `.foliko/config`
+
+基础配置文件，`key: value` 格式，支持 `#` 注释：
+
+```ini
+# AI 配置
+api_key: sk-your-key
+model: deepseek-chat
+provider: deepseek
+baseURL: https://api.deepseek.com
+
+# 目录路径配置 (覆盖默认值)
+skills_dirs: ~/.foliko/skills,.foliko/skills,skills
+workflows_dir: ~/.foliko/workflows
+rules_dir: ~/.foliko/rules
+agents_dir: ~/.foliko/agents
+```
+
+- `skills_dirs`: 逗号分隔的目录列表，顺序决定优先级（先匹配的优先）
+- `workflows_dir`: 工作流目录
+- `rules_dir`: 规则目录
+- `agents_dir`: SubAgent 定义目录
+
+不设置则使用默认路径（参见下方"目录优先级"）。
+
+### `.foliko/ai.json`
+
+AI 模型配置，支持所有 provider 参数：
+
+```json
+{
+  "provider": "deepseek",
+  "model": "deepseek-chat",
+  "apiKey": "sk-xxx",
+  "baseURL": "https://api.deepseek.com"
+}
+```
+
+支持 provider: `deepseek`, `openai`, `anthropic`, `minimax`, `openai-compatible`
+
+### `.foliko/plugins.json`
+
+插件配置：
+
+```json
+{
+  "telegram": { "botToken": "xxx" },
+  "weixin": { "appId": "xxx", "appSecret": "xxx" },
+  "email": { "host": "smtp.xxx.com", "port": 587 },
+  "pluginLinks": {
+    "my-plugin": "/path/to/my-plugin/index.js"
+  }
+}
+```
+
+`pluginLinks` 用于注册自定义插件路径。
+
+### `.foliko/mcp_config.json`
+
+MCP 服务器配置：
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
+      "env": { "KEY": "value" },
+      "enabled": true
+    }
+  }
+}
+```
+
+## 目录优先级
+
+### Skills
+
+扫描顺序（先加载的优先，同名 skill 不会被后加载的覆盖）：
+
+1. `~/.foliko/skills/` — 用户全局
+2. `~/.foliko/workflows/` — 用户全局工作流（作为 skill）
+3. `.foliko/skills/` — 项目级
+4. `.foliko/workflows/` — 项目级工作流（作为 skill）
+5. `skills/` — 项目根目录
+6. `plugins/core/skills/` — 内置（不存在则跳过）
+
+可在 `.foliko/config` 中通过 `skills_dirs` 完全替换默认列表。
+
+### Workflows (结构化)
+
+默认扫描（用户优先）：
+
+1. `~/.foliko/workflows/` — 用户全局
+2. `.foliko/workflows/` — 项目级
+
+只加载 `.json` 和 `.js` 文件（需包含 `steps` 数组）。
+可在 `.foliko/config` 通过 `workflows_dir` 修改项目级目录。
+
+### Rules
+
+默认扫描（用户优先）：
+
+1. `~/.foliko/rules/` — 用户全局
+2. `.foliko/rules/` — 项目级
+
+支持 `.json` 和 `.md`（YAML frontmatter）格式。
+可在 `.foliko/config` 通过 `rules_dir` 修改项目级目录。
+
+## Skills
+
+### 格式
+
+Skill 是一个 markdown 文件，包含 YAML frontmatter：
+
+```markdown
+---
+name: my-skill
+description: 技能描述
+---
+
+# 技能标题
+
+这里写技能的具体使用指导。
+```
+
+### 加载方式
+
+```
+skills/              → 子目录内有 SKILL.md → 加载为 skill
+.foliko/skills/      → 同上
+.foliko/workflows/   → 独立 .md 文件 → 加载为 skill（文件名即为 skill 名）
+```
+
+### 命令注册
+
+如果 skill 目录下有 `index.js`，导出命令数组即可注册为可调用的 slash 命令：
+
+```js
+module.exports = [
+  {
+    name: 'greet',
+    description: '打招呼',
+    options: [
+      { flags: '-n, --name <value>', description: '姓名' }
+    ],
+    execute: async (parsedArgs, ctx) => {
+      return `Hello, ${parsedArgs.name || 'World'}!`
+    }
+  }
+]
+```
+
+命令通过 `ext_call({ plugin: "skill", tool: "skill-name:command-name", args: { command: "..." } })` 调用。
+
+### 相关工具
+
+- `loadSkill({ skill: "name" })` — 获取技能内容
+- `reloadSkills` — 重载所有技能
+- `loadReference({ skill, reference })` — 加载技能的参考文档
+- `listScripts` / `loadScript` — 技能脚本管理
+
+## Workflows
+
+### 结构化工作流
+
+`.foliko/workflows/` 下的 `.json` 或 `.js` 文件，定义带步骤的工作流：
+
+```json
+{
+  "name": "my-workflow",
+  "description": "工作流描述",
+  "steps": [
+    { "type": "tool", "tool": "tool_name", "args": { ... } },
+    { "type": "script", "script": "return input.value" },
+    { "type": "condition", "branches": [...] }
+  ]
+}
+```
+
+支持的步骤类型：`tool`, `script`, `condition`, `switch`, `try`, `parallel`, `sequential`, `loop`, `delay`, `workflow`
+
+### 相关工具
+
+- `execute_workflow({ workflow, input })` — 执行工作流
+- `listWorkflows` — 列出所有已加载工作流
+- `reloadWorkflows` — 重载工作流
+
+## Rules
+
+### JSON 格式
+
+```json
+[
+  {
+    "name": "block-dangerous-tools",
+    "type": "deny",
+    "target": "shell_exec",
+    "pattern": "rm\\s+-rf",
+    "enabled": true
+  }
+]
+```
+
+### Markdown 格式
+
+```markdown
+---
+name: block-dangerous
+type: deny
+target: shell_exec
+condition: rm\s+-rf
+description: 阻止危险命令
+enabled: true
+---
+```
+
+规则类型：
+- `allow` — 允许特定调用
+- `deny` — 拒绝特定调用
+- `transform` — 转换调用参数
+
+### 相关工具
+
+- `rules_list` — 列出所有规则
+- `rules_add` — 添加规则
+- `rules_remove` — 移除规则
+- `rules_stats` — 规则统计
+- `rules_test` — 测试规则匹配
+
+## 动态切换工作目录
+
+在运行时切换到其他项目目录，所有插件自动重载：
+
+```js
+const { setCwd } = require('./src/framework')
+await setCwd(framework, '/new/project/path')
+```
+
+切换后自动：
+1. 更新 `framework._cwd`（通过 `framework.getCwd()` 获取）
+2. 销毁当前 session 上下文
+3. 调每个插件的 `onCwdChanged()` 做预清理
+4. 调每个插件的 `reload()` 从新目录重新扫描
+   - skill-manager: 从新 CWD 的 skillsDirs 重新加载技能
+   - workflow: 从新 CWD 重新加载工作流
+   - rules: 从新 CWD 重新加载规则
+   - extension-executor: 重新扫描所有插件的工具注册
+5. 发射 `cwd:changed` 事件
+
+### 在 agent 中使用
+
+```js
+// 注册为 agent 可调用的工具
+framework.registerTool({
+  name: 'set_working_directory',
+  description: '切换工作目录',
+  inputSchema: z.object({
+    path: z.string().describe('新工作目录路径')
+  }),
+  execute: async (args) => {
+    await setCwd(framework, args.path)
+    return { success: true, data: `Switched to ${args.path}` }
+  }
+})
+```
+
+## 常用事件
+
+| 事件 | 触发时机 | 参数 |
+|---|---|---|
+| `framework:ready` | 框架启动完成 | `framework` |
+| `framework:destroyed` | 框架销毁 | — |
+| `cwd:changed` | 工作目录切换 | `{ oldCwd, newCwd, framework }` |
+| `skill:reloaded` | 技能重载 | `{ skills: string[] }` |
+| `session:context-created` | 新会话创建 | `{ sessionId, manager }` |
+| `rescan:complete` | 项目重新扫描完成 | `{ unloaded, loaded, keepLoaded }` |
+| `plugin:loaded` | 插件加载 | plugin 实例 |
+| `plugin:reloaded` | 插件重载 | plugin 实例 |
+| `tool:call` / `tool-call` | 工具调用 | `{ name, args, source }` |
+| `tool:result` | 工具返回结果 | `{ name, result }` |
+| `tool:error` | 工具出错 | `{ name, args, error, source }` |
+
+## 插件开发
+
+### 基础结构
+
+```js
+const { Plugin } = require('./src/plugin/base')
+
+class MyPlugin extends Plugin {
+  constructor(config = {}) {
+    super()
+    this.name = 'my-plugin'
+    this.version = '1.0.0'
+    this.description = 'My custom plugin'
+    this.priority = 50
+    this.system = false
+  }
+
+  install(framework) {
+    // 注册工具、监听事件
+    framework.registerTool({
+      name: 'my_tool',
+      description: 'My tool',
+      inputSchema: z.object({ ... }),
+      execute: async (args) => { ... }
+    })
+    framework.on('some:event', handler)
+    return this
+  }
+
+  start(framework) {
+    // 初始化逻辑，start() 可能会被调用多次
+    return this
+  }
+
+  reload(framework) {
+    // 热重载
+  }
+
+  async onCwdChanged(oldCwd, newCwd, framework) {
+    // 工作目录切换前的预清理
+    // 之后会自动调 reload()
+  }
+
+  uninstall(framework) {
+    // 清理
+  }
+}
+
+module.exports = MyPlugin
+```
+
+### 生命周期
+
+```
+install() → load() → [start() + 注册工具]
+                ↓
+         startAll() → [start() 再次调用]
+                ↓
+         reload() → 热重载
+                ↓
+         uninstall() → 卸载清理
+```
+
+**注意**：`start()` 会被调用两次（`load()` 和 `startAll()`），插件需通过 `_loaded` 标志或幂等设计来防止重复初始化。
+
+### 放置位置
+
+- 项目级：`plugins/<name>/index.js`
+- 全局：`~/.foliko/plugins/<name>.js` 或 `~/.foliko/plugins/<name>/index.js`
+- 通过 `pluginLinks` 指定任意路径