# opencode-session-browser

**Repository Path**: int_me/opencode-session-browser

## Basic Information

- **Project Name**: opencode-session-browser
- **Description**: OpenCode 历史会话重现与恢复
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-14
- **Last Updated**: 2026-03-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenCode 会话浏览器

轻量级 Web 应用，用于浏览和恢复 OpenCode 历史会话。

## 功能特性

- **会话列表**：展示所有历史会话，支持按项目筛选、标题搜索、分页
- **会话恢复**：一键复制 Session ID，提供 PowerShell 命令快速恢复
- **数据统计**：可视化展示 Token 使用量、模型分布、Agent 类型、时间趋势
- **身份验证**：可选的 HTTP Basic Auth 保护访问安全
- **局域网访问**：支持从局域网内任何设备访问

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 启动服务

**基本用法：**
```bash
python app.py
```

**启用身份验证（局域网访问推荐）：**
```bash
# Windows
set OPENCODE_SERVER_USERNAME=admin
set OPENCODE_SERVER_PASSWORD=your_password
python app.py

# Linux/macOS
export OPENCODE_SERVER_USERNAME=admin
export OPENCODE_SERVER_PASSWORD=your_password
python app.py
```

**自定义端口：**
```bash
python app.py --port 8080
```

### 3. 打开浏览器

- 本地访问：http://127.0.0.1:5000
- 局域网访问：http://你的局域网IP:5000

## 使用说明

### 浏览会话

- 在"会话列表"标签页查看所有历史会话
- 使用项目下拉框筛选特定项目的会话
- 使用搜索框按标题关键词过滤
- 勾选"显示子会话"查看 subagent 会话

### 恢复会话

**方法 1：复制 ID**
1. 点击"复制 ID"按钮
2. 在终端运行：`opencode --session <session_id>`

**方法 2：复制 PowerShell 命令**
1. 点击"复制 PS"按钮
2. 在 PowerShell 中粘贴运行 - 自动切换目录并打开会话

### 查看统计

切换到"数据统计"标签页，查看：
- 总会话数、消息数、Token 使用量、缓存命中率
- 各模型的 Token 使用明细和费用
- Agent 类型分布
- 每日会话数趋势
- 项目会话分布

## 配置说明

### 数据库路径

默认路径：`~/.local/share/opencode/opencode.db`

通过环境变量自定义路径：
```bash
export OPENCODE_DB_PATH=/path/to/opencode.db
python app.py
```

### 身份验证

设置环境变量启用 HTTP Basic Auth：
- `OPENCODE_SERVER_USERNAME`：登录用户名
- `OPENCODE_SERVER_PASSWORD`：登录密码

如果未设置，则不启用身份验证。

### 局域网访问

服务器默认监听 `0.0.0.0:5000`，可从局域网内其他设备访问。

**Windows 防火墙配置：**
如果无法从其他设备访问，需要放行 5000 端口：
```powershell
New-NetFirewallRule -DisplayName "Flask 5000" -Direction Inbound -Port 5000 -Protocol TCP -Action Allow
```

## 技术栈

- **后端**：Python + Flask
- **前端**：Tailwind CSS + Alpine.js + Chart.js
- **数据库**：SQLite（只读模式）

## 项目结构

```
opencode-session-browser/
├── app.py              # Flask 后端 + API
├── templates/
│   └── index.html      # 前端界面
├── requirements.txt    # 依赖列表
├── README.md           # 英文文档
└── README_CN.md        # 中文文档
```

## 统计数据说明

- **总会话数**：包含主会话和子会话（subagent）
- **Token 统计**：从 assistant 消息的 `tokens` 字段提取
- **缓存命中率**：`cache.read / total_input_tokens * 100%`
- **费用**：从 `cost` 字段累加（单位：美元）

## 故障排查

### 数据库找不到

确认 `~/.local/share/opencode/opencode.db` 存在，或设置 `OPENCODE_DB_PATH` 环境变量。

### 页面无法加载

检查 Flask 是否正常启动，确认访问正确的 URL。

### 统计数据为空

确认数据库中有 assistant 消息且包含 `tokens` 字段。

### 局域网无法访问

- 检查防火墙是否放行 5000 端口
- 确认两台设备在同一局域网
- 使用电脑的局域网 IP 地址，不是 127.0.0.1

## 许可证

MIT