ChoiceDownloader 使用说明

English Guide

ChoiceDownloader 是一个用于在 Windows 桌面环境中批量下载 Choice 公司公告和年报文件的小工具。它会读取 Excel 中的公司名称，连接或启动本机 Choice 金融终端，自动搜索公司、进入公司公告页、筛选“全部公告 / 财务报告”，执行批量下载，并按文件名关键词筛选目标文件。

本工具主要面向已经拥有 Choice 金融终端账号、终端安装环境和相应数据下载权限的用户。它不会绕过登录、授权或平台限制，也不内置 Choice 客户端。所有公告文件都来自用户本机已经登录并可正常操作的 Choice 终端。

主要功能

• 提供 Windows 图形界面，日常使用无需手动输入命令。
• 支持 Excel 批量导入公司名单，按 公司名称 列逐家公司处理。
• 支持连接已打开的 Choice 窗口；如未打开，可通过配置的 exe 或桌面快捷方式启动 Choice。
• 自动完成公司搜索、页面跳转、F9 切换、公告页定位、公告筛选和批量下载。
• 支持坐标校准：可测试关键定位点、读取鼠标位置并覆盖默认坐标，适配港股公告入口或不同屏幕布局。
• 支持设置 Excel 行范围，例如只运行第 3 到第 20 家公司。
• 支持设置每家公司下载篇数，并在界面调整本次运行的最大下载上限。
• 支持设置启动等待、Enter 后等待和 F9 后等待时间，适配不同电脑和网络速度。
• 支持文件名关键词筛选，例如 10-K,20-F,40-F。
• 支持“满足任一关键词”和“满足全部关键词”两种匹配方式。
• 可选择只生成 最新 文件夹：勾选后才会把日期最新的匹配文件复制到 最新。
• 支持单家公司调试模式，例如只导航到公告页、不执行下载。
• 支持失败后继续下一家公司，并输出批量结果汇总。
• 发布版界面不预填用户路径、公司名单、下载目录、日志目录或筛选关键词，所有运行信息均由用户自行填写。
• 支持本机设置记忆：用户修改后的路径、数字、选项和坐标会保存到系统用户配置目录，下一次打开自动恢复；配置不会写到 exe 所在目录。

适用环境

项目	要求
操作系统	Windows 10 / Windows 11 桌面环境
数据终端	已安装并可正常登录 Choice 金融终端
输入文件	.xlsx 或 .xlsm
推荐屏幕环境	稳定分辨率、稳定缩放比例、Choice 窗口最大化
使用权限	用户应自行确认拥有对应公告数据访问和下载权限

本工具使用桌面自动化方式操作 Choice，因此对界面布局较敏感。建议在批量运行时不要手动点击 Choice 窗口，不要频繁改变分辨率、缩放比例或窗口位置。

快速使用 exe

如果你只想直接使用软件，可以从 GitHub Releases 下载：

ChoiceDownloader-v0.3.2-hk-windows-x64.exe

使用步骤：

1. 双击运行 exe。
2. 选择 Excel 公司名单文件。
3. 选择本机 Choice 程序或快捷方式。
4. 选择下载目录和日志目录。
5. 手动填写每家公司下载篇数、下载上限、提取范围和等待上限。
6. 如需筛选年报文件，再填写文件名筛选关键词，例如 10-K,20-F,40-F；留空表示不过滤。
7. 首次使用建议只运行 1 家公司。
8. 确认 Choice 已登录并处于可操作状态。
9. 点击“开始批量运行”。
10. 运行完成后，到下载目录查看下载文件和 choice_batch_summary.xlsx；如勾选“只生成最新文件夹”，再查看 最新 文件夹。

Excel 公司名单模板

项目提供模板：

templates\company_list_template.xlsx

模板包含两个工作表：

工作表	说明
Companies	公司名单填写区，程序读取这里的 公司名称 列。
说明	模板填写说明和注意事项。

Companies 工作表至少需要保留这一列：

公司名称
Microsoft Corp
Apple Inc

填写注意：

• 第一行必须保留列名 公司名称，不要添加空格或改名。
• 公司名称从第二行开始填写。
• 示例行可以删除。
• 代码或简称（可选）、备注（可选） 只供人工记录，程序不会读取。
• 程序读取当前活动工作表中的 公司名称 列，建议保留模板默认结构。

图形界面字段说明

