dsh-plugin-catalog · 插件目录面板

English

> 状态：开发版，非最终版本。 这是「边用边改」放出来的版本：功能与界面会不定期更新，
> 配置项、命令与数据目录都可能变。装之前请确认下一节的 DSH 版本区间，装完先跑一次自检。
>
> Status: development build — not a final release. Released as-is from daily use; features and UI
> change from time to time (settings, commands and the data directory may change too). Check the DSH
> version range below before installing, and run the self-checks after you do.

DSH 侧栏「插件目录」：把本机的 插件与 Skill 摊成卡片，按来源四分类（官方 / 自写 / 第三方 / 混血），
用会话事件日志统计最近 90 天每个工具的调用次数、报错、耗时与涉及会话（子代理单独标出），
支持自定义标签 + AI 分类、每周缺口分析与安全审核、以及自写/混血的一键私有备份到 GitHub。

> 官方插件入口保留不隐藏。 本插件是独立的客户端插件：禁用它即恢复官方界面（见文末「自救」）。
>
> 内嵌的审核/发布 Agent 同时注册为工具（catalog_*，共 14 个），普通会话里一句话就能调起：
> 「审一遍 dsh-screenshot」「开放 dsh-catalog 仓」「列出我的自写插件」。

支持的 DSH 版本

> 装之前先对一下版本。版本不对时不会"凑合能用"：轻则面板能打开但按钮点了没反应，重则整个插件树加载失败。

适用 profile

• desktop（本机实测环境：DSH 0.2.x，Windows）
• 任何带 tools 与 webServer 服务的 profile 都可用（客户端半边是标准 web 平台 bundle）
• 依赖宿主的 llm 服务（AI 分类 / 翻译 / 审核）；没有它时面板仍可用，只是这些按钮会报「AI 通道不可用」

安装

三步装完，不需要任何本机脚本（Windows / macOS / Linux 都一样）。

# 0) 先确认宿主版本在上一节的区间里
dsh --version

# 1) 克隆到**工作区**（不要直接克隆进 profile/node_modules —— 那份会被后续 install 覆盖掉）
git clone https://github.com/JHboy203/dsh-plugin-catalog.git "<你的工作区>/DSH-Plugin/dsh-plugin-catalog"

2) 把目录链进 profile（` 默认desktop`）：

# macOS / Linux
ln -s "<你的工作区>/DSH-Plugin/dsh-plugin-catalog" ~/.dsh/profiles//node_modules/dsh-plugin-catalog
# Windows（普通 cmd 即可，不需要管理员）
mklink /J "%USERPROFILE%\.dsh\profiles\\node_modules\dsh-plugin-catalog" "<你的工作区>\DSH-Plugin\dsh-plugin-catalog"

3) 改 /package.json 两处，然后完全退出并重启 DSH：

{
"dependencies": {
"dsh-plugin-catalog": "link:<你的工作区>/DSH-Plugin/dsh-plugin-catalog"
},
"dsh": {
"profile": {
"bundles": [ /* …原有条目…, "dsh-plugin-catalog" */ ]
}
}
}

侧栏出现「插件目录」图标即成功。

> ⚠️ 不要用 pnpm 系命令（dsh plugin add / pnpm add / npm install）装它。
> dsh plugin 只是把参数原样转发给 pnpm；pnpm 会重算整棵树、把 @deepseek-ai/dsh-tools
> 再 hoist 一份到 profile 里，那一份会遮蔽宿主的 —— 后果是每次工具调用都报
> Cannot read properties of undefined (reading 'prepare')，或下次启动时插件批量加载失败
> （does not provide an export named 'CallId'）。这个坑在本机复发过三次。
>
> 本机若已有 .tools/dsh-plugin-install.cjs（作者工作区里的辅助脚本，不在本仓内），
> 它就是上面三步的自动化版：node .tools/dsh-plugin-install.cjs install dsh-plugin-catalog "<目录>"。
> 没有它也能按上面的手做装。

装完必须完全重启 DSH：dsh.profile.bundles 与 cordis.patch.yml 都是启动期读的。

平台：Windows / macOS / Linux 均可（路径按平台分隔符处理；本机只在 Windows 11 实测）。
卸载：面板卡片底部「卸载」（走宿主 removeBundle，不动文件），或从 dsh.profile.bundles 去掉包名后删除链接目录。

装完检查一下有没有埋雷 —— 工具调用报 prepare、或下次启动插件批量加载失败，基本都是
/node_modules/@deepseek-ai/dsh-tools 里多了一份（它会遮蔽宿主那份）。有这个目录就先移走再重启：

# macOS / Linux
ls ~/.dsh/profiles//node_modules/@deepseek-ai
# Windows
dir "%USERPROFILE%\.dsh\profiles\\node_modules\@deepseek-ai"

用法

面板

侧栏出现「插件目录」图标（sidebar.panellist id = catalog）。点开是：

• 卡片：名称、简介（中文优先，没有中文就直接拿英文当正文，不再每张顶一行占位提示）、来源徽章、标签、创建/下载时间、调用总次数（含子代理拆分）；有报错的条目多一枚红色「报错 N」chip（悬停看错误率），从未调用过的次数置灰
• 搜索：名称 / 简介 / 判定依据，以及工具名 —— 输入 acp_status、catalog_export 这类工具名能直接定位到提供它的插件（命中时卡片上会显示「工具：xxx」）
• 洞察条：「全部 / 有调用 / 未使用 / 有报错 / 仅子代理」五个 chip 直接给条数，点一下就是筛选（计数为 0 的档位置灰但保留 —— 看得见"这台机器上没有这种人"，点开是空态 + 说明书）。每个 chip 悬停有一句解释，数字只随来源 / 类型变，不随关键词跳 —— 否则点开「未使用」后数字自己变成 0，看起来像数据丢了。「仅子代理」= 每一次调用都发生在子代理会话里：删掉它不会当场报错，只会让某条委派链下次跑的时候悄悄变差
• 筛选：来源（全部/官方/自写/第三方/混血/待标记）× 类型（全部/插件/Skill）
• 排序：调用次数 / 报错次数 / 报错率 / 体积 / 最近使用 / 时间 / 名称
  （报错率比次数更能看出毛病：本机实测 @liustack/modlens 6 次调用全报错 = 100%，而 dsh-vision-router 报错 23 次却没进前四 —— 252 次调用里只占 9%）
