@yottameta/yotta-skills 0.1.0

package/references/install-flow.md

@@ -0,0 +1,68 @@
+# 安装器工作原理（install-flow）
+
+> 面向想了解 yotta-skills 内部机制的开发者；日常使用请读 `SKILL.md` 或中文教程
+> （`references/tutorial.md`）。
+
+## 总体流程
+
+对每个待装技能：
+
+1. 读清单（`skills.json`，默认随包；`YOTTA_SKILLS_MANIFEST` 可覆盖）；
+2. `npm pack <pkg>@<spec> --pack-destination <临时目录>`；
+3. 系统 `tar -xzf` 解压到临时目录（产物应有 `SKILL.md`）；
+4. 元信装前摘要（若引擎可用；`--skip-scan` 关闭）；
+5. 删除目标 `<dest>/<slug>` 后重新复制（跳过规则见下）；
+6. 汇总报告：✔ 成功 / - 跳过（已是最新）/ ✘ 失败；有失败项时退出码 1。
+
+## 复制跳过规则
+
+- 顶层跳过：`package.json` / `bin` / `node_modules` / `.git` / `__pycache__`；
+- 任意层级跳过：`.pytest_cache` / `.mypy_cache` 目录、`*.pyc` / `*.pyo` 文件。
+
+因此装进技能目录的是「技能本体」（SKILL.md / references / scripts 等），不含 npm
+安装器自身、测试夹具与 Python 字节码缓存。
+
+## 幂等与版本判断
+
+- 读取目标 `<dest>/<slug>/SKILL.md` 的 frontmatter `version`；
+- 与清单 `version` 一致 → 跳过（幂等：第二次安装 22 个全部跳过）；
+- `--force` 强制重装；`update` 对「缺失 / 版本不一致」的技能重装。
+
+## 版本策略
+
+- 默认 range：spec = `<pkg>@<major>.x`（如 `0.x`），`npm pack` 取同 major 最新 patch；
+- `--pin`：spec = `<pkg>@<清单精确版本>`。
+
+## npm 解析（Windows）
+
+- 优先：`where.exe npm.cmd` → 读同目录 `node_modules/npm/bin/npm-cli.js` → 用 node 直接执行
+  （npm.cmd 直跑在 Windows 有 EINVAL，`cmd /c` 引号脆弱；npm-cli.js 直跑无 shell 变量坑）；
+- `--npm` / `YOTTA_SKILLS_NPM`：`.js` → node 执行；`.cmd/.bat` → 同样解析 npm-cli.js；
+  其它 → 直接执行；
+- `YOTTA_SKILLS_NPM_FLAGS` 追加到 `npm pack` 参数。
+
+## 元信装前摘要
+
+- 引擎查找：`--verify` → `YOTTA_SKILLS_VERIFY` → `<dest>/yotta-verify/scripts/yotta_verify.py`；
+- python 查找：`--python` → `YOTTA_SKILLS_PYTHON` → `python3` / `python` / `py`（win32）；
+- 执行：`python -B <engine> scan <解压目录> --json`（`-B` 禁止写 `__pycache__`，防止污染
+  引擎所在目录）；
+- 输出 verdict + counts（critical / high / medium / low / info）；DO NOT INSTALL 额外提示
+  人工复核；仅摘要、不拦截。
+
+## 退出码
+
+| 退出码 | 含义 |
+|---|---|
+| 0 | 成功（含全部跳过） |
+| 1 | 安装 / 更新存在失败项 |
+| 2 | 用法错误（未知参数 / 未知技能 / 未收录智能体） |
+| 4 | 未指定目标且当前目录未检测到项目级技能目录 |
+
+## 目标目录解析
+
+- `--dir`：直接使用（技能落在 `<dir>/<slug>`）；
+- `--agent`：查内置 17 智能体表（codex 特判 `$CODEX_HOME/skills`；opencode 特判
+  `$XDG_CONFIG_HOME/opencode/skills`；其余 `~/.<agent>/skills` 或 `~/.config/...`）；
+- 都未指定：检测当前目录是否存在项目级技能目录（`.claude/skills`、`.codex/skills`、
+  `.agents/skills` 等 17 个），存在则用之；否则退出码 4。

package/references/skill-list.md

@@ -0,0 +1,40 @@
+# 全家技能清单（22 个）
+
+> 机器权威源：`skills.json`（随包分发）；本文件为人工可读副本，新技能发布后须同步更新
+> `skills.json`（登记表为内部台账，不随包分发）。清单更新日期：2026-08-29。
+
+| 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 | 跨会话/跨项目通用工作流协议（状态就近存 .workflow） |
+| `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-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-skill-creator` | 元造 | `@yottameta/yotta-skill-creator` | 0.1.0 | 工坊「造」：端到端造技能脚手架 |
+| `yotta-publish-guard` | 元守 | `@yottameta/yotta-publish-guard` | 0.1.1 | 工坊「守」：发布前守门（版本四件对齐 + 三通道查重） |
+| `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-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 + 危险模式） |
+
+## 家族分布
+
+- 安全与护栏（12）：元安 / 元审 / 元析 / 元盾 / 元测 / 元安全 / 元察 / 元情 / 元钥 / 元链 / 元鉴 / 元信
+- 质量与工程（4）：元谨 / 元质 / 元造 / 元守
+- 记忆与上下文（3）：元忆 / 元史 / 元习
+- 写作与表达（1）：元真
+- 工作流（1）：元序
+- 入口与引导（1）：元引
+
+合计 22 个已发布技能；本安装器自身（yotta-skills / 元阁）归「分发与安装」家族。

package/references/tutorial.md

@@ -0,0 +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` 则锁定清单版本。

package/skills.json

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