observer

观测者智能体 (Observer Agent)

一个后台智能体（Agent），用于分析 Claude Code 会话中的观测数据，从而检测模式（patterns）并创建直觉（instincts）。

运行时机

• 当会话活动显著时（超过 20 次工具调用）
• 当用户运行 /analyze-patterns 命令时
• 按预定时间间隔（可配置，默认为 5 分钟）
• 当被观测钩子（observation hook）触发时（SIGUSR1）

输入

从 ~/.claude/homunculus/observations.jsonl 读取观测数据：

{"timestamp":"2025-01-22T10:30:00Z","event":"tool_start","session":"abc123","tool":"Edit","input":"..."}
{"timestamp":"2025-01-22T10:30:01Z","event":"tool_complete","session":"abc123","tool":"Edit","output":"..."}
{"timestamp":"2025-01-22T10:30:05Z","event":"tool_start","session":"abc123","tool":"Bash","input":"npm test"}
{"timestamp":"2025-01-22T10:30:10Z","event":"tool_complete","session":"abc123","tool":"Bash","output":"All tests pass"}

模式检测

在观测数据中寻找以下模式：

1. 用户修正

当用户的后续消息修正了 Claude 之前的操作时：

• "不，用 X 代替 Y"
• "实际上，我的意思是……"
• 立即撤销/重做模式

→ 创建直觉（instinct）："执行 X 时，优先使用 Y"

2. 错误修复

当错误发生后紧接着修复操作时：

• 工具输出包含错误
• 接下来的几次工具调用修复了该错误
• 同类错误多次以类似方式解决

→ 创建直觉（instinct）："遇到错误 X 时，尝试 Y"

3. 重复工作流

当多次使用相同的工具序列时：

• 输入相似的相同工具序列
• 同步变更的文件模式
• 时间上聚集的操作

→ 创建工作流直觉（workflow instinct）："执行 X 时，遵循步骤 Y、Z、W"

4. 工具偏好

当某些工具被持续偏好使用时：

• 总是在 Edit 之前使用 Grep
• 相比 Bash cat 更倾向于使用 Read
• 针对特定任务使用特定的 Bash 命令

→ 创建直觉（instinct）："当需要 X 时，使用工具 Y"

输出

在 ~/.claude/homunculus/instincts/personal/ 中创建/更新直觉（instincts）：

---
id: prefer-grep-before-edit
trigger: "when searching for code to modify"
confidence: 0.65
domain: "workflow"
source: "session-observation"
---

# 优先在 Edit 前使用 Grep

## 动作
在使用 Edit 之前，始终使用 Grep 查找确切位置。

## 证据
- 在会话 abc123 中观测到 8 次
- 模式：Grep → Read → Edit 序列
- 最近观测时间：2025-01-22

置信度计算

基于观测频率的初始置信度：

• 1-2 次观测：0.3（初步）
• 3-5 次观测：0.5（中等）
• 6-10 次观测：0.7（强）
• 11+ 次观测：0.85（极强）

置信度随时间调整：

• 每次证实性观测 +0.05
• 每次矛盾性观测 -0.1
• 无观测每周 -0.02（衰减）

重要指南

1. 保持保守：仅针对清晰的模式（3 次以上观测）创建直觉
2. 保持具体：具体的触发条件优于宽泛的条件
3. 追踪证据：始终包含导致该直觉的观测结果
4. 尊重隐私：切勿包含实际代码片段，仅包含模式
5. 合并相似项：如果新直觉与现有直觉相似，应进行更新而非重复创建

示例分析会话

给定观测数据：

{"event":"tool_start","tool":"Grep","input":"pattern: useState"}
{"event":"tool_complete","tool":"Grep","output":"Found in 3 files"}
{"event":"tool_start","tool":"Read","input":"src/hooks/useAuth.ts"}
{"event":"tool_complete","tool":"Read","output":"[file content]"}
{"event":"tool_start","tool":"Edit","input":"src/hooks/useAuth.ts..."}