• 视图记忆：筛选 / 搜索词 / 排序 / 页码 / 每页条数 / 滚动位置存在 localStorage，改客户端代码触发的热重载、或刷新页面之后，回来还是刚才那一屏；换筛选或换页会自动回顶部（否则第 2 页的第一条会落在屏幕外）。存储被禁用、或数据损坏时安静退回默认视图，不会白屏
• 多选批次：工具条「选择」进入选择模式，点卡片即选中（再点取消），被选中的卡有蓝框 + 勾徽章。批次条实时显示已选 N 条 · 约 X MB（体积一次性批量问，服务端并发 4；没有独立目录的 Skill 会如实标「N 条没有独立目录，按 0 计」），可「导出选中」「打标」「选中当前 N 条」「清空」。选中项跨筛选保留（未使用里挑几个、有报错里再挑几个，凑成一批），但不进 localStorage —— 重载后清空是故意的，免得半个批次被忘在那里
• 批量打标（三态）：批次条「打标」打开浮层，一次给这批条目加上/去掉 purpose 与 context 标签。每个标签显示这批里几个已经有它（n/N）：
  全都有 → 实心，点一下＝全部去掉（−）；部分有 → 虚线；都没有 → 空态，点一下＝给缺的补上（＋）；
  还没点之前 title 就写明"点一下会发生什么"。只改你点过的标签，不会清掉条目各自已有的其它标签（与浮窗里"整条替换"是两种语义，刻意分开）；
  勾选只是本地意图，点「应用」才发一次请求 —— 中途失败不会留下半个批次。打过的条目记为手标，AI 自动分类不再覆盖
• 标签筛选：工具条下有一行标签（只在某个标签真的有条目在用时才出现），每个 chip 带命中条数。
  同维度多选＝或（做截图 或 做媒体），跨维度＝且（再叠 用在 Web GUI）。点 chip 即筛，右侧「清除标签」只清标签、不动其它筛选条件
• 导出这一屏：工具条右侧「导出这 N 条」把当前筛选结果（顺序就是屏幕顺序，含筛选条件、报错率、安装位置）写成 reports/catalog-filtered-<时间戳>.md，路径可一键复制；0 条时按钮禁用。要完整快照（来源分布、调用 Top、归属覆盖率）仍用 catalog_export
• 也能导成 CSV（R28）：同一个按钮旁边还有一个「CSV」—— 同一屏、同一批筛选，只换格式：一条一行、12 列（名称/类型/来源/版本/加载/调用/报错/报错率/最近一次/体积/被依赖/位置），带 UTF-8 BOM，Excel 直接双击打开中文不乱码。catalog_export format=csv 出的是全量条目的那份表；选中批次同样有「CSV」按钮。两种格式共用同一批数字与措辞，差别只在装饰（Markdown 有反引号与加粗，CSV 里那些都是噪音）
• 体积（一等公民）：卡片上直接有体积 chip，能按「体积」排序，工具条显示当前筛选结果的合计
  （点「未使用」就立刻看到"删这批能省多少"）。数据来自后台全量快照（cache/sizes.json，约 1.5 秒量完 120+ 个目录；
  面板自己触发一次，头部也有「量体积 / 重量体积」按钮）。三条如实：
• 量不到就不显示，绝不写「0 B」—— 官方包在 app.asar 里（realDir 是虚拟成员路径，递归必然为 0），
  浮窗会说「在官方 asar 里，没有独立目录（体积记在 DSH 安装包内）」；
• Skill 也有自己的体积（用 catalog 里的 dir，不是 skills 根目录 —— 拿错就是假警报）；
• 超过 1.5 秒 / 2 万文件预算的条目带「+」，数字是下限，合计里也一样标出来。
  浮窗里仍是懒算的 /size（打开哪一个才算哪一个，5 分钟缓存），绝不在目录构建里递归 ——
  71 个包逐个 du 会把面板打开从秒级拖到十秒级；统计时不跟随 junction / 符号链接（跟随会走出 profile 甚至成环）
• 依赖关系（谁把它带进来的 / 删它会弄坏谁）：卡片上直接有 chip ——
  「被 N 依赖」（删了会连带弄坏这些包；悬停列出是谁）与 「无人依赖」（候选，琥珀色）。
  数据来自构建目录时扫的全量依赖图：profile 里每个 package.json 的
  dependencies / optionalDependencies / peerDependencies（不只 DSH 插件，还展开一层嵌套 node_modules），
  反向索引成「谁声明的它」。工具条还有「无人依赖 N」筛选，勾上只剩候选。
• 为什么不能只看"在不在 profile 的 dependencies 里"：@dsh-ops/bash-win32-x64（354 MB）两方面都占 ——
  既写在 profile 里，又被 dsh-ops 依赖；删了 dsh-ops 立刻坏。本机 850.6 MB 里有 651.8 MB 属于这种"被依赖的运行时"，
  合计的 tooltip 会单独点出来，不算可回收空间。
