Text Insight · 文本分析工作台

把一份文本或整个目录变成可比较、可交互、可导出的分析报告。命令行完成批量处理，独立 HTML 展示词频、文档统计与相似度矩阵，保存后可以直接在浏览器中打开。

Python 3.10+，运行时只用标准库。文本在本机处理，HTML 的样式、脚本和数据全部内嵌，分析与查看报告都无需联网。

先看效果：一键演示

在项目根目录执行，无需安装项目：

python examples/demo.py

Windows 也可使用 py -3 examples/demo.py，下文的 python 命令同样可以替换为 py -3。

脚本读取 examples/corpus/ 中的三篇原创演示文本，生成 examples/demo-report.html 并打开浏览器。两篇围绕开源协作和网络服务，一篇讨论城市园艺，内容混合中英文。报告中的数值由程序实际计算。

只生成报告：

python examples/demo.py --no-open

在报告中切换文档、搜索高频词、比较两篇文档，再查看相似度矩阵与导出的 JSON。浏览器未自动打开时，直接双击 examples/demo-report.html。

能做什么

• 单文件统计：字符、词元、句子、段落、行数、平均词长、词汇多样性与粗略阅读时长。
• 批量分析：多个文件、目录、递归扫描与自定义文件匹配模式，也支持从标准输入读取。
• 可解释比较：使用完整词频计算文档余弦相似度，展示所有文档的比较矩阵。
• 五种输出：终端文本、JSON、Markdown、CSV、独立 HTML。
• 交互报告：词频搜索、文档切换、文档对比、相似度矩阵、导出当前 JSON。
• 自定义停用词：每行一个词元，支持空行与 # 注释。

安装与运行

推荐在项目根目录安装可编辑版本：

python -m pip install -e .
text-insight --version
text-insight examples/sample.txt

安装构建依赖可能使用网络；安装完成后的分析与报告无需网络。也可以设置 PYTHONPATH 后直接运行源码。

PowerShell：

$env:PYTHONPATH = (Join-Path (Get-Location) "src")
python -m text_insight examples/sample.txt

Linux / macOS / 其他 POSIX Shell：

PYTHONPATH=src python -m text_insight examples/sample.txt

以下例子使用安装后的 text-insight 命令；直接运行源码时，把它替换成 python -m text_insight，并按上面的方法设置 PYTHONPATH。

命令与常用场景

text-insight INPUT [INPUT ...]
  --recursive
  --glob PATTERN
  --format {text,json,markdown,csv,html}
  --output PATH
  --stopwords PATH
  --top N
  --version

INPUT 可以是 UTF-8 文件、目录或标准输入 -。目录默认匹配 *.txt；--recursive 进入子目录；--glob 改变目录的匹配模式，仅接受相对模式，拒绝绝对路径与 .. 父目录路径。--top 控制展示的高频词数量，默认 10，须大于等于 1。省略 --output 时报告输出到终端。

单文件 JSON 与 Markdown：

text-insight examples/sample.txt --format json
text-insight examples/sample.txt --format markdown --output report.md

目录生成交互报告，或指定两个文件比较：

text-insight examples/corpus --format html --output report.html --top 15
text-insight examples/corpus/open-source-collaboration.txt examples/corpus/network-service.txt --format html --output report.html

递归分析 Markdown 笔记：

text-insight notes --recursive --glob '*.md' --format json --output output/notes.json

批量 CSV，方便在 Excel 中继续分析；保存为文件时使用 UTF-8 BOM：

text-insight examples/corpus --format csv --output output/documents.csv

自定义停用词：

text-insight examples/corpus --stopwords examples/stopwords.txt --top 8 --format html --output report.html

从标准输入分析（POSIX Shell）：

printf 'Hello network. Hello open source.\n' | text-insight - --format json

空文件会生成全零统计；路径不存在、无法读取、非 UTF-8 文本或非法参数会给出错误信息。输入接受 UTF-8 BOM。目录扫描会跳过当前输出文件和指定停用词文件；显式输入文件或停用词文件与输出指向同一文件时会拒绝写入，也覆盖硬链接等别名，保护原文。

统计口径：每个数都能解释

