my-ai-chat-framework 2.7.0 → 4.0.0

package/docs/DEVELOPER.md

@@ -0,0 +1,569 @@
+# 开发者文档
+
+> 版本 2.7.0 | 2026-06-05
+
+---
+
+## 架构
+
+```
+ChatService (核心)
+  ├── config        — 全部配置（model、apiKey、capabilities…）
+  ├── messages      — MessageStore 实例（对话历史）
+  ├── systemPrompts — SystemPromptStore 实例（可开关的 system 提示词）
+  ├── _adapter      — 当前适配器（openaiAdapter 等）
+  ├── _abortController — 当前请求的中断控制器
+  └── _isGenerating — 是否正在生成中
+
+插件（通过 chat.use() 安装）
+  ├── openaiAdapter         — HTTP 请求 + 流式解析
+  ├── toolCallingPlugin     — 工具调用循环
+  └── modelRegistryPlugin   — 模型能力表自动同步
+
+工具层
+  ├── MessageFormatter  — 消息格式转换（内置 openai，可注册自定义）
+  ├── EventEmitter      — 发布/订阅（ChatService 继承它）
+  └── Errors            — APIError / NetworkError / ConfigurationError / ParsingError
+```
+
+---
+
+## 配置
+
+配置按**归属分层**：谁消费，谁声明。内置与自定义插件走同一条路径。
+
+| 层 | 内容 | 归谁管 |
+|----|------|--------|
+| 运输层 | `apiKey` / `baseUrl` / `apiUrl` / `path` / `headers` | 适配器工厂 `createOpenAIAdapter(opts)` |
+| 请求层 | `model` / `temperature` / `maxTokens` / `modelParams.*` / `messageFormat` / `resolveImage` | 会话默认 + 请求级覆盖 |
+| 会话层 | `system` / `retry` / `ephemeralContinue` | `new ChatService({...})` + `updateConfig` |
+| 插件自有 | `toolTimeout` / `maxIterations` / `models` 等 | 各插件工厂 options |
+
+### 归属模式（自由）
+
+```javascript
+import { ChatService, createOpenAIAdapter, createToolCallingPlugin, createModelRegistryPlugin } from 'my-ai-chat-framework';
+
+const adapter = createOpenAIAdapter({
+  apiKey: 'sk-xxxx',
+  baseUrl: 'https://api.deepseek.com',
+  modelParams: { temperature: 0.8, maxTokens: 2000 }   // 请求默认参数
+});
+
+const chat = new ChatService({
+  adapter,                    // 构造时注入适配器（等价于 chat.use(adapter)）
+  model: 'deepseek-chat',     // 会话默认 model
+  system: '你是猫娘',          // 自动同步到 systemPrompts
+  retry: { maxRetries: 2, retryDelay: 1000 }
+});
+
+chat.use(createToolCallingPlugin({ timeout: 30000 }));       // 工具插件自带配置
+chat.use(createModelRegistryPlugin({ models: { 'my-model': { reasoning: true } } }));
+
+// 请求级覆盖：只对本次请求生效
+await chat.send('你好', { temperature: 0.2, model: 'deepseek-reasoner' });
+```
+
+### 平铺兼容写法（简单模式）
+
+```javascript
+// 运输层/请求层字段在构造时平铺传入，内部路由给内置 openaiAdapter
+const chat = new ChatService({
+  apiKey: 'sk-xxxx',
+  baseUrl: 'https://api.deepseek.com',
+  model: 'deepseek-chat',
+  modelParams: { temperature: 0.8, maxTokens: 2000 }
+});
+chat.use(openaiAdapter);      // 无状态单例，配置从 chat.config 读取
+```
+
+### 合并优先级
+
+```
+适配器默认(getRequestDefaults) ← 会话配置(this.config) ← 本次覆盖(params)
+```
+
+`modelParams` 深层合并；平铺便捷键（`temperature` / `maxTokens` / `reasoningEffort`）自动折叠进 `modelParams`。
+
+### 插件配置归属
+
+- 插件 options 在**工厂创建时**传入：`createXxxPlugin(opts)`
+- 也支持安装时传入：`chat.use(plugin, opts)`，合并进 `_options`
+- **推荐用工厂**：模块级单例（`openaiAdapter` / `toolCallingPlugin` / `modelRegistryPlugin`）装到多个 ChatService 实例会互相覆盖，仅作兼容保留
+
+---
+
+## 配置校验
+
+- 构造器：`model` 必填（`config.model` 或 `config.modelParams.model`）；`temperature` 0~2；`maxTokens` 正整数
+- `updateConfig`：只接受会话层字段（`model` / `temperature` / `maxTokens` / `modelParams` / `system` / `retry` / `ephemeralContinue`），非白名单字段或非法值抛 `ConfigurationError`，与构造器校验一致
+- 请求级覆盖（`chat.send(x, params)`）不做运行时校验——API 会返回错误，适合调试
+
+---
+
+## API
+
+### ChatService
+
+| 方法 | 说明 |
+|------|------|
+| `chat.send(input, params?)` | 发送消息，返回助手消息。`params` 为请求级覆盖（仅本次生效）。AbortError 内部捕获，不向外抛 |
+| `chat.stream(input, params?, onProgress, onDone)` | 流式发送。兼容旧签名 `stream(input, onProgress, onDone)`。AbortError 内部捕获 |
+| `chat.sendExisting(params?)` | 重发当前消息（不加用户消息）。AbortError 内部捕获 |
+| `chat.sendExistingStream(params?, onProgress, onDone)` | 流式重发。兼容旧签名。AbortError 内部捕获 |
+| `chat.plugins['continuation'].continueLast()` | 前缀续写：从最后一条 assistant/ephemeral 续写并拼回原消息，续写后自动转正。AbortError 内部捕获，返回 target |
+| `chat.plugins['continuation'].continueLastStream(onProgress, onDone)` | 流式前缀续写。AbortError 内部捕获，返回 target |
+| `chat.abort()` | 中断当前请求，触发 `aborted` 事件 |
+| `chat.use(plugin, options?)` | 安装插件，options 透传给 `plugin.install(chat, options)` |
+| `chat.updateConfig(partial)` | 更新会话层配置（白名单+校验），触发 `config-updated` |
+| `chat.plugins['tool-calling'].registerTool(name, desc, fn, params?)` | 注册工具（需 toolCallingPlugin） |
+| `chat.plugins['model-registry'].registerModel(name, caps)` | 注册/覆盖模型能力（需 modelRegistryPlugin） |
+
+### 属性
+
+| 属性 | 说明 |
+|------|------|
+| `chat.messages` | MessageStore 实例 |
+| `chat.systemPrompts` | SystemPromptStore 实例 |
+| `chat.config` | 当前配置对象（可直接读） |
+| `chat.isGenerating` | 是否正在生成（只读） |
+
+### SystemPromptStore
+
+| 方法 | 说明 |
+|------|------|
+| `add(content, enabled?)` | 添加 system prompt |
+| `remove(index)` | 删除 |
+| `toggle(index)` | 切换启用/禁用 |
+| `update(index, content)` | 修改内容 |
+| `set(content)` | 清空并用一条替换 |
+| `getEnabled()` | 返回启用的 `[{role:'system',content}]` |
+| `getAll()` | 返回全部（含 enabled 状态） |
+
+### MessageStore
+
+| 方法 | 说明 |
+|------|------|
+| `add(msg)` | 添加消息 |
+| `addUser(content)` / `addAssistant(content)` / `addSystem(content)` / `addTool(content, toolCallId)` | 快捷方法 |
+| `addOnceAssistant(content, options?)` | 一次性引导消息：默认 `_ephemeral: true` + `prefix: true`，options 可传 `{ reasoningContent, prefix }` |
+| `getAll()` | 返回浅拷贝 |
+| `getLast()` | 最后一条（或 null） |
+| `clear()` | 清空 |
+| `undoToLastAssistant()` | 撤回最后 assistant 之后的消息 |
+| `undoToPreviousUser(id)` | 撤回到指定消息之前的最近 user：删除该 user 之后到该消息（含）之间的消息（适用于重发） |
+
+消息格式：
+
+```javascript
+{
+  id: 'msg_1716300000_1',
+  role: 'user' | 'assistant' | 'system' | 'tool',
+  content: string,
+  images?: ['https://...'],
+  toolCalls?: [{ id, type:'function', function:{name,arguments} }],
+  toolCallId?: string,
+  reasoningContent?: string,
+  // 流式标记（自动添加）
+  _streaming?: true,      // 正在生成
+  prefix?: boolean,       // 前缀续写标记
+  _ephemeral?: boolean,   // 临时消息：仅底部连续时参与请求，续写后转正
+  _complete?: boolean,    // 流式是否完成（false=未完成/中断，true=正常结束），非流式无此字段
+  timestamp: 1716300000,
+  metadata?: any
+}
+```
+
+---
+
+## 事件
+
+| 事件 | 数据 | 触发时机 |
+|------|------|---------|
+| `sending` | `{ addUser, userInput, timestamp }` | 请求发送前 |
+| `stream-progress` | chunk 对象 | 每个流式块 |
+| `message` | 助手消息对象 | 完整消息收到 |
+| `aborted` | `{ timestamp }` | 用户调用 abort() 中断请求 |
+| `error` | `{ error, timestamp }` | 请求失败（AbortError 不触发此事件） |
+| `retry` | `{ attempt, maxRetries, lastError }` | 网络错误重试 |
+| `config-updated` | `{ changes, timestamp }` | config 更新 |
+| `tool-success` | `{ toolName, result, toolCallId }` | 工具执行成功 |
+| `tool-error` | `{ toolName, error, toolCallId, stage }` | 工具执行失败（stage: parse / lookup / execute / timeout） |
+| `beforeRequest` | `{ messages, config, options }` | 请求发送前，可修改 messages/config（见下方钩子说明） |
+
+```javascript
+// 状态管理示例：用事件驱动 UI，不需要手动 catch
+chat.on('sending', () => { /* 按钮切发送中 */ });
+chat.on('message', () => { /* 按钮恢复 idle */ });
+chat.on('aborted', () => { /* 按钮恢复 idle */ });
+chat.on('error', ({ error }) => { /* 按钮恢复 idle + 显示错误 */ });
+```
+
+```javascript
+chat.on('error', ({ error }) => {
+  if (error instanceof APIError)     console.error('API错误', error.statusCode);
+  if (error instanceof NetworkError)  console.error('网络错误');
+  if (error instanceof ConfigurationError) console.error('配置错误');
+});
+```
+
+### beforeRequest 钩子
+
+在 adapter 构建请求体之前触发，可修改 messages 或 config。所有请求（send / stream / continueLast / continueLastStream）都会触发。
+
+```javascript
+chat._hooks.on('beforeRequest', async ({ messages, config, options }) => {
+  // messages — MessageStore 实例，可直接 add/update/clear
+  // config   — 当前配置对象，可修改（仅本次请求生效）
+  // options  — 本次请求的参数
+});
+```
+
+`options` 字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `addUser` | boolean | `true` = 普通发送（send/stream），`false` = 续写/重发 |
+| `isStream` | boolean | 是否流式 |
+| `userInput` | string\|object | 用户输入（续写时为 undefined） |
+| `mergeToEntry` | string\|undefined | 续写目标 id，有值 = 续写模式 |
+| `onProgress` | function | 流式进度回调 |
+| `onDone` | function | 流式结束回调 |
+
+**区分普通发送和续写**：
+
+```javascript
+chat._hooks.on('beforeRequest', async ({ messages, options }) => {
+  // 续写时不注入，避免重复
+  if (options.mergeToEntry) return;
+
+  // 普通发送时注入 ephemeral 引导
+  messages.add({
+    role: 'assistant', content: '',
+    _ephemeral: true, prefix: true
+  });
+});
+```
+
+---
+
+## 临时消息（Ephemeral）
+
+标记 `_ephemeral: true` 的消息**仅底部连续时参与请求**，其余位置自动被 MessageFormatter 过滤。
+续写后自动转正（`delete _ephemeral`），变为永久消息。
+
+```javascript
+// 注入临时引导消息（仅本次请求生效）
+chat._hooks.on('beforeRequest', async ({ messages }) => {
+  messages.add({
+    role: 'assistant', content: '让我分析一下：',
+    reasoningContent: '我需要逐步推理',
+    _ephemeral: true, prefix: true
+  });
+});
+
+// 续写后自动转正
+await chat.plugins['continuation'].continueLast();
+// 该消息的 _ephemeral 已被清除，成为永久 assistant
+```
+
+### 自动续写（ephemeralContinue）
+
+`config.ephemeralContinue: true` 启用后，当底部消息带有 `prefix: true` 且角色为 `assistant` 或 `_ephemeral` 时，
+框架自动将其设为续写目标（`mergeToEntry`），结果拼回原消息而非追加为新消息。
+
+适用于 ephemeral 注入引导场景——钩子注入一条带 prefix 的引导消息后，API 的回复直接合并回该消息：
+
+```javascript
+const chat = new ChatService({
+  apiKey: 'sk-xxx',
+  model: 'deepseek-chat',
+  ephemeralContinue: true
+});
+
+chat._hooks.on('beforeRequest', async ({ messages }) => {
+  messages.addOnceAssistant('让我分析一下', { reasoningContent: '逐步推理' });
+});
+```
+
+启用后每次正常请求（send/stream）都会检测底部 prefix 消息，不影响已有语义。
+不启用时 `prefix` 仅透传给 API，结果作为新消息追加。
+
+---
+
+## MessageFormatter
+
+```javascript
+import { MessageFormatter } from 'my-ai-chat-framework';
+
+// 注册 Anthropic 格式
+MessageFormatter.register('anthropic', ({ messages, systemPrompts, capabilities }) => {
+  const result = [];
+  // Anthropic 格式：user/assistant 交替
+  for (const msg of messages) {
+    if (msg.role === 'user' || msg.role === 'assistant') {
+      result.push({ role: msg.role, content: msg.content });
+    }
+  }
+  return result;
+});
+
+// 使用
+const chat = new ChatService({
+  messageFormat: 'anthropic',  // 指定格式
+  // ...
+});
+
+// 列出所有格式
+console.log(MessageFormatter.listFormats()); // ['openai', 'anthropic']
+```
+
+---
+
+## 前缀续写
+
+调用 `chat.plugins['continuation'].continueLast()` 从最后一条 assistant 消息续写——
+模型直接从原内容末尾接续，结果拼回原消息（不新增消息）。
+
+> 部分服务商需 baseUrl 加 `/beta` 开启该功能（如 DeepSeek）。
+
+```javascript
+// 中断后直接续写（流式标记 _complete 为 false）
+chat.abort();
+const msg = await chat.plugins['continuation'].continueLast();
+// msg.content 已是原始 + 续写拼接，_complete 变为 true
+
+// 已完成的对话也可以续写（但通常没必要）
+await chat.plugins['continuation'].continueLast();
+```
+
+---
+
+## 流式消息与 Vue 渲染
+
+框架自动在流式开始时 push 占位消息到 `messages`，并实时更新 content：
+
+```vue
+<template>
+  <div v-for="msg in messages" :key="msg.id">
+    <div v-if="msg.role === 'user'">{{ msg.content }}</div>
+    <div v-else-if="msg.role === 'assistant'" :class="{ streaming: msg._streaming }">
+      {{ msg.content }}
+      <span v-if="msg._complete === false">▊</span>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+const messages = ref([]);
+
+chat.on('stream-progress', (chunk) => {
+  // 不需要手动 push，messages 已实时更新
+  // 只需触发 Vue 响应
+});
+</script>
+```
+
+---
+
+## 自定义适配器
+
+适配器契约（`config` 为合并后的请求参数，运输层可从实例自持或 `config` 读取）：
+
+```javascript
+export const myAdapter = {
+  name: 'custom',
+  install(chat, options = {}) { chat.setAdapter(this); },
+
+  // 可选：工厂实例可提供的"请求默认参数"（运输键除外），
+  // 会话层会按 适配器默认 ← 会话配置 ← 本次覆盖 合并
+  getRequestDefaults() { return { modelParams: { temperature: 0.7 } }; },
+
+  buildRequest(messages, config, systemPrompts) {
+    return MessageFormatter.format({
+      messages, systemPrompts,
+      capabilities: config.capabilities,
+      format: config.messageFormat || 'openai'
+    });
+  },
+
+  async send(requestBody, config, options) { /* ... */ },
+
+  // stream 只负责解析 SSE：onProgress 传累积快照 { content, reasoningContent, toolCalls }，
+  // onDone 传最终消息。占位消息的创建/更新由 ChatService 管理，adapter 不碰
+  async stream(requestBody, config, onProgress, onDone, options) {
+    // ...解析 chunk，accumulated 累积后调用 onProgress({ ...accumulated })
+    // 结束时调用 onDone(finalMessage)
+  },
+
+  parseResponse(apiResponse) { /* ... */ },
+};
+```
+
+---
+
+## 完整示例
+
+```javascript
+import {
+  ChatService, openaiAdapter, toolCallingPlugin, modelRegistryPlugin,
+  APIError, NetworkError
+} from 'my-ai-chat-framework';
+
+const chat = new ChatService({
+  apiKey: 'sk-xxxx',
+  model: 'deepseek-chat',
+  system: '你是乐于助人的AI助手',
+  retry: { maxRetries: 2 },
+  toolTimeout: 10000,
+});
+
+chat.use(openaiAdapter);
+chat.use(modelRegistryPlugin);
+chat.use(toolCallingPlugin);
+
+chat.plugins['tool-calling'].registerTool('get_weather', '查询天气', async (args) => {
+  return `${args.city}: 22°C, 晴`;
+}, { city: { type: 'string', description: '城市', required: true } });
+
+chat.on('message', msg => console.log('AI:', msg.content));
+chat.on('error', ({ error }) => console.error(error.message));
+
+// 基础对话
+await chat.send('你好');
+
+// 工具调用
+await chat.send('北京天气？');
+
+// 手动中断
+setTimeout(() => chat.abort(), 3000);
+await chat.stream('讲个长故事', ...);
+
+// 前缀续写（从最后一条 assistant 续写）
+await chat.plugins['continuation'].continueLast();
+// 结果拼回原消息，不新增消息
+```
+
+---
+
+## 扩展：写一个"车间"（v3.0）
+
+核心流程已是一辆小车（ctx）依次开过车间。想加一个新功能 = 注册一个车间，核心代码一行不用改。
+
+```javascript
+const chat = new ChatService({ adapter, model: 'deepseek-chat' });
+
+// 发送前：给每句话注入角色卡（ctx.messages 是 MessageStore，可用 add / addUser …）
+chat.pipe({
+  name: '角色卡注入',
+  phase: 'beforeSend',            // 默认即 beforeSend
+  async run(ctx) {
+    ctx.messages.add({ role: 'system', content: '你是傲娇霸总' });
+  }
+});
+
+// 发送后：把回复打上时间戳（ctx.result 可改，send() 的返回值会跟着变）
+chat.pipe({
+  name: '回复打标',
+  phase: 'afterSend',
+  run(ctx) {
+    if (ctx.result?.content) ctx.result.content += '（来自' + new Date().toLocaleTimeString() + '）';
+  }
+});
+
+// 移除车间
+chat.unpipe('角色卡注入');
+```
+
+车间即"同级功能"：tool-calling / model-registry 本身现在就是车间（见 src/plugins/）。ctx 的全部字段见 ChatService.js 顶部 @typedef PipelineContext。
+
+---
+
+## 出口：替换 / 关闭内部步骤（v3.1）
+
+框架的 5 个内部步骤都能被替换、关闭、包装——"加功能只能改源码"成为历史。
+
+```js
+chat.internalStages   // ['prepareInput','beforeSend','autoContinue','buildRequest','send']
+
+// 1) 完全接管"发送"这一步（框架不再插手）
+chat.replaceStage('send', async (ctx) => {
+  ctx.result = await 我自己的发送逻辑(ctx.body);
+});
+
+// 2) 包一层：先做自己的事，再交回默认实现
+const 默认发送 = chat.getStage('send');
+chat.replaceStage('send', async (ctx) => { 记录日志(ctx); await 默认发送(ctx); });
+
+// 3) 彻底关掉某一步
+chat.unstage('autoContinue');
+
+// 4) 反悔
+chat.restoreStage('send');      // 恢复默认实现
+chat.restage('autoContinue');   // 重新启用
+```
+
+---
+
+## 临时消息：用业务规则实现（v4.0）
+
+> v4.0 起，**核心不认识 ephemeral（临时消息）与续写** —— 它们是玩法，住在 `src/plugins/continuation.js`。
+> 两条路，按需选。
+
+### 场景 A：不装插件 —— 一次性注入（最轻）
+
+```js
+// 让一段内容"只影响本次请求、不进历史"
+chat.pipe({
+  name: '临时引导',
+  phase: 'beforeSend',
+  run(ctx) { ctx.config.guideText = '接下来用三句话总结'; }
+});
+
+// 在你自己写的 adapter.buildRequest 里，把 config.guideText 变成请求里的一条消息
+```
+
+### 场景 B：装插件 —— 模拟思维链 / 前缀续写
+
+```js
+import { createContinuationPlugin } from 'my-ai-chat-framework';
+
+chat.use(createContinuationPlugin({ autoContinue: true }));
+
+// 1) 模拟思维链：注入临时引导，结果并回上一条 assistant，不留痕
+chat.messages.addOnceAssistant('（内心：他肯定又要熬夜）');
+await chat.stream('在吗');
+
+// 2) 前缀续写：让 AI 接着最后一条 assistant 往下写
+await chat.plugins['continuation'].continueLast();
+```
+
+### 插件到底装了什么（可整体卸载）
+
+| 装的东西 | 用到的机制 |
+|---|---|
+| 续写检测（`autoContinue` 步骤） | `chat.replaceStage('autoContinue', …)`（v3.1 出口） |
+| ephemeral 过滤规则 | `MessageFormatter.registerFilter('ephemeral', …)`（v4.0 过滤器注册点） |
+| `chat.plugins['continuation'].continueLast` / `chat.plugins['continuation'].continueLastStream` | 挂到实例上 |
+| `plugin.uninstall(chat)` | 全部还原（步骤 / 过滤器 / 方法） |
+
+### 只要规则、不要插件
+
+```js
+import { ephemeralFilterRule } from 'my-ai-chat-framework';
+MessageFormatter.registerFilter('ephemeral', ephemeralFilterRule, { priority: 100 });
+```
+
+### 自定义消息过滤（决定哪些消息进入请求）
+
+```js
+MessageFormatter.registerFilter('我的规则', (msg, { index, messages, capabilities }) => {
+  if (msg.metadata?.hidden) return null;      // 丢弃
+  return msg;                                  // 保留（也可返回改写后的新对象）
+}, { priority: 100 });                         // 数字越小越先执行
+
+MessageFormatter.listFilters();                // 查看当前过滤器链
+MessageFormatter.unregisterFilter('我的规则');  // 移除
+```
+

