Development Guide

Prerequisites, setup, common commands, and troubleshooting for QitOS contributors.

Development Guide

Prerequisites

• Python 3.10+
• pip
• git

Optional but recommended:

• rg for fast search
• pre-commit

Local Setup

Quickstart from a local clone:

pip install -r requirements.txt

Full contributor setup:

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

Common Commands

Run tests:

python -m pytest -q

Run stable-surface lint:

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

Run stable-surface type checks:

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

Run coverage gate:

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

Build the package:

python -m build

Audit Python dependencies:

pip-audit

Preview docs locally:

npx mintlify dev docs

Check docs links:

npx mintlify broken-links docs

Environment Configuration

Copy .env.example and set only the provider variables you need.

Avoid committing:

• .env
• local API keys
• temporary benchmark data
• generated run artifacts

Common Tasks

Adding A New Tool

1. Implement it under the appropriate qitos/kit/tool module.
2. Give it a clear docstring and tool spec.
3. Register it through the canonical toolset or an explicit registry builder.
4. Add behavior tests.
5. Update docs if it changes the public surface.

Security-sensitive tools must require explicit opt-in imports and must not be exposed from qitos, default qitos.kit imports, qit demo, or quickstart examples.

Adding A Product Agent

Product-grade agents belong in qitos-zoo. Keep QitOS examples small, teaching-first, and focused on one framework concept at a time.

Changing Engine Behavior

1. Preserve Decision as the execution contract.
2. Add or update hook/trace coverage.
3. Verify qita and parser behavior if event payloads change.

Removing Or Replacing APIs

1. Update examples, templates, and docs in the same change.
2. Remove long-term compatibility layers rather than introducing new ones unless migration risk is high.
3. Record the change in CHANGELOG.md.

Release Checklist

When cutting a GitHub release, verify the repo-facing surfaces before you tag:

1. Run python -m pytest -q.
2. Run python -m build.
3. Run python -m twine check dist/*.
4. Run npx mintlify broken-links docs.
5. Confirm README.md, README.zh.md, CHANGELOG.md, and the relevant docs/ pages match the shipped behavior.
6. Confirm GitHub auth works with gh auth status.
7. Create or update the release body from the release notes.
8. Push the release branch and tag, then publish with gh release create.

Troubleshooting

If coverage flags are unavailable locally, reinstall the contributor environment:

pip install -r requirements-dev.txt

If build artifacts or caches cause confusion, remove:

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

If docs links appear stale, run npx mintlify broken-links docs and preview the site with npx mintlify dev docs.