• 浮窗「依赖关系」块给出三件事：直接声明在哪、被谁依赖（全名）、它自己声明依赖了谁（就是体积 Top 的来源）。
• 「无人依赖」只是候选：嵌套只展开一层，更深的声明可能漏读 —— 文案一律带"用 npm ls / pnpm why 确认"，绝不写成"可以删"。
• 副本同步：面板顶部公告 + 卡片标签告诉你「你改的那份，真的是加载的那份吗」。
  插件比 4 个关键文件（package.json / index.js / client.js / cordis.patch.yml）的 size + mtime，Skill 比 SKILL.md 的 size + mtime + 正文哈希（R20）；
  junction 安装直接说「只有一份，改源码立即生效」；发现不同步则标「副本不同步 / 副本较旧 / 工作区较旧」，
  Skill 的 staging 副本标「staging 不同步」——发布推的是 staging 那份，它旧了就等于发了个旧版。
  扫描 60 秒缓存一次，重建目录会作废；Skill 正文各读一遍算 sha1（17 对 ≈ 680 KB，实测 < 10 ms）——
  同字数改一个字也认得出（R20 之前只比长度，这种改动会被静默判成"一致"）
• 就地处置（R11）：Skill 的 staging 旧了不用离开面板——公告条上就有「同步 staging（N）」。
  点它先拿到一份计划（会覆盖哪几个 SKILL.md、方向、备份落在哪），再点「确认同步」才写盘：
  单向 live → staging，覆盖前把 staging 那份备份成 SKILL.md.bak-<时间戳>，不会动 DSH 正在加载的那份。
  浮窗里也有「同步这一份 → staging」。写盘闸在服务端（必须 confirm:true），所以误点一下最多出一份计划、不会改文件；
  staging 反而更新（staging 较新）时不给这个按钮 —— 那会把线上正在用的那份覆盖回旧版
• 写错了能撤销（R20）：条目浮窗里显示「历史备份 N 份 · 最近 <时间戳>」，点「还原到 <时间戳>」先出一份
  还原计划（方向 backup → staging、覆盖谁、备份落在哪），再点「确认还原」才写盘；覆盖前把 staging 当前那份
  另存成新 .bak，还原本身也能再撤销。只动 staging，永远不碰 DSH 加载的那份；工具侧是 catalog_skill_sync action=restore
• R28：不只能还原"最近一份" —— 确认条下面会把更早的几份也列出来（最近 8 份里除当前目标之外的最多 4 个），点哪一个就换成还原它、重新出计划，仍然要按「确认还原」才写盘。工具侧对应 restore + backup=<时间戳 或全名>；点名的那份不存在时明说「没有这份备份（现有 N 份：…）」，不会静默退回最近一份
• 运行期真相（R35）：目录的「会不会被加载」是声明层判据；面板另有运行期判据 ——
  直接读宿主 Loader 的 fiberPhase（pending / loading / active / failed / unloading）与 enabled，
  专抓声明层看不见的三类事：① fiberPhase = failed（插件被加载但 apply 抛错 —— 面板照常渲染、
  它的工具与路由已经被回滚）；② 声明在 dsh.profile.bundles 里、Loader 里却没有这一条
  （宿主启动时按版本/依赖 skip 了它）；③ 声明与运行时打架（enabled:false 却 active）。
  卡片上只在有问题时给一枚 chip（运行期失败 红 / 不在 loader 琥珀 / 已停用 灰），
  洞察条多一颗「运行期问题 N」，点一下只看这些；头部横幅会点名具体插件。
  ⚠️ 读不到运行期（旧宿主 / 没有 pluginManager）时一律 unknown + 一句原因，绝不猜成 active。
• 卡片底部直接操作（R35）：点卡片仍然打开详情；卡片最下面一排小按钮可以直接做事 ——
  插件：详情 / 复制路径 / 停用（或启用）/ 卸载；Skill：详情 / 复制路径 / 删除；
  MCP：详情 / 停用 / 删除条目。点动作只出计划（只读：会改什么、阻断项、警告、目标、备份位置），
  确认条里再点一次「确认 …」才真执行；计划是一次性 token（5 分钟过期），刷新即失效。
• 插件卸载走宿主 pluginManager.removeBundle()（源码一个字节都不动；link 安装时只去掉那条依赖）
• 插件停用/启用走 setBundleEnabled / setPluginEnabled（保留文件与依赖）
• Skill 删除 = 移进回收站 <数据目录>/trash/skills/，头部「回收站」里可以直接还原到原位
  （原位已有同名目录时拒绝覆盖）。随插件安装的 Skill、没有独立目录的、不在已知 Skills 根目录下的，一律阻断并说明原因
• MCP 停用 = 往 profile 的 cordis.patch.yml 追加一条按 id 覆盖的 disabled: true（幂等，重启 DSH 生效）；
  MCP 删除条目 = 从组合文件里删掉那一段（写前 .bak-<时间戳> 备份、写后重新解析校验：
  目标少一条、别的条目一条不少、总数只少 1，校验不过自动回滚）。bundle 自带 patch 层里的条目不给删（那是改安装包）
• 命中阻断项时，确认按钮禁用，但原因原样摊开 —— "为什么不能删"比"按钮灰着"有用得多
• 这些动作没有注册成工具：模型拿不到"删用户东西"这个动作，只有人在面板上点了才会发生
• 顺手的小习惯（R35）：工具条吸顶（长列表滚动时搜索与筛选仍在）；「密度」一键在舒适/紧凑之间切换
  （紧凑模式隐藏英文原文、压缩行距 —— 一条条扫 133 张卡时更好用，记在本地）；只要有筛选生效，
  工具条下面就有一行筛选摘要，每个条件都能单独摘掉，右侧「清除全部」；空态会说清"为什么空"并给一键清除；
  首次打开有一行引导提示（点过就记住）—— 卡片底部的操作是新入口，不提示的话没人会往下看
