@storyclaw/talenthub 0.3.6 → 0.3.8

package/README.md

@@ -0,0 +1,273 @@
+# @storyclaw/talenthub
+
+CLI tool to manage StoryClaw AI agents — publish, install, update, and browse the TalentHub marketplace.
+
+[中文文档](#中文文档)
+
+## Install
+
+```bash
+npm install -g @storyclaw/talenthub
+```
+
+## Quick Start
+
+```bash
+# Login
+talenthub login
+
+# Initialize an agent
+talenthub agent init --dir ~/.openclaw/workspace-my-agent
+
+# Publish it
+talenthub agent publish --dir ~/.openclaw/workspace-my-agent
+
+# Browse & install agents
+talenthub agent search
+talenthub agent install <agent-name>
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `talenthub login` | Authenticate with StoryClaw |
+| `talenthub logout` | Remove stored credentials |
+| `talenthub agent init` | Initialize a new agent with manifest.json and prompt files |
+| `talenthub agent publish` | Publish a local agent to the registry |
+| `talenthub agent unpublish <name>` | Archive an agent from the registry |
+| `talenthub agent install <name>` | Install an agent and its skills |
+| `talenthub agent update [name]` | Update an agent or all agents (`--all`, `--json`) |
+| `talenthub agent uninstall <name>` | Remove an installed agent |
+| `talenthub agent list` | List installed agents and check for updates |
+| `talenthub agent search [query]` | Browse available agents |
+
+## Agent Structure
+
+A publishable agent directory contains:
+
+| File | Required | Description |
+|------|----------|-------------|
+| `manifest.json` | **Required** | Agent metadata (id, name, category, etc.) |
+| `IDENTITY.md` | Yes | Core identity and personality prompt |
+| `USER.md` | Optional | User-facing instructions |
+| `SOUL.md` | Optional | Deep personality and behavioral guidelines |
+| `AGENTS.md` | Optional | Multi-agent coordination instructions |
+
+### manifest.json
+
+```json
+{
+  "id": "my-agent",
+  "name": "My Agent",
+  "emoji": "🤖",
+  "role": "Assistant",
+  "tagline": "A helpful AI assistant",
+  "description": "Longer description of what this agent does.",
+  "category": "productivity",
+  "skills": [],
+  "i18n": {},
+  "minOpenClawVersion": "2026.3.1"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique identifier (lowercase alphanumeric + hyphens) |
+| `name` | string | Human-readable display name |
+| `emoji` | string | Single emoji icon |
+| `role` | string | Short role description |
+| `tagline` | string | One-line summary for search results |
+| `description` | string | Longer description for detail page |
+| `category` | string | One of: `creative`, `finance`, `productivity`, `companion`, `research`, `engineering` |
+| `skills` | string[] | Skill specs (e.g. `https://github.com/owner/repo@skill-name`) |
+| `i18n` | object | Translations keyed by locale (`zh-CN`, `zh-TW`, `ja`). Fill via web interface. |
+| `minOpenClawVersion` | string | Minimum StoryClaw version required |
+| `avatarUrl` | string \| null | Optional avatar image URL |
+
+> **Note:** Version is not in the manifest — it is generated automatically by the server.
+
+### Size Limits
+
+- Each file: **200 KB** max
+- Total across all files: **1 MB** max
+
+## Publishing
+
+```bash
+# From a directory (recommended)
+talenthub agent publish --dir /path/to/agent
+
+# From an installed agent
+talenthub agent publish --name my-agent
+
+# From the current directory
+talenthub agent publish
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dir <path>` | Agent directory with manifest.json and .md files |
+| `--name <name>` | Agent name in openclaw config (resolves workspace dir) |
+| `--id <id>` | Override agent ID from manifest |
+
+## Versioning
+
+Versions are fully server-managed in `YYYY.MM.DD-X` format (e.g. `2026.04.13-1`).
+
+- **New agent** → `YYYY.MM.DD-1`
+- **Core field changes** (skills, USER.md, SOUL.md, AGENTS.md) → version auto-bumps
+- **Metadata-only changes** (emoji, role, tagline, etc.) → version stays the same
+
+Previous versions are automatically saved as snapshots.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `TALENTHUB_URL` | Override registry base URL (default: `https://app.storyclaw.com`) |
+| `TALENTHUB_REGISTRY` | Alias for `TALENTHUB_URL` |
+
+## Docs
+
+- [Publishing Guide (English)](https://github.com/storyclaw-official/talenthub/blob/main/docs/publishing-guide.md)
+- [Publishing Guide (中文)](https://github.com/storyclaw-official/talenthub/blob/main/docs/publishing-guide.zh-CN.md)
+
+## License
+
+MIT
+
+---
+
+## 中文文档
+
+StoryClaw AI Agent 管理工具 — 发布、安装、更新和浏览 TalentHub 市场。
+
+[English](#storyclawtalenthub)
+
+### 安装
+
+```bash
+npm install -g @storyclaw/talenthub
+```
+
+### 快速开始
+
+```bash
+# 登录
+talenthub login
+
+# 初始化 Agent
+talenthub agent init --dir ~/.openclaw/workspace-my-agent
+
+# 发布
+talenthub agent publish --dir ~/.openclaw/workspace-my-agent
+
+# 浏览和安装
+talenthub agent search
+talenthub agent install <agent-name>
+```
+
+### 命令列表
+
+| 命令 | 说明 |
+|------|------|
+| `talenthub login` | 登录 StoryClaw |
+| `talenthub logout` | 退出登录 |
+| `talenthub agent init` | 初始化新 Agent（生成 manifest.json 和提示词文件） |
+| `talenthub agent publish` | 发布 Agent 到注册中心 |
+| `talenthub agent unpublish <name>` | 下架 Agent |
+| `talenthub agent install <name>` | 安装 Agent 及其技能 |
+| `talenthub agent update [name]` | 更新 Agent（`--all` 更新全部，`--json` 结构化输出） |
+| `talenthub agent uninstall <name>` | 卸载 Agent |
+| `talenthub agent list` | 列出已安装的 Agent |
+| `talenthub agent search [query]` | 搜索可用 Agent |
+
+### Agent 目录结构
+
+| 文件 | 是否必须 | 说明 |
+|------|----------|------|
+| `manifest.json` | **必须** | Agent 元数据（ID、名称、分类等） |
+| `IDENTITY.md` | 必须 | 核心身份和人设提示词 |
+| `USER.md` | 可选 | 面向用户的使用说明 |
+| `SOUL.md` | 可选 | 深层性格和行为准则 |
+| `AGENTS.md` | 可选 | 多 Agent 协作指令 |
+
+### manifest.json
+
+```json
+{
+  "id": "my-agent",
+  "name": "My Agent",
+  "emoji": "🤖",
+  "role": "Assistant",
+  "tagline": "一句话描述你的 Agent",
+  "description": "更详细的介绍。",
+  "category": "productivity",
+  "skills": [],
+  "i18n": {},
+  "minOpenClawVersion": "2026.3.1"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 唯一标识符，小写字母加连字符 |
+| `name` | string | 显示名称 |
+| `emoji` | string | 一个 emoji 图标 |
+| `role` | string | 角色简述 |
+| `tagline` | string | 一行摘要 |
+| `description` | string | 详细描述 |
+| `category` | string | `creative`、`finance`、`productivity`、`companion`、`research`、`engineering` |
+| `skills` | string[] | 技能包列表（如 `https://github.com/owner/repo@skill-name`） |
+| `i18n` | object | 按语言代码存放翻译（`zh-CN`、`zh-TW`、`ja`），可通过网页界面填写 |
+| `minOpenClawVersion` | string | 最低 StoryClaw 版本 |
+| `avatarUrl` | string \| null | 头像 URL（可选） |
+
+> **注意：** manifest 中没有 `version` 字段，版本由服务器自动生成。
+
+### 发布
+
+```bash
+# 从目录发布（推荐）
+talenthub agent publish --dir /path/to/agent
+
+# 从已安装的 Agent 发布
+talenthub agent publish --name my-agent
+
+# 从当前目录发布
+talenthub agent publish
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--dir <path>` | Agent 目录 |
+| `--name <name>` | openclaw 配置中的 Agent 名称 |
+| `--id <id>` | 覆盖 manifest 中的 Agent ID |
+
+### 版本管理
+
+版本完全由服务器管理，格式为 `YYYY.MM.DD-X`（如 `2026.04.13-1`）。
+
+- **新 Agent** → `YYYY.MM.DD-1`
+- **核心字段变更**（skills、USER.md、SOUL.md、AGENTS.md）→ 版本自动递增
+- **仅元数据变更**（emoji、role、tagline 等）→ 版本不变
+
+每次版本递增时自动保存上一版本快照。
+
+### 文件大小限制
+
+- 单个文件：最大 **200 KB**
+- 所有文件总计：最大 **1 MB**
+
+### 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `TALENTHUB_URL` | 覆盖注册中心地址（默认：`https://app.storyclaw.com`） |
+| `TALENTHUB_REGISTRY` | `TALENTHUB_URL` 的别名 |
+
+### 详细文档
+
+- [发布指南（中文）](https://github.com/storyclaw-official/talenthub/blob/main/docs/publishing-guide.zh-CN.md)
+- [Publishing Guide (English)](https://github.com/storyclaw-official/talenthub/blob/main/docs/publishing-guide.md)

package/dist/cli.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 // try IPv4 first to avoid EHOSTUNREACH delays on every fetch.
 dns.setDefaultResultOrder("ipv4first");
 import { Command } from "commander";
+import { agentInit } from "./commands/agent-init.js";
 import { agentInstall } from "./commands/agent-install.js";
 import { agentList } from "./commands/agent-list.js";
 import { agentPublish } from "./commands/agent-publish.js";
@@ -30,16 +31,23 @@ program
     .action(login);
 program.command("logout").description("Remove stored credentials").action(logout);
 const agent = program.command("agent").description("Agent management commands");
+agent
+    .command("init")
+    .description("Initialize a new agent with manifest.json and prompt files")
+    .option("-d, --dir <path>", "Target directory (defaults to current directory)")
+    .action(agentInit);
 agent
     .command("install <name>")
     .description("Install an agent and its skills")
     .option("-f, --force", "Overwrite existing agent", false)
     .option("-t, --token <token>", "Authenticate with a th_* token for private agents")
+    .option("--json", "Output structured JSONL progress for machine consumption", false)
     .action(agentInstall);
 agent
     .command("update [name]")
     .description("Update an agent or all agents")
     .option("-a, --all", "Update all installed agents")
+    .option("--json", "Output structured JSONL progress for machine consumption", false)
     .action(agentUpdate);
 agent
     .command("uninstall <name>")
@@ -55,9 +63,11 @@ agent
     .description("Browse available agents")
     .action(agentSearch);
 agent
-    .command("publish <name>")
+    .command("publish")
     .description("Publish a local agent to the registry")
-    .option("-d, --dir <path>", "Agent directory containing manifest.json and .md files")
+    .option("-d, --dir <path>", "Agent directory containing manifest.json and .md files (defaults to current directory)")
+    .option("-n, --name <name>", "Agent name in openclaw config (used to resolve workspace dir)")
+    .option("--id <id>", "Override agent ID from manifest")
     .action(agentPublish);
 agent
     .command("unpublish <name>")

package/dist/commands/agent-init.d.ts

@@ -0,0 +1,3 @@
+export declare function agentInit(opts?: {
+    dir?: string;
+}): Promise<void>;

package/dist/commands/agent-init.js

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+function prompt(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+/**
+ * Parse IDENTITY.md to extract Name and Emoji fields.
+ *
+ * Expected format:
+ *   - **Name:** Aria
+ *   - **Emoji:** 🎭
+ */
+function parseIdentityMd(dir) {
+    const filePath = path.join(dir, "IDENTITY.md");
+    if (!fs.existsSync(filePath))
+        return {};
+    const content = fs.readFileSync(filePath, "utf-8");
+    const result = {};
+    const nameMatch = content.match(/\*\*Name:\*\*\s*(.+)/i);
+    if (nameMatch) {
+        // Take first part before | or — (e.g. "AI Assistant | AI 助理" → "AI Assistant")
+        result.name = nameMatch[1].split(/\s*[|—]\s*/)[0].trim();
+    }
+    const emojiMatch = content.match(/\*\*Emoji:\*\*\s*(.+)/i);
+    if (emojiMatch) {
+        const val = emojiMatch[1].trim();
+        // Skip if it says "none" or similar
+        if (val && !/^none/i.test(val)) {
+            result.emoji = val;
+        }
+    }
+    return result;
+}
+const VALID_CATEGORIES = ["creative", "finance", "productivity", "companion", "research", "engineering"];
+export async function agentInit(opts = {}) {
+    const dir = path.resolve(opts.dir || ".");
+    const manifestPath = path.join(dir, "manifest.json");
+    if (fs.existsSync(manifestPath)) {
+        console.error(`manifest.json already exists in ${dir}`);
+        process.exit(1);
+    }
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Derive defaults from directory name and IDENTITY.md
+    // Agent dirs are typically "workspace-xxx" — extract "xxx" as the id
+    const baseName = path.basename(dir);
+    const dirName = (baseName.startsWith("workspace-") ? baseName.slice("workspace-".length) : baseName)
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-");
+    const identity = parseIdentityMd(dir);
+    // --- ID ---
+    const defaultId = /^[a-z0-9-]+$/.test(dirName) ? dirName : "";
+    const idInput = await prompt(defaultId ? `Agent ID [${defaultId}]: ` : "Agent ID (lowercase alphanumeric + hyphens): ");
+    const id = idInput || defaultId;
+    if (!id || !/^[a-z0-9-]+$/.test(id)) {
+        console.error("Invalid agent ID. Must be lowercase alphanumeric + hyphens only.");
+        process.exit(1);
+    }
+    // --- Name ---
+    const defaultName = identity.name || "";
+    const nameInput = await prompt(defaultName ? `Agent name [${defaultName}]: ` : "Agent name: ");
+    const name = nameInput || defaultName;
+    if (!name) {
+        console.error("Agent name is required.");
+        process.exit(1);
+    }
+    // --- Emoji ---
+    const defaultEmoji = identity.emoji || "";
+    const emojiInput = await prompt(defaultEmoji ? `Emoji [${defaultEmoji}]: ` : "Emoji (optional): ");
+    const emoji = emojiInput || defaultEmoji;
+    // --- Category ---
+    const category = await prompt(`Category (${VALID_CATEGORIES.join(", ")}) [productivity]: `);
+    const finalCategory = category || "productivity";
+    if (!VALID_CATEGORIES.includes(finalCategory)) {
+        console.error(`Invalid category. Must be one of: ${VALID_CATEGORIES.join(", ")}`);
+        process.exit(1);
+    }
+    const role = await prompt("Role (optional): ");
+    const tagline = await prompt("Tagline (optional): ");
+    const manifest = {
+        id,
+        name,
+        category: finalCategory,
+        ...(emoji && { emoji }),
+        ...(role && { role }),
+        ...(tagline && { tagline }),
+        description: "",
+        skills: [],
+        i18n: {},
+    };
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+    console.log(`\n✓ Created ${manifestPath}`);
+    // Create placeholder prompt files if they don't exist
+    for (const file of ["IDENTITY.md", "USER.md", "SOUL.md", "AGENTS.md"]) {
+        const filePath = path.join(dir, file);
+        if (!fs.existsSync(filePath)) {
+            fs.writeFileSync(filePath, `# ${file.replace(".md", "")}\n`);
+        }
+    }
+    console.log("✓ Created prompt files (IDENTITY.md, USER.md, SOUL.md, AGENTS.md)");
+    console.log(`\nNext: edit the prompt files, then run "talenthub agent publish ${id} --dir ${dir}"`);
+}

package/dist/commands/agent-install.d.ts

@@ -1,4 +1,5 @@
 export declare function agentInstall(name: string, options: {
     force?: boolean;
     token?: string;
+    json?: boolean;
 }): Promise<void>;

package/dist/commands/agent-install.js

@@ -6,72 +6,128 @@ import { addOrUpdateAgent, findAgentEntry, readConfig, writeConfig } from "../li
 import { fetchCatalog, fetchManifest } from "../lib/registry.js";
 import { resolveWorkspaceDir } from "../lib/paths.js";
 import { markInstalled } from "../lib/state.js";
+function jsonl(obj) {
+    process.stdout.write(`${JSON.stringify(obj)}\n`);
+}
+// Weight breakdown: manifest 0→5%, skills 5→90%, files 90→95%, config 95→100%
+const WEIGHT = { manifest: 5, skillsStart: 5, skillsEnd: 90, files: 95, config: 100 };
 export async function agentInstall(name, options) {
     const token = options.token;
+    const json = options.json === true;
+    const log = json ? () => { } : console.log.bind(console);
     if (token) {
         if (!token.startsWith("th_")) {
-            console.error("Invalid token format. Token must start with 'th_'.");
+            if (json)
+                jsonl({ event: "error", message: "Invalid token format" });
+            else
+                console.error("Invalid token format. Token must start with 'th_'.");
             process.exit(1);
         }
-        console.log("Verifying token...");
+        log("Verifying token...");
         try {
             await verifyToken(token);
         }
         catch {
-            console.error("Token verification failed. Please check your token and try again.");
+            if (json)
+                jsonl({ event: "error", message: "Token verification failed" });
+            else
+                console.error("Token verification failed. Please check your token and try again.");
             process.exit(1);
         }
     }
-    console.log(`Looking up agent "${name}"...`);
+    log(`Looking up agent "${name}"...`);
     const catalog = await fetchCatalog(token);
     if (!catalog.agents[name]) {
         const available = Object.keys(catalog.agents).join(", ");
-        console.error(`Agent "${name}" not found. Available: ${available}`);
+        if (json)
+            jsonl({ event: "error", message: `Agent "${name}" not found`, available });
+        else
+            console.error(`Agent "${name}" not found. Available: ${available}`);
         process.exit(1);
     }
     const manifest = await fetchManifest(name, token);
-    console.log(`Found ${manifest.emoji} ${manifest.name} v${manifest.version} (${manifest.skills.length} skills)`);
+    log(`Found ${manifest.emoji} ${manifest.name} v${manifest.version} (${manifest.skills.length} skills)`);
+    if (json)
+        jsonl({
+            event: "start",
+            agentId: manifest.id, name: manifest.name, emoji: manifest.emoji,
+            version: manifest.version, skillCount: manifest.skills.length,
+        });
+    if (json)
+        jsonl({ event: "progress", phase: "manifest", percent: WEIGHT.manifest });
     const cfg = readConfig();
     const existing = findAgentEntry(cfg, name);
     if (existing && !options.force) {
-        console.error(`Agent "${name}" already exists in config. Use --force to overwrite.`);
+        if (json)
+            jsonl({ event: "error", message: `Agent "${name}" already exists. Use --force.` });
+        else
+            console.error(`Agent "${name}" already exists in config. Use --force to overwrite.`);
         process.exit(1);
     }
     const wsDir = resolveWorkspaceDir(name);
     fs.mkdirSync(wsDir, { recursive: true });
-    console.log("Writing agent files...");
-    if (manifest.files) {
-        for (const [filename, content] of Object.entries(manifest.files)) {
-            if (content) {
-                fs.writeFileSync(path.join(wsDir, filename), content, "utf-8");
-            }
-        }
-    }
+    // Install skills first — this is the slowest step (5% → 90%)
     let installed = 0;
     let failed = 0;
     let skipped = 0;
-    if (manifest.skills.length > 0) {
-        console.log(`Installing ${manifest.skills.length} skills via npx skills...`);
-        const result = installAllSkills(manifest.skills, wsDir);
+    const warnings = [];
+    const skillTotal = manifest.skills.length;
+    if (skillTotal > 0) {
+        log(`Installing ${skillTotal} skills via npx skills...`);
+        const skillWeight = WEIGHT.skillsEnd - WEIGHT.skillsStart;
+        const result = installAllSkills(manifest.skills, wsDir, json ? (evt) => {
+            const percent = WEIGHT.skillsStart + Math.round((evt.current / evt.total) * skillWeight);
+            jsonl({
+                event: "progress", phase: "skills", percent,
+                detail: evt.name, current: evt.current, total: evt.total, status: evt.status,
+            });
+            if (evt.status === "failed") {
+                warnings.push(`${evt.name}: ${evt.error ?? "install failed"}`);
+            }
+        } : undefined, json);
         installed = result.installed;
         failed = result.failed;
         skipped = result.skipped;
     }
+    else {
+        if (json)
+            jsonl({ event: "progress", phase: "skills", percent: WEIGHT.skillsEnd });
+    }
+    // Write agent files (90% → 95%)
+    log("Writing agent files...");
+    if (manifest.files) {
+        for (const [filename, content] of Object.entries(manifest.files)) {
+            if (content) {
+                fs.writeFileSync(path.join(wsDir, filename), content, "utf-8");
+            }
+        }
+    }
+    if (json)
+        jsonl({ event: "progress", phase: "files", percent: WEIGHT.files });
+    // Update config (95% → 100%)
+    // Write workspace path instead of skills — the gateway discovers skills
+    // from <workspace>/skills/ symlinks that were created during skill install.
     const updatedCfg = addOrUpdateAgent(cfg, {
         id: manifest.id,
         name: manifest.name,
-        skills: manifest.skills,
+        workspace: wsDir,
     });
     writeConfig(updatedCfg);
     markInstalled(manifest.id, manifest.version);
-    const parts = [];
-    if (installed > 0)
-        parts.push(`${installed} installed`);
-    if (skipped > 0)
-        parts.push(`${skipped} already present`);
-    if (failed > 0)
-        parts.push(`${failed} failed`);
-    const skillSummary = parts.length > 0 ? ` (skills: ${parts.join(", ")})` : "";
-    console.log(`\n${manifest.emoji} Installed ${manifest.name}${skillSummary}.`);
-    console.log("Restart the OpenClaw gateway to apply changes.");
+    if (json)
+        jsonl({ event: "progress", phase: "config", percent: WEIGHT.config });
+    if (json) {
+        jsonl({ event: "done", success: true, installed, skipped, failed, warnings, workspace: wsDir });
+    }
+    else {
+        const parts = [];
+        if (installed > 0)
+            parts.push(`${installed} installed`);
+        if (skipped > 0)
+            parts.push(`${skipped} already present`);
+        if (failed > 0)
+            parts.push(`${failed} failed`);
+        const skillSummary = parts.length > 0 ? ` (skills: ${parts.join(", ")})` : "";
+        console.log(`\n${manifest.emoji} Installed ${manifest.name}${skillSummary}.`);
+    }
 }

package/dist/commands/agent-publish.d.ts

@@ -1,3 +1,5 @@
-export declare function agentPublish(name: string, opts?: {
+export declare function agentPublish(opts?: {
     dir?: string;
+    name?: string;
+    id?: string;
 }): Promise<void>;

package/dist/commands/agent-publish.js

@@ -1,19 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
-import readline from "node:readline";
 import { readAuth, getRegistryBaseUrl } from "../lib/auth.js";
 import { findAgentEntry, readConfig } from "../lib/config.js";
 import { fetchRetry } from "../lib/fetch.js";
 import { resolveWorkspaceDir } from "../lib/paths.js";
-function prompt(question) {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-        rl.question(question, (answer) => {
-            rl.close();
-            resolve(answer.trim());
-        });
-    });
-}
 const MAX_FILE_SIZE = 200 * 1024;
 const MAX_TOTAL_SIZE = 1024 * 1024;
 function readAgentDir(dir) {
@@ -21,15 +11,19 @@ function readAgentDir(dir) {
         console.error(`Directory not found: ${dir}`);
         process.exit(1);
     }
-    let manifest = {};
     const manifestPath = path.join(dir, "manifest.json");
-    if (fs.existsSync(manifestPath)) {
-        try {
-            manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
-        }
-        catch {
-            console.warn("Warning: could not parse manifest.json.");
-        }
+    if (!fs.existsSync(manifestPath)) {
+        console.error(`manifest.json not found in ${dir}`);
+        console.error("Create a manifest.json with at least: { \"id\": \"...\", \"name\": \"...\", \"category\": \"...\" }");
+        process.exit(1);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    }
+    catch {
+        console.error("Failed to parse manifest.json.");
+        process.exit(1);
     }
     const files = {};
     let totalSize = 0;
@@ -52,7 +46,7 @@ function readAgentDir(dir) {
     }
     return { manifest, files };
 }
-export async function agentPublish(name, opts = {}) {
+export async function agentPublish(opts = {}) {
     const auth = readAuth();
     if (!auth) {
         console.error("Not logged in. Run \"talenthub login\" first.");
@@ -60,42 +54,45 @@ export async function agentPublish(name, opts = {}) {
     }
     let manifest;
     let files;
-    let fallbackName = name;
-    let fallbackModel = "claude-sonnet-4-5";
-    let fallbackSkills = [];
     if (opts.dir) {
         const agentDir = path.resolve(opts.dir);
         ({ manifest, files } = readAgentDir(agentDir));
     }
-    else {
+    else if (opts.name) {
         const cfg = readConfig();
-        const entry = findAgentEntry(cfg, name);
+        const entry = findAgentEntry(cfg, opts.name);
         if (!entry) {
-            console.error(`Agent "${name}" not found in openclaw config.`);
-            console.error("Use --dir to publish from an agent directory, or install the agent first.");
+            console.error(`Agent "${opts.name}" not found in openclaw config.`);
+            console.error("Use --dir to publish from an agent directory.");
             process.exit(1);
         }
-        fallbackName = entry.name || name;
-        fallbackModel = entry.model || fallbackModel;
-        fallbackSkills = entry.skills || [];
-        const wsDir = resolveWorkspaceDir(name);
+        const wsDir = resolveWorkspaceDir(opts.name);
         ({ manifest, files } = readAgentDir(wsDir));
     }
-    const agentId = manifest.id || name;
-    const currentVersion = manifest.version || "0.1.0";
-    const version = await prompt(`Version [${currentVersion}]: `);
-    const finalVersion = version || currentVersion;
+    else {
+        // Default to current directory
+        ;
+        ({ manifest, files } = readAgentDir(path.resolve(".")));
+    }
+    const agentId = opts.id || manifest.id;
+    if (!agentId) {
+        console.error("No agent ID found. Set \"id\" in manifest.json or use --id.");
+        process.exit(1);
+    }
+    const agentName = manifest.name;
+    if (!agentName) {
+        console.error("No agent name found. Set \"name\" in manifest.json.");
+        process.exit(1);
+    }
     const payload = {
         id: agentId,
-        version: finalVersion,
-        name: manifest.name || fallbackName,
+        name: agentName,
         emoji: manifest.emoji || "",
         role: manifest.role || "",
         tagline: manifest.tagline || "",
         description: manifest.description || "",
         category: manifest.category || "productivity",
-        model: manifest.model || fallbackModel,
-        skills: manifest.skills || fallbackSkills,
+        skills: manifest.skills || [],
         identity_prompt: files["IDENTITY.md"] || "",
         user_prompt: files["USER.md"] || "",
         soul_prompt: files["SOUL.md"] || "",
@@ -103,11 +100,9 @@ export async function agentPublish(name, opts = {}) {
         min_openclaw_version: manifest.minOpenClawVersion || null,
         avatar_url: manifest.avatarUrl || null,
         is_public: true,
-        ...(manifest.i18n && typeof manifest.i18n === "object"
-            ? { i18n: manifest.i18n }
-            : {}),
+        i18n: manifest.i18n && typeof manifest.i18n === "object" ? manifest.i18n : {},
     };
-    console.log(`\nPublishing ${payload.emoji || ""} ${payload.name} v${finalVersion}...`);
+    console.log(`\nPublishing ${payload.emoji || ""} ${payload.name}...`);
     const base = getRegistryBaseUrl();
     const url = `${base}/api/talenthub/registry/publish`;
     const res = await fetchRetry(url, {

package/dist/commands/agent-uninstall.js

@@ -43,7 +43,6 @@ export async function agentUninstall(name, options) {
     console.log(`Removed agent "${name}"` +
         (removedBindings > 0 ? ` (${removedBindings} binding(s) cleaned)` : "") +
         ".");
-    console.log("Restart the OpenClaw gateway to apply changes.");
 }
 function removeAgentFromConfig(cfg, agentId) {
     const result = removeAgent(cfg, agentId);

package/dist/commands/agent-update.d.ts

@@ -1,3 +1,4 @@
 export declare function agentUpdate(name?: string, options?: {
     all?: boolean;
+    json?: boolean;
 }): Promise<void>;

package/dist/commands/agent-update.js

@@ -6,9 +6,22 @@ import { fetchManifest } from "../lib/registry.js";
 import { resolveWorkspaceDir } from "../lib/paths.js";
 import { markInstalled, readState } from "../lib/state.js";
 import { checkUpdates } from "../lib/update-check.js";
-async function updateAgent(agentId) {
+function jsonl(obj) {
+    process.stdout.write(`${JSON.stringify(obj)}\n`);
+}
+const WEIGHT = { manifest: 10, skillsStart: 10, skillsEnd: 80, files: 90, config: 100 };
+async function updateAgent(agentId, json) {
+    const log = json ? () => { } : console.log.bind(console);
     const manifest = await fetchManifest(agentId);
     const wsDir = resolveWorkspaceDir(agentId);
+    if (json)
+        jsonl({
+            event: "start",
+            agentId: manifest.id, name: manifest.name, emoji: manifest.emoji,
+            version: manifest.version, skillCount: manifest.skills.length,
+        });
+    if (json)
+        jsonl({ event: "progress", phase: "manifest", percent: WEIGHT.manifest });
     // Backup workspace
     const backupDir = `${wsDir}.bak`;
     if (fs.existsSync(wsDir)) {
@@ -19,6 +32,7 @@ async function updateAgent(agentId) {
     }
     fs.mkdirSync(wsDir, { recursive: true });
     // Write agent files from the registry response
+    log("  Writing agent files...");
     if (manifest.files) {
         for (const [filename, content] of Object.entries(manifest.files)) {
             if (content) {
@@ -26,48 +40,89 @@ async function updateAgent(agentId) {
             }
         }
     }
-    // Install any new skills and re-sync symlinks for all
-    if (manifest.skills.length > 0) {
-        installAllSkills(manifest.skills, wsDir);
+    if (json)
+        jsonl({ event: "progress", phase: "files", percent: WEIGHT.files });
+    // Install any new skills (existing skills are skipped)
+    let installed = 0;
+    let failed = 0;
+    let skipped = 0;
+    const warnings = [];
+    const skillTotal = manifest.skills.length;
+    if (skillTotal > 0) {
+        log("  Installing new skills...");
+        const skillWeight = WEIGHT.skillsEnd - WEIGHT.skillsStart;
+        const result = installAllSkills(manifest.skills, wsDir, json ? (evt) => {
+            const percent = WEIGHT.skillsStart + Math.round((evt.current / evt.total) * skillWeight);
+            jsonl({
+                event: "progress", phase: "skills", percent,
+                detail: evt.name, current: evt.current, total: evt.total, status: evt.status,
+            });
+            if (evt.status === "failed") {
+                warnings.push(`${evt.name}: ${evt.error ?? "install failed"}`);
+            }
+        } : undefined, json);
+        installed = result.installed;
+        failed = result.failed;
+        skipped = result.skipped;
+    }
+    else {
+        if (json)
+            jsonl({ event: "progress", phase: "skills", percent: WEIGHT.skillsEnd });
     }
     // Update config
     const cfg = readConfig();
     const updatedCfg = addOrUpdateAgent(cfg, {
         id: manifest.id,
         name: manifest.name,
-        skills: manifest.skills,
+        workspace: wsDir,
     });
     writeConfig(updatedCfg);
     markInstalled(manifest.id, manifest.version);
+    if (json)
+        jsonl({ event: "progress", phase: "config", percent: WEIGHT.config });
+    if (json) {
+        jsonl({ event: "done", agentId, success: true, version: manifest.version, installed, skipped, failed, warnings });
+    }
     return true;
 }
 export async function agentUpdate(name, options) {
+    const json = options?.json === true;
+    const log = json ? () => { } : console.log.bind(console);
     if (options?.all || !name) {
         const updates = await checkUpdates();
         if (updates.length === 0) {
-            console.log("All agents are up to date.");
+            if (json)
+                jsonl({ event: "done", success: true, updated: 0 });
+            else
+                log("All agents are up to date.");
             return;
         }
         // Update shared skills first
-        console.log("Updating shared skills...");
+        log("Updating shared skills...");
         updateAllSkills();
-        console.log(`\nFound ${updates.length} update(s):\n`);
+        log(`\nFound ${updates.length} update(s):\n`);
         for (const u of updates) {
-            console.log(`  Updating ${u.name}: ${u.currentVersion} → ${u.latestVersion}`);
-            await updateAgent(u.agentId);
-            console.log(`  ✓ ${u.name} updated to ${u.latestVersion}`);
+            log(`  Updating ${u.name}: ${u.currentVersion} → ${u.latestVersion}`);
+            await updateAgent(u.agentId, json);
+            log(`  ✓ ${u.name} updated to ${u.latestVersion}`);
         }
-        console.log("\nRestart the OpenClaw gateway to apply changes.");
+        if (json)
+            jsonl({ event: "done", success: true, updated: updates.length });
+        else
+            log("\nAll done.");
         return;
     }
     const state = readState();
     if (!state.agents[name]) {
-        console.error(`Agent "${name}" is not installed. Use "talenthub agent install ${name}" first.`);
+        if (json)
+            jsonl({ event: "error", message: `Agent "${name}" is not installed` });
+        else
+            console.error(`Agent "${name}" is not installed. Use "talenthub agent install ${name}" first.`);
         process.exit(1);
     }
-    console.log("Updating shared skills...");
+    log("Updating shared skills...");
     updateAllSkills();
-    console.log(`Updating agent "${name}"...`);
-    await updateAgent(name);
-    console.log(`✓ Agent "${name}" updated. Restart the OpenClaw gateway to apply changes.`);
+    log(`Updating agent "${name}"...`);
+    await updateAgent(name, json);
+    log(`✓ Agent "${name}" updated. All done.`);
 }

package/dist/lib/skills.d.ts

@@ -37,7 +37,15 @@ export declare function installSkill(entry: string, workspaceDir: string): boole
  * @param skills Array of skill URL strings ("https://github.com/owner/repo@skill")
  * Returns { installed, skipped, failed } counts.
  */
-export declare function installAllSkills(skills: string[], workspaceDir: string): {
+export type SkillProgressCallback = (event: {
+    name: string;
+    repo: string;
+    status: "skipped" | "installing" | "done" | "failed";
+    current: number;
+    total: number;
+    error?: string;
+}) => void;
+export declare function installAllSkills(skills: string[], workspaceDir: string, onProgress?: SkillProgressCallback, quiet?: boolean): {
     installed: number;
     skipped: number;
     failed: number;

package/dist/lib/skills.js

@@ -19,6 +19,18 @@ function resolveSkillsBin() {
     }
 }
 const SKILLS_BIN = resolveSkillsBin();
+/**
+ * Replace `https://github.com/...` URLs with a mirror when TALENTHUB_GITHUB_URL is set.
+ * Example: TALENTHUB_GITHUB_URL=https://gitmirror.com
+ *   https://github.com/owner/repo → https://gitmirror.com/owner/repo
+ */
+function applyGithubMirror(url) {
+    const mirror = process.env.TALENTHUB_GITHUB_URL?.trim();
+    if (!mirror)
+        return url;
+    const base = mirror.replace(/\/+$/, "");
+    return url.replace(/^https?:\/\/github\.com/i, base);
+}
 /**
  * Parse a skill URL string into repo source and skill name.
  * Accepts "https://github.com/owner/repo@skill" (preferred) and
@@ -67,16 +79,22 @@ export function isSkillInstalled(name) {
  *
  * Returns the list of skill names that were successfully installed.
  */
-function installSkillsFromRepo(repo, skillNames) {
+function installSkillsFromRepo(repo, skillNames, quiet = false) {
     const skillFlag = skillNames.join(" ");
     try {
-        const cmd = `node ${SKILLS_BIN} add ${repo} --skill ${skillFlag} --agent openclaw -y`;
-        execSync(cmd, { stdio: "inherit", cwd: resolveStateDir(), timeout: 300_000 });
+        const cmd = `node ${SKILLS_BIN} add ${applyGithubMirror(repo)} --skill ${skillFlag} --agent openclaw -y`;
+        execSync(cmd, { stdio: quiet ? "pipe" : "inherit", cwd: resolveStateDir(), timeout: 300_000 });
     }
-    catch {
-        console.error(`  Warning: failed to install skills from ${repo}: ${skillNames.join(", ")}`);
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Extract stderr from ExecSyncError if available
+        const stderr = err?.stderr?.toString().trim();
+        const detail = stderr || msg;
+        if (!quiet)
+            console.error(`  Warning: failed to install skills from ${repo}: ${skillNames.join(", ")}`);
+        return { ok: skillNames.filter((s) => isSkillInstalled(s)), error: detail };
     }
-    return skillNames.filter((s) => isSkillInstalled(s));
+    return { ok: skillNames.filter((s) => isSkillInstalled(s)) };
 }
 /**
  * Install a single skill via `skills add` into the shared directory,
@@ -93,8 +111,8 @@ export function installSkill(entry, workspaceDir) {
         return false;
     }
     if (!isSkillInstalled(spec.skill)) {
-        const ok = installSkillsFromRepo(spec.repo, [spec.skill]);
-        if (ok.length === 0)
+        const result = installSkillsFromRepo(spec.repo, [spec.skill]);
+        if (result.ok.length === 0)
             return false;
     }
     if (!isSkillInstalled(spec.skill)) {
@@ -126,30 +144,30 @@ function linkSkillToWorkspace(name, workspaceDir) {
     }
     fs.symlinkSync(target, link, "dir");
 }
-/**
- * Install all skills for an agent: skip already-installed, batch-install
- * missing skills grouped by repo (one clone per repo), then symlink
- * everything into the workspace.
- *
- * @param skills Array of skill URL strings ("https://github.com/owner/repo@skill")
- * Returns { installed, skipped, failed } counts.
- */
-export function installAllSkills(skills, workspaceDir) {
+export function installAllSkills(skills, workspaceDir, onProgress, quiet = false) {
     fs.mkdirSync(resolveStateDir(), { recursive: true });
     let installed = 0;
     let skipped = 0;
     let failed = 0;
+    let current = 0;
+    const total = skills.length;
     // Group missing skills by repo so each repo is cloned only once
     const needInstall = new Map();
+    const skillRepoMap = new Map();
     for (const entry of skills) {
         const spec = parseSkillSpec(entry);
         if (!spec) {
+            current++;
             console.error(`  Warning: invalid skill spec "${entry}" — expected "https://github.com/owner/repo@skill"`);
+            onProgress?.({ name: entry, repo: "", status: "failed", current, total, error: "invalid spec" });
             failed++;
             continue;
         }
+        skillRepoMap.set(spec.skill, spec.repo);
         if (isSkillInstalled(spec.skill)) {
+            current++;
             linkSkillToWorkspace(spec.skill, workspaceDir);
+            onProgress?.({ name: spec.skill, repo: spec.repo, status: "skipped", current, total });
             skipped++;
         }
         else {
@@ -160,11 +178,25 @@ export function installAllSkills(skills, workspaceDir) {
     }
     // Batch install: one `skills add` per repo
     for (const [repo, skillNames] of needInstall) {
-        const ok = installSkillsFromRepo(repo, skillNames);
-        installed += ok.length;
-        failed += skillNames.length - ok.length;
-        for (const name of ok) {
-            linkSkillToWorkspace(name, workspaceDir);
+        for (const name of skillNames) {
+            current++;
+            onProgress?.({ name, repo, status: "installing", current, total });
+        }
+        // Rewind current so we can report done/failed per skill
+        current -= skillNames.length;
+        const result = installSkillsFromRepo(repo, skillNames, quiet);
+        const okSet = new Set(result.ok);
+        for (const name of skillNames) {
+            current++;
+            if (okSet.has(name)) {
+                installed++;
+                linkSkillToWorkspace(name, workspaceDir);
+                onProgress?.({ name, repo, status: "done", current, total });
+            }
+            else {
+                failed++;
+                onProgress?.({ name, repo, status: "failed", current, total, error: result.error ?? "install failed" });
+            }
         }
     }
     return { installed, skipped, failed };

package/dist/lib/update-check.js

@@ -1,5 +1,6 @@
 import { fetchCatalog } from "./registry.js";
 import { readState, writeState } from "./state.js";
+import { isOlderVersion } from "./version.js";
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 export async function getCatalogCached() {
     const state = readState();
@@ -21,7 +22,7 @@ export async function checkUpdates() {
         const remote = catalog.agents[agentId];
         if (!remote)
             continue;
-        if (remote.version !== installed.version) {
+        if (isOlderVersion(installed.version, remote.version)) {
             updates.push({
                 agentId,
                 currentVersion: installed.version,

package/dist/lib/version.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Agent version utilities.
+ *
+ * Format: YYYY.MM.DD-X
+ *   - YYYY: 4-digit year
+ *   - MM:   2-digit zero-padded month (01-12)
+ *   - DD:   2-digit zero-padded day (01-31)
+ *   - X:    positive integer counter (1, 2, 3, ...)
+ */
+/**
+ * Compare two version strings.
+ * Returns -1 if a < b, 0 if a === b, 1 if a > b.
+ *
+ * Falls back to string comparison if either version doesn't match the
+ * YYYY.MM.DD-X format (for backwards compatibility with old versions).
+ */
+export declare function compareVersions(a: string, b: string): -1 | 0 | 1;
+/**
+ * Check if version `a` is older than version `b`.
+ */
+export declare function isOlderVersion(a: string, b: string): boolean;

package/dist/lib/version.js

@@ -0,0 +1,53 @@
+/**
+ * Agent version utilities.
+ *
+ * Format: YYYY.MM.DD-X
+ *   - YYYY: 4-digit year
+ *   - MM:   2-digit zero-padded month (01-12)
+ *   - DD:   2-digit zero-padded day (01-31)
+ *   - X:    positive integer counter (1, 2, 3, ...)
+ */
+const VERSION_RE = /^(\d{4})\.(\d{2})\.(\d{2})-(\d+)$/;
+function parseVersion(v) {
+    const m = VERSION_RE.exec(v);
+    if (!m)
+        return null;
+    const month = Number(m[2]);
+    const day = Number(m[3]);
+    const counter = Number(m[4]);
+    if (month < 1 || month > 12 || day < 1 || day > 31 || counter < 1)
+        return null;
+    return { year: Number(m[1]), month, day, counter };
+}
+/**
+ * Compare two version strings.
+ * Returns -1 if a < b, 0 if a === b, 1 if a > b.
+ *
+ * Falls back to string comparison if either version doesn't match the
+ * YYYY.MM.DD-X format (for backwards compatibility with old versions).
+ */
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    // If both parse, compare structurally
+    if (pa && pb) {
+        const fields = ["year", "month", "day", "counter"];
+        for (const field of fields) {
+            if (pa[field] < pb[field])
+                return -1;
+            if (pa[field] > pb[field])
+                return 1;
+        }
+        return 0;
+    }
+    // Fallback: string comparison (handles old "2026.3.16" style versions)
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+/**
+ * Check if version `a` is older than version `b`.
+ */
+export function isOlderVersion(a, b) {
+    return compareVersions(a, b) === -1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storyclaw/talenthub",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "CLI tool to manage StoryClaw AI agents",
   "type": "module",
   "bin": {