chore: configure and apply ruff format

.env.example

@@ -4,7 +4,11 @@
 # 聊天模型或 OpenAI 兼容渠道
 OPENAI_API_KEY="sk-your-openai-compatible-key"
 OPENAI_API_BASE="https://api.openai.com/v1"
-DEFAULT_LLM_PROVIDER="openai"
+# 默认聊天渠道由 config.toml 的 default_llm_provider 决定（默认 "google"）。
+# 不要放开下一行：环境变量优先于 config.toml，一旦启用就会覆盖 TOML 里的
+# 零凭证默认值，导致「按示例复制即可运行」失效（14 条模型配置因密钥为空串
+# 在运行期失败）。若确实要用 OpenAI 兼容渠道，请在 config.toml 中改。
+# DEFAULT_LLM_PROVIDER="openai"
 
 # 其他可选模型密钥
 ANTHROPIC_API_KEY=""

.github/workflows/quality.yml

@@ -0,0 +1,55 @@
+name: quality
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6.0.2
+
+      - name: Setup Python
+        uses: actions/setup-python@v6.2.0
+        with:
+          python-version: "3.11"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7.6.0
+
+      - name: Sync dependencies
+        run: uv sync --group dev
+
+      - name: Check lockfile is up to date
+        run: uv lock --check
+
+      # 格式化检查放在最前：它的失败最容易被后续步骤的输出淹没，
+      # 而且未格式化的代码会让 lint 的 diff 变得难以阅读。
+      - name: Check formatting
+        run: uv run ruff format --check main.py src scripts tests
+
+      - name: Lint
+        run: uv run ruff check main.py src scripts tests
+
+      - name: Type check
+        run: uv run mypy --cache-dir /tmp/pyrag-kit-mypy main.py src
+
+      - name: Security scan
+        run: uv run bandit -r main.py src scripts -ll
+
+      - name: Byte-compile
+        run: uv run python -m compileall -q main.py src scripts tests
+
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Check for whitespace errors
+        run: git diff --check

.github/workflows/release.yml

@@ -95,6 +95,34 @@ jobs:
             echo "version=${version}" >> "${GITHUB_OUTPUT}"
           fi
 
+      - name: Validate version metadata
+        shell: bash
+        run: |
+          set -euo pipefail
+          tag="${{ steps.release_meta.outputs.tag }}"
+          version="${{ steps.release_meta.outputs.version }}"
+
+          # 手动 workflow_dispatch 的 tag/version 是手填的，必须与仓库中的
+          # 唯一真源交叉校验：否则会发出一个版本号与产物/说明不符的 release。
+          pyproject_version="$(python -c "import tomllib, pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")"
+          if [ "${version}" != "${pyproject_version}" ]; then
+            echo "版本不匹配: 输入 ${version} vs pyproject.toml ${pyproject_version}" >&2
+            exit 1
+          fi
+
+          expected_tag="v${pyproject_version}"
+          if [ "${tag}" != "${expected_tag}" ]; then
+            echo "标签不匹配: 输入 ${tag} vs 期望 ${expected_tag}" >&2
+            exit 1
+          fi
+
+          # CHANGELOG 必须已有该版本条目（extract_release_notes 也会检查，
+          # 但在这里提前失败能给出更清楚的错误位置）。
+          if ! grep -q "^## \[${pyproject_version}\]" CHANGELOG.md; then
+            echo "CHANGELOG.md 中未找到版本 ${pyproject_version} 的条目。" >&2
+            exit 1
+          fi
+
       - name: Extract release notes
         run: python scripts/extract_release_notes.py --version "${{ steps.release_meta.outputs.version }}" --output RELEASE_NOTES.md
 

.gitignore

@@ -60,3 +60,9 @@ config.toml
 
 # 缓存目录
 .cache/
+
+# 会话/审查中间产物（本地工作文件，不入库）
+# HANDOFF.md 可能含 API Key、令牌等敏感信息，只作为本地交接备忘。
+HANDOFF.md
+# 审查过程生成的复核报告（快照哈希命名，属于一次性产物）
+.review-*.html

AGENTS.md

@@ -30,6 +30,7 @@ uv run python scripts/build_binary_release.py --target macos-arm64 --validate
 开发依赖包含 Ruff、Bandit 和 MyPy。提交前可运行：
 
 ```bash
+uv run ruff format --check main.py src scripts tests
 uv run ruff check main.py src scripts tests
 uv run bandit -r main.py src scripts -ll
 uv run mypy --cache-dir /tmp/pyrag-kit-mypy main.py src
@@ -40,9 +41,11 @@ git diff --check
 
 MyPy 使用任务专用缓存目录，避免多个进程共享 `.mypy_cache` 造成锁等待；优先修复本次改动引入的问题，并记录未覆盖的历史基线告警。
 
+以上检查由 `.github/workflows/quality.yml` 在每次 PR 与 `main` 推送时执行；本地通过后再提交，避免 CI 往返。
+
 ## Coding Style & Naming Conventions
 
-使用 4 个空格缩进、明确的公开函数类型标注和简短客观的 docstring。函数、变量和模块使用 `snake_case`，类使用 `PascalCase`，常量使用 `UPPER_CASE`。项目使用 Ruff 做 lint 检查，未配置独立 formatter；修改时遵循相邻代码风格并运行 `git diff --check`。保持服务、provider、检索和快照边界，不用静默回退或占位结果掩盖失败。
+使用 4 个空格缩进、明确的公开函数类型标注和简短客观的 docstring。函数、变量和模块使用 `snake_case`，类使用 `PascalCase`，常量使用 `UPPER_CASE`。项目使用 Ruff 同时做 lint 与格式化，配置见 `pyproject.toml` 的 `[tool.ruff]`（行宽 100、双引号、4 空格）；提交前运行 `uv run ruff format main.py src scripts tests`，不要手工对齐或调整引号。保持服务、provider、检索和快照边界，不用静默回退或占位结果掩盖失败。
 
 ## Testing Guidelines