CodexRitual

简体中文 | English

CodexRitual 是一个使用 PyQt6 编写的本地代码键入练习工具。程序显示一份代码文件，按顺序接收键盘输入，并用颜色标记输入结果。可选的 AI 功能通过 OpenAI 兼容接口提供代码问答和注释副本生成。

已实现功能

代码键入练习

• 从用户数据目录读取 UTF-8 代码文件。
• 使用 Pygments 标记语法类别，并跳过注释和文档字符串。
• 正确字符显示语法颜色，错误字符显示错误颜色；错误后继续推进。
• 正确输入换行后自动跳过紧随其后的空格缩进。
• Tab 仅在当前位置确实为空格缩进时推进，单次最多处理四个空格。
• 支持退格回到前一个可练习字符。
• 接收中文输入法等 IME 已确认上屏的文本，不渲染预编辑字符串。
• 完成后显示耗时、输入字符数、错误输入数和输入准确率。

界面与本地资源

• 提供浅色和深色主题、窗口透明度设置。
• 显示仓库附带的键盘图、GIF 完成动画和编程名言。
• 可从设置窗口导入本地代码；同名文件覆盖前会确认。
• 首次启动时在系统“文档”目录下创建 CodexRitual_Data。
• 启动时补齐缺失的内置资源，不覆盖已经存在的用户文件。

当前识别的练习文件后缀：

.py .js .ts .jsx .tsx .c .h .cpp .hpp .java .go .rs
.html .css .sql .sh .txt

可选 AI 功能

• 配置 API Key、Base URL 和模型名称。
• 使用 OpenAI 兼容的 Chat Completions 接口。
• 将当前画布中的完整代码作为上下文发送给模型进行问答。
• 生成代码注释副本，并以新文件名保存，不覆盖已有副本。
• API Key 优先保存在系统凭据存储中；凭据存储不可用时会提示，并回退到本地配置文件。

AI 返回内容只做空内容和外层代码围栏检查，不做语法正确性验证。使用前应确认接口兼容性、费用和代码隐私要求。

环境要求

• Python 3.8 或更高
• 依赖见 requirements.txt

从源码运行

git clone https://github.com/tail258/CodexRitual.git
cd CodexRitual

python -m venv venv

Windows PowerShell：

.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
python main.py

macOS 或 Linux：

source venv/bin/activate
pip install -r requirements.txt
python main.py

仓库当前没有可复现的独立可执行文件构建配置，主要运行方式是从源码启动。

使用方法

1. 在顶部下拉框选择练习代码。
2. 按显示内容依次输入。错误字符会标红，但练习位置继续前进。
3. 使用退格回到前一个可练习字符；在缩进位置使用 Tab。
4. 完成后查看耗时和输入统计。
5. 在设置中导入代码、切换主题或填写 AI 接口参数。

用户数据默认位于：

系统文档目录/CodexRitual_Data/
├── assets/
│   ├── animations/
│   ├── keyboards/
│   └── snippets/
└── data/
    ├── ai_skill.txt
    ├── config.json
    └── quotes.json

代码结构

core/
├── ai_bridge.py            # AI 请求线程
├── credential_store.py     # API Key 凭据存储
├── practice_session.py     # 练习状态与输入统计
├── resource_manager.py     # 用户资源初始化
├── snippet_repository.py   # 代码文件扫描、导入和保存
└── typing_logic.py         # Pygments 逐字符映射

gui/
├── dialogs.py              # 设置与完成对话框
├── editor_widget.py        # 代码显示与输入事件
├── main_window.py          # 主窗口和功能编排
└── theme_manager.py        # 主题与偏好配置

测试

python -m unittest discover -s tests -v

测试覆盖核心状态机、代码围栏清理、Pygments 映射、凭据降级、资源初始化、文件仓库和部分无界面 GUI 行为。

当前限制

• 不记录跨会话的练习历史、课程或复习计划。
• AI 问答每次只使用当前代码和当前问题，不保存对话历史。
• AI 注释结果未进行语法解析或差异预览。
• 代码文件按 UTF-8 读取，其他编码会读取失败。
• 没有经过独立可执行文件的完整打包验证。

许可证

MIT License