@yottameta/yotta-skills 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 更新日志
 
+## v0.3.0 (2026-08-31)
+
+阶段 B（D2 re-index 自动钩子）：新装技能自动被发现。
+
+- 新增 CLI `--reindex`：重扫所有技能目录并增量合并注册表，变化聚焦输出（文本 / `--json` 机器可读），供会话开工与钩子调用；`--rescan` 为同义别名。
+- 装技能后自动 re-index：`install` / `update` 完成后自动重扫注册表，把本次落位结果反映进 `~/.yottaskills/registry.json`（新增 / 更新 / 消失随输出列出）；`--no-reindex` 可关闭。
+- 会话开工 re-scan：SKILL.md「使用须知」护栏补「会话开工先跑一次 `yotta-skills --reindex`」；注册表 `note` 口径同步 `--inventory / --reindex`。
+- MCP `reindex` 工具改走 `--reindex --json`（同一套扫描核心）；CLI 等价命令注明。
+- 文档：SKILL.md / README 中英 / references/install-flow.md / tutorial.md 同步 re-index 用法。
+- 测试：新增 `--reindex`（含幂等）与装后自动 re-index（含 `--no-reindex` 关闭）用例；全量用例全绿。
+- 版本升至 0.3.0。
+
+## v0.2.1 (2026-08-31)
+
+MCP 配置说明补全（按需加载口径）。
+
+- SKILL.md「技能盘点」节补「MCP：按需加载（可选）」：明确本技能与 MCP 均为按需触发、不走常驻；mcpServers 配置 JSON 示例、按需写入步骤（用后可移除）、重启/重载提示、未加载降级 CLI 兜底；frontmatter description 同步按需加载口径。
+- 测试：mcp-e2e serverInfo.version 断言改为动态读 package.json；python 探测加候选兜底（YOTTA_TEST_PYTHON / python / python3 / Scoop python38），Windows 无需手动设环境变量。
+- 版本升至 0.2.1。
+
 ## v0.2.0 (2026-08-31)
 
 技能生态盘点层（阶段 A）：元阁从「编排策划 + 安装器」升级为「编排策划 + 安装器 + 技能盘点」。

package/README.md

@@ -30,7 +30,7 @@ Installing the whole YottaMeta family used to mean running <code>npx</code> for
 - **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** — scan the skill directories on this machine and keep a local registry (<code>~/.yottaskills/registry.json</code>); self-contained, no other skills required.
+- **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.
 
 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.
 
@@ -57,6 +57,9 @@ npx -y @yottameta/yotta-skills --dry-run
 
 # Inventory installed skills on this machine (self-contained scan, no other skills needed)
 npx -y @yottameta/yotta-skills --inventory
+
+# Re-index the registry (session start / after installing skills; incremental)
+npx -y @yottameta/yotta-skills --reindex
 ```
 
 Requirements: Node.js 18+, npm, and system <code>tar</code> (built into Windows 10+ / macOS / most Linux distributions).
@@ -71,6 +74,8 @@ Requirements: Node.js 18+, npm, and system <code>tar</code> (built into Windows
 | `install <skill>... [--agent <name> \| --dir <path>]` | Install only the given skills |
 | `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 |
+| `--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) |
 | `--force` | Reinstall even when already at the latest version |
@@ -141,12 +146,12 @@ The full 22-skill manifest with Chinese names, package names, versions and descr
 
 ## How it works
 
-For each skill in the manifest: `npm pack <pkg>@<spec>` into a temp directory → `tar -xzf` → optional yotta-verify pre-install summary → replace `<dest>/<slug>` → summary report. Details: `references/install-flow.md`; beginner tutorial (Chinese): `references/tutorial.md`.
+For each skill in the manifest: `npm pack <pkg>@<spec>` into a temp directory → `tar -xzf` → optional yotta-verify pre-install summary → replace `<dest>/<slug>` → summary report. After `install` / `update` finishes, the local skill registry is re-indexed automatically so newly installed skills show up in `--inventory` / `--reindex` (disable with `--no-reindex`). Details: `references/install-flow.md`; beginner tutorial (Chinese): `references/tutorial.md`.
 
 ## Development & validation
 
 ```bash
