第二次课程作业——我是懒人，但我的AI不是
| 这个作业属于哪个课程 | 26软件技术基础 |
|---|---|
| 这个作业的目标 | 用 Python 实现英文文本统计工具，练习命令行接口、Git 版本管理、单元测试与性能分析，并记录 AI 协作过程 |
| 姓名-学号 | 丁晓帆-2024326690034 |
WC 使用说明书：让电脑数单词，别让眼睛加班
以前看到一篇英文文章，我会先想：这题会不会考？现在还多了一个念头：这东西到底多少词？
于是，本次课程作业的产品登场了：WC，一个负责数数、暂时不负责拯救英语成绩的命令行工具。
它用 Python 编写，当前版本为 v0.4。原来的命令行继续上班，现在还多了一套 WC Studio 本地可视化界面：想敲命令可以，想用鼠标选文件也可以。懒人少敲几行，统计规则可没有跟着偷懒。
项目传送门：Gitee · word-counter-app
本文负责带你逛一圈、跑一次、看懂结果。完整规则、逐步手册、测试数据和 AI 记录，请到仓库按需领取。
01｜产品档案：本工具的工作范围
| 你交给它的任务 | 对应参数 | 它会交回什么 |
|---|---|---|
| 英文文本有多少字符？ | -c |
字符数，包含空格、标点、换行 |
| 有多少英文单词？ | -w |
按项目规则识别的单词数 |
| 有多少句话？ | -s |
按句末标点规则统计的句子数 |
| Python 文件有多少代码、空行和注释？ | -l |
三类行数，以及总行数 |
命令行一次运行选择一种统计模式；可视化界面则在选择文件后同时展示基础统计，Python 文件额外展示源码行分类。它接受 UTF-8 文本；源码行分类面向 Python。把 Java 文件塞进来再要求它理解 /* */，属于跨部门派活。
02｜三分钟开机：先让它数一份现成样本
电脑需要安装 Python 3.10 或更新版本，并且能在终端使用 python 命令。程序运行只依赖 Python 标准库。
先在 Gitee 点击“克隆/下载”，复制仓库地址；也可以直接运行：
git clone https://gitee.com/ding-dong132/word-counter-app.git
cd word-counter-app
已经有本地项目的同学，进入原来的项目文件夹即可，不必再克隆一套“备用宇宙”。终端可以使用 PowerShell、Git Bash 或 VS Code 内置终端。
在包含 wc.py 的目录执行：
python wc.py -c samples/sample.txt
python wc.py -w samples/sample.txt
python wc.py -s samples/sample.txt
这份样本为 Hello, world! This is a test.，末尾保留一个 LF 换行。实际结果：
Characters: 30
Words: 6
Sentences: 2
注意：上面三行来自三条命令。一条命令只选一个模式，不会一次打印三种统计。
想换成自己的文件？新建一个 UTF-8 编码的英文 TXT，先保存，再运行。文件名有空格时加引号：
python wc.py -w "my article.txt"
不知道参数怎么写，就请帮助页出场：
python wc.py -h
如果希望使用题目示例里的 wc.exe 形式，仓库 README 提供了 Windows 打包步骤。克隆源码不会自动得到 dist/wc.exe，需要先构建，再运行：
.\dist\wc.exe -w samples/sample.txt
v0.4 新增｜鼠标接班：选个文件，数字自动到岗
如果只想快速使用，不必先背命令。先安装 Python 3.10 或更新版本，再从仓库下载整个项目并完整解压，Windows 双击 启动可视化界面.cmd 即可。 不需要额外运行 pip install，也不要只下载 gui.py 一个文件；ui、samples 和 test_cases 等目录要保留原来的相对位置。
也可以在项目目录手动启动：
python gui.py
macOS / Linux 可使用 python3 gui.py。浏览器通常会自动打开 http://127.0.0.1:8765。这个地址代表使用者自己的电脑，不是一个可以分享给全班直接访问的在线网站。 每个人下载后在自己的电脑启动即可。界面不依赖作者的文件夹路径，文件仅在本机分析，不会传到外网，也不会把上传文件保存进项目。
图：实际打开并操作后的浏览器界面，基础统计卡片、Python 源码行占比图和只读预览同时展示。示例源码的代码、注释、空行各为 2 行，总计 6 行。这是本次运行截图，不是界面效果图。
| 在页面上做什么 | 接下来会发生什么 |
|---|---|
点击“选择文件”，或拖入一份 UTF-8 .txt / .py 文件 |
自动开始解析，一次处理一个文件，最大 20 MiB |
| 选择英文 TXT | 同时显示字符、单词和句子数量 |
| 选择 Python 源码 | 额外显示代码行、注释行、空行、总行数及占比图 |
| 切换左侧“解析方式” | 自动重新分析；TXT 里放的是 Python 代码时可手动选源码模式 |
| 查看“文件预览” | 只读显示正文；大文件仅预览前 12,000 个字符，统计仍覆盖全文 |
| 点击“导出报告” | 下载包含文件信息、统计结果和规则说明的 TXT 报告 |
| 选择错误编码的文件 | 显示中文提示、清除旧结果，避免误把上一份文件的数字当成新结果 |
第一次可以点击左侧的“短文本”“Python 源码”“长文章”示例。短文本应得到 30 个字符、6 个单词、2 个句子。1.4 MB 规模文件也已通过实际上传验证，结果为 1,400,000 个字符、250,000 个单词、100,000 个句子。
界面与命令行直接共用 wc.py 的统计函数，所以不是给同一道题另外发明一套答案。预览不会修改文件；用记事本改完原文后，要先保存，再重新选择文件。源码词法分析失败时会给出提示，基础文本统计仍可查看。
使用时保留启动服务的终端窗口。 浏览器没自动打开时，手动访问终端显示的地址；端口被占用可运行 python gui.py --port 8766。用完在终端按 Ctrl+C 停止服务。原来的 dist/wc.exe 仍是命令行程序，不是这次的浏览器界面入口。
03｜使用法则：数数之前，先统一口径
老师没有指定所有计数细则，因此项目把规则写进了 README，并据此设计测试。这里先交代最容易“数着数着就吵起来”的几项。
| 情况 | 本项目怎么数 | 为什么需要说明 |
|---|---|---|
| 空格、标点、Tab、换行 | 都计入字符数 | 肉眼没看见，不代表字符不存在 |
| LF 与 CRLF 换行 | 分别计 1、2 个字符 | 同样的两行文字，原始换行符可能不同 |
don't、it's |
各算 1 个单词 | 字母之间的撇号属于同一个词 |
well-known |
算 2 个单词 | 连字符作为单词边界 |
独立数字 123 |
算 0 个英文单词 | 当前单词规则识别英文字母 |
Hello?! |
算 1 句 | 连续句末标点只结束一句 |
| 最后一段没有句末标点，但有英文单词 | 仍算 1 句 | 不因为作者忘了句号就让它失踪 |
字符数不等于文件字节数；UTF-8 BOM 作为编码标记会被去掉。以上“单词”是项目约定的英文词形规则，不是词典检索。
句子统计也有能力边界。 例如 Mr. Smith arrived. 会被计为 2 句。当前实现按 . ! ? 分段，没有进行缩写识别和完整的自然语言分析；不能仅凭普通样本正确，就宣称所有英文文章都能按语义完美分句。
04｜扩展服务：代码和注释，也来报个数
v0.3 增加了 Python 源码行统计。试运行：
python wc.py -l test_cases/source_lines/01_basic.py
输出为：
Code lines: 2
Blank lines: 2
Comment lines: 2
Total lines: 6
分类遵循“每条物理行只领一个身份”的规则：
- 空白行：没有内容，或只有空格、Tab 等空白。
- 注释行：只有 Python 的
#注释，可以带缩进。 - 代码行：非空且含代码或字符串内容；同一行既有代码又有注释，归为代码行。
因此，print("#我只是字符串") 是代码，#我才是注释 才是注释。三引号字符串、文档字符串的非空行归为代码行，不把它们当作 # 注释。末尾换行也不会额外赠送一个空行——本工具暂未推出“满五行送一行”活动。
05｜仓库导览：别让文件夹把你劝退
第一次打开仓库，如果感觉每个文件都在说“你先看我”，可以按这张路线图走：
这是一张根据实际项目目录绘制的导览示意图，不是 Gitee 网页截图。文件名对应真实材料，右侧说明用于帮助快速定位。
| 你现在想做什么 | 去哪里 |
|---|---|
| 先了解功能和完整规则 | README |
| 看程序怎么实现 | wc.py |
| 找可视化界面入口与页面代码 | gui.py / ui |
| 跟着步骤自己打开、保存、运行文件 | 本地使用说明 |
| 对照案例逐步核对结果 | 测试操作手册 |
| 自己修改文字或源码练习 | manual_tests |
| 找固定案例、文章和大文件 | test_cases |
| 查自动测试逻辑 | tests |
| 看性能数据、截图和解读 | 性能测试报告 |
练习修改用 manual_tests，核对固定结果用 test_cases。 固定案例经过编辑器保存后，可能被改变换行方式或添加末尾换行；如果想改内容玩一玩，请先复制一份。否则就像把秤上的苹果换了，还坚持旧重量必须成立。
06｜验货现场：不能只证明 Hello World 会数数
在项目目录运行全部单元测试：
python -m unittest discover -s tests -v
当前测试结果为 38 个测试方法通过：原有基础 11 项、源码扩展 7 项、强化验证 12 项，加上本次界面与上传接口 8 项，包含基本统计、错误处理、编码与换行、源码分类和强化验证。其中一个方法还包含 200 组固定种子的组合子案例；这里没有把子案例重复包装成 200 个独立测试方法。
| 案例 | 规模 | 预期结果 |
|---|---|---|
| 原创英文文章 | 7,670 字符 | 1,248 单词、64 句 |
| 合成规模文本 | 1,400,000 字节 | 250,000 单词、100,000 句 |
| Python 规模源码 | 10,000 行 | 代码 4,000、空行 2,000、注释 4,000 |
想亲手验一次大文件，可以执行：
python wc.py -w test_cases/stress/06_megabyte_repeated.txt
python wc.py -l test_cases/stress/07_ten_thousand_lines.py
长文章用于检查连贯文本，重复合成数据用于检查规模，两者分工不同。固定案例的预期表与校验值放在仓库，便于复核，而不是让被测程序自己给自己批满分。
07｜性能体检：跑得对之后，再看看跑多久
单元测试回答“结果对不对”；性能分析进一步观察“时间花在哪”。两份成绩单不能互相冒充。
本项目对四种工作负载分别进行 2 次预热、9 次无分析器计时，并单独测量 Python 可追踪分配峰值。部分结果如下：
| 场景 | 正常运行中位耗时 | Python 分配峰值 |
|---|---|---|
| 文章单词统计 | 0.328 ms | 0.082 MiB |
| 1.4 MB 文本单词统计 | 36.885 ms | 15.981 MiB |
| 1.4 MB 文本句子统计 | 43.446 ms | 8.014 MiB |
| 万行源码分类 | 37.350 ms | 2.254 MiB |
这些是本机、本次输入、文件预热后的观察值；计时包括读取、统计和结果核对，不包括 Python 进程启动与模块导入。这里的内存是 Python 分配峰值，不是整个进程的内存占用。它不是“所有电脑都必须跑进这个数字”的产品承诺。
此外，在 VS Code 中使用 Nifty Python Profiler 扩展运行四个场景，各重复 10 次，保存函数耗时表、真实 IDE 截图与原始 .prof 文件。
图中 Calls 为调用次数，Own time 为函数自身时间，Total time 包含被调函数的时间。分析器有额外开销，所以图中时间不能直接代替上表的正常运行计时。
观察到的热点包括单词统计中的正则匹配、句子统计中的片段遍历，以及源码分类中的词法分析。当前没有宣称已做性能优化，也没有制作未经测量的“优化后快十倍”。 该工具属于 VS Code 扩展；老师若将“IDE 附带工具”严格限定为默认内置功能，需要以教师口径为准。
这些数据针对读取文件和统计函数，不包含 v0.4 浏览器页面渲染、上传传输和报告下载耗时。新增界面复用原有算法，没有把旧性能数据说成界面的端到端测量。
08｜版本履历：从“有个文件夹”到“能交差的工具”
| 阶段 | 本阶段做了什么 | 关键提交 |
|---|---|---|
| v0.1 | 初始化空项目和 README | d561380 |
| v0.2 | 完成字符、单词、句子统计及基础测试 | b4e28df |
| v0.3 | 增加 Python 源码行分类和扩展测试 | c820437 |
| v0.4 | 增加本地可视化界面、文件自动解析、源码占比图、预览与报告导出；测试扩充到 38 项 | bab828a |
| 强化验证 | 增加文章、大文本、万行源码与组合测试 | 1fc996c |
| 性能材料 | 保存后台测量、IDE 分析证据和操作说明 | d24f1d9、c3c432a |
完整修改过程可以查看 Gitee 提交历史。版本迭代靠真实 commit 留痕，不是把文件夹依次命名为“最终版”“最终版2”“这回真的最终版”。
历史版本当时没有完整保留截图，因此后来从对应提交导出代码、实际复跑，再保存日志和报告截图。这些材料已明确标注为后补复跑证据，不把它们说成开发当时的终端原图。详情见 运行证据说明。
09｜AI 协作说明：提示词已放仓库，本文不再连载
本项目使用 AI 协助生成和修改代码、测试、文档及性能分析材料，也通过多轮追问核对规则、补足案例和纠正说明。AI 给出的内容仍需结合代码、实际输出和测试核查，不能把“它说完成了”直接当作验收结论。
提示词与完整问答集中放在仓库，本文不重复粘贴：
完整归档的具体截止时间和范围以归档说明为准，不包含导出后继续发生的所有新消息。完整问答、全部用户提示词与原始图片按目录保存在仓库，阅读时请保留它们的链接关系。
10｜售后小抄：程序不背所有锅
| 现象 | 先检查什么 |
|---|---|
| 界面打不开或无法继续分析 | 是否完整解压项目、安装 Python，并保持启动服务的终端运行 |
找不到 wc.py |
是否进入了包含程序的项目目录 |
Error: cannot read file |
路径、文件是否存在、是否为 UTF-8 文本 |
| 修改文字后数字不变 | 是否先保存文件，再重新运行命令 |
| 字符比肉眼看到的多 | 空格、Tab、CRLF 和末尾换行是否也被计入 |
双击 wc.exe 后窗口闪退 |
请在终端带参数运行，不要靠双击传达文件名 |
-l 不能按预期识别其他语言 |
当前只支持 Python 源码的分类规则 |
最后的使用建议很简单：先拿样本跑通，再换自己的输入；数字不对，先看规则，再看代码。
仓库入口再放一次，省得大家翻回去：word-counter-app。工具负责数数，读懂代码和说明书这件事，还得由使用者亲自上场。
浙公网安备 33010602011771号