• 会不会被加载（R12）：enabled（在不在 dsh.profile.bundles）不是加载判据 —— cordis.yml / cordis.patch.yml 的顶层条目按 name: 能直接挂包，依赖链也会把包带起来。
  面板按入口算四态：bundles 直接启用 / 配置条目挂载 / 随某个入口（依赖链）加载 /
  不会被加载（三条都不沾）。卡片只给两枚 chip（不会被加载 灰、配置入口 蓝），
  浮窗写出「随 dsh-ops 加载」这类具体链路，工具条有「不会被加载 N」筛选 ——
  这是比「未使用」更硬的死重量判据（装了根本不会跑）。
  ⚠️ 这是声明层面的判据：运行时按路径 require() 的动态加载看不见，所以文案是「不会被加载」而不是「绝对没跑」。
• 判据能自己下结论（R13）：node dev/probe-loadstate.mjs 独立重算加载路径
  （自己扫 profile 的 node_modules 与两份组合文件），再和目录快照对账，钉七条不变式 ——
  计数守恒 / bundle 口径 / via 指得回入口 / dormant 与入口无交集 / disabled 不算入口 / 快照与重算一致 /
  dormant 对加载中的声明封闭（I7），破一条退出码 1；--json 可机读。
  它用的是同一份判据（不是第二套规则），所以抓的是"实现与数据脱节"。
• 报告自带加载口径（R13）：catalog_export 的概览多一行「加载路径」（入口数 + 四态），
  并单开一节「不会被加载（N 条）」（名称/来源/版本/体积/最近调用 + 边界说明 + 可省体积）；
  当前筛选清单（exportFiltered）多一列「加载」。清单拿出去不用再自己算。
• 不会被加载 → 怎么卸干净（R14）：工具条上「不会被加载 N」的旁边有「处置清单」。
  点它（或调 catalog_uninstall action=plan）会按弱连通分量分组给出可执行清单，
  因为那 26 个目录不是同一种东西，处置方式完全相反：

三条硬规矩：
1. 按分量分组，不是一个包一条 —— dsh-mnemon 自己声明 18 个 dormant 子包，子包又反向声明它（有环）。
单删父留子 = 留一堆孤儿；单删子 = 父（将来若启用）缺件。
2. 只生成、永不执行删除：面板与工具都不提供"删"按钮，清单里给的是可复制的
Remove-Item 命令 + 复核命令，删不删由人决定；写入 reports/uninstall-*.md|.json 还要二次确认。
3. 判据是声明层面：运行时按路径 require() 看不见；hoisted 扁平 node_modules 下，
一个插件可以不声明却 require('lodash') 命中 —— 删纯库前先 pnpm why。
- 删之前先预演（R16）：清单卡片上多一个「预演（不动盘）」按钮（工具侧 catalog_uninstall action=simulate）。
它在内存里把选中的目录从依赖图上摘掉、重算四态，然后回答这份清单没回答的问题：
删完以后会不会有东西指空。三个可能的坑各占一行，空的不出现：

★ 预演按目录算，不按包名：同项目第二份（ghbackup 与 dsh-github-backup 是同一个包名）
只删一份时，包名还有一份在盘上 —— 按包名整体算会把正在被加载的那一份也算进去，
于是把一次安全的清理报成"有风险"。这条是真踩到的：按包名预演，整份清单被判 risky。
★ 它不是删吧没问题的背书：判据仍是声明层面（运行时按路径 require() 看不见）。
★ 一个自证：按整份清单预演必须判安全。判据说 dormant 不在任何入口、也不在任何加载链上，
那么把这批目录全摘掉就不该有入口指空、不该有加载中的包声明它们 —— 这条写进了 hosttest，
它一旦变红，说明清单选错了包，而不是模拟器坏了。
- 删完以后再对一次账（R27）：清单卡片上多一个「对账（不动盘）」按钮（工具侧 catalog_uninstall action=verify）。
预演回答"删了会怎样"，对账回答"照这份计划动完手，盘上到底成了什么样"。三个问题，按优先级：

★ 对账只 stat 计划里点名的那些目录（本机 26 次 stat，不遍历 node_modules），
其余判据走同一个 resolveLoadPaths（与预演、加载四态、catalog_health 同源，不另写一份）。
★ 组内互相声明不算失守：计划按弱连通分量分组，整组一起走才是预期 ——
这里按包名反查「谁声明了它」再把同组成员剔除，否则每一组都会误报。
★ 结论同样不进 localStorage：一份过期的「已删干净」会替人背书下一次动手。
★ 计划从哪来：显式 planPath（只许 reports/ 下）> 本次会话算过的那份 > reports/ 里最新一份。
删完常常隔一次重启才回来对账，落盘的 uninstall-*.json 才是可信来源。
★ enabled 与「白删」是两件事：enabled 说的是在不在 dsh.profile.bundles，而白删看的是
今天仍在引用它的三处入口（bundles / 未关掉的配置条目 / profile 的 dependencies）。
- 改了代码，宿主里跑的是新的吗（R18）：面板头部与 catalog_health 现在同时给磁盘版本与
运行中版本；不一致就明说「运行中仍是 0.17.0，磁盘已是 0.18.0 —— 重载插件或重启 DSH 之后
新代码才生效」。为什么不加就不行：build 标签读的是磁盘（package.json + 最新文件 mtime），
所以显示 0.18.0 时宿主里跑的可能是 0.17.0，新工具、新路由根本不存在 ——
R16/R17 两轮都因此误判过一次「已经生效了」。同一轮里还把独立探针收进了 dev/ship.mjs
（probes 项，现在十一个、231 条不变式），交接前那条命令从「三层自检」变成三层 + 探针 + 副本同步。
- 这两天变了什么（R17）：面板顶部多一条变化条（只在真有变化时出现）：
「自 10-24 11:27 以来 · 3 处变化 · 新增 1 · 升版 2」，点开列明细。历史落在 history.json：

