工作流

保持开发变更小而聚焦、验证明确、影响可理解。仓库使用 Turborepo 作为统一任务编排器：根任务（//#py:*、//#md:*、//#js:*，脚本位于根 package.json）覆盖 Python 工具链，工作区包（apps/docs、apps/lingc-cli）各自负责 lint / 类型 / 测试 / 构建。Taskfile.yml 是薄委托壳——task check / task test / task build / task format / task fix / task ci:* 均为单行 pnpm turbo run ... 委托——并保留需要 secrets 或 CLI 参数透传的 release / version / db / hooks / smoke 任务。

开发环境搭建

本节引导外部开发者从零开始搭建可用的开发环境。

前置条件

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）：
Terminal window
```
task install
```
这会运行 uv sync 和 pnpm install。如需分别安装：
Terminal window
```
uv sync --frozen       # Python 依赖
pnpm install --frozen-lockfile  # Node.js 依赖
```
复制环境模板：
Terminal window
```
cp .env.example .env
```
编辑 .env，设置 LINGCHU_SUPERUSERS 以及适配器连接详情以适配你的环境。

验证搭建：

task check    # 静态检查、格式化、Markdown lint、类型检查
task test     # 根 pytest + lingc-cli 测试 + 文档测试

如果两者均通过，则环境已准备好进行开发。

开发工作流

典型的开发周期：

创建分支：git checkout -b feature/your-feature
遵循现有模式和风格进行修改。

对修改过的文件运行聚焦检查：

uv run -m ruff check path/to/file.py
uv run -m ruff format path/to/file.py

提交前运行完整检查套件：
Terminal window
```
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 turbo run build --filter=docs`	静态文档输出与 Starlight/Pagefind 生成
E2E 测试	`pnpm --filter docs exec playwright test`	Playwright 浏览器测试
完整 CI 序列	`task ci`	check + test + build

构建

task build      # 构建所有工作区（根 wheel + lingc-cli + 文档）
pnpm turbo run build --filter=docs  # 仅构建文档站点
uv build --clear  # 仅构建 Python 包

i18n 工作流

当修改可翻译字符串时：

task i18n   # 提取、更新和编译 gettext 目录

这会运行 pybabel extract、pybabel update 和 pybabel compile。详见国际化。

自动化入口

优先使用以下 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/`	紧急生产修复
`docs/`	文档变更
`refactor/`	代码重构

GitHub Actions 也会匹配 feature/**、fix/**、hotfix/*、main 和 dev 等分支。正式发布仅手动触发 —— 参见发布版本，不再推送 releases/** 分支。实际目标分支应遵循维护者或 PR 页面的指引。

提交信息必须遵循 gitmoji + Conventional Commits。参见提交风格。

🐛 fix: 修复成员禁言成功反馈
📝 docs: 重写文档站
✅ test: 增加群管理异常覆盖

PR 描述

PR 应说明：

变更目的。
关键实现细节。
GitNexus 影响分析结果。
已运行的检查。
未决事项或已知风险。

如果 PR 涉及文档站点或国际化，请注明是否运行了 Markdown lint、docs lint/test/build 和 task i18n。

工作流

工作流

开发环境搭建

前置条件

安装

开发工作流

测试

构建

i18n 工作流

推荐步骤

明确目标

检查现有变更

阅读相关代码

分析影响

实现并测试

运行检查

验证变更范围