> ## 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 体系中设计智能体。

这套教程建议按顺序完成。

它不是示例展示墙，而是一门课程：帮助你在 QitOS 的体系中设计智能体，而不用凭猜测决定提示词策略、解析器（parser）选择、工具组合、记忆与追踪能力到底该落在哪一层。

四节课共享同一个执行内核：

`task -> state -> prompt/protocol -> decision -> tool execution -> reduce -> trace`

变化的不是运行时，而是你在这条主链路之上逐层叠加的策略。

## 两条编写路径

这套课程会明确区分两条 QitOS 编写路径：

* `Research-first`：手写提示词、解析器、协议、传输层与工具界面。
* `Preset-first`：保持智能体实现稳定，通过家族预设（preset）切换模型家族。

理解内核时，research-first 仍然是默认心智模型。preset-first 是你在需要更强复用或多模型比较时引入的加速层。

## 这套课程和一般教程有什么不同

每一课都是自洽的，也就是说它都会明确回答：

* 这一课到底在构建什么智能体
* 新引入了哪些 state 字段，以及它们为什么重要
* 本课使用什么系统提示词，或什么提示词对
* 解析器或协议契约如何和提示词对齐
* 暴露了哪些工具或预设工具集
* 使用什么模型适配层（harness）与大模型通信
* 在这个复杂度阶段，记忆与历史应该如何选择
* 运行后应该在 `qita` 里检查哪些追踪检查点

如果某个概念在前面几课还没出现，那通常是有意为之，而不是遗漏。课程是递进式的。

## QitOS 智能体设计工作表

在 QitOS 中设计智能体，本质上总是在回答同一组问题：

| 设计问题        | 对应 QitOS 表面                                             | 你要做的决定                                     |
| ----------- | ------------------------------------------------------- | ------------------------------------------ |
| 智能体要解决什么问题？ | `task`、`prepare()`                                      | 每步要暴露给模型的目标与上下文                            |
| 哪些信息必须跨步保存？ | `StateSchema`                                           | 计划、临时记录、发现、模式标记、排序摘要                       |
| 模型该如何输出？    | `build_system_prompt()`、`model_parser`、`model_protocol` | 文本、JSON、XML、Terminus、MiniMax 或模型专属适配层      |
| 智能体能做什么？    | `ToolRegistry`、预设工具集                                    | 最小工具、编码预设、审计工具、网页工具、任务板                    |
| 循环如何从执行中学习？ | `reduce()`                                              | 哪些内容进入 state，哪些只留在追踪记录，什么算成功               |
| 长时运行如何保持稳定？ | `HistoryPolicy`、`History`、`Memory`                      | 消息裁剪、上下文压缩、检索、持久记忆                         |
| 如何检查智能体行为？  | `TraceWriter`、`qita`                                    | 面板、回放（replay）、导出（export）、提示词哈希、解析器诊断、上下文遥测 |

这张工作表会贯穿四节课始终。

## 课程递进路线

| 课次                   | 你会构建什么        | 新增的设计点                               | 提示词与解析器                                                                     | 工具                                     | 上下文策略                                           |
| -------------------- | ------------- | ------------------------------------ | --------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------- |
| 1. ReAct             | 最小但真实可用的编码智能体 | 学会默认的 `LLM -> parser -> Decision` 路径 | `REACT_SYSTEM_PROMPT` + `ReActTextParser`                                   | 手工 `ToolRegistry` + 紧凑 `CodingToolSet` | 无记忆，无上下文压缩，只在 state 中保留小临时记录                    |
| 2. PlanAct           | 规划优先的修复智能体    | 引入显式规划，而不新增第二个运行时                    | `PLAN_DRAFT_PROMPT` 用于规划，`PLAN_EXEC_SYSTEM_PROMPT` + `ReActTextParser` 用于执行 | 与第 1 课相同的编码工具                          | 计划放进 state，仍不引入记忆与上下文压缩                         |
| 3. Claude Code 风格智能体 | 长时间运行的编码智能体   | 从手工组装过渡到预设工具集与工作流提示词                 | 自定义工作流系统提示词 + `ReActTextParser`                                             | `coding_tools(...)` 预设                 | 先用 `HistoryPolicy`，再理解何时需要 `CompactHistory` 与记忆 |
| 4. 代码安全审计智能体         | 领域化审查智能体      | 在不重写运行时的情况下做领域专门化                    | `SECURITY_AUDIT_SYSTEM_PROMPT` + `ReActTextParser`，并讨论协议升级                  | `SecurityAuditToolSet` + 代码库与任务工具      | 排序发现、有限历史、面向审计的追踪记录                             |

## 模型适配层在课程中的位置

前三课共享同一种简单心智模型：

* 一个传输层（与模型 API 通信的客户端）
* 一个解析器（将原始模型输出解析为决策的组件）契约
* 通过提示词注入工具模式
* 一条清晰可见的 `LLM -> parser -> Decision` 路径

