@yottameta/yotta-skills 0.22.2 → 0.23.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## v0.23.1 (2026-10-01)
+
+- 文档：环境变量表补齐 `YOTTA_SKILLS_REGISTRY_FILE` / `YOTTA_SKILLS_USAGE_FILE` / `YOTTA_PROVIDER_HOME` 三项，并新增「隔离环境：三个状态文件成组导出」小节（bash / PowerShell 示例）——测试、CI 与多 agent 场景需三件成组导出，避免读写宿主真实状态。
+- 行为零变更：安装 / 更新 / 路由 / hook / MCP 契约不变。
+
+## v0.23.0 (2026-10-01)
+
+- O1 动态路由 MVP：`--route` / MCP `route_request` 在静态 playbook 之上，可选调用本地 provider（capability `o1.route`）做确定性组合排序；新增 `confidence` / `reasons` / `summary` / `alternatives` 输出。
+- 开源侧新增 `lib/route-features.js`（请求特征 + 已装技能元数据 + 聚合使用信号 + 公开 playbook 元数据）与 `lib/route-dynamic.js`（白名单 / 枚举 / 限长校验）；静态技能始终保留，provider 不能删除静态技能或改变 `missing_skills` 语义。
+- `usage` 默认关闭；仅显式启用后向本地 provider 发送聚合计数（used / named / accepted / route_hits / distinct_pairs / last_signal_at），不发送需求原文、记忆正文、路径或身份信息；provider 审计仍只记元数据。
+- 非元阁家族技能仍只作候选并标注 `scan_required`；不自动安装、不自动调用。
+- 评分算法位于本地私有目录 `license/o1/`，不进任何发布件；未配置 / 未授权 / 超时 / 非法输出时回落静态路由，退出码保持 0。
+- 元忆 0.20.0 不变；安装 / 更新 / hook / scanPolicy 契约零变更。
+
 ## v0.22.2 (2026-09-30)
 
 - 修复 `doctor --dir` 指向单个技能包目录时的 UX：现在会按 `SKILL.md` / `skill-manifest.json` / 目录名自动识别技能身份，不再误报「目标目录下没有可检查的元阁家族技能」。

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. 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>).
+- **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 and return <code>confidence</code> / <code>reasons</code> / <code>summary</code> / <code>alternatives</code> (no behavior change when unconfigured; see <code>references/provider-protocol.md</code>).
 - **M1 memory adjudication** - <code>decide-memory</code> returns read-only <code>promote / hold / demote</code> suggestions, scores and signal details. Scoring is performed by a user-configured local provider (capability <code>m1.adjudicate</code>). It is read-only by default; <code>--promote</code> writes only a local recommendation file and never writes memory or deletes anything. <code>usage</code> is off by default and records only structured signals after the user enables it.
 - **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.
@@ -121,7 +121,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; 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 |
+| `--route <task-summary>` | 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 and return <code>confidence</code> / <code>reasons</code> / <code>summary</code> / <code>alternatives</code> (see <code>references/provider-protocol.md</code>); `--json` for JSON plus a `dynamic` status block, `--project` adds project-level dirs |
 | `usage status` / `usage enable` / `usage disable` | Inspect / enable / disable local structured usage signals; off by default and limited to slug, time, signal type, playbook / confidence and skill pairs |
 | `usage mark --skill <slug> --signal used\|named\|accepted` | Record one explicit usage signal; no prior enable required |
 | `usage reset --yes` | Clear the local usage record |

package/README.zh-CN.md

@@ -29,7 +29,7 @@
 元阁也是全家的**编排策划层**：接到需求先查「编排策划」组合表——该组合哪几个技能、按什么顺序、各自强在哪——然后给出安装与调用**建议**，由用户确认后执行。决策表随包提供（<code>references/orchestration.md</code>），<code>SKILL.md</code> 中有摘要。
 
 - **看清单**--全家技能一览：slug / 中文名 / 包名 / 版本 / 一句话说明。
-- **编排路由**--`--route` 按需求摘要输出候选组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装命令；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；只建议安装，不自动安装。可选本地扩展提供方可在已装白名单内增补 / 重排（未配置时行为不变），协议见 `references/provider-protocol.md`。
+- **编排路由**--`--route` 按需求摘要输出候选组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装命令；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；只建议安装，不自动安装。可选本地扩展提供方可在已装白名单内增补 / 重排，并返回 `confidence` / `reasons` / `summary` / `alternatives`（未配置时行为不变），协议见 `references/provider-protocol.md`。
 - **M1 记忆裁决**--`decide-memory` 输出技能 `promote / hold / demote` 只读建议、分数与信号明细；评分由用户显式配置的本地 provider（capability `m1.adjudicate`）完成。默认只读，`--promote` 只写本地建议文件，不写元忆、不删除内容。`usage` 默认关闭，显式开启后才记录结构化使用信号（不含需求原文）。
 - **安装**——装全家（或指定技能）到智能体默认用户级目录或任意目录。
 - **更新**——增量更新：补齐缺失技能、升级版本不一致的技能。
