@morehao/dsh-skills-console 0.3.1 → 0.3.3

package/README.md

@@ -12,10 +12,10 @@ DSH（DeepSeek Harness）的**技能控制台**：装、更新、删除、接入
 
 ## 为什么需要它
 
-- **两份目录，一个真身**：技能装在 `~/.agents/skills`，DSH 只读 `~/.dsh/skills`。插件负责在两边建软链，不复制文件、不产生第二份真相。
+- **两份目录，一个真身**：技能装在 `~/.agents/skills`；DSH 默认同时扫描 `~/.dsh/skills`（rank 400）和 `~/.agents/skills`（rank 500）。插件负责在 DSH 侧建软链，不复制文件、不产生第二份真相。
 - **一份技能，多个 Agent**：Claude Code / Cursor / Codex … 各自只认自己的 `skills` 目录。勾一次，分别建链，之后装新技能也能按偏好自动接入。
 - **装完不是结束**：上游仓库一直在动。插件按 commit 比对，先给出「会影响哪些技能」的计划，再让你决定更新。
-- **看不见 ≠ 删掉**：临时不想让模型用到某个技能，关掉 DSH 侧链接即可；文件和其他 Agent 的接入原样保留。
+- **停用 ≠ 删掉**：关掉 DSH 侧链接，文件和其他 Agent 的接入原样保留；注意 canonical 本身仍在 DSH 的扫描根里，彻底隐藏需要 provider 覆盖层（尚未实现）。
 - **删错还能救**：删除前先快照进回收站（保留 7 天），更新失败自动回滚上一版。
 
 ## 功能
@@ -27,17 +27,31 @@ DSH（DeepSeek Harness）的**技能控制台**：装、更新、删除、接入
 | 更新 | GitHub Trees 检测上游新 commit → 计划（commit 区间 + 影响范围 + 防抖 token）→ 应用前备份，失败自动回滚上一版 |
 | 删除 | 先体检（真实目录 / 外部链接直接中止）→ 快照进回收站 → installer 删 lock 条目与真身（lock 写失败从回收站恢复）→ 只清本插件建的链接与记账 |
 | 接入 | 软链四态判定（`managed` / `managed-external` / `foreign-link` / `real`），**绝不覆盖**别人创建的东西；只列本机已安装目录，已删的 Agent 自动从列表消失 |
-| 启停 | `mode: on/off` 只摘或重建 DSH 侧链接，不动 `SKILL.md`，其他 Agent 的链接也不受影响 |
+| 启停 | `mode: on/off` 只摘或重建 DSH 侧链接，不动 `SKILL.md`，其他 Agent 的链接也不受影响；canonical 仍在 rank 500 扫描范围，彻底隐藏待 provider 覆盖层 |
 | 作用范围 | 全局 `~/.dsh/skills`，或仅指定项目；项目可直接勾选 DSH 已登记的工作区，也可手动选目录 |
+| 查看 | 已安装技能可以只读打开：抽屉速览或整页深读，正文渲染 / 原文切换，文件树与单文件预览，信息 tab 汇总来源、哈希、接入与更新时间 |
 | 订阅 | 关注 `owner/repo`（可指定 ref / 子目录；ref 缺省时跟随仓库默认分支，`master` 仓库也能用），只记快照、不装技能；上游读不到快照时直接报错，不会留下空订阅 |
 
 ## 界面
 
 - **两个入口**：默认在「设置 → 技能控制台」；页头 ⚙ 里可切到左侧栏独立面板，切换立即生效。
 - **一页两 tab**：已安装 / 订阅。页头右侧是「自动接入」（多选 Agent）与「添加技能 / 添加订阅」。
-- **每行四个动作**：开关（启停）、更新、接入设置、删除；状态标签覆盖最新 / 可更新 / 本地已改 / 上游已移除 / 软链断裂等。
+- **每行五个动作**：开关（启停）、查看、更新、接入设置、删除；窄面板下隐藏「查看」，技能名本身仍是入口。状态标签覆盖最新 / 可更新 / 本地已改 / 上游已移除 / 软链断裂 / 无上游等。
 - **Agent 多了不挤**：每行最多展示 3 个，其余折成 `+n`，悬浮或聚焦即可看全。
 - **找得到**：支持按名称 / 来源 / Agent 搜索，按「可更新 / 待检查 / 已停用」筛选，平铺或按 Agent 分组。
