@yottameta/yotta-skills-plugin 0.19.28 → 0.20.1

package/skills/yotta-skills/lib/scan-policy.js

@@ -0,0 +1,209 @@
+'use strict';
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const VERDICT_SAFE = 'SAFE TO INSTALL';
+const VERDICT_CAUTION = 'INSTALL WITH CAUTION';
+const VERDICT_REVIEW = 'REVIEW REQUIRED';
+const VERDICT_BLOCK = 'DO NOT INSTALL';
+
+const VERDICT_BY_SEVERITY = {
+  critical: VERDICT_BLOCK,
+  high: VERDICT_CAUTION,
+  medium: VERDICT_REVIEW,
+  low: VERDICT_SAFE,
+  info: VERDICT_SAFE,
+};
+const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low', 'info'];
+const VERIFY_SCANNER = 'yotta-verify';
+
+// 与 tools/build_opencode_bundle.py（handoff 构建器）逐字节同口径：
+// 例外表绑定 prune 后的技能树 treeHash，技能升版或内容变化后旧例外自动失效（fail-closed）。
+const REMOVE_NAMES = new Set([
+  '.git', '.github', '.gitignore', '.npmignore', 'test', 'bin',
+  'package.json', 'package-lock.json', 'install.sh', 'server.json',
+  '__pycache__', '.pytest_cache', '.mypy_cache',
+]);
+const KEEP_EXTRA = {
+  'yotta-memory': ['bin'],
+  'yotta-skills': ['bin', 'lib', 'skills.json', 'scan-policy.json'],
+};
+const PRUNE_DIRS = new Set(['__pycache__', '.pytest_cache', '.mypy_cache']);
+const HASH_SKIP_FILES = new Set(['.yotta-managed.json']);
+
+function normalizeRel(value) {
+  return String(value == null ? '' : value).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function loadPolicy(policyPath) {
+  try {
+    const raw = fs.readFileSync(policyPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !parsed.skills) return null;
+    return parsed;
+  } catch (_) {
+    return null;
+  }
+}
+
+function keepExtraFor(slug) {
+  return new Set(KEEP_EXTRA[slug] || []);
+}
+
+function collectRows(dir, relBase, keepExtra, depth, rows) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_) {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+    const rel = relBase ? relBase + '/' + entry.name : entry.name;
+    if (entry.isDirectory()) {
+      if (PRUNE_DIRS.has(entry.name)) continue;
+      if (depth === 0 && REMOVE_NAMES.has(entry.name) && !keepExtra.has(entry.name)) continue;
+      collectRows(path.join(dir, entry.name), rel, keepExtra, depth + 1, rows);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (depth === 0 && REMOVE_NAMES.has(entry.name) && !keepExtra.has(entry.name)) continue;
+    if (entry.name.endsWith('.pyc') || entry.name.endsWith('.pyo')) continue;
+    if (HASH_SKIP_FILES.has(rel)) continue;
+    let data;
+    try {
+      data = fs.readFileSync(path.join(dir, entry.name));
+    } catch (_) {
+      continue;
+    }
+    rows.push({ rel, hash: crypto.createHash('sha256').update(data).digest('hex') });
+  }
+}
+
+function computeTreeHash(pkgDir, slug) {
+  const rows = [];
+  collectRows(pkgDir, '', keepExtraFor(slug), 0, rows);
+  rows.sort((a, b) => Buffer.compare(Buffer.from(a.rel, 'utf8'), Buffer.from(b.rel, 'utf8')));
+  const manifest = rows.map((row) => Buffer.concat([
+    Buffer.from(row.rel, 'utf8'),
+    Buffer.from('\0', 'ascii'),
+    Buffer.from(row.hash, 'ascii'),
+    Buffer.from('\n', 'ascii'),
+  ]));
+  const digest = crypto.createHash('sha256').update(Buffer.concat(manifest)).digest('hex');
+  return 'sha256:' + digest;
+}
+
+function summarize(findings) {
+  const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+  for (const finding of findings) {
+    const severity = finding && finding.severity;
+    if (Object.prototype.hasOwnProperty.call(counts, severity)) counts[severity] += 1;
+  }
+  let verdict = VERDICT_SAFE;
+  for (const severity of SEVERITY_ORDER) {
+    if (counts[severity]) {
+      verdict = VERDICT_BY_SEVERITY[severity];
+      break;
+    }
+  }
+  return { counts, verdict };
+}
+
+function exceptionMatches(exception, finding) {
+  if (!exception || exception.action !== 'allow') return false;
+  const scanners = Array.isArray(exception.scanners) ? exception.scanners : [];
+  if (scanners.length > 0 && !scanners.includes(VERIFY_SCANNER)) return false;
+  if (String(exception.rule || '') !== String(finding.rule_id || '')) return false;
+  return normalizeRel(exception.path) === normalizeRel(finding.file);
+}
+
+/**
+ * 用随包分发的 scanPolicy 例外表复核元信扫描结果。
+ *
+ * 绑定校验（缺一即不生效，fail-closed）：skill 条目存在 + version 一致 + treeHash 一致。
+ * 只有 action=allow 且 scanners 含 yotta-verify 的例外才会豁免对应 (rule, path) 发现。
+ */
+function applyScanPolicy(scan, context) {
+  const ctx = context || {};
+  const base = {
+    applied: false,
+    reason: null,
+    excluded: 0,
+    excludedFindings: [],
+    version: null,
+    treeHash: null,
+  };
+  const result = { ...scan, policy: base };
+  if (!scan || !scan.ok) {
+    result.policy.reason = 'scan-failed';
+    return result;
+  }
+  const policy = ctx.policy;
+  const slug = ctx.slug;
+  const version = ctx.version;
+  const pkgDir = ctx.pkgDir;
+  if (!policy || !slug || !pkgDir) {
+    result.policy.reason = 'policy-unavailable';
+    return result;
+  }
+  const entry = policy.skills[slug];
+  if (!entry) {
+    result.policy.reason = 'no-entry';
+    return result;
+  }
+  if (!Array.isArray(scan.findings)) {
+    result.policy.reason = 'findings-unavailable';
+    return result;
+  }
+  if (entry.version !== version) {
+    result.policy.reason = 'version-mismatch';
+    return result;
+  }
+  const treeHash = computeTreeHash(pkgDir, slug);
+  result.policy.version = entry.version;
+  result.policy.treeHash = treeHash;
+  if (entry.treeHash !== treeHash) {
+    result.policy.reason = 'treehash-mismatch';
+    return result;
+  }
+  const exceptions = Array.isArray(entry.exceptions) ? entry.exceptions : [];
+  const kept = [];
+  for (const finding of scan.findings) {
+    const hit = exceptions.find((exception) => exceptionMatches(exception, finding));
+    if (hit) {
+      result.policy.excludedFindings.push({
+        rule: finding.rule_id,
+        path: normalizeRel(finding.file),
+        severity: finding.severity,
+        reason: hit.reason || null,
+      });
+      continue;
+    }
+    kept.push(finding);
+  }
+  const summary = summarize(kept);
+  result.policy.applied = true;
+  result.policy.reason = 'applied';
+  result.policy.excluded = result.policy.excludedFindings.length;
+  result.verdict = summary.verdict;
+  result.counts = summary.counts;
+  result.findings = kept;
+  return result;
+}
+
+module.exports = {
+  VERDICT_SAFE,
+  VERDICT_CAUTION,
+  VERDICT_REVIEW,
+  VERDICT_BLOCK,
+  REMOVE_NAMES,
+  KEEP_EXTRA,
+  normalizeRel,
+  loadPolicy,
+  computeTreeHash,
+  summarize,
+  exceptionMatches,
+  applyScanPolicy,
+};