三条硬规矩：
1. 指纹没变就不记：每次「重新扫描」都写一条的话，基线时间会被不断刷新，
「自 11:27 以来」永远只剩几分钟，等于看不到真实的变化窗口；
2. 只留最近 20 条；坏 JSON 当空历史（面板不该因为一行脏数据打不开）；
3. 第一条快照是 0 处变化，不是「133 条新增」——「还没有历史」和「没变化」是两件事，
界面上都不能画成空横幅（hosttest 真机抓到过这个：first=true 却报 133 处）。
- 确认之后，窗口清零（R19）：变化条右边多一个「标记已看过」按钮 —— 点一下把当前目录冻结成基线
（写数据目录里的 history-ack.json，存的是整份快照而不是一个时间戳），之后变化条只显示
「自你 X 确认以来」的变化，没变化就整条消失；history.json 不动（「我看过了」不等于「历史变了」）。
同一轮把 R17 那条「Skill 正文改动看不见」补上了：readSkillDir 本来就要读整份 SKILL.md，
顺手算一个 sha1 前 12 位（58 个技能 ≈ 1.2 MB 内存哈希，实测 < 10 ms），所以改一个字也会进「被编辑」。
升级窗口有明确判据：旧快照里没有哈希时不算编辑，否则第一次重建会报 58 处「被编辑」。
这也是 CATALOG_VERSION 抬到 9 与 HISTORY_VERSION 抬到 2 的原因。
- 回看更早的窗口（R21）：changes 只给最近一个窗口、sinceAck 只给确认之后的窗口 ——
再往前的快照一直躺在 history.json 里却没有任何界面能读到。现在变化条下方多一行
「历史（N 个窗口 / 共 M 条快照）」：点开就是相邻快照相减的时间线，每行写清哪个窗口、
新增/消失/升版/来源变/加载态变/被编辑各几处、以及前几个名字（Skill 正文改过会标「正文已改」）。
基线本身不产出一行（它没有「之前」，写成「新增 133 条」会误导）；指纹相同 / 0 处变化的窗口跳过；
只带每类前 4 个名字，counts 永远是真实数字。导出报告的「变化」一节下面也会列出最近 8 个窗口；
catalog_health 多一行「历史：共 N 条快照 / M 个窗口可回看」。
- 只改配置也要看得见（R23）：R17/R19/R21 的变化条只比目录条目（插件版本 / 来源 / 加载态、
Skill 正文哈希）—— 改 cordis.patch.yml 里的 disabled、往 dsh.profile.bundles 加一个包时，
条目一个都不变，变化条照样报「0 处变化」。现在快照里多一段配置层签名 {fingerprint, counts}：
指纹取排序后的 id / name / disabledKind + bundles（sha1 前 12 位），计数是声明层的
生效条目 / 启用 / 关掉 / 条件启用 / 被 patch 覆盖 / bundles / 组合文件数。
变化条因此多一个「配置层」chip，点开写「关掉 25 → 24，bundles 50 → 51」；只换了哪个条目被关掉
（计数没变）时写「条目变了（生效 246）」；更早窗口的时间线里同样一句话。
签名只解析声明（不扫 222 个包、不读 asar）—— 历史每次重建都要记一条，付不起完整审计那份代价；
同一原因，present / asar / missing 不进指纹（依赖安装态，换台机器就会变，会误报成「配置被改」）。
升级规则与 R19 同型：两条快照里只有一条有签名时不判变化，否则升级后第一次重建就报警。
HISTORY_VERSION 抬到 3；确认基线 history-ack.json 也冻结签名，「自上次确认以来」同样看得见配置层。
- 从配置层点回卡片（R24）：浮层里每条声明后面多了两样东西 —— 解析徽标（profile / asar / 查不到 /
无法判定）和 「在 bundles / 不在 bundles」（关掉与条件启用的条目尤其需要：bundles 里的包即使这里写着
disabled: true，bundle 自带的 patch 层也可能把它重新打开）。profile 与 asar 的行可以点：点一下关掉浮层、
把搜索框换成包名并跳到对应卡片；查不到 / 按路径 / 分组条目没有卡片，不冒充可点。
跳转时会清掉来源 / 加载态 / 用法 / 标签筛选——否则当前筛选正好把目标卡藏起来，看起来就像"跳转坏了"。
键盘同样可用（Tab 到行、Enter / 空格触发）。数据侧只给 /state.composition 多一份去重排序的 bundleNames
（50 个包名，不传 bundles.rows，20 秒轮询里不多塞 file/line）。
- 配置层变化下钻到具体条目（R25）：R23 只能说「关掉 25 → 24」，说不清是哪一条。现在
signatureOf 把声明身份表（id / name / disabledKind）与 bundles 名单一起压进快照；指纹没变就不追加，
但老快照缺这份明细时会补记一条（只补一次，不伪造）。compareComposition 新增
stateChanged / declsAdded / declsRemoved / bundlesAdded / bundlesRemoved，规则仍是单边缺就不判——
否则升级后第一次改动会把 50 个 bundle 全报成"新加的"。面板变化条与报告共用同一套措辞：
「关掉 25 → 24，@deepseek-ai/dsh-hmr 关掉→启用，bundles +dsh-extra」；明细最多 4 条，多的写「…等 N 条」
（完整名单在快照里，HISTORY_VERSION 不变）。
- 交接单（R26）：换会话前最容易漏看的不是数据，而是几份既有结论的交叉核对 —— 运行中到底是哪一版、
最新 ship 有没有失败、工作区脏不脏、staging 旧不旧、目录快照还对得上现实吗（R34：profile 比快照新就判 bad 并先让你重建）。catalog_handoff 把 11 项压成一张单子：
版本（磁盘 vs 运行中，含「重启 DSH」而不是含糊的 stale）、工具数、配置层缺口、变化与确认、历史快照、
staging、最新 ship、git 头部/脏文件/未推送、最新目录快照；write:true 才落 reports/handoff-<时间戳>.md。
判断在 lib/handoff.mjs（纯函数，dev/probe-handoff.mjs 9 条合成数据探针），默认只读。
- 卸载清单的前提能被证伪（R14）：「删 dormant 不会弄坏正在加载的东西」不是感觉，是一条不变式 ——
I7：没有任何「会被加载」的包声明依赖一个 dormant 包。node dev/probe-loadstate.mjs 每次都会验它，
而 node dev/probe-uninstall.mjs 再验清单本身四条（I8 覆盖与不重叠 / I9 体积口径 / I10 钉住键安全 / I11 不误伤加载路径）。
这条抓到过真问题：按「同名副本取最后读到那份」算依赖图，emoji-regex 被算成 dormant，
而顶层 string-width（随 @anweat/dsh-browser 加载）正声明着它 —— 照那份清单删就会弄坏加载。
修法是同名副本取依赖并集（保守方向：宁可少判一个 dormant），并把 CATALOG_VERSION 抬到 8。
- 配置层到底挂了什么（R22）：面板头部多一个「配置层」入口（有缺口时角标写「查不到 N」/「缺 N」），
点开是把两份组合文件的声明摊开：cordis.yml + cordis.patch.yml 各多少条顶层条目、按 id 合并后生效多少条、
每条是包 / 子路径 / file:// 路径 / cordis:group 分组 / 只按 id 覆盖，那个包在 profile 还是官方 asar 里，
哪些被 disabled: true 关掉、哪些是 !!js 条件启用（给原文，不求值）。
另有一行专门核对 dsh.profile.bundles：声明 50 → profile 里 43 + 官方 asar 7 + 真的缺 0。
三条边界直接印在浮层脚注里：不展开 bundle 自带的 patch 层（本机 tool-bash 在 cordis.yml 里写着
disabled: true，但 bash 工具确实在跑）、表达式不求值、组合条目「静态查不到」≠ 一定坏
（运行期注入的虚拟模块看不见 —— 本机 dsh-plugin-desktop 就是这种）。
只有 bundles 里点名却找不到才会占顶部公告位并说「宿主启用它们时会失败」。
同一份数据还进 catalog_health（一行）、catalog_composition 工具、导出报告的「配置层（声明）」一节。
另有一个 catalog_handoff（R26/R34）：把「换会话之前」要对的 11 项压成一张交接单。
判据在 lib/composition.mjs（纯函数、不碰磁盘），dev/probe-composition.mjs 用合成文本钉 C1–C14。
- 快捷键：/ 聚焦搜索、Esc 清空搜索（浮窗里 Esc 关闭浮窗）
- 缓存自愈：统计缓存超过 10 分钟且没有任务在跑时，面板自己起一次增量刷新（只重读变化的会话，实测 0.4~0.7 秒），不用记着点「刷新统计」；有任务在跑、或本挂载已经刷过，就不再触发 —— 否则会和 20 秒轮询叠成「一直在刷新」
- 传输压缩（R31）：/state 实测 359 KB（139 条条目）、面板每 20 秒拉一次，所以路由按需 gzip ——
请求头带 accept-encoding: gzip 且正文 ≥ 1 KB 才压，否则原样（浏览器/Electron 的 fetch 自动解压，
零客户端改动）。刻意读 res.req 而不是改 20 个调用点的签名：压缩是传输层的事，不漏进业务代码。
R31c：这件事现在能自己报 —— json() 把 {raw, packed} 回给 /state，/state 再 noteTransport
记到 service 上，于是 catalog_health 多一行「传输：上次 /state 359361 字节 → gzip 85631 字节（23.8%，4.20×）」，
/health.transport 是同一个数。要现量仍可用 dev/measure-state.mjs --base http://127.0.0.1:<端口>。
- 分页：列表底部「共 N 条 · 第 X / Y 页」+ 上一页/下一页/首页/末页，每页 12 / 24 / 48 / 96 / 全部；搜索、筛选、排序任一变化自动回第 1 页
- 外观：深/浅主题共用一套本地色板（由 label-primary 混出，深色下不再是刺眼白框）；卡片悬停时边缘发一圈克莱因蓝 #002FA7 的光，键盘 :focus-visible 同样有蓝环
- 浮窗（点卡片，屏幕居中，点外部或 Esc 关闭）：
- 每个工具各自的调用次数、报错、平均耗时、最近一次、涉及会话数
- 会话列表：会话昵称 + 次数 + 是否子代理（含父会话名），可分页、每页条数可选（10/20/50/100）
- 来源判定依据（逐条列出为什么这么判）、标签编辑、创建时间、仓库链接
- 「位置与安装形态」（插件）与「位置与体积」（Skill）：源目录（一键复制）、是 junction 还是 profile 里的实体目录副本、磁盘体积与文件数 —— 「装上了却不工作」时先看这里，「要不要删」时也看这里
- 自写/混血额外有「上传 / 更新到 GitHub」「缺口分析」
- 判错来源可以手工标一次（存进 .dsh-plugin-catalog/overrides.json，之后不再问）

