mingdao-harness 0.1.54

package/src/session.js

@@ -0,0 +1,131 @@
+// 会话持久化：JSONL 格式存放在 <mingdao-home>/sessions/。
+// 每轮自动追加；mingdao --continue 载入最近一次会话。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function listSessions(home) {
+  const dir = path.join(home, 'sessions');
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith('.jsonl'))
+      .map((f) => {
+        const file = path.join(dir, f);
+        return { file, name: f, mtime: fs.statSync(file).mtimeMs };
+      })
+      .sort((a, b) => b.mtime - a.mtime);
+  } catch {
+    return [];
+  }
+}
+
+export function latestSession(home) {
+  return listSessions(home)[0] || null;
+}
+
+export function createSession(home) {
+  const dir = path.join(home, 'sessions');
+  fs.mkdirSync(dir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const rand = Math.random().toString(36).slice(2, 6);
+  const file = path.join(dir, `${stamp}-${rand}.jsonl`);
+  return { file, name: path.basename(file) };
+}
+
+export function appendMessages(file, messages) {
+  if (!messages?.length) return;
+  const lines = messages.map((m) => JSON.stringify(m)).join('\n') + '\n';
+  fs.appendFileSync(file, lines);
+}
+
+// 整文件原子重写：自动压缩后把会话文件同步为压缩形态（否则每次加载历史都会重新触发压缩）
+export function rewriteSession(file, messages) {
+  const lines = messages.map((m) => JSON.stringify(m)).join('\n');
+  const tmp = file + '.tmp';
+  fs.writeFileSync(tmp, lines + (lines ? '\n' : ''), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+export function loadSession(file) {
+  const raw = fs.readFileSync(file, 'utf8');
+  const messages = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const m = JSON.parse(line);
+      if (m && typeof m === 'object' && ['system', 'user', 'assistant', 'tool'].includes(m.role)) {
+        messages.push(m);
+      }
+    } catch {}
+  }
+  return { file, messages };
+}
+
+// 会话预览：第一条用户消息（用于会话选择器）
+export function sessionPreview(file) {
+  try {
+    const raw = fs.readFileSync(file, 'utf8');
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      const m = JSON.parse(line);
+      if (!m || typeof m !== 'object') continue; // 审计 B4：null/非对象行跳过而非中断预览
+      if (m.role === 'user') {
+        const s = String(m.content).split('\n')[0].trim().slice(0, 60);
+        return s || '(空消息)';
+      }
+    }
+    return '(无内容)';
+  } catch {
+    return '(无法读取)';
+  }
+}
+
+export function relativeTime(mtime) {
+  const diff = Date.now() - mtime;
+  if (diff < 60000) return '刚刚';
+  if (diff < 3600000) return `${Math.floor(diff / 60000)} 分钟前`;
+  if (diff < 86400000) return `${Math.floor(diff / 3600000)} 小时前`;
+  return `${Math.floor(diff / 86400000)} 天前`;
+}
+
+// 全文检索历史会话（P3-2 索引化）：增量词表倒排 + AND 匹配（中文 bigram），
+// 只对命中的少数文件读原文生成片段；未命中/无关键词时回退列表。
+import { syncSessionIndex, tokenize, extractSessionText } from './session-index.js';
+
+export function searchSessions(home, keyword, { limit = 20 } = {}) {
+  const kw = String(keyword ?? '').trim();
+  if (!kw) return listSessions(home).slice(0, limit);
+  const sessions = listSessions(home);
+  const idx = syncSessionIndex(home, sessions);
+  const qTerms = [...tokenize(kw).keys()];
+  if (!qTerms.length) return [];
+  const lower = kw.toLowerCase();
+  const out = [];
+  for (const s of sessions) {
+    if (out.length >= limit) break;
+    const e = idx.files[s.name];
+    if (!e?.terms) continue;
+    let hit = true;
+    for (const t of qTerms) {
+      if (!e.terms[t]) {
+        hit = false;
+        break;
+      }
+    }
+    if (!hit) continue;
+    // 命中（数量受 limit 约束）：读原文生成干净片段
+    let snippet = '';
+    try {
+      const text = extractSessionText(s.file);
+      const at = text.toLowerCase().indexOf(lower);
+      if (at !== -1) {
+        snippet = `…${text.slice(Math.max(0, at - 30), at + kw.length + 50).replace(/\s+/g, ' ').trim()}…`;
+      } else {
+        snippet = `…${text.slice(0, 80).replace(/\s+/g, ' ').trim()}…`;
+      }
+    } catch {}
+    out.push({ ...s, snippet });
+  }
+  return out;
+}