-# Run the test suite (12 cases) from the skill directory
+# Run the test suite from the skill directory
 npm test
 ```
 

package/README.zh-CN.md

@@ -33,7 +33,7 @@
 - **更新**——增量更新：补齐缺失技能、升级版本不一致的技能。
 - **幂等**——已在清单版本的技能跳过；重复运行安全。
 - **装前摘要**——若装了元信（yotta-verify），先对每个待装技能做一次装前扫描；verdict 仅提示、不拦截。
-- **盘点**——扫描本机各智能体技能目录，维护本地注册表（<code>~/.yottaskills/registry.json</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>SKILL.md</code>。
 
 边界：只做「下载 + 落位 + 汇总」——**不**开发技能内容、**不**内置任何技能本体、**不**用 <code>-g</code>
 全局安装；只在你指定的目标内写文件。
@@ -61,6 +61,9 @@ npx -y @yottameta/yotta-skills --dry-run
 
 # 盘点本机已装技能（自包含扫描，不依赖任何元技能）
 npx -y @yottameta/yotta-skills --inventory
+
+# 重扫注册表（会话开工 / 新装技能后，增量合并变化）
+npx -y @yottameta/yotta-skills --reindex
 ```
 
 前置：Node.js 18+、npm、系统 tar（Windows 10+ / macOS / 多数 Linux 自带）。
@@ -75,6 +78,8 @@ npx -y @yottameta/yotta-skills --inventory
 | `install <skill>... [--agent <name> \| --dir <path>]` | 只装指定的一个或多个技能 |
 | `update [--agent <name> \| --dir <path>]` | 增量更新：补齐缺失、升级版本不一致的技能 |
 | `--inventory` | 盘点已装技能：扫描技能目录并更新本地注册表（自包含）；`--json` 输出 JSON、`--project` 附扫项目级目录 |
+| `--reindex` | 重扫注册表：扫描技能目录并增量合并变化（会话开工 / 装技能后自动调用；`--rescan` 同义）；`--json` 输出 JSON |
+| `--no-reindex` | 安装 / 更新后不自动重扫注册表 |
 | `--dry-run` | 预览将执行的安装 / 更新清单；不联网、不改动 |
 | `--pin` | 锁死清单精确版本（默认 range：跟随同 major 最新 patch） |
 | `--force` | 已是最新也重新安装 |
@@ -150,13 +155,14 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 ## 工作原理
 
 对清单里每个技能：`npm pack <pkg>@<spec>` 到临时目录 → `tar -xzf` 解压 → 可选元信装前摘要 →
-替换 `<dest>/<slug>` → 汇总报告。细节见 `references/install-flow.md`；新手中文教程见
-`references/tutorial.md`。
+替换 `<dest>/<slug>` → 汇总报告。`install` / `update` 完成后自动重扫本地技能注册表，
+新装技能随即出现在 `--inventory` / `--reindex` 里（可用 `--no-reindex` 关闭）。
+细节见 `references/install-flow.md`；新手中文教程见 `references/tutorial.md`。
 
 ## 开发与校验
 
 ```bash
-# 在技能目录内跑测试（12 个用例）
+# 在技能目录内跑测试
 npm test
 ```
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-skills
-version: 0.2.0
-description: 元阁 —— 元阁全家技能的总编排策划 + 一键安装器 + 技能盘点。策划层：按场景给出「该组合哪几个元技能、组合强在哪、怎么自动装+自动用」；安装层：一条命令把 YottaMeta 已发布的全部 yotta-* 技能装进指定智能体或目录；盘点层：--inventory 扫描本机已装技能生成注册表（自包含零依赖，不依赖任何元技能）。支持 --list 清单 / install / update / --inventory / --dry-run 预览 / --pin 锁版本。触发：需要批量安装或更新元阁全家技能、按场景组合多个元技能、盘点或查看本机已装技能、给某个智能体或目录一次性铺齐 yotta-* 技能、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/盘点技能/查看已装技能 等。边界（Do NOT trigger）：只做「组合策划 + 清单 + 下载 + 落位 + 汇总 + 盘点」，不含技能本体、不做技能内容开发、不 -g 污染全局；装前摘要仅供参考，安装决策由用户确认。
+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 污染全局；装前摘要仅供参考，安装决策由用户确认。
 license: MIT
 metadata:
   zh_name: 元阁
@@ -15,7 +15,8 @@ metadata:
 
 **写入内容（逐字）**：
 
