formagent-sdk 0.1.0 → 0.1.1

package/docs/README.md

@@ -0,0 +1,122 @@
+# 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

@@ -0,0 +1,516 @@
+# 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 仓库。