agent-chat-sdk-core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+本项目的所有显著变更都记录在此文件中。
+
+格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本管理遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.1.0] - 2026-09-09
+
+### Added
+
+- `AgentChatClient` 流式对话客户端：回调（`chatStream`）与异步迭代器（`streamEvents`）双消费模式，支持 `AbortSignal`、`extraBody` / `extraHeaders`、自定义 `fetch` / 请求体 / 请求头。
+- SSE 解析器：`parseSSELine` / `readSSEStream` / `isStreamEndSignal`，兼容普通分片、工作流直连事件（`workflow_*` / `node_*` / `text_chunk`）与 `[DONE]` 结束信号。
+- ReAct 事件归一化：`createNormalizeContext` / `normalizeRawChunk` / `finalizeNormalizeContext`，输出标准化事件流（多轮思考、工具/知识库调用、最终回答）。
+- 可选会话状态机：`createSessionState` / `applyEventToSession`。
+- 知识库引用标注解析：`parseKnowledgeSupLabels` / `stripKnowledgeSupLabels`。
+- 三种数据推送模式：`normalized` / `raw` / `both`。
+- 双格式构建产物（ESM + CJS）与完整 TypeScript 类型声明。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 paco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,492 @@
+# agent-chat-sdk-core
+
+智能体（ReAct）流式对话 SDK。负责调用 SSE 接口、解析服务端分片，并将 **思考 / 工具调用 / 最终回答** 等过程推送为标准化事件，**不包含任何 UI 组件**，由使用方自行决定如何渲染。
+
+---
+
+## 安装与引用
+
+### 在本仓库（Monorepo）内引用
+
+`tsconfig.json` 已配置路径别名（指向源码，便于本地联调）：
+
+```json
+{
+  "paths": {
+    "agent-chat-sdk-core": ["./packages/agent-chat-sdk/src/index.ts"],
+    "agent-chat-sdk-core/*": ["./packages/agent-chat-sdk/src/*"]
+  }
+}
+```
+
+```typescript
+import { AgentChatClient } from 'agent-chat-sdk-core';
+```
+
+### 作为独立包使用
+
+已发布至 npm，直接安装：
+
+```bash
+npm install agent-chat-sdk-core
+```
+
+```typescript
+import { AgentChatClient } from 'agent-chat-sdk-core';
+```
+
+> 包内提供双格式产物：`dist/esm`（ESM）与 `dist/cjs`（CommonJS），通过 `exports` 映射自动适配；类型声明随包发布，无需额外安装 `@types`。要求 Node.js >= 18。
+
+---
+
+## 快速开始
+
+```typescript
+import { AgentChatClient } from 'agent-chat-sdk-core';
+
+const client = new AgentChatClient({
+  url: 'https://your-host/appforge/openapi/v1/InvokeApp/app-xxxxxxxx',
+  appId: 'app-xxxxxxxx',
+  appKey: 'your-app-key',
+});
+
+await client.chatStream(
+  { query: '帮我查一下水费' },
+  {
+    onEvent: (event) => {
+      switch (event.type) {
+        case 'thinking_start':
+          console.log('开始思考，第', event.round, '轮');
+          break;
+        case 'thinking_end':
+          console.log('思考完成，用时', event.runningTime, '秒');
+          break;
+        case 'tool_call_start':
+          console.log('调用中:', event.title);
+          break;
+        case 'tool_call_end':
+          console.log('调用完成:', event.title, event.runningTime);
+          break;
+        case 'answer_delta':
+          // event.content 为当前累积的完整回复
+          renderAnswer(event.content);
+          break;
+        case 'error':
+          showError(event.message, event.detail);
+          break;
+        case 'stream_end':
+          stopLoading();
+          break;
+      }
+    },
+    onError: (err) => console.error(err),
+    onComplete: () => console.log('流结束'),
+  },
+);
+```
+
+---
+
+## 配置说明
+
+### `AgentChatClientConfig`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `url` | `string` | 是 | 流式对话**完整请求地址**（SDK 不做路径拼接） |
+| `appId` | `string` | 是 | 智能体应用 ID（默认写入请求体 `id` 字段） |
+| `appKey` | `string` | 否 | 鉴权 Key，自动设置 `Authorization: Bearer {appKey}` |
+| `fetch` | `typeof fetch` | 否 | 自定义 fetch（测试 / Node 环境） |
+| `buildRequestBody` | `function` | 否 | 自定义请求体 |
+| `buildHeaders` | `function` | 否 | 自定义请求头 |
+
+### 关于 `url`
+
+SDK **只接收完整链接**。代理、网关、路径规则由各项目自行处理，例如：
+
+```typescript
+// 直连后端
+new AgentChatClient({
+  url: 'http://58.19.19.197:9080/appforge/openapi/v1/InvokeApp/app-xxx',
+  appId: 'app-xxx',
+  appKey: 'your-key',
+});
+
+// 本仓库 Demo：Next.js rewrite 到 `/api/chat/:appId`
+new AgentChatClient({
+  url: '/api/chat/app-xxx',
+  appId: 'app-xxx',
+  appKey: 'your-key',
+});
+```
+
+见 `src/utils/chat-api.ts` 中的 `CHAT_API_URL`。
+
+### 默认请求格式
+
+- **Method**: `POST`
+- **Headers**: `Content-Type: application/json`、`Accept: text/event-stream`、`Authorization: Bearer {appKey}`
+- **Body**:
+
+```json
+{
+  "id": "app-xxx",
+  "query": "用户输入的问题"
+}
+```
+
+可通过 `extraBody` / `extraHeaders` 或 `buildRequestBody` / `buildHeaders` 扩展。
+
+---
+
+## 数据推送模式
+
+通过 `chatStream` 的 `dataMode` 参数选择：
+
+| 模式 | 说明 | 适用场景 |
+|------|------|----------|
+| `normalized`（默认） | 推送标准化 `AgentStreamEvent` | 推荐，直接驱动 UI |
+| `raw` | 仅推送原始 `RawSSEChunk` | 完全自定义解析逻辑 |
+| `both` | 同时推送上述两种 | 调试、渐进迁移 |
+
+```typescript
+await client.chatStream(
+  { query: '你好', dataMode: 'raw' },
+  {
+    onRawChunk: (chunk) => {
+      console.log(chunk.type, chunk.content, chunk.raw);
+    },
+  },
+);
+```
+
+---
+
+## ReAct 交互时序
+
+SDK 将服务端 SSE 归一化为以下事件流，对应 ReAct 智能体的多轮 **思考 → 工具 → 再思考 → 回答** 过程：
+
+```
+用户发送
+  → stream_start
+  → [可多轮]
+      thinking_start
+      thinking_delta × N   （思考中，建议 UI 不展示正文）
+      thinking_end         （思考完成，展示耗时）
+      tool_call_start      （工具/知识库调用中）
+      tool_call_end        （调用完成）
+  → answer_delta × N       （流式最终回复）
+  → stream_end
+```
+
+### 服务端 SSE `type` 与 SDK 事件对应
+
+| 服务端 `type` | SDK 事件 |
+|---------------|----------|
+| `thinking` | `thinking_start` / `thinking_delta` / `thinking_end` |
+| `tool` / `plugin` | `tool_call_start` / `tool_call_end` |
+| `knowledge` | `knowledge_call_start` / `knowledge_call_end` |
+| `answer` / `text` / `message` | `answer_delta` |
+| `error` | `error` |
+| `done` / `[DONE]` | `stream_end` |
+
+常量 `REACT_SSE_TYPE_MAP` 提供中文说明，便于文档与调试。
+
+---
+
+## 标准化事件类型
+
+### 生命周期
+
+| 事件 | 字段 | 说明 |
+|------|------|------|
+| `stream_start` | `query` | 流开始 |
+| `stream_end` | — | 流正常结束 |
+
+### 思考阶段
+
+| 事件 | 主要字段 | 说明 |
+|------|----------|------|
+| `thinking_start` | `round` | 新一轮思考开始 |
+| `thinking_delta` | `delta`, `content`, `round` | 思考内容增量（`content` 为累积全文） |
+| `thinking_end` | `content`, `runningTime`, `round` | 思考结束 |
+
+> **数据与 UI 分离**：SDK **始终推送**完整 `content`（`thinking_delta` / `thinking_end` / `tool_call_end`）。是否渲染正文由调用方决定，例如仅展示步骤与耗时、调试时展开全文等。
+
+```typescript
+// 调用方：只用步骤，不渲染思考正文
+onEvent: (event) => {
+  if (event.type === 'thinking_delta') {
+    setStatus('thinking'); // 忽略 event.content
+  }
+  if (event.type === 'thinking_end') {
+    addStep({ label: '深度思考', time: event.runningTime }); // 可选存 event.content 但不展示
+  }
+};
+
+// 调用方：需要调试/审计时渲染正文
+if (event.type === 'thinking_delta') {
+  debugPanel.append(event.delta);
+}
+```
+
+### 工具调用
+
+| 事件 | 主要字段 | 说明 |
+|------|----------|------|
+| `tool_call_start` | `toolId`, `title` | 工具开始调用 |
+| `tool_call_end` | `toolId`, `title`, `content`, `runningTime` | 工具调用完成 |
+| `knowledge_call_start` | 同上 | 知识库调用开始 |
+| `knowledge_call_end` | 同上 | 知识库调用完成 |
+
+### 回答与错误
+
+| 事件 | 主要字段 | 说明 |
+|------|----------|------|
+| `answer_delta` | `delta`, `content` | 最终回复增量（`content` 为累积全文） |
+| `error` | `message`, `detail?` | 执行错误 |
+| `raw` | `chunk` | 未识别的原始分片 |
+
+---
+
+## API 参考
+
+### `AgentChatClient`
+
+#### `constructor(config: AgentChatClientConfig)`
+
+创建客户端实例。
+
+#### `chatStream(options, handlers?): Promise<void>`
+
+发起一次流式对话。
+
+**`options`（`AgentChatStreamOptions`）**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `query` | `string` | 用户问题 |
+| `dataMode` | `'normalized' \| 'raw' \| 'both'` | 数据模式，默认 `normalized` |
+| `signal` | `AbortSignal` | 外部取消信号 |
+| `extraBody` | `object` | 合并到请求体 |
+| `extraHeaders` | `object` | 合并到请求头 |
+
+**`handlers`（`AgentChatStreamHandlers`）**
+
+| 回调 | 说明 |
+|------|------|
+| `onEvent` | 收到标准化事件 |
+| `onRawChunk` | 收到原始 SSE 分片（`dataMode` 为 `raw` 或 `both`） |
+| `onError` | 请求或解析异常 |
+| `onComplete` | 流正常结束 |
+
+#### `streamEvents(options): AsyncGenerator<AgentStreamEvent>`
+
+以异步迭代器消费事件，适合 `for await...of`：
+
+```typescript
+for await (const event of client.streamEvents({ query: '你好' })) {
+  if (event.type === 'answer_delta') {
+    updateUI(event.content);
+  }
+}
+```
+
+#### `abort(): void`
+
+中止当前进行中的流式请求。
+
+#### `updateConfig(partial): void` / `getConfig()` / `getUrl()`
+
+更新配置、读取配置、获取当前请求 URL。
+
+---
+
+## 进阶用法
+
+### 1. 会话状态聚合（可选）
+
+若不想逐事件手写 UI 逻辑，可使用内置状态机：
+
+```typescript
+import {
+  AgentChatClient,
+  createSessionState,
+  applyEventToSession,
+} from 'agent-chat-sdk-core';
+
+let session = createSessionState('用户问题');
+
+await client.chatStream({ query: '用户问题' }, {
+  onEvent: (event) => {
+    session = applyEventToSession(session, event);
+    // session.status / session.processes / session.answerContent
+    bindToYourUI(session);
+  },
+});
+```
+
+### 2. 仅使用解析器（无 HTTP）
+
+自行拿到 `ReadableStream` 或 SSE 文本行时：
+
+```typescript
+import {
+  parseSSELine,
+  readSSEStream,
+  createNormalizeContext,
+  normalizeRawChunk,
+} from 'agent-chat-sdk-core';
+
+const ctx = createNormalizeContext();
+
+// 按行解析
+const chunk = parseSSELine('data: {"type":"thinking","content":"..."}');
+if (chunk && chunk !== 'end') {
+  const events = normalizeRawChunk(chunk, ctx);
+  events.forEach(handleEvent);
+}
+
+// 或从 Response.body 读取
+await readSSEStream(response.body!, (raw) => {
+  normalizeRawChunk(raw, ctx).forEach(handleEvent);
+});
+```
+
+### 3. 中止请求
+
+```typescript
+const controller = new AbortController();
+
+client.chatStream(
+  { query: '...', signal: controller.signal },
+  { onEvent: handleEvent },
+);
+
+// 用户点击停止
+controller.abort();
+// 或
+client.abort();
+```
+
+### 4. React 集成示例
+
+```tsx
+const [answer, setAnswer] = useState('');
+const [steps, setSteps] = useState<ProcessStep[]>([]);
+const [loading, setLoading] = useState(false);
+
+const send = async (query: string) => {
+  setLoading(true);
+  setAnswer('');
+  setSteps([]);
+
+  const client = new AgentChatClient({ url: chatApiUrl, appId, appKey });
+
+  try {
+    await client.chatStream({ query }, {
+      onEvent: (event) => {
+        if (event.type === 'answer_delta') setAnswer(event.content);
+        if (event.type === 'thinking_end') {
+          setSteps((s) => [...s, { type: 'thinking', time: event.runningTime }]);
+        }
+        if (event.type === 'tool_call_end') {
+          setSteps((s) => [...s, { type: 'tool', title: event.title, time: event.runningTime }]);
+        }
+        if (event.type === 'stream_end') setLoading(false);
+        if (event.type === 'error') {
+          setAnswer(event.message);
+          setLoading(false);
+        }
+      },
+    });
+  } catch {
+    setLoading(false);
+  }
+};
+```
+
+本仓库 Demo 的适配层见：`src/lib/stream-to-message.ts`。
+
+---
+
+## 推荐 UI 映射
+
+| 阶段 | SDK 推送数据 | 常见 UI（可选） |
+|------|-------------|----------------|
+| 等待首包 | — | Loading |
+| `thinking_delta` | `delta`, `content`（累积全文） | 仅「思考中」，**可不渲染 content** |
+| `thinking_end` | `content`, `runningTime` | 「深度思考成功，用时 Xs」 |
+| `tool_call_end` | `content`, `runningTime` | 「XX 成功，用时 Xs」，**可不渲染 content** |
+| `answer_delta` | `content`（累积全文） | 流式展示最终回复 |
+| `error` | `message`, `detail` | 错误摘要 + 可展开详情 |
+
+本仓库 Demo 的 `ChatMessage` 默认 `showProcessContent={false}`，数据仍写入 `message.processes[].content` 供其他场景使用。
+
+---
+
+## 导出清单
+
+```typescript
+// 客户端
+export { AgentChatClient } from './client';
+
+// 解析与归一化
+export { parseSSELine, readSSEStream, isStreamEndSignal } from './parser';
+export { normalizeRawChunk, createNormalizeContext, finalizeNormalizeContext } from './normalizer';
+
+// 会话状态（可选）
+export { createSessionState, applyEventToSession } from './session';
+
+// 文档常量
+export { REACT_SSE_TYPE_MAP } from './react-flow';
+
+// 类型
+export type { AgentChatClientConfig, AgentStreamEvent, RawSSEChunk, ... } from './types';
+```
+
+---
+
+## 常见问题
+
+### Q: 为什么收不到 `answer_delta`？
+
+检查服务端是否返回 `type: "answer"` 及 `content` 字段；也可先用 `dataMode: 'raw'` 打印原始分片排查。
+
+### Q: 思考内容要不要展示？
+
+SDK 会在 `thinking_delta` 中累积全文，但是否展示由使用方决定。ReAct 场景建议思考中仅显示状态，结束后显示耗时。
+
+### Q: 工具调用为什么只有一条事件？
+
+若服务端一次返回完整工具结果（含 `running_time`），SDK 会连续推送 `tool_call_start` 与 `tool_call_end`，UI 可分别展示「调用中」和「调用完成」。
+
+### Q: 流结束后无法再次发送？
+
+确保在 `stream_end` 或 `onComplete` 中重置 loading 状态；必要时调用 `client.abort()` 后再发下一条。
+
+---
+
+## 开发与发布
+
+```bash
+npm install        # 安装开发依赖（typescript / vitest）
+npm run typecheck  # 类型检查
+npm test           # 运行单元测试
+npm run build      # 构建双格式产物到 dist/（ESM + CJS + d.ts）
+npm pack --dry-run # 发布前干跑，检查 tarball 内容
+npm publish        # 发布（prepublishOnly 会自动执行检查与构建）
+```
+
+## 相关文件
+
+| 路径 | 说明 |
+|------|------|
+| `src/client.ts` | HTTP 请求与流调度 |
+| `src/parser.ts` | SSE 行解析 |
+| `src/normalizer.ts` | ReAct 事件归一化 |
+| `src/session.ts` | 可选会话状态机 |
+| `src/knowledge-label.ts` | 知识库引用标注解析 |
+| `src/react-flow.ts` | 交互时序说明 |
+| `src/types.ts` | 类型定义 |
+| `tests/` | 单元测试（解析 / 归一化 / 会话 / 标注 / 客户端） |