package/skills/yotta-skills/lib/verify-gate.js

@@ -48,11 +48,17 @@ function parseScanOutput(stdout) {
   try {
     const value = JSON.parse(String(stdout || ''));
     if (!value || typeof value.verdict !== 'string') {
-      return { ok: false, verdict: null, counts: null, error: '扫描输出缺少 verdict' };
+      return { ok: false, verdict: null, counts: null, findings: null, error: '扫描输出缺少 verdict' };
     }
-    return { ok: true, verdict: value.verdict, counts: value.counts || {}, error: null };
+    return {
+      ok: true,
+      verdict: value.verdict,
+      counts: value.counts || {},
+      findings: Array.isArray(value.findings) ? value.findings : null,
+      error: null,
+    };
   } catch (error) {
-    return { ok: false, verdict: null, counts: null, error: error.message };
+    return { ok: false, verdict: null, counts: null, findings: null, error: error.message };
   }
 }
 
@@ -62,22 +68,70 @@ function evaluateVerdict(verdict) {
   return { decision: 'block', block: true, warn: true };
 }
 
-function runVerifier(engine, target, options) {
-  const result = options.spawnSync(options.python, ['-B', engine, 'scan', target, '--json'], {
+function runScanOnce(engine, target, options) {
+  return options.spawnSync(options.python, ['-B', engine, 'scan', target, '--json'], {
     encoding: 'utf8',
     timeout: 60000,
+    maxBuffer: 32 * 1024 * 1024,
   });
+}
+
+function stderrBrief(result) {
+  const text = String((result && result.stderr) || '').trim();
+  if (!text) return '';
+  return text.split(/\r?\n/).filter(Boolean).slice(-2).join(' | ').slice(0, 300);
+}
+
+/**
+ * 元信扫描是只读幂等操作：解析失败（空输出 / 截断 / 进程异常）时重试一次，
+ * 避免偶发的子进程抖动把安装判死；两次都失败才按阻断处理。
+ */
+function runVerifier(engine, target, options) {
+  const opts = options || {};
+  const retries = opts.retries === undefined ? 1 : Math.max(0, Number(opts.retries) || 0);
+  let result = null;
+  let parsed = null;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    result = runScanOnce(engine, target, opts);
+    if (!result || result.error || result.status === null) {
+      parsed = null;
+      continue;
+    }
+    parsed = parseScanOutput(result.stdout);
+    if (parsed.ok) break;
+  }
   if (result && result.error) {
-    return { ok: false, verdict: null, counts: null, error: result.error.message, exitCode: null };
+    return { ok: false, verdict: null, counts: null, findings: null, error: result.error.message, exitCode: null };
   }
   if (!result || result.status === null) {
-    return { ok: false, verdict: null, counts: null, error: '元信 scan 执行失败', exitCode: null };
+    return {
+      ok: false,
+      verdict: null,
+      counts: null,
+      findings: null,
+      error: '元信 scan 执行失败（超时或无法启动）',
+      exitCode: null,
+    };
   }
-  const parsed = parseScanOutput(result.stdout);
-  if (!parsed.ok) {
-    return { ok: false, verdict: null, counts: null, error: parsed.error, exitCode: result.status };
+  if (!parsed || !parsed.ok) {
+    const brief = stderrBrief(result);
+    return {
+      ok: false,
+      verdict: null,
+      counts: null,
+      findings: null,
+      error: '元信 scan 输出无法解析（exit ' + result.status + '）' + (brief ? ': ' + brief : ''),
+      exitCode: result.status,
+    };
   }
-  return { ok: true, verdict: parsed.verdict, counts: parsed.counts, error: null, exitCode: result.status };
+  return {
+    ok: true,
+    verdict: parsed.verdict,
+    counts: parsed.counts,
+    findings: parsed.findings,
+    error: null,
+    exitCode: result.status,
+  };
 }
 
 module.exports = {

package/skills/yotta-skills/references/install-flow.md

@@ -85,6 +85,9 @@
   与 `bootstrap_scan=self`，随后用元信扫描其余家族包；
 - verdict 处置：`SAFE TO INSTALL` 继续；`INSTALL WITH CAUTION` / `REVIEW REQUIRED`
   继续但显示风险并留证；`DO NOT INSTALL` 和扫描失败阻断，不替换目标；
+- scanPolicy 复核：`DO NOT INSTALL` 时用包内 `scan-policy.json` 的已审查例外复核（逐条绑定
+  skill + version + treeHash + 规则 + 路径；缺失 / 不匹配一律 fail-closed）；豁免后无阻断级
+  发现则继续，显示 `↳ scanPolicy 复核：豁免 N 条已审查发现` 并把 `scan_policy` 写进安装证据；
 - `--skip-scan` 只保留为人工应急路径，使用时输出 `explicit-unverified` 并写入证据；
 - `update --auto` 始终执行装前门禁，不接受 `--skip-scan`。
 

package/skills/yotta-skills/references/provider-protocol.md

@@ -0,0 +1,101 @@
+# 扩展提供方协议 v1（元阁 · capability `o1.route`）
+
+元阁可以可选地调用一个由用户显式配置的**本地扩展提供方（provider）**，由它在已装技能白名单内
+对静态路由结果做增补 / 重排。未配置提供方时，`--route` 的行为与输出与之前完全一致。
+
+## 1. 配置
+
+配置文件：`<YOTTA_PROVIDER_HOME>/provider.json`，默认 `~/.yottameta/provider.json`。
+环境变量 `YOTTA_PROVIDER_HOME` 可覆盖根目录（测试与隔离环境用）。
+
+```json
+{
+  "schema": 1,
+  "providers": [
+    {
+      "id": "local-provider",
+      "version": "0.1.0",
+      "capabilities": ["o1.route"],
+      "command": ["node", "C:/path/to/provider.js"],
+      "timeout_ms": 600
+    }
+  ]
+}
+```
+
+- `command` 必须是**数组**（argv 语义），以 `shell: false` 执行；不接受字符串命令。
+- `timeout_ms` 默认 600，最小 50，最大 5000；超时即回落。
+- 配置文件缺失、解析失败、`command` 非数组、capability 未知：**只记录状态，不阻断命令**；缺失等同「未安装」。
+
+## 2. 调用
+
+- 只在用户显式执行 `--route`（CLI）或 `route_request`（MCP，内部走同一 CLI）时触发；安装 / 更新 / 盘点等路径不触发。
+- 元阁把**一个 JSON 请求**写入 provider 的 stdin（随后关闭），从 stdout 读**一个 JSON 响应**；stderr 只作诊断。
+- stdout 上限 256 KB；超过按错误处理并回落。
+
+```json
+{
+  "schema": 1,
+  "capability": "o1.route",
+  "request_id": "<uuid>",
+  "payload": {
+    "request": "帮我做发布前质量检查",
+    "static_result": {
+      "playbook": "delivery-quality-gate",
+      "confidence": "high",
+      "skills": ["yotta-anti-shallow", "yotta-code-quality", "yotta-publish-guard"]
+    },
+    "installed_skills": [
+      { "slug": "yotta-code-quality", "version": "0.3.0", "sources": ["Codex"] }
+    ]
+  }
+}
+```
+
+## 3. 响应
+
+```json
+{
+  "ok": true,
+  "capability": "o1.route",
+  "data": {
+    "skills": [
+      { "slug": "yotta-code-quality", "role": "可选：补充代码质量评审" },
+      { "slug": "yotta-anti-shallow" }
+    ]
+  }
+}
+```
+
+- `skills[].slug` 必须 ∈ `installed_skills` 白名单；未安装或未知的 slug 会被丢弃并记入 `dropped`，不会写入结果。
+- `role` 可选；缺省时增补条目使用「由扩展提供方补充」。
+- 元阁先算静态结果：provider 给出的顺序用于重排；静态结果中未被提及的技能会**追加保留**，不会丢失。
+- 返回空列表 / 全是不合法 slug：视为未应用（`applied = false`），静态结果原样返回。
+
+需要授权或不可用时：
+
+```json
+{ "ok": false, "code": "license_required", "message": "该能力需要授权后使用" }
+```
+
+## 4. 状态与回落
+
+| 状态 | 触发 | 元阁行为 |
+| --- | --- | --- |
+| `not_installed` | 无配置 / 无匹配 capability | 纯静态路由，文本输出与历史一致 |
+| `active` | 调用成功且响应合法 | 白名单内增补 / 重排，静态结果保留 |
+| `license_required` | provider 明确返回该 code | 纯静态路由 +「需授权」提示 |
+| `timeout` | 超过 `timeout_ms` | 纯静态路由 + 一行状态提示 |
+| `invalid_output` | 非 JSON / 缺 `ok` | 纯静态路由 + 一行状态提示 |
+| `error` | 启动失败 / 退出码非 0 / 输出超限 / 配置非法 | 纯静态路由 + 一行状态提示 |
+
+`--json` 输出始终包含 `dynamic` 块：`status` / `provider_id` / `applied` / `added` / `dropped` / `note`；
+CLI 文本输出只在状态非 `not_installed` 时多一行「动态路由: ...」，退出码不受影响（始终 0）。
+
+## 5. 审计与边界
+
+- 每次实际调用写一行 `<YOTTA_PROVIDER_HOME>/provider-audit.jsonl`：`ts` / `capability` / `provider_id` / `status` / `duration_ms` / `bytes_out`。
+- 审计**不记录**需求原文或任何 payload 内容。
+- 元阁不替 provider 联网；provider 自身行为由它自己的包声明。
+- 删除 `provider.json` 即回到纯静态路由，无残留依赖。
+- provider 输出只当数据使用：白名单外的 slug、非法结构一律丢弃，不作为指令执行。

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

@@ -8,7 +8,7 @@
 | `yotta-anti-shallow` | 元谨 | `@yottameta/yotta-anti-shallow` | 1.4.1 | 防 AI 敷衍规则引擎（深入分析/根因追溯时激活） |
 | `yotta-code-quality` | 元质 | `@yottameta/yotta-code-quality` | 0.4.1 | 结对式代码质量评审（十二类腐化风险 + 0-100 健康分） |
 | `yotta-workflow` | 元序 | `@yottameta/yotta-workflow` | 0.4.2 | 跨会话/跨项目通用工作流协议（状态就近存） |
-| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.18.1 | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
+| `yotta-memory` | 元忆 | `@yottameta/yotta-memory` | 0.19.0 | 有权限边界的文件式智能体记忆（FACT/PREF/BOUND/COMMIT） |
 | `yotta-learn` | 元习 | `@yottameta/yotta-learn` | 0.2.1 | 学习沉淀 CLI：错误/纠正/洞见沉淀为 .learnings/ 条目 |
 | `yotta-security-audit` | 元安 | `@yottameta/yotta-security-audit` | 0.3.0 | 安全扫描引擎：13 类检测器 + 系统安全基线 + 学生数据隐私（教育版） |
 | `yotta-vetter` | 元审 | `@yottameta/yotta-vetter` | 0.2.6 | 安全审查协议：四阶段 review + SAFE TO INSTALL 判定 |