> ⚠️ 面板必须自己滚：DSH 官方中列（div._centerCol）是 overflow:hidden，
> 面板若不自己 height:100% + overflow-y:auto，第二屏之后会被静默裁掉 ——
> 表现为「没有滚动条、也翻不到下面」。这条已固化成 dev/audit.mjs 的断言，改回去会红。

工具（同一套能力，普通会话里直接调）

MCP 分类（R30）

面板工具条上第三颗类型 chip：全部 / 插件 / Skill / MCP。MCP 与插件是两种不同的东西，所以它有自己的判据：

数据来源与边界：

• 声明层（与「配置层」浮层读同一份文本、同一时刻），改完组合文件要 重启 DSH 才生效（cordis.patch.yml 不热更）。
• env / headers 的值永不下发到浏览器或报告，只给键名；url 的 userinfo 与 query 隐藏。
• 「孤儿调用」= 统计里出现过 mcp____*，但组合文件里现在没有这台服务器 —— 删过条目或改了 serverName；catalog_health / 交接单会把它标成 warn。

运行期真相与卡片操作（R35）

两件事必须分开看：声明层回答"按配置会不会被加载"，运行期回答"宿主 Loader 里它到底怎么了"。
本插件两个都有，而且互不替代。

运行期真相（catalog_runtime / 卡片 chip / 洞察条）

