@morehao/dsh-skills-console 0.4.0 → 0.5.1

package/README.md

@@ -6,14 +6,14 @@
 [![check](https://github.com/morehao/dsh-skills-console/actions/workflows/check.yml/badge.svg)](https://github.com/morehao/dsh-skills-console/actions/workflows/check.yml)
 [![license](https://img.shields.io/npm/l/@morehao/dsh-skills-console.svg)](LICENSE)
 
-DSH（DeepSeek Harness）的技能控制台：**装、更新、删除、启停、导出到其他 Agent，外加一份订阅清单**。
+DSH（DeepSeek Harness）的技能控制台：**装、更新、删除、启停、共享至其他 Agent，外加一份订阅清单**。
 
 它把本机技能收进一张清单：有哪些、从哪来、谁能用、是不是最新。要用的打开，不用的关掉；别的 Agent 需要，一键建链过去——技能本体始终只有一份。
 
 ## 为什么需要它
 
-- **一个地方管所有技能**：装好的和本机已有的技能都在同一张清单里，来源、版本、接入的 Agent、更新时间一眼看清，不用去翻目录。
-- **按需启停，省上下文**：暂时用不上的技能一键停用，DSH 的模型调用与 `/` 手动调用立刻看不到它，再打开就恢复；磁盘上的技能、导出关系、其他 Agent 都不受影响。
+- **一个地方管所有技能**：装好的和本机已有的技能都在同一张清单里，来源、版本、共享至哪些 Agent、更新时间一眼看清，不用去翻目录。
+- **按需启停，省上下文**：暂时用不上的技能一键停用，DSH 的模型调用与 `/` 手动调用立刻看不到它，再打开就恢复；磁盘上的技能、共享关系、其他 Agent 都不受影响。
 - **一份技能，多个 Agent**：多数 Agent（OpenCode、Cursor、Gemini CLI 等）直接读共享技能目录，装好即用；只认自己目录的（如 Claude Code）在面板里勾一下就能建链过去。
 - **装完不是结束**：上游仓库一直在动，控制台会检查新提交，先告诉你「会影响哪些技能」，再由你决定更不更新。
 - **删错还能救**：删除先进回收站保留 7 天；更新失败自动回滚上一版。
@@ -22,21 +22,22 @@ DSH（DeepSeek Harness）的技能控制台：**装、更新、删除、启停
 
 | 能力 | 说明 |
 | --- | --- |
-| 清单 | 汇总本机技能，来源、版本、可见状态、已接入的 Agent 一处看全；共享目录里已有的技能第一次打开就自动纳入管理 |
+| 清单 | 汇总本机技能，来源、版本、可见状态、共享至哪些 Agent 一处看全；共享目录里已有的技能第一次打开就自动纳入管理 |
 | 安装 | 填 `owner/repo` 或 GitHub URL，先检测仓库里有哪些技能、各自做什么；可以全装，也可以只挑几个 |
 | 更新 | 检查上游新提交，列出 commit 区间和受影响的技能，确认后一键更新；本地改过的技能会先要求确认 |
 | 删除 | 删除前体检（不碰别人建的东西），再快照进回收站（保留 7 天） |
 | 启停 | 一键开关；停用后 DSH 的模型调用与 `/` 手动调用都看不到它，其他 Agent 与磁盘文件不受影响 |
-| 导出 | 只给「只读自己目录」的 Agent 建链，默认不导出；直接读共享目录的 Agent 不出现在列表里 |
-| 查看 | 只读打开技能正文与文件：渲染 / 原文切换、目录树、单文件预览，外加来源、哈希与接入信息 |
-| 订阅 | 关注 `owner/repo` 的上游变化，只记快照、不下载技能；ref / 子目录可选，不填 ref 时跟随默认分支 |
+| 共享 | 只给「只读自己目录」的 Agent 建链，默认不共享；直接读共享目录的 Agent 不出现在列表里 |
+| 查看 | 只读打开技能正文与文件：渲染 / 原文切换、目录树、单文件预览，外加来源、哈希与共享信息 |
+| 技能介绍 | 列表每行一个 ✨，点开就能看到模型写的「这个技能能做什么、什么时候用」；只发 `SKILL.md` 与文件名清单，结果缓存在本地，内容没变不重复调用 |
+| 订阅 | 关注 `owner/repo` 的上游变化，只记快照、不下载技能；展开条目能看到作者原描述，也可以让模型写一段 AI 介绍再决定装不装；ref / 子目录可选，不填 ref 时跟随默认分支 |
 | 作用范围 | 管 user 级共享技能；暂不支持按项目启停。项目或用户目录里有同名副本时，副本仍优先可见 |
 
 ## 界面
 
 - **两个入口**：默认在 DSH 设置页的「技能控制台」分区；页头 ⚙ 里打开「侧边栏入口」，左侧栏就会出现独立面板，切换立即生效。
-- **一页两 tab**：已安装 / 订阅。页头右侧是「新安装时自动导出」与「添加技能 / 添加订阅」。
-- **每行五个动作**：开关（启停）、查看、更新、导出设置、删除；窄面板下隐藏「查看」，技能名本身仍是入口。状态标签覆盖最新 / 可更新 / 本地已改 / 上游已移除 / 软链断裂 / 无上游等。
+- **一页两 tab**：已安装 / 订阅。页头右侧是「新安装时自动共享」与「添加技能 / 添加订阅」。
+- **每行五个动作**：开关（启停）、查看、更新、共享设置、删除；技能名旁的 ✨ 打开 AI 介绍；窄面板下隐藏「查看」，技能名本身仍是入口。状态标签覆盖最新 / 可更新 / 本地已改 / 上游已移除 / 软链断裂 / 无上游等。
 - **窄面板不跳版**：动作组按面板宽度自然换行，插件名始终完整；列表按宽度切两列；滚动只发生在列表区，切 tab、调整窗口都不会让整页翻面。
 - **Agent 多了不挤**：每行最多展示 3 个，其余折成 `+n`，悬浮或聚焦即可看全。
 - **找得到**：支持按名称 / 来源 / Agent 搜索，按「可更新 / 待检查 / 已停用」筛选，平铺或按 Agent 分组。
@@ -48,10 +49,22 @@ DSH（DeepSeek Harness）的技能控制台：**装、更新、删除、启停
 
 - **抽屉速览**：列表不动，右侧滑出只读抽屉；Esc / 点遮罩 / × 关闭，关闭后回到原来的筛选与滚动位置。
 - **整页深读**：抽屉底部「在整页打开」切到整页阅读（正文 + 左侧目录），顶部返回条回列表。
-- **三个 tab**：正文（渲染 / 原文切换，原文保留 frontmatter）、文件（目录树 + 单文件预览；`.md` 默认渲染、可切原文，其他文本直接出源码）、信息（来源、ref、commit、skillPath、内容哈希、安装 / 更新时间、接入 Agent、启停、本地改动）。
-- **只读**：没有输入框和保存按钮。更新 / 导出设置按可写状态决定是否可用；状态文件损坏时仍可查看，管理动作禁用。
+- **三个 tab**：正文（渲染 / 原文切换，原文保留 frontmatter）、文件（目录树 + 单文件预览；`.md` 默认渲染、可切原文，其他文本直接出源码）、信息（来源、ref、commit、skillPath、内容哈希、安装 / 更新时间、共享至哪些 Agent、启停、本地改动）。
+- **只读**：没有输入框和保存按钮。更新 / 共享设置按可写状态决定是否可用；状态文件损坏时仍可查看，管理动作禁用。
 - **能预览什么**：能按 UTF-8 解码的文本文件（`.md` / `.html` / `.jsx` / `.css` / `.sh` / 无扩展名脚本…）直接显示源码；单文件上限 256 KB（超出截断并提示）；图片、音视频、压缩包等二进制显示「暂不支持预览」和文件名 / 大小。
 
+## 技能介绍（AI 生成）
+
+有些技能只有英文说明，也有的光看标题不知道能干什么。已安装列表里每行技能名旁都有一个 `✨ 介绍`：
+
+- **点开即看**：生成过的直接显示本地缓存，秒开；没生成过才出现「生成介绍」按钮，点它才调模型。
+- **写什么**：2–3 句能力介绍——能做什么、适合什么场景 / 典型触发，必要时点出关键限制；用模型自己的话概括，不是逐字翻译。
+- **发什么**：`SKILL.md` 正文（超出 `maxInputBytes` 截断）与技能目录的文件名清单（最多 30 个），**不读其他文件内容**；语言跟随界面（中文 / English）。
+- **缓存在本地**：`$DSH_HOME/skills-console/intros.json`，按技能名 + 语言分开存；`SKILL.md` 内容哈希变了会提示「可能过期」，重新生成才覆盖。失败不缓存。
+- **默认模型**：优先用 `config.intro.provider/model`，没配就用 DSH 当前默认模型；同一时间只跑一个生成，重复点击返回「正在生成」。
+- **订阅候选也能看**：展开订阅后，条目行同样有 `✨ 介绍`；按快照 `commit` 拉远端 `SKILL.md` 再生成，缓存 key 带 commit，不挡「安装」。展开时还会显示作者自己的 frontmatter 描述，不花额度。
+- **关闭方式**：`config.intro.enabled = false`（界面隐藏 ✨ 入口）。其他可调项见「数据与配置」。
+
 ## 安装
 
 插件自带下载与解压能力，**不需要预装 Node / npm / npx / git**；首次安装需要联网拉取依赖。
@@ -75,19 +88,19 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 ## 快速上手
 
 1. **添加技能**：点右上角「添加技能」，填 `owner/repo` 或 GitHub URL，点「检测技能」；仓库里有多个技能时勾选要装的（支持多选，默认全选，列表带每个技能的说明），只有一个会默认勾上。检测不到时可以手填技能名，留空则装仓库内全部。
-2. **导出到别的 Agent**：只有「只读自己目录」的 Agent 才需要这一步（例如 Claude Code）。点行内「导出设置」勾选目标 Agent；本来就读共享目录的 Agent 不在列表里。之后新装技能默认导出到哪里，用页头「新安装时自动导出」设定（默认一个都不勾）。
+2. **共享至其他 Agent**：只有「只读自己目录」的 Agent 才需要这一步（例如 Claude Code）。点行内「共享设置」勾选目标 Agent；本来就读共享目录的 Agent 不在列表里。之后新装技能默认共享至哪些 Agent，用页头「新安装时自动共享」设定（默认一个都不勾）。
 3. **检查更新**：点列表头上的刷新图标；有更新的行会亮起「更新」，也可以一次「全部更新」。本地改过的技能会先要求确认。
-4. **临时停用**：关掉行内开关，只影响 DSH 侧；DSH 的模型与 `/` 调用立刻看不到它，技能文件、导出关系与其他 Agent 都还在，再打开就恢复。项目或用户目录里另有同名副本时，副本仍优先可见，行内会点名。
+4. **调用策略**：点行内「自动 / 仅手动 / 完全停用」状态按钮切换，弹层里同时给出各 Agent 的覆盖情况。自动＝模型与 `/` 都能调用；仅手动＝只改 `SKILL.md` 的 `disable-model-invocation`，`/` 仍可用；完全停用＝把 `SKILL.md` 改名为 `SKILL.md.disabled` 并留 marker，恢复时回到停用前的模式。作者已在 `SKILL.md` 里声明仅手动时，chip 只读展示，不会被覆盖。停用期间更新 / 安装会被拒绝，避免文件被悄悄写回。
 
 ## 安全与可靠性
 
 - **只动自己的东西**：只维护本插件创建的链接；删除前先体检，要删的链接已被换成真实目录或外来链就中止，别人的同名链接不碰也不删。
-- **启停不改文件**：停用只写插件状态，技能本体与导出链一个字节都不动——本地修改不会被下次更新覆盖，更新也不用跟你的编辑抢文件。
+- **文件改动的边界**：自动只写插件状态；仅手动只改 frontmatter 的一行并先备份；完全停用只做改名 + marker，内容一字节不差。v3 lock、共享链接与正文都不碰；更新会重放调用策略，其余本地改动仍会先要求确认。
 - **可回滚**：删除进回收站（7 天）；更新前自动备份，失败还原上一版，需要时也能手动回滚。
 - **状态坏了就只读**：状态文件损坏或版本不认识时，插件降级只读、管理动作禁用，不猜结构、不自动修复。
-- **不接收任意路径**：请求里的目标一律走注册表反查，导出链只会指向共享目录下的同名技能。
+- **不接收任意路径**：请求里的目标一律走注册表反查，共享链接只会指向共享目录下的同名技能。
 - **大仓库也能更新**：带设计素材的大仓库（压缩包 50MB+）不会被大小上限卡住。
-- **「仅手动」不算丢技能**：技能自己声明只在 `/` 手动调用时，行内标「仅手动」并给出原因，不会被当成异常。
+- **「仅手动」有明确入口**：可以在控制台切换，也可能由技能作者在 `SKILL.md` 里声明；作者声明时只读展示，不会被覆盖，也不会被当成异常。
 - **同名副本会点名**：项目或用户目录里另有同名技能时，界面直接指出「模型看到的是另一份」，不假装可见的就是共享目录那一份。
 - **限流有兜底**：公开仓库匿名可用；GitHub 配额打满时会自动换通道继续检查，也可以设置 `GITHUB_TOKEN`，把配额从 60 次/小时提到 5000 次/小时——私有仓库安装也靠它。
 
@@ -97,10 +110,21 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 | --- | --- |
 | 技能本体 | `~/.agents/skills`（DSH 与多数 Agent 共用的技能目录） |
 | 插件状态 | `$DSH_HOME/skills-console/state.json`（`DSH_SKILLS_CONSOLE_HOME` 可换根目录） |
-| 备份 / 回收站 | `$DSH_HOME/skills-console/{backups,trash}` |
+| 备份 / 回收站 | `$DSH_HOME/skills-console/{backups,trash}`；仅手动改写的原文另存 `backups/invocation/` |
+| 技能介绍缓存 | `$DSH_HOME/skills-console/intros.json`（已安装技能按名字、订阅候选按 `source@commit:path`；只存生成的文本与元数据，不存 `SKILL.md` 原文） |
 | 事件日志 | `$DSH_HOME/skills-console/dsh-skills-console.log`（JSONL，1MB 滚动） |
 
-技能本体留在共享目录，导出只是建链，不搬文件。
+技能本体留在共享目录，共享只是建链，不搬文件。
+
+技能介绍的可调项（写在 profile / `cordis.patch.yml` 的插件 `config` 里）：
+
+| 键 | 默认 | 说明 |
+| --- | --- | --- |
+| `intro.enabled` | `true` | `false` 时界面隐藏 ✨ 入口，接口返回 501 |
+| `intro.provider` / `intro.model` | 空 | 留空用 DSH 当前默认模型；两个必须同时给 |
+| `intro.maxInputBytes` | `24576` | 发给模型的 `SKILL.md` 上限（8–48 KB），超出截断并在提示词里标注 |
+| `intro.maxOutputTokens` | `300` | 输出上限（96–1024） |
+| `intro.timeoutMs` | `30000` | 单次生成超时（5–60 秒），超时返回 504 |
 
 ## 开发与发布
 
@@ -109,11 +133,11 @@ plugin_manager install_bundle(target = <本仓库绝对路径>)
 ## 边界（明确不做）
 
 - 不做技能市场 / 搜索，也不接管或改写其他工具自己的 Agent 分发。
-- 不编辑技能正文：查看器只读，更新会整份覆盖。
+- 不编辑技能正文：查看器只读；只有「仅手动」会改 frontmatter 的 `disable-model-invocation`，「完全停用」只做改名，其它内容不碰。
 - 不做文件级差异预览：只给 commit 区间与受影响技能；要看具体行，在终端跑 `git diff <from>..<to> -- <skillDir>`。
 - 不做图片 / 二进制预览。
 - 不做跨机器同步，不落盘任何 token。
-- 不做全机隐身：启停只对 DSH 生效，直接读共享目录的其他 Agent 仍会看到技能。
+- 不做进程级隐身：「自动」的启停只对 DSH 生效；「完全停用」会改名 `SKILL.md`，读该目录的其他 Agent 也看不到，但不会阻止外部重新写回文件。
 - 不支持项目级启停：项目里的同名技能仍按 DSH 的优先级可见。
 - 不接管宿主 preset 层与其他插件自带的技能源；诊断里会把它们标成盲区，而不是假装支持。