开发指南

QitOS 贡献者的前置条件、环境配置、常用命令和问题排查。

​

开发指南

​

前置条件

• Python 3.10+
• pip
• git

可选但推荐：

• rg 用于快速搜索
• pre-commit

​

本地配置

从本地克隆快速开始：

pip install -r requirements.txt

完整贡献者配置：

pip install -r requirements-dev.txt
pre-commit install

​

常用命令

运行测试：

python -m pytest -q

运行核心模块 lint：

python -m flake8 qitos/core qitos/engine qitos/models qitos/trace

运行核心模块类型检查：

python -m mypy qitos/core qitos/engine qitos/models qitos/trace

运行覆盖率门槛：

pytest --cov=qitos.core --cov=qitos.engine --cov=qitos.trace --cov-report=term --cov-fail-under=80 -q

构建包：

python -m build

审计依赖：

pip-audit

本地预览文档：

npx mintlify dev docs

检查文档链接：

npx mintlify broken-links docs

​

环境配置

复制 .env.example 并仅设置需要的 provider 变量。

避免提交：

• .env
• 本地 API 密钥
• 临时 benchmark 数据
• 生成的运行产物

​

常见任务

​

添加新工具

1. 在相应的 qitos/kit/tool 模块下实现。
2. 添加清晰的 docstring 和 tool spec。
3. 通过规范 toolset 或显式 registry builder 注册。
4. 添加行为测试。
5. 如果影响公共接口，更新文档。

安全敏感工具必须要求显式 opt-in 导入，不得从 qitos、默认 qitos.kit 导入、qit demo 或快速开始示例中暴露。

​

添加产品 Agent

产品级 Agent 属于 qitos-zoo。保持 QitOS 示例小巧、教学优先、专注于一个框架概念。

​

修改引擎行为

1. 保持 Decision 作为执行契约。
2. 添加或更新 hook/trace 覆盖。
3. 如果事件 payload 变化，验证 qita 和 parser 行为。

​

移除或替换 API

1. 在同一变更中更新示例、模板和文档。
2. 优先移除长期兼容层，除非迁移风险高。
3. 在 CHANGELOG.md 中记录变更。

​

发布检查清单

发布 GitHub release 前，验证仓库面向外部的接口：

1. 运行 python -m pytest -q。
2. 运行 python -m build。
3. 运行 python -m twine check dist/*。
4. 运行 npx mintlify broken-links docs。
5. 确认 README.md、README.zh.md、CHANGELOG.md 和相关 docs/ 页面与发布行为一致。
6. 确认 GitHub 认证正常：gh auth status。
7. 创建或更新 release body。
8. 推送发布分支和标签，然后使用 gh release create 发布。

​

问题排查

如果覆盖率标记本地不可用，重新安装贡献者环境：

pip install -r requirements-dev.txt

如果构建产物或缓存造成混乱，删除：

• build/
• dist/
• .pytest_cache/
• .mypy_cache/

如果文档链接过时，运行 npx mintlify broken-links docs 并用 npx mintlify dev docs 预览。