> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 开发指南

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

# 开发指南

## 前置条件

* Python 3.10+
* `pip`
* `git`

可选但推荐：

* `rg` 用于快速搜索
* `pre-commit`

## 本地配置

从本地克隆快速开始：

```bash theme={null}
pip install -r requirements.txt
```

完整贡献者配置：

```bash theme={null}
pip install -r requirements-dev.txt
pre-commit install
```

## 常用命令

运行测试：

```bash theme={null}
python -m pytest -q
```

运行核心模块 lint：

```bash theme={null}
python -m flake8 qitos/core qitos/engine qitos/models qitos/trace
```

运行核心模块类型检查：

```bash theme={null}
python -m mypy qitos/core qitos/engine qitos/models qitos/trace
```

运行覆盖率门槛：

```bash theme={null}
pytest --cov=qitos.core --cov=qitos.engine --cov=qitos.trace --cov-report=term --cov-fail-under=80 -q
```

构建包：

```bash theme={null}
python -m build
```

审计依赖：

```bash theme={null}
pip-audit
```

本地预览文档：

```bash theme={null}
npx mintlify dev docs
```

检查文档链接：

```bash theme={null}
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` 发布。

## 问题排查

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

```bash theme={null}
pip install -r requirements-dev.txt
```

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

* `build/`
* `dist/`
* `.pytest_cache/`
* `.mypy_cache/`

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