package/docs/README.md

@@ -0,0 +1,33 @@
+# 文档索引
+
+> 按"你现在想干什么"挑一份看。
+
+| 我想…… | 看这份 |
+|---|---|
+| **快速用起来**（抄代码） | [COOKBOOK.md](./COOKBOOK.md) —— 16 个常见任务配方 |
+| **查某个方法/事件/错误** | [API-REFERENCE.md](./API-REFERENCE.md) —— 完整 API 参考 |
+| **搞懂它为什么这么设计** | [ARCHITECTURE.md](./ARCHITECTURE.md) —— 架构、数据流、五种扩展方式 |
+| **确认哪些能改、哪些不能改** | [API-STABILITY.md](./API-STABILITY.md) —— 稳定性契约（Stable/Experimental/Internal） |
+| **理解"框架 vs 库"、责任边界** | [DESIGN-boundaries.md](./DESIGN-boundaries.md) —— 责任边界与出口缺口 |
+| **上手时的注意点 / 试用结论** | [FRAMEWORK-REVIEW.md](./FRAMEWORK-REVIEW.md) —— 试用报告（5 个易踩点） |
+| **发布到 npm** | [PUBLISHING.md](./PUBLISHING.md) —— 发布流程（含 2027 变化） |
+| **看还有什么没做** | [TODO.md](./TODO.md) —— 路线图与已知问题 |
+| **开发这个框架本身** | [DEVELOPER.md](./DEVELOPER.md) —— 扩展教程（写车间/出口/临时消息） |
+| **让 AI 帮你改这个仓库** | [../AGENTS.md](../AGENTS.md) · [../CLAUDE.md](../CLAUDE.md) —— 给 AI 的说明书 |
+
+## 推荐阅读顺序（第一次接触）
+
+1. 仓库根目录 [README_ZH.md](../README_ZH.md) —— 5 分钟了解是什么
+2. [COOKBOOK.md](./COOKBOOK.md) 的配方 1、3、4 —— 能跑起来、能流式、能注入角色卡
+3. [ARCHITECTURE.md](./ARCHITECTURE.md) 的第三节（生命周期）+ 第四节（五种扩展方式）
+4. [API-STABILITY.md](./API-STABILITY.md) —— 记住"只加不改"，然后放心写业务
+5. 剩下按需查
+
+## 可运行的示例
+
+| 文件 | 用途 |
+|---|---|
+| [../examples/selfcheck.js](../examples/selfcheck.js) | 无网络自检 21 项：`node examples/selfcheck.js` |
+| [../examples/demo.html](../examples/demo.html) | 浏览器真实对话（含车间开关、插件开关） |
+| [../tests/pipeline.test.js](../tests/pipeline.test.js) | **测试即文档**：36 个用例，每个演示一种用法 |
+| [../tests/core.test.js](../tests/core.test.js) | 48 个基础用例（存储/配置/适配器/过滤器） |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-ai-chat-framework",
-  "version": "2.7.0",
+  "version": "4.0.0",
   "description": "A lightweight AI chat framework with plugin system, unified message format, and tool calling support.",
   "type": "module",
   "main": "dist/my-ai-chat-framework.node.cjs.js",
@@ -13,6 +13,35 @@
       "browser": "./dist/my-ai-chat-framework.browser.umd.js"
     }
   },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "preview": "vite preview",
+    "test": "node tests/core.test.js && node tests/pipeline.test.js",
+    "test:integration": "node tests/integration.test.js",
+    "selfcheck": "node examples/selfcheck.js",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md",
+    "README_ZH.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs/DEVELOPER.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/233zrl/my-chat-test.git"
+  },
+  "homepage": "https://github.com/233zrl/my-chat-test#readme",
+  "bugs": {
+    "url": "https://github.com/233zrl/my-chat-test/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "ai",
     "chat",
@@ -22,16 +51,10 @@
     "streaming",
     "plugin"
   ],
-  "author": "Your Name",
+  "author": "233zrl <zrl233333@outlook.com>",
   "license": "MIT",
   "devDependencies": {
     "dotenv": "^17.3.1",
     "vite": "^8.0.2"
-  },
-  "scripts": {
-    "build": "vite build",
-    "dev": "vite",
-    "preview": "vite preview",
-    "test": "node test.js"
   }
 }