Reflexio 使用指南：让 AI 智能体从每次交互中持续学习

Reflexio 使用指南：让 AI 智能体从每次交互中持续学习

智能体犯了错，用户纠正了它------然后呢？大多数系统里，这条经验就埋进日志里再也没人看了。Reflexio 把它变成智能体下次可复用的行为：哪些该重复、哪些该避免，每一次学习都清晰可见、可测试、可回滚。

一、Reflexio 是什么？

1.1 一句话定义

Reflexio 是一个开源的 AI 智能体自我改进框架（Agent Self-Improvement Harness），Apache 2.0 协议。它让你的智能体从真实用户交互中持续学习------用户纠正、执行失败、出色表现，都被转化为可复用的行为改进。

核心理念：AI 系统应该在每次交互后变得更好。

1.2 解决的痛点

痛点	Reflexio 的解法
用户纠正了智能体，但下次还犯同样的错	将纠正转化为持久化的行为改进（Playbook）
成功的执行路径没有沉淀，每次从零开始	捕获成功策略并复用，避免重复规划
经验只存在于日志中，无法反哺智能体	自动提取、聚合、审批后注入智能体上下文
单个用户的偏好无法跨会话保留	用户画像（User Profile）跨会话持久化
改进过程不透明，无法审计	每次学习可见、可测试、可回滚

1.3 核心效果

根据官方基准测试和案例数据：

• 任务失败率降低超 30%（HN 发布帖数据为 36%）
• Token 消耗减少超 60%（HN 数据为 >50%，GDPVal 基准为 72%）
• 规划步骤减少 81%（GDPVal 基准，在 Hermes 智能体上测得）

GDPVal 基准细节：在 OpenAI 公开的 GDPVal 知识工作任务中，5 项任务里有 4 项，Reflexio 在已经自我学习过的 Hermes 智能体基础上，进一步减少中位数 81% 规划步骤和 72% Token 消耗------也就是说，节省是在 SOTA 自我改进智能体之上的额外增益。

---

二、核心概念

2.1 双管道架构

Reflexio 对每次交互运行两条并行管道：

用户与智能体交互
    │
    ├──→ 画像提取（Profile Extraction）→ 用户画像 → 个性化响应
    │
    └──→ 手册分析（Playbook Analysis）→ 用户手册 → 聚合 → 智能体手册 → 行为改进

管道	产出	用途
画像管道	User Profiles（用户画像）	per-user 个性化，记住用户偏好和环境
手册管道	User Playbooks → Agent Playbooks	跨用户行为改进，智能体进化

2.2 Interactions（交互）

交互是 Reflexio 的原始输入，捕获用户与系统的完整上下文：

• 文本交互：对话内容、问题、评论
• 行为交互：点击、滚动、表单提交
• 视觉交互：用户分享的图片、截图
• 元数据：角色、来源（source）、请求 ID、时间戳、智能体版本

2.3 User Profiles（用户画像）

用户画像是 Reflexio 的 per-user 记忆系统：

• AI 自动提取：可配置的提取 prompt 控制从每次交互中提取什么
• 语义可搜索：用自然语言查询，不需要精确匹配
• 持续进化：新交互自动更新和完善已有画像
• 来源可追溯：每条画像记录创建它的交互和时间
• 版本管理：current → pending → archived，支持升级/降级工作流

2.4 Playbook System（手册系统）

手册系统是 Reflexio 的核心创新，分两级：

User Playbooks（用户手册）

• 从单个用户交互中自动提取
• 每条捕获一个信号：投诉、建议、偏好
• 绑定到具体用户、交互和智能体版本
• 无需审批，自动存储

Agent Playbooks（智能体手册）

• 当足够多的用户手册围绕同一主题聚集时，Reflexio 聚类并综合为跨用户的智能体手册
• 剥离用户特定上下文，提炼为可操作的行为指令（做什么/避免什么）+ 触发条件（何时应用）
• 审批工作流：pending → approved / rejected，只有 approved 的手册才进入生产提示词

维度	User Playbook	Agent Playbook
范围	单用户、单交互	跨用户、全智能体
生成方式	从交互自动提取	用户手册聚类综合
用途	个体改进信号	可操作的智能体改进建议
审批	无，自动存储	审批工作流

2.5 Expert Learning（专家学习）

除了从用户纠正中学习，Reflexio 还支持从人类专家中学习：

• 通过 expert_content 字段发布专家提供的理想回复
• Reflexio 自动对比智能体回复与专家回复，聚焦实质性差异（缺失信息、错误方法、推理缺口），忽略风格差异
• 生成 trigger/instruction/pitfall 格式的 SOP 手册，教会智能体该怎么做

