通用操作手册 · 以 Banana Cat + DeepSeek API 为例

适用环境：Windows + PowerShell + Python

示例项目路径：D:\Project\banana_cat\banana_cat_codex_pack_v1

1. 整体流程

本地 Python 项目调用在线 API，通常遵循：进入项目目录 → 创建/使用虚拟环境 → 安装依赖 → 获取 API Key → 安全地把 Key 提供给程序 → SDK 请求 API → 程序处理返回结果。

香蕉猫示例：Banana Cat → OpenAI Python SDK → DeepSeek API → 模型 → 返回文本 → 桌宠气泡显示。

2. 打开终端并进入项目

打开 Windows PowerShell。提示符一般类似：

PS C:\Users\用户名>

进入项目目录：

cd "D:\Project\banana_cat\banana_cat_codex_pack_v1"

成功后，提示符会切换到项目路径。

3. 创建虚拟环境

项目第一次运行时，通常创建独立虚拟环境：

python -m venv .venv

虚拟环境可以理解为“这个项目自己的 Python 环境”，用于隔离 PySide6、openai 等依赖，避免污染系统全局 Python。

4. 安装与检查依赖

如果项目有 requirements.txt：

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

检查依赖关系：

.\.venv\Scripts\python.exe -m pip check

看到 “No broken requirements found.” 通常表示依赖关系正常。查看已安装包：

.\.venv\Scripts\python.exe -m pip list

5. API Key 与安全原则

API Key 是访问在线服务的凭证，应像密码一样保护。不要公开截图、上传 GitHub、写入 README，也不要把真实 Key 硬编码进源码。

错误示例：

api_key = "sk-真实密钥"

更推荐让程序从环境变量或系统安全凭据存储中读取。

6. PowerShell 临时设置 API Key

以 DeepSeek 为例，程序读取 DEEPSEEK_API_KEY：

$env:DEEPSEEK_API_KEY="你的API Key"

检查是否存在而不打印完整 Key：

if ($env:DEEPSEEK_API_KEY) { "API Key 已设置" } else { "API Key 未设置" }

这种 $env:... 设置通常只对当前 PowerShell 会话有效。关闭终端后，新终端往往需要重新设置。

7. Python 如何读取环境变量

import os

api_key = os.getenv("DEEPSEEK_API_KEY")

源码只知道变量名，不需要包含真实凭据。

8. 运行项目

香蕉猫项目入口为 main.py。推荐明确使用项目虚拟环境中的 Python：

.\.venv\Scripts\python.exe main.py

相比直接执行 python main.py，这种方式可以确保使用的是项目自己的解释器和依赖。

9. 香蕉猫日常启动速查

已经完成环境安装后，日常开发启动只需：

cd "D:\Project\banana_cat\banana_cat_codex_pack_v1"
$env:DEEPSEEK_API_KEY="你的API Key"
.\.venv\Scripts\python.exe main.py

如果 Phase 9A 已将 Key 保存到 Windows 安全凭据存储，之后可能不再需要每次手动设置环境变量。

10. 第一次拿到类似 Python 项目的通用模板

cd "项目路径"
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
$env:SOME_API_KEY="你的Key"
.\.venv\Scripts\python.exe main.py

可记忆为：cd → venv → pip install → API Key → run。

11. SDK、API 与模型的区别

SDK：程序使用的客户端库，例如 Python 的 openai 包。

API：远程服务入口，例如 DeepSeek 的 API 服务。

模型：服务端实际处理请求的模型名称。

关系：Python 程序 → SDK → API 服务 → 模型 → 返回结果。

安装 openai SDK 并不意味着一定调用 OpenAI；兼容 OpenAI API 格式的服务可以通过修改 base_url 等配置使用同一 SDK。

12. 常见错误排查

12.1 Python 找不到

python --version

若命令不可用，优先检查 Python 安装和 PATH。

12.2 ModuleNotFoundError

.\.venv\Scripts\python.exe -m pip list
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

重点确认运行程序和安装依赖使用的是同一个虚拟环境。

12.3 API Key 未配置

if ($env:DEEPSEEK_API_KEY) { "已设置" } else { "未设置" }

12.4 401 / Unauthorized

优先检查 Key 是否正确/失效、账户权限和请求服务是否正确，不要一上来重构程序。

12.5 项目能启动但 AI 不能用

这通常意味着 GUI/Python 环境正常，问题集中在 API 层。依次检查：凭据 → 网络 → Base URL → 模型名 → 余额/权限 → 请求参数。

13. 开发模式与正式软件

开发阶段：PowerShell → 设置环境 → Python → main.py → 桌宠。优点是日志和报错清晰，适合调试。

正式发布阶段：BananaCat.exe → 读取用户设置/安全凭据 → 桌宠出现。用户不再需要手动 cd、设置环境变量或运行 Python。

14. 最值得记住的十个问题

1. 项目在哪里？

2. Python 环境是什么？

3. 依赖安装了吗？

4. API Key 从哪里来？

5. Key 如何安全提供给程序？

6. SDK 请求哪个 API 地址？

7. 使用哪个模型/服务？

8. 入口文件是什么？

9. 怎么运行？

10. 出错属于环境、依赖、认证、网络还是程序？

15. 香蕉猫速查卡

进入项目：
cd "D:\Project\banana_cat\banana_cat_codex_pack_v1"

检查 Key：
if ($env:DEEPSEEK_API_KEY) { "API Key 已设置" } else { "API Key 未设置" }

临时设置 Key：
$env:DEEPSEEK_API_KEY="你的API Key"

检查依赖：
.\.venv\Scripts\python.exe -m pip check

重新安装依赖：
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

启动：
.\.venv\Scripts\python.exe main.py