PAR 文档¶

本目录包含 PAR (Programmable Agent Runtime) 的用户文档。

文档按 Diátaxis 框架组织为四个分类：教程、操作指南、参考、解释。

教程 (Tutorial)¶

学习导向 — 从零开始，手把手带你跑通。

文档	时间	内容
快速上手	30 min	安装 → 配置 provider → 写第一个带工具调用的 agent
01: RAG 问答机器人	30 min	PDF 风格问答：embed、索引、检索、回答
02: 流式 UI	25 min	用 `invoke_stream` 消费 token 流，构建实时 TTY UI
04: 多 Provider 回退	—	stub（仅英文）
05: 会话恢复	—	stub（仅英文）

任务导向 — 解决具体问题的步骤。

文档	内容
并发模式	3 层并发：Runtime 级、Fiber 级、Tool 级并行
自定义 LLM Provider	注册 Cohere、Mistral、Ollama 等自定义 provider
错误处理	error_category 分类、恢复策略、event bus 审计

FAQ：6 个常见问题（PAR vs LangChain、选择界面、流式行为、持久化、provider 支持、技能系统）。

查阅导向 — API 签名、配置项。

文档	内容
SDK 概览	SDK 模块索引与文档导航
Agent API	Agent 配置、Runtime API、工具注册、ReAct 循环
HITL API	人在环路审批（挂起-恢复、持久化、跨进程）
并行分发	并行多 Agent 分发，类型化合并
Invoke Context	单次调用上下文隔离（`Fiber.key` 绑定）
Workflow API	工作流定义、8 种 step 类型、检查点
Middleware API	9 个内置中间件与自定义中间件编写
Tools API	23 个内置工具（含类型安全 bash）
Streaming API	流式 API，token 流式输出与工具调用事件
Generate API	`invoke_generate` 长输出生成模式，截断自动续写
RAG API	RAG API，embeddings、向量存储、检索
MCP Client API	MCP 客户端（stdio + HTTP/SSE）：连接外部工具服务器
文档加载器	加载文本、Markdown、HTML、CSV、PDF 为 `Document.t`，接入 RAG
Memory API	跨会话记忆，FTS5 + 3 个内置工具
Persistence API	SQLite + Noop 持久化后端
Skills API	可复用的 prompt + 工具包，支持触发条件
Observability	指标、健康检查端点、事件总线、结构化日志
Prompt Caching	缓存系统 prompt 和重复上下文，降低延迟和成本
Content Blocks	结构化内容块，支持多模态和类型化消息部件

理解导向 — 架构原理与设计决策。

文档	内容
架构深度解析	核心抽象、模块结构、数据流、类型系统、并发模型、事件流

FAQ：6 个常见问题（PAR vs LangChain、选择界面、流式行为、持久化、provider 支持、技能系统）。

文档维护规则：标识符保留、语言标记、CJK 检查、CI 集成——见 CONTRIBUTING.md。

不在上述四个分类中的项目级文档。