---

三、快速开始

3.1 环境要求

工具	要求
Python	≥ 3.12
SQLite 运行时	Python 链接的 SQLite ≥ 3.35.0
uv	源码运行时需要
Node.js	≥ 18（仅源码本地文档站需要）
LLM API Key	至少一个（OpenAI / Anthropic / DeepSeek 等）

检查 SQLite 版本：

python -c "import sqlite3; print(sqlite3.sqlite_version_info)"

3.2 方式一：PyPI 安装（最快）

pip install reflexio-ai

# 启动服务（API 8061、推理 8069、SQLite 存储）
# 数据保存在 ~/.reflexio
reflexio services start

# 停止服务
reflexio services stop

3.3 方式二：源码安装（贡献者）

git clone https://github.com/ReflexioAI/reflexio.git
cd reflexio

# 配置环境变量
cp .env.example .env
# 编辑 .env，设置至少一个 LLM API Key

# 安装依赖
uv sync              # Python 依赖
npm --prefix docs install  # API 文档站

# 启动服务（API 8061、Docs 8062、推理 8069）
uv run reflexio services start

# 停止
uv run reflexio services stop

源码安装后可访问 http://localhost:8062 浏览交互式 API 文档。

3.4 方式三：托管版

不想自己运维？访问 reflexio.ai 注册，免费开始，获得 30 天 Pro 试用。托管版包含增强检索和持续 RL 驱动改进，无需自己运维基础设施。

3.5 30 秒 CLI 体验

启动服务后，用 CLI 发布一段用户纠正了智能体的对话：

reflexio publish --user-id alice --session-id deploy-demo-1 --wait --data '{
  "interactions": [
    {"role": "user", "content": "Deploy the new service."},
    {"role": "assistant", "content": "Starting deployment to us-east-1..."},
    {"role": "user", "content": "Wait --- we never deploy production to us-east-1. Always use us-west-2."},
    {"role": "assistant", "content": "Understood. Switching to us-west-2."}
  ]
}'

# 搜索提取到的画像和手册
reflexio search "deployment region" --user-id alice

这段对话可能产生：

• 用户画像 ：production region is us-west-2
• 用户手册 ：confirm region before deploying

---

四、Python SDK 使用

4.1 初始化客户端

import reflexio

client = reflexio.ReflexioClient(
    url_endpoint="http://localhost:8061/"
)

托管版使用：

client = reflexio.ReflexioClient(
    url_endpoint="https://www.reflexio.ai",
    api_key="your-reflexio-api-key"
)

4.2 发布交互

client.publish_interaction(
    user_id="user-123",
    session_id="session-abc",          # 必填，稳定的会话 ID
    source="support_chat",             # 非敏感的生产者标签
    agent_version="support-agent@2.4.0",  # 追踪智能体版本
    interactions=[
        {"role": "user", "content": "Please update my billing email."},
        {"role": "agent", "content": "Done---the email is now changed."},
        {
            "role": "user",
            "content": "You must verify account ownership before changing billing details.",
        },
    ],
)

发布完整的对话轮次，包括用户的纠正或确认，并保持 agent_version 一致。不要为了触发提取而编造正面反馈。

4.3 发布专家回复

client.publish_interaction(
    user_id="user-123",
    session_id="session-xyz",
    agent_version="support-agent@2.4.0",
    interactions=[
        {"role": "user", "content": "How do I reset my password?"},
        {"role": "agent", "content": "Click forgot password."},
    ],
    expert_content="Guide the user through security verification first, then send a reset link. Never skip identity verification.",
)

Reflexio 自动对比智能体回复与专家回复，提取实质性差异并生成手册。

4.4 搜索用户画像

profiles = client.search_user_profiles(
    user_id="user_123",
    query="laptop preferences and budget",
    threshold=0.7,
)

4.5 统一搜索（推荐）

context = client.search(
    query="user wants to change sensitive account details",
    user_id="customer_123",
    agent_version="support-agent@2.4.0",
    entity_types=["user_playbooks", "agent_playbooks"],
    agent_playbook_status_filter=["approved"],  # 只有 approved 的手册才进生产
    top_k=5,
)

当智能体手册代表了某个用户手册的来源时，Reflexio 会抑制重复的用户手册，结果可能少于 top_k。

4.6 查看和审批智能体手册

# 查看待审批的手册
pending = client.get_agent_playbooks(
    agent_version="support-agent@2.4.0",
    status_filter=["pending"],
)

