openclawmp 0.1.6 → 1.0.0-alpha.0

package/README.md

@@ -4,176 +4,194 @@
 
 A command-line client for the [OpenClaw Marketplace](https://openclawmp.cc), allowing you to search, install, publish, and manage agent assets (skills, plugins, triggers, channels, and more).
 
-## Installation
+## 安装
 
 ```bash
 npm install -g openclawmp
 ```
 
-Requires **Node.js 18+** (uses built-in `fetch`).
+需要 Node.js `>=18.0.0`。项目使用 Node 内置 `fetch`，无额外运行时依赖。
 
-## Quick Start
+## 快速开始
 
 ```bash
-# Search for assets
-openclawmp search "web search"
+# 搜索市场资产
+openclawmp search 天气
 
-# Install a skill
-openclawmp install skill/@cybernova/web-search
+# 查看资产详情
+openclawmp info 7c19dc4c3244418096f1dcb59c93f795
 
-# List installed assets
+# 安装资产
+openclawmp install skill/7c19dc4c3244418096f1dcb59c93f795
+
+# 安装指定版本
+openclawmp install skill/7c19dc4c3244418096f1dcb59c93f795@1.0.3
+
+# 列出本地已安装资产
 openclawmp list
 
-# View asset details
-openclawmp info skill/web-search
+# 卸载本地资产
+openclawmp uninstall skill/demo-skill
 
-# Publish your own skill
-openclawmp publish ./my-skill
+# 发布本地资产
+openclawmp publish ./my-skill --type skill --version 1.0.0 --yes
 ```
 
-## Commands
+## 功能概览
 
-### `openclawmp search <query>`
+- `search`：搜索市场资产，按类型、作者、安装量、标签和简介格式化输出。
+- `info`：查看资产详情与版本信息。
+- `install`：根据 `assetId` 和可选 `semver` 下载归档并安装到本地 OpenClaw 目录。
+- `uninstall`：删除本地安装目录，并清理对应锁文件记录。
+- `list`：扫描本地已安装资产，结合 lockfile 和安装元数据展示结果。
+- `publish`：打包本地目录并上传发布，串联 `createUpload`、`signUploadPartUrl`、`completeUpload`、`createAssetSemver`。
 
-Search the marketplace for assets.
+## 支持的资产类型
 
-```bash
-openclawmp search "文件监控"
-openclawmp search weather
-```
+- `skill`
+- `experience`
+- `plugin`
+- `trigger`
+- `channel`
 
-### `openclawmp install <type>/@<author>/<slug>`
+## 运行要求
 
-Install an asset from the marketplace.
+- Node.js `>=18.0.0`
+- 零运行时依赖
 
-```bash
-# Full format with author scope
-openclawmp install trigger/@xiaoyue/fs-event-trigger
-openclawmp install skill/@cybernova/web-search
+## 凭证
+
+默认读取：
 
-# Legacy format (no author)
-openclawmp install skill/web-search
+- macOS / Linux: `~/.openclaw/hub-credentials.json`
+- Windows: `%USERPROFILE%\\.openclaw\\hub-credentials.json`
 
-# Force overwrite existing
-openclawmp install skill/@cybernova/web-search --force
+文件最少需要：
+
+```json
+{
+    "token": "your-credential-token"
+}
 ```
 
-**Supported asset types:** `skill`, `config`, `plugin`, `trigger`, `channel`, `template`
+请求头约定：
 
-### `openclawmp list`
+- `Authorization: Bearer <credential token>`：受保护接口必需；`search` 可匿名调用
+- `X-Request-ID`：自动生成，也可通过 `--request-id` 显式指定
+- `Cli-Version`：自动带当前 package 版本
 
-List all assets installed via the marketplace.
+## 常用示例
 
 ```bash
-openclawmp list
+npm install -g openclawmp
+openclawmp publish /path/to/asset
 ```
 
-### `openclawmp uninstall <type>/<slug>`
-
-Remove an installed asset.
+示例：
 
 ```bash
-openclawmp uninstall skill/web-search
-openclawmp uninstall trigger/fs-event-trigger
+openclawmp publish ./my-skill \
+  --type skill \
+  --category productivity \
+  --tags agent,automation \
+  --version 1.0.0 \
+  --yes
 ```
 
-### `openclawmp info <type>/<slug>`
-
-View detailed information about an asset from the registry.
+更新已有资产版本：
 
 ```bash
-openclawmp info skill/web-search
-openclawmp info trigger/fs-event-trigger
+openclawmp publish ./my-skill --version 1.0.1 --yes
 ```
 
-### `openclawmp publish [path]`
+如果目录根部已存在 `.assetid`，会自动把该值透传为 `assetId`；也可显式传入 `--asset-id <id>`。
 
-Publish a local asset directory to the marketplace. Defaults to current directory.
+只做本地校验和打包：
 
 ```bash
-# Publish current directory
-openclawmp publish
-
-# Publish a specific directory
-openclawmp publish ./my-skill
-
-# Skip confirmation prompt
-openclawmp publish ./my-skill --yes
+openclawmp publish ./my-skill --dry-run
 ```
 
-The command will auto-detect the asset type from:
-1. `SKILL.md` frontmatter (for skills)
-2. `openclaw.plugin.json` (for plugins/channels)
-3. `package.json` (fallback)
-4. `README.md` (fallback)
-
-### `openclawmp login`
-
-Show device authorization information. Your OpenClaw device identity is used for publishing.
+安装示例：
 
 ```bash
-openclawmp login
+openclawmp install skill/7c19dc4c3244418096f1dcb59c93f795
+openclawmp install skill/7c19dc4c3244418096f1dcb59c93f795@1.0.3
 ```
 
-### `openclawmp whoami`
-
-Show current user/device info and configuration status.
+卸载示例：
 
 ```bash
-openclawmp whoami
+openclawmp uninstall skill/7c19dc4c3244418096f1dcb59c93f795
+openclawmp uninstall skill/demo-skill
 ```
 
-## Global Options
-
-| Option | Description |
-|--------|-------------|
-| `--api <url>` | Override the API base URL |
-| `--version`, `-v` | Show version |
-| `--help`, `-h` | Show help |
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `OPENCLAWMP_API` | Override the default API base URL (`https://openclawmp.cc`) |
-| `OPENCLAW_STATE_DIR` | Override the OpenClaw state directory (default: `~/.openclaw`) |
-| `NO_COLOR` | Disable colored output |
-
-## Configuration
-
-Configuration files are stored in `~/.openclawmp/`:
-
-- `auth.json` — Authentication token
-
-Install metadata is tracked in `~/.openclaw/seafood-lock.json` (shared with the OpenClaw ecosystem).
-
-## Asset Types
-
-| Type | Icon | Description |
-|------|------|-------------|
-| `skill` | 🧩 | Agent skills and capabilities |
-| `config` | ⚙️ | Configuration presets |
-| `plugin` | 🔌 | Gateway plugins |
-| `trigger` | ⚡ | Event triggers |
-| `channel` | 📡 | Communication channels |
-| `template` | 📋 | Project templates |
-
-## Development
+搜索示例：
 
 ```bash
-# Clone and run locally
-git clone https://github.com/openclaw/openclawmp.git
-cd openclawmp
-
-# Run directly
-node bin/openclawmp.js --help
-node bin/openclawmp.js search weather
-
-# Link globally for testing
-npm link
-openclawmp --help
+openclawmp search 天气 --page-size 10
 ```
 
-## License
-
-MIT
+## 命令结构
+
+入口采用懒加载：
+
+- `publish`
+- `search`
+- `install`
+- `uninstall`
+- `list`
+
+其中当前可用的是 `publish`、`search`、`install`、`uninstall`、`list`。
+
+## 发布命令参数
+
+- `--type <skill|experience|plugin|trigger|channel>`
+- `--asset-id <id>`：未传时会尝试读取目录根部 `.assetid`
+- `--name <slug>`
+- `--display-name <name>`
+- `--description <text>`
+- `--version <semver>`
+- `--category <category>`
+- `--tags <a,b,c>`
+- `--tag <value>`：可重复
+- `--long-description <text>`
+- `--base-url <url>`
+- `--token-file <path>`
+- `--part-size-mb <number>`
+- `--ttl-seconds <number>`
+- `--request-id <id>`
+- `--dry-run`
+- `--yes, -y`
+- `--verbose`
+
+## 目录发布打包规则
+
+- 目录发布会默认跳过 `.git`、`node_modules`、`__MACOSX`、`.DS_Store`、`Thumbs.db`
+- 根目录可通过 `.openclawmpignore` 补充忽略规则，也会读取根目录 `.gitignore` / `.npmignore` 的常见规则
+- 子路径遇到无权限读取的目录或文件时会自动跳过；使用 `--verbose` 可查看具体跳过项
+
+## Metadata 提取规则
+
+- 优先级：CLI 显式参数 > `.metadata.json` > `README.md` > `package.json` > `openclaw.plugin.json` > `SKILL.md`
+- `.metadata.json` 存在时会优先使用，适合显式固定 `type`、`name`、`displayName`、`description`、`version`、`category`、`tags`、`longDescription`
+- `SKILL.md` 的 `name`、`display-name`、`description`、`version`、`tags` 只从 frontmatter（`---` 到 `---`）提取，不会把正文内容混进 `description`
+- `README.md` 支持 YAML frontmatter 和前置 `key: value` 形式字段提取 `name`、`display-name`、`description`、`version`、`type`、`category`、`tags`
+- `trigger` / `experience` 会把 README 标题后的第一段作为描述兜底
+- 发布必填规则：`assetType`、`name`、`displayName`、`semver`
+- `version` 必须是严格的 `x.x.x` 形式，例如 `1.2.1`、`1.1.10`
+- `assetId` 为可选字段；有就透传，没有就省略，由后端判断是新建还是已有资产发新版
+- `objectId` 由上传完成后自动生成，登录态始终必需
+- 调用发布接口前会打印 `CreateAssetSemver` 请求预览；真正发网请求前会打印对应 request body
+
+## 默认配置来源
+
+`baseUrl` 优先级：
+
+1. `--base-url`
+2. `OPENCLAWMP_API_BASE_URL`
+3. `OPENCLAWMP_BASE_URL`
+4. `API_BASE_URL`
+5. `NEXT_PUBLIC_API_BASE_URL`
+6. 仓库根目录 `.env.local` / `.env` / `.env.prod`
+7. `https://seafood.c.stepfun-inc.net`

package/bin/openclawmp.js

@@ -1,85 +1,83 @@
 #!/usr/bin/env node
-// ============================================================================
-// 🐟 OpenClaw Marketplace CLI (openclawmp)
-//
-// Pure Node.js rewrite of seafood-market.sh
-// Zero external runtime dependencies
-// ============================================================================
 
-'use strict';
+const path = require("node:path");
 
-const path = require('path');
-const libDir = path.join(__dirname, '..', 'lib');
-const { parseArgs } = require(path.join(libDir, 'cli-parser.js'));
-const { printHelp } = require(path.join(libDir, 'help.js'));
+const pkg = require(path.join(__dirname, "..", "package.json"));
+const { parseCommandLine } = require("../lib/cli-parser");
+const { printGlobalHelp } = require("../lib/help");
+const { maybeNotifyAboutUpdates } = require("../lib/update-notifier");
+const { formatUserFacingError } = require("../lib/utils");
 
-// Command handlers (lazy-loaded)
-const cmdDir = path.join(libDir, 'commands');
-const commands = {
-  install:          () => require(path.join(cmdDir, 'install.js')),
-  uninstall:        () => require(path.join(cmdDir, 'uninstall.js')),
-  search:           () => require(path.join(cmdDir, 'search.js')),
-  list:             () => require(path.join(cmdDir, 'list.js')),
-  info:             () => require(path.join(cmdDir, 'info.js')),
-  publish:          () => require(path.join(cmdDir, 'publish.js')),
-  login:            () => require(path.join(cmdDir, 'login.js')),
-  authorize:        () => require(path.join(cmdDir, 'login.js')),  // alias
-  whoami:           () => require(path.join(cmdDir, 'whoami.js')),
-  star:             () => ({ run: (a, f) => require(path.join(cmdDir, 'star.js')).runStar(a, f) }),
-  unstar:           () => ({ run: (a, f) => require(path.join(cmdDir, 'star.js')).runUnstar(a, f) }),
-  comment:          () => ({ run: (a, f) => require(path.join(cmdDir, 'comment.js')).runComment(a, f) }),
-  comments:         () => ({ run: (a, f) => require(path.join(cmdDir, 'comment.js')).runComments(a, f) }),
-  issue:            () => ({ run: (a, f) => require(path.join(cmdDir, 'issue.js')).runIssue(a, f) }),
-  issues:           () => ({ run: (a, f) => require(path.join(cmdDir, 'issue.js')).runIssues(a, f) }),
-  'delete-account': () => require(path.join(cmdDir, 'delete-account.js')),
-  unbind:           () => require(path.join(cmdDir, 'unbind.js')),
-  help:             () => ({ run: () => printHelp() }),
+const COMMAND_LOADERS = {
+  help: function loadHelp() {
+    return require("../lib/commands/help");
+  },
+  login: function loadLogin() {
+    return require("../lib/commands/login");
+  },
+  publish: function loadPublish() {
+    return require("../lib/commands/publish");
+  },
+  search: function loadSearch() {
+    return require("../lib/commands/search");
+  },
+  info: function loadInfo() {
+    return require("../lib/commands/info");
+  },
+  install: function loadInstall() {
+    return require("../lib/commands/install");
+  },
+  uninstall: function loadUninstall() {
+    return require("../lib/commands/uninstall");
+  },
+  list: function loadList() {
+    return require("../lib/commands/list");
+  }
 };
 
 async function main() {
-  const { command, args, flags } = parseArgs(process.argv.slice(2));
+  const parsed = parseCommandLine(process.argv.slice(2));
 
-  // Handle version flag
-  if (flags.version || flags.v) {
-    const pkg = require(path.join(__dirname, '..', 'package.json'));
+  if (parsed.version) {
     console.log(pkg.version);
-    process.exit(0);
+    return;
   }
 
-  // Handle help flag or no command
-  if (flags.help || flags.h || command === 'help' || !command) {
-    printHelp();
-    process.exit(0);
+  if (!parsed.command) {
+    printGlobalHelp();
+    return;
   }
 
-  // Resolve command
-  const loader = commands[command];
-  if (!loader) {
-    const ui = require(path.join(libDir, 'ui.js'));
-    ui.err(`Unknown command: ${command}`);
-    console.log('');
-    printHelp();
-    process.exit(1);
+  const loadCommand = COMMAND_LOADERS[parsed.command];
+  if (!loadCommand) {
+    throw new Error("未知命令: " + parsed.command);
   }
 
-  // Override API base if --api flag or env var provided
-  if (flags.api || process.env.OPENCLAWMP_API) {
-    const config = require(path.join(libDir, 'config.js'));
-    config.setApiBase(flags.api || process.env.OPENCLAWMP_API);
-  }
+  const commandModule = loadCommand();
 
-  try {
-    const mod = loader();
-    await mod.run(args, flags);
-  } catch (e) {
-    const ui = require(path.join(libDir, 'ui.js'));
-    if (e.code === 'ENOTFOUND' || e.code === 'ECONNREFUSED') {
-      ui.err(`Cannot reach API server. Check your connection or use --api to set a custom endpoint.`);
-    } else {
-      ui.err(e.message || String(e));
+  if (parsed.help) {
+    if (typeof commandModule.printHelp === "function") {
+      commandModule.printHelp();
+      return;
     }
-    process.exit(1);
+    printGlobalHelp();
+    return;
   }
+
+  await commandModule.run({
+    argv: parsed.argv,
+    command: parsed.command,
+    cliVersion: pkg.version
+  });
+
+  await maybeNotifyAboutUpdates({
+    command: parsed.command,
+    packageName: pkg.name,
+    currentVersion: pkg.version
+  });
 }
 
-main();
+main().catch(function onError(error) {
+  console.error(formatUserFacingError(error, { title: "执行失败" }));
+  process.exitCode = 1;
+});