# Gumloop 官方文档 — Reflections（完整版）

> 来源：https://docs.gumloop.com/core-concepts/reflections.md
> 抓取日期：2026-06-01
> 关联 Spec：`spec_reflections.md`

---

## 概述

Reflections 让 Gumloop Agent 能够按计划审查自己过去的工作，跨对话寻找模式，并自动提议批量改进。官方描述为"在自动驾驶仪上运行的内置绩效评审"。

**解决的问题：** 没有 Reflections 时，Agent 仅在被手动纠正或编辑指令时才改进——"这无法规模化"。Reflections 让 Agent 主动诊断你可能未注意到的系统性问题。

---

## 与其他自我改进机制的对比

| 机制 | 性质 | 时机 |
|------|------|------|
| Self-Improve Instructions | 基于用户反馈更新系统提示 | 实时，任何对话中 |
| Skill Editing | 按需创建/更新 Skill | 实时，任何对话中 |
| **Reflections** | 审查历史工作，提议批量改进 | 定时（cron），主动 |

前两者是**被动的**（由用户触发），Reflections 是**主动的**（Agent 搜寻你没发现的问题）。

三者构成 Agent 学习体系——Self-Improve Instructions（对话中实时更新 Prompt）和 Skill Editing（对话中创建/修改 Skills）是反应式的；Reflections 是主动的，发现用户自己可能没注意到的跨对话模式。

---

## 五步工作流程

### Step 1: Gather Recent Activity（收集）
收集自上次 Reflection 以来的所有操作——工具调用、对话和错误。

### Step 2: Mine for Patterns（挖掘）
自动分析产生候选模式：
- 重复的请求类型
- 反复出现的错误
- 低效的工具调用序列
- 频繁被重新获取的数据

每个候选附带置信度分数和支持的交互次数。

### Step 3: Validate with Transcripts（验证——关键步骤）
Agent 阅读实际对话记录验证每个候选模式：
- 是否真实存在
- 是否跨不同交互一致
- 是否值得修复

一次性模式、已处理的已知问题、任务固有的行为特征被拒绝。

### Step 4: Check Existing Knowledge（检查已有知识）
Agent 读取当前指令和 Skills 避免重复提议。同时检查之前的 Reflections：持续出现的模式标记为"persistent"，已修复的标记为"resolved"。

### Step 5: Propose Improvements（提议改进）
对每个验证通过的模式，Agent 选择合适的改进类型并创建提案（含详细提示词说明改什么和为什么）。

---

## 四种改进类型

| 类型 | 触发条件 | 示例 |
|------|---------|------|
| **New Skill** | 重复的多步骤工作流（3+ 一致的工具调用序列） | 反复搜索 Jira→按状态筛选→格式化表格 |
| **Skill Fix** | 现有 Skill 遗漏边界情况 | 外发邮件 Skill 未处理 OOO 回复 |
| **Instruction Update** | 行为规则或领域知识 | 强制 UTC 时间戳、记住格式偏好 |
| **Tool Access** | Agent 在绕过缺失的集成 | 用沙箱 curl 而非正确的 API 工具 |

---

## 配置选项

### Apply Behavior
- **Review Queue（默认）**：每个提案需人工审核。批准前不修改任何内容。推荐生产/面向客户 Agent
- **Auto-Apply Eligible Reflections**：低风险、证据充分的建议自动应用。高风险/不确定的仍进入审核队列。适合内部 Agent/个人助手。Auto-Apply 被描述为"保守的"

### Reflection Schedule
- 通过 cron 设置，默认**每日 UTC 22:00**
- 可自定义（每 2 天、每周等）
- 高频 Agent 建议每日运行
- 低频 Agent 建议 2-3 天或每周
- 无新活动时被跳过，不消耗信用

### Extra Reflection Instructions
自由文本字段，引导 Agent 的分析焦点：
- 针对特定集成的错误模式
- 优先减少工具调用次数
- 寻找不必要的澄清请求

### 报告投递
位于 Configuration 面板中，**所有渠道默认关闭**：
- **Send Email Report**：完成的 Reflection 报告邮件发送到指定地址
- **Send Slack DM Report**：完成的 Reflection 报告以 Slack DM 发送给 Agent 所有者
- **Notify When Skipped**：因对话量不足而跳过时通知（需先开启 Email 或 Slack）

---

## 审核与应用

Reflection 运行完成后，提案以**卡片形式**出现在 Agent 侧边栏的 Reflections 页面上。每张卡片显示标题、理由、状态和日期。

1. 点击卡片查看完整详情（含 Agent 获批后将遵循的确切提示词）
2. 审核提示词
3. 点击 **Apply** → Agent 启动新的自我改进交互
4. 该交互出现在 Agent 对话历史中

**权限：** 仅 Owner/Editor 可应用或驳回。Viewer 只读。

---

## FAQ

- **跳过运行**：无新活动时自动跳过，零信用消耗
- **信用成本**：约等于中等复杂度的 Agent 对话，取决于分析的操作和对话记录数量
- **手动触发**：不支持通过 Reflections 系统。可在对话中要求 Agent 审查（使用 Self-Improve Instructions）
- **未应用的 Reflections**：无限期保留。新运行可能取代旧的待处理建议
- **Auto-Apply 安全性**：仅低风险、证据充分的自动应用。模糊建议留在队列中
- **变更可见性**：应用的 Reflections 在对话历史中创建条目，显示编辑内容和原因

---

## 最佳实践

- 从 Review Queue 开始，评估提案质量
- 撰写具体的额外指令——针对性引导效果好于通用引导
- 定期检查 Reflections——待处理建议不会过期但会失去时效性
- 让 Agent 建立势头——早期 Reflections 可能较温和，质量随历史积累提升
- 开启 Search Past Conversations 以让 Reflection Agent 能访问完整对话记录

---

*文档由 Claude 竞品情报系统整理 · 原始来源：docs.gumloop.com*