判据在 lib/runtime.mjs（纯函数）：moduleName 带子路径时按包名归一；同一个包多条 Loader 条目时
取"最能说明问题"的那条（failed 优先）；读失败给 index = null，而不是空表 ——
用空表会把所有"声明会加载"的条目全判成 declared-absent，面板立刻一片假警报。

两类"看起来缺席、其实正常"的东西（真机第一跑踩到的坑，已进自检）：
bundle 是层（@deepseek-ai/dsh-base 就是 96 条 insert 的官方大层），它自己不作为插件运行；
transitive 是 npm 依赖（@dsh-ops/bash-win32-x64 是原生二进制），本来就不注册 Loader 条目。
所以 declared-absent 只对非 bundle 的普通插件与 config 条目成立；bundle 的健康改问
listBundles() 的 availability / error，而且只对 enabled === true 的 bundle 报 ——
离线官方目录里"可选但没装"的条目（本机 dsh-subagent-claude-code / -codex）不算故障。

卡片上的五个动作（只走面板，不注册成工具）

三条安全纪律（都有自检钉死）：

1. 两段式：点动作只出计划（POST /action/plan：可不可用、阻断项、警告、目标、备份/回收站位置）；
   确认条里再点一次才执行（POST /action/apply 必须带一次性 token + confirm:true，5 分钟过期）。
2. 写前备份、写后校验：改组合文件先复制 .bak-<时间戳>，再写临时文件 + rename 原子替换；
   然后重新解析校验（目标 id 少一条、别的条目一条不少、总数只少 1），校验不过自动把备份写回去。
   Skill 删除本身就是"移动"，所以回收站就是它的备份。
3. 留痕：每次动作（成功与失败）追加一条到 <数据目录>/actions-journal.json（最多 100 条），
   面板与 catalog_health 都能看到最近几条 ——"它怎么不见了"要能查到是谁、什么时候干的。

边界（如实）：

• MCP 只处置 profile 自己那两份组合文件里的条目；bundle 自带 patch 层里的条目（node_modules//cordis.patch.yml）阻断 ——
  删它等于改安装包，重装/升级就回来了。MCP 的解析器也只看 profile 两份文件（bundle 层的 config: 最小解析器读不懂）。
• 插件卸载不删源码：自写插件通常是 junction，卸载只去掉依赖与入口。想彻底删，先卸载、再自己删工作区目录。
• 随插件安装的 Skill（assets/skill/ / skill/）不给删 —— 请卸载插件或改插件源码。
• 运行期真相依赖宿主 pluginManager.listPlugins()；没有它的老宿主上这一层退化为「读不到」，面板其余功能不受影响。

数据与隐私

全部落在工作区 .dsh-plugin-catalog/（不写插件安装目录 —— 升级/重装即丢）：

红线：统计里只有会话 ID、会话昵称、时间戳、工具名、计数。没有任何对话文本。
工具参数只在解析 skill 调用取技能名时被读一次，随后丢弃。

统计口径：

• 只读 .dsh/sessions/**/session*.zstd，绝不扫 .dsh/dsh-checkpoint-rewind/ 那类百万文件级快照目录。
• 一个会话可能同时有 v3 与 v4 两份日志（本机 772 个会话里 36 个如此），按 callId 去重，不会把调用算两遍。
• 首次打开前台不等：先显示缓存，后台算（本机 811 个日志 / 455 MB / 59,813 次调用，全量约 40~60 秒）；
  之后走缓存，增量刷新约 0.5 秒。
• 缓存超过 24 小时会在界面上提示「建议刷新」，不会自动重算（避免你以为卡了）。

来源四分类怎么判

Skill 的「自写」判据是：.gh-upload/my-dsh-skills/（自写集合仓）里有同名目录。

诚实的边界：npm 装进来后被就地改过的包，本工具无法自动判定 —— node_modules 里没有 .git，
也没有发布包的哈希可比。这类会标「待确认」或需要你手工标一次；标完存在 overrides.json，不再问。

用在哪里（与本机其它插件的关系）

• 工具归属是推断的：ctx.tools.schemas() 只给 name/description/parameters，宿主没有工具→插件的登记表
  （ToolService 按 agent scope 分 layers，与插件无关）。所以用两条证据链：
  ① description 指纹（那段描述逐字来自注册它的插件源码，唯一命中即归它）；
  ② 无 description 时退到 name: '' 字面量（弱证据）。
  有描述却哪儿都找不到 ⇒ 判为宿主核心/官方，面板单列，不算进任何插件卡片。
