@yottameta/yotta-skills-plugin 0.28.3 → 0.29.0

package/skills/yotta-skills/lib/hub-view-server.js

@@ -33,6 +33,8 @@ const routeDynamicLib = require('./route-dynamic');
 const providerLib = require('./provider');
 const usageLib = require('./usage-journal');
 const cliHelpLib = require('./cli-help');
+const hostsRegistryLib = require('./hosts-registry');
+const hostPurgeLib = require('./host-purge');
 
 const DEFAULT_HOST = '127.0.0.1';
 const DEFAULT_PORT = 8789;
@@ -42,7 +44,7 @@ const DEFAULT_LIMIT = 100;
 const MAX_LIMIT = 500;
 const TOKEN_HEADER = 'x-yotta-view-token';
 const TOKEN_PLACEHOLDER = '__YOTTA_VIEW_TOKEN__';
-const CONFIRM = { unlink: 'unlink', rollback: 'rollback', remove: 'remove' };
+const CONFIRM = { unlink: 'unlink', rollback: 'rollback', remove: 'remove', purge: 'purge' };
 const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
 
 function nowIso() {
@@ -219,6 +221,14 @@ function hostsPayload(ctx) {
       installedMarks: found.installed.length,
       links: links.length,
       brokenLinks: links.filter((link) => link.status !== 'ok').length,
+      // 0.29.0 F3：宿主生命周期状态细分（面板分组 / 筛选）。
+      states: {
+        available: hosts.filter((host) => host.state === 'available').length,
+        orphan: hosts.filter((host) => host.state === 'orphan').length,
+        missing: hosts.filter((host) => host.state === 'missing').length,
+        markerOnly: hosts.filter((host) => host.state === 'marker-only').length,
+        ignored: hosts.filter((host) => host.state === 'ignored').length,
+      },
     },
   };
 }
@@ -525,6 +535,74 @@ function writeRollback(ctx, body) {
   return { code: result.error ? (result.code || 400) : 200, payload: result };
 }
 
+// ── 宿主注册与残留清理（0.29.0 F2/F3） ─────────────────────────────────────
+function auditViewHostEvent(ctx, entry) {
+  try {
+    if (fs.existsSync(ctx.hubDir)) hubLib.appendAudit(ctx.hubDir, entry);
+  } catch (_) { /* 审计失败不阻断主流程 */ }
+}
+
+function writeHostAdd(ctx, body) {
+  const dir = String(body.dir || '').trim();
+  if (!dir) return { code: 400, payload: { error: '缺少目录。' } };
+  const label = String(body.label || '').trim();
+  const result = hostsRegistryLib.addHost(
+    { homeDir: ctx.homeDir, env: ctx.env },
+    { dir, label: label || undefined },
+  );
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  auditViewHostEvent(ctx, {
+    event: 'hosts.add',
+    dir: result.entry.dir,
+    label: result.entry.label,
+    agentId: result.entry.agentId,
+    via: 'view',
+  });
+  return { code: 200, payload: { action: 'hosts.add', entry: result.entry } };
+}
+
+function writeHostRemove(ctx, body) {
+  const dir = String(body.dir || '').trim();
+  if (!dir) return { code: 400, payload: { error: '缺少目录。' } };
+  const result = hostsRegistryLib.removeHost({ homeDir: ctx.homeDir, env: ctx.env }, { dir });
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  auditViewHostEvent(ctx, {
+    event: 'hosts.remove',
+    dir: result.removed.dir,
+    label: result.removed.label,
+    agentId: result.removed.agentId,
+    via: 'view',
+  });
+  return { code: 200, payload: { action: 'hosts.remove', removed: result.removed } };
+}
+
+function writeHostPurge(ctx, body) {
+  if (String(body.confirm || '') !== CONFIRM.purge) {
+    return { code: 400, payload: { error: '破坏性操作确认不匹配；请确认后再执行。' } };
+  }
+  const dir = String(body.dir || '').trim();
+  if (!dir) return { code: 400, payload: { error: '缺少目录。' } };
+  const result = hostPurgeLib.applyHostPurge({
+    hubDir: ctx.hubDir,
+    dir,
+    homeDir: ctx.homeDir,
+    env: ctx.env,
+  });
+  if (!result.ok) return { code: result.code || 400, payload: { error: result.error, state: result.state || null } };
+  return {
+    code: 200,
+    payload: {
+      action: 'hosts.purge',
+      dir: result.dir,
+      state: result.state,
+      unlinkCount: result.unlinkCount,
+      keptLinks: result.keptLinks,
+      keptEntries: result.keptEntries,
+      trashedTo: result.trashedTo,
+    },
+  };
+}
+
 function json(res, code, value) {
   if (res.writableEnded) return;
   res.writeHead(code, {
@@ -632,6 +710,25 @@ function handleGet(ctx, pathname, url, res) {
     return json(res, 200, removePlanPayload(ctx, slug));
   }
   if (pathname === '/api/hosts') return json(res, 200, hostsPayload(ctx));
+  if (pathname === '/api/hosts/purge-plan') {
+    const dir = url.searchParams.get('dir') || '';
+    if (!dir) return json(res, 400, { error: '缺少 dir 参数（目标宿主目录）。' });
+    const plan = hostPurgeLib.planHostPurge({
+      hubDir: ctx.hubDir,
+      dir,
+      homeDir: ctx.homeDir,
+      env: ctx.env,
+    });
+    if (!plan.ok) return json(res, plan.code || 400, { error: plan.error, state: plan.state || null });
+    return json(res, 200, {
+      dir: plan.target,
+      state: plan.state,
+      unlinkCount: plan.linkSlugs.length,
+      keptLinks: plan.keptLinks,
+      keptEntries: plan.keptEntries,
+      trashedTo: plan.trashPath,
+    });
+  }
   if (pathname === '/api/adopt/scan') return json(res, 200, adoptScanPayload(ctx));
   if (pathname === '/api/links') return json(res, 200, linksPayload(ctx));
   if (pathname === '/api/links/plan') {
@@ -664,6 +761,9 @@ function handlePost(ctx, pathname, req, res) {
       if (pathname === '/api/links/remove') return writeUnlink(ctx, body);
       if (pathname === '/api/rollback/apply') return writeRollback(ctx, body);
       if (pathname === '/api/skills/remove') return writeRemove(ctx, body);
+      if (pathname === '/api/hosts/add') return writeHostAdd(ctx, body);
+      if (pathname === '/api/hosts/remove') return writeHostRemove(ctx, body);
+      if (pathname === '/api/hosts/purge') return writeHostPurge(ctx, body);
       return { code: 404, payload: { error: 'not found' } };
     };
     ctx.queue(run)

package/skills/yotta-skills/lib/hub.js

@@ -1461,6 +1461,22 @@ function doctor(options) {
     singleSourceChecks(opts, add);
   } catch (_) { /* 只读检查失败不影响 doctor 主流程 */ }
 
+  // F3（0.29.0）：宿主状态细分只读检查 —— 残留 / 仅标记给 info 提示，不 fail。
+  if (opts.discovery) {
+    for (const host of opts.discovery.hosts || []) {
+      if (!host || !host.dir) continue;
+      if (host.state === 'orphan') {
+        add('host_state:' + pathKey(host.dir), true, 'info',
+          '宿主目录疑似残留（实体未确认）: ' + host.label + ' — ' + host.dir,
+          '确认宿主已卸载后可清理：yotta-skills hub hosts remove "' + host.dir + '" --purge（默认预览，--yes 执行）');
+      } else if (host.state === 'marker-only') {
+        add('host_state:' + pathKey(host.dir), true, 'info',
+          '已装实体但技能目录未创建: ' + host.label,
+          '需要分发时运行 yotta-skills hub link --agent ' + (host.agentId || '<id>'));
+      }
+    }
+  }
+
   const errors = checks.filter((check) => !check.ok && check.severity === 'error');
   const warnings = checks.filter((check) => !check.ok && check.severity === 'warning');
   return {

package/skills/yotta-skills/lib/install-pipeline.js

@@ -86,6 +86,25 @@ function createInstaller(deps) {
     if (!opts.force && existingVersion === skill.version) {
       return { skill, status: 'skip', version: existingVersion, note: '已是最新', exitCode: 0 };
     }
+    if (opts.dryRun) {
+      // 0.29.0 D1：只读预览 —— 不发网络请求、不写任何文件（含台账）。
+      const latestUnresolved = skill.version === 'latest';
+      const planned = existingVersion ? 'update' : 'install';
+      return {
+        skill,
+        status: 'planned',
+        planned,
+        version: latestUnresolved ? 'latest' : skill.version,
+        installedVersion: existingVersion,
+        latestUnresolved,
+        note: latestUnresolved
+          ? 'latest（预览不解析）'
+          : planned === 'update'
+            ? '将更新 v' + existingVersion + ' -> v' + skill.version
+            : '将安装 v' + skill.version,
+        exitCode: 0,
+      };
+    }
 
     let tmp = null;
     let staged = null;

package/skills/yotta-skills/lib/self-install.js

@@ -0,0 +1,224 @@
+'use strict';
+/**
+ * 元阁独立安装（install-self）与位置查看（where）—— 0.29.0 F1。
+ *
+ * 独立安装 = 把管理引擎完整运行件（bin / lib / assets / package.json / skills.json）
+ * 装到用户级独立位置（默认 ~/.yottaskills/yotta-skills；YOTTA_SKILLS_HOME 可覆盖根），
+ * 写 <root>/self.json 登记。与 Hub 真源、宿主技能池完全独立：不写宿主配置、
+ * 不写 mcp.json、不建全局 shim。
+ *
+ * fail-closed：目标与 Hub 真源重叠 / 锁与数据桥接目录 / 非空陌生目录（--force 才覆盖
+ * 同名运行件，无关文件保留）。
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const hubLib = require('./hub');
+const agentDirsLib = require('./agent-dirs');
+
+const SELF_REGISTRY_VERSION = 1;
+const RUNTIME_PAYLOAD = ['bin', 'lib', 'assets', 'package.json', 'skills.json'];
+const PACKAGE_NAME = '@yottameta/yotta-skills';
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function resolveSelfRoot(opts) {
+  const options = opts || {};
+  const env = options.env || process.env;
+  const explicit = options.selfRoot || env.YOTTA_SKILLS_HOME;
+  if (explicit) return path.resolve(explicit);
+  return path.join(options.homeDir || os.homedir(), '.yottaskills');
+}
+
+function selfRegistryPath(opts) {
+  return path.join(resolveSelfRoot(opts), 'self.json');
+}
+
+function defaultSelfDir(opts) {
+  return path.join(resolveSelfRoot(opts), 'yotta-skills');
+}
+
+function readSelfRegistry(opts) {
+  try {
+    const value = JSON.parse(fs.readFileSync(selfRegistryPath(opts), 'utf8'));
+    if (value && typeof value === 'object' && Array.isArray(value.installs)) {
+      return {
+        version: SELF_REGISTRY_VERSION,
+        installs: value.installs.filter((item) => item && typeof item.dir === 'string' && item.dir),
+      };
+    }
+  } catch (_) { /* missing or corrupt registry falls back to empty */ }
+  return { version: SELF_REGISTRY_VERSION, installs: [] };
+}
+
+function writeSelfRegistry(opts, registry) {
+  const file = selfRegistryPath(opts);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp-' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify({
+    version: SELF_REGISTRY_VERSION,
+    installs: registry.installs,
+  }, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+function safeRealpath(target) {
+  try {
+    return fs.realpathSync.native(target);
+  } catch (_) {
+    try {
+      return fs.realpathSync(target);
+    } catch (_) {
+      return path.resolve(target);
+    }
+  }
+}
+
+function samePath(left, right) {
+  const a = safeRealpath(left);
+  const b = safeRealpath(right);
+  if (process.platform === 'win32') return a.toLowerCase() === b.toLowerCase();
+  return a === b;
+}
+
+function isInside(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function packageRoot() {
+  return path.join(__dirname, '..');
+}
+
+function readPackageVersion(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function hasContent(dir) {
+  try {
+    return fs.readdirSync(dir).length > 0;
+  } catch (_) {
+    return false;
+  }
+}
+
+/** 目标是否已是元阁运行件目录（允许正常覆盖升级）。 */
+function hasOwnMarker(dir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    if (pkg && pkg.name === PACKAGE_NAME) return true;
+  } catch (_) { /* no readable package.json */ }
+  return fs.existsSync(path.join(dir, 'bin', 'yotta-skills.js'));
+}
+
+function guardTarget(dir, opts) {
+  const hubDir = hubLib.resolveHubDir(opts);
+  if (samePath(dir, hubDir) || isInside(hubDir, dir) || isInside(dir, hubDir)) {
+    return '目标与 Hub 真源重叠（' + hubDir + '）：独立安装与 Hub 必须分离';
+  }
+  if (agentDirsLib.isBridgeOnlyDir(dir, opts)) {
+    return '目标是锁 / 数据桥接目录（XDG_STATE_HOME/skills 或 XDG_DATA_HOME/skills），不允许独立安装';
+  }
+  return null;
+}
+
+function copyEntry(from, to) {
+  fs.rmSync(to, { recursive: true, force: true });
+  if (fs.statSync(from).isDirectory()) {
+    fs.mkdirSync(to, { recursive: true });
+    fs.cpSync(from, to, { recursive: true });
+  } else {
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.copyFileSync(from, to);
+  }
+}
+
+function installSelf(opts) {
+  const options = opts || {};
+  const src = packageRoot();
+  const dir = path.resolve(options.dir || defaultSelfDir(options));
+  const dryRun = Boolean(options.dryRun);
+  const force = Boolean(options.force);
+  const version = readPackageVersion(src);
+  const registryFile = selfRegistryPath(options);
+
+  const guard = guardTarget(dir, options);
+  if (guard) return { ok: false, error: guard, exitCode: 2 };
+
+  const exists = fs.existsSync(dir);
+  const stranger = exists && hasContent(dir) && !hasOwnMarker(dir);
+  if (stranger && !force) {
+    return {
+      ok: false,
+      error: '目标是非空陌生目录：' + dir + '（默认拒绝覆盖）',
+      hint: '确认目录用途后加 --force 覆盖同名运行件（无关文件保留）；或改用 --dir 指定空目录。',
+      exitCode: 2,
+    };
+  }
+
+  const payload = {
+    action: 'install-self',
+    dryRun,
+    dir,
+    version,
+    files: RUNTIME_PAYLOAD.slice(),
+    registry: registryFile,
+    overwrite: exists,
+    forced: Boolean(stranger && force),
+    exitCode: 0,
+  };
+  if (dryRun) return { ok: true, ...payload };
+
+  for (const name of RUNTIME_PAYLOAD) {
+    copyEntry(path.join(src, name), path.join(dir, name));
+  }
+
+  const registry = readSelfRegistry(options);
+  const entry = { dir, version, installedAt: nowIso(), source: src };
+  const index = registry.installs.findIndex((item) => samePath(item.dir, dir));
+  if (index >= 0) registry.installs[index] = entry;
+  else registry.installs.push(entry);
+  writeSelfRegistry(options, registry);
+
+  return { ok: true, ...payload, installs: registry.installs };
+}
+
+function whereInfo(opts) {
+  const options = opts || {};
+  const running = safeRealpath(process.argv[1] || '');
+  const registry = readSelfRegistry(options);
+  return {
+    action: 'where',
+    running,
+    version: readPackageVersion(packageRoot()),
+    defaultDir: defaultSelfDir(options),
+    hubDir: hubLib.resolveHubDir(options),
+    registry: selfRegistryPath(options),
+    installs: registry.installs.map((item) => ({
+      dir: item.dir,
+      version: item.version || null,
+      installedAt: item.installedAt || null,
+      source: item.source || null,
+      current: running ? isInside(item.dir, running) : false,
+    })),
+  };
+}
+
+module.exports = {
+  SELF_REGISTRY_VERSION,
+  RUNTIME_PAYLOAD,
+  resolveSelfRoot,
+  selfRegistryPath,
+  defaultSelfDir,
+  readSelfRegistry,
+  writeSelfRegistry,
+  installSelf,
+  whereInfo,
+};

package/skills/yotta-skills/references/hub.md

@@ -55,12 +55,48 @@ Hub 真源对清单声明了 `runtimePayload` 的技能（元忆 / 元阁：`bin
 `hub doctor` 的 `link_scope:*` 检查只读报告「位于默认范围之外」的已建链接，
 并给出 `hub unlink --dir <目录>` 的清理提示；`hub hosts` 输出三类的本机计数。
 
+## 宿主状态细分与自定义注册（0.29.0 起）
+
+每条宿主目录带生命周期状态（`hub hosts` / 面板宿主矩阵）：
+
+- **可用**：目录存在 + 实体证据（应用标记 / 用户注册 / 手动标记）—— 默认链接 / 分发；
+- **残留**：目录存在 + 无实体证据（卸载残留或 CLI-only 安装）—— 默认保留使用（仍可链接），
+  可显式清理；文案统一「实体未确认」，不判定「已卸载」；
+- **未创建**：目录不存在且无实体证据 —— 安装宿主后自动出现；
+- **仅标记**：已装实体、技能目录未创建 —— `hub link --agent <id>` 会创建目录并链接。
+
+`hub doctor` 的 `host_state:*` 检查对残留 / 仅标记给 info 提示，不判 fail。
+自定义宿主目录可用 `hub hosts add` 注册进发现 / 分发 / 收编范围（只注册，
+不创建目录、不改宿主配置；移除注册绝不删目录）：
+
+```bash
+# 注册 / 查看 / 移除自定义宿主（realpath 去重；Hub / 桥接目录拒绝注册）
+npx -y @yottameta/yotta-skills hub hosts add ~/my-agent/skills --label "我的宿主"
+npx -y @yottameta/yotta-skills hub hosts list
+npx -y @yottameta/yotta-skills hub hosts remove ~/my-agent/skills
+
+# 手动标记状态（实体证据不足时）：available / orphan / ignored
+npx -y @yottameta/yotta-skills hub hosts mark ~/my-agent/skills --state orphan
+
+# 清理残留目录：默认预览；--yes 执行 —— 只删指向 Hub 的链接（含死链），
+# 非 Hub 链接 / 非技能内容随目录保留在回收站（7 天，输出恢复路径）
+npx -y @yottameta/yotta-skills hub hosts remove ~/my-agent/skills --purge
+npx -y @yottameta/yotta-skills hub hosts remove ~/my-agent/skills --purge --yes
+```
+
+注册表 = `<root>/hosts.json`（root = `YOTTA_SKILLS_HOME` 或 `~/.yottaskills`，schema v1，
+可 diff）；面板「宿主矩阵 → 添加自定义目录」等价可用，写操作需页面令牌与确认串。
+
 ## 命令
 
 ```bash
 # 发现本机已装智能体与技能目录（文件系统优先；不读元忆 / 注册表）
 npx -y @yottameta/yotta-skills hub hosts
 
+# 状态过滤 / 自定义注册 / 残留清理（详见「宿主状态细分与自定义注册」节）
+npx -y @yottameta/yotta-skills hub hosts --state orphan
+npx -y @yottameta/yotta-skills hub hosts add ~/my-agent/skills --label "我的宿主"
+
 # 安装 / 更新 Hub 真源
 # 范围 = 全家清单 27 + 特殊家族 5；特殊家族跟随各自 npm latest
 # 非元技能不参与更新（来源无统一安装源，用户自行处理）

package/skills/yotta-skills/scan-policy.json

@@ -198,9 +198,9 @@
     },
     "yotta-memory": {
       "version": "0.22.1",
-      "treeHash": "sha256:0fb2fa87f85c43a4e6393791944516e3daa5fecbf5bff77648f57eed71aa1ee2",
+      "treeHash": "sha256:7ad5ec9cb790bd6f96ecc1977fcc5428fbea9c4d1ebb2b2dd5943e75f2e2a410",
       "files": 18,
-      "bytes": 1299467,
+      "bytes": 1302396,
       "mode": "strict",
       "exceptions": [
         {

package/skills/yotta-skills/scripts/yotta-skills-mcp.py

@@ -27,7 +27,7 @@ import subprocess
 import sys
 from pathlib import Path
 
-VERSION = "0.28.3"
+VERSION = "0.29.0"
 TOOL_NAME = "yotta-skills"
 CN_NAME = "元阁"
 MCP_PROTOCOL_MODERN = "2026-07-28"