GNC 配置管理系统

集中管理 Claude Code 的多个配置文件，支持快速切换不同工作环境。

✨ 主要功能

配置管理: 快速切换多个 Claude 配置文件
工作区管理: 为不同项目创建独立工作区
实时通知: 基于 Claude Code hooks 的多渠道通知系统
Token 统计: 🆕 自动追踪和分析 Token 使用情况
预算监控: 🆕 设置使用限额，超限自动告警
Web 管理后台: 可视化管理界面

📁 目录结构

~/.gnc/
├── cli/                  # 🆕 Node.js CLI 工具（跨平台）
│   ├── src/             # 源代码
│   │   ├── index.mjs    # CLI 入口
│   │   ├── commands/    # 命令实现
│   │   ├── platform/    # 平台抽象层
│   │   ├── services/    # 业务服务
│   │   └── utils/       # 工具函数
│   └── dist/            # 构建输出
├── configs/              # 配置文件目录
│   ├── notify-hook.ps1       # Claude Code Hook Handler (含 Token 统计)
│   ├── system-toast.ps1      # 系统通知脚本
│   ├── desktop-toast.ps1     # 桌面弹窗脚本
│   ├── play-sound.ps1        # 声音播放脚本
│   └── ...                   # 其他脚本
├── sounds/               # 提示音目录（用户数据，不提交到 git）
│   └── README.txt
├── data/                 # 数据目录（用户数据，不提交到 git）
│   └── stats.db             # SQLite 备份数据库（已弃用）
├── web/                  # Web 管理后台
│   ├── server/             # Express 后端
│   │   ├── src/
│   │   │   ├── db/
│   │   │   │   ├── mysql.js        # MySQL 数据库模块
│   │   │   │   ├── pool.js         # MySQL 连接池
│   │   │   │   ├── schema/         # MySQL 表结构
│   │   │   │   └── migrate/        # 数据迁移工具
│   │   │   ├── routes/
│   │   │   │   ├── config.js       # 配置管理 API
│   │   │   │   ├── workspace.js    # 工作区 API
│   │   │   │   ├── notification.js # 通知 API
│   │   │   │   ├── stats.js        # 统计 API 🆕
│   │   │   │   └── budget.js       # 预算 API 🆕
│   │   │   ├── services/
│   │   │   │   ├── stats.js        # 统计服务 🆕
│   │   │   │   └── budget.js       # 预算服务 🆕
│   │   │   └── utils/
│   │   │       └── websocket.js    # WebSocket 服务
│   │   └── tests/
│   │       ├── notification.test.js
│   │       ├── stats.test.js       # 统计测试 🆕
│   │       ├── budget.test.js      # 预算测试 🆕
│   │       ├── stats-api.test.js   # 统计 API 测试 🆕
│   │       └── budget-api.test.js  # 预算 API 测试 🆕
│   └── client/             # Vue 3 前端
│       ├── src/
│       │   ├── views/
│       │   │   └── NotificationSettings.vue  # 通知设置页面
│       │   ├── components/
│       │   │   ├── NotificationToast.vue     # 通知 Toast 组件
│       │   │   ├── TokenStats.vue           # 统计页面 🆕
│       │   │   ├── BudgetManager.vue        # 预算管理页面 🆕
│       │   │   └── BudgetSummaryCard.vue    # 预算汇总卡片 🆕
│       │   ├── composables/
│       │   │   └── useWebSocket.js           # WebSocket 管理
│       │   ├── api/
│       │   │   └── notification.js           # 通知 API
│       │   └── router.js                    # 路由配置（含统计和预算路由）
│       └── dist/           # 构建产物
├── docs/                 # 文档目录
│   └── TESTING.md         # 测试指南 🆕
├── gnc.sh              # Bash 脚本
├── gnc.ps1             # PowerShell 脚本
├── default             # 当前默认配置名称
└── README.md           # 说明文档

🚀 快速开始

1. 安装

选项 A: Node.js CLI（跨平台，推荐）🆕

cd ~/.gnc
pnpm install
cd cli
pnpm build

# 使用（开发模式）
node cli/src/index.mjs list

# 使用（构建模式）
node cli/dist/gnc.js list

优点：

完全跨平台（Windows/Linux/macOS）
平台抽象层架构
可直接集成到现有 Node.js 项目

选项 B: PowerShell 脚本（Windows）

# 添加到 PowerShell 配置文件（如果还没配置）
Add-Content -Path $PROFILE -Value 'function gnc { & "$env:USERPROFILE\.gnc\gnc.ps1" @args }'

# 重新加载配置
. $PROFILE

Windows (Git Bash / MSYS)

