@fllf/agent-sdk 0.1.2 → 0.1.3

package/README.md

@@ -1,73 +1,34 @@
 # FAgent Agent SDK
 
-FAgent is a composable TypeScript SDK for building LLM agents, tool-calling
-workflows, and RAG-powered chat systems.
+FAgent Agent SDK 是一个可组合的 TypeScript Agent 运行时基础库，用于在第三方系统中接入：
 
-The published npm package is:
+- LLM 对话与流式输出。
+- OpenAI、Anthropic、OpenAI-compatible 本地/网关模型。
+- 工具调用 Agent，含并发工具执行、工具错误回传、工具调用流式事件。
+- 多模态消息内容：文本、图片 URL、图片 base64。
+- 会话级消息历史、上下文窗口截断、可选历史摘要压缩。
+- RAG 文档 ingestion、切块、embedding、检索、rerank、上下文构建、答案生成与引用校验。
+- 内存存储与 Postgres/pgvector 参考存储。
+- 运行时事件、错误类型与下游测试辅助工具。
+
+本 SDK 只提供运行时与扩展点；不包含 Web UI、用户体系、鉴权、业务数据库迁移、部署脚本或产品级限流。
+
+## 安装
 
 ```bash
 npm install @fllf/agent-sdk
 ```
 
-Use it as the runtime core behind a web chat product, backend API, worker, or
-third-party integration layer. The SDK does not include a web UI, database
-migrations for your application, authentication, or deployment code.
-
-## Capabilities
-
-- Composable `Agent` runtime.
-- Unified `LLM.chat()` interface.
-- OpenAI and OpenAI-compatible local providers.
-- Streaming through `LLM.stream()`.
-- Timeout, retry, abort, and normalized LLM errors.
-- `generateObject()` structured output with Zod validation.
-- Session-scoped message history.
-- Simple chat, tool-calling, and RAG executors.
-- Zod-driven tool definitions.
-- RAG ingestion, chunking, embedding, retrieval, reranking, context building,
-  generation, and verification.
-- In-memory stores for development and tests.
-- Postgres RAG store adapters that work with any compatible `query()` client.
-- Observer events for logging, tracing, and debugging.
-
-## Runtime requirements
-
-- Node.js 18 or newer.
-- TypeScript is recommended for typed integration.
-- Install optional document conversion dependencies only if you use those
-  loaders:
+运行要求：
+
+- Node.js 18 或更高版本。
+- 推荐使用 TypeScript。
+- RAG 文档转换按需安装可选依赖：
   - HTML: `turndown`, `turndown-plugin-gfm`
   - DOCX: `mammoth`
   - PDF: `pdf-parse`
 
-## Environment variables
-
-OpenAI:
-
-```bash
-OPENAI_API_KEY=...
-OPENAI_MODEL=gpt-4o-mini
-OPENAI_BASE_URL=https://api.openai.com/v1
-OPENAI_EMBEDDING_MODEL=text-embedding-3-small
-```
-
-OpenAI-compatible local runtime, such as Ollama, LM Studio, vLLM, or a gateway:
-
-```bash
-LOCAL_BASE_URL=http://127.0.0.1:11434/v1
-LOCAL_MODEL=llama3
-LOCAL_API_KEY=local-key
-```
-
-If no OpenAI key is configured, the default `LLM` auto-detection falls back to
-the local OpenAI-compatible provider.
-
-`OPENAI_BASE_URL` also applies to `OpenAIEmbedder`. For OpenAI-compatible
-embedding providers, configure it as the API root, for example
-`https://gateway.example.test/v1`; the SDK posts embedding requests to
-`{OPENAI_BASE_URL}/embeddings`.
-
-## Basic chat integration
+## 快速开始
 
 ```ts
 import { Agent } from '@fllf/agent-sdk';
@@ -87,13 +48,10 @@ const result = await agent.run('How do I reset my password?', {
 });
 
 console.log(result.output);
+console.log(result.usage);
 ```
 
-### Suggested HTTP contract
-
-Your API layer owns authentication, authorization, persistence, rate limits, and
-request validation. A typical chat endpoint can adapt incoming requests to
-`Agent.run()`:
+第三方 HTTP 服务通常只需要把自己的认证、租户、会话和用户输入转换为 `Agent.run()`：
 
 ```ts
 import { Agent } from '@fllf/agent-sdk';
@@ -103,10 +61,10 @@ const agent = new Agent({
   requireSessionId: true,
 });
 
-export async function handleChatRequest(body: {
-  conversationId: string;
-  userId: string;
+export async function handleChat(body: {
   tenantId: string;
+  userId: string;
+  conversationId: string;
   message: string;
 }) {
   const sessionId = `${body.tenantId}:${body.userId}:${body.conversationId}`;
@@ -116,6 +74,7 @@ export async function handleChatRequest(body: {
     metadata: {
       tenantId: body.tenantId,
       userId: body.userId,
+      conversationId: body.conversationId,
     },
   });
 
@@ -126,54 +85,269 @@ export async function handleChatRequest(body: {
 }
 ```
 
