foliko 1.0.0 → 1.0.1

package/README.md

@@ -1,217 +1,177 @@
-# JavaScript 测试代码示例
+# Foliko
 
-这个项目展示了现代 JavaScript 测试的最佳实践，使用 Jest 作为测试框架。
+简约的插件化 Agent 框架
 
-## 文件结构
+## 特性
 
-- `test-example.js` - 完整的测试示例，包含多种测试类型
-- `simple-test-example.js` - 简洁的测试示例，适合初学者
-- `package.json` - 项目配置和 Jest 设置
+- **插件化架构** - 核心简单，通过插件扩展功能
+- **流式输出** - 支持实时流式输出
+- **多 AI 支持** - 支持 Anthropic、DeepSeek、MiniMax 等
+- **内置工具** - Shell、Python、MCP、文件系统等
+- **技能系统** - 可扩展的 Skill 管理
+- **会话管理** - 支持多会话切换
+- **规则引擎** - 可配置的行为规则
 
-## 包含的测试类型
+## 快速开始
 
-### 1. 单元测试
-- 函数测试
-- 类方法测试
-- 边界情况测试
-- 异常测试
-
-### 2. 异步测试
-- Promise 测试
-- async/await 测试
-- 超时处理
-
-### 3. 集成测试
-- 多个类的组合测试
-- 完整流程测试
-
-### 4. Mock 和 Spy
-- 模拟函数
-- 模拟 API 调用
-- 验证函数调用
-
-### 5. 参数化测试
-- 使用 `test.each` 测试多组数据
-
-### 6. 快照测试
-- 对象结构验证
-
-## 最佳实践展示
+```bash
+# 安装
+npm install
 
-### 1. AAA 模式 (Arrange-Act-Assert)
-```javascript
-test('应该正确计算两个数的和', () => {
-  // Arrange: 准备测试数据
-  const a = 5;
-  const b = 3;
-  const expected = 8;
-
-  // Act: 执行被测试的方法
-  const result = calculator.add(a, b);
-
-  // Assert: 验证结果
-  expect(result).toBe(expected);
-});
+# 启动聊天
+npm run chat
 ```
 
-### 2. 描述性测试名称
-- 使用 "should" 描述预期行为
-- 包含测试条件
-- 清晰表达测试目的
-
-### 3. 测试隔离
-- 每个测试独立运行
-- 使用 `beforeEach` 重置状态
-- 避免测试间的依赖
+## 项目结构
 
-### 4. 恰当的断言
-- 使用合适的匹配器
-- 验证异常
-- 检查异步结果
-
-### 5. 测试覆盖率
-- 行覆盖率
-- 分支覆盖率
-- 函数覆盖率
-- 语句覆盖率
-
-## 安装和运行
-
-### 1. 安装依赖
-```bash
-npm install
+```
+vb-agent/
+├── cli/                 # 命令行入口
+│   └── bin/foliko.js    # CLI 入口
+├── src/                 # 核心框架
+│   ├── core/            # 核心组件
+│   ├── capabilities/    # 能力插件
+│   └── executors/       # 执行器
+├── plugins/             # 内置插件
+├── skills/              # 技能目录
+└── examples/            # 示例
 ```
 
-### 2. 运行测试
-```bash
-# 运行所有测试
-npm test
+## 配置
 
-# 监视模式（文件变化时自动运行）
-npm run test:watch
+在项目根目录创建 `.agent` 目录：
 
-# 生成覆盖率报告
-npm run test:coverage
+```
+.agent/
+├── config              # 配置文件
+├── ai.json            # AI 配置
+├── mcp_config.json    # MCP 服务器配置
+├── plugins/           # 用户插件目录
+├── skills/            # 用户技能目录
+└── data/              # 数据目录
+```
 
-# 详细输出
-npm run test:verbose
+### config 文件格式
 
-# 更新快照
-npm run test:update
+```
+ai_key: your-api-key
+ai_model: MiniMax-M2.7
+ai_provider: minimax
 ```
 
-### 3. 查看覆盖率报告
-运行 `npm run test:coverage` 后，打开 `coverage/index.html` 查看详细的覆盖率报告。
+### ai.json 格式
 
-## Jest 配置说明
+```json
+{
+  "provider": "minimax",
+  "model": "MiniMax-M2.7",
+  "apiKey": "your-api-key",
+  "baseURL": "https://api.minimaxi.com/v1"
+}
+```
 
-在 `package.json` 中的 Jest 配置：
+### mcp_config.json 格式
 
 ```json
 {
-  "jest": {
-    "testEnvironment": "node",          // 测试环境
-    "verbose": true,                    // 详细输出
-    "collectCoverage": true,            // 收集覆盖率
-    "coverageDirectory": "coverage",    // 覆盖率输出目录
-    "coverageReporters": ["text", "lcov", "html"], // 报告格式
-    "coverageThreshold": {              // 覆盖率阈值
-      "global": {
-        "branches": 80,
-        "functions": 80,
-        "lines": 80,
-        "statements": 80
-      }
-    },
-    "testMatch": [                      // 测试文件匹配模式
-      "**/__tests__/**/*.js",
-      "**/?(*.)+(spec|test).js"
-    ],
-    "testTimeout": 10000,               // 测试超时时间
-    "clearMocks": true,                 // 自动清理 mock
-    "resetMocks": true,                 // 重置 mock
-    "restoreMocks": true                // 恢复原始实现
+  "mcpServers": {
+    "fetch": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-fetch"]
+    }
   }
 }
 ```
 
-## 测试技巧
+## 开发插件
+
+### 用户插件（.agent/plugins/）
 
-### 1. 测试异步代码
 ```javascript