+- **待检查 vs 无上游**：「待检查」只表示*这次*没拿到上游结论（限流、网络、仓库 404 等）；再次点「检查更新」时，如果上次没有结论、上游又只回了 304，会无视 ETag 完整重读一次树，不会把「待检查」永久粘住。没有可用订阅来源的技能标「无上游」——它们无法参与更新检查，不计入待检查。
+
+## 查看技能内容
+
+管理途中想知道「这个技能写了什么、值不值得留」，点技能名或行内「查看」即可：
+
+- **抽屉速览**：列表不动，右侧滑出 700px 只读抽屉；Esc / 点遮罩 / × 关闭，关闭后回到原来的筛选与滚动位置。
+- **整页深读**：抽屉底部「在整页打开」切到整页阅读（720px 正文 + 左侧目录），顶部返回条回列表。
+- **三个 tab**：正文（渲染 / 原文切换，原文保留 frontmatter）、文件（目录树 + 单文件预览；`.md` 默认渲染、可切原文，其他文本直接出源码）、信息（来源、ref、commit、skillPath、内容哈希、安装 / 更新时间、接入 Agent、启停、本地改动）。
+- **只读**：没有任何输入框和保存按钮。更新 / 接入设置按 `writable` 与 `readOnly` 复用现有规则；`state.json` 损坏时仍可查看，管理动作禁用。
+- **限制**：按内容判断能否预览，能解码成 UTF-8 的源码类文件（`.md` / `.html` / `.jsx` / `.css` / `.sh` / 无扩展名脚本…）都直接显示源码；单文件上限 256 KB（超出截断并提示）；真正的二进制（图片、音视频、压缩包等）显示「暂不支持预览」+ 文件名与大小，不请求本地文件当图片渲染。
+
+接口与错误码见 [docs/skill-viewer.md](docs/skill-viewer.md)。
 
 ## 安装
 
@@ -64,13 +78,14 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 1. **添加技能**：点右上角「添加技能」，填 `owner/repo` 或 GitHub URL，点「检测技能」；仓库里有多个技能时勾选要装的（支持多选，默认全选，列表带每个技能的说明），只有一个会默认勾上。检测不到时可以直接手填技能名，留空则装仓库内全部。
 2. **接到别的 Agent**：点行内「接入设置」，勾选目标 Agent；需要限定项目时改选「仅以下项目」并勾工作区。之后新装技能默认接哪些 Agent，用它旁边的「自动接入」设定。
 3. **检查更新**：点列表头上的刷新图标；有更新的行会亮起「更新」，也可以一次「全部更新」。本地改过的技能会先要求确认。
-4. **临时停用**：关掉行内开关。DSH 看不到它，但文件和其他 Agent 的接入都还在；再打开就恢复。
+4. **临时停用**：关掉行内开关，摘掉 DSH 侧链接；文件和其他 Agent 的接入都还在，再打开就恢复。canonical 本身仍在 DSH 的扫描根里，所以这并不等于真正隐藏（见「可靠性」里的已知限制）。
 
 ## 可靠性
 
 - **canonical 与 v3 lock 的写入口**：安装、更新、删除由 native installer 统一处理（下载/解压/发现/tree SHA/原子 promote/lock 事务）；插件其他模块只读。限流兜底的 codeload 扫描只在 `os.tmpdir()` 里解压，结果绝不落进 canonical 或 lock。
 - **只动自己的东西**：只处理本插件创建的 `managed` 链接，以及已记账的 `managed-external`；`real` 目录和 `foreign-link` 永不改写，删除前体检直接中止。
 - **启停不改正文**：`mode` 只增删 DSH 侧链接，避免本地修改被下一次安装/更新覆盖。
+- **已知限制：停用 ≠ 不可见**：`mode: off` 只摘 `~/.dsh/skills`（rank 400）的链；canonical 所在的 `~/.agents/skills` 仍是 DSH rank 500 的扫描根，模型可能照旧读到该技能。彻底隐藏需要 provider 覆盖层，尚未实现。
 - **可回滚**：删除进回收站（7 天）；更新前快照到 `backups/`，失败自动还原（接口另提供手动回滚）。
 - **状态坏了就只读**：`state.json` 是坏 JSON 或版本未知时，插件降级为只读并让写接口返回 409，不猜结构、不自动修复。
 - **不做任意路径**：请求里的目标一律走注册表反查，软链目标恒为 canonical 下同名目录。
@@ -107,6 +122,7 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 
 - 不做技能市场 / 搜索，不接管 CLI 已有的 Agent 分发，不给 CLI 打补丁。
 - 不编辑技能正文（`add` 会整份重建，本地改写必然被覆盖）。
+- 不做技能正文编辑与图片 / 二进制预览；查看器只读，更新会整份覆盖正文。
 - 不做文件级差异预览：只给 commit 区间与受影响技能；要看具体行，终端跑 `git diff <from>..<to> -- <skillDir>`。
 - 不做跨机器同步，不落盘任何 token。