@@ -124,7 +124,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 <需求摘要>` | 静态编排路由：输出组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装建议；可选本地扩展提供方在已装白名单内增补 / 重排（未配置时行为不变，协议见 `references/provider-protocol.md`）；`--json` 输出 JSON 与 `dynamic` 状态块、`--project` 附扫项目级目录 |
+| `--route <需求摘要>` | 编排路由：输出组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装建议；可选本地扩展提供方在已装白名单内增补 / 重排并返回 `confidence` / `reasons` / `summary` / `alternatives`（未配置时行为不变，协议见 `references/provider-protocol.md`）；`--json` 输出 JSON 与 `dynamic` 状态块、`--project` 附扫项目级目录 |
 | `usage status` / `usage enable` / `usage disable` | 查看 / 开启 / 关闭本地结构化使用记录；默认关闭，只记录 slug、时间、信号类型、playbook / confidence 与组合对 |
 | `usage mark --skill <slug> --signal used\|named\|accepted` | 记录一次显式使用信号；不要求先 enable |
 | `usage reset --yes` | 清空本地使用记录 |

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-skills
-version: 0.22.2
+version: 0.23.1
 description: 元阁 -- 元阁全家技能的总编排策划 + 编排路由 + 一键安装器 + 技能盘点 + 运行时 hook 适配。路由层：--route / route_request 按需求摘要给出候选组合、调用顺序、角色、置信度、依据、已装/缺失状态与安装命令，只建议不自动安装；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；M1 记忆裁决层：usage enable/mark 本地结构化记录 + decide-memory / MCP decide_memory 输出 promote / hold / demote 只读建议（需授权 provider；只建议不删除、不自动写元忆）；策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么组合使用（安装与调用均由用户确认后执行）」；安装层：一条命令把 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/decide_memory，不常驻，未加载降级 CLI）。支持 --list 清单 / --route 路由 / usage 使用记录 / decide-memory 记忆裁决 / 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）：只做「组合策划 + 静态路由建议 + M1 记忆裁决只读建议 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index + hook 适配」，不含技能本体、不做技能内容开发、不 -g 污染全局、不自动安装缺失技能、不静默写宿主配置或全局记忆、不自动删除技能或记忆；家族安装先自举或调用元信装前门禁，DO NOT INSTALL 阻断，非元阁家族包不自动安装。
 license: MIT
 metadata:
@@ -43,7 +43,7 @@ metadata:
 **元阁全家的总编排策划 + 编排路由 + 一键安装 + 技能盘点**，一句话四层：
 
 - **路由层（该用哪几个）**：`--route "<需求摘要>"` / MCP `route_request` 查本地注册表与静态编排 playbook，输出候选组合、调用顺序、每个技能角色、置信度、依据、已装/缺失状态与安装命令；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；只建议安装，不自动安装。
-- **动态扩展口（v0.20.0，capability `o1.route`）**：可选调用用户显式配置的本地扩展提供方（provider），在已装注册表白名单内对路由结果增补 / 重排；静态 playbook 结果先算必算、永不缺席，未配置或调用失败时文本输出与历史一致，`--json` 仅多一个 `dynamic` 状态块。协议与配置见 `references/provider-protocol.md`。
+- **O1 动态路由层（v0.23.0，capability `o1.route`）**：可选调用用户显式配置的本地扩展提供方（provider），在已装注册表白名单内对路由结果增补 / 重排，并返回 `confidence` / `reasons` / `summary` / `alternatives`；静态 playbook 结果先算必算、永不缺席，未配置或调用失败时文本输出与历史一致，`--json` 仅多一个 `dynamic` 状态块。协议与配置见 `references/provider-protocol.md`。
 - **M1 记忆裁决层（哪些值得长期记住）**：`decide-memory` / MCP `decide_memory` 调用可选本地 provider（capability `m1.adjudicate`），输出 `promote / hold / demote` 只读建议、分数与信号明细；默认不写元忆、不删除技能。`usage` 默认关闭，用户显式开启后才记录结构化使用信号。协议与边界见 `references/provider-protocol.md`。
 - **策划层（怎么用）**：接到需求，先按「编排策划」定位命中哪个组合——哪些元技能搭配起来最强、适合什么场景、AI 该给出什么安装与调用建议（**安装与调用均由用户确认后执行**）。
 - **安装层（怎么装）**：一条 `npx -y @yottameta/yotta-skills` 把组合/全家装进指定智能体或目录——`--list` 看清单、`install` 装、`update` 增量更新、`doctor` 只读自检、`rollback` 恢复快照、`--dry-run` 预览、`--pin` 锁版本。
@@ -173,7 +173,7 @@ openclaw skills update @yottameta/yotta-skills
 | `hook bind --host <name> --manifest <file>` | 幂等注册 hook 声明；`hook unbind <id>` 反注册 |
 | `--inventory` | 盘点本机已装技能：扫描技能目录生成/更新注册表（自包含，不依赖元技能）；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `--reindex` | 重扫注册表：扫描技能目录并增量合并变化（install / update 完成后 CLI 自动重扫；也可在会话开工等时机手动运行）；`--json` 输出 JSON、`--project` 附扫项目级目录；`--rescan` 同义 |
-| `--route <需求摘要>` | 静态编排路由：输出组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装建议；`--json` 输出 JSON、`--project` 附扫项目级目录 |
+| `--route <需求摘要>` | 编排路由：输出组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装建议；可选本地 provider 增补 / 重排并返回 `confidence` / `reasons` / `summary` / `alternatives`；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `usage status` | 查看本地使用记录开关与计数；默认关闭，不创建文件 |
 | `usage enable` / `usage disable` | 开启 / 关闭 `--route` 的结构化使用记录；不记录需求原文 |
 | `usage mark --skill <slug> --signal used\|named\|accepted` | 记录一次显式使用信号；不要求先 enable |
@@ -340,7 +340,7 @@ npx -y @yottameta/yotta-skills usage reset --yes
 
 本技能自带一个 MCP server：`yotta-skills`（`scripts/yotta-skills-mcp.py`，零依赖、数据不出本机），
 基于 MCP 最新协议 2026-07-28（无状态时代；向后兼容 2025-11-25 及更早握手客户端）。
-提供 `list_installed_skills`（盘点）/ `describe_skill`（单技能详情）/ `reindex`（强制重扫）/ `route_request`（静态编排路由）/ `decide_memory`（M1 记忆裁决只读建议）五个工具。
+提供 `list_installed_skills`（盘点）/ `describe_skill`（单技能详情）/ `reindex`（强制重扫）/ `route_request`（编排路由，静态基线 + 可选本地动态扩展）/ `decide_memory`（M1 记忆裁决只读建议）五个工具。
 
 **按需加载，不走常驻**：本技能与 MCP 均为按需触发。默认以 CLI 为主
 （`npx -y @yottameta/yotta-skills --inventory`）；需要让 AI 通过工具直接调用时，再按下面配置启用。
@@ -417,6 +417,29 @@ npx -y @yottameta/yotta-skills usage reset --yes
 | `YOTTA_SKILLS_PYTHON` | 指定 python 可执行文件（元信 scan 用，同 `--python`） |
 | `YOTTA_SKILLS_VERIFY` | 指定 yotta_verify.py 路径（同 `--verify`） |
 | `YOTTA_SKILLS_MANIFEST` | 指定技能清单 JSON 路径（默认随包 skills.json） |
+| `YOTTA_SKILLS_REGISTRY_FILE` | 技能注册表文件路径（多 agent / 隔离环境用；默认 `~/.yottaskills/registry.json`） |
+| `YOTTA_SKILLS_USAGE_FILE` | 使用记录文件路径（`usage` 记录落点；默认 `~/.yottaskills/usage.json`） |
+| `YOTTA_PROVIDER_HOME` | provider 配置根目录（M1 裁决 / O1 动态路由；默认 `~/.yottameta/`，协议见 `references/provider-protocol.md`） |
+
+### 隔离环境：三个状态文件成组导出
+
+测试、CI 与多 agent 共存场景建议把下面三个状态文件变量**成组**导出，避免读写宿主真实状态；
+只导出其中一个时，其余状态仍会落到用户目录（例如漏掉 `YOTTA_SKILLS_USAGE_FILE` 时，
+`usage` 记录仍会写入 `~/.yottaskills/usage.json`）。
+
+```bash
+# bash（Linux / macOS / Git Bash）
+export YOTTA_SKILLS_REGISTRY_FILE="${TMPDIR:-/tmp}/registry.json"
+export YOTTA_SKILLS_USAGE_FILE="${TMPDIR:-/tmp}/usage.json"
+export YOTTA_PROVIDER_HOME="${TMPDIR:-/tmp}/provider"
+```
+
+```powershell
+# PowerShell（Windows）
+$env:YOTTA_SKILLS_REGISTRY_FILE = "$env:TEMP\registry.json"
+$env:YOTTA_SKILLS_USAGE_FILE = "$env:TEMP\usage.json"
+$env:YOTTA_PROVIDER_HOME = "$env:TEMP\provider"
+```
 
 ## 常见问题
 

package/bin/yotta-skills.js

@@ -39,10 +39,12 @@ const scanPolicyLib = require('../lib/scan-policy');
 const npmPackLib = require('../lib/npm-pack');
 const usageJournalLib = require('../lib/usage-journal');
 const m1FeaturesLib = require('../lib/m1-features');
+const routeFeaturesLib = require('../lib/route-features');
+const routeDynamicLib = require('../lib/route-dynamic');
 const { createInstaller, isSafeTarEntry } = require('../lib/install-pipeline');
 
 const PKG_ROOT = path.join(__dirname, '..');
-let VERSION = '0.22.2';
+let VERSION = '0.23.1';
 try { VERSION = require(path.join(PKG_ROOT, 'package.json')).version; } catch (_) { /* keep fallback */ }
 
 function loadManifest() {
@@ -1250,95 +1252,40 @@ 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');
+  const { PLAYBOOKS } = require('../lib/route');
+  const usage = usageJournalLib.readUsage();
+  const payload = routeFeaturesLib.buildRouteFeatures({
+    request: String(opts.route || ''),
+    registry,
+    staticResult: result,
+    usage,
+    playbooks: PLAYBOOKS,
+  });
   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 || [] })),
-    });
+    run = provider.runCapability('o1.route', payload);
   } catch (e) {
-    return dynamicBlock('error', '', '动态路由装载失败：' + e.message);
+    return routeDynamicLib.dynamicBlock('error', '', '动态路由装载失败：' + e.message);
   }
-  const block = dynamicBlock(run.status, run.provider_id, run.note || run.message || '');
+  const block = routeDynamicLib.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;
+  return routeDynamicLib.applyDynamicData(result, run.data, registry, {
+    providerId: run.provider_id,
+  });
 }
 
 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 + '）';
+    const confidence = block.confidence ? '；置信度 ' + block.confidence : '';
+    return '已应用（' + who + confidence + '；新增 ' + block.added.length + ' / 丢弃 ' + block.dropped.length + '）';
   }
   if (block.status === 'license_required') return '需授权（该能力需要授权后使用；静态路由不受影响）';
   if (block.status === 'timeout') return '未生效（提供方超时，已回落静态路由）';
@@ -1402,6 +1349,10 @@ function runRoute(opts) {
   if (result.dynamic.status !== 'not_installed') {
     out('');
     out('动态路由: ' + dynamicRouteText(result.dynamic));
+    if (result.dynamic.status === 'active' && opts.explain) {
+      if (result.dynamic.summary) out('动态摘要: ' + result.dynamic.summary);
+      for (const reason of result.dynamic.reasons || []) out('  - ' + reason);
+    }
   }
   out('');
   out('应用模式: 显式调用（可经用户确认后切换为按场景自动调用）');

package/lib/route-dynamic.js

@@ -0,0 +1,188 @@
+'use strict';
+
+/**
+ * 元阁 O1 动态路由：provider 响应白名单校验与应用。
+ *
+ * provider 输出一律当数据：未知 slug 丢弃、非法字段忽略、展示文本限长去控制字符。
+ * 静态 playbook 是锚点：provider 只允许在已装白名单内增补 / 重排，不能删除静态技能。
+ */
+
+const CONFIDENCE = new Set(['high', 'medium', 'low']);
+const MAX_SKILLS = 8;
+const MAX_ADDED = 3;
+const MAX_REASONS = 20;
+const MAX_ALTERNATIVES = 3;
+const MAX_ROLE = 160;
+const MAX_REASON = 240;
+const MAX_SUMMARY = 320;
+
+function sanitizeText(value, maxLen) {
+  return String(value || '')
+    .replace(/[\u0000-\u001f\u007f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, maxLen);
+}
+
+function sanitizeList(value, maxItems, maxLen) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const item of value) {
+    const text = sanitizeText(item, maxLen);
+    if (!text || seen.has(text)) continue;
+    seen.add(text);
+    out.push(text);
+    if (out.length >= maxItems) break;
+  }
+  return out;
+}
+
+function dynamicBlock(status, providerId, note) {
+  return {
+    status: status || 'not_installed',
+    provider_id: providerId || '',
+    applied: false,
+    confidence: '',
+    added: [],
+    dropped: [],
+    summary: '',
+    reasons: [],
+    alternatives: [],
+    note: note || '',
+  };
+}
+
+function installedSet(registry) {
+  return new Set(Object.values((registry && registry.skills) || {})
+    .filter((record) => record && record.slug && record.status !== 'gone')
+    .map((record) => String(record.slug)));
+}
+
+function normalizeRequestedSkills(data, installed) {
+  const requested = Array.isArray(data && data.skills) ? data.skills : [];
+  const seen = new Set();
+  const ordered = [];
+  const dropped = [];
+  for (const raw of requested) {
+    const slug = raw && typeof raw === 'object' ? String(raw.slug || '') : '';
+    if (!slug) continue;
+    if (seen.has(slug) || !installed.has(slug)) {
+      dropped.push(slug);
+      continue;
+    }
+    seen.add(slug);
+    const score = Number(raw.score);
+    ordered.push({
+      slug,
+      role: sanitizeText(raw.role, MAX_ROLE),
+      reason: sanitizeText(raw.reason, MAX_REASON),
+      score: Number.isFinite(score) ? Math.max(0, Math.min(100, Math.round(score))) : null,
+    });
+    if (ordered.length >= MAX_SKILLS) break;
+  }
+  return { ordered, dropped };
+}
+
+function normalizeAlternatives(value, installed, selected) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const raw of value) {
+    const slug = raw && typeof raw === 'object' ? String(raw.slug || '') : '';
+    if (!slug || seen.has(slug) || !installed.has(slug) || selected.has(slug)) continue;
+    seen.add(slug);
+    const score = Number(raw.score);
+    out.push({
+      slug,
+      score: Number.isFinite(score) ? Math.max(0, Math.min(100, Math.round(score))) : null,
+      reason: sanitizeText(raw.reason, MAX_REASON),
+    });
+    if (out.length >= MAX_ALTERNATIVES) break;
+  }
+  return out;
+}
+
+/**
+ * 把 provider 的 data 应用到静态结果。
+ * 返回 dynamic 块；若 provider 未给出任何有效技能，则不修改 result。
+ */
+function applyDynamicData(result, data, registry, options) {
+  const opts = options || {};
+  const block = dynamicBlock('active', opts.providerId || '', '');
+  const installed = installedSet(registry);
+  const staticBySlug = new Map((result.skills || []).map((skill) => [skill.slug, skill]));
+  const { ordered, dropped } = normalizeRequestedSkills(data, installed);
+  block.dropped = dropped;
+  if (!ordered.length) {
+    block.note = '提供方未返回白名单内技能';
+    return block;
+  }
+
+  const next = [];
+  for (const item of ordered) {
+    const existing = staticBySlug.get(item.slug);
+    if (existing) {
+      next.push(Object.assign({}, existing, {
+        role: item.role || existing.role,
+        dynamic_reason: item.reason || '',
+        dynamic_score: item.score,
+      }));
+      continue;
+    }
+    const record = (registry.skills && 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 : [],
+      dynamic_reason: item.reason || '',
+      dynamic_score: item.score,
+    });
+  }
+  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; });
+
+  const added = next.filter((skill) => !staticBySlug.has(skill.slug)).map((skill) => skill.slug);
+  if (added.length > MAX_ADDED) {
+    const allowed = new Set(added.slice(0, MAX_ADDED));
+    for (const skill of next.slice()) {
+      if (!staticBySlug.has(skill.slug) && !allowed.has(skill.slug)) {
+        block.dropped.push(skill.slug);
+      }
+    }
+    for (let i = next.length - 1; i >= 0; i--) {
+      if (!staticBySlug.has(next[i].slug) && !allowed.has(next[i].slug)) next.splice(i, 1);
+    }
+    next.forEach((skill, index) => { skill.order = index + 1; });
+  }
+
+  const selected = new Set(next.map((skill) => skill.slug));
+  block.applied = true;
+  block.confidence = CONFIDENCE.has(data && data.confidence) ? data.confidence : (result.confidence || '');
+  block.summary = sanitizeText(data && data.summary, MAX_SUMMARY);
+  block.reasons = sanitizeList(data && data.reasons, MAX_REASONS, MAX_REASON);
+  block.alternatives = normalizeAlternatives(data && data.alternatives, installed, selected);
+  block.added = next.filter((skill) => !staticBySlug.has(skill.slug)).map((skill) => skill.slug);
+  result.skills = next;
+  return block;
+}
+
+module.exports = {
+  CONFIDENCE,
+  MAX_SKILLS,
+  MAX_ADDED,
+  MAX_REASONS,
+  MAX_ALTERNATIVES,
+  sanitizeText,
+  sanitizeList,
+  dynamicBlock,
+  installedSet,
+  applyDynamicData,
+};

package/lib/route-features.js

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * 元阁 O1 动态路由：开源侧确定性特征快照。
+ *
+ * 边界：
+ * - 只读注册表元数据与本地使用记录的聚合计数；不读 SKILL.md 全文。
+ * - 不评分、不排序；评分在私有 provider 中完成。
+ * - 不写文件、不联网、不调用模型。
+ */
+
+const crypto = require('crypto');
+
+const MAX_TOKENS = 64;
+const MAX_INSTALLED = 500;
+const MAX_PLAYBOOK_MATCHES = 5;
+const MAX_DESCRIPTION = 500;
+
+const EN_STOPWORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'of', 'to', 'in', 'on', 'for', 'with', 'from',
+  'this', 'that', 'is', 'are', 'was', 'were', 'be', 'been', 'your', 'you', 'our',
+  'we', 'it', 'at', 'by', 'as', 'not', 'no', 'so', 'do', 'does',
+]);
+
+function normalizeText(text) {
+  return String(text || '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function normalizedKeyword(text) {
+  return normalizeText(text).replace(/\s+/g, '');
+}
+
+function englishTokens(text) {
+  const out = [];
+  const seen = new Set();
+  for (const match of normalizeText(text).match(/[a-z][a-z0-9]{2,}/g) || []) {
+    if (EN_STOPWORDS.has(match) || seen.has(match)) continue;
+    seen.add(match);
+    out.push(match);
+    if (out.length >= MAX_TOKENS) break;
+  }
+  return out;
+}
+
+function cjkBigrams(text) {
+  const out = [];
+  const seen = new Set();
+  for (const match of String(text || '').match(/[\u4e00-\u9fff]+/g) || []) {
+    for (let i = 0; i < match.length - 1; i++) {
+      const bigram = match.slice(i, i + 2);
+      if (seen.has(bigram)) continue;
+      seen.add(bigram);
+      out.push(bigram);
+      if (out.length >= MAX_TOKENS) return out;
+    }
+  }
+  return out;
+}
+
+function requestHash(request) {
+  return crypto.createHash('sha256').update(normalizeText(request), 'utf8').digest('hex');
+}
+
+function playbookMatches(request, playbooks) {
+  const text = normalizedKeyword(request);
+  const matches = [];
+  for (const playbook of Array.isArray(playbooks) ? playbooks : []) {
+    const matched = [];
+    let score = 0;
+    for (const keyword of Array.isArray(playbook.keywords) ? playbook.keywords : []) {
+      const normalized = normalizedKeyword(keyword);
+      if (!normalized || !text.includes(normalized)) continue;
+      matched.push(String(keyword));
+      score += normalized.length >= 3 ? 2 : 1;
+    }
+    if (score > 0) {
+      matches.push({
+        id: String(playbook.id || ''),
+        score,
+        matched_keywords: matched,
+      });
+    }
+  }
+  return matches
+    .sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))
+    .slice(0, MAX_PLAYBOOK_MATCHES);
+}
+
+function trustOf(record) {
+  const slug = String(record && record.slug || '');
+  const sources = Array.isArray(record && record.sources) ? record.sources.join(' ').toLowerCase() : '';
+  if (slug.startsWith('yotta-') || sources.includes('yottameta')) return 'yottameta';
+  return 'third-party';
+}
+
+function skillUsage(usage, slug) {
+  const source = usage && usage.skills && usage.skills[slug] ? usage.skills[slug] : {};
+  const pairs = source.pairs && typeof source.pairs === 'object' && !Array.isArray(source.pairs)
+    ? source.pairs
+    : {};
+  return {
+    used: Number(source.used) || 0,
+    named: Number(source.named) || 0,
+    accepted: Number(source.accepted) || 0,
+    route_hits: Number(source.route_hits) || 0,
+    distinct_pairs: Object.keys(pairs).length,
+    last_signal_at: String(source.last_signal_at || ''),
+  };
+}
+
+function buildRouteFeatures(options) {
+  const opts = options || {};
+  const request = String(opts.request || '');
+  const registry = opts.registry || { skills: {} };
+  const staticResult = opts.staticResult || {};
+  const usage = opts.usage || {};
+  const playbooks = Array.isArray(opts.playbooks) ? opts.playbooks : [];
+  const usageEnabled = usage.enabled === true;
+
+  const installedSkills = Object.values(registry.skills || {})
+    .filter((record) => record && record.slug && record.status !== 'gone')
+    .slice(0, MAX_INSTALLED)
+    .map((record) => ({
+      slug: String(record.slug),
+      version: String(record.version || ''),
+      description: String(record.description || '').slice(0, MAX_DESCRIPTION),
+      status: String(record.status || 'known'),
+      sources: Array.isArray(record.sources) ? record.sources.slice(0, 8).map(String) : [],
+      first_seen: String(record.first_seen || ''),
+      last_seen: String(record.last_seen || ''),
+      trust: trustOf(record),
+    }));
+
+  const usageSkills = {};
+  if (usageEnabled) {
+    for (const slug of Object.keys(usage.skills || {}).sort()) {
+      usageSkills[slug] = skillUsage(usage, slug);
+    }
+  }
+
+  return {
+    schema: 2,
+    request,
+    request_features: {
+      request_hash: requestHash(request),
+      english_tokens: englishTokens(request),
+      cjk_bigrams: cjkBigrams(request),
+      playbook_matches: playbookMatches(request, playbooks),
+    },
+    static_result: {
+      playbook: String(staticResult.playbook && staticResult.playbook.id || staticResult.playbook || ''),
+      confidence: String(staticResult.confidence || ''),
+      skills: Array.isArray(staticResult.skills)
+        ? staticResult.skills.map((skill) => String(skill && skill.slug || skill || '')).filter(Boolean)
+        : [],
+    },
+    installed_skills: installedSkills,
+    usage: {
+      enabled: usageEnabled,
+      skills: usageSkills,
+      last_route: usage.last_route && typeof usage.last_route === 'object'
+        ? {
+          at: String(usage.last_route.at || ''),
+          playbook: String(usage.last_route.playbook || ''),
+          confidence: String(usage.last_route.confidence || ''),
+          skills: Array.isArray(usage.last_route.skills) ? usage.last_route.skills.map(String).slice(0, 12) : [],
+        }
+        : null,
+    },
+    playbooks: playbooks.map((playbook) => ({
+      id: String(playbook.id || ''),
+      name: String(playbook.name || ''),
+      intent: String(playbook.intent || ''),
+      keywords: Array.isArray(playbook.keywords) ? playbook.keywords.slice(0, 32).map(String) : [],
+      skills: Array.isArray(playbook.skills)
+        ? playbook.skills.map((skill) => String(skill && skill.slug || skill || '')).filter(Boolean)
+        : [],
+    })),
+  };
+}
+
+module.exports = {
+  MAX_TOKENS,
+  MAX_INSTALLED,
+  MAX_PLAYBOOK_MATCHES,
+  normalizeText,
+  englishTokens,
+  cjkBigrams,
+  requestHash,
+  playbookMatches,
+  trustOf,
+  skillUsage,
+  buildRouteFeatures,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-skills",
-  "version": "0.22.2",
+  "version": "0.23.1",
   "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
   "license": "MIT",
   "keywords": [

package/references/provider-protocol.md

@@ -1,5 +1,8 @@
 # 扩展提供方协议 v1（元阁 · capability `o1.route` / `m1.adjudicate`）
 
+> O1 动态路由的请求 payload 已加法扩展到 schema 2（新增 `request_features` / `usage` / `playbooks`）；
+> 旧 provider 仍可按原 `skills[]` 响应工作，新 provider 可返回 `confidence` / `reasons` / `summary` / `alternatives`。
+
 元阁可以可选地调用一个由用户显式配置的**本地扩展提供方（provider）**：
 
 - `o1.route`：在已装技能白名单内对静态路由结果做增补 / 重排；未配置时 `--route` 行为与输出与之前完全一致。
@@ -54,6 +57,63 @@
 }
 ```
 
