@yottameta/yotta-skills 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 更新日志
 
+## v0.5.0 (2026-08-31)
+
+方案 A（其他已装技能候选编排）：路由输出从「只编排元阁组合」扩展为「组合 + 并列候选提示」。
+
+- 新增 `--route` / `route_request` 输出「其他已装技能候选」：注册表中非元阁家族的已装技能，按 frontmatter `description` 与需求文本做本地机械匹配（英文词项 + 中文二字组交集），Top N（默认 3）并列展示，标注来源、得分、命中词项与扫描状态。
+- 安全边界：只读 frontmatter `description` 做机械匹配，不读取全文指令、不做语义推理、不自动调用；候选默认标注「未扫描」，使用/安装前需先做装前安全扫描；数据不出本机。
+- 确定性：同输入同输出，无状态、无个人数据；候选不参与组合融合排序，7 个静态组合输出保持不变。
+- CLI 文本输出追加「其他已装技能候选」段；`--json` 追加 `other_skill_candidates` / `other_skills_note` 字段；MCP `route_request` 同步。
+- 测试：路由核心新增候选匹配 / 元技能排除 / Top N 与排序 / 确定性 / 空结果；CLI JSON 与文本输出用例。
+- 版本升至 0.5.0。
+
+## v0.4.0 (2026-08-31)
+
+阶段 C（O1 静态编排 playbook + 路由指引）：从「知道装了什么」升级为「给出该用哪几个、什么顺序」。
+
+- 新增静态编排 playbook（7 个场景组合）：输出呈现、长生命周期、交付质量门、装前安全门、造技能发版、安全事件响应、入口安装。
+- 新增 CLI `--route "<需求摘要>"`：先更新本地注册表，再输出候选组合、调用顺序、技能角色、置信度、命中依据、已装/缺失状态、安装命令与应用模式提醒；支持 `--json`。
+- 新增 MCP `route_request` 工具，与 CLI 复用同一套路由核心；MCP 工具扩展为四个。
+- 缺失技能只建议安装，不自动安装；安装命令需用户确认并先执行装前安全扫描。应用模式默认显式调用，切换为按场景自动调用需用户确认。
+- 文档：SKILL.md / README 中英 / orchestration.md / tutorial.md 同步「编排路由」层与边界；banner 同步升级为编排层定位。
+- 测试：新增路由核心（playbook 完整性 / 命中顺序 / 缺失建议 / 无匹配兜底 / 应用模式）、CLI JSON 与文本输出、MCP e2e 用例。
+- 版本升至 0.4.0。
+
 ## v0.3.0 (2026-08-31)
 
 阶段 B（D2 re-index 自动钩子）：新装技能自动被发现。

package/README.md

@@ -6,8 +6,8 @@
 
 <h1 align="center">yotta-skills · 元阁 (YuanGe)</h1>
 
-<p align="center">YottaMeta's skill-family <b>orchestration planner + one-command installer</b>: plan which skills to combine for a task, then one <code>npx</code> line installs the published <code>yotta-*</code> skills (currently <b>22</b>) into any agent or directory.</p>
-<p align="center">List the family, install everything, incrementally update, preview with <code>--dry-run</code>, pin exact versions — idempotent and zero-dependency (Node.js 18+), pure npm ecosystem.</p>
+<p align="center">YottaMeta's skill-family <b>orchestration router, inventory, and one-command installer</b>: route which skills to combine for a task, then one <code>npx</code> line installs the published <code>yotta-*</code> skills (currently <b>22</b>) into any agent or directory.</p>
+<p align="center">List the family, route a task, install everything, incrementally update, preview with <code>--dry-run</code>, pin exact versions - idempotent and zero-dependency (Node.js 18+), pure npm ecosystem.</p>
 <p align="center">This package contains <b>no skill bodies</b> — only a manifest, a downloader, a placer and a summary. Each skill still comes from its own npm package.</p>
 
 <p align="center">
@@ -25,12 +25,13 @@ 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.
+- **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.
 - **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.
 - **Idempotent** — a skill already at the manifest version is skipped; re-running is safe.
 - **Pre-install summary** — if yotta-verify (元信) is available, each skill is scanned first; the verdict is informational only.
-- **Inventory / re-index** — scan the skill directories on this machine and keep a local registry (<code>~/.yottaskills/registry.json</code>); self-contained, no other skills required. Newly installed skills are discovered automatically: <code>install</code> / <code>update</code> re-index the registry afterwards, and <code>--reindex</code> re-scans on demand (e.g. at session start). An optional <code>yotta-skills</code> MCP (on-demand, not resident) exposes <code>list_installed_skills</code> / <code>describe_skill</code> / <code>reindex</code>; see <code>SKILL.md</code> for the config.
+- **Inventory / re-index** - scan the skill directories on this machine and keep a local registry (<code>~/.yottaskills/registry.json</code>); self-contained, no other skills required. Newly installed skills are discovered automatically: <code>install</code> / <code>update</code> re-index the registry afterwards, and <code>--reindex</code> re-scans on demand (e.g. at session start). An optional <code>yotta-skills</code> MCP (on-demand, not resident) exposes <code>list_installed_skills</code> / <code>describe_skill</code> / <code>reindex</code> / <code>route_request</code>; see <code>SKILL.md</code> for the config.
 
 Boundaries: it only downloads, places and summarizes — it does **not** develop skill content, does **not** bundle any skill body, and does **not** use <code>-g</code> global installs. It never writes outside the target you specify.
 
