focalapi-cli 0.1.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "focalapi-cli",
+  "version": "0.1.0",
+  "description": "连接 focalapi 与 AI Agent 的命令行工具——让 Agent 直接调用 focalapi 的对话、图像、视频、搜索、音频等模型能力",
+  "type": "module",
+  "bin": {
+    "focalapi": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "focalapi",
+    "ai",
+    "agent",
+    "cli",
+    "llm",
+    "image-generation",
+    "video-generation"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/xnn-ai/focalapi-cli.git"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.2.4",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.4",
+    "vitest": "^2.1.9"
+  }
+}

package/skills/focalapi/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: focalapi
+description: focalapi 能力总入口。Use when 用户要求使用 focalapi / focalapi-cli，或需要调用 focalapi 的对话、图像、视频、搜索、音频、向量、重排、用量等任意模型能力。先读本技能确定该用哪个子技能/命令。
+---
+
+# focalapi 能力总览
+
+focalapi 是统一的 AI 模型 API 网关（OpenAI 兼容），`focalapi` CLI 让 Agent 一条命令调用全部能力。
+
+## 前置检查
+
+```bash
+focalapi --version          # 确认 CLI 已安装
+focalapi auth status        # 确认 Key 有效、看额度
+focalapi doctor             # 全链路自检（用免费演练模型，不花额度）
+```
+
+任何命令失败，先跑 `focalapi doctor` 按提示修复（Key 缺失 → `focalapi auth login --key <sk-...>`）。
+
+## 能力 → 命令速查
+
+| 需求 | 命令 | 子技能 |
+|---|---|---|
+| 对话/总结/翻译/看图 | `focalapi chat` | focalapi-chat |
+| 生成图片 | `focalapi gen image` | focalapi-gen |
+| 生成视频 | `focalapi gen video`（任务制，可 `--no-wait`） | focalapi-gen |
+| 联网搜索 | `focalapi search` | focalapi-search |
+| 语音转文字 | `focalapi audio transcribe` | focalapi-chat |
+| 文字转语音 | `focalapi audio speech` | focalapi-chat |
+| 文本向量化 | `focalapi embed` | focalapi-chat |
+| 文档重排序 | `focalapi rerank` | focalapi-chat |
+| 额度/用量 | `focalapi usage` / `focalapi auth status` | focalapi-usage |
+| 诊断排障 | `focalapi doctor` | focalapi-usage |
+| 读取未封装端点 | `focalapi request get /v1/... --json` | focalapi |
+
+## Agent 使用约定
+
+1. **机器可读输出**：所有命令加 `--json`，stdout 是纯净 JSON，可直接 `jq` 解析。
+2. **模型选择**：先 `focalapi models list --json` 拿当前 Key 可用模型，不要猜模型名。
+3. **演练模型**：`focal-rehearsal-chat` 免费，适合做链路验证和演示。
+4. **产物路径**：生成类命令默认写入 `./focalapi-out/`，把绝对路径告诉用户。
+5. **非交互**：本 CLI 在非 TTY 环境全自动（无提示无动画），认证用环境变量 `FOCALAPI_API_KEY` 或已保存的配置。
+6. **原始请求**：优先用语义化命令；只有读取尚未封装的端点时才用 `request get` / `request head`。它只允许站内路径和 GET/HEAD，绝不用于写入操作。

