第二次作业

这个作业属于哪个课程	26软件技术基础
这个作业的目标	实现英文文本的命令行计数统计，掌握参数解析、文件处理、单元测试和性能分析，并完成代码行分类、词频分析与网页可视化等扩展功能
姓名-学号	翁毓阳-2024333503006

项目仓库： statistic_app

一、项目简介

本项目围绕“实现一个命令行文本计数统计程序”展开，使用 Python 统计 UTF-8 英文 TXT 文件的字符数、单词数和句子数，并通过 Windows 可执行程序 wc.exe 提供命令行接口。

当前版本为 v0.3。在基础计数之外，项目增加了代码行分类、Top10 英文词频和浏览器可视化网页。命令行与网页共用统计核心，翻译作为网页中的独立扩展提供。

主体源码位于 src/，测试位于 tests/，打包、验证与性能分析工具位于 tools/。网页的 HTML、CSS 和 JavaScript 内嵌在 Python 文件中，由本机 HTTP 服务提供；运行源码需要 Python 3.10+，核心功能只依赖标准库。

二、开发过程与关键修正

项目在原 wc-v0.1 目录中逐步完善，目录名保留，程序版本随阶段推进。

阶段	开发重点	形成的内容
v0.1 空项目	确定 Python 技术路线，搭建可运行的工程结构	程序入口、README、目录划分与忽略规则
v0.2 基础功能	完成字词句统计、命令行参数、测试与性能验证	基础计数、UTF-8 文件处理、样例、单元测试、Windows EXE 和大文件性能对比
v0.3 扩展功能	增加行分类、可视化及文本分析	文本／代码模式、浏览器网页、详细指标、Top10 和在线翻译
最终完善	核对界面、命令行、源码与 EXE 的一致性	命令行 Top10、最终性能复测、EXE 检查、清晰截图与 AI 使用记录

开发过程中，有三处需求需要反复明确：普通英文文章的“非空行”不能叫“代码行”；可视化界面应当是浏览器网页；网页扩展加入后，wc.exe -c file.txt、wc.exe -w file.txt 等命令仍是项目的主要入口。这些修正同时落实到了代码、测试和文档中。

三、主要功能：命令行文本计数

命令格式：

wc.exe [参数] [文件名]

功能	命令示例	统计含义
字符数	wc.exe -c file.txt	包含空白、标点及原始换行；开头的 UTF-8 BOM 不计入正文
英文单词数	wc.exe -w file.txt	按 ASCII 字母识别，允许内部直撇号和连字符；纯数字不计为词
句子数	wc.exe -s file.txt	按连续的 . ! ? 分隔，含字母或数字的有效片段计一句
总行数	wc.exe -l file.txt	统计物理行，包含空白行
综合统计	wc.exe --all file.txt	输出当前文本模式适用的全部计数

字符统计保留文件原始换行，因此 LF 算一个字符，CRLF 算两个字符。don't、well-known 各算一个英文单词。末尾没有终止标点的有效片段仍计为一句；缩写、小数和网址也遵循上述基础分隔规则。

项目提供的小样例如下，文件末尾保留 LF 换行：

Hello world!
Python makes text counting easy.
Ready to test?

实际运行：

> wc.exe -c file.txt
characters: 61
> wc.exe -w file.txt
words: 10
> wc.exe -s file.txt
sentences: 3

图 1 是在 VS Code 中查看的实际 EXE 运行记录，包含基础计数和扩展行统计。

完整参数、组合用法、错误处理和退出码详见仓库 README.md。

四、附加功能

1. 普通文本与代码文本分别统计

普通 TXT 默认按text 模式分析，显示总行、非空行和空白行。Python、C 等源文件在自动模式下进入 code模式，再增加代码行和纯注释行。

wc.exe --line-stats examples/source_sample.py
wc.exe --mode code --line-stats examples/mixed_sample.txt

第二条命令用于 TXT 中保存了代码的情况。也可以明确指定 --mode text，将文件作为普通正文分析。

