mioku-service-webui 2.0.0

package/system.ts

@@ -0,0 +1,1894 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import process from "node:process";
+import { connectedBots, systemInfo } from "mioki";
+import type {
+  InstallRequest,
+  ManagedTarget,
+  PackageManager,
+  RemoveRequest,
+  UpdateRequest,
+  WebUISettings,
+} from "./types";
+import {
+  CHAT_CONFIG_DIR,
+  defaultWebUISettings,
+  ensureDir,
+  getInstallCommand,
+  isValidRepoUrl,
+  LOCAL_CONFIG_PATH,
+  normalizeManagedPackageName,
+  normalizePackageManager,
+  PLUGINS_DIR,
+  readJsonFile,
+  ROOT_PACKAGE_PATH,
+  runCommand,
+  SERVICES_DIR,
+  SETTINGS_PATH,
+  WEBUI_DIST,
+  writeJsonFile,
+} from "./utils";
+
+interface NapcatNodeConfig {
+  name?: string;
+  host?: string;
+  port?: number;
+  token?: string;
+  protocol?: string;
+}
+
+interface MiokiRuntimeConfig {
+  mioki?: {
+    napcat?: NapcatNodeConfig[];
+    [key: string]: any;
+  };
+  [key: string]: any;
+}
+
+const SYSTEM_PLUGIN_NAMES = new Set(["boot", "chat", "help"]);
+const SYSTEM_SERVICE_NAMES = new Set(["ai", "config", "help", "screenshot"]);
+const BOOT_CONFIG_PATH = path.join(process.cwd(), "config", "boot", "base.json");
+
+interface AccessRuleConfig {
+  whitelist: Array<string | number>;
+  blacklist: Array<string | number>;
+}
+
+export interface BootSystemConfig {
+  likeCommand: {
+    enabled: boolean;
+    keyword: string;
+    likeTimes: number;
+    reactionEmojiId: number;
+  };
+  friend: {
+    autoApprove: boolean;
+  };
+  group: {
+    minMemberCount: number;
+    welcome: {
+      enabled: boolean;
+      mode: "ai" | "text";
+      text: string;
+      aiPrompt: string;
+    };
+  };
+  messageFilter: {
+    user: AccessRuleConfig;
+    group: AccessRuleConfig;
+  };
+}
+
+const DEFAULT_BOOT_SYSTEM_CONFIG: BootSystemConfig = {
+  likeCommand: {
+    enabled: true,
+    keyword: "赞我",
+    likeTimes: 10,
+    reactionEmojiId: 66,
+  },
+  friend: {
+    autoApprove: false,
+  },
+  group: {
+    minMemberCount: 0,
+    welcome: {
+      enabled: true,
+      mode: "ai",
+      text: "欢迎 {user} 加入 {group}",
+      aiPrompt: "",
+    },
+  },
+  messageFilter: {
+    user: {
+      whitelist: [],
+      blacklist: [],
+    },
+    group: {
+      whitelist: [],
+      blacklist: [],
+    },
+  },
+};
+
+function isContainerRuntime(): boolean {
+  return fs.existsSync("/.dockerenv");
+}
+
+function isSystemPluginName(name: string): boolean {
+  return SYSTEM_PLUGIN_NAMES.has(
+    String(name || "")
+      .trim()
+      .toLowerCase(),
+  );
+}
+
+function isSystemServiceName(name: string): boolean {
+  return SYSTEM_SERVICE_NAMES.has(
+    String(name || "")
+      .trim()
+      .toLowerCase(),
+  );
+}
+
+function getTargetRoot(target: ManagedTarget): string {
+  return target === "plugin" ? PLUGINS_DIR : SERVICES_DIR;
+}
+
+async function getCurrentBranchName(dir: string): Promise<string> {
+  const branchRes = await runCommand("git", ["branch", "--show-current"], dir);
+  if (branchRes.code !== 0) {
+    return "unknown";
+  }
+  return String(branchRes.stdout || "").trim() || "unknown";
+}
+
+async function getDefaultRemoteBranch(dir: string): Promise<string> {
+  const headRes = await runCommand(
+    "git",
+    ["symbolic-ref", "refs/remotes/origin/HEAD"],
+    dir,
+  );
+  if (headRes.code !== 0) {
+    return "main";
+  }
+  const ref = String(headRes.stdout || "").trim();
+  return ref.split("/").pop() || "main";
+}
+
+async function resolveMiokuTargetRef(
+  dir: string,
+): Promise<{ currentBranch: string; targetRef: string; targetBranch: string }> {
+  const currentBranch = await getCurrentBranchName(dir);
+  if (currentBranch !== "unknown") {
+    return {
+      currentBranch,
+      targetRef: `origin/${currentBranch}`,
+      targetBranch: currentBranch,
+    };
+  }
+
+  const targetBranch = await getDefaultRemoteBranch(dir);
+  return {
+    currentBranch,
+    targetRef: `origin/${targetBranch}`,
+    targetBranch,
+  };
+}
+
+function deepMerge<T extends Record<string, any>>(
+  target: T,
+  source: Partial<T>,
+): T {
+  const result = { ...target };
+  for (const key in source) {
+    const sourceValue = source[key];
+    const targetValue = result[key];
+    if (
+      sourceValue &&
+      typeof sourceValue === "object" &&
+      !Array.isArray(sourceValue) &&
+      targetValue &&
+      typeof targetValue === "object" &&
+      !Array.isArray(targetValue)
+    ) {
+      result[key] = deepMerge(targetValue, sourceValue);
+    } else if (sourceValue !== undefined) {
+      result[key] = sourceValue as any;
+    }
+  }
+  return result;
+}
+
+function cloneJson<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function normalizeAccessRuleConfig(input: any): AccessRuleConfig {
+  return {
+    whitelist: Array.isArray(input?.whitelist) ? input.whitelist : [],
+    blacklist: Array.isArray(input?.blacklist) ? input.blacklist : [],
+  };
+}
+
+function normalizeBootSystemConfig(input: any): BootSystemConfig {
+  const merged = deepMerge(cloneJson(DEFAULT_BOOT_SYSTEM_CONFIG), input || {});
+  const legacyPrivateFilter = input?.messageFilter?.private;
+  const userFilterSource = input?.messageFilter?.user ?? legacyPrivateFilter;
+
+  return {
+    likeCommand: {
+      enabled: Boolean(merged?.likeCommand?.enabled),
+      keyword:
+        typeof merged?.likeCommand?.keyword === "string" &&
+        merged.likeCommand.keyword.trim()
+          ? merged.likeCommand.keyword.trim()
+          : DEFAULT_BOOT_SYSTEM_CONFIG.likeCommand.keyword,
+      likeTimes:
+        typeof merged?.likeCommand?.likeTimes === "number" &&
+        Number.isFinite(merged.likeCommand.likeTimes)
+          ? merged.likeCommand.likeTimes
+          : DEFAULT_BOOT_SYSTEM_CONFIG.likeCommand.likeTimes,
+      reactionEmojiId:
+        typeof merged?.likeCommand?.reactionEmojiId === "number" &&
+        Number.isFinite(merged.likeCommand.reactionEmojiId)
+          ? merged.likeCommand.reactionEmojiId
+          : DEFAULT_BOOT_SYSTEM_CONFIG.likeCommand.reactionEmojiId,
+    },
+    friend: {
+      autoApprove: Boolean(merged?.friend?.autoApprove),
+    },
+    group: {
+      minMemberCount:
+        typeof merged?.group?.minMemberCount === "number" &&
+        Number.isFinite(merged.group.minMemberCount)
+          ? merged.group.minMemberCount
+          : DEFAULT_BOOT_SYSTEM_CONFIG.group.minMemberCount,
+      welcome: {
+        enabled: Boolean(merged?.group?.welcome?.enabled),
+        mode:
+          merged?.group?.welcome?.mode === "text" ? "text" : "ai",
+        text:
+          typeof merged?.group?.welcome?.text === "string"
+            ? merged.group.welcome.text
+            : DEFAULT_BOOT_SYSTEM_CONFIG.group.welcome.text,
+        aiPrompt:
+          typeof merged?.group?.welcome?.aiPrompt === "string"
+            ? merged.group.welcome.aiPrompt
+            : DEFAULT_BOOT_SYSTEM_CONFIG.group.welcome.aiPrompt,
+      },
+    },
+    messageFilter: {
+      user: normalizeAccessRuleConfig(userFilterSource),
+      group: normalizeAccessRuleConfig(merged?.messageFilter?.group),
+    },
+  };
+}
+
+function readPackageJson(dir: string): any {
+  const packagePath = path.join(dir, "package.json");
+  if (!fs.existsSync(packagePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function readRootPackageJson(): any {
+  return JSON.parse(fs.readFileSync(ROOT_PACKAGE_PATH, "utf-8"));
+}
+
+function writeRootPackageJson(data: any): void {
+  fs.writeFileSync(ROOT_PACKAGE_PATH, JSON.stringify(data, null, 2), "utf-8");
+}
+
+function packageManagerFromSettings(input?: PackageManager): PackageManager {
+  if (input) {
+    return normalizePackageManager(input);
+  }
+  const settings = getWebUISettings();
+  return normalizePackageManager(settings.packageManager);
+}
+
+export function getWebUISettings(): WebUISettings {
+  ensureDir(path.dirname(SETTINGS_PATH));
+  const settings = readJsonFile<Record<string, unknown>>(
+    SETTINGS_PATH,
+    defaultWebUISettings as unknown as Record<string, unknown>,
+  );
+  const merged: WebUISettings = {
+    port:
+      typeof settings.port === "number" && Number.isFinite(settings.port)
+        ? settings.port
+        : defaultWebUISettings.port,
+    host:
+      typeof settings.host === "string" && settings.host.trim()
+        ? settings.host
+        : defaultWebUISettings.host,
+    packageManager: normalizePackageManager(
+      typeof settings.packageManager === "string"
+        ? settings.packageManager
+        : undefined,
+    ),
+  };
+  writeJsonFile(SETTINGS_PATH, merged);
+  return merged;
+}
+
+export function updateWebUISettings(
+  input: Partial<WebUISettings>,
+): WebUISettings {
+  const current = getWebUISettings();
+  const next: WebUISettings = {
+    port:
+      typeof input.port === "number" && Number.isFinite(input.port)
+        ? input.port
+        : current.port,
+    host:
+      typeof input.host === "string" && input.host.trim()
+        ? input.host
+        : current.host,
+    packageManager: normalizePackageManager(
+      input.packageManager ?? current.packageManager,
+    ),
+  };
+  writeJsonFile(SETTINGS_PATH, next);
+  return next;
+}
+
+export function getBootSystemConfig(): BootSystemConfig {
+  ensureDir(path.dirname(BOOT_CONFIG_PATH));
+  const raw = readJsonFile<any>(BOOT_CONFIG_PATH, DEFAULT_BOOT_SYSTEM_CONFIG);
+  const normalized = normalizeBootSystemConfig(raw);
+  writeJsonFile(BOOT_CONFIG_PATH, normalized);
+  return normalized;
+}
+
+export function updateBootSystemConfig(
+  input: Partial<BootSystemConfig>,
+): BootSystemConfig {
+  const current = getBootSystemConfig();
+  const next = normalizeBootSystemConfig(deepMerge(current, input || {}));
+  writeJsonFile(BOOT_CONFIG_PATH, next);
+  return next;
+}
+
+function checkDependentServices(packageJson: any): string[] {
+  const services = packageJson?.mioku?.services;
+  if (!Array.isArray(services)) {
+    return [];
+  }
+  return services.filter((serviceName: string) => {
+    const servicePath = path.join(SERVICES_DIR, serviceName);
+    return !fs.existsSync(servicePath);
+  });
+}
+
+function assertSafePackageName(name: string): string {
+  const trimmed = String(name || "").trim();
+  if (!trimmed) {
+    throw new Error("名称不能为空");
+  }
+  if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) {
+    throw new Error("名称格式非法");
+  }
+  return trimmed;
+}
+
+function resolveManagedDir(target: ManagedTarget, name: string): string {
+  const safeName = assertSafePackageName(name);
+  const root = path.resolve(getTargetRoot(target));
+  const dir = path.resolve(root, safeName);
+  if (!dir.startsWith(`${root}${path.sep}`)) {
+    throw new Error("非法路径");
+  }
+  if (!fs.existsSync(dir)) {
+    throw new Error("目录不存在");
+  }
+  return dir;
+}
+
+function getRepositoryFromPackage(pkg: any): string {
+  const repository = pkg?.repository;
+  if (!repository) return "";
+  if (typeof repository === "string") return repository;
+  if (typeof repository?.url === "string") return repository.url;
+  return "";
+}
+
+async function getGitOriginUrl(dir: string): Promise<string> {
+  const res = await runCommand("git", ["remote", "get-url", "origin"], dir);
+  if (res.code !== 0) return "";
+  return res.stdout.trim();
+}
+
+function resolveWebUIProjectDir(): string {
+  const candidates = [
+    path.join(process.cwd(), "mioku-webui"),
+    path.join(process.cwd(), "webui"),
+  ];
+
+  for (const dir of candidates) {
+    if (fs.existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+  }
+  return candidates[0];
+}
+
+function readInstalledWebUIVersion(): string {
+  const versionFileCandidates = [
+    path.join(WEBUI_DIST, "webui-version.json"),
+    path.join(WEBUI_DIST, ".webui-version"),
+  ];
+
+  for (const versionFile of versionFileCandidates) {
+    if (!fs.existsSync(versionFile)) continue;
+    try {
+      const raw = fs.readFileSync(versionFile, "utf-8").trim();
+      if (!raw) continue;
+      if (versionFile.endsWith(".json")) {
+        const parsed = JSON.parse(raw);
+        const version = String(parsed?.version || "").trim();
+        if (version) return normalizeVersionSpec(version);
+      } else {
+        return normalizeVersionSpec(raw);
+      }
+    } catch {
+      // ignore invalid version marker
+    }
+  }
+
+  return readPackageVersion(
+    path.join(resolveWebUIProjectDir(), "package.json"),
+  );
+}
+
+function parseGitHubRepo(
+  input: string,
+): { owner: string; repo: string; fullName: string } | null {
+  const url = String(input || "").trim();
+  if (!url) return null;
+
+  const patterns = [
+    /^https?:\/\/github\.com\/([^/]+)\/([^/#?]+?)(?:\.git)?(?:[/?#].*)?$/i,
+    /^git@github\.com:([^/]+)\/([^/#?]+?)(?:\.git)?$/i,
+    /^ssh:\/\/git@github\.com\/([^/]+)\/([^/#?]+?)(?:\.git)?$/i,
+  ];
+
+  for (const pattern of patterns) {
+    const matched = url.match(pattern);
+    if (!matched) continue;
+    const owner = matched[1];
+    const repo = matched[2];
+    if (!owner || !repo) continue;
+    return { owner, repo, fullName: `${owner}/${repo}` };
+  }
+
+  return null;
+}
+
+function parseVersionParts(input: string): number[] {
+  const normalized = normalizeVersionSpec(input).replace(/^v/i, "");
+  const core = normalized.split("-")[0].split("+")[0];
+  if (!core) return [];
+  return core
+    .split(".")
+    .map((part) => Number(part))
+    .filter((part) => Number.isFinite(part) && part >= 0);
+}
+
+function isVersionNewer(latest: string, current: string): boolean {
+  const latestParts = parseVersionParts(latest);
+  const currentParts = parseVersionParts(current);
+  const maxLen = Math.max(latestParts.length, currentParts.length, 3);
+
+  for (let i = 0; i < maxLen; i += 1) {
+    const a = latestParts[i] ?? 0;
+    const b = currentParts[i] ?? 0;
+    if (a > b) return true;
+    if (a < b) return false;
+  }
+
+  const latestNormalized = normalizeVersionSpec(latest).replace(/^v/i, "");
+  const currentNormalized = normalizeVersionSpec(current).replace(/^v/i, "");
+  return latestNormalized !== currentNormalized;
+}
+
+function hasUsableDistFiles(dir: string): boolean {
+  return fs.existsSync(path.join(dir, "index.html"));
+}
+
+function resolveDistSourceDir(unpackDir: string): string | null {
+  const directCandidates = [path.join(unpackDir, "dist"), unpackDir];
+  for (const candidate of directCandidates) {
+    if (hasUsableDistFiles(candidate)) {
+      return candidate;
+    }
+  }
+
+  const children = fs.existsSync(unpackDir)
+    ? fs.readdirSync(unpackDir, { withFileTypes: true })
+    : [];
+  for (const child of children) {
+    if (!child.isDirectory()) continue;
+    const childDir = path.join(unpackDir, child.name);
+    const nestedDist = path.join(childDir, "dist");
+    if (hasUsableDistFiles(nestedDist)) {
+      return nestedDist;
+    }
+    if (hasUsableDistFiles(childDir)) {
+      return childDir;
+    }
+  }
+
+  return null;
+}
+
+function readReadmeFile(
+  dir: string,
+): { fileName: string; content: string } | null {
+  const candidates = [
+    "README.md",
+    "README.MD",
+    "readme.md",
+    "README.txt",
+    "README",
+    "readme",
+  ];
+
+  for (const fileName of candidates) {
+    const filePath = path.join(dir, fileName);
+    if (!fs.existsSync(filePath)) continue;
+    try {
+      const content = fs.readFileSync(filePath, "utf-8");
+      return { fileName, content };
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+interface ManagedPackageUpdateInfo {
+  state: "up-to-date" | "has-updates" | "unknown" | "no-git";
+  hasUpdates: boolean;
+  behind: number;
+  changelog: string[];
+  error?: string;
+}
+
+interface ManagedPackageUpdateCacheEntry {
+  checkedAt: number;
+  info: ManagedPackageUpdateInfo;
+}
+
+interface WebUIReleaseAsset {
+  name: string;
+  browser_download_url: string;
+}
+
+interface WebUIUpdateCheckResult {
+  currentVersion: string;
+  latestVersion: string;
+  releaseTag: string;
+  releaseUrl: string;
+  sourceRepo: string;
+  hasUpdates: boolean;
+  canUpdate: boolean;
+  assetName: string;
+  assetUrl: string;
+  checkedAt: number;
+  error?: string;
+}
+
+interface MiokuUpdateCheckResult {
+  currentVersion: string;
+  latestVersion: string;
+  sourceRepo: string;
+  currentBranch: string;
+  targetRef: string;
+  hasUpdates: boolean;
+  behind: number;
+  changelog: string[];
+  checkedAt: number;
+  error?: string;
+}
+
+const MANAGED_UPDATE_CACHE_TTL_MS = 120_000;
+const managedPackageUpdateCache = new Map<
+  string,
+  ManagedPackageUpdateCacheEntry
+>();
+const managedOverviewRefreshInFlight = new Map<ManagedTarget, Promise<void>>();
+const WEBUI_UPDATE_CACHE_TTL_MS = 60_000;
+let webuiUpdateCache: WebUIUpdateCheckResult | null = null;
+let webuiUpdateCheckInFlight: Promise<WebUIUpdateCheckResult> | null = null;
+let webuiUpdatingInFlight: Promise<Record<string, any>> | null = null;
+const MIOKU_UPDATE_CACHE_TTL_MS = 60_000;
+let miokuUpdateCache: MiokuUpdateCheckResult | null = null;
+let miokuUpdateCheckInFlight: Promise<MiokuUpdateCheckResult> | null = null;
+
+function makeManagedUpdateCacheKey(
+  target: ManagedTarget,
+  name: string,
+): string {
+  return `${target}:${name}`;
+}
+
+function getCachedManagedUpdateInfo(
+  target: ManagedTarget,
+  name: string,
+): ManagedPackageUpdateCacheEntry | null {
+  return (
+    managedPackageUpdateCache.get(makeManagedUpdateCacheKey(target, name)) ||
+    null
+  );
+}
+
+function setCachedManagedUpdateInfo(
+  target: ManagedTarget,
+  name: string,
+  info: ManagedPackageUpdateInfo,
+): void {
+  managedPackageUpdateCache.set(makeManagedUpdateCacheKey(target, name), {
+    checkedAt: Date.now(),
+    info,
+  });
+}
+
+function isManagedUpdateCacheFresh(
+  entry: ManagedPackageUpdateCacheEntry | null,
+): boolean {
+  if (!entry) return false;
+  return Date.now() - entry.checkedAt < MANAGED_UPDATE_CACHE_TTL_MS;
+}
+
+async function refreshManagedUpdatesInBackground(
+  target: ManagedTarget,
+  packages: Array<Record<string, any>>,
+): Promise<void> {
+  for (const item of packages) {
+    const name = String(item.name || "");
+    if (!name) continue;
+
+    if (!item.hasGit) {
+      setCachedManagedUpdateInfo(target, name, {
+        state: "no-git",
+        hasUpdates: false,
+        behind: 0,
+        changelog: [],
+        error: "NOT_GIT_REPO",
+      });
+      continue;
+    }
+
+    try {
+      const updateInfo = await getManagedPackageUpdateInfo(
+        String(item.path || ""),
+      );
+      setCachedManagedUpdateInfo(target, name, updateInfo);
+    } catch (error: any) {
+      setCachedManagedUpdateInfo(target, name, {
+        state: "unknown",
+        hasUpdates: false,
+        behind: 0,
+        changelog: [],
+        error: error?.message || "UPDATE_CHECK_FAILED",
+      });
+    }
+  }
+}
+
+function scheduleManagedUpdatesRefresh(
+  target: ManagedTarget,
+  packages: Array<Record<string, any>>,
+): void {
+  if (managedOverviewRefreshInFlight.has(target)) return;
+
+  const shouldRefresh = packages.some((item) => {
+    if (!item.hasGit) return false;
+    const cached = getCachedManagedUpdateInfo(target, String(item.name || ""));
+    return !isManagedUpdateCacheFresh(cached);
+  });
+
+  if (!shouldRefresh) return;
+
+  const job = refreshManagedUpdatesInBackground(target, packages).finally(
+    () => {
+      managedOverviewRefreshInFlight.delete(target);
+    },
+  );
+  managedOverviewRefreshInFlight.set(target, job);
+}
+
+async function getManagedPackageUpdateInfo(
+  dir: string,
+): Promise<ManagedPackageUpdateInfo> {
+  if (!fs.existsSync(path.join(dir, ".git"))) {
+    return {
+      state: "no-git",
+      hasUpdates: false,
+      behind: 0,
+      changelog: [],
+      error: "NOT_GIT_REPO",
+    };
+  }
+
+  const fetchRes = await runCommand("git", ["fetch", "--all"], dir);
+  if (fetchRes.code !== 0) {
+    return {
+      state: "unknown",
+      hasUpdates: false,
+      behind: 0,
+      changelog: [],
+      error: `git fetch 失败: ${fetchRes.stderr || fetchRes.stdout}`.trim(),
+    };
+  }
+
+  const compare = await runCommand(
+    "git",
+    ["rev-list", "--left-right", "--count", "HEAD...@{u}"],
+    dir,
+  );
+  if (compare.code !== 0) {
+    return {
+      state: "unknown",
+      hasUpdates: false,
+      behind: 0,
+      changelog: [],
+      error: `无法比较更新: ${compare.stderr || compare.stdout}`.trim(),
+    };
+  }
+
+  const parts = compare.stdout
+    .trim()
+    .split(/\s+/)
+    .map((item) => Number(item));
+  const behind = Number.isFinite(parts[1]) ? parts[1] : 0;
+
+  const changelog = await runCommand(
+    "git",
+    ["log", "--oneline", "HEAD..@{u}", "-n", "30"],
+    dir,
+  );
+
+  return {
+    state: behind > 0 ? "has-updates" : "up-to-date",
+    hasUpdates: behind > 0,
+    behind,
+    changelog: changelog.stdout.trim().split("\n").filter(Boolean),
+  };
+}
+
+export function listManagedPackages(
+  target: ManagedTarget,
+): Array<Record<string, any>> {
+  const root = getTargetRoot(target);
+  ensureDir(root);
+  const names = fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name);
+
+  return names.map((name) => {
+    const fullPath = path.join(root, name);
+    const pkg = readPackageJson(fullPath);
+    return {
+      name,
+      path: fullPath,
+      version: pkg?.version ?? "0.0.0",
+      description: pkg?.description ?? "",
+      hasGit: fs.existsSync(path.join(fullPath, ".git")),
+      isSystemPlugin: target === "plugin" ? isSystemPluginName(name) : false,
+      isSystemService: target === "service" ? isSystemServiceName(name) : false,
+      repository: getRepositoryFromPackage(pkg),
+      requiredServices: pkg?.mioku?.services ?? [],
+    };
+  });
+}
+
+export async function installManagedPackage(
+  input: InstallRequest,
+): Promise<Record<string, any>> {
+  if (!isValidRepoUrl(input.repoUrl)) {
+    throw new Error("仓库地址无效");
+  }
+
+  const targetRoot = getTargetRoot(input.target);
+  ensureDir(targetRoot);
+
+  const packageName = normalizeManagedPackageName(input.repoUrl, input.target);
+  const destination = path.join(targetRoot, packageName);
+
+  if (fs.existsSync(destination)) {
+    throw new Error(`${packageName} 已存在`);
+  }
+
+  const clone = await runCommand(
+    "git",
+    ["clone", input.repoUrl, destination],
+    process.cwd(),
+  );
+  if (clone.code !== 0) {
+    throw new Error(`git clone 失败: ${clone.stderr || clone.stdout}`);
+  }
+
+  const packageJson = readPackageJson(destination);
+  const missingServices = checkDependentServices(packageJson);
+
+  const packageManager = packageManagerFromSettings(input.packageManager);
+  const installCmd = getInstallCommand(packageManager);
+  const install = await runCommand(
+    installCmd.cmd,
+    installCmd.args,
+    destination,
+  );
+
+  if (install.code !== 0) {
+    throw new Error(`依赖安装失败: ${install.stderr || install.stdout}`);
+  }
+
+  managedPackageUpdateCache.delete(
+    makeManagedUpdateCacheKey(input.target, packageName),
+  );
+
+  return {
+    ok: true,
+    name: packageName,
+    missingServices,
+    packageManager,
+    restartRequired: true,
+    installOutput: install.stdout || install.stderr,
+  };
+}
+
+export async function checkUpdate(
+  name: string,
+  target: ManagedTarget,
+): Promise<Record<string, any>> {
+  const dir = resolveManagedDir(target, name);
+  const result = await getManagedPackageUpdateInfo(dir);
+  setCachedManagedUpdateInfo(target, name, result);
+  return {
+    ok: true,
+    state: result.state,
+    hasUpdates: result.hasUpdates,
+    behind: result.behind,
+    changelog: result.changelog,
+    hasGit: result.state !== "no-git",
+    error: result.error,
+  };
+}
+
+function packageJsonChanged(before: string, after: string): boolean {
+  return before !== after;
+}
+
+export async function updateManagedPackage(
+  input: UpdateRequest,
+): Promise<Record<string, any>> {
+  const dir = resolveManagedDir(input.target, input.name);
+
+  const before = await runCommand("git", ["show", "HEAD:package.json"], dir);
+
+  const pull = await runCommand("git", ["pull"], dir);
+  if (pull.code !== 0) {
+    throw new Error(`git pull 失败: ${pull.stderr || pull.stdout}`);
+  }
+
+  const after = await runCommand("git", ["show", "HEAD:package.json"], dir);
+  const changed = packageJsonChanged(before.stdout, after.stdout);
+
+  let reinstallOutput = "";
+  if (changed) {
+    const packageManager = packageManagerFromSettings(input.packageManager);
+    const installCmd = getInstallCommand(packageManager);
+    const install = await runCommand(installCmd.cmd, installCmd.args, dir);
+    if (install.code !== 0) {
+      throw new Error(`依赖安装失败: ${install.stderr || install.stdout}`);
+    }
+    reinstallOutput = install.stdout || install.stderr;
+  }
+
+  managedPackageUpdateCache.delete(
+    makeManagedUpdateCacheKey(input.target, input.name),
+  );
+
+  return {
+    ok: true,
+    restartRequired: true,
+    packageJsonChanged: changed,
+    reinstallOutput,
+  };
+}
+
+export async function removeManagedPackage(
+  input: RemoveRequest,
+): Promise<Record<string, any>> {
+  if (input.target === "plugin" && isSystemPluginName(input.name)) {
+    throw new Error("系统插件不可卸载");
+  }
+  if (input.target === "service" && isSystemServiceName(input.name)) {
+    throw new Error("系统服务不可卸载");
+  }
+
+  const dir = resolveManagedDir(input.target, input.name);
+
+  fs.rmSync(dir, { recursive: true, force: true });
+
+  managedPackageUpdateCache.delete(
+    makeManagedUpdateCacheKey(input.target, input.name),
+  );
+
+  return {
+    ok: true,
+    restartRequired: true,
+  };
+}
+
+export async function listManagedPackagesWithUpdates(
+  target: ManagedTarget,
+): Promise<Array<Record<string, any>>> {
+  const packages = listManagedPackages(target);
+  scheduleManagedUpdatesRefresh(target, packages);
+  const refreshRunning = managedOverviewRefreshInFlight.has(target);
+
+  return packages.map((item) => {
+    const name = String(item.name || "");
+
+    if (!item.hasGit) {
+      return {
+        ...item,
+        updateState: "no-git",
+        hasUpdates: false,
+        behind: 0,
+        updateError: "NOT_GIT_REPO",
+        updateChecking: false,
+      };
+    }
+
+    const cached = getCachedManagedUpdateInfo(target, name);
+    if (cached) {
+      return {
+        ...item,
+        updateState: cached.info.state,
+        hasUpdates: cached.info.hasUpdates,
+        behind: cached.info.behind,
+        updateError: cached.info.error || "",
+        updateChecking: refreshRunning && !isManagedUpdateCacheFresh(cached),
+        updateCheckedAt: cached.checkedAt,
+      };
+    }
+
+    return {
+      ...item,
+      updateState: "unknown",
+      hasUpdates: false,
+      behind: 0,
+      updateError: "",
+      updateChecking: true,
+      updateCheckedAt: 0,
+    };
+  });
+}
+
+export async function getManagedPackageDetail(
+  name: string,
+  target: ManagedTarget,
+): Promise<Record<string, any>> {
+  const dir = resolveManagedDir(target, name);
+  const pkg = readPackageJson(dir) || {};
+  const readme = readReadmeFile(dir);
+  const originUrl = await getGitOriginUrl(dir);
+  const repositoryFromPkg = getRepositoryFromPackage(pkg);
+  const updateInfo = await getManagedPackageUpdateInfo(dir);
+  setCachedManagedUpdateInfo(target, name, updateInfo);
+  const requiredServices = Array.isArray(pkg?.mioku?.services)
+    ? pkg.mioku.services
+    : [];
+  const missingServices = checkDependentServices(pkg);
+
+  return {
+    ok: true,
+    data: {
+      name,
+      target,
+      path: dir,
+      version: pkg?.version || "0.0.0",
+      description: pkg?.description || "",
+      hasGit: fs.existsSync(path.join(dir, ".git")),
+      isSystemPlugin: target === "plugin" ? isSystemPluginName(name) : false,
+      isSystemService: target === "service" ? isSystemServiceName(name) : false,
+      repository: repositoryFromPkg,
+      originUrl,
+      homepage: pkg?.homepage || "",
+      requiredServices,
+      missingServices,
+      help: pkg?.mioku?.help || null,
+      readme: readme?.content || "",
+      readmeFile: readme?.fileName || "",
+      updateState: updateInfo.state,
+      hasUpdates: updateInfo.hasUpdates,
+      behind: updateInfo.behind,
+      changelog: updateInfo.changelog,
+      updateError: updateInfo.error || "",
+    },
+  };
+}
+
+export async function changeManagedPackageRepo(
+  name: string,
+  target: ManagedTarget,
+  repoUrl: string,
+): Promise<Record<string, any>> {
+  if (!isValidRepoUrl(repoUrl)) {
+    throw new Error("仓库地址无效");
+  }
+
+  const dir = resolveManagedDir(target, name);
+  const nextUrl = repoUrl.trim();
+  const oldUrl = await getGitOriginUrl(dir);
+
+  const setRemote = await runCommand(
+    "git",
+    ["remote", "set-url", "origin", nextUrl],
+    dir,
+  );
+  if (setRemote.code !== 0) {
+    throw new Error(
+      `更新仓库地址失败: ${setRemote.stderr || setRemote.stdout}`,
+    );
+  }
+
+  const packagePath = path.join(dir, "package.json");
+  if (fs.existsSync(packagePath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+      if (typeof pkg.repository === "string") {
+        pkg.repository = nextUrl;
+      } else if (pkg.repository && typeof pkg.repository === "object") {
+        pkg.repository = { ...pkg.repository, url: nextUrl };
+      } else {
+        pkg.repository = nextUrl;
+      }
+      fs.writeFileSync(packagePath, JSON.stringify(pkg, null, 2), "utf-8");
+    } catch {
+      // ignore package.json update failure, git remote is the source of truth
+    }
+  }
+
+  managedPackageUpdateCache.delete(makeManagedUpdateCacheKey(target, name));
+
+  return {
+    ok: true,
+    oldUrl,
+    newUrl: nextUrl,
+  };
+}
+
+export async function updateAllManagedPackages(input: {
+  target: ManagedTarget;
+  packageManager?: PackageManager;
+}): Promise<Record<string, any>> {
+  const packages = listManagedPackages(input.target);
+  const results: Array<Record<string, any>> = [];
+
+  for (const item of packages) {
+    const updateInfo = await getManagedPackageUpdateInfo(item.path);
+    if (updateInfo.state === "no-git") {
+      results.push({
+        name: item.name,
+        ok: false,
+        skipped: true,
+        reason: "NOT_GIT_REPO",
+      });
+      continue;
+    }
+    if (!updateInfo.hasUpdates) {
+      results.push({
+        name: item.name,
+        ok: true,
+        skipped: true,
+        reason: updateInfo.state === "unknown" ? "CHECK_FAILED" : "UP_TO_DATE",
+        error: updateInfo.error || "",
+      });
+      continue;
+    }
+
+    try {
+      const updated = await updateManagedPackage({
+        name: item.name,
+        target: input.target,
+        packageManager: input.packageManager,
+      });
+      results.push({
+        name: item.name,
+        ok: true,
+        skipped: false,
+        ...updated,
+      });
+    } catch (error: any) {
+      results.push({
+        name: item.name,
+        ok: false,
+        skipped: false,
+        error: error?.message || "UPDATE_FAILED",
+      });
+    }
+  }
+
+  const updatedCount = results.filter(
+    (item) => item.ok && !item.skipped,
+  ).length;
+  const failedCount = results.filter(
+    (item) => !item.ok && !item.skipped,
+  ).length;
+  const skippedCount = results.filter((item) => item.skipped).length;
+
+  return {
+    ok: failedCount === 0,
+    restartRequired: updatedCount > 0,
+    updatedCount,
+    failedCount,
+    skippedCount,
+    results,
+  };
+}
+
+function pickWebUIDistAsset(
+  assets: WebUIReleaseAsset[],
+): WebUIReleaseAsset | null {
+  const zipAssets = assets.filter((asset) =>
+    /\.zip$/i.test(String(asset?.name || "")),
+  );
+  if (zipAssets.length === 0) return null;
+  const distAsset = zipAssets.find((asset) =>
+    /dist/i.test(String(asset?.name || "")),
+  );
+  return distAsset || zipAssets[0] || null;
+}
+
+async function fetchLatestWebUIUpdate(
+  force = false,
+): Promise<WebUIUpdateCheckResult> {
+  const now = Date.now();
+  if (
+    !force &&
+    webuiUpdateCache &&
+    now - webuiUpdateCache.checkedAt < WEBUI_UPDATE_CACHE_TTL_MS
+  ) {
+    return webuiUpdateCache;
+  }
+
+  if (!force && webuiUpdateCheckInFlight) {
+    return webuiUpdateCheckInFlight;
+  }
+
+  const job = (async () => {
+    const projectDir = resolveWebUIProjectDir();
+    const currentVersion = readInstalledWebUIVersion();
+    const pkg = readPackageJson(projectDir) || {};
+    const originUrl = (await getGitOriginUrl(projectDir)) || "";
+    const repoUrl = originUrl || getRepositoryFromPackage(pkg);
+    const repo = parseGitHubRepo(repoUrl);
+
+    const fallback: WebUIUpdateCheckResult = {
+      currentVersion,
+      latestVersion: currentVersion,
+      releaseTag: "",
+      releaseUrl: "",
+      sourceRepo: repo?.fullName || "",
+      hasUpdates: false,
+      canUpdate: false,
+      assetName: "",
+      assetUrl: "",
+      checkedAt: Date.now(),
+    };
+
+    if (!repo) {
+      return {
+        ...fallback,
+        error: "WebUI 仓库不是 GitHub，暂不支持自动检查更新",
+      };
+    }
+
+    const res = await fetch(
+      `https://api.github.com/repos/${repo.owner}/${repo.repo}/releases/latest`,
+      {
+        headers: {
+          Accept: "application/vnd.github+json",
+          "User-Agent": "mioku-webui-updater",
+        },
+      },
+    );
+
+    if (!res.ok) {
+      return {
+        ...fallback,
+        error: `查询 GitHub Release 失败: HTTP_${res.status}`,
+      };
+    }
+
+    const release = (await res.json().catch(() => ({}))) as any;
+    const releaseTag = String(release?.tag_name || release?.name || "").trim();
+    const latestVersion = normalizeVersionSpec(releaseTag || "unknown");
+    const assets = Array.isArray(release?.assets)
+      ? (release.assets as WebUIReleaseAsset[])
+      : [];
+    const distAsset = pickWebUIDistAsset(assets);
+    const hasUpdates =
+      latestVersion !== "unknown" &&
+      isVersionNewer(latestVersion, currentVersion);
+
+    return {
+      currentVersion,
+      latestVersion,
+      releaseTag,
+      releaseUrl: String(release?.html_url || ""),
+      sourceRepo: repo.fullName,
+      hasUpdates,
+      canUpdate: hasUpdates && Boolean(distAsset?.browser_download_url),
+      assetName: String(distAsset?.name || ""),
+      assetUrl: String(distAsset?.browser_download_url || ""),
+      checkedAt: Date.now(),
+      error:
+        hasUpdates && !distAsset
+          ? "已检测到新版本，但 Release 没有可用 dist 压缩包"
+          : "",
+    };
+  })();
+
+  webuiUpdateCheckInFlight = job;
+  try {
+    const result = await job;
+    webuiUpdateCache = result;
+    return result;
+  } finally {
+    webuiUpdateCheckInFlight = null;
+  }
+}
+
+export async function checkWebUIReleaseUpdate(
+  force = false,
+): Promise<Record<string, any>> {
+  return fetchLatestWebUIUpdate(force);
+}
+
+async function fetchLatestMiokuUpdate(
+  force = false,
+): Promise<MiokuUpdateCheckResult> {
+  const now = Date.now();
+  if (
+    !force &&
+    miokuUpdateCache &&
+    now - miokuUpdateCache.checkedAt < MIOKU_UPDATE_CACHE_TTL_MS
+  ) {
+    return miokuUpdateCache;
+  }
+
+  if (!force && miokuUpdateCheckInFlight) {
+    return miokuUpdateCheckInFlight;
+  }
+
+  const job = (async () => {
+    const cwd = process.cwd();
+    const rootPkg = readRootPackageJson() || {};
+    const currentVersion = normalizeVersionSpec(rootPkg?.version || "unknown");
+    const originUrl = (await getGitOriginUrl(cwd)) || "";
+    const repoUrl = originUrl || getRepositoryFromPackage(rootPkg);
+    const repo = parseGitHubRepo(repoUrl);
+    const { currentBranch, targetRef, targetBranch } =
+      await resolveMiokuTargetRef(cwd);
+
+    const fallback: MiokuUpdateCheckResult = {
+      currentVersion,
+      latestVersion: currentVersion,
+      sourceRepo: repo?.fullName || "",
+      currentBranch,
+      targetRef,
+      hasUpdates: false,
+      behind: 0,
+      changelog: [],
+      checkedAt: Date.now(),
+    };
+
+    if (!fs.existsSync(path.join(cwd, ".git"))) {
+      return {
+        ...fallback,
+        error: isContainerRuntime()
+          ? "当前 Docker 容器未挂载 .git 到 /app/.git，无法检查 Mioku 更新"
+          : "当前目录不是 Git 仓库，无法检查 Mioku 更新",
+      };
+    }
+
+    if (!repo) {
+      return {
+        ...fallback,
+        error: "Mioku 仓库不是 GitHub，暂不支持自动检查更新",
+      };
+    }
+
+    const fetchRes = await runCommand(
+      "git",
+      ["fetch", "origin", targetBranch],
+      cwd,
+    );
+
+    if (fetchRes.code !== 0) {
+      return {
+        ...fallback,
+        error: `git fetch 失败: ${fetchRes.stderr || fetchRes.stdout}`.trim(),
+      };
+    }
+
+    const compare = await runCommand(
+      "git",
+      ["rev-list", "--left-right", "--count", `HEAD...${targetRef}`],
+      cwd,
+    );
+
+    if (compare.code !== 0) {
+      return {
+        ...fallback,
+        error: `无法比较更新: ${compare.stderr || compare.stdout}`.trim(),
+      };
+    }
+
+    const parts = compare.stdout
+      .trim()
+      .split(/\s+/)
+      .map((item) => Number(item));
+    const behind = Number.isFinite(parts[1]) ? parts[1] : 0;
+    const changelogRes = await runCommand(
+      "git",
+      ["log", "--oneline", `HEAD..${targetRef}`, "-n", "30"],
+      cwd,
+    );
+
+    let latestVersion = currentVersion;
+    const remotePkg = await runCommand(
+      "git",
+      ["show", `${targetRef}:package.json`],
+      cwd,
+    );
+    if (remotePkg.code === 0) {
+      try {
+        const parsed = JSON.parse(remotePkg.stdout);
+        latestVersion = normalizeVersionSpec(parsed?.version || currentVersion);
+      } catch {
+        latestVersion = currentVersion;
+      }
+    }
+
+    return {
+      currentVersion,
+      latestVersion,
+      sourceRepo: repo.fullName,
+      currentBranch,
+      targetRef,
+      hasUpdates: behind > 0,
+      behind,
+      changelog: changelogRes.stdout.trim().split("\n").filter(Boolean),
+      checkedAt: Date.now(),
+      error: "",
+    };
+  })();
+
+  miokuUpdateCheckInFlight = job;
+  try {
+    const result = await job;
+    miokuUpdateCache = result;
+    return result;
+  } finally {
+    miokuUpdateCheckInFlight = null;
+  }
+}
+
+export async function checkMiokuReleaseUpdate(
+  force = false,
+): Promise<Record<string, any>> {
+  return fetchLatestMiokuUpdate(force);
+}
+
+export async function updateMiokuFromMain(): Promise<Record<string, any>> {
+  const cwd = process.cwd();
+  if (!fs.existsSync(path.join(cwd, ".git"))) {
+    throw new Error(
+      isContainerRuntime()
+        ? "当前 Docker 容器未挂载 .git 到 /app/.git，无法更新 Mioku"
+        : "当前目录不是 Git 仓库，无法更新 Mioku",
+    );
+  }
+
+  const { targetBranch } = await resolveMiokuTargetRef(cwd);
+  const before = await runCommand("git", ["show", "HEAD:package.json"], cwd);
+  const pull = await runCommand("git", ["pull", "origin", targetBranch], cwd);
+
+  if (pull.code !== 0) {
+    throw new Error(`git pull 失败: ${pull.stderr || pull.stdout}`);
+  }
+
+  const after = await runCommand("git", ["show", "HEAD:package.json"], cwd);
+  const changed = packageJsonChanged(before.stdout, after.stdout);
+
+  let reinstallOutput = "";
+  if (changed) {
+    const packageManager = packageManagerFromSettings();
+    const installCmd = getInstallCommand(packageManager);
+    const install = await runCommand(installCmd.cmd, installCmd.args, cwd);
+    if (install.code !== 0) {
+      throw new Error(`依赖安装失败: ${install.stderr || install.stdout}`);
+    }
+    reinstallOutput = install.stdout || install.stderr;
+  }
+
+  miokuUpdateCache = null;
+
+  const next = await fetchLatestMiokuUpdate(true);
+  return {
+    ok: true,
+    restartRequired: true,
+    packageJsonChanged: changed,
+    reinstallOutput,
+    currentVersion: next.currentVersion,
+    latestVersion: next.latestVersion,
+    hasUpdates: next.hasUpdates,
+  };
+}
+
+export async function updateWebUIDistFromRelease(): Promise<
+  Record<string, any>
+> {
+  if (webuiUpdatingInFlight) {
+    return webuiUpdatingInFlight;
+  }
+
+  const task = (async () => {
+    const check = await fetchLatestWebUIUpdate(true);
+    if (!check.hasUpdates) {
+      return {
+        ok: true,
+        updated: false,
+        message: "当前已是最新版本",
+        currentVersion: check.currentVersion,
+        latestVersion: check.latestVersion,
+      };
+    }
+
+    if (!check.assetUrl) {
+      throw new Error(
+        check.error || "没有找到可下载的 dist 压缩包，请检查 Release 资产",
+      );
+    }
+
+    const tempDir = path.join(
+      os.tmpdir(),
+      `mioku-webui-update-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    );
+    const zipPath = path.join(tempDir, check.assetName || "webui-dist.zip");
+    const unpackDir = path.join(tempDir, "unpack");
+
+    ensureDir(tempDir);
+    ensureDir(unpackDir);
+
+    let backupPath = "";
+    try {
+      const downloadRes = await fetch(check.assetUrl, {
+        headers: {
+          Accept: "application/octet-stream",
+          "User-Agent": "mioku-webui-updater",
+        },
+      });
+
+      if (!downloadRes.ok) {
+        throw new Error(`下载 dist 压缩包失败: HTTP_${downloadRes.status}`);
+      }
+
+      const buffer = Buffer.from(await downloadRes.arrayBuffer());
+      fs.writeFileSync(zipPath, buffer);
+
+      const unzip = await runCommand(
+        "unzip",
+        ["-oq", zipPath, "-d", unpackDir],
+        process.cwd(),
+      );
+      if (unzip.code !== 0) {
+        throw new Error(`解压失败: ${unzip.stderr || unzip.stdout}`);
+      }
+
+      const sourceDir = resolveDistSourceDir(unpackDir);
+      if (!sourceDir) {
+        throw new Error("压缩包内未找到可用的 WebUI dist 文件");
+      }
+
+      ensureDir(path.dirname(WEBUI_DIST));
+      const targetExisted = fs.existsSync(WEBUI_DIST);
+      if (targetExisted) {
+        backupPath = `${WEBUI_DIST}.backup.${Date.now()}`;
+        fs.renameSync(WEBUI_DIST, backupPath);
+      }
+
+      fs.mkdirSync(WEBUI_DIST, { recursive: true });
+      fs.cpSync(sourceDir, WEBUI_DIST, { recursive: true, force: true });
+
+      if (!hasUsableDistFiles(WEBUI_DIST)) {
+        throw new Error("更新后的 dist 无效，缺少 index.html");
+      }
+
+      fs.writeFileSync(
+        path.join(WEBUI_DIST, ".webui-version"),
+        `${check.latestVersion}\n`,
+        "utf-8",
+      );
+
+      if (backupPath && fs.existsSync(backupPath)) {
+        fs.rmSync(backupPath, { recursive: true, force: true });
+      }
+    } catch (error) {
+      if (backupPath && fs.existsSync(backupPath)) {
+        fs.rmSync(WEBUI_DIST, { recursive: true, force: true });
+        fs.renameSync(backupPath, WEBUI_DIST);
+      }
+      throw error;
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+
+    webuiUpdateCache = {
+      ...check,
+      checkedAt: Date.now(),
+      currentVersion: check.latestVersion,
+      hasUpdates: false,
+      canUpdate: false,
+      error: "",
+    };
+
+    return {
+      ok: true,
+      updated: true,
+      version: check.latestVersion,
+      assetName: check.assetName,
+      releaseUrl: check.releaseUrl,
+      restartRequired: false,
+    };
+  })().finally(() => {
+    webuiUpdatingInFlight = null;
+  });
+
+  webuiUpdatingInFlight = task;
+  return task;
+}
+
+function readPackageVersion(filePath: string): string {
+  try {
+    if (!fs.existsSync(filePath)) return "unknown";
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    return parsed?.version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+async function getSystemInformationSnapshot(): Promise<{
+  diskUsagePercent: number;
+  diskTotal: number;
+  diskUsed: number;
+  netRxPerSec: number;
+  netTxPerSec: number;
+}> {
+  try {
+    const [fsSize, netStats] = await Promise.all([
+      systemInfo.fsSize().catch(() => [] as any[]),
+      systemInfo.networkStats().catch(() => [] as any[]),
+    ]);
+
+    const disk = Array.isArray(fsSize) && fsSize.length > 0 ? fsSize[0] : null;
+    const diskTotal = Number(disk?.size || 0);
+    const diskUsed = Number(disk?.used || 0);
+    const diskUsagePercent =
+      diskTotal > 0
+        ? Number(((diskUsed / diskTotal) * 100).toFixed(1))
+        : Number(disk?.use || 0);
+
+    const networkList = Array.isArray(netStats) ? netStats : [];
+    const netRxPerSec = networkList.reduce(
+      (acc, item) => acc + Number(item?.rx_sec || 0),
+      0,
+    );
+    const netTxPerSec = networkList.reduce(
+      (acc, item) => acc + Number(item?.tx_sec || 0),
+      0,
+    );
+
+    return {
+      diskUsagePercent: Number.isFinite(diskUsagePercent)
+        ? diskUsagePercent
+        : 0,
+      diskTotal,
+      diskUsed,
+      netRxPerSec: Number.isFinite(netRxPerSec) ? netRxPerSec : 0,
+      netTxPerSec: Number.isFinite(netTxPerSec) ? netTxPerSec : 0,
+    };
+  } catch {
+    return {
+      diskUsagePercent: 0,
+      diskTotal: 0,
+      diskUsed: 0,
+      netRxPerSec: 0,
+      netTxPerSec: 0,
+    };
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function sampleCpuTimes() {
+  const cpus = os.cpus();
+  let idle = 0;
+  let total = 0;
+
+  for (const cpu of cpus) {
+    idle += cpu.times.idle;
+    total +=
+      cpu.times.user +
+      cpu.times.nice +
+      cpu.times.sys +
+      cpu.times.irq +
+      cpu.times.idle;
+  }
+
+  return { idle, total };
+}
+
+async function getCpuUsagePercent(): Promise<number> {
+  const start = sampleCpuTimes();
+  await sleep(180);
+  const end = sampleCpuTimes();
+  const idleDelta = end.idle - start.idle;
+  const totalDelta = end.total - start.total;
+  if (totalDelta <= 0) return 0;
+  return Number((((totalDelta - idleDelta) / totalDelta) * 100).toFixed(1));
+}
+
+function toHttpBaseUrl(bot: any): string {
+  const protocol = String(bot.options?.protocol || "ws");
+  const httpProtocol = protocol === "wss" ? "https" : "http";
+  const host = bot.options?.host || "127.0.0.1";
+  const port = bot.options?.port || 3001;
+  return `${httpProtocol}://${host}:${port}`;
+}
+
+async function fetchYiyan(): Promise<{ text: string }> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 4500);
+  try {
+    const res = await fetch("https://uapis.cn/api/v1/saying", {
+      method: "GET",
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      throw new Error(`HTTP_${res.status}`);
+    }
+    const data = (await res.json()) as { text?: string };
+    return { text: data?.text || "愿每一次启动都带来新的灵感。" };
+  } catch {
+    return { text: "愿每一次启动都带来新的灵感。" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function normalizeVersionSpec(input: string): string {
+  if (!input || input === "unknown") return "unknown";
+  const cleaned = input.trim().replace(/^[~^<>=\s]+/, "");
+  const matched = cleaned.match(/\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?/);
+  return matched?.[0] || cleaned;
+}
+
+async function getBotDetails(bot: any): Promise<Record<string, any>> {
+  const base = {
+    botId: bot?.bot_id || bot?.uin || 0,
+    qq: bot?.uin || bot?.user_id || 0,
+    nickname: bot?.nickname || bot?.name || "Unknown Bot",
+    avatar: `https://q1.qlogo.cn/g?b=qq&nk=${bot?.uin || bot?.user_id || 0}&s=160`,
+    online: true,
+    napcatVersion: bot?.app_version || "unknown",
+    napcatApiBase: toHttpBaseUrl(bot),
+    groupCount: 0,
+    friendCount: 0,
+    onlineDurationMs: 0,
+    statusText: "online",
+  };
+
+  try {
+    const [status, versionInfo, groups, friends] = await Promise.all([
+      bot.api("get_status").catch(() => null),
+      bot.api("get_version_info").catch(() => null),
+      bot.getGroupList().catch(() => []),
+      bot.getFriendList().catch(() => []),
+    ]);
+
+    const stat = status?.stat || null;
+    const startTs = Number(stat?.start_time || 0);
+    const onlineDurationMs =
+      startTs > 0 ? Math.max(0, Date.now() - startTs) : 0;
+    const onlineFromStatus =
+      typeof status?.online === "boolean" ? status.online : true;
+
+    return {
+      ...base,
+      online: onlineFromStatus,
+      napcatVersion: versionInfo?.app_version || base.napcatVersion,
+      groupCount: Array.isArray(groups) ? groups.length : 0,
+      friendCount: Array.isArray(friends) ? friends.length : 0,
+      onlineDurationMs,
+      statusText: onlineFromStatus ? "online" : "offline",
+    };
+  } catch (error: any) {
+    return {
+      ...base,
+      online: false,
+      statusText: "error",
+      error: error?.message || "NAPCAT_API_ERROR",
+    };
+  }
+}
+
+export async function getSystemOverview(): Promise<Record<string, any>> {
+  const rootPkg = readRootPackageJson();
+  const cpus = os.cpus();
+  const cpuModel = cpus[0]?.model || "unknown";
+  const cpuSpeedMHz = cpus[0]?.speed || 0;
+  const cpuCores = cpus.length;
+  const cpuUsagePercent = await getCpuUsagePercent();
+
+  const totalMemory = os.totalmem();
+  const freeMemory = os.freemem();
+  const usedMemory = Math.max(0, totalMemory - freeMemory);
+  const memoryUsagePercent =
+    totalMemory > 0 ? Number(((usedMemory / totalMemory) * 100).toFixed(1)) : 0;
+
+  const processMemory = process.memoryUsage();
+  const processMemoryPercent =
+    totalMemory > 0
+      ? Number(((processMemory.rss / totalMemory) * 100).toFixed(1))
+      : 0;
+  const siSnapshot = await getSystemInformationSnapshot();
+
+  const botInstances = Array.from(connectedBots.values());
+  const bots = await Promise.all(botInstances.map((bot) => getBotDetails(bot)));
+  const selectedBot = bots[0] || null;
+
+  return {
+    uptimeSeconds: process.uptime(),
+    bots,
+    selectedBot,
+    system: {
+      cpuModel,
+      cpuSpeedMHz,
+      cpuCores,
+      cpuUsagePercent,
+      memoryTotal: totalMemory,
+      memoryUsed: usedMemory,
+      memoryFree: freeMemory,
+      memoryUsagePercent,
+      processMemoryRss: processMemory.rss,
+      processMemoryHeapUsed: processMemory.heapUsed,
+      processMemoryPercent,
+      diskUsagePercent: siSnapshot.diskUsagePercent,
+      diskTotal: siSnapshot.diskTotal,
+      diskUsed: siSnapshot.diskUsed,
+      networkRxPerSec: siSnapshot.netRxPerSec,
+      networkTxPerSec: siSnapshot.netTxPerSec,
+      osType: os.type(),
+      osPlatform: os.platform(),
+      osRelease: os.release(),
+      osVersion: typeof os.version === "function" ? os.version() : "unknown",
+      nodeVersion: process.version,
+    },
+    versions: {
+      mioki: normalizeVersionSpec(
+        rootPkg?.dependencies?.mioki ||
+          rootPkg?.devDependencies?.mioki ||
+          "unknown",
+      ),
+      mioku: rootPkg?.version || "unknown",
+      webui: readInstalledWebUIVersion(),
+      webuiService: readPackageVersion(
+        path.join(process.cwd(), "src", "services", "webui", "package.json"),
+      ),
+    },
+    plugins: listManagedPackages("plugin"),
+    services: listManagedPackages("service"),
+  };
+}
+
+export async function getSaying(): Promise<{ text: string }> {
+  return fetchYiyan();
+}
+
+export function getChatConfig(fileName: string): any {
+  const filePath = path.join(CHAT_CONFIG_DIR, fileName);
+  return readJsonFile(filePath, {});
+}
+
+export function updateChatConfig(fileName: string, data: any): any {
+  const filePath = path.join(CHAT_CONFIG_DIR, fileName);
+  writeJsonFile(filePath, data);
+  return data;
+}
+
+export interface MiokuConfig {
+  owners: number[];
+  admins: number[];
+  napcat: Array<{
+    name: string;
+    protocol: string;
+    port: number;
+    host: string;
+    token: string;
+  }>;
+  plugins: string[];
+  boot: BootSystemConfig;
+}
+
+export function getMiokuConfig(): MiokuConfig {
+  const localConfig = readJsonFile<any>(LOCAL_CONFIG_PATH, { mioki: {} });
+  const rootPkg = readRootPackageJson();
+
+  const miokiConfig = localConfig?.mioki || rootPkg?.mioki || {};
+
+  return {
+    owners: Array.isArray(miokiConfig.owners) ? miokiConfig.owners : [],
+    admins: Array.isArray(miokiConfig.admins) ? miokiConfig.admins : [],
+    napcat: Array.isArray(miokiConfig.napcat) ? miokiConfig.napcat : [],
+    plugins: Array.isArray(miokiConfig.plugins) ? miokiConfig.plugins : [],
+    boot: getBootSystemConfig(),
+  };
+}
+
+export function updateMiokuConfig(config: Partial<MiokuConfig>): MiokuConfig {
+  const current = getMiokuConfig();
+  const updated: MiokuConfig = {
+    owners: Array.isArray(config.owners) ? config.owners : current.owners,
+    admins: Array.isArray(config.admins) ? config.admins : current.admins,
+    napcat: Array.isArray(config.napcat) ? config.napcat : current.napcat,
+    plugins: Array.isArray(config.plugins) ? config.plugins : current.plugins,
+    boot: config.boot ? updateBootSystemConfig(config.boot) : current.boot,
+  };
+
+  const localConfig = readJsonFile<any>(LOCAL_CONFIG_PATH, { mioki: {} });
+  localConfig.mioki = {
+    ...localConfig.mioki,
+    ...updated,
+  };
+  writeJsonFile(LOCAL_CONFIG_PATH, localConfig);
+
+  const rootPkg = readRootPackageJson();
+  if (rootPkg.mioki) {
+    rootPkg.mioki.owners = updated.owners;
+    rootPkg.mioki.admins = updated.admins;
+    rootPkg.mioki.napcat = updated.napcat;
+    rootPkg.mioki.plugins = updated.plugins;
+    writeRootPackageJson(rootPkg);
+  }
+
+  return updated;
+}
+
+export function getAvailablePlugins(): string[] {
+  ensureDir(PLUGINS_DIR);
+  return fs
+    .readdirSync(PLUGINS_DIR, { withFileTypes: true })
+    .filter(
+      (e) =>
+        e.isDirectory() && !e.name.startsWith("_") && !e.name.startsWith("."),
+    )
+    .map((e) => e.name);
+}