mioku-service-webui 4.11.3 → 4.13.0

package/index.ts

@@ -37,6 +37,7 @@ import {
   createDataManagementRoutes,
   createStrangerRoutes,
   createAccessControlRoutes,
+  createMcpRoutes,
 } from "./routes";
 import { freePort } from "./port-utils";
 
@@ -132,6 +133,7 @@ class WebUIRuntime {
     this.app.route("/api/data-management", createDataManagementRoutes());
     this.app.route("/api/stranger", createStrangerRoutes());
     this.app.route("/api/access-control", createAccessControlRoutes());
+    this.app.route("/api/mcp", createMcpRoutes());
 
     this.app.get(
       "/api/ws/logs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mioku-service-webui",
-  "version": "4.11.3",
+  "version": "4.13.0",
   "description": "Mioku WebUI 服务",
   "main": "index.ts",
   "type": "module",
@@ -26,11 +26,18 @@
     "systeminformation": "^5.31.6"
   },
   "peerDependencies": {
-    "mioku-service-ai": "^4.0.0"
+    "mioku-service-ai": "^4.0.0",
+    "mioku-service-mcp": "^0.1.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",
     "mioku": "workspace:*",
-    "mioku-service-ai": "workspace:*"
+    "mioku-service-ai": "workspace:*",
+    "mioku-service-mcp": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "mioku-service-mcp": {
+      "optional": true
+    }
   }
 }

package/routes/agent-skills.ts

@@ -0,0 +1,137 @@
+import { Hono } from "hono";
+import { logger } from "mioku";
+import { probeSkillSource } from "../skill-sources";
+import {
+  getSkillOrigin,
+  installAgentSkill,
+  listAgentSkillRoots,
+  listAgentSkills,
+  readAgentSkill,
+  setSkillEnabled,
+  uninstallAgentSkill,
+} from "../skill-store";
+
+function badRequest(c: { json: (body: unknown, status: 400) => Response }, error: string): Response {
+  return c.json({ ok: false, error }, 400);
+}
+
+export function createAgentSkillRoutes() {
+  const app = new Hono();
+
+  app.get("/", async (c) => c.json({ ok: true, data: await listAgentSkills() }));
+
+  app.get("/roots", async (c) =>
+    c.json({ ok: true, data: await listAgentSkillRoots() }),
+  );
+
+  app.post("/probe", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const input = String(body?.input ?? "").trim();
+    if (!input) return badRequest(c, "请填写技能来源");
+
+    const result = await probeSkillSource(input);
+    if ("error" in result) return badRequest(c, result.error);
+    logger.info(`[webui-action] skill.probe`, {
+      input,
+      candidates: result.candidates.length,
+    });
+    return c.json({ ok: true, data: result });
+  });
+
+  app.post("/install", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const rootId = String(body?.rootId ?? "").trim();
+    if (!rootId) return badRequest(c, "请选择安装到哪个技能目录");
+
+    const input = String(body?.input ?? "").trim();
+    let stagingId = String(body?.stagingId ?? "").trim();
+    let rel = String(body?.rel ?? "").trim();
+
+    if (!stagingId) {
+      if (!input) return badRequest(c, "请先检测来源");
+      const probed = await probeSkillSource(input);
+      if ("error" in probed) return badRequest(c, probed.error);
+      stagingId = probed.stagingId;
+      if (!rel) {
+        if (probed.candidates.length > 1) {
+          return c.json({
+            ok: true,
+            data: { needSelection: true, ...probed },
+          });
+        }
+        rel = probed.candidates[0]!.rel;
+      }
+    }
+
+    const result = await installAgentSkill({
+      rootId,
+      stagingId,
+      rel,
+      overwrite: Boolean(body?.overwrite),
+      ...(body?.name ? { name: String(body.name) } : {}),
+      ...(input ? { originInput: input } : {}),
+    });
+    if ("error" in result) return badRequest(c, result.error);
+
+    logger.info(`[webui-action] skill.install`, {
+      name: result.name,
+      rootId: result.rootId,
+    });
+    return c.json({ ok: true, data: result });
+  });
+
+  app.put("/state", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const name = String(body?.name ?? "").trim();
+    if (!name) return badRequest(c, "缺少技能名");
+    const enabled = body?.enabled !== false;
+    const state = setSkillEnabled(name, enabled);
+    logger.info(`[webui-action] skill.${enabled ? "enable" : "disable"}`, { name });
+    return c.json({ ok: true, data: state });
+  });
+
+  app.get("/:name", async (c) => {
+    const name = c.req.param("name");
+    const rootId = c.req.query("rootId") ?? "";
+    const detail = await readAgentSkill(rootId, name);
+    if (!detail) return c.json({ ok: false, error: "技能不存在" }, 404);
+    return c.json({ ok: true, data: detail });
+  });
+
+  app.delete("/:name", async (c) => {
+    const name = c.req.param("name");
+    const rootId = c.req.query("rootId") ?? "";
+    const result = await uninstallAgentSkill(rootId, name);
+    if ("error" in result) return badRequest(c, result.error);
+    logger.info(`[webui-action] skill.uninstall`, { name, rootId });
+    return c.json({ ok: true, data: result });
+  });
+
+  app.post("/:name/update", async (c) => {
+    const name = c.req.param("name");
+    const rootId = c.req.query("rootId") ?? "";
+    const origin = getSkillOrigin(rootId, name);
+    if (!origin) return badRequest(c, "该技能不是从来源安装的，无法自动更新");
+
+    const probed = await probeSkillSource(origin.input);
+    if ("error" in probed) return badRequest(c, probed.error);
+    const match =
+      probed.candidates.find((item) => item.name === name) ??
+      probed.candidates[0]!;
+
+    const result = await installAgentSkill({
+      rootId,
+      stagingId: probed.stagingId,
+      rel: match.rel,
+      name,
+      overwrite: true,
+      originInput: origin.input,
+    });
+    if ("error" in result) return badRequest(c, result.error);
+
+    logger.info(`[webui-action] skill.update`, { name, rootId });
+    return c.json({ ok: true, data: result });
+  });
+
+  return app;
+}

