@yottameta/yotta-skills-plugin 0.6.2 → 0.7.1

package/.agents/plugins/marketplace.json

@@ -12,7 +12,7 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools",
-      "version": "0.6.2",
+      "version": "0.7.1",
       "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
       "interface": {
         "displayName": "元阁 yotta-skills",

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools",
-      "version": "0.6.2",
+      "version": "0.7.1",
       "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
       "interface": {
         "displayName": "元阁 yotta-skills",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-skills-plugin",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "YuanGe (元阁) — orchestration and routing for the YottaMeta skill family, packaged as a YottaMeta Agent Plugin.",
   "license": "MIT",
   "keywords": [

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "yotta-skills",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
   "author": {
     "name": "YottaMeta",

package/skills/yotta-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-skills
-version: 0.6.2
+version: 0.7.1
 description: 元阁 -- 元阁全家技能的总编排策划 + 编排路由 + 一键安装器 + 技能盘点。路由层：--route / route_request 按需求摘要给出候选组合、调用顺序、角色、置信度、依据、已装/缺失状态与安装命令，只建议不自动安装；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么自动装+自动用」；安装层：一条命令把 YottaMeta 已发布的全部 yotta-* 技能装进指定智能体或目录；盘点层：--inventory / --reindex 扫描本机已装技能生成/更新注册表，新装技能自动被发现（install/update 后自动 re-index，会话开工可先跑 --reindex 与 update --check（联网只读检查更新）；自包含零依赖，不依赖任何元技能）；MCP 按需加载（可选：list_installed_skills/describe_skill/reindex/route_request，不常驻，未加载降级 CLI）。支持 --list 清单 / --route 路由 / install / update / update --check（只读检查）/ update --auto（家族自动更新）/ --inventory / --reindex / --dry-run 预览 / --pin 锁版本。触发：需要批量安装或更新元阁全家技能、按场景组合多个元技能、路由或判断该用哪些技能、盘点或查看本机已装技能、重扫技能注册表、给某个智能体或目录一次性铺齐 yotta-* 技能、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/检查更新/自动更新/该用哪个技能/路由技能/盘点技能/查看已装技能 等。边界（Do NOT trigger）：只做「组合策划 + 静态路由建议 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index」，不含技能本体、不做技能内容开发、不 -g 污染全局、不自动安装缺失技能；装前摘要仅供参考，安装决策由用户确认。
 license: MIT
 metadata:
@@ -272,3 +272,5 @@ npx -y @yottameta/yotta-skills --route "检查代码质量，别糊弄" --json
 - 全家技能清单（人工可读版）：`references/skill-list.md`（机器权威源为 `skills.json`）。
 - 内部机制：`references/install-flow.md`。
 - 新手中文教程：`references/tutorial.md`。
+- 常见问题：`references/faq.md`。
+- 复杂场景走查：`references/walkthroughs.md`。

package/skills/yotta-skills/bin/yotta-skills.js

@@ -35,7 +35,7 @@ function loadManifest() {
   try {
     data = JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch (e) {
-    die('无法读取技能清单: ' + file + '（' + e.message + '）');
+    die('无法读取技能清单: ' + file + '（' + e.message + '）', 2, '检查 YOTTA_SKILLS_MANIFEST 或 skills.json 是否存在且为合法 JSON。');
   }
   const list = Array.isArray(data) ? data : data.skills;
   if (!Array.isArray(list) || list.length === 0) die('技能清单为空: ' + file);
@@ -85,8 +85,9 @@ function resolveUserDir(rel) {
 }
 
 // ── 工具函数 ───────────────────────────────────────────────────────────────
-function die(msg, code) {
+function die(msg, code, hint) {
   process.stderr.write('错误：' + msg + '\n');
+  if (hint) process.stderr.write('修复建议：' + hint + '\n');
   process.exit(code === undefined ? 2 : code);
 }
 function out(s) { process.stdout.write(s + '\n'); }
@@ -141,7 +142,7 @@ function parseArgs(argv) {
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    const take = (name) => { const v = argv[i + 1]; if (v === undefined || v.startsWith('--')) die(name + ' 缺少参数值'); i++; return v; };
+    const take = (name) => { const v = argv[i + 1]; if (v === undefined || v.startsWith('--')) die(name + ' 缺少参数值', 2, '请为该选项提供一个非空值；可用 --help 查看用法。'); i++; return v; };
     if (a === '--list' || a === '-l') opts.list = true;
     else if (a === '--dry-run') opts.dryRun = true;
     else if (a === '--pin') opts.pin = true;
@@ -152,7 +153,7 @@ function parseArgs(argv) {
     else if (a === '--inventory' || a === '--inv') opts.inventory = true;
     else if (a === '--route') {
       const value = argv[i + 1];
-      if (value === undefined || value.startsWith('--')) die('--route 缺少需求摘要');
+      if (value === undefined || value.startsWith('--')) die('--route 缺少需求摘要', 2, '请提供一句需求描述，例如 --route "帮我做发布前质量检查"。');
       opts.route = value;
       i++;
     }
@@ -168,7 +169,7 @@ function parseArgs(argv) {
     else if (a === '--check') opts.check = true;
     else if (a === '--auto') opts.auto = true;
     else if (a === '--registry') opts.registry = take('--registry');
-    else if (a.startsWith('-')) die('未知参数: ' + a);
+    else if (a.startsWith('-')) die('未知参数: ' + a, 2, '可用 --help 查看支持的选项。');
     else positionals.push(a);
   }
   // 命令解析：install / update，其余位置参数 = 技能 slug（可多个）
@@ -201,7 +202,7 @@ function selectSkills(opts) {
   const picked = [];
   for (const slug of opts.skills) {
     const s = findSkill(slug);
-    if (!s) die('未知技能: ' + slug + '（可用: yotta-skills --list）');
+    if (!s) die('未知技能: ' + slug + '（可用: yotta-skills --list）', 2, '请先运行 --list 查看技能名，或检查拼写。');
     picked.push(s);
   }
   return picked;
@@ -748,7 +749,7 @@ function main() {
   let dest = resolveTargetDir(opts);
   if (!dest && !opts.dryRun) dest = detectProjectDir();
   if (!dest && command === 'install' && !opts.dryRun) {
-    die('未指定目标：请用 --agent <name> 或 --dir <path>（当前目录未检测到项目级技能目录）。', 4);
+    die('未指定目标：请用 --agent <name> 或 --dir <path>（当前目录未检测到项目级技能目录）。', 4, '未收录智能体也可用 --dir 指定其技能目录。');
   }
 
   if (opts.dryRun) {
@@ -785,4 +786,10 @@ function main() {
   }
 }
 
-main();
+try {
+  main();
+} catch (err) {
+  process.stderr.write('错误：' + (err && err.message ? err.message : String(err)) + '\n');
+  process.stderr.write('修复建议：检查目标目录权限、npm 可用性与网络；可用 --help 查看用法。\n');
+  process.exitCode = 1;
+}

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

@@ -0,0 +1,84 @@
+# 元阁常见问题
+
+## 速查索引
+
+- **安装目标**：未指定目标怎么办 · 支持哪些智能体 · 装完为什么看不到
+- **网络与源**：国内访问慢 · 镜像延迟 · 网络失败
+- **更新**：`update --check` 退出码 · 自动更新边界 · 幂等
+- **版本**：`--pin` 与默认策略 · 清单漂移 · 单技能安装
+- **安全**：装前扫描 · 目标目录校验 · 失败恢复
+
+---
+
+## 1. 安装时提示「未指定目标」怎么办？
+
+这表示当前目录没有检测到项目级技能目录。两种解决方式：
+
+```bash
+npx -y @yottameta/yotta-skills --agent codex
+npx -y @yottameta/yotta-skills --dir /path/to/skills
+```
+
+`--agent` 使用内置智能体默认目录；`--dir` 适合自定义目录或未收录智能体。
+
+## 2. 支持哪些智能体？
+
+内置 17 个键名：`claude`、`cursor`、`codex`、`gemini`、`goose`、`amp`、`opencode`、`windsurf`、`workbuddy`、`kiro`、`trae`、`trae-cn`、`qwen`、`comate`、`codebuddy`、`kimi`、`agents`。未收录的智能体用 `--dir` 指定目录。
+
+## 3. 国内访问 npm 慢或失败怎么办？
+
+可用 `YOTTA_SKILLS_NPM_FLAGS` 追加 registry 参数：
+
+```bash
+YOTTA_SKILLS_NPM_FLAGS="--registry=https://registry.npmmirror.com" npx -y @yottameta/yotta-skills --agent codex
+```
+
+新版本发布后镜像可能有延迟；如需立即获取，可临时改回 npm 官方源并配置代理。
+
+## 4. `update --check` 的退出码是什么意思？
+
+- `0`：全部最新
+- `3`：存在可更新技能
+- `1`：检查失败（网络或 registry 异常）
+
+该命令只读，不修改文件。
+
+## 5. `update --auto` 会更新所有技能吗？
+
+只自动更新元阁家族内技能（`yotta-*` 且在清单中）。其他已装技能只提示，不自动改动。
+
+## 6. 重复安装会重复占空间吗？
+
+不会。默认按清单版本判断，已一致的技能跳过；需要强制覆盖时加 `--force`。
+
+## 7. `--pin` 和默认版本策略怎么选？
+
+默认策略是同 major 跟随最新 patch，适合日常使用；`--pin` 锁定清单精确版本，适合可复现部署。
+
+## 8. 为什么清单和文档版本会不一致？
+
+人工文档可能滞后。机器权威源是 `skills.json`，人工可读副本是 `references/skill-list.md`；当前版本已加入自动测试，两者不一致会导致测试失败。
+
+## 9. 如何只安装部分技能？
+
+```bash
+npx -y @yottameta/yotta-skills install yotta-memory yotta-workflow --agent codex
+```
+
+也可以先用 `--route` 查看建议组合，再按需安装。
+
+## 10. 安装前安全扫描怎么用？
+
+默认会查找可用的元信引擎并输出摘要；可用 `--verify <path>` 指定引擎，或 `--skip-scan` 关闭。扫描结果仅提示，不替代人工判断。
+
+## 11. 安装失败后如何恢复？
+
+查看汇总中的失败原因，先修复目录权限或网络，再单独安装失败技能：
+
+```bash
+npx -y @yottameta/yotta-skills install <slug> --dir /path/to/skills
+```
+
+## 12. 装完为什么智能体里看不到？
+
+确认安装目录与智能体实际读取目录一致；安装后通常需要重启会话或重新加载技能列表。

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

@@ -1,32 +1,32 @@
 # 全家技能清单（22 个）
 
 > 机器权威源：`skills.json`（随包分发）；本文件为人工可读副本，新技能发布后须同步更新
-> `skills.json`（登记表为内部台账，不随包分发）。清单更新日期：2026-08-29。
+> `skills.json`（登记表为内部台账，不随包分发）。清单更新日期：2026-09-09。
 
 | slug | 中文名 | npm 包 | 清单版本 | 说明 |
 |---|---|---|---|---|
-| `yotta-anti-shallow` | 元谨 | `@yottameta/yotta-anti-shallow` | 1.3.4 | 防 AI 敷衍规则引擎（深入分析/根因追溯时激活） |
-| `yotta-code-quality` | 元质 | `@yottameta/yotta-code-quality` | 0.3.4 | 结对式代码质量评审（十二类腐化风险 + 0-100 健康分） |
-| `yotta-workflow` | 元序 | `@yottameta/yotta-workflow` | 0.2.6 | 跨会话/跨项目通用工作流协议（状态就近存） |
-| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.8.4 | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
-| `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.1.4 | 学习沉淀 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目 |
-| `yotta-security-audit` | 元安 | `@yottameta/yotta-security-audit` | 0.1.7 | 安全扫描引擎：13 类检测器 + 系统安全基线 |
-| `yotta-vetter` | 元审 | `@yottameta/yotta-vetter` | 0.1.5 | 安全审查协议：四阶段 review + SAFE TO INSTALL 判定 |
+| `yotta-anti-shallow` | 元谨 | `@yottameta/yotta-anti-shallow` | 1.4.0 | 防 AI 敷衍规则引擎（深入分析/根因追溯时激活） |
+| `yotta-code-quality` | 元质 | `@yottameta/yotta-code-quality` | 0.4.0 | 结对式代码质量评审（十二类腐化风险 + 0-100 健康分） |
+| `yotta-workflow` | 元序 | `@yottameta/yotta-workflow` | 0.3.0 | 跨会话/跨项目通用工作流协议（状态就近存） |
+| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.11.0 | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
+| `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.2.0 | 学习沉淀 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目 |
+| `yotta-security-audit` | 元安 | `@yottameta/yotta-security-audit` | 0.2.2 | 安全扫描引擎：13 类检测器 + 系统安全基线 |
+| `yotta-vetter` | 元审 | `@yottameta/yotta-vetter` | 0.2.3 | 安全审查协议：四阶段 review + SAFE TO INSTALL 判定 |
 | `yotta-recon` | 元析 | `@yottameta/yotta-recon` | 0.1.5 | 跨智能体网络侦察：零依赖端口/服务/版本指纹探测 |
 | `yotta-guardian` | 元盾 | `@yottameta/yotta-guardian` | 0.1.2 | 跨智能体危险调用拦截护栏：确定性规则 + 可插拔意图验证 |
-| `yotta-humanize` | 元真 | `@yottameta/yotta-humanize` | 0.1.2 | 去 AI 味中文写作编辑：检测器引擎 |
-| `yotta-logs` | 元史 | `@yottameta/yotta-logs` | 0.2.2 | 跨智能体历史会话 / 记忆日志检索 |
-| `yotta-security-testing` | 元测 | `@yottameta/yotta-security-testing` | 0.1.0 | 有纪律的 AI 安全测试方法论 + Scope Guard 五道防线 |
-| `yotta-agent-hardening` | 元安全 | `@yottameta/yotta-agent-hardening` | 0.1.0 | 防御向 AI 智能体自身安全加固（配置面静态扫描三域） |
+| `yotta-humanize` | 元真 | `@yottameta/yotta-humanize` | 0.2.0 | 去 AI 味中文写作编辑：检测器引擎 |
+| `yotta-logs` | 元史 | `@yottameta/yotta-logs` | 0.3.0 | 跨智能体历史会话 / 记忆日志检索 |
+| `yotta-security-testing` | 元测 | `@yottameta/yotta-security-testing` | 0.3.0 | 有纪律的 AI 安全测试方法论 + Scope Guard 五道防线 |
+| `yotta-agent-hardening` | 元安全 | `@yottameta/yotta-agent-hardening` | 0.2.4 | 防御向 AI 智能体自身安全加固（配置面静态扫描三域） |
 | `yotta-skill-creator` | 元造 | `@yottameta/yotta-skill-creator` | 0.1.0 | 工坊「造」：端到端造技能脚手架 |
-| `yotta-publish-guard` | 元守 | `@yottameta/yotta-publish-guard` | 0.1.1 | 工坊「守」：发布前守门（版本四件对齐 + 三通道查重） |
+| `yotta-publish-guard` | 元守 | `@yottameta/yotta-publish-guard` | 0.3.0 | 工坊「守」：发布前守门（版本四件对齐 + 三通道查重） |
 | `yotta-logwatch` | 元察 | `@yottameta/yotta-logwatch` | 0.2.7 | 安全日志分析检测引擎（攻击链识别/告警聚合） |
-| `yotta-intel` | 元情 | `@yottameta/yotta-intel` | 0.1.1 | 威胁情报 IOC 提取与规范化引擎（STIX-lite） |
-| `yotta-secret` | 元钥 | `@yottameta/yotta-secret` | 0.1.2 | 密钥 / 凭据泄露源头扫描引擎 |
+| `yotta-intel` | 元情 | `@yottameta/yotta-intel` | 0.2.0 | 威胁情报 IOC 提取与规范化引擎（STIX-lite） |
+| `yotta-secret` | 元钥 | `@yottameta/yotta-secret` | 0.2.0 | 密钥 / 凭据泄露源头扫描引擎 |
 | `yotta-chain` | 元链 | `@yottameta/yotta-chain` | 0.1.2 | 供应链依赖校验引擎 |
 | `yotta-triage` | 元鉴 | `@yottameta/yotta-triage` | 0.1.1 | 恶意样本静态初筛引擎（哈希/熵/字符串/PE-ELF） |
-| `yotta-prompt` | 元引 | `@yottameta/yotta-prompt` | 0.1.1 | 意图澄清 + 生态入口（常驻注入，map 串联元阁全家） |
-| `yotta-verify` | 元信 | `@yottameta/yotta-verify` | 0.1.1 | 装前安全扫描器 + audited 徽章（prompt injection + 危险模式） |
+| `yotta-prompt` | 元引 | `@yottameta/yotta-prompt` | 0.2.0 | 意图澄清 + 生态入口（常驻注入，map 串联元阁全家） |
+| `yotta-verify` | 元信 | `@yottameta/yotta-verify` | 0.2.2 | 装前安全扫描器 + audited 徽章（prompt injection + 危险模式） |
 
 ## 家族分布
 

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

@@ -0,0 +1,61 @@
+# 元阁复杂场景走查
+
+## 走查 1：新智能体初始化
+
+目标：在一台新机器上为 Codex 安装元阁家族。
+
+1. 查看清单：
+
+```bash
+npx -y @yottameta/yotta-skills --list
+```
+
+2. 安装到默认目录：
+
+```bash
+npx -y @yottameta/yotta-skills --agent codex
+```
+
+3. 核对结果：输出应包含安装路径与成功 / 跳过 / 失败汇总。
+
+4. 重启会话后输入“列出已装技能”，确认注册表能读取到新技能。
+
+## 走查 2：版本漂移更新
+
+背景：本机已装 22 个技能，其中 5 个版本落后。
+
+1. 只读检查：
+
+```bash
+npx -y @yottameta/yotta-skills update --check --agent codex
+```
+
+2. 根据输出确认可更新清单。
+
+3. 执行增量更新：
+
+```bash
+npx -y @yottameta/yotta-skills update --agent codex
+```
+
+4. 复核：已最新的技能应显示跳过，落后的技能显示更新；失败项单独重装。
+
+## 走查 3：按路由安装单个技能
+
+用户需求：“帮我做发布前质量检查。”
+
+1. 路由：
+
+```bash
+npx -y @yottameta/yotta-skills --route "发布前质量检查"
+```
+
+2. 输出建议组合与缺失技能。
+
+3. 只安装缺失技能：
+
+```bash
+npx -y @yottameta/yotta-skills install yotta-code-quality yotta-anti-shallow --agent codex
+```
+
+4. 重新执行路由，确认缺失技能已补齐。

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

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