# actrack

**Repository Path**: yysimple/actrack

## Basic Information

- **Project Name**: actrack
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-04-16
- **Last Updated**: 2026-05-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ACTrack

ACTrack 是一个面向 AI 编码工具的本地会话追踪、统计分析和记忆管理系统。它读取 Claude Code、OpenAI Codex、Cursor 的本地会话数据，提供 Web 仪表盘、CLI 看板、FastAPI 接口，以及可打包的 Electron 桌面应用。

## 当前开发端口

| 服务 | 地址 | 来源 |
|------|------|------|
| Web 前端 | `http://localhost:4120` | `frontend/vite.config.ts` |
| 后端 API | `http://localhost:4121` | `app/main.py` / `backend-entry.py` |
| API 文档 | `http://localhost:4121/docs` | FastAPI Swagger |
| 健康检查 | `http://localhost:4121/health` | FastAPI |

前端开发环境使用相对 API 地址 `/api`，由 Vite 代理到 `http://localhost:4121`。Electron 生产模式下后端由 `backend-entry.py` 动态分配本机端口，前端通过 preload 暴露的 `window.actrackAPI` 获取实际地址。

## 功能概览

- 多数据源会话读取：Claude Code、OpenAI Codex、Cursor。
- 使用统计：会话数、token、成本、模型、项目、任务类型。
- 会话浏览：列表过滤、详情查看、图片代理、本地文件定位。
- 会话评估与总结：基于 LLM 的单会话诊断、多会话总结，支持 SSE 流式输出。
- 记忆管理：记忆 CRUD、版本回滚、全文搜索、语义搜索、同步管理。
- 技能库：技能元数据管理、YAML 持久化、导出到 Claude。
- 桌面应用：Electron + PyInstaller，生产后端使用动态端口。

## 技术栈

| 层 | 技术 |
|----|------|
| 后端 | Python 3.13、FastAPI、Uvicorn、Pydantic |
| 数据 | SQLite + FTS5、YAML、可选 ChromaDB |
| 后台任务 | Watchdog 文件监听、asyncio 定时缓存刷新 |
| CLI | Typer、Rich |
| 前端 | Vue 3、TypeScript、Vite、Element Plus、ECharts、Pinia、Vue Router |
| 桌面 | Electron、electron-builder、PyInstaller |

## 目录结构

```text
actrack/
├── actrack                     # CLI 入口脚本
├── app/                        # FastAPI 后端
│   ├── main.py                 # 后端应用入口，开发端口 4121
│   ├── api/                    # 会话统计、缓存、导出接口
│   ├── core/                   # Claude/Codex/Cursor Provider
│   ├── memory/                 # 记忆、技能、同步、诊断、总结接口
│   ├── services/               # 缓存与统计服务
│   └── cli/                    # Typer/Rich CLI
├── frontend/                   # Vue 前端，开发端口 4120
│   ├── src/
│   │   ├── App.vue             # 主布局与导航
│   │   ├── router/index.ts     # 前端路由
│   │   ├── services/api.ts     # Axios API 封装
│   │   └── views/              # 页面组件
│   └── vite.config.ts          # Vite 端口和 /api 代理
├── electron/                   # Electron 主进程与 preload
├── scripts/                    # 构建和辅助脚本
├── tests/                      # pytest 测试
├── .docs/                      # 项目文档
├── backend-entry.py            # Electron 后端入口
├── package.bat / package.sh    # 桌面应用打包脚本
├── start.bat / start.sh        # 开发环境一键启动脚本
└── requirements.txt            # Python 依赖
```

## 环境要求

- Python 3.13+
- Node.js `^20.19.0` 或 `>=22.12.0`
- npm

## 安装依赖

```bash
# Python
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Frontend
cd frontend
npm install
cd ..
```

## 启动开发环境

一键启动：

```bash
./start.sh       # macOS / Linux / Git Bash
start.bat        # Windows
```

手动启动：

```bash
# 终端 1：后端
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 4121

# 终端 2：前端
cd frontend
npm run dev
```

启动后访问：

- 前端：`http://localhost:4120`
- API 文档：`http://localhost:4121/docs`
- 健康检查：`http://localhost:4121/health`

## CLI

