chinese-summary 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,255 @@
+# chinese-summary
+
+[![npm version](https://img.shields.io/npm/v/chinese-summary.svg)](https://www.npmjs.com/package/chinese-summary)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+中文文本概要提取库 — 纯机器算法，无 AI 依赖，零外部依赖。
+
+基于 TextRank + 位置加权 + TF-IDF 关键词加权 + MMR 多样性选句，支持 5 级压缩，可将长文压缩为一句话。
+
+## 特性
+
+- **零外部依赖** — 纯 TypeScript 实现，无需分词器、无需 AI 模型
+- **字级 n-gram** — 绕过中文分词，直接按字符滑动窗口计算相似度
+- **5 级压缩** — 从"不压缩"到"极致压缩为一句话"，灵活控制摘要长度
+- **位置加权** — 首段首句、段落首尾句获得更高先验权重
+- **TF-IDF 关键词加权** — 包含全文关键词的句子获得额外权重
+- **MMR 去冗余** — 选句时兼顾相关性和多样性，避免语义重复
+- **子句连词处理** — 极致压缩时自动剥离脱离上下文的连词
+- **健壮性** — 完善的输入校验、参数校验、数值安全防护
+
+## 安装
+
+```bash
+npm install chinese-summary
+```
+
+## 使用方式
+
+### Node.js（ESM）
+
+```ts
+import { extractSummary, rankSentences } from "chinese-summary";
+
+const text = "人工智能是计算机科学的重要分支。深度学习推动了AI的快速发展。自然语言处理取得了突破性进展。";
+
+// 默认：级别 3（中度压缩，约 30% 句子）
+const result = extractSummary(text);
+console.log(result.text);
+
+// 极致压缩：压缩为一句话
+const extreme = extractSummary(text, { compressionLevel: 1 });
+console.log(extreme.text);
+
+// 指定句子数量（兼容旧接口）
+const legacy = extractSummary(text, { sentenceCount: 2 });
+console.log(legacy.text);
+```
+
+### Node.js（CJS）
+
+```js
+const { extractSummary, rankSentences } = require("chinese-summary");
+
+const result = extractSummary(text, { compressionLevel: 3 });
+console.log(result.text);
+```
+
+### 浏览器（IIFE）
+
+```html
+<script src="node_modules/chinese-summary/dist/chinese-summary.iife.js"></script>
+<script>
+  var result = ChineseSummary.extractSummary(text, { compressionLevel: 2 });
+  console.log(result.text);
+</script>
+```
+
+### 浏览器（ES Module）
+
+```html
+<script type="module">
+  import { extractSummary } from "./node_modules/chinese-summary/dist/chinese-summary.mjs";
+  const result = extractSummary(text, { compressionLevel: 2 });
+</script>
+```
+
+## 压缩级别
+
+| 级别 | 说明 | 压缩策略 | 适用场景 |
+|------|------|----------|----------|
+| 1 | 极致压缩 | 子句级提取，拼接为一句话 | 标题生成、推送摘要 |
+| 2 | 高度压缩 | 约 20% 句子 + 多轮重排 | 短摘要、列表预览 |
+| 3 | 中度压缩 | 约 30% 句子（**默认**） | 通用摘要 |
+| 4 | 轻度压缩 | 约 50% 句子 | 长摘要、速读 |
+| 5 | 不压缩 | 返回全部句子 | 仅排序、调试 |
+
+压缩效果示例（1584 字 AI 文章）：
+
+| 级别 | 输出字数 | 压缩率 |
+|------|----------|--------|
+| 1 | 69 字 | 95.6% |
+| 2 | 408 字 | 74.2% |
+| 3 | 536 字 | 66.2% |
+| 4 | 886 字 | 44.1% |
+| 5 | 1603 字 | -1.2% |
+
+## API
+
+### `extractSummary(text, options?)`
+
+提取中文文本概要，返回 `SummaryResult`：
+
+```ts
+interface SummaryResult {
+  summary: string[];          // 摘要句子（按原文顺序）
+  sentences: SentenceInfo[];  // 所有句子及其得分
+  text: string;               // 摘要文本（句子间用空格连接）
+  compressionLevel: 1|2|3|4|5;
+  clauses?: ClauseInfo[];     // 子句信息（仅级别 1）
+}
+```
+
+### `rankSentences(text, options?)`
+
+仅获取句子得分排名，不提取摘要。返回 `SentenceInfo[]`（按得分降序）。
+
+## 配置选项
+
+### 压缩控制
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `compressionLevel` | `1\|2\|3\|4\|5` | `3` | 压缩级别，与 `sentenceCount` 互斥 |
+| `sentenceCount` | `number` | `3` | 摘要句子数（旧接口） |
+| `maxClauses` | `number` | `3` | 极致压缩最大子句数（仅级别 1） |
+
+### TextRank 算法
+
+| 选项 | 类型 | 默认值 | 范围 | 说明 |
+|------|------|--------|------|------|
+| `ngramSize` | `number` | `2` | 1-5 | n-gram 大小 |
+| `dampingFactor` | `number` | `0.85` | 0.1-0.95 | 阻尼系数 |
+| `maxIterations` | `number` | `30` | 1-200 | 最大迭代次数 |
+| `convergenceThreshold` | `number` | `0.0001` | 1e-8~1 | 收敛阈值 |
+
+### 位置权重
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `weightFirstSentence` | `number` | `1.5` | 首段首句权重 |
+| `weightFirstParagraph` | `number` | `1.2` | 首段其他句权重 |
+| `weightParagraphStart` | `number` | `1.1` | 段落首句权重 |
+| `weightParagraphEnd` | `number` | `1.05` | 段落末句权重 |
+
+### 多样性与关键词
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `mmrLambda` | `number` | `0.7` | MMR 多样性系数 λ（0.3-1.0） |
+| `keywordWeight` | `number` | `1.2` | 关键词权重系数（0=关闭） |
+
+## 更多示例
+
+```ts
+// 调整多样性：0.3=最大多样性，1.0=纯得分排序
+extractSummary(text, { compressionLevel: 3, mmrLambda: 0.3 });
+
+// 调整主题聚焦度：0=关闭，2.0+=强聚焦
+extractSummary(text, { compressionLevel: 3, keywordWeight: 2.0 });
+
+// 极致压缩为 5 个子句
+extractSummary(text, { compressionLevel: 1, maxClauses: 5 });
+
+// 获取句子排名（调试用）
+const ranked = rankSentences(text);
+ranked.slice(0, 5).forEach(s => console.log(`[${s.score.toFixed(4)}] ${s.text}`));
+
+// 强化首段首句（适合新闻）
+extractSummary(text, { compressionLevel: 3, weightFirstSentence: 2.0 });
+```
+
+## 构建产物
+
+| 文件 | 格式 | 适用环境 |
+|------|------|----------|
+| `dist/chinese-summary.cjs` | CJS | Node.js `require()` |
+| `dist/chinese-summary.mjs` | ESM | Node.js `import`、浏览器 `<script type="module">` |
+| `dist/chinese-summary.iife.js` | IIFE | 浏览器 `<script>` 标签，全局变量 `ChineseSummary` |
+| `dist/chinese-summary.d.ts` | 类型声明 | TypeScript 智能提示 |
+
+## 从源码构建
+
+```bash
+git clone https://github.com/cn-dev/chinese-summary.git
+cd chinese-summary
+npm install
+npm run build
+```
+
+## 运行测试
+
+```bash
+# 基础功能测试
+npx tsx test/test.ts
+
+# 长文本测试（约 2000 字）
+npx tsx test/test-long.ts
+
+# 健壮性测试（74 项边界用例）
+npx tsx test/test-robust.ts
+```
+
+## 算法说明
+
+本库从零实现了 TextRank 算法（未引用任何第三方库），在此基础上加入了：
+
+- **位置先验权重** — 首段首句、段落首尾句获得更高初始分数
+- **TF-IDF 关键词加权** — 以句子为文档，字级 unigram 提取关键词，包含关键词的句子获得额外权重
+- **MMR 多样性选句** — `MMR(s) = λ×score(s) - (1-λ)×max_sim(s, 已选集)`，避免语义重复
+- **子句连词处理** — 极致压缩时自动剥离脱离上下文的连词（如"然而""因此"）
+
+## 项目结构
+
+```
+chinese-summary/
+├── src/
+│   └── chinese-summary.ts    # 核心源码（单文件，约 1200 行）
+├── dist/                      # 构建产物
+├── test/
+│   ├── test.ts                # 基础功能测试
+│   ├── test-long.ts           # 长文本测试
+│   └── test-robust.ts         # 健壮性测试（74 项）
+├── docs/
+│   ├── usage-guide.md         # 详细使用指南
+│   └── test-report.md         # 测试报告
+├── tsconfig.json              # TypeScript 配置
+├── tsup.config.ts             # 构建配置
+└── package.json
+```
+
+## License
+
+MIT License
+
+Copyright (c) 2025 北京锋通科技有限公司
+
+Authors: 郭玉峰, 吴琼
+
+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/docs/test-report.md

@@ -0,0 +1,231 @@
+# chinese-summary 测试报告
+
+> 测试日期：2026-06-16
+> 测试环境：Node.js + tsx
+> 测试版本：chinese-summary@1.0.0
+
+## 测试概览
+
+| 测试文件 | 用例数 | 通过 | 失败 | 结果 |
+|----------|--------|------|------|------|
+| `test/test.ts` — 基础功能 | 5 组 | 5 组 | 0 | PASS |
+| `test/test-robust.ts` — 健壮性 | 74 项 | 74 项 | 0 | PASS |
+| `test/test-long.ts` — 长文本 | 3 组 | 3 组 | 0 | PASS |
+| **合计** | **82 项/组** | **82** | **0** | **ALL PASS** |
+
+---
+
+## 一、基础功能测试（test/test.ts）
+
+### 1.1 多级压缩对比
+
+测试文本为 261 字的量子计算介绍（4 段 9 句），各级别输出如下：
+
+| 级别 | 输出字数 | 句数 | 压缩率 | 说明 |
+|------|----------|------|--------|------|
+| 1 | 57 字 | — | 78.2% | 极致压缩，子句级提取拼接为一句话 |
+| 2 | 50 字 | 2 句 | 80.8% | 高度压缩，多轮重排精选核心句 |
+| 3 | 95 字 | 3 句 | 63.6% | 中度压缩，TextRank + MMR 选句 |
+| 4 | 144 字 | 5 句 | 44.8% | 轻度压缩，保留约半数句子 |
+| 5 | 263 字 | 9 句 | -0.8% | 不压缩，仅排序（字数微增因空格连接） |
+
+**级别 1 子句得分：**
+
+| 得分 | 来源句子 | 子句文本 |
+|------|----------|----------|
+| 1.5202 | 句3 | IBM和微软等科技巨头都在积极投入量子计算的研究。 |
+| 1.4217 | 句4 | 量子计算目前仍面临许多技术挑战。 |
+| 1.1595 | 句1 | 与经典计算机使用比特（0或1）不同， |
+| 0.2855 | 句7 | 尽管如此， |
+| 0.2668 | 句3 | 谷歌、 |
+| 0.2612 | 句4 | 然而， |
+| 0.2214 | 句1 | 可以同时处于0和1的叠加态。 |
+
+> 连词"尽管如此，""然而，"被自动剥离，保证可读性。
+
+### 1.2 旧接口兼容性（sentenceCount）
+
+| 参数 | 输出字数 | 句数 |
+|------|----------|------|
+| `sentenceCount=2` | 67 字 | 2 句 |
+
+> 旧接口 `sentenceCount` 正常工作，与 `compressionLevel` 互斥时后者优先。
+
+### 1.3 极致压缩 maxClauses 参数对比
+
+| maxClauses | 输出 |
+|------------|------|
+| 2 | 量子计算是一种利用量子力学原理进行计算的新型计算模式。量子计算机使用量子比特， |
+| 3 | 量子计算是一种利用量子力学原理进行计算的新型计算模式。量子计算机使用量子比特，科学家们对量子计算的未来保持乐观。 |
+| 4 | 量子计算是一种利用量子力学原理进行计算的新型计算模式。量子计算机使用量子比特，IBM和微软等科技巨头都在积极投入量子计算的研究。科学家们对量子计算的未来保持乐观。 |
+| 5 | 量子计算是一种利用量子力学原理进行计算的新型计算模式。量子计算机使用量子比特，IBM和微软等科技巨头都在积极投入量子计算的研究。量子计算目前仍面临许多技术挑战。科学家们对量子计算的未来保持乐观。 |
+
+### 1.4 短文本保护
+
+| 输入 | 输出 |
+|------|------|
+| "今天天气很好，适合出门散步。" | "今天天气很好，适合出门散步。" |
+
+> 短文本（仅 1 句）在级别 1 下原样返回，不会丢失内容。
+
+---
+
+## 二、健壮性测试（test/test-robust.ts）
+
+共 74 项断言，全部通过。按类别分布如下：
+
+### 2.1 空值 / 非法输入（7 项）
+
+| 用例 | 预期行为 | 结果 |
+|------|----------|------|
+| `null` | 返回空结果 | PASS |
+| `undefined` | 返回空结果 | PASS |
+| 数字 `123` | 返回空结果 | PASS |
+| 空字符串 `""` | 返回空结果 | PASS |
+| 纯空白 `"   "` | 返回空结果 | PASS |
+| 纯换行 `"\n\n\n"` | 返回空结果 | PASS |
+| 纯制表符 `"\t\t"` | 返回空结果 | PASS |
+
+### 2.2 特殊字符（8 项）
+
+| 用例 | 预期行为 | 结果 |
+|------|----------|------|
+| BOM + 零宽字符 | 正常处理 | PASS |
+| BOM 被移除 | BOM 不出现在输出中 | PASS |
+| 中文引号 `""` | 正常处理 | PASS |
+| 书名号+圆括号 `《》()` | 正常处理 | PASS |
+| 全角空格+省略号 | 正常处理 | PASS |
+| 混合换行符 `\r\n/\r/\n` | 正常处理 | PASS |
+| Emoji | 正常处理 | PASS |
+| HTML 实体 ` ` | 正常处理 | PASS |
+
+### 2.3 极端参数（14 项）
+
+| 用例 | 预期行为 | 结果 |
+|------|----------|------|
+| `compressionLevel=0` | 自动修正为有效值 | PASS |
+| `compressionLevel=99` | 自动修正为有效值 | PASS |
+| `compressionLevel=-1` | 自动修正为有效值 | PASS |
+| `compressionLevel=1.5` | 自动修正为有效值 | PASS |
+| `ngramSize=0` | 自动修正为默认值 | PASS |
+| `ngramSize=100` | 自动修正为默认值 | PASS |
+| `dampingFactor=0` | 自动修正为默认值 | PASS |
+| `dampingFactor=2` | 自动修正为默认值 | PASS |
+| `maxIterations=0` | 自动修正为默认值 | PASS |
+| `minSentenceLength=-1` | 自动修正为默认值 | PASS |
+| `maxClauses=0` | 自动修正为默认值 | PASS |
+| `sentenceCount=NaN` | 自动修正为默认值 | PASS |
+| `sentenceCount=Infinity` | 自动修正为默认值 | PASS |
+| `weightFirstSentence=NaN` | 自动修正为默认值 | PASS |
+
+### 2.4 极短文本（4 项）
+
+| 用例 | 预期行为 | 结果 |
+|------|----------|------|
+| 2 字文本 "你好" | 空结果（低于 minSentenceLength） | PASS |
+| 5 字文本 "你好世界！" | 正常处理 | PASS |
+| 单句级别 1 | 正常处理 | PASS |
+| 单段 3 句级别 3 | 正常处理 | PASS |
+
+### 2.5 无句末标点（1 项）
+
+| 用例 | 预期行为 | 结果 |
+|------|----------|------|
+| 无句末标点文本 | 整段作为一个句子 | PASS |
+
+### 2.6 纯英文 / 混合（2 项）
+
+| 用例 | 预期行为 | 结果 |
+|------|----------|------|
+| 纯英文 | 正常处理 | PASS |
+| 中英混合 | 正常处理 | PASS |
+
+### 2.7 重复文本（1 项）
+
+| 用例 | 预期行为 | 结果 |
+|------|----------|------|
+| 完全重复句子 | 正常处理 | PASS |
+
+### 2.8 rankSentences 健壮性（4 项）
+
+| 用例 | 预期行为 | 结果 |
+|------|----------|------|
+| `rankSentences(null)` | 返回空数组 | PASS |
+| `rankSentences('')` | 返回空数组 | PASS |
+| `rankSentences(42)` | 返回空数组 | PASS |
+| `rankSentences(正常文本)` | 返回非空数组 | PASS |
+
+### 2.9 结果完整性校验（25 项）
+
+对 5 个压缩级别逐一校验，每级 5 项断言：
+
+| 校验项 | 级别1 | 级别2 | 级别3 | 级别4 | 级别5 |
+|--------|-------|-------|-------|-------|-------|
+| `summary` 非空 | PASS | PASS | PASS | PASS | PASS |
+| `sentences` 非空 | PASS | PASS | PASS | PASS | PASS |
+| `text` 是字符串 | PASS | PASS | PASS | PASS | PASS |
+| `compressionLevel` 正确 | PASS | PASS | PASS | PASS | PASS |
+| `text === summary.join(' ')` | PASS | PASS | PASS | PASS | PASS |
+| 所有句子得分为有限数 | PASS | PASS | PASS | PASS | PASS |
+
+### 2.10 子句拼接标点去重（3 项）
+
+| 校验项 | 结果 |
+|--------|------|
+| 无 `。，` 重复标点 | PASS |
+| 无 `，，` 重复标点 | PASS |
+| 标点去重后仍有内容 | PASS |
+
+---
+
+## 三、长文本测试（test/test-long.ts）
+
+测试文本为 1584 字的 AI 发展史文章（8 段 20+ 句）。
+
+### 3.1 各级别压缩效果
+
+| 级别 | 输出字数 | 句数 | 压缩率 | 说明 |
+|------|----------|------|--------|------|
+| 1 | 69 字 | — | 95.6% | 极致压缩，3 个子句拼接为一句话 |
+| 2 | 408 字 | — | 74.2% | 高度压缩，多轮重排精选核心句 |
+| 3 | 536 字 | — | 66.2% | 中度压缩，TextRank + MMR 选句 |
+| 4 | 886 字 | — | 44.1% | 轻度压缩，保留约半数句子 |
+| 5 | 1603 字 | — | -1.2% | 不压缩，仅排序（字数微增因空格连接） |
+
+### 3.2 极致压缩 maxClauses 参数对比
+
+| maxClauses | 输出字数 | 压缩率 |
+|------------|----------|--------|
+| 2 | 49 字 | 96.9% |
+| 3 | 69 字 | 95.6% |
+| 4 | 94 字 | 94.1% |
+| 5 | 116 字 | 92.7% |
+| 6 | 145 字 | 90.8% |
+
+### 3.3 句子得分排名 Top-10
+
+| 排名 | 得分 | 位置标记 | 句子（前 60 字） |
+|------|------|----------|------------------|
+| 1 | 2.1302 | 首段首句 | 人工智能（Artificial Intelligence，简称AI）是计算机科学的一个重... |
+| 2 | 2.0271 | — | 2022年底，ChatGPT的发布更是引发了全球性的AI应用热潮，让普通大... |
+| 3 | 1.7314 | — | 欧盟于2023年通过了《人工智能法案》，成为全球首个对AI进行全面立... |
+| 4 | 1.7042 | 段尾 | AlphaGo的胜利不仅证明了AI在复杂决策任务上的能力，也标志着人工... |
+| 5 | 1.7024 | — | 这次会议被认为是人工智能学科诞生的标志，标志着人类开始系统地研究... |
+| 6 | 1.6668 | 首段+段尾 | 人工智能的发展可以追溯到20世纪50年代，当时一批具有远见卓识的科... |
+| 7 | 1.5541 | 段首 | 自然语言处理是人工智能最活跃的研究方向之一。 |
+| 8 | 1.5183 | 段首 | 然而，人工智能的快速发展也带来了一系列社会问题和伦理挑战。 |
+| 9 | 1.4769 | — | 中国也出台了《生成式人工智能服务管理暂行办法》，对AI内容的生成和... |
+| 10 | 1.4715 | 段首 | 进入21世纪后，随着计算能力的大幅提升、大数据的积累以及算法的突破... |
+
+> 位置加权效果明显：首段首句得分最高（2.1302），段首/段尾句子普遍排名靠前。
+
+---
+
+## 四、测试结论
+
+1. **功能完整性**：5 级压缩、sentenceCount 旧接口、maxClauses 参数、rankSentences 排名均正常工作。
+2. **健壮性**：74 项边界用例全部通过，库对 null/undefined/空字符串/特殊字符/极端参数/极短文本等场景均有完善防护，不会崩溃。
+3. **压缩效果**：以 1584 字长文为例，级别 3（默认）压缩至 536 字（压缩率 66.2%），级别 1 极致压缩至 69 字（压缩率 95.6%），各级别压缩比例符合设计预期。
+4. **位置加权**：首段首句、段落首尾句的得分显著高于中间句子，符合中文文章"首段点题、段首概括"的结构特点。
+5. **子句连词处理**：极致压缩时，脱离上下文的连词（如"然而，""尽管如此，"）被正确剥离，保证输出可读性。
+6. **标点去重**：子句拼接时不会出现 `。，` 或 `，，` 等重复标点。