QitOS 是面向 agent 研究者的 torch-flavor 框架。
你可以在同一个 AgentModule + Engine 内核上原型化方法、运行 benchmark，并用内建 qita 检查长时轨迹。
QitOS 主仓库是小而清晰的核心框架。产品级 / 展示级应用会进入独立的 qitos-zoo，包括计划中的 qitos-coder 与 qitos-cyber-agent。
快速开始 · 教程课程 · 基准测试 · CLI 参考 · 更新日志 · English README
- 立即取消状态保持一致：Engine 识别立即取消后，State、任务/运行结果、END event 与 trace manifest 现在都会记录
cancelled_immediate；qita 会将该 manifest 视为stopped，不再误判为正常完成。 - 结构化动作文本不再假完成：当原生工具模型没有返回
tool_calls、却以文本输出了格式错误的动作字段时，QitOS 现在会保留 parser 恢复路径，而不会把动作文本当成最终答案；普通自然语言结论的行为保持不变。 - 窗口安全的原生工具历史：当消息窗口裁掉 assistant 调用声明时，模型请求会移除对应的孤立工具结果，避免长时并行工具 Agent 发送非法
tool_call_id链，同时保持完整轮次和原有恢复行为不变。 - 直接构造 Engine 时保留 preset 协议：
Engine(agent=...)现在会采用build_model_for_preset(...)写入模型的协议，使 Kimi K3 等服务商别名继续使用 JSON/原生 API 工具交付，而不会静默回退到文本 ReAct。 - 空模型响应有界恢复：既无有效文本也无工具调用的模型响应现在会被记录为可追踪的
model_error，重试一次后若仍为空则明确停止，不再伪装成 parserwait并耗尽 Agent 步数预算。 - 可选 OpenAI Responses API 传输：通过
api_mode="responses"（或 YAMLapi_mode: responses）保留类型化输出项、并行函数调用、call_id工具结果、流式事件和可重放工具上下文。现有 Chat Completions 行为仍是默认值。
- 12 个方法模板：ReAct、PlanAct、SWE-Agent、Voyager、Debate、Manager-Worker、Planner-Executor、Self-Refine、Reflexion、LATS、MoA 和 Magentic-One — 每个都包含 paper.md、config.yaml 和 recipe 实现。
qit newCLI：使用qit new --template <name>从内建模板脚手架新 agent 项目。- 导出 API：
EngineConfig、ToolPermissionSpec、CriticTrace和HandoffTrace用于程序化访问引擎配置和 trace 数据。 - Tracing 集成：W&B (
WandbTraceProcessor) 和 MLflow (MlflowTraceProcessor) 实验追踪。 - FamilyPreset 可扩展性：
override()、recommended_*建议字段、MaxTokensCriteria停止条件。 - qita 成本面板：运行概览中的 token 用量和成本指标。
详见 CHANGELOG.md。
- 方法研究者：频繁改 prompt、parser、critic、tool 与 memory policy，但不想每次都重写 runtime。
- benchmark 使用者：希望 GAIA、Tau-Bench、CyBench 跑在和 agent 开发同一套内核上。
- 长时 agent 调试者：更关心 trajectory review、replay、diff 与 context collapse，而不是先拼应用脚手架。
QitOS 里的 minimal agent 应该是一个最轻量的 coding agent。它会配置真实模型、进入 workspace、改代码、跑验证，并留下 qita 可检查的 trace。
pip install "qitos[models]"
export OPENAI_API_KEY="sk-..."
qit --version
qit demo minimal
qita board --logdir runsOpenAI-compatible provider 常见补充配置：
export OPENAI_BASE_URL="https://api.siliconflow.cn/v1/"
export QITOS_MODEL="Qwen/Qwen3-8B"qit demo minimal 会先种一个最小 bug workspace，再让模型驱动的 coding agent 修复它、运行验证，并把轨迹写到 ./runs。
接下来可以继续：
- 想看 ReAct：见
examples/patterns/react.py - 想看 coding agent：见
examples/real/coding_agent.py - 想看 benchmark：从 评测总览 开始
- 想看方法模板：见 方法模板指南
| 如果你想要... | QitOS 提供... |
|---|---|
| 可复现的 agent 研究 | 稳定的 AgentModule + Engine 内核 |
| 方法 = Agent + Critic | 12 个内建方法模板，映射经典论文 |
| 强可观测性 | qita board、replay、export 与 trace 工件 |
| benchmark 工作流 | GAIA、Tau-Bench、CyBench 适配器 |
| 更少框架胶水 | 一条 canonical 执行主线 |
QitOS 内置 12 个方法模板 — 每个都是实现经典 agentic 推理模式的 Agent + Critic 组合：
| 模板 | 模式 | 论文 |
|---|---|---|
| ReAct | 推理 + 行动 | Yao et al. 2023 |
| PlanAct | 先规划再执行 | — |
| SWE-Agent | 软件工程 | Princeton 2024 |
| Voyager | 开放探索 | Wang et al. 2023 |
| Debate | 多 Agent 辩论 | — |
| Manager-Worker | 编排与委派 | — |
| Planner-Executor | 计划分解 | — |
| Self-Refine | 生成 → 批评 → 改进 | Madaan et al. 2023 |
| Reflexion | 行动 → 反思 → 重试 | Shinn et al. 2023 |
| LATS | 蒙特卡洛树搜索 | Zhou et al. 2023 |
| MoA | 并行提议 + 聚合 | Wang et al. 2024 |
| Magentic-One | 编排器 + 专家 | Furtado et al. 2024 |
直接使用：
from qitos.recipes.reflexion import ReflexionAgent, ReflexionCritic
agent = ReflexionAgent(llm=my_llm)
result = agent.run(
task="Debug the failing test",
critics=[ReflexionCritic(max_reflections=3)],
max_steps=15,
return_state=True,
)或从任意模板脚手架新 agent：
pip install qitos[cookiecutter]
qit new --agent-name my_agent --agent-description "My custom agent"
qit list-templatesQitOS 将工具导入分为三层：
qitos.kit：最简单的常用工具集入口qitos.kit.toolset：场景导向的预设和注册表构建器qitos.kit.tool.<domain>：高级原子能力导入
默认组合是列表优先：
from qitos import ToolRegistry
from qitos.kit.tool.file import ReadFile
from qitos.kit.toolset import coding_tools
registry = ToolRegistry().include_toolset(
[
ReadFile(workspace_root="."),
coding_tools(workspace_root="."),
]
)安全敏感工具为显式 opt-in 导入，不在 qitos、qitos.kit、qit demo 或快速开始路径中。
- 第一次接触： 简介
- 第一条成功路径： 快速开始
- 安装方式： 安装
- 写自己的最小 coding agent： 构建第一个 Agent
- 方法模板： 方法模板指南
- 理解运行时： AgentModule / Engine
- 看 trace： 可观测性
- 走完整课程： 教程
- 看 benchmark： 评测总览
- 看命令： CLI 参考
- 看 API： API 参考
| QitOS CLI | qita Board | qita Trajectory View |
|
|
|
QitOS 当前处于 Beta。
- 相对稳定：
AgentModule + Engine、trace/qita、canonical examples、benchmark adapters，以及官方可复现 run 契约。 - 仍会演进：更高层 convenience API、部分
kit模块、实验性 toolset。 - 如果你正在评估接入，建议从 kernel 与 examples 开始，而不是假设所有高层表面都已冻结。
- 持续演进和升级说明见 CHANGELOG.md。
- 支持的 Python 版本：3.10+
- 普通用户安装：
pip install "qitos[models]" - 版本检查：
qit --version - 最小 coding agent：
qit demo minimal - 常见 provider 配置：
OPENAI_API_KEY、OPENAI_BASE_URL、QITOS_MODEL - 仅核心安装：
pip install qitos - 仓库源码安装：
pip install -r requirements.txt - 完整开发安装：
pip install -r requirements-dev.txt - 可选扩展：
qitos[wandb]、qitos[mlflow]、qitos[cookiecutter]、qitos[all] - 安装说明： 安装
欢迎贡献方法模板、benchmark adapters、memory/history 工作流、qita UX 与核心框架能力。产品级 agent 应优先进入 qitos-zoo。开发环境、方法模板贡献、文档贡献流程详见 CONTRIBUTING.md。
MIT，见 LICENSE。