@neta-art/neta-search-cli 0.2.8 → 0.2.14

package/README.md

@@ -5,13 +5,15 @@ Command-line client for **neta-search**, the skill registry of the Cohub / Neta
 ```bash
 npx -y @neta-art/neta-search-cli@0.2 skills find "generate video"     # search (Chinese or English)
 npx -y @neta-art/neta-search-cli@0.2 skills find "browser automation" --json
-npx -y @neta-art/neta-search-cli@0.2 skills use  <id>                 # pull into a temp dir, no files written
+npx -y @neta-art/neta-search-cli@0.2 skills use  <id>                 # print the SKILL.md (pulled into a temp dir; no project files written)
 npx -y @neta-art/neta-search-cli@0.2 skills add  <id>                 # install into .agents/skills/
 npx -y @neta-art/neta-search-cli@0.2 skills init <name>               # scaffold your own skill
 ```
 
 `<id>` comes from `find` results, e.g. `cohub:<spaceId>/<name>`.
 
+`use` prints the skill directory and the full SKILL.md, so an agent can follow it right away; relative paths in SKILL.md resolve against that directory. If the local entry is a pointer (frontmatter `metadata.neta-skill-id`), `use` fetches the full skill it points to.
+
 Inside a Cohub sandbox the CLI picks up the sandbox identity automatically; elsewhere it runs anonymously.
 
 Single file, no runtime dependencies. Node.js 20+.

package/neta-search.mjs

