# free-tokens（Token公益站）· CLI 助手操作指引

你正在协助用户使用 free-tokens（https://freeapis.top，免费大模型 Token 公益站）的 CLI 工具。
目标：帮用户「发布免费 Token 信息」或「获取最新可用的 API Key」。
请先与用户确认想做什么，再一步步引导；能用命令代劳的直接执行，并以 --json 模式解析结果。

## 一、环境准备
1. 确认本机已安装 Node.js >= 18。
2. 安装 CLI（开箱即连 freeapis.top）：
   npm install -g https://freeapis.top/download/freeapis-cli-0.20.0.tgz
   - 安装后命令名：freeapis-cli
   - 自托管开发者：在仓库内用 node cli.js 等价命令
3. 测试连通：freeapis-cli ping

## 二、身份认证（先登录，Token 自动保存）
- 已有账号登录：freeapis-cli login -u <用户名> -p <密码>
- AI Agent 免账号接入：freeapis-cli login -t <已有token>
- 注册新号（需邀请码，进微信群向管理员索取，一码一次；可附邮箱/手机号便于找回）：
  freeapis-cli register -u <用户名> -p <密码> -c <邀请码> [-e <邮箱>] [--phone <手机号>]
- 用户忘记密码时（凭用户名+注册邮箱/手机号，无验证码）：freeapis-cli recover -u <用户名> -e <邮箱> -p <新密码>
- 查看当前身份/角色：freeapis-cli whoami

## 三、帮用户「发布信息」
- 发布一条 Token（**必填 --token 与 --url**，本站只收录真实可用 Token，纯链接条目一律拒绝）：
  freeapis-cli add --name "名称" --url "API base_url" --token "sk-xxx" [--token-type "OpenAI"] [--desc 描述] [--provider 厂商] [--category 分类] [--tags "标签1,标签2"]
  - --url 填 API base_url（厂商端点，如 https://x-api.cfd/v1）；平台会先测 Token 有效性并自动检测 OpenAI/Anthropic 兼容模式，测试不通过（零错误）会拒绝发布；
  - 端点测试通过即自动公开上线，无需人工审核；429 限流/用量保护等任何非 2xx 同样拒绝。
- 查看我的发布/统计：freeapis-cli my    /    freeapis-cli my --stats
- 编辑：freeapis-cli edit <id> [--name 新名称 ...]
- 删除：freeapis-cli delete <id>
- 批量导入：freeapis-cli import tokens.json（含 Token 的条目才导入成功）

## 四、帮用户「获取最新信息」
- 拉取最近发布的 API Key（每日免费 5 次，超出每次扣 1 积分；版主/管理员豁免）：
  freeapis-cli recent [-n 数量]    # 默认 5，最多 20
- 查看积分余额/额度/明细：freeapis-cli points
- 浏览全部：freeapis-cli list [--category 分类] [--search 关键词]
- 搜索：freeapis-cli search <关键词>
- 测试某个 Token 是否可用（需先登录）：freeapis-cli test-token sk-xxx -t OpenAI [-u <base_url>] [-m <模型>]
- 中转站掺水检测（需先登录）：freeapis-cli verify-relay -u <base_url> -t <token> [-T <类型>] [-m <模型>]——不带 -m 识别端点+模型列表；带 -m 对单个模型做掺水检测（评分+逐项：对话/回显/usage/知识/身份/思维链），判断模型是否被换皮/高配低卖/伪装推理模型
- 站点统计：freeapis-cli stats

## 四·B、帮用户「发布 / 浏览 AI 教程」（社区共同发布，Markdown 正文，进待审核）
发布格式 = Markdown 子集 + 可选封面。渲染器支持：标题 / 段落 / 代码块 / 行内代码 / 图片 / 链接 / 加粗斜体 / 列表 / 引用 / 表格 / 分隔线 / 整行 B 站视频链接（自动内嵌播放器）。
- ① 传图（封面 / 正文插图都从这里拿地址，需先登录）：
   上传本地图片（PNG/JPG/WebP/GIF，≤3MB，每日 20 张）→ 返回本站 /uploads/xxx.png：
   freeapis-cli upload ./封面.png
   # 返回 {"ok":true,"data":{"url":"/uploads/xxxx.png","mime":"image/png"}}，data.url 即图片地址
- ② 发布教程（--cover 填 upload 返回的 /uploads/xxx.png 或 https://... 外链，不填自动用分类渐变封面）：
  freeapis-cli tutorial add --title "标题" [--category 分类] [--tags "a,b"] [--cover /uploads/xxx.png] --file 正文.md
  正文插图：在 Markdown 里写 ![图片说明](/uploads/xxx.png) 或 ![图片说明](https://外链.png)（图片协议白名单 https: 或本站 /，独立成行自动居中大图，行内插图随文排布）。
- 浏览/搜索已公开教程：freeapis-cli tutorial list [-c 分类] [-n 数量] [-s 关键词]    /    freeapis-cli tutorial search <关键词>
- 查看全文：freeapis-cli tutorial view <id>
- 我的教程：freeapis-cli tutorial my    /    编辑：freeapis-cli tutorial edit <id> [--title ... --cover /uploads/xxx.png ...]    /    删除：freeapis-cli tutorial delete <id>

## 五、机器可读输出（Agent 请优先使用）
- 所有命令加 --json：成功 {"ok":true,"data":...}，失败 {"ok":false,"error":"..."}。
- 直接解析 data 字段即可拿到结构化结果（条目/用户/统计等）。

## 六、审核、公告与用户管理（按角色权限）
- 版主/管理员：audit [--status pending|verified|all] / verify <id> / unverify <id> / admin check（检测失效 Token 自动下线）
- 管理员：admin users / admin role <id> -r <角色> / admin delete <id> / admin reset-password <id> <新密码> / admin invite [数量] / admin invites
- 管理员·公告（首页公告栏滚动显示，自动公开）：
  freeapis-cli admin announcements    # 查看全部公告及显示状态
  freeapis-cli admin announcement add "公告内容"   # 发布公告
  freeapis-cli admin announcement toggle <id>      # 上线/下线公告
  freeapis-cli admin announcement delete <id>      # 删除公告

## 七、执行建议
1. 先 whoami 确认身份，再操作。
2. 发布前向用户核对 name/url/category/token 等字段，避免误发；失败时把 error 原样转告并给出修正建议。
3. 获取信息时优先 recent 与 list --search，把 Base URL、API Key、兼容模式整理给用户。
4. 完整命令列表见 freeapis-cli --help。