@aicodewith/ccstatusline/README.md

AiCodeWith credits display plugin for Claude Code with customizable status line

# AiCodeWith CCStatusline

**🎯 Claude Code 专用 AI Code With 积分显示插件**

*在 Claude Code 终端实时显示 AI Code With 网站的月卡、加油包和今日消耗积分*

[![npm version](https://img.shields.io/npm/v/@aicodewith/ccstatusline.svg)](https://www.npmjs.com/package/@aicodewith/ccstatusline)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js Version](https://img.shields.io/node/v/@aicodewith/ccstatusline.svg)](https://nodejs.org)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-blue)](https://github.com)

简体中文 | [English](README_en.md)

## 📚 目录

- [功能特点](#-功能特点)
- [系统要求](#-系统要求)
- [快速开始](#-快速开始)
- [详细安装](#-详细安装)
- [配置说明](#-配置说明)
- [使用方法](#-使用方法)
- [故障排除](#-故障排除)
- [开发指南](#-开发指南)
- [更新日志](#-更新日志)
- [许可证](#-许可证)

---

## ✨ 功能特点

### 核心功能
- **🎯 实时积分显示** - 通过官方 API 获取 aicodewith.com 的完整账户信息
- **🔄 自动刷新** - 每30秒自动更新，无需手动干预
- **🔐 安全认证** - 使用 API 密钥认证，安全加密存储
- **💾 智能缓存** - 智能缓存机制，减少 API 请求
- **🎨 交互式 TUI** - 使用 React/Ink 构建的精美终端界面
- **⚡ 非阻塞更新** - 后台异步更新，不影响 Claude Code 性能
- **🔧 错误处理** - 完善的错误处理和清晰的状态提示
- **🌍 跨平台支持** - 支持 Windows、macOS 和 Linux

### 显示内容（通过 API 获取）
- **今日消耗** - 当天使用的积分数量
- **月卡剩余** - 月卡套餐剩余积分
- **月卡总额** - 月卡套餐总积分
- **加油包** - 额外购买的加油包积分
- **总积分** - 所有可用积分总和
- **使用率** - 月卡已使用百分比
- **剩余率** - 月卡剩余百分比
- **剩余天数** - 月卡到期剩余天数
- **到期时间** - 月卡具体到期时间
- **套餐类型** - 当前订阅的套餐类型（如：独享）
- **用户名** - 账户用户名
- **邮箱** - 账户邮箱地址

### 显示格式示例
```
今日消耗: 71500 | 月卡剩余: 0 | 月卡总额: 71500 | 加油包: 59880 | 总积分: 59880 | 使用率: 100.0% | 剩余率: 0.0% | 剩余: 0天 | 到期: 8/19 22:36 | 套餐: 独享 | 用户: 参宿四 | 邮箱: 1307398262@qq.com
```

### 额外 Claude Code 功能
- **📊 实时指标** - 模型名称、Git 分支、Token 使用量、会话时长
- **📐 多行支持** - 配置最多3个独立的状态行
- **🎨 颜色自定义** - 为每个元素自定义颜色
- **📏 智能宽度检测** - 自动适应终端宽度
- **⚙️ 全局选项** - 内边距、分隔符、粗体文本、背景色
- **🔤 自定义组件** - 添加自定义文本或执行 Shell 命令

---

## 📋 系统要求

- **Node.js** 14.0 或更高版本
- **npm** 或 **bun** 包管理器
- **API 访问** - AI Code With 官方 API 访问权限
- **AI Code With 账号** - 在 aicodewith.com 注册的有效账号
- **Claude Code CLI** - 已安装并配置

---

## 🚀 快速开始

## 🌟 无需安装，直接使用

> ### **一行命令，立即体验！**

```bash
npx @aicodewith/ccstatusline
```

✨ **就是这么简单！** 运行后将自动：
- 📦 下载最新版本
- 🔑 检测并获取 ANTHROPIC_AUTH_TOKEN 环境变量  
- 🎨 打开交互式 TUI 配置界面
- 📊 显示你的 AiCodeWith 积分信息
- ⚡ 自动测试 API 连接并保存配置

---

## 📦 安装方式

### 方式一：使用 npx（推荐）

```bash
npx @aicodewith/ccstatusline
```

### 方式二：全局安装

```bash
# 全局安装
npm install -g @aicodewith/ccstatusline

# 运行 TUI 配置界面
ccstatusline

# 或使用短命令
ccsl
```

### 方式三：从源码安装

#### 1. 克隆仓库

```bash
git clone https://github.com/XiaoYanKongLing/AiCodeWith-ccstatusline.git
cd AiCodeWith-ccstatusline
```

#### 2. 安装依赖

```bash
npm install
```

这将自动安装所有依赖。

如果你更喜欢使用 bun（速度更快）：
```bash
bun install
```

#### 3. 构建项目

```bash
npm run build
```

这将在 `dist` 目录生成编译后的文件。

#### 4. 配置 AI Code With 账号

运行配置工具：
```bash
node dist/ccstatusline.js
```

在 TUI 中：
1. 选择 **"🔑 Configure AI Code With Account"**
2. 输入 API 密钥（从 aicodewith.com 获取）
3. 按 **(t)** 测试连接
4. 按 **(s)** 保存配置

### 5. 安装到 Claude Code

在 TUI 主菜单中：
1. 选择 **"📦 Install to Claude Code"**
2. 确认安装

或手动编辑 `~/.claude/settings.json`：
```json
{
  "statusLine": {
    "type": "command",
    "command": "node \"/path/to/AiCodeWith-ccstatusline/dist/ccstatusline.js\"",
    "padding": 0
  }
}
```

---

## 📦 详细安装

### 安装步骤说明

#### 步骤 1：检查系统要求

验证 Node.js 安装：
```bash
node --version  # 应该是 v14.0.0 或更高
npm --version   # 应该是 v6.0.0 或更高
```

#### 步骤 2：下载和设置

```bash
# 克隆仓库
git clone https://github.com/XiaoYanKongLing/AiCodeWith-ccstatusline.git
cd AiCodeWith-ccstatusline

# 安装依赖
npm install

# 构建项目
npm run build
```

#### 步骤 3：配置

启动 TUI 配置界面：
```bash
node dist/ccstatusline.js
```

使用方向键导航并配置：
1. **Edit Lines** - 添加 AI Code With 积分显示
2. **Configure Colors** - 自定义外观
3. **AI Code With Account** - 设置凭据
4. **Install to Claude Code** - 与 Claude 集成

---

## ⚙️ 配置说明

### AI Code With API 配置

插件将 API 密钥安全存储在：
- **Windows**: `C:\Users\[用户名]\.config\ccstatusline\aicodewith\credentials.json`
- **macOS/Linux**: `~/.config/ccstatusline/aicodewith/credentials.json`

#### 获取 API 密钥

1. 登录 [aicodewith.com](https://aicodewith.com)
2. 进入账户设置页面
3. 找到 API 密钥部分
4. 复制你的 API 密钥

#### 手动配置

创建配置文件：
```json
{
  "apiKey": "你的API密钥"
}
```json
{
  "email": "your-email@example.com",
  "password": "base64编码的密码"
}
```

编码密码：
```bash
# Linux/macOS
echo -n "你的密码" | base64

# Windows PowerShell
[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("你的密码"))
```

### TUI 控制键

#### 主菜单
- **↑↓** - 导航菜单项
- **Enter** - 选择项目
- **Ctrl+C** - 退出

#### AI Code With 配置
- **(k)** - 编辑 API 密钥
- **(s)** - 保存凭据
- **(t)** - 测试连接
- **(c)** - 清除所有数据
- **ESC** - 返回

#### 行编辑器
- **↑↓** - 选择项目
- **←→** - 更改项目类型为 AI 积分选项
- **a** - 添加项目
- **d** - 删除项目
- **r** - 切换原始值模式
- **ESC** - 返回

### 配置文件

| 文件 | 用途 | 位置 |
|------|------|------|
| `settings.json` | 主配置 | `~/.config/ccstatusline/` |
| `credentials.json` | API 密钥配置 | `~/.config/ccstatusline/aicodewith/` |
| `full-data-cache.json` | 完整数据缓存 | `~/.config/ccstatusline/aicodewith/` | `~/.config/ccstatusline/aicodewith/` |
| `auth.json` | 认证状态 | `~/.config/ccstatusline/aicodewith/` |
| `debug.log` | 调试信息 | `~/.config/ccstatusline/aicodewith/` |

---

## 📖 使用方法

### 测试积分获取

直接测试状态栏显示：
```bash
echo '{"model":{"display_name":"Claude 3.5 Sonnet"}}' | node dist/ccstatusline.js
```

预期输出（完整数据）：
```
今日消耗: 71500 | 月卡剩余: 0 | 月卡总额: 71500 | 加油包: 59880 | 总积分: 59880 | 使用率: 100.0% | 剩余率: 0.0% | 剩余: 0天 | 到期: 8/19 22:36 | 套餐: 独享 | 用户: 参宿四 | 邮箱: 1307398262@qq.com
```

错误输出：
```
月卡: - | 加油包: - | 今日消耗: - (API错误)
月卡: - | 加油包: - | 今日消耗: - (网络错误)
月卡: - | 加油包: - | 今日消耗: - (离线)
```

### 测试完整状态栏

```bash
echo '{"model":{"display_name":"Claude 3.5 Sonnet"},"transcript_path":"test.jsonl"}' | node dist/ccstatusline.js
```

### 自动刷新机制

插件在以下条件下自动刷新积分，默认每30秒，可通过环境变量调整：
- Claude Code 在交互模式运行（TTY）
- 已配置有效凭据
- 网络连接可用

可配置的环境变量：
- CCSTATUSLINE_REFRESH_INTERVAL_MS：后台刷新间隔（毫秒），默认 30000。
- CCSTATUSLINE_API_TIMEOUT_MS：单次 API 请求超时（毫秒），默认 8000。
- CCSTATUSLINE_CREDITS_TTL_MS：进程内缓存 TTL，默认等于刷新间隔。

Windows PowerShell 示例：

  $env:CCSTATUSLINE_REFRESH_INTERVAL_MS = "30000"; $env:CCSTATUSLINE_API_TIMEOUT_MS = "8000"

bash 示例：

  export CCSTATUSLINE_REFRESH_INTERVAL_MS=30000; export CCSTATUSLINE_API_TIMEOUT_MS=8000

说明：刷新管理器的提示文本会动态显示当前配置的间隔，不再固定显示“每30秒”。

---

## 🔧 故障排除

### 常见问题和解决方案

#### 1. API 密钥错误
- 验证 credentials.json 中的 API 密钥是否正确
- 在 https://aicodewith.com 重新获取 API 密钥
- 清除认证缓存：`rm ~/.config/ccstatusline/aicodewith/auth.json`

#### 2. 网络错误
- 检查网络连接
- 验证是否能访问 https://aicodewith.com
- 如果在公司防火墙后，检查代理设置

#### 3. 积分不更新
- 检查调试日志：`cat ~/.config/ccstatusline/aicodewith/debug.log`
- 清除缓存：`rm ~/.config/ccstatusline/aicodewith/full-data-cache.json`
- 重启 Claude Code

#### 4. 进程挂起
- 终止所有卡住的 Node.js 进程
- 清除锁文件：`rm ~/.config/ccstatusline/aicodewith/refresh.lock`
- 重启终端

#### 5. 安装路径问题
- 确保在 Claude 设置中使用绝对路径
- 移动项目后重新构建：`npm run build`
- 验证 dist 文件存在：`ls dist/ccstatusline.js`

### 调试命令

查看调试日志：
```bash
# 查看最近的获取尝试
tail -f ~/.config/ccstatusline/aicodewith/debug.log

# 检查错误日志
cat ~/.config/ccstatusline/aicodewith/error.log

# 监控缓存更新
watch -n 1 cat ~/.config/ccstatusline/aicodewith/full-data-cache.json
```

清除所有数据：
```bash
# 清除所有缓存和日志
rm -rf ~/.config/ccstatusline/aicodewith/*.json
rm -rf ~/.config/ccstatusline/aicodewith/*.log
```

---

## 🛠️ 开发指南

### 项目结构

```
AiCodeWith-ccstatusline/
├── src/
│   ├── ccstatusline.ts         # 主入口点
│   ├── cli.js                  # CLI 包装器
│   ├── tui.tsx                 # React/Ink TUI 界面
│   ├── utils/
│   │   ├── config.ts           # 设置管理
│   │   ├── aicodewith.ts       # 积分显示逻辑
│   │   ├── claude-settings.ts  # Claude 集成
│   │   ├── renderer.ts         # 渲染器
│   │   └── aicodewith/
│   │       └── background-refresh.cjs   # 后台刷新脚本
├── dist/                        # 构建文件（生成）
├── patches/                     # Ink 补丁文件
├── screenshots/                 # 屏幕截图
├── package.json
├── tsconfig.json
├── build.cjs                    # 构建脚本
└── README.md                    # 本文件
```

### 开发命令

```bash
# 开发模式运行（TUI 模式）
bun run src/ccstatusline.ts

# 生产构建
npm run build

# 使用示例数据测试
echo '{"model":{"display_name":"Claude 3.5"}}' | bun run src/ccstatusline.ts

# 监控调试日志
tail -f ~/.config/ccstatusline/aicodewith/debug.log
```

### 关键实现细节

#### 自动刷新实现
```typescript
// 智能自动刷新检测
function shouldEnableAutoRefresh(): boolean {
    if (process.env.CCSTATUSLINE_AUTO_REFRESH === '0') return false;
    if (process.env.CCSTATUSLINE_AUTO_REFRESH === '1') return true;
    const hasTTY = Boolean(process.stdin?.isTTY) || Boolean(process.stdout?.isTTY);
    return hasTTY;
}

// 使用 unref() 的非阻塞定时器
refreshTimer = setInterval(() => {
    fetchCreditsSync();
}, CACHE_TTL_MS);
refreshTimer.unref(); // 不阻止进程退出
```

#### 进程锁机制
```typescript
// 防止并发获取
const lockPath = path.join(configDir, 'refresh.lock');
try {
    const fd = fs.openSync(lockPath, 'wx'); // 独占创建
    fs.closeSync(fd);
    // 继续获取
} catch {
    // 另一个进程正在获取
    return getCachedCredits();
}
```

#### 跨平台路径处理
```typescript
// 适用于 Windows、Linux 和 macOS
const configDir = path.join(
    process.env.HOME || process.env.USERPROFILE || '', 
    '.config', 
    'ccstatusline', 
    'aicodewith'
);
```

---

## 📝 更新日志

### v1.3.0 (2024-01)
- ✅ 完全集成自动刷新到主进程
- ✅ 修复安装路径硬编码问题
- ✅ 添加 TUI 标题自定义
- ✅ 修复颜色配置菜单缺失项
- ✅ 优化跨平台兼容性

### v1.2.0
- ✅ 修复错误信息不显示的问题
- ✅ 优化缓存策略，延长有效期到120秒
- ✅ 改进进程管理，避免挂起
- ✅ 完善错误处理机制

### v1.1.0
- 添加自动登录功能
- 支持密码加密存储
- 添加 TUI 配置界面

### v1.0.0
- 初始版本发布
- 基础积分显示功能

---

## 📮 相关链接

- **AI Code With 网站**: [https://aicodewith.com](https://aicodewith.com)
- **Claude Code 镜像站**: 本项目为 AI Code With 积分显示功能提供支持

---

<div align="center">

### 🌟 支持项目

如果这个项目帮助你显示 AI 积分，请给它一个 ⭐！

为 AI Code With 和 Claude Code 社区用 ❤️ 制作

</div>