@@ -3247,13 +3247,13 @@ Expecting one of '${allowedValues.join("', '")}'`);
           contextOptions = void 0;
         }
         const outputContext = this._getOutputContext(contextOptions);
-        const eventContext = {
+        const eventContext2 = {
           error: outputContext.error,
           write: outputContext.write,
           command: this
         };
-        this._getCommandAndAncestors().reverse().forEach((command) => command.emit("beforeAllHelp", eventContext));
-        this.emit("beforeHelp", eventContext);
+        this._getCommandAndAncestors().reverse().forEach((command) => command.emit("beforeAllHelp", eventContext2));
+        this.emit("beforeHelp", eventContext2);
         let helpInformation = this.helpInformation({ error: outputContext.error });
         if (deprecatedCallback) {
           helpInformation = deprecatedCallback(helpInformation);
@@ -3265,9 +3265,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._getHelpOption()?.long) {
           this.emit(this._getHelpOption().long);
         }
-        this.emit("afterHelp", eventContext);
+        this.emit("afterHelp", eventContext2);
         this._getCommandAndAncestors().forEach(
-          (command) => command.emit("afterAllHelp", eventContext)
+          (command) => command.emit("afterAllHelp", eventContext2)
         );
       }
       /**
@@ -26912,10 +26912,18 @@ function detectEnv() {
   const spaceId = process.env["COHUB_SPACE_ID"] ?? "";
   const apiBase = process.env["NETASEARCH_API"] ?? // sandbox 内（平台注入 COHUB_*）：默认 prod Service——真实用户的事件该写
   // prod 账本；否则 prod sandbox 的事件会全部写进 dev 账本（review #76 抓过的
-  // 隐患）。sandbox 外（本地/验收）：默认 dev 公网地址，NETASEARCH_API 可覆盖。
+  // 隐患）。sandbox 外：默认 prod 公网地址（2026-10-09 起；此前是 dev，公网 npm 版发布前改），
+  // 本地验收用 NETASEARCH_API 指 dev。
   // 不依赖平台注入 NETASEARCH_API——COHUB_SPACE_ID 就是平台已给的信号。
-  (spaceId !== "" ? "http://neta-search-api.recsys.svc.cluster.local" : "https://dev-search.neta.art");
-  return { apiBase, actorId, spaceId, anonymous: actorId === "" || spaceId === "" };
+  (spaceId !== "" ? "http://neta-search-api.recsys.svc.cluster.local" : "https://search.neta.art");
+  return {
+    apiBase,
+    actorId,
+    spaceId,
+    sessionId: process.env["COHUB_SESSION_ID"] ?? "",
+    turnId: process.env["COHUB_TURN_ID"] ?? "",
+    anonymous: actorId === "" || spaceId === ""
+  };
 }
 function searchClient(env) {
   const transport = createConnectTransport({ baseUrl: env.apiBase, httpVersion: "1.1" });
@@ -26925,12 +26933,27 @@ function feedbackClient(env) {
   const transport = createConnectTransport({ baseUrl: env.apiBase, httpVersion: "1.1" });
   return createClient(SkillFeedbackService, transport);
 }
-async function reportSkillEvent(env, event, skillId, digest, skillName) {
+function eventContext(env, extra = {}) {
+  const ctx = { source: "cli", ...extra };
+  if (env.sessionId) ctx["session_id"] = env.sessionId;
+  if (env.turnId) ctx["turn_id"] = env.turnId;
+  return ctx;
+}
+async function reportSkillEvent(env, event, skillId, digest, skillName, extra = {}) {
   if (env.anonymous) return false;
   try {
     await feedbackClient(env).reportSkillEvents({
       events: [
-        { event, skillId, skillName, contentHash: digest, actorId: env.actorId, spaceId: env.spaceId, anonymous: false }
+        {
+          event,
+          skillId,
+          skillName,
+          contentHash: digest,
+          actorId: env.actorId,
+          spaceId: env.spaceId,
+          anonymous: false,
+          context: eventContext(env, extra)
+        }
       ]
     });
     return true;
@@ -27041,21 +27064,29 @@ var ArchiveNotFound = class extends Error {
 };
 async function fetchArchive(env, id) {
   const url = `${env.apiBase}${ARCHIVE_PATH}?id=${encodeURIComponent(id)}`;
+  const res = await fetch(url, { redirect: "manual", signal: AbortSignal.timeout(TIMEOUT_MS) });
+  if (res.status === 404) throw new ArchiveNotFound(`${id} \u4E0D\u5B58\u5728\uFF0C\u6216\u8FD8\u6CA1\u6709\u4E0A\u67B6\u7684\u7248\u672C`);
+  const location = res.headers.get("location");
+  if (res.status < 300 || res.status >= 400 || !location) throw new Error(`\u4E0B\u8F7D ${id} \u5931\u8D25\uFF1AHTTP ${res.status}`);
+  const digest = res.headers.get("x-skill-digest") ?? "";
+  const name = res.headers.get("x-skill-name") ?? id.split("/").pop();
+  if (!digest) throw new Error(`\u4E0B\u8F7D ${id} \u5931\u8D25\uFF1A\u670D\u52A1\u7AEF\u6CA1\u6709\u7ED9\u51FA\u7248\u672C\uFF08x-skill-digest\uFF09`);
+  const body = await download(new URL(location, url).toString(), id);
+  const files = untarGz(body);
+  const got = digestOf(new Map(files.map((f) => [f.path, f.data])));
+  if (got !== digest) throw new Error(`\u4E0B\u8F7D\u7684 ${id} \u5185\u5BB9\u6821\u9A8C\u5931\u8D25\uFF08\u671F\u671B ${digest}\uFF0C\u5B9E\u9645 ${got}\uFF09`);
+  return { id, name, digest, files };
+}
+async function download(url, id) {
   for (let attempt = 1; ; attempt++) {
     const res = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
-    if (res.status === 404) throw new ArchiveNotFound(`${id} \u4E0D\u5B58\u5728\uFF0C\u6216\u4F5C\u8005\u8FD8\u6CA1\u6709\u53EF\u5206\u4EAB\u7684\u7248\u672C`);
-    if (res.status === 503 && attempt < MAX_TRIES) {
-      const wait = Number(res.headers.get("retry-after") ?? "2") || 2;
-      await new Promise((r) => setTimeout(r, wait * 1e3));
+    if (res.status === 202 && attempt < MAX_TRIES) {
+      const body = await res.json().catch(() => ({}));
+      await new Promise((r) => setTimeout(r, Math.min(Math.max(body.retryAfterMs ?? 2e3, 250), 5e3)));
       continue;
     }
-    if (!res.ok) throw new Error(`\u4E0B\u8F7D ${id} \u5931\u8D25\uFF1AHTTP ${res.status}`);
-    const digest = res.headers.get("x-skill-digest") ?? "";
-    const name = res.headers.get("x-skill-name") ?? id.split("/").pop();
-    const files = untarGz(Buffer.from(await res.arrayBuffer()));
-    const got = digestOf(new Map(files.map((f) => [f.path, f.data])));
-    if (!digest || got !== digest) throw new Error(`\u4E0B\u8F7D\u7684 ${id} \u5185\u5BB9\u6821\u9A8C\u5931\u8D25\uFF08\u671F\u671B ${digest}\uFF0C\u5B9E\u9645 ${got}\uFF09`);
-    return { id, name, digest, files };
+    if (!res.ok) throw new Error(`\u4E0B\u8F7D ${id} \u5931\u8D25\uFF1Aregistry \u8FD4\u56DE HTTP ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
   }
 }
 function untarGz(gz) {
@@ -27156,6 +27187,23 @@ function writeSkill(target, files, source) {
   renameSync(staging, target);
   if (hadOld) rmSync(trash, { recursive: true, force: true });
 }
+var POINTER_RE = /^\s*neta-skill-id:\s*["']?(cohub:[^"'\s]+)["']?\s*$/m;
+function frontmatterOf(raw) {
+  if (!raw.startsWith("---\n")) return "";
+  const end = raw.indexOf("\n---", 4);
+  return end < 0 ? "" : raw.slice(4, end);
+}
+function pointerTargetOf(raw) {
+  const m = POINTER_RE.exec(frontmatterOf(raw));
+  return m ? m[1] : null;
+}
+function pointerTarget(dir) {
+  try {
+    return pointerTargetOf(readFileSync2(join2(dir, "SKILL.md"), "utf8"));
+  } catch {
+    return null;
+  }
+}
 function sharedOptOut(dir) {
   try {
     const raw = readFileSync2(join2(dir, "SKILL.md"), "utf8");
@@ -27227,10 +27275,23 @@ async function graduate(env, name, target, opts) {
 }
 
 // cli/src/skills/use.ts
-import { existsSync as existsSync3, readdirSync as readdirSync2 } from "node:fs";
+import { existsSync as existsSync3, readdirSync as readdirSync2, readFileSync as readFileSync3 } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { join as join4 } from "node:path";
+var FETCH_ROOT = process.env["NETASEARCH_FETCH_ROOT"] ?? join4("/tmp", "neta-skills");
+var HANDLE_RE = /^(@[a-z0-9_.-]{1,64}|[a-z0-9][a-z0-9-]{0,31})\/[a-z0-9][a-z0-9-]{0,63}$/i;
+async function resolveHandle(env, input) {
+  const r = await fetch(`${env.apiBase}/v1/skills/resolve?handle=${encodeURIComponent(input)}`, { signal: AbortSignal.timeout(5e3) });
+  if (!r.ok) return null;
+  const out = await r.json();
+  return typeof out.id === "string" && parseId(out.id) ? out.id : null;
+}
 async function cmdUse(idOrName, opts) {
   const env = detectEnv();
+  if (!parseId(idOrName) && HANDLE_RE.test(idOrName)) {
+    const resolved = await resolveHandle(env, idOrName).catch(() => null);
+    if (resolved) idOrName = resolved;
+  }
   const parsed = parseId(idOrName);
   const name = parsed?.name ?? idOrName;
   const mine = !parsed || parsed.spaceId === env.spaceId;
@@ -27238,6 +27299,8 @@ async function cmdUse(idOrName, opts) {
   let where = "local";
   let reportId = null;
   let notice = null;
+  let fetchId = parsed && !mine ? idOrName : null;
+  let via = opts.via ? opts.via.slice(0, 32) : null;
   const installed = join4(SKILLS_DIR, name);
   const draft = join4(DRAFTS_DIR, name);
   if (skillDirExists(installed)) {
@@ -27263,11 +27326,32 @@ async function cmdUse(idOrName, opts) {
       where = "mod";
     }
   }
-  if (!path && parsed && !mine) {
+  if (path) {
+    const target = pointerTarget(path);
+    if (target !== null) {
+      if (!parseId(target)) {
+        console.error(`${join4(path, "SKILL.md")} \u662F\u6307\u9488\uFF0C\u4F46\u5B83\u7684 neta-skill-id \u4E0D\u662F\u5408\u6CD5 id\uFF1A${target}`);
+        return 1;
+      }
+      via = "pointer";
+      fetchId = target;
+      path = null;
+      reportId = null;
+      notice = null;
+    }
+  }
+  if (!path && fetchId) {
     try {
-      const a = await fetchArchive(env, idOrName);
-      path = join4("/tmp", "neta-skills", `${name}-${a.digest.slice(7, 19)}`);
-      if (!existsSync3(join4(path, "SKILL.md"))) writeSkill(path, a.files, { id: a.id, digest: a.digest });
+      const a = await fetchArchive(env, fetchId);
+      const skillMd2 = a.files.find((f) => f.path === "SKILL.md");
+      if (skillMd2 && pointerTargetOf(skillMd2.data.toString("utf8")) !== null) {
+        console.error(`${fetchId} \u4E0B\u8F7D\u5230\u7684\u5185\u5BB9\u8FD8\u662F\u6307\u9488\uFF0C\u505C\u5728\u8FD9\u91CC\uFF08\u4E0D\u8DDF\u7B2C\u4E8C\u5C42\uFF0C\u9632\u6B62\u7ED5\u5708\uFF09\u3002`);
+        return 1;
+      }
+      const p = parseId(a.id);
+      path = join4(FETCH_ROOT, p.spaceId, p.name);
+      const have = readSource(path);
+      if (!skillDirExists(path) || have?.digest !== a.digest) writeSkill(path, a.files, { id: a.id, digest: a.digest });
       reportId = a.id;
       where = "fetched";
     } catch (e) {
@@ -27279,14 +27363,21 @@ async function cmdUse(idOrName, opts) {
     console.error(`skill "${idOrName}" \u672C\u5730\u6CA1\u6709\u2014\u2014\u5148 neta-search skills find "${name}" \u62FF\u5230 id\u3002`);
     return 1;
   }
-  const reported = reportId ? await reportSkillEvent(env, "use", reportId, skillDirDigest(path), name) : false;
-  if (opts.json) console.log(JSON.stringify({ skill: reportId ?? name, path, where }));
-  else {
+  const useId = randomUUID();
+  const extra = { use_id: useId };
+  if (via) extra["via"] = via;
+  const reported = reportId ? await reportSkillEvent(env, "use", reportId, skillDirDigest(path), name, extra) : false;
+  const skillMd = readFileSync3(join4(path, "SKILL.md"), "utf8");
+  if (opts.json) {
+    console.log(JSON.stringify({ skill: reportId ?? name, path, where, use_id: reportId ? useId : void 0, skill_md: skillMd }));
+  } else {
     const label = { local: "\u672C\u5730", mod: "\u5E73\u53F0 mod", fetched: "\u5DF2\u4E0B\u8F7D\u5230\u4E34\u65F6\u76EE\u5F55" }[where];
-    console.log(`${name} \u5C31\u7EEA\uFF08${label}\uFF09\uFF1A`);
-    console.log(`  ${join4(path, "SKILL.md")}`);
+    console.log(`${reportId ?? name} \u5C31\u7EEA\uFF08${label}${via === "pointer" ? "\uFF0C\u7ECF\u6307\u9488" : ""}\uFF09`);
+    console.log(`skill \u76EE\u5F55\uFF1A${path}`);
+    console.log(`SKILL.md \u91CC\u7684\u76F8\u5BF9\u8DEF\u5F84\u90FD\u4ECE\u8FD9\u4E2A\u76EE\u5F55\u7B97\u8D77\u3002\u4E0B\u9762\u5C31\u662F SKILL.md \u7684\u5168\u6587\uFF0C\u7167\u7740\u505A\u5373\u53EF\uFF08\u4E0D\u7528\u518D\u8BFB\u4E00\u6B21\u6587\u4EF6\uFF09\u3002`);
     console.log(`
-\u7528 agent \u8BFB\u4E0A\u9762\u7684\u8DEF\u5F84\u5373\u53EF\uFF08use \u4E0D\u5B89\u88C5\u3001\u4E0D\u6539\u9879\u76EE\u6587\u4EF6\uFF09\u3002`);
+----- SKILL.md -----
+${skillMd}${skillMd.endsWith("\n") ? "" : "\n"}----- end -----`);
   }
   if (notice && reportId && !env.anonymous) shareNotice(reportId, path, notice === "draft", reported);
   return 0;
@@ -27377,7 +27468,7 @@ skills.command("find").description("\u627E skill\uFF08\u751F\u6001\u8D26\u672C+\
 skills.command("add").description("\u88C5 skill\uFF08find \u7ED3\u679C\u7684 id\uFF1A\u4E0B\u8F7D\u4F5C\u8005\u7528\u8FC7\u7684\u90A3\u4E00\u7248\uFF1B\u6216\u81EA\u5DF1\u8349\u7A3F\u533A\u7684\u540D\u5B57\uFF1A\u79FB\u5230 .agents/skills/\uFF09").argument("<id-or-name>", "find \u8FD4\u56DE\u7684 skill id\uFF0C\u6216\u81EA\u5DF1\u8349\u7A3F\u533A\u7684 skill \u540D").option("--dir <dir>", "\u5B89\u88C5\u76EE\u5F55\uFF08\u9ED8\u8BA4 .agents/skills/\uFF09", ".agents/skills").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").action(async (idOrName, opts) => {
   await run(cmdAdd(idOrName, opts));
 });
-skills.command("use").description("\u7528 skill\uFF08\u4E0D\u88C5\uFF1A\u672C\u5730\u6709\u2192\u7ED9\u8DEF\u5F84\uFF1B\u672C\u5730\u6CA1\u6709\u4E14\u662F id\u2192\u4E0B\u8F7D\u5230\u4E34\u65F6\u76EE\u5F55+\u7ED9\u8DEF\u5F84\uFF09").argument("<id-or-name>", "skill id \u6216 name").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").action(async (idOrName, opts) => {
+skills.command("use").description("\u7528 skill\uFF08\u4E0D\u88C5\uFF1A\u6253\u5370 SKILL.md \u5168\u6587\u548C skill \u76EE\u5F55\uFF1B\u672C\u5730\u6709\u2192\u7528\u672C\u5730\u7684\uFF1B\u672C\u5730\u662F\u6307\u9488\u6216\u6CA1\u6709\u2192\u6309 id \u4E0B\u8F7D\u5230\u4E34\u65F6\u76EE\u5F55\uFF09").argument("<id-or-name>", "skill id \u6216 name").option("--json", "\u7D27\u51D1 JSON \u8F93\u51FA\uFF08agent \u6D88\u8D39\uFF09").option("--via <channel>", "\u4ECE\u54EA\u4E2A\u6E20\u9053\u6765\u7684\uFF08\u8BB0\u8FDB\u4F7F\u7528\u8BB0\u5F55\uFF1Bhub mod \u7684\u6307\u9488\u5199 pointer\uFF09").action(async (idOrName, opts) => {
   await run(cmdUse(idOrName, opts));
 });
 skills.command("init").description("\u521B\u5EFA skill \u811A\u624B\u67B6\uFF08SKILL.md + frontmatter \u89C4\u8303\uFF09").argument("[name]", "skill \u540D\uFF08kebab-case\uFF09").option("--here", "\u5728\u5F53\u524D\u76EE\u5F55\u751F\u6210\uFF08\u9ED8\u8BA4\u751F\u6210\u5230 ./<name>/ \u5B50\u76EE\u5F55\uFF09").action(async (name, opts) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/neta-search-cli",
-  "version": "0.2.8",
+  "version": "0.2.14",
   "description": "neta-search CLI — find, try and install skills from the Cohub / Neta skill registry",
   "type": "module",
   "bin": {