yuanflow-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YuanFlow
+
+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,77 @@
+# yuanflow-cli
+
+Agent-friendly local CLI wrapper for YuanFlow cloud APIs.
+
+## 安装
+
+```bash
+npm install -g yuanflow-cli
+```
+
+## 初始化 token
+
+推荐直接写入本地配置：
+
+```bash
+ycloud config set-token <your-token>
+```
+
+也支持环境变量：
+
+```bash
+export YUANCHUANG_API_TOKEN=<your-token>
+```
+
+Windows PowerShell:
+
+```powershell
+$env:YUANCHUANG_API_TOKEN="<your-token>"
+```
+
+## 常用命令
+
+```bash
+ycloud auth status
+ycloud commands list --output json
+ycloud health check --output json
+ycloud social bilibili-fetch-one-video-v3 --url "https://www.bilibili.com/video/BV1GJ411x7h7" --output json
+```
+
+## 说明
+
+发布包由仓库内独立的 NPM 封装目录维护，不直接在业务源码根目录做发包逻辑。
+
+---
+
+下面内容面向仓库维护者。
+
+## 目录职责
+
+- 独立维护 NPM 发布所需的 `package.json`
+- 生成可发布的 `dist/` 目录
+- 放安装说明、打包脚本、发布收口逻辑
+
+## 源码来源
+
+当前发布包源码来自仓库主源码目录：
+
+- `../../src/ycloud`
+
+打包脚本会把这部分源码复制到：
+
+- `./dist/src/ycloud`
+
+这样做的目的很简单：
+
+- NPM 封装逻辑和 CLI 主源码分离
+- 后续调整发布逻辑时，不容易和 CLI 开发逻辑冲突
+
+## 常用命令
+
+```powershell
+npm run build
+npm run check:version-sync
+npm run check:publish
+npm run pack:dry-run
+npm run pack
+```

