Skip to main content

Documentation Index

Fetch the complete documentation index at: https://qitor.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

这套教程建议按顺序完成。 它不是示例展示墙，而是一门课程：帮助你在 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 风格智能体长时间运行的编码智能体从手工组装过渡到预设工具集与工作流提示词自定义工作流系统提示词 + ReActTextParsercoding_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。

​
开始前建议

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

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

​
延伸阅读

构建第一个智能体

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

智能体模式

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

Kit 参考

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

可观测性

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