package/skills/focalapi-auth/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: focalapi-auth
+description: focalapi CLI 的安装、登录、Key 管理与连通性验证。Use when focalapi 命令报 missing_api_key/invalid_api_key 错误、需要配置 FOCALAPI_API_KEY、或首次安装接入 focalapi。
+---
+
+# focalapi 认证与接入
+
+## 安装
+
+```bash
+npm i -g focalapi-cli
+focalapi --version
+```
+
+要求 Node.js ≥ 18。
+
+## 登录（三选一）
+
+```bash
+# 1. 显式传 key（Agent 环境推荐）
+focalapi auth login --key sk-xxxx
+
+# 2. 环境变量（不落盘，CI/沙箱推荐）
+export FOCALAPI_API_KEY=sk-xxxx
+
+# 3. 交互粘贴（仅终端）
+focalapi auth login
+```
+
+Key 在 https://focalapi.com/console/token 创建。本地保存位置：`~/.focalapi/config.json`（权限 600）。
+
+## 验证
+
+```bash
+focalapi auth status        # Key 有效性 + 额度 + 来源
+focalapi doctor             # 网络→鉴权→演练模型→额度 全链路（免费）
+```
+
+## 自定义端点
+
+私有化部署时：`export FOCALAPI_BASE_URL=https://你的域名`（或 `--base-url` flag，或登录时写入 profile）。
+
+## 常见错误
+
+| 错误码 | 含义 | 处理 |
+|---|---|---|
+| missing_api_key | 没配 Key | 按上面任一方式登录 |
+| invalid_api_key | Key 无效/过期/被删 | 控制台重建 Key 后重新 login |
+| insufficient_quota | 额度不足 | 控制台充值；`focalapi usage` 查明细 |
+| network_error | 连不上 | 查网络/代理/BASE_URL；跑 `focalapi doctor` |

package/skills/focalapi-chat/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: focalapi-chat
+description: 用 focalapi 做对话、多模态理解（看图）、embedding 与 rerank。Use when 需要文本生成/总结/翻译/问答、理解图片内容、文本向量化或文档重排序。
+---
+
+# focalapi 对话与理解
+
+## 对话
+
+```bash
+# 基础（模型名先从 focalapi models list 获取；演练用免费 focal-rehearsal-chat）
+focalapi chat "用一句话总结 RAG" -m <model>
+
+# 管道输入（处理长文本/文件内容）
+cat report.md | focalapi chat -m <model> --system "你是严谨的技术编辑"
+
+# 看图（多模态）
+focalapi chat "描述这张图的 UI 布局" -m <多模态模型> --input @screenshot.png
+
+# 机器可读输出（Agent 串联）
+focalapi chat "提取关键日期" -m <model> --json
+```
+
+- `--stream` / `--no-stream` 控制流式（TTY 默认流式，`--json` 默认非流式）。
+- `--input` 支持多张图片；txt/md/json 文件会作为文本拼入。
+- 默认模型可用 `FOCALAPI_MODEL` 环境变量固定。
+
+## 向量化
+
+```bash
+focalapi embed "待编码文本" -m <embedding模型> --json
+focalapi embed -m <model> --input @doc.txt --json
+```
+
+## 重排序
+
+```bash
+focalapi rerank -m <rerank模型> --query "用户问题" --docs @docs.json --json
+# docs.json 是字符串数组
+```
+
+## 音频
+
+```bash
+focalapi audio transcribe meeting.mp3 -m <转写模型>          # 语音→文字
+focalapi audio speech "大家好" -m <TTS模型> --voice alloy -o out.mp3
+```
+
+## 排错
+
+失败先 `focalapi doctor`；报 model_not_found 时 `focalapi models list --filter <关键字>` 确认模型名。