字段	说明
Excel 文件	包含 公司名称 列的 Excel 文件。
Choice 程序/快捷方式	本机 Choice 入口，可以选择 .exe，也可以选择 .lnk 快捷方式。
下载目录	Choice 下载结果保存目录。
日志目录	运行日志保存目录。
每家公司下载篇数	每家公司批量下载的最近公告数量。
本次上限	本次运行允许的最大下载篇数，超过上限会在开始前阻止运行。
提取范围	只处理 Excel 中指定序号范围内的公司。选择 Excel 后程序会自动填入完整范围，用户可自行修改。
启动等待	点击开始后先等待的秒数，便于让系统和终端窗口稳定。
Enter 等待	输入公司名并回车后的最长等待秒数。页面稳定后会提前继续。
F9 等待	发送 F9 后的最长等待秒数。页面稳定后会提前继续。
文件名筛选	可选。逗号分隔关键词，留空表示不过滤。
匹配方式	命中任一关键词，或必须命中全部关键词。
只生成最新文件夹	开启后按文件名筛选结果，只复制日期最新的一份到 最新 文件夹；未开启时不生成 最新 文件夹。
只导航到公告页，不执行下载	调试定位时使用，只进入公告页。
跳过导航，假设当前已经在公告页	仅适合单家公司调试，不建议批量运行。
跳过下载弹窗里的目录选择步骤	当 Choice 批量下载弹窗已经保留正确目录时可使用。
最后一家公司完成后返回首页	批量运行结束后回到 Choice 首页。

坐标校准

Choice 的公告入口、筛选按钮和下载弹窗位置可能因市场、终端版本、分辨率或缩放比例不同而变化。新版界面提供“坐标校准”区域，默认坐标仍为原始美股流程使用的点位；如果港股公告入口位置不同，可以只修改对应点位。

可校准的定位点包括：

定位点	用途
左侧导航滚动点	F9 后左侧导航区域的滚动位置。
公司公告入口	左侧导航中的公司公告入口。港股入口不同时，优先调整这一项。
全部公告筛选	公告页中的“全部公告”筛选位置。
财务报告筛选	公告类型中的“财务报告”位置。
批量下载按钮	公告列表页右上或工具栏中的批量下载按钮。
弹窗浏览按钮	批量下载弹窗中的目录浏览按钮。
弹窗范围勾选	批量下载弹窗中的范围勾选项。
弹窗篇数输入	批量下载弹窗中的下载篇数输入框。
弹窗下载按钮	批量下载弹窗中的确认下载按钮。
返回首页按钮	Choice 首页或返回入口位置。

推荐校准方法：

1. 先填写 Excel、Choice 程序路径、日志目录和等待上限。
2. 在“测试定位点”中选择需要检查的点，例如 公司公告入口。
3. 点击“流程测试到此处”。程序会使用当前范围第一家公司执行到该步骤，只移动鼠标，不继续下载。
4. 如果鼠标位置不准确，可以手动修改 X/Y；也可以把鼠标移动到正确位置后点击该行的“取鼠标”。
5. 点击该行“确认”，后续运行会使用当前界面中的坐标，并在下次打开软件时自动恢复。
6. 如需撤回某个定位点，点击该行“恢复默认”。
7. 港股流程通常优先测试并调整 公司公告入口，如果后续筛选或下载弹窗位置不同，再逐项校准。

坐标为相对 Choice 窗口左上角的坐标。批量运行时建议保持 Choice 窗口最大化，并避免中途改变屏幕缩放、分辨率或窗口位置。

文件名筛选规则

文件名筛选用于保留目标公告类型。发布版不会预填关键词，用户可按需要填写。美股年报常用配置示例：

10-K,20-F,40-F

当匹配方式为“满足任一关键词”时，只要文件名包含任意一个关键词就会保留。程序会兼容常见写法差异：

输入关键词	可兼容示例
10-K	10K、10 K、10－K
20-F	20F、20 F、20－F
40-F	40F、40 F、40－F

只有开启“只生成最新文件夹”时，程序才会从匹配文件中选择日期最新的一份复制到 最新 文件夹。未开启时，程序只保留 Choice 原始下载结果，不额外创建 最新 文件夹。若开启后没有匹配到目标文件，汇总表会记录 没筛选成功。

运行流程

1. 读取 Excel 中的公司名单。
2. 根据界面设置校验提取范围、下载篇数和安全上限。
3. 连接已打开的 Choice 窗口；如果没有找到窗口，则尝试启动 Choice。
4. 在 Choice 底部搜索框输入公司名称。
5. 回车进入公司页面。
6. 发送 F9 并等待页面响应。
7. 滚动左侧导航，进入公司公告页面。
8. 点击“全部公告”。
9. 点击“财务报告”。
10. 打开批量下载弹窗。
11. 设置下载目录和下载篇数。
12. 等待文件下载完成并稳定。
13. 按文件名关键词筛选下载结果。
14. 如果勾选“只生成最新文件夹”，将最新匹配结果复制到 最新 文件夹；否则跳过这一步。
15. 返回首页并继续处理下一家公司。
16. 输出批量汇总表和运行日志。

输出文件

下载结果保存在界面选择的下载目录中。Choice 终端可能会按自身规则创建文件或子文件夹。

常见输出：

