agentsview 完整教學 — Coding Agent Session 智慧分析平台
1. 專案定位
1.1 是什麼？
agentsview 是一個 local-first (本地優先) 的 coding agent session intelligence (session 智慧分析) 平台。它以單一 Go binary 自動發現你機器上所有 AI coding agent 的 session 資料，建立本地 SQLite 索引，提供跨 agent 的瀏覽、搜尋、token usage (token 用量) 追蹤與 cost tracking (成本追蹤) 功能。
1.2 解決什麼問題？
隨著 AI coding agent 工具百花齊放（Claude Code、Codex、Cursor、Copilot、Gemini CLI⋯⋯），開發者日常可能同時使用 3-5 種工具。各工具的 session 檔分散在不同路徑，格式不一，導致：
- 無法統一檢視：每個 agent 各有各的 session 格式與路徑
- 成本不透明：token 用量與費用散落各處，難以總覽
- 搜尋困難：過去某個 session 中的對話片段，沒有全文搜尋
- 團隊無法共享：個人 session 資料無法匯入團隊 dashboard
agentsview 一次解決以上所有問題：一個 binary，25+ agents，統一索引，100x 查詢速度。
1.3 相較於其他工具
| 特性 | agentsview | ccusage | 各 agent 內建 |
|---|---|---|---|
| 支援 agent 數 | 25+ | 僅 Claude Code | 僅自身 |
| 查詢速度 | 100x（SQLite 索引） | 每次重 parse | 各異 |
| Web UI | ✅ 含 analytics dashboard | ❌ | 部分 |
| 桌面應用 | ✅ Tauri | ❌ | ❌ |
| 團隊 PostgreSQL | ✅ | ❌ | ❌ |
| 全文搜尋 | ✅ FTS5 | ❌ | ❌ |
| Secret leak scan | ✅ | ❌ | ❌ |
| 隱私 | 完全本地 | 完全本地 | 各異 |
2. 安裝指南
2.1 一鍵安裝（推薦）
1# macOS / Linux
2curl -fsSL https://agentsview.io/install.sh | bash
3
4# Windows
5powershell -ExecutionPolicy ByPass -c "irm https://agentsview.io/install.ps1 | iex"
2.2 Homebrew
1# 桌面應用（macOS / Windows）
2brew install --cask agentsview
3
4# 注意：Linux 下 cask 安裝的 Tauri AppImage 可能顯示空白視窗
5# Linux 建議用 curl 安裝 server binary
2.3 Docker
1docker run --rm -p 127.0.0.1:8080:8080 \
2 -v agentsview-data:/data \
3 -v "$HOME/.claude/projects:/agents/claude:ro" \
4 -v "$HOME/.forge:/agents/forge:ro" \
5 -e CLAUDE_PROJECTS_DIR=/agents/claude \
6 -e FORGE_DIR=/agents/forge \
7 ghcr.io/kenn-io/agentsview:latest
Docker Compose（推薦長期運行）：
1# docker-compose.prod.yaml
2services:
3 agentsview:
4 image: ghcr.io/kenn-io/agentsview:latest
5 restart: unless-stopped
6 ports:
7 - "127.0.0.1:8080:8080"
8 environment:
9 CLAUDE_PROJECTS_DIR: /agents/claude
10 CODEX_SESSIONS_DIR: /agents/codex
11 FORGE_DIR: /agents/forge
12 OPENCODE_DIR: /agents/opencode
13 volumes:
14 - agentsview-data:/data
15 - ${HOME}/.claude/projects:/agents/claude:ro
16 - ${HOME}/.codex/sessions:/agents/codex:ro
17 - ${HOME}/.forge:/agents/forge:ro
18 - ${HOME}/.local/share/opencode:/agents/opencode:ro
19volumes:
20 agentsview-data:
2.4 從原始碼編譯
1git clone https://github.com/kenn-io/agentsview.git
2cd agentsview
3make install # 需要 Go 1.26+ 與 Node 24+
2.5 驗證安裝
1agentsview --version
2# agentsview v0.32.1 (commit: xxx, built: 2026-06-xx)
3. 核心架構解析
3.1 系統架構總覽
graph TB
subgraph "Agent Session Files"
CC[Claude Code
~/.claude/projects/]
CX[Codex
~/.codex/sessions/]
CP[Copilot CLI
~/.copilot/]
GC[Gemini CLI
~/.gemini/]
OC[OpenCode
~/.local/share/opencode/]
MORE[25+ agents...]
end
subgraph "agentsview Core (Go)"
SYNC[sync engine
file watcher + hash]
PARSER[parser
48 agent parsers]
DB[(SQLite
FTS5 full-text)]
PRICING[pricing
LiteLLM rates]
SECRETS[secrets
leak scanner]
end
subgraph "Interfaces"
CLI[CLI
cobra commands]
WEB[Web UI
Svelte 5 SPA]
DESK[Desktop App
Tauri]
API[REST API
/api/v1/*]
end
subgraph "Optional Backends"
PG[(PostgreSQL
team dashboard)]
DUCK[(DuckDB
mirror + Quack)]
end
CC & CX & CP & GC & OC & MORE --> SYNC
SYNC --> PARSER
PARSER --> DB
DB --> CLI & API
API --> WEB & DESK
DB --> PG & DUCK
PRICING --> CLI & API
SECRETS --> CLI
3.2 資料流
flowchart LR
A[Session Files
JSONL / JSON / SQLite / protobuf] -->|file watcher| B[Sync Engine]
B -->|hash dedup| C[Parser
per-agent logic]
C -->|structured data| D[(SQLite + FTS5)]
D -->|query| E[CLI Commands]
D -->|REST API + SSE| F[Web UI / Desktop]
D -->|pg push| G[(PostgreSQL)]
D -->|duckdb push| H[(DuckDB)]
3.3 核心模組詳解
internal/parser（48 個原始碼檔案）——最大模組，每個 agent 一個 parser：
| 分類 | 包含的 Agent |
|---|---|
| Anthropic 系 | Claude Code, Claude AI |
| OpenAI 系 | Codex, ChatGPT |
| Google 系 | Antigravity, Antigravity CLI |
| Microsoft 系 | Copilot CLI, VSCode Copilot |
| IDE 內建 | Cursor, Zed, Positron, Kiro IDE |
| 獨立 CLI | OpenCode, Forge, Amp, Pi, Qwen, Warp, Hermes |
| 其他 | OpenHands, iFlow, Zencoder, OpenClaw, QClaw, Kimi, Cortex, WorkBuddy, Piebald, CommandCode |
| 基礎設施 | discovery (自動偵測), taxonomy (分類), types (共用型別), content (訊息解析), termination (session 結束判斷), project (專案偵測) |
internal/server（43 個原始碼檔案）——HTTP API 服務器：
- Huma-based REST routes（
/api/v1/*） - SSE live updates（active session 即時更新）
- SPA static file serving（Svelte 5 嵌入）
- Auth middleware + CSP + DNS-rebinding protection
- Session resume（從 Web UI 恢復 terminal session）
internal/db（35 個原始碼檔案）——SQLite 資料層：
- Session / Message / ToolCall 資料表
- FTS5 全文搜尋（across all message content）
- Batch import with SAVEPOINT rollback
- Migration 管理
internal/sync（9 個原始碼檔案）——Session 發現與同步：
- File watcher（自動偵測新 session）
- SHA-256 hash-based dedup（避免重複匯入）
- Per-agent directory discovery
- 環境變數覆蓋路徑
4. CLI 命令詳細用法
4.1 基本命令
1# 啟動 server + Web UI
2agentsview serve
3
4# 指定 port
5agentsview serve --port 9090
6
7# 遠端存取（SSH port forwarding 場景）
8agentsview serve --public-url http://127.0.0.1:18080
9
10# 啟用認證
11agentsview serve --require-auth
4.2 Token Usage 追蹤
1# 每日成本摘要（預設最近 30 天）
2agentsview usage daily
3
4# 按 model 分類
5agentsview usage daily --breakdown
6
7# 過濾 agent + 日期
8agentsview usage daily --agent claude --since 2026-04-01
9
10# JSON 輸出（適合腳本整合）
11agentsview usage daily --all --json
12
13# 狀態列顯示（可整合到 shell prompt）
14agentsview usage statusline
4.3 Session 操作
1# 列出 sessions
2agentsview session list
3
4# 單一 session 的 token 用量 + 費用
5agentsview session usage <id>
6agentsview session usage <id> --format json
7
8# 搜尋 session 內容
9agentsview session search "keyword"
10
11# 匯出 session
12agentsview session export <id>
13
14# Session 訊息瀏覽
15agentsview session messages <id>
16
17# Session 中的 tool calls
18agentsview session tool-calls <id>
4.4 統計分析
1# 人類可讀的統計摘要（最近 28 天）
2agentsview stats
3
4# 機器可讀 JSON + 日期範圍
5agentsview stats --format json --since 2026-04-01 --until 2026-04-15
6
7# 按 agent 過濾
8agentsview stats --agent claude
9
10# 含 git outcome metrics（較慢，opt-in）
11agentsview stats --include-git-outcomes
12
13# 含 GitHub PR 計數
14agentsview stats --include-github-outcomes
4.5 PostgreSQL 團隊同步
1# 推送本地資料到 PG
2agentsview pg push
3
4# 背景 watch mode（自動推送新 session）
5agentsview pg push --watch --debounce 1m --interval 5m
6
7# 從 PG 提供 Web UI（唯讀）
8agentsview pg serve
9
10# OS service 管理
11agentsview pg service install # 安裝 + 啟動
12agentsview pg service status # 狀態
13agentsview pg service logs -f # 即時 log
14agentsview pg service uninstall # 移除
4.6 DuckDB 鏡像
1# 鏡像 SQLite 到 DuckDB
2agentsview duckdb push
3
4# 鏡像狀態
5agentsview duckdb status
6
7# 從 DuckDB 提供 Web UI（唯讀）
8agentsview duckdb serve
9
10# Quack 協定服務
11agentsview duckdb quack serve
4.7 Secret 掃描
1# 掃描 session 中的 secret leak
2agentsview secrets
3
4# 列出發現的 secret（預設已遮蔽）
5agentsview secrets list
6
7# 顯示所有信心等級
8agentsview secrets list --confidence all
9
10# 顯示原始值（危險！）
11agentsview secrets list --reveal
5. 應用場景
5.1 個人開發者
- 每日成本監控：
agentsview usage daily --breakdown了解各 model 的花費 - Session 回顧：搜尋過去對話中的解法片段
- 多 Agent 比較：在 analytics dashboard 比較不同 agent 的效能與成本
5.2 團隊管理
- PostgreSQL 共享 dashboard：團隊成員各自
pg push，manager 透過pg serve看全隊用量 - 成本控管：匯出 JSON → 自動化報表 → 月度 AI 工具支出報告
- Secret leak 偵測：確保團隊成員的 session 中沒有洩漏密鑰
5.3 Shell 整合
1# 在 shell prompt 中顯示今日 AI 花費
2export PS1="\$(agentsview usage statusline) \$ "
3
4# 自動化報告腳本
5agentsview stats --format json --agent claude --since $(date -d '7 days ago' +%Y-%m-%d) | jq '.cost'
5.4 CI/CD 整合
- 在 CI pipeline 中追蹤 AI agent 的 token 消耗
- 自動化成本警報（超過閾值時通知）
- Session 匯出為 HTML 或 GitHub Gist 供 code review
6. 資安掃描報告
6.1 掃描範圍
- 原始碼
cmd/、internal/、scripts/（排除 test 檔案與 testdata） - 檢查項目：任意執行、SQL injection、硬編碼 secret、網路請求、密碼學使用
6.2 發現與評估
🟢 整體風險等級：低
| 項目 | 等級 | 說明 |
|---|---|---|
| exec.CommandContext | 🟢 低 | 僅用於 pg_service_manager.go 的 OS service 管理（launchd/systemd），參數非使用者可控 |
| SQL SAVEPOINT | 🟢 低 | session_batch.go 中 SAVEPOINT 名稱為內部生成，非使用者輸入，無 SQL injection 風險 |
| http.Get | 🟢 低 | update.go 中僅用於下載更新檔案，含 SHA-256 checksum 驗證 |
| 密碼學使用 | 🟢 低 | crypto/sha256（檔案 hash）、crypto/rand（隨機 ID）——皆為標準安全實踐 |
| Telemetry | 🟡 注意 | 匿名 PostHog ping（install ID + version + OS），可透過 AGENTSVIEW_TELEMETRY_ENABLED=0 停用 |
| DNS Rebinding 防護 | 🟢 佳 | Server 驗證 Host header，預設綁定 loopback |
| CSP Middleware | 🟢 佳 | Content Security Policy 已配置 |
| Auth Middleware | 🟢 佳 | --require-auth 支援遠端存取場景 |
| Frontend XSS | 🟢 佳 | 使用 DOMPurify 消毒 HTML 內容 |
| Secret Scanning | 🟢 佳 | 內建 agentsview secrets 命令掃描 session 中的 secret leak |
| Quack 協定 | 🟡 注意 | 預設綁 loopback + 需 token；非 loopback plain HTTP 需 --allow-insecure 顯式開啟 |
6.3 安全建議
- 保護設定檔：
chmod 600 ~/.agentsview/config.toml（內含 PostgreSQL DSN） - 停用 telemetry（若有隱私顧慮）：
export AGENTSVIEW_TELEMETRY_ENABLED=0 - 遠端存取務必啟用 auth：
agentsview serve --require-auth --public-url <origin> - DuckDB Quack 遠端使用：建議 TLS URL 或走 authenticated tunnel
7. FAQ
Q1: agentsview 會上傳我的 session 資料嗎？
不會。 所有 session 資料留在本地 SQLite。唯一的網路行為：(1) 匿名 telemetry ping（可停用），(2) 選用的更新檢查（--no-update-check 可停用），(3) 選用的 PostgreSQL/DuckDB sync（由你主動觸發）。
Q2: 支援哪些作業系統？
macOS、Linux、Windows（含 WSL）。Docker 映像基於 Debian bookworm-slim。Desktop app 透過 Tauri 支援 macOS + Windows + Linux（Linux AppImage）。
Q3: 如何新增尚未支援的 agent？
agentsview 的 parser 架構是 pluggable 的——每個 agent 一個 Go 檔案在 internal/parser/。可參考現有 parser（如 claude.go 或 codex.go）的模式，實作 discovery + parsing 邏輯，提交 PR。
Q4: SQLite vs PostgreSQL vs DuckDB 如何選擇？
- SQLite（預設）：個人使用，零設定，FTS5 搜尋，寫入 UI
- PostgreSQL：團隊 dashboard，
pg push推送，唯讀 UI - DuckDB：可攜式分析檔案，Quack 協定遠端讀取，唯讀 UI
三者可並存——SQLite 是 primary archive，PG / DuckDB 是 mirror。
Q5: 如何處理 Antigravity CLI 的加密 session？
較新版的 Antigravity CLI 以 SQLite 儲存 trajectory，agentsview 直接讀取。較舊版以 AES-GCM 加密的 .pb 存放，需搭配 agy-reader 解密後生成 sidecar，agentsview 的 file watcher 會自動偵測。
Q6: 費用計算準確嗎？
agentsview 使用 LiteLLM rates 計算，支援 prompt caching (cache creation / read tokens) 的差異化計費。有離線 fallback。若 model 無定價資料，has_cost 欄位為 false。
8. 進階技巧
8.1 自定義 Agent 路徑
每個 agent 的 session 目錄都可透過環境變數覆蓋：
1export CLAUDE_PROJECTS_DIR=/custom/path/claude
2export CODEX_SESSIONS_DIR=/custom/path/codex
3export FORGE_DIR=/custom/path/forge
8.2 SSH Port Forwarding 遠端開發
1# 在遠端伺服器啟動
2agentsview serve --public-url http://127.0.0.1:18080
3
4# 本地 SSH tunnel
5ssh -L 18080:127.0.0.1:8080 remote-host
6
7# 瀏覽器開 http://127.0.0.1:18080
8.3 Session 匯出與分享
1# 匯出為 HTML
2agentsview session export <id>
3
4# 發佈為 GitHub Secret Gist（v0.32.0+）
5# 在 Web UI 中：Session viewer → Export → Publish as Gist
8.4 鍵盤導航（Web UI）
| 快捷鍵 | 功能 |
|---|---|
j / k | 上下移動 |
[ / ] | 前後 session |
Cmd+K | 搜尋 |
? | 顯示所有快捷鍵 |
8.5 PostgreSQL 背景 Service
Linux headless 環境需啟用 lingering：
1loginctl enable-linger "$USER"
2agentsview pg service install
3agentsview pg service status
8.6 開發者模式
1# 前端熱重載開發
2make frontend-dev
3
4# 後端 + 前端熱重載（需 air）
5make dev
6
7# 桌面應用開發
8make desktop-dev
9
10# 執行測試
11make test # 快速測試
12make test-postgres # PostgreSQL 整合測試
13make test-ssh # SSH 整合測試
9. 整合進其他工作流
9.1 與 AIKT Pipeline 整合
agentsview 可作為 AI-Knowledge Template 的監控層：
- Session 成本追蹤：追蹤各 research pipeline session 的 token 消耗
- Session 搜尋：快速找回過去 paper-tutorial / gh-tutorial-qd 的對話片段
- 團隊 Dashboard：研究團隊共享 PostgreSQL，統一查看 AI 工具使用狀況
1# 每日自動推送
2agentsview pg push --watch
3
4# 查看今日 AI 支出
5agentsview usage daily --breakdown --json | jq '.total_cost_usd'
9.2 與 Shell Script 整合
1# 成本超標警報
2COST=$(agentsview usage daily --json | jq -r '.total_cost_usd')
3if (( $(echo "$COST > 50" | bc -l) )); then
4 echo "WARNING: Daily AI cost exceeds $50: $COST" | notify
5fi
9.3 與 Claude Code Status Line 整合
1agentsview usage statusline
2# 輸出一行人類可讀的今日用量摘要
10. 重點摘要 Checklist
- 安裝 agentsview（curl / brew / docker）
- 執行
agentsview serve確認 Web UI 正常開啟 - 檢查 Session list 是否偵測到你使用的 agents
- 試跑
agentsview usage daily --breakdown了解費用分佈 - 執行
agentsview secrets掃描 session 中是否有 secret leak - （選用）設定 PostgreSQL 團隊同步
- （選用）設定 DuckDB 鏡像供分析
- （選用）設定 SSH port forwarding 遠端存取
- 保護設定檔：
chmod 600 ~/.agentsview/config.toml - （選用）停用 telemetry：
export AGENTSVIEW_TELEMETRY_ENABLED=0
11. 進一步閱讀
- 官方文件：agentsview.io
- Quick Start：agentsview.io/quickstart
- CLI Reference：agentsview.io/commands
- Configuration：agentsview.io/configuration
- Architecture：agentsview.io/architecture
- GitHub Repo：github.com/kenn-io/agentsview
- SECURITY.md：github.com/kenn-io/agentsview/blob/main/SECURITY.md
- Antigravity CLI decryption：github.com/mjacobs/agy-reader
Comments