# 添加到 PowerShell 配置文件（如果还没配置）
Add-Content -Path $PROFILE -Value 'function gnc { & "$env:USERPROFILE\.gnc\gnc.ps1" @args }'

# 重新加载配置
. $PROFILE

Windows (Git Bash / MSYS)

# 添加到 ~/.bashrc
echo 'alias gnc="bash ~/.gnc/gnc.sh"' >> ~/.bashrc

# 重新加载配置
source ~/.bashrc

2. 基本使用

# 查看所有可用配置
gnc list

# 使用指定配置启动
gnc glm-pro

# 设置默认配置
gnc use glm-pro

# 使用默认配置启动
gnc

🔔 通知系统

GNC 支持多渠道实时通知，基于 Claude Code hooks 自动推送通知。

支持的渠道

渠道	说明
系统通知	Windows 原生 Toast 通知
桌面弹窗	自定义 WPF 弹窗
Web 推送	Web 界面实时显示

支持的事件

事件	说明
用户发送消息	`user-prompt-submit`
工具开始执行	`tool-use-start`
工具执行完成	`tool-use-end`
Claude 通知	`notification`
任务完成	`stop`

启动 Web 管理后台

# 方式一：使用 gnc 命令（推荐）
gnc web

# 方式二：手动启动
cd ~/.gnc/web/server && npm start

启动后访问 http://localhost:3000 进入 Web 管理后台，可在"通知设置"页面配置通知行为。

数据库配置

Web 管理后台使用 MySQL 数据库存储数据。

环境变量

复制 web/server/.env.example 到 web/server/.env 并配置：

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=gnc_database

初始化

首次启动时会自动创建表结构。如需从旧版 SQLite 迁移数据：

cd web/server
node src/db/migrate/migrate-to-mysql.js ~/.gnc/data/gnc.db

配置 Claude Code Hooks

在 Claude Code 配置文件（~/.claude/settings.json 或项目级配置）中添加：

{
  "hooks": {
    "user-prompt-submit": "powershell -File \"$USERPROFILE\\.gnc\\scripts\\notify-hook.ps1\" -Event user-prompt-submit -Workspace \"$CLAUDE_WORKSPACE\"",
    "tool-use-start": "powershell -File \"$USERPROFILE\\.gnc\\scripts\\notify-hook.ps1\" -Event tool-use-start -Workspace \"$CLAUDE_WORKSPACE\"",
    "tool-use-end": "powershell -File \"$USERPROFILE\\.gnc\\scripts\\notify-hook.ps1\" -Event tool-use-end -Workspace \"$CLAUDE_WORKSPACE\"",
    "notification": "powershell -File \"$USERPROFILE\\.gnc\\scripts\\notify-hook.ps1\" -Event notification -Workspace \"$CLAUDE_WORKSPACE\" -Message \"$CLAUDE_NOTIFICATION\"",
    "stop": "powershell -File \"$USERPROFILE\\.gnc\\scripts\\notify-hook.ps1\" -Event stop -Workspace \"$CLAUDE_WORKSPACE\""
  }
}

安装 BurntToast（可选，推荐）

Install-Module -Name BurntToast -Scope CurrentUser -Force

📊 Token 使用统计与预算监控

GNC 新增 Token 使用统计和预算监控功能，自动追踪和分析 AI 模型的使用情况。

功能特性

功能	说明
自动统计	基于 hooks 自动记录每次对话的 Token 使用
趋势分析	按日/周/月查看使用趋势图表
配置对比	对比不同配置的使用情况
成本估算	自动计算预估费用
预算设置	为每个配置设置 Token 或费用限额
超限告警	使用量超过阈值时自动告警

Web 管理界面

启动 Web 服务后可访问：

统计页面: http://localhost:3000/stats
- 时间范围筛选（今天/本周/本月/自定义）
- 配置筛选
- 汇总卡片（总 Tokens、总费用、会话数）
- ECharts 趋势图表
- 详细使用记录列表
预算管理: http://localhost:3000/budgets
- 创建和管理预算设置
- 实时查看使用进度
- 查看活跃告警
- 启用/禁用预算

配置 Hooks 启用统计

在 Claude Code 配置中添加 session_end 事件 hook：

{
  "hooks": {
    "session_end": "powershell -File \"$USERPROFILE\\.gnc\\scripts\\notify-hook.ps1\" -Event session_end -Workspace \"$CLAUDE_WORKSPACE\" -ConfigName \"$CLAUDE_CONFIG\" -ModelName \"$CLAUDE_MODEL\" -InputTokens $CLAUDE_INPUT_TOKENS -OutputTokens $CLAUDE_OUTPUT_TOKENS -TotalTokens $CLAUDE_TOTAL_TOKENS -EstimatedCost $CLAUDE_ESTIMATED_COST -SessionId \"$CLAUDE_SESSION_ID\""
  }
}

