chinese-summary 1.0.1 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chinese-summary",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "中文文本概要提取库（TextRank + 位置加权 + TF-IDF + MMR）",
   "author": "郭玉峰, 吴琼 <gyfinjava@163.com> (北京锋通科技有限公司)",
   "license": "MIT",
@@ -38,7 +38,9 @@
     "dist",
     "src",
     "test",
-    "docs"
+    "docs",
+    "tsconfig.json",
+    "tsup.config.ts"
   ],
   "scripts": {
     "build": "tsup",

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig([
+  // CJS + ESM
+  {
+    entry: { "chinese-summary": "src/chinese-summary.ts" },
+    format: ["esm", "cjs"],
+    dts: true,
+    clean: true,
+    minify: false,
+    sourcemap: true,
+    outDir: "dist",
+    outExtension({ format }) {
+      return format === "esm" ? { js: ".mjs" } : { js: ".cjs" };
+    },
+  },
+  // IIFE：浏览器 <script> 标签引入
+  {
+    entry: { "chinese-summary": "src/chinese-summary.ts" },
+    format: ["iife"],
+    globalName: "ChineseSummary",
+    clean: false,
+    minify: false,
+    sourcemap: true,
+    outDir: "dist",
+    outExtension: () => ({ js: ".iife.js" }),
+  },
+]);