工作流
工作流
保持开发变更小而聚焦、验证明确、影响可理解。仓库使用 Taskfile.yml 作为主要自动化入口：Python/代码工作通过 uv 运行，文档/前端工作通过 pnpm 运行，跨工作区任务由 Turbo 编排。
开发环境搭建
本节引导外部开发者从零开始搭建可用的开发环境。
前置条件
- Python 3.13（
requires-python = ">=3.13, <3.14"） - uv — Python 包和项目管理器
- Node.js 22+ 和 pnpm — 用于文档站点和前端工作区
- git
安装
-
克隆仓库：
git clone https://github.com/xinvxueyuan/lingchu-bot.git cd lingchu-bot -
安装所有依赖（Python + Node.js）：
task install这会运行
uv sync和pnpm install。如需分别安装：uv sync --frozen # Python 依赖 pnpm install --frozen-lockfile # Node.js 依赖 -
复制环境模板：
cp .env.example .env编辑
.env，设置LINGCHU_SUPERUSERS、SUPERUSERS以及适配器连接详情以适配你的环境。 -
验证搭建：
task check # 静态检查、格式化、Markdown lint、类型检查 task test # Python 测试 + 文档测试如果两者均通过，则环境已准备好进行开发。
开发工作流
典型的开发周期：
-
创建分支：
git checkout -b feature/your-feature -
遵循现有模式和风格进行修改。
-
对修改过的文件运行聚焦检查：
uv run -m ruff check path/to/file.py uv run -m ruff format path/to/file.py -
提交前运行完整检查套件：
task check task test -
使用 gitmoji + Conventional Commits 格式提交（由
.husky/commit-msg强制执行）。 -
推送并按照 PR 描述指南 开启 PR。
测试
| 测试类型 | 命令 | 范围 |
|---|---|---|
| Python 单元测试 | uv run -m pytest | 所有 Python 测试 |
| Python 聚焦测试 | uv run -m pytest tests/handle/commands/test_mute.py | 单个测试文件 |
| 文档测试 | pnpm --filter docs test | Vitest 组件/单元测试 |
| 文档链接检查 | pnpm --filter docs run lint:links | 内部链接验证 |
| E2E 测试 | pnpm --filter docs exec playwright test | Playwright 浏览器测试 |
| 完整 CI 序列 | task ci | check + test + build |
构建
task build # 构建所有工作区（Python + 文档）
pnpm turbo run build --filter=docs # 仅构建文档站点
uv build --clear # 仅构建 Python 包i18n 工作流
当修改可翻译字符串时：
task i18n # 提取、更新和编译 gettext 目录这会运行 pybabel extract、pybabel update 和 pybabel compile。详见国际化。
推荐步骤
明确目标
在编写任何代码之前，明确目标、成功标准和范围外事项。
检查现有变更
运行 git status --short 确认现有变更。默认假设现有变更来自其他贡献者或更早的工作会话。
阅读相关代码
阅读相关代码和测试，优先遵循现有结构。使用 GitNexus 或 codegraph 理解代码结构和关系。
分析影响
在修改函数、类或方法之前，运行 GitNexus 或 codegraph 影响分析。
实现并测试
实现最小有用的变更并添加测试。
运行检查
通过 task check、task test 或聚焦的 uv / pnpm 命令运行相关检查。
验证变更范围
提交前运行 GitNexus detect changes。
可翻译字符串
当修改可翻译字符串时，也要同步 Babel 目录。参见国际化。
自动化入口
优先使用以下 Taskfile 任务：
task install
task check
task test
task build
task ci
task i18n对于仅涉及 Python 的变更，适当时使用聚焦的 uv run ... 检查。对于文档或前端包的变更，使用聚焦的 pnpm --filter docs ... 或 pnpm turbo run ... 检查。
工具地图
GitNexus / codegraph
理解代码结构、影响和变更范围
Context7
查询库、框架、SDK、CLI 工具或云服务的当前文档
Husky / prek
本地 Git 钩子和预提交检查
Turbo
跨工作区的 lint、类型检查和构建编排
保护工作区
不要还原、格式化或重写与当前任务无关的文件。当存在现有变更时，默认假设它们来自其他贡献者或更早的工作会话。
分支与提交
常用分支前缀：
| 前缀 | 用途 |
|---|---|
feature/ | 新功能 |
fix/ | 缺陷修复 |
hotfix/ | 紧急生产修复 |
releases/ | 发布分支 |
docs/ | 文档变更 |
refactor/ | 代码重构 |
GitHub Actions 也会匹配 feature/**、fix/**、hotfix/*、releases/**、main 和 dev 等分支。实际目标分支应遵循维护者或 PR 页面的指引。
提交信息必须遵循 gitmoji + Conventional Commits。参见提交风格。
🐛 fix: 修复成员禁言成功反馈
📝 docs: 重写文档站
✅ test: 增加群管理异常覆盖PR 描述
PR 应说明：
- 变更目的。
- 关键实现细节。
- GitNexus 影响分析结果。
- 已运行的检查。
- 未决事项或已知风险。
如果 PR 涉及文档站点或国际化，请注明是否运行了 Markdown lint、docs lint/test/build 和 task i18n。
最后更新于