代码模式支持 Python #和 C 风格 //、/* */ 注释。字符串中的注释标记属于字符串；含代码与行尾注释的行归为代码行；空白行优先计为空行；Python 三引号字符串按代码处理。这些规则用于轻量分类，支持范围详见 README。

2. 命令行与网页共用 Top10 词频

使用以下命令，可直接在 EXE 命令行显示英文词频：

wc.exe --top10 file.txt
wc.exe --all --top10 file.txt

--top10 的别名是 --top-words。结果忽略大小写、保留常用词，按次数降序排列，同频时按字母排序；每项显示单词、出现次数及占全部英文单词的百分比。--all 单独使用时仍只输出计数，需要词频时再显式添加 --top10。

图 2 展示最终 EXE 对小样例和约 32 MiB 英文文件的实际输出。其中大文件的最高频词 a出现 454,701 次，占 8.50%，与网页结果一致。

3. 浏览器可视化网页

通过 wc.exe --gui 启动网页，程序会选择空闲端口并打开实际地址。网页采用紫色与白色双栏布局：左侧导入或编辑文本，右侧展示统计卡片、详细指标、词频和翻译。

功能	网页中的使用方式
文件与正文输入	导入本地 TXT 或代码文件，也可以粘贴、输入和编辑
分析模式	自动识别，或手动选择普通文本／代码分析
主统计卡片	展示字符、单词、行数和句子数
详细指标	查看字符类别、段落、不同单词、平均词长、每句平均词数等
词频与时长	查看 Top10 条形图、全文占比及阅读／朗读时长估算
编辑与导出	大小写转换、整理多余空格、复制全文和下载 TXT

下面用两份样例对比最终界面：

指标	英文短文 sample.txt	Python 代码 source_sample.py
字符数	61	387
英文单词数	10	56
句子数	3	10
总行数	3	13
非空行	3	10
空白行	0	3
代码行	不适用	8
纯注释行	不适用	2

英文短文只区分非空行和空白行：

Python 示例的 13 行则分为 8 行代码、3 行空白、2 行纯注释。代码和注释中的英文也参与全文词句统计，界面中的句子数不代表代码语句数。

超过 1 MiB 的文件提供前 6,000 字符的只读预览，统计、词频、复制和下载均使用完整原文。阅读与朗读时长分别按每分钟 200／130 个英文词估算，属于文本指标。

4. 网页专属英译中文

翻译区域优先处理选中的片段，没有选区时使用正文。只有点击翻译后，相应文本才会发送到 MyMemory 在线服务；单次最多 3,000 个字符，超限直接提示，大文件必须明确选中预览片段。

网络、服务额度或超时失败会提示错误并保留原文。计数和词频可离线运行，翻译需要联网。该功能仅在网页中提供，命令行没有翻译参数。

五、运行方法与验证结果

1. EXE 与源码入口

在 Windows CMD 中进入项目目录：

wc.exe -c file.txt
wc.exe -w file.txt
wc.exe --all --top10 file.txt
wc.exe --gui

PowerShell 中使用 .\wc.exe。打包程序面向 Windows x64，复制项目目录后无需另装 Python；已验证环境为 Windows 11。

使用 Python 3.10+ 运行源码：

python src/wc.py --all examples/sample.txt
python src/wc.py --top10 examples/sample.txt
python src/web_app.py --port 0

网页由运行程序的电脑处理文本，127.0.0.1 指向当前电脑自身。换一台电脑后，应在那台电脑上启动程序并打开它输出的本机地址。

2. 测试与性能

以下是仓库保存的 2026 年 10 月 29 日最终验证记录。

验证项目	结果
单元测试	303 项通过，失败、错误、跳过均为 0
独立 EXE 检查	73/73 项通过
大文件输入	原创英文种子构造，33,554,602 字节，约 32 MiB
最终源码 VS Code 完整分析	预热一次后正式测量三次，中位数 4006.058 ms，约 4.006 秒

