Merge pull request #27 from Gui-Yue/updat_doc

Update doc and fix unit test

Author: CrazyBoyM

.gitignore

@@ -18,6 +18,8 @@ test-cli.ts
 # Ignore all markdown files except README.md and files in doc/docs folders
 *.md
 !README.md
+!README.zh-CN.md
+!ROADMAP.md
 !doc/**/*.md
 !docs/**/*.md
 !tests/**/*.md

README.md

@@ -1,175 +1,84 @@
 # KODE SDK
 
-> **Stateful Agent Runtime Kernel** - The engine that powers your AI agents with persistence, recovery, and trajectory exploration.
+[English](./README.md) | [中文](./README.zh-CN.md)
 
-```
-                    +------------------+
-                    |   Your App       |  CLI / Desktop / IDE / Server
-                    +--------+---------+
-                             |
-                    +--------v---------+
-                    |    KODE SDK      |  Agent Runtime Kernel
-                    |  +-----------+   |
-                    |  |  Agent    |   |  Lifecycle + State + Events
-                    |  +-----------+   |
-                    |  |  Store    |   |  Persistence (Pluggable)
-                    |  +-----------+   |
-                    |  |  Sandbox  |   |  Execution Isolation
-                    |  +-----------+   |
-                    +------------------+
-```
-
----
-
-## What is KODE SDK?
-
-KODE SDK is an **Agent Runtime Kernel** - think of it like V8 for JavaScript, but for AI agents. It handles the complex lifecycle management so you can focus on building your agent's capabilities.
-
-**Core Capabilities:**
-- **Crash Recovery**: WAL-protected persistence with 7-stage breakpoint recovery
-- **Fork & Resume**: Explore different agent trajectories from any checkpoint
-- **Event Streams**: Progress/Control/Monitor channels for real-time UI updates
-- **Tool Governance**: Permission system, approval workflows, audit trails
-
-**What KODE SDK is NOT:**
-- Not a cloud platform (you deploy it)
-- Not an HTTP server (you add that layer)
-- Not a multi-tenant SaaS framework (you build that on top)
-
----
-
-## When to Use KODE SDK
-
-### Perfect Fit (Use directly)
-
-| Scenario | Why It Works |
-|----------|--------------|
-| **CLI Agent Tools** | Single process, local filesystem, zero config |
-| **Desktop Apps** (Electron/Tauri) | Full system access, long-running process |
-| **IDE Plugins** (VSCode/JetBrains) | Single user, workspace integration |
-| **Local Development** | Fast iteration, instant persistence |
-
-### Good Fit (With architecture)
-
-| Scenario | What You Need |
-|----------|---------------|
-| **Self-hosted Server** | Add HTTP layer (Express/Fastify/Hono) |
-| **Small-scale Backend** (<1K users) | Implement PostgresStore, add user isolation |
-| **Kubernetes Deployment** | Implement distributed Store + locks |
-
-### Needs Custom Architecture
-
-| Scenario | Recommended Approach |
-|----------|---------------------|
-| **Large-scale ToC** (10K+ users) | Worker microservice pattern (see [Architecture Guide](./docs/ARCHITECTURE.md)) |
-| **Serverless** (Vercel/Cloudflare) | API layer on serverless + Worker pool for agents |
-| **Multi-tenant SaaS** | Tenant isolation layer + distributed Store |
+> Event-driven, long-running AI Agent framework with enterprise-grade persistence and multi-agent collaboration.
 
-### Not Designed For
+## Features
 
-| Scenario | Reason |
-|----------|--------|
-| **Pure browser runtime** | No filesystem, no process execution |
-| **Edge functions only** | Agent loops need long-running processes |
-| **Stateless microservices** | Agents are inherently stateful |
+- **Event-Driven Architecture** - Three-channel system (Progress/Control/Monitor) for clean separation of concerns
+- **Long-Running & Resumable** - Seven-stage checkpoints with Safe-Fork-Point for crash recovery
+- **Multi-Agent Collaboration** - AgentPool, Room messaging, and task delegation
+- **Enterprise Persistence** - SQLite/PostgreSQL support with unified WAL
+- **Extensible Ecosystem** - MCP tools, custom Providers, Skills system
 
-> **Rule of Thumb**: If your agents need to run for more than a few seconds, execute tools, and remember state - KODE SDK is for you. If you just need stateless LLM calls, use the provider APIs directly.
+## Quick Start
 
