@yottameta/yotta-skills 0.1.2 → 0.2.0

package/references/tutorial.md

@@ -1,106 +1,106 @@
-# 元阁中文教程（新手全流程）
-
-> 配套技能：元阁 yotta-skills（全家技能一键安装 CLI，依赖 Node.js 18+ / npm / 系统 tar）。
-> 目标：把元阁已发布的 22 个 `yotta-*` 技能一次装进指定智能体或目录，并学会预览、更新、
-> 锁版本与常见排查。
-
-## 1. 教程目标与前置
-
-- 学会 `--list` / `install` / `update` / `--dry-run` / `--pin` / `--force` 的用法；
-- 理解版本策略（range 与 --pin）与幂等行为；
-- 掌握元信装前摘要的开关与配置；
-- 前置：Node.js 18+、npm、系统 tar（Windows 10+ 自带）；网络可访问 npm 注册表
-  （国内可配置镜像或代理）。
-
-## 2. 查看全家清单
-
-```bash
-npx -y @yottameta/yotta-skills --list
-```
-
-输出 22 个技能：slug / 中文名 / 包名与版本范围 / 清单版本 / 一句话说明。
-确认某个技能在不在清单里，可加技能名过滤：
-
-```bash
-npx -y @yottameta/yotta-skills --list yotta-memory
-```
-
-## 3. 安装全家到智能体
-
-推荐用 `--agent` 装到指定智能体默认用户级目录（如 Codex）：
-
-```bash
-npx -y @yottameta/yotta-skills install --agent codex
-```
-
-支持 17 个智能体键名：`claude` / `cursor` / `codex` / `gemini` / `goose` / `amp` /
-`opencode` / `windsurf` / `workbuddy` / `kiro` / `trae` / `trae-cn` / `qwen` / `comate` /
-`codebuddy` / `kimi` / `agents`。未收录的智能体用 `--dir` 指到它的技能目录。
-
-## 4. 安装到任意目录
-
-```bash
-npx -y @yottameta/yotta-skills install --dir ~/my-skills
-```
-
-每个技能落在 `<dir>/<slug>`（如 `~/my-skills/yotta-memory/`）。
-只装个别技能：
-
-```bash
-npx -y @yottameta/yotta-skills install yotta-memory yotta-verify --dir ~/my-skills
-```
-
-## 5. 更新已装技能
-
-```bash
-npx -y @yottameta/yotta-skills update --agent codex
-```
-
-- 缺失的技能 → 补装；版本不一致的技能 → 按当前版本策略重装；
-- 已是最新的技能显示「已是最新」并跳过（幂等）。
-
-## 6. 安装前预览
-
-```bash
-npx -y @yottameta/yotta-skills --dry-run
-```
-
-dry-run 只打印将要执行的清单（含目标与版本策略），不联网、不写任何文件。
-
-## 7. 版本策略：range 与 --pin
-
-- 默认 range：按同 major 最新 patch（如 `0.x`），维护性更新随最新；
-- 想完全可复现 → 加 `--pin` 锁死清单精确版本：
-
-```bash
-npx -y @yottameta/yotta-skills install --agent codex --pin
-```
-
-## 8. 强制重装与跳过元信摘要
-
-```bash
-npx -y @yottameta/yotta-skills install --agent codex --force     # 已是最新也重装
-npx -y @yottameta/yotta-skills install --agent codex --skip-scan # 跳过装前摘要
-```
-
-元信（yotta-verify）已安装时默认会对每个待装技能输出装前摘要（verdict + 计数），仅提示
-不拦截；verdict 为 DO NOT INSTALL 时会提示人工复核。
-
-## 9. 验证安装结果
-
-- 看安装汇总：成功 N / 跳过 N / 失败 N；
-- 抽查技能目录：`ls ~/.codex/skills/yotta-memory/SKILL.md`；
-- 复核版本：每个技能 SKILL.md 的 frontmatter `version` 应与 `--list` 一致（这也是幂等
-  判断的依据）。
-
-## 10. 常见问题
-
-- **npmmirror 全新包 404**：镜像同步有延迟。设置环境变量 `YOTTA_SKILLS_NPM_FLAGS` 为
-  `--registry=https://registry.npmjs.org/`（国内需代理）再执行，或等待镜像缓存后重试。
-- **`--agent` 报未收录**：改用 `--dir` 指到该智能体的技能目录（`.agents/skills` 不是
-  通用目录）。
-- **某技能安装失败**：汇总报告给出失败原因；可单装该技能排查：
-  `install <slug> --dir <path>`。
-- **目标未指定**：当前目录没有项目级技能目录时报错（退出码 4），加 `--agent` 或
-  `--dir`。
-- **已有旧版本**：默认按 range 覆盖升级到最新 patch；`--pin` 则锁定清单版本。
+# 元阁中文教程（新手全流程）
+
+> 配套技能：元阁 yotta-skills（全家技能一键安装 CLI，依赖 Node.js 18+ / npm / 系统 tar）。
+> 目标：把元阁已发布的 22 个 `yotta-*` 技能一次装进指定智能体或目录，并学会预览、更新、
+> 锁版本与常见排查。
+
+## 1. 教程目标与前置
+
+- 学会 `--list` / `install` / `update` / `--dry-run` / `--pin` / `--force` 的用法；
+- 理解版本策略（range 与 --pin）与幂等行为；
+- 掌握元信装前摘要的开关与配置；
+- 前置：Node.js 18+、npm、系统 tar（Windows 10+ 自带）；网络可访问 npm 注册表
+  （国内可配置镜像或代理）。
+
+## 2. 查看全家清单
+
+```bash
+npx -y @yottameta/yotta-skills --list
+```
+
+输出 22 个技能：slug / 中文名 / 包名与版本范围 / 清单版本 / 一句话说明。
+确认某个技能在不在清单里，可加技能名过滤：
+
+```bash
+npx -y @yottameta/yotta-skills --list yotta-memory
+```
+
+## 3. 安装全家到智能体
+
+推荐用 `--agent` 装到指定智能体默认用户级目录（如 Codex）：
+
+```bash
+npx -y @yottameta/yotta-skills install --agent codex
+```
+
+支持 17 个智能体键名：`claude` / `cursor` / `codex` / `gemini` / `goose` / `amp` /
+`opencode` / `windsurf` / `workbuddy` / `kiro` / `trae` / `trae-cn` / `qwen` / `comate` /
+`codebuddy` / `kimi` / `agents`。未收录的智能体用 `--dir` 指到它的技能目录。
+
+## 4. 安装到任意目录
+
+```bash
+npx -y @yottameta/yotta-skills install --dir ~/my-skills
+```
+
+每个技能落在 `<dir>/<slug>`（如 `~/my-skills/yotta-memory/`）。
+只装个别技能：
+
+```bash
+npx -y @yottameta/yotta-skills install yotta-memory yotta-verify --dir ~/my-skills
+```
+
+## 5. 更新已装技能
+
+```bash
+npx -y @yottameta/yotta-skills update --agent codex
+```
+
+- 缺失的技能 → 补装；版本不一致的技能 → 按当前版本策略重装；
+- 已是最新的技能显示「已是最新」并跳过（幂等）。
+
+## 6. 安装前预览
+
+```bash
+npx -y @yottameta/yotta-skills --dry-run
+```
+
+dry-run 只打印将要执行的清单（含目标与版本策略），不联网、不写任何文件。
+
+## 7. 版本策略：range 与 --pin
+
+- 默认 range：按同 major 最新 patch（如 `0.x`），维护性更新随最新；
+- 想完全可复现 → 加 `--pin` 锁死清单精确版本：
+
+```bash
+npx -y @yottameta/yotta-skills install --agent codex --pin
+```
+
+## 8. 强制重装与跳过元信摘要
+
+```bash
+npx -y @yottameta/yotta-skills install --agent codex --force     # 已是最新也重装
+npx -y @yottameta/yotta-skills install --agent codex --skip-scan # 跳过装前摘要
+```
+
+元信（yotta-verify）已安装时默认会对每个待装技能输出装前摘要（verdict + 计数），仅提示
+不拦截；verdict 为 DO NOT INSTALL 时会提示人工复核。
+
+## 9. 验证安装结果
+
+- 看安装汇总：成功 N / 跳过 N / 失败 N；
+- 抽查技能目录：`ls ~/.codex/skills/yotta-memory/SKILL.md`；
+- 复核版本：每个技能 SKILL.md 的 frontmatter `version` 应与 `--list` 一致（这也是幂等
+  判断的依据）。
+
+## 10. 常见问题
+
+- **npmmirror 全新包 404**：镜像同步有延迟。设置环境变量 `YOTTA_SKILLS_NPM_FLAGS` 为
+  `--registry=https://registry.npmjs.org/`（国内需代理）再执行，或等待镜像缓存后重试。
+- **`--agent` 报未收录**：改用 `--dir` 指到该智能体的技能目录（`.agents/skills` 不是
+  通用目录）。
+- **某技能安装失败**：汇总报告给出失败原因；可单装该技能排查：
+  `install <slug> --dir <path>`。
+- **目标未指定**：当前目录没有项目级技能目录时报错（退出码 4），加 `--agent` 或
+  `--dir`。
+- **已有旧版本**：默认按 range 覆盖升级到最新 patch；`--pin` 则锁定清单版本。