@@ -55,6 +56,9 @@ npx -y @yottameta/yotta-skills update --agent codex
 # Preview what would be installed (no network, no changes)
 npx -y @yottameta/yotta-skills --dry-run
 
+# Route a task to a combination, call order, and missing-skill install suggestion
+npx -y @yottameta/yotta-skills --route "Review this code carefully before release"
+
 # Inventory installed skills on this machine (self-contained scan, no other skills needed)
 npx -y @yottameta/yotta-skills --inventory
 
@@ -75,6 +79,7 @@ Requirements: Node.js 18+, npm, and system <code>tar</code> (built into Windows
 | `update [--agent <name> \| --dir <path>]` | Incremental update: add missing, upgrade version-skewed |
 | `--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 (session start / after installing skills; `--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 |
 | `--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: range, latest patch of the same major) |

package/README.zh-CN.md

@@ -6,9 +6,9 @@
 
 <h1 align="center">yotta-skills · 元阁 (YuanGe)</h1>
 
-<p align="center">YottaMeta 的<b>技能生态编排策划 + 全家一键安装器</b>：先按场景规划该组合哪几个技能，再一条 <code>npx</code> 命令把已发布的全部
+<p align="center">YottaMeta 的<b>技能生态编排路由 + 全家一键安装器 + 技能盘点</b>：先按需求路由该组合哪几个技能，再一条 <code>npx</code> 命令把已发布的全部
 <code>yotta-*</code> 技能（当前 <b>22</b> 个）装进指定智能体或目录。</p>
-<p align="center">看清单、装全家、增量更新、<code>--dry-run</code> 预览、<code>--pin</code> 锁版本——
+<p align="center">看清单、路由组合、装全家、增量更新、<code>--dry-run</code> 预览、<code>--pin</code> 锁版本--
 幂等、零依赖（Node.js 18+）、纯 npm 生态。</p>
 <p align="center">本包<b>不含任何技能本体</b>——只做「清单 + 下载 + 落位 + 汇总」；每个技能仍走各自 npm 包。</p>
 
@@ -28,12 +28,13 @@
 
 元阁也是全家的**编排策划层**：接到需求先查「编排策划」组合表——该组合哪几个技能、按什么顺序、各自强在哪——再按需安装恰好那几个。决策表随包提供（<code>references/orchestration.md</code>），<code>SKILL.md</code> 中有摘要。
 
-- **看清单**——全家技能一览：slug / 中文名 / 包名 / 版本 / 一句话说明。
+- **看清单**--全家技能一览：slug / 中文名 / 包名 / 版本 / 一句话说明。
+- **编排路由**--`--route` 按需求摘要输出候选组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装命令；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；只建议安装，不自动安装。
 - **安装**——装全家（或指定技能）到智能体默认用户级目录或任意目录。
 - **更新**——增量更新：补齐缺失技能、升级版本不一致的技能。
 - **幂等**——已在清单版本的技能跳过；重复运行安全。
 - **装前摘要**——若装了元信（yotta-verify），先对每个待装技能做一次装前扫描；verdict 仅提示、不拦截。
-- **盘点 / re-index**——扫描本机各智能体技能目录，维护本地注册表（<code>~/.yottaskills/registry.json</code>）；自包含，不需要任何其他技能。新装技能自动被发现：<code>install</code> / <code>update</code> 完成后自动重扫注册表，<code>--reindex</code> 可随时手动重扫（如会话开工）。可选 <code>yotta-skills</code> MCP（按需加载、不常驻）提供 <code>list_installed_skills</code> / <code>describe_skill</code> / <code>reindex</code> 三工具，配置见 <code>SKILL.md</code>。
+- **盘点 / re-index**--扫描本机各智能体技能目录，维护本地注册表（<code>~/.yottaskills/registry.json</code>）；自包含，不需要任何其他技能。新装技能自动被发现：<code>install</code> / <code>update</code> 完成后自动重扫注册表，<code>--reindex</code> 可随时手动重扫（如会话开工）。可选 <code>yotta-skills</code> MCP（按需加载、不常驻）提供 <code>list_installed_skills</code> / <code>describe_skill</code> / <code>reindex</code> / <code>route_request</code> 四工具，配置见 <code>SKILL.md</code>。
 
 边界：只做「下载 + 落位 + 汇总」——**不**开发技能内容、**不**内置任何技能本体、**不**用 <code>-g</code>
 全局安装；只在你指定的目标内写文件。
@@ -59,6 +60,9 @@ npx -y @yottameta/yotta-skills update --agent codex
 # 预览将安装清单（不联网、不改动）
 npx -y @yottameta/yotta-skills --dry-run
 
+# 按需求摘要给出组合、顺序与缺失技能安装建议
+npx -y @yottameta/yotta-skills --route "检查代码质量，别糊弄"
+
 # 盘点本机已装技能（自包含扫描，不依赖任何元技能）
 npx -y @yottameta/yotta-skills --inventory
 
@@ -79,6 +83,7 @@ npx -y @yottameta/yotta-skills --reindex
 | `update [--agent <name> \| --dir <path>]` | 增量更新：补齐缺失、升级版本不一致的技能 |
 | `--inventory` | 盘点已装技能：扫描技能目录并更新本地注册表（自包含）；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `--reindex` | 重扫注册表：扫描技能目录并增量合并变化（会话开工 / 装技能后自动调用；`--rescan` 同义）；`--json` 输出 JSON |
+| `--route <需求摘要>` | 静态编排路由：输出组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装建议；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `--no-reindex` | 安装 / 更新后不自动重扫注册表 |
 | `--dry-run` | 预览将执行的安装 / 更新清单；不联网、不改动 |
 | `--pin` | 锁死清单精确版本（默认 range：跟随同 major 最新 patch） |

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-skills
-version: 0.3.0
-description: 元阁 —— 元阁全家技能的总编排策划 + 一键安装器 + 技能盘点。策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么自动装+自动用」；安装层：一条命令把 YottaMeta 已发布的全部 yotta-* 技能装进指定智能体或目录；盘点层：--inventory / --reindex 扫描本机已装技能生成/更新注册表，新装技能自动被发现（install/update 后自动 re-index，会话开工可先跑 --reindex；自包含零依赖，不依赖任何元技能）；MCP 按需加载（可选：list_installed_skills/describe_skill/reindex，不常驻，未加载降级 CLI）。支持 --list 清单 / install / update / --inventory / --reindex / --dry-run 预览 / --pin 锁版本。触发：需要批量安装或更新元阁全家技能、按场景组合多个元技能、盘点或查看本机已装技能、重扫技能注册表、给某个智能体或目录一次性铺齐 yotta-* 技能、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/盘点技能/查看已装技能 等。边界（Do NOT trigger）：只做「组合策划 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index」，不含技能本体、不做技能内容开发、不 -g 污染全局；装前摘要仅供参考，安装决策由用户确认。
+version: 0.5.0
+description: 元阁 -- 元阁全家技能的总编排策划 + 编排路由 + 一键安装器 + 技能盘点。路由层：--route / route_request 按需求摘要给出候选组合、调用顺序、角色、置信度、依据、已装/缺失状态与安装命令，只建议不自动安装；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么自动装+自动用」；安装层：一条命令把 YottaMeta 已发布的全部 yotta-* 技能装进指定智能体或目录；盘点层：--inventory / --reindex 扫描本机已装技能生成/更新注册表，新装技能自动被发现（install/update 后自动 re-index，会话开工可先跑 --reindex；自包含零依赖，不依赖任何元技能）；MCP 按需加载（可选：list_installed_skills/describe_skill/reindex/route_request，不常驻，未加载降级 CLI）。支持 --list 清单 / --route 路由 / install / update / --inventory / --reindex / --dry-run 预览 / --pin 锁版本。触发：需要批量安装或更新元阁全家技能、按场景组合多个元技能、路由或判断该用哪些技能、盘点或查看本机已装技能、重扫技能注册表、给某个智能体或目录一次性铺齐 yotta-* 技能、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/该用哪个技能/路由技能/盘点技能/查看已装技能 等。边界（Do NOT trigger）：只做「组合策划 + 静态路由建议 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index」，不含技能本体、不做技能内容开发、不 -g 污染全局、不自动安装缺失技能；装前摘要仅供参考，安装决策由用户确认。
 license: MIT
 metadata:
   zh_name: 元阁
@@ -27,8 +27,9 @@ metadata:
 
 # 元阁（yotta-skills）
 
-**元阁全家的总编排策划 + 一键安装 + 技能盘点**，一句话三层：
+**元阁全家的总编排策划 + 编排路由 + 一键安装 + 技能盘点**，一句话四层：
 
+- **路由层（该用哪几个）**：`--route "<需求摘要>"` / MCP `route_request` 查本地注册表与静态编排 playbook，输出候选组合、调用顺序、每个技能角色、置信度、依据、已装/缺失状态与安装命令；非元阁家族已装技能按 frontmatter description 机械匹配作并列候选（标注来源与未扫描状态，只读不自动调用）；只建议安装，不自动安装。
 - **策划层（怎么用）**：接到需求，先按「编排策划」定位命中哪个组合——哪些元技能搭配起来最强、适合什么场景、AI 该怎么自动装并自动用起来。
 - **安装层（怎么装）**：一条 `npx -y @yottameta/yotta-skills` 把组合/全家装进指定智能体或目录——`--list` 看清单、`install` 装、`update` 增量更新、`--dry-run` 预览、`--pin` 锁版本。
 - **盘点层（已装了什么）**：`--inventory` / `--reindex` 扫描本机各智能体技能目录，生成/更新本地注册表；装技能后自动 re-index，新装技能自动被发现——自包含扫描，不依赖任何元技能。
@@ -117,6 +118,7 @@ npx -y @yottameta/yotta-skills --reindex
 | `update [--agent <name> \| --dir <path>]` | 增量更新：补齐缺失技能、升级版本不一致的技能 |
 | `--inventory` | 盘点本机已装技能：扫描技能目录生成/更新注册表（自包含，不依赖元技能）；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `--reindex` | 重扫注册表：扫描技能目录并增量合并变化（会话开工 / 装技能后自动调用）；`--json` 输出 JSON、`--project` 附扫项目级目录；`--rescan` 同义 |
+| `--route <需求摘要>` | 静态编排路由：输出组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装建议；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `--no-reindex` | 安装 / 更新后不自动重扫注册表 |
 | `--dry-run` | 预览将执行的安装 / 更新清单；不联网、不改动 |
 | `--pin` | 锁死清单精确版本（默认 range：跟随同 major 最新 patch） |
@@ -156,10 +158,28 @@ npx -y @yottameta/yotta-skills --inventory --dir ~/my-skills --project
   让新装 / 更新的技能自动进入注册表。
 - **手动**：`yotta-skills --reindex`（`--rescan` 同义）；`--json` 机器可读、`--project` 附扫项目级目录。
 
+## 编排路由（--route）
+
+把需求摘要交给静态编排 playbook 和本地注册表，得到一组可执行建议：
+
+```bash
+# 文本输出：组合、调用顺序、角色、置信度、依据、缺失技能安装命令
+npx -y @yottameta/yotta-skills --route "帮我润色输出，要规范可复制，别有 AI 味"
+
+# 机器可读（JSON）
+npx -y @yottameta/yotta-skills --route "检查代码质量，别糊弄" --json
+```
+
+- **输出**：候选组合、调用顺序、每个技能的角色、置信度、命中依据、已装/缺失状态、安装命令与应用模式提醒。
+- **缺失技能**：只给安装命令，不自动安装；安装前应先做装前安全扫描，决定权在用户。
+- **应用模式**：默认用户显式调用；切换为「按场景自动调用」需要用户确认。
+- **无明确匹配**：低置信度回退到「入口 + 安装」组合，先澄清需求再继续。
+- **边界**：路由是建议，不保证完全正确；关键动作由用户确认，数据不出本机。
+
 ### MCP：按需加载（可选）
 
 本技能自带一个 MCP server：`yotta-skills`（`scripts/yotta-skills-mcp.py`，零依赖、数据不出本机），
-提供 `list_installed_skills`（盘点）/ `describe_skill`（单技能详情）/ `reindex`（强制重扫）三个工具。
+提供 `list_installed_skills`（盘点）/ `describe_skill`（单技能详情）/ `reindex`（强制重扫）/ `route_request`（静态编排路由）四个工具。
 
 **按需加载，不走常驻**：本技能与 MCP 均为按需触发。默认以 CLI 为主
 （`npx -y @yottameta/yotta-skills --inventory`）；需要让 AI 通过工具直接调用时，再按下面配置启用：
@@ -178,9 +198,9 @@ npx -y @yottameta/yotta-skills --inventory --dir ~/my-skills --project
    ```
    > `<技能目录>` = 本技能实际安装目录，**不要写死盘符路径**；Windows 用 `python`，Linux/macOS 用 `python3`。
 3. **提醒用户**：改 `mcpServers` 后多数客户端需**重启 / 重载一次** MCP server 才生效；加载后应看到
-   `list_installed_skills` / `describe_skill` / `reindex` 三个工具。
+   `list_installed_skills` / `describe_skill` / `reindex` / `route_request` 四个工具。
 4. **降级兜底（重要）**：若客户端未暴露 MCP 工具 / 无法改配置 / server 未加载，**自动降级 CLI**
-   （同一套扫描核心、结果一致）：`npx -y @yottameta/yotta-skills --inventory / --reindex ...`。
+   （同一套扫描与路由核心、结果一致）：`npx -y @yottameta/yotta-skills --inventory / --reindex / --route ...`。
 
 ## 版本策略
 

package/bin/yotta-skills.js

@@ -131,7 +131,7 @@ function parseArgs(argv) {
     list: false, dryRun: false, pin: false, skipScan: false, force: false,
     help: false, version: false, agent: null, dir: null, npm: null,
     python: null, verify: null, command: null, skill: null, rest: [],
-    inventory: false, reindex: false, noReindex: false, json: false, project: false,
+    inventory: false, reindex: false, noReindex: false, json: false, project: false, route: null,
   };
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
@@ -145,6 +145,12 @@ function parseArgs(argv) {
     else if (a === '--help' || a === '-h') opts.help = true;
     else if (a === '--version' || a === '-v') opts.version = true;
     else if (a === '--inventory' || a === '--inv') opts.inventory = true;
+    else if (a === '--route') {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('--')) die('--route 缺少需求摘要');
+      opts.route = value;
+      i++;
+    }
     else if (a === '--reindex' || a === '--rescan') opts.reindex = true;
     else if (a === '--no-reindex') opts.noReindex = true;
     else if (a === '--json') opts.json = true;
@@ -439,6 +445,7 @@ function printHelp() {
   out('  yotta-skills --dry-run              预览将安装清单（不联网、不改动）');
   out('  yotta-skills --inventory            盘点本机已装技能（自研扫描，不依赖任何元技能）');
   out('  yotta-skills --reindex              重扫注册表（会话开工 / 装技能后自动调用；增量合并）');
+  out('  yotta-skills --route "<需求摘要>"   给出场景组合、调用顺序、缺失技能安装建议');
   out('');
   out('选项:');
   out('  --agent <name>   智能体键名（--list 可查看；未知智能体请用 --dir）');
@@ -449,7 +456,8 @@ function printHelp() {
   out('  --npm <path>     指定 npm 可执行文件（默认 npm / npm.cmd）');
   out('  --python <path>  指定 python 可执行文件（元信 scan 用）');
   out('  --verify <path>  指定 yotta_verify.py 路径（默认找目标目录已装的元信）');
-  out('  --json            inventory / reindex 时输出 JSON');
+  out('  --json            inventory / reindex / route 时输出 JSON');
+  out('  --route <需求>    静态编排路由（输出组合 / 顺序 / 依据 / 缺失技能建议）');
   out('  --project         inventory / reindex 时附加扫描当前项目 .agents/skills / .codex/skills');
   out('  --no-reindex      安装 / 更新后不自动重扫注册表');
   out('  -h, --help       帮助');
@@ -521,6 +529,45 @@ function runReindex(opts) {
   out('注册表: ' + scan.registryPath());
 }
 
+/** --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 });
+  if (opts.json) {
+    out(JSON.stringify(result, null, 2));
+    return;
+  }
+  out('路由结果: ' + result.playbook.name + '（置信度: ' + result.confidence + '）');
+  out('适配意图: ' + result.playbook.intent);
+  out('依据: ' + (result.matched_keywords.length ? result.matched_keywords.join('、') : '无明确匹配，回退到入口澄清'));
+  out('');
+  out('调用顺序:');
+  for (const skill of result.skills) {
+    out('  ' + skill.order + '. ' + skill.slug + ' [' + (skill.installed ? '已装' : '缺失') + '] - ' + skill.role);
+  }
+  if (result.missing_skills.length) {
+    out('');
+    out('缺失技能: ' + result.missing_skills.map((skill) => skill.slug).join(', '));
+    out('安装命令: ' + result.install_command);
+    out('安全提示: 安装前请先执行装前安全扫描；本命令不会自动安装。');
+  }
+  if (result.other_skill_candidates.length) {
+    out('');
+    out('其他已装技能候选（非元阁家族，仅本地机械匹配 frontmatter description）:');
+    for (const c of result.other_skill_candidates) {
+      out('  - ' + c.slug + ' v' + c.version + ' [' + (c.sources || []).join(',') + ']');
+      out('    匹配: ' + c.matched_terms.join('、') + '（得分 ' + c.score + '）· 扫描状态: ' + (c.scan_status === 'not_scanned' ? '未扫描' : c.scan_status));
+      out('    ' + (c.description || ''));
+    }
+    out('安全提示: 其他已装技能只读 frontmatter description 做机械匹配，不读取全文指令、不自动调用；使用/安装前请先执行装前安全扫描，决定权在用户。');
+  }
+  out('');
+  out('应用模式: 显式调用（可经用户确认后切换为按场景自动调用）');
+  out('说明: ' + result.disclaimer);
+}
+
 /** 装技能后自动 re-index（--no-reindex 关闭）：把本次落位结果反映进注册表。best-effort：失败不阻断安装。 */
 function maybeAutoReindex(opts, dest) {
   if (opts.noReindex || opts.dryRun || !dest) return;
@@ -543,6 +590,7 @@ function main() {
   if (opts.list) { printList(opts); return; }
   if (opts.inventory && !opts.command) { runInventory(opts); return; }
   if (opts.reindex && !opts.command) { runReindex(opts); return; }
+  if (opts.route && !opts.command) { runRoute(opts); return; }
 
   const command = opts.command || 'install';
   let dest = resolveTargetDir(opts);

package/lib/route.js

@@ -0,0 +1,238 @@
+'use strict';
+
+const PLAYBOOKS = [
+  {
+    id: 'output-standard',
+    name: '输出呈现标准',
+    intent: '让输出先判型渲染为可复制格式，再去除 AI 味。',
+    keywords: ['输出', '呈现', '渲染', '排版', '可复制', 'AI味', 'AI 味', '润色', '文档', '报告'],
+    skills: [
+      { slug: 'yotta-present', order: 1, role: '判断内容形态并渲染为可复制 Markdown / 纯文本。' },
+      { slug: 'yotta-humanize', order: 2, role: '检测中文 AI 腔，并按用户原意做确定性改写。' },
+    ],
+  },
+  {
+    id: 'long-lived-agent',
+    name: '长生命周期智能体',
+    intent: '让智能体跨会话恢复状态、记忆、经验与历史。',
+    keywords: ['长期', '跨会话', '忘了我', '别忘了我', '记忆', '上下文', '状态', '历史'],
+    skills: [
+      { slug: 'yotta-workflow', order: 1, role: '开工读取项目状态，会话结束更新状态并留下次接续记录。' },
+      { slug: 'yotta-memory', order: 2, role: '按权限边界保存与恢复跨会话记忆。' },
+      { slug: 'yotta-learn', order: 3, role: '沉淀错误、纠正与洞见，供后续会话复用。' },
+      { slug: 'yotta-logs', order: 4, role: '按需检索历史会话与日志记录。' },
+    ],
+  },
+  {
+    id: 'delivery-quality-gate',
+    name: '交付质量门',
+    intent: '交付前做防敷衍、代码质量与发布守门检查。',
+    keywords: ['检查', '代码', '质量', '别糊弄', '敷衍', '评审', '发布', '守门', '交付'],
+    skills: [
+      { slug: 'yotta-anti-shallow', order: 1, role: '强制先分析、再执行、后自检，防止表面化交付。' },
+      { slug: 'yotta-code-quality', order: 2, role: '按十二类腐化风险做结对式代码质量评审。' },
+      { slug: 'yotta-publish-guard', order: 3, role: '发布前校验版本、发布件与分发通道一致性。' },
+    ],
+  },
+  {
+    id: 'preinstall-security-gate',
+    name: '装前安全门',
+    intent: '安装其他来源技能、插件或 MCP 前做安全判定。',
+    keywords: ['安装', '装前', '其他来源', '技能', '插件', 'MCP', '安全扫描'],
+    skills: [
+      { slug: 'yotta-verify', order: 1, role: '执行确定性装前扫描并给出安全判定。' },
+      { slug: 'yotta-vetter', order: 2, role: '按四阶段协议审查来源、代码、权限与风险。' },
+      { slug: 'yotta-security-audit', order: 3, role: '做深度静态检测与安全基线兜底。' },
+    ],
+  },
+  {
+    id: 'skill-build-publish',
+    name: '造技能 / 发版',
+    intent: '创建合规技能包，并在发布前完成守门检查。',
+    keywords: ['造一个', '新 skill', '新技能', '脚手架', '发版', '发布技能', '技能包'],
+    skills: [
+      { slug: 'yotta-skill-creator', order: 1, role: '生成符合规范的技能目录与发布件结构。' },
+      { slug: 'yotta-publish-guard', order: 2, role: '校验版本四件、发布件与分发通道。' },
+    ],
+  },
+  {
+    id: 'security-incident-response',
+    name: '安全事件响应',
+    intent: '从日志、情报、样本、密钥、供应链与资产侦察看清事件链路。',
+    keywords: ['日志', '攻击', '安全事件', '入侵', 'IOC', '威胁情报', '样本', '密钥泄露', '供应链', '资产', '侦察'],
+    skills: [
+      { slug: 'yotta-logwatch', order: 1, role: '分析安全日志并识别攻击链与告警聚合。' },
+      { slug: 'yotta-intel', order: 2, role: '提取、去武器化并规范化威胁情报 IOC。' },
+      { slug: 'yotta-triage', order: 3, role: '对可疑样本做静态初筛。' },
+      { slug: 'yotta-secret', order: 4, role: '扫描密钥与凭据泄露源头。' },
+      { slug: 'yotta-chain', order: 5, role: '校验依赖供应链与 lockfile 一致性。' },
+      { slug: 'yotta-recon', order: 6, role: '在授权范围内做端口、服务与版本指纹侦察。' },
+    ],
+  },
+  {
+    id: 'entry-install',
+    name: '入口 + 安装',
+    intent: '需求方向不明确时先澄清意图，再按需安装合适技能。',
+    keywords: ['不知道用哪个', '需求模糊', '该用哪个', '怎么说', '技能该用哪个'],
+    skills: [
+      { slug: 'yotta-prompt', order: 1, role: '澄清需求意图并串联到合适的技能方向。' },
+      { slug: 'yotta-skills', order: 2, role: '按场景组合安装所需技能，不默认安装全家。' },
+    ],
+  },
+];
+
+const OTHER_SKILLS_NOTE = '其他已装技能仅作并列候选提示：机械匹配 frontmatter description，未做语义推理、未读取全文指令、未自动调用；数据不出本机。';
+const OTHER_SKILL_NOTE = '非元阁家族技能：仅按 frontmatter description 本地机械匹配；不读取全文指令、不自动调用；使用/安装前请先做装前安全扫描。';
+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',
+]);
+
+/** 元阁家族 slug 集合：playbook 引用 + 已知不入 playbook 的元技能（如 yotta-chart）。 */
+function defaultYottaSlugs() {
+  const set = new Set(['yotta-chart']);
+  for (const playbook of PLAYBOOKS) {
+    for (const skill of playbook.skills) set.add(skill.slug);
+  }
+  return Array.from(set);
+}
+
+/** 英文词项：≥3 字母的单词，过滤停用词（保留出现顺序、去重）。 */
+function enTokens(text) {
+  const tokens = [];
+  const seen = new Set();
+  for (const m of String(text || '').toLowerCase().match(/[a-z][a-z0-9]{2,}/g) || []) {
+    if (EN_STOPWORDS.has(m) || seen.has(m)) continue;
+    seen.add(m);
+    tokens.push(m);
+  }
+  return tokens;
+}
+
+/** 中文词项：CJK 连续片段内相邻两字 bigram（零依赖确定性分词）。 */
+function cjkBigrams(text) {
+  const bigrams = [];
+  const seen = new Set();
+  for (const m of String(text || '').match(/[\u4e00-\u9fff]+/g) || []) {
+    for (let i = 0; i < m.length - 1; i++) {
+      const g = m.slice(i, i + 2);
+      if (seen.has(g)) continue;
+      seen.add(g);
+      bigrams.push(g);
+    }
+  }
+  return bigrams;
+}
+
+/** 需求与候选文本的词项匹配：英文 token + 中文 bigram 交集，按需求侧出现顺序输出。 */
+function scoreOtherSkill(request, record) {
+  const candidateText = [record.description, record.slug].filter(Boolean).join(' ');
+  const reqTokens = enTokens(request);
+  const reqBigrams = cjkBigrams(request);
+  const candTokens = new Set(enTokens(candidateText));
+  const candBigrams = new Set(cjkBigrams(candidateText));
+  const matched = [];
+  for (const item of reqTokens) if (candTokens.has(item)) matched.push(item);
+  for (const item of reqBigrams) if (candBigrams.has(item)) matched.push(item);
+  return { score: matched.length, matched_terms: matched };
+}
+
+function normalizeText(text) {
+  return String(text || '').toLowerCase().replace(/\s+/g, '');
+}
+
+function scorePlaybook(request, playbook) {
+  const text = normalizeText(request);
+  const matchedKeywords = [];
+  let score = 0;
+  for (const keyword of playbook.keywords) {
+    if (text.includes(normalizeText(keyword))) {
+      matchedKeywords.push(keyword);
+      score += normalizeText(keyword).length >= 3 ? 2 : 1;
+    }
+  }
+  return { score, matchedKeywords };
+}
+
+function routeRequest(request, options) {
+  const registry = (options && options.registry) || { skills: {} };
+  const installed = registry.skills || {};
+  const yottaSlugs = new Set((options && options.yottaSlugs) || defaultYottaSlugs());
+  const otherSkillsTopN = (options && options.otherSkillsTopN) || 3;
+  const ranked = PLAYBOOKS
+    .map((playbook) => ({ playbook, ...scorePlaybook(request, playbook) }))
+    .sort((a, b) => b.score - a.score || a.playbook.id.localeCompare(b.playbook.id));
+  const best = ranked[0];
+  const runnerUp = ranked[1];
+  const fallback = !best || best.score === 0;
+  const playbook = fallback
+    ? PLAYBOOKS.find((item) => item.id === 'entry-install')
+    : best.playbook;
+  const matchedKeywords = fallback ? [] : best.matchedKeywords;
+  const margin = fallback ? 0 : best.score - (runnerUp ? runnerUp.score : 0);
+  const confidence = !fallback && best.score >= 3 && margin >= 1
+    ? 'high'
+    : (!fallback && best.score >= 1 ? 'medium' : 'low');
+
+  const skills = playbook.skills.map((skill) => {
+    const record = installed[skill.slug];
+    const isInstalled = Boolean(record && record.status !== 'gone');
+    return {
+      ...skill,
+      installed: isInstalled,
+      version: isInstalled ? record.version || '' : '',
+      sources: isInstalled ? record.sources || [] : [],
+    };
+  });
+  const missingSkills = skills
+    .filter((skill) => !skill.installed)
+    .map((skill) => ({ slug: skill.slug, scan_required: true }));
+  const installCommand = missingSkills.length
+    ? 'npx -y @yottameta/yotta-skills install '
+      + missingSkills.map((skill) => skill.slug).join(' ')
+      + ' --dir <skills-dir>'
+    : null;
+
+  const otherCandidates = Object.values(installed)
+    .filter((record) => record && record.status !== 'gone' && !yottaSlugs.has(record.slug))
+    .map((record) => ({ record, ...scoreOtherSkill(request, record) }))
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score || a.record.slug.localeCompare(b.record.slug))
+    .slice(0, otherSkillsTopN)
+    .map(({ record, score, matched_terms }) => ({
+      slug: record.slug,
+      version: record.version || '',
+      sources: record.sources || [],
+      description: record.description || '',
+      score,
+      matched_terms,
+      scan_status: 'not_scanned',
+      note: OTHER_SKILL_NOTE,
+    }));
+
+  return {
+    request,
+    playbook: {
+      id: playbook.id,
+      name: playbook.name,
+      intent: playbook.intent,
+    },
+    confidence,
+    matched_keywords: matchedKeywords,
+    skills,
+    missing_skills: missingSkills,
+    install_command: installCommand,
+    auto_install: false,
+    application_mode: {
+      default: 'explicit',
+      options: ['explicit', 'scene-auto'],
+      note: '默认用户显式调用；切换为按场景自动调用需要用户确认。',
+    },
+    disclaimer: '路由建议不保证完全正确；关键动作应由用户确认，数据不出本机。',
+    other_skill_candidates: otherCandidates,
+    other_skills_note: OTHER_SKILLS_NOTE,
+  };
+}
+
+module.exports = { PLAYBOOKS, defaultYottaSlugs, routeRequest };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yottameta/yotta-skills",
-  "version": "0.3.0",
-  "description": "YuanGe (元阁) — one-command installer for the whole YottaMeta skill family: list, install, and update all published yotta-* skills into any agent (npx one-shot, zero dependencies, Node.js only).",
+  "version": "0.5.0",
+  "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
   "license": "MIT",
   "keywords": [
     "agent-skills",

package/references/orchestration.md

@@ -6,6 +6,22 @@
 
 ---
 
+## 〇、编排路由（--route / route_request）
+
+把需求摘要交给静态 playbook 与本地注册表，得到一组建议：
+
+```bash
+npx -y @yottameta/yotta-skills --route "帮我润色输出，要规范可复制，别有 AI 味"
+```
+
+- **输出**：候选组合、调用顺序、每个技能的角色、置信度、命中依据、已装/缺失状态、安装命令与应用模式提醒；如本机装了非元阁家族技能，还会给出其他已装技能候选（仅按 frontmatter description 机械匹配，标注来源与未扫描状态）。
+- **缺失技能**：只给安装命令，不自动安装；安装前先做装前安全扫描，决定权在用户。
+- **应用模式**：默认用户显式调用；切换为「按场景自动调用」需要用户确认。
+- **无明确匹配**：低置信度回退到「入口 + 安装」组合，先澄清需求再继续。
+- **边界**：路由是建议，不保证完全正确；关键动作由用户确认，数据不出本机。其他已装技能候选只读 frontmatter description、不读取全文指令、不自动调用；使用/安装前先做装前安全扫描。
+
+---
+
 ## 一、技能家族全景（24 技能 / 8 家族）
 
 | 家族 | 技能（中文名 / slug） | 一句话能力 |

package/references/tutorial.md

@@ -118,4 +118,15 @@ npx -y @yottameta/yotta-skills --reindex
 - `install` / `update` 完成后会自动重扫注册表（`~/.yottaskills/registry.json`），新装 / 更新的
   技能随即出现在 `--inventory` / `--reindex` 里；`--no-reindex` 可关闭自动重扫。
 - 建议每会话开工先跑一次 `--reindex`（快速增量，只合并变化），让后装的技能自动被看见。
+
+## 编排路由（--route）
+
+当你不知道「这个需求该用哪几个技能」，可以先把需求摘要交给元阁：
+
+```bash
+npx -y @yottameta/yotta-skills --route "检查代码质量，别糊弄"
+```
+
+输出会告诉你命中哪个组合、按什么顺序调用、每个技能负责什么、哪些已装、哪些缺失，以及缺失技能的安装命令。元阁只给建议，不会自动安装；安装前请先做装前安全扫描，并由用户确认。
 - `--json` 输出机器可读结果（含新增 / 更新 / 消失），适合脚本与钩子。
+- 如果本机还装了非元阁家族技能，`--route` 会额外列出「其他已装技能候选」：只按 frontmatter description 与需求文本做本地机械匹配，标注来源、得分、命中词项与扫描状态（默认未扫描），不读取全文指令、不自动调用；使用/安装前请先做装前安全扫描。

package/scripts/yotta-skills-mcp.py

@@ -6,6 +6,7 @@ stdio MCP server（JSON-RPC 2.0，换行分隔），把元阁技能扫描核心
   list_installed_skills  盘点本机已装技能（读本地注册表；未生成则先扫描一次）
   describe_skill         查看单个技能详情（slug / 版本 / 功能 / 来源）
   reindex                强制重新扫描并更新注册表
+  route_request          按需求摘要给出静态编排路由建议
 
 自包含原则：扫描由元阁自带核心（bin/yotta-skills.js --inventory / --reindex）完成，
 不依赖任何元技能；数据只写本机 ~/.yottaskills/registry.json，不出本机。
@@ -23,7 +24,7 @@ import subprocess
 import sys
 from pathlib import Path
 
-VERSION = "0.3.0"
+VERSION = "0.5.0"
 TOOL_NAME = "yotta-skills"
 CN_NAME = "元阁"
 MCP_PROTOCOL = "2025-03-26"
@@ -138,10 +139,24 @@ def _tool_reindex(arguments):  # noqa: ARG001
             "isError": False}
 
 
+def _tool_route(arguments):
+    request = str(arguments.get("request") or "").strip()
+    if not request:
+        return _tool_error("route_request 需要 request 参数")
+    stdout = _run_cli(["--route", request, "--json"])
+    try:
+        payload = json.loads(stdout)
+    except json.JSONDecodeError as e:
+        return _tool_error("route_request 输出解析失败：%s" % e)
+    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,
+    "route_request": _tool_route,
 }
 
 
@@ -167,6 +182,14 @@ def mcp_tools():
             {},
             [],
         ),
+        _tool_spec(
+            "route_request",
+            "按需求摘要给出静态编排路由建议：候选组合、调用顺序、每个技能角色、置信度、依据、已装/缺失状态与安装命令。"
+            "并给出其他已装技能候选（仅按 frontmatter description 本地机械匹配、标注未扫描状态，不读取全文指令、不自动调用）。"
+            "只建议安装，不自动安装；数据不出本机。",
+            {"request": {"type": "string", "description": "用户需求摘要"}},
+            ["request"],
+        ),
     ]