# echocat-skill-panel — 安装说明

给**另一台机器 / 另一位用户**用。整个文件夹就是插件本体，拷走即可。

- 包名：`echocat-skill-panel`　版本：`4.2.0`（**全小写**，npm 风格；这个名字同时是 Loader 条目名、vendor 目录名和客户端 bundle id，**五处必须一致** —— 见第五节）
- 面向：DSH Desktop Beta，实测 `2.0.11-beta.1` / 内核 `@deepseek-ai/*` `0.1.6-alpha.1` / cordis 4
- 自带已构建的 `lib/client.js`，**目标机器不需要任何构建步骤**

**它做什么**

1. **每轮对话结束时报一次 skill 调用情况**（模型自动 / 你手动 `/name` / 一个都没调用），并弹一次系统原生通知。
2. **三个常驻界面**：输入框正上方的横栏（点一下就地展开完整报告）、左栏图标、中栏完整面板。
3. **在界面里直接安装 / 管理 skill**（3.0 新增）：粘贴 SKILL.md、上传 `.md`/`.zip`、从链接、从 Git 仓库；还能预览、覆盖、卸载。
4. **记住每个 skill 的来源，并能一键更新**（4.0 新增）：安装时把来源地址、分支、子目录、commit 与内容指纹写进该 skill 自己的 `.echocat.json`；面板标出「可更新」，点两下即用作者的新版本替换旧版本（旧版本先进备份）。手工装的 skill 可以「标记来源」补上这条记录。

---

## 一、安装

**最省事**：直接跑文件夹里的 `安装-3.0.ps1`。它会先备份 profile 清单，再镜像文件、清掉旧包名、建目录联接、改写 manifest，最后跑 `pnpm install`；出错可以一键回退：

```powershell
& ".\安装-3.0.ps1"                    # 安装
& ".\安装-3.0.ps1" -Rollback          # 回退到上一次安装前的清单
& ".\安装-3.0.ps1" -SkipInstall        # 只装文件、不改 manifest
```

**手动四步**（想自己控制时用）：

```powershell
$ProfileDir = "$env:USERPROFILE\.dsh-beta\profiles\desktop"   # 按实际数据目录调整
$Src        = "<这个文件夹的路径>"

# 1) 拷进 profile 的 vendor 目录（文件夹名必须是包名）
New-Item -ItemType Directory -Force "$ProfileDir\vendor" | Out-Null
Copy-Item -Recurse $Src "$ProfileDir\vendor\echocat-skill-panel"

# 2) 建目录联接，让裸 import 能被解析
New-Item -ItemType Junction -Path "$ProfileDir\node_modules\echocat-skill-panel" `
                             -Target "$ProfileDir\vendor\echocat-skill-panel" -Force