-// 使用 async/await
-test('应该异步返回数据', async () => {
-  const result = await fetchData();
-  expect(result).toEqual({ data: '测试数据' });
-});
-
-// 测试异步异常
-test('应该抛出异步错误', async () => {
-  await expect(asyncFunction()).rejects.toThrow('错误信息');
-});
+// .agent/plugins/my-plugin.js
+module.exports = function(Plugin) {
+  return class MyPlugin extends Plugin {
+    constructor(config = {}) {
+      super()
+      this.name = 'my-plugin'
+      this.version = '1.0.0'
+      this.description = '我的工具插件'
+      this.priority = 10
+    }
+
+    install(framework) {
+      const { z } = require('zod')
+      framework.registerTool({
+        name: 'my_tool',
+        description: '我的工具',
+        inputSchema: z.object({
+          param: z.string().describe('参数描述')
+        }),
+        execute: async (args, framework) => {
+          return { success: true, result: args.param }
+        }
+      })
+      return this
+    }
+  }
+}
 ```
 
-### 2. Mock 函数
-```javascript
-// 创建 mock 函数
-const mockFn = jest.fn();
+**注意**：如果插件需要第三方库（如 `zod`），需要先安装：
 
-// 设置返回值
-mockFn.mockReturnValue('返回值');
+1. 创建插件文件
+2. 调用 `install` 工具安装依赖
+3. 热重载插件
 
-// 验证调用
-expect(mockFn).toHaveBeenCalledTimes(1);
-expect(mockFn).toHaveBeenCalledWith('参数');
-```
+### 技能开发
 
-### 3. 参数化测试
-```javascript
-test.each([
-  [1, 1, 2],
-  [1, 2, 3],
-  [2, 1, 3],
-])('add(%i, %i) should equal %i', (a, b, expected) => {
-  expect(a + b).toBe(expected);
-});
+在 `.agent/skills/` 下创建技能：
+
+```
+.agent/skills/my-skill/
+└── SKILL.md
 ```
 
-### 4. 快照测试
-```javascript
-test('对象应该匹配快照', () => {
-  const obj = {
-    id: 1,
-    name: '测试',
-    date: new Date('2024-01-01')
-  };
-  
-  expect(obj).toMatchSnapshot({
-    date: expect.any(Date) // 忽略具体日期值
-  });
-});
+SKILL.md 格式：
+
+```markdown
+---
+name: my-skill
+description: 技能描述
+allowed-tools: tool1,tool2
+---
+
+技能内容...
 ```
 
-## 常见问题
+## CLI 命令
 
-### 1. 测试运行太慢
-- 减少不必要的异步等待
-- 使用 `jest.useFakeTimers()` 模拟时间
-- 避免在测试中执行真实 API 调用
+```bash
+# 聊天模式
+foliko chat
+
+# 指定模型
+foliko chat --model gpt-4
+
+# 指定 API
+foliko chat --api-key xxx
+```
 
-### 2. 测试不稳定（Flaky Tests）
-- 确保测试独立
-- 避免依赖外部状态
-- 使用固定的测试数据
+## 内置工具
 
-### 3. 覆盖率不足
-- 添加边界情况测试
-- 测试错误处理路径
-- 验证所有分支条件
+| 工具 | 说明 |
+|------|------|
+| `loadSkill` | 加载技能 |
+| `mcp_execute` | 执行 MCP 工具 |
+| `shell_execute` | 执行 Shell 命令 |
+| `python_execute` | 执行 Python 代码 |
+| `install` | 安装 npm 包 |
+| `mcp_reload` | 重载 MCP 服务器 |
+| `audit_query` | 查询审计日志 |
 
-## 扩展阅读
+## 工作目录
 
-- [Jest 官方文档](https://jestjs.io/)
-- [测试金字塔原则](https://martinfowler.com/bliki/TestPyramid.html)
-- [AAA 测试模式](https://medium.com/@pjbgf/title-testing-code-ocd-and-the-aaa-pattern-df453975ab80)
+CLI 工作目录默认使用执行命令的目录。
 
 ## 许可证
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foliko",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "简约的插件化 Agent 框架",
   "main": "src/index.js",
   "bin": {