@yottameta/yotta-skills 0.22.1 → 0.22.2

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## v0.22.2 (2026-09-30)
+
+- 修复 `doctor --dir` 指向单个技能包目录时的 UX：现在会按 `SKILL.md` / `skill-manifest.json` / 目录名自动识别技能身份，不再误报「目标目录下没有可检查的元阁家族技能」。
+- 修复 doctor 退出码语义：没有可检查对象返回 `4`，检查失败仍返回 `1`，manifest / 身份校验失败仍返回 `6`，便于只读调用方区分「没目标」与「检查失败」。
+- 新增单技能目录、显式 `--slug` 单技能目录、空目录退出码三组 CLI 回归。
+
 ## v0.22.1 (2026-09-30)
 
 - 清单同步：元忆 pin 0.19.0 → 0.20.0，承接上下文分页 (`context.paging`) 与 `memory.hook` PREF 驱逐修复。

package/README.md

@@ -31,7 +31,7 @@ Installing the whole YottaMeta family used to mean running <code>npx</code> for
 - **Install** — install everything (or a subset) into an agent's default user-level directory or any directory.
 - **Update** — incremental update: add missing skills, upgrade version-skewed ones.
 - **Update check / auto-update** — <code>update --check</code> compares installed skill versions against the npm registry and reports; <code>update --check --scheduled</code> is the weekly background entry with a local cache and jitter, so it stays offline until due; <code>update --auto</code> upgrades the installed YottaMeta family to the latest (non-family skills are never auto-updated).
-- **Doctor / rollback** — <code>doctor</code> checks the installed skill directory, version, manifest, registry and custom doctor script without modifying it; <code>rollback</code> validates a snapshot and restores the latest install or update.
+- **Doctor / rollback** — <code>doctor</code> checks the installed skill directory, version, manifest, registry and custom doctor script without modifying it; <code>--dir</code> may point to a skills container or directly to a single skill package. <code>rollback</code> validates a snapshot and restores the latest install or update.
 - **Runtime hook adapter** — manifests declare six lifecycle requirements; <code>hook capabilities / evaluate / bind / unbind</code> probe host support, apply deterministic decisions, record evidence, and never overstate audit-only hosts as enforced.
 - **Idempotent** — a skill already at the manifest version is skipped; re-running is safe.
 - **Pre-install gate** — family installs read the package manifest, bootstrap yotta-verify (元信) when it is missing, then scan each package. <code>DO NOT INSTALL</code> blocks; caution/review continue with visible risk. Old versions are snapshotted before replacement.
