@yottameta/yotta-skills 0.19.28 → 0.20.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## v0.20.1 (2026-09-29)
+- 家族安装接入 scanPolicy 例外复核：元信判 `DO NOT INSTALL` 时，按包内 `scan-policy.json` 的已审查例外（逐条绑定技能 + 版本 + treeHash + 规则 + 路径）复核，豁免检测规则表 / 攻防样例 / 文档说明类命中；复核后无阻断级发现则继续安装。
+- 修复元忆 / 元察 / 元鉴从元阁安装时被元信自指误报阻断的问题（检测类技能自带规则表字面量）；例外表与 handoff / OpenCode 的 scanPolicy 同源，由 `tools/build_scan_policy.py` 生成。
+- 技能升版或内容变化后旧例外自动失效（treeHash 绑定，fail-closed），安装回到元信原始判定。
+- 安装日志新增 `scan_policy` 字段（是否应用 / 豁免条数 / version / treeHash）。
+- 元信扫描输出解析失败（空输出 / 截断 / 子进程抖动）自动重试一次；仍失败时报错带退出码与 stderr 摘要。
+- 静态 playbook / 路由 / hook 契约零变更。
+
+## v0.20.0 (2026-09-28)
+- 新增 `o1.route` 动态扩展口：`--route` / MCP `route_request` 可选调用用户配置的本地扩展提供方（provider），在已装注册表白名单内增补 / 重排路由结果。
+- 静态 playbook 结果先算必算；未配置或未授权 / 超时 / 非法输出时一律回落静态结果，文本输出与历史一致，`--json` 增加 `dynamic` 状态块。
+- 清单同步：元忆 pin 0.19.0。
+- 协议与配置见 `references/provider-protocol.md`。
+
 ## v0.19.28 (2026-09-28)
 
 清单同步元盾 `0.1.7`（代码围栏占位符修复 20 处 / 非法转义告警与致命异常退出码 fail-open 修复 / 彩色输出路径在真人终端崩溃修复 / 新增宿主接入说明）。

package/README.md

@@ -26,7 +26,7 @@ Installing the whole YottaMeta family used to mean running <code>npx</code> for
 元阁 is also the **family orchestration planner**: given a task, check the orchestration table first — which skills to combine, in what order, and why — then install exactly those. The decision table ships in the package as <code>references/orchestration.md</code> and is summarized in <code>SKILL.md</code>.
 
 - **List** - see the whole family: slug, Chinese name, package, version and a one-line description.
-- **Orchestration routing** - <code>--route</code> turns a task summary into a candidate combination, call order, per-skill roles, confidence, evidence, installed/missing status, and an install command; it only suggests installation and never installs automatically.
+- **Orchestration routing** - <code>--route</code> turns a task summary into a candidate combination, call order, per-skill roles, confidence, evidence, installed/missing status, and an install command; it only suggests installation and never installs automatically. An optional local provider may add or re-order installed skills within the allow-list (no behavior change when unconfigured; see <code>references/provider-protocol.md</code>).
 - **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).
