@yottameta/yotta-skills-plugin 0.29.10 → 0.30.1

package/skills/yotta-skills/lib/cli-help.js

@@ -179,24 +179,25 @@ const CLI_HELP_MODEL = [
         subcommands: [
           { name: 'hosts', usage: 'hub hosts [--json] [--state <state>]', what: '发现宿主与技能目录（可用 / 残留 / 未创建 / 仅标记 / 桥接）', when: '先看这台机器有哪些宿主目录时', options: ['--json', '--state'] },
           { name: 'hosts add', usage: 'hub hosts add <dir> [--label <名称>] [--id <agentId>] [--json]', what: '注册自定义宿主目录（纳入发现 / 分发 / 收编；不创建目录）', when: '宿主未被自动识别或识别错误时', options: ['--label', '--id', '--json'] },
-          { name: 'hosts remove', usage: 'hub hosts remove <dir | --id <agentId>> [--purge [--yes]] [--json]', what: '移除注册（绝不删目录）；--purge = 清理残留目录（默认预览，--yes 执行）', when: '注销自定义宿主、清理残留目录时', options: ['--id', '--purge', '--yes', '--json'] },
-          { name: 'hosts list', usage: 'hub hosts list [--json]', what: '查看自定义宿主注册表（hosts.json）', when: '核对已注册的自定义目录时', options: ['--json'] },
-          { name: 'hosts mark', usage: 'hub hosts mark <dir> --state <available|orphan|ignored> [--json]', what: '手动标记宿主状态（可用 / 残留 / 忽略）', when: '实体证据不足需要人工确认时', options: ['--state', '--json'] },
-          { name: 'hosts exclude', usage: 'hub hosts exclude <agentId|dir> [--json]', what: '加入「不接管」名单（发现 / 显示 / 链接三层跳过）', when: '某宿主 / 目录不归元阁管理时', options: ['--json'] },
+          { name: 'hosts rename', usage: 'hub hosts rename <dir | --id <agentId>> --label <名称> [--json]', what: '一步改名（只改显示名；目录与手动状态保持）', when: '自定义宿主显示名不合适时', options: ['--label', '--id', '--json'] },
+          { name: 'hosts remove', usage: 'hub hosts remove <dir | --id <agentId>> [--purge [--yes]] [--json]', what: '移除注册（绝不删目录）；--purge = 清理残留目录（默认预览，--yes 执行）', when: '注销自定义宿主、清理残留目录时', options: ['--id', '--purge', '--yes', '--json'], impact: '影响面：只移除注册表条目（目录保留）；--purge 会把残留目录移入回收站（保留 7 天）；不会自动清理该目录里已有的 Hub 链接。', alternative: '替代路径：只想暂停接管用 hub hosts exclude；清理该目录链接用 hub unlink --dir "<目录>"。' },
+          { name: 'hosts list', usage: 'hub hosts list [--json]', what: '查看自定义宿主注册表（仅手动 add 的目录；全部宿主用 hub hosts）', when: '核对已注册的自定义目录时', options: ['--json'] },
+          { name: 'hosts mark', usage: 'hub hosts mark <dir> --state <available|orphan|ignored> [--json]', what: '手动标记宿主状态（可用 / 残留 / 隐藏标记）；隐藏标记只影响显示，不拦截行为', when: '实体证据不足需要人工确认、或想让某行从列表淡化时', options: ['--state', '--json'], impact: '影响面：纯状态标记（available / orphan / ignored），不移动目录、不改链接。真正拦截行为的是「不接管」（hosts exclude）。' },
+          { name: 'hosts exclude', usage: 'hub hosts exclude <agentId|dir> [--json]', what: '加入「不接管」名单（发现 / 显示 / 链接三层跳过）', when: '某宿主 / 目录不归元阁管理时', options: ['--json'], impact: '影响面：发现 / 显示 / 链接三层全部跳过（--include-discovered 也不纳入）；已有链接不动。', alternative: '替代路径：只淡化显示用 hub hosts mark --state ignored；恢复接管用 hub hosts include。' },
           { name: 'hosts include', usage: 'hub hosts include <agentId|dir> [--json]', what: '恢复接管（移出「不接管」名单）', when: '重新纳入发现 / 链接时', options: ['--json'] },
           { name: 'hosts set', usage: 'hub hosts set <agentId> --dir <dir> [--label <名称>] [--json] | hub hosts set <agentId> --clear', what: '目录覆盖：用户级覆盖内置映射；--clear 恢复默认', when: '宿主技能目录与内置映射不一致时', options: ['--dir', '--label', '--clear', '--json'] },
           { name: 'config get', usage: 'hub config get [--json]', what: '查看生效 Hub 位置与来源（--hub / YOTTA_SKILLS_HUB / config.json / 默认）', when: '确认当前 Hub 与配置覆盖时', options: ['--json'] },
           { name: 'config set', usage: 'hub config set --hub <path> [--move [--clean-residue]]', what: '持久化 Hub 位置；--move 迁移旧 Hub（复制校验 → 重链 → 回收站 7 天）；未迁移时记录原位置供面板提示', when: '换 Hub 存储位置时', options: ['--hub', '--move', '--clean-residue', '--json'] },
-          { name: 'config rollback', usage: 'hub config rollback [--yes] [--clean-residue]', what: '回滚到上次迁移前的 Hub 位置（位置回退，用当前内容；反向迁移同内核）', when: '迁移后想退回原位置时', options: ['--yes', '--clean-residue', '--json'] },
-          { name: 'config clear', usage: 'hub config clear [--json]', what: '清除配置覆盖，恢复 flag > env > 默认', when: '撤销持久 Hub 位置时', options: ['--json'] },
+          { name: 'config rollback', usage: 'hub config rollback [--yes] [--clean-residue]', what: '回滚到上次迁移前的 Hub 位置（位置回退，用当前内容；反向迁移同内核）', when: '迁移后想退回原位置时', options: ['--yes', '--clean-residue', '--json'], impact: '影响面：位置回退（用当前内容复制回原位置并重链，不恢复旧快照）；目标非空时 fail-closed 阻断。', alternative: '替代路径：只查看历史迁移用 hub config get；继续当前位置则不需要操作。' },
+          { name: 'config clear', usage: 'hub config clear [--yes] [--json]', what: '清除配置覆盖，恢复 flag > env > 默认；当前 Hub 有技能时默认阻断，--yes 显式确认', when: '撤销持久 Hub 位置时', options: ['--yes', '--json'], impact: '影响面：清除后生效位置回落到默认（可能是空目录）；Hub 真源与宿主链接不移动，但元阁命令将按新位置工作（表现为台账 / 链接空转）。', alternative: '替代路径：迁移位置用 hub config set --hub "<新路径>" --move；想回原位置用 hub config set --hub "<原路径>"。' },
           { name: 'cleanup-backups', usage: 'hub cleanup-backups [--yes] [--include-discovered]', what: '清理宿主 / Hub 里的 .yottaskills-backup-* / .yottaskills-staging 历史残留（移入回收站 7 天）', when: '宿主把备份当技能扫描、或迁移后要清残留时', options: ['--yes', '--include-discovered', '--dir', '--agent', '--json'] },
           { name: 'install', usage: 'hub install [skill...]', what: '把元技能装进 Hub 真源（清单 27 + 特殊家族 5）', when: '初始化 Hub 或补装技能时', options: ['--hub'] },
           { name: 'update', usage: 'hub update', what: '更新 Hub 内的元技能（非元技能不参与；只升不降）', when: '日常维护 Hub 真源时', options: ['--hub'] },
           { name: 'adopt', usage: 'hub adopt [--scan | --apply] [--include <a,b>] [--in-place]', what: '把各宿主已有技能收编进 Hub（默认复制保真）', when: '接管机器上已装的技能时', options: ['--scan', '--apply', '--include', '--in-place', '--force', '--skip-scan', '--allow-unverified'] },
           { name: 'refresh', usage: 'hub refresh <slug> --from <path>', what: '手动同步非元阁技能（无统一更新源）', when: '外部技能更新后刷新 Hub 副本时', options: ['--from'] },
           { name: 'link', usage: 'hub link [skill...] [--all | --agent <id> | --dir <path>] [--include-discovered] [--dry-run]', what: '把 Hub 技能链接到宿主目录（指定智能体 / 全量）', when: '分发技能到各智能体时', options: ['--all', '--agent', '--dir', '--include-discovered', '--force', '--dry-run'] },
-          { name: 'unlink', usage: 'hub unlink [skill...] [--all | --agent <id> | --dir <path>] [--dry-run]', what: '只删除链接，不动 Hub 真源（fail-closed）', when: '解除某个 / 全部宿主的链接时', options: ['--all', '--agent', '--dir', '--include-discovered', '--dry-run'] },
-          { name: 'remove', usage: 'hub remove <slug> [--dry-run] [--include-discovered]', what: '删除 Hub 技能：全宿主清链接（含死链）+ 目录入回收站 + 清台账 + 审计', when: '彻底删除某个 Hub 技能时', options: ['--dry-run', '--include-discovered', '--json'] },
+          { name: 'unlink', usage: 'hub unlink [skill...] [--all | --agent <id> | --dir <path>] [--dry-run]', what: '只删除链接，不动 Hub 真源（fail-closed；--dir 无 slug 时以文件系统为真源清理该目录全部 Hub 链接）', when: '解除某个 / 全部宿主的链接时', options: ['--all', '--agent', '--dir', '--include-discovered', '--dry-run'], impact: '影响面：只删除宿主目录中的链接（Hub 真源保留）；只处理指向当前 Hub 的链接，指向其它位置的链接 fail-closed 不动并给出错位警告。', alternative: '替代路径：删除整个技能用 hub remove <slug>；重建链接用 hub link --dir "<目录>" --force。' },
+          { name: 'remove', usage: 'hub remove <slug> [--dry-run] [--include-discovered]', what: '删除 Hub 技能：全宿主清链接（含死链）+ 目录入回收站 + 清台账 + 审计', when: '彻底删除某个 Hub 技能时', options: ['--dry-run', '--include-discovered', '--json'], impact: '影响面：全宿主清理该技能链接（含死链）→ Hub 目录移入回收站（保留 7 天）→ 清台账；影响范围大。', alternative: '替代路径：只想解除某宿主链接用 hub unlink；只想清死链用 hub remove <slug> --agent/--dir（目标缺失时）。' },
           { name: 'status', usage: 'hub status [--json]', what: '查看 Hub 技能 / 来源 / 版本 / 链接 / 宿主', when: '核对 Hub 现状时', options: ['--json'] },
           { name: 'doctor', usage: 'hub doctor [--json]', what: '检查断链 / 目标缺失 / slug 不一致 / 单一真源 / 链接范围', when: 'Hub 异常后排查时', options: ['--json'] },
         ],
@@ -267,96 +268,152 @@ const CLI_HELP_QUICK = [
   {
     group: '安装与更新',
     items: [
-      { cmd: 'install', example: 'yotta-skills install --agent codex' },
-      { cmd: 'install', example: 'yotta-skills install yotta-memory --dir <技能目录>' },
-      { cmd: 'update', example: 'yotta-skills update --installed-only --dir <技能目录>' },
-      { cmd: 'update', example: 'yotta-skills update --check' },
-      { cmd: 'update', example: 'yotta-skills update --auto' },
-      { cmd: '--dry-run', example: 'yotta-skills install --dry-run --agent codex' },
-      { cmd: 'install-self', example: 'yotta-skills install-self' },
-      { cmd: 'where', example: 'yotta-skills where' },
+      { cmd: 'install', example: 'yotta-skills install --agent codex', note: '装全家到指定智能体' },
+      { cmd: 'install', example: 'yotta-skills install yotta-memory --dir <技能目录>', note: '只装一个技能到指定目录' },
+      { cmd: 'update', example: 'yotta-skills update --installed-only --dir <技能目录>', note: '接管现有技能（只升不降）' },
+      { cmd: 'update', example: 'yotta-skills update --check', note: '只读检查 npm 更新（不改动）' },
+      { cmd: 'update', example: 'yotta-skills update --auto', note: '检查到家族更新后自动更新' },
+      { cmd: '--dry-run', example: 'yotta-skills install --dry-run --agent codex', note: '预演安装 / 更新清单（不联网不改动）' },
+      { cmd: 'install-self', example: 'yotta-skills install-self', note: '把元阁装成独立 CLI' },
+      { cmd: 'where', example: 'yotta-skills where', note: '查看运行中 / 独立安装 / Hub 位置' },
     ],
   },
   {
     group: '体检与回滚',
     items: [
-      { cmd: 'doctor', example: 'yotta-skills doctor --dir <技能目录>' },
-      { cmd: 'rollback', example: 'yotta-skills rollback --list' },
-      { cmd: 'rollback', example: 'yotta-skills rollback --slug <技能> --dir <技能目录>' },
+      { cmd: 'doctor', example: 'yotta-skills doctor --dir <技能目录>', note: '只读自检技能目录与注册表' },
+      { cmd: 'rollback', example: 'yotta-skills rollback --list', note: '列出可回滚的备份点' },
+      { cmd: 'rollback', example: 'yotta-skills rollback --slug <技能> --dir <技能目录>', note: '回滚指定技能到上一个备份' },
     ],
   },
   {
     group: '盘点与路由',
     items: [
-      { cmd: '--list', example: 'yotta-skills --list' },
-      { cmd: '--inventory', example: 'yotta-skills --inventory --json' },
-      { cmd: '--reindex', example: 'yotta-skills --reindex' },
-      { cmd: '--route', example: 'yotta-skills --route "帮我做发布前质量检查"' },
-      { cmd: 'decide-memory', example: 'yotta-skills decide-memory --dry-run' },
+      { cmd: '--list', example: 'yotta-skills --list', note: '列出全家技能与版本' },
+      { cmd: '--inventory', example: 'yotta-skills --inventory --json', note: '盘点本机已装技能' },
+      { cmd: '--reindex', example: 'yotta-skills --reindex', note: '重扫本地技能注册表' },
+      { cmd: '--route', example: 'yotta-skills --route "帮我做发布前质量检查"', note: '按需求给技能组合建议（不自动安装）' },
+      { cmd: 'decide-memory', example: 'yotta-skills decide-memory --dry-run', note: 'M1 记忆裁决只读建议' },
     ],
   },
   {
     group: '技能 Hub',
     items: [
-      { cmd: 'hub', example: 'yotta-skills hub' },
-      { cmd: 'hub hosts', example: 'yotta-skills hub hosts' },
-      { cmd: 'hub hosts', example: 'yotta-skills hub hosts --state orphan' },
-      { cmd: 'hub hosts add', example: 'yotta-skills hub hosts add <技能目录>' },
-      { cmd: 'hub hosts list', example: 'yotta-skills hub hosts list' },
-      { cmd: 'hub hosts mark', example: 'yotta-skills hub hosts mark <技能目录> --state orphan' },
-      { cmd: 'hub hosts exclude', example: 'yotta-skills hub hosts exclude <agentId|目录>' },
-      { cmd: 'hub hosts include', example: 'yotta-skills hub hosts include <agentId|目录>' },
-      { cmd: 'hub hosts set', example: 'yotta-skills hub hosts set <agentId> --dir <目录>' },
+      { cmd: 'hub', example: 'yotta-skills hub', note: 'Hub 子命令总览' },
+      { cmd: 'hub hosts', example: 'yotta-skills hub hosts', note: '查看全部宿主与技能目录状态' },
+      { cmd: 'hub hosts', example: 'yotta-skills hub hosts --state orphan', note: '只筛选「残留」状态的宿主' },
+      { cmd: 'hub hosts add', example: 'yotta-skills hub hosts add <技能目录>', note: '注册自定义宿主目录（不创建目录）' },
+      { cmd: 'hub hosts rename', example: 'yotta-skills hub hosts rename <技能目录> --label <新名称>', note: '只改显示名；目录与手动状态保持' },
+      { cmd: 'hub hosts list', example: 'yotta-skills hub hosts list', note: '查看手动注册的自定义宿主' },
+      { cmd: 'hub hosts mark', example: 'yotta-skills hub hosts mark <技能目录> --state orphan', note: '手动标记状态（可用 / 残留 / 隐藏标记）' },
+      { cmd: 'hub hosts exclude', example: 'yotta-skills hub hosts exclude <agentId|目录>', note: '加入「不接管」名单' },
+      { cmd: 'hub hosts include', example: 'yotta-skills hub hosts include <agentId|目录>', note: '恢复接管' },
+      { cmd: 'hub hosts set', example: 'yotta-skills hub hosts set <agentId> --dir <目录>', note: '覆盖某智能体的技能目录映射' },
       { cmd: 'hub config get', example: 'yotta-skills hub config get', note: '查看生效位置与来源' },
       { cmd: 'hub config set', example: 'yotta-skills hub config set --hub <Hub目录>', note: '持久化 Hub 位置；迁移旧 Hub 加 --move' },
       { cmd: 'hub config rollback', example: 'yotta-skills hub config rollback --yes', note: '回滚到上次迁移前的位置（位置回退，用当前内容）', danger: true },
-      { cmd: 'hub config clear', example: 'yotta-skills hub config clear', note: '清除持久覆盖，恢复默认解析' },
+      { cmd: 'hub config clear', example: 'yotta-skills hub config clear', danger: true, note: '清除持久覆盖，恢复默认解析；当前 Hub 有技能时默认阻断，确认影响后加 --yes' },
       { cmd: 'hub cleanup-backups', example: 'yotta-skills hub cleanup-backups --yes', note: '历史备份 / 暂存残留移入回收站（7 天可恢复）', danger: true },
-      { cmd: 'hub hosts remove', example: 'yotta-skills hub hosts remove <技能目录>', note: '只移除注册，不删目录' },
+      { cmd: 'hub hosts remove', example: 'yotta-skills hub hosts remove <技能目录>', note: '只移除注册，不删目录；该目录已有链接不清理（用 hub unlink --dir）' },
       { cmd: 'hub hosts remove', example: 'yotta-skills hub hosts remove <技能目录> --purge', danger: true, note: '清理残留目录：先预览，--yes 才执行；目录入回收站保留 7 天' },
-      { cmd: 'hub install', example: 'yotta-skills hub install' },
-      { cmd: 'hub update', example: 'yotta-skills hub update' },
-      { cmd: 'hub adopt', example: 'yotta-skills hub adopt --scan' },
-      { cmd: 'hub adopt', example: 'yotta-skills hub adopt --apply --include <技能>' },
-      { cmd: 'hub refresh', example: 'yotta-skills hub refresh <技能> --from <技能目录>' },
-      { cmd: 'hub link', example: 'yotta-skills hub link --all' },
+      { cmd: 'hub install', example: 'yotta-skills hub install', note: '把元技能装进 Hub 真源' },
+      { cmd: 'hub update', example: 'yotta-skills hub update', note: '更新 Hub 内元技能（只升不降）' },
+      { cmd: 'hub adopt', example: 'yotta-skills hub adopt --scan', note: '只读预演收编候选与冲突' },
+      { cmd: 'hub adopt', example: 'yotta-skills hub adopt --apply --include <技能>', note: '执行收编（逐项元信扫描，high / critical 阻断）' },
+      { cmd: 'hub refresh', example: 'yotta-skills hub refresh <技能> --from <技能目录>', note: '手动同步非元阁技能（需 --from）' },
+      { cmd: 'hub link', example: 'yotta-skills hub link --all', note: '全量分发到全部已核实宿主' },
       { cmd: 'hub link', example: 'yotta-skills hub link <技能> --agent codex', note: '针对指定智能体分发' },
       { cmd: 'hub unlink', example: 'yotta-skills hub unlink <技能> --agent codex', note: '只解除该智能体的链接，Hub 真源保留' },
-      { cmd: 'hub unlink', example: 'yotta-skills hub unlink --all' },
+      { cmd: 'hub unlink', example: 'yotta-skills hub unlink --dir <技能目录>', note: '清理该目录全部指向当前 Hub 的链接（文件系统为真源；其它位置链接不动）' },
+      { cmd: 'hub unlink', example: 'yotta-skills hub unlink --all', note: '解除全部已核实宿主的链接' },
       { cmd: 'hub remove', example: 'yotta-skills hub remove <技能> --dry-run', danger: true, note: '删除 Hub 技能：全宿主清链接（含死链）+ 目录入回收站（7 天）+ 清台账；先 --dry-run 看影响' },
-      { cmd: 'hub status', example: 'yotta-skills hub status' },
-      { cmd: 'hub doctor', example: 'yotta-skills hub doctor' },
+      { cmd: 'hub status', example: 'yotta-skills hub status', note: '查看 Hub 技能 / 版本 / 链接 / 宿主' },
+      { cmd: 'hub doctor', example: 'yotta-skills hub doctor', note: '检查断链 / 缺失 / slug 不一致' },
     ],
   },
   {
     group: '使用记录与 Hook',
     items: [
-      { cmd: 'usage', example: 'yotta-skills usage status' },
-      { cmd: 'usage status', example: 'yotta-skills usage status --json' },
-      { cmd: 'usage enable', example: 'yotta-skills usage enable' },
-      { cmd: 'usage disable', example: 'yotta-skills usage disable' },
-      { cmd: 'usage mark', example: 'yotta-skills usage mark --skill yotta-memory --signal used' },
+      { cmd: 'usage', example: 'yotta-skills usage status', note: '使用记录开关与计数总览' },
+      { cmd: 'usage status', example: 'yotta-skills usage status --json', note: '查看开关与计数（JSON）' },
+      { cmd: 'usage enable', example: 'yotta-skills usage enable', note: '开启本地使用记录' },
+      { cmd: 'usage disable', example: 'yotta-skills usage disable', note: '关闭本地使用记录' },
+      { cmd: 'usage mark', example: 'yotta-skills usage mark --skill yotta-memory --signal used', note: '记录一次使用信号' },
       { cmd: 'usage reset', example: 'yotta-skills usage reset --yes', danger: true, note: '清空本地使用记录，先确认不再需要计数' },
-      { cmd: 'hook', example: 'yotta-skills hook capabilities' },
-      { cmd: 'hook capabilities', example: 'yotta-skills hook capabilities --host codex --json' },
-      { cmd: 'hook evaluate', example: 'yotta-skills hook evaluate --event before_install --manifest <file>' },
-      { cmd: 'hook bind', example: 'yotta-skills hook bind --manifest <file>' },
-      { cmd: 'hook unbind', example: 'yotta-skills hook unbind <binding-id>' },
+      { cmd: 'hook', example: 'yotta-skills hook capabilities', note: 'hook 子命令总览' },
+      { cmd: 'hook capabilities', example: 'yotta-skills hook capabilities --host codex --json', note: '查看宿主六事件能力矩阵' },
+      { cmd: 'hook evaluate', example: 'yotta-skills hook evaluate --event before_install --manifest <file>', note: '评估 hook 声明并留证' },
+      { cmd: 'hook bind', example: 'yotta-skills hook bind --manifest <file>', note: '注册 hook 声明（幂等）' },
+      { cmd: 'hook unbind', example: 'yotta-skills hook unbind <binding-id>', note: '反注册 hook 声明' },
     ],
   },
   {
     group: '面板与帮助',
     items: [
-      { cmd: 'view', example: 'yotta-skills view' },
-      { cmd: 'view', example: 'yotta-skills view --port 8790' },
-      { cmd: '--version', example: 'yotta-skills --version' },
-      { cmd: '--help', example: 'yotta-skills --help' },
+      { cmd: 'view', example: 'yotta-skills view', note: '打开本地控制面板（仅 127.0.0.1）' },
+      { cmd: 'view', example: 'yotta-skills view --port 8790', note: '指定端口打开（默认 8789）' },
+      { cmd: '--version', example: 'yotta-skills --version', note: '查看当前版本' },
+      { cmd: '--help', example: 'yotta-skills --help', note: '查看终端帮助（与面板同一真源）' },
     ],
   },
 ];
 
+/**
+ * UX-10：速查引用解析（单一真源，服务端随 /api/help 下发）。
+ *
+ * 按「最深前缀」把速查条目的 cmd 解析到模型条目：
+ * - 'hub hosts add'  → 'hub hosts add'（不是父级 'hub hosts'）
+ * - 'hub hosts --state orphan' → 'hub hosts'（旗标 / 参数尾段容忍）
+ * - '--list' 等伪命令按全名精确匹配
+ */
+function resolveHelpEntry(groups, ref) {
+  const raw = String(ref || '').trim();
+  if (!raw) return null;
+  const entries = [];
+  for (const group of groups) {
+    for (const cmd of group.commands) {
+      entries.push({ path: cmd.name, entry: cmd });
+      for (const sub of cmd.subcommands || []) {
+        entries.push({ path: cmd.name + ' ' + sub.name, entry: sub });
+      }
+    }
+  }
+  for (const item of entries) {
+    if (item.path === raw) return item.entry;
+  }
+  const tokens = [];
+  for (const token of raw.split(/\s+/)) {
+    if (token.startsWith('-') || token.startsWith('<') || token.startsWith('[')) break;
+    tokens.push(token);
+  }
+  if (!tokens.length) return null;
+  let best = null;
+  let bestLen = -1;
+  for (const item of entries) {
+    const pathTokens = item.path.split(' ');
+    if (pathTokens.length > tokens.length || pathTokens.length <= bestLen) continue;
+    if (pathTokens.every((token, index) => token === tokens[index])) {
+      best = item.entry;
+      bestLen = pathTokens.length;
+    }
+  }
+  return best;
+}
+
+/** 速查数据 + 服务端解析结果（面板直接用 meta，不再自行解析）。 */
+function quickWithMeta() {
+  return CLI_HELP_QUICK.map((group) => ({
+    group: group.group,
+    items: group.items.map((item) => Object.assign({}, item, {
+      meta: resolveHelpEntry(CLI_HELP_MODEL, item.cmd) || {},
+    })),
+  }));
+}
+
 module.exports = {
   CLI_HELP_MODEL,
   CLI_HELP_QUICK,
   CLI_GLOBAL_OPTIONS,
+  resolveHelpEntry,
+  quickWithMeta,
 };

package/skills/yotta-skills/lib/hosts-registry.js

@@ -183,7 +183,7 @@ function markHost(opts, input) {
   const options = opts || {};
   const state = input && input.state ? String(input.state).toLowerCase() : null;
   if (!MANUAL_STATES.includes(state)) {
-    return { ok: false, error: '未知手动状态：' + state + '（可用 available / 残留 orphan / 忽略 ignored）' };
+    return { ok: false, error: '未知手动状态：' + state + '（可用 available / 残留 orphan / 隐藏标记 ignored）' };
   }
   const dir = input && input.dir ? path.resolve(input.dir) : null;
   if (!dir) return { ok: false, error: '缺少目录' };
@@ -206,6 +206,33 @@ function markHost(opts, input) {
   return { ok: true, entry, registry };
 }
 
+/** 一步改名：只改显示名 label，不动目录 / 手动状态 / 覆盖（0.30.0 UX-08）。 */
+function renameHost(opts, input) {
+  const options = opts || {};
+  const label = String((input && input.label) || '').trim();
+  const labelError = validateLabel(label);
+  if (labelError) return { ok: false, error: labelError };
+  const dir = input && input.dir ? path.resolve(input.dir) : null;
+  const id = input && input.id ? String(input.id).trim().toLowerCase() : null;
+  if (!dir && !id) return { ok: false, error: '缺少目标：hub hosts rename <目录> --label <名称> 或 --id <agentId>' };
+  const registry = readHostsRegistry(options);
+  const entry = registry.hosts.find((item) =>
+    (dir && samePath(item.dir, dir)) ||
+    (id && String(item.agentId || '').toLowerCase() === id));
+  if (!entry) {
+    return {
+      ok: false,
+      error: '未找到注册项' + (dir ? '：' + dir : '：' + id),
+      hint: '本命令只改自定义注册表（hub hosts list）里的显示名；未注册目录先 hub hosts add <目录> --label <名称>，内置映射改名用 hub hosts set <agentId> --label <名称>。',
+    };
+  }
+  const previous = entry.label;
+  entry.label = label;
+  entry.updatedAt = nowIso();
+  writeHostsRegistry(options, registry);
+  return { ok: true, entry, previous, registry };
+}
+
 /** 0.29.1 U2：不接管名单匹配（agentId 或目录）；返回命中条目或 null。 */
 function excludedEntryFor(registry, input) {
   const agentId = input && input.agentId ? String(input.agentId).toLowerCase() : null;
@@ -331,6 +358,7 @@ module.exports = {
   addHost,
   removeHost,
   markHost,
+  renameHost,
   excludedEntryFor,
   excludeHost,
   includeHost,

package/skills/yotta-skills/lib/hub-adopt.js

@@ -314,7 +314,18 @@ function refreshFrom(options) {
     }
     scan = opts.scan(source, { slug });
     if (!scan.ok) return { ok: false, slug, error: scan.error || '扫描失败' };
-    if (scan.block && !opts.allowUnverified) return { ok: false, slug, error: '元信 verdict: ' + scan.verdict };
+    if (scan.block && !opts.allowUnverified) {
+      return {
+        ok: false, slug, error: '元信 verdict: ' + scan.verdict, blocked: true,
+        // 0.30.0 OPT-05：附带扫描明细，供 CLI 输出「与上一已审版本」差异摘要。
+        scan: {
+          verdict: scan.verdict,
+          counts: scan.counts || null,
+          findings: scan.findings || null,
+          excluded: (scan.policy && scan.policy.excludedFindings) || [],
+        },
+      };
+    }
   }
   let backup = null;
   let tmp = null;

package/skills/yotta-skills/lib/hub-scan.js

@@ -117,6 +117,7 @@ function hubScanSkill(hubDir, discovery, opts, skillDir, context) {
     counts: reviewed.counts,
     block: verdict.block,
     policy: reviewed.policy || null,
+    findings: reviewed.findings || null,
   };
 }
 

package/skills/yotta-skills/lib/hub-view-server.js

@@ -204,6 +204,7 @@ function overviewPayload(ctx) {
       configured: hubNow.configured,
       configFile: hubNow.configFile,
       effectiveNow: hubNow.dir,
+      defaultDir: skillsConfigLib.defaultHubDir({ homeDir: ctx.homeDir, env: ctx.env }),
       restartRequired: !ctx.hubFlag && !sameDir(hubNow.dir, ctx.hubDir),
     },
     standard: hubLib.STANDARD_ID,
@@ -278,9 +279,25 @@ function hostsPayload(ctx) {
   }));
   const hosts = found.hosts.map((host) => {
     const hostLinks = links.filter((link) => sameDir(link.dir, host.dir));
+    const ledgerOk = hostLinks.filter((link) => link.status === 'ok').length;
+    // 0.30.0 OPT-03：「指向当前 Hub」以文件系统为真源（台账辅助）；指向其它
+    // 位置的链接单独计数（只统计能识别为「其它 Hub」的目标），用于配置错位预警。
+    let scan = null;
+    if (host.exists && !host.bridgeOnly) {
+      try {
+        scan = hubLib.scanDirForHubLinks(host.dir, ctx.hubDir);
+      } catch (_) {
+        scan = null;
+      }
+    }
+    const otherHubLinks = scan ? scan.otherLinks.filter((item) => item.root) : [];
+    const otherHubRoots = [...new Set(otherHubLinks.map((item) => item.root))];
     return {
       ...host,
-      hubLinks: hostLinks.filter((link) => link.status === 'ok').length,
+      hubLinks: scan ? scan.hubSlugs.length : ledgerOk,
+      hubLinksLedger: ledgerOk,
+      hubLinksOther: otherHubLinks.length,
+      hubLinksOtherRoots: otherHubRoots.slice(0, 3),
       brokenLinks: hostLinks.filter((link) => link.status !== 'ok').length,
     };
   });