测试覆盖基础计数、参数与退出码、分批匹配边界、文本／代码模式、行分类、词频、翻译异常及本地 HTTP 接口。翻译异常使用模拟请求测试，真实联网验证另外记录。

最终性能测量包含全文读取、六项基础统计、详细指标和词频分析，排除 HTTP／JSON、浏览器渲染、翻译、程序启动及报告写入。cProfile 在普通计时后独立运行。历史三项统计优化与最终完整分析的工作量不同，分别保留报告。

博客仅放四张功能展示图。更多规则、测试证据和性能截图可在仓库中查看：

• 完整用法、计数边界、文件清单与运行条件：README.md。
• 最终 VS Code 性能数据与热点解释：reports/final-vscode-performance/README.md。
• v0.2 优化前后对比：reports/PERFORMANCE.md。
• 单元测试与 EXE 验证：reports/unit-tests.txt、reports/executable-checks.json。
• 实际网页检查与截图说明：reports/GUI-CHECKS.md、screenshots/README.md。

六、AI 使用方式与开发体会

环节	AI 辅助内容	我的工作
需求与结构	拆解版本任务、整理模块与目录	确定阶段、语言、项目位置和功能范围
编码与修正	实现统计核心、行分类、网页、词频与翻译	纠正 TXT 行分类、网页形式及命令行功能边界
验证与交付	运行测试、性能分析和 EXE 检查，保存结果	核对功能、截图和数据，完成验收、提交与发布

这次开发让我更注意统计规则的定义。例如，“非空行”和“代码行”虽然可能得到相同数量，含义却不同；字符、单词和句子也都需要先约定边界，再通过测试验证。性能方面，需要先测量并找出热点，才能判断优化是否有效。

AI 给出的初始实现也需要审查。通过具体样例、错误反馈和运行结果逐步修正，比只检查页面是否能打开更能说明程序是否满足要求。

整份项目由用户提供提示词需求，智能体编写完成，根据完成情况进行修改与完善，最终由用户自行使用git相关命令语句上传项目仓库进行更新迭代，并添加三个版本的标签。主要AI提示词如下，具体可见仓库 AI_USAGE_AND_PROMPTS.md 。

（一）v0.1：空项目与 Python 技术路线

提示词 1：先搭建 Python 空项目

我要完成一个命令行文本计数作业，后续需要统计纯英文 TXT 文件的字符数、单词数和句子数，并逐步增加扩展功能。
整个项目采用 Python，先完成 v0.1 空项目，为后续 v0.2 基础功能和 v0.3 扩展功能保留清楚的结构。

请完成以下内容：
1. 建立可运行的 Python 入口，保留后续参数解析和统计模块的位置。
2. 区分主体源码、测试、示例数据、辅助工具和说明文档的用途。
3. 配置 .gitignore，忽略 Python 缓存、虚拟环境和打包中间文件。
4. README 先介绍项目目标、运行方法和分阶段计划。
5. 本阶段先交付工程骨架，后续在同一个项目中继续开发。
6. 仓库提交和上传由我自行完成，不代替我上传。

（二）v0.2：基础统计、测试与性能分析

提示词 2：实现基础功能并完善 README

在 v0.1 的基础上完成 v0.2，核心功能是读取英文 TXT 文件并统计字符、英文单词和句子。
提供 wc.exe [参数] [文件名] 形式的接口；源码也能通过 Python 直接运行。

请实现并说明：
1. -c 统计字符数，-w 统计英文单词数，-s 统计句子数，--all 输出全部基础统计。
2. 参数可以组合，帮助信息应说明用途；错误参数、缺失文件和无效编码应有清楚的提示及退出码。
3. 文件读取采用 UTF-8，兼容开头的 BOM，并保留原始换行用于字符计数。
4. 字符包括空白和标点；单词允许内部直撇号或连字符；句子采用明确的 . ! ? 分隔规则。
5. 对缩写、小数、网址、连续标点和末尾无句号等情况，写明当前规则的实际含义，不暗示已经实现完整自然语言分句。
6. README 包含项目简介、运行用法、文件清单、样例输入、运行命令和实际结果。

