第 19 章：从零到 PR

1
2

卷三：工坊实战
[15] 造新工具 -> [16] 造新技能 -> [17] 接入新模型 -> [18] 接入新频道 -> [19] 从零到PR <- you are here

前三章我们造了工具、技能、频道。代码写完了，怎么把它变成一个合规的 Pull Request？QwenPaw 有一套完整的质量门禁。这一章我们走完整流程。

质量门禁全景

1
2
3
4

本地：pre-commit -> pytest -> push
                         |
CI：  pre-commit.yml -> tests.yml -> channel-tests.yml -> merge
       (HARD gate)    (需审批)     (HARD for channels)

任何一个 HARD gate 失败，PR 不能合并。

第一步：环境准备（一次性）

1
2

pip install -e ".[dev,full]"
pre-commit install

pre-commit install 后，每次 git commit 自动运行代码质量检查。

第二步：本地质量检查

1
2
3
4
5
6
7
8
9
10
11

# 运行 pre-commit（black + flake8 + mypy + pylint）
pre-commit run --all-files

# 如果 black 自动修复了格式，重新提交
git add -u && git commit -m "style: fix formatting"

# 运行测试
pytest tests/unit/ -v --tb=short

# 如果改了 Channel，额外运行
pytest tests/contract/channels/ -v

pre-commit 检查清单

测试结构

1
2
3
4
5

tests/
  unit/           # 单元测试（按组件分目录）
  contract/       # 契约测试（接口合规性）
  integration/    # 集成测试
  conftest.py     # 全局 fixtures

第三步：提交代码

遵循 Conventional Commits 格式：

1

git commit -m "feat(tools): add http_request tool for fetching web content"

类型前缀：feat、fix、docs、style、refactor、test、chore。

第四步：创建 PR

1
2

git push origin my-feature-branch
gh pr create --title "feat(tools): add http_request tool" --body "..."

PR 模板要求填写：

• Description：改动说明和关联 Issue
• Type of change：bug fix / feature / breaking change
• Components affected：Core / Channels / Skills / CLI / Tests
• Checklist：确认 pre-commit 通过、测试通过

第五步：CI 检查

pre-commit.yml（HARD gate）

运行 black、flake8、mypy、pylint。失败则 PR 不能合并。

tests.yml（需要审批）

Python 3.10 和 3.13，在 Ubuntu/macOS/Windows 上测试。需要 maintainer 审批后运行。

channel-tests.yml（改了 Channel 时触发）

• 契约测试（HARD gate）——验证 Channel 实现了所有必需方法
• 单元测试（soft gate）
• 覆盖率报告

Channel 契约测试

新增 Channel 需要写契约测试，验证接口合规性：

1
2
3
4
5
6
7
8
9
10
11

# tests/contract/channels/test_chatx_contract.py
from tests.contract import ChannelContractTest


class TestChatXContract(ChannelContractTest):
    def create_instance(self):
        from qwenpaw.app.channels.chatx import ChatXChannel
        return ChatXChannel(
            process=mock_process,
            bot_token="test-token",
        )

契约测试自动检查 19 个验证点：抽象方法已实现、方法签名兼容、session 管理正常等。

PR 提交后

PR 创建后，GitHub Actions 自动触发 CI 检查。接下来：

Review 流程

1. 自动化检查（1-5 分钟内自动完成）：

   • pre-commit.yml 立即运行，失败则 PR 标记为 ❌
   • 如果改了 Channel，channel-tests.yml 的契约测试是 HARD gate

2. 人工 Review（通常 1-3 天内）：

   • QwenPaw 的 maintainer 团队有人认领 review
   • Review 重点：接口合规性、安全性、测试覆盖、代码风格
   • 可能需要多轮 review（review → 修改 → re-review）

3. 处理 Review 意见：

   1 2 3

   # 在同一个分支修改代码 git add -u && git commit -m "fix: address review feedback" git push origin my-feature-branch

   PR 自动更新，不需要重新创建。在 PR 评论区回复”Fixed in [commit-hash]”帮助 reviewer 追踪修改。

4. Merge 条件：

   • 所有 CI 检查通过
   • 至少一位 maintainer 批准
   • 无未解决的 review 意见

提示：如果 reviewer 的反馈你不理解，直接在评论区问清楚再改——不要猜。盲改往往会引入新问题。

常见问题

pre-commit 失败了？

black 自动修复了格式 → git add -u && git commit
flake8 报未使用导入 → 删除未使用的 import
mypy 报类型错误 → 添加类型注解

测试失败了？

1
2

# 只运行失败的测试
pytest tests/unit/test_xxx.py -v --tb=long

快速参考：Makefile 命令

自检

• 运行了 pre-commit run --all-files 且通过
• 运行了 pytest tests/unit/ -v 且通过
• 提交消息遵循 type(scope): description 格式
• PR 标题和描述填写完整
• （如果改了 Channel）契约测试通过

卷三”工坊实战”完成。下一卷”纵深”，我们深入 QwenPaw 的高级功能——配置系统、记忆管理、自治任务、多智能体协作、插件系统、命令行部署、测试与质量。