第二次作业

项目	内容
这个作业属于哪个课程	26软件技术基础
这个作业要求在哪里	WordCount 命令行文本计数统计程序
这个作业的目标	完成英文字符、单词、句子计数与源码行统计，运用模块化设计、单元测试和性能分析，把命令行程序完善为易用、可维护的工具。
姓名-学号	潘镜天-2024329301005
码云仓库地址	TextScope 源码仓库
程序下载	TextScope-1.1.1-candidate-win-x64-Setup.exe；便携版：TextScope-1.1.1-candidate-win-x64-portable.zip（需整包解压）

TextScope：一个能计数、识字、保存和分析的文本工具

一、我完成了什么

我把程序命名为 TextScope。它首先提供题目要求的 wc.exe [参数] [文件名]，完成基础计数；在此基础上，我增加了可以点击的中文工作台。用户可以选择命令操作，也可以用鼠标完成分析、查历史和导出。

本次展示版本为 v1.1.1 候选版。下表区分已经实现的功能和本次实际验证的范围，避免把一个成功样例当成全部场景都没有问题。

功能	程序提供的能力	实际验证情况
基础文本计数	字符、英文词、句子；单项或组合输出	命令、自动测试和固定样例通过
中文与混排	离线分词，分别显示中英文词数、合计和词频	英文、中文、混排均有运行图
源码行统计	10 类语言，四类物理行与派生计数	Python、C++ 等固定样例和边界测试通过
中文工作台	鼠标点击、命令栏、滚动结果、帮助与首次向导	真实 Textual 运行采证
历史与收藏	保存结果、来源信息和配置，检索、收藏、重新查看	已有自动测试与历史页面采证
图片识字	本机 OCR，准备区编辑后再统计	本轮中英文图片实际识别并校正
可选 AI 报告	本机统计先完成，确认后生成结构化报告	本轮一个小英文文件真实请求成功
报告导出	Markdown、HTML、JSON、CSV、TXT、ZIP	4 份报告 × 6 格式，共 24 个文件核对通过
桌面浮窗	常用功能快捷入口，独立进程	本轮确认能够打开并显示；未补测全部快捷动作
外观与配置	深色、浅色、高对比主题，图标与偏好保存	已有界面、配置和主题相关验证
Windows 分发	安装器与便携包，无需另装 Python	冻结程序 10 项检查通过；本轮未重复安装卸载

二、版本是怎样改进的

版本	当时解决的问题	主要结果
v0.1	先把开发环境和目录组织好	隔离环境、依赖检查、空项目骨架
v0.2	先完成题目基础功能	英文计数、命令入口、文件错误反馈
v0.3	文本和源码不能混用规则	独立源码统计与行分类
v0.4、v0.5	统计后还要查找和继续使用	中文混排、历史、收藏等逐步加入
v1.0	将分散能力连接为完整操作流程	工作台、导出、本机 OCR、浮窗、可选 AI
v1.1	基础命令和界面要更贴近实际使用	中文界面、wc.exe 与字符边界补测
v1.1.1	修正真实 AI 协议和源码导出问题	Responses/Chat Completions 兼容，真实报告与导出复测

表中的版本表示开发阶段。Git 中保留了实际提交记录；这不表示每个表中版本都建立了同名标签。当前候选版仍需要在更多电脑上验证安装兼容性。

三、我为什么采用现在的架构

Python 适合文本处理、OCR 和自动测试，也便于在 VS Code 中调试。但如果把按钮、数据库、统计公式和网络请求写在一起，后续修改会牵动很多地方。因此，我把程序拆成四层。

层次及目录	主要职责	刻意保持的边界
统计规则 src/textscope/domain	字符、词、句子、源码行分类和结果结构	不依赖窗口、数据库和真实网络
操作流程 src/textscope/application	分析、保存、检索、导出、任务与命令路由	组合能力，不把算法写进按钮事件
外部能力 src/textscope/infrastructure	文件、SQLite、OCR、AI、凭据和主题读取	将外部失败转成明确状态
用户界面 src/textscope/interfaces	Typer CLI、Textual 工作台、PySide6 浮窗	接收输入、展示结果，尽量保持轻薄
测试 tests	单元、集成、界面和手工采证脚本	与正式源码分开
文档与证据 docs、artifacts	使用说明、测试记录、图片、性能和发行包	记录真实结果，不当作产品源码

主要调用流程如下：

