skillpp 0.1.0

package/skills/binance/square-post/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: square-post
+description: |
+  Use when the user wants to publish new content to Binance Square — short text, multi-image
+  posts (up to 4), long-form articles with an optional cover, or videos with an auto-generated
+  cover frame. Trigger on direct phrasings like "post to Square", "publish to Binance Square",
+  "发广场", "发布到广场", and on near-miss intents where the user clearly wants to share or
+  publish content on Square even without naming the skill: "share this analysis on Square",
+  "把这篇文章发出去", "发个动态", "把这个视频上传到广场", "publish my chart to Square as an
+  article". Also use when the user provides media (images, video) plus a caption and asks to
+  push it to Square, or asks to turn a draft into a Square article. Do not use for reading,
+  searching, commenting, liking, editing, deleting, scheduling, or managing existing Square
+  posts — this skill only creates new posts.
+allowed-tools:
+  - Bash
+metadata:
+  author: binance-square
+  version: "2.0.0"
+---
+
+# Square Post Skill
+
+## Purpose
+
+Publish new content to Binance Square by running the local scripts in `scripts/`.
+
+Supported post types:
+- Text-only short posts
+- Image posts with up to 4 images
+- Long articles with a title and optional cover image
+- Video posts with an auto-generated cover image
+
+Do not hand-code API requests for normal posting. The scripts own upload, polling, cover generation, and publish behavior.
+
+## Runtime Dependencies
+
+- Node.js 18 or newer. The scripts use native ES modules and the built-in `fetch` API.
+- `ffmpeg` is required for video posts because `post-video.mjs` extracts the first frame as the cover image.
+- `ffprobe` is required when a video duration is not provided by the user.
+- Network access is required for Binance Square OpenAPI requests and presigned media uploads.
+
+## Authentication
+
+Posting requires a Binance Square OpenAPI key.
+
+Before posting:
+- Prefer `BINANCE_SQUARE_OPENAPI_KEY` from the user's environment if present.
+- If it is not present, the scripts automatically check `~/.config/binance-square/openapi-key`.
+- If no valid key is found, ask the user to provide an API key first.
+- If the user wants to reuse the key in future requests, save it with `BINANCE_SQUARE_OPENAPI_KEY=<apiKey> node scripts/save-key.mjs`; otherwise use it only for the current command environment.
+- Tell the user they can create an API key at: https://www.binance.com/square/creator-center/home
+
+Pass the key only via `BINANCE_SQUARE_OPENAPI_KEY` (env or saved file). Never write it into command arguments or print the full key — CLI args appear in `ps` output and shell history. When mentioning a key, show only the first 5 and last 4 characters, such as `abc12...xyz9`.
+
+## Scripts
+
+All commands should be run from this skill directory.
+
+### Text Or Article Post
+
+Use for text-only short posts or long articles without images.
+
+```bash
+node scripts/post-text.mjs --text "Hello #crypto $BTC"
+```
+
+Long article with title and no cover:
+
+```bash
+node scripts/post-text.mjs --text "Full article body..." --title "Market Report"
+```
+
+Flags:
+- `--text` required, post text content
+- `--title` optional, sets article-style content
+
+### Image Post
+
+Use for short image posts or long articles with a cover image.
+
+```bash
+node scripts/post-image.mjs --text "Chart analysis" --images "./chart1.png,./chart2.png"
+```
+
+Long article with title and cover:
+
+```bash
+node scripts/post-image.mjs --text "Full analysis..." --title "Market Report" --cover "./chart.png"
+```
+
+Flags:
+- `--text` required, post or article content
+- `--images` required for short image posts only. Use comma-separated image paths with max 4.
+- `--title` optional, sets article-style content. When present, do not pass `--images`.
+- `--cover` required when `--title` is present for an article with media. Article mode supports exactly one cover image.
+
+The script uploads each image, waits for processing, and publishes with the processed image URL returned by the backend. If `--title` is provided, it publishes `contentType=2`, requires `--cover`, and sends that uploaded image URL as `cover` only. If no `--title` is provided, it publishes `contentType=1` and sends all `--images` as `imageList`.
+
+### Video Post
+
+Use for video posts.
+
+```bash
+node scripts/post-video.mjs --video "./video.mp4" --duration 7.5 --text "My analysis"
+```
+
+Flags:
+- `--video` required, local video path
+- `--duration` required, video duration in seconds
+- `--text` optional, post text content
+
+The script uploads the video, waits for processing, extracts the first frame with `ffmpeg`, uploads that frame as the cover image, and publishes with `cover` included in the request.
+
+If the user does not provide a duration, use `ffprobe` to determine it before running the script.
+
+## Agent Workflow
+
+1. Resolve the API key (see Authentication). If unresolved, stop and ask the user before doing anything else.
+
+2. Pick the script from user intent using the table below. Then validate against Constraints — if a constraint is violated, explain it and do not run.
+
+   | User intent | Script | Required flags |
+   |---|---|---|
+   | Short text post | `post-text.mjs` | `--text` |
+   | Long article, no media | `post-text.mjs` | `--text --title` |
+   | Image short post (1–4 imgs, no title) | `post-image.mjs` | `--text --images "<p1,p2,...>"` |
+   | Article with cover | `post-image.mjs` | `--text --title --cover` |
+   | Video post | `post-video.mjs` | `--video --duration` (+ optional `--text`) |
+
+3. Disambiguate edge cases before running:
+   - Title + exactly one image → that image is the cover (`--cover`, not `--images`).
+   - Title + multiple images → stop and ask which single image is the cover.
+   - Video without duration → run `ffprobe` first to get it.
+
+4. Preserve user content exactly. Do not rewrite, translate, add hashtags/cashtags, or change punctuation. `$coin` and `#topic` text passes through verbatim — the backend parses them.
+
+5. Run the script with `BINANCE_SQUARE_OPENAPI_KEY` injected into the command environment for one-time use (never as a CLI arg).
+
+6. Report the result:
+   - On success, return the `ID` and `Link` printed by the script.
+   - If the script prints `Success!` with `ID: unavailable` and `Link: unavailable`, treat it as successful — `/content/add` returned 504 after submission, so no post ID or link is available.
+   - On failure, surface the script error and any API code/message.
+
+## Constraints
+
+- Images: max 4 per post; article cover is exactly 1 image.
+- Video: max 1 per post.
+- Images and video are mutually exclusive in a single post.
+- Only attach media the user explicitly provided; do not auto-attach.
+- Do not modify user-provided text. `#topic` and `$coin` are parsed server-side.
+- Daily limits: 100 posts/day, 400 uploads/day.
+
+## Common Errors
+
+- `220003`: API key not found.
+- `220004`: API key expired.
+- `220009`: Daily post limit exceeded for OpenAPI.
+- `220014`: Daily upload limit exceeded.
+- `20002` or `20022`: Sensitive words detected.
+- `20013`: Content length is limited.
+- `20020` or `220011`: Content body must not be empty.
+- `30008`, `2000001`, or `2000002`: Account or device posting restriction.
+
+## Scope
+
+This skill only supports publishing new posts. It does not support:
+- Reading, listing, or searching existing posts
+- Editing or deleting posts
+- Commenting, liking, or other interactions
+- User profile or account management
+- Scheduling or drafts

