> ## 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 是一个以研究为先的智能体框架，用清晰的 AgentModule + Engine 内核构建可复现的 LLM 智能体。
QitOS 提供了一套稳定的 `AgentModule + Engine` 内核（kernel），用于构建可复现的 LLM 智能体（agent）。无论你是在原型化 ReAct 循环、运行 GAIA 基准测试（benchmark），还是交付一个面向真实工作流的编程智能体，运行结果始终可追踪、可组合、可复现。
一个长时间运行的 QitOS 编程任务不应该退化成难以理解的胶水代码。
## QitOS 中的两种编写方式
QitOS 提供两种智能体编写方式。
### 研究优先（research-first）
这是研究者的默认入口。
你可以手写：
* 系统提示词（prompt）
* 解析器（parser）——将原始模型输出解析为决策（decision）的组件
* 模型协议（protocol）——模型输出的格式契约
* 模型传输层（transport）——与模型 API 通信的客户端
* 工具面（tool surface）
这是框架里最接近 PyTorch 风格的路径：直接、显式、便于实验。
### 预设优先（preset-first）
当你需要稳定基线（baseline）或快速切换模型家族时，可以选择预设优先方式。
你会从这些层开始：
* 家族预设（family preset）
* 适配层策略（harness policy）
* 预设工具构建器
这条路径尤其适合同一个智能体在 Qwen、Kimi、MiniMax、`gpt-oss` 与 Gemma 4 之间切换的场景。
## QitOS 适合谁
QitOS 主要面向三类实践者：
* **研究者**：原型化 ReAct、PlanAct、Tree-of-Thought、Reflexion 与新的智能体方法，并获得可回放（replay）、可对比、可发表的追踪记录（trace）。
* **智能体构建者**：在稳定执行循环上构建使用工具的智能体，而不是反复手写围绕裸 LLM 调用的框架胶水。
* **评测者**：在和产品智能体相同的内核上运行 GAIA、Tau-Bench 与 CyBench，让基准测试结果真正能够迁移。
## 核心能力
### 可复现的运行
每次 QitOS 运行都会产出 `manifest.json`、`events.jsonl` 和 `steps.jsonl`。这些文件记录模型 ID、提示词哈希、配置哈希、随机种子、工具清单等关键信息，足以精确复现或比较两次运行。
### 内置可观测性：qita
`qita` 是 QitOS 自带的追踪记录查看器。任意一次运行结束后，启动看板即可查看逐步执行、回放运行轨迹，并导出（export）成独立 HTML。
```bash theme={null}
qita board --logdir runs
```
看板默认运行在 `http://127.0.0.1:8765`，当新运行出现时会自动刷新。
### 规范化的智能体模式
QitOS 内置四种经典推理模式，对应的可运行示例位于 `examples/patterns/`：
| 模式 | 说明 |
| ------------------- | ------------------------- |
| **ReAct** | 文本协议，每步至多执行一个核心动作（action） |
| **PlanAct** | 先生成显式计划，再按步骤执行 |
| **Tree-of-Thought** | 先分支、评分，再决定执行路径 |
| **Reflexion** | Actor-Critic 循环，带基于证据的重试 |
### 基准测试适配器
QitOS 提供 GAIA、Tau-Bench 与 CyBench 适配器，它们都运行在与你自定义智能体相同的 `AgentModule + Engine` 内核上，不需要另一套独立评测框架。
## 特色设计
这些设计决定了 QitOS 不只是智能体工具集合，而是一套清晰的运行时（runtime）方法论。
### 单内核架构
QitOS 最核心的约束只有一条：一次运行只有一个运行时内核。
* `AgentModule` 定义策略
* `Engine` 负责执行
* 工具、解析器、评估器（critic，可批准、停止或重试当前步骤的后置评估组件）、记忆与追踪都附着在这条主链路上
这样示例、基准测试和生产型智能体之间就能保持可比性。
### 协议感知的提示词与解析器
QitOS 把提示词格式与解析器选择当作一等设计契约：
* ReAct 提示词搭配 `ReActTextParser`
* JSON 提示词搭配 `JsonDecisionParser`
* XML 提示词搭配 `XmlDecisionParser`
* Terminus、MiniMax 工具调用解析器等结构化变体也仍然走同一条 `model response -> parser -> Decision` 路径
正因为这层契约是显式的，追踪记录才不会退化成提供商特定的隐式胶水。协议和解析器的匹配关系始终可审计。
### 以预设为优先的智能体编写方式
QitOS 提供可复用的编写模块，不需要每个智能体从零开始组装一切：
* `coding_tools(...)`、`advanced_coding_tools(...)`、`web_tools()`、`task_tools(...)`
* `WindowMemory`、`SummaryMemory`、`VectorMemory`、`MarkdownFileMemory`
* `WindowHistory`、`TokenBudgetSummaryHistory`、`CompactHistory`
* `NumberedPlanBuilder`、`DynamicTreeSearch`
研究者可以调整策略，而不必重搭整套基础设施。
### 面向长时运行的上下文控制
长时运行智能体是 QitOS 的一等公民。你可以通过这些层次控制上下文膨胀：
* `HistoryPolicy` 控制消息选择
* `TokenBudgetSummaryHistory` 做 token 预算感知的摘要
* `CompactHistory` 做多阶段上下文压缩（compaction）
* 记忆适配器负责语义检索与持久记忆
这也是 QitOS 的研究价值所在：框架帮你研究长时运行，而不是假设上下文是免费的。
### 追踪优先的可观测性
QitOS 的假设是：只要一次运行重要，它就应该可检查。
每次追踪运行都会产出结构化产物（artifact），而 `qita` 会把它们变成：
* 用于比较多次实验的看板
* 用于逐步理解单次运行的回放
* 用于分享与审计的导出
### 不引入新运行时的领域专门化
QitOS 一个关键的设计点是：领域智能体仍然是普通的 QitOS 智能体。
Claude Code 风格智能体、基准测试运行器、代码安全审计智能体都复用了同一个运行时。领域行为体现在：
* 状态设计
* 提示词策略
* 工具组合
* `reduce()` 归约（reduce）语义
专门化因此更容易理解，也更容易复现。
## 当前状态
QitOS 当前处于 **Alpha** 阶段。稳定的基础主要是 `AgentModule + Engine` 内核、`qita` 追踪与可观测性流程、规范化示例以及基准测试适配器。更高层的便捷 API、部分 `kit` 模块和实验性工具集仍可能持续演进。若你正在评估采用路径，建议从内核与示例入手，不要假设所有 API 表面都已冻结。
## 接下来读什么
2 分钟内运行第一个智能体
通过四节课程理解 QitOS 的智能体设计方法
安装 QitOS 及其可选组件
理解 AgentModule、Engine、State 与 Tools
查看 ReAct、PlanAct、ToT 与 Reflexion 的模式地图
浏览内置解析器、工具集、记忆、规划与历史策略
了解 QitOS 如何让每次运行都可检查、可回放、可导出