package/skills/focalapi-gen/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: focalapi-gen
+description: 用 focalapi 生成图片和视频（产物自动下载到本地）。Use when 用户要画图、生成海报/插画/logo、图生图、文生视频、或查询/下载视频生成任务产物。
+---
+
+# focalapi 图像与视频生成
+
+## 图片（同步）
+
+```bash
+focalapi gen image "未来城市夜景海报，赛博朋克风" -m <图像模型> --size 1024x1024 -o ./out
+# 多张：--n 4（上限 128）
+```
+
+产物保存到 `-o` 目录（默认 `./focalapi-out/`），stdout/stderr 会打印绝对路径，把路径直接交给用户或后续步骤。
+
+## 视频（任务制）
+
+```bash
+# 方式一：前台等待完成并自动下载（默认）
+focalapi gen video "海浪拍打礁石，电影感" -m <视频模型> --seconds 5 -o ./out
+
+# 方式二：异步——Agent 做长任务编排时推荐
+focalapi gen video "..." -m <视频模型> --no-wait --json     # 立即拿 task_id
+focalapi task status <task_id> --json                      # 轮询状态
+focalapi task download <task_id> -o ./out                  # 完成后取 mp4
+```
+
+- `--seconds` 上限 3600（CLI 与后端双重 clamp，超限直接报错）。
+- 轮询参数：`--poll-interval <ms>`（默认 5000）、`--timeout <分钟>`（默认 30）。
+- 产物下载走 focalapi 内容代理（`/v1/videos/:task_id/content`），不依赖上游签名 URL，不过期。
+
+## JSON 输出约定（供 Agent 解析）
+
+- `gen image --json` → `{"files": ["..."], "count": N}`
+- `gen video --no-wait --json` → `{"task_id": "...", "submitted": true}`
+- `gen video --json`（等待模式）→ `{"task_id": "...", "status": "success", "file": "..."}`
+- `task status --json` → `{"task_id","status":"pending|running|success|failed|unknown","progress","raw"}`
+
+## 排错
+
+- 任务失败：`focalapi task status <task_id> --json` 看 `raw` 里上游详情。
+- 模型名不确定：`focalapi models list --filter video` / `--filter image`。

package/skills/focalapi-search/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: focalapi-search
+description: 用 focalapi 联网搜索。Use when 需要实时信息、新闻、资料检索、事实核查，或用户明确要求"搜一下/查一下"。
+---
+
+# focalapi 联网搜索
+
+```bash
+focalapi search "过去7天 AI 行业重要新闻" -m <搜索模型> --json
+```
+
+- 端点为 `/v1/alpha/search`（alpha 级，响应结构由上游定义）；`--json` 原样透传，pretty 模式尽力解析为结果表格。
+- 搜索模型名先确认：`focalapi models list --filter search`。
+
+## 自定义请求体（逃生门）
+
+上游格式变更或需要高级参数时，用 `--raw` 直接控制请求体：
+
+```bash
+focalapi search "查询" -m <model> --raw '{"query":"...","search_depth":"advanced"}' --json
+focalapi search x -m <model> --raw @body.json
+```
+
+## 典型编排
+
+搜索 → 把 `--json` 结果交给 `focalapi chat` 做摘要/分析：
+
+```bash
+focalapi search "主题" -m <搜索模型> --json > results.json
+cat results.json | focalapi chat -m <对话模型> --system "把输入的搜索结果整理成 5 条要点"
+```

package/skills/focalapi-usage/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: focalapi-usage
+description: 查询 focalapi 额度/用量/账单，以及用 doctor 做链路诊断。Use when 用户问余额、用量、花了多少、Key 什么时候过期，或任何 focalapi 调用失败需要排障。
+---
+
+# focalapi 用量与诊断
+
+## 额度与用量
+
+```bash
+focalapi auth status            # Key 有效性 + 剩余额度 + 过期时间
+focalapi usage                  # 令牌额度 + 本周期账单用量
+focalapi usage --start 2026-08-01 --end 2026-08-05 --json
+```
+
+额度字段说明：`total_granted` 总额度、`total_used` 已用、`total_available` 剩余、`unlimited_quota` 为 true 表示不限额。
+
+## 诊断（doctor）
+
+任何 focalapi 调用失败，第一步永远是：
+
+```bash
+focalapi doctor            # 人读报告
+focalapi doctor --json     # 机读报告（checks 数组，每项 ok/detail/hint）
+```
+
+检查链：Key 解析 → 网络与鉴权（GET /v1/models）→ 端到端推理（focal-rehearsal-chat 免费演练模型，不耗额度）→ 额度。
+
+- 全部 ✓：链路正常，问题在调用参数（对照命令 --help）。
+- 任一 ✗：按该项 hint 修复；退出码非零适合脚本判断。
+
+## 成本控制建议
+
+- 演示/联调一律用 `focal-rehearsal-chat`（免费）。
+- 生成类操作前先 `focalapi usage` 确认额度充足。
+- 视频是任务制计费，优先用 `--seconds` 显式控制时长。