用途
Session Search 用于搜索和分析 AI 编程助手的会话历史,帮助用户查找过去的对话、发现工作模式,并从之前的工作中学习。它适用于需要回顾历史上下文、复用过往解决方案或进行知识转移的场景。
主要能力
Terraphim 提供跨多个 AI 编程助手的统一会话搜索,支持以下来源:
- Claude Code:从 ~/.claude/projects/ 原生解析会话
- Cursor:IDE 会话历史
- Aider:基于 Git 的对话日志
- OpenCode:会话历史
核心功能包括:
- 跨消息的全文搜索
- 知识图谱增强的概念搜索
- 相关会话发现
- 时间线可视化
- 导出为 JSON/Markdown
使用方式
REPL 快速开始
构建带会话功能的版本:
cargo build -p terraphim_agent --features repl-full --release
启动 REPL:
./target/release/terraphim-agent
在 REPL 中执行:
/sessions sources # 检测可用来源
/sessions import # 从所有来源导入
/sessions search "rust" # 在会话中搜索 "rust"
/sessions stats # 显示统计信息
会话命令参考
| 命令 | 描述 |
|---|---|
| /sessions sources | 检测可用的会话来源 |
| /sessions import [source] [--limit N] | 从来源导入会话 |
| /sessions list [source] [--limit N] | 列出已导入的会话 |
| /sessions search <query> | 全文搜索 |
| /sessions stats | 显示统计信息 |
| /sessions show <id> | 显示会话详情 |
| /sessions concepts <concept> | 按知识图谱概念搜索 |
| /sessions related <id> [--min N] | 查找相关会话 |
| /sessions timeline [--group day | week] |
| /sessions export [--format json | md] [--output file] |
| /sessions enrich [id] | 用概念丰富会话 |
CLI 用法
直接使用 CLI 搜索(无需 REPL):
terraphim-agent sessions search "database migration"
导入并搜索:
terraphim-agent sessions import && terraphim-agent sessions search "API design"
导出特定会话:
terraphim-agent sessions export --session abc123 --format markdown --output session.md
面向 AI 代理
检测会话能力是否可用:
if terraphim-agent sessions sources 2>/dev/null | grep -q "claude-code"; then
echo "Session search available"
fi
编程使用(Rust)
use terraphim_sessions::{SessionService, ImportOptions};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let service = SessionService::new();
let sources = service.detect_sources();
for source in sources {
println!("{}: {:?}", source.id, source.status);
}
let options = ImportOptions::default().with_limit(100);
let sessions = service.import_all(&options).await?;
let results = service.search("async rust").await;
for session in results {
println!("{}: {} messages", session.id, session.message_count());
}
Ok(())
}
知识图谱增强
use terraphim_sessions::{SessionEnricher, EnrichmentConfig};
let config = EnrichmentConfig {
thesaurus_path: "docs/src/kg/".into(),
min_confidence: 0.8,
};
let enricher = SessionEnricher::new(config)?;
let enriched = enricher.enrich(&session)?;
for concept in enriched.concepts {
println!("{}: {} occurrences", concept.term, concept.occurrences.len());
}
let related = find_related_sessions(&sessions, &enriched, 3)?;
MCP 集成
会话搜索可通过 MCP 工具暴露:
{
"tool": "session_search",
"arguments": {
"query": "error handling patterns",
"limit": 10
}
}
claude-log-analyzer 用法
use claude_log_analyzer::{Analyzer, Reporter};
let analyzer = Analyzer::from_default_location()?;
let analyses = analyzer.analyze(None)?;
for analysis in &analyses {
for agent in &analysis.agents {
println!("{}: {} invocations", agent.agent_type, agent.invocation_count);
}
}
let reporter = Reporter::new();
reporter.print_terminal(&analyses);
适用场景
- 从过往工作中学习:搜索特定主题(如 "authentication"),查看时间线,显示相关会话详情。
- 发现模式:导入所有会话,分析代理使用情况,生成统计。
- 为新任务获取上下文:按概念搜索(如 "caching"),查找相关会话,提取可复用模式。
- 知识转移:搜索并导出会话为 Markdown 文件,便于分享或归档。
会话数据模型
pub struct Session {
pub id: SessionId,
pub source: String,
pub title: Option<String>,
pub messages: Vec<Message>,
pub metadata: SessionMetadata,
}
pub struct Message {
pub role: MessageRole,
pub content: String,
pub timestamp: Option<DateTime>,
}
pub struct SessionMetadata {
pub project_path: Option<String>,
pub started_at: Option<DateTime>,
pub ended_at: Option<DateTime>,
pub agent_types: Vec<String>,
}
配置
特性标志
[dependencies]
terraphim_agent = {
version = "1.6",
features = ["repl-sessions"]
}
terraphim_sessions = {
version = "1.6",
features = ["tsa-full", "enrichment"]
}
环境变量
| 变量 | 描述 |
|---|---|
| CLAUDE_SESSIONS_DIR | 覆盖 Claude 会话位置 |
| TERRAPHIM_VERBOSE | 启用详细日志 |
限制与故障排除
| 问题 | 解决方案 |
|---|---|
| 未找到会话 | 运行 /sessions sources 检查可用来源 |
| 导入失败 | 检查 ~/.claude/projects/ 的权限 |
| 搜索太慢 | 使用 --limit 缩小范围 |
| 概念不匹配 | 验证 docs/src/kg/ 中的知识图谱文件 |
| 功能不可用 | 使用 --features repl-sessions 重新构建 |
相关技能
- terraphim-hooks:基于知识图谱的文本替换
- debugging:使用会话历史作为调试上下文
- architecture:参考过往架构决策