提示词 3：补足基础与边界情况的单元测试

为基础计数和命令行接口编写对应单元测试，使用项目现有的标准库 unittest。
测试应依据明确的输入和预期答案检查结果，并包含容易出错的边界情况。

至少覆盖：
1. 空文件、只有空白、多个空格、Tab、LF 和 CRLF 换行。
2. 大小写单词、标点相邻、don't、well-known，以及纯数字不计为英文词的规则。
3. 单个或连续句末标点、只有标点的片段、末尾没有终止符的有效片段。
4. UTF-8 BOM、中文路径、路径含空格、文件不存在、目录误作文件和无效 UTF-8。
5. 参数单独使用、组合使用、帮助、版本、错误参数及对应退出码。
6. 后续扩展功能加入后继续增加回归用例，保存真实日志和测试数量，并在 VS Code 中保留测试结果截图。

提示词 4：准备大文件，真实测量性能并解释热点

示例文本太小，无法说明大文件处理的性能。请另准备超过 10 MB 的纯英文 TXT，并说明它与 examples 中的小示例有什么区别。

请使用 VS Code 中的运行配置完成性能验证：
1. 先保留原有实现作为基线，再根据测量结果确定需要优化的地方。
2. 对同一输入预热后重复测量，保留每次耗时、中位数、环境和测量范围。
3. 使用独立 cProfile 观察函数热点，普通计时与剖析计时分开，不能混用。
4. 优化后检查字符、单词和句子结果与基线一致，补测分批匹配边界。
5. 根据实际热点说明优化原因；“逐字符读取改成整批读取”只是讨论中的示例，不能写成未发生过的项目经历。
6. 保存真实 IDE 截图、原始数据和数据解释，避免只给出一个缺乏范围说明的秒数。

提示词 5：保留作业要求的命令形式

请对照我附上的作业要求，检查项目是否确实支持命令行使用。
作业中的核心形式不可省略：
wc.exe [参数] [文件名]
wc.exe -c file.txt
wc.exe -w file.txt

请补齐 Windows 可执行程序和对应的运行示例；源码入口也应保留。
在项目目录中实际执行命令并记录结果，而不是仅在 README 中写几个未运行的命令。
CMD 与 PowerShell 的写法需要分别说明，PowerShell 中使用 .\wc.exe。
打包后检查参数、输出和错误处理，确保 EXE 对应当前源码。

（三）v0.3：行分类、网页可视化与词频扩展

提示词 6：扩展代码行、空行和注释行统计

在基础计数上增加总行、非空行、空白行、代码行和纯注释行，并提供相应命令接口。
保持已有字符、单词、句子统计可用，新增行分类要有独立模块和测试。

请明确分类规则：
1. 空文件为 0 行，结尾换行不凭空增加一行；空白行优先归为空行。
2. 支持 Python # 和 C 风格 //、/* */ 注释，并按文件类型或显式参数选择样式。
3. 字符串中的注释标记不能直接当作注释，含代码和行尾注释的行归代码行。
4. 本项目最终将 Python 三引号字符串按代码处理，并把这条规则写入文档和测试。
5. 用 --line-stats、--code-lines、--blank-lines、--comment-lines 等接口输出适用的统计。
6. 注释扫描按轻量规则实现，说明支持范围，不把它表述为完整语言解析器。

提示词 7：纠正普通英文 TXT 的代码行概念，增加网页形式

普通英文文章中的非空行不应被称为代码行，请修正这个概念和对应输出。
同时，可视化前端就是浏览器网页，请参考“ https://charactercounteronline.com/?utm_source=chatgpt.com ”这一网页，制作方面用户使用的前端界面

