oh-my-agent-web 0.3.0 → 0.5.0

package/dist/server/skills/skillhub.js

@@ -0,0 +1,214 @@
+/**
+ * SkillHub（skillhub.tencent.com / api.skillhub.cn）技能市场。
+ *
+ * 接口来自参考实现 `/Users/dds/data/git/oh-my-skills`（`src/core/hub.ts` 与
+ * `src/core/skillhub-install.ts`），这里只保留 OMAW 需要的部分，并补上两个参考实现没有的细节：
+ *
+ *   - **列表**：`GET https://api.skillhub.cn/api/skills?page=&pageSize=&sortBy=score&order=desc&keyword=&category=`
+ *     返回 `{ code, data: { skills: [...], total } }`；字段名很花（`name`/`slug`/`namespace`/
+ *     `ownerName`/`downloads`/`stars`/`description_zh`…），这里统一收敛成一个结构。
+ *   - **下载**：`GET https://api.skillhub.cn/api/v1/download?slug=<slug>` → 一个 zip，
+ *     `SKILL.md` 一般在根目录，也可能套一层目录。
+ *   - **分类**：接口不给分类清单，参考实现是写死的 8 个 key（截图里那排就是它们）。
+ *
+ * 缓存：搜索结果在进程内存里放 5 分钟（同参数直接命中）。技能库首页是「打开面板就看」，
+ * 每次翻面板都打一次外网既慢又没必要。
+ */
+import { extractZip, skillRootOf } from "./zip.js";
+import { mkdtemp, readdir, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const BASE = "https://api.skillhub.cn";
+const SEARCH_TTL_MS = 5 * 60_000;
+const TIMEOUT_MS = 20_000;
+/** 分类清单：与 SkillHub 前端的 key 一致（接口不返回分类表） */
+export const HUB_CATEGORIES = [
+    { key: "", label: "全部" },
+    { key: "ai-intelligence", label: "AI 智能" },
+    { key: "developer-tools", label: "开发工具" },
+    { key: "productivity", label: "效率提升" },
+    { key: "data-analysis", label: "数据分析" },
+    { key: "content-creation", label: "内容创作" },
+    { key: "security-compliance", label: "安全合规" },
+    { key: "communication-collaboration", label: "通讯协作" },
+];
+function str(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * 条目自己带的分类（`dev-programming` 这种）跟筛选用的 key 是**两套词表**：
+ * 筛选那 8 个 key 是 SkillHub 前端的侧栏分类（接口会做别名映射，实测每个 key 命中数不同），
+ * 条目上的 `category` 则是更细的 12 类。两套都要有中文名，否则卡片上会直接露英文 key。
+ */
+const ITEM_CATEGORY_LABELS = {
+    "dev-programming": "开发编程",
+    "knowledge-management": "知识管理",
+    "life-service": "生活服务",
+    "office-efficiency": "办公效率",
+    "design-media": "设计媒体",
+    professional: "专业服务",
+    education: "教育学习",
+    "content-creation": "内容创作",
+    "data-analysis": "数据分析",
+    "ai-agent": "AI 智能体",
+    "business-ops": "商业运营",
+    "it-ops-security": "IT 运维安全",
+};
+function categoryLabel(key) {
+    if (key === undefined)
+        return undefined;
+    return ITEM_CATEGORY_LABELS[key] ?? HUB_CATEGORIES.find((item) => item.key === key)?.label ?? key;
+}
+/** 一条原始记录 → HubSkill（字段名各家不一，按优先级取第一个非空的） */
+function toHubSkill(raw) {
+    const slug = str(raw.slug) ?? str(raw.id);
+    const name = str(raw.name) ?? str(raw.title);
+    if (slug === undefined || name === undefined)
+        return null;
+    const namespace = record(raw.namespace);
+    const category = str(raw.category);
+    return {
+        slug,
+        name,
+        ...((str(raw.ownerName) ?? str(namespace?.handle) ?? str(raw.upstream_owner_login))
+            ? { author: str(raw.ownerName) ?? str(namespace?.handle) ?? str(raw.upstream_owner_login) }
+            : {}),
+        description: str(raw.description_zh) ?? str(raw.description) ?? str(raw.summary) ?? "",
+        ...(category === undefined ? {} : { category, categoryLabel: categoryLabel(category) }),
+        ...(num(raw.downloads) === undefined ? {} : { downloads: num(raw.downloads) }),
+        ...(num(raw.stars) === undefined ? {} : { stars: num(raw.stars) }),
+        ...(str(raw.version) === undefined ? {} : { version: str(raw.version) }),
+        ...(str(raw.homepage) === undefined ? {} : { homepage: str(raw.homepage) }),
+        ...(str(raw.iconUrl) === undefined ? {} : { iconUrl: str(raw.iconUrl) }),
+        ...(str(raw.source) === undefined ? {} : { source: str(raw.source) }),
+        ...(raw.verified === true ? { verified: true } : {}),
+    };
+}
+export function createSkillHub(options = {}) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const cache = new Map();
+    return {
+        async search(input) {
+            const page = Math.max(1, Math.floor(input.page ?? 1));
+            const pageSize = Math.max(1, Math.min(50, Math.floor(input.pageSize ?? 24)));
+            const query = (input.query ?? "").trim();
+            const category = (input.category ?? "").trim();
+            const key = `${query}\0${category}\0${page}\0${pageSize}`;
+            const hit = cache.get(key);
+            if (input.refresh !== true && hit !== undefined && Date.now() - hit.at < SEARCH_TTL_MS)
+                return hit.result;
+            const url = new URL(`${BASE}/api/skills`);
+            url.searchParams.set("page", String(page));
+            url.searchParams.set("pageSize", String(pageSize));
+            url.searchParams.set("sortBy", "score");
+            url.searchParams.set("order", "desc");
+            if (query !== "")
+                url.searchParams.set("keyword", query);
+            if (category !== "")
+                url.searchParams.set("category", category);
+            const response = await fetchImpl(url.toString(), {
+                headers: { accept: "application/json", "user-agent": "oh-my-agent-web" },
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            if (!response.ok)
+                throw new Error(`SkillHub 返回 HTTP ${response.status}`);
+            const payload = (await response.json());
+            const data = record(record(payload)?.data);
+            const list = Array.isArray(data?.skills) ? data.skills : [];
+            const seen = new Set();
+            const skills = [];
+            for (const item of list) {
+                const recordItem = record(item);
+                if (recordItem === null)
+                    continue;
+                const skill = toHubSkill(recordItem);
+                // SkillHub 同一个技能会出现多条（不同版本/命名空间）：按 slug 只留第一条，
+                // 否则界面里同一个技能排两遍，React 的 key 还会撞（重复 key 的渲染结果不可控）
+                if (skill === null || seen.has(skill.slug))
+                    continue;
+                seen.add(skill.slug);
+                skills.push(skill);
+            }
+            const total = num(data?.total);
+            const result = {
+                skills,
+                page,
+                pageSize,
+                ...(total === undefined ? {} : { total }),
+                hasMore: total === undefined ? skills.length === pageSize : page * pageSize < total,
+            };
+            cache.set(key, { at: Date.now(), result });
+            return result;
+        },
+        async fetchPackage(slug) {
+            const response = await fetchImpl(`${BASE}/api/v1/download?slug=${encodeURIComponent(slug)}`, {
+                headers: { accept: "application/zip", "user-agent": "oh-my-agent-web" },
+                signal: AbortSignal.timeout(60_000),
+            });
+            if (!response.ok) {
+                // 4xx 基本都是对面仓库里没有这一版的包（实测有技能 302 到 COS 后 404），
+                // 不是我们的参数错了 —— 把话说清楚，别让人去查自己的配置
+                throw new Error(response.status === 404
+                    ? "下载技能包失败：对方仓库里这一版的包不存在（SkillHub 数据问题，换一个技能或稍后再试）"
+                    : `下载技能包失败（HTTP ${response.status}）`);
+            }
+            const buffer = Buffer.from(await response.arrayBuffer());
+            const workDir = await mkdtemp(join(tmpdir(), "omaw-skill-"));
+            const cleanup = () => rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+            try {
+                const files = await extractZip(buffer, workDir);
+                const sub = skillRootOf(files);
+                if (sub === null)
+                    throw new Error("技能包里没有 SKILL.md");
+                const dir = sub === "" ? workDir : join(workDir, sub);
+                await stat(join(dir, "SKILL.md"));
+                return { dir, cleanup };
+            }
+            catch (error) {
+                await cleanup();
+                throw error;
+            }
+        },
+    };
+}
+/** 干净的技能目录名：只留字母数字与 `-_.`，并去掉开头那个点 */
+export function safeSkillDirName(raw) {
+    const cleaned = raw
+        .trim()
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/^\.+/, "")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return cleaned === "" ? "skill" : cleaned.slice(0, 80);
+}
+/** 目录里是不是一个技能（有 SKILL.md 或 .SKILL.md.disabled） */
+export async function hasSkillFile(dir) {
+    for (const name of ["SKILL.md", ".SKILL.md.disabled"]) {
+        const ok = await stat(join(dir, name))
+            .then((info) => info.isFile())
+            .catch(() => false);
+        if (ok)
+            return true;
+    }
+    return false;
+}
+/** 列一个目录下所有「是技能」的子目录名 */
+export async function listSkillDirs(root) {
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const names = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        if (await hasSkillFile(join(root, entry.name)))
+            names.push(entry.name);
+    }
+    return names.sort();
+}

package/dist/server/skills/zip.js

@@ -0,0 +1,121 @@
+/**
+ * 一个**够用就好**的 ZIP 解包器：把 SkillHub 下发的技能包解到临时目录。
+ *
+ * 为什么自己写而不装 `adm-zip`：这里只需要「读中央目录 → 逐个 inflate」这一件事
+ * （ADR-0008 的依赖预算），而 `node:zlib` 自带 `inflateRaw`，四十行就够。
+ *
+ * 安全边界（解压是典型的高危动作，一条都不能省）：
+ *   - 只认 `store`（0）与 `deflate`（8）两种方法，别的直接拒；
+ *   - 每个条目名先归一化：绝对路径、`..`、反斜杠（Windows 路径穿越）、符号链接一律拒绝；
+ *   - 单文件 8MB、总量 64MB 上限 —— 一个「技能包」不该比这更大，防 zip bomb；
+ *   - 只写普通文件与目录，不还原权限位、不还原时间（技能包不需要）。
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, normalize, sep } from "node:path";
+import { inflateRawSync } from "node:zlib";
+const MAX_ENTRY_BYTES = 8 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+/** 读中央目录：条目清单 + 名字（ZIP64 / 加密包直接拒，技能包用不上） */
+function readCentralDirectory(buffer) {
+    // 找 EOCD（末尾 22 字节起，注释最多 64KB）
+    let eocd = -1;
+    for (let offset = buffer.length - 22; offset >= Math.max(0, buffer.length - 22 - 0xffff); offset -= 1) {
+        if (buffer.readUInt32LE(offset) === 0x06054b50) {
+            eocd = offset;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new Error("不是 ZIP 文件（找不到目录结尾）");
+    const count = buffer.readUInt16LE(eocd + 10);
+    const directoryOffset = buffer.readUInt32LE(eocd + 16);
+    if (count === 0xffff || directoryOffset === 0xffffffff)
+        throw new Error("不支持 ZIP64 包");
+    const entries = [];
+    let offset = directoryOffset;
+    for (let index = 0; index < count; index += 1) {
+        if (offset + 46 > buffer.length || buffer.readUInt32LE(offset) !== 0x02014b50) {
+            throw new Error("ZIP 目录损坏");
+        }
+        const flags = buffer.readUInt16LE(offset + 8);
+        if ((flags & 0x1) !== 0)
+            throw new Error("不支持加密的 ZIP 包");
+        const nameLength = buffer.readUInt16LE(offset + 28);
+        const extraLength = buffer.readUInt16LE(offset + 30);
+        const commentLength = buffer.readUInt16LE(offset + 32);
+        const name = buffer.subarray(offset + 46, offset + 46 + nameLength).toString("utf8");
+        entries.push({
+            name,
+            method: buffer.readUInt16LE(offset + 10),
+            compressedSize: buffer.readUInt32LE(offset + 20),
+            uncompressedSize: buffer.readUInt32LE(offset + 24),
+            localHeaderOffset: buffer.readUInt32LE(offset + 42),
+        });
+        offset += 46 + nameLength + extraLength + commentLength;
+    }
+    return entries;
+}
+/** 条目名 → 安全的相对路径（不安全的直接抛，不静默跳过：坏包就该整个失败） */
+function safeRelativePath(name) {
+    if (name.endsWith("/"))
+        return null; // 目录条目：由文件的父目录创建
+    if (name.includes("\\"))
+        throw new Error(`包里出现 Windows 反斜杠路径：${name}`);
+    if (name.startsWith("/") || /^[A-Za-z]:/.test(name))
+        throw new Error(`包里出现绝对路径：${name}`);
+    const normalized = normalize(name);
+    if (normalized.startsWith("..") || normalized.includes(`${sep}..${sep}`) || normalized === "..") {
+        throw new Error(`包里出现越界路径：${name}`);
+    }
+    return normalized;
+}
+/**
+ * 解到 `destination`，返回解出来的相对文件清单。
+ * 调用方负责建临时目录、用完删掉（见 `skill-install.ts`）。
+ */
+export async function extractZip(buffer, destination) {
+    const entries = readCentralDirectory(buffer);
+    const written = [];
+    let total = 0;
+    for (const entry of entries) {
+        const relative = safeRelativePath(entry.name);
+        if (relative === null)
+            continue;
+        if (entry.uncompressedSize > MAX_ENTRY_BYTES)
+            throw new Error(`包里的 ${entry.name} 太大（>8MB）`);
+        total += entry.uncompressedSize;
+        if (total > MAX_TOTAL_BYTES)
+            throw new Error("包解压后太大（>64MB）");
+        // 跳到本地文件头，跳过它自己的名字与扩展字段
+        const header = entry.localHeaderOffset;
+        if (header + 30 > buffer.length || buffer.readUInt32LE(header) !== 0x04034b50) {
+            throw new Error(`ZIP 条目头损坏：${entry.name}`);
+        }
+        const nameLength = buffer.readUInt16LE(header + 26);
+        const extraLength = buffer.readUInt16LE(header + 28);
+        const start = header + 30 + nameLength + extraLength;
+        const raw = buffer.subarray(start, start + entry.compressedSize);
+        let content;
+        if (entry.method === 0)
+            content = raw;
+        else if (entry.method === 8)
+            content = inflateRawSync(raw);
+        else
+            throw new Error(`不支持的压缩方式 ${entry.method}：${entry.name}`);
+        if (content.length > MAX_ENTRY_BYTES)
+            throw new Error(`包里的 ${entry.name} 解压后太大`);
+        const target = join(destination, relative);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, content);
+        written.push(relative.split(sep).join("/"));
+    }
+    return written;
+}
+/** 解出来的文件里，`SKILL.md` 所在的那一层（技能包有时会套一层目录） */
+export function skillRootOf(files) {
+    const direct = files.find((file) => file.toLowerCase() === "skill.md");
+    if (direct !== undefined)
+        return "";
+    const nested = files.find((file) => /^[^/]+\/skill\.md$/i.test(file));
+    return nested === undefined ? null : nested.slice(0, nested.indexOf("/"));
+}

package/dist/server/snapshot/fan-out.js

@@ -0,0 +1,10 @@
+export function fanOutSnapshot(snapshot, targets) {
+    const shared = JSON.stringify({ type: "event", event: "snapshot", snapshot });
+    for (const socket of targets.sockets) {
+        if (socket.readyState === socket.OPEN)
+            socket.send(shared);
+    }
+    for (const [clientId, sink] of targets.sinks) {
+        sink(JSON.stringify({ type: "event", event: "snapshot", snapshot: targets.snapshotFor(clientId) }));
+    }
+}

package/dist/server/snapshot/messages.js

@@ -0,0 +1,75 @@
+/**
+ * 消息块的纯函数工具（ADR-0012：消息由块构成）。
+ *
+ * 全部是纯函数（不改入参），便于单测覆盖「文本追加 / 工具卡状态流转 / 摘录截断」。
+ */
+import { TOOL_EXCERPT_CHARS } from "../protocol.js";
+export function createMessage(id, role, ts) {
+    return { id, role, ts, blocks: [] };
+}
+/** 追加文本：接到最后一个文本块后面（保持「说一句 → 调工具 → 再说一句」的交错顺序） */
+export function appendText(message, text) {
+    const blocks = [...message.blocks];
+    const last = blocks[blocks.length - 1];
+    if (last && last.kind === "text")
+        blocks[blocks.length - 1] = { kind: "text", text: last.text + text };
+    else
+        blocks.push({ kind: "text", text });
+    return { ...message, blocks };
+}
+export function startTool(message, input) {
+    const block = {
+        kind: "tool",
+        toolCallId: input.toolCallId,
+        name: input.name,
+        argsSummary: input.argsSummary,
+        // 摘要已经够短就不重复带一份：界面靠「有没有 argsFull」判断要不要显示「完整命令」
+        ...(input.argsFull && input.argsFull !== input.argsSummary ? { argsFull: input.argsFull } : {}),
+        status: "running",
+        outputExcerpt: "",
+        truncated: false,
+        startedAt: input.startedAt,
+    };
+    return { ...message, blocks: [...message.blocks, block] };
+}
+/** 摘录预算（ADR-0004 §5）：超限截断并打标记，而不是把 200KB 塞进快照 */
+export function truncateExcerpt(output, limit = TOOL_EXCERPT_CHARS) {
+    if (output.length <= limit)
+        return { outputExcerpt: output, truncated: false };
+    return { outputExcerpt: output.slice(0, limit), truncated: true };
+}
+export function finishTool(message, input) {
+    const { outputExcerpt, truncated } = truncateExcerpt(input.output);
+    const blocks = message.blocks.map((block) => {
+        if (block.kind !== "tool" || block.toolCallId !== input.toolCallId)
+            return block;
+        return {
+            ...block,
+            status: input.status,
+            outputExcerpt,
+            truncated,
+            endedAt: input.endedAt,
+            ...(input.exitCode === undefined ? {} : { exitCode: input.exitCode }),
+        };
+    });
+    return { ...message, blocks };
+}
+export function appendError(message, code, text) {
+    return { ...message, blocks: [...message.blocks, { kind: "error", code, message: text }] };
+}
+/** 快照里最后一条消息的纯文本（给状态栏/调试用） */
+export function messageText(message) {
+    return message.blocks
+        .map((block) => block.kind === "text" ? block.text : block.kind === "error" ? `[${block.code}] ${block.message}` : "")
+        .join("");
+}
+/** 追加思考文本（与正文分开：正文说结论，思考说过程） */
+export function appendThinking(message, text) {
+    const blocks = [...message.blocks];
+    const last = blocks[blocks.length - 1];
+    if (last && last.kind === "thinking")
+        blocks[blocks.length - 1] = { kind: "thinking", text: last.text + text };
+    else
+        blocks.push({ kind: "thinking", text });
+    return { ...message, blocks };
+}

package/dist/server/snapshot/sender.js

@@ -0,0 +1,62 @@
+export const DEFAULT_WINDOW_MS = 60;
+export function createSender(options) {
+    const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+    const stats = {
+        sentSnapshots: 0,
+        coalescedSnapshots: 0,
+        skippedSnapshots: 0,
+        sentEvents: 0,
+        sentReplies: 0,
+    };
+    let pending = null;
+    let lastSentAt = Number.NEGATIVE_INFINITY;
+    let busy = false;
+    const sendNow = () => {
+        if (!pending)
+            return false;
+        options.send({ kind: "snapshot", snapshot: pending });
+        pending = null;
+        stats.sentSnapshots += 1;
+        return true;
+    };
+    return {
+        pushSnapshot(snapshot) {
+            if (pending)
+                stats.coalescedSnapshots += 1;
+            pending = snapshot;
+        },
+        pushEvent(event) {
+            options.send({ kind: "event", event });
+            stats.sentEvents += 1;
+        },
+        pushReply(reply) {
+            options.send({ kind: "reply", reply });
+            stats.sentReplies += 1;
+        },
+        tick(now) {
+            if (!pending)
+                return;
+            if (busy) {
+                stats.skippedSnapshots += 1;
+                return;
+            }
+            if (now - lastSentAt < windowMs)
+                return;
+            if (sendNow())
+                lastSentAt = now;
+        },
+        setBusy(next) {
+            busy = next;
+        },
+        flush(now) {
+            if (sendNow())
+                lastSentAt = now;
+        },
+        stats() {
+            return { ...stats };
+        },
+        hasPendingSnapshot() {
+            return pending !== null;
+        },
+    };
+}