@manturhub/cli 0.9.11 → 0.10.1

package/README.md

@@ -51,12 +51,32 @@ CLI 会在付费调用前按算子实时 schema 校验未知字段、必填项
 | `manturhub balance [--json]` | 查询余额及美元等值（1 馒头 = $0.01 USD） |
 | `manturhub skill ls [--json]` / `skill add <slug> [--client codex]` | 浏览并从当前 ManturHub 站点安装业务 Skill |
 | `manturhub skill outdated [--json]` / `skill update <slug> [--force]` | 比较本地与线上版本并更新；本地修改默认不覆盖 |
+| `manturhub skill doctor <slug>` / `skill run <slug> --project <目录>` | 验证 Skill 安装与依赖；从指定项目目录启动或恢复工作流 |
+| `manturhub skill exec <slug> <action> -- <参数>` | 给 Agent 使用的安全机器入口；只执行 Skill 包声明的白名单动作 |
 | `manturhub recipe [关键词]` / `recipe get <ID>` | 搜索并查看已验证配方 |
 | `manturhub suite ls [--json]` / `suite install <slug>` | 安装多角色 Agent 套件，不复制 API Key |
 | `manturhub init [--force]` | 从线上安装核心 `manturhub` Skill，并给当前项目写入 Agent 使用引导 |
 
 机器消费输出可在支持的查询命令上加 `--json`。进度和提示写入 stderr，JSON 结果写入 stdout。
 
+## Skill 本地运行契约
+
+需要确定性本地动作的 Skill 可在包根目录声明 `skill-runtime.json`：
+
+```json
+{
+  "schema_version": 1,
+  "runtime": "node",
+  "minimum_cli_version": "0.10.0",
+  "entry": "runtime/runner.mjs",
+  "doctor_action": "doctor",
+  "run_action": "run",
+  "actions": ["doctor", "run", "validate-input"]
+}
+```
+
+CLI 只执行 `actions` 白名单内的动作，且入口必须是 Skill 包内的 `.mjs` 文件。执行前会验证当前站点、可信安装记录、整包 SHA-256、frontmatter 版本和最低 CLI 版本；本地内容被修改、入口越界或动作未声明时直接失败，不会寻找其他脚本或解释器。动作必须只向 stdout 写一个 JSON object，日志与进度写 stderr。
+
 环境变量：`MANTURHUB_KEY`（优先于配置文件） · `MANTURHUB_BASE`（测试或私有部署覆盖，默认 `https://hub.mantur.ai`）。
 
 ManturHub 算子广场：https://hub.mantur.ai

package/bin/cli.js

@@ -7,6 +7,11 @@ import { suiteLs, suiteInstall } from "../lib/suite-install.js";
 import { loginViaBrowser } from "../lib/login-link.js";
 import { maybeNotifyUpdate } from "../lib/update-check.js";
 import { maybeNotifySkillUpdates } from "../lib/skill-update-check.js";
+import {
+  executeSkillAction,
+  parseSkillExecutionArgs,
+  resolveInstalledSkillRuntime,
+} from "../lib/skill-runtime.js";
 import { createReadStream, readFileSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, basename, extname } from "node:path";