```

3) 编辑 `$ProfileDir\package.json`，两处都要有：

```json
{
  "dependencies": {
    "echocat-skill-panel": "link:./vendor/echocat-skill-panel"
  },
  "dsh": {
    "profile": {
      "bundles": [ "@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "echocat-skill-panel" ],
      "patchReload": "live"
    }
  }
}
```

4) 装依赖并重启：

```powershell
Set-Location $ProfileDir
node "<DSH 安装目录>\resources\app\node_modules\pnpm\bin\pnpm.mjs" install
```

**必须重启 DSH Desktop Beta。** host 半侧与客户端 bundle 都在启动时读入，刷新页面不够。

> 从 2.0 升级过来：先把旧条目（`echocat-skill-panel-2.0` 或 `EchoCat-skill-Panel-2.0`）从 `bundles` 与 `dependencies` 里**删掉**，再按上面装 3.0。留着旧条目而旧目录已不存在，会让 profile 拼装失败、应用起不来。

## 二、重启后怎么确认装好了

看 `%APPDATA%\DSH Desktop Beta\logs\host\dsh-<日期>.log`：

```
[I] [echocat-skill-panel] skill-report: panel feed at /api/skill-report/state
[I] [echocat-skill-panel] skill-report: install endpoint will write to C:\Users\...\.dsh-beta\skills
[I] [echocat-skill-panel] skill-report: skill install endpoint at /api/skill-report/skills
[I] [echocat-skill-panel] skill-report mounted: per-turn skill audit active
```

界面上：

1. **输入框正上方**多一条横栏（圆点 + `技能` + 本轮结论 + 回合数），点一下就地展开完整报告；右侧有**检查更新**与**安装**图标。
2. **左栏最左列**多一个图标，点它在中栏打开同一份报告。
3. 报告里「已安装 skill」小节（默认收起）展开后是卡片网格，每张卡片有「引用 / 复制名称 / 中文名 / 更新 / 删除」；小节标题上有「检查更新」「重新扫描」「安装」按钮。

> **宽度是跟着界面走的**：横栏与面板的宽度从**你这个界面的输入框宽度**推导（减 16px），所以永远比输入框窄一点，并且和输入框共用同一条中轴 —— 窗口拉宽拉窄、界面整体放大缩小都对。这是 4.0 修的：3.0 用的是写死的 1120px，窗口一窄就比输入框还宽。

## 三、在界面里安装 skill

打开的安装面板有四种方式：

| 方式 | 适合 | 说明 |
| --- | --- | --- |
| **粘贴 SKILL.md** | 最常用 | 整篇粘进去即可。缺 frontmatter 会自动补（`description` 取正文第一段）。 |
| **上传文件** | 别人发你的 skill | `.md` 或 `.zip`，可拖拽进面板。zip 会自动找到里面的 `SKILL.md`，压平多余的包装目录。 |
| **从链接** | 网上的 SKILL.md 或直链 zip | 默认拒绝内网/本机地址。 |
| **Git 仓库** | `owner/repo`、完整 URL、GitHub 的 `…/tree/<分支>/<子目录>` | 需要机器上有 `git`；没有时面板会说明并建议用前三种。 |

**写到哪儿**：优先用配置项 `skillsRoot`；否则用**正在运行的 app 实际报出来的那些 skill 的父目录**（也就是界面底部显示的那个路径）；再否则 `$DSH_HOME/skills` → `~/.dsh-beta/skills`。面板底部会如实显示最终路径，可以一键复制。

**同名怎么办**：不会静默覆盖。先报「已存在同名 skill」，勾上「覆盖」后才写，且旧版本会先被复制进备份目录。

**卸载**：删掉的是移动，不是真删 —— 目录进 `~/.dsh-beta/skill-report/backups/<时间戳>-<名字>`，随时可以手工拷回来。

装完之后面板会自己刷新（host 每 5 秒轮询一次）。如果几十秒后「已安装 skill」里还是没有，重启一次 DSH 让它重新扫描。

## 四、更新 skill（4.0 新增）

**为什么需要它**：3.0 把地址用一次就丢了（git 克隆还会被删掉），于是作者发了修复你也无从判断新旧 —— 只能删掉重装，而删除是移动到备份目录。

**来源记录**：每个由本插件装出来的 skill，目录里都有一份 `.echocat.json`，内容是来源类型、地址、分支、子目录、**安装时的 commit**、以及一份**内容指纹**。它是纯文本，可以自己读、自己删；删除后卡片会退回「标记来源」状态，skill 本身不受影响。

**面板上怎么用**：

| 卡片上的标记 | 含义 | 能做什么 |
| --- | --- | --- |
| `owner/repo · 已是最新` | 来源可比对，远端没变 | 无（或手动「更新」重装一次） |
| `owner/repo · 可更新` | 远端有新 commit | 点「**可更新**」→ 再点一次「确认更新」 |
| `owner/repo · 检查失败` | 连不上远端等 | 稍后再试；鼠标悬停看原因 |
| `标记来源 · owner/repo` | 地址是你手填的，**尚未核对** | 更新会多问一次（因为没人验证过这个地址） |
| `粘贴内容` / `上传文件` / 直链 | 没有可比的版本 | 只能重新从原地址装一次 |
| （没有这一行） | 没有来源记录（手工装的、或 2.x/3.0 装的） | 点 🔗 补一个地址 |

- **检查时机**：打开面板时自动查一次（只对**有来源记录**的 skill，一次批量请求），也可以随时点小节标题上的 ⟳。
- **绝不自动下载**：判断"有没有新版"只跑一次 `git ls-remote`，不重新下载内容。
- **固定版本不误报**：来源固定在某个 commit 上时，不会提示"可更新"。
- **更新前会告诉你**：如果你改过这个 skill 的文件，确认文案会明确说"更新会覆盖它们"；旧版本**总是**先复制进备份目录（`~/.dsh-beta/skill-report/backups/`）。
- **中文名不会被冲掉**：更新沿用你为该 skill 设的 `display-name-zh`。

## 五、卸载插件

1. 从 profile `package.json` 的 `bundles` 与 `dependencies` 里删掉该条目
2. 删除 `vendor\echocat-skill-panel` 与 `node_modules` 下的同名联接
3. 重启

**起不来时的自救**（不用重装应用）：

- `"<DSH>\DSH Desktop Beta.exe" --dsh-desktop-safe-mode` → 安全模式
- `"<DSH>\DSH Desktop Beta.exe" --dsh-desktop-recovery` → 恢复界面，可回滚到健康检查点

## 六、五条硬性约束（踩过坑，别改）

1. **`package.json` 必须有 `dsh.bundle.patch`**，且被 `bundles` 列出的包名要能解析到。缺了它 profile 拼装阶段直接抛错，**应用起不来**。
2. **`dsh.client.platform` 必须是 `"web"`**，且 `exports["./client"]` 指向的文件**必须真实存在**。错了会让 `modules`（必需启动条目）失败，**应用起不来**。
3. **不要动包名**。**五处必须完全一致**：包名、bundle 的 `id`、Loader 条目名（`cordis.patch.yml` 里的 `name`）、vendor 目录名、junction 名。注意 4.0 **没有**改包名 —— 名字里的 `3.0` 是标识的一部分，与内部版本号无关。
4. **`@deepseek-ai/dsh-llm` 与 `@deepseek-ai/schemastery` 只能作 `peerDependencies`**，由 DSH 运行时提供。写进 `dependencies` 并锁版本就会和内核漂移，插件树加载失败。
5. **改了 `src/client/**` 就必须重建 `lib/client.js`**（`node tools/build-client.mjs`），并**在同一次提交里带上** —— 它是入库的构建产物。`verify-install` 会核对 bundle 与包是否一致，漏了会在门里失败。

## 七、配置

在 profile 的 `cordis.patch.yml` 里加**按 id 的覆盖**（是 `id` 覆盖，**不是 `insert`**，`insert` 会塞重复条目）：

```yaml
- id: skill-report
  config:
    enabled: true
    notifyOnNoSkill: true        # false = 只在本轮用到 skill 时才弹通知
    includeSubagents: false      # true = 子代理回合也提醒
    logReports: false            # true = 每条报告也写进 host 日志
    maxRecent: 200
    httpRoute: true              # false = 完全不注册任何路由（面板与安装都失效）
    httpPath: /api/skill-report/state
    translateMissing: true       # 关掉可停止一切模型调用
    allowInstall: true           # false = 面板变只读，安装入口整个消失
    installPath: /api/skill-report/skills
    skillsRoot: ''               # 留空 = 自动解析（推荐）
    backupRoot: ''               # 留空 = ~/.dsh-beta/skill-report/backups
    allowPrivateHosts: false     # true = 允许从本机/内网地址安装
```

## 八、关于自动翻译

面板里每个 skill 的小字中文，来源优先级：

1. 该 skill 目录 `meta.yaml` 的 `summary-cn`
2. 该 skill 目录 `SKILL.cn.md` 的 frontmatter `description`
3. **自动翻译**（`translateMissing: true` 时）—— 用该用户**自己配置的默认模型**翻一次，结果缓存到
   `~/.dsh-beta/skill-report/translations.json`，之后永久复用
4. 都没有 → 显示英文原文

自动翻译消耗该用户自己的 API 额度（每个没有中文的 skill **一次**）。不想要就设 `translateMissing: false`。想手改某条译文，直接编辑那个 JSON（key 是 skill 名）。

> 注：推理模型（推理档设为 High 的模型）会把输出预算烧在思考上而不产出正文；插件已显式按 `none → minimal → low` 依次尝试，实测 `low` 可用。

## 九、许可

MIT，见 `LICENSE`。完整的功能与实现文档见 `README.md`。