-> **元阁编排**：单技能是零件，组合才是系统。接到需求，先查「元阁编排策划」命中哪个组合
+> **元阁编排**：单技能是零件，组合才是系统。会话开工先跑一次 `yotta-skills --reindex`
+> （重扫本机技能注册表，新装技能自动被看见）。接到需求，先查「元阁编排策划」命中哪个组合
 > （输出呈现标准 / 长生命周期 / 交付质量门 / 装前安全门 / 造技能发版 / 安全事件响应 / 入口安装），
 > 再按需自动安装并应用。完整决策表见技能 `yotta-skills/references/orchestration.md`。
 
@@ -30,7 +31,7 @@ metadata:
 
 - **策划层（怎么用）**：接到需求，先按「编排策划」定位命中哪个组合——哪些元技能搭配起来最强、适合什么场景、AI 该怎么自动装并自动用起来。
 - **安装层（怎么装）**：一条 `npx -y @yottameta/yotta-skills` 把组合/全家装进指定智能体或目录——`--list` 看清单、`install` 装、`update` 增量更新、`--dry-run` 预览、`--pin` 锁版本。
-- **盘点层（已装了什么）**：`--inventory` 扫描本机各智能体技能目录，生成/更新本地注册表——自包含扫描，不依赖任何元技能。
+- **盘点层（已装了什么）**：`--inventory` / `--reindex` 扫描本机各智能体技能目录，生成/更新本地注册表；装技能后自动 re-index，新装技能自动被发现——自包含扫描，不依赖任何元技能。
 
 每个技能仍走各自独立的 npm 包（版本源唯一）；本包只做「清单 + 下载 + 落位 + 汇总」，**不内置任何技能本体**。
 > **本包不含技能本体**：拿到它只代表有了「编排策划 + 安装工具」；真正装齐需运行 `install`。
@@ -100,6 +101,9 @@ npx -y @yottameta/yotta-skills --dry-run
 
 # 盘点本机已装技能（自包含扫描，不依赖任何元技能）
 npx -y @yottameta/yotta-skills --inventory