@@ -147,6 +152,12 @@ const HELP = `manturhub — ManturHub 算子广场 CLI  v${VERSION}
   manturhub skill outdated            比较本地安装与当前站点的线上版本
   manturhub skill update <slug> [--client ...] [--force]
                                       从线上更新；本地改过时默认拒绝覆盖
+  manturhub skill doctor <slug> [--client ...] [-- <参数>]
+                                      验证安装完整性并运行 Skill 声明的预检
+  manturhub skill run <slug> --project <目录> [--client ...] [-- <参数>]
+                                      从项目目录启动或恢复 Skill 工作流
+  manturhub skill exec <slug> <action> [--client ...] [--project <目录>] [-- <参数>]
+                                      运行 Skill 白名单内的机器动作
   manturhub suite ls                  列出 Agent 套件（多角色团队工作区，给 Agent 配一整个团队）
   manturhub suite install <slug>      安装套件为工作目录 ./<slug>/（不复制 API Key）
   manturhub recipe [关键词] [--cat x] 搜配方（已验证创作的效果+可复现参数；分类 video/image/script）
@@ -325,6 +336,20 @@ async function main() {
         console.error(error.message);
         process.exit(1);
       }
+      if (operator.billing_mode === "internal_free") {
+        const free = {
+          operator_id: operator.id,
+          billing_mode: "internal_free",
+          estimated_dumplings: 0,
+          formula: "内部管理员只读查询，不扣馒头",
+        };
+        console.log(
+          args.includes("--json")
+            ? JSON.stringify(free, null, 2)
+            : `${operator.name}: 内部管理员只读查询，不扣馒头`
+        );
+        break;
+      }
       const r = await apiFetch(`/api/v1/operators/${encodeURIComponent(operator.id)}/quote`, { auth: "optional" });
       if (!r.ok) {
         console.error(`查询价格失败（HTTP ${r.status}）: ${JSON.stringify(r.json)}`);
@@ -409,7 +434,7 @@ async function main() {
         process.exit(1);
       }
       let quoteId = getFlag("confirm");
-      if (!quoteId) {
+      if (!quoteId && operator.billing_mode !== "internal_free") {
         const quote = await apiFetch(`/api/v1/operators/${encodeURIComponent(operatorId)}/quote`, {
           method: "POST",
           body,
@@ -623,11 +648,49 @@ async function main() {
           process.exit(1);
         }
         await skillUpdate(args[2], getFlag("client"), { force: hasFlag("force") });
+      } else if (sub === "doctor" || sub === "run" || sub === "exec") {
+        const slug = args[2];
+        if (!slug || slug.startsWith("--")) {
+          console.error(`用法: manturhub skill ${sub} <slug>${sub === "exec" ? " <action>" : ""}`);
+          process.exit(1);
+        }
+        let action;
+        let remaining;
+        if (sub === "exec") {
+          action = args[3];
+          if (!action || action.startsWith("--")) {
+            console.error("用法: manturhub skill exec <slug> <action> [--client ...] [--project <目录>] [-- <参数>]");
+            process.exit(1);
+          }
+          remaining = args.slice(4);
+        } else {
+          remaining = args.slice(3);
+        }
+        let options;
+        try {
+          options = parseSkillExecutionArgs(remaining, { requireProject: sub === "run" });
+          if (!action) {
+            const runtime = resolveInstalledSkillRuntime(slug, {
+              client: options.client,
+              cliVersion: VERSION,
+            });
+            action = sub === "doctor" ? runtime.manifest.doctor_action : runtime.manifest.run_action;
+            if (!action) throw new Error(`Skill「${slug}」没有声明 ${sub}_action`);
+          }
+          const exitCode = await executeSkillAction(slug, action, options.actionArgs, {
+            client: options.client,
+            project: options.project,
+            cliVersion: VERSION,
+          });
+          if (exitCode !== 0) process.exit(exitCode);
+        } catch (error) {
+          console.error(error.message);
+          process.exit(1);
+        }
       }
       else {
         console.error(
-          "用法: manturhub skill ls | outdated | add <slug> | update <slug>"
-          + " [--client claude-code|codex|all] [--force]"
+          "用法: manturhub skill ls | outdated | add <slug> | update <slug> | doctor <slug> | run <slug> | exec <slug> <action>"
         );
         process.exit(1);
       }

package/lib/api.js

@@ -20,6 +20,7 @@ export async function apiFetch(
     fetch(url, {
       method,
       headers: {
+        "X-Mantur-Client": "cli",
         ...(includeKey && apiKey ? { "x-api-key": apiKey } : {}),
         ...(body ? { "Content-Type": "application/json" } : {}),
         ...headers,

package/lib/skill-runtime.js

@@ -0,0 +1,332 @@
+import { spawn } from "node:child_process";
+import {
+  existsSync,
+  lstatSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateSlug } from "./archive.js";
+import { getBaseUrl } from "./config.js";
+import {
+  compareSkillVersions,
+  getSkillRecord,
+  hashSkillDirectory,
+  loadSkillState,
+  readInstalledSkillMetadata,
+  skillDestination,
+} from "./skill-state.js";
+
+const MANIFEST_NAME = "skill-runtime.json";
+const MAX_OUTPUT_BYTES = 10 * 1024 * 1024;
+const SUPPORTED_CLIENTS = new Set(["codex", "claude-code"]);
+const ACTION_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+const CLI_ENTRY = fileURLToPath(new URL("../bin/cli.js", import.meta.url));
+
+function plainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function validateRecordedBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`Skill 安装记录的 ManturHub 环境不合法: ${value}`);
+  }
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (
+    (url.protocol !== "https:" && !(url.protocol === "http:" && loopback))
+    || url.username
+    || url.password
+    || url.pathname !== "/"
+    || url.search
+    || url.hash
+  ) {
+    throw new Error(`Skill 安装记录的 ManturHub 环境不安全: ${value}`);
+  }
+  return url.href.replace(/\/$/, "");
+}
+
+function validateActionName(value, label = "action") {
+  if (typeof value !== "string" || !ACTION_PATTERN.test(value)) {
+    throw new Error(`${label} 格式不合法: ${value || "(空)"}`);
+  }
+  return value;
+}
+
+function validateEntryPath(skillDir, entry) {
+  if (
+    typeof entry !== "string"
+    || !entry
+    || entry.includes("\\")
+    || isAbsolute(entry)
+    || entry.split("/").some((part) => !part || part === "." || part === "..")
+  ) {
+    throw new Error("Skill runtime entry 必须是包内相对路径");
+  }
+  if (!entry.endsWith(".mjs")) {
+    throw new Error("Skill runtime entry 必须是 .mjs 文件");
+  }
+  const root = realpathSync(skillDir);
+  const target = resolve(root, entry);
+  const relation = relative(root, target);
+  if (!relation || relation.startsWith("..") || isAbsolute(relation)) {
+    throw new Error("Skill runtime entry 超出 Skill 包目录");
+  }
+  if (!existsSync(target) || !lstatSync(target).isFile()) {
+    throw new Error(`Skill runtime entry 不存在: ${entry}`);
+  }
+  const realTarget = realpathSync(target);
+  const realRelation = relative(root, realTarget);
+  if (realRelation.startsWith("..") || isAbsolute(realRelation)) {
+    throw new Error("Skill runtime entry 指向包外路径");
+  }
+  return realTarget;
+}
+
+export function readSkillRuntimeManifest(skillDir, cliVersion) {
+  const manifestPath = join(skillDir, MANIFEST_NAME);
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    throw new Error(`Skill 缺少有效的 ${MANIFEST_NAME}: ${error.message}`);
+  }
+  if (!plainObject(manifest) || manifest.schema_version !== 1) {
+    throw new Error("Skill runtime manifest 的 schema_version 必须为 1");
+  }
+  if (manifest.runtime !== "node") {
+    throw new Error(`不支持的 Skill runtime: ${manifest.runtime || "(空)"}`);
+  }
+  if (!manifest.minimum_cli_version) {
+    throw new Error("Skill runtime manifest 缺少 minimum_cli_version");
+  }
+  const compatible = compareSkillVersions(cliVersion, manifest.minimum_cli_version);
+  if (compatible === null) {
+    throw new Error(`无法比较 CLI 版本: ${cliVersion} / ${manifest.minimum_cli_version}`);
+  }
+  if (compatible < 0) {
+    throw new Error(
+      `此 Skill 需要 ManturHub CLI >= ${manifest.minimum_cli_version}，当前为 ${cliVersion}。`
+      + "请先运行: npm i -g @manturhub/cli@latest"
+    );
+  }
+  if (!Array.isArray(manifest.actions) || !manifest.actions.length || manifest.actions.length > 100) {
+    throw new Error("Skill runtime manifest 的 actions 必须是 1-100 个动作名");
+  }
+  const actions = new Set();
+  for (const action of manifest.actions) {
+    validateActionName(action, "Skill action");
+    if (actions.has(action)) throw new Error(`Skill runtime manifest 包含重复 action: ${action}`);
+    actions.add(action);
+  }
+  for (const field of ["doctor_action", "run_action"]) {
+    if (manifest[field] !== undefined) {
+      validateActionName(manifest[field], field);
+      if (!actions.has(manifest[field])) {
+        throw new Error(`${field} 未列入 actions 白名单: ${manifest[field]}`);
+      }
+    }
+  }
+  return {
+    ...manifest,
+    actions,
+    entryPath: validateEntryPath(skillDir, manifest.entry),
+  };
+}
+
+function validateTrackedInstallation(slug, client, baseUrl, state) {
+  const skillDir = skillDestination(slug, client);
+  if (!existsSync(skillDir)) return null;
+  if (lstatSync(skillDir).isSymbolicLink() || !lstatSync(skillDir).isDirectory()) {
+    throw new Error(`Skill「${slug}」安装目录不是可信普通目录，拒绝执行`);
+  }
+  const record = getSkillRecord(state, slug, client);
+  if (!record) {
+    throw new Error(
+      `本地 Skill「${slug}」[${client}] 没有可信安装记录。请用 manturhub skill update ${slug} --client ${client} --force 重新安装。`
+    );
+  }
+  if (record.base_url !== baseUrl) {
+    throw new Error(
+      `Skill「${slug}」来自 ${record.base_url}，当前连接 ${baseUrl}；为防止跨站运行已停止。`
+    );
+  }
+  const expectedPath = skillDestination(slug, client);
+  if (record.path && resolve(record.path) !== resolve(expectedPath)) {
+    throw new Error(`Skill「${slug}」安装记录路径异常`);
+  }
+  const actualHash = hashSkillDirectory(skillDir);
+  if (!record.content_sha256 || actualHash !== record.content_sha256) {
+    throw new Error(
+      `Skill「${slug}」[${client}] 内容哈希与安装记录不一致，拒绝执行。请检查本地修改或重新安装。`
+    );
+  }
+  const metadata = readInstalledSkillMetadata(skillDir);
+  if (metadata.name !== slug || metadata.version !== record.version) {
+    throw new Error(`Skill「${slug}」frontmatter 与可信安装记录不一致，拒绝执行`);
+  }
+  return { client, skillDir, record, contentSha256: actualHash };
+}
+
+export function resolveInstalledSkillRuntime(slug, { client, cliVersion }) {
+  validateSlug(slug, "Skill ID");
+  if (client && !SUPPORTED_CLIENTS.has(client)) {
+    throw new Error(`不支持的 Skill 客户端: ${client}`);
+  }
+  const state = loadSkillState();
+  if (client) {
+    const record = getSkillRecord(state, slug, client);
+    if (!record) validateTrackedInstallation(slug, client, getBaseUrl(), state);
+    const baseUrl = process.env.MANTURHUB_BASE
+      ? getBaseUrl()
+      : validateRecordedBaseUrl(record?.base_url);
+    const selected = validateTrackedInstallation(slug, client, baseUrl, state);
+    if (!selected) throw new Error(`未安装 Skill「${slug}」[${client}]`);
+    return {
+      ...selected,
+      baseUrl,
+      manifest: readSkillRuntimeManifest(selected.skillDir, cliVersion),
+    };
+  }
+
+  const installedClients = [...SUPPORTED_CLIENTS].filter((candidate) =>
+    existsSync(skillDestination(slug, candidate))
+  );
+  if (!installedClients.length) {
+    throw new Error(`未安装 Skill「${slug}」。请先运行: manturhub skill add ${slug}`);
+  }
+  if (installedClients.length > 1) {
+    const records = installedClients.map((candidate) => getSkillRecord(state, slug, candidate));
+    if (
+      records.some((record) => !record)
+      || new Set(records.map((record) => `${record.base_url}:${record.content_sha256}`)).size !== 1
+    ) {
+      throw new Error(`Skill「${slug}」存在多个不一致安装，请用 --client codex 或 --client claude-code 明确选择`);
+    }
+  }
+  const selectedClient = installedClients.includes("codex") ? "codex" : installedClients[0];
+  const selectedRecord = getSkillRecord(state, slug, selectedClient);
+  if (!selectedRecord) validateTrackedInstallation(slug, selectedClient, getBaseUrl(), state);
+  const baseUrl = process.env.MANTURHUB_BASE
+    ? getBaseUrl()
+    : validateRecordedBaseUrl(selectedRecord?.base_url);
+  const selected = validateTrackedInstallation(slug, selectedClient, baseUrl, state);
+  return {
+    ...selected,
+    baseUrl,
+    manifest: readSkillRuntimeManifest(selected.skillDir, cliVersion),
+  };
+}
+
+function collectProcessOutput(child) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let stdout = "";
+    let stdoutBytes = 0;
+    let failed = false;
+    child.stdout.on("data", (chunk) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > MAX_OUTPUT_BYTES) {
+        failed = true;
+        child.kill();
+        rejectPromise(new Error("Skill action stdout 超过 10 MB 限制"));
+        return;
+      }
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr.on("data", (chunk) => process.stderr.write(chunk));
+    child.on("error", rejectPromise);
+    child.on("close", (code, signal) => {
+      if (!failed) resolvePromise({ code, signal, stdout });
+    });
+  });
+}
+
+export async function executeSkillAction(
+  slug,
+  action,
+  actionArgs,
+  { client, project, cliVersion }
+) {
+  validateActionName(action);
+  const runtime = resolveInstalledSkillRuntime(slug, { client, cliVersion });
+  if (!runtime.manifest.actions.has(action)) {
+    throw new Error(`Skill「${slug}」未声明 action: ${action}`);
+  }
+  let projectDir = process.cwd();
+  if (project) {
+    const requested = resolve(project);
+    if (!existsSync(requested) || !lstatSync(requested).isDirectory()) {
+      throw new Error(`项目目录不存在或不是目录: ${project}`);
+    }
+    projectDir = realpathSync(requested);
+  }
+  const child = spawn(process.execPath, [runtime.manifest.entryPath, action, ...actionArgs], {
+    cwd: projectDir,
+    env: {
+      ...process.env,
+      MANTURHUB_BASE: runtime.baseUrl,
+      MANTURHUB_CLI_ENTRY: CLI_ENTRY,
+      MANTURHUB_SKILL_DIR: runtime.skillDir,
+      MANTURHUB_SKILL_SLUG: slug,
+      MANTURHUB_SKILL_ACTION: action,
+      MANTURHUB_PROJECT: projectDir,
+    },
+    stdio: ["inherit", "pipe", "pipe"],
+  });
+  const result = await collectProcessOutput(child);
+  let payload;
+  try {
+    payload = JSON.parse(result.stdout);
+  } catch {
+    throw new Error(`Skill action「${action}」没有返回合法 JSON object`);
+  }
+  if (!plainObject(payload)) {
+    throw new Error(`Skill action「${action}」必须返回 JSON object`);
+  }
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  if (result.signal) throw new Error(`Skill action「${action}」被信号 ${result.signal} 终止`);
+  return Number.isInteger(result.code) ? result.code : 1;
+}
+
+export function parseSkillExecutionArgs(tokens, { requireProject = false } = {}) {
+  let client;
+  let project;
+  const actionArgs = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token === "--") {
+      actionArgs.push(...tokens.slice(i + 1));
+      break;
+    }
+    if (token === "--client" || token === "--project") {
+      const value = tokens[++i];
+      if (!value || value.startsWith("--")) throw new Error(`参数 ${token} 缺少值`);
+      if (token === "--client") {
+        if (client !== undefined) throw new Error("选项 --client 不能重复");
+        client = value;
+      } else {
+        if (project !== undefined) throw new Error("选项 --project 不能重复");
+        project = value;
+      }
+      continue;
+    }
+    if (token.startsWith("--client=")) {
+      if (client !== undefined) throw new Error("选项 --client 不能重复");
+      client = token.slice("--client=".length);
+      if (!client) throw new Error("参数 --client 缺少值");
+      continue;
+    }
+    if (token.startsWith("--project=")) {
+      if (project !== undefined) throw new Error("选项 --project 不能重复");
+      project = token.slice("--project=".length);
+      if (!project) throw new Error("参数 --project 缺少值");
+      continue;
+    }
+    actionArgs.push(token);
+  }
+  if (requireProject && !project) throw new Error("manturhub skill run 必须提供 --project <目录>");
+  return { client, project, actionArgs };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manturhub/cli",
-  "version": "0.9.11",
+  "version": "0.10.1",
   "description": "ManturHub 算子广场 CLI：通过 REST 发现和调用 AI 算子、浏览配方，并安装 Skill 与 Agent 套件",
   "type": "module",
   "bin": {