教程课程

一套面向研究者的自洽课程，帮助你在 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 支持这些变体，但课程从最可迁移、最容易观察的路径开始。

推荐学习顺序

第 1 课：ReAct

从最小但完整的智能体开始，理解真实提示词、真实解析器、真实工具与 qita

第 2 课：PlanAct

加入显式规划，但仍保留同一条默认 Engine 主链路

第 3 课：Claude Code 风格智能体

学习预设工具集、工作流提示词、历史控制与上下文压缩的引入时机

第 4 课：代码安全审计智能体

学习领域专门化、排序发现，以及如何把 qita 用作审查产物

Research-first 示例

查看一个真正手写适配层的真实编码智能体。

Preset-first 切换

学习如何让同一个编码智能体切换多个模型家族。

v0.3 可复现性工作坊

可复现基准测试运行

学习官方 qit bench 路径、统一结果行，以及官方运行元信息。

回放失败运行

学习如何用 qita 面板、回放、导出与差异对比来复盘失败。

切换模型家族

在同一个 Claude Code 风格示例中切换 Qwen、Kimi、MiniMax、gpt-oss 与 Gemma 4。

开始前建议

• 先跑过 快速入门 或 构建第一个智能体
• 已经理解 Agent Module 与 Engine 的职责划分
• 能够提供一个 OpenAI 兼容端点，可以直接手动配置，也可以通过 QitOS 家族预设解析

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

你应该能够：

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

延伸阅读

构建第一个智能体

在课程前或课程中回顾基础 AgentModule 契约

智能体模式

查看 ReAct、PlanAct、ToT 与 Reflexion 的更大地图

Kit 参考

查询课程中涉及的解析器、规划器、工具集、记忆与历史辅助工具

可观测性

了解 qita 面板、回放与导出如何把追踪记录变成研究产物