终端命令 / 工作台按钮 / 内置命令栏
                ↓
         同一套应用动作与输入校验
                ↓
       文本规则 或 源码规则 → 统一结果
                ↓
       历史保存 → 页面显示 / 报告导出
                └→ 用户确认 → 可选 AI 报告

这个结构让按钮与命令共用统计规则，避免两条入口算出不同数字。历史、导出和 AI 使用稳定的记录 ID 相互关联。OCR、AI 与报告渲染分别通过内部接口接入，便于替换实现。首版只注册程序自带模块，不扫描并加载第三方插件代码。

耗时工作放在后台任务中执行，界面展示状态和进度，基础统计不会等待 AI 返回。取消会停止后续工作并反馈状态；已经发到远端的请求不能保证被服务端撤回。

我采用 Textual TUI 的一个重要原因，是图形化操作方便初学者使用。 用户可以点击模式、按钮和历史项目，也能用滚轮阅读结果，不必先记住命令。熟悉之后，用户仍能在同一工作台使用内置命令。它还保留终端部署方便、与 CLI 共用业务逻辑的优点。

工作台用边框、彩色表格和文字状态区分功能，标题采用字符艺术。程序提供三套内置 YAML 主题，默认 Nerd Fonts 图标，也能切回普通图标；图标始终配文字。终端的字体和字号仍由终端设置决定，缺字时应切换图标方案。

四、怎样安装和使用

1. 安装与打开

程序首发面向 Windows 10/11 x64。Windows 离线安装器与便携包已发布在 Gitee v1.1.1 候选版发行页。发行页按大小限制提供分卷：安装版为 TextScope-1.1.1-candidate-win-x64-Setup.exe.001/.002；便携版为 TextScope-1.1.1-candidate-win-x64-portable.zip.001/.002/.003。任选一种并下载该组全部分卷，再按分卷合并与安装说明核对 SHA-256 并还原完整文件。最终文件名分别为 TextScope-1.1.1-candidate-win-x64-Setup.exe 和 TextScope-1.1.1-candidate-win-x64-portable.zip。安装版按提示安装，再从开始菜单或桌面快捷方式打开；便携版要完整解压后运行其中的 textscope.exe，不要只复制 exe，它需要同目录资源。

命令行示例以下都假设已进入程序目录。PowerShell 对当前目录程序使用 ./ 或 .\ 前缀；CMD 可直接输入程序名。若未加入 PATH，可填写 exe 的完整路径。第一次启动会出现配置向导；之后不重复弹出，需要时可在工作台手动打开。

.\textscope.exe ui
.\wc.exe --help

2. 题目要求的 wc 命令

命令	作用
wc.exe -c file.txt	只统计字符数
wc.exe -w file.txt	只统计单词数
wc.exe -s file.txt	只统计句子数
wc.exe -cws file.txt	同时输出三项
wc.exe file.txt	默认输出字符、词、句子三项
wc.exe --language chinese 文件.txt	中文模式
wc.exe --language mixed 文件.txt	中英混排模式
wc.exe --code main.py	独立源码行统计
wc.exe --code --language cpp main.cpp	显式指定源码语言
wc.exe --format json file.txt	输出结构化结果

例如，把以下内容保存为 UTF-8 demo.txt。两行之间使用 CRLF，文件末尾不再换行：

Hello, world!
Python is useful.

.\wc.exe -c demo.txt      # 32 个字符
.\wc.exe -w demo.txt      # 5 个英文词
.\wc.exe -s demo.txt      # 2 个句子
.\wc.exe -cws demo.txt
.\wc.exe -cws "带空格的目录\demo.txt"

wc.exe 每次接收一个文件；批量分析使用下面的主命令或工作台。--code 不能与 -c/-w/-s 混用，语言参数是 --language。文件不存在、编码错误或参数错误时，程序明确说明原因。

3. 进阶命令与帮助

.\textscope.exe text stats a.txt b.txt --language english
.\textscope.exe text stats "混排文本.txt" --language mixed --format json
.\textscope.exe text stats a.txt --format md
.\textscope.exe code stats src/main.py
.\textscope.exe code stats src --recursive
.\textscope.exe code languages
.\textscope.exe code explain
.\textscope.exe --help

主统计命令支持表格、JSON 和 Markdown 等输出。需要管道时可将 UTF-8 文本交给 text stats -；Windows 管道编码由外层终端决定，不应把编码已损坏的输入当成原文统计。

分析结果保存后，可以用结果中的运行 ID 查看或导出：

