oh-my-agent-web 0.3.0 → 0.5.0

package/dist/server/skills/skill-install.js

@@ -0,0 +1,186 @@
+/**
+ * 技能的三种安装方式 + 删除。
+ *
+ * 参考 `/Users/dds/data/git/oh-my-skills`（`skillhub-install.ts` / `repo-install.ts`），
+ * 但有一处**刻意不同**：参考实现装 Git 仓库里的技能时只写一份 `SKILL.md`，
+ * 那样 `scripts/`、`references/` 全丢 —— 而现在的技能大量靠这两样干活。
+ * 这里一律**整目录复制**。
+ *
+ * 三条纪律：
+ *   - **只往 `~/.agents/skills` 写**（目录由调用方给，默认就是它）：这是 pi 真正扫的那份，
+ *     也是界面上「默认列出来」的那份，安装完不用第二处同步；
+ *   - **不覆盖同名**：目标目录已存在就报错（`skill.exists`），让用户自己去删 ——
+ *     静默覆盖会把人家手改过的技能冲掉，这比多一步麻烦糟得多；
+ *   - **临时目录一定会清**（`finally`），下载/克隆失败不留下几百 MB 垃圾。
+ */
+import { execFile } from "node:child_process";
+import { cp, mkdir, mkdtemp, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { hasSkillFile, safeSkillDirName } from "./skillhub.js";
+const run = promisify(execFile);
+/** git clone 的上限：技能仓库一般很小，卡住不收就是事故 */
+const GIT_TIMEOUT_MS = 120_000;
+async function exists(path) {
+    return stat(path)
+        .then(() => true)
+        .catch(() => false);
+}
+/** 目标目录已有技能时的统一报错（README 里也这么写，用户知道下一步干什么） */
+function existsError(id) {
+    return { ok: false, error: `这个技能目录已经存在：${id}（要重装先删掉它，我不想覆盖你手改过的东西）` };
+}
+/** 把一个技能目录整份复制到 `skillsRoot/<id>` */
+async function copyInto(skillsRoot, sourceDir, id) {
+    const target = join(skillsRoot, id);
+    if (await exists(target))
+        return existsError(id);
+    await mkdir(skillsRoot, { recursive: true });
+    // `cp` 的 recursive 会连 `scripts/`、`references/`、`assets/` 一起带过去
+    await cp(sourceDir, target, { recursive: true, errorOnExist: true, force: false });
+    return { ok: true, id, path: target };
+}
+function gitUrlLooksSafe(url) {
+    const value = url.trim();
+    if (value === "")
+        return false;
+    // 允许 https / ssh / git@host:path / 本地绝对路径（自己机器上的仓库也该能装）
+    if (/^https?:\/\//i.test(value))
+        return true;
+    if (/^git@[^:\s]+:.+$/i.test(value))
+        return true;
+    if (/^ssh:\/\//i.test(value))
+        return true;
+    return value.startsWith("/") && !value.includes("..");
+}
+/** 克隆到一个临时目录；返回目录与清理函数 */
+async function cloneRepo(repoUrl) {
+    const workDir = await mkdtemp(join(tmpdir(), "omaw-repo-"));
+    const dir = join(workDir, "repo");
+    await run("git", ["clone", "--depth", "1", repoUrl, dir], {
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: 8 * 1024 * 1024,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    });
+    return { dir, cleanup: () => rm(workDir, { recursive: true, force: true }).catch(() => undefined) };
+}
+/** 仓库里的技能可能在根目录，也可能在 `skills/` 下（两种都认，跟参考实现一致） */
+async function findSkillInRepo(repoDir, skill) {
+    const candidates = [join(repoDir, "skills", skill), join(repoDir, skill)];
+    for (const candidate of candidates) {
+        if (await hasSkillFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+export function createSkillInstaller(options) {
+    const { skillsRoot, hub } = options;
+    return {
+        async fromHub(input) {
+            const id = safeSkillDirName(input.name ?? input.slug);
+            if (await exists(join(skillsRoot, id)))
+                return existsError(id);
+            try {
+                const pkg = await hub.fetchPackage(input.slug);
+                try {
+                    return await copyInto(skillsRoot, pkg.dir, id);
+                }
+                finally {
+                    await pkg.cleanup();
+                }
+            }
+            catch (error) {
+                return { ok: false, error: error instanceof Error ? error.message : String(error) };
+            }
+        },
+        async listRepo(repoUrl) {
+            if (!gitUrlLooksSafe(repoUrl))
+                return { ok: false, error: "仓库地址看起来不对（支持 https / ssh / git@host:path / 本地绝对路径）" };
+            let cloned;
+            try {
+                cloned = await cloneRepo(repoUrl.trim());
+                const found = new Set();
+                for (const base of [join(cloned.dir, "skills"), cloned.dir]) {
+                    const entries = await readdir(base, { withFileTypes: true }).catch(() => []);
+                    for (const entry of entries) {
+                        if (!entry.isDirectory() || entry.name.startsWith("."))
+                            continue;
+                        if (await hasSkillFile(join(base, entry.name)))
+                            found.add(entry.name);
+                    }
+                }
+                if (found.size === 0)
+                    return { ok: false, error: "这个仓库里没找到技能（根目录或 skills/ 下要有 SKILL.md）" };
+                return { ok: true, skills: [...found].sort() };
+            }
+            catch (error) {
+                return { ok: false, error: describeGit(error) };
+            }
+            finally {
+                await cloned?.cleanup();
+            }
+        },
+        async fromRepo(input) {
+            if (!gitUrlLooksSafe(input.repoUrl))
+                return { ok: false, error: "仓库地址看起来不对（支持 https / ssh / git@host:path / 本地绝对路径）" };
+            const id = safeSkillDirName(input.name ?? input.skill);
+            if (await exists(join(skillsRoot, id)))
+                return existsError(id);
+            let cloned;
+            try {
+                cloned = await cloneRepo(input.repoUrl.trim());
+                const dir = await findSkillInRepo(cloned.dir, input.skill);
+                if (dir === null)
+                    return { ok: false, error: `仓库里没找到技能 "${input.skill}"` };
+                return await copyInto(skillsRoot, dir, id);
+            }
+            catch (error) {
+                return { ok: false, error: describeGit(error) };
+            }
+            finally {
+                await cloned?.cleanup();
+            }
+        },
+        async manual(input) {
+            const id = safeSkillDirName(input.name);
+            const target = join(skillsRoot, id);
+            if (await exists(target))
+                return existsError(id);
+            await mkdir(target, { recursive: true });
+            const name = input.name.trim() === "" ? id : input.name.trim();
+            const body = input.raw !== undefined && input.raw.trim() !== ""
+                ? input.raw
+                : `---\nname: ${name}\ndescription: （一句话说明这个技能什么时候用）\n---\n\n# ${name}\n\n写清楚：什么时候用它、怎么做、做完怎么确认。\n`;
+            await writeFile(join(target, "SKILL.md"), body, "utf8");
+            return { ok: true, id, path: target };
+        },
+        async remove(id) {
+            const safe = safeSkillDirName(id);
+            if (safe !== id)
+                return { ok: false, error: `非法技能 id：${id}` };
+            const target = join(skillsRoot, id);
+            if (!(await hasSkillFile(target)))
+                return { ok: false, error: `"${id}" 不是一个技能目录` };
+            try {
+                // 整目录删：SKILL.md（或禁用态的 .SKILL.md.disabled）与 scripts/references 一起走
+                await rm(target, { recursive: true, force: true });
+                return { ok: true };
+            }
+            catch (error) {
+                return { ok: false, error: error instanceof Error ? error.message : String(error) };
+            }
+        },
+    };
+}
+/** git 的报错尾巴通常很有用（`Repository not found` / `could not resolve host`），别吞掉 */
+function describeGit(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stderr = error.stderr;
+    const text = (stderr !== undefined && stderr.trim() !== "" ? stderr : message).trim();
+    const lines = text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line !== "");
+    return `克隆失败：${lines.slice(-2).join(" / ").slice(0, 400)}`;
+}

package/dist/server/skills/skill-routes.js

@@ -0,0 +1,134 @@
+import { HUB_CATEGORIES, createSkillHub, listSkillDirs } from "./skillhub.js";
+import { createSkillInstaller } from "./skill-install.js";
+import { createSkillStore } from "./skill-store.js";
+export function registerSkillRoutes(app, options = {}) {
+    const skills = options.skills ?? createSkillStore();
+    const skillsRoot = skills.dir;
+    const hub = createSkillHub();
+    const installer = createSkillInstaller({ skillsRoot, hub });
+    /** 安装成功后刷新列表：界面一次请求拿到「新列表 + 提示」，不用再打一次 */
+    const afterInstall = async (result, notice) => ({
+        ...(result.ok ? { notice } : { installError: result.error ?? "安装失败" }),
+        skills: await skills.list(),
+    });
+    app.get("/api/skills", async (_request, response) => {
+        response.json({ skills: await skills.list(), root: skillsRoot });
+    });
+    app.post("/api/skills/enabled", async (request, response) => {
+        const body = request.body;
+        const ids = Array.isArray(body?.ids) ? body.ids.filter((item) => typeof item === "string") : [];
+        if (ids.length === 0) {
+            response.status(400).json({ error: { code: "skills.no_ids", message: "没有指定要操作的技能" } });
+            return;
+        }
+        const enabled = body?.enabled === true;
+        const result = await skills.setEnabled(ids, enabled);
+        options.onChange?.();
+        response.json({ ...result, skills: await skills.list() });
+    });
+    // ---- 技能市场 ----
+    app.get("/api/skills/hub", async (request, response) => {
+        const query = typeof request.query.q === "string" ? request.query.q : "";
+        const rawCategory = typeof request.query.category === "string" ? request.query.category : "";
+        const category = HUB_CATEGORIES.some((item) => item.key === rawCategory) ? rawCategory : "";
+        const page = Number.parseInt(typeof request.query.page === "string" ? request.query.page : "1", 10) || 1;
+        try {
+            const result = await hub.search({
+                query,
+                category,
+                page,
+                pageSize: 24,
+                refresh: request.query.refresh === "1",
+            });
+            // 已安装的标记：按目录名比（安装时目录名就是 slug / 技能名，见 skill-install.ts）
+            const installed = new Set(await listSkillDirs(skillsRoot));
+            response.json({
+                ...result,
+                skills: result.skills.map((skill) => ({
+                    ...skill,
+                    installed: installed.has(skill.slug) || installed.has(skill.name),
+                })),
+                categories: HUB_CATEGORIES,
+            });
+        }
+        catch (error) {
+            response.status(502).json({
+                error: { code: "skills.hub_failed", message: error instanceof Error ? error.message : String(error) },
+            });
+        }
+    });
+    app.post("/api/skills/install", async (request, response) => {
+        const body = request.body;
+        const source = body?.source;
+        const text = (value) => (typeof value === "string" ? value : undefined);
+        if (source === "hub") {
+            const slug = text(body?.slug) ?? "";
+            if (slug === "") {
+                response.status(400).json({ error: { code: "skills.no_slug", message: "没有指定要装的技能" } });
+                return;
+            }
+            const result = await installer.fromHub({ slug, name: text(body?.name) });
+            response.json(await afterInstall(result, `已安装「${text(body?.name) ?? slug}」`));
+            return;
+        }
+        if (source === "git") {
+            const repoUrl = text(body?.repoUrl) ?? "";
+            const skill = text(body?.skill);
+            // 没给 skill = 先看仓库里有什么（两段式），给了才真装
+            if (skill === undefined || skill === "") {
+                response.json(await installer.listRepo(repoUrl));
+                return;
+            }
+            const result = await installer.fromRepo({ repoUrl, skill, name: text(body?.name) });
+            response.json(await afterInstall(result, `已从仓库安装「${skill}」`));
+            return;
+        }
+        if (source === "manual") {
+            const name = text(body?.name) ?? "";
+            const result = await installer.manual({ name, raw: text(body?.raw) });
+            response.json(await afterInstall(result, `已创建「${name}」`));
+            return;
+        }
+        response.status(400).json({ error: { code: "skills.bad_source", message: "不认识的安装方式" } });
+    });
+    app.post("/api/skills/remove", async (request, response) => {
+        const body = request.body;
+        // 单个（老的调用点）与批量（左栏多选）都走这一条：删除是「一个目录一个目录地删」，
+        // 批量只是循环，没必要再加一个端点
+        const ids = Array.isArray(body?.ids)
+            ? body.ids.filter((item) => typeof item === "string")
+            : typeof body?.id === "string"
+                ? [body.id]
+                : [];
+        if (ids.length === 0) {
+            response.status(400).json({ error: { code: "skills.no_id", message: "没有指定要删除的技能" } });
+            return;
+        }
+        const removed = [];
+        const failures = [];
+        for (const id of ids) {
+            const result = await installer.remove(id);
+            if (result.ok)
+                removed.push(id);
+            else
+                failures.push(`${id}：${result.error ?? "删除失败"}`);
+        }
+        options.onChange?.();
+        response.json({
+            ...(removed.length > 0
+                ? { notice: removed.length === 1 ? `已删除「${removed[0]}」` : `已删除 ${removed.length} 个技能` }
+                : {}),
+            ...(failures.length > 0 ? { removeError: failures.join("；") } : {}),
+            skills: await skills.list(),
+        });
+    });
+    app.get("/api/skills/:id/file", async (request, response) => {
+        const relPath = typeof request.query.path === "string" ? request.query.path : "";
+        const result = await skills.readFile(request.params.id, relPath);
+        if (!result.ok) {
+            response.status(400).json({ error: { code: "skills.read_failed", message: result.error } });
+            return;
+        }
+        response.json(result);
+    });
+}

package/dist/server/skills/skill-store.js

@@ -0,0 +1,163 @@
+/**
+ * 技能列表与启停（P8）。
+ *
+ * 技能目录：`~/.agents/skills/<目录名>/SKILL.md`（frontmatter 里有 name / description），
+ * 目录里还可能有 `scripts/`、`references/` 等。
+ *
+ * **启停的实现方式（刻意选择）**：把 `SKILL.md` 改名成 `.SKILL.md.disabled`。
+ *   - pi 扫描技能只认 `SKILL.md`，改名即"看不见"，这是真正生效的禁用；
+ *   - 不动其它文件、不动目录结构，一条 mv 就能复原，**不产生第二份状态文件**
+ *     （两处状态必然不一致，这是 ADR-0021 的教训）。
+ */
+import { readdir, readFile, rename, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readPreview } from "../files/file-service.js";
+export const SKILL_ENTRY = "SKILL.md";
+export const SKILL_ENTRY_DISABLED = ".SKILL.md.disabled";
+export function defaultSkillsDir() {
+    return join(homedir(), ".agents", "skills");
+}
+/**
+ * 纯函数：从 SKILL.md 的 frontmatter 里抠 name / description（不引 yaml 依赖）。
+ *
+ * 两种写法都要认 —— 真实技能里用折叠标量的很多（`anthropics/skills` 的 academy-guide 就是）：
+ *
+ *     description: 一句话
+ *     description: >
+ *       折成一行的一段
+ *       可以有缩进的续行
+ *
+ * 只认折叠（`>`）与字面（`|`）两种块标量：这两种占真实用法的全部，
+ * 为它们引一个 YAML 库不划算（ADR-0008）。
+ */
+export function parseFrontmatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (!match)
+        return { name: "", description: "" };
+    const body = match[1] ?? "";
+    const lines = body.split(/\r?\n/);
+    const read = (key) => {
+        const start = lines.findIndex((line) => new RegExp(`^${key}:`).test(line));
+        if (start === -1)
+            return "";
+        const rawValue = (lines[start] ?? "").replace(new RegExp(`^${key}:\\s*`), "").trim();
+        // 块标量：`>` 折叠成空格，`|` 保留换行；续行是后面那些「缩进或空行」的行
+        const scalar = /^([>|])([+-]?)$/.exec(rawValue);
+        if (scalar) {
+            const collected = [];
+            for (let index = start + 1; index < lines.length; index += 1) {
+                const line = lines[index] ?? "";
+                if (line.trim() !== "" && !/^\s/.test(line))
+                    break; // 顶格 = 下一个键
+                collected.push(line.trim());
+            }
+            const text = collected.join(scalar[1] === "|" ? "\n" : " ").trim();
+            return text.replace(/\s+/g, " ");
+        }
+        // 单行：去掉包裹的引号
+        return rawValue.replace(/^["']/, "").replace(/["']$/, "");
+    };
+    return { name: read("name"), description: read("description") };
+}
+/** 递归列目录里的文件（相对路径），有上限，避免某个技能塞几千个文件把界面拖死 */
+export async function listFiles(root, prefix = "", out = []) {
+    if (out.length >= 200)
+        return out;
+    let entries;
+    try {
+        entries = await readdir(join(root, prefix), { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (out.length >= 200)
+            break;
+        if (entry.name === "cache" || entry.name.startsWith("."))
+            continue;
+        const rel = join(prefix, entry.name);
+        if (entry.isDirectory())
+            await listFiles(root, rel, out);
+        else
+            out.push(rel);
+    }
+    return out;
+}
+function safeId(id) {
+    // 目录名白名单：不允许穿越、不允许以点开头（那是内部文件）
+    return /^[A-Za-z0-9._-]{1,80}$/.test(id) && !id.startsWith(".");
+}
+export function createSkillStore(options = {}) {
+    const root = options.dir ?? defaultSkillsDir();
+    const resolve = (id) => (safeId(id) ? join(root, id) : null);
+    return {
+        dir: root,
+        async list() {
+            let names = [];
+            try {
+                names = (await readdir(root, { withFileTypes: true }))
+                    .filter((entry) => entry.isDirectory())
+                    .map((entry) => entry.name);
+            }
+            catch {
+                return [];
+            }
+            const skills = [];
+            for (const id of names.sort()) {
+                const dir = join(root, id);
+                const enabled = await stat(join(dir, SKILL_ENTRY))
+                    .then(() => true)
+                    .catch(() => false);
+                const entryPath = join(dir, enabled ? SKILL_ENTRY : SKILL_ENTRY_DISABLED);
+                const text = await readFile(entryPath, "utf8").catch(() => "");
+                if (text === "")
+                    continue; // 既没有 SKILL.md 也没有 .disabled 的目录不是技能
+                const meta = parseFrontmatter(text);
+                skills.push({
+                    id,
+                    name: meta.name !== "" ? meta.name : id,
+                    description: meta.description,
+                    enabled,
+                    files: await listFiles(dir),
+                });
+            }
+            return skills;
+        },
+        async setEnabled(ids, enabled) {
+            const changed = [];
+            const errors = [];
+            for (const id of ids) {
+                const dir = resolve(id);
+                if (!dir) {
+                    errors.push(`非法技能 id：${id}`);
+                    continue;
+                }
+                const from = join(dir, enabled ? SKILL_ENTRY_DISABLED : SKILL_ENTRY);
+                const to = join(dir, enabled ? SKILL_ENTRY : SKILL_ENTRY_DISABLED);
+                const exists = await stat(from)
+                    .then(() => true)
+                    .catch(() => false);
+                if (!exists)
+                    continue; // 已经是目标状态
+                try {
+                    await rename(from, to);
+                    changed.push(id);
+                }
+                catch (error) {
+                    errors.push(`${id}：${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            return { changed, errors };
+        },
+        async readFile(id, relPath) {
+            const dir = resolve(id);
+            if (!dir)
+                return { ok: false, error: "非法技能 id" };
+            const result = await readPreview(dir, relPath);
+            if (!result.ok)
+                return { ok: false, error: result.error };
+            return { ok: true, text: result.text, binary: result.binary, bytes: result.bytes };
+        },
+    };
+}