# 审批通过
client.update_agent_playbook_status(
    playbook_id="pb_123",
    status="approved",
)

# 手动触发聚合
client.run_playbook_aggregation(
    agent_version="support-agent@2.4.0",
    wait_for_response=True,
)

4.7 配置调整

# 局部配置更新
client.update_config({
    "window_size": 20,
    "stride_size": 10,
})

# 自定义手册提取器
client.update_config({
    "user_playbook_extractor_config": {
        "extraction_definition_prompt": (
            "Extract reusable procedures and explicit corrections about "
            "handling sensitive account changes."
        ),
        "aggregation_config": {
            "min_cluster_size": 3,
            "reaggregation_trigger_count": 2,
        },
    }
})

嵌套对象是替换而非深度合并，所以保留你仍需要的已有嵌套字段。

---

五、CLI 命令参考

命令	说明
reflexio services start	启动所有服务（API、推理、存储）
reflexio services stop	停止所有服务
reflexio publish	发布交互（支持 --data 内联 JSON、--file、--stdin）
reflexio search	搜索画像和手册
reflexio --help	查看完整命令列表

发布交互的输入方式：

# 内联 JSON
reflexio publish --user-id u1 --session-id s1 --wait --data '{"interactions": [...]}'

# 从文件
reflexio publish --user-id u1 --session-id s1 --wait --file conversation.json

# 从标准输入
cat conversation.json | reflexio publish --user-id u1 --session-id s1 --wait --stdin

---

六、集成

6.1 OpenClaw 原生集成

Reflexio 与 OpenClaw 智能体框架原生集成，无需额外配置。

6.2 mem0 无缝替换

已经在用 mem0？安装扩展包，改一行 import 即可：

pip install 'reflexio-ai[mem0]'

# 之前
from mem0 import MemoryClient

# 之后
from reflexio.mem0 import MemoryClient

client = MemoryClient(api_key="your-mem0-key")

工作原理：

• add() 调用先运行 mem0，然后尽力将同一段对话发布到 Reflexio
• search() 默认完全是 mem0 行为，不调用 Reflexio
• 需要同时获取两组结果时：

result = client.search(
    query,
    filters={"user_id": "user-123", "agent_id": "support-bot"},
    include_reflexio=True,
)
memories = result["results"]
learnings = result["reflexio"]  # 包含 status、profiles、user_playbooks、agent_playbooks

Reflexio 不会重写查询或自动将值注入提示词------由应用决定如何验证和格式化检索到的文本。Reflexio 失败不会改变成功的 mem0 add() 结果。

支持 mem0ai>=2.0,<2.1。

6.3 通用框架集成

对于 LangChain 等其他框架，直接调用 Reflexio 客户端的搜索 API，将格式化结果添加到提示词（如 system message）即可，不需要框架特定的胶水代码。

---

七、多 LLM 提供商支持

Reflexio 通过 LiteLLM 支持多家 LLM 提供商：

提供商	配置方式
OpenAI / Azure OpenAI	API Key
Anthropic	API Key
OpenRouter	API Key
Google Gemini	API Key
MiniMax	API Key
DeepSeek	API Key
DashScope / Qwen	API Key
智谱 AI / GLM	API Key
Moonshot / Kimi	API Key
xAI / Grok	API Key
自定义 OpenAI 兼容端点	base_url + API Key

在 .env 中配置对应提供商的 API Key 即可。本地嵌入模型使用 MiniLM-L6-v2（ONNX 运行时，约 80MB，冷启动自动下载）。

---

八、智能体成功评估

Reflexio 内置评估系统，量化改进效果：

8.1 会话级评估

• 默认自动采样 5% 的会话
• 会话最后一次请求后 10 分钟调度评估
• 按 source 分组比较

8.2 影子对比（Shadow Comparison）

当智能体交互包含 shadow_content 字段时，进行逐轮 head-to-head 对比。

8.3 工具使用分析

检测阻塞性问题，分析智能体的工具调用模式。

注意：按 source 分组的比较只在会话被随机分配时才能支持因果声明。

---

九、检索性能

Reflexio 的统一搜索（混合向量 + 全文检索）性能：

• 约 3,000 条索引行（画像 + 用户手册 + 智能体手册各约 1,000 条，并行查询）
• ~57 ms p50 / ~73 ms p95
• 测试环境：本地 SQLite + Apple Silicon MacBook，30 次试验 × 20 个固定查询
• 可选 LLM 查询改写提升召回率
• 可选 cross-encoder 重排序（REFLEXIO_RERANK_ENABLED 默认 true）

---

十、架构总览