package/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "./src/ycloud/cli.js";

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "yuanflow-cli",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "NPM packaging wrapper for YuanFlow CLI",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ycloud": "cli.js"
+  },
+  "files": [
+    "cli.js",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/ycloud/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+import { executeCommand } from "./commands/index.js";
+
+const args = process.argv.slice(2);
+
+try {
+  const { code, output } = await executeCommand(args);
+  process.stdout.write(output);
+  process.exitCode = code;
+} catch (error) {
+  const mappedCode = error?.code || "INTERNAL_ERROR";
+  const mappedExitCode = error?.exitCode || 1;
+  const mappedRetryable = error?.retryable || false;
+  const payload = {
+    success: false,
+    command: args.slice(0, 2).join(" ").trim() || "unknown",
+    data: null,
+    warnings: [],
+    error: {
+      code: mappedCode,
+      message: error instanceof Error ? error.message : String(error),
+      retryable: mappedRetryable,
+    },
+    meta: {},
+  };
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.exitCode = mappedExitCode;
+}

package/src/ycloud/commands/analysis.js

@@ -0,0 +1,82 @@
+import { apiPost } from "../core/http.js";
+import { getToken } from "../core/token.js";
+import { getGlobalFlagsHelp, parseInteger } from "./shared.js";
+
+export function getAnalysisHelp(subcommand) {
+  if (subcommand === "creator-profile") {
+    return `Analyze creator profile
+
+Usage:
+  ycloud analysis creator-profile [flags]
+
+Required Flags:
+  --profile-url string   creator profile share URL
+
+Optional Flags:
+  --video-limit int      number of videos to analyze (default 20)
+
+${getGlobalFlagsHelp()}
+
+Examples:
+  ycloud analysis creator-profile --profile-url "https://v.douyin.com/xxxx/" --video-limit 20 --output json
+
+Read on success:
+  data.profile
+  data.insights
+
+Read on error:
+  error.code
+  error.message
+  error.retryable`;
+  }
+
+  return `Analysis commands
+
+Usage:
+  ycloud analysis <creator-profile> [flags]`;
+}
+
+async function requireToken(context) {
+  const token = await getToken();
+  if (!token) {
+    return context.fail(
+      context.commandName,
+      "TOKEN_MISSING",
+      "缺少 YUANCHUANG_API_TOKEN",
+      3,
+      false,
+    );
+  }
+  return token;
+}
+
+export async function executeAnalysisCreatorProfile(context, tokens) {
+  const options = context.parseCommandFlags(tokens);
+  if (!options["profile-url"]) {
+    return context.fail(
+      "analysis creator-profile",
+      "BAD_ARGUMENT",
+      "缺少必填参数 --profile-url",
+      2,
+      false,
+    );
+  }
+
+  const token = await requireToken(context);
+  if (typeof token !== "string") {
+    return token;
+  }
+
+  const data = await apiPost("/v1/analysis/douyin/creator-profile", {
+    token,
+    traceId: context.globalOptions.traceId,
+    timeout: context.globalOptions.timeout,
+    baseUrl: context.globalOptions.baseUrl,
+    body: {
+      profile_url: options["profile-url"],
+      video_limit: parseInteger(options["video-limit"]) ?? 20,
+    },
+  });
+
+  return context.ok("analysis creator-profile", data);
+}

package/src/ycloud/commands/auth.js

@@ -0,0 +1,191 @@
+import { apiGet } from "../core/http.js";
+import { getConfigPath, maskToken } from "../core/config.js";
+import { getToken, getTokenWithSource } from "../core/token.js";
+import { getGlobalFlagsHelp, parseInteger } from "./shared.js";
+
+export function getAuthHelp(subcommand) {
+  if (subcommand === "validate") {
+    return `Validate current API token
+
+Usage:
+  ycloud auth validate [flags]
+
+Optional Flags:
+  none
+
+${getGlobalFlagsHelp()}
+
+Examples:
+  ycloud auth validate --output json
+
+Read on success:
+  success
+  data
+
+Read on error:
+  error.code
+  error.message
+  error.retryable`;
+  }
+
+  if (subcommand === "info") {
+    return `Get current token account info
+
+Usage:
+  ycloud auth info [flags]
+
+Optional Flags:
+  none
+
+${getGlobalFlagsHelp()}
+
+Examples:
+  ycloud auth info --output json
+
+Read on success:
+  data
+
+Read on error:
+  error.code
+  error.message
+  error.retryable`;
+  }
+
+  if (subcommand === "charges") {
+    return `List token billing charge records
+
+Usage:
+  ycloud auth charges [flags]
+
+Optional Flags:
+  --model-id string      filter by model id
+  --charge-type string   filter by charge type
+  --user-level string    filter by user level
+  --start-at string      ISO datetime start
+  --end-at string        ISO datetime end
+  --limit int            page size, default 20
+  --offset int           offset, default 0
+
+${getGlobalFlagsHelp()}
+
+Examples:
+  ycloud auth charges --limit 20 --output json
+
+Read on success:
+  data
+
+Read on error:
+  error.code
+  error.message
+  error.retryable`;
+  }
+
+  if (subcommand === "status") {
+    return `Show current token source and masked token
+
+Usage:
+  ycloud auth status [flags]
+
+Optional Flags:
+  none
+
+${getGlobalFlagsHelp()}
+`;
+  }
+
+  return `Auth commands
+
+Usage:
+  ycloud auth <validate|info|charges|status> [flags]`;
+}
+
+async function requireToken(context) {
+  const token = await getToken();
+  if (!token) {
+    return context.fail(
+      context.commandName,
+      "TOKEN_MISSING",
+      "缺少 YUANCHUANG_API_TOKEN",
+      3,
+      false,
+    );
+  }
+  return token;
+}
+
+export async function executeAuthInfo(context) {
+  const token = await requireToken(context);
+  if (typeof token !== "string") {
+    return token;
+  }
+  const data = await apiGet("/v1/auth/info", {
+    token,
+    traceId: context.globalOptions.traceId,
+    timeout: context.globalOptions.timeout,
+    baseUrl: context.globalOptions.baseUrl,
+  });
+  return context.ok("auth info", data);
+}
+
+export async function executeAuthValidate(context) {
+  const token = await requireToken(context);
+  if (typeof token !== "string") {
+    return token;
+  }
+  const data = await apiGet("/v1/auth/validate", {
+    token,
+    traceId: context.globalOptions.traceId,
+    timeout: context.globalOptions.timeout,
+    baseUrl: context.globalOptions.baseUrl,
+  });
+  return context.ok("auth validate", data);
+}
+
+export async function executeAuthCharges(context, tokens) {
+  const token = await requireToken(context);
+  if (typeof token !== "string") {
+    return token;
+  }
+
+  const options = context.parseCommandFlags(tokens);
+  const query = new URLSearchParams();
+  const mapping = {
+    "model-id": "model_id",
+    "charge-type": "charge_type",
+    "user-level": "user_level",
+    "start-at": "start_at",
+    "end-at": "end_at",
+  };
+
+  for (const [flag, field] of Object.entries(mapping)) {
+    if (options[flag] !== undefined) {
+      query.set(field, String(options[flag]));
+    }
+  }
+
+  if (options.limit !== undefined) {
+    query.set("limit", String(parseInteger(options.limit) ?? 20));
+  }
+  if (options.offset !== undefined) {
+    query.set("offset", String(parseInteger(options.offset) ?? 0));
+  }
+
+  const suffix = query.toString() ? `?${query.toString()}` : "";
+  const data = await apiGet(`/v1/auth/charges${suffix}`, {
+    token,
+    traceId: context.globalOptions.traceId,
+    timeout: context.globalOptions.timeout,
+    baseUrl: context.globalOptions.baseUrl,
+  });
+  return context.ok("auth charges", data);
+}
+
+export async function executeAuthStatus(context) {
+  const { token, source } = await getTokenWithSource();
+  return context.ok("auth status", {
+    token_present: Boolean(token),
+    token_source: source,
+    token_masked: maskToken(token),
+    config_path: getConfigPath(),
+  });
+}

package/src/ycloud/commands/commands.js

@@ -0,0 +1,262 @@
+import { getGlobalFlagsHelp } from "./shared.js";
+
+export function getCommandsHelp(subcommand) {
+  if (subcommand === "list") {
+    return `List all exposed CLI commands for Agent usage
+
+Usage:
+  ycloud commands list
+
+Optional Flags:
+  none
+
+${getGlobalFlagsHelp()}
+`;
+  }
+
+  if (subcommand === "describe") {
+    return `Describe one exposed command
+
+Usage:
+  ycloud commands describe <command-key>
+
+Optional Flags:
+  none
+
+${getGlobalFlagsHelp()}
+
+Examples:
+  ycloud commands describe auth.validate
+  ycloud commands describe social.bilibili-fetch-one-video-v3
+`;
+  }
+
+  return `Commands discovery
+
+Usage:
+  ycloud commands <list|describe> [flags]`;
+}
+
+function buildStaticCommands() {
+  return [
+    {
+      key: "auth.validate",
+      command: "auth validate",
+      kind: "api",
+      description: "Validate current API token",
+      api_path: "/v1/auth/validate",
+      method: "GET",
+      flags: [],
+    },
+    {
+      key: "auth.info",
+      command: "auth info",
+      kind: "api",
+      description: "Get current token account info",
+      api_path: "/v1/auth/info",
+      method: "GET",
+      flags: [],
+    },
+    {
+      key: "auth.charges",
+      command: "auth charges",
+      kind: "api",
+      description: "List token billing charge records",
+      api_path: "/v1/auth/charges",
+      method: "GET",
+      flags: [
+        { flag: "--model-id", required: false },
+        { flag: "--charge-type", required: false },
+        { flag: "--user-level", required: false },
+        { flag: "--start-at", required: false },
+        { flag: "--end-at", required: false },
+        { flag: "--limit", required: false },
+        { flag: "--offset", required: false },
+      ],
+    },
+    {
+      key: "auth.status",
+      command: "auth status",
+      kind: "local",
+      description: "Show current token source and masked token",
+      flags: [],
+    },
+    {
+      key: "health.check",
+      command: "health check",
+      kind: "api",
+      description: "Check cloud service health",
+      api_path: "/v1/health",
+      method: "GET",
+      flags: [],
+    },
+    {
+      key: "version.check",
+      command: "version check",
+      kind: "api",
+      description: "Check remote version update information",
+      api_path: "/v1/version/check",
+      method: "GET",
+      flags: [
+        { flag: "--app-id", required: false },
+        { flag: "--platform", required: false },
+        { flag: "--channel", required: false },
+        { flag: "--current-version", required: false },
+        { flag: "--current-build", required: false },
+      ],
+    },
+    {
+      key: "tool.catalog",
+      command: "tool catalog",
+      kind: "api",
+      description: "List server tool catalog",
+      api_path: "/v1/tools/catalog",
+      method: "GET",
+      flags: [],
+    },
+    {
+      key: "tool.execute",
+      command: "tool execute",
+      kind: "local",
+      description: "Execute only registered tool_id values through CLI",
+      flags: [
+        { flag: "--tool-id", required: true },
+        { flag: "--params", required: false },
+        { flag: "--params-file", required: false },
+        { flag: "--session-id", required: false },
+        { flag: "--idempotency-key", required: false },
+      ],
+    },
+    {
+      key: "kb.search",
+      command: "kb search",
+      kind: "api",
+      description: "Search knowledge base content",
+      api_path: "/v1/knowledge-base/search",
+      method: "POST",
+      flags: [
+        { flag: "--query", required: true },
+        { flag: "--top-k", required: false },
+        { flag: "--min-score", required: false },
+        { flag: "--course-name", required: false },
+      ],
+    },
+    {
+      key: "analysis.creator-profile",
+      command: "analysis creator-profile",
+      kind: "api",
+      description: "Analyze Douyin creator profile",
+      api_path: "/v1/analysis/douyin/creator-profile",
+      method: "POST",
+      flags: [
+        { flag: "--profile-url", required: true },
+        { flag: "--video-limit", required: false },
+      ],
+    },
+    {
+      key: "compliance.check",
+      command: "compliance check",
+      kind: "api",
+      description: "Check compliance risk for content",
+      api_path: "/v1/compliance/check",
+      method: "POST",
+      flags: [
+        { flag: "--content", required: false },
+        { flag: "--content-file", required: false },
+        { flag: "--project-id", required: false },
+        { flag: "--metadata", required: false },
+        { flag: "--metadata-file", required: false },
+      ],
+    },
+    {
+      key: "config.set-token",
+      command: "config set-token",
+      kind: "local",
+      description: "Store token into local CLI config file",
+      flags: [{ flag: "<token>", required: true }],
+    },
+    {
+      key: "config.get",
+      command: "config get",
+      kind: "local",
+      description: "Read current CLI config",
+      flags: [],
+    },
+    {
+      key: "config.clear-token",
+      command: "config clear-token",
+      kind: "local",
+      description: "Clear stored token from local CLI config",
+      flags: [],
+    },
+  ];
+}
+
+function buildToolCommands(toolRegistry, catalogMap) {
+  const rows = [];
+  for (const [domain, domainConfig] of Object.entries(toolRegistry)) {
+    for (const [subcommand, commandConfig] of Object.entries(domainConfig.commands)) {
+      const catalogItem = catalogMap.get(commandConfig.toolId);
+      const properties = catalogItem?.schema?.properties || {};
+      const flags = Object.keys(properties).map((name) => ({
+        flag: `--${name.replace(/_/g, "-")}`,
+        required: (catalogItem?.schema?.required || []).includes(name),
+      }));
+      rows.push({
+        key: `${domain}.${subcommand}`,
+        command: `${domain} ${subcommand}`,
+        kind: "tool",
+        description: catalogItem?.description || commandConfig.description,
+        tool_id: commandConfig.toolId,
+        exposed: true,
+        flags,
+      });
+    }
+  }
+  return rows;
+}
+
+export function buildExposedCommands(toolRegistry, catalogMap) {
+  return [
+    ...buildStaticCommands().map((item) => ({ ...item, exposed: true })),
+    ...buildToolCommands(toolRegistry, catalogMap),
+  ].sort((left, right) => left.command.localeCompare(right.command));
+}
+
+export async function executeCommandsList(context, exposedCommands) {
+  return context.ok("commands list", {
+    commands: exposedCommands.map((item) => ({
+      key: item.key,
+      command: item.command,
+      kind: item.kind,
+      exposed: true,
+      description: item.description,
+    })),
+  });
+}
+
+export async function executeCommandsDescribe(context, tokens, exposedCommands) {
+  const key = tokens[0];
+  if (!key) {
+    return context.fail(
+      "commands describe",
+      "BAD_ARGUMENT",
+      "缺少命令标识，例如 social.bilibili-fetch-one-video-v3",
+      2,
+      false,
+    );
+  }
+
+  const match = exposedCommands.find((item) => item.key === key);
+  if (!match) {
+    return context.fail(
+      "commands describe",
+      "BAD_ARGUMENT",
+      `未找到命令: ${key}`,
+      2,
+      false,
+    );
+  }
+
+  return context.ok("commands describe", match);
+}