cnkibug 0.7.0__tar.gz

cnkibug-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaffu_Alcaid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cnkibug-0.7.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: cnkibug
+Version: 0.7.0
+Summary: CNKI literature metadata collection with a desktop GUI
+License: MIT License
+        
+        Copyright (c) 2026 Kaffu_Alcaid
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Repository, https://github.com/KaffuAlcaid/CNKIBug
+Project-URL: Issues, https://github.com/KaffuAlcaid/CNKIBug/issues
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright==1.60.0
+Requires-Dist: openpyxl==3.1.5
+Requires-Dist: pywin32==311; sys_platform == "win32"
+Requires-Dist: psutil==7.2.2
+Requires-Dist: rich==15.0.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: gui
+Requires-Dist: ttkbootstrap==1.20.4; extra == "gui"
+Dynamic: license-file
+
+# CNKIBug
+
+中国知网论文信息抓取工具，提供 GUI 和终端入口，支持普通检索、GUI 高级检索、Excel/CSV 导出、引文及详情提取、停止和断点续抓。
+
+## 安装和启动
+
+Python 3.10 至 3.14，需要图形桌面和浏览器完成知网的人工验证。
+
+```bash
+python -m pip install "cnkibug[gui]"
+python -m playwright install chromium
+cnkibug-gui
+```
+
+Linux 需要 Python Tk 支持。Debian/Ubuntu 可通过系统包管理器安装 `python3-tk`；建议在虚拟环境中安装 Python 依赖。Playwright 的系统依赖按其官方安装说明准备。
+
+终端入口：
+
+```bash
+python -m pip install cnkibug
+python -m playwright install chromium
+cnkibug
+```
+
+Windows 用户可直接从 [GitHub Releases](https://github.com/KaffuAlcaid/CNKIBug/releases) 下载单文件 GUI EXE。
+
+## 数据和更新
+
+通过安装命令启动时，数据存放位置为：
+
+- Linux：`$XDG_DATA_HOME/CNKIBug-data`，默认 `~/.local/share/CNKIBug-data`
+- Windows：`%LOCALAPPDATA%/CNKIBug-data`
+- macOS：`~/Library/Application Support/CNKIBug-data`，当前不在正式支持范围
+
+导出目录由用户选择。通过源码入口或便携 EXE 启动时，仍使用启动文件旁的 `CNKIBug-data`。
+
+Python 包通过 `python -m pip install --upgrade "cnkibug[gui]"` 升级；GUI 中的 EXE 自动替换仅适用于 Windows 打包版。
+
+## 使用范围
+
+项目与中国知网不存在隶属、授权或合作关系。验证码需要手动完成；不支持校园 WebVPN、统一认证网关或纯无头服务器。请遵守网站协议和所在机构规定，合理控制访问频率。
+
+项目按 MIT License 提供，不保证网站长期兼容或结果完整。完整说明见 [项目仓库](https://github.com/KaffuAlcaid/CNKIBug)。

cnkibug-0.7.0/README.md

@@ -0,0 +1,233 @@
+# CNKIBug
+
+> 中国知网（CNKI）论文信息批量抓取工具。Windows 提供单文件 GUI `.exe`；Linux 可通过源码启动 GUI 或终端版本；macOS 可尝试通过源码运行终端版，当前不在正式支持范围。
+
+![Python](https://img.shields.io/badge/Python-3.10--3.14-blue?logo=python)
+![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux-lightgrey)
+![License](https://img.shields.io/badge/License-MIT-green)
+![Version](https://img.shields.io/github/v/release/KaffuAlcaid/CNKIBug?color=orange&label=Version)
+
+---
+
+## 功能
+
+- GUI 和终端版都支持单个或批量检索
+- GUI 提供高级检索（实验性），支持多组条件与普通检索混合执行，可在弹窗中编辑条件
+- TXT 导入自动去重，开始前会显示任务规模和预计耗时
+- 可导出 Excel 或 CSV，也可选抓取引文、关键词和摘要
+- 自动保存配置、浏览器会话、日志和任务报告
+- 中途可安全停止，并从最近完成页继续
+- GUI 可手动检查更新、选择下载加速线路并测试连接
+
+---
+
+## 运行截图
+
+<table style="border: none;">
+  <tr>
+    <td style="text-align: center; vertical-align: top; width: 50%;">
+      <img src="docs/1.png" alt="GUI 任务设置" style="width: 100%; aspect-ratio: 25 / 18; object-fit: contain; border: 1px solid #ddd; border-radius: 4px;"/>
+      <br /><sub><b>输入关键词与设置</b></sub>
+    </td>
+    <td style="text-align: center; vertical-align: top; width: 50%;">
+      <img src="docs/3.png" alt="GUI 抓取过程" style="width: 100%; aspect-ratio: 25 / 18; object-fit: contain; border: 1px solid #ddd; border-radius: 4px;"/>
+      <br /><sub><b>GUI 抓取过程</b></sub>
+    </td>
+  </tr>
+</table>
+
+完整截图和操作说明见 [使用说明](docs/usage.md)。
+
+
+---
+
+
+## 快速开始
+
+
+### 方式一：Windows 直接运行（推荐）
+
+1. 前往 [Releases](../../releases) 页面下载 `CNKIBug-GUI.exe`
+2. 确保电脑已安装 **Microsoft Edge**（Win10/11 通常已预装）
+3. 启动后输入检索项，按界面提示确认任务
+4. 手动通过知网滑块验证
+5. 抓取完成后，在任务中选择的保存目录查看 Excel 或 CSV；配置、日志和任务报告保存在启动文件旁的 `CNKIBug-data/`
+
+### 方式二：源码运行（Linux / macOS 用户或开发者）
+
+先取得完整源码并进入项目根目录：
+
+```bash
+git clone https://github.com/KaffuAlcaid/CNKIBug.git
+cd CNKIBug
+```
+
+也可下载 GitHub 提供的 Source code 压缩包，解压后进入项目根目录。
+
+#### Linux 终端版
+
+```bash
+pip install -e .
+playwright install chromium
+python run.py
+```
+
+#### Linux GUI 版
+
+```bash
+pip install -e ".[gui]"
+playwright install chromium
+python run_gui.py
+```
+
+#### macOS 终端版（非正式支持）
+
+```bash
+pip install -e .
+playwright install chromium
+python run.py
+```
+
+macOS 当前未纳入正式测试和支持范围。Release 中单独提供的 `CNKIBug-<版本>-source-tui.tar.gz` 只包含终端版源码，不包含 `run_gui.py` 和 `cnkibug/gui/`。
+
+浏览器启动并完成滑块验证后，程序会将 Excel 或 CSV 写入任务中选择的保存目录；配置、日志和任务报告保存在项目根目录的 `CNKIBug-data/`。
+
+> 源码运行需要可用的图形桌面完成滑块验证，Linux 使用 X11 / Wayland；无法在纯无头服务器运行。
+
+### 更多说明
+
+- [使用说明](docs/usage.md)：导入、输出、进度和完整截图
+- [配置说明](docs/configuration.md)：`config.json` 和常见调整
+- [开发和打包](docs/development.md)：手动打包、项目结构和测试
+
+## 系统要求
+
+| 平台            | GUI          | 终端版          |
+|---------------|--------------|--------------|
+| Windows 10/11 | `.exe` 或源码运行 | 源码运行 |
+| Linux         | 源码运行         | 源码运行         |
+| macOS         | 不支持          | 源码运行（非正式支持）  |
+
+| 项目     | 要求                                                                                      |
+|--------|-----------------------------------------------------------------------------------------|
+| 浏览器    | Windows：Microsoft Edge（已预装或手动安装）；Linux / macOS：`playwright install chromium` 的 Chromium |
+| Python | 3.10–3.14（仅源码运行需要）                                                                      |
+| 图形桌面   | 所有抓取方式均需要人工通过知网滑块验证，无法在纯无头服务器运行                                                         |
+
+---
+
+## 不支持范围
+
+CNKIBug 面向中国知网（CNKI）检索结果及公开详情页信息抓取，GUI 高级检索处于实验阶段。不支持 Web of Science / SCI 数据库，也不支持通过校园 WebVPN、统一认证网关或代管账号密码的方式抓取机构资源。
+
+遇到这类访问环境时，请改用浏览器手动访问对应平台。
+
+---
+
+## 免责声明
+
+CNKIBug 是独立开发的开源工具，与中国知网（CNKI）及其关联方不存在隶属、授权、合作或背书关系。
+
+本软件仅提供自动化操作能力。使用者应确保其访问和使用行为符合所在国家和地区合法的适用的法律法规、CNKI 用户协议及所在机构的相关规定，并自行确认对相关内容访问和处理权限。
+
+请合理控制任务规模和访问频率，本项目不以绕过任何网站的技术或商业限制为目的，不鼓励或支持任何违反服务协议或适用法律法规的使用方式。
+
+本软件按“现状”提供，不保证 CNKI 页面长期兼容，也不保证结果完整、准确或持续可用。
+
+因网络异常、网站变更、验证码、账号或 IP 限制、数据处理及使用本软件产生的风险，由使用者依法承担；作者在所在国家和地区合法的适用法律允许的范围内不承担相关责任。
+
+本免责声明作为项目文档的一部分，与仓库中的 MIT License 共同适用于本项目；如两者存在冲突，以适用法律规定为准。
+
+软件会在本地保存配置、日志、任务状态和浏览器会话信息。请妥善保管运行数据目录，并在分享日志或任务报告前检查其中是否包含敏感信息。
+
+本软件不会主动修改、去除或规避内容版权标识，也不会授予用户访问任何受版权保护内容的权利。
+
+用户应自行妥善保管账号凭据，不建议在非受信任环境运行本软件。
+
+下载并使用本软件，视作您同意本免责声明和 MIT License。
+
+---
+## 致谢 / Contributors
+
+<table style="border: none;">
+  <tr>
+    <td style="text-align: center; vertical-align: top; width: 200px;">
+      <a href="https://github.com/KaffuAlcaid">
+        <img src="https://github.com/KaffuAlcaid.png" width="80px" alt="KaffuAlcaid"/>
+        <br /><sub><b>Kaffu_Alcaid</b></sub>
+      </a><br />核心开发
+    </td>
+    <td style="text-align: center; vertical-align: top; width: 200px;">
+      <a href="https://github.com/Speechlessyc">
+        <img src="https://github.com/Speechlessyc.png" width="80px" alt="Speechlessyc"/>
+        <br /><sub><b>Speechlessyc</b></sub>
+      </a><br />图标设计 & 测试
+    </td>
+    <td style="text-align: center; vertical-align: top; width: 200px;">
+      <a href="https://github.com/cloudw233">
+        <img src="https://github.com/cloudw233.png" width="80px" alt="cloudw233"/>
+        <br /><sub><b>cloudw233</b></sub>
+      </a><br />自动化构建(CI/CD)
+    </td>
+  </tr>
+  <tr>
+     <td style="text-align: center; vertical-align: top; width: 200px;">
+      <a href="https://github.com/zirend666-prog">
+        <img src="https://github.com/zirend666-prog.png" width="80px" alt="zirend666-prog"/>
+        <br /><sub><b>zirend666-prog</b></sub>
+      </a><br />产品经理
+    </td>
+    <td style="text-align: center; vertical-align: top; width: 200px;">
+      <a href="https://github.com/LuisCotton">
+        <img src="https://github.com/LuisCotton.png" width="80px" alt="LuisCotton"/>
+        <br /><sub><b>LuisCotton</b></sub>
+      </a><br />特约吉祥物
+    </td>
+    <td style="text-align: center; vertical-align: top; width: 200px;">
+      <a href="https://github.com/clover1909">
+        <img src="https://github.com/clover1909.png" width="80px" alt="clover1909"/>
+        <br /><sub><b>clover1909</b></sub>
+      </a><br />可爱群友
+    </td>
+  </tr>
+  <tr>
+    <td style="text-align: center; vertical-align: top; width: 200px;">
+      <img src="./logo.png" width="80px" alt="Placeholder"/>
+      <br /><sub><b>虚位以待</b></sub>
+      <br />欢迎提交 PR
+    </td>
+    <td style="text-align: center; vertical-align: top; width: 200px;">
+      <img src="./logo.png" width="80px" alt="Placeholder"/>
+      <br /><sub><b>虚位以待</b></sub>
+      <br />欢迎提交 PR
+    </td>
+    <td style="text-align: center; vertical-align: top; width: 200px;">
+      <img src="./logo.png" width="80px" alt="Placeholder"/>
+      <br /><sub><b>虚位以待</b></sub>
+      <br />欢迎提交 PR
+    </td>
+  </tr>
+  <tr>
+    <td style="text-align: center; vertical-align: top; width: 200px;">
+      <a href="https://openai.com/codex/">
+        <img src="https://github.com/openai.png" width="80px" alt="ChatGPT / Codex"/>
+        <br /><sub><b>ChatGPT / Codex</b></sub>
+      </a><br />代码改进
+    </td>
+      <td style="text-align: center; vertical-align: top; width: 200px;">
+      <a href="https://claude.ai">
+        <img src="https://github.com/claude.png" width="80px" alt="Claude"/>
+        <br /><sub><b>Claude</b></sub>
+      </a><br /> 代码改进
+    </td>
+    <td style="text-align: center; vertical-align: top; width: 200px;">
+      <a href="https://gemini.google.com/">
+        <img src="https://github.com/google.png" width="80px" alt="Gemini"/>
+        <br />
+        <sub><b>Gemini</b></sub>
+      </a>
+      <br />
+      代码审查<br/>
+    </td>
+  </tr>
+</table>

cnkibug-0.7.0/cnkibug/app/__init__.py

@@ -0,0 +1 @@
+"""Application bootstrap, configuration, and console UI."""

cnkibug-0.7.0/cnkibug/app/cli.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+from ..core.events import EventSink
+from ..core.memory import MemorySampler, format_task_finished_memory
+from ..core.runtime import RuntimePaths
+from ..core.settings import ScraperSettings, get_scraper_settings
+from ..workflow.runner import scrape_cnki
+from ..workflow.state import (
+    delete_last_task,
+    describe_task,
+    get_last_task_path,
+    load_last_task,
+)
+from .console import clear_screen, safe_input
+from .environment import check_env
+from .errors import _popup_error
+from .events import ConsoleEventSink
+from .prompts import collect_task_request
+from .runtime import RuntimeState, init_runtime
+from .ui import _console
+from ..core.version import APP_VERSION
+
+
+logging.basicConfig(
+    level=logging.ERROR,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+)
+
+_logger = logging.getLogger("cnkibug.app")
+
+
+def main(program_dir: Path) -> None:
+    runtime_state = _initialize_runtime(program_dir)
+    settings = get_scraper_settings(runtime_state.config)
+    memory_sampler = MemorySampler()
+    events = ConsoleEventSink(memory_sampler=memory_sampler)
+    try:
+        clear_screen()
+        _print_banner(runtime_state)
+        check_env()
+
+        while True:
+            try:
+                resume_action = _handle_pending_task(
+                    runtime_state.paths,
+                    settings,
+                    events,
+                    memory_sampler,
+                )
+                if resume_action == "exit":
+                    break
+                if resume_action == "again":
+                    clear_screen()
+                    continue
+
+                request = collect_task_request(
+                    detail_txt_export=settings.detail_txt_export,
+                    config_path=runtime_state.paths.config_path,
+                )
+                if request is None:
+                    break
+                _logger.info(
+                    "用户选择: save_mode=%s keyword_count=%d pages=%d "
+                    "include_citation=%s include_details=%s detail_txt_export=%s",
+                    request.save_mode,
+                    len(request.keywords),
+                    request.max_pages,
+                    request.include_citation,
+                    request.include_details,
+                    request.detail_txt_export,
+                )
+                _run_task(
+                    memory_sampler,
+                    request.keywords,
+                    request.max_pages,
+                    request.save_mode,
+                    include_citation=request.include_citation,
+                    include_details=request.include_details,
+                    detail_txt_export=request.detail_txt_export,
+                    settings=settings,
+                    paths=runtime_state.paths,
+                    events=events,
+                )
+                _logger.info("本轮抓取完成")
+                if _ask_run_again("\n[*] 本轮抓取已完成！是否清屏并开始新一轮抓取？(y/n): "):
+                    clear_screen()
+                    continue
+                _console.print("\n[bold green]感谢使用 CNKIBug，再见！[/bold green]")
+                break
+            except RuntimeError as error:
+                _logger.warning("运行时错误: %s", error)
+                print(f"\n[!] {error}")
+                if safe_input("是否返回主菜单重试？(y/n): ").strip().lower() == "y":
+                    _logger.info("用户选择返回主菜单重试")
+                    continue
+                break
+            except Exception as error:
+                _logger.exception("程序遇到未知错误")
+                print("\n" + "!" * 40)
+                print(f"  程序遇到未知错误: {error}")
+                print("!" * 40)
+                break
+    except KeyboardInterrupt:
+        _logger.warning("用户中断，程序退出")
+        print("\n[*] 用户中断，程序退出。")
+    finally:
+        _logger.info("程序退出")
+        try:
+            input("\n按 [回车键 Enter] 退出程序...")
+        except (EOFError, KeyboardInterrupt):
+            pass
+
+
+def _initialize_runtime(program_dir: Path) -> RuntimeState:
+    try:
+        return init_runtime(program_dir=program_dir, app_version=APP_VERSION)
+    except OSError as error:
+        if sys.platform == "win32":
+            _popup_error([
+                "==============================================",
+                " [致命错误] 无法创建运行数据目录！",
+                "----------------------------------------------",
+                f" 错误信息: {error}",
+                "",
+                " 请检查 run.py 或 CNKIBug.exe 所在目录的写入权限。",
+                "==============================================",
+            ])
+        else:
+            print(f"[FATAL] 无法创建运行数据目录: {error}")
+        raise SystemExit(1) from error
+
+
+def _print_banner(runtime_state: RuntimeState) -> None:
+    _console.print("=" * 50)
+    _console.print("  CNKI_Bug_dev  |  copyright by Kaffu_Alcaid")
+    _console.print(f"  Version {APP_VERSION}")
+    _console.print("=" * 50)
+    _console.print("  本软件用于抓取中国知网的论文标题\n")
+    _console.print("按 Ctrl+C 可随时中断并保存已抓取数据")
+    _console.print("それは，幾千の夜を舞う、さくらと少女たちの物語ーーー")
+    _console.print("祈祷着今后的你的人生，永远都有幸福的“魔法”相伴")
+    if any(level in {"WARNING", "ERROR"} for level, _ in runtime_state.events):
+        _console.print(
+            f"[yellow][配置提示] 配置文件或运行目录已自动调整，"
+            f"详情见日志：{runtime_state.log_path}[/yellow]"
+        )
+
+
+def _handle_pending_task(
+    paths: RuntimePaths,
+    settings: ScraperSettings,
+    events: EventSink,
+    memory_sampler: MemorySampler,
+) -> str:
+    resume_state = load_last_task(paths)
+    last_task_path = get_last_task_path(paths)
+    if resume_state is None:
+        if last_task_path.exists():
+            if delete_last_task(paths) or not last_task_path.exists():
+                _console.print("[yellow][!] 检测到损坏的未完成任务缓存，已删除。[/yellow]")
+            else:
+                _console.print(
+                    "[red][x] 损坏的断点文件无法删除，请手动删除后重新启动："
+                    f"{last_task_path}[/red]"
+                )
+                return "exit"
+        return "new"
+
+    _console.print("\n[yellow][!] 检测到上次未完成的抓取任务。[/yellow]")
+    _console.print(f"    {describe_task(resume_state)}")
+    print("  1 -> 继续上次任务")
+    print("  2 -> 忽略断点，删除断点文件并开始新任务")
+    print("  0 -> 保留断点并退出程序")
+    while True:
+        choice = safe_input("请输入选项（1、2 或 0）: ").strip()
+        if choice not in {"0", "1", "2"}:
+            print("[!] 无效选项，请重新输入。")
+            continue
+        if choice == "0":
+            _logger.info("用户选择保留断点并退出")
+            return "exit"
+        if choice == "1":
+            break
+        if delete_last_task(paths) or not last_task_path.exists():
+            _logger.info("用户选择忽略并删除未完成任务断点")
+            _console.print("[yellow][*] 已忽略并删除上次任务断点。[/yellow]")
+            return "new"
+        _console.print(
+            "[red][x] 断点文件删除失败，尚未忽略该任务。"
+            f"请关闭占用文件的程序后重试：{last_task_path}[/red]"
+        )
+
+    _logger.info("用户选择继续未完成任务")
+    _run_task(
+        memory_sampler,
+        list(resume_state["keywords"]),
+        int(resume_state["max_pages"]),
+        str(resume_state["save_mode"]),
+        resume_state=resume_state,
+        settings=settings,
+        paths=paths,
+        events=events,
+    )
+    _logger.info("恢复任务结束")
+    if _ask_run_again("\n[*] 本轮抓取已结束！是否清屏并开始新一轮抓取？(y/n): "):
+        _logger.info("用户选择开始新一轮抓取")
+        return "again"
+    _console.print("\n[bold green]感谢使用 CNKIBug，再见！[/bold green]")
+    return "exit"
+
+
+def _run_task(
+    memory_sampler: MemorySampler,
+    keywords: list[str],
+    max_pages: int,
+    save_mode: str,
+    **kwargs,
+) -> None:
+    memory_sampler.reset()
+    try:
+        scrape_cnki(keywords, max_pages, save_mode, **kwargs)
+    finally:
+        _console.print(format_task_finished_memory(memory_sampler.sample(force=True)))
+
+
+def _ask_run_again(prompt: str) -> bool:
+    return safe_input(prompt).strip().lower() == "y"

cnkibug-0.7.0/cnkibug/app/console.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import os
+import sys
+
+
+def clear_screen() -> None:
+    try:
+        if not sys.stdout.isatty():
+            return
+    except Exception:
+        return
+    if sys.platform == "win32":
+        os.system("cls")  # noqa: S605, S607
+        sys.stdout.write("\033[3J")
+        sys.stdout.flush()
+    else:
+        sys.stdout.write("\033c")
+        sys.stdout.flush()
+
+
+def safe_input(prompt: str = "") -> str:
+    try:
+        return input(prompt)
+    except EOFError:
+        print("\n[*] 检测到输入流结束（EOF），程序退出。")
+        raise SystemExit(0)

cnkibug-0.7.0/cnkibug/app/environment.py

@@ -0,0 +1,47 @@
+
+# noinspection PyDeprecation
+
+import sys
+import os
+import shutil
+
+from .ui import _console
+
+_EDGE_PATHS = [
+    r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe",
+    r"C:\Program Files\Microsoft\Edge\Application\msedge.exe",
+    os.path.expandvars(r"%LOCALAPPDATA%\Microsoft\Edge\Application\msedge.exe"),
+]
+
+
+def _edge_installed() -> bool:
+    if any(os.path.isfile(p) for p in _EDGE_PATHS):
+        return True
+    return shutil.which("msedge") is not None # noqa
+
+
+def check_env():
+    if sys.platform != "win32":
+        _home = os.path.expanduser("~")
+        if sys.platform == "darwin":
+            playwright_path = os.path.join(_home, "Library", "Caches", "ms-playwright")
+        else:
+            playwright_path = os.path.join(_home, ".cache", "ms-playwright")
+        _override = os.environ.get("PLAYWRIGHT_BROWSERS_PATH")
+        if _override and _override != "0":
+            playwright_path = _override
+        if not os.path.exists(playwright_path):
+            _console.print("\n[yellow][环境缺失] 请先在终端运行: playwright install chromium[/yellow]\n")
+            # 缺少必需依赖属于失败退出，用非 0 退出码，便于脚本化/CI 正确判断。
+            sys.exit(1)
+        return
+
+    if not _edge_installed():
+        _console.print(
+            "\n[yellow][环境提示] 未检测到 Microsoft Edge，"
+            "将尝试使用 Playwright Chromium。[/yellow]"
+        )
+        _console.print(
+            "[dim]若后续浏览器启动失败，请安装 Edge 或运行："
+            "playwright install chromium[/dim]\n"
+        )