这是理解内核最短、最透明的路径。

到了 v0.4，旗舰编码示例又增加了一层：

* 底层传输层仍然可以是 `OpenAICompatibleModel`
* 但在创建传输层之前，会先解析家族预设（预配置的模型家族默认值）与适配层策略

这样同一个示例才能在 Qwen、Kimi、MiniMax、`gpt-oss` 与 Gemma 4 之间切换。

到后面你会逐渐学会何时该做协议（模型输出的格式契约）升级：

* 如果你要最大可迁移性，就继续使用文本 ReAct
* 如果你需要更严格的输出契约，可以升级到 JSON 或 XML
* 如果智能体正在驱动实时终端流，可以考虑 Terminus 协议
* 如果模型原生输出结构化工具调用，可以考虑 `MiniMaxToolCallParser` 等模型专属适配层

QitOS 支持这些变体，但课程从最可迁移、最容易观察的路径开始。

## 推荐学习顺序

<CardGroup cols={2}>
  <Card title="第 1 课：ReAct" icon="brain" href="/zh/tutorials/react">
    从最小但完整的智能体开始，理解真实提示词、真实解析器、真实工具与 qita
  </Card>

  <Card title="第 2 课：PlanAct" icon="list-check" href="/zh/tutorials/planact">
    加入显式规划，但仍保留同一条默认 Engine 主链路
  </Card>

  <Card title="第 3 课：Claude Code 风格智能体" icon="rectangle-terminal" href="/zh/tutorials/claude-code">
    学习预设工具集、工作流提示词、历史控制与上下文压缩的引入时机
  </Card>

  <Card title="第 4 课：代码安全审计智能体" icon="shield-check" href="/zh/tutorials/code-security-audit">
    学习领域专门化、排序发现，以及如何把 qita 用作审查产物
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Research-first 示例" icon="flask" href="https://github.com/Qitor/qitos/blob/main/examples/real/research_harness_agent.py">
    查看一个真正手写适配层的真实编码智能体。
  </Card>

  <Card title="Preset-first 切换" icon="shuffle" href="/zh/tutorials/switch-model-families">
    学习如何让同一个编码智能体切换多个模型家族。
  </Card>
</CardGroup>

## v0.3 可复现性工作坊

<CardGroup cols={2}>
  <Card title="可复现基准测试运行" icon="flask" href="/zh/tutorials/reproducible-benchmark-runs">
    学习官方 `qit bench` 路径、统一结果行，以及官方运行元信息。
  </Card>

  <Card title="回放失败运行" icon="arrow-rotate-left" href="/zh/tutorials/replay-and-inspect-failed-runs">
    学习如何用 qita 面板、回放、导出与差异对比来复盘失败。
  </Card>

  <Card title="切换模型家族" icon="shuffle" href="/zh/tutorials/switch-model-families">
    在同一个 Claude Code 风格示例中切换 Qwen、Kimi、MiniMax、`gpt-oss` 与 Gemma 4。
  </Card>
</CardGroup>

## 开始前建议

* 先跑过 [快速入门](/zh/quickstart) 或 [构建第一个智能体](/zh/guides/build-your-first-agent)
* 已经理解 [Agent Module](/zh/concepts/agent-module) 与 [Engine](/zh/concepts/engine) 的职责划分
* 能够提供一个 OpenAI 兼容端点，可以直接手动配置，也可以通过 QitOS 家族预设解析

## 完成四课后，你应该掌握什么

你应该能够：

* 把系统提示词当作协议契约，而不是模糊说明文字
* 选择和提示词相匹配的解析器，而不是把解析当作事后清洗
* 判断何时手工构建注册表，何时切换到预设工具集
* 区分纯状态记忆、`HistoryPolicy`、`CompactHistory` 与显式记忆适配器
* 判断什么时候值得引入模型专属适配层
* 使用 `qita` 调试提示词故障、解析器故障、工具选择错误与上下文崩溃

## 延伸阅读

<CardGroup cols={2}>
  <Card title="构建第一个智能体" icon="code" href="/zh/guides/build-your-first-agent">
    在课程前或课程中回顾基础 AgentModule 契约
  </Card>

  <Card title="智能体模式" icon="diagram-project" href="/zh/guides/agent-patterns">
    查看 ReAct、PlanAct、ToT 与 Reflexion 的更大地图
  </Card>

  <Card title="Kit 参考" icon="toolbox" href="/zh/reference/kit">
    查询课程中涉及的解析器、规划器、工具集、记忆与历史辅助工具
  </Card>

  <Card title="可观测性" icon="chart-line" href="/zh/guides/observability">
    了解 qita 面板、回放与导出如何把追踪记录变成研究产物
  </Card>
</CardGroup>