.\textscope.exe report show --run-id RUN_ID --format txt
.\textscope.exe report export --run-id RUN_ID --format html --output report.html
.\textscope.exe report export --run-id RUN_ID --format html --output report.html --confirm

第一条导出命令预览，第二条确认写入；覆盖已有文件还需明确指定 --overwrite。请把 RUN_ID 替换成实际记录 ID。工作台命令栏省略 textscope.exe 前缀，例如 text stats demo.txt、code stats main.py、history、favorites、help。工作台不运行系统 Shell，也不会在命令栏启动 wc.exe。

4. 鼠标操作工作台

我想做什么	操作步骤	可以看到什么
第一次配置	选择默认语言、主题和图标，保存向导	后续启动恢复已保存偏好
分析文本	选择文本模式，填写文件路径或粘贴文字，选择语言并开始	基础数字、词频和文本体检结果
批量分析	在文件输入区提交多个文件	逐文件状态；成功结果保留，失败项单列
分析代码	切换代码模式，选文件，必要时指定语言	四种行分类、含代码行与含注释行
查找旧结果	打开历史，检索并点选记录	结果、来源和当时配置
收藏常用内容	在记录中收藏，再打开收藏页	集中查找已收藏项目
导出	在报告页选择格式和目标路径，核对预览后确认	真实写入文件与导出反馈
识别图片	打开 OCR，导入图片，运行本机识别	准备区可编辑文字，修改后再统计
配置 AI	填服务地址、协议和模型，安全保存密钥，先测试连接	连接状态；不会把用户文档当连接测试材料
生成 AI 报告	本机分析后准备请求，完整预览并确认发送	后台报告状态和保存后的结果
查命令用法	点击帮助，或输入 help	命令介绍、参数和示例

五、统计口径与边界

同一个“字数”可能有不同含义。我把规则写清楚，并随结果保存规则和配置，便于复查。

项目	本程序的处理方式
字符	UTF-8 解码后的 Unicode 码点数，不是文件字节数，也不是屏幕字形数
空格、Tab、换行	都计入字符；CRLF 是两个码点；BOM 若存在也计入
emoji、组合字符	按实际码点计数，一个显示图形可能算多个字符
英文词	ASCII 字母词，可带一个内部撇号或连字符，如 don't、well-known；不把任意连续连接符当一个词
英文句子	[.!?]+ 后接空白或文本结束时计一个句末簇；没有句末标点的尾段不额外算一句
中文模式	固定离线 jieba 统计中文词；夹杂英文只进入字符数，不进中文词数
混排模式	中文词、英文词分别统计，再显示合计
中文/混排句子	连续 。！？.!?… 合并为句末簇，屏蔽 URL 和小数中的点；无结束标记的尾段不另计
公式与特殊符号	参与字符计数；本程序不声称理解公式结构
长短句建议	少于 8 个当前模式的词为短句，30 个及以上为长句；这是明确阈值的启发式
可读性	本机词典与透明公式估算，不能当作客观写作评分
末尾换行与源码行	LF、CRLF、单独 CR 分隔物理行；最后一个换行只结束当前行，不额外产生空白行

源码统计支持 Python、C、C++、Java、JavaScript、TypeScript、Shell、HTML、CSS、SQL。Python 使用 AST 与 tokenize 严格检查；语法或 token 错误时整文件不提供完整分类。其他语言使用 Pygments 作词法估计，不能代替编译器；遇到未识别片段会保留结果并警告。

行分类	判断与示例
空白行	只有空格或 Tab；不把任意不可见 Unicode 都当空白
纯代码行	有代码 token，没有注释 token
纯注释行	只有注释内容，没有代码
混合行	同一物理行同时有代码和注释，如 x = 1 # 注释
含代码行	纯代码行＋混合行
含注释行	纯注释行＋混合行

前四类互斥，相加等于总行数；后两项允许重叠，不能再加到总数里。字符串中的 #、// 不因外观就算注释，Python docstring 和多行字符串算代码。

六、实际运行结果

以下材料均为自己生成的小样本。英文、中文固定样本来自 v1.1.0；本轮混排、Python、C++、OCR 和真实 AI 来自 v1.1.1，未混成同一轮测试。

材料	字符	英文词	中文词	总词	句子
英文固定样本	117	17	0	17	3
中文固定样本	39	0	12	12	3
混排固定样本	66	7	7	14	3
本轮混排文件	101	10	16	26	4
本轮校正后图片文字	48	5	7	12	3
本轮 AI 输入英文	219	33	0	33	4