@@ -309,6 +326,7 @@ function hostsPayload(ctx) {
       overrides: (registry.overrides || []).length,
       links: links.length,
       brokenLinks: links.filter((link) => link.status !== 'ok').length,
+      otherHubLinks: hosts.reduce((sum, host) => sum + (host.hubLinksOther || 0), 0),
       // 0.29.0 F3：宿主生命周期状态细分（面板分组 / 筛选）。
       states: {
         available: hosts.filter((host) => host.state === 'available').length,
@@ -664,6 +682,27 @@ function writeHostRemove(ctx, body) {
   return { code: 200, payload: { action: 'hosts.remove', removed: result.removed } };
 }
 
+function writeHostRename(ctx, body) {
+  const dir = String(body.dir || '').trim();
+  const id = String(body.id || '').trim();
+  const label = String(body.label || '').trim();
+  if (!label) return { code: 400, payload: { error: '缺少新名称。' } };
+  if (!dir && !id) return { code: 400, payload: { error: '缺少目标目录或 agentId。' } };
+  const result = hostsRegistryLib.renameHost(
+    { homeDir: ctx.homeDir, env: ctx.env },
+    { dir, id, label },
+  );
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  auditViewHostEvent(ctx, {
+    event: 'hosts.rename',
+    dir: result.entry.dir,
+    from: result.previous,
+    to: result.entry.label,
+    via: 'view',
+  });
+  return { code: 200, payload: { action: 'hosts.rename', entry: result.entry, previous: result.previous } };
+}
+
 function writeHostPurge(ctx, body) {
   if (String(body.confirm || '') !== CONFIRM.purge) {
     return { code: 400, payload: { error: '破坏性操作确认不匹配；请确认后再执行。' } };
@@ -1053,7 +1092,8 @@ function handleGet(ctx, pathname, url, res) {
     return json(res, 200, {
       version: ctx.version || '',
       groups: cliHelpLib.CLI_HELP_MODEL,
-      quick: cliHelpLib.CLI_HELP_QUICK,
+      // UX-10：速查解析在服务端完成（单一真源），面板直接用 item.meta。
+      quick: cliHelpLib.quickWithMeta(),
       options: cliHelpLib.CLI_GLOBAL_OPTIONS,
     });
   }
@@ -1117,6 +1157,7 @@ function handlePost(ctx, pathname, req, res) {
       if (pathname === '/api/skills/remove') return writeRemove(ctx, body);
       if (pathname === '/api/hosts/add') return writeHostAdd(ctx, body);
       if (pathname === '/api/hosts/remove') return writeHostRemove(ctx, body);
+      if (pathname === '/api/hosts/rename') return writeHostRename(ctx, body);
       if (pathname === '/api/hosts/purge') return writeHostPurge(ctx, body);
       if (pathname === '/api/hosts/mark') return writeHostMark(ctx, body);
       if (pathname === '/api/hosts/set') return writeHostSet(ctx, body);

package/skills/yotta-skills/lib/hub.js

@@ -749,6 +749,47 @@ function classifyTarget(target, hubDir) {
   return { kind: 'file' };
 }
 
+/**
+ * 0.30.0 UX-02 / OPT-01：以文件系统为真源扫描目标目录内的链接。
+ * - hubSlugs：指向当前 Hub 的链接（可安全清理）
+ * - otherLinks：指向其它位置的链接（fail-closed，不动；供错位警告）
+ */
+function scanDirForHubLinks(targetDir, hubDir) {
+  const hubSlugs = [];
+  const otherLinks = [];
+  let entries = [];
+  try {
+    entries = fs.readdirSync(targetDir, { withFileTypes: true });
+  } catch (_) {
+    return { hubSlugs, otherLinks, scanned: 0, readable: false };
+  }
+  for (const entry of entries) {
+    const target = path.join(targetDir, entry.name);
+    const current = classifyTarget(target, hubDir);
+    if (current.kind !== 'link') continue;
+    if (current.inHub) hubSlugs.push(entry.name);
+    else otherLinks.push({ slug: entry.name, target: current.target, root: foreignHubRoot(current.target) });
+  }
+  return { hubSlugs, otherLinks, scanned: entries.length, readable: true };
+}
+
+/**
+ * 解析链接目标所属的「其它 Hub」根目录：宿主链接通常指向 <hub>/<slug>，
+ * 因此先看目标本身、再看父目录是否含元阁 Hub 台账标记；都不是则返回 null。
+ */
+function foreignHubRoot(target) {
+  if (!target) return null;
+  const resolved = path.resolve(target);
+  for (const dir of [resolved, path.dirname(resolved)]) {
+    try {
+      if (fs.existsSync(path.join(dir, STATE_FILE))) return dir;
+      if (fs.existsSync(path.join(dir, LINKS_FILE))) return dir;
+      if (fs.existsSync(path.join(dir, AUDIT_FILE))) return dir;
+    } catch (_) { /* 单个候选失败继续 */ }
+  }
+  return null;
+}
+
 function linkSkills(options) {
   const opts = options || {};
   const hubDir = path.resolve(opts.hubDir);
@@ -1125,13 +1166,32 @@ function unlinkSkills(options) {
   const hubDir = path.resolve(opts.hubDir);
   const targetDir = path.resolve(opts.targetDir);
   const dryRun = Boolean(opts.dryRun);
-  const slugs = Array.isArray(opts.slugs) && opts.slugs.length > 0
-    ? opts.slugs
-    : readLinkState(hubDir).links
+  const linkState = readLinkState(hubDir);
+  let slugs = null;
+  let discovery = null;
+  if (Array.isArray(opts.slugs) && opts.slugs.length > 0) {
+    slugs = opts.slugs;
+  } else {
+    // 0.30.0 UX-02 / OPT-01：无 slug 时以文件系统为真源扫描目标目录
+    // （台账仅作辅助），保证「指向当前 Hub 的链接」即使台账缺失也能被清理；
+    // 同时记录指向其它位置的链接数，供调用方输出错位警告。
+    const ledgerSlugs = linkState.links
       .filter((item) => samePath(item.dir || '', targetDir))
       .map((item) => item.slug);
+    const scan = scanDirForHubLinks(targetDir, hubDir);
+    slugs = [...new Set(ledgerSlugs.concat(scan.hubSlugs))];
+    discovery = {
+      source: 'filesystem+ledger',
+      fromLedger: ledgerSlugs.length,
+      fromFilesystem: scan.hubSlugs.length,
+      scannedEntries: scan.scanned,
+      dirReadable: scan.readable,
+      otherLinks: scan.otherLinks.length,
+      otherTargets: [...new Set(scan.otherLinks.map((item) => item.root || item.target))].slice(0, 5),
+    };
+  }
   const unique = [...new Set(slugs)];
-  const links = readLinkState(hubDir).links.slice();
+  const links = linkState.links.slice();
   const results = [];
 
   for (const slug of unique) {
@@ -1165,7 +1225,7 @@ function unlinkSkills(options) {
     }
   }
   if (!dryRun) writeLinkState(hubDir, { links });
-  return { hubDir, targetDir, dryRun, results };
+  return { hubDir, targetDir, dryRun, results, discovery };
 }
 
 /**
@@ -1640,6 +1700,39 @@ function doctor(options) {
     }
   }
 
+  // 0.30.0 UX-03：宿主链接目标 vs 当前 Hub 一致性（配置错位提前发现）。
+  if (scopeDirs && scopeDirs.length > 0) {
+    const foreign = new Map();
+    for (const dir of scopeDirs) {
+      let entries = [];
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch (_) {
+        continue;
+      }
+      for (const entry of entries) {
+        const target = path.join(dir, entry.name);
+        const current = classifyTarget(target, hubDir);
+        if (current.kind !== 'link' || current.inHub) continue;
+        const root = foreignHubRoot(current.target);
+        if (!root) continue;
+        if (!foreign.has(root)) {
+          foreign.set(root, { count: 0, dirs: new Set(), slugs: new Set() });
+        }
+        const rec = foreign.get(root);
+        rec.count += 1;
+        rec.dirs.add(dir);
+        rec.slugs.add(entry.name);
+      }
+    }
+    for (const [target, rec] of foreign) {
+      add('hub_mismatch:' + pathKey(target), false, 'warning',
+        '发现 ' + rec.count + ' 条链接指向其它 Hub: ' + target + '（当前 Hub: ' + hubDir + '）',
+        '核对位置来源: yotta-skills hub config get；恢复配置 = hub config set --hub "' + target +
+        '"，或重链到当前 Hub = hub link --all --force。');
+    }
+  }
+
   try {
     singleSourceChecks(opts, add);
   } catch (_) { /* 只读检查失败不影响 doctor 主流程 */ }
@@ -1711,6 +1804,7 @@ module.exports = {
   createDirLink,
   removeDirLink,
   classifyTarget,
+  scanDirForHubLinks,
   linkSkills,
   unlinkSkills,
   removeSkills,