----
-
-## 60-Second Quick Start
+**One-liner setup** (install dependencies and build):
 
 ```bash
-npm install @anthropic/kode-sdk
-
-# Set your API key
-export ANTHROPIC_API_KEY=sk-...
-
-# Run the example
-npx ts-node examples/getting-started.ts
-```
-
-```typescript
-import { Agent, AnthropicProvider, LocalSandbox } from '@anthropic/kode-sdk';
-
-const agent = await Agent.create({
-  agentId: 'my-first-agent',
-  template: { systemPrompt: 'You are a helpful assistant.' },
-  deps: {
-    modelProvider: new AnthropicProvider(process.env.ANTHROPIC_API_KEY!),
-    sandbox: new LocalSandbox({ workDir: './workspace' }),
-  },
-});
-
-// Subscribe to events
-agent.subscribeProgress({ kinds: ['text_chunk'] }, (event) => {
-  process.stdout.write(event.text);
-});
-
-// Chat with the agent
-await agent.chat('Hello! What can you help me with?');
+./quickstart.sh
 ```
 
----
-
-## Core Concepts
+Or install as a dependency:
 
-### 1. Three-Channel Event System
-
-```
-+-------------+     +-------------+     +-------------+
-|  Progress   |     |   Control   |     |   Monitor   |
-+-------------+     +-------------+     +-------------+
-| text_chunk  |     | permission  |     | tool_audit  |
-| tool:start  |     | _required   |     | state_change|
-| tool:complete|    | approval    |     | token_usage |
-| done        |     | _response   |     | error       |
-+-------------+     +-------------+     +-------------+
-      |                   |                   |
-      v                   v                   v
-   Your UI         Approval Service     Observability
+```bash
+npm install @shareai-lab/kode-sdk
 ```
 
-### 2. Crash Recovery & Breakpoints
+Set environment variables:
 
+<!-- tabs:start -->
+#### **Linux / macOS**
+```bash
+export ANTHROPIC_API_KEY=sk-...
+export ANTHROPIC_MODEL_ID=claude-sonnet-4-20250514  # optional, default: claude-sonnet-4-20250514
+export ANTHROPIC_BASE_URL=https://api.anthropic.com  # optional, default: https://api.anthropic.com
 ```
-Agent Execution Flow:
-
-  READY -> PRE_MODEL -> STREAMING -> TOOL_PENDING -> PRE_TOOL -> EXECUTING -> POST_TOOL
-    |         |            |             |              |           |           |
-    +-------- WAL Protected State -------+-- Approval --+---- Tool Execution ---+
 
-On crash: Resume from last safe breakpoint, auto-seal incomplete tool calls
+#### **Windows (PowerShell)**
+```powershell
+$env:ANTHROPIC_API_KEY="sk-..."
+$env:ANTHROPIC_MODEL_ID="claude-sonnet-4-20250514"  # optional, default: claude-sonnet-4-20250514
+$env:ANTHROPIC_BASE_URL="https://api.anthropic.com"  # optional, default: https://api.anthropic.com
 ```
+<!-- tabs:end -->
 
-### 3. Fork & Trajectory Exploration
+Minimal example:
 
 ```typescript
-// Create a snapshot at current state
-const snapshotId = await agent.snapshot('before-decision');
+import { Agent, AnthropicProvider, JSONStore } from '@shareai-lab/kode-sdk';
 
-// Fork to explore different paths
-const explorerA = await agent.fork(snapshotId);
-const explorerB = await agent.fork(snapshotId);
+const provider = new AnthropicProvider(
+  process.env.ANTHROPIC_API_KEY!,
+  process.env.ANTHROPIC_MODEL_ID
+);
 
-await explorerA.chat('Try approach A');
-await explorerB.chat('Try approach B');
-```
+const agent = await Agent.create({
+  provider,
+  store: new JSONStore('./.kode'),
+  systemPrompt: 'You are a helpful assistant.'
+});
 
----
+// Subscribe to progress events
+for await (const envelope of agent.subscribe(['progress'])) {
+  if (envelope.event.type === 'text_chunk') {
+    process.stdout.write(envelope.event.delta);
+  }
+  if (envelope.event.type === 'done') break;
+}
 
-## Examples
+await agent.send('Hello!');
+```
 
-| Example | Description | Key Features |
-|---------|-------------|--------------|
-| `npm run example:getting-started` | Minimal chat loop | Progress stream, basic setup |
-| `npm run example:agent-inbox` | Event-driven inbox | Todo management, tool concurrency |
-| `npm run example:approval` | Approval workflow | Control channel, hooks, policies |
-| `npm run example:room` | Multi-agent collaboration | AgentPool, Room, Fork |
-| `npm run example:scheduler` | Long-running with reminders | Scheduler, step triggers |
-| `npm run example:nextjs` | Next.js API integration | Resume-or-create, SSE streaming |
+Run examples:
 
----
+```bash
+npm run example:getting-started    # Minimal chat
+npm run example:agent-inbox        # Event-driven inbox
+npm run example:approval           # Tool approval workflow
+npm run example:room               # Multi-agent collaboration
+```
 
 ## Architecture for Scale
 
