doc-stream-sdk

@alauda/doc-stream-sdk 是解析 Smart Doc v2（event-based）SSE 响应的 TypeScript SDK。它按 SSE event: 字段做语义路由，覆盖三层能力：

• v2 SSE 事件解析（快照 / 流式 / resume 续接）
• token / docs / tool_* / approval_* / error / end 的结构化拆分
• Markdown 整理与完整文档渲染

协议版本：本包是 v2-only。仍消费 v1（裸 data: 文本流 + <docs>/<plg-hf-*> 哨兵）的接入方请锁老版本 @alauda/[email protected]。v1/v2 由后端 X-Hyperflux-SSE 请求头协商，互不兼容。

安装

pnpm add @alauda/doc-stream-sdk

本地开发：

pnpm install
pnpm run build
pnpm test          # node --experimental-strip-types --test

快速开始

直接消费 fetch() 流（推荐）

import { consumeSmartDocV2DisplayStream } from '@alauda/doc-stream-sdk';

const response = await fetch('/smart-doc/api/smart_answer_with_search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Hyperflux-SSE': '2' },
  body: JSON.stringify(payload),
});

const display = await consumeSmartDocV2DisplayStream(response.body!, {
  onDisplayMessage(msg) {
    console.log(msg.content);    // 干净 markdown（token 拼接，\n\n 不截帧）
    console.log(msg.refDocs);    // 结构化引用文档
    console.log(msg.toolTrace);  // 工具调用轨迹
  },
});

解析完整快照

import { parseSmartDocV2DisplayMessage } from '@alauda/doc-stream-sdk';

const display = parseSmartDocV2DisplayMessage(rawSseSnapshot);
console.log(display.content, display.refDocs, display.usage);

审批暂停 / 续接（resume）

当工具命中审批门，后端发 approval_paused 并关闭流。拿到用户决定后，用 同一个 SmartDocV2Session 把 /smart_answer/resume 的流续接上去——正文从 上一段末尾继续累计，已处理过的 approval_id 不会重复触发暂停。

import { SmartDocV2Session } from '@alauda/doc-stream-sdk';

const session = new SmartDocV2Session();

await session.consume(firstStream, {
  onDisplayMessage: render,
  onPaused(approval) {
    // 展示审批卡片；用户决定后：
    waitForDecision(approval).then(async () => {
      const resumeResp = await fetch(approval.resumeUrl!, { method: 'GET' });
      await session.resume(resumeResp.body!, { onDisplayMessage: render });
    });
  },
});

UI（审批卡片、决定回传）由接入方持有；SDK 只负责流控（多段拼接 + 去重）。

核心规则

• 按 SSE event: 字段路由，不 sniff data: 文本。
• data: 恒为单行 JSON 信封 → token 含 \n\n 不会截帧（修掉 v1 的根 bug）。
• start / heartbeat 不进正文、不塌 loading；data: [DONE] 忽略。
• approval_paused 是独立事件，永不进 token 文本。

事件目录

| event: | data: payload | 落到 SmartDocDisplayMessage | |---|---|---| | start | {conversation_id, session_id, mode, history_truncated, history_entries_loaded} | .start | | token | {text} | .content（拼接 + markdown 归一化） | | docs | {documents:[{content, cos_sim, path}]} | .refDocs（按 path 去重） | | tool_call | {id, name, args} | .toolTrace[]（status running） | | tool_result | {id, name, status, output_len} | .toolTrace[]（更新 status/outputLen） | | approval_required | {approval_id, nonce, tool, args} | .approval | | approval_paused | {approval_id, nonce, tool, resume_url} | .approval + onPaused | | error | {status_code, response, cause} | .errors[] | | end | {referenced_documents, truncated, usage} | .usage（+ 合并 referenced_documents） | | heartbeat | {} | 忽略（保活） |

文档

• API 说明：docs/api.md
• 规则说明：docs/rules.md
• 开发说明：docs/development.md

发布产物

对外入口是 src/index.ts，公开导出：

• consumeSmartDocV2DisplayStream
• SmartDocV2Session
• SmartDocV2Parser
• parseSmartDocV2DisplayMessage
• SmartDocV2Accumulator
• normalizeSmartDocReferenceDocs
• formatSmartDocMarkdown
• renderSmartDocMarkdownDocument
• 类型：SmartDocDisplayMessage / SmartDocV2Event / SmartDocApprovalState / SmartDocToolTraceItem / SmartDocUsage / SmartDocStartInfo 等