SubsTracker API 技能

通过封装 SubsTracker REST API 的 CLI 脚本管理订阅。这些脚本处理身份验证、Cookie 管理和重试——您只需调用命令即可获取 JSON 返回。

技能结构

substracker-skills/
├── SKILL.md ← 您在此处
└── scripts/
├── main.ts ← CLI 入口点（仅路由）
├── client.ts ← HTTP 客户端、环境变量加载、身份验证
├── types.ts ← TypeScript 接口（规范模式 + 文档）
├── subscriptions.ts ← 订阅命令
├── payments.ts ← 支付命令
├── config.ts ← 配置命令
├── dashboard.ts ← 仪表盘命令
└── notifications.ts ← 通知测试命令

阅读 scripts/types.ts 获取所有字段名称、类型、默认值和描述（TSDoc 注释）。

配置

脚本自动从 .env 文件加载凭据。无需在会话中手动设置。

加载优先级（先找到的优先）：

1. 1. 系统环境变量
2. /.substracker-skills/.env
3. ~/.substracker-skills/.env

.env 中必需的变量：

SUBSTRACKER_URL=https://sub.example.com
SUBSTRACKER_USER=admin
SUBSTRACKERPASS=yourpassword

如果变量缺失，脚本会退出并显示清晰的错误信息。请用户创建他们的 .env 文件。

运行命令

解析运行时：如果安装了 bun 则使用，否则使用 npx -y bun。

所有命令遵循相同模式：
bash
bun /scripts/main.ts [subcommand] [--flags]

脚本输出 JSON 到 stdout（供您解析）并记录日志到 stderr（用于调试）。身份验证和会话 cookie 自动处理——如果会话过期，脚本会重新登录并重试。

命令参考

登录

bash
bun scripts/main.ts login

通常不需要——所有命令在无会话时自动登录。使用此命令验证凭据。

订阅

bash
bun scripts/main.ts s list
bun scripts/main.ts s create --name Netflix --expiry-date 2026-04-07 --amount 15.99
bun scripts/main.ts s get
bun scripts/main.ts s update --amount 19.99
bun scripts/main.ts s delete
bun scripts/main.ts s toggle --active false
bun scripts/main.ts s renew --amount 15.99 --note March renewal
bun scripts/main.ts s test-notify

订阅标志（create / update）

标志	类型	必需	描述
--name	string	仅创建	订阅名称
--expiry-date

string | 仅创建 | 到期日期（ISO 格式） | | --amount | number | - | 每个计费周期的费用 | | --currency | string | - | 货币代码，默认 CNY | | --period-unit | day\|month\|year | - | 计费周期单位，默认 month | | --period-value | number | - | 计费周期长度，默认 1 | | --category | string | - | 分类标签（例如 娱乐） | | --custom-type | string | - | 自定义类型（例如 视频流媒体） | | --mode | cycle\|reset | - | 订阅模式 | | --start-date | string | - | 开始日期（ISO 格式） | | --auto-renew | true\|false | - | 自动续费标志，默认 true | | --active | true\|false | - | 活动状态 | | --reminder-unit | day\|hour | - | 提醒单位 | | --reminder-value | number | - | 提醒值 | | --reminder-days | number | - | 到期前提醒天数 | | --lunar | true\|false | - | 使用农历 | | --notes | string | - | 备注/备忘录 |

切换标志

标志	类型	描述
--active	true\	false	设置为活动或非活动

续费标志

标志	类型	描述
--amount	number	支付金额
--period-multiplier

number | 计费周期倍数 | | --payment-date | string | 支付日期 | | --note | string | 支付备注 |

支付

bash
bun scripts/main.ts p list
bun scripts/main.ts p edit --amount 19.99 --note adjusted
bun scripts/main.ts p delete

支付编辑标志

标志	类型	描述
--date	string	支付日期
--amount

number | 支付金额 | | --note | string | 支付备注 |

仪表盘

bash
bun scripts/main.ts d

返回月度/年度支出、活动数量、即将到来的续费、费用明细。

配置

bash
bun scripts/main.ts c get
bun scripts/main.ts c update --timezone Asia/Shanghai --notifiers telegram,bark

配置标志

标志	类型	描述
--username	string	管理员用户名
--password

string | 管理员密码 | | --timezone | string | 时区（例如 Asia/Shanghai） | | --show-lunar | true\|false | 显示农历日期 | | --theme | string | 主题模式 | | --notifiers | string | 逗号分隔：telegram,bark,email,webhook,wechatbot,gotify | | --tg-bot-token | string | Telegram 机器人令牌 | | --tg-chat-id | string | Telegram 聊天 ID | | --bark-key | string | Bark 设备密钥 | | --bark-server | string | Bark 服务器 URL | | --webhook-url | string | Webhook URL | | --webhook-method | string | Webhook HTTP 方法 | | --webhook-template | string | Webhook 正文模板 | | --wechat-webhook | string | 微信机器人 webhook URL | | --gotify-url | string | Gotify 服务器 URL | | --gotify-token | string | Gotify 应用令牌 | | --email-from | string | 发件人邮箱 | | --email-to | string | 收件人邮箱 | | --resend-key | string | Resend API 密钥 | | --clear-secrets | string | 逗号分隔的要清除的字段 | | --debug | true\|false | 启用调试日志 | | --payment-history-limit | number | 最大支付历史记录数 |

测试通知

bash
bun scripts/main.ts t --type telegram

标志	类型	必需	描述
--type	string	✓	telegram\	notifyx\	webhook\	wechatbot\	email\	bark\	gotify
其他标志

- | - | 作为配置覆盖传递（例如 --tg-bot-token → TGBOTTOKEN） |

呈现结果

向用户展示订阅数据时，将 JSON 响应格式化为可读的表格或摘要——不要直接输出原始 JSON。例如，订阅列表应显示为包含名称、金额、周期、下次续费日期和状态的表格。

错误处理

• - 缺少环境变量：脚本退出并提示创建 .env
• 401 未授权：自动重新登录并重试（一次）
• API 错误：响应包含 success: false 和 message 说明错误原因