@@ -209,76 +118,36 @@ For production deployments serving many users, we recommend the **Worker Microse
 3. **Store is shared** - Single source of truth for agent state
 4. **Queue decouples** - Request handling from agent execution
 
-See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for detailed deployment guides.
-
----
-
-## Documentation
-
-| Document | Description |
-|----------|-------------|
-| [Architecture Guide](./docs/ARCHITECTURE.md) | Mental model, deployment patterns, scaling strategies |
-| [Quickstart](./docs/quickstart.md) | Step-by-step first agent |
-| [Events System](./docs/events.md) | Three-channel event model |
-| [API Reference](./docs/api.md) | Core types and interfaces |
-| [Playbooks](./docs/playbooks.md) | Common patterns and recipes |
-| [Deployment](./docs/DEPLOYMENT.md) | Production deployment guide |
-| [Roadmap](./docs/ROADMAP.md) | Future development plans |
-
-### Scenario Guides
-
-| Scenario | Guide |
-|----------|-------|
-| CLI Tools | [docs/scenarios/cli-tools.md](./docs/scenarios/cli-tools.md) |
-| Desktop Apps | [docs/scenarios/desktop-apps.md](./docs/scenarios/desktop-apps.md) |
-| IDE Plugins | [docs/scenarios/ide-plugins.md](./docs/scenarios/ide-plugins.md) |
-| Web Backend | [docs/scenarios/web-backend.md](./docs/scenarios/web-backend.md) |
-| Large-scale ToC | [docs/scenarios/large-scale-toc.md](./docs/scenarios/large-scale-toc.md) |
-
----
+See [docs/en/guides/architecture.md](./docs/en/guides/architecture.md) for detailed deployment guides.
 
 ## Supported Providers
 
-| Provider | Streaming | Tool Calling | Thinking/Reasoning |
-|----------|-----------|--------------|-------------------|
-| **Anthropic** | SSE | Native | Extended Thinking |
-| **OpenAI** | SSE | Function Calling | o1/o3 reasoning |
-| **Gemini** | SSE | Function Calling | thinkingLevel |
-| **DeepSeek** | SSE | OpenAI-compatible | reasoning_content |
-| **Qwen** | SSE | OpenAI-compatible | thinking_budget |
-| **Groq/Cerebras** | SSE | OpenAI-compatible | - |
-
----
-
-## Roadmap
+| Provider | Streaming | Tools | Reasoning | Files |
+|----------|-----------|-------|-----------|-------|
+| Anthropic | ✅ | ✅ | ✅ Extended Thinking | ✅ |
+| OpenAI | ✅ | ✅ | ✅ | ✅ |
+| Gemini | ✅ | ✅ | ✅ | ✅ |
 
-### v2.8 - Storage Foundation
-- PostgresStore with connection pooling
-- Distributed locking (Advisory Lock)
-- Graceful shutdown support
+> **Note**: OpenAI-compatible services (DeepSeek, GLM, Qwen, Minimax, OpenRouter, etc.) can be used via `OpenAIProvider` with custom `baseURL` configuration. See [Providers Guide](./docs/en/guides/providers.md) for details.
 
-### v3.0 - Performance
-- Incremental message storage (append-only)
-- Copy-on-Write fork optimization
-- Event sampling and aggregation
-
-### v3.5 - Distributed
-- Agent Scheduler with LRU caching
-- Distributed EventBus (Redis Pub/Sub)
-- Worker mode helpers
-
-See [docs/ROADMAP.md](./docs/ROADMAP.md) for the complete roadmap.
-
----
-
-## Contributing
+## Documentation
 
-We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+| Section | Description |
+|---------|-------------|
+| **Getting Started** | |
+| [Installation](./docs/en/getting-started/installation.md) | Setup and configuration |
+| [Quickstart](./docs/en/getting-started/quickstart.md) | Build your first Agent |
+| [Concepts](./docs/en/getting-started/concepts.md) | Core concepts explained |
+| **Guides** | |
+| [Events](./docs/en/guides/events.md) | Three-channel event system |
+| [Tools](./docs/en/guides/tools.md) | Built-in tools & custom tools |
+| [Providers](./docs/en/guides/providers.md) | Model provider configuration |
+| [Database](./docs/en/guides/database.md) | SQLite/PostgreSQL persistence |
+| [Resume & Fork](./docs/en/guides/resume-fork.md) | Crash recovery & branching |
+| **Reference** | |
+| [API Reference](./docs/en/reference/api.md) | Complete API documentation |
+| [Examples](./docs/en/examples/playbooks.md) | All examples explained |
 
 ## License
 
-MIT License - see [LICENSE](./LICENSE) for details.
-
----
-
-**KODE SDK** - *The runtime kernel that lets you build agents that persist, recover, and explore.*
+MIT