源码样本	总行	空白	纯代码	纯注释	混合	含代码	含注释
Python	5	1	2	1	1	3	2
C++	9	1	5	2	1	6	3

OCR 和 AI 怎样配合基础统计

我用本机 OCR 识别中英文图片。原始结果把 OCR 识别为 OcR，中文还出现拆行。即使置信度约为 0.994，结果仍需要核对。因此程序先把文字放进可修改的准备区，用户修正后再正式统计。

AI 首次默认关闭。开启后，本机先完成统计，再准备外发内容。发送前展示完整内容、地址、模型和请求范围，用户确认后才调用。连接测试与报告生成是两个操作：连接成功不能证明报告一定成功，报告还要处理超时、响应格式和引用校验。

本轮用 219 字符的合成英文文件发出一次真实 Responses 请求，没有重试。程序生成中文结构化报告，通过原文引用检查，保存后重新读回成功。易读页展示摘要，逐文件详细发现保存在完整 JSON 中。这个结果只证明本样本和当前服务可用，不代表全部模型、批量和图片输入均已验证。

桌面浮窗由独立进程提供，不会把 Qt 事件循环塞进终端界面。本轮拍到了实际打开的浮窗，未把拖动、多屏和所有快捷按钮都列为本轮通过项。

七、导出后的文件确实可以使用

本轮把混排文本、Python、C++ 和图片文字的四份报告分别导出为六种格式，共 24 个真实文件。我核对了统计值、哈希及 ZIP 内容，各格式关键数字一致。导出前会预览，覆盖同名文件需要确认。

格式	适合用途	本轮例子
HTML	保留表格和图表，浏览器阅读、打印	混排文本报告
Markdown	写博客、笔记或作业文档	C++ 9 行分类报告
JSON	程序继续读取，保留字段结构	Python 5 行分类报告
CSV	表格软件整理和比较数据	Python 各类行数
TXT	普通编辑器快速查看	OCR 修正后统计
ZIP	汇总保存相关报告文件	混排文本报告包

这些是分析结果导出，不应理解为自动附带全部原始文件或独立 AI 正文。AI 的完整结果保存在历史中；本次另附的 AI 阅读材料属于展示附件，不是新增导出格式。

CSV 图是编辑器中的文件文本，不是 Excel 展示。分析页面图来自真实程序的 Textual 离屏渲染；浮窗及四份导出文档图来自实际 Windows 窗口。HTML 已导出核对，本轮未补拍浏览器页面。运行截图与导出说明保留了附件入口。

八、失败时程序怎样反馈

情况	处理方式
文件不存在、读不了或不是合法 UTF-8	返回具体失败项，不伪造零结果
批量中部分失败	保留成功结果，说明失败文件及覆盖范围
Python 语法错误	停止该文件完整分类，避免输出看似准确的数字
OCR 失败、低置信度或取消	显示原因，允许校正或重试，不自动换成云端
AI 超时、鉴权失败、限流或格式不符	保留本机统计，记录失败状态，不展示伪造报告
AI 上下文预检超限	暂停，缩小范围后重新预览确认，不静默截断
原文件被移动或修改	保存时有哈希与结果快照，打开时提示变化，不覆盖旧结果
历史库接近或达到容量	默认 5 GB，80% 提醒；满后拒绝新增，不自动删资料
导出覆盖已有文件	预览并再次确认，不静默覆盖

API 密钥只交给配置的服务，通过 Windows 凭据管理器保存，不写入提示词、配置、历史或日志。开发自动测试采用合成材料与模拟接口。真实 AI 本轮也只发送上述选定小样本。程序不复用 Codex 登录凭据，不提供手机上传和入站局域网服务。

九、测试做了哪些工作

测试类别	代表检查	真实结果与范围
完整自动化回归	统计、文件、历史、导出、界面及 AI 协议等	最近一次完整运行 546 项通过，52.26 秒
基础边界	空文件、换行、CRLF、BOM、emoji、连接词、句末簇	纳入现有自动测试；以固定规则判断
源码边界	混合行、字符串注释符、docstring、末尾换行、语法错	代表样本与回归测试
本轮导出修复	自动识别源码语言后保存与导出	21 项聚焦测试通过，1.62 秒
命令实际执行	wc.exe 单项、组合、中文、混排及源码	已保存真实输出图；小样本 32/5/2 核对
本轮本机 OCR	识别、人工修改、保存、再统计	实际完成，识别错误如实保留说明
本轮真实 AI	预览确认、请求、引用校验、保存、读回	一个小英文文件，一次请求成功
本轮导出采证	4 份报告 × 6 格式	24 文件关键值与 ZIP 内容核对
冻结程序自检	发行运行目录的关键能力	10 项通过，另检查 Python/C++ 保存导出
图片与报告	文件存在、关键说明与附件一致	文档组装时检查，不代替功能测试

