formagent-sdk 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formagent-sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "FormAgent SDK - AI Agent framework with streaming support, tool execution, skill management, and hooks system",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,9 +26,6 @@
   },
   "files": [
     "dist",
-    "src",
-    "examples",
-    "docs/*.md",
     "README.md",
     "LICENSE"
   ],

package/docs/README.md

@@ -1,122 +0,0 @@
-# formagent-sdk Documentation
-
-Welcome to the documentation for `formagent-sdk`, a Claude Agent SDK compatible framework for building AI agents with streaming support, tool execution, and skill management.
-
-## Table of Contents
-
-- [Getting Started](./getting-started.md) - Quick start guide
-- [API Reference](./api-reference.md) - Complete API documentation
-- [Built-in Tools](./tools.md) - File operations, bash, and more
-- [MCP Servers](./mcp-servers.md) - Model Context Protocol integration
-- [Examples](./examples.md) - Code examples and tutorials
-
-## Quick Links
-
-### Installation
-
-```bash
-npm install formagent-sdk
-# or
-bun add formagent-sdk
-```
-
-### Environment Setup
-
-```bash
-export ANTHROPIC_API_KEY=your-api-key
-# Optional: Custom endpoint
-export ANTHROPIC_BASE_URL=https://your-proxy.com
-```
-
-### Minimal Example
-
-```typescript
-import { createSession, builtinTools } from "formagent-sdk"
-
-const session = await createSession({
-  model: "claude-sonnet-4-20250514",
-  tools: builtinTools,
-})
-
-await session.send("List files in the current directory")
-
-for await (const event of session.receive()) {
-  if (event.type === "text") {
-    process.stdout.write(event.text)
-  }
-}
-
-await session.close()
-```
-
-## Core Concepts
-
-### Sessions
-
-Sessions manage conversations with Claude. They handle message history, tool execution, and streaming responses.
-
-```typescript
-const session = await createSession({ model: "claude-sonnet-4-20250514" })
-await session.send("Hello!")
-for await (const event of session.receive()) { /* ... */ }
-await session.close()
-```
-
-### Tools
-
-Tools extend Claude's capabilities. The SDK provides built-in tools and supports custom tool definitions.
-
-```typescript
-import { builtinTools, tool } from "formagent-sdk"
-import { z } from "zod"
-
-// Use built-in tools
-const session = await createSession({ tools: builtinTools })
-
-// Or create custom tools
-const myTool = tool({
-  name: "my_tool",
-  description: "Does something useful",
-  schema: z.object({ input: z.string() }),
-  execute: async ({ input }) => `Result: ${input}`,
-})
-```
-
-### MCP Servers
-
-MCP (Model Context Protocol) servers provide a standardized way to expose tools.
-
-```typescript
-import { createSdkMcpServer, tool } from "formagent-sdk"
-
-const server = createSdkMcpServer({
-  name: "my-server",
-  version: "1.0.0",
-  tools: [myTool],
-})
-```
-
-## Architecture
-
-```
-formagent-sdk
-├── Session API          # Conversation management
-│   ├── createSession()  # Create new sessions
-│   ├── send()          # Send messages
-│   └── receive()       # Stream responses
-├── Tool System          # Tool execution
-│   ├── builtinTools    # Built-in tools (Bash, Read, Write, etc.)
-│   ├── tool()          # Tool definition helper
-│   └── ToolManager     # Tool registration and execution
-├── MCP Integration      # Model Context Protocol
-│   ├── createSdkMcpServer()
-│   └── MCPServerManager
-└── Providers            # LLM providers
-    ├── AnthropicProvider
-    └── OpenAIProvider
-```
-
-## Support
-
-- [GitHub Issues](https://github.com/anthropics/claude-code/issues)
-- [Examples](../examples/)

package/docs/agent-core-summary.md

@@ -1,516 +0,0 @@
-# AgentCore 项目总结
-
-## 项目概述
-
-`@opencode/agent-core` 是一个独立的 AI Agent 框架，提供完整的 agent 执行能力，包括消息循环、LLM 调用、工具系统、技能管理和流式响应。
-
-## 项目结构
-
-```
-./
-├── src/
-│   ├── index.ts                    # 主入口，导出所有公共 API
-│   ├── types.ts                   # 核心类型定义
-│   ├── tools/
-│   │   └── registry.ts           # 工具注册表
-│   ├── skills/
-│   │   └── loader.ts             # 技能加载器
-│   ├── llm/
-│   │   └── openai.ts             # OpenAI LLM Provider 实现
-│   ├── loop/
-│   │   └── agent.ts             # Agent 主类（消息循环）
-│   └── stream/
-│       └── processor.ts          # 流式响应处理器
-├── test/
-│   └── agent-core.test.ts          # 单元测试
-├── example.ts                       # 完整使用示例
-├── package.json                    # 包配置
-├── tsconfig.json                   # TypeScript 配置
-└── README.md                      # 项目文档
-```
-
-## 核心功能
-
-### 1. Agent 类 (`src/loop/agent.ts`)
-
-Agent 类是整个框架的核心，负责：
-
-**主要职责：**
-- 管理消息历史
-- 执行主循环（自动处理工具调用、生成响应等）
-- 协调 LLM、工具、技能系统
-- 事件发射（流式通知）
-- Doom Loop 检测
-- 上下文压缩
-
-**核心方法：**
-```typescript
-class Agent {
-  // 启动 agent 执行
-  async run(input: AgentInput, options?: AgentOptions): Promise<AgentResult>
-
-  // 注册事件监听器
-  on(event: string, listener: (...args: any[]) => void): this
-
-  // 访问内部组件
-  getMessages(): Message[]
-  getToolRegistry(): ToolRegistry
-  getSkillLoader(): SkillLoader
-
-  // 重置状态
-  reset(): void
-}
-```
-
-### 2. ToolRegistry (`src/tools/registry.ts`)
-
-工具注册表，管理所有可用工具。
-
-**主要职责：**
-- 注册和注销工具
-- 查找和获取工具
-- 执行工具（带权限检查和错误处理）
-- 工具调用事件通知
-
-**核心方法：**
-```typescript
-class ToolRegistry {
-  register(tool: ToolDefinition): void
-  unregister(toolId: string): void
-  get(toolId: string): ToolDefinition | undefined
-  getAll(): ToolDefinition[]
-  clear(): void
-  async execute(toolId, input, context): Promise<ToolResult>
-}
-```
-
-### 3. SkillLoader (`src/skills/loader.ts`)
-
-技能加载器，管理动态技能。
-
-**主要职责：**
-- 注册和注销技能
-- 查找和获取技能
-- 搜索技能（按名称或描述）
-- 加载技能内容
-
-**核心方法：**
-```typescript
-class SkillLoader {
-  register(skill: SkillDefinition): void
-  unregister(skillId: string): void
-  async load(skillId: string): Promise<SkillDefinition | undefined>
-  async loadAll(): Promise<SkillDefinition[]>
-  async search(query?: string): Promise<SkillDefinition[]>
-  clear(): void
-}
-```
-
-### 4. OpenAIProvider (`src/llm/openai.ts`)
-
-OpenAI LLM Provider 实现。
-
-**主要职责：**
-- 创建流式 LLM 调用
-- 处理 SSE (Server-Sent Events) 响应
-- 转换消息格式
-- 支持工具调用
-
-**核心方法：**
-```typescript
-class OpenAIProvider implements LLMProvider {
-  async stream(config: {
-    messages: LLMMessage[]
-    tools: ToolDefinition[]
-    llmConfig: LLMConfig
-    abortSignal: AbortSignal
-    onChunk?: (chunk: LLMResponseChunk) => void
-  }): Promise<LLMStream>
-}
-```
-
-### 5. StreamProcessor (`src/stream/processor.ts`)
-
-流式响应处理器，处理 LLM 响应 chunk 并发射事件。
-
-**主要职责：**
-- 处理各种 chunk 类型（文本、工具调用、完成等）
-- 累积文本和推理内容
-- 发射适当的事件
-
-**核心方法：**
-```typescript
-class StreamProcessor {
-  async processChunk(chunk: LLMResponseChunk): Promise<void>
-  reset(): void
-  getText(): string
-  getReasoning(): string
-}
-```
-
-### 6. AgentEventEmitter (`src/types.ts`)
-
-基于 Node.js EventEmitter 的事件发射器，提供类型安全的事件系统。
-
-**支持的事件：**
-- `chunk`: 响应 chunk
-- `tool_call`: 工具调用（开始、结果、错误）
-- `message_complete`: 消息完成
-- `error`: 发生错误
-- `complete`: 整体完成
-
-## 使用方式
-
-### 基础用法
-
-```typescript
-import { createAgent, AgentConfig, UserMessage } from "@opencode/agent-core"
-
-// 1. 创建 Agent
-const config: AgentConfig = {
-  id: "my-agent",
-  name: "My Agent",
-  llmConfig: {
-    providerId: "openai",
-    modelId: "gpt-4",
-    apiKey: "your-api-key",
-  },
-  tools: [
-    // 定义工具
-    {
-      id: "read_file",
-      name: "read_file",
-      description: "Reads a file",
-      parameters: { /* schema */ },
-      async execute(input, context) { /* 实现 */ },
-    },
-  ],
-}
-
-const agent = createAgent(config)
-
-// 2. 运行 Agent
-const result = await agent.run(
-  {
-    sessionId: "session-123",
-    userMessage: {
-      id: "user-1",
-      role: "user",
-      timestamp: Date.now(),
-      content: [
-        { type: "text", text: "Hello!" },
-      ],
-    },
-    abortSignal: new AbortController().signal,
-  },
-  {
-    // 实时事件处理
-    onChunk: async (chunk) => {
-      console.log("Received chunk:", chunk)
-
-      if (chunk.type === "text") {
-        // 实时显示文本
-      }
-
-      if (chunk.type === "tool_call") {
-        // 显示工具调用进度
-      }
-    },
-    onToolCall: async (event) => {
-      console.log("Tool event:", event)
-    },
-    onMessageComplete: async (message) => {
-      console.log("Message complete:", message)
-    },
-    onComplete: async (result) => {
-      console.log("Agent completed:", result)
-    },
-    onError: async (error) => {
-      console.error("Agent error:", error)
-    },
-  },
-)
-
-console.log("Final result:", result)
-```
-
-### 自定义工具
-
-```typescript
-import type { ToolDefinition, ToolContext } from "@opencode/agent-core"
-
-const customTool: ToolDefinition = {
-  id: "search_api",
-  name: "search_api",
-  description: "Searches external API",
-  parameters: {
-    type: "object",
-    properties: {
-      query: { type: "string", description: "Search query" },
-    },
-    required: ["query"],
-  },
-  async execute(input, context) {
-    const response = await fetch(`https://api.example.com/search?q=${input.query}`)
-    const data = await response.json()
-
-    return {
-      output: JSON.stringify(data.results),
-      metadata: { query: input.query },
-    }
-  },
-}
-
-const config: AgentConfig = {
-  // ...其他配置
-  tools: [customTool],
-}
-
-const agent = createAgent(config)
-```
-
-### 自定义 LLM Provider
-
-```typescript
-import type { LLMProvider, LLMConfig, LLMMessage, ToolDefinition } from "@opencode/agent-core"
-
-class CustomProvider implements LLMProvider {
-  id = "custom"
-  name = "Custom Provider"
-
-  async stream(config: {
-    messages: LLMMessage[]
-    tools: ToolDefinition[]
-    llmConfig: LLMConfig
-    abortSignal: AbortSignal
-  }) {
-    // 实现自定义的 LLM 调用逻辑
-    // 返回异步生成器
-  }
-}
-```
-
-### 事件监听
-
-```typescript
-import { createAgent, AgentConfig, UserMessage } from "@opencode/agent-core"
-
-const config: AgentConfig = { /* ... */ }
-const agent = createAgent(config)
-
-// 监听所有事件
-agent.on("chunk", (chunk) => {
-  if (chunk.type === "text") {
-    // 实时更新 UI
-  }
-})
-
-agent.on("tool_call", (event) => {
-  if (event.type === "start") {
-    // 显示工具调用开始
-  }
-})
-
-agent.on("message_complete", (message) => {
-  // 更新消息历史 UI
-})
-
-agent.on("error", (error) => {
-  // 显示错误提示
-})
-
-agent.on("complete", (result) => {
-  // 更新最终状态
-})
-```
-
-## 高级特性
-
-### Doom Loop 检测
-
-自动检测并阻止无限循环的工具调用：
-
-```typescript
-const config: AgentConfig = {
-  enableDoomLoopDetection: true,
-  doomLoopThreshold: 3,  // 同一工具调用3次后触发
-}
-```
-
-### 上下文压缩
-
-自动压缩对话历史以控制 token 使用：
-
-```typescript
-const config: AgentConfig = {
-  enableCompaction: true,
-  compactionThreshold: 100000,  // 100k tokens 后压缩
-}
-```
-
-### 最大步数限制
-
-防止 agent 运行过多步数：
-
-```typescript
-const config: AgentConfig = {
-  maxSteps: 50,  // 最多50步后停止
-}
-```
-
-## 类型安全
-
-所有核心类型都在 `src/types.ts` 中定义，包括：
-
-- `Message`, `UserMessage`, `AssistantMessage`, `SystemMessage`
-- `ToolDefinition`, `ToolContext`, `ToolResult`
-- `SkillDefinition`
-- `AgentConfig`, `AgentInput`, `AgentOptions`, `AgentResult`
-- `LLMConfig`, `LLMMessage`, `LLMResponseChunk`, `LLMStream`
-- `ToolEvent`, `AgentChunk`, `AgentEventEmitter`
-
-## 测试
-
-```bash
-# 运行测试
-bun test
-
-# 运行示例
-bun run example.ts
-```
-
-## 构建和发布
-
-```bash
-# 构建
-bun run build
-
-# 本地测试
-bun run dev
-
-# 发布到 npm
-npm publish
-```
-
-## 设计原则
-
-1. **最小依赖**: 仅依赖 TypeScript，无其他运行时依赖
-2. **接口优先**: 所有核心组件都通过接口定义，易于扩展
-3. **事件驱动**: 使用 EventEmitter 实现流式通知
-4. **类型安全**: 完整的 TypeScript 支持
-5. **零外部耦合**: 不依赖特定的 LLM 提供商或工具实现
-6. **易于测试**: 简单的单元测试和集成测试
-
-## 与 OpenCode 的区别
-
-### OpenCode 实现：
-- 深度集成到项目基础设施（文件系统、权限等）
-- 复杂的会话持久化
-- 与 CLI 和 TUI 深度耦合
-- MCP 协议实现
-- ACP (Agent Client Protocol) 实现
-
-### AgentCore 实现：
-- 纯粹的 agent 逻辑
-- 可在任何项目中独立使用
-- 只提供核心抽象
-- 需要外部实现 LLM provider 和工具
-- 简单的内存会话管理
-
-## 扩展性
-
-### 添加自定义工具：
-
-```typescript
-// 1. 实现工具接口
-const myTool: ToolDefinition = {
-  id: "my_tool",
-  name: "My Tool",
-  description: "Does something useful",
-  parameters: { /* schema */ },
-  async execute(input, context) { /* 实现 */ },
-}
-
-// 2. 注册到 agent
-const config: AgentConfig = {
-  tools: [myTool, /* ...其他工具 */],
-}
-
-const agent = createAgent(config)
-```
-
-### 添加自定义 LLM Provider：
-
-```typescript
-// 1. 实现 LLMProvider 接口
-class MyProvider implements LLMProvider {
-  async stream(config: { /* ... */ }) { /* 实现 */ }
-}
-
-// 2. 创建 agent 时使用
-// 注意：Agent 类默认使用 OpenAIProvider
-// 你需要修改 Agent 类以支持自定义 provider
-```
-
-### 添加技能：
-
-```typescript
-// 1. 定义技能
-const mySkill: SkillDefinition = {
-  id: "my_skill",
-  name: "My Skill",
-  description: "Specialized skill for something",
-  content: /* 技能内容 */,
-}
-
-// 2. 注册到 skill loader
-const loader = agent.getSkillLoader()
-loader.register(mySkill)
-
-// 3. 在工具中加载技能
-const skillTool: ToolDefinition = {
-  id: "load_skill",
-  name: "Load Skill",
-  description: "Load a skill",
-  async execute(input, context) {
-    const skill = await agent.getSkillLoader().load(input.skillId)
-    return {
-      output: skill.content,
-      metadata: { skillId: input.skillId },
-    }
-  },
-}
-
-const config: AgentConfig = {
-  tools: [skillTool, /* ...其他工具 */],
-}
-
-const agent = createAgent(config)
-```
-
-## 未来计划
-
-- [ ] 添加更多 LLM Provider（Anthropic、Google 等）
-- [ ] 实现更复杂的工具系统（插件架构）
-- [ ] 添加持久化支持（存储会话到数据库/文件）
-- [ ] 实现对话上下文窗口管理
-- [ ] 添加 rate limiting（速率限制）
-- [ ] 添加更详细的性能指标
-
-## 许可证
-
-MIT License
-
-## 贡献
-
-欢迎贡献！请遵循以下步骤：
-
-1. Fork 本仓库
-2. 创建特性分支
-3. 提交更改
-4. 推送到分支
-5. 创建 Pull Request
-
-## 联系
-
-如有问题或建议，请提交 issue 到 OpenCode 仓库。