• 实测覆盖率（本机 196 个工具 / 53,759 次调用）：描述指纹 193 个（85.2% 的调用量）、
  名字字面量 1 个、判为宿主 2 个（plugin_manager / exit_plan_mode）、歧义 0、未归属 0。
  所以卡片上的「调用总次数」是按真实归属累加的，不是按名字猜的。
  ⚠️ 关键细节：插件源码里的 description 常被多行字符串拼接切开，直接拿拼好的句子去源码里找
  会永远找不到（一开始就是这么把一堆自写插件误判成"宿主"的）。所以两边都压平（去空白/引号/加号/转义）
  再比，dev/audit.mjs 里有针对拼接与转义 \n 的回归用例。
• 官方工具包在 app.asar 内（77 个 dsh-tool-*），会按 asar 索引读出来参与归属判定 —— 否则
  65% 的调用量会挂在一句「未知来源」上。
  ⚠️ Electron 把 app.asar 当目录，openSync 打开归档本身会失败；lib/asar.mjs 自动区分
  「virtual 模式（宿主里，走成员路径）」与「header 模式（纯 node）」，/health 会报当前模式。

「插件安装」升级时的卸载协作（R32）

宿主 0.2.1 的 pluginManager.installBundle 按包名判已装，对已存在的包名一律回
already-installed（原文：uninstall it before installing another version）。所以
dsh-plugin-installer 的「检查更新 → 升级」只有一条路：先卸载旧版，再装新版。

卸载这件事落在本插件，原因是判据都在这儿：谁声明依赖它、它现在会不会被加载、
它是 npm 还是 link:、是不是宿主自带包。判据与执行分开写，就会出现「面板说安全、执行时指空」。

两边都不硬依赖：

• 本插件不改「处置清单」的行为（批量清理目录仍然只生成、永不执行）。它只是多了一项
  「单个包」的能力，没有消费方时安静地待着，面板与 13 个工具一个都不变；
• dsh-plugin-installer 取不到这个服务时，升级会被明确拒绝并说清原因（不会排一队必然失败的任务）；
  安装、回滚、诊断、Skill 安装等全部照常。

判断「它到底会不会被加载」仍然只看 catalog_list 的 loadState；这里提供的是
动手那一步，不是第二套判据。

发布到 GitHub（自写 / 混血）

一个总按钮：「上传备份到 GitHub」→ 先出计划（不动任何东西）→ 你确认后才推。

• 命名：自写 dsh-；混血 dsh--local（不覆盖原仓）
• 所有仓默认私有，全插件只有一处建仓且写死 --private
• 不 force push（lib/gitops.mjs 里没有 --force 这条路径）
• 密钥命中即停：扫 .env、.env.*、secrets/、*.key、*.pem、configs/*-secret.json、
  configs/*-config.json 与常见 token/私钥/连接串模式；命中 critical/high 的仓跳过、其余照推，
  最后给「未推清单」。清单只给「文件:行 + 规则 + 掩码 + 一句判断」，不回显明文。
• README 中英两版：英文版由 AI 按规范翻译（章节一一对应、专有名词保留原文、代码块与占位符原样、
  「待补充」→ TBD）；没有需要补英文的内容就不生成（英文 README、正文过少、只有「待补充」骨架都不生成）。
• 公开是独立的一次操作（catalog_publish action=public）：必须 confirm:true，且先重扫一遍，
  有命中直接拒绝。

每周任务

打开面板时若距上次超过 7 天，后台跑一次缺口分析（不阻塞界面）。
安全审核 不自动跑 —— 面板上会显示「安全审核（已到期）」按钮，由你点（它要读源码片段，更贵也更需要你在场）。

• 缺口分析维度：README 缺哪些关键章节、构建产物该不该入库、package.json 有无自包含安装命令、
  有没有把宿主核心包误写进 dependencies（会遮蔽宿主、导致插件批量加载失败）、Skill 的 description 够不够用
• 安全审核维度：pull_request_target / workflow_run 是否检出并执行 fork 代码、GITHUB_TOKEN 是否最小权限、
  可疑 eval / 拼接执行的 spawn、依赖线索。按「文件 + 行号」给发现，按置信度排序，每条附「可采纳 / 可拒绝」

已知限制（如实说明，不夸大）

0. 安装 / 升级 / 卸载插件与 Skill 不归本插件管（刻意如此）：装东西走 dsh-plugin-installer
   （install_hub_search_plugins / install_hub_submit_request / install_hub_status）或官方 plugin_manager。
   本插件只做清点、判据、处置清单、对账、导出。★ 曾计划过一个 catalog_import，评估后主动不做：
   两套安装路径会各写各的快照与回滚，出问题时谁也没法证明是哪一套写的。两边的关系是"它装、我核"——
   装完回面板看 loadState 是否 loaded、进了 catalog_mcp / catalog_list 没有。
   R35 的卡片动作是例外，且只走面板：卸载 / 停用 / 删 Skill / 删 MCP 由人点、服务端两段式确认；
   它们没有注册成工具（模型拿不到"删用户东西"这个动作）。
   0b. R35 动作层的三条边界：MCP 只处置 profile 自己那两份组合文件（bundle 自带的 patch 层阻断）；
   插件卸载不删源码（junction 只去掉依赖与入口）；随插件安装的 Skill 不给删。详见「运行期真相与卡片操作（R35）」。
   0c. 运行期真相依赖宿主 pluginManager.listPlugins()：没有它的老宿主上这一层退化为「读不到」
   （面板与工具都会如实说原因），其余功能不受影响。fiberPhase=failed 只能告诉你"它失败了"，
   具体错误仍在宿主日志 / plugin_manager set_plugin 的 diagnostic 里。
1. 私有仓拿不到平台级安全扫描：GitHub 的 Secret Scanning / Dependabot / Push Protection 需要付费 GHAS。
   所以「依赖已知高危」只能靠本地规则与模型常识，准确度低于平台级扫描。
2. Skill 的调用统计只能到「次数 + 最近一次时间」，无法细分到会话 —— 这是机制限制，界面上有标注。