```bash
./actrack                       # 默认打开周视角报告
./actrack report --period today
./actrack status
./actrack today --refresh 5
./actrack month
./actrack export -f csv
./actrack providers
```

## 前端页面

| 路由 | 页面 | 说明 |
|------|------|------|
| `/` | 数据看板 | 统计卡片、趋势和分布 |
| `/conversations` | 会话记录 | 会话列表、过滤、详情 |
| `/diagnostic` / `/diagnostic/:sessionId` | 会话评估 | 单会话 LLM 诊断 |
| `/session-summary` | 会话总结 | 多会话总结生成与历史 |
| `/memory` | 记忆管理 | 记忆 CRUD、搜索、版本 |
| `/memory-package` | 记忆包 | 多会话记忆包生成 |
| `/skills` | 技能库 | 技能列表与管理 |
| `/skills/editor` | 技能编辑器 | 技能 YAML/元数据编辑 |
| `/sync` | 同步管理 | 查看和管理同步产物 |
| `/settings` | 系统设置 | LLM 配置、模块开关、日志 |

## 常用 API

所有业务 API 都挂载在 `/api` 下。

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/dashboard` | 仪表盘数据 |
| GET | `/api/stats/{period}` | 指定时间段统计 |
| GET | `/api/conversations` | 会话列表 |
| GET | `/api/conversations/{session_id}` | 会话详情 |
| POST | `/api/cache/refresh` | 手动刷新缓存 |
| GET | `/api/cache/status` | 缓存状态 |
| GET | `/api/memories` | 记忆列表 |
| POST | `/api/memories` | 创建记忆 |
| GET | `/api/search` | 全文搜索 |
| GET | `/api/search/semantic` | 语义搜索 |
| GET | `/api/search/hybrid` | 混合搜索 |
| GET | `/api/skills` | 技能列表 |
| POST | `/api/sync/push` | 推送到同步目标 |
| GET | `/api/sync/status` | 同步状态 |
| POST | `/api/memory-package/generate-stream` | 流式生成记忆包 |
| GET | `/api/diagnose-session/{session_id}` | 单会话诊断 |
| POST | `/api/diagnose-session/{session_id}/stream` | 流式诊断 |
| POST | `/api/session-summary/generate-stream` | 流式生成会话总结 |
| GET | `/api/settings/llm` | LLM 配置 |
| POST | `/api/settings/llm` | 保存 LLM 配置 |
| GET | `/api/settings/system` | 系统配置 |
| POST | `/api/settings/system` | 保存系统配置 |

完整接口以运行时 Swagger 为准：`http://localhost:4121/docs`。

## 数据位置

| 数据 | 默认位置 |
|------|----------|
| ACTrack 数据目录 | `~/.actrack/`，可用 `ACTRACK_DATA_DIR` 覆盖 |
| SQLite 数据库 | `~/.actrack/memory.db` |
| 技能 YAML | `~/.actrack/skills/` |
| 记忆版本 | `~/.actrack/versions/` |
| 向量库 | `~/.actrack/chroma/` |
| 日志 | `~/.actrack/logs/` |
| Claude Code 数据源 | `~/.claude/projects/` |
| OpenAI Codex 数据源 | `~/.codex/sessions/` |
| Cursor 数据源 | 平台默认 Cursor 用户数据目录 |

## 桌面打包

```bash
./package.sh      # macOS / Linux / Git Bash
package.bat       # Windows
```

打包流程分三步：

1. `frontend` 使用 `VITE_ELECTRON=1 npm run build` 构建相对路径静态资源。
2. PyInstaller 使用 `pyinstaller.spec` 构建 `actrack-backend`。
3. Electron Builder 将 `frontend/dist` 和后端可执行文件打包为桌面应用。

开发 Electron：

```bash
cd electron
npm install
npm run electron:dev
```

Electron 开发模式依赖 `http://localhost:4120` 的 Vite 服务；生产模式从本地文件加载前端，并由后端动态端口提供 API。

## 相关文档

- [.docs/技术架构.md](.docs/技术架构.md)
- [.docs/数据库表结构.md](.docs/数据库表结构.md)
- [.docs/desktop-packaging.md](.docs/desktop-packaging.md)