-Recommended request body:
+建议第三方系统自己负责：
+
+- 登录态、租户边界、权限校验。
+- 外部 API 输入校验与限流。
+- 持久化用户、会话、消息、审计日志。
+- 日志脱敏与成本控制。
+
+## 模型与环境变量
+
+`LLM` 默认自动探测 provider：
+
+1. 存在 `OPENAI_API_KEY` 时使用 `openai`。
+2. 否则存在 `ANTHROPIC_API_KEY` 时使用 `anthropic`。
+3. 否则使用 `local`，即 OpenAI-compatible 本地服务。
+
+### OpenAI
+
+```bash
+OPENAI_API_KEY=...
+OPENAI_MODEL=gpt-4o-mini
+OPENAI_BASE_URL=https://api.openai.com/v1
+OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+```
+
+官方 OpenAI provider 会把 `maxTokens` 映射为 `max_completion_tokens`，流式请求会启用 usage 回传。
+`OpenAIEmbedder` 也会读取 `OPENAI_API_KEY`、`OPENAI_BASE_URL` 和 `OPENAI_EMBEDDING_MODEL`；
+兼容服务应把 `OPENAI_BASE_URL` 配为 API root，SDK 会请求 `{baseURL}/embeddings`。
+
+### Anthropic
+
+```bash
+ANTHROPIC_API_KEY=...
+ANTHROPIC_MODEL=claude-opus-4-8
+ANTHROPIC_BASE_URL=
+```
+
+Anthropic provider 支持 Messages API、多模态、工具调用、流式输出、结构化输出、reasoning effort、prompt cache usage 字段和 `tool_result.is_error`。
+
+### 本地或网关 OpenAI-compatible 服务
+
+适用于 Ollama、LM Studio、vLLM 或统一网关：
+
+```bash
+LOCAL_BASE_URL=http://127.0.0.1:11434/v1
+LOCAL_MODEL=llama3
+LOCAL_API_KEY=local-key
+```
+
+### SDK 运行参数
+
+`Config.fromEnv()` 支持：
+
+```bash
+MODEL=
+MODEL_PROVIDER=
+TEMPERATURE=
+MAX_TOKENS=
+MAX_INPUT_TOKENS=
+REQUEST_TIMEOUT_MS=
+MAX_RETRIES=
+RETRY_DELAY_MS=
+RETRY_MAX_DELAY_MS=
+MAX_HISTORY_LENGTH=
+DEBUG=
+LOG_LEVEL=
+```
+
+示例：
+
+```ts
+import { Config } from '@fllf/agent-sdk';
+
+const config = Config.fromEnv({
+  onWarning: (warning) => logger.warn({ warning }, 'invalid SDK env var'),
+});
 
-```json
-{
-  "conversationId": "conversation_1001",
-  "userId": "user_42",
-  "tenantId": "tenant_1",
-  "message": "How do I reset my password?"
+if (config.envWarnings.length > 0) {
+  // 按业务策略决定继续启动或失败退出。
 }
 ```
 
-Recommended response body:
+`Config.fromEnv({ strict: true })` 在环境变量非法时抛出 `ConfigError`。SDK 不会自动打印非法值。
+
+注意：`temperature` 没有默认值；未显式配置时不下发，让模型/provider 使用自身默认值。
+
+## Agent 核心用法
+
+### 构造参数
+
+常用 `Agent` 组件：
+
+```ts
+import {
+  Agent,
+  Config,
+  InMemoryMessageHistoryStore,
+  SimpleChatExecutor,
+} from '@fllf/agent-sdk';
+
+const agent = new Agent({
+  name: 'agent-name',
+  llmConfig: { provider: 'openai', model: 'gpt-4o-mini' },
+  config: new Config({
+    maxHistoryLength: 100,
+    maxInputTokens: 8000,
+    requestTimeoutMs: 60_000,
+    maxRetries: 2,
+  }),
+  historyStore: new InMemoryMessageHistoryStore(),
+  executor: new SimpleChatExecutor(),
+  systemPrompt: 'You are helpful.',
+  requireSessionId: true,
+});
+```
+
+可替换组件包括：
+
+- `llm`: 任意实现 `ChatModel` 的模型适配器。
+- `historyStore`: 任意实现 `MessageHistoryStore` 的历史存储。
+- `executor`: `SimpleChatExecutor`、`ToolCallingExecutor`、`RagExecutor` 或自定义 executor。
+- `tools`: `Tool[]` 或 `ToolRegistry`。
+- `observer`: 运行时事件接收器。
+- `contextCompressor`: 超出 `maxInputTokens` 时的历史压缩器。
+- `hooks`: `beforeRun`、`afterRun`、`onRunError` 生命周期钩子。
+- `runIdFactory`: 自定义 run id 生成器。
+
+### run 选项与返回值
+
+```ts
+const result = await agent.run('hello', {
+  sessionId: 'tenant:user:conversation',
+  runId: 'optional-fixed-run-id',
+  model: 'gpt-4o-mini',
+  temperature: 0.2,
+  maxTokens: 1024,
+  timeoutMs: 30_000,
+  maxRetries: 1,
+  systemPrompt: 'Override this run only.',
+  signal: abortController.signal,
+  metadata: { tenantId: 'tenant_1' },
+});
+```
+
+`AgentRunOptions` 会在执行前校验；非法数值、空 `runId` 或非普通对象 `metadata` 会抛 `AgentExecutionError`，code 为 `invalid_agent_run_options`。
+
+返回值：
+
+```ts
+type AgentResult = {
+  output: string;
+  messages: Message[];
+  usage?: TokenUsage;
+  raw?: unknown;
+};
+```
+
+`raw` 由 executor 决定：
+
+- simple chat: provider 原始响应。
+- tool calling: 最近一次模型原始响应。
+- RAG: `RagAnswer`。
+
+### 会话与历史
+
+`Agent` 实例可复用。`sessionId` 决定会话上下文：
+
+```ts
+await agent.run('Hi', { sessionId: 'tenant_1:user_1:conv_a' });
+await agent.run('New conversation', { sessionId: 'tenant_1:user_1:conv_b' });
+```
+
+同一 `sessionId` 的 run/stream/add/clear/get 操作在进程内串行化，避免消息顺序错乱。不同 session 可并发。
 
-```json
-{
-  "message": "Open the account settings page and choose Reset password.",
-  "usage": {
-    "promptTokens": 120,
-    "completionTokens": 30,
-    "totalTokens": 150
+生产接入建议：
+
+- 设置 `requireSessionId: true`。
+- session id 由租户、用户、会话 id 共同组成。
+- 开发/测试可使用内存历史；生产应接入持久化 `MessageHistoryStore`。
+
+## 流式输出
+
+`Agent.stream()` 返回 `AsyncIterable<AgentStreamEvent>`。
+
+```ts
+const agent = new Agent({ name: 'streaming-chat' });
+
+for await (const event of agent.stream('Write a short summary.', {
+  sessionId: 'tenant_1:user_42:conversation_stream',
+})) {
+  if (event.type === 'agent:text_delta') {
+    process.stdout.write(event.delta ?? '');
+  }
+  if (event.type === 'agent:end') {
+    console.log('\nfinal:', event.output);
   }
 }
 ```
 
-## Sessions and message history
+事件类型：
+
+- `agent:start`
+- `agent:text_delta`
+- `agent:tool_call`
+- `agent:tool_result`
+- `agent:end`
+- `agent:error`
+
+流式行为：
+
+- `SimpleChatExecutor` 支持流式，但要求模型实现 `stream()` 并声明 streaming capability。
+- `ToolCallingExecutor` 支持工具调用流式；模型支持流式时聚合 tool call delta，模型不支持流式时会退化为一次非流式 `chat()` 并整体输出。
+- `RagExecutor` 当前只实现非流式 `run()`。
+- 流式成功完成后才提交本轮 user/assistant 消息；中途失败或 abort 时不会提交未完成的 simple-chat 轮次。
 
-`Agent` is reusable. `sessionId` selects a conversation context.
+工具调用流式会额外产生：
 
 ```ts
-await agent.run('Hi', { sessionId: 'tenant_1:user_42:conversation_a' });
-await agent.run('Start another conversation', {
-  sessionId: 'tenant_1:user_42:conversation_b',
+if (event.type === 'agent:tool_call') {
+  console.log(event.toolCall);
+}
+if (event.type === 'agent:tool_result') {
+  console.log(event.toolResult?.isError, event.toolResult?.content);
+}
+```
+
+## 多模态消息
+
+消息内容类型为：
+
+```ts
+type MessageContent = string | ContentBlock[];
+```
+
+示例：
+
+```ts
+import { Agent, imageUrlBlock, textBlock } from '@fllf/agent-sdk';
+
+await agent.run([
+  textBlock('Describe this image.'),
+  imageUrlBlock('https://example.test/image.png'),
+], {
+  sessionId: 'tenant:user:conv',
 });
 ```
 
-Runs from different sessions can proceed concurrently. Runs for the same session
-are serialized so message order remains stable.
+也可使用 base64：
 
-For production APIs, set `requireSessionId: true` and pass an explicit
-tenant/user/conversation scoped session id. The built-in
-`InMemoryMessageHistoryStore` is suitable for development and tests. Production
-systems should provide a persistent `MessageHistoryStore`.
+```ts
+import { imageBase64Block } from '@fllf/agent-sdk';
+
+const image = imageBase64Block('image/png', base64Data);
+```
 
-## Tool calling
+Provider 行为：
 
-Tools are defined with Zod schemas. The SDK converts the schema into an
-OpenAI-compatible tool schema and validates model-supplied arguments before
-running the tool.
+- OpenAI/OpenAI-compatible：user 多模态映射为 `image_url`；assistant/tool 非文本内容会降级为文本占位。
+- Anthropic：user 图片映射为 Anthropic image block；tool 结果可携带 `is_error`。
+- 不支持 vision 的 provider 会在 capability 检查或 provider 侧失败；第三方系统应按模型能力选择输入。
+
+## 工具调用
+
+工具通过 Zod schema 定义。SDK 会把 schema 转成 provider-neutral tool definition，并在执行前校验模型传入参数。
 
 ```ts
 import { z } from 'zod';
@@ -190,6 +364,8 @@ class AddTool extends Tool<typeof AddToolSchema, number> {
       name: 'add',
       description: 'Adds two numbers.',
       schema: AddToolSchema,
+      timeoutMs: 5000,
+      errorMode: 'return_to_model',
     });
   }
 
@@ -200,7 +376,7 @@ class AddTool extends Tool<typeof AddToolSchema, number> {
 
 const agent = new Agent({
   name: 'tool-agent',
-  executor: new ToolCallingExecutor(),
+  executor: new ToolCallingExecutor({ maxIterations: 5 }),
   tools: [new AddTool()],
   requireSessionId: true,
 });
@@ -208,25 +384,252 @@ const agent = new Agent({
 const result = await agent.run('Calculate 19 + 23 with the tool.', {
   sessionId: 'tenant_1:user_42:conversation_tools',
 });
+```
 
-console.log(result.output);
+工具运行控制：
+
+- `timeoutMs`: 工具超时后抛 `ToolTimeoutError`。
+- `AgentRunOptions.signal`: 会传入 `ToolRunContext.signal`。
+- `ToolRunContext`: 包含 `runId`、`agentName`、`sessionId`、`metadata`、`signal`。
+- `canExecute(context)`: 工具级权限策略，返回 `false` 时抛 `ToolPermissionError`。
+- `errorMode`: 默认 `return_to_model`，工具失败会作为 `isError: true` 的工具结果回传给模型；设为 `throw` 会中止本次 Agent run。
+- `serializeResult`: 可自定义工具结果如何转成 `MessageContent`。默认规则：字符串和 content block 原样返回，`undefined` 返回空字符串，其余值 `JSON.stringify()`。
+
+工具名必须符合 OpenAI-compatible function name 要求：1-64 个字符，仅字母、数字、下划线或连字符。
+
+`ToolRegistry` 默认拒绝重复工具名：
+
+```ts
+import { ToolRegistry } from '@fllf/agent-sdk';
+
+const registry = new ToolRegistry();
+registry.register(tool);
+registry.register(nextTool, { replace: true });
 ```
 
-## RAG integration
+`ToolCallingExecutor` 关键行为：
+
+- 单轮模型返回多个 tool call 时并发执行，结果顺序保持与模型请求一致。
+- 默认 `onMaxIterations: 'finalize'`：达到迭代上限后追加一轮不带工具的模型请求，让模型给出文字收尾。
+- 可设置 `onMaxIterations: 'throw'` 恢复超限即抛错；已执行轨迹仍会写入 history。
+
+## 直接使用 LLM
+
+```ts
+import { LLM } from '@fllf/agent-sdk';
 
-RAG is exposed as an independent subsystem. Agent code only depends on
-`RagPipeline` through either:
+const llm = new LLM({
+  provider: 'anthropic',
+  model: 'claude-opus-4-8',
+});
 
-- `RagExecutor`: always retrieve before answering. Use this for knowledge-base
-  QA.
-- `RagSearchTool`: let a tool-calling agent retrieve evidence only when the
-  model decides it needs knowledge-base context.
+const response = await llm.chat({
+  messages: [{ role: 'user', content: 'Say hello.' }],
+  maxTokens: 256,
+});
 
-### Build an in-memory RAG pipeline
+console.log(response.content);
+```
 
-This example is suitable for local development, tests, or a minimal MVP. Replace
-the stores with Postgres, pgvector, Qdrant, Elasticsearch, or your own adapters
-for production.
+流式：
+
+```ts
+for await (const chunk of llm.stream({
+  messages: [{ role: 'user', content: 'Stream a short answer.' }],
+})) {
+  process.stdout.write(chunk.contentDelta ?? '');
+}
+```
+
+结构化输出：
+
+```ts
+import { z } from 'zod';
+import { LLM } from '@fllf/agent-sdk';
+
+const llm = new LLM();
+
+const result = await llm.generateObject({
+  messages: [{ role: 'user', content: 'Return a short project summary.' }],
+  schema: z.object({
+    summary: z.string(),
+    confidence: z.number(),
+  }),
+});
+
+console.log(result.value);
+```
+
+高级请求字段：
+
+- `tools`: provider-neutral `ToolDefinition[]`。
+- `toolChoice`: `'auto' | 'none' | 'required' | { type: 'tool'; name: string }`。
+- `reasoning: { effort }`: OpenAI 映射为 `reasoning_effort`，Anthropic 映射为 `output_config.effort`。
+- `ChatMessage.cacheControl: 'ephemeral'`: Anthropic prompt cache 断点；其他 provider 忽略。
+- `responseFormat`: JSON schema 结构化输出。
+
+`ChatStreamAccumulator` 可把 provider 的 `ChatStreamChunk` 聚合成完整 `ChatResponse`：
+
+```ts
+import { ChatStreamAccumulator } from '@fllf/agent-sdk';
+
+const acc = new ChatStreamAccumulator();
+for await (const chunk of llm.stream(request)) {
+  acc.add(chunk);
+}
+const response = acc.toResponse();
+```
+
+## 自定义模型 provider
+
+全局注册：
+
+```ts
+import { LLM, ModelProviderFactory } from '@fllf/agent-sdk';
+
+ModelProviderFactory.register('tenant-provider', (config) => (
+  new TenantProvider(config)
+));
+
+const llm = new LLM({ provider: 'tenant-provider' });
+```
+
+多租户、测试或插件系统建议使用隔离 registry，避免全局污染：
+
+```ts
+import { LLM, ModelProviderRegistry } from '@fllf/agent-sdk';
+
+const registry = new ModelProviderRegistry({
+  includeDefaultProviders: false,
+});
+
+registry.register('tenant-provider', (config) => new TenantProvider(config));
+
+const llm = new LLM({
+  provider: 'tenant-provider',
+  providerRegistry: registry,
+});
+```
+
+自定义 provider 需要实现 `ChatModel`，并正确声明 `capabilities()`。SDK 会在调用前校验 tool calling、structured output、streaming 等能力，不支持时抛 `LLMUnsupportedCapabilityError`。
+
+## 消息历史与持久化
+
+`Message.toJSON()` 是推荐持久化格式；读取时用 `Message.fromJSON(row)` 或 `reviveMessage(row)`。
+
+```ts
+type MessageJSON = {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string | ContentBlock[];
+  timestamp: string;
+  metadata: Record<string, unknown>;
+};
+```
+
+读取窗口：
+
+```ts
+const recent = await history.get({ limit: 20 });
+const before = await history.get({
+  before: '2026-01-01T00:00:00.000Z',
+  limit: 20,
+});
+```
+
+`before` 是排他的时间游标；`limit` 返回过滤后的最近 N 条消息。窗口截断会修复开头孤儿 tool 上下文，避免 provider 400。
+
+### Postgres 消息历史
+
+适用于任何提供 `query(sql, params)` 的对象，例如 `pg.Pool`。SDK 不依赖 `pg` 包，也不依赖事务 API；原子写路径使用单条 SQL。
+
+```ts
+import {
+  createPostgresMessageHistorySchemaSql,
+  PostgresMessageHistoryStore,
+} from '@fllf/agent-sdk';
+
+await db.query(createPostgresMessageHistorySchemaSql({
+  tablePrefix: 'agent_history',
+}));
+
+const historyStore = new PostgresMessageHistoryStore({
+  db,
+  tablePrefix: 'agent_history',
+});
+```
+
+多实例共享同一个历史库时，可使用乐观并发：
+
+```ts
+const history = historyStore.get(sessionId);
+const version = await history.getVersion?.();
+
+await history.addMany(messages, {
+  expectedVersion: version,
+});
+```
+
+版本冲突抛 `HistoryVersionConflictError`，`retryable: true`。典型处理方式是重新读取历史和版本后重试。
+
+## 上下文窗口与历史压缩
+
+配置 `maxInputTokens` 后，executor 会从最新消息向前保留，超预算时截断较旧消息。估算器为轻量启发式，不用于计费。
+
+```ts
+import {
+  Agent,
+  Config,
+  SummarizingContextCompressor,
+} from '@fllf/agent-sdk';
+
+const agent = new Agent({
+  name: 'compressing-agent',
+  config: new Config({ maxInputTokens: 8000 }),
+  contextCompressor: new SummarizingContextCompressor({
+    maxSummaryTokens: 512,
+  }),
+});
+```
+
+`SummarizingContextCompressor` 会复用当前 Agent 的 LLM，把被截断的旧消息压缩成一条摘要前缀。摘要失败时自动降级为纯截断，不中断主请求。
+
+## RAG 接入
+
+RAG 子系统通过 `RagPipeline` 暴露三个核心方法：
+
+- `ingest(input)`: 文档解析、标准化、切块、embedding、写入文档库/向量索引/关键词索引。
+- `retrieve(query, options)`: 只返回可引用证据。
+- `answer(query, options)`: 检索、构建上下文、调用模型生成答案、校验引用。
+
+常用检索/回答参数：
+
+```ts
+type RetrieveOptions = {
+  topK?: number;
+  minScore?: number;
+  tenantId?: string;
+  knowledgeBaseId?: string;
+  acl?: string[];
+  documentIds?: string[];
+  sources?: string[];
+  metadataFilter?: Record<string, unknown>;
+};
+
+type AnswerOptions = RetrieveOptions & {
+  llm?: ChatModel;
+  maxContextTokens?: number;
+  minFusedScore?: number;
+  requireCitations?: boolean;
+  systemPrompt?: string;
+  metadata?: Record<string, unknown>;
+};
+```
+
+`minScore` 作用在具体 retriever 的原始分数尺度上；`minFusedScore` 作用在 context builder 的融合后分数尺度上，两者不要混用。
+
+### 构建内存 RAG pipeline
+
+适合本地开发、测试或最小 MVP；生产应替换为 Postgres/pgvector 或自有存储。
 
 ```ts
 import {
@@ -242,6 +645,7 @@ import {
   InMemoryKeywordStore,
   InMemoryVectorStore,
   OpenAIEmbedder,
+  ParentChildExpandingRetriever,
   RuleBasedVerifier,
   SparseRetriever,
 } from '@fllf/agent-sdk';
@@ -264,6 +668,17 @@ const sparseRetriever = new SparseRetriever({
   documentStore,
 });
 
+const retriever = new ParentChildExpandingRetriever({
+  retriever: new HybridRetriever({
+    denseRetriever,
+    sparseRetriever,
+  }),
+  documentStore,
+  strategy: 'parent_or_neighbors',
+  neighborWindow: 1,
+  maxExpandedChunkCharacters: 3000,
+});
+
 export const ragPipeline = new DefaultRagPipeline({
   loader: new AutoDocumentLoader(),
   normalizer: new DefaultDocumentNormalizer(),
@@ -272,23 +687,26 @@ export const ragPipeline = new DefaultRagPipeline({
   documentStore,
   vectorStore,
   keywordStore,
-  retriever: new HybridRetriever({
-    denseRetriever,
-    sparseRetriever,
-  }),
-  contextBuilder: new DefaultContextBuilder({
-    maxContextTokens: 3000,
-  }),
+  retriever,
+  contextBuilder: new DefaultContextBuilder({ maxContextTokens: 3000 }),
   generator: new DefaultRagGenerator(),
   verifier: new RuleBasedVerifier(),
 });
 ```
 
-`OpenAIEmbedder` and `OpenAICompatibleEmbedder` send embedding requests with
-`encoding_format: "float"` and validate that the returned embedding length
-matches `embedder.dimensions`. When using a third-party OpenAI-compatible
-embedding model whose dimension is not known by the SDK, pass `dimensions`
-explicitly and create the vector store with the same value:
+### Embedding
+
+OpenAI embedding：
+
+```ts
+import { OpenAIEmbedder } from '@fllf/agent-sdk';
+
+const embedder = new OpenAIEmbedder({
+  model: 'text-embedding-3-small',
+});
+```
+
+OpenAI-compatible embedding provider：
 
 ```ts
 import {
@@ -308,14 +726,20 @@ const vectorStore = new InMemoryVectorStore({
 });
 ```
 
-If you change the embedding model or dimensions, build a new vector collection
-or re-ingest documents. Vectors from different models or dimensions must not be
-mixed in the same index.
+未知 embedding 模型必须显式传 `dimensions`。更换 embedding 模型或维度时，应新建向量集合或重新 ingestion，不能混用不同维度/模型的向量。
+
+可用 `EmbeddingCache` 缓存 embedding：
 
-### Ingest documents
+```ts
+import { EmbeddingCache, OpenAIEmbedder } from '@fllf/agent-sdk';
+
+const embedder = new EmbeddingCache({
+  embedder: new OpenAIEmbedder(),
+  namespace: 'tenant_1:kb_support',
+});
+```
 
-Your application should run ingestion from an admin API, background worker, or
-document synchronization job.
+### Ingest 文档
 
 ```ts
 await ragPipeline.ingest({
@@ -328,16 +752,92 @@ await ragPipeline.ingest({
 });
 ```
 
-Important ingestion fields:
+关键字段：
+
+- `source`: 稳定来源路径、URL 或业务文档 id，会出现在引用中。
+- `tenantId`: 租户边界。
+- `knowledgeBaseId`: 知识库边界。
+- `acl`: 检索阶段的访问控制标签。
+- `metadata`: 文档元数据，可包含 `title`、`mimeType`、`version`、`extra` 等。
+- `replaceExisting`: 使用稳定 document id 清理旧 chunks/vectors/keywords；checksum 相同则跳过重复 ingestion。
+
+`AutoDocumentLoader` 根据 `mimeType` 或 `source` 后缀选择 Markdown、HTML、DOCX、PDF、纯文本 loader。HTML/DOCX/PDF 需要安装对应可选依赖。
+
+### 切块与检索
+
+`AutoChunker` 当前策略：
+
+- Markdown 或由 HTML/DOCX/PDF 转换出的 Markdown：`MarkdownChunker`，保留标题、表格、代码等结构。
+- FAQ/QA 风格文本：`QaPairChunker`。
+- 长无结构文本：`ParentChildChunker`，小块召回、大块提供上下文。
+- 其他短文本：`RecursiveChunker`。
+
+检索器：
+
+- `DenseRetriever`: embedding + vector store。
+- `SparseRetriever`: keyword store。
+- `HybridRetriever`: dense/sparse 并行检索，使用 RRF 融合，可接 reranker。
+- `ParentChildExpandingRetriever`: 把 child hit 扩展为 parent 或邻近 chunk。
+- `DefaultReranker`: 未配置模型时 no-op；配置 `RerankModelClient` 后按 rerank 分数重排。
+- `HttpRerankModelClient`: 适配 Jina/Cohere/常见网关 `/rerank` 端点。
+
+Rerank 示例：
+
+```ts
+import {
+  DefaultReranker,
+  HttpRerankModelClient,
+  HybridRetriever,
+} from '@fllf/agent-sdk';
+
+const reranker = new DefaultReranker({
+  model: new HttpRerankModelClient({
+    baseURL: process.env.RERANK_BASE_URL,
+    apiKey: process.env.RERANK_API_KEY,
+    model: process.env.RERANK_MODEL ?? 'jina-reranker-v2-base-multilingual',
+  }),
+});
+
+const retriever = new HybridRetriever({
+  denseRetriever,
+  sparseRetriever,
+  reranker,
+});
+```
+
+### Postgres/pgvector RAG 存储
 
-- `source`: stable source path, URL, or document id shown in citations.
-- `tenantId`: tenant boundary.
-- `knowledgeBaseId`: knowledge-base boundary.
-- `acl`: access-control labels used at retrieval time.
-- `replaceExisting`: delete previous chunks and indexes for the same document id
-  before writing new ones.
+```ts
+import {
+  createPostgresRagSchemaSql,
+  PgVectorStore,
+  PostgresDocumentStore,
+  PostgresKeywordStore,
+} from '@fllf/agent-sdk';
 
-### Knowledge-base QA agent
+await db.query(createPostgresRagSchemaSql({
+  tablePrefix: 'rag',
+  dimensions: embedder.dimensions,
+}));
+
+const documentStore = new PostgresDocumentStore({ db, tablePrefix: 'rag' });
+const vectorStore = new PgVectorStore({
+  db,
+  tablePrefix: 'rag',
+  dimensions: embedder.dimensions,
+});
+const keywordStore = new PostgresKeywordStore({ db, tablePrefix: 'rag' });
+```
+
+建表 SQL 默认：
+
+- 创建 `vector` 扩展。
+- 创建 documents、chunks、embeddings、keyword_entries 表。
+- 创建 HNSW 向量索引、GIN 关键词/ACL/extra 索引等。
+
+所有 Postgres RAG store 只依赖注入的 `query(sql, params)`，可直接使用 `pg.Pool` 或兼容封装。
+
+### Knowledge-base QA Agent
 
 ```ts
 import { Agent, RagExecutor } from '@fllf/agent-sdk';
@@ -363,11 +863,17 @@ const result = await knowledgeAgent.run('What is the refund window?', {
   },
 });
 
-console.log(result.output);
-console.log(result.raw);
+return {
+  message: result.output,
+  citations: (result.raw as any).citations,
+  confidence: (result.raw as any).confidence,
+  usage: result.usage,
+};
 ```
 
-`result.raw` is the `RagAnswer`:
+`RagExecutor` 会从 `metadata` 读取 `tenantId`、`knowledgeBaseId`、`acl`、`documentIds`、`sources`、`metadataFilter`、`topK`、`minScore`、`maxContextTokens`。
+
+`RagAnswer` 形状：
 
 ```ts
 type RagAnswer = {
@@ -383,27 +889,15 @@ type RagAnswer = {
     quote?: string;
   }>;
   confidence: 'high' | 'medium' | 'low';
-  retrieved: unknown[];
-  usage?: unknown;
+  retrieved: RetrievedChunk[];
+  usage?: TokenUsage;
   metadata?: Record<string, unknown>;
 };
 ```
 
-Recommended RAG chat response:
+### RAG 作为可选工具
 
-```ts
-return {
-  message: result.output,
-  citations: (result.raw as any).citations,
-  confidence: (result.raw as any).confidence,
-  usage: result.usage,
-};
-```
-
-### RAG as an optional search tool
-
-Use `RagSearchTool` when the agent should decide whether to search the knowledge
-base.
+模型需要时才检索知识库：
 
 ```ts
 import {
@@ -420,6 +914,9 @@ const agent = new Agent({
     new RagSearchTool({
       pipeline: ragPipeline,
       defaultRetrieveOptions: {
+        tenantId: 'tenant_1',
+        knowledgeBaseId: 'kb_support',
+        acl: ['user:user_42', 'role:support'],
         topK: 5,
       },
     }),
@@ -428,30 +925,53 @@ const agent = new Agent({
 });
 ```
 
-## Structured output
+安全边界：`RagSearchTool` 不把 `tenantId`、`knowledgeBaseId`、`acl` 暴露给模型参数，这些权限字段只能由服务端通过 `defaultRetrieveOptions` 设置。模型可传的仅是 `query`、`topK`、`minScore`、`documentIds`、`sources`、`metadataFilter` 等检索调优字段。
+
+## 内置搜索工具
+
+`AdvancedSearchTool` 可接入 Tavily 和 SerpAPI：
 
 ```ts
-import { z } from 'zod';
-import { LLM } from '@fllf/agent-sdk';
+import { AdvancedSearchTool } from '@fllf/agent-sdk';
 
-const llm = new LLM();
+const tools = [new AdvancedSearchTool({ logger })];
+```
 
-const result = await llm.generateObject({
-  messages: [
-    { role: 'user', content: 'Return a short project summary.' },
-  ],
-  schema: z.object({
-    summary: z.string(),
-    confidence: z.number(),
-  }),
-});
+环境变量：
 
-console.log(result.value);
+```bash
+TAVILY_API_KEY=...
+SERPAPI_API_KEY=...
 ```
 
-## Observability
+若两个 key 都未配置，工具会返回提示文本，不会抛出配置错误。该工具会真实调用外部搜索 API，第三方系统应自行处理网络权限、配额、审计和结果可信度。
 
-The SDK emits structured runtime events and does not print by default.
+## 生命周期钩子
+
+```ts
+import { Agent } from '@fllf/agent-sdk';
+
+const agent = new Agent({
+  name: 'audited-chat',
+  hooks: {
+    beforeRun(context) {
+      authorize(context.metadata);
+    },
+    afterRun(context, result) {
+      audit.info({ runId: context.runId, outputLength: result.output.length });
+    },
+    onRunError(context, error) {
+      audit.error({ runId: context.runId, error });
+    },
+  },
+});
+```
+
+`beforeRun` 失败会中止 run。`afterRun` 和 `onRunError` 失败不会替换主结果/主错误，会作为 warn 级 `agent:error` observer event 发出。
+
+## 可观测性
+
+SDK 默认不打印日志。接入方可通过 observer 收集事件。
 
 ```ts
 import { Agent, ConsoleObserver } from '@fllf/agent-sdk';
@@ -464,7 +984,7 @@ const agent = new Agent({
 await agent.run('Hello');
 ```
 
-Event types include:
+事件类型：
 
 - `agent:start`
 - `agent:end`
@@ -472,37 +992,101 @@ Event types include:
 - `llm:start`
 - `llm:end`
 - `llm:error`
+- `llm:retry`
 - `tool:start`
 - `tool:end`
 - `tool:error`
 
-Forward events to your logging or tracing system:
+自定义 observer：
 
 ```ts
 const observer = {
+  redactEvent(event) {
+    return {
+      ...event,
+      metadata: undefined,
+    };
+  },
   onEvent(event) {
     logger.info({ event }, 'agent runtime event');
   },
 };
 ```
 
-## Production integration checklist
+事件包含 `runId`、`timestamp`、可选 `spanId` / `parentSpanId`、provider/model、toolName/toolCallId、duration、usage、error 等字段。不要把敏感信息放入 `metadata`，因为 metadata 可能出现在消息、工具上下文和 observer 事件中。
+
+测试中可使用：
+
+```ts
+import { CollectingObserver } from '@fllf/agent-sdk';
+
+const observer = new CollectingObserver();
+await agent.run('Hello', { observer });
+
+console.log(observer.events);
+observer.clear();
+```
+
+## 错误处理
+
+核心错误类型从根包和 `@fllf/agent-sdk/errors` 导出：
+
+- `AgentSDKError`: SDK 统一错误基类，含 `code`、`retryable`、`metadata`。
+- `AgentError`、`AgentSessionError`、`AgentExecutionError`。
+- `ToolError`、`ToolConfigurationError`、`ToolPermissionError`、`ToolTimeoutError`、`ToolAbortError`、`ToolExecutionError`、`ToolNotFoundError`。
+- `HistoryError`、`HistoryVersionConflictError`。
+- `ConfigError`。
+- LLM 层错误：`LLMAuthenticationError`、`LLMRateLimitError`、`LLMTimeoutError`、`LLMAbortError`、`LLMUnsupportedCapabilityError`、`LLMProviderError`、`LLMInvalidResponseError`、`LLMStructuredOutputError`。
+
+示例：
+
+```ts
+import { AgentSDKError } from '@fllf/agent-sdk';
+
+try {
+  await agent.run(input, options);
+} catch (error) {
+  if (error instanceof AgentSDKError) {
+    logger.warn({
+      code: error.code,
+      retryable: error.retryable,
+      metadata: error.metadata,
+    });
+  }
+  throw error;
+}
+```
+
+LLM 会把 401/403、429、超时、调用方 abort、常见瞬态网络错误归一化为稳定错误类型。可重试错误会触发内置重试，并产生 `llm:retry` 事件。
+
+## 测试辅助工具
+
+下游系统可使用 SDK 提供的测试工具编写稳定集成测试：
 
-The SDK provides runtime primitives. A complete product should add:
+```ts
+import {
+  assertMessageHistoryStoreContract,
+  assertToolSchemaSnapshot,
+  createTestAgent,
+  createToolSchemaSnapshot,
+  FakeChatModel,
+  FakeTool,
+  ScriptedChatModel,
+} from '@fllf/agent-sdk';
+```
+
+用途：
 
-- Persistent users, conversations, messages, and audit logs.
-- A persistent `MessageHistoryStore`.
-- Persistent RAG stores and a vector/search backend.
-- AuthN/AuthZ before `Agent.run()` or `RagPipeline.retrieve()`.
-- Tenant, knowledge-base, and ACL filters in every RAG request.
-- Background document ingestion and index rebuild jobs.
-- Rate limits, model cost controls, and request timeouts.
-- Redaction or filtering for logs that may contain user messages or document
-  snippets.
+- `ScriptedChatModel`: 队列化返回固定模型响应，并记录请求。
+- `FakeChatModel`: 回显最后一条 user 消息。
+- `FakeTool`: 校验输入并记录调用。
+- `createTestAgent()`: 快速创建测试 Agent。
+- `createToolSchemaSnapshot()` / `assertToolSchemaSnapshot()`: 对工具暴露 schema 做快照测试。
+- `assertMessageHistoryStoreContract()`: 校验自定义历史存储满足 session 隔离、窗口读取、防御性拷贝、可选 CAS 语义等契约。
 
-## Public API map
+## 包导出
 
-All public APIs are exported from the package root:
+推荐从根包导入稳定 API：
 
 ```ts
 import {
@@ -516,33 +1100,75 @@ import {
 } from '@fllf/agent-sdk';
 ```
 
-Main areas:
+也支持子路径导入：
+
+```ts
+import { Agent } from '@fllf/agent-sdk/agent';
+import { Config } from '@fllf/agent-sdk/config';
+import { AgentSDKError } from '@fllf/agent-sdk/errors';
+import { LLM } from '@fllf/agent-sdk/llm';
+import { Message } from '@fllf/agent-sdk/messages';
+import { ConsoleObserver } from '@fllf/agent-sdk/observability';
+import { DefaultRagPipeline } from '@fllf/agent-sdk/rag';
+import { Tool } from '@fllf/agent-sdk/tools';
+```
+
+稳定接入面：
+
+- Agent: `Agent`、`createAgent`、`AgentRunOptions`、`AgentResult`、`AgentLifecycleHooks`。
+- Executors: `SimpleChatExecutor`、`ToolCallingExecutor`、`RagExecutor`、`BaseExecutor`、`buildChatMessages`、`buildChatRequest`。
+- LLM: `LLM`、`ChatModel`、`ChatRequest`、`ChatResponse`、`ModelProviderFactory`、`ModelProviderRegistry`。
+- Messages: `Message`、`MessageContent`、`ContentBlock`、`textBlock()`、`imageUrlBlock()`、`imageBase64Block()`、`contentToText()`。
+- Tools: `Tool`、`ToolRegistry`、`ToolExecutor`、`RagSearchTool`、`AdvancedSearchTool`。
+- History: `MessageHistory`、`MessageHistoryStore`、`InMemoryMessageHistoryStore`、`PostgresMessageHistoryStore`、`MessageJSON`、`reviveMessage()`。
+- RAG: pipeline、loader、normalizer、chunker、embedder、retriever、reranker、store、generator、verifier 相关接口与默认实现。
+- Observability: `Observer`、`RuntimeEvent`、`ConsoleObserver`、`CollectingObserver`。
+- Testing: `ScriptedChatModel`、`FakeChatModel`、`FakeTool`、`createTestAgent()`、契约/快照 helper。
+
+包仍处于 `0.x` 阶段。应用代码应优先依赖上述稳定集成面；低层 provider 映射细节、SQL helper、实验性 chunker 等可能在小版本中调整。
+
+## 生产接入清单
 
-- `agent`: runtime composition.
-- `llm`: provider abstraction and structured output.
-- `history`: session-scoped message history interfaces and in-memory store.
-- `tools`: Zod-driven tools and tool execution.
-- `executors`: simple chat, tool calling, and RAG execution strategies.
-- `rag`: ingestion, chunking, embeddings, stores, retrieval, generation, and
-  verification.
-- `observability`: observer interface and console observer.
+- 为每个外部请求建立明确的 tenant/user/conversation/session 边界。
+- 在调用 `Agent.run()`、`Agent.stream()`、`RagPipeline.retrieve()` 前完成认证与授权。
+- 使用持久化 `MessageHistoryStore`，多实例部署时处理 `HistoryVersionConflictError` 重试。
+- RAG 检索必须带 `tenantId`、`knowledgeBaseId` 和 ACL/metadata filter。
+- 文档 ingestion 放入后台任务或管理端流程，支持重建索引。
+- 为模型请求、工具、外部搜索和 rerank 设置超时与配额。
+- 对日志、observer event、metadata、工具结果和 RAG 片段做脱敏。
+- 不把用户可控字段作为 RAG 权限字段；`RagSearchTool` 权限字段只由服务端设置。
+- 更换 embedding 模型或维度后重建向量索引。
 
-## Development
+## 本仓库开发命令
 
 ```bash
 npm install
 npm run typecheck
 npm test
 npm run build
+npm run test:exports
 ```
 
-Examples:
+示例：
 
 ```bash
 npm run example:simple-chat
+npm run example:streaming-chat
 npm run example:tool-calling
+npm run example:tool-error-policy
 npm run example:local-ollama
+npm run example:custom-provider
+npm run example:custom-history-store
+npm run example:custom-executor
+npm run example:custom-observer
 ```
 
-During local development, examples may import from `../src` so they can run
-without building first.
+发布前建议：
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run test:exports
+npm run pack:dry-run
+```