项目	计算方式
字符数	原始文本的 Unicode 字符数量，包括空白；另外提供非空白字符数
词元	Unicode 字母单词、数值词元，以及逐字提取的中文字符；统一大小写与 Unicode NFC 形式
中文处理	中文采用单字词元，例如“计算机网络”计为 5 个词元；没有使用中文词语分词模型
词汇多样性	不同词元数 ÷ 全部词元数，空文档为 0
停用词	从词频与相似度计算中排除指定词元；基础字数、词元总数与词汇多样性保留原始统计
句子 / 段落	句子按英文与中文句末标点估算，段落按空行分隔；缩写等特殊文本可能影响句子计数
粗略阅读时长	字母及数值词元按 240 个/分钟、中文单字按 400 个/分钟相加，结果向上取整为秒；这是明示速度假设下的估算
汇总词频	合并各文档过滤后的全部词频再取前 N 个，不把各文档的前 N 个直接相加
文档相似度	以过滤停用词后的完整词元原始计数为向量计算余弦值；--top 只影响展示，不改变相似度

余弦相似度计算：

similarity(A, B) = Σ(A词频 × B词频) / (√ΣA词频² × √ΣB词频²)

结果在 0 到 1 之间，表示词元分布的接近程度，不是语义评分或查重结论。任何一个词频向量为空时相似度为 0；非空文档与自身为 1。共享通用词、文档长度和中文单字处理都会影响结果，可以结合停用词和原文解释。

显式单文件 JSON 保留原有顶层字段，并增加中文字符、字母词元、数值词元、平均句长和阅读时长等字段。多文件或目录输入的 JSON 使用 documents、summary、similarities 三个部分；即使目录内只有一篇文档也采用此结构。CSV 提供便于表格处理的文档统计。

实现结构

examples/
├─ demo.py                     # 直接从源码调用 CLI，生成演示 HTML
├─ corpus/                     # 三份原创演示文档
├─ sample.txt
└─ stopwords.txt
src/text_insight/
├─ __main__.py                 # python -m text_insight 入口
├─ cli.py                      # 参数解析、文件收集、错误提示与输出
├─ analyzer.py                 # 词元、单文档统计与阅读时长
├─ corpus.py                   # 完整词频汇总与文档余弦相似度
├─ reporters.py                # 文本、JSON、Markdown、CSV 与 HTML 入口
└─ dashboard.py                # 独立 HTML 的样式、数据与交互
tests/                         # 标准库 unittest 测试

处理流程是“收集文件 → 读取 UTF-8 → 统一词元 → 统计及比较 → 渲染报告”。分析层产生结构化结果，报告层负责表现，CLI 负责文件与参数；同一份数据可以输出成五种格式。

词频由 collections.Counter 统计，相似度使用完整词频向量。HTML 把结果嵌入页面，由浏览器中的 JavaScript 完成筛选和切换，报告拷贝到另一台电脑也能查看。文档比较需要计算两两组合，文档很多时计算量会增加。

验证

无需安装项目即可在根目录运行测试。

PowerShell：

$env:PYTHONPATH = (Join-Path (Get-Location) "src")
python -m unittest discover -s tests -v
python examples/demo.py --no-open

POSIX Shell：

PYTHONPATH=src python -m unittest discover -s tests -v
python examples/demo.py --no-open

测试检查统计与输出行为；HTML 的视觉与交互可以通过一键演示实际操作核验。

课堂两分钟演示

1. 0:00–0:20：运行 python examples/demo.py，说明输入是三份有完整内容的本地文本，输出是可独立打开的 HTML。
2. 0:20–0:50：切换开源协作和网络服务文档，搜索 network，展示词频随文档变化。解释中文单字与英文单词的处理口径。
3. 0:50–1:20：查看对比表和矩阵，比较开源协作、网络服务与园艺的词元分布。结合共享词元说明结果，展示余弦公式与停用词的作用。
4. 1:20–1:45：导出 JSON，展示批量 CSV 命令。说明分析层与报告层共用结构化结果，输出格式可以替换。
5. 1:45–2:00：运行测试，指出 --top 只改变展示，完整词频参与汇总和相似度计算；这使报告中的比较有可核验的依据。

License

采用 MIT License，便于学习、修改与复用；分发时保留版权与许可声明。