@yottameta/yotta-skills-plugin 0.28.2 → 0.29.0

package/.agents/plugins/marketplace.json

@@ -12,7 +12,7 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools",
-      "version": "0.28.2",
+      "version": "0.29.0",
       "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
       "interface": {
         "displayName": "元阁 yotta-skills",

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools",
-      "version": "0.28.2",
+      "version": "0.29.0",
       "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
       "interface": {
         "displayName": "元阁 yotta-skills",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-skills-plugin",
-  "version": "0.28.2",
+  "version": "0.29.0",
   "description": "YuanGe (元阁) — orchestration and routing for the YottaMeta skill family, packaged as a YottaMeta Agent Plugin and DeepSeek Harness profile bundle.",
   "license": "MIT",
   "keywords": [

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "yotta-skills",
-  "version": "0.28.2",
+  "version": "0.29.0",
   "description": "YuanGe (元阁) - orchestration routing, inventory, and one-command installer for the YottaMeta skill family (zero dependencies, Node.js only).",
   "author": {
     "name": "YottaMeta",

package/skills/yotta-skills/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-skills
-version: 0.28.2
-description: 元阁 -- 元阁全家技能的总编排策划 + 编排路由 + 一键安装器 + 技能盘点 + 本机技能 Hub + 运行时 hook 适配。Hub 层：hub hosts 只读发现本机已装智能体与技能目录（文件系统优先，不读元忆；按已核实 / 自动发现 / 桥接分类）；hub install / update 把技能装到 ~/.yottaskills/hub 单点真源（清单 27 + 特殊家族 5，特殊家族跟随各自 npm latest）；hub link --all 用 Windows junction / POSIX symlink 分发到全部已核实宿主（默认范围；--include-discovered 显式纳入自动发现目录；锁 / 数据桥接目录永不链接），元技能在链接时收敛宿主旧副本（移入 ~/.yottaskills/trash 保留 7 天、版本闸门 Hub ≥ 宿主）；hub unlink 只删链接、fail-closed；非元技能不参与更新（用户自行处理）；hub status 显示来源、版本、链接与异常；view 启动本机技能枢纽面板（默认 127.0.0.1:8789，六视图 + 高级 CLI 页，写操作需页面令牌与确认）；兼容 agentskills.io 技能格式、Vercel Labs skills CLI 的 .agents/skills 通用目录与 .skill-lock.json v3（只读）。路由层：--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 记忆裁决 / hub 技能 Hub / install / update / update --check（只读检查）/ update --check --scheduled（后台周检）/ update --auto（家族自动更新）/ hook 适配 / --inventory / --reindex / --dry-run 预览 / --pin（默认）/ --range。触发：需要批量安装或更新元阁全家技能、单点安装并分发到多个智能体、查看本机装了哪些智能体与技能目录、接管非元技能、按场景组合多个元技能、路由或判断该用哪些技能、判断哪些技能值得长期记忆、查看或记录技能使用信号、盘点或查看本机已装技能、重扫技能注册表、给某个智能体或目录一次性铺齐 yotta-* 技能、评估宿主 hook 能力、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/检查更新/自动更新/hook 适配/该用哪个技能/路由技能/记忆裁决/技能该不该记住/盘点技能/查看已装技能/技能 Hub/单点安装/链接分发/接管技能/技能枢纽面板/图形化面板 等。边界（Do NOT trigger）：只做「组合策划 + 静态路由建议 + M1 记忆裁决只读建议 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index + Hub 本机真源与链接分发 + hook 适配」，不含技能本体、不做技能内容开发、不 -g 污染全局、不自动安装缺失技能、不静默写宿主配置或全局记忆、不自动删除技能或记忆；家族安装先自举或调用元信装前门禁，DO NOT INSTALL 阻断，非元阁家族包不自动安装。
+version: 0.29.0
+description: 元阁 -- 元阁全家技能的总编排策划 + 编排路由 + 一键安装器 + 技能盘点 + 本机技能 Hub + 运行时 hook 适配。Hub 层：hub hosts 只读发现本机已装智能体与技能目录（文件系统优先，不读元忆；已核实 / 自动发现 / 桥接分类 + 状态细分：可用 / 残留（实体未确认）/ 未创建 / 仅标记）；hub hosts add/remove/list/mark 注册自定义宿主目录与手动标记（只注册不建目录、移除不删目录；残留清理 hub hosts remove --purge 默认预览、目录入回收站 7 天）；install-self / where 把元阁管理引擎独立安装（默认 ~/.yottaskills/yotta-skills，--dir 指定）并查看运行位置；hub install / update 把技能装到 ~/.yottaskills/hub 单点真源（清单 27 + 特殊家族 5，特殊家族跟随各自 npm latest）；hub link --all 用 Windows junction / POSIX symlink 分发到全部已核实宿主（默认范围；--include-discovered 显式纳入自动发现目录；锁 / 数据桥接目录永不链接），元技能在链接时收敛宿主旧副本（移入 ~/.yottaskills/trash 保留 7 天、版本闸门 Hub ≥ 宿主）；hub unlink 只删链接、fail-closed；非元技能不参与更新（用户自行处理）；hub status 显示来源、版本、链接与异常；view 启动本机技能枢纽面板（默认 127.0.0.1:8789，六视图 + 高级 CLI 页，写操作需页面令牌与确认）；兼容 agentskills.io 技能格式、Vercel Labs skills CLI 的 .agents/skills 通用目录与 .skill-lock.json v3（只读）。路由层：--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 记忆裁决 / hub 技能 Hub / install-self 独立安装 / where 位置查看 / install / update / update --check（只读检查）/ update --check --scheduled（后台周检）/ update --auto（家族自动更新）/ hook 适配 / --inventory / --reindex / --dry-run 预览 / --pin（默认）/ --range。触发：需要批量安装或更新元阁全家技能、单点安装并分发到多个智能体、查看本机装了哪些智能体与技能目录、接管非元技能、按场景组合多个元技能、路由或判断该用哪些技能、判断哪些技能值得长期记忆、查看或记录技能使用信号、盘点或查看本机已装技能、重扫技能注册表、给某个智能体或目录一次性铺齐 yotta-* 技能、评估宿主 hook 能力、预览安装清单、锁版本安装、或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家/检查更新/自动更新/hook 适配/该用哪个技能/路由技能/记忆裁决/技能该不该记住/盘点技能/查看已装技能/技能 Hub/单点安装/链接分发/接管技能/技能枢纽面板/图形化面板/独立安装元阁/查看元阁位置/自定义宿主/残留清理/宿主状态 等。边界（Do NOT trigger）：只做「组合策划 + 静态路由建议 + M1 记忆裁决只读建议 + 清单 + 下载 + 落位 + 汇总 + 盘点 + re-index + Hub 本机真源与链接分发 + hook 适配」，不含技能本体、不做技能内容开发、不 -g 污染全局、不自动安装缺失技能、不静默写宿主配置或全局记忆、不自动删除技能或记忆；家族安装先自举或调用元信装前门禁，DO NOT INSTALL 阻断，非元阁家族包不自动安装。
 license: MIT
 metadata:
   zh_name: 元阁
@@ -105,11 +105,40 @@ metadata:
 
 ## 快速使用（安装层）
 
+**首选流程（Hub 主路径，安装本体与智能体无关）**：
+
+```bash
+# 1) 看本机有哪些宿主与技能目录（状态细分：可用 / 残留 / 未创建 / 仅标记）
+npx -y @yottameta/yotta-skills hub hosts
+
+# 2) 装进 Hub 真源（默认 ~/.yottaskills/hub；无需指定智能体）
+npx -y @yottameta/yotta-skills hub install
+
+# 3) 分发到全部已核实宿主（Windows junction / macOS·Linux symlink）
+npx -y @yottameta/yotta-skills hub link --all
+
+# 4) 图形化面板管理（宿主矩阵 / 链接与体检 / 收编 / 回滚）
+npx -y @yottameta/yotta-skills view
+```
+
+**元阁独立安装（把管理引擎装成独立 CLI，不依赖任何智能体）**：
+
+```bash
+# 默认装到 ~/.yottaskills/yotta-skills；--dir 指定位置
+npx -y @yottameta/yotta-skills install-self
+npx -y @yottameta/yotta-skills install-self --dir ~/tools/yotta-skills
+
+# 查看元阁位置（运行中 CLI / 独立安装目录 / Hub 真源）
+npx -y @yottameta/yotta-skills where
+```
+
+**指定智能体直装（兼容路径）**：
+
 ```bash
 # 列出全家技能 + 版本 + 说明
 npx -y @yottameta/yotta-skills --list
 
-# 装全家到指定智能体默认用户级目录（推荐）
+# 装全家到指定智能体默认用户级目录
 npx -y @yottameta/yotta-skills install --agent codex
 
 # 装全家到任意目录（每个技能落在 <dir>/<slug>）
@@ -188,11 +217,28 @@ npx -y @yottameta/yotta-skills hub link --all --include-discovered
 npx -y @yottameta/yotta-skills hub status
 npx -y @yottameta/yotta-skills hub doctor
 
+# 5b) 自定义宿主注册（只注册，不创建目录、不改宿主配置；移除注册不删目录）
+npx -y @yottameta/yotta-skills hub hosts add ~/my-agent/skills --label "我的宿主"
+npx -y @yottameta/yotta-skills hub hosts list
+npx -y @yottameta/yotta-skills hub hosts remove ~/my-agent/skills
+
+# 5c) 手动标记状态 / 清理残留（清理默认预览；只删指向 Hub 的链接，目录入回收站 7 天）
+npx -y @yottameta/yotta-skills hub hosts mark ~/my-agent/skills --state orphan
+npx -y @yottameta/yotta-skills hub hosts remove ~/my-agent/skills --purge
+npx -y @yottameta/yotta-skills hub hosts remove ~/my-agent/skills --purge --yes
+
 # 6) 本地面板：预览、确认、执行、留证（仅 127.0.0.1:8789）
 npx -y @yottameta/yotta-skills view
 
 # 只删链接，不动 Hub 真源（真目录 / 外部链接一律拒绝）
 npx -y @yottameta/yotta-skills hub unlink --all
+
+# 指定智能体分发 / 解除（只影响该宿主；Hub 真源保留）
+npx -y @yottameta/yotta-skills hub link yotta-memory --agent codex
+npx -y @yottameta/yotta-skills hub unlink yotta-memory --agent codex
+
+# 彻底删除 Hub 技能：全宿主清链接（含死链）+ 目录入回收站 + 清台账 + 审计
+npx -y @yottameta/yotta-skills hub remove my-skill --dry-run
 ```
 
 链接范围（0.28.0 起）：`hub hosts` 把目录分为已核实 / 自动发现 / 桥接三类 ——
@@ -202,11 +248,24 @@ npx -y @yottameta/yotta-skills hub unlink --all
 `hub doctor` 的 `link_scope` 检查只读报告范围外链接。逐智能体核实表见
 发布方内部核实记录；本机可随时用 `hub hosts` 复算分类与范围。
 
+状态细分（0.29.0 起）：每条宿主目录带生命周期状态 —— **可用**（实体已确认：应用标记 /
+用户注册 / 手动标记）、**残留**（实体未确认；可手动确认后清理）、**未创建**、
+**仅标记**（已装实体、技能目录未创建）；`hub doctor` 的 `host_state` 检查只读提示，
+不判 fail。残留清理 = `hub hosts remove <目录> --purge`（默认预览，`--yes` 执行；
+只删指向 Hub 的链接，非 Hub 链接 / 非技能内容随目录保留在回收站 7 天）。
+
 宿主发现兼容 `agentskills.io` 技能格式与 Vercel Labs `skills` CLI 的
 `.agents/skills` 通用目录；已收录 81 条宿主映射，并只读兼容
 `.skill-lock.json` v3（`$XDG_STATE_HOME/skills/` 或 `~/.agents/`）。
 不读元忆，不重写官方锁文件，不静默降级为复制。
 
+删除技能（0.28.3 起）：`hub remove <slug>` 一条命令完成「全宿主清链接（含死链）→
+Hub 目录入回收站（保留 7 天）→ 清 Hub / 链接台账 → 写审计」，fail-closed：只删指向
+Hub 的链接与 Hub 内目录，真副本 / 外部链接一律保留并报告；链接清理报错即中止、不删
+Hub。默认范围为已核实宿主 ∪ 本技能链接台账；`--agent` / `--dir` 收窄仅用于 Hub 目标
+已缺失的死链清理（防止只清一个宿主导致其他宿主变死链）。指定智能体分发 / 解除用
+`hub link|unlink <slug> --agent <id>`。
+
 ## 命令与选项
 
 | 命令 / 选项 | 作用 |
@@ -235,9 +294,10 @@ npx -y @yottameta/yotta-skills hub unlink --all
 | `hub refresh <slug> --from <path>` | 手动同步非元阁技能（重新收编 + 更新哈希 + 台账） |
 | `hub link --agent <id> \| --dir <dir> \| --all [--include-discovered]` | 把 Hub 技能链接到指定宿主 / 目录 / 全部已核实宿主（默认范围）；`--include-discovered` 显式纳入自动发现目录；元技能链接时收敛旧副本（回收站 7 天）；`--dry-run` 只预览（含将收敛明细）；`--force` 可替换指向 Hub 之外的链接（仅移除链接本身） |
 | `hub unlink --agent <id> \| --dir <dir> \| --all [--include-discovered]` | 只删除链接；lstat + readlink 校验目标在 Hub 内，fail-closed；清理范围外链接用 `--dir <目录>` 精确指定 |
+| `hub remove <slug> [--dry-run] [--include-discovered]` | 删除 Hub 技能：全宿主清链接（含死链）+ Hub 目录入回收站（7 天）+ 清 Hub / 链接台账 + 写审计；fail-closed（真副本 / 外部链接保留并报告；链接报错即中止不删 Hub）；`--agent` / `--dir` 收窄仅用于死链清理 |
 | `hub status [--json]` | 查看 Hub 技能来源、版本、链接宿主、异常链接与宿主发现摘要 |
 | `hub doctor [--json]` | 检查断链 / Hub 目标缺失 / slug 不一致 / 单一真源（只读报告多份副本与版本参差）/ 链接范围（`link_scope` 只读报告范围外链接）/ 目录权限；异常时退出码 1 |
-| `view [--port <n>]` | 启动本机技能枢纽面板（默认 `127.0.0.1:8789`，仅本机监听）：六视图（概览 / 宿主矩阵 / 收编向导 / 链接与体检 / 记录与回滚 / 路由与编排）+ 高级 CLI 页；可执行收编 / 链接 / 解除 / 回滚，写操作需页面会话令牌与破坏性确认，install / update / refresh 只给命令 |
+| `view [--port <n>]` | 启动本机技能枢纽面板（默认 `127.0.0.1:8789`，仅本机监听）：六视图（概览 / 宿主矩阵 / 收编向导 / 链接与体检 / 记录与回滚 / 路由与编排）+ **全量 CLI 页**（全部命令 / 子命令 + 人话说明 + 可复制示例 + 完整选项，与 `--help` 单一真源）；可执行收编 / 链接 / 解除 / 回滚 / 删除技能（影响预览 + 手输 slug 二次确认），写操作需页面会话令牌，install / update / refresh 只给命令 |
 | `--route <需求摘要>` | 编排路由：输出组合、调用顺序、技能角色、置信度、依据、已装/缺失状态与安装建议；可选本地 provider 增补 / 重排并返回 `confidence` / `reasons` / `summary` / `alternatives`；`--json` 输出 JSON、`--project` 附扫项目级目录 |
 | `usage status` | 查看本地使用记录开关与计数；默认关闭，不创建文件 |
 | `usage enable` / `usage disable` | 开启 / 关闭 `--route` 的结构化使用记录；不记录需求原文 |

package/skills/yotta-skills/assets/view.html

@@ -50,6 +50,9 @@
   .page-sub{color:var(--faint);font-size:12px;margin-top:2px}
   .spacer{flex:1}
   .chip{display:flex;align-items:center;gap:7px;padding:5px 10px;border:1px solid var(--line);border-radius:999px;color:var(--muted);font-size:12px;white-space:nowrap}
+  .chips{display:flex;gap:6px;flex-wrap:wrap}
+  .chip{cursor:pointer;background:transparent}
+  .chip.active{color:var(--acc);border-color:rgba(95,191,143,.45);background:rgba(95,191,143,.10)}
   .dot{width:7px;height:7px;border-radius:50%;background:var(--acc)}
 
   .view{display:none}.view.active{display:block}
@@ -132,6 +135,10 @@
   .cmd code{flex:1;min-width:0;word-break:break-all;color:var(--text)}
   .cmd .why{color:var(--faint);font-size:11px}
   .note{color:var(--muted);font-size:12px;margin-top:8px}
+  .cmd-detail{border:1px solid var(--line);border-radius:6px;background:var(--panel2);margin-top:8px;padding:0 11px;min-width:0}
+  .cmd-detail summary{cursor:pointer;padding:9px 0;display:flex;gap:8px;align-items:baseline;flex-wrap:wrap}
+  .cmd-detail .note{padding:0 0 8px}
+  .cmd-detail .cmd{margin:0 0 8px}
 
   @media (max-width:980px){.g4{grid-template-columns:repeat(2,minmax(0,1fr))}}
   @media (max-width:760px){
@@ -188,7 +195,10 @@
       <div class="grid g4" id="ovCards"></div>
       <div class="section" id="ovDoctor"></div>
       <div class="section grid g2">
-        <div class="panel"><h3>Hub 内容</h3><div class="faint">技能真源在 Hub 目录，宿主目录通过链接分发。</div><div class="list" id="ovSkills"></div></div>
+        <div class="panel"><h3>Hub 内容</h3><div class="faint">技能真源在 Hub 目录，宿主目录通过链接分发。</div>
+          <label class="search section" style="min-width:100%"><svg class="sv" viewBox="0 0 24 24"><circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/></svg><input id="ovSkillFilter" placeholder="过滤技能（输入后显示全部匹配）"></label>
+          <div class="list" id="ovSkills"></div>
+        </div>
         <div class="panel"><h3>最近动作</h3><div class="faint">收编 / 链接 / 解除都写入 Hub 审计。</div><div class="list" id="ovAudit"></div></div>
       </div>
       <div class="section panel">
@@ -206,10 +216,12 @@
     <section class="view" id="view-hosts">
       <div class="toolbar">
         <label class="search"><svg class="sv" viewBox="0 0 24 24"><circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/></svg><input id="hostSearch" placeholder="过滤宿主 / 目录"></label>
-        <span class="label" id="hostSummary"></span>
+        <div class="chips" id="hostStateChips"></div>
+        <button class="btn small" id="hostAddBtn">添加自定义目录</button>
       </div>
       <div class="section panel">
-        <table><thead><tr><th>宿主</th><th>技能目录</th><th>范围</th><th>目录技能</th><th>指向 Hub</th><th>异常</th><th>状态</th></tr></thead><tbody id="hostRows"></tbody></table>
+        <div class="faint" id="hostSummary"></div>
+        <table><thead><tr><th>宿主</th><th>技能目录</th><th>范围</th><th>目录技能</th><th>指向 Hub</th><th>异常</th><th>状态</th><th></th></tr></thead><tbody id="hostRows"></tbody></table>
         <div class="empty" id="hostEmpty" hidden>没有匹配的宿主目录。</div>
       </div>
       <div class="section panel"><h3>已安装标记（无技能目录的宿主）</h3><div class="list" id="hostMarks"></div></div>
@@ -286,9 +298,18 @@
     <section class="view" id="view-cli">
       <div class="banner">
         <svg class="sv" viewBox="0 0 24 24"><path d="m4 7 5 5-5 5"/><path d="M12 19h8"/></svg>
-        <div><div class="banner-title">高级 CLI</div><div class="banner-body">低频 / 长尾命令在这里复制到终端执行；网页不代替终端运行安装与更新。</div></div>
+        <div><div class="banner-title">高级 CLI（全量）</div><div class="banner-body">全部命令 + 人话说明 + 可复制示例；网页只展示与复制，不代替终端执行安装、更新与删除。</div></div>
+      </div>
+      <div class="section panel">
+        <div class="shead"><h2>命令速查</h2><span class="faint" id="cliMeta">加载中…</span></div>
+        <div id="cliQuick"></div>
+      </div>
+      <div class="section panel">
+        <details id="cliFullWrap">
+          <summary>完整命令与参数（点击展开）</summary>
+          <div id="cliFull"></div>
+        </details>
       </div>
-      <div id="cliGroups"></div>
     </section>
   </main>
 </div>
@@ -299,7 +320,7 @@
 <script>
 (function () {
   var TOKEN = (document.querySelector('meta[name="yotta-view-token"]') || {}).content || '';
-  var state = { view: 'overview', overview: null, hosts: null, adopt: null, selected: {}, records: null, tab: 'snapshots', hostFilter: '', adoptFilter: '' };
+  var state = { view: 'overview', overview: null, hosts: null, adopt: null, selected: {}, records: null, tab: 'snapshots', hostFilter: '', hostStateFilter: '', adoptFilter: '', ovSkillFilter: '' };
 
   function $(sel) { return document.querySelector(sel); }
   function esc(value) {
@@ -380,7 +401,7 @@
     links: { title: '链接与体检', sub: '断链 / 漂移 / 目标缺失在哪、怎么修', load: loadLinks },
     records: { title: '记录与回滚', sub: '安装、收编、链接都做了什么，怎么退回', load: loadRecords },
     route: { title: '路由与编排', sub: '一句话需求该用哪些技能、缺什么（只读）', load: null },
-    cli: { title: '高级 CLI', sub: '低频命令速查与复制', load: null }
+    cli: { title: '高级 CLI', sub: '全量命令速查与复制（与 CLI --help 同源）', load: null }
   };
   var loadSeq = 0;
   function showLoad(text) {
@@ -450,10 +471,7 @@
       statCard('异常链接', d.status.summary.brokenLinks, d.status.summary.brokenLinks ? '需要处理' : '全部正常', d.status.summary.brokenLinks ? 'danger' : 'ok') +
       statCard('Doctor', d.doctor.ok ? '通过' : '未通过', '错误 ' + d.doctor.summary.errors + ' / 警告 ' + d.doctor.summary.warnings, d.doctor.ok ? 'ok' : 'danger');
     $('#ovDoctor').innerHTML = doctorBanner(d.doctor);
-    var skills = d.status.skills || [];
-    $('#ovSkills').innerHTML = skills.length ? skills.slice(0, 8).map(function (s) {
-      return '<div class="row"><div class="row-main"><div class="row-title">' + esc(s.slug) + '</div><div class="row-meta">v' + esc(s.version || '-') + ' · ' + esc(s.origin === 'external' ? '外部来源' : '元阁家族') + ' · 链接 ' + (s.links || []).length + '</div></div><span class="badge ' + (s.status === 'present' ? 'ok' : 'danger') + '">' + esc(s.status === 'present' ? '已入库' : '缺失') + '</span></div>';
-    }).join('') : '<div class="empty">Hub 还是空的。先在「收编向导」把已装技能收编进来。</div>';
+    renderOverviewSkills();
     var audit = (d.audit && d.audit.recent) || [];
     $('#ovAudit').innerHTML = audit.length ? audit.slice().reverse().map(function (a) {
       return '<div class="row"><div class="row-main"><div class="row-title">' + esc(a.event || '动作') + ' · ' + esc(a.slug || '') + '</div><div class="row-meta">' + esc(fmtTime(a.at)) + (a.verdict ? ' · ' + esc(a.verdict) : '') + '</div></div></div>';
@@ -462,38 +480,166 @@
     $('#copyHubDir').onclick = function () { copyText(d.hubDir); };
   }
 
+  function renderOverviewSkills() {
+    var d = state.overview;
+    if (!d) return;
+    var skills = (d.status && d.status.skills) || [];
+    var filter = state.ovSkillFilter.trim().toLowerCase();
+    var list = filter
+      ? skills.filter(function (s) { return String(s.slug || '').toLowerCase().indexOf(filter) >= 0; })
+      : skills.slice(0, 8);
+    $('#ovSkills').innerHTML = list.length ? list.map(function (s) {
+      return '<div class="row"><div class="row-main"><div class="row-title">' + esc(s.slug) + '</div><div class="row-meta">v' + esc(s.version || '-') + ' · ' + esc(s.origin === 'external' ? '外部来源' : '元阁家族') + ' · 链接 ' + (s.links || []).length + '</div></div>' +
+        '<span class="badge ' + (s.status === 'present' ? 'ok' : 'danger') + '">' + esc(s.status === 'present' ? '已入库' : '缺失') + '</span>' +
+        '<div class="row-actions"><button class="btn small danger" data-remove-skill="' + esc(s.slug) + '">删除</button></div></div>';
+    }).join('') : '<div class="empty">' + (filter ? '没有匹配的技能。' : 'Hub 还是空的。先在「收编向导」把已装技能收编进来。') + '</div>';
+  }
+  $('#ovSkillFilter').addEventListener('input', function () {
+    state.ovSkillFilter = $('#ovSkillFilter').value || '';
+    renderOverviewSkills();
+  });
+  $('#ovSkills').addEventListener('click', async function (e) {
+    var b = e.target.closest('[data-remove-skill]');
+    if (!b) return;
+    var slug = b.dataset.removeSkill;
+    var plan = await api('/api/skills/remove-plan?slug=' + encodeURIComponent(slug));
+    if (!plan || plan.error) { toast((plan && plan.error) || '影响预览失败'); return; }
+    var targets = plan.targets || [];
+    var willUnlink = targets.filter(function (t) { return t.action === 'unlink'; });
+    var kept = targets.filter(function (t) { return t.action === 'keep'; });
+    var rows = targets.map(function (t) {
+      var tone = t.action === 'unlink' ? 'warn' : t.action === 'keep' ? 'info' : '';
+      return '<div class="result"><span class="badge ' + tone + '">' + esc(t.action === 'unlink' ? '将清理' : t.action === 'keep' ? '保留' : '无动作') + '</span><span class="mono">' + esc(t.dir) + '</span><span class="faint">' + esc(t.note || '') + '</span></div>';
+    }).join('');
+    var body = '<p class="label">将清理 ' + willUnlink.length + ' 条宿主链接（含死链）' +
+      (plan.hubPresent ? '，并把 Hub 目录移入回收站（保留 7 天）' : '；Hub 目录已缺失，仅清理残留') +
+      '；保留 ' + kept.length + ' 项宿主真副本 / 外部链接。</p>' +
+      '<div class="result-list">' + (rows || '<div class="faint">没有需要处理的宿主目录。</div>') + '</div>' +
+      '<div class="section"><label class="label">输入完整技能名确认：' + esc(slug) + '</label><input id="removeConfirmSlug" placeholder="' + esc(slug) + '"></div>';
+    confirmModal('删除 Hub 技能 ' + slug + '？', body, '删除', true, async function () {
+      var typed = ($('#removeConfirmSlug') && $('#removeConfirmSlug').value || '').trim();
+      if (typed !== slug) { toast('技能名不匹配'); return; }
+      var r = await api('/api/skills/remove', { body: { slug: slug, confirm: 'remove', confirmSlug: typed } });
+      if (r.error) { toast(r.error); return; }
+      closeModal();
+      toast(r.verdict === 'cleanup-only' ? '已清理残留（Hub 目录原本缺失）' : '已删除 ' + slug + '（目录已入回收站）');
+      loadOverview();
+    });
+  });
+
   async function loadHosts() {
     var d = await api('/api/hosts');
     if (d.error) { toast(d.error); return; }
     state.hosts = d;
-    $('#hostSummary').textContent = '目录 ' + d.summary.existing + ' / ' + d.summary.hosts + '（已核实 ' + d.summary.verified + ' · 自动发现 ' + d.summary.discovered + ' · 桥接 ' + d.summary.bridge + '）· 已装标记 ' + d.summary.installedMarks + ' · 链接 ' + d.summary.links;
+    var s = d.summary.states || {};
+    $('#hostSummary').textContent = '可用 ' + (s.available || 0) + ' · 残留 ' + (s.orphan || 0) + ' · 未创建 ' + (s.missing || 0) + ' · 仅标记 ' + (s.markerOnly || 0) + (s.ignored ? ' · 已忽略 ' + s.ignored : '') + ' · 链接 ' + d.summary.links + '（异常 ' + d.summary.brokenLinks + '）';
+    renderHostStateChips();
     renderHosts();
     var marks = d.installed || [];
     $('#hostMarks').innerHTML = marks.length ? marks.map(function (m) {
       return '<div class="row"><div class="row-main"><div class="row-title">' + esc(m.label) + '</div><div class="row-meta">' + esc(m.source || '') + (m.hasSkillsDir ? ' · 技能目录：' + esc(m.skillDir || '') : ' · 未发现技能目录') + '</div></div><span class="badge ' + (m.hasSkillsDir ? 'ok' : 'info') + '">' + esc(m.hasSkillsDir ? '可链接' : '仅标记') + '</span></div>';
     }).join('') : '<div class="empty">没有检测到额外宿主标记。</div>';
   }
+  function renderHostStateChips() {
+    var d = state.hosts; if (!d) return;
+    var s = d.summary.states || {};
+    var chips = [
+      ['', '全部'],
+      ['available', '可用 ' + (s.available || 0)],
+      ['orphan', '残留 ' + (s.orphan || 0)],
+      ['missing', '未创建 ' + (s.missing || 0)],
+      ['marker-only', '仅标记 ' + (s.markerOnly || 0)],
+    ];
+    $('#hostStateChips').innerHTML = chips.map(function (c) {
+      return '<button class="chip' + (state.hostStateFilter === c[0] ? ' active' : '') + '" data-host-state="' + esc(c[0]) + '">' + esc(c[1]) + '</button>';
+    }).join('');
+  }
+  function hostStateBadge(h) {
+    if (h.bridgeOnly) return '<span class="badge info">桥接</span>';
+    var map = { available: ['ok', '可用'], orphan: ['warn', '残留'], missing: ['', '未创建'], 'marker-only': ['info', '仅标记'], ignored: ['', '已忽略'] };
+    var item = map[h.state] || ['', h.state || '未知'];
+    return '<span class="badge ' + item[0] + '">' + esc(item[1]) + (h.stateSource === 'manual' ? '·手动' : '') + '</span>' + (h.brokenLinks ? ' <span class="badge danger">异常</span>' : '');
+  }
   function renderHosts() {
     var d = state.hosts; if (!d) return;
     var q = state.hostFilter.toLowerCase();
+    var sf = state.hostStateFilter;
     var rows = (d.hosts || []).filter(function (h) {
+      if (sf && h.state !== sf) return false;
       if (!q) return true;
       return String(h.label || '').toLowerCase().includes(q) || String(h.dir || '').toLowerCase().includes(q);
     });
     $('#hostEmpty').hidden = rows.length > 0;
     $('#hostRows').innerHTML = rows.map(function (h) {
-      var status = !h.exists ? '<span class="badge">未创建</span>' : (h.brokenLinks ? '<span class="badge danger">有异常</span>' : '<span class="badge ok">可用</span>');
-      var scopeBadge = h.bridgeOnly ? '<span class="badge info">桥接·不链</span>' : h.verified ? '<span class="badge ok">已核实</span>' : '<span class="badge warn">自动发现</span>';
+      var scopeBadge = h.bridgeOnly ? '<span class="badge info">桥接·不链</span>' : (h.detection === 'user-registry' ? '<span class="badge info">用户注册</span>' : h.verified ? '<span class="badge ok">已核实</span>' : '<span class="badge warn">自动发现</span>');
+      var action = '';
+      if (h.exists && h.state === 'orphan' && !h.bridgeOnly) action += '<button class="btn small danger" data-host-purge="' + esc(h.dir) + '">清理</button> ';
+      if (h.detection === 'user-registry') action += '<button class="btn small" data-host-unregister="' + esc(h.dir) + '">移除注册</button>';
       return '<tr><td><div class="cell-main">' + esc(h.label) + '</div><div class="cell-sub">' + esc(h.agentId || (h.known ? '已知宿主' : h.detection || '自动发现')) + '</div></td>' +
         '<td><div class="mono">' + esc(h.dir) + '</div><button class="btn small" data-copy="' + esc(h.dir) + '">复制</button></td>' +
         '<td>' + scopeBadge + '</td>' +
-        '<td>' + esc(h.skillCount || 0) + '</td><td>' + esc(h.hubLinks || 0) + '</td><td>' + esc(h.brokenLinks || 0) + '</td><td>' + status + '</td></tr>';
+        '<td>' + esc(h.skillCount || 0) + '</td><td>' + esc(h.hubLinks || 0) + '</td><td>' + esc(h.brokenLinks || 0) + '</td><td>' + hostStateBadge(h) + '</td><td>' + action + '</td></tr>';
     }).join('');
   }
   $('#hostSearch').addEventListener('input', function (e) { state.hostFilter = e.target.value; renderHosts(); });
-  $('#hostRows').addEventListener('click', function (e) {
-    var b = e.target.closest('[data-copy]');
-    if (b) copyText(b.dataset.copy);
+  $('#hostStateChips').addEventListener('click', function (e) {
+    var b = e.target.closest('[data-host-state]');
+    if (!b) return;
+    state.hostStateFilter = b.dataset.hostState;
+    renderHostStateChips();
+    renderHosts();
+  });
+  $('#hostAddBtn').addEventListener('click', function () {
+    var body = '<p class="label">注册自定义宿主目录：纳入发现 / 分发 / 收编。不创建目录、不改宿主配置。</p>' +
+      '<div class="section"><label class="label">目录（必须已存在）</label><input id="hostAddDir" placeholder="例如 D:\\my-agent\\skills"></div>' +
+      '<div class="section"><label class="label">名称（可选，默认目录名）</label><input id="hostAddLabel" placeholder="我的宿主"></div>';
+    openModal('添加自定义目录', body, {
+      okText: '注册',
+      onOk: async function () {
+        var dir = ($('#hostAddDir') && $('#hostAddDir').value || '').trim();
+        var label = ($('#hostAddLabel') && $('#hostAddLabel').value || '').trim();
+        if (!dir) { toast('请填写目录'); return; }
+        var r = await api('/api/hosts/add', { body: { dir: dir, label: label } });
+        if (r.error) { toast(r.error); return; }
+        closeModal();
+        toast('已注册：' + ((r.entry && r.entry.label) || dir));
+        loadHosts();
+      },
+    });
+  });
+  async function openHostPurgeModal(dir) {
+    var plan = await api('/api/hosts/purge-plan?dir=' + encodeURIComponent(dir));
+    if (plan.error) { toast(plan.error); return; }
+    var body = '<p class="label">只删除指向 Hub 的链接（含死链）；非 Hub 链接 / 非技能内容随目录保留在回收站（7 天可恢复）。</p>' +
+      '<div class="result"><span class="badge warn">将解除链接</span><b>' + esc(plan.unlinkCount) + '</b><span>条（保留 ' + esc(plan.keptLinks) + ' 非 Hub 链接 / ' + esc(plan.keptEntries) + ' 非链接内容）</span></div>' +
+      '<div class="mono">' + esc(dir) + '</div>' +
+      '<div class="section"><label class="label">输入 purge 确认执行：</label><input id="hostPurgeConfirm" placeholder="purge"></div>';
+    confirmModal('清理残留目录？', body, '清理（移入回收站）', true, async function () {
+      var typed = ($('#hostPurgeConfirm') && $('#hostPurgeConfirm').value || '').trim();
+      if (typed !== 'purge') { toast('确认串不匹配（输入 purge）'); return; }
+      var r = await api('/api/hosts/purge', { body: { dir: dir, confirm: 'purge' } });
+      if (r.error) { toast(r.error); return; }
+      closeModal();
+      toast('已清理：解除 ' + r.unlinkCount + ' 条链接；回收站保留 7 天');
+      loadHosts();
+    });
+  }
+  $('#hostRows').addEventListener('click', async function (e) {
+    var copyBtn = e.target.closest('[data-copy]');
+    if (copyBtn) { copyText(copyBtn.dataset.copy); return; }
+    var purgeBtn = e.target.closest('[data-host-purge]');
+    if (purgeBtn) { openHostPurgeModal(purgeBtn.dataset.hostPurge); return; }
+    var unregBtn = e.target.closest('[data-host-unregister]');
+    if (unregBtn) {
+      var dir = unregBtn.dataset.hostUnregister;
+      confirmModal('移除注册？', '<p class="label">只移除自定义宿主注册，不删除目录、不改宿主配置。</p><div class="mono">' + esc(dir) + '</div>', '移除注册', false, async function () {
+        var r = await api('/api/hosts/remove', { body: { dir: dir } });
+        if (r.error) { toast(r.error); return; }
+        closeModal();
+        toast('已移除注册（目录保留）');
+        loadHosts();
+      });
+    }
   });
 
   async function loadAdopt() {
@@ -722,40 +868,58 @@
     if (b) copyText(b.dataset.copyCmd);
   });
 
-  var CLI_GROUPS = [
-    { name: 'Hub 发现与安装', items: [
-      { cmd: 'yotta-skills hub hosts', why: '发现本机宿主与技能目录' },
-      { cmd: 'yotta-skills hub install', why: '把元阁家族装进 Hub 真源' },
-      { cmd: 'yotta-skills hub adopt --scan', why: '只读预演收编候选与冲突' },
-      { cmd: 'yotta-skills hub adopt --apply', why: '执行收编（默认复制保真）' },
-    ] },
-    { name: '链接与体检', items: [
-      { cmd: 'yotta-skills hub link --all', why: '链接到已核实宿主（默认范围）' },
-      { cmd: 'yotta-skills hub link --all --include-discovered', why: '显式纳入自动发现目录' },
-      { cmd: 'yotta-skills hub link --agent codex', why: '只链接到一个宿主' },
-      { cmd: 'yotta-skills hub unlink --all', why: '只删链接，不动 Hub 真源' },
-      { cmd: 'yotta-skills hub status', why: '查看技能 / 来源 / 链接' },
-      { cmd: 'yotta-skills hub doctor', why: '检查断链 / 缺失 / slug 不一致' },
-    ] },
-    { name: '安装与更新', items: [
-      { cmd: 'yotta-skills update --installed-only --dir <技能目录>', why: '只维护已装元技能' },
-      { cmd: 'yotta-skills update --check', why: '只读检查更新' },
-      { cmd: 'yotta-skills rollback --list', why: '查看可回滚快照' },
-      { cmd: 'yotta-skills rollback --slug <技能> --dir <技能目录>', why: '回滚单个技能' },
-    ] },
-    { name: '路由与使用', items: [
-      { cmd: 'yotta-skills --route "帮我做发布前质量检查"', why: '静态编排路由 + 动态路由块' },
-      { cmd: 'yotta-skills --list', why: '列出全家技能与版本' },
-      { cmd: 'yotta-skills --inventory --json', why: '盘点本机已装技能' },
-    ] },
-  ];
-  $('#cliGroups').innerHTML = CLI_GROUPS.map(function (g) {
-    return '<div class="panel cmd-group"><h3>' + esc(g.name) + '</h3>' + g.items.map(function (item) {
-      return '<div class="cmd"><code>' + esc(item.cmd) + '</code><span class="why">' + esc(item.why) + '</span><button class="btn small" data-copy-cmd="' + esc(item.cmd) + '">复制</button></div>';
+  /* 高级 CLI：/api/help 单一真源（与 CLI --help 同源） */
+  function findHelpEntry(groups, ref) {
+    var seg = String(ref).split(' ');
+    for (var i = 0; i < groups.length; i++) {
+      var cmds = groups[i].commands || [];
+      for (var j = 0; j < cmds.length; j++) {
+        var c = cmds[j];
+        if (c.name !== seg[0]) continue;
+        if (seg.length === 1) return c;
+        var subs = c.subcommands || [];
+        for (var k = 0; k < subs.length; k++) if (subs[k].name === seg[1]) return subs[k];
+      }
+    }
+    return null;
+  }
+  function renderCliHelp(d) {
+    if (!d || d.error) { $('#cliMeta').textContent = '帮助加载失败'; return; }
+    var total = 0;
+    (d.groups || []).forEach(function (g) {
+      (g.commands || []).forEach(function (c) { total += 1 + (c.subcommands || []).length; });
+    });
+    $('#cliMeta').textContent = 'v' + (d.version || '-') + ' · 命令 ' + total + ' · 选项 ' + (d.options || []).length;
+    $('#cliQuick').innerHTML = (d.quick || []).map(function (g) {
+      return '<div class="cmd-group"><h3>' + esc(g.group) + '</h3>' + (g.items || []).map(function (item) {
+        var meta = findHelpEntry(d.groups, item.cmd) || {};
+        return '<div class="cmd"><code>' + esc(item.example) + '</code><span class="why">' + esc(meta.what || '') +
+          (item.note ? ' · ' + esc(item.note) : '') + '</span>' +
+          (item.danger ? '<span class="badge danger">危险</span>' : '') +
+          '<button class="btn small" data-copy-cmd="' + esc(item.example) + '">复制</button></div>';
+      }).join('') + '</div>';
+    }).join('');
+    var full = (d.groups || []).map(function (g) {
+      return '<div class="cmd-group"><h3>' + esc(g.group) + '</h3>' + (g.commands || []).map(function (c) {
+        var opts = (c.options || []).length
+          ? '<div class="note">常用选项: ' + c.options.map(function (f) { return '<code>' + esc(f) + '</code>'; }).join(' ') + '</div>'
+          : '';
+        var subs = (c.subcommands || []).map(function (s) {
+          return '<div class="cmd"><code>' + esc('yotta-skills ' + s.usage) + '</code><span class="why">' + esc(s.what || '') + '</span><button class="btn small" data-copy-cmd="' + esc('yotta-skills ' + s.usage) + '">复制</button></div>';
+        }).join('');
+        return '<details class="cmd-detail"><summary><code>' + esc('yotta-skills ' + c.usage) + '</code> <span class="why">' + esc(c.what || '') + '</span></summary>' +
+          (c.when ? '<div class="note">' + esc(c.when) + '</div>' : '') + opts + subs + '</details>';
+      }).join('') + '</div>';
+    }).join('');
+    full += '<div class="cmd-group"><h3>完整选项</h3>' + (d.options || []).map(function (o) {
+      return '<div class="cmd"><code>' + esc(o.flag + (o.arg ? ' ' + o.arg : '')) + '</code><span class="why">' + esc(o.what || '') +
+        (o.when ? ' · ' + esc(o.when) : '') + (o.caution ? ' · ⚠ ' + esc(o.caution) : '') + '</span></div>';
     }).join('') + '</div>';
-  }).join('');
+    $('#cliFull').innerHTML = full;
+  }
+  api('/api/help').then(renderCliHelp);
   document.addEventListener('click', function (e) {
-    var b = e.target.closest('#cliGroups [data-copy-cmd]');
+    var b = e.target.closest('#view-cli [data-copy-cmd]');
     if (b) copyText(b.dataset.copyCmd);
   });