package/routes/agent.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import { logger } from "mioku";
 import { getAgentConfig, updateAgentConfig } from "../system";
+import { createAgentSkillRoutes } from "./agent-skills";
 import aiService from "mioku-service-ai";
 
 const PERMISSION_LEVELS = new Set([
@@ -51,6 +52,10 @@ function sanitizeSettingsForSave(body: any): any {
     const num = Math.floor(Number(value));
     return Number.isFinite(num) && num > 0 ? num : fallback;
   };
+  const nonNegative = (value: unknown, fallback: number) => {
+    const num = Math.floor(Number(value));
+    return Number.isFinite(num) && num >= 0 ? num : fallback;
+  };
   delete next.temperature;
   delete next.enableMediaRecognition;
   next.maxIterations = positive(next.maxIterations, 500);
@@ -79,7 +84,24 @@ function sanitizeSettingsForSave(body: any): any {
     timeoutMs: positive(next.bash?.timeoutMs, 120000),
     approvalTimeoutMs: positive(next.bash?.approvalTimeoutMs, 300000),
   };
+  next.skills = {
+    enabled: next.skills?.enabled !== false,
+    extraRoots: Array.isArray(next.skills?.extraRoots)
+      ? next.skills.extraRoots
+          .map((item: unknown) => String(item ?? "").trim())
+          .filter(Boolean)
+      : [],
+    maxInPrompt: positive(next.skills?.maxInPrompt, 50),
+    descriptionMaxLength: positive(next.skills?.descriptionMaxLength, 500),
+    activationTtlMs: positive(next.skills?.activationTtlMs, 3_600_000),
+    rescanIntervalMs: nonNegative(next.skills?.rescanIntervalMs, 2000),
+    maxResourceFiles: positive(next.skills?.maxResourceFiles, 200),
+  };
   next.dataCollection = { enabled: next.dataCollection?.enabled !== false };
+  next.mcp = {
+    enabled: next.mcp?.enabled !== false,
+    maxTools: nonNegative(next.mcp?.maxTools, 48),
+  };
   next.debug = Boolean(next.debug);
   return next;
 }
@@ -91,6 +113,8 @@ function getAIApi() {
 export function createAgentRoutes() {
   const app = new Hono();
 
+  app.route("/skills", createAgentSkillRoutes());
+
   app.get("/base", (c) =>
     c.json({ ok: true, data: getAgentConfig("base.json") }),
   );

package/routes/index.ts

@@ -9,3 +9,4 @@ export { createStoreRoutes } from "./store";
 export { createDataManagementRoutes } from "./data-management";
 export { createStrangerRoutes } from "./stranger";
 export { createAccessControlRoutes } from "./access-control";
+export { createMcpRoutes } from "./mcp";

package/routes/mcp.ts

@@ -0,0 +1,136 @@
+import { Hono } from "hono";
+import { logger, servicesRegistry } from "mioku";
+import type { McpServerInput, McpServiceApi } from "mioku-service-mcp";
+
+/** 服务可能没装或没起来，统一走注册表按名查，缺失时返回 503 */
+function mcp(): McpServiceApi | undefined {
+  return servicesRegistry.mcp as McpServiceApi | undefined;
+}
+
+function unavailable(c: { json: (body: unknown, status: 503) => Response }): Response {
+  return c.json({ ok: false, error: "MCP_SERVICE_UNAVAILABLE" }, 503);
+}
+
+function badRequest(
+  c: { json: (body: unknown, status: 400) => Response },
+  error: string,
+): Response {
+  return c.json({ ok: false, error }, 400);
+}
+
+function normalizeLimit(value: string | undefined, fallback: number): number {
+  const num = Math.floor(Number(value));
+  if (!Number.isFinite(num) || num <= 0) return fallback;
+  return Math.min(num, 500);
+}
+
+export function createMcpRoutes() {
+  const app = new Hono();
+
+  app.get("/overview", (c) => {
+    const api = mcp();
+    if (!api) return unavailable(c);
+    const config = api.getConfig();
+    return c.json({
+      ok: true,
+      data: {
+        autoConnect: config.autoConnect,
+        reconnectDelayMs: config.reconnectDelayMs,
+        maxConcurrency: config.maxConcurrency,
+        maxTools: config.maxTools,
+        maxResultChars: config.maxResultChars,
+        maxResultImages: config.maxResultImages,
+        revision: api.revision(),
+        toolCount: api.listTools().length,
+        catalogOnlyCount: api.listAllTools().filter((tool) => tool.catalogOnly).length,
+        servers: api.listServers(),
+        configs: api.listServerConfigs(),
+      },
+    });
+  });
+
+  app.post("/servers", async (c) => {
+    const api = mcp();
+    if (!api) return unavailable(c);
+    const body = (await c.req.json().catch(() => ({}))) as McpServerInput;
+    const name = String(body?.name ?? "").trim().toLowerCase();
+    if (!name) return badRequest(c, "请填写服务器名称");
+    logger.info("[webui-action] mcp.server.upsert", { name });
+    const result = await api.upsertServer({ ...body, name });
+    if ("error" in result) return badRequest(c, result.error);
+    return c.json({ ok: true, data: result });
+  });
+
+  app.delete("/servers/:name", async (c) => {
+    const api = mcp();
+    if (!api) return unavailable(c);
+    const name = c.req.param("name");
+    const removed = await api.removeServer(name);
+    if (!removed) return badRequest(c, `服务器 "${name}" 不存在`);
+    logger.info("[webui-action] mcp.server.remove", { name });
+    return c.json({ ok: true, data: { name } });
+  });
+
+  app.put("/servers/:name/enabled", async (c) => {
+    const api = mcp();
+    if (!api) return unavailable(c);
+    const name = c.req.param("name");
+    const body = (await c.req.json().catch(() => ({}))) as { enabled?: unknown };
+    const enabled = body?.enabled !== false;
+    const result = await api.setServerEnabled(name, enabled);
+    if ("error" in result) return badRequest(c, result.error);
+    logger.info(`[webui-action] mcp.server.${enabled ? "enable" : "disable"}`, { name });
+    return c.json({ ok: true, data: result });
+  });
+
+  for (const action of ["connect", "disconnect", "reconnect"] as const) {
+    app.post(`/servers/:name/${action}`, async (c) => {
+      const api = mcp();
+      if (!api) return unavailable(c);
+      const name = c.req.param("name");
+      logger.info(`[webui-action] mcp.server.${action}`, { name });
+      const result = await api[action](name);
+      if ("error" in result) return badRequest(c, result.error);
+      return c.json({ ok: true, data: result });
+    });
+  }
+
+  app.get("/servers/:name/tools", (c) => {
+    const api = mcp();
+    if (!api) return unavailable(c);
+    const name = c.req.param("name");
+    if (!api.getServer(name)) return badRequest(c, `服务器 "${name}" 不存在`);
+    const tools = api
+      .listAllTools()
+      .filter((tool) => tool.server === name)
+      .map((tool) => ({
+        publicName: tool.publicName,
+        tool: tool.tool,
+        description: tool.description,
+        catalogOnly: tool.catalogOnly,
+        parameters: tool.parameters,
+      }));
+    return c.json({ ok: true, data: tools });
+  });
+
+  app.post("/probe", async (c) => {
+    const api = mcp();
+    if (!api) return unavailable(c);
+    const body = (await c.req.json().catch(() => ({}))) as McpServerInput;
+    const name = String(body?.name ?? "").trim().toLowerCase();
+    if (!name) return badRequest(c, "请填写服务器名称");
+    logger.info("[webui-action] mcp.probe", { name });
+    const result = await api.probe({ ...body, name });
+    return c.json({ ok: true, data: result });
+  });
+
+  app.get("/logs", (c) => {
+    const api = mcp();
+    if (!api) return unavailable(c);
+    const server = c.req.query("server") || undefined;
+    const limit = normalizeLimit(c.req.query("limit"), 100);
+    return c.json({ ok: true, data: api.recentLogs(server, limit) });
+  });
+
+  return app;
+}

package/skill-sources.ts

@@ -0,0 +1,290 @@
+import AdmZip from "adm-zip";
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { locateSkillRoots, type SkillLocation } from "mioku";
+import { ensureDir, isValidRepoUrl, runCommand, TEMP_DIR } from "./utils";
+
+const STAGING_ROOT = path.join(TEMP_DIR, "webui-skills");
+const STAGING_TTL_MS = 30 * 60_000;
+const GIT_TIMEOUT_MS = 90_000;
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+const MAX_ARCHIVE_BYTES = 40 * 1024 * 1024;
+const MAX_EXTRACTED_FILES = 2000;
+
+export type SkillSourceKind = "git" | "file" | "archive" | "local";
+
+export interface ResolvedSkillSource {
+  kind: SkillSourceKind;
+  /** git 仓库地址（kind=git） */
+  gitUrl?: string;
+  /** 分支 / tag（kind=git） */
+  ref?: string;
+  /** 集合仓库内的子路径 */
+  subPath?: string;
+  /** 直接下载地址（kind=file / archive） */
+  url?: string;
+  /** 本地目录（kind=local） */
+  localDir?: string;
+  /** 展示用 */
+  display: string;
+}
+
+export interface SkillStaging {
+  id: string;
+  dir: string;
+  display: string;
+  createdAt: number;
+}
+
+const staging = new Map<string, SkillStaging>();
+
+function randomId(): string {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function pruneStaging(): void {
+  const now = Date.now();
+  for (const [id, item] of staging) {
+    if (now - item.createdAt < STAGING_TTL_MS) continue;
+    staging.delete(id);
+    fs.rmSync(item.dir, { recursive: true, force: true });
+  }
+}
+
+export function getStaging(id: string): SkillStaging | undefined {
+  pruneStaging();
+  return staging.get(id);
+}
+
+export function releaseStaging(id: string): void {
+  const item = staging.get(id);
+  if (!item) return;
+  staging.delete(id);
+  fs.rmSync(item.dir, { recursive: true, force: true });
+}
+
+function expandHome(input: string): string {
+  const raw = String(input ?? "").trim();
+  if (raw === "~") return os.homedir();
+  if (raw.startsWith("~/")) return path.join(os.homedir(), raw.slice(2));
+  return raw;
+}
+
+/** 把用户粘进来的东西解析成可下载的来源 */
+export function resolveSkillSource(
+  input: string,
+): ResolvedSkillSource | { error: string } {
+  const raw = String(input ?? "").trim();
+  if (!raw) return { error: "来源不能为空" };
+  if (/\s/.test(raw)) return { error: "来源不能包含空白字符" };
+
+  if (raw.startsWith("/") || raw.startsWith("~") || raw.startsWith("./") || raw.startsWith("../")) {
+    const dir = path.resolve(expandHome(raw));
+    if (!fs.existsSync(dir)) return { error: `本地路径不存在：${dir}` };
+    return { kind: "local", localDir: dir, display: dir };
+  }
+
+  if (!/^https?:\/\//.test(raw)) {
+    // `owner/repo`、`owner/repo#ref`、`owner/repo/sub/path`
+    const [repoPart, ref] = raw.split("#");
+    const segments = repoPart.split("/").filter(Boolean);
+    if (segments.length < 2) {
+      return { error: "简写需要 `owner/repo`，或直接粘贴完整 URL" };
+    }
+    const [owner, repo, ...rest] = segments;
+    return {
+      kind: "git",
+      gitUrl: `https://github.com/${owner}/${repo.replace(/\.git$/, "")}`,
+      ...(ref ? { ref } : {}),
+      ...(rest.length > 0 ? { subPath: rest.join("/") } : {}),
+      display: raw,
+    };
+  }
+
+  if (!isValidRepoUrl(raw)) return { error: "不支持的 URL" };
+
+  const github = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)(?:\/(?:tree|blob)\/([^/]+)\/(.*))?$/.exec(
+    raw,
+  );
+  if (github) {
+    const [, owner, repo, ref, rest] = github;
+    const isBlob = raw.includes("/blob/");
+    if (isBlob) {
+      return { kind: "file", url: raw.replace("/blob/", "/raw/"), display: raw };
+    }
+    return {
+      kind: "git",
+      gitUrl: `https://github.com/${owner}/${repo.replace(/\.git$/, "")}`,
+      ...(ref ? { ref } : {}),
+      ...(rest ? { subPath: rest.replace(/\/$/, "") } : {}),
+      display: raw,
+    };
+  }
+
+  if (/\.git$/.test(raw) || /^https?:\/\/(?:[^/]+)\/[^/]+\/[^/]+$/.test(raw)) {
+    return { kind: "git", gitUrl: raw.replace(/\.git$/, ""), display: raw };
+  }
+  if (/\.zip$/i.test(raw)) return { kind: "archive", url: raw, display: raw };
+  return { kind: "file", url: raw, display: raw };
+}
+
+async function runWithTimeout(
+  command: string,
+  args: string[],
+  cwd: string,
+  timeoutMs: number,
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      runCommand(command, args, cwd),
+      new Promise<{ code: number; stdout: string; stderr: string }>((resolve) => {
+        timer = setTimeout(
+          () => resolve({ code: -1, stdout: "", stderr: `${command} 超时` }),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+async function download(url: string, target: string): Promise<void> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      redirect: "follow",
+      headers: { "User-Agent": "mioku-skills" },
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const length = Number(res.headers.get("content-length") ?? 0);
+    if (length > MAX_ARCHIVE_BYTES) throw new Error("文件过大");
+    const buffer = Buffer.from(await res.arrayBuffer());
+    if (buffer.byteLength > MAX_ARCHIVE_BYTES) throw new Error("文件过大");
+    await fsp.writeFile(target, buffer);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function isInside(root: string, target: string): boolean {
+  const rel = path.relative(root, target);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+/** zip-slip 防护：条目必须落在目标目录内，符号链接一律拒绝 */
+function extractZip(zipPath: string, target: string): void {
+  const zip = new AdmZip(zipPath);
+  const entries = zip.getEntries();
+  if (entries.length > MAX_EXTRACTED_FILES) {
+    throw new Error(`压缩包条目过多（${entries.length}）`);
+  }
+  for (const entry of entries) {
+    const full = path.resolve(target, entry.entryName);
+    if (!isInside(target, full)) throw new Error(`压缩包路径越界：${entry.entryName}`);
+    const attr = entry.attr >>> 16;
+    if ((attr & 0o170000) === 0o120000) {
+      throw new Error(`压缩包包含符号链接：${entry.entryName}`);
+    }
+  }
+  zip.extractAllTo(target, true);
+}
+
+export interface FetchResult {
+  stagingId: string;
+  /** 取件根目录（subPath 指向的子目录或仓库根） */
+  dir: string;
+  display: string;
+}
+
+/** 取件到 temp 下的 staging 目录，按 TTL 自动清理 */
+export async function fetchSkillSource(
+  source: ResolvedSkillSource,
+): Promise<FetchResult | { error: string }> {
+  pruneStaging();
+  const id = randomId();
+  const dir = path.join(STAGING_ROOT, id);
+  ensureDir(dir);
+
+  try {
+    if (source.kind === "git") {
+      const args = ["clone", "--depth", "1"];
+      if (source.ref) args.push("--branch", source.ref);
+      args.push(source.gitUrl!, dir);
+      const result = await runWithTimeout("git", args, STAGING_ROOT, GIT_TIMEOUT_MS);
+      if (result.code !== 0) {
+        throw new Error(`git clone 失败：${result.stderr || result.stdout}`);
+      }
+      fs.rmSync(path.join(dir, ".git"), { recursive: true, force: true });
+      const target = source.subPath ? path.join(dir, source.subPath) : dir;
+      if (!isInside(dir, target) || !fs.existsSync(target)) {
+        throw new Error(`仓库里没有路径 ${source.subPath}`);
+      }
+      staging.set(id, { id, dir: target, display: source.display, createdAt: Date.now() });
+      return { stagingId: id, dir: target, display: source.display };
+    }
+
+    if (source.kind === "local") {
+      staging.set(id, {
+        id,
+        dir: source.localDir!,
+        display: source.display,
+        createdAt: Date.now(),
+      });
+      return { stagingId: id, dir: source.localDir!, display: source.display };
+    }
+
+    const fileName = source.kind === "archive" ? "archive.zip" : "SKILL.md";
+    const downloadPath = path.join(dir, fileName);
+    await download(source.url!, downloadPath);
+    if (source.kind === "archive") {
+      const extracted = path.join(dir, "extracted");
+      ensureDir(extracted);
+      extractZip(downloadPath, extracted);
+      fs.rmSync(downloadPath, { force: true });
+      staging.set(id, { id, dir: extracted, display: source.display, createdAt: Date.now() });
+      return { stagingId: id, dir: extracted, display: source.display };
+    }
+    staging.set(id, { id, dir, display: source.display, createdAt: Date.now() });
+    return { stagingId: id, dir, display: source.display };
+  } catch (err) {
+    fs.rmSync(dir, { recursive: true, force: true });
+    return { error: String(err instanceof Error ? err.message : err) };
+  }
+}
+
+export interface ProbeResult {
+  stagingId: string;
+  display: string;
+  candidates: Array<SkillLocation & { rel: string }>;
+}
+
+/** 取件并列出可安装的技能候选 */
+export async function probeSkillSource(
+  input: string,
+): Promise<ProbeResult | { error: string }> {
+  const resolved = resolveSkillSource(input);
+  if ("error" in resolved) return resolved;
+
+  const fetched = await fetchSkillSource(resolved);
+  if ("error" in fetched) return fetched;
+
+  const located = await locateSkillRoots(fetched.dir);
+  if (located.length === 0) {
+    releaseStaging(fetched.stagingId);
+    return { error: "没找到 SKILL.md，确认这是技能仓库或技能目录" };
+  }
+  return {
+    stagingId: fetched.stagingId,
+    display: fetched.display,
+    candidates: located.map((item) => ({
+      ...item,
+      rel: path.relative(fetched.dir, item.dir).split(path.sep).join("/") || ".",
+    })),
+  };
+}

package/skill-store.ts

@@ -0,0 +1,373 @@
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import {
+  discoverSkills,
+  parseSkillFile,
+  resolveSkillRoots,
+  SKILL_FILE_NAME,
+  SKILL_NAME_PATTERN,
+  type SkillDiagnostic,
+  type SkillRoot,
+} from "mioku";
+import { getAgentConfig, updateAgentConfig } from "./system";
+import {
+  getStaging,
+  resolveSkillSource,
+  type SkillSourceKind,
+} from "./skill-sources";
+import { DATA_DIR, ensureDir, readJsonFile, writeJsonFile } from "./utils";
+
+const REGISTRY_PATH = path.join(DATA_DIR, "webui", "skills.json");
+const INSTALL_TMP_PREFIX = ".mioku-install-";
+
+export interface SkillOrigin {
+  kind: SkillSourceKind;
+  /** 原始来源输入，更新时重新取件 */
+  input: string;
+  display: string;
+  installedAt: number;
+}
+
+interface SkillsRegistry {
+  version: 1;
+  origins: Record<string, SkillOrigin>;
+}
+
+export interface SkillRootInfo extends SkillRoot {
+  exists: boolean;
+  skills: number;
+}
+
+export interface SkillListItem {
+  name: string;
+  description: string;
+  rootId: string;
+  rootLabel: string;
+  rootPath: string;
+  dir: string;
+  path: string;
+  resources: number;
+  modelInvocable: boolean;
+  userInvocable: boolean;
+  enabled: boolean;
+  canUninstall: boolean;
+  origin?: SkillOrigin;
+  diagnostics: SkillDiagnostic[];
+}
+
+export interface SkillDetail extends SkillListItem {
+  content: string;
+  license?: string;
+  compatibility?: string;
+  metadata?: Record<string, string>;
+  allowedTools: string[];
+  resourceList: string[];
+}
+
+function readRegistry(): SkillsRegistry {
+  const raw = readJsonFile<SkillsRegistry>(REGISTRY_PATH, {
+    version: 1,
+    origins: {},
+  });
+  return {
+    version: 1,
+    origins: raw && typeof raw.origins === "object" && raw.origins ? raw.origins : {},
+  };
+}
+
+function writeRegistry(registry: SkillsRegistry): void {
+  ensureDir(path.dirname(REGISTRY_PATH));
+  writeJsonFile(REGISTRY_PATH, registry);
+}
+
+function registryKey(rootId: string, name: string): string {
+  return `${rootId}/${name}`;
+}
+
+export function agentSkillRoots(): SkillRoot[] {
+  const settings = getAgentConfig("settings.json") as {
+    skills?: { extraRoots?: unknown };
+  };
+  const extraRoots = Array.isArray(settings?.skills?.extraRoots)
+    ? settings.skills.extraRoots.map((item) => String(item ?? "")).filter(Boolean)
+    : [];
+  return resolveSkillRoots({ extraRoots });
+}
+
+export function readSkillsState(): { disabled: string[] } {
+  const raw = getAgentConfig("skills.json") as { disabled?: unknown };
+  const disabled = Array.isArray(raw?.disabled)
+    ? raw.disabled.map((item) => String(item ?? "")).filter(Boolean)
+    : [];
+  return { disabled };
+}
+
+export function setSkillEnabled(name: string, enabled: boolean): { disabled: string[] } {
+  const current = readSkillsState();
+  const next = new Set(current.disabled);
+  if (enabled) next.delete(name);
+  else next.add(name);
+  const value = { disabled: [...next].sort() };
+  updateAgentConfig("skills.json", value);
+  return value;
+}
+
+function isInside(root: string, target: string): boolean {
+  const rel = path.relative(root, target);
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+/** 清掉上次安装失败留下的临时目录 */
+function cleanupStaleInstalls(root: SkillRoot): void {
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(root.path);
+  } catch {
+    return;
+  }
+  const cutoff = Date.now() - 60 * 60_000;
+  for (const entry of entries) {
+    if (!entry.startsWith(INSTALL_TMP_PREFIX)) continue;
+    const full = path.join(root.path, entry);
+    try {
+      if (fs.statSync(full).mtimeMs < cutoff) {
+        fs.rmSync(full, { recursive: true, force: true });
+      }
+    } catch {
+      // 忽略
+    }
+  }
+}
+
+export async function listAgentSkillRoots(): Promise<SkillRootInfo[]> {
+  const roots = agentSkillRoots();
+  const { skills } = await discoverSkills(roots);
+  return roots.map((root) => ({
+    ...root,
+    exists: fs.existsSync(root.path),
+    skills: skills.filter((skill) => skill.rootId === root.id).length,
+  }));
+}
+
+export async function listAgentSkills(): Promise<{
+  skills: SkillListItem[];
+  diagnostics: SkillDiagnostic[];
+  roots: SkillRootInfo[];
+}> {
+  const roots = agentSkillRoots();
+  for (const root of roots) cleanupStaleInstalls(root);
+
+  const { skills, diagnostics } = await discoverSkills(roots);
+  const registry = readRegistry();
+  const { disabled } = readSkillsState();
+  const disabledSet = new Set(disabled);
+  const rootById = new Map(roots.map((root) => [root.id, root]));
+
+  return {
+    skills: skills.map((skill) => {
+      const root = rootById.get(skill.rootId);
+      const origin = registry.origins[registryKey(skill.rootId, skill.name)];
+      return {
+        name: skill.name,
+        description: skill.description,
+        rootId: skill.rootId,
+        rootLabel: root?.label ?? skill.rootId,
+        rootPath: root?.path ?? "",
+        dir: skill.dir,
+        path: skill.path,
+        resources: skill.resources.length,
+        modelInvocable: skill.invoke.modelInvocable,
+        userInvocable: skill.invoke.userInvocable,
+        enabled: !disabledSet.has(skill.name),
+        canUninstall: Boolean(root?.writable),
+        ...(origin ? { origin } : {}),
+        diagnostics: diagnostics.filter((item) => item.path === skill.path),
+      };
+    }),
+    diagnostics,
+    roots: roots.map((root) => ({
+      ...root,
+      exists: fs.existsSync(root.path),
+      skills: skills.filter((skill) => skill.rootId === root.id).length,
+    })),
+  };
+}
+
+export async function readAgentSkill(
+  rootId: string,
+  name: string,
+): Promise<SkillDetail | undefined> {
+  const roots = agentSkillRoots();
+  const { skills, diagnostics } = await discoverSkills(roots);
+  const source = skills.find(
+    (skill) => skill.name === name && (!rootId || skill.rootId === rootId),
+  );
+  if (!source) return undefined;
+
+  const root = roots.find((item) => item.id === source.rootId);
+  const registry = readRegistry();
+  const origin = registry.origins[registryKey(source.rootId, source.name)];
+  const disabledSet = new Set(readSkillsState().disabled);
+
+  let raw: string;
+  try {
+    raw = await fsp.readFile(source.path, "utf-8");
+  } catch {
+    return undefined;
+  }
+  const parsed = parseSkillFile(source.path, raw);
+  if (!parsed.skill) return undefined;
+
+  return {
+    name: source.name,
+    description: source.description,
+    rootId: source.rootId,
+    rootLabel: root?.label ?? source.rootId,
+    rootPath: root?.path ?? "",
+    dir: source.dir,
+    path: source.path,
+    resources: source.resources.length,
+    resourceList: source.resources,
+    modelInvocable: source.invoke.modelInvocable,
+    userInvocable: source.invoke.userInvocable,
+    enabled: !disabledSet.has(source.name),
+    canUninstall: Boolean(root?.writable),
+    ...(origin ? { origin } : {}),
+    diagnostics: [
+      ...diagnostics.filter((item) => item.path === source.path),
+      ...parsed.diagnostics,
+    ],
+    content: parsed.skill.content,
+    allowedTools: parsed.skill.allowedTools,
+    ...(parsed.skill.license ? { license: parsed.skill.license } : {}),
+    ...(parsed.skill.compatibility
+      ? { compatibility: parsed.skill.compatibility }
+      : {}),
+    ...(parsed.skill.metadata ? { metadata: parsed.skill.metadata } : {}),
+  };
+}
+
+export interface InstallSkillInput {
+  rootId: string;
+  stagingId: string;
+  /** staging 内的相对子目录，空表示根 */
+  rel?: string;
+  /** 覆盖安装名，默认用 frontmatter 的 name */
+  name?: string;
+  overwrite?: boolean;
+  /** 原始来源输入，写进注册表供更新使用 */
+  originInput?: string;
+}
+
+export interface InstallSkillResult {
+  name: string;
+  rootId: string;
+  dir: string;
+}
+
+export async function installAgentSkill(
+  input: InstallSkillInput,
+): Promise<InstallSkillResult | { error: string }> {
+  const root = agentSkillRoots().find((item) => item.id === input.rootId);
+  if (!root) return { error: `未知的技能根：${input.rootId}` };
+  if (!root.writable) return { error: `技能根 ${root.label} 不允许安装` };
+
+  const staged = getStaging(input.stagingId);
+  if (!staged) return { error: "取件结果已过期，请重新检测来源" };
+
+  const sourceDir =
+    input.rel && input.rel !== "."
+      ? path.resolve(staged.dir, input.rel)
+      : staged.dir;
+  if (!isInside(staged.dir, sourceDir) && sourceDir !== staged.dir) {
+    return { error: "候选路径越界" };
+  }
+  if (!fs.existsSync(sourceDir)) return { error: "候选目录不存在" };
+
+  let raw: string;
+  try {
+    raw = await fsp.readFile(path.join(sourceDir, SKILL_FILE_NAME), "utf-8");
+  } catch {
+    return { error: "候选目录里没有 SKILL.md" };
+  }
+  const parsed = parseSkillFile(path.join(sourceDir, SKILL_FILE_NAME), raw);
+  if (!parsed.skill) {
+    return {
+      error: `SKILL.md 校验不通过：${parsed.diagnostics[0]?.message ?? "未知原因"}`,
+    };
+  }
+
+  const name = String(input.name ?? "").trim() || parsed.skill.name;
+  if (!SKILL_NAME_PATTERN.test(name)) {
+    return { error: `技能名 "${name}" 不合法（小写字母、数字与单个连字符）` };
+  }
+
+  ensureDir(root.path);
+  const target = path.join(root.path, name);
+  if (fs.existsSync(target) && !input.overwrite) {
+    return { error: `技能 ${name} 已存在于 ${root.label}，确认覆盖后再试` };
+  }
+
+  const stagingDir = path.join(root.path, `${INSTALL_TMP_PREFIX}${Date.now()}`);
+  try {
+    await fsp.cp(sourceDir, stagingDir, { recursive: true, dereference: true });
+    if (fs.existsSync(target)) {
+      await fsp.rm(target, { recursive: true, force: true });
+    }
+    await fsp.rename(stagingDir, target);
+  } catch (err) {
+    await fsp.rm(stagingDir, { recursive: true, force: true }).catch(() => {});
+    return { error: `写入失败：${err instanceof Error ? err.message : err}` };
+  }
+
+  const registry = readRegistry();
+  const originInput = String(input.originInput ?? staged.display);
+  const resolved = resolveSkillSource(originInput);
+  registry.origins[registryKey(root.id, name)] = {
+    kind: "error" in resolved ? "local" : resolved.kind,
+    input: originInput,
+    display: staged.display,
+    installedAt: Date.now(),
+  };
+  writeRegistry(registry);
+
+  return { name, rootId: root.id, dir: target };
+}
+
+export async function uninstallAgentSkill(
+  rootId: string,
+  name: string,
+): Promise<{ ok: true } | { error: string }> {
+  if (!SKILL_NAME_PATTERN.test(name)) return { error: "技能名不合法" };
+  const root = agentSkillRoots().find((item) => item.id === rootId);
+  if (!root) return { error: `未知的技能根：${rootId}` };
+  if (!root.writable) return { error: `技能根 ${root.label} 不允许卸载` };
+
+  const target = path.join(root.path, name);
+  if (!isInside(root.path, target)) return { error: "路径越界" };
+  if (!fs.existsSync(path.join(target, SKILL_FILE_NAME))) {
+    return { error: `在 ${root.label} 下找不到技能 ${name}` };
+  }
+
+  await fsp.rm(target, { recursive: true, force: true });
+  const registry = readRegistry();
+  delete registry.origins[registryKey(rootId, name)];
+  writeRegistry(registry);
+  setSkillEnabled(name, true);
+  return { ok: true };
+}
+
+export function getSkillOrigin(rootId: string, name: string): SkillOrigin | undefined {
+  return readRegistry().origins[registryKey(rootId, name)];
+}
+
+export function recordSkillOrigin(
+  rootId: string,
+  name: string,
+  origin: SkillOrigin,
+): void {
+  const registry = readRegistry();
+  registry.origins[registryKey(rootId, name)] = origin;
+  writeRegistry(registry);
+}