# 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**: 2
- **Forks**: 1
- **Created**: 2026-04-16
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ACTrack

ACTrack 是一个面向 AI 编程工具的本地会话追踪与分析系统。它读取 Claude Code、OpenAI Codex、Cursor、OpenCode、Gemini、GitHub Copilot、Windsurf、Kiro、Qwen、QwenPaw、Hermes、OpenClaw、ZCode 等工具产生的本地会话数据，帮助用户查看 token 使用、费用估算、项目分布、模型分布、会话详情，并提供会话诊断、会话总结、记忆管理、技能管理和模型工具管理能力。

项目包含 Web 前端、FastAPI 后端、CLI 看板，以及 Electron / Tauri 两套桌面打包方案。

## 快速启动

安装依赖：

```bash
python -m venv .venv
.\.venv\Scripts\python -m pip install -r requirements.txt  # Windows
# .venv/bin/python -m pip install -r requirements.txt      # macOS / Linux

cd frontend
npm install
cd ..
```

启动开发环境：

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

也可以手动启动：

```bash
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 4121

cd frontend
npm run dev
```

默认访问地址：

| 服务 | 地址 |
| --- | --- |
| Web 前端 | `http://localhost:4120` |
| 后端 API | `http://localhost:4121` |
| API 文档 | `http://localhost:4121/docs` |
| 健康检查 | `http://localhost:4121/health` |

## AI Agent 规则入口

本项目为不同 AI IDE 提供同一套规则入口：

- `CLAUDE.md`
- `AGENTS.md`
- `.cursorrules`

规则入口只保留全局约束和任务路由，具体执行流程都在 `.docs/` 中。修改任意规则入口后，运行：

```bash
python scripts/sync_ai_rules.py --source CLAUDE.md
python scripts/sync_ai_rules.py --check
```

## 详细文档

| 文档 | 说明 |
| --- | --- |
| [CLAUDE.md](CLAUDE.md) | AI Agent 的主规则入口，说明不同任务应该先读哪些文档。 |
| [.docs/README.md](.docs/README.md) | `.docs` 分目录索引和归档说明。 |
| [.docs/operations/troubleshooting.md](.docs/operations/troubleshooting.md) | 系统报错、页面异常、接口失败时的排障流程。 |
| [.docs/operations/logging-observability.md](.docs/operations/logging-observability.md) | 日志体系、request_id、模块标签、级别约定和性能边界。 |
| [.docs/providers/onboarding.md](.docs/providers/onboarding.md) | 接入新的 AI IDE / Provider 的标准流程。 |
| [.docs/providers/ai-ide-capabilities.md](.docs/providers/ai-ide-capabilities.md) | 各 AI IDE 厂商 Skills、MCP、Memory、Hooks、会话数据和 CLI 能力索引。 |
| [.docs/token-accounting/debugging.md](.docs/token-accounting/debugging.md) | token 或费用计算不准时的四层对账流程。 |
| [.docs/token-accounting/details.md](.docs/token-accounting/details.md) | token 字段、Prompt 明细、Provider 口径和费用口径。 |
| [.docs/token-accounting/stats-overview.md](.docs/token-accounting/stats-overview.md) | 概览面板 token 统计、时间范围和趋势图逻辑。 |
| [.docs/architecture/technical-architecture.md](.docs/architecture/technical-architecture.md) | 系统架构、运行模式、Provider、缓存和关键数据流。 |
| [.docs/architecture/database-schema.md](.docs/architecture/database-schema.md) | SQLite 表结构、FTS5 索引、配置和历史记录。 |
| [.docs/frontend/design-system-v2.md](.docs/frontend/design-system-v2.md) | 前端设计系统和页面级 UI 规范。 |
| [.docs/analytics/session-evaluation.md](.docs/analytics/session-evaluation.md) | 会话质量评估、静态规则和 LLM 增强口径。 |
| [.docs/analytics/session-tools.md](.docs/analytics/session-tools.md) | 工具调用、MCP、Skill 分类和成功率口径。 |
| [.docs/desktop/electron-packaging.md](.docs/desktop/electron-packaging.md) | Electron 桌面应用打包流程。 |
| [.docs/desktop/electron-auto-update.md](.docs/desktop/electron-auto-update.md) | Electron GitHub Release 自动更新流程。 |
| [.docs/desktop/tauri-packaging.md](.docs/desktop/tauri-packaging.md) | Tauri 打包、签名和手动发布流程。 |
| [.docs/desktop/embedded-terminal.md](.docs/desktop/embedded-terminal.md) | 内嵌终端实现、IPC、安全边界和验证方式。 |

## 常用验证

```bash
python -m pytest

cd frontend
npm run type-check
npm run build
```