openclawmp 1.0.3 → 1.0.5

package/README.md

@@ -1,8 +1,8 @@
 # 🐟 openclawmp
 
-**OpenClaw Marketplace CLI** — 水产市场命令行工具
+**OpenClaw Marketplace CLI** — 面向 OpenClaw Marketplace 的命令行工具。
 
-A command-line client for the [OpenClaw Marketplace](https://openclawmp.stepfun.com), allowing you to search, install, publish, and manage agent assets (skills, plugins, triggers, channels, and more).
+用于在终端中完成资产搜索、用户搜索、详情查看、评论、安装、卸载、列表查看和发布等常用操作。当前支持的资产类型包括 `skill`、`experience`、`plugin`、`trigger`、`channel`。
 
 ## 安装
 
@@ -10,7 +10,7 @@ A command-line client for the [OpenClaw Marketplace](https://openclawmp.stepfun.
 npm install -g openclawmp
 ```
 
-需要 Node.js `>=18.0.0`。项目使用 Node 内置 `fetch`，无额外运行时依赖。
+运行要求：Node.js `>=18.0.0`。项目使用 Node 内置 `fetch`，无额外运行时依赖。
 
 ## 快速开始
 
@@ -18,13 +18,13 @@ npm install -g openclawmp
 # 写入本地 token
 openclawmp oauth <your-token>
 
+# 查看本地登录状态
+openclawmp login
+
 # 搜索市场资产
 openclawmp search 天气
 
-# 搜索用户
-openclawmp users 张三
-
-# 根据 assetId 查看资产详情
+# 查看资产详情
 openclawmp info 6c476a36955a4270a3fa303beeeed5ee
 
 # 安装资产
@@ -40,150 +40,174 @@ openclawmp uninstall skill/demo-skill
 openclawmp publish ./my-asset --yes
 ```
 
-## 功能概览
-
-- `search`：搜索市场资产，按类型、作者、安装量、标签和简介格式化输出。
-- `users`：搜索用户，默认展示前 10 条，并显示总结果数与下一页游标。
-- `oauth`：将 token 写入本地凭证文件。
-- `info`：根据 `assetId` 查看资产详情与版本信息。
-- `install`：根据 `assetId` 和可选 `semver` 下载归档并安装到本地 OpenClaw 目录。
-- `uninstall`：删除本地安装目录，并清理对应锁文件记录。
-- `list`：扫描本地已安装资产，结合 lockfile 和安装元数据展示结果。
-- `publish`：打包本地目录并上传发布，串联 `createUpload`、`signUploadPartUrl`、`completeUpload`、`createAssetSemver`。
+## 命令概览
 
-## 支持的资产类型
+| 命令 | 说明 |
+| --- | --- |
+| `login` | 查看当前本地 token 状态和凭证文件位置。 |
+| `oauth` | 将 token 写入本地凭证文件。 |
+| `search` | 按关键词搜索市场资产，并展示类型、作者、安装量、标签和简介等信息。 |
+| `users` | 按关键词搜索用户，默认展示前 10 条，并显示总结果数与下一页游标。 |
+| `info` | 根据 `assetId` 查看资产详情和版本信息。 |
+| `createComment` | 给指定资产发送文本评论；当前用法为 `openclawmp createComment <assetId> <content>`，需要默认本地 token。 |
+| `install` | 根据 `type/assetId` 和可选版本号下载并安装资产到本地目录。 |
+| `list` | 扫描本地已安装资产，并结合锁文件和安装元数据展示结果。 |
+| `uninstall` | 删除本地安装目录，并清理对应锁文件记录。 |
+| `publish` | 校验、打包并发布本地资产目录或归档。 |
 
-- `skill`
-- `experience`
-- `plugin`
-- `trigger`
-- `channel`
-
-## 运行要求
-
-- Node.js `>=18.0.0`
-- 零运行时依赖
+> 查看某个命令的完整参数：`openclawmp help <command>` 或 `openclawmp <command> --help`。
 
 ## 凭证
 
-默认读取：
+默认凭证文件：
 
-- macOS / Linux: `~/.openclaw/hub-credentials.json`
-- Windows: `%USERPROFILE%\\.openclaw\\hub-credentials.json`
+- macOS / Linux：`~/.openclaw/hub-credentials.json`
+- Windows：`%USERPROFILE%\.openclaw\hub-credentials.json`
 
-文件最少需要：
+文件最少需要包含：
 
 ```json
 {
-    "token": "your-credential-token"
+  "token": "your-credential-token"
 }
 ```
 
-也可以直接通过命令写入：
+写入或查看凭证：
 
 ```bash
 openclawmp oauth <your-token>
+openclawmp login
 ```
 
-请求头约定：
-
-- `Authorization: Bearer <credential token>`：受保护接口必需；`search` 可匿名调用
-- `X-Request-ID`：自动生成，也可通过 `--request-id` 显式指定
-- `Cli-Version`：自动带当前 package 版本
+需要登录态的命令会读取本地 token；部分命令也支持通过 `--token-file <path>` 指定其他凭证文件，具体以命令帮助为准。
 
 ## 常用示例
 
-```bash
-npm install -g openclawmp
-openclawmp oauth <your-token>
-openclawmp publish /path/to/asset
-```
-
-示例：
+### 搜索资产和用户
 
 ```bash
-cat .metadata.json
+openclawmp search 天气 --page-size 10
+openclawmp search "stock realtime" --page-size 10
+openclawmp users openclawmp.cc
+openclawmp users 窦窦 --page-size 20
 ```
 
-```json
-{
-    "assetType": "skill",
-    "name": "my-skill",
-    "displayName": "My Skill",
-    "semver": "1.0.0",
-    "category": "productivity",
-    "tags": ["agent", "automation"]
-}
-```
+### 查看资产详情
 
 ```bash
-openclawmp publish ./my-skill --yes
+openclawmp info 6c476a36955a4270a3fa303beeeed5ee
 ```
 
-查看资产详情：
+### 发送资产评论
 
 ```bash
-openclawmp info 6c476a36955a4270a3fa303beeeed5ee
+openclawmp createComment 8ec77f07430644bc3a848235d5c8d911 "这个资产很有帮助"
 ```
 
-更新已有资产版本：
+### 安装资产
 
 ```bash
-openclawmp publish ./my-skill --asset-id s-123456 --yes
+openclawmp install skill/7c19dc4c3244418096f1dcb59c93f795
+openclawmp install skill/7c19dc4c3244418096f1dcb59c93f795@1.0.3
+openclawmp install skill/7c19dc4c3244418096f1dcb59c93f795 --version 1.0.3
 ```
 
-如果目录根部已存在 `.assetid`，会自动把该值透传为 `assetId`；也可显式传入 `--asset-id <id>`。
+默认安装根会优先跟随当前 OpenClaw / StepClaw state dir：
 
-只做本地校验和打包：
+1. `OPENCLAWMP_INSTALL_ROOT`
+2. `OPENCLAW_STATE_DIR` 或 `STEPCLAW_STATE_DIR`
+3. `~/.stepclaw/stepclaw-install-state.json` 中记录的 state dir
+4. 检测到 `~/.stepclaw` 时使用该目录
+5. 否则回退到 `~/.openclaw`
 
-```bash
-openclawmp publish ./my-skill --dry-run
-```
+不同资产类型的默认子目录：
 
-安装示例：
+| 类型 | 默认子目录 |
+| --- | --- |
+| `skill` | `skills` |
+| `plugin` / `channel` | `extensions` |
+| `trigger` | `triggers` |
+| `experience` | `experiences` |
 
-```bash
-openclawmp install skill/7c19dc4c3244418096f1dcb59c93f795
-openclawmp install skill/7c19dc4c3244418096f1dcb59c93f795@1.0.3
-```
+也可以通过 `--target-dir <path>` 显式指定安装根目录。
 
-卸载示例：
+### 列出和卸载本地资产
 
 ```bash
+openclawmp list
+openclawmp list --type skill
 openclawmp uninstall skill/7c19dc4c3244418096f1dcb59c93f795
 openclawmp uninstall skill/demo-skill
+openclawmp uninstall skill/@author/name
+```
+
+### 发布资产
+
+发布目录或归档中必须包含 `.metadata.json`：
+
+```json
+{
+  "assetType": "skill",
+  "name": "my-skill",
+  "displayName": "My Skill",
+  "semver": "1.0.0",
+  "category": "productivity",
+  "tags": ["agent", "automation"],
+  "description": "A short description"
+}
 ```
 
-搜索示例：
+发布示例：
 
 ```bash
-openclawmp search 天气 --page-size 10
-openclawmp users openclawmp.cc
+openclawmp publish ./my-skill --yes
+openclawmp publish ./my-skill --asset-id s-123456 --yes
+openclawmp publish ./my-skill --dry-run
 ```
 
-## 命令结构
+如果目录根部存在 `.assetid`，发布时会自动作为目标资产 ID 使用；也可通过 `--asset-id <id>` 显式指定。
+
+`--dry-run` 只做本地校验和打包，不提交发布。
+
+## 发布 Metadata 规则
+
+- `publish` 只读取发布目录或归档里的 `.metadata.json`。
+- `.metadata.json` 必须包含 `assetType`、`name`、`displayName`、`semver`。
+- `assetType` 支持：`skill`、`experience`、`plugin`、`trigger`、`channel`。
+- `semver` 必须是严格的 `x.y.z` 纯数字格式，例如 `1.2.3`。
+- 可选字段：`assetId`、`category`、`tags`、`description`、`longDescription`。
+- 不再从 `README.md`、`package.json`、`openclaw.plugin.json`、`SKILL.md` 自动推断发布 metadata。
+- 不再通过 CLI 参数补录 `assetType`、`name`、`displayName`、`semver`。
+- `assetId` 可写在 `.metadata.json`，也可以通过 `--asset-id` 或目录根部 `.assetid` 传入。
+- 默认不打印请求细节；加 `--verbose` 会额外输出调试信息。
+
+## 发布打包规则
+
+- 目录发布会默认跳过 `.git`、`node_modules`、`__MACOSX`、`.DS_Store`、`Thumbs.db`。
+- 根目录可通过 `.openclawmpignore` 补充忽略规则，也会读取根目录 `.gitignore` / `.npmignore` 的常见规则。
+- 子路径遇到无权限读取的目录或文件时会自动跳过；使用 `--verbose` 可查看具体跳过项。
 
-入口采用懒加载：
+## 常用参数
 
-- `publish`
-- `oauth`
-- `search`
-- `users`
-- `info`
-- `install`
-- `uninstall`
-- `list`
+不同命令支持的参数略有差异，请以 `--help` 输出为准。常见参数包括：
 
-其中当前可用的是 `publish`、`oauth`、`search`、`users`、`info`、`install`、`uninstall`、`list`。
+| 参数 | 说明 |
+| --- | --- |
+| `--base-url <url>` | 指定服务基地址。 |
+| `--token-file <path>` | 指定本地凭证文件。 |
+| `--request-id <id>` | 指定请求追踪 ID。 |
+| `--page-size <number>` | 指定搜索分页大小。 |
+| `--page-token <token>` | 指定下一页游标。 |
+| `--verbose` | 输出更多调试信息。 |
+| `-h, --help` | 查看帮助。 |
+| `-v, --version` | 查看版本。 |
 
-## 发布命令参数
+服务基地址优先级：
 
-- `--asset-id <id>`：未传时会尝试读取目录根部 `.assetid`
-- `--base-url <url>`
-- `--token-file <path>`
-- `--part-size-mb <number>`
-- `--ttl-seconds <number>`
-- `--request-id <id>`
-- `--dry-run`
-- `--yes, -y`
-- `--verbose`
+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://openclawmp.stepfun.com`

package/bin/openclawmp.js

@@ -27,6 +27,9 @@ const COMMAND_LOADERS = {
   users: function loadUsers() {
     return require("../lib/commands/users");
   },
+  createComment: function loadCreateComment() {
+    return require("../lib/commands/create-comment");
+  },
   info: function loadInfo() {
     return require("../lib/commands/info");
   },

package/lib/api.js

@@ -11,6 +11,7 @@ const {
 
 const CATALOG_SERVICE = "step.seafood.catalog.CatalogService";
 const IDENTITY_SERVICE = "step.seafood.identity.IdentityService";
+const ENGAGEMENT_SERVICE = "step.seafood.engagement.EngagementService";
 
 class ApiError extends Error {
   constructor(message, details) {
@@ -245,6 +246,9 @@ function createCatalogClient(options) {
     searchUsers: function searchUsers(body, extra) {
       return unaryForService(IDENTITY_SERVICE, "SearchUsers", body, extra);
     },
+    createComment: function createComment(body, extra) {
+      return unaryForService(ENGAGEMENT_SERVICE, "CreateComment", body, extra);
+    },
     listUserAssets: function listUserAssets(body, extra) {
       return unary("ListUserAssets", body, extra);
     },

package/lib/commands/create-comment.js

@@ -0,0 +1,130 @@
+"use strict";
+
+const { parseOptions } = require("../cli-parser");
+const { CLI_NAME } = require("../cli-text");
+const { createCatalogClient } = require("../api");
+const { loadHubCredentials } = require("../credentials");
+const { defaultCredentialsPath, resolveConnectBaseUrl } = require("../config");
+const { generateRequestId, trimOrUndefined } = require("../utils");
+
+function printHelp() {
+  console.log(CLI_NAME + " createComment");
+  console.log("");
+  console.log("用法:");
+  console.log("  " + CLI_NAME + " createComment <assetId> <content>");
+  console.log("");
+  console.log("说明:");
+  console.log("  调用 step.seafood.engagement.EngagementService/CreateComment 发送文本评论。");
+  console.log("  命令只支持最简单的 assetId + 评论内容用法。");
+  console.log("  baseUrl 和 token 读取方式与 publish 命令一致。");
+  console.log("");
+  console.log("示例:");
+  console.log("  " + CLI_NAME + " createComment 8ec77f07430644bc3a848235d5c8d911 \"agrent\"");
+}
+
+function firstText(values) {
+  return values.find(function findValue(value) {
+    return typeof value === "string" && value.trim();
+  }) || "";
+}
+
+function parseArguments(positionals) {
+  const args = Array.isArray(positionals) ? positionals : [];
+  const assetId = trimOrUndefined(args[0]) || "";
+  const content = args.slice(1).join(" ").trim();
+
+  if (!assetId) {
+    throw new Error("createComment 命令缺少 assetId");
+  }
+  if (/\s/u.test(assetId) || assetId.includes("/")) {
+    throw new Error("createComment 命令的 assetId 格式不正确");
+  }
+  if (!content) {
+    throw new Error("createComment 命令缺少评论内容");
+  }
+
+  return {
+    assetId,
+    content
+  };
+}
+
+function buildCreateCommentRequest(assetId, content) {
+  return {
+    assetId,
+    contentSegments: [
+      {
+        type: "COMMENT_CONTENT_TYPE_TEXT",
+        text: content
+      }
+    ]
+  };
+}
+
+function resolveCommentId(data) {
+  if (!data || typeof data !== "object") {
+    return "";
+  }
+
+  return firstText([
+    data.commentId,
+    data.id,
+    data.comment && data.comment.commentId,
+    data.comment && data.comment.id
+  ]);
+}
+
+function loadCommentCredentials() {
+  try {
+    return loadHubCredentials();
+  } catch {
+    throw new Error(
+      [
+        "未检测到可用于发送评论的登录态。",
+        "请先通过 " + CLI_NAME + " oauth <token> 写入 token，或手动写入 " + defaultCredentialsPath() + "。"
+      ].join("\n")
+    );
+  }
+}
+
+async function run(context) {
+  const parsed = parseOptions(context.argv, {});
+  const args = parseArguments(parsed.positionals);
+  const loadedCredentials = loadCommentCredentials();
+  const requestId = generateRequestId();
+  const client = createCatalogClient({
+    baseUrl: resolveConnectBaseUrl(),
+    token: loadedCredentials.credentials.token,
+    cliVersion: context.cliVersion,
+    requestId
+  });
+
+  const response = await client.createComment(
+    buildCreateCommentRequest(args.assetId, args.content)
+  );
+  const data = response.data || {};
+  const commentId = resolveCommentId(data);
+
+  console.log("");
+  console.log("评论发送成功");
+  console.log("- assetId: " + args.assetId);
+  if (commentId) {
+    console.log("- commentId: " + commentId);
+  }
+  console.log("- 内容: " + args.content);
+
+  return {
+    assetId: args.assetId,
+    content: args.content,
+    commentId,
+    data,
+    requestId: response.requestId
+  };
+}
+
+module.exports = {
+  buildCreateCommentRequest,
+  parseArguments,
+  printHelp,
+  run
+};

package/lib/commands/help.js

@@ -22,6 +22,9 @@ const COMMAND_LOADERS = {
   users: function loadUsers() {
     return require("./users");
   },
+  createComment: function loadCreateComment() {
+    return require("./create-comment");
+  },
   info: function loadInfo() {
     return require("./info");
   },

package/lib/commands/install.js

@@ -33,11 +33,12 @@ function printHelp() {
   console.log("  install 需要本地 token，默认读取 ~/.openclaw/hub-credentials.json");
   console.log("  可通过 --token-file <path> 指定其他凭证文件");
   console.log("  默认安装目录:");
-  console.log("    skill -> ~/.openclaw/skills");
-  console.log("    plugin -> ~/.openclaw/extensions");
-  console.log("    channel -> ~/.openclaw/extensions");
-  console.log("    trigger -> ~/.openclaw/triggers");
-  console.log("    experience -> ~/.openclaw/experiences");
+  console.log("    优先跟随当前 OpenClaw/StepClaw state dir（OPENCLAW_STATE_DIR、STEPCLAW_STATE_DIR 或 ~/.stepclaw）");
+  console.log("    未检测到 StepClaw 时回退到 ~/.openclaw");
+  console.log("    skill -> <state-dir>/skills 或 ~/.openclaw/skills");
+  console.log("    plugin/channel -> <state-dir>/extensions 或 ~/.openclaw/extensions");
+  console.log("    trigger -> <state-dir>/triggers 或 ~/.openclaw/triggers");
+  console.log("    experience -> <state-dir>/experiences 或 ~/.openclaw/experiences");
   console.log("");
   console.log("示例:");
   console.log("  " + buildInstallCommand("skill", "7c19dc4c3244418096f1dcb59c93f795"));

package/lib/config.js

@@ -17,6 +17,12 @@ const INSTALL_ROOT_BY_TYPE = {
     experience: ["experiences"],
     template: ["templates"],
 };
+const OPENCLAWMP_INSTALL_ROOT_ENV = "OPENCLAWMP_INSTALL_ROOT";
+const OPENCLAW_STATE_DIR_ENV = "OPENCLAW_STATE_DIR";
+const STEPCLAW_STATE_DIR_ENV = "STEPCLAW_STATE_DIR";
+const STEPCLAW_STATE_DIR_NAME = ".stepclaw";
+const STEPCLAW_INSTALL_STATE_FILE = "stepclaw-install-state.json";
+const STEPCLAW_RUNTIME_STATE_FILE = "stepclaw-state.json";
 
 function parseEnvFile(content) {
     const result = {};
@@ -68,6 +74,26 @@ function firstDefined(values) {
     });
 }
 
+function trimString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+
+function expandHomePath(value) {
+    const trimmed = trimString(value);
+    if (trimmed === "~") {
+        return os.homedir();
+    }
+    if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) {
+        return path.join(os.homedir(), trimmed.slice(2));
+    }
+    return trimmed;
+}
+
+function resolvePathValue(value) {
+    const expanded = expandHomePath(value);
+    return expanded ? path.resolve(expanded) : "";
+}
+
 function normalizeBaseUrl(value) {
     return String(value)
         .trim()
@@ -100,6 +126,53 @@ function getOpenClawHome() {
     return path.join(os.homedir(), ".openclaw");
 }
 
+function getDefaultStepClawStateDir() {
+    return path.join(os.homedir(), STEPCLAW_STATE_DIR_NAME);
+}
+
+function readJsonFileIfExists(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    } catch (error) {
+        return null;
+    }
+}
+
+function looksLikeStepClawStateDir(stateDir) {
+    return (
+        fs.existsSync(path.join(stateDir, "openclaw.json")) ||
+        fs.existsSync(path.join(stateDir, STEPCLAW_INSTALL_STATE_FILE)) ||
+        fs.existsSync(
+            path.join(stateDir, "runtime", STEPCLAW_RUNTIME_STATE_FILE),
+        )
+    );
+}
+
+function resolveStepClawStateDir() {
+    const envStateDir = firstDefined([
+        process.env[OPENCLAW_STATE_DIR_ENV],
+        process.env[STEPCLAW_STATE_DIR_ENV],
+    ]);
+    if (envStateDir) {
+        return resolvePathValue(envStateDir);
+    }
+
+    const defaultStateDir = getDefaultStepClawStateDir();
+    const presence = readJsonFileIfExists(
+        path.join(defaultStateDir, STEPCLAW_INSTALL_STATE_FILE),
+    );
+    const redirectedStateDir = trimString(presence && presence.stateDir);
+    if (redirectedStateDir) {
+        return resolvePathValue(redirectedStateDir);
+    }
+
+    if (looksLikeStepClawStateDir(defaultStateDir)) {
+        return defaultStateDir;
+    }
+
+    return "";
+}
+
 function defaultCredentialsPath() {
     return path.join(getOpenClawHome(), "hub-credentials.json");
 }
@@ -109,7 +182,14 @@ function getLockfilePath() {
 }
 
 function getManagedAssetsRoot() {
-    return getOpenClawHome();
+    const explicitInstallRoot = firstDefined([
+        process.env[OPENCLAWMP_INSTALL_ROOT_ENV],
+    ]);
+    if (explicitInstallRoot) {
+        return resolvePathValue(explicitInstallRoot);
+    }
+
+    return resolveStepClawStateDir() || getOpenClawHome();
 }
 
 function getInstallRoot(assetType) {
@@ -126,6 +206,8 @@ module.exports = {
     resolveApiBaseUrl,
     resolveConnectBaseUrl,
     getOpenClawHome,
+    getDefaultStepClawStateDir,
+    resolveStepClawStateDir,
     defaultCredentialsPath,
     getLockfilePath,
     getManagedAssetsRoot,

package/lib/help.js

@@ -33,6 +33,11 @@ const COMMAND_SECTIONS = [
     description: "搜索用户",
     usage: CLI_NAME + " users <keyword> [options]"
   },
+  {
+    name: "createComment",
+    description: "发送资产评论",
+    usage: CLI_NAME + " createComment <assetId> <content>"
+  },
   {
     name: "info",
     description: "查看某个资产的详细信息",
@@ -63,7 +68,7 @@ function printGlobalHelp() {
   console.log("");
   console.log("命令:");
   COMMAND_SECTIONS.forEach(function eachSection(section) {
-    const paddedName = (section.name + "          ").slice(0, 12);
+    const paddedName = (section.name + "               ").slice(0, 15);
     console.log("  " + paddedName + section.description);
   });
   console.log("");
@@ -82,6 +87,7 @@ function printGlobalHelp() {
   console.log("  " + CLI_NAME + " publish ./my-asset --yes");
   console.log("  " + CLI_NAME + " search 天气");
   console.log("  " + CLI_NAME + " users openclawmp.cc");
+  console.log("  " + CLI_NAME + " createComment 8ec77f07430644bc3a848235d5c8d911 \"agrent\"");
   console.log("  " + CLI_NAME + " info 6c476a36955a4270a3fa303beeeed5ee");
   console.log("  " + buildInstallCommand("skill", "7c19dc4c3244418096f1dcb59c93f795"));
   console.log("  " + buildInstallCommand("skill", "7c19dc4c3244418096f1dcb59c93f795", "1.0.3"));

package/lib/utils.js

@@ -199,6 +199,8 @@ function humanizeApiMethodName(methodName) {
       return "搜索资产";
     case "SearchUsers":
       return "搜索用户";
+    case "CreateComment":
+      return "发送评论";
     case "ListUserAssets":
       return "查询用户资产";
     case "GetAsset":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclawmp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "OpenClaw Marketplace CLI client",
   "bin": {
     "openclawmp": "bin/openclawmp.js"