package/skills/binance/square-post/scripts/lib.mjs

@@ -0,0 +1,175 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+const BASE_URL_V1 = "https://www.binance.com/bapi/composite/v1/public/pgc/openApi";
+const BASE_URL_V2 = "https://www.binance.com/bapi/composite/v2/public/pgc/openApi";
+const POLL_INTERVAL_MS = 3000;
+const MAX_POLL_RETRIES = 10;
+const CONFIG_DIR = path.join(os.homedir(), ".config", "binance-square");
+const CONFIG_FILE = path.join(CONFIG_DIR, "openapi-key");
+
+const CONTENT_TYPE_MAP = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  mp4: "video/mp4",
+  mov: "video/quicktime",
+  avi: "video/x-msvideo",
+  webm: "video/webm",
+};
+
+export function getContentType(filePath) {
+  const ext = path.extname(filePath).slice(1).toLowerCase();
+  return CONTENT_TYPE_MAP[ext] || "application/octet-stream";
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function getConfigFilePath() {
+  return CONFIG_FILE;
+}
+
+export function maskApiKey(apiKey) {
+  if (!apiKey) return "";
+  if (apiKey.length <= 9) return `${apiKey.slice(0, 2)}...`;
+  return `${apiKey.slice(0, 5)}...${apiKey.slice(-4)}`;
+}
+
+export function readSavedApiKey() {
+  const keyFile = getConfigFilePath();
+  if (!fs.existsSync(keyFile)) return "";
+  return fs.readFileSync(keyFile, "utf8").trim();
+}
+
+export function saveApiKey(apiKey) {
+  const key = apiKey.trim();
+  if (!key) {
+    throw new Error("Missing Square OpenAPI key");
+  }
+
+  const keyFile = getConfigFilePath();
+  fs.mkdirSync(path.dirname(keyFile), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(keyFile, `${key}\n`, { mode: 0o600 });
+  fs.chmodSync(keyFile, 0o600);
+  return keyFile;
+}
+
+export function resolveApiKey(args = []) {
+  if (args.includes("--key")) {
+    throw new Error("Do not pass API keys with --key. Set BINANCE_SQUARE_OPENAPI_KEY or save the key locally first.");
+  }
+
+  const envKey = process.env.BINANCE_SQUARE_OPENAPI_KEY;
+  if (envKey?.trim()) return envKey.trim();
+
+  const savedKey = readSavedApiKey();
+  if (savedKey) return savedKey;
+
+  throw new Error(
+    `Missing Square OpenAPI key. Set BINANCE_SQUARE_OPENAPI_KEY or save it to ${getConfigFilePath()} first.`,
+  );
+}
+
+export async function api(endpoint, apiKey, body, baseUrl = BASE_URL_V2) {
+  const res = await fetch(`${baseUrl}${endpoint}`, {
+    method: "POST",
+    headers: {
+      "X-Square-OpenAPI-Key": apiKey,
+      "Content-Type": "application/json",
+      clienttype: "binanceSkill",
+    },
+    body: JSON.stringify(body),
+  });
+  const raw = await res.text();
+
+  if (endpoint === "/content/add" && res.status === 504) {
+    return { id: null, shareLink: null, publishStatus: "success_without_post_id" };
+  }
+
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (error) {
+    console.error("API returned non-JSON response", {
+      endpoint,
+      status: res.status,
+      statusText: res.statusText,
+      body: raw,
+    });
+    throw new Error(`API returned non-JSON response: ${res.status} ${res.statusText}`);
+  }
+  if (json.code !== "000000") {
+    throw new Error(`API error [${json.code}]: ${json.message}`);
+  }
+  return json.data;
+}
+
+export async function uploadToS3(presignedUrl, filePath, contentType) {
+  const fileBuffer = fs.readFileSync(filePath);
+  const res = await fetch(presignedUrl, {
+    method: "PUT",
+    headers: { "Content-Type": contentType },
+    body: fileBuffer,
+  });
+  if (!res.ok) {
+    throw new Error(`S3 upload failed: ${res.status} ${res.statusText}`);
+  }
+}
+
+export async function uploadImage(apiKey, imgPath) {
+  const imageName = path.basename(imgPath);
+  const contentTypeHeader = getContentType(imgPath);
+
+  console.log(`Uploading: ${imageName}`);
+  const { presignedUrl, fileTicket } = await api("/image/presignedUrl", apiKey, { imageName });
+
+  await uploadToS3(presignedUrl, imgPath, contentTypeHeader);
+  console.log(`  Uploaded to S3, polling status...`);
+
+  const imageStatus = await pollImageStatus(apiKey, fileTicket);
+  console.log(`  Ready: ${imageStatus.imageUrl}`);
+  return imageStatus.imageUrl;
+}
+
+export async function pollImageStatus(apiKey, fileTicket) {
+  for (let i = 0; i < MAX_POLL_RETRIES; i++) {
+    const data = await api("/image/imageStatus", apiKey, { fileTicket });
+    if (data.status === 1) return data;
+    if (data.status === 2) throw new Error(`Processing failed: ${data.failedReason}`);
+    console.log(`  Processing... (${i + 1}/${MAX_POLL_RETRIES})`);
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error(`Poll timed out after ${MAX_POLL_RETRIES} retries`);
+}
+
+export async function publish(apiKey, body) {
+  return await api("/content/add", apiKey, body, BASE_URL_V1);
+}
+
+export function printPublishSuccess(result) {
+  console.log(`\nSuccess!`);
+  console.log(`ID: ${result.id ?? "unavailable"}`);
+  console.log(`Link: ${result.shareLink ?? "unavailable"}`);
+}
+
+export function parseArgs(args, required, optional = []) {
+  const result = {};
+  for (const flag of [...required, ...optional]) {
+    const idx = args.indexOf(`--${flag}`);
+    if (idx !== -1 && idx + 1 < args.length) {
+      result[flag] = args[idx + 1];
+    }
+  }
+  for (const flag of required) {
+    if (!result[flag]) {
+      console.error(`Error: --${flag} is required`);
+      process.exit(1);
+    }
+  }
+  return result;
+}

package/skills/binance/square-post/scripts/post-image.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+import { parseArgs, printPublishSuccess, publish, resolveApiKey, uploadImage } from "./lib.mjs";
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help")) {
+  console.log(`Usage:
+  node post-image.mjs --text <content> --images <paths>
+  node post-image.mjs --text <content> --title <title> --cover <path>
+
+Post short image content or an article with a cover image to Binance Square.
+
+Options:
+  --text <content> Post text content (required)
+  --images <paths> Comma-separated image paths for short posts, max 4
+  --title <title>  Article title. When present, publish as contentType=2
+  --cover <path>   Cover image path for article posts with --title
+
+Authentication:
+  Set BINANCE_SQUARE_OPENAPI_KEY or save a key with scripts/save-key.mjs.`);
+  process.exit(0);
+}
+
+const { text } = parseArgs(args, ["text"]);
+const { title, images, cover } = parseArgs(args, [], ["title", "images", "cover"]);
+
+if (title && images) {
+  console.error("Error: article posts with --title use --cover, not --images");
+  process.exit(1);
+}
+if (cover && !title) {
+  console.error("Error: --cover requires --title");
+  process.exit(1);
+}
+
+const imagePaths = title ? [] : images ? images.split(",").map((p) => p.trim()).filter(Boolean) : [];
+
+if (title && !cover) {
+  console.error("Error: article posts with --title require --cover <path>");
+  process.exit(1);
+}
+if (title && cover.includes(",")) {
+  console.error("Error: article posts support exactly one --cover image");
+  process.exit(1);
+}
+if (!title && imagePaths.length === 0) {
+  console.error("Error: --images is required for short image posts");
+  process.exit(1);
+}
+if (imagePaths.length > 4) {
+  console.error("Error: max 4 images allowed");
+  process.exit(1);
+}
+
+const contentType = title ? 2 : 1;
+
+try {
+  const key = resolveApiKey(args);
+
+  const body = { contentType, bodyTextOnly: text };
+  if (title) {
+    const coverUrl = await uploadImage(key, cover);
+    body.title = title;
+    body.cover = coverUrl;
+  } else {
+    const uploadedImages = [];
+    for (const imgPath of imagePaths) {
+      uploadedImages.push(await uploadImage(key, imgPath));
+    }
+    body.imageList = uploadedImages;
+  }
+
+  console.log("Publishing...");
+  const result = await publish(key, body);
+  printPublishSuccess(result);
+} catch (err) {
+  console.error(`\nFailed: ${err.message}`);
+  process.exit(1);
+}

package/skills/binance/square-post/scripts/post-text.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { parseArgs, printPublishSuccess, publish, resolveApiKey } from "./lib.mjs";
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help")) {
+  console.log(`Usage: node post-text.mjs --text <content> [--title <title>]
+
+Post text content to Binance Square as a short post or long article.
+
+Options:
+  --text <content> Post text content (required)
+  --title <title>  Article title. When present, publish as contentType=2 (optional)
+
+Authentication:
+  Set BINANCE_SQUARE_OPENAPI_KEY or save a key with scripts/save-key.mjs.`);
+  process.exit(0);
+}
+
+const { text } = parseArgs(args, ["text"]);
+const { title } = parseArgs(args, [], ["title"]);
+
+const contentType = title ? 2 : 1;
+
+try {
+  const key = resolveApiKey(args);
+
+  console.log(contentType === 2 ? "Publishing article..." : "Publishing text post...");
+  const body = {
+    contentType,
+    bodyTextOnly: text,
+  };
+  if (title) body.title = title;
+
+  const result = await publish(key, body);
+  printPublishSuccess(result);
+} catch (err) {
+  console.error(`\nFailed: ${err.message}`);
+  process.exit(1);
+}

package/skills/binance/square-post/scripts/post-video.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { spawnSync } from "child_process";
+import { parseArgs, api, uploadToS3, pollImageStatus, publish, getContentType, uploadImage, printPublishSuccess, resolveApiKey } from "./lib.mjs";
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help")) {
+  console.log(`Usage: node post-video.mjs --video <path> --duration <seconds> [--text <content>]
+
+Post a video to Binance Square.
+
+Options:
+  --video <path>       Video file path (required)
+  --duration <seconds> Video duration in seconds (required)
+  --text <content>     Post text content (optional)
+
+Authentication:
+  Set BINANCE_SQUARE_OPENAPI_KEY or save a key with scripts/save-key.mjs.`);
+  process.exit(0);
+}
+
+const { video, duration } = parseArgs(args, ["video", "duration"]);
+const { text } = parseArgs(args, [], ["text"]);
+
+const videoTimeSeconds = Number(duration);
+if (isNaN(videoTimeSeconds) || videoTimeSeconds <= 0) {
+  console.error("Error: --duration must be a positive number");
+  process.exit(1);
+}
+
+function extractVideoCover(videoPath) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "square-video-cover-"));
+  const coverPath = path.join(tempDir, `${path.parse(videoPath).name}-cover.png`);
+  const result = spawnSync("ffmpeg", [
+    "-y",
+    "-loglevel",
+    "error",
+    "-i",
+    videoPath,
+    "-frames:v",
+    "1",
+    "-q:v",
+    "2",
+    coverPath,
+  ], { encoding: "utf8" });
+
+  if (result.error) {
+    throw new Error(`Failed to run ffmpeg: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new Error(`Failed to extract video cover: ${result.stderr || "ffmpeg exited with an error"}`);
+  }
+  if (!fs.existsSync(coverPath) || fs.statSync(coverPath).size === 0) {
+    throw new Error("Failed to extract video cover: empty cover file");
+  }
+
+  return { coverPath, tempDir };
+}
+
+function cleanupCover(coverPath, tempDir) {
+  if (coverPath && fs.existsSync(coverPath)) fs.unlinkSync(coverPath);
+  if (tempDir && fs.existsSync(tempDir)) fs.rmdirSync(tempDir);
+}
+
+let coverPath;
+let coverTempDir;
+
+try {
+  const key = resolveApiKey(args);
+
+  const fileName = path.basename(video);
+  const size = fs.statSync(video).size;
+  const contentTypeHeader = getContentType(video);
+
+  console.log(`Uploading video: ${fileName} (${(size / 1024 / 1024).toFixed(1)}MB)`);
+  const { presignedUrl, fileTicket } = await api("/video/preSign", key, { fileName, size });
+
+  await uploadToS3(presignedUrl, video, contentTypeHeader);
+  console.log(`  Uploaded to S3, polling status...`);
+
+  await pollImageStatus(key, fileTicket);
+  console.log(`  Video processed.`);
+
+  console.log("Extracting video cover...");
+  ({ coverPath, tempDir: coverTempDir } = extractVideoCover(video));
+  const cover = await uploadImage(key, coverPath);
+
+  console.log("Publishing...");
+  const body = {
+    contentType: 3,
+    fileTicket,
+    cover,
+    videoTimeSeconds,
+    isPublish: true,
+  };
+  if (text) body.bodyTextOnly = text;
+
+  const result = await publish(key, body);
+
+  printPublishSuccess(result);
+} catch (err) {
+  console.error(`\nFailed: ${err.message}`);
+  process.exitCode = 1;
+} finally {
+  cleanupCover(coverPath, coverTempDir);
+}

package/skills/binance/square-post/scripts/save-key.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { maskApiKey, saveApiKey } from "./lib.mjs";
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help")) {
+  console.log(`Usage: BINANCE_SQUARE_OPENAPI_KEY=<apiKey> node scripts/save-key.mjs
+
+Save the Binance Square OpenAPI key to a local user config file with 0600 permissions.
+
+Authentication:
+  Read the key from BINANCE_SQUARE_OPENAPI_KEY. Do not pass keys as CLI arguments.`);
+  process.exit(0);
+}
+
+if (args.length > 0) {
+  console.error("Error: do not pass API keys as CLI arguments. Set BINANCE_SQUARE_OPENAPI_KEY instead.");
+  process.exit(1);
+}
+
+const key = process.env.BINANCE_SQUARE_OPENAPI_KEY?.trim();
+if (!key) {
+  console.error("Error: BINANCE_SQUARE_OPENAPI_KEY is required.");
+  process.exit(1);
+}
+
+try {
+  const keyFile = saveApiKey(key);
+  console.log(`Saved Square OpenAPI key ${maskApiKey(key)} to ${keyFile}`);
+} catch (err) {
+  console.error(`Failed: ${err.message}`);
+  process.exit(1);
+}