package/scripts/yotta-skills-mcp.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""yotta-skills-mcp.py — 元阁（yotta-skills）技能盘点 MCP server。
+
+stdio MCP server（JSON-RPC 2.0，换行分隔），把元阁技能扫描核心暴露为 MCP 工具：
+  list_installed_skills  盘点本机已装技能（读本地注册表；未生成则先扫描一次）
+  describe_skill         查看单个技能详情（slug / 版本 / 功能 / 来源）
+  reindex                强制重新扫描并更新注册表
+
+自包含原则：扫描由元阁自带核心（bin/yotta-skills.js --inventory）完成，
+不依赖任何元技能；数据只写本机 ~/.yottaskills/registry.json，不出本机。
+
+运行：python scripts/yotta-skills-mcp.py
+MCP 客户端配置：
+  {"mcpServers":{"yotta-skills":{"command":"python",
+    "args":["<绝对路径>/scripts/yotta-skills-mcp.py"]}}}
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+VERSION = "0.2.0"
+TOOL_NAME = "yotta-skills"
+CN_NAME = "元阁"
+MCP_PROTOCOL = "2025-03-26"
+SERVERS = {TOOL_NAME: {"name": TOOL_NAME, "cn": CN_NAME, "version": VERSION}}
+
+_HERE = Path(__file__).resolve().parent
+BIN_JS = (_HERE.parent / "bin" / "yotta-skills.js").resolve()
+REGISTRY_FILE = Path(os.path.expanduser("~/.yottaskills/registry.json"))
+
+
+def _tool_error(message, extra=None):
+    payload = {"error": message}
+    if extra:
+        payload.update(extra)
+    return {"content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False, indent=2)}],
+            "isError": True}
+
+
+def _tool_spec(name, description, properties, required=None):
+    return {
+        "name": name,
+        "description": description,
+        "inputSchema": {
+            "type": "object",
+            "properties": properties,
+            **({"required": required} if required else {}),
+        },
+    }
+
+
+def _run_cli(args):
+    """运行元阁 CLI（Node），返回 stdout 文本；失败抛 RuntimeError。"""
+    node = shutil.which("node")
+    if not node:
+        raise RuntimeError("未找到 node 可执行文件（元阁 CLI 依赖 Node.js 18+）")
+    proc = subprocess.run(
+        [node, str(BIN_JS)] + args,
+        capture_output=True, text=True, encoding="utf-8",
+        timeout=120,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError("yotta-skills CLI 失败（exit %s）：%s" % (proc.returncode, (proc.stderr or proc.stdout).strip()[:500]))
+    return proc.stdout
+
+
+def _read_registry():
+    if not REGISTRY_FILE.is_file():
+        return None
+    try:
+        return json.loads(REGISTRY_FILE.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _ensure_registry():
+    """注册表不存在时先扫描生成一次；返回注册表 dict。"""
+    reg = _read_registry()
+    if reg is not None:
+        return reg
+    _run_cli(["--inventory"])
+    reg = _read_registry()
+    if reg is None:
+        raise RuntimeError("技能注册表生成失败（~/.yottaskills/registry.json）")
+    return reg
+
+
+def _skills_list(registry):
+    return sorted(
+        [s for s in registry.get("skills", {}).values() if s.get("status") != "gone"],
+        key=lambda s: s.get("slug", ""),
+    )
+
+
+def _tool_list(arguments):  # noqa: ARG001
+    registry = _ensure_registry()
+    skills = _skills_list(registry)
+    payload = {
+        "count": len(skills),
+        "registry": str(REGISTRY_FILE),
+        "skills": skills,
+    }
+    return {"content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False, indent=2)}],
+            "isError": False}
+
+
+def _tool_describe(arguments):
+    slug = str(arguments.get("slug") or "").strip()
+    if not slug:
+        return _tool_error("describe_skill 需要 slug 参数")
+    registry = _ensure_registry()
+    skill = registry.get("skills", {}).get(slug)
+    if not skill or skill.get("status") == "gone":
+        return _tool_error("未找到技能: %s" % slug)
+    payload = {"skill": skill}
+    return {"content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False, indent=2)}],
+            "isError": False}
+
+
+def _tool_reindex(arguments):  # noqa: ARG001
+    stdout = _run_cli(["--inventory", "--json"])
+    try:
+        data = json.loads(stdout)
+    except json.JSONDecodeError as e:
+        return _tool_error("reindex 输出解析失败：%s" % e)
+    payload = {
+        "count": len(data.get("skills", [])),
+        "changes": data.get("changes"),
+        "errors": data.get("errors"),
+        "registry": str(REGISTRY_FILE),
+    }
+    return {"content": [{"type": "text", "text": json.dumps(payload, ensure_ascii=False, indent=2)}],
+            "isError": False}
+
+
+TOOL_HANDLERS = {
+    "list_installed_skills": _tool_list,
+    "describe_skill": _tool_describe,
+    "reindex": _tool_reindex,
+}
+
+
+def mcp_tools():
+    return [
+        _tool_spec(
+            "list_installed_skills",
+            "盘点本机已装技能：返回技能列表（slug / 版本 / 功能一句话 / 来源）。"
+            "读本地注册表 ~/.yottaskills/registry.json；未生成则先扫描一次。"
+            "扫描由元阁自带核心完成，不依赖任何其他技能。数据不出本机。",
+            {},
+            [],
+        ),
+        _tool_spec(
+            "describe_skill",
+            "查看单个技能的详情（slug / 版本 / 功能 / 来源目录）。",
+            {"slug": {"type": "string", "description": "技能 slug（如 yotta-memory）"}},
+            ["slug"],
+        ),
+        _tool_spec(
+            "reindex",
+            "强制重新扫描所有技能目录并更新本地注册表，返回本次变化（新增 / 更新 / 消失）。",
+            {},
+            [],
+        ),
+    ]
+
+
+def handle_message(msg):
+    """处理一行 JSON-RPC 消息，返回响应 dict；通知返回 None。"""
+    if not isinstance(msg, dict) or msg.get("jsonrpc") != "2.0":
+        rid = msg.get("id") if isinstance(msg, dict) else None
+        return {"jsonrpc": "2.0", "id": rid, "error": {"code": -32600, "message": "invalid request"}}
+    method = msg.get("method")
+    rid = msg.get("id")
+    if rid is None:  # JSON-RPC 通知（无 id）不响应
+        return None
+    if method is None:
+        return None
+    params = msg.get("params") or {}
+
+    if method == "initialize":
+        return {
+            "jsonrpc": "2.0", "id": rid,
+            "result": {
+                "protocolVersion": MCP_PROTOCOL,
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": TOOL_NAME, "version": VERSION},
+            },
+        }
+    if method == "ping":
+        return {"jsonrpc": "2.0", "id": rid, "result": {}}
+    if method == "tools/list":
+        return {"jsonrpc": "2.0", "id": rid, "result": {"tools": mcp_tools()}}
+    if method == "tools/call":
+        name = params.get("name")
+        arguments = params.get("arguments") or {}
+        handler = TOOL_HANDLERS.get(name)
+        if not handler:
+            return {
+                "jsonrpc": "2.0", "id": rid,
+                "result": {"content": [{"type": "text", "text": "未知工具: %s" % name}], "isError": True},
+            }
+        try:
+            return {"jsonrpc": "2.0", "id": rid, "result": handler(arguments)}
+        except Exception as e:  # noqa: BLE001
+            return {
+                "jsonrpc": "2.0", "id": rid,
+                "result": {"content": [{"type": "text", "text": "工具执行异常：%s" % e}], "isError": True},
+            }
+    return {"jsonrpc": "2.0", "id": rid, "error": {"code": -32601, "message": "Method not found: " + str(method)}}
+
+
+def main():
+    """stdio 主循环：读行 -> JSON-RPC -> 响应行。"""
+    try:
+        sys.stdin.reconfigure(encoding="utf-8")
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except Exception:  # noqa: BLE001
+        pass
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            sys.stdout.write(json.dumps(
+                {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "parse error"}},
+                ensure_ascii=False) + "\n")
+            sys.stdout.flush()
+            continue
+        resp = handle_message(msg)
+        if resp is not None:
+            sys.stdout.write(json.dumps(resp, ensure_ascii=False) + "\n")
+            sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

package/skills.json

@@ -1,6 +1,6 @@
 {
   "manifestVersion": 1,
-  "updated": "2026-08-29",
+  "updated": "2026-08-30",
   "note": "清单同步要求：每次技能发布新版本后，按 YottaSkills 技能登记表更新本文件（登记表为内部台账，不随包分发）。",
   "skills": [
     {
@@ -22,13 +22,13 @@
       "name": "元序",
       "pkg": "@yottameta/yotta-workflow",
       "version": "0.2.6",
-      "desc": "跨会话/跨项目通用工作流协议（状态就近存 .workflow）"
+      "desc": "跨会话/跨项目通用工作流协议（状态就近存）"
     },
     {
       "slug": "yotta-memory",
       "name": "元忆",
       "pkg": "@yottameta/yotta-memory",
-      "version": "0.8.4",
+      "version": "0.8.5",
       "desc": "有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT）"
     },
     {
@@ -36,20 +36,20 @@
       "name": "元习",
       "pkg": "@yottameta/yotta-learn",
       "version": "0.1.4",
-      "desc": "学习闭环 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目"
+      "desc": "学习沉淀 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目"
     },
     {
       "slug": "yotta-security-audit",
       "name": "元安",
       "pkg": "@yottameta/yotta-security-audit",
-      "version": "0.1.7",
+      "version": "0.2.2",
       "desc": "安全扫描引擎：13 类检测器 + 系统安全基线"
     },
     {
       "slug": "yotta-vetter",
       "name": "元审",
       "pkg": "@yottameta/yotta-vetter",
-      "version": "0.1.5",
+      "version": "0.2.3",
       "desc": "安全审查协议：四阶段 review + SAFE TO INSTALL 判定"
     },
     {
@@ -84,14 +84,14 @@
       "slug": "yotta-security-testing",
       "name": "元测",
       "pkg": "@yottameta/yotta-security-testing",
-      "version": "0.1.0",
+      "version": "0.2.4",
       "desc": "有纪律的 AI 安全测试方法论 + Scope Guard 五道防线"
     },
     {
       "slug": "yotta-agent-hardening",
       "name": "元安全",
       "pkg": "@yottameta/yotta-agent-hardening",
-      "version": "0.1.0",
+      "version": "0.2.4",
       "desc": "防御向 AI 智能体自身安全加固（配置面静态扫描三域）"
     },
     {
@@ -154,7 +154,7 @@
       "slug": "yotta-verify",
       "name": "元信",
       "pkg": "@yottameta/yotta-verify",
-      "version": "0.1.1",
+      "version": "0.2.2",
       "desc": "装前安全扫描器 + audited 徽章（prompt injection + 危险模式）"
     }
   ]