aixlab-skills 0.1.0

package/README.md

@@ -0,0 +1,9 @@
+# aixlab-skills
+
+AixLab 自有数字资产平台的 Agent Skill 安装器。它通过浏览器设备授权取得最小权限令牌，下载用户已拥有的私有 ZIP，校验 SHA-256 与 `SKILL.md` 名称后，再调用固定版本的通用 `skills` CLI 完成全局复制安装。
+
+```bash
+npx aixlab-skills add xhs-creator -g -y
+```
+
+本地联调可设置 `AIXLAB_SKILLS_HOST=http://localhost:8180`。生产环境默认连接 `https://www.aixc4d.com`。本目录只包含待发布的 npm 包源码；发布属于独立操作。

package/bin/aixlab-skills.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { run } from "../src/index.js";
+
+const result = await run(process.argv.slice(2));
+
+process.stdout.write(`${JSON.stringify(result)}\n`);
+
+if (! result.success) {
+    process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "aixlab-skills",
+  "version": "0.1.0",
+  "description": "Secure installer for owned AixLab agent Skills",
+  "type": "module",
+  "bin": {
+    "aixlab-skills": "bin/aixlab-skills.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "agent-skills",
+    "codex",
+    "aixlab"
+  ],
+  "license": "UNLICENSED",
+  "dependencies": {
+    "yauzl": "3.4.0"
+  },
+  "devDependencies": {
+    "yazl": "3.3.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,463 @@
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { chmod, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { homedir, platform, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { spawn } from "node:child_process";
+import yauzl from "yauzl";
+
+const DEFAULT_HOST = "https://www.aixc4d.com";
+const GENERIC_INSTALLER_VERSION = "1.5.22";
+const MAX_PACKAGE_BYTES = 100 * 1024 * 1024;
+const MAX_ARCHIVE_ENTRIES = 2000;
+
+export function parseArguments(args) {
+    const values = [...args];
+
+    if (values.shift() !== "add") {
+        throw new Error("用法：aixlab-skills add <skill-name> -g -y");
+    }
+
+    const skillName = values.shift() ?? "";
+
+    if (! /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skillName)) {
+        throw new Error("Skill 名称格式无效。");
+    }
+
+    const accepted = new Set(["-g", "--global", "-y", "--yes"]);
+
+    if (values.some(value => ! accepted.has(value))) {
+        throw new Error("包含不支持的安装参数。");
+    }
+
+    return { skillName };
+}
+
+export function normalizeHost(rawHost) {
+    const url = new URL(rawHost || DEFAULT_HOST);
+    const localHttp = url.protocol === "http:"
+        && ["localhost", "127.0.0.1", "::1"].includes(url.hostname);
+
+    if ((url.protocol !== "https:" && ! localHttp)
+        || url.username
+        || url.password
+        || url.search
+        || url.hash
+    ) {
+        throw new Error("AIXLAB_SKILLS_HOST 必须是 HTTPS 地址；仅本机调试允许 HTTP。");
+    }
+
+    url.pathname = url.pathname.replace(/\/?$/, "/");
+
+    return url;
+}
+
+export function skillNameFromMarkdown(markdown) {
+    const text = String(markdown).replace(/^\uFEFF/, "");
+    const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] ?? "";
+    const match = frontmatter.match(/^name:\s*(["']?)([a-z0-9]+(?:-[a-z0-9]+)*)\1\s*$/m);
+
+    return match?.[2] ?? "";
+}
+
+function configPath() {
+    return join(homedir(), ".config", "aixlab-skills", "config.json");
+}
+
+async function loadToken(host) {
+    const environmentToken = process.env.AIXLAB_SKILLS_TOKEN?.trim();
+
+    if (environmentToken) return environmentToken;
+
+    try {
+        const stored = JSON.parse(await readFile(configPath(), "utf8"));
+
+        return stored.host === host.origin && typeof stored.access_token === "string"
+            ? stored.access_token
+            : null;
+    } catch {
+        return null;
+    }
+}
+
+async function saveToken(host, token) {
+    const target = configPath();
+    const temporary = `${target}.${process.pid}.tmp`;
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    await writeFile(temporary, `${JSON.stringify({ host: host.origin, access_token: token })}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    await chmod(temporary, 0o600);
+    await rename(temporary, target);
+}
+
+async function requestJson(host, path, { method = "GET", token, body, statuses = [200] } = {}) {
+    const url = new URL(path.replace(/^\//, ""), host);
+    const response = await fetch(url, {
+        method,
+        redirect: "manual",
+        headers: {
+            Accept: "application/json",
+            ...(body ? { "Content-Type": "application/json" } : {}),
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    let payload = {};
+
+    try {
+        payload = await response.json();
+    } catch {
+        // The status remains the source of truth for malformed error responses.
+    }
+
+    if (! statuses.includes(response.status)) {
+        const error = new Error(payload.message || payload.error || `平台请求失败（HTTP ${response.status}）。`);
+        error.status = response.status;
+        throw error;
+    }
+
+    return { status: response.status, payload };
+}
+
+function openBrowser(url) {
+    const command = platform() === "win32"
+        ? ["explorer.exe", [url]]
+        : platform() === "darwin"
+            ? ["open", [url]]
+            : ["xdg-open", [url]];
+
+    try {
+        const child = spawn(command[0], command[1], { detached: true, stdio: "ignore" });
+        child.unref();
+    } catch {
+        // Printing the URL is sufficient when the desktop opener is unavailable.
+    }
+}
+
+async function authorizeDevice(host) {
+    const { payload } = await requestJson(host, "marketplace-cli/device-codes", { method: "POST" });
+    const expiresIn = Number(payload.expires_in);
+    const interval = Number(payload.interval);
+
+    if (typeof payload.device_code !== "string"
+        || typeof payload.user_code !== "string"
+        || typeof payload.verification_uri_complete !== "string"
+        || ! Number.isFinite(expiresIn)
+        || ! Number.isFinite(interval)
+    ) {
+        throw new Error("平台返回了无效的设备授权信息。");
+    }
+
+    process.stderr.write(`请在浏览器中确认 AixLab 安装授权：\n${payload.verification_uri_complete}\n授权码：${payload.user_code}\n`);
+    openBrowser(payload.verification_uri_complete);
+    const deadline = Date.now() + (expiresIn * 1000);
+
+    while (Date.now() < deadline) {
+        await new Promise(resolve => setTimeout(resolve, Math.max(2, interval) * 1000));
+        const result = await requestJson(host, "marketplace-cli/device-token", {
+            method: "POST",
+            body: { device_code: payload.device_code },
+            statuses: [200, 202, 410],
+        });
+
+        if (result.status === 202) continue;
+        if (result.status === 410) break;
+
+        if (typeof result.payload.access_token !== "string" || result.payload.token_type !== "Bearer") {
+            throw new Error("平台返回了无效的访问令牌。");
+        }
+
+        await saveToken(host, result.payload.access_token);
+
+        return result.payload.access_token;
+    }
+
+    throw new Error("安装授权已过期，请重新执行原命令。");
+}
+
+function validateManifest(payload, skillName, host) {
+    const packageData = payload?.package;
+
+    if (payload?.skill_name !== skillName
+        || typeof payload.version !== "string"
+        || ! packageData
+        || typeof packageData.url !== "string"
+        || typeof packageData.sha256 !== "string"
+        || ! /^[0-9a-f]{64}$/.test(packageData.sha256)
+        || ! Number.isSafeInteger(packageData.size_bytes)
+        || packageData.size_bytes < 0
+        || packageData.size_bytes > MAX_PACKAGE_BYTES
+    ) {
+        throw new Error("平台返回了无效的 Skill 安装清单。");
+    }
+
+    const packageUrl = new URL(packageData.url);
+
+    if (packageUrl.origin !== host.origin || packageUrl.protocol !== host.protocol) {
+        throw new Error("平台返回的下载地址不属于当前 AixLab 站点。");
+    }
+
+    return { ...payload, package: { ...packageData, url: packageUrl } };
+}
+
+async function issuePackage(host, token, skillName) {
+    const { payload } = await requestJson(
+        host,
+        `marketplace-cli/skills/${encodeURIComponent(skillName)}/package-access`,
+        { method: "POST", token },
+    );
+
+    return validateManifest(payload, skillName, host);
+}
+
+async function downloadPackage(manifest, token, target) {
+    const response = await fetch(manifest.package.url, {
+        headers: { Authorization: `Bearer ${token}`, Accept: "application/zip" },
+        redirect: "manual",
+    });
+
+    if (response.status !== 200) {
+        throw new Error(`Skill 下载失败（HTTP ${response.status}）。`);
+    }
+
+    const bytes = Buffer.from(await response.arrayBuffer());
+
+    if (bytes.length !== manifest.package.size_bytes
+        || createHash("sha256").update(bytes).digest("hex") !== manifest.package.sha256
+    ) {
+        throw new Error("Skill 包完整性校验失败。");
+    }
+
+    await writeFile(target, bytes, { flag: "wx", mode: 0o600 });
+}
+
+function validatedEntryName(name) {
+    if (! name
+        || name.includes("\\")
+        || name.includes("\0")
+        || name.startsWith("/")
+        || /^[A-Za-z]:/.test(name)
+    ) {
+        throw new Error("Skill 包包含不安全的文件路径。");
+    }
+
+    const trimmed = name.endsWith("/") ? name.slice(0, -1) : name;
+    const segments = trimmed.split("/");
+
+    if (! trimmed || segments.some(segment => ! segment || segment === "." || segment === "..")) {
+        throw new Error("Skill 包包含不安全的文件路径。");
+    }
+
+    return segments;
+}
+
+export async function extractPackage(archive, destination) {
+    await mkdir(destination, { recursive: true, mode: 0o700 });
+
+    return new Promise((resolve, reject) => {
+        yauzl.open(archive, { lazyEntries: true, strictFileNames: true, validateEntrySizes: true }, (openError, zipfile) => {
+            if (openError || ! zipfile) {
+                reject(new Error("Skill 包不是有效的 ZIP 文件。", { cause: openError }));
+                return;
+            }
+
+            let settled = false;
+            let entryCount = 0;
+            let totalBytes = 0;
+            const paths = new Set();
+            const fail = error => {
+                if (settled) return;
+                settled = true;
+                zipfile.close();
+                reject(error);
+            };
+
+            zipfile.on("error", fail);
+            zipfile.on("end", () => {
+                if (settled) return;
+                settled = true;
+                resolve();
+            });
+            zipfile.on("entry", async entry => {
+                try {
+                    entryCount += 1;
+                    totalBytes += entry.uncompressedSize;
+
+                    if (entryCount > MAX_ARCHIVE_ENTRIES || totalBytes > MAX_PACKAGE_BYTES) {
+                        throw new Error("Skill 包超过安全解压限制。");
+                    }
+
+                    const segments = validatedEntryName(entry.fileName);
+                    const relative = segments.join("/");
+
+                    if (paths.has(relative)) {
+                        throw new Error("Skill 包包含重复文件路径。");
+                    }
+
+                    paths.add(relative);
+                    const mode = (entry.externalFileAttributes >>> 16) & 0o170000;
+                    const isDirectory = entry.fileName.endsWith("/");
+
+                    if (mode === 0o120000 || (mode !== 0 && mode !== 0o100000 && mode !== 0o040000)) {
+                        throw new Error("Skill 包包含不支持的文件类型。");
+                    }
+
+                    const target = join(destination, ...segments);
+
+                    if (isDirectory) {
+                        await mkdir(target, { recursive: true, mode: 0o700 });
+                        zipfile.readEntry();
+                        return;
+                    }
+
+                    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+                    zipfile.openReadStream(entry, async (streamError, stream) => {
+                        if (streamError || ! stream) {
+                            fail(new Error("无法读取 Skill 包内容。", { cause: streamError }));
+                            return;
+                        }
+
+                        try {
+                            await pipeline(stream, createWriteStream(target, { flags: "wx", mode: 0o600 }));
+                            zipfile.readEntry();
+                        } catch (error) {
+                            fail(error);
+                        }
+                    });
+                } catch (error) {
+                    fail(error);
+                }
+            });
+            zipfile.readEntry();
+        });
+    });
+}
+
+async function findSkillRoots(directory, depth = 0) {
+    if (depth > 4) return [];
+
+    const entries = await readdir(directory, { withFileTypes: true });
+    const roots = [];
+
+    if (entries.some(entry => entry.isFile() && entry.name === "SKILL.md")) {
+        roots.push(directory);
+    }
+
+    for (const entry of entries) {
+        if (entry.isDirectory() && entry.name !== "__MACOSX") {
+            roots.push(...await findSkillRoots(join(directory, entry.name), depth + 1));
+        }
+    }
+
+    return roots;
+}
+
+export async function validateExtractedSkill(directory, expectedName) {
+    const roots = await findSkillRoots(directory);
+
+    if (roots.length !== 1) {
+        throw new Error("Skill 包必须且只能包含一个 SKILL.md。");
+    }
+
+    const markdown = await readFile(join(roots[0], "SKILL.md"), "utf8");
+
+    if (skillNameFromMarkdown(markdown) !== expectedName) {
+        throw new Error("SKILL.md 的 name 与安装名称不一致。");
+    }
+
+    return roots[0];
+}
+
+export function installerArguments(skillRoot) {
+    return [
+        "--yes",
+        `skills@${GENERIC_INSTALLER_VERSION}`,
+        "add",
+        skillRoot,
+        "--global",
+        "--yes",
+        "--copy",
+    ];
+}
+
+async function installSkill(skillRoot) {
+    const executable = platform() === "win32" ? "npx.cmd" : "npx";
+    const child = spawn(executable, installerArguments(skillRoot), {
+        stdio: ["inherit", "pipe", "pipe"],
+        windowsHide: true,
+    });
+
+    child.stdout.pipe(process.stderr);
+    child.stderr.pipe(process.stderr);
+    const exitCode = await new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("close", resolve);
+    });
+
+    if (exitCode !== 0) {
+        throw new Error(`通用 Skills 安装器执行失败（退出码 ${exitCode}）。`);
+    }
+}
+
+async function execute(skillName) {
+    const major = Number(process.versions.node.split(".")[0]);
+
+    if (! Number.isInteger(major) || major < 20) {
+        throw new Error("aixlab-skills 需要 Node.js 20 或更高版本。");
+    }
+
+    const host = normalizeHost(process.env.AIXLAB_SKILLS_HOST || DEFAULT_HOST);
+    let token = await loadToken(host);
+
+    if (! token) token = await authorizeDevice(host);
+
+    let manifest;
+
+    try {
+        manifest = await issuePackage(host, token, skillName);
+    } catch (error) {
+        if (error.status !== 401) throw error;
+        token = await authorizeDevice(host);
+        manifest = await issuePackage(host, token, skillName);
+    }
+
+    const working = await mkdtemp(join(tmpdir(), "aixlab-skills-"));
+
+    try {
+        const archive = join(working, "package.zip");
+        const extracted = join(working, "extracted");
+        await downloadPackage(manifest, token, archive);
+        await extractPackage(archive, extracted);
+        const skillRoot = await validateExtractedSkill(extracted, skillName);
+        await installSkill(skillRoot);
+
+        return {
+            skill_name: skillName,
+            success: true,
+            version: manifest.version,
+            verified: true,
+            message: "Skill 已通过 AixLab 权益校验、完整性校验并完成全局安装。",
+        };
+    } finally {
+        await rm(working, { recursive: true, force: true });
+    }
+}
+
+export async function run(args) {
+    let skillName = "";
+
+    try {
+        ({ skillName } = parseArguments(args));
+
+        return await execute(skillName);
+    } catch (error) {
+        return {
+            skill_name: skillName,
+            success: false,
+            message: error instanceof Error ? error.message : "未知安装错误。",
+        };
+    }
+}