stepfun-status 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jochen Yang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# stepfun-status
+
+> StepFun Token-Plan 使用状态监控工具，支持 Claude Code 状态栏常驻显示。
+
+[![npm version](https://img.shields.io/npm/v/stepfun-status)](https://www.npmjs.com/package/stepfun-status)
+[![Node >=16](https://img.shields.io/node/v/stepfun-status)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## 效果预览
+
+Claude Code 底部状态栏：
+
+```
+my-app │ main │ step-3.5-flash │ ██████░░░░ 60% (40/100) │ ⏱ 1h30m │ W ███░░ 58% │ 到期 12天
+```
+
+终端详细视图：
+
+```
+┌──────────────────────────────────────────────┐
+│ StepFun Claude Code 使用状态                  │
+│                                               │
+│ 当前模型: step-3.5-flash                      │
+│ 套餐:     Mini                                │
+│                                               │
+│ 5小时用量: ██████████████████░░░░░░░░░░ 60%  │
+│      剩余: 40%                                │
+│      重置: 1 小时 30 分钟后重置               │
+│                                               │
+│ 每周用量: ████████░░░░░░░ 58%                 │
+│     剩余: 42%                                 │
+│     重置: 3 小时 12 分钟后重置                │
+│                                               │
+│ 套餐到期: 2025/6/1 00:00:00 (还剩 12 天)      │
+│                                               │
+│ 状态: ⚡ 注意使用                             │
+└──────────────────────────────────────────────┘
+```
+
+## 安装
+
+```bash
+npm install -g stepfun-status
+```
+
+## 快速开始
+
+### 1. 获取 Cookie 并认证
+
+运行下方命令，会自动打印获取步骤：
+
+```bash
+stepfun auth
+```
+
+按提示操作：
+1. 登录 [https://platform.stepfun.com](https://platform.stepfun.com)
+2. F12 → Network 标签 → 刷新页面
+3. 点击任意 API 请求（如 `GetStepPlanStatus`）
+4. 滚动到 Request Headers → 找到 `Cookie` 行
+5. **右键 → Copy value**（必须用此方式，直接框选会截断）
+6. 粘贴到终端并回车
+
+> **提示**：Cookie 较长，建议使用交互式 `stepfun auth`（无参数），避免命令行参数截断问题。
+
+### 2. 验证连接
+
+```bash
+stepfun health
+```
+
+### 3. 查看状态
+
+```bash
+stepfun status
+```
+
+## Claude Code 状态栏集成
+
+### 配置
+
+编辑 `~/.claude/settings.json`，添加：
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "stepfun statusline"
+  }
+}
+```
+
+重启 Claude Code 后生效。
+
+
+### 状态栏格式
+
+```
+目录 │ 分支 │ 模型 │ 5小时用量进度条(剩余) │ ⏱ 倒计时 │ W 周用量 │ 到期天数
+```
+
+**颜色说明**：
+
+| 指标 | 绿色 | 黄色 | 红色 |
+|------|------|------|------|
+| 用量 | < 60% | 60–85% | ≥ 85% |
+| 到期 | > 7 天 | ≤ 7 天 | ≤ 3 天 |
+| 分支 | main/master | — | 有未提交改动（`*`） |
+
+## 命令参考
+
+| 命令 | 选项 | 说明 |
+|------|------|------|
+| `stepfun auth [cookie]` | — | 设置认证 Cookie（推荐无参数交互式输入） |
+| `stepfun health` | — | 检查配置文件、Cookie 和 API 连通性 |
+| `stepfun status` | — | 详细模式显示当前使用状态 |
+| `stepfun status` | `-c, --compact` | 紧凑单行模式 |
+| `stepfun status` | `-w, --watch` | 实时监控，每 10 秒刷新 |
+| `stepfun status` | `-c -w` | 紧凑模式 + 实时监控 |
+| `stepfun statusline` | — | 输出状态行（供 Claude Code 调用） |
+| `stepfun statusline` | `-w, --watch` | 持续刷新状态行输出 |
+
+## 配置文件
+
+| 项目 | 说明 |
+|------|------|
+| 路径 | `~/.stepfun-config.json` |
+| 内容 | `{ "cookie": "..." }` |
+| 权限 | Unix/Mac 下自动设置为 `0600`（仅所有者可读写） |
+
+> **Windows 注意**：不支持 Unix 文件权限位，Cookie 以明文存储，请妥善保管配置文件，避免他人访问。
+
+> **macOS / Linux**：配置文件权限已自动设为 `0600`，只有当前用户可读写，无需额外操作。
+
+## 常见问题
+
+**Q: 状态栏显示 ❌**
+A: Cookie 未配置或已过期，运行 `stepfun health` 诊断，再用 `stepfun auth` 重新设置。
+
+**Q: Cookie 粘贴后提示"不能为空"**
+A: 可能复制到了空内容，请确保在 Network 面板使用"右键 → Copy value"而非框选复制。
+
+**Q: 状态栏不显示**
+A: 确认 `~/.claude/settings.json` 中 `statusLine.command` 为 `stepfun statusline`，且 `stepfun-status` 已全局安装（`npm install -g stepfun-status`）。
+
+**Q: macOS / Linux 上 `stepfun` 命令找不到**
+A: 确认 npm 全局 bin 目录已加入 `PATH`。可运行 `npm bin -g` 查看路径，并将其添加到 `~/.zshrc` 或 `~/.bashrc`：
+```bash
+export PATH="$(npm bin -g):$PATH"
+```
+
+## 开发
+
+```bash
+git clone https://github.com/Daiyimo/stepfun-status.git
+cd stepfun-status
+npm install
+npm link          # 本地全局链接，方便调试
+
+npm start         # 查看当前状态
+npm test          # 检查连通性
+npm run lint      # 语法检查
+```
+
+## 许可证
+
+[MIT](LICENSE)
+
+## 相关链接
+
+- [StepFun 开放平台](https://platform.stepfun.com)
+- [StepFun 接口密钥](https://platform.stepfun.com/interface-key)
+- [StepFun 订阅情况](https://platform.stepfun.com/plan-subscribe)
+- [StepFun 接入指南](https://platform.stepfun.com/docs/zh/step-plan/integrations)

package/cli/api.js

@@ -0,0 +1,345 @@
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+// ─── 常量 ─────────────────────────────────────────────────────────────────────
+
+const STEPFUN_HOST = "platform.stepfun.com";
+const STEPFUN_ORIGIN = `https://${STEPFUN_HOST}`;
+
+const CONFIG = {
+  CACHE_TIMEOUT: 30000,       // 缓存超时：30 秒
+  REQUEST_TIMEOUT: 8000,      // 网络请求超时：8 秒
+  CONFIG_FILENAME: ".stepfun-config.json",
+};
+
+// ─── 跨平台 User-Agent ────────────────────────────────────────────────────────
+
+/**
+ * 根据当前操作系统返回对应的浏览器 User-Agent 字符串，
+ * 避免 macOS/Linux 下使用 Windows UA 被服务端检测。
+ */
+function getPlatformUserAgent() {
+  const platform = os.platform();
+  if (platform === "darwin") {
+    return "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36";
+  }
+  if (platform === "linux") {
+    return "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36";
+  }
+  // Windows（默认）
+  return "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36";
+}
+
+// 配置文件路径（模块级常量，供外部共享，避免各处重复计算）
+const CONFIG_PATH = path.join(
+  process.env.HOME || process.env.USERPROFILE,
+  CONFIG.CONFIG_FILENAME
+);
+
+// ─── 模块级纯函数（提升出 parseUsageData，避免每次调用重新创建） ──────────────
+
+/**
+ * 将 Unix 时间戳转换为剩余时间对象
+ * @param {string|number|null} timestamp  Unix 秒级时间戳
+ * @returns {{ ts: number, date: string, hoursUntil: number, minutesUntil: number } | null}
+ */
+function formatResetTime(timestamp) {
+  if (!timestamp) return null;
+  const ts = parseInt(timestamp, 10);
+  const date = new Date(ts * 1000);
+  const diffMs = date.getTime() - Date.now();
+  return {
+    ts,
+    date: date.toLocaleString(),
+    hoursUntil: Math.max(0, Math.floor(diffMs / (1000 * 60 * 60))),
+    minutesUntil: Math.max(0, Math.floor((diffMs % (1000 * 60 * 60)) / (1000 * 60))),
+  };
+}
+
+/**
+ * 将剩余时间对象格式化为可读文本
+ * @param {{ hoursUntil: number, minutesUntil: number } | null} resetInfo
+ * @returns {string}
+ */
+function calcRemainingText(resetInfo) {
+  if (!resetInfo) return "未知";
+  const { hoursUntil, minutesUntil } = resetInfo;
+  return hoursUntil > 0
+    ? `${hoursUntil} 小时 ${minutesUntil} 分钟后重置`
+    : `${minutesUntil} 分钟后重置`;
+}
+
+// ─── StepFunAPI 类 ────────────────────────────────────────────────────────────
+
+class StepFunAPI {
+  constructor() {
+    this.cookie = null;
+    this.cache = {
+      statusData: null,
+      quotaData: null,
+      statusTimestamp: 0,
+      quotaTimestamp: 0,
+    };
+    this.loadConfig();
+  }
+
+  /** 是否已配置凭据 */
+  isAuthenticated() {
+    return Boolean(this.cookie);
+  }
+
+  loadConfig() {
+    try {
+      if (fs.existsSync(CONFIG_PATH)) {
+        const config = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+        this.cookie = config.cookie || null;
+      }
+    } catch (error) {
+      console.error("Failed to load config:", error.message);
+    }
+  }
+
+  saveConfig() {
+    try {
+      const config = { cookie: this.cookie };
+      // 0o600：仅所有者可读写，在 Unix/Mac 上防止其他用户读取 Cookie
+      fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
+    } catch (error) {
+      console.error("Failed to save config:", error.message);
+    }
+  }
+
+  setCredentials(cookie) {
+    if (!cookie || typeof cookie !== "string" || !cookie.trim()) {
+      throw new Error("Cookie 不能为空");
+    }
+    this.cookie = cookie.trim();
+    this.saveConfig();
+  }
+
+  /** 从 Cookie 字符串中提取指定字段 */
+  extractFromCookie() {
+    if (!this.cookie) return { oasisWebid: null };
+
+    const cookies = {};
+    this.cookie.split(/;\s*/).forEach((c) => {
+      const idx = c.indexOf("=");
+      if (idx === -1) return;
+      const key = c.slice(0, idx).trim();
+      const val = c.slice(idx + 1);
+      if (!key) return;
+      try {
+        cookies[key] = decodeURIComponent(val);
+      } catch {
+        cookies[key] = val;
+      }
+    });
+
+    return { oasisWebid: cookies["Oasis-Webid"] || null };
+  }
+
+  async makePlatformRequest(endpoint, data = {}) {
+    if (!this.cookie) {
+      throw new Error(
+        'Missing cookie. Please run "stepfun auth <cookie>" first.\n' +
+          "获取方式:\n" +
+          "1. 登录 https://platform.stepfun.com\n" +
+          "2. F12 -> Network -> 刷新页面\n" +
+          "3. 点击任意 API 请求 -> Copy -> Copy request headers -> 复制 Cookie 行"
+      );
+    }
+
+    const { oasisWebid } = this.extractFromCookie();
+    const postData = JSON.stringify(data);
+
+    const headers = {
+      accept: "*/*",
+      "content-type": "application/json",
+      "oasis-appid": "10300",
+      "oasis-platform": "web",
+      "oasis-webid": oasisWebid || "",
+      origin: STEPFUN_ORIGIN,
+      referer: `${STEPFUN_ORIGIN}/plan-subscribe`,
+      "user-agent": getPlatformUserAgent(),
+      "content-length": Buffer.byteLength(postData),
+      Cookie: this.cookie,
+    };
+
+    return new Promise((resolve, reject) => {
+      const req = https.request(
+        {
+          hostname: STEPFUN_HOST,   // 与 STEPFUN_ORIGIN 保持同一数据源
+          port: 443,
+          path: endpoint,
+          method: "POST",
+          headers,
+          rejectUnauthorized: true, // 显式启用 SSL 证书验证
+        },
+        (res) => {
+          let body = "";
+          res.on("data", (chunk) => { body += chunk; });
+          res.on("end", () => {
+            if (res.statusCode === 200) {
+              try {
+                resolve(JSON.parse(body));
+              } catch {
+                reject(new Error("Failed to parse response: invalid JSON"));
+              }
+            } else if (res.statusCode === 401) {
+              reject(new Error("Cookie 已失效或过期，请重新运行 auth 命令"));
+            } else {
+              reject(new Error(`API error: HTTP ${res.statusCode}`));
+            }
+          });
+        }
+      );
+
+      // 超时保护
+      req.setTimeout(CONFIG.REQUEST_TIMEOUT, () => {
+        req.destroy();
+        reject(new Error(`Request timeout after ${CONFIG.REQUEST_TIMEOUT / 1000}s`));
+      });
+
+      req.on("error", (e) => {
+        reject(new Error(`Network error: ${e.message}`));
+      });
+
+      req.write(postData);
+      req.end();
+    });
+  }
+
+  /**
+   * 带缓存的请求封装，消除 getSubscriptionStatus / getQuotaInfo 的重复逻辑
+   * @param {'statusData'|'quotaData'} dataKey       缓存数据字段名
+   * @param {'statusTimestamp'|'quotaTimestamp'} tsKey 缓存时间戳字段名
+   * @param {string} endpoint                         API 路径
+   * @param {boolean} forceRefresh                    是否强制跳过缓存
+   */
+  async _cachedRequest(dataKey, tsKey, endpoint, forceRefresh) {
+    const now = Date.now();
+    if (
+      !forceRefresh &&
+      this.cache[dataKey] &&
+      now - this.cache[tsKey] < CONFIG.CACHE_TIMEOUT
+    ) {
+      return this.cache[dataKey];
+    }
+    const data = await this.makePlatformRequest(endpoint);
+    this.cache[dataKey] = data;
+    this.cache[tsKey] = now;
+    return data;
+  }
+
+  async getSubscriptionStatus(forceRefresh = false) {
+    return this._cachedRequest(
+      "statusData",
+      "statusTimestamp",
+      "/api/step.openapi.devcenter.Dashboard/GetStepPlanStatus",
+      forceRefresh
+    );
+  }
+
+  async getQuotaInfo(forceRefresh = false) {
+    return this._cachedRequest(
+      "quotaData",
+      "quotaTimestamp",
+      "/api/step.openapi.devcenter.Dashboard/QueryStepPlanRateLimit",
+      forceRefresh
+    );
+  }
+
+  // ── 预留扩展区 ──────────────────────────────────────────────────────────────
+  // 后续新增接口时，只需：
+  //   1. 在 this.cache 里加对应的 data/timestamp 字段
+  //   2. 仿照下方模板写一个 get 方法
+  //   3. 在 getUsageStatus / parseUsageData 里消费新数据
+  //
+  // 模板（等 Token 用量明细接口开放后接入）：
+  //
+  // async getTokenUsage(forceRefresh = false) {
+  //   return this._cachedRequest(
+  //     "tokenData",
+  //     "tokenTimestamp",
+  //     "/api/step.openapi.devcenter.Dashboard/QueryTokenUsage",  // 待确认
+  //     forceRefresh
+  //   );
+  // }
+  // ────────────────────────────────────────────────────────────────────────────
+
+  async getUsageStatus(forceRefresh = false) {
+    const [statusData, quotaData] = await Promise.all([
+      this.getSubscriptionStatus(forceRefresh),
+      this.getQuotaInfo(forceRefresh),
+    ]);
+    return this.parseUsageData(statusData, quotaData);
+  }
+
+  parseUsageData(statusData, quotaData) {
+    const subscription = statusData.subscription || {};
+    const planDefinition = statusData.plan_definition || {};
+
+    const fiveHourLeftRate = quotaData.five_hour_usage_left_rate || 0;
+    const weeklyLeftRate = quotaData.weekly_usage_left_rate || 0;
+
+    const fiveHourUsedPercent = Math.round((1 - fiveHourLeftRate) * 100);
+    const weeklyUsedPercent = Math.round((1 - weeklyLeftRate) * 100);
+
+    const fiveHourReset = formatResetTime(quotaData.five_hour_usage_reset_time);
+    const weeklyReset = formatResetTime(quotaData.weekly_usage_reset_time);
+
+    let expiry = null;
+    if (subscription.expired_at) {
+      const expiryDate = new Date(parseInt(subscription.expired_at, 10) * 1000);
+      const daysRemaining = Math.ceil(
+        (expiryDate.getTime() - Date.now()) / (1000 * 3600 * 24)
+      );
+      expiry = {
+        date: expiryDate.toLocaleString(),
+        daysRemaining,
+        text:
+          daysRemaining > 0
+            ? `还剩 ${daysRemaining} 天`
+            : daysRemaining === 0
+            ? "今天到期"
+            : `已过期 ${Math.abs(daysRemaining)} 天`,
+      };
+    }
+
+    return {
+      modelName: planDefinition.support_models?.[0] || "step-3.5-flash",
+      planName: subscription.name || "Mini",
+      remaining: {
+        hours: fiveHourReset?.hoursUntil || 0,
+        minutes: fiveHourReset?.minutesUntil || 0,
+        text: calcRemainingText(fiveHourReset),
+      },
+      usage: {
+        percentage: fiveHourUsedPercent,
+        remaining: Math.round(fiveHourLeftRate * 100),
+      },
+      weekly: {
+        percentage: weeklyUsedPercent,
+        remaining: Math.round(weeklyLeftRate * 100),
+        text: calcRemainingText(weeklyReset),
+        daysUntilReset: weeklyReset?.hoursUntil
+          ? Math.floor(weeklyReset.hoursUntil / 24)
+          : 0,
+      },
+      expiry,
+    };
+  }
+
+  clearCache() {
+    this.cache = {
+      statusData: null,
+      quotaData: null,
+      statusTimestamp: 0,
+      quotaTimestamp: 0,
+    };
+  }
+}
+
+module.exports = { StepFunAPI, CONFIG_PATH };

package/cli/index.js

@@ -0,0 +1,415 @@
+#!/usr/bin/env node
+
+// Force color output even in non-TTY environments (e.g., Claude Code statusline)
+process.env.FORCE_COLOR = "1";
+
+const { execSync } = require("child_process");
+const { Command } = require("commander");
+const chalk = require("chalk").default;
+const ora = require("ora").default;
+const { default: boxen } = require("boxen");
+const { StepFunAPI, CONFIG_PATH } = require("./api");
+const packageJson = require("../package.json");
+const fs = require("fs");
+
+// ─── 全局错误兜底 ─────────────────────────────────────────────────────────────
+process.on("uncaughtException", (error) => {
+  console.error(chalk.red("💥 未捕获的错误:"), error.message);
+  process.exit(1);
+});
+
+process.on("unhandledRejection", (reason) => {
+  console.error(
+    chalk.red("💥 未处理的 Promise 错误:"),
+    reason instanceof Error ? reason.message : reason
+  );
+  process.exit(1);
+});
+
+// ─── 常量 ────────────────────────────────────────────────────────────────────
+const WATCH_INTERVAL = 10000; // watch 模式刷新间隔：10 秒
+
+// ─── 阈值常量（避免魔法数字） ─────────────────────────────────────────────────
+const THRESHOLD = {
+  USAGE_CRITICAL: 85,  // 用量 >= 85% 时显示红色告警
+  USAGE_WARNING: 60,   // 用量 >= 60% 时显示黄色警告
+  EXPIRY_CRITICAL: 3,  // 订阅剩余 <= 3 天时显示红色
+  EXPIRY_WARNING: 7,   // 订阅剩余 <= 7 天时显示黄色
+};
+
+const program = new Command();
+const api = new StepFunAPI();
+
+program
+  .name("stepfun-status")
+  .description("StepFun Claude Code 使用状态监控工具")
+  .version(packageJson.version);
+
+// ─── 公共工具函数 ─────────────────────────────────────────────────────────────
+
+/** 根据已用百分比返回对应的 chalk 颜色函数 */
+function getUsageColor(percentage) {
+  if (percentage >= THRESHOLD.USAGE_CRITICAL) return chalk.red;
+  if (percentage >= THRESHOLD.USAGE_WARNING) return chalk.yellow;
+  return chalk.green;
+}
+
+/** 根据订阅剩余天数返回对应的 chalk 颜色函数 */
+function getExpiryColor(daysRemaining) {
+  if (daysRemaining <= THRESHOLD.EXPIRY_CRITICAL) return chalk.red;
+  if (daysRemaining <= THRESHOLD.EXPIRY_WARNING) return chalk.yellow;
+  return chalk.green;
+}
+
+/**
+ * 生成带颜色的进度条字符串
+ * @param {number} percentage  0–100
+ * @param {number} width       进度条总格数
+ * @param {Function} colorFn   chalk 颜色函数
+ */
+function renderProgressBar(percentage, width, colorFn) {
+  const filled = Math.round((Math.min(100, Math.max(0, percentage)) / 100) * width);
+  const empty = width - filled;
+  return colorFn("█".repeat(filled)) + chalk.dim("░".repeat(empty));
+}
+
+/** 清屏（仅在 TTY 环境，兼容各终端） */
+function clearScreen() {
+  if (process.stdout.isTTY) {
+    process.stdout.write("\x1B[2J\x1B[0f");
+  }
+}
+
+/** 获取当前 Git 分支信息，非 Git 目录返回 null */
+function getGitBranch(cwd) {
+  try {
+    const branch = execSync("git symbolic-ref --short HEAD", {
+      encoding: "utf8",
+      timeout: 3000,
+      stdio: ["pipe", "pipe", "pipe"],
+      cwd,
+    }).trim();
+
+    // 基本格式校验，防止异常值
+    if (!branch || !/^[\w\-\./]+$/.test(branch)) return null;
+
+    const status = execSync("git status --porcelain", {
+      encoding: "utf8",
+      timeout: 3000,
+      stdio: ["pipe", "pipe", "pipe"],
+      cwd,
+    }).trim();
+
+    return { name: branch, hasChanges: Boolean(status) };
+  } catch {
+    return null;
+  }
+}
+
+// ─── Auth 命令 ────────────────────────────────────────────────────────────────
+program
+  .command("auth")
+  .description("设置认证凭据 (从浏览器 Network 面板复制)")
+  .argument("[cookie]", "完整 Cookie 字符串（可选，可直接粘贴不带引号）")
+  .action(async (cookie) => {
+    // 无论是否已有参数，都先打印获取方式
+    console.log(chalk.yellow("\n获取 Cookie 方式:"));
+    console.log(chalk.gray("1. 登录 https://platform.stepfun.com"));
+    console.log(chalk.gray("2. F12 -> Network 标签"));
+    console.log(chalk.gray("3. 刷新页面"));
+    console.log(chalk.gray("4. 点击任意 API 请求（如 GetStepPlanStatus）"));
+    console.log(chalk.gray("5. 滚动到 Request Headers -> 找到 Cookie 行"));
+    console.log(chalk.gray("6. 右键 -> Copy value"));
+
+    if (!cookie) {
+      const readline = require("readline");
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+      });
+
+      console.log(chalk.yellow("\n请粘贴完整的 Cookie 字符串:"));
+      console.log(chalk.gray("(粘贴后按回车)"));
+
+      cookie = await new Promise((resolve) => {
+        rl.on("line", (input) => {
+          rl.close();
+          resolve(input.trim());
+        });
+      });
+    }
+
+    try {
+      api.setCredentials(cookie);
+    } catch (err) {
+      console.error(chalk.red(`✗ ${err.message}`));
+      process.exit(1);
+    }
+
+    console.log(chalk.green("\n✓ 认证信息已保存"));
+    console.log(chalk.gray(`配置文件: ${CONFIG_PATH}`));
+  });
+
+// ─── Health 命令 ──────────────────────────────────────────────────────────────
+program
+  .command("health")
+  .description("检查配置和连接状态")
+  .action(async () => {
+    const spinner = ora("正在检查...").start();
+
+    if (!fs.existsSync(CONFIG_PATH)) {
+      spinner.fail("配置文件检查");
+      console.log(chalk.red("✗ 配置文件: ") + chalk.gray("未找到"));
+      console.log(chalk.yellow("请先运行: stepfun-status auth <cookie>"));
+      return;
+    }
+
+    spinner.succeed("配置文件检查");
+    console.log(chalk.green("✓ 配置文件: ") + chalk.gray("已找到"));
+
+    if (api.isAuthenticated()) {
+      console.log(chalk.green("✓ Cookie: ") + chalk.gray("已配置"));
+      try {
+        await api.getUsageStatus();
+        console.log(chalk.green("✓ API连接: ") + chalk.gray("正常"));
+      } catch (error) {
+        console.log(chalk.red("✗ API连接: ") + chalk.gray(error.message));
+      }
+    } else {
+      console.log(chalk.red("✗ Cookie: ") + chalk.gray("未配置"));
+    }
+  });
+
+// ─── Status 命令 ──────────────────────────────────────────────────────────────
+program
+  .command("status")
+  .description("显示当前使用状态")
+  .option("-c, --compact", "紧凑模式显示")
+  .option("-w, --watch", "实时监控模式")
+  .action(async (options) => {
+    const spinner = ora("获取使用状态中...").start();
+
+    try {
+      const usageData = await api.getUsageStatus();
+      spinner.succeed("状态获取成功");
+
+      if (options.compact) {
+        console.log(renderCompact(usageData));
+      } else {
+        console.log("\n" + renderDetailed(usageData) + "\n");
+      }
+
+      if (options.watch) {
+        console.log(chalk.gray("监控中... 按 Ctrl+C 退出"));
+        // 将已获取的数据和当前渲染函数传入，避免启动时重复请求，并保持显示模式一致
+        const renderFn = options.compact ? renderCompact : renderDetailed;
+        startWatching(usageData, renderFn);
+      }
+    } catch (error) {
+      spinner.fail(chalk.red("获取状态失败"));
+      console.error(chalk.red(`错误: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// ─── Statusline 命令 ──────────────────────────────────────────────────────────
+program
+  .command("statusline")
+  .description("Claude Code状态栏集成")
+  .option("-w, --watch", "持续监控模式，用于Claude Code状态栏")
+  .action(async (options) => {
+    // 缓存一次，避免 renderStatusline 与 execSync 重复调用 process.cwd()
+    const cwd = process.cwd();
+    const cliCurrentDir = cwd.split(/[/\\]/).pop();
+
+    const renderStatusline = async () => {
+      try {
+        const usageData = await api.getUsageStatus();
+        const { usage, modelName, remaining, expiry, weekly } = usageData;
+        const percentage = usage.percentage;
+        const color = getUsageColor(percentage);
+
+        const gitBranch = getGitBranch(cwd);
+
+        const parts = [];
+
+        if (cliCurrentDir) {
+          parts.push(chalk.cyan(cliCurrentDir));
+        }
+
+        if (gitBranch) {
+          const isMainBranch = gitBranch.name === "main" || gitBranch.name === "master";
+          const branchColor = isMainBranch ? chalk.green : chalk.white;
+          let branchStr = branchColor(gitBranch.name);
+          if (gitBranch.hasChanges) branchStr += chalk.red(" *");
+          parts.push(branchStr);
+        }
+
+        parts.push(chalk.magenta(modelName));
+
+        const bar = renderProgressBar(percentage, 10, color);
+        parts.push(`${bar} ${color(percentage + "%")} (${usage.remaining}/100)`);
+
+        const remainingText =
+          remaining.hours > 0
+            ? `${remaining.hours}h${remaining.minutes}m`
+            : `${remaining.minutes}m`;
+        parts.push(`${chalk.yellow("⏱")} ${remainingText}`);
+
+        if (weekly) {
+          const weeklyColor = getUsageColor(weekly.percentage);
+          const weeklyBar = renderProgressBar(weekly.percentage, 5, weeklyColor);
+          parts.push(`${chalk.blue("W")} ${weeklyBar} ${weeklyColor(weekly.percentage + "%")}`);
+        }
+
+        if (expiry) {
+          parts.push(getExpiryColor(expiry.daysRemaining)("到期 " + expiry.daysRemaining + "天"));
+        }
+
+        console.log(parts.join(" │ "));
+      } catch {
+        console.log(
+          `${chalk.cyan(cliCurrentDir || "")} │ ${chalk.magenta("step-3.5-flash")} │ ${chalk.red("❌")}`
+        );
+      }
+    };
+
+    if (options.watch) {
+      console.log(chalk.gray("Claude Code 状态栏已启动..."));
+
+      let stopped = false;
+      const shutdown = () => {
+        stopped = true;
+        process.exit(0);
+      };
+      process.on("SIGINT", shutdown);
+      process.on("SIGTERM", shutdown);
+
+      // 递归 setTimeout：等本次渲染完成后再安排下一次，避免并发请求
+      const loop = async () => {
+        if (stopped) return;
+        clearScreen();
+        await renderStatusline();
+        if (!stopped) setTimeout(loop, WATCH_INTERVAL);
+      };
+
+      loop();
+    } else {
+      await renderStatusline();
+    }
+  });
+
+// ─── 渲染函数 ─────────────────────────────────────────────────────────────────
+
+function renderCompact(data) {
+  const { usage, remaining, modelName, expiry, weekly } = data;
+  const { percentage } = usage;
+  const color = getUsageColor(percentage);
+
+  const statusIcon =
+    percentage >= THRESHOLD.USAGE_CRITICAL ? "⚠" :
+    percentage >= THRESHOLD.USAGE_WARNING  ? "⚡" : "✓";
+  const weeklyInfo = weekly ? ` ${chalk.blue("W")} ${weekly.percentage}%` : "";
+  const expiryInfo = expiry ? ` ${chalk.gray("•")} 剩余: ${expiry.daysRemaining}天` : "";
+
+  return (
+    `${color("●")} ${modelName} ${percentage}% ` +
+    `${chalk.dim(`(${usage.remaining}/100)`)} ${chalk.gray("•")} ` +
+    `${remaining.text}${weeklyInfo} ${chalk.gray("•")} ${statusIcon}${expiryInfo}`
+  );
+}
+
+function renderDetailed(data) {
+  const { modelName, remaining, usage, weekly, expiry } = data;
+
+  const barColor = getUsageColor(usage.percentage);
+  const progressBar = renderProgressBar(usage.percentage, 30, barColor);
+
+  const lines = [];
+  lines.push(chalk.bold("StepFun Claude Code 使用状态"));
+  lines.push("");
+  lines.push(`${chalk.cyan("当前模型:")} ${modelName}`);
+  lines.push(`${chalk.cyan("套餐:")} ${data.planName || "Mini"}`);
+  lines.push("");
+  lines.push(`${chalk.cyan("5小时用量:")} ${progressBar} ${usage.percentage}%`);
+  lines.push(`${chalk.dim("     剩余:")} ${usage.remaining}%`);
+  lines.push(`${chalk.dim("     重置:")} ${remaining.text}`);
+
+  if (weekly) {
+    const weeklyBar = renderProgressBar(weekly.percentage, 15, getUsageColor(weekly.percentage));
+    lines.push("");
+    lines.push(`${chalk.cyan("每周用量:")} ${weeklyBar} ${weekly.percentage}%`);
+    lines.push(`${chalk.dim("     剩余:")} ${weekly.remaining}%`);
+    lines.push(`${chalk.dim("     重置:")} ${weekly.text}`);
+  }
+
+  if (expiry) {
+    lines.push("");
+    lines.push(`${chalk.cyan("套餐到期:")} ${expiry.date} (${expiry.text})`);
+  }
+
+  lines.push("");
+
+  const status =
+    usage.percentage >= THRESHOLD.USAGE_CRITICAL ? "⚠ 即将用完" :
+    usage.percentage >= THRESHOLD.USAGE_WARNING  ? "⚡ 注意使用" : "✓ 正常使用";
+  lines.push(`${chalk.cyan("状态:")} ${getUsageColor(usage.percentage)(status)}`);
+
+  return boxen(lines.join("\n"), {
+    padding: { top: 0, bottom: 0, left: 1, right: 1 },
+    borderColor: "blue",
+    borderStyle: "single",
+    dimBorder: true,
+  });
+}
+
+/**
+ * 启动实时监控模式
+ * @param {object|null} initialData  已获取的 usageData，传入可避免启动时重复请求
+ * @param {Function} renderFn        渲染函数，默认 renderDetailed，可传 renderCompact 保持模式一致
+ */
+function startWatching(initialData = null, renderFn = renderDetailed) {
+  const render = (data) => {
+    clearScreen();
+    console.log("\n" + renderFn(data) + "\n");
+    console.log(chalk.gray(`最后更新: ${new Date().toLocaleTimeString()}`));
+  };
+
+  let stopped = false;
+  const shutdown = () => {
+    stopped = true;
+    console.log(chalk.yellow("\n监控已停止"));
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  // 递归 setTimeout：等本次请求完成后再安排下一次，避免慢网络下并发请求堆积
+  const loop = async () => {
+    if (stopped) return;
+    try {
+      const usageData = await api.getUsageStatus();
+      render(usageData);
+    } catch (error) {
+      console.error(chalk.red(`更新失败: ${error.message}`));
+    }
+    if (!stopped) setTimeout(loop, WATCH_INTERVAL);
+  };
+
+  // 立即用已有数据渲染首帧，之后进入定时循环
+  if (initialData) {
+    render(initialData);
+    setTimeout(loop, WATCH_INTERVAL);
+  } else {
+    loop();
+  }
+}
+
+// ─── 入口 ─────────────────────────────────────────────────────────────────────
+
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+  process.exit(1);
+}
+
+program.parse();

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "stepfun-status",
+  "version": "1.0.0",
+  "description": "StepFun Token-Plan 使用状态监控工具，支持 Claude Code 状态栏集成",
+  "main": "cli/index.js",
+  "bin": {
+    "stepfun-status": "cli/index.js",
+    "stepfun": "cli/index.js"
+  },
+  "files": [
+    "cli/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node cli/index.js health",
+    "start": "node cli/index.js status",
+    "lint": "node --check cli/api.js cli/index.js"
+  },
+  "keywords": [
+    "stepfun",
+    "step",
+    "claude",
+    "claude-code",
+    "status",
+    "monitor",
+    "token-plan"
+  ],
+  "author": "Daiyimo",
+  "license": "MIT",
+  "homepage": "https://github.com/Daiyimo/stepfun-status",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Daiyimo/stepfun-status.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Daiyimo/stepfun-status/issues"
+  },
+  "dependencies": {
+    "boxen": "^8.0.1",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "ora": "^9.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}