客户端（SDK / CLI / HTTP API）
    │
    ▼
FastAPI 后端
    ├── 画像生成服务 → 画像提取器 → 整合器 → 存储
    ├── 手册生成服务 → 用户手册提取器 → 整合器
    │                       ├── 用户手册（存储）
    │                       └── 聚合器 → 智能体手册（存储）
    ├── 分组评估调度器 → 智能体成功评估器 → 存储（采样，延迟 10 分钟）
    ├── 影子对比工作器 → 逐轮评判 → 存储
    └── 统一搜索服务 → 画像 + 用户/智能体手册

---

十一、最佳实践

11.1 数据采集

• 发布完整对话轮次：包括用户的纠正和确认，上下文越完整提取质量越高
• 保持 agent_version 一致：这是追踪改进效果的关键
• 不要编造正面反馈：只发布真实的用户行为
• source 用非敏感标签 ：如 support-agent:v2，不要用用户 ID 或 PII

11.2 手册管理

• 审批是边界：只有 approved 的智能体手册才是有效的全智能体指导，pending 的手册属于评审工作流，不要进生产提示词
• 先看证据再调参：在审查实际提取到的证据之后，再调整手册提取定义
• 保持行为导向：手册应该是可操作的行为指令，用户事实应该放在画像里

11.3 生产集成

• 在智能体响应前调用 client.search() 获取相关画像和已审批手册
• 将检索结果格式化为 system message 或上下文注入
• 监控 approved 手册数量和用户纠正频率的变化趋势
• 定期审查 pending 手册，及时审批或拒绝

11.4 成本控制

• 画像和手册提取在后台异步排队，不阻塞主流程
• 使用本地 MiniLM 嵌入模型避免额外 API 费用
• 托管版的增强检索和 RL 改进适合高流量场景

---

十二、常见问题

Q: Reflexio 和 2023 年的 Reflexion 论文是什么关系？

A: Reflexion（Noah Shinn 等，NeurIPS 2023）是一个让智能体用自然语言自我反思并存储在情景记忆中的学术框架。Reflexio 是一个生产级的自我改进 harness，理念同源但工程化程度完全不同------它提供用户画像、手册聚合审批、专家学习、评估系统、多提供商支持和完整 SDK/CLI，是可直接嵌入生产系统的基础设施。

Q: 用户画像和用户手册有什么区别？

A: 用户画像记录关于用户的稳定事实（偏好、环境、预算），用于个性化。用户手册记录关于智能体行为的改进信号（"回复太长了"、"先验证身份"），用于行为改进。用户事实属于画像，行为指令属于手册。

Q: 智能体手册需要人工审批吗？

A: 是的。智能体手册从用户手册聚合而来后进入 pending 状态，需要人工审批后才会进入生产提示词。这确保了跨用户的行为改进是可控的、可审计的。

Q: 可以完全本地运行吗？

A: 可以。PyPI 或源码安装后，所有服务本地运行，数据存储在 ~/.reflexio 的 SQLite 中。嵌入模型使用本地 MiniLM。但提取和聚合需要调用 LLM API，需要配置至少一个提供商的 API Key。

Q: 支持哪些语言？

A: Reflexio 通过 LiteLLM 支持多语言 LLM，提取和搜索不限制语言。官方文档和界面以英文为主。

Q: 如何回滚一个不好的手册？

A: 将智能体手册的状态从 approved 改为 rejected 或 archived 即可。所有手册都有版本和来源追踪，可审计可回滚。

Q: 和 mem0 的区别是什么？

A: mem0 专注于用户记忆的存储和检索。Reflexio 在记忆之外，增加了行为改进循环（手册提取、聚合、审批）、专家学习、成功评估等能力。如果你已经在用 mem0，可以用 drop-in wrapper 同时获得两者。

---

参考资源

• 官方网站：https://www.reflexio.ai
• GitHub 仓库：https://github.com/ReflexioAI/reflexio
• 官方文档：https://www.reflexio.ai/docs
• 核心概念文档：https://www.reflexio.ai/docs/concepts/core-concepts
• 手册系统文档：https://www.reflexio.ai/docs/build/agent-playbook
• Hacker News 发布帖：https://news.ycombinator.com/item?id=49482176
• Discord 社区：https://discord.gg/7fnCxahase
• GDPVal 基准结果：见仓库 benchmark/gdpval/RESULTS.md
• Reflexion 原论文：https://arxiv.org/pdf/2303.11366

---

Reflexio 采用 Apache 2.0 协议开源，本文基于 2026 年 9 月公开资料整理。具体 API 和配置以官方文档为准。