@@ -113,6 +113,8 @@ Requirements: Node.js 18+, npm, and system <code>tar</code> (built into Windows
 | `update --check` | Read-only update check: compare installed versions against the npm registry and report (exit 0 = up to date, 3 = updates available, 1 = could not check; run with `--registry <url>` to target a mirror); no changes |
 | `update --check --scheduled` | Weekly background entry: no network until due, then one check and a local cache write; text mode stays quiet on failure, `--json` keeps diagnostics; always exits 0 |
 | `update --auto` | Check and automatically update the installed YottaMeta family to the latest (runs the pre-install gate; never auto-updates non-family skills) |
+| `doctor [--agent <name> \| --dir <path>] [--slug <slug>]` | Read-only self-check: SKILL / version / manifest / registry / custom doctor; `--dir` may point to a skills container or a single skill package; exit 0 = pass, 4 = no checkable target, 1 = check failed, 6 = manifest identity failure |
+| `rollback [--agent <name> \| --dir <path>] [--slug <slug>]` | Validate and restore the latest snapshot; `--list` lists snapshots; `--json` returns machine-readable output |
 | `hook capabilities --host <name>` | Show the six-event host capability matrix; unknown hosts stay <code>unsupported</code> |
 | `hook evaluate --host <name> --event <event> --manifest <file> --context <json>` | Evaluate a manifest hook event, return allow / block / warn / unverified, and append structured evidence |
 | `hook bind --host <name> --manifest <file>` / `hook unbind <id>` | Idempotently register or remove hook declarations |

package/README.zh-CN.md

@@ -34,7 +34,7 @@
 - **安装**——装全家（或指定技能）到智能体默认用户级目录或任意目录。
 - **更新**——增量更新：补齐缺失技能、升级版本不一致的技能。
 - **更新检查 / 自动更新**——<code>update --check</code> 只读比对已装技能版本与 npm 注册表并报告；<code>update --check --scheduled</code> 是后台周检入口，用本地缓存和随机抖动做到未到期不联网；<code>update --auto</code> 检查后自动把已装元阁家族升到最新（非元阁家族技能绝不自动更新）。
-- **自检 / 回滚**——<code>doctor</code> 只读检查技能目录、版本、manifest、注册表和自定义 doctor；<code>rollback</code> 校验快照后恢复最近一次安装或更新，恢复失败不会覆盖当前目录。
+- **自检 / 回滚**——<code>doctor</code> 只读检查技能目录、版本、manifest、注册表和自定义 doctor，`--dir` 可直接指向单个技能包目录；<code>rollback</code> 校验快照后恢复最近一次安装或更新，恢复失败不会覆盖当前目录。
 - **运行时 hook 适配层**——技能 manifest 只声明六个生命周期要求；<code>hook capabilities / evaluate / bind / unbind</code> 负责宿主能力探测、确定性决策、结构化证据和降级标注，不把 audit 能力夸大为强制。
 - **幂等**——已在清单版本的技能跳过；重复运行安全。
 - **装前门禁**——家族安装先读取包内 manifest，元信（yotta-verify）缺失时自动自举，再逐个扫描。`DO NOT INSTALL` 阻断；`CAUTION` / `REVIEW` 继续但显示风险。旧版本会先做快照再替换。
@@ -116,6 +116,8 @@ npx -y @yottameta/yotta-skills --reindex
 | `update --check` | 只读更新检查：比对已装版本与 npm 注册表并报告（退出码 0=最新 / 3=有更新 / 1=无法检查；可用 `--registry <url>` 指定镜像）；不改动 |
 | `update --check --scheduled` | 后台周检入口：未到期不联网；到期只检查一次并写本地缓存；文本失败静默，`--json` 保留诊断；始终退出 0 |
 | `update --auto` | 检查后自动更新已装元阁家族到最新（含装前门禁；非元阁家族技能绝不自动更新） |
+| `doctor [--agent <name> \| --dir <path>] [--slug <slug>]` | 只读自检：SKILL / 版本 / manifest / 注册表 / 自定义 doctor；`--dir` 可指向技能集合目录或单个技能包目录；退出码 0=通过 / 4=没有可检查对象 / 1=检查失败 / 6=manifest 身份失败 |
+| `rollback [--agent <name> \| --dir <path>] [--slug <slug>]` | 校验并恢复最近一次快照；`--list` 只列快照；`--json` 输出机器可读结果 |
 | `hook capabilities --host <name>` | 查看六个统一事件的宿主能力矩阵；未知宿主默认 `unsupported` |
 | `hook evaluate --host <name> --event <event> --manifest <file> --context <json>` | 评估 manifest hook 事件，返回 allow / block / warn / unverified，并写结构化证据 |
 | `hook bind --host <name> --manifest <file>` / `hook unbind <id>` | 幂等注册或反注册 hook 声明 |

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-skills
-version: 0.22.1
+version: 0.22.2
 description: 元阁 -- 元阁全家技能的总编排策划 + 编排路由 + 一键安装器 + 技能盘点 + 运行时 hook 适配。路由层：--route / route_request 按需求摘要给出候选组合、调用顺序、角色、置信度、依据、已装/缺失状态与安装命令，只建议不自动安装；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；M1 记忆裁决层：usage enable/mark 本地结构化记录 + decide-memory / MCP decide_memory 输出 promote / hold / demote 只读建议（需授权 provider；只建议不删除、不自动写元忆）；策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么组合使用（安装与调用均由用户确认后执行）」；安装层：一条命令把 YottaMeta 已发布的全部 yotta-* 技能装进指定智能体或目录（默认 --pin 锁死清单精确版本）；盘点层：--inventory / --reindex 扫描本机已装技能生成/更新注册表，新装技能自动被发现（install/update 后自动 re-index，会话开工只建议跑本地 --reindex；更新检查走手动 --check 或后台 --check --scheduled）；运行时适配层：hook capabilities / evaluate / bind / unbind 按宿主能力矩阵执行六个统一事件并留证降级，元信 before_install 已接入安装管线；自包含零依赖，不依赖任何元技能；MCP 按需加载且需用户确认后写入配置（可选：list_installed_skills/describe_skill/reindex/route_request/decide_memory，不常驻，未加载降级 CLI）。支持 --list 清单 / --route 路由 / usage 使用记录 / decide-memory 记忆裁决 / install / update / update --check（只读检查）/ update --check --scheduled（后台周检）/ update --auto（家族自动更新）/ hook 适配 / --inventory / --reindex / --dry-run 预览 / --pin（默认）/ --range。触发：需要批量安装或更新元阁全家技能、按场景组合多个元技能、路由或判断该用哪些技能、判断哪些技能值得长期记忆、查看或记录技能使用信号、盘点或查看本机已装技能、重扫技能注册表、给某个智能体或目录一次性铺齐 yotta-* 技能、评估宿主 hook 能力、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/检查更新/自动更新/hook 适配/该用哪个技能/路由技能/记忆裁决/技能该不该记住/盘点技能/查看已装技能 等。边界（Do NOT trigger）：只做「组合策划 + 静态路由建议 + M1 记忆裁决只读建议 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index + hook 适配」，不含技能本体、不做技能内容开发、不 -g 污染全局、不自动安装缺失技能、不静默写宿主配置或全局记忆、不自动删除技能或记忆；家族安装先自举或调用元信装前门禁，DO NOT INSTALL 阻断，非元阁家族包不自动安装。
 license: MIT
 metadata:
@@ -166,7 +166,7 @@ openclaw skills update @yottameta/yotta-skills
 | `update --check [--agent <name> \| --dir <path>]` | 只读检查更新：联网对 npm 最新，不改动；退出码 0=全部最新 / 3=有更新 / 1=查失败 |
 | `update --check --scheduled [--agent <name> \| --dir <path>]` | 后台周检入口：未到期不联网；到期只检查一次并写本地缓存；文本失败静默，`--json` 保留诊断；始终退出 0 |
 | `update --auto [--agent <name> \| --dir <path>]` | 检查到家族更新后自动更新（仅 yotta-* 自家家族，含装前安全扫描） |
-| `doctor [--agent <name> \| --dir <path>] [--slug <slug>]` | 只读自检：SKILL / 版本 / manifest / 注册表 / 自定义 doctor；`--json` 输出稳定字段 |
+| `doctor [--agent <name> \| --dir <path>] [--slug <slug>]` | 只读自检：SKILL / 版本 / manifest / 注册表 / 自定义 doctor；`--dir` 可指向技能集合目录或单个技能包目录；退出码 0=通过 / 4=没有可检查对象 / 1=检查失败 / 6=manifest 身份失败 |
 | `rollback [--agent <name> \| --dir <path>] [--slug <slug>]` | 校验并恢复最近一次快照；`--list` 只列快照；`--json` 输出机器可读结果 |
 | `hook capabilities --host <name>` | 查看宿主六个统一事件的能力等级；未知宿主默认 `unsupported` |
 | `hook evaluate --host <name> --event <event> --manifest <file> --context <json>` | 评估 manifest hook 声明，输出 allow / block / warn / unverified，并写结构化证据 |
@@ -262,7 +262,9 @@ npx -y @yottameta/yotta-skills update --auto --agent codex
 
 `doctor` 是只读自检，不会修改技能目录或注册表。它检查目标技能目录、`SKILL.md`、
 frontmatter 版本、manifest 身份、本地注册表记录，以及包内声明的自定义 doctor 脚本。
-`--json` 返回稳定字段，适合脚本和智能体消费。
+`--dir` 既可指向包含多个 `yotta-*` 子目录的技能集合目录，也可直接指向单个技能包目录；
+后者会按 `SKILL.md` / `skill-manifest.json` 自动识别技能身份。`--json` 返回稳定字段，
+适合脚本和智能体消费。退出码：`0` 通过，`4` 没有可检查对象，`1` 检查失败，`6` manifest 身份失败。
 
 ```bash
 npx -y @yottameta/yotta-skills doctor --agent codex --slug yotta-memory

package/bin/yotta-skills.js

@@ -42,7 +42,7 @@ const m1FeaturesLib = require('../lib/m1-features');
 const { createInstaller, isSafeTarEntry } = require('../lib/install-pipeline');
 
 const PKG_ROOT = path.join(__dirname, '..');
-let VERSION = '0.22.1';
+let VERSION = '0.22.2';
 try { VERSION = require(path.join(PKG_ROOT, 'package.json')).version; } catch (_) { /* keep fallback */ }
 
 function loadManifest() {
@@ -820,27 +820,62 @@ function runCustomDoctor(skillDir, dest) {
   });
 }
 
+function withDoctorTarget(skill, target) {
+  return Object.assign({}, skill, { target });
+}
+
+function selfDoctorTarget(dest) {
+  const meta = readInstalledMeta(dest);
+  const manifest = readInstalledManifest(dest);
+  const candidates = [
+    manifest && manifest.slug,
+    meta.name,
+    path.basename(dest),
+  ]
+    .filter(Boolean)
+    .map((value) => String(value).trim().toLowerCase());
+
+  for (const slug of candidates) {
+    const skill = familySkillFor(slug);
+    if (skill) return withDoctorTarget(skill, dest);
+  }
+  return null;
+}
+
 function doctorTargets(opts, dest) {
+  const self = selfDoctorTarget(dest);
   if (opts.slug) {
+    if (self && self.slug === opts.slug) return [self];
     const skill = familySkillFor(opts.slug);
-    return skill ? [skill] : [];
+    return skill ? [withDoctorTarget(skill, path.join(dest, skill.slug))] : [];
   }
   if (opts.skills.length) {
-    return opts.skills.map((slug) => familySkillFor(slug)).filter(Boolean);
+    const targets = [];
+    for (const slug of opts.skills) {
+      if (self && self.slug === slug) {
+        targets.push(self);
+        continue;
+      }
+      const skill = familySkillFor(slug);
+      if (skill) targets.push(withDoctorTarget(skill, path.join(dest, skill.slug)));
+    }
+    return targets;
   }
   const found = [];
   let entries;
-  try { entries = fs.readdirSync(dest, { withFileTypes: true }); } catch (_) { return found; }
+  try { entries = fs.readdirSync(dest, { withFileTypes: true }); } catch (_) { return self ? [self] : found; }
   for (const entry of entries) {
     if (!entry.isDirectory() || !/^yotta-/.test(entry.name)) continue;
     const skill = familySkillFor(entry.name);
-    if (skill) found.push(skill);
+    if (skill) found.push(withDoctorTarget(skill, path.join(dest, skill.slug)));
   }
+  if (found.length === 0 && self) return [self];
   return found;
 }
 
 function doctorExitCode(payload) {
   if (payload.ok) return 0;
+  if (payload.checked === 0) return 4;
   const manifestFailure = payload.results.some((result) =>
     (result.checks || []).some((check) =>
       (check.id === 'manifest' || check.id === 'manifest_trust') && !check.ok));
@@ -861,7 +896,7 @@ function runDoctor(opts, dest) {
   }
 
   for (const skill of targets) {
-    const target = path.join(dest, skill.slug);
+    const target = skill.target || path.join(dest, skill.slug);
     const result = healthLib.checkInstalledSkill({
       slug: skill.slug,
       target,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-skills",
-  "version": "0.22.1",
+  "version": "0.22.2",
   "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
   "license": "MIT",
   "keywords": [

package/references/install-flow.md

@@ -145,6 +145,8 @@ yotta-skills doctor --dir <skills-dir> --json
 
 doctor 只读检查目录、`SKILL.md`、版本、manifest 身份、注册表记录和自定义 doctor，
 不会修改目标目录或注册表。注册表版本不一致属于 warning，可用 `--reindex` 修复。
+`--dir` 也可以直接指向单个技能包目录，此时会按 `SKILL.md` / `skill-manifest.json` / 目录名自动识别技能身份。
+退出码：`0` 通过，`4` 没有可检查对象，`1` 检查失败，`6` manifest / 身份校验失败。
 
 ## 安装证据
 
@@ -164,7 +166,7 @@ doctor 只读检查目录、`SKILL.md`、版本、manifest 身份、注册表记
 | 0 | 成功（含全部跳过） |
 | 1 | 安装 / 更新存在失败项 |
 | 2 | 用法错误（未知参数 / 未知技能 / 未收录智能体） |
-| 4 | 未指定目标且当前目录未检测到项目级技能目录 |
+| 4 | 未指定目标且当前目录未检测到项目级技能目录，或 doctor 没有可检查的元阁家族技能 |
 | 5 | 装前 gate 阻断或元信不可用 |
 | 6 | manifest / 身份校验失败 |
 

package/scripts/yotta-skills-mcp.py

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

package/skill-manifest.json

@@ -3,7 +3,7 @@
   "slug": "yotta-skills",
   "name": "元阁",
   "package": "@yottameta/yotta-skills",
-  "version": "0.22.1",
+  "version": "0.22.2",
   "trust": "yottameta",
   "install": {
     "idempotent": true