Tyon-nos-Ty90/dsh-mcsm-panel

dsh-mcsm-panel — MCSM 面板集成插件（DSH Desktop）

让 DSH 的 AI 助手直接管理你的 MCSManager 服务器实例（仅限你授予该账户的实例权限）：

| 工具 | 功能 | 示例 |
|---|---|---|
| mcsm_console | 向服务器控制台发送命令并按序执行，返回最近若干行输出（真实执行！） | /say 公告、list、kubejs reload、stop |
| mcsm_file | 实例文件管理：list 列目录 / read 读文件 / write 写入（不存在自动创建） / delete 删除（高危） | 查看 mods、改 kubejs 脚本、读取日志、删旧日志 |
| mcsm_instance | 实例级控制（REST，立即生效）：status 查询状态 / open 启动 / restart 重启 / stop 停止 / kill 强杀 | 开服、重启、停服 |
| mcsm_upload | 将本地文件上传到实例目录（两步直传：面板申请通道 → daemon multipart） | 上传 mods 的 jar |

示例（对 ai 说）："在服务器控制台发公告 /say 维护中，10 秒后 stop"——它会用 mcsm_console 完成。

版本与更新（1.0.1）

相比 1.0.0 修复/新增了以下内容（新增 mcsm_instance 与 mcsm_upload 后，请在设置卡片里勾选启用并重启 DSH）：

- HTTPS 面板连接失败：stream_channel 返回的地址若是 https:// 无法建立控制台流连接；现同时处理 https→wss / http→ws。
- 超长输出被截断到开头：mcsm_console 输出超过 maxOutputChars 时改为保留最末尾（最近） 的输出，而不是开头。
- 令牌过期只认 403：会话失效/返回 401 时也会自动重新登录后重试。
- 每次调用都重复登录：同一面板下的令牌现在跨多次工具调用复用，减少频繁登录。
- mcsm_file write 只能改已存在文件：现在会自动检测目标是否缺失，缺失则先创建再写入。
- 新增 mcsm_file delete：删除文件/目录（危险，请谨慎）。
- 新增 mcsm_instance：查询/启动/重启/停止/强制杀死实例（REST，立即生效，高危）。
- 新增 mcsm_upload：把本地文件上传到实例目录（面板申请通道 → daemon multipart 直传，适合 mods jar）。
- 更友好的错误信息：登录/接口返回非 JSON（如登录页/错误页）时给出可读提示。
- 设置卡片：不再裁剪密码字段的空白；保存成功后自动清空草稿；编辑时清除错误提示；新增两个工具的启用开关。

安全提醒：这些工具都是真实、立即生效的。账号只授予目标实例的控制台 + 文件管理权限，不要给实例管理/管理员账号。

安装

解压 zip 后, 在插件文件夹里运行 (DSH Desktop 需已运行过一次):
powershell -ExecutionPolicy Bypass -File install.ps1
可选: -Profile web / -Profile all

安装器会：复制插件到 ~\.dsh\profiles\node_modules\dsh-mcsm-panel，并把一行写入 ~\.dsh\profiles\\cordis.patch.yml（幂等，不会重复）。

手动安装：把 package.json + lib/ 放到 ~\.dsh\profiles\node_modules\dsh-mcsm-panel\，再在 ~\.dsh\profiles\\cordis.patch.yml 追加：
- insert:
- id: mcsm-panel
name: dsh-mcsm-panel

配置（设置 → 插件 → MCSM 面板 卡片）

| 字段 | 说明 |
|---|---|
| 面板地址 | MCSM 面板地址，如 http://127.0.0.1:23333，HTTPS 面板亦支持 |
| 用户名 / 密码 | 面板登录账号（明文保存在 settings.yaml，勿共享该文件） |
| daemonId | 实例所在 daemon 的 ID |
| 实例ID | 实例 UUID |

右下角四个开关：mcsm_console / mcsm_file / mcsm_instance / mcsm_upload（默认全开）。

daemonId / 实例ID 从面板网页地址栏复制：#/instances/terminal/files?daemonId=&instanceId=
（或对象存储/接口返回里取）。

技术细节：mcsm_console 走面板 POST /api/protected_instance/stream_channel 获得 daemon 直连地址后，经 socket.io（engine.io v4）stream/auth + stream/input 发命令。mcsm_file 走 /api/files REST。mcsm_instance 走 /api/instance（查状态）与 /api/protected_instance/{open|restart|stop|kill}。mcsm_upload 先 POST /api/files/upload 申请通道，再把文件以 multipart（字段 file）POST 到 {daemon 地址}/upload/{password}。全部需要：登录会话 Cookie + ?token= 查询参数 + X-Requested-With 请求头。

安全须知（重要）

- 账号只需授予目标实例的控制台 + 文件管理权限——不要给实例管理/管理员账号。
- 密码是明文配置；mcsm_console 能执行 stop、/kill 等一切控制台命令，mcsm_file delete 能删除服务器文件，mcsm_instance 能停止/强杀实例——请自行判断该工具交给 AI 的风险。
- 如需"每次访问前必须用户批准"，可与 dsh-url-gate 网址门禁 配合：把面板地址加入门禁名单（门禁扫描的是命令文本；若 ai 改用 mcsm_* 工具则门禁不拦截，请依赖 AI 的行为约束）。
- 建议只在本机/可信网络使用；跨公网请用面板自带的 HTTPS/TLS。

常见问题

- 工具出现但执行报"未完全配置"：设置卡片保存后立即生效，无需重启（工具本身首次安装需重启才出现）。
- mcsm_console 连接失败：确认目标实例在线、账号有该实例权限、24444 这类 daemon 端口外部可直连（若 daemon 只对内网开放，需在能访问的网络环境运行，或让面板代理）。若面板/daemon 使用 HTTPS，确认 daemon 也支持 wss。
- mcsm_file write 报 Illegal access path：父目录不可写，或目标路径不合法；不存在的新文件会自动补建，但仍需父目录存在且当前账号有写入权限。
- mcsm_file delete 未生效：确认账号有文件管理权限，且目标路径正确（目录可整体删除，请谨慎）。
- mcsm_instance 无反应：确认账号有所需权限，实例不在"安装中"等占用状态。
- mcsm_upload 失败：确认本地路径存在、目标目录可写、daemon 端口可直连；大文件受 daemon maxFileSize（默认 100MB）限制。
- 卸载：从 cordis.patch.yml 删除对应 insert 块，重启；删除 ~\.dsh\profiles\node_modules\dsh-mcsm-panel。

文件清单

dsh-mcsm-panel/
├── install.ps1      # 安装器
├── package.json     # 插件清单 (host 入口 + dsh.client 声明)
├── lib/
│   ├── index.js     # Host: mcsm_console / mcsm_file / mcsm_instance / mcsm_upload 工具 + 面板会话
│   └── client.js    # 设置卡片 (浏览器端)
└── README.md