@yottameta/yotta-skills-plugin 0.29.0 → 0.29.2

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

@@ -0,0 +1,170 @@
+'use strict';
+/**
+ * 用户级配置（0.29.2 U4）—— <root>/config.json。
+ *
+ * root = YOTTA_SKILLS_HOME 或 ~/.yottaskills（与 hosts.json / self.json 同根，
+ * 独立于 Hub 目录本身）。schema v1：{ version, hub: "<path>" | null }。
+ *
+ * Hub 解析优先级：--hub flag > YOTTA_SKILLS_HUB env > config.hub > 默认 <root>/hub。
+ * set 为 fail-closed 校验：不能是文件、不能与配置根 / 独立安装目录重叠、
+ * 不能是锁 / 数据桥接目录；路径不存在时允许（首次使用时创建）。
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const agentDirsLib = require('./agent-dirs');
+
+const CONFIG_VERSION = 1;
+
+function resolveSkillsRoot(opts) {
+  const options = opts || {};
+  const env = options.env || process.env;
+  const explicit = options.skillsRoot || env.YOTTA_SKILLS_HOME;
+  if (explicit) return path.resolve(explicit);
+  return path.join(options.homeDir || os.homedir(), '.yottaskills');
+}
+
+function configPath(opts) {
+  return path.join(resolveSkillsRoot(opts), 'config.json');
+}
+
+function defaultHubDir(opts) {
+  return path.join(resolveSkillsRoot(opts), 'hub');
+}
+
+function readConfig(opts) {
+  try {
+    const value = JSON.parse(fs.readFileSync(configPath(opts), 'utf8'));
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      return {
+        version: CONFIG_VERSION,
+        hub: typeof value.hub === 'string' && value.hub.trim() ? value.hub : null,
+      };
+    }
+  } catch (_) { /* missing or corrupt config falls back to empty */ }
+  return { version: CONFIG_VERSION, hub: null };
+}
+
+function writeConfig(opts, config) {
+  const file = configPath(opts);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp-' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify({
+    version: CONFIG_VERSION,
+    hub: config && config.hub ? config.hub : null,
+  }, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+/** 解析生效 Hub：返回 { dir, source, configured, configFile, defaultDir }。 */
+function resolveHub(opts) {
+  const options = opts || {};
+  const env = options.env || process.env;
+  const config = readConfig(options);
+  const base = {
+    configured: config.hub,
+    configFile: configPath(options),
+    defaultDir: defaultHubDir(options),
+  };
+  if (options.hub) return { dir: path.resolve(options.hub), source: 'flag', ...base };
+  if (env.YOTTA_SKILLS_HUB) return { dir: path.resolve(env.YOTTA_SKILLS_HUB), source: 'env', ...base };
+  if (config.hub) return { dir: path.resolve(config.hub), source: 'config', ...base };
+  return { dir: base.defaultDir, source: 'default', ...base };
+}
+
+function sourceLabel(source) {
+  if (source === 'flag') return '--hub 参数';
+  if (source === 'env') return 'YOTTA_SKILLS_HUB 环境变量';
+  if (source === 'config') return 'config.json 配置';
+  return '默认位置';
+}
+
+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));
+}
+
+/** fail-closed 校验 Hub 路径；返回 { ok:true, dir } 或 { ok:false, error }。 */
+function validateHubPath(input, opts) {
+  const options = opts || {};
+  const raw = String(input == null ? '' : input).trim();
+  if (!raw) return { ok: false, error: '缺少路径：hub config set --hub <path>' };
+  const dir = path.resolve(raw);
+  let stat = null;
+  try {
+    stat = fs.statSync(dir);
+  } catch (_) { /* 不存在允许：首次使用时创建 */ }
+  if (stat && !stat.isDirectory()) return { ok: false, error: '不是目录：' + dir };
+  const root = resolveSkillsRoot(options);
+  if (isInside(dir, root)) {
+    return {
+      ok: false,
+      error: 'Hub 不能与配置根相同或包含配置根（' + root + '）：config.json / hosts.json / self.json 需保持独立',
+    };
+  }
+  const selfDir = path.join(root, 'yotta-skills');
+  if (samePath(dir, selfDir) || isInside(selfDir, dir) || isInside(dir, selfDir)) {
+    return { ok: false, error: 'Hub 不能与独立安装目录重叠（' + selfDir + '）' };
+  }
+  if (agentDirsLib.isBridgeOnlyDir(dir, options)) {
+    return { ok: false, error: '锁 / 数据桥接目录不能作为 Hub：' + dir };
+  }
+  return { ok: true, dir };
+}
+
+/** 写入持久 Hub 覆盖；返回 { ok, hub, configFile, previous }。 */
+function setHub(opts, input) {
+  const options = opts || {};
+  const guard = validateHubPath(input && input.hub, options);
+  if (!guard.ok) return guard;
+  const config = readConfig(options);
+  const previous = config.hub;
+  config.hub = guard.dir;
+  const file = writeConfig(options, config);
+  return { ok: true, hub: guard.dir, configFile: file, previous };
+}
+
+/** 清除持久 Hub 覆盖（恢复 flag > env > 默认）。 */
+function clearHub(opts) {
+  const options = opts || {};
+  const config = readConfig(options);
+  if (!config.hub) return { ok: false, error: '没有可清除的 Hub 配置覆盖（当前来源不是 config.json）' };
+  const removed = config.hub;
+  config.hub = null;
+  const file = writeConfig(options, config);
+  return { ok: true, removed, configFile: file };
+}
+
+module.exports = {
+  CONFIG_VERSION,
+  resolveSkillsRoot,
+  configPath,
+  defaultHubDir,
+  readConfig,
+  writeConfig,
+  resolveHub,
+  sourceLabel,
+  validateHubPath,
+  setHub,
+  clearHub,
+};

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