请统一 CLI 和网页的处理方式：
1. 普通 TXT 默认进入 text 模式，只显示总行、非空行和空白行。
2. Python、C 等源文件在自动模式下进入 code 模式，再增加代码行和注释行。
3. TXT 中实际存放代码时，可手动使用 --mode code；明确指定 --mode text 时按普通文本处理。
4. 普通 TXT 中的 #、网址里的 // 仍属于正文，不因标记出现就变成代码。
5. 网页提供导入、编辑和模式切换，统计计算复用 Python 核心。
6. 分别准备英文短文与 Python 代码样例，显示各自结果和行数关系，增加回归测试。

提示词 8：网页增加翻译，命令行继续作为核心

项目核心仍是命令行文本计数程序。网页可以有翻译扩展，但 wc.exe 不增加翻译参数。
必须继续支持 wc.exe -c file.txt、wc.exe -w file.txt 等基础命令。

网页翻译请完成以下行为：
1. 增加独立英译中文区域，有选区时优先翻译选中的片段。
2. 用户点击翻译后再发起请求，普通导入、编辑和统计不自动发送正文到外部服务。
3. 使用真实在线服务，说明网络要求、字符限制和分段规则。
4. 请求失败、超限或超时时给出提示并保留原文，不伪造离线翻译结果。
5. 基础计数和词频继续在本机完成，不依赖翻译服务是否可用。
6. 网络异常用模拟请求测试，真实联网结果另留运行记录。

提示词 9：把 Top10 英文词频加入 EXE 命令行

Top10 英文词频不能只在网页中使用，也要在最终 wc.exe 命令行中实现。
为该功能提供 --top10 参数，别名为 --top-words，并在帮助和 README 中说明。

要求如下：
1. 与网页使用相同的英文分词和频次统计实现，忽略大小写、保留常用词。
2. 最多输出十项，按次数降序，同频按字母排序。
3. 每项输出单词、出现次数和占全文英文单词总数的百分比，保留两位小数。
4. 支持单独使用，也支持与 -c、--all 等计数参数组合。
5. --all 单独使用时仍输出当前模式适用的计数；要追加词频，需明确指定 --top10。
6. 对空文件、无英文词、少于十词、同频、撇号和连字符、错误输入等情况补充测试。
7. 重建 EXE 后，实际运行小样例和大文件，核对网页、源码与 EXE 的结果一致。

（四）最终验证、AI 记录与博客整理

提示词 10：补齐最终版本的真实验证和截图

请检查当前源码、打包 EXE、测试日志、性能数据和截图是否对应，补齐最终版本的验证证据。
1. 在 VS Code 中实际运行最终源码性能任务，使用同一份 32 MiB 英文文件。
2. 预热后测量三次，再独立运行 cProfile，保存原始 JSON、文本日志、剖析数据和截图。
3. 说明计时包含文件读取、基础统计和附加分析，排除 HTTP／JSON、浏览器渲染、翻译和启动等开销。
4. 实跑最终 EXE 的独立检查，记录真实通过数量和与构建清单对应的哈希。
5. 在网页确认 Top10、主卡和只读预览的实际值，拍摄清晰画面；内部滚动列表用必要的补图展示。
6. 保留各批历史记录的实际范围，区分普通 CLI 测量、IDE 测量和 EXE 验证，不拿不同工作量计算加速比例。
7. 对工具中断、未完成或待补状态如实记录，恢复后核实结果再更新文档。

提示词 11：编写面向博客的项目介绍

根据现有项目和 README 写一份可直接用于博客的 Markdown。
请把仓库地址、项目目的和最关键的使用说明写清楚，正文控制在读者容易浏览的范围。

请分别介绍：
1. 主要功能：命令行字符、英文单词和句子统计，保留实际命令示例。
2. 附加功能：行分类、CLI／网页 Top10、可视化编辑、详细指标和网页翻译。
3. 普通英文文本与代码文本的不同统计界面及含义。
4. EXE 和 Python 源码的启动方式、跨电脑运行条件。
5. 简短概述真实测试和性能结果，详细规则、文件列表和测量数据指向仓库文档。
6. 使用已核对的仓库地址；博客发布和仓库上传仍由我自行完成。