+
+# 重扫注册表（会话开工 / 新装技能后，增量合并变化）
+npx -y @yottameta/yotta-skills --reindex
 ```
 
 ## 命令与选项
@@ -112,6 +116,8 @@ npx -y @yottameta/yotta-skills --inventory
 | `install <skill>... [--agent <name> \| --dir <path>]` | 只装指定的一个或多个技能 |
 | `update [--agent <name> \| --dir <path>]` | 增量更新：补齐缺失技能、升级版本不一致的技能 |
 | `--inventory` | 盘点本机已装技能：扫描技能目录生成/更新注册表（自包含，不依赖元技能）；`--json` 输出 JSON、`--project` 附扫项目级目录 |
+| `--reindex` | 重扫注册表：扫描技能目录并增量合并变化（会话开工 / 装技能后自动调用）；`--json` 输出 JSON、`--project` 附扫项目级目录；`--rescan` 同义 |
+| `--no-reindex` | 安装 / 更新后不自动重扫注册表 |
 | `--dry-run` | 预览将执行的安装 / 更新清单；不联网、不改动 |
 | `--pin` | 锁死清单精确版本（默认 range：跟随同 major 最新 patch） |
 | `--force` | 已是最新也重新安装 |
@@ -142,9 +148,39 @@ npx -y @yottameta/yotta-skills --inventory --dir ~/my-skills --project
 
 注册表增量合并：新增（added）/ 更新（updated）/ 消失（gone）随输出列出；同名技能来自多个目录时合并来源，版本不一致记录冲突。
 
-**MCP（按需加载）**：`scripts/yotta-skills-mcp.py` 提供三个工具——
-`list_installed_skills`（盘点）/ `describe_skill`（单技能详情）/ `reindex`（强制重扫），
-走 stdio JSON-RPC，数据不出本机。需要时按需加载，不常驻。
+### re-index：新装技能自动被发现
+
+- **装技能后自动**：`install` / `update` 完成后自动重扫注册表，把本次落位结果反映进
+  `~/.yottaskills/registry.json`（新增 / 更新 / 消失随输出列出）；`--no-reindex` 可关闭。
+- **会话开工**：建议每会话开工先跑一次 `yotta-skills --reindex`（快速增量，只合并变化），
+  让新装 / 更新的技能自动进入注册表。
+- **手动**：`yotta-skills --reindex`（`--rescan` 同义）；`--json` 机器可读、`--project` 附扫项目级目录。
+
+### MCP：按需加载（可选）
+
+本技能自带一个 MCP server：`yotta-skills`（`scripts/yotta-skills-mcp.py`，零依赖、数据不出本机），
+提供 `list_installed_skills`（盘点）/ `describe_skill`（单技能详情）/ `reindex`（强制重扫）三个工具。
+
+**按需加载，不走常驻**：本技能与 MCP 均为按需触发。默认以 CLI 为主
+（`npx -y @yottameta/yotta-skills --inventory`）；需要让 AI 通过工具直接调用时，再按下面配置启用：
+
+1. **检查当前客户端的 `mcpServers`** 是否已有 `yotta-skills` 条目；已有 → 直接使用。
+2. **没有 → 按需写入**下面这一条 server 配置（用后可移除，不要求常驻）：
+   ```json
+   {
+     "mcpServers": {
+       "yotta-skills": {
+         "command": "python",
+         "args": ["<技能目录>/scripts/yotta-skills-mcp.py"]
+       }
+     }
+   }
+   ```
+   > `<技能目录>` = 本技能实际安装目录，**不要写死盘符路径**；Windows 用 `python`，Linux/macOS 用 `python3`。
+3. **提醒用户**：改 `mcpServers` 后多数客户端需**重启 / 重载一次** MCP server 才生效；加载后应看到
+   `list_installed_skills` / `describe_skill` / `reindex` 三个工具。
+4. **降级兜底（重要）**：若客户端未暴露 MCP 工具 / 无法改配置 / server 未加载，**自动降级 CLI**
+   （同一套扫描核心、结果一致）：`npx -y @yottameta/yotta-skills --inventory / --reindex ...`。
 
 ## 版本策略
 

package/bin/yotta-skills.js

@@ -22,7 +22,7 @@ const os = require('os');
 const { spawnSync } = require('child_process');
 
 const PKG_ROOT = path.join(__dirname, '..');
-let VERSION = '0.2.0';
+let VERSION = '0.2.1';
 try { VERSION = require(path.join(PKG_ROOT, 'package.json')).version; } catch (_) { /* keep fallback */ }
 
 function loadManifest() {
@@ -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, rescan: false, json: false, project: false,
+    inventory: false, reindex: false, noReindex: false, json: false, project: false,
   };
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
@@ -145,7 +145,8 @@ 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 === '--rescan') opts.rescan = true;
+    else if (a === '--reindex' || a === '--rescan') opts.reindex = true;
+    else if (a === '--no-reindex') opts.noReindex = true;
     else if (a === '--json') opts.json = true;
     else if (a === '--project') opts.project = true;
     else if (a === '--agent') opts.agent = take('--agent').toLowerCase();
@@ -437,6 +438,7 @@ function printHelp() {
   out('  yotta-skills update --agent <name>  增量更新已装技能（补齐缺失 / 版本不一致）');
   out('  yotta-skills --dry-run              预览将安装清单（不联网、不改动）');
   out('  yotta-skills --inventory            盘点本机已装技能（自研扫描，不依赖任何元技能）');
+  out('  yotta-skills --reindex              重扫注册表（会话开工 / 装技能后自动调用；增量合并）');
   out('');
   out('选项:');
   out('  --agent <name>   智能体键名（--list 可查看；未知智能体请用 --dir）');
@@ -447,8 +449,9 @@ function printHelp() {
   out('  --npm <path>     指定 npm 可执行文件（默认 npm / npm.cmd）');
   out('  --python <path>  指定 python 可执行文件（元信 scan 用）');
   out('  --verify <path>  指定 yotta_verify.py 路径（默认找目标目录已装的元信）');
-  out('  --json            inventory 时输出 JSON');
-  out('  --project         inventory 时附加扫描当前项目 .agents/skills / .codex/skills');
+  out('  --json            inventory / reindex 时输出 JSON');
+  out('  --project         inventory / reindex 时附加扫描当前项目 .agents/skills / .codex/skills');
+  out('  --no-reindex      安装 / 更新后不自动重扫注册表');
   out('  -h, --help       帮助');
   out('  -v, --version    版本');
   out('');
@@ -458,8 +461,9 @@ function printHelp() {
 
 
 
-// ── 技能盘点（--inventory，自研零依赖扫描） ────────────────────────────────
-function runInventory(opts) {
+// ── 技能盘点 / re-index（自研零依赖扫描核心） ────────────────────────────────
+/** 重扫所有技能根目录并增量合并进注册表；返回 { result, registry, changes }。 */
+function reindexRegistry(opts) {
   const scan = require('../lib/skills-scan');
   const extraDirs = opts.dir ? [opts.dir] : [];
   const roots = scan.defaultRoots({ extraDirs: extraDirs, project: opts.project });
@@ -467,6 +471,12 @@ function runInventory(opts) {
   const prev = scan.readRegistry();
   const { registry, changes } = scan.mergeRegistry(result, prev);
   scan.saveRegistry(registry);
+  return { result, registry, changes };
+}
+
+function runInventory(opts) {
+  const scan = require('../lib/skills-scan');
+  const { result, registry, changes } = reindexRegistry(opts);
   if (opts.json) {
     out(JSON.stringify({
       generated_at: registry.updated,
@@ -486,13 +496,53 @@ function runInventory(opts) {
   }
 }
 
+/** --reindex：重扫 + 增量合并，变化聚焦输出（供会话开工 / 钩子使用）。 */
+function runReindex(opts) {
+  const scan = require('../lib/skills-scan');
+  const { result, registry, changes } = reindexRegistry(opts);
+  if (opts.json) {
+    out(JSON.stringify({
+      reindexed_at: registry.updated,
+      note: registry.note,
+      count: Object.values(registry.skills).filter((s) => s.status !== 'gone').length,
+      changes: changes,
+      errors: result.errors,
+      scanned: result.scanned,
+    }, null, 2));
+    return;
+  }
+  out('re-index 完成: 新增 ' + changes.added.length + ' / 更新 ' + changes.updated.length + ' / 消失 ' + changes.gone.length);
+  for (const slug of changes.added) out('  + ' + slug);
+  for (const slug of changes.updated) out('  ~ ' + slug);
+  for (const slug of changes.gone) out('  - ' + slug);
+  if (result.errors.length) {
+    out('跳过不存在目录 ' + result.errors.length + ' 个');
+  }
+  out('注册表: ' + scan.registryPath());
+}
+
+/** 装技能后自动 re-index（--no-reindex 关闭）：把本次落位结果反映进注册表。best-effort：失败不阻断安装。 */
+function maybeAutoReindex(opts, dest) {
+  if (opts.noReindex || opts.dryRun || !dest) return;
+  const scan = require('../lib/skills-scan');
+  try {
+    const { changes } = reindexRegistry({ ...opts, dir: dest });
+    out('');
+    out('已自动 re-index 注册表（新增 ' + changes.added.length + ' / 更新 ' + changes.updated.length + ' / 消失 ' + changes.gone.length + '；注册表: ' + scan.registryPath() + '）');
+  } catch (e) {
+    out('');
+    out('提示: 自动 re-index 跳过（' + e.message + '）；稍后可手动 --reindex 重扫');
+  }
+}
+
 // ── main ───────────────────────────────────────────────────────────────────
 function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (opts.help) { printHelp(); return; }
   if (opts.version) { out('yotta-skills v' + VERSION); return; }
   if (opts.list) { printList(opts); return; }
-  if (opts.inventory) { runInventory(opts); return; }
+  if (opts.inventory && !opts.command) { runInventory(opts); return; }
+  if (opts.reindex && !opts.command) { runReindex(opts); return; }
 
   const command = opts.command || 'install';
   let dest = resolveTargetDir(opts);
@@ -518,6 +568,7 @@ function main() {
 
   if (command === 'update') runUpdate(opts, dest);
   else runInstall(opts, dest);
+  maybeAutoReindex(opts, dest);
 }
 
 main();

package/lib/skills-scan.js

@@ -267,7 +267,7 @@ function mergeRegistry(scanResult, previous) {
   }
   const registry = {
     updated: now,
-    note: '本地技能注册表（yotta-skills --inventory 生成）。数据不出本机。',
+    note: '本地技能注册表（yotta-skills --inventory / --reindex 生成）。数据不出本机。',
     skills: next,
   };
   return { registry, changes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-skills",
-  "version": "0.2.0",
+  "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).",
   "license": "MIT",
   "keywords": [

package/references/install-flow.md

@@ -13,6 +13,8 @@
 4. 元信装前摘要（若引擎可用；`--skip-scan` 关闭）；
 5. 删除目标 `<dest>/<slug>` 后重新复制（跳过规则见下）；
 6. 汇总报告：✔ 成功 / - 跳过（已是最新）/ ✘ 失败；有失败项时退出码 1。
+7. 全部完成后自动 re-index 本地技能注册表（`~/.yottaskills/registry.json`）：重扫技能根目录并增量合并，
+   新装 / 更新的技能随即进入注册表（`--no-reindex` 可关闭；`--dry-run` 不触发）。
 
 ## 复制跳过规则
 
@@ -22,6 +24,14 @@
 因此装进技能目录的是「技能本体」（SKILL.md / references / scripts 等），不含 npm
 安装器自身、测试夹具与 Python 字节码缓存。
 
+## re-index（装技能后自动重扫注册表）
+
+- `install` / `update` 完成后，CLI 自动调用 `--reindex`（同一套 `lib/skills-scan.js` 扫描核心）：
+  重扫技能根目录 → 增量合并进 `~/.yottaskills/registry.json`（新增 / 更新 / 消失）。
+- `--no-reindex` 关闭自动重扫；`--reindex` 也可单独手动执行（会话开工 / 新装技能后）。
+- 与 `--inventory` 的区别：`--inventory` 侧重「盘点展示」（文本表格 / JSON 全量），
+  `--reindex` 侧重「变化合并」（增量、输出聚焦新增 / 更新 / 消失，适合钩子与脚本）。
+
 ## 幂等与版本判断
 
 - 读取目标 `<dest>/<slug>/SKILL.md` 的 frontmatter `version`；

package/references/tutorial.md

@@ -104,3 +104,18 @@ npx -y @yottameta/yotta-skills install --agent codex --skip-scan # 跳过装前
 - **目标未指定**：当前目录没有项目级技能目录时报错（退出码 4），加 `--agent` 或
   `--dir`。
 - **已有旧版本**：默认按 range 覆盖升级到最新 patch；`--pin` 则锁定清单版本。
+
+## 11. 盘点已装技能与 re-index（新装技能自动被发现）
+
+```bash
+# 盘点本机已装技能（文本表格）
+npx -y @yottameta/yotta-skills --inventory
+
+# 重扫注册表（会话开工 / 新装技能后，增量合并变化）
+npx -y @yottameta/yotta-skills --reindex
+```
+
+- `install` / `update` 完成后会自动重扫注册表（`~/.yottaskills/registry.json`），新装 / 更新的
+  技能随即出现在 `--inventory` / `--reindex` 里；`--no-reindex` 可关闭自动重扫。
+- 建议每会话开工先跑一次 `--reindex`（快速增量，只合并变化），让后装的技能自动被看见。
+- `--json` 输出机器可读结果（含新增 / 更新 / 消失），适合脚本与钩子。

package/scripts/yotta-skills-mcp.py

@@ -7,7 +7,7 @@ stdio MCP server（JSON-RPC 2.0，换行分隔），把元阁技能扫描核心
   describe_skill         查看单个技能详情（slug / 版本 / 功能 / 来源）
   reindex                强制重新扫描并更新注册表
 
-自包含原则：扫描由元阁自带核心（bin/yotta-skills.js --inventory）完成，
+自包含原则：扫描由元阁自带核心（bin/yotta-skills.js --inventory / --reindex）完成，
 不依赖任何元技能；数据只写本机 ~/.yottaskills/registry.json，不出本机。
 
 运行：python scripts/yotta-skills-mcp.py
@@ -23,7 +23,7 @@ import subprocess
 import sys
 from pathlib import Path
 
-VERSION = "0.2.0"
+VERSION = "0.3.0"
 TOOL_NAME = "yotta-skills"
 CN_NAME = "元阁"
 MCP_PROTOCOL = "2025-03-26"
@@ -123,13 +123,13 @@ def _tool_describe(arguments):
 
 
 def _tool_reindex(arguments):  # noqa: ARG001
-    stdout = _run_cli(["--inventory", "--json"])
+    stdout = _run_cli(["--reindex", "--json"])
     try:
         data = json.loads(stdout)
     except json.JSONDecodeError as e:
         return _tool_error("reindex 输出解析失败：%s" % e)
     payload = {
-        "count": len(data.get("skills", [])),
+        "count": data.get("count", len(data.get("skills", []))),
         "changes": data.get("changes"),
         "errors": data.get("errors"),
         "registry": str(REGISTRY_FILE),
@@ -163,7 +163,7 @@ def mcp_tools():
         ),
         _tool_spec(
             "reindex",
-            "强制重新扫描所有技能目录并更新本地注册表，返回本次变化（新增 / 更新 / 消失）。",
+            "强制重新扫描所有技能目录并更新本地注册表，返回本次变化（新增 / 更新 / 消失）；CLI 等价命令：yotta-skills --reindex。",
             {},
             [],
         ),