预算设置示例

通过 Web 界面或 API 设置预算：

{
  "config_name": "glm-pro",
  "period": "daily",
  "token_limit": 100000,
  "cost_limit": 1.0,
  "alert_threshold": 0.8
}

period: 统计周期（daily/weekly/monthly）
token_limit: Token 使用上限
cost_limit: 费用上限（美元）
alert_threshold: 告警阈值（0-1，默认 0.8 即 80%）

数据存储

统计数据存储在本地 SQLite 数据库：

~/.gnc/data/stats.db

包含三张表：

token_usage: 原始使用记录
daily_stats: 每日汇总统计
budget_settings: 预算配置

API 接口

统计 API

# 记录使用
POST /api/stats/record
{
  "workspace_id": "my-project",
  "config_name": "glm-pro",
  "model_name": "glm-4.7",
  "input_tokens": 1000,
  "output_tokens": 500,
  "total_tokens": 1500,
  "event_type": "session_end"
}

# 获取汇总
GET /api/stats/summary?days=30

# 获取趋势
GET /api/stats/trend?granularity=daily&days=7

# 获取记录
GET /api/stats/records?limit=100

预算 API

# 创建预算
POST /api/budgets
{
  "config_name": "glm-pro",
  "period": "daily",
  "token_limit": 100000,
  "cost_limit": 1.0
}

# 获取所有预算
GET /api/budgets

# 检查预算状态
GET /api/budgets/glm-pro/check

# 检查所有预算
GET /api/budgets/check/all

# 更新预算
PUT /api/budgets/glm-pro

# 删除预算
DELETE /api/budgets/glm-pro

详细测试指南请参考 TESTING.md

📖 命令详解

命令	说明
`gnc`	使用默认配置启动 Claude
`gnc <配置名>`	使用指定配置启动 Claude
`gnc list`	列出所有可用配置
`gnc use <配置名>`	设置默认配置
`gnc help`	显示帮助信息

💡 工作流程

配置切换流程

查看可用配置：gnc list
临时使用配置：gnc glm-pro
设置默认配置：gnc use glm-pro
使用默认配置：直接 gnc

通知系统工作流程

启动 Web 服务：gnc web
配置通知行为：在 Web 界面"通知设置"页面
配置 Claude Code hooks：在配置文件中添加 hooks
开始使用：Claude Code 事件触发时自动收到通知

🔧 添加自定义配置

在 ~/.gnc/configs/ 目录下创建新的 JSON 文件：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "your-model-name",
  "appendSystemPrompt": "Your custom prompt",
  "env": {
    "CLAUDE_CONFIG": "your-config-name"
  }
}

然后使用 gnc your-config-name 即可。

📋 可用配置

glm (默认)

使用智谱 AI 的 GLM 模型

glm-pro

使用智谱 AI 的 GLM-Pro 模型

default

使用 Anthropic 的 Claude Sonnet 模型

🎯 最佳实践

为不同场景配置不同环境：如 glm 用于日常开发，glm-pro 用于复杂任务
设置常用配置为默认：使用 gnc use 命令
配置命名规范：使用有意义的名称，如 backend, frontend, mobile 等

🔄 默认配置管理

默认配置保存在 ~/.gnc/default 文件中：

# 查看当前默认配置
cat ~/.gnc/default

# 修改默认配置
gnc use glm-pro

Name		Name	Last commit message	Last commit date
Latest commit History 240 Commits
cli		cli
docs		docs
hooks		hooks
sounds		sounds
web		web
.gitignore		.gitignore
README.md		README.md
package.json		package.json
pnpm-workspace.yaml		pnpm-workspace.yaml

Folders and files

Latest commit

History

Repository files navigation

GNC 配置管理系统

✨ 主要功能

📁 目录结构

🚀 快速开始

1. 安装

选项 A: Node.js CLI（跨平台，推荐）🆕

选项 B: PowerShell 脚本（Windows）

Windows (Git Bash / MSYS)

Windows (Git Bash / MSYS)

2. 基本使用

🔔 通知系统

支持的渠道

支持的事件

启动 Web 管理后台

数据库配置

环境变量

初始化

配置 Claude Code Hooks

安装 BurntToast（可选，推荐）

📊 Token 使用统计与预算监控

功能特性

Web 管理界面

配置 Hooks 启用统计

预算设置示例

数据存储

API 接口

统计 API

预算 API

📖 命令详解

💡 工作流程

配置切换流程

通知系统工作流程

🔧 添加自定义配置

📋 可用配置

glm (默认)

glm-pro

default

🎯 最佳实践

🔄 默认配置管理

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages