@yottameta/yotta-skills-plugin 0.28.3 → 0.29.1

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/lib/skills-scan.js

@@ -113,6 +113,30 @@ function compareSemver(left, right) {
   return comparePrerelease(a.prerelease, b.prerelease);
 }
 
+/**
+ * 版本关系判定（元阁 update「只升不降」统一口径，0.29.1 U1）。
+ *
+ * installed：本地已装版本（null = 未装）；target：目标版本（精确 semver 或 'latest'）。
+ * 返回：
+ * - install：本地未装（含 target = latest，解析后照常安装）
+ * - upgrade：本地低于目标（唯一应安装的关系）
+ * - equal：本地与目标相等
+ * - local-ahead：本地高于目标（保留，不降级）
+ * - unknown：任一侧无法解析（fail-safe 保留）
+ * - resolve-needed：目标为 latest（需先解析出精确版本再复判）
+ *
+ * 注意：compareSemver 对不可解析输入返回 0，必须先 parseSemver 校验，
+ * 不能直接拿 compare === 0 当相等。
+ */
+function versionRelation(installed, target) {
+  if (!installed) return 'install';
+  if (target === 'latest') return 'resolve-needed';
+  if (!parseSemver(installed) || !parseSemver(target)) return 'unknown';
+  const diff = compareSemver(installed, target);
+  if (diff === 0) return 'equal';
+  return diff > 0 ? 'local-ahead' : 'upgrade';
+}
+
 /** 从多个安装副本中选择代表版本：优先合法版本中的最高 semver。 */
 function selectRepresentativeVariant(variants) {
   let selected = null;
@@ -436,6 +460,7 @@ module.exports = {
   parseFrontmatter,
   parseSemver,
   compareSemver,
+  versionRelation,
   strictFrontmatterWarnings,
   scanSkillDir,
   defaultRoots,

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

@@ -55,12 +55,78 @@ 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）；面板「宿主矩阵 → 添加自定义目录」等价可用，写操作需页面令牌与确认串。
+
+## 不接管与目录覆盖（0.29.1 起）
+
+**不接管**（excluded）：把某个智能体或目录从发现、显示、链接三层全部跳过
+（`--include-discovered` 也不纳入）；已建立的链接不受影响，可用 `hub unlink` 清理：
+
+```bash
+npx -y @yottameta/yotta-skills hub hosts exclude box                    # 按 agentId
+npx -y @yottameta/yotta-skills hub hosts exclude "D:\my-agent\skills"  # 按目录
+npx -y @yottameta/yotta-skills hub hosts include box                    # 恢复接管
+```
+
+**目录覆盖**（override）：用户级覆盖某个已收录 agentId 的内置映射目录
+（不改宿主配置；被覆盖的旧目录不再进入默认发现 / 链接）：
+
+```bash
+npx -y @yottameta/yotta-skills hub hosts set box --dir "D:\box-agent\skills"
+npx -y @yottameta/yotta-skills hub hosts set box --clear     # 恢复内置映射
+```
+
+面板「宿主矩阵」提供等价动作：行内「不接管 / 编辑目录 / 标记可用 / 忽略」，
+底部「不接管名单」区可「恢复接管」；写操作均写 Hub 审计。
+
+**YottaCode 不纳入接管**：YottaCode 自带三层技能管理（skill-inventory / skill /
+user-skills），元阁对其 `.yottacode` 路径与 `YOTTACODE_HOME` 子树在映射、扫描、
+注册、标记、链接全部 fail-closed 排除，避免重复管理。
+
+**未核实映射 ≠ 自动发现**：内置映射里尚未逐机核实的条目显示「映射·未核实」；
+「自动发现」只用于文件系统扫描结果。`installed` 配对按「用户注册 / 已核实映射 > env >
+未核实映射 > 自动发现」确定性优选（同级按技能数 + 路径稳定排序）。
+
 ## 命令
 
 ```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/references/install-flow.md

@@ -77,14 +77,17 @@
 
 - 读取目标 `<dest>/<slug>/SKILL.md` 的 frontmatter `version`；
 - 与清单 `version` 一致 → 跳过（幂等：第二次安装 27 个全部跳过）；
-- `--force` 强制重装；`update` 对「缺失 / 版本不一致」的技能重装。
+- **只升不降（0.29.1 起）**：本地版本高于目标（清单 pin / npm latest）→ 保留并标注「本地领先」，
+  `update` / `hub update` 跳过、`update --check` 不计更新（退出码 0）、`update --auto` 不动作；
+  `latest` / `--range` 目标在解析出精确版本后、任何写入之前复判；
+- `--force` 强制重装 / 显式降级；`rollback` 恢复快照；`update` 对「缺失 / 需要升级」的技能安装。
 
 ## 范围控制（接多少管多少）
 
 | 用法 | 范围 |
 |---|---|
 | `install`（无旗标） | 全量清单全部安装 |
-| `update`（无旗标） | 补齐缺失 + 升级已装（现状语义不变） |
+| `update`（无旗标） | 补齐缺失 + 升级已装（只升不降：本地更高保留不降级） |
 | `update --installed-only` | 只维护目标目录已安装的家族技能（不补装缺失；无匹配时退出码 0） |
 | `--only <a,b>` / `--domain <name>` | 只处理指定技能 / 家族；与 `--installed-only` 取交集 |
 | `update --check` / `--auto` | 只检查 / 维护已装技能，不补装缺失 |

package/skills/yotta-skills/references/skill-list.md

@@ -8,7 +8,7 @@
 | `yotta-anti-shallow` | 元谨 | `@yottameta/yotta-anti-shallow` | 1.4.2 | quality | 防 AI 敷衍规则引擎（深入分析/根因追溯时激活） |
 | `yotta-code-quality` | 元质 | `@yottameta/yotta-code-quality` | 0.4.3 | quality | 结对式代码质量评审（十二类腐化风险 + 0-100 健康分） |
 | `yotta-workflow` | 元序 | `@yottameta/yotta-workflow` | 0.4.3 | workflow | 跨会话/跨项目通用工作流协议（状态就近存） |
-| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.22.1 | memory | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
+| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.22.2 | memory | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
 | `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.2.2 | memory | 学习沉淀 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目 |
 | `yotta-security-audit` | 元安 | `@yottameta/yotta-security-audit` | 0.3.1 | security | 安全扫描引擎：13 类检测器 + 系统安全基线 + 学生数据隐私（教育版） |
 | `yotta-vetter` | 元审 | `@yottameta/yotta-vetter` | 0.2.7 | security | 安全审查协议：四阶段 review + SAFE TO INSTALL 判定 |

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

@@ -197,10 +197,10 @@
       ]
     },
     "yotta-memory": {
-      "version": "0.22.1",
-      "treeHash": "sha256:0fb2fa87f85c43a4e6393791944516e3daa5fecbf5bff77648f57eed71aa1ee2",
+      "version": "0.22.2",
+      "treeHash": "sha256:7b2cd7a2b5d4eef365dabd6f1d83200458d28ddea1140c362bbea628e832b5f6",
       "files": 18,
-      "bytes": 1299467,
+      "bytes": 1302762,
       "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.1"
 TOOL_NAME = "yotta-skills"
 CN_NAME = "元阁"
 MCP_PROTOCOL_MODERN = "2026-07-28"

package/skills/yotta-skills/skills.json

@@ -31,7 +31,7 @@
     "slug": "yotta-memory",
     "name": "元忆",
     "pkg": "@yottameta/yotta-memory",
-    "version": "0.22.1",
+    "version": "0.22.2",
     "domain": "memory",
     "runtimePayload": ["bin"],
     "desc": "有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT）"