@@ -110,7 +110,7 @@ Requirements: Node.js 18+, npm, and system <code>tar</code> (built into Windows
 | `--registry <url>` | npm registry to check against (default https://registry.npmjs.org/; `YOTTA_SKILLS_REGISTRY` overrides) |
 | `--inventory` | Inventory installed skills: scan skill directories and update the local registry (self-contained); `--json` for JSON, `--project` adds project-level dirs |
 | `--reindex` | Re-index the registry: re-scan skill directories and merge changes incrementally (on demand; `install` / `update` re-index automatically; `--rescan` is a synonym); `--json` for JSON |
-| `--route <task-summary>` | Static orchestration routing: return a combination, call order, per-skill roles, confidence, evidence, installed/missing status, and an install suggestion; also lists other installed (non-YottaMeta) skills as candidates matched mechanically against their frontmatter description, tagged "not scanned", read-only and never auto-invoked; `--json` for JSON, `--project` adds project-level dirs |
+| `--route <task-summary>` | Static orchestration routing: return a combination, call order, per-skill roles, confidence, evidence, installed/missing status, and an install suggestion; also lists other installed (non-YottaMeta) skills as candidates matched mechanically against their frontmatter description, tagged "not scanned", read-only and never auto-invoked; an optional local provider may add or re-order installed skills within the allow-list (see <code>references/provider-protocol.md</code>); `--json` for JSON plus a `dynamic` status block, `--project` adds project-level dirs |
 | `--no-reindex` | Do not re-index the registry automatically after `install` / `update` |
 | `--dry-run` | Preview the install / update list; no network, no changes |
 | `--pin` | Lock the exact manifest versions (default) |

package/README.zh-CN.md

@@ -29,7 +29,7 @@
 元阁也是全家的**编排策划层**：接到需求先查「编排策划」组合表——该组合哪几个技能、按什么顺序、各自强在哪——然后给出安装与调用**建议**，由用户确认后执行。决策表随包提供（<code>references/orchestration.md</code>），<code>SKILL.md</code> 中有摘要。
 
 - **看清单**--全家技能一览：slug / 中文名 / 包名 / 版本 / 一句话说明。
-- **编排路由**--`--route` 按需求摘要输出候选组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装命令；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；只建议安装，不自动安装。
+- **编排路由**--`--route` 按需求摘要输出候选组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装命令；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；只建议安装，不自动安装。可选本地扩展提供方可在已装白名单内增补 / 重排（未配置时行为不变），协议见 `references/provider-protocol.md`。
 - **安装**——装全家（或指定技能）到智能体默认用户级目录或任意目录。
 - **更新**——增量更新：补齐缺失技能、升级版本不一致的技能。
 - **更新检查 / 自动更新**——<code>update --check</code> 只读比对已装技能版本与 npm 注册表并报告；<code>update --check --scheduled</code> 是后台周检入口，用本地缓存和随机抖动做到未到期不联网；<code>update --auto</code> 检查后自动把已装元阁家族升到最新（非元阁家族技能绝不自动更新）。
@@ -113,7 +113,7 @@ npx -y @yottameta/yotta-skills --reindex
 | `--registry <url>` | 检查的 npm registry 地址（默认 https://registry.npmjs.org/；`YOTTA_SKILLS_REGISTRY` 覆盖） |
 | `--inventory` | 盘点已装技能：扫描技能目录并更新本地注册表（自包含）；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `--reindex` | 重扫注册表：扫描技能目录并增量合并变化（install / update 完成后自动重扫，也可随时手动运行；`--rescan` 同义）；`--json` 输出 JSON |
-| `--route <需求摘要>` | 静态编排路由：输出组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装建议；`--json` 输出 JSON、`--project` 附扫项目级目录 |
+| `--route <需求摘要>` | 静态编排路由：输出组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装建议；可选本地扩展提供方在已装白名单内增补 / 重排（未配置时行为不变，协议见 `references/provider-protocol.md`）；`--json` 输出 JSON 与 `dynamic` 状态块、`--project` 附扫项目级目录 |
 | `--no-reindex` | 安装 / 更新后不自动重扫注册表 |
 | `--dry-run` | 预览将执行的安装 / 更新清单；不联网、不改动 |
 | `--pin` | 锁死清单精确版本（默认） |

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-skills
-version: 0.19.28
+version: 0.20.1
 description: 元阁 -- 元阁全家技能的总编排策划 + 编排路由 + 一键安装器 + 技能盘点 + 运行时 hook 适配。路由层：--route / route_request 按需求摘要给出候选组合、调用顺序、角色、置信度、依据、已装/缺失状态与安装命令，只建议不自动安装；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么组合使用（安装与调用均由用户确认后执行）」；安装层：一条命令把 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，不常驻，未加载降级 CLI）。支持 --list 清单 / --route 路由 / 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）：只做「组合策划 + 静态路由建议 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index + hook 适配」，不含技能本体、不做技能内容开发、不 -g 污染全局、不自动安装缺失技能、不静默写宿主配置或全局记忆；家族安装先自举或调用元信装前门禁，DO NOT INSTALL 阻断，非元阁家族包不自动安装。
 license: MIT
 metadata:
@@ -43,6 +43,7 @@ metadata:
 **元阁全家的总编排策划 + 编排路由 + 一键安装 + 技能盘点**，一句话四层：
 
 - **路由层（该用哪几个）**：`--route "<需求摘要>"` / MCP `route_request` 查本地注册表与静态编排 playbook，输出候选组合、调用顺序、每个技能角色、置信度、依据、已装/缺失状态与安装命令；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；只建议安装，不自动安装。
+- **动态扩展口（v0.20.0，capability `o1.route`）**：可选调用用户显式配置的本地扩展提供方（provider），在已装注册表白名单内对路由结果增补 / 重排；静态 playbook 结果先算必算、永不缺席，未配置或调用失败时文本输出与历史一致，`--json` 仅多一个 `dynamic` 状态块。协议与配置见 `references/provider-protocol.md`。
 - **策划层（怎么用）**：接到需求，先按「编排策划」定位命中哪个组合——哪些元技能搭配起来最强、适合什么场景、AI 该给出什么安装与调用建议（**安装与调用均由用户确认后执行**）。
 - **安装层（怎么装）**：一条 `npx -y @yottameta/yotta-skills` 把组合/全家装进指定智能体或目录——`--list` 看清单、`install` 装、`update` 增量更新、`doctor` 只读自检、`rollback` 恢复快照、`--dry-run` 预览、`--pin` 锁版本。
 
@@ -347,6 +348,12 @@ npx -y @yottameta/yotta-skills --route "检查代码质量，别糊弄" --json
 - `INSTALL WITH CAUTION` / `REVIEW REQUIRED`：继续安装，但显示风险并写入证据；
 - `DO NOT INSTALL` 或扫描失败：阻断，不替换旧版本。
 
+扫描后元阁会用包内 `scan-policy.json`（已审查例外表）复核：每条例外绑定「技能 + 版本 +
+内容 treeHash + 规则 + 路径」，只豁免检测规则表、攻防样例与文档说明这类已审查命中。
+技能升版或内容有任何变化，旧例外自动失效（fail-closed），安装回到元信原始判定。
+命中例外的安装会显示 `↳ scanPolicy 复核：豁免 N 条已审查发现` 并写入安装证据；
+未命中例外的 `DO NOT INSTALL` 照常阻断。
+
 引擎查找顺序（v0.19.13 收紧）：`--verify` 指定路径 → 环境变量 `YOTTA_SKILLS_VERIFY` →
 **受信安装记录**（`~/.yottaskills/trusted-verifier.json`，由安装管线在元信安装 / 更新成功后写入，
 记录包身份 + 引擎路径 + SHA-256）。候选引擎必须同时满足：路径不经符号链接跳转、

package/bin/yotta-skills.js

@@ -35,10 +35,11 @@ const lifecycleLib = require('../lib/install-lifecycle');
 const snapshotLib = require('../lib/install-snapshot');
 const updateCheckLib = require('../lib/update-check');
 const hookAdapterLib = require('../lib/hook-adapter');
+const scanPolicyLib = require('../lib/scan-policy');
 const { createInstaller, isSafeTarEntry } = require('../lib/install-pipeline');
 
 const PKG_ROOT = path.join(__dirname, '..');
-let VERSION = '0.19.28';
+let VERSION = '0.20.1';
 try { VERSION = require(path.join(PKG_ROOT, 'package.json')).version; } catch (_) { /* keep fallback */ }
 
 function loadManifest() {
@@ -586,22 +587,33 @@ function runScan(engine, skillDir) {
   return gateLib.runVerifier(engine, skillDir, { python, spawnSync });
 }
 
-function scanTarget(engine, skillDir) {
+function scanTarget(engine, skillDir, context) {
   const scan = runScan(engine, skillDir);
-  if (scan.ok) {
-    const counts = scan.counts || {};
-    const line = 'critical ' + (counts.critical || 0) + ' / high ' + (counts.high || 0) +
-      ' / medium ' + (counts.medium || 0) + ' / low ' + (counts.low || 0) +
-      ' / info ' + (counts.info || 0);
-    out('  元信 scan: ' + scan.verdict + '（' + line + '）');
-    if (scan.verdict === gateLib.BLOCK) out('  ⚠ 元信 verdict 为 DO NOT INSTALL，已阻断安装。');
-    else if (scan.verdict === gateLib.CAUTION || scan.verdict === gateLib.REVIEW) {
-      out('  ⚠ 元信 verdict 为 ' + scan.verdict + '，继续安装并保留风险证据。');
-    }
-  } else {
+  if (!scan.ok) {
     out('  元信 scan: ' + scan.error);
-  }
-  return scan;
+    return scan;
+  }
+  const ctx = context || {};
+  const reviewed = scanPolicyLib.applyScanPolicy(scan, {
+    slug: ctx.slug,
+    version: ctx.version,
+    pkgDir: skillDir,
+    policy: scanPolicyLib.loadPolicy(path.join(PKG_ROOT, 'scan-policy.json')),
+  });
+  const counts = scan.counts || {};
+  const line = 'critical ' + (counts.critical || 0) + ' / high ' + (counts.high || 0) +
+    ' / medium ' + (counts.medium || 0) + ' / low ' + (counts.low || 0) +
+    ' / info ' + (counts.info || 0);
+  out('  元信 scan: ' + scan.verdict + '（' + line + '）');
+  if (reviewed.policy && reviewed.policy.applied && reviewed.policy.excluded > 0) {
+    out('  ↳ scanPolicy 复核：豁免 ' + reviewed.policy.excluded +
+      ' 条已审查发现（检测规则 / 文档说明，treeHash 绑定）→ ' + reviewed.verdict);
+  }
+  if (reviewed.verdict === gateLib.BLOCK) out('  ⚠ 元信 verdict 为 DO NOT INSTALL，已阻断安装。');
+  else if (reviewed.verdict === gateLib.CAUTION || reviewed.verdict === gateLib.REVIEW) {
+    out('  ⚠ 元信 verdict 为 ' + reviewed.verdict + '，继续安装并保留风险证据。');
+  }
+  return reviewed;
 }
 
 // ── 安装 ───────────────────────────────────────────────────────────────────
@@ -1202,12 +1214,110 @@ function runReindex(opts) {
   out('注册表: ' + scan.registryPath());
 }
 
+function dynamicBlock(status, providerId, note) {
+  return {
+    status: status || 'not_installed',
+    provider_id: providerId || '',
+    applied: false,
+    added: [],
+    dropped: [],
+    note: note || '',
+  };
+}
+
+/**
+ * o1.route 动态扩展口：静态结果先算必算；provider 只允许在已装注册表白名单内增补 / 重排，
+ * 任何失败都回静态结果（fail-open）。协议见 references/provider-protocol.md。
+ */
+function applyDynamicRoute(result, registry, opts) {
+  const provider = require('../lib/provider');
+  let run;
+  try {
+    run = provider.runCapability('o1.route', {
+      request: String(opts.route || ''),
+      static_result: {
+        playbook: result.playbook.id,
+        confidence: result.confidence,
+        skills: result.skills.map((skill) => skill.slug),
+      },
+      installed_skills: Object.values(registry.skills || {})
+        .filter((record) => record && record.status !== 'gone')
+        .map((record) => ({ slug: record.slug, version: record.version || '', sources: record.sources || [] })),
+    });
+  } catch (e) {
+    return dynamicBlock('error', '', '动态路由装载失败：' + e.message);
+  }
+  const block = dynamicBlock(run.status, run.provider_id, run.note || run.message || '');
+  if (run.status !== 'active' || !run.data || typeof run.data !== 'object') return block;
+
+  const installed = new Set(Object.values(registry.skills || {})
+    .filter((record) => record && record.status !== 'gone')
+    .map((record) => record.slug));
+  const requested = Array.isArray(run.data.skills) ? run.data.skills : [];
+  const seen = new Set();
+  const ordered = [];
+  for (const item of requested) {
+    const slug = item && typeof item === 'object' ? String(item.slug || '') : '';
+    if (!slug) continue;
+    if (seen.has(slug) || !installed.has(slug)) {
+      block.dropped.push(slug);
+      continue;
+    }
+    seen.add(slug);
+    ordered.push({ slug, role: typeof item.role === 'string' ? item.role : '' });
+  }
+  if (!ordered.length) return block;
+
+  const staticBySlug = new Map(result.skills.map((skill) => [skill.slug, skill]));
+  const next = [];
+  for (const item of ordered) {
+    const existing = staticBySlug.get(item.slug);
+    if (existing) {
+      next.push(existing);
+      continue;
+    }
+    const record = registry.skills[item.slug] || {};
+    next.push({
+      slug: item.slug,
+      order: 0,
+      role: item.role || '由扩展提供方补充',
+      installed: true,
+      version: record.version || '',
+      sources: record.sources || [],
+      variants: Array.isArray(record.variants) ? record.variants : [],
+      conflicts: Array.isArray(record.conflicts) ? record.conflicts : [],
+    });
+  }
+  for (const skill of result.skills) {
+    if (!next.some((item) => item.slug === skill.slug)) next.push(skill);
+  }
+  next.forEach((skill, index) => { skill.order = index + 1; });
+  block.added = next.filter((skill) => !staticBySlug.has(skill.slug)).map((skill) => skill.slug);
+  block.applied = true;
+  result.skills = next;
+  return block;
+}
+
+function dynamicRouteText(block) {
+  if (!block) return '';
+  if (block.status === 'active') {
+    const who = block.provider_id ? '提供方 ' + block.provider_id : '提供方';
+    return '已应用（' + who + '；新增 ' + block.added.length + ' / 丢弃 ' + block.dropped.length + '）';
+  }
+  if (block.status === 'license_required') return '需授权（该能力需要授权后使用；静态路由不受影响）';
+  if (block.status === 'timeout') return '未生效（提供方超时，已回落静态路由）';
+  if (block.status === 'invalid_output') return '未生效（提供方输出无效，已回落静态路由）';
+  if (block.status === 'error') return '未生效（提供方异常，已回落静态路由）';
+  return block.status;
+}
+
 /** --route：静态编排路由，输出组合、顺序、角色、缺失技能建议与其他已装技能候选。 */
 function runRoute(opts) {
   const { routeRequest, defaultYottaSlugs } = require('../lib/route');
   const { registry } = reindexRegistry(opts);
   const yottaSlugs = new Set([...defaultYottaSlugs(), ...MANIFEST.map((s) => s.slug)]);
   const result = routeRequest(opts.route, { registry, yottaSlugs });
+  result.dynamic = applyDynamicRoute(result, registry, opts);
   if (opts.json) {
     out(JSON.stringify(result, null, 2));
     return;
@@ -1244,6 +1354,10 @@ function runRoute(opts) {
     }
     out('安全提示: 其他已装技能只读 frontmatter description 做机械匹配，不读取全文指令、不自动调用；使用/安装前请先执行装前安全扫描，决定权在用户。');
   }
+  if (result.dynamic.status !== 'not_installed') {
+    out('');
+    out('动态路由: ' + dynamicRouteText(result.dynamic));
+  }
   out('');
   out('应用模式: 显式调用（可经用户确认后切换为按场景自动调用）');
   out('说明: ' + result.disclaimer);

package/install.sh

@@ -89,7 +89,7 @@ install_to() {
       rm -rf -- "$dest/$item"
     fi
   done
-  for item in SKILL.md skill-manifest.json references scripts assets skills.json LICENSE NOTICE README.md README.zh-CN.md CHANGELOG.md USER_GUIDE.md; do
+  for item in SKILL.md skill-manifest.json references scripts assets skills.json scan-policy.json LICENSE NOTICE README.md README.zh-CN.md CHANGELOG.md USER_GUIDE.md; do
     if [ -e "$SOURCE_DIR/$item" ]; then
       cp -RP "$SOURCE_DIR/$item" "$dest/"
     fi

package/lib/install-pipeline.js

@@ -148,7 +148,10 @@ function createInstaller(deps) {
           safeRecord({ event: 'before_install', skill: skill.slug, decision: 'block', error: gate.error });
           return { skill, status: 'fail', version: packed.resolved, note: gate.error, exitCode: 5 };
         }
-        const scanResult = deps.scanTarget(gate.engine, extracted.pkgDir);
+        const scanResult = deps.scanTarget(gate.engine, extracted.pkgDir, {
+          slug: skill.slug,
+          version: packed.resolved,
+        });
         if (!scanResult.ok) {
           safeRecord({ event: 'before_install', skill: skill.slug, decision: 'block', error: scanResult.error });
           return { skill, status: 'fail', version: packed.resolved, note: scanResult.error, exitCode: 5 };
@@ -193,6 +196,7 @@ function createInstaller(deps) {
             decision: 'block',
             verdict: scanResult.verdict,
             counts: scanResult.counts,
+            scan_policy: scanResult.policy || null,
             hook_decision: hookEvaluation.decision,
           });
           return {
@@ -208,6 +212,7 @@ function createInstaller(deps) {
           verdict: scanResult.verdict,
           counts: scanResult.counts,
           warn: verdict.warn,
+          policy: scanResult.policy || null,
         };
       }
 
@@ -332,6 +337,7 @@ function createInstaller(deps) {
           bootstrap_scan: gate.mode === 'trusted-bootstrap' && skill.slug === 'yotta-verify' ? 'self' : null,
           verdict: scan.verdict,
           decision: scan.decision,
+          scan_policy: scan.policy || null,
           snapshot,
         });
       } catch (error) {

package/lib/provider.js

@@ -0,0 +1,248 @@
+'use strict';
+
+// 扩展提供方（provider）装载器 v1：外部子进程 + stdin/stdout JSON。
+// 设计：docs/路线B-P1-接口预留设计-2026-09-28.md（根仓库）；对外协议：references/provider-protocol.md。
+// 零依赖；未配置 / 任何失败都 fail-open 回开源基线，不阻断调用方。
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const SCHEMA = 1;
+const DEFAULT_TIMEOUT_MS = 600;
+const MAX_TIMEOUT_MS = 5000;
+const MIN_TIMEOUT_MS = 50;
+const MAX_STDOUT_BYTES = 256 * 1024;
+const KNOWN_CAPABILITIES = ['o1.route', 'm1.adjudicate', 'memory.hook', 'context.paging'];
+
+function providerHome() {
+  const fromEnv = process.env.YOTTA_PROVIDER_HOME;
+  if (fromEnv && String(fromEnv).trim()) return path.resolve(String(fromEnv).trim());
+  return path.join(os.homedir(), '.yottameta');
+}
+
+function configPath() {
+  return path.join(providerHome(), 'provider.json');
+}
+
+function validateProvider(item) {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return 'provider 条目必须是对象';
+  if (!item.id || typeof item.id !== 'string') return 'provider 缺 id';
+  if (!Array.isArray(item.capabilities) || !item.capabilities.length) return 'provider ' + item.id + ' 缺 capabilities';
+  for (const capability of item.capabilities) {
+    if (KNOWN_CAPABILITIES.indexOf(capability) === -1) return 'provider ' + item.id + ' 含未知 capability：' + capability;
+  }
+  if (!Array.isArray(item.command) || !item.command.length) return 'provider ' + item.id + ' 的 command 必须是数组';
+  for (const part of item.command) {
+    if (typeof part !== 'string' || !part) return 'provider ' + item.id + ' 的 command 含非法参数';
+    if (part.indexOf('\0') !== -1) return 'provider ' + item.id + ' 的 command 含非法字符';
+  }
+  if (item.timeout_ms !== undefined && (!Number.isFinite(item.timeout_ms) || item.timeout_ms <= 0)) {
+    return 'provider ' + item.id + ' 的 timeout_ms 非法';
+  }
+  return '';
+}
+
+function normalizeProvider(item) {
+  return {
+    id: item.id,
+    version: typeof item.version === 'string' ? item.version : '',
+    capabilities: item.capabilities.slice(),
+    command: item.command.slice(),
+    timeout_ms: Math.min(MAX_TIMEOUT_MS, Math.max(MIN_TIMEOUT_MS, Math.round(item.timeout_ms || DEFAULT_TIMEOUT_MS))),
+  };
+}
+
+function readConfig() {
+  const file = configPath();
+  if (!fs.existsSync(file)) return { status: 'not_installed', providers: [], error: '' };
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    return { status: 'error', providers: [], error: 'provider.json 解析失败：' + e.message };
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { status: 'error', providers: [], error: 'provider.json 必须是对象' };
+  }
+  if (raw.schema !== SCHEMA) {
+    return { status: 'error', providers: [], error: 'provider.json schema 不支持：' + String(raw.schema) };
+  }
+  if (!Array.isArray(raw.providers)) {
+    return { status: 'error', providers: [], error: 'provider.json providers 必须是数组' };
+  }
+  const providers = [];
+  for (const item of raw.providers) {
+    const invalid = validateProvider(item);
+    if (invalid) return { status: 'error', providers: [], error: invalid };
+    providers.push(normalizeProvider(item));
+  }
+  return { status: 'ok', providers, error: '' };
+}
+
+function pickProvider(config, capability) {
+  if (!config || config.status !== 'ok') return null;
+  for (const item of config.providers) {
+    if (item.capabilities.indexOf(capability) !== -1) return item;
+  }
+  return null;
+}
+
+function minimalEnv() {
+  const keep = [
+    'PATH', 'Path', 'PATHEXT', 'SystemRoot', 'windir', 'COMSPEC', 'ComSpec',
+    'TEMP', 'TMP', 'HOME', 'USERPROFILE', 'LANG', 'LC_ALL',
+  ];
+  const env = {};
+  for (const key of keep) {
+    if (process.env[key] !== undefined) env[key] = process.env[key];
+  }
+  env.YOTTA_PROVIDER_HOME = providerHome();
+  return env;
+}
+
+function requestId() {
+  try {
+    if (typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  } catch (e) {
+    // 回退到随机 hex
+  }
+  return crypto.randomBytes(16).toString('hex');
+}
+
+function invokeProvider(provider, capability, payload) {
+  const started = Date.now();
+  const request = {
+    schema: SCHEMA,
+    capability,
+    request_id: requestId(),
+    payload: payload || {},
+  };
+  let proc;
+  try {
+    proc = spawnSync(provider.command[0], provider.command.slice(1), {
+      input: JSON.stringify(request),
+      encoding: 'utf8',
+      timeout: provider.timeout_ms,
+      maxBuffer: MAX_STDOUT_BYTES,
+      shell: false,
+      cwd: providerHome(),
+      env: minimalEnv(),
+      windowsHide: true,
+    });
+  } catch (e) {
+    return {
+      status: 'error',
+      provider_id: provider.id,
+      duration_ms: Date.now() - started,
+      note: 'provider 启动失败：' + e.message,
+    };
+  }
+  const duration = Date.now() - started;
+  if (proc.error) {
+    const code = proc.error.code || '';
+    const timedOut = code === 'ETIMEDOUT';
+    const oversize = code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER';
+    return {
+      status: timedOut ? 'timeout' : 'error',
+      provider_id: provider.id,
+      duration_ms: duration,
+      note: timedOut
+        ? 'provider 超时'
+        : (oversize
+          ? 'provider 输出超过 ' + MAX_STDOUT_BYTES + ' 字节'
+          : 'provider 执行失败：' + (code || proc.error.message || 'unknown')),
+    };
+  }
+  if (proc.status !== 0) {
+    return {
+      status: 'error',
+      provider_id: provider.id,
+      duration_ms: duration,
+      note: 'provider 退出码非 0：' + proc.status,
+    };
+  }
+  let response;
+  try {
+    response = JSON.parse(String(proc.stdout || '').trim() || '{}');
+  } catch (e) {
+    return { status: 'invalid_output', provider_id: provider.id, duration_ms: duration, note: 'provider 输出不是 JSON' };
+  }
+  if (!response || typeof response !== 'object' || Array.isArray(response)) {
+    return { status: 'invalid_output', provider_id: provider.id, duration_ms: duration, note: 'provider 输出不是对象' };
+  }
+  if (response.ok === false) {
+    const code = typeof response.code === 'string' && response.code ? response.code : 'provider_error';
+    return {
+      status: code === 'license_required' ? 'license_required' : 'error',
+      provider_id: provider.id,
+      code,
+      message: typeof response.message === 'string' ? response.message : '',
+      duration_ms: duration,
+      note: typeof response.message === 'string' ? response.message : code,
+    };
+  }
+  if (response.ok !== true) {
+    return { status: 'invalid_output', provider_id: provider.id, duration_ms: duration, note: 'provider 响应缺 ok 字段' };
+  }
+  return {
+    status: 'active',
+    provider_id: provider.id,
+    data: response.data,
+    duration_ms: duration,
+    bytes_out: Buffer.byteLength(String(proc.stdout || ''), 'utf8'),
+    note: '',
+  };
+}
+
+function appendAudit(entry) {
+  try {
+    const home = providerHome();
+    fs.mkdirSync(home, { recursive: true });
+    fs.appendFileSync(
+      path.join(home, 'provider-audit.jsonl'),
+      JSON.stringify(Object.assign({ schema: SCHEMA, ts: new Date().toISOString() }, entry)) + '\n',
+      'utf8',
+    );
+  } catch (e) {
+    // 审计失败不影响调用
+  }
+}
+
+function runCapability(capability, payload) {
+  const config = readConfig();
+  if (config.status === 'not_installed') {
+    return { status: 'not_installed', provider_id: '', note: '未配置扩展提供方' };
+  }
+  if (config.status === 'error') {
+    return { status: 'error', provider_id: '', note: config.error };
+  }
+  const provider = pickProvider(config, capability);
+  if (!provider) {
+    return { status: 'not_installed', provider_id: '', note: '未配置声明 ' + capability + ' 的提供方' };
+  }
+  const result = invokeProvider(provider, capability, payload);
+  appendAudit({
+    capability,
+    provider_id: result.provider_id,
+    status: result.status,
+    duration_ms: result.duration_ms,
+    bytes_out: result.bytes_out || 0,
+  });
+  return result;
+}
+
+module.exports = {
+  SCHEMA,
+  DEFAULT_TIMEOUT_MS,
+  MAX_TIMEOUT_MS,
+  MAX_STDOUT_BYTES,
+  KNOWN_CAPABILITIES,
+  providerHome,
+  configPath,
+  readConfig,
+  pickProvider,
+  runCapability,
+};