goatchain 0.0.2 → 0.0.3

package/README.zh.md

@@ -0,0 +1,430 @@
+# GoatChain 🐐
+
+> 轻量级、可扩展的 TypeScript SDK，用于构建具有流式支持、工具调用和中间件模式的 AI 代理。
+
+[![npm version](https://badge.fury.io/js/goatchain.svg)](https://badge.fury.io/js/goatchain)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[English Documentation](../README.md)
+
+## ✨ 特性
+
+- **🔄 代理循环** - 自动工具调用循环，可配置最大迭代次数
+- **📡 流式优先** - 实时流式响应，包含详细事件
+- **🧅 中间件模式** - Koa 风格的洋葱模型，支持可扩展钩子
+- **🔧 工具系统** - 易于使用的工具注册和执行
+- **💾 状态管理** - 两级状态存储（代理 + 会话级别）
+- **📸 快照/恢复** - 代理和会话的完整持久化支持
+- **🎯 TypeScript 原生** - 完整的类型安全和全面的类型导出
+
+## 📦 安装
+
+```bash
+pnpm add goatchain
+```
+
+## 🚀 快速开始
+
+最简单的 Agent Loop 示例：
+
+```typescript
+import process from 'node:process'
+import { Agent, createModel, createOpenAIAdapter } from 'goatchain'
+
+// 创建模型
+const model = createModel({
+  adapter: createOpenAIAdapter({
+    defaultModelId: 'gpt-4o',
+    apiKey: process.env.OPENAI_API_KEY!,
+  }),
+})
+
+// 创建 Agent
+const agent = new Agent({
+  name: 'Simple Assistant',
+  systemPrompt: 'You are a helpful assistant.',
+  model,
+})
+
+// 流式处理响应
+const session = await agent.createSession()
+session.send('Hello!')
+for await (const event of session.receive()) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta)
+  } else if (event.type === 'done') {
+    console.log('\n完成:', event.stopReason)
+  }
+}
+```
+
+📖 **详细文档**: 查看 [docs/getting-started.md](./docs/getting-started.md) 了解更多示例和完整指南。
+
+## 🧰 CLI
+
+全局安装 `goatchain-cli` 后（或在此仓库中使用 `pnpm -s cli`），运行：
+
+```bash
+goatchain
+```
+
+常用选项：
+
+- `-k, --api-key <key>`（或设置 `OPENAI_API_KEY`）
+- `-m, --model <id>`
+- `--base-url <url>`
+- `--max-tokens <n>`
+- `--temperature <n>`
+
+命令：
+
+- `/help` 帮助
+- `/model <id>` 切换模型 ID（OpenAI）
+- `/plan [on|off|toggle]` 切换计划模式（计划 → 确认 → 执行）
+- `/approvals` 选择审批模式（交互式）
+- `/set <k> <v>` 设置请求参数（例如 `temperature`、`maxTokens`）
+- `/unset <k>` 清除请求参数
+- `/params` 显示当前请求参数
+- `/base-url <url>` 设置基础 URL
+- `/api-key <key>` 设置 API 密钥（不显示）
+- `/web-search-key <key>` 设置 WebSearch 工具的 Serper API 密钥（不显示）
+- `/tools` 列出启用的工具（Read/Write/Edit/Glob/Grep/WebSearch*）
+- `/sessions` 列出并选择保存的会话
+- `/use <sessionId>` 恢复已保存的会话（打印最近历史）
+- `/save` 持久化当前配置/会话
+- `/status` 显示当前模型/会话信息
+- `/new` 开始新对话（清除历史）
+
+需要环境变量 `OPENAI_API_KEY`。
+
+网络搜索（可选）：
+
+- 设置 `SERPER_API_KEY`（或 `GOATCHAIN_SERPER_API_KEY`）以启用内置的 `WebSearch` 工具获取最新信息，如天气
+- 在交互模式下，可以运行 `/web-search-key <key>` 将密钥持久化到工作区配置中
+- 也可以在 `./.goatchain/config.json` 中设置（工作区范围，gitignore）：
+  - `{"tools":{"webSearch":{"apiKey":"...","apiEndpoint":"...","numResults":10}}}`
+
+计划模式（交互式规划）：
+
+- 使用 `/plan on` 启用，进入计划优先的工作流程：
+  1. 代理探索代码库并研究您的请求
+  2. 代理可能使用 `AskUserQuestion` 工具询问澄清问题以了解您的偏好（例如库选择、架构决策）
+  3. 代理使用 `TodoPlan` 创建结构化计划（3-8 步）
+  4. 您审查并批准计划
+  5. 代理执行批准的计划
+- 规划期间，文件修改被阻止（只读阶段）
+- 设置 `GOATCHAIN_PLAN_MODE=1` 或在 `.goatchain/config.json` 中配置以默认启用
+
+本地持久化（工作区范围）：
+
+- 配置和会话保存在 `./.goatchain/` 下（自动创建）
+- `.goatchain/` 被 gitignore 以避免意外提交密钥
+
+DeepSeek 思考模式兼容性：
+
+- 一些 OpenAI 兼容的网关（例如 DeepSeek 思考模式）要求包含 `tool_calls` 的助手消息上存在 `reasoning_content`（可能拒绝空字符串）。GoatChain 会在可用时附加累积的思考内容
+- 如果您通过 GoatChain 无法从 `baseUrl`/`modelId` 检测到的代理使用 DeepSeek，可以显式启用：
+  - 交互式：运行 `/settings` 并切换"交错思考 (Interleaved Thinking)"
+  - 配置文件：在 `./.goatchain/config.json` 中设置 `openai.compat.interleavedThinking=true`
+
+## 🏗️ 架构
+
+```mermaid
+classDiagram
+    direction TB
+
+	    class Agent {
+	        +id: string
+	        +name: string
+	        +systemPrompt: string
+	        +model: ModelClient
+	        +tools: ToolRegistry
+	        +stateStore: StateStore
+	        +sessionManager: BaseSessionManager
+	        +stats: AgentStats
+	        +use(middleware): this
+	        +createSession(options): BaseSession
+	        +resumeSession(sessionId, options): BaseSession
+	        +setModel(modelOrRef): void
+	    }
+
+	    class ModelClient {
+	        <<interface>>
+	        +modelId: string
+	      +stream(request): AsyncIterable~ModelStreamEvent~
+	      +run?(request): Promise~ModelRunResult~
+	    }
+
+    class StateStore {
+        <<interface>>
+        +savePoint: string
+        +deleteOnComplete: boolean
+        +saveCheckpoint(checkpoint): Promise~void~
+        +loadCheckpoint(sessionId): Promise~AgentLoopCheckpoint~
+        +deleteCheckpoint(sessionId): Promise~void~
+        +listCheckpoints(): Promise~AgentLoopCheckpoint[]~
+    }
+
+    class BaseTool {
+        <<abstract>>
+        +name: string
+        +description: string
+        +parameters: JSONSchema
+      +execute(args, ctx?): Promise~unknown~
+    }
+
+    class ToolRegistry {
+        +register(tool): void
+        +unregister(name): boolean
+        +get(name): BaseTool
+        +list(): BaseTool[]
+        +toOpenAIFormat(): OpenAITool[]
+    }
+
+    class BaseSession {
+        <<abstract>>
+        +id: string
+        +status: SessionStatus
+        +messages: Message[]
+        +usage: Usage
+        +configOverride: SessionConfigOverride
+        +addMessage(message): void
+        +save(): Promise~void~
+        +toSnapshot(): SessionSnapshot
+        +restoreFromSnapshot(snapshot): void
+    }
+
+    class BaseSessionManager {
+        <<abstract>>
+        +create(sessionId?): Promise~BaseSession~
+        +get(sessionId): Promise~BaseSession~
+        +list(): Promise~BaseSession[]~
+        +destroy(sessionId): Promise~void~
+    }
+
+    class Middleware {
+        <<function>>
+        (ctx: AgentLoopState, next: NextFunction) => Promise~void~
+    }
+
+    class AgentLoopState {
+        +sessionId: string
+        +messages: Message[]
+        +iteration: number
+        +pendingToolCalls: ToolCallWithResult[]
+        +currentResponse: string
+        +shouldContinue: boolean
+        +usage: Usage
+    }
+
+    Agent --> ModelClient : uses
+    Agent --> ToolRegistry : uses
+    Agent --> StateStore : uses
+    Agent --> BaseSessionManager : uses
+    Agent ..> Middleware : applies
+    Agent ..> AgentLoopState : manages
+    ToolRegistry --> BaseTool : contains
+    BaseSessionManager --> BaseSession : manages
+```
+
+## 🧅 中间件模式
+
+GoatChain 使用 Koa 风格的洋葱模型作为中间件。每个中间件围绕核心执行进行包装：
+
+```
+outer:before → inner:before → exec (model.stream) → inner:after → outer:after
+```
+
+### 命名中间件
+
+中间件可以有名字，方便管理和移除：
+
+```typescript
+// 添加命名中间件（推荐）
+agent.use(async (state, next) => {
+  const start = Date.now()
+  console.log(`[${state.iteration}] 模型调用前`)
+  const nextState = await next(state)
+  console.log(`[${state.iteration}] 模型调用后 (${Date.now() - start}ms)`)
+  return nextState
+}, 'logging')
+
+// 通过名字移除
+agent.removeMiddleware('logging')
+
+// 查看所有中间件名字
+console.log(agent.middlewareNames) // ['logging', 'compression', ...]
+
+// 使用 unsubscribe 函数
+const unsubscribe = agent.use(middleware, 'temp')
+unsubscribe() // 移除中间件
+```
+
+### 内置中间件的默认名字
+
+GoatChain 的内置中间件工厂函数会自动提供默认名字：
+
+```typescript
+// 计划模式中间件 - 自动命名为 'plan-mode'
+agent.use(createPlanModeMiddleware())
+
+// 上下文压缩中间件 - 自动命名为 'context-compression'
+agent.use(createContextCompressionMiddleware({
+  maxTokens: 128000,
+}))
+
+// 查看所有中间件
+console.log(agent.middlewareNames)
+// 输出: ['plan-mode', 'context-compression']
+
+// 通过默认名字移除
+agent.removeMiddleware('plan-mode')
+
+// 或者自定义名字
+agent.use(createPlanModeMiddleware({ name: 'my-plan' }))
+agent.use(createContextCompressionMiddleware({
+  maxTokens: 128000,
+}), 'my-compression') // 覆盖默认名字
+```
+
+### 中间件示例
+
+```typescript
+// 日志中间件
+agent.use(async (state, next) => {
+  const start = Date.now()
+  console.log(`[${state.iteration}] 模型调用前`)
+
+  const nextState = await next(state) // 执行模型流
+
+  console.log(`[${state.iteration}] 模型调用后 (${Date.now() - start}ms)`)
+  return nextState
+}, 'logging')
+
+// 错误处理中间件
+agent.use(async (state, next) => {
+  try {
+    return await next(state)
+  }
+  catch (error) {
+    state.shouldContinue = false
+    state.stopReason = 'error'
+    state.error = error
+    return state
+  }
+}, 'error-handler')
+
+// 速率限制中间件
+agent.use(async (state, next) => {
+  await rateLimiter.acquire()
+  return next(state)
+}, 'rate-limiter')
+```
+
+## 📡 事件类型
+
+会话接收流发出以下事件：
+
+| 事件             | 描述                           |
+| ----------------- | ------------------------------------- |
+| `iteration_start` | 循环迭代开始         |
+| `text_delta`      | LLM 的部分文本响应        |
+| `thinking_start`  | 思考阶段开始（如果支持）  |
+| `thinking_delta`  | 思考内容增量（如果支持） |
+| `thinking_end`    | 思考阶段结束（如果支持）    |
+| `tool_call_start` | 工具调用开始                      |
+| `tool_call_delta` | 工具调用参数增量             |
+| `tool_call_end`   | 工具调用完成                 |
+| `tool_result`     | 工具执行完成              |
+| `iteration_end`   | 循环迭代结束（包括使用量） |
+| `done`            | 流完成（包括使用量）        |
+| `error`           | 发生错误                        |
+
+```typescript
+interface AgentEvent {
+  type:
+    | 'text_delta'
+    | 'tool_call_start'
+    | 'tool_call_delta'
+    | 'tool_call_end'
+    | 'tool_result'
+    | 'thinking_start'
+    | 'thinking_delta'
+    | 'thinking_end'
+    | 'error'
+    | 'done'
+    | 'iteration_start'
+    | 'iteration_end'
+  // ... 事件特定字段
+}
+```
+
+`iteration_end` 和 `done` 事件包括可选的 `usage: Usage`，包含累积的令牌计数。
+
+## 💾 检查点与恢复
+
+内置检查点支持，用于恢复中断的代理执行：
+
+```typescript
+import { Agent, FileStateStore } from 'goatchain'
+
+// 创建带配置的状态存储
+const stateStore = new FileStateStore({
+  dir: './checkpoints',
+  savePoint: 'before', // 每次迭代前保存
+  deleteOnComplete: true, // 成功完成后清理
+})
+
+// 提供 stateStore 时，代理自动保存检查点
+const agent = new Agent({
+  name: 'MyAgent',
+  systemPrompt: 'You are helpful.',
+  model,
+  stateStore,
+})
+
+// 运行代理 - 检查点自动保存
+const session = await agent.createSession()
+session.send('Hello')
+for await (const event of session.receive()) {
+  console.log(event)
+}
+
+// 如果中断，从检查点恢复
+const checkpoint = await stateStore.loadCheckpoint(session.id)
+if (checkpoint) {
+  const resumed = await agent.resumeSession(session.id)
+  for await (const event of resumed.receive()) {
+    console.log(event)
+  }
+}
+```
+
+可用的状态存储：
+
+- `FileStateStore` - 基于文件的持久化
+- `InMemoryStateStore` - 内存中（用于测试）
+
+## 📖 API 参考
+
+### Agent
+
+| 方法                          | 描述             |
+| ------------------------------- | ----------------------- |
+| `constructor(options)`          | 创建新代理      |
+| `use(middleware)`               | 添加中间件          |
+| `createSession(options)`        | 创建会话        |
+| `resumeSession(sessionId, options)` | 恢复会话    |
+| `setModel(modelOrRef)`          | 运行时切换/固定模型 |
+
+### Session
+
+| 方法                  | 描述                                  |
+| ----------------------- | -------------------------------------------- |
+| `send(input, options?)` | 将输入排队到会话                  |
+| `receive(options?)`     | 流式事件，如果存在检查点则从中恢复 |
+| `messages`              | 对话历史                         |
+
+## 📄 许可证
+
+MIT © [Simon He](https://github.com/Simon-He95)