@@ -12,7 +12,24 @@ symlink），升级只改真源，已链接宿主即时生效。
 - 技能台账：`<hub>/.yotta-hub.json`
 - 链接台账：`<hub>/.yotta-links.json`
 - 收敛回收站：`~/.yottaskills/trash/<时间戳>/<宿主>/<技能>/`（保留 7 天，可用 `YOTTA_SKILLS_TRASH` 覆盖）
-- 覆盖方式：`--hub <dir>` 或 `YOTTA_SKILLS_HUB`
+- 覆盖方式（优先级）：`--hub <dir>` > `YOTTA_SKILLS_HUB` > `config.json`（`hub config set`）> 默认
+
+## Hub 位置持久化（0.29.2 起）
+
+`hub config` 把 Hub 位置写进用户级配置（与 hosts.json / self.json 同根）：
+
+```bash
+npx -y @yottameta/yotta-skills hub config get                # 生效位置 + 来源 + 配置文件
+npx -y @yottameta/yotta-skills hub config set --hub "D:\my-hub"        # 只换指针（旧 Hub 保留）
+npx -y @yottameta/yotta-skills hub config set --hub "D:\my-hub" --move # 迁移：复制校验 → 重链 → 旧 Hub 入回收站
+npx -y @yottameta/yotta-skills hub config clear              # 清除覆盖，回到 flag > env > 默认
+```
+
+- 配置文件：`<YOTTA_SKILLS_HOME>/config.json`（默认 `~/.yottaskills/config.json`；schema v1，原子写）。
+- 校验（fail-closed）：路径不能是文件、不能与配置根 / 独立安装目录重叠、不能是锁 / 数据桥接目录；路径不存在允许（首次使用时创建）。
+- `--move` 语义：旧 Hub 复制到新位置 → 逐技能 treeHash 校验 → 切换配置 → `hub link` 以新 Hub 为源 `--force` 重链 → 旧 Hub 入回收站（保留 7 天）。校验失败不切配置；重链未全部完成时旧 Hub 保留供重试（新旧内容一致，混合链接均可用）。
+- 面板「Hub 位置」区显示来源 / 配置覆盖 / 重启提示，并提供「设置新位置 / 清除覆盖」（写操作需页面令牌 + `hub-config` 确认串）；已在运行的 `view` 需重启后生效。
+- 误用防护：`--hub` 只允许与 `hub` / `view` / `where` 一起使用；其它命令（含裸 `--hub`）fail-closed 报错，不再静默忽略。
 
 ## 元技能唯一性收敛（`hub link` 执行时）
 
@@ -87,6 +104,36 @@ 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

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

@@ -1,14 +1,14 @@
 # 全家技能清单（27 个）
 
 > 机器权威源：`skills.json`（随包分发）；本文件为人工可读副本，新技能发布后须同步更新
-> `skills.json`（登记表为内部台账，不随包分发）。清单更新日期：2026-10-03。
+> `skills.json`（登记表为内部台账，不随包分发）。清单更新日期：2026-10-05。
 
 | slug | 中文名 | npm 包 | 清单版本 | 家族 | 说明 |
 |---|---|---|---|---|
 | `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.3 | 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:7ad5ec9cb790bd6f96ecc1977fcc5428fbea9c4d1ebb2b2dd5943e75f2e2a410",
+      "version": "0.22.3",
+      "treeHash": "sha256:4f499e0d61ec567d76a22ca6cb43fb2488129d3043a880b4d40b2c96de377ef0",
       "files": 18,
-      "bytes": 1302396,
+      "bytes": 1303762,
       "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.29.0"
+VERSION = "0.29.2"
 TOOL_NAME = "yotta-skills"
 CN_NAME = "元阁"
 MCP_PROTOCOL_MODERN = "2026-07-28"

package/skills/yotta-skills/skills.json

@@ -1,6 +1,6 @@
 {
   "manifestVersion": 1,
-  "updated": "2026-10-02",
+  "updated": "2026-10-05",
   "note": "清单同步要求：每次技能发布新版本后，按 YottaSkills 技能登记表更新本文件（登记表为内部台账，不随包分发）。",
   "skills": [
     {
@@ -31,7 +31,7 @@
     "slug": "yotta-memory",
     "name": "元忆",
     "pkg": "@yottameta/yotta-memory",
-    "version": "0.22.1",
+    "version": "0.22.3",
     "domain": "memory",
     "runtimePayload": ["bin"],
     "desc": "有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT）"