这些结果属于不同轮次，不能相加说成一次完整测试。本轮修改集中在源码语言标记与导出，因此只重跑相关测试，没有重复运行完整 546 项；也没有再次进行安装和卸载验收。发现问题时，我先重现，再修复，再复测，保留失败与修复关联记录。

十、性能测试与分析

以下是 v1.1.0 已记录的测量，本轮未重测。环境为 Windows 11 x64、i5-1340P、Python 3.12.10。测试从 VS Code 启动，使用 cProfile 与 tracemalloc；每项预热一次，正式测三次，波动明显时再补两次。表中取中位数，同时给出范围。

项目与固定规模	中位 ms	最小—最大 ms	Python 峰值 MiB
英文统计，22,800 字符	11.94	11.35—13.44	0.44
混排统计，6,200 字符	138.92	138.27—141.02	0.32
Python 源码，399 行	14.41	13.57—15.38	0.73
C++ 源码，480 行	257.44	253.27—262.43	0.15
历史导入，固定样本	26.58	26.54—27.12	0.06
Markdown 导出	65.82	65.34—67.43	0.23
HTML 导出	57.57	54.92—74.38	0.31
JSON 导出	18.93	18.47—20.18	0.09
ZIP 导出	161.26	158.80—161.97	0.53
本机 OCR，760×155 图片	842.66	838.04—855.52	130.19

测量包含调试器和内存跟踪开销，不是 IDE 原生 profiler 的结果；PyCharm 未完成真实启动验证。OCR 的底层模型内存不能由 Python 峰值完整代表。数据只说明这台电脑、这些固定输入的表现，不应推广为所有机器的保证。

大规模矩阵里，中文约 3.31 秒、混排约 4.44 秒，离线分词仍是明显耗时点。因此，我把耗时任务与界面分开，先给本机结果，再让 OCR、AI 等继续处理。后续优化应继续用相同输入比较，不能为了更快而悄悄改变统计口径。性能原始记录可以复查。

十一、收获与仍需改进的地方

这次实现让我认识到，一个可靠工具除了“算对”，还要解释数字、处理失败，并让用户找到和带走结果。Textual 的点击操作降低了命令学习门槛；分层架构则让新增 OCR 和 AI 时不必改动基础计数。

当前程序只面向 Windows。其他电脑的安装、所有模型、复杂图片和大批量 AI 仍需继续验证；非 Python 的源码统计是词法估计，OCR 也不能代替人工校对。我的下一步应先改进大文件分词和 AI 详细结果阅读，再补兼容性测试，而不是继续堆积功能。

我用 AI 协助拆分需求、设计模块和检查测试，但以实际运行、测试日志和截图判断是否完成。AI 协作提示词整理按阶段保留了代表性提示词，经过删减润色，不是逐字完整对话记录。

十二、AI 协作提示词

本文按开发阶段整理代表性提示词，经过删减和润色，不是逐字完整聊天记录。这些提示词用于说明我怎样提出任务、限制范围和核对结果。实际测试结果以项目日志为准。

1. 明确需求

请帮我规划一个 Python 文本统计工具，先完成英文字符、单词和句子计数，并支持题目要求的 wc.exe [参数] [文件名]。文本统计与源码行统计要分开。扩展功能可以包括历史、收藏、本机 OCR、可选 AI 报告和多格式导出。请先列清楚功能、边界和阶段，不要立即生成产品代码。

2. 确定结构

请将项目分成统计规则、操作流程、外部能力和用户界面四层。命令行、鼠标按钮和工作台命令要调用同一套分析流程。请用小而稳定的接口隔开 OCR、AI、数据库和导出格式，避免界面直接处理全部业务。先检查已有入口和相关函数，再读取必要片段，不要反复扫描依赖目录。

3. 分阶段实现

请从 v0.1 的最小工程开始，先实现 v0.2 英文基础计数，再实现 v0.3 源码统计。后续逐步加入中文与混排、历史、界面、OCR、AI 和导出。每阶段说明修改范围和验收条件，保留真实提交、测试命令、失败与修正记录；不要把规划或下载的样例称为已实现功能。