package/src/skill-lib.js

@@ -0,0 +1,350 @@
+// 技能库（借鉴 WorkBuddy 技能市场「搜索 + 一键安装」的思路）：
+//  - 内置技能库 <安装包>/skills-lib/：预置常用技能，按需安装，不默认注入系统提示
+//  - 安装来源四选一（自动识别）：
+//      · 库名      → 从内置库复制（mingdao skill install sql）
+//      · 本地目录   → 目录内含 SKILL.md 即整体复制
+//      · 远程 URL   → http(s) 下载单个 SKILL.md（.md 结尾）
+//      · git 仓库   → git clone --depth 1 后扫描含 SKILL.md 的目录
+//  - 统一安装到用户级 <home>/skills/<name>/：可编辑、可删除、同名覆盖内置（用户级优先级最高）
+//  - 每个技能写 .mingdao-source.json 记录来源，供卸载 / 重新安装（update）使用
+//  - 安装后自动进入系统提示技能清单，Agent 按需用 skill 工具加载全文（渐进式披露）
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { mingdaoHome, ensureHome } from './config.js';
+
+const LIB_DIR = fileURLToPath(new URL('../skills-lib', import.meta.url));
+
+// ---------- 完整性（P3-3）：技能目录联合哈希 ----------
+// 对目录内全部文件（排除 .mingdao-source.json 自身）按相对路径排序，
+// 逐文件 sha256 后拼成 "rel:hash\n" 再取一次 sha256，作为目录内容指纹。
+export function skillDirHash(dir) {
+  const out = [];
+  const walk = (d, base) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = path.join(d, e.name);
+      const rel = path.join(base, e.name).split(path.sep).join('/');
+      if (rel === '.mingdao-source.json') continue;
+      if (e.isDirectory()) walk(full, rel);
+      else if (e.isFile()) out.push([rel, crypto.createHash('sha256').update(fs.readFileSync(full)).digest('hex')]);
+    }
+  };
+  walk(dir, '');
+  out.sort((a, b) => a[0].localeCompare(b[0]));
+  return crypto
+    .createHash('sha256')
+    .update(out.map(([rel, h]) => `${rel}:${h}`).join('\n'))
+    .digest('hex');
+}
+
+export function readSourceMeta(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, '.mingdao-source.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeSourceMeta(dir, meta) {
+  fs.writeFileSync(path.join(dir, '.mingdao-source.json'), JSON.stringify(meta, null, 2) + '\n', { mode: 0o600 });
+}
+
+// 显式信任当前内容（用户改过 registry/library 安装的技能后重新记录指纹）
+export function trustSkill(name) {
+  const target = path.join(userSkillsDir(), name);
+  const meta = readSourceMeta(target);
+  if (!meta) return { error: `技能 ${name} 没有来源记录（无需 trust）` };
+  meta.sha256 = skillDirHash(target);
+  meta.trustedAt = Date.now();
+  writeSourceMeta(target, meta);
+  return { ok: true, name, sha256: meta.sha256.slice(0, 16) };
+}
+
+export function skillLibDir() {
+  return LIB_DIR;
+}
+
+export function userSkillsDir() {
+  return path.join(mingdaoHome(), 'skills');
+}
+
+// 从技能目录读取 name / description（frontmatter 优先，回退标题/目录名）
+function readSkillMeta(dir) {
+  try {
+    const text = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8');
+    const fm = text.match(/^---\n([\s\S]*?)\n---/);
+    let name = '';
+    let description = '';
+    if (fm) {
+      name = fm[1].match(/^name:\s*(.+)$/m)?.[1]?.trim() || '';
+      description = fm[1].match(/^description:\s*(.+)$/m)?.[1]?.trim() || '';
+    }
+    if (!name) name = path.basename(dir);
+    if (!description) description = text.match(/^#\s+(.+)$/m)?.[1]?.trim() || '';
+    return { name, description };
+  } catch {
+    return null;
+  }
+}
+
+export function installedUserSkillNames() {
+  const out = new Set();
+  let entries;
+  try {
+    entries = fs.readdirSync(userSkillsDir(), { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    try {
+      if (fs.statSync(path.join(userSkillsDir(), e.name, 'SKILL.md')).isFile()) out.add(e.name);
+    } catch {}
+  }
+  return out;
+}
+
+export function libraryList() {
+  const installed = installedUserSkillNames();
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(LIB_DIR, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const meta = readSkillMeta(path.join(LIB_DIR, e.name));
+    if (!meta) continue;
+    out.push({ ...meta, dir: path.join(LIB_DIR, e.name), installed: installed.has(meta.name) });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function searchLibrary(kw) {
+  const k = String(kw || '').trim().toLowerCase();
+  return libraryList().filter(
+    (s) => !k || s.name.toLowerCase().includes(k) || (s.description || '').toLowerCase().includes(k)
+  );
+}
+
+// 安装前 dry-run 校验 SKILL.md 格式（借鉴 npm 打包前的格式检查思路）：
+//  - 必须含合法 frontmatter（--- 起止）
+//  - name：字母/数字/连字符/点/下划线，1–64 位
+//  - description：非空且 ≤ 200 字
+// 校验失败返回具体错误，绝不装入技能目录。
+export function validateSkillMarkdown(text, hint) {
+  const src = hint ? `（${hint}）` : '';
+  if (!text || !String(text).trim()) return { error: `SKILL.md 为空${src}` };
+  const fm = String(text).match(/^---\s*\n([\s\S]*?)\n---\s*\n?/);
+  if (!fm) return { error: `缺少 frontmatter（应以 --- 开头并闭合）${src}` };
+  const name = fm[1].match(/^name:\s*(.+)$/m)?.[1]?.trim() || '';
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(name)) {
+    return { error: `frontmatter.name 非法：${name || '（缺失）'}（允许字母/数字/点/连字符/下划线，1–64 位）${src}` };
+  }
+  const desc = fm[1].match(/^description:\s*(.+)$/m)?.[1]?.trim() || '';
+  if (!desc) return { error: `frontmatter.description 缺失或为空${src}` };
+  if (desc.length > 200) return { error: `frontmatter.description 超过 200 字（当前 ${desc.length}）${src}` };
+  return { ok: true, name, description: desc };
+}
+
+export function validateSkillDir(dir, hint) {
+  const skillMd = path.join(dir, 'SKILL.md');
+  let text;
+  try {
+    text = fs.readFileSync(skillMd, 'utf8');
+  } catch {
+    return { error: `未找到 SKILL.md：${skillMd}` };
+  }
+  return validateSkillMarkdown(text, hint);
+}
+
+function copySkillIntoUser(dir, name, source, extra) {
+  ensureHome();
+  const target = path.join(userSkillsDir(), name);
+  if (path.resolve(dir) === path.resolve(target)) {
+    // 源目录就是用户级安装位置：视为已安装，保持现状
+    return { name, dir: target };
+  }
+  const check = validateSkillDir(dir, name);
+  if (check.error) return { error: check.error };
+  fs.rmSync(target, { recursive: true, force: true });
+  fs.mkdirSync(target, { recursive: true });
+  fs.cpSync(dir, target, { recursive: true });
+  // 安装即记录内容指纹（P3-3）：加载时校验，被篡改则拒绝加载
+  const meta = { source, installedAt: Date.now(), sha256: skillDirHash(target), ...(extra || {}) };
+  fs.writeFileSync(path.join(target, '.mingdao-source.json'), JSON.stringify(meta, null, 2) + '\n');
+  return { name, dir: target };
+}
+
+export function installFromLibrary(name) {
+  const found = libraryList().find((s) => s.name === name);
+  if (!found) return { error: `技能库中没有 ${name}（mingdao skill search 查看全部）` };
+  return copySkillIntoUser(found.dir, found.name, 'library', {});
+}
+
+export function installFromDir(dir) {
+  const abs = path.resolve(dir);
+  if (!fs.existsSync(path.join(abs, 'SKILL.md'))) {
+    return { error: `目录内未找到 SKILL.md：${abs}` };
+  }
+  const meta = readSkillMeta(abs);
+  if (!meta) return { error: `无法解析 SKILL.md：${abs}` };
+  return copySkillIntoUser(abs, meta.name, 'dir', { from: abs });
+}
+
+export async function installFromUrl(url) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    return { error: 'URL 无效' };
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    return { error: '仅支持 http/https URL（下载单个 SKILL.md）' };
+  }
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 30000);
+  let text;
+  try {
+    const res = await fetch(u, { signal: ctrl.signal, redirect: 'follow' });
+    if (!res.ok) return { error: `下载失败：HTTP ${res.status}` };
+    text = await res.text();
+    if (text.length > 512 * 1024) return { error: 'SKILL.md 超过 512KB 上限' };
+  } catch (e) {
+    return { error: `下载失败：${e.name === 'AbortError' ? '30 秒超时' : e.message}` };
+  } finally {
+    clearTimeout(timer);
+  }
+  const head = text.trim();
+  if (!head.startsWith('---') && !head.startsWith('# ')) {
+    return { error: '内容不是合法的 SKILL.md（需 frontmatter 或 # 标题开头）' };
+  }
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'mingdao-skill-'));
+  fs.writeFileSync(path.join(tmp, 'SKILL.md'), text);
+  const check = validateSkillDir(tmp, url);
+  if (check.error) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    return { error: check.error };
+  }
+  const meta = readSkillMeta(tmp);
+  const r = copySkillIntoUser(tmp, meta.name, 'url', { url });
+  fs.rmSync(tmp, { recursive: true, force: true });
+  return r;
+}
+
+export function installFromGit(gitUrl) {
+  if (typeof gitUrl !== 'string' || gitUrl.trim().startsWith('-')) {
+    return { error: 'git 地址不能以 - 开头（防选项注入）' };
+  }
+  const check = spawnSync('git', ['--version'], { stdio: 'ignore' });
+  if (check.error || check.status !== 0) {
+    return { error: '未找到 git（git 仓库安装需要系统 git，可用 URL 安装单文件技能）' };
+  }
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'mingdao-skill-git-'));
+  // -- 分隔符：gitUrl 即使形似选项也只按路径处理
+  const r = spawnSync('git', ['clone', '--depth', '1', '--', gitUrl, tmp], { stdio: 'ignore', timeout: 120000 });
+  if (r.error || r.status !== 0) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    return { error: `git clone 失败：${r.error?.message || `退出码 ${r.status}`}` };
+  }
+  const found = [];
+  const stack = [tmp];
+  while (stack.length && found.length < 20) {
+    const dir = stack.pop();
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    if (entries.some((e) => e.isFile() && e.name === 'SKILL.md')) {
+      found.push(dir);
+      continue;
+    }
+    for (const e of entries) {
+      if (e.isDirectory() && e.name !== '.git') stack.push(path.join(dir, e.name));
+    }
+  }
+  if (!found.length) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    return { error: '仓库中未找到含 SKILL.md 的技能目录' };
+  }
+  ensureHome();
+  const installed = [];
+  const skipped = [];
+  for (const d of found) {
+    const meta = readSkillMeta(d);
+    const r = copySkillIntoUser(d, meta.name, 'git', { url: gitUrl });
+    if (r.error) skipped.push(`${meta.name}：${r.error}`);
+    else installed.push(r);
+  }
+  fs.rmSync(tmp, { recursive: true, force: true });
+  if (!installed.length) {
+    return { error: `仓库中的技能均未通过校验${skipped.length ? '（' + skipped.join('；') + '）' : ''}` };
+  }
+  return { names: installed.map((i) => i.name), dirs: installed.map((i) => i.dir), skipped };
+}
+
+export function uninstallSkill(name) {
+  const key = String(name).trim();
+  // '.'/'..' 会拼出上级目录，必须硬拒绝（正则 [A-Za-z0-9_.-]+ 会放行纯点号名）
+  if (key === '.' || key === '..') return { error: `技能名非法：${key}` };
+  const target = path.join(userSkillsDir(), key);
+  if (!/^[A-Za-z0-9_.-]+$/.test(key) || !fs.existsSync(path.join(target, 'SKILL.md'))) {
+    return { error: `用户级未安装技能 ${name}（内置技能不可卸载，可同名覆盖）` };
+  }
+  fs.rmSync(target, { recursive: true, force: true });
+  return { name: String(name).trim() };
+}
+
+// 按元数据来源重新安装（库：重新复制；url：重新下载；git：重新克隆）
+export async function reinstallSkill(name) {
+  const target = path.join(userSkillsDir(), name);
+  let meta = {};
+  try {
+    meta = JSON.parse(fs.readFileSync(path.join(target, '.mingdao-source.json'), 'utf8'));
+  } catch {
+    return { error: `未找到安装元数据（${name} 可能是手动创建或内置技能）` };
+  }
+  if (meta.source === 'library') return installFromLibrary(name);
+  if (meta.source === 'url') return installFromUrl(meta.url);
+  if (meta.source === 'git') return installFromGit(meta.url);
+  if (meta.source === 'dir') return installFromDir(meta.from);
+  if (meta.source === 'registry') {
+    const { installFromRegistry } = await import('./skill-registry.js');
+    return installFromRegistry(name);
+  }
+  return { error: `未知来源：${meta.source}` };
+}
+
+// 统一入口：自动识别 库名 | 本地目录 | SKILL.md URL | git 仓库
+export async function installSkill(arg) {
+  const a = String(arg || '').trim();
+  if (!a) return { error: '缺少参数：mingdao skill install <库名|目录|SKILL.md URL|git 仓库地址>' };
+  const libHit = libraryList().find((s) => s.name === a);
+  if (libHit) return installFromLibrary(a);
+  if (fs.existsSync(path.resolve(a))) return installFromDir(a);
+  if (/^https?:\/\//i.test(a)) {
+    if (/\.md(#.*)?$/i.test(a.split('?')[0])) return installFromUrl(a);
+    return installFromGit(a);
+  }
+  if (/^git@/.test(a)) return installFromGit(a);
+  if (/^[A-Za-z0-9_.-]+$/.test(a)) {
+    // 本地库没有：回退线上 registry（离线时报错并给出提示）
+    const { installFromRegistry } = await import('./skill-registry.js');
+    return installFromRegistry(a);
+  }
+  return { error: `无法识别安装来源：${a}（支持：技能库名 / 本地目录 / SKILL.md 的 http(s) URL / git 仓库地址）` };
+}

package/src/skill-registry.js

@@ -0,0 +1,165 @@
+// 技能库线上 registry 客户端（零依赖，纯 fetch + 本地缓存）：
+//  - 默认 registry：MingDao-Harness 仓库 registry/index.json（github/gitee/gitcode 三镜像自动回退）
+//  - 自建 registry：设置环境变量 MINGDAO_REGISTRY_URL 指向自己的 index.json（企业内网可用）
+//  - 本地缓存 <home>/skill-registry-cache.json，TTL 1 小时（force 可强制刷新）
+//  - 安装：按索引逐文件下载 → dry-run 校验 frontmatter → 写入用户级技能目录
+//    （来源元数据 source=registry，mingdao skill update 可重装）
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { mingdaoHome, ensureHome } from './config.js';
+import { userSkillsDir, validateSkillDir, installedUserSkillNames, skillDirHash, writeSourceMeta } from './skill-lib.js';
+
+const DEFAULT_HOSTS = [
+  'https://raw.githubusercontent.com/MingDaoTCM/MingDao-Harness/main',
+  'https://gitee.com/MingDaoTCM/MingDao-harness/raw/main',
+  'https://gitcode.com/MingDaoTCM/MingDao-Harness/raw/main',
+];
+
+const TTL_MS = 60 * 60 * 1000;
+const MAX_FILE = 512 * 1024;
+
+function registryBase() {
+  const env = process.env.MINGDAO_REGISTRY_URL;
+  if (env) {
+    const u = String(env).replace(/\/index\.json$/, '').replace(/\/+$/, '');
+    return { hosts: [u], isCustom: true };
+  }
+  return { hosts: DEFAULT_HOSTS, isCustom: false };
+}
+
+function cacheFile() {
+  return path.join(mingdaoHome(), 'skill-registry-cache.json');
+}
+
+function loadCache() {
+  try {
+    return JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function saveCache(data, host) {
+  try {
+    ensureHome();
+    fs.writeFileSync(cacheFile(), JSON.stringify({ fetchedAt: Date.now(), host, data }, null, 2) + '\n', { mode: 0o600 });
+  } catch {}
+}
+
+async function fetchText(url, timeoutMs = 20000, maxBytes = 2 * 1024 * 1024) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal, redirect: 'follow' });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    // Content-Length 预检：超限直接拒绝，不再全量下载进内存
+    const len = Number(res.headers.get('content-length'));
+    if (Number.isFinite(len) && len > maxBytes) throw new Error('响应超过大小上限');
+    const text = await res.text();
+    if (text.length > maxBytes) throw new Error('响应超过大小上限');
+    return text;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// 取远端索引（缓存优先；force 强制刷新；allowNetwork=false 时只读缓存，用于 WebUI 常规加载避免阻塞）
+export async function fetchRegistryIndex({ force = false, allowNetwork = true } = {}) {
+  const cached = loadCache();
+  const fresh = cached && Date.now() - cached.fetchedAt < TTL_MS;
+  if (!force && (fresh || !allowNetwork)) {
+    if (cached?.data?.skills) return { data: cached.data, host: cached.host, fromCache: true, stale: !fresh };
+    if (!allowNetwork) {
+      return { error: '尚无线上技能库缓存（点击「刷新线上」拉取，或设置 MINGDAO_REGISTRY_URL 指向自建 registry）' };
+    }
+  }
+  const { hosts } = registryBase();
+  let lastErr = null;
+  for (const host of hosts) {
+    try {
+      const text = await fetchText(`${host}/registry/index.json`, 8000);
+      const data = JSON.parse(text);
+      if (!Array.isArray(data.skills)) throw new Error('索引缺少 skills 数组');
+      saveCache(data, host);
+      return { data, host, fromCache: false };
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  // 网络失败时回退旧缓存（过期也可用）
+  if (cached?.data?.skills) return { data: cached.data, host: cached.host, fromCache: true, stale: true };
+  return { error: `无法获取线上技能库：${lastErr?.message || '网络不可达'}（可用 MINGDAO_REGISTRY_URL 指向自建 registry）` };
+}
+
+// 远端搜索（合并展示：name/description/source/installed）
+export async function searchRegistry(kw, { force = false, allowNetwork = true } = {}) {
+  const r = await fetchRegistryIndex({ force, allowNetwork });
+  if (r.error) return { error: r.error };
+  const k = String(kw || '').trim().toLowerCase();
+  const installed = installedUserSkillNames();
+  const skills = r.data.skills
+    .filter((s) => !k || s.name.toLowerCase().includes(k) || (s.description || '').toLowerCase().includes(k))
+    .map((s) => ({ name: s.name, description: s.description, source: 'registry', installed: installed.has(s.name) }));
+  return { skills, host: r.host, updatedAt: r.data.updatedAt, fromCache: r.fromCache, stale: r.stale || false };
+}
+
+// 按索引安装（逐文件下载 + dry-run 校验）
+export async function installFromRegistry(name) {
+  const r = await fetchRegistryIndex();
+  if (r.error) return { error: r.error };
+  const entry = r.data.skills.find((s) => s.name === name);
+  if (!entry) return { error: `线上技能库中没有 ${name}（mingdao skill search 查看）` };
+  if (!Array.isArray(entry.files) || !entry.files.length) return { error: `技能 ${name} 的索引缺少文件清单` };
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'mingdao-reg-'));
+  try {
+    let verified = false; // 是否至少一个文件做了 sha256 校验（索引声明了哈希才校验）
+    for (const f of entry.files) {
+      const rel = String(f.path || '').replace(/\\/g, '/');
+      if (!rel || rel.includes('..') || rel.startsWith('/')) {
+        return { error: `技能 ${name} 的文件路径非法：${f.path}` };
+      }
+      const dest = path.join(tmp, rel);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      let text;
+      try {
+        text = await fetchText(`${r.host}/skills-lib/${encodeURI(name)}/${rel.split('/').map(encodeURIComponent).join('/')}`, 30000, MAX_FILE);
+      } catch (e) {
+        return { error: `下载 ${name}/${rel} 失败：${e.message}` };
+      }
+      if (text.length > MAX_FILE) return { error: `${name}/${rel} 超过 512KB 上限` };
+      // 完整性校验（P3-3）：索引声明 sha256 时逐文件比对，不符即拒绝安装（供应链防护）
+      if (f.sha256 && typeof f.sha256 === 'string') {
+        const got = crypto.createHash('sha256').update(text).digest('hex');
+        if (got !== f.sha256.toLowerCase()) {
+          return { error: `完整性校验失败：${name}/${rel} 与 registry 声明的 sha256 不符（文件可能被篡改或索引过期），已拒绝安装` };
+        }
+        verified = true;
+      }
+      fs.writeFileSync(dest, text);
+    }
+    const check = validateSkillDir(tmp, name);
+    if (check.error) return { error: check.error };
+    const target = path.join(userSkillsDir(), name);
+    if (path.resolve(tmp) !== path.resolve(target)) {
+      ensureHome();
+      fs.rmSync(target, { recursive: true, force: true });
+      fs.mkdirSync(target, { recursive: true });
+      fs.cpSync(tmp, target, { recursive: true });
+    }
+    writeSourceMeta(target, {
+      source: 'registry',
+      installedAt: Date.now(),
+      host: r.host,
+      name,
+      sha256: skillDirHash(target), // 安装即记录指纹：加载时校验防本地篡改
+      verified: Boolean(verified),
+    });
+    return { name, dir: target, host: r.host, verified: Boolean(verified) };
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}