@morehao/dsh-skills-console 0.5.0 → 0.5.1

package/README.md

@@ -29,14 +29,15 @@ DSH（DeepSeek Harness）的技能控制台：**装、更新、删除、启停
 | 启停 | 一键开关；停用后 DSH 的模型调用与 `/` 手动调用都看不到它，其他 Agent 与磁盘文件不受影响 |
 | 共享 | 只给「只读自己目录」的 Agent 建链，默认不共享；直接读共享目录的 Agent 不出现在列表里 |
 | 查看 | 只读打开技能正文与文件：渲染 / 原文切换、目录树、单文件预览，外加来源、哈希与共享信息 |
-| 订阅 | 关注 `owner/repo` 的上游变化，只记快照、不下载技能；ref / 子目录可选，不填 ref 时跟随默认分支 |
+| 技能介绍 | 列表每行一个 ✨，点开就能看到模型写的「这个技能能做什么、什么时候用」；只发 `SKILL.md` 与文件名清单，结果缓存在本地，内容没变不重复调用 |
+| 订阅 | 关注 `owner/repo` 的上游变化，只记快照、不下载技能；展开条目能看到作者原描述，也可以让模型写一段 AI 介绍再决定装不装；ref / 子目录可选，不填 ref 时跟随默认分支 |
 | 作用范围 | 管 user 级共享技能；暂不支持按项目启停。项目或用户目录里有同名副本时，副本仍优先可见 |
 
 ## 界面
 
 - **两个入口**：默认在 DSH 设置页的「技能控制台」分区；页头 ⚙ 里打开「侧边栏入口」，左侧栏就会出现独立面板，切换立即生效。
 - **一页两 tab**：已安装 / 订阅。页头右侧是「新安装时自动共享」与「添加技能 / 添加订阅」。
-- **每行五个动作**：开关（启停）、查看、更新、共享设置、删除；窄面板下隐藏「查看」，技能名本身仍是入口。状态标签覆盖最新 / 可更新 / 本地已改 / 上游已移除 / 软链断裂 / 无上游等。
+- **每行五个动作**：开关（启停）、查看、更新、共享设置、删除；技能名旁的 ✨ 打开 AI 介绍；窄面板下隐藏「查看」，技能名本身仍是入口。状态标签覆盖最新 / 可更新 / 本地已改 / 上游已移除 / 软链断裂 / 无上游等。
 - **窄面板不跳版**：动作组按面板宽度自然换行，插件名始终完整；列表按宽度切两列；滚动只发生在列表区，切 tab、调整窗口都不会让整页翻面。
 - **Agent 多了不挤**：每行最多展示 3 个，其余折成 `+n`，悬浮或聚焦即可看全。
 - **找得到**：支持按名称 / 来源 / Agent 搜索，按「可更新 / 待检查 / 已停用」筛选，平铺或按 Agent 分组。
@@ -52,6 +53,18 @@ DSH（DeepSeek Harness）的技能控制台：**装、更新、删除、启停
 - **只读**：没有输入框和保存按钮。更新 / 共享设置按可写状态决定是否可用；状态文件损坏时仍可查看，管理动作禁用。
 - **能预览什么**：能按 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**；首次安装需要联网拉取依赖。
@@ -98,10 +111,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}`；仅手动改写的原文另存 `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 |
+
 ## 开发与发布
 
 源码结构、测试策略与本地 `link:` 验证见 [docs/development.md](docs/development.md)；可见性、数据落点与实现边界见 [docs/internals.md](docs/internals.md)；发布流程与排障清单见 [docs/publishing.md](docs/publishing.md)。在本仓工作的 AI agent 请先读 [AGENTS.md](AGENTS.md)。