4. 固定计数规则

请明确并测试字符、词、句子和物理行的计数口径。字符按 Unicode 码点计数，保留原始换行；英文词允许规定的词内撇号和连字符。中文使用离线 jieba，混排分别列出英文、中文及合计。源码行分为空白、纯代码、纯注释和混合四类，末尾换行不增加空白行。请重点检查空文件、CRLF、特殊符号、字符串中的注释符号和语法错误。

5. 设计交互界面

请用 Textual 提供中文工作台，让初学者能够点击按钮、选择模式、滚动历史和查看帮助，同时保留内置命令栏。标题要醒目，功能区用边框、留白和颜色区分，状态同时显示文字。请提供深色、浅色和高对比主题，默认 Nerd 图标并保留普通图标选项。每个页面都要有清楚的返回、取消和错误反馈。

6. 完成 OCR 和历史

请优先使用本机 OCR。图片识别后先进入可编辑准备区，用户修正后再统计，不要自动上传到云端。请处理空图、损坏、低置信度、超限和取消。历史要关联原文件、分析结果和生效设置，支持检索和收藏；文件变化时提醒，不覆盖旧结果。

7. 接入 AI 报告

请让基础统计先完成，AI 报告默认关闭。用户开启后，每批发送前必须看到实际文本或图片、服务地址、模型和请求范围，并明确确认。报告用中文说明摘要、主题、原文证据、建议和限制，多文件再补共性与差异。请同时考虑 Chat Completions 和 Responses，分别验证连接与实际生成；连接成功不能替代报告成功。

8. 保护密钥和文件

请把 API 密钥保存在 Windows 凭据管理器，不写入配置、提示词、历史、截图或日志。测试优先使用合成材料与模拟接口。文件读取、网络请求和批量操作要有上限、超时和取消；失败要说清原因，并保留已经完成的本机结果。工作台命令栏只允许应用内命令，不执行任意系统 Shell。

9. 验证正确性和性能

请针对一个代表性成功场景和一个有价值的失败场景先写测试，确认测试能够发现问题后再实现。小改动只跑相关测试和必要检查，最终再跑完整套件。性能测量使用固定样本，先预热一次，再测三次，记录中位数、范围和峰值内存。请分清纯统计、文件导出和程序启动，不能把它们直接比较，也不能把普通脚本结果写成 IDE 测量。

10. 导出、截图与交付

请用同一份结果导出 Markdown、HTML、JSON、CSV、TXT 和 ZIP，并实际打开导出文件检查内容。请对已经运行成功的工作台、源码结果、OCR、AI、浮窗和导出文档截图，使用小型合成样本，注明截图方式和对应场景。功能尚不成熟时先修正或记录限制，不用静态稿冒充运行结果。最后提供离线安装器，明确测试过的环境与尚未验证的范围。

11. 整理报告

请把报告写得简洁通俗，主语明确。报告开头列课程、作业要求、目标、姓名学号、仓库和下载入口；正文说明版本演进、为什么采用四层架构和 Textual、基本功能、特色功能、真实测试和性能。请让图片与说明对应，不堆砌内部记录和无关版本串，不把参考资料、未实现项或模拟测试写成真实功能成果。

12. 补充实际运行证据

AI 接口配置完成后，请用小型合成文件补拍本地代码统计、真实 AI 报告和本机 OCR 结果，再拍桌面浮窗。请将不同报告导出为多种格式，实际打开文档并截图，核对界面、历史和导出数字一致。OCR 错误要如实保留并展示校正流程；AI 请求必须确认预览，不拍密钥和私人内容。只展示已经运行成功的功能，将简短说明同步到报告，提示词按阶段删减润色，不冒称逐字记录。

使用方式与技能

每次只使用当前阶段的提示词，并补充输入文件、允许修改的目录和验收标准。遇到缺陷先复现，再修复；需要并行工作时，给不同子任务明确互不重叠的文件范围。AI 完成任务后，我检查实际运行和原始记录。

整理提示词时使用 prompt-engineering-patterns，把目标、边界、输出和验收写清楚。项目协作提示中还约定按任务选择 codebase-design、superpowers:test-driven-development、superpowers:systematic-debugging 和 superpowers:verification-before-completion 等技能；仅在环境中实际可用并确实执行时记录为已使用，截图工具同样如此。