+### 2.1 O1 动态路由 payload（schema 2）
+
+```json
+{
+  "schema": 1,
+  "capability": "o1.route",
+  "request_id": "<uuid>",
+  "payload": {
+    "schema": 2,
+    "request": "帮我做发布前质量检查",
+    "request_features": {
+      "request_hash": "<sha256>",
+      "english_tokens": ["release", "quality"],
+      "cjk_bigrams": ["发布", "质量", "检查"],
+      "playbook_matches": [
+        { "id": "delivery-quality-gate", "score": 6, "matched_keywords": ["检查", "质量", "发布"] }
+      ]
+    },
+    "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",
+        "description": "代码质量评审...",
+        "status": "known",
+        "sources": ["Codex"],
+        "first_seen": "2026-08-23T00:00:00Z",
+        "last_seen": "2026-10-01T00:00:00Z",
+        "trust": "yottameta"
+      }
+    ],
+    "usage": {
+      "enabled": false,
+      "skills": {},
+      "last_route": null
+    },
+    "playbooks": [
+      {
+        "id": "delivery-quality-gate",
+        "name": "交付质量门",
+        "keywords": ["检查", "代码", "质量", "发布"],
+        "skills": ["yotta-anti-shallow", "yotta-code-quality", "yotta-publish-guard"]
+      }
+    ]
+  }
+}
+```
+
+- `request_features` 由元阁本地确定性提取；`request_hash` 只用于审计关联，不用于还原原文。
+- `usage.enabled=false` 时 `usage.skills` 为空；只有用户显式启用使用记录后，才发送聚合计数。
+- `installed_skills` 只含 slug / 版本 / frontmatter description / 状态 / 来源标签 / 时间戳 / 信任标注；不含安装路径。
+- `playbooks` 只含公开静态 playbook 元数据。
+
 ## 3. 响应
 
 ```json
@@ -61,9 +121,20 @@
   "ok": true,
   "capability": "o1.route",
   "data": {
+    "policy": { "version": "o1-mvp-1" },
+    "confidence": "high",
+    "summary": "建议先跑防敷衍，再做代码质量评审，最后过发布守门。",
     "skills": [
-      { "slug": "yotta-code-quality", "role": "可选：补充代码质量评审" },
-      { "slug": "yotta-anti-shallow" }
+      { "slug": "yotta-anti-shallow", "role": "先做防敷衍检查", "score": 82, "reason": "意图匹配 + 静态场景" },
+      { "slug": "yotta-code-quality", "role": "补充代码质量评审", "score": 76, "reason": "历史使用 x2" },
+      { "slug": "yotta-publish-guard", "role": "最后做发布守门", "score": 70, "reason": "静态场景 + 组合出现" }
+    ],
+    "reasons": [
+      "意图匹配：检查 / 代码 / 质量 / 发布",
+      "静态场景：交付质量门"
+    ],
+    "alternatives": [
+      { "slug": "yotta-verify", "score": 54, "reason": "可补充装前安全扫描" }
     ]
   }
 }
@@ -71,6 +142,9 @@
 
 - `skills[].slug` 必须 ∈ `installed_skills` 白名单；未安装或未知的 slug 会被丢弃并记入 `dropped`，不会写入结果。
 - `role` 可选；缺省时增补条目使用「由扩展提供方补充」。
+- `confidence` 只接受 `high / medium / low`；非法值回落静态置信度。
+- `reasons` / `summary` 只作为展示数据，限长并去除控制字符；不作为指令执行。
+- `alternatives` 只接受白名单内、且未进入主组合的技能。
 - 元阁先算静态结果：provider 给出的顺序用于重排；静态结果中未被提及的技能会**追加保留**，不会丢失。
 - 返回空列表 / 全是不合法 slug：视为未应用（`applied = false`），静态结果原样返回。
 
@@ -98,6 +172,8 @@ CLI 文本输出只在状态非 `not_installed` 时多一行「动态路由: ...
 
 - 每次实际调用写一行 `<YOTTA_PROVIDER_HOME>/provider-audit.jsonl`：`ts` / `capability` / `provider_id` / `status` / `duration_ms` / `bytes_out`。
 - 审计**不记录**需求原文或任何 payload 内容。
+- `usage` 只含聚合计数与技能 slug；不记录需求原文、记忆正文、路径或身份信息。
+- P3 仅面向用户显式配置的本地 provider；未来云端 provider 的「只发特征、不传原文」模式留 P5。
 - 元阁不替 provider 联网；provider 自身行为由它自己的包声明。
 - 删除 `provider.json` 即回到纯静态路由，无残留依赖。
 - provider 输出只当数据使用：白名单外的 slug、非法结构一律丢弃，不作为指令执行。

package/scripts/yotta-skills-mcp.py

@@ -27,7 +27,7 @@ import subprocess
 import sys
 from pathlib import Path
 
-VERSION = "0.22.2"
+VERSION = "0.23.1"
 TOOL_NAME = "yotta-skills"
 CN_NAME = "元阁"
 MCP_PROTOCOL_MODERN = "2026-07-28"
@@ -209,9 +209,9 @@ def mcp_tools():
         ),
         _tool_spec(
             "route_request",
-            "按需求摘要给出静态编排路由建议：候选组合、调用顺序、每个技能角色、置信度、依据、已装/缺失状态与安装命令。"
+            "按需求摘要给出编排路由建议：静态 playbook 基线 + 可选本地扩展提供方动态增补 / 重排；返回候选组合、调用顺序、每个技能角色、置信度、依据、已装 / 缺失状态与安装命令。"
             "并给出其他已装技能候选（仅按 frontmatter description 本地机械匹配、标注未扫描状态，不读取全文指令、不自动调用）。"
-            "只建议安装，不自动安装；数据不出本机。",
+            "动态扩展仅在配置了本地 provider 且授权可用时生效；未配置 / 未授权 / 异常时回落静态路由。只建议安装，不自动安装；数据不出本机。",
             {"request": {"type": "string", "description": "用户需求摘要"}},
             ["request"],
         ),
@@ -285,7 +285,7 @@ def handle_message(msg):
                 "result": _modern_ok({
                     "supportedVersions": [MCP_PROTOCOL_MODERN],
                     "capabilities": {"tools": {}},
-                    "instructions": "元阁 MCP（基于 MCP 最新协议 2026-07-28，向后兼容 2025-11-25 及更早握手）：本机技能盘点、静态编排路由与 M1 记忆裁决只读建议 list_installed_skills/describe_skill/reindex/route_request/decide_memory；数据不出本机。",
+                    "instructions": "元阁 MCP（基于 MCP 最新协议 2026-07-28，向后兼容 2025-11-25 及更早握手）：本机技能盘点、编排路由（静态基线 + 可选本地动态扩展）与 M1 记忆裁决只读建议 list_installed_skills/describe_skill/reindex/route_request/decide_memory；数据不出本机。",
                 }, (3600000, "public")),
             }
         if method == "tools/list":

package/skill-manifest.json

@@ -3,7 +3,7 @@
   "slug": "yotta-skills",
   "name": "元阁",
   "package": "@yottameta/yotta-skills",
-  "version": "0.22.2",
+  "version": "0.23.1",
   "trust": "yottameta",
   "install": {
     "idempotent": true