输出	说明
原始公告文件	Choice 批量下载得到的网页或文档文件。
最新\	仅在勾选“只生成最新文件夹”时创建，用于保存筛选后的最新匹配文件。
choice_batch_summary.xlsx	批量运行汇总，记录每家公司成功或失败状态。
运行日志	保存在界面选择的日志目录中，用于排查失败步骤。

失败状态说明

批量运行不会因为单家公司失败而整体停止。程序会尽量返回首页并继续下一家公司。

失败说明	含义	建议处理
没有找到公司	点击批量下载后没有找到“浏览文件夹”弹窗，通常表示没有进入正确的公司公告下载页面。	检查公司名称是否能在 Choice 中搜索到；必要时换成更准确的名称或 CUSIP。
没筛选成功	已有下载文件，但按文件名关键词没有找到目标年报。	检查该公司下载目录，确认文件名是否包含 10-K、20-F、40-F，必要时调整关键词。
Run stopped by user	用户点击了停止运行。	属于正常中断，可查看已完成企业的结果。
Choice executable not found	Choice 程序或快捷方式路径不存在。	重新选择本机正确的 Choice 入口。

从源码运行

安装依赖：

python -m pip install -r requirements.txt

启动图形界面：

python scripts\choice_automation_gui.py

核心命令行脚本位于：

scripts\choice_automation.py

一般用户建议使用图形界面。

生成 exe

项目内置 PyInstaller spec 文件：

choice_announcement_workbench.spec

在项目根目录运行：

pyinstaller choice_announcement_workbench.spec

打包完成后会生成：

dist\ChoiceDownloader.exe

发布到 GitHub Releases 时，建议命名为：

ChoiceDownloader-v0.3.2-hk-windows-x64.exe

项目结构

ChoiceDownloader\
  scripts\
    choice_automation.py          # Choice 自动化核心流程
    choice_automation_gui.py      # Tkinter 图形界面
  templates\
    company_list_template.xlsx    # 公司名单导入模板
    README.md                     # 模板说明
  release\
    ChoiceDownloader-v0.3.2-hk-windows-x64.exe
  choice_announcement_workbench.spec
  requirements.txt
  README.md
  README_EN.md
  .gitignore

使用前检查

批量处理真实任务前，建议确认：

• Choice 金融终端已经登录。
• Excel 第一行存在完全一致的 公司名称 列。
• 下载目录和日志目录有写入权限。
• GUI 中路径和运行参数均已填写。
• 首次运行先用 1 家公司验证流程。
• 屏幕分辨率、缩放比例和 Choice 界面布局保持稳定。
• 运行期间不要手动点击 Choice 页面或移动鼠标干扰自动化流程。
• 批量运行时不要勾选“跳过导航”。
• 文件名筛选关键词符合目标公告类型，例如 10-K,20-F,40-F。

常见问题

情况	处理方式
找不到 Choice 程序	在界面里重新选择本机 Choice 的 .exe 或快捷方式。
找不到 公司名称 列	检查 Excel 第一行列名是否完全等于 公司名称。
页面点击位置不准	检查分辨率、缩放比例和 Choice 页面布局，先用 1 家公司测试。
下载后没有匹配文件	检查文件名关键词和匹配方式，或先清空关键词确认是否下载成功。
某些公司失败但其他公司正常	查看 choice_batch_summary.xlsx 和日志，失败企业可后续单独重跑。
程序目录没有生成 JSON 配置	当前版本预期如此。设置记忆保存在用户配置目录，例如 %APPDATA%\ChoiceDownloader\settings.json，不会写到 exe 所在目录。
目录选择按钮打不开	可直接手动输入目录路径；也可查看系统临时目录里的 GUI 错误日志。

隐私与发布清理

发布源码或共享项目文件夹前，请不要提交以下内容：

• 真实下载结果：downloads/
• 运行日志：logs/
• PyInstaller 中间目录：build/、dist/
• Python 缓存：__pycache__/、*.pyc
• 本机 GUI 配置缓存，例如 %APPDATA%\ChoiceDownloader\settings.json
• 真实公司名单、真实业务 Excel、Choice 下载文件

当前发布版不会预填用户路径、公司名单和筛选关键词。GUI 记忆配置只保存在当前 Windows 用户的 AppData 配置目录，不会写入项目目录；日志和下载结果只会写入你在界面中选择的目录。

致谢

感谢所有在 Choice 公告下载流程、字段定位、批量测试、失败企业复核和模板整理过程中提供反馈的使用者。也感谢 pywinauto、openpyxl、PyInstaller 等开源项目为本工具提供桌面自动化、Excel 处理和 Windows 打包能力。

版权说明

Copyright (c) 2026 Liu Juncheng. All rights reserved.

本项目用于辅助用户在已授权的 Choice 金融终端环境中批量下载公告文件。未经作者许可，请勿将本项目代码、模板或打包产物用于未授权的商业分发。使用本工具下载和整理的数据仍需使用者自行核对，工具输出不构成投资、财务、法律、审计或数据合规意见。