# 插件安装与分享（标准版 / 兼容版）

在「插件市场」点击「前往 dsha.cc 选插件」，会使用系统浏览器打开网站。
选取后复制插件下载链接或下载插件包，再回到 App 粘贴安装或本地导入。
在「插件市场」粘贴链接后，页面会显示识别结果，点「安装」开始下载。
安装、启用或禁用完成后，到启动页重启 Web 才会生效。

## 支持的链接

- GitHub 仓库简写：owner/repo，或完整仓库 URL、SSH 仓库地址。
- 分支与子目录：GitHub 的 tree 链接；blob 链接定位到该文件所在的插件目录。
  带斜杠的分支通过 GitHub API 解析到具体提交，不会改装默认分支。
- GitHub archive、codeload、Release 附件下载链接。
- Release 页面：只有一个压缩包附件时直接安装；多个附件时提示复制所需附件下载链接。
- HTTPS 的 .zip / .tar / .tar.gz / .tgz 压缩包直链。
- 含一个完整链接的分享文字。含多个链接时请只保留要安装的那个。

GitHub 网络或 API 受限时，可以先下载插件压缩包，再从本地导入。
GitHub archive 链接会直接使用官方 codeload 下载并保留分支/标签；HTTPS 证书随 APK 提供，
无需先运行基础工具安装。TLS 校验保持开启。
网站入口与现有链接安装、本地导入配合使用；App 不会自动安装在网站浏览的插件。

## 本地导入与导出

「导入插件包」通过系统文件选择器读取 ZIP、TAR、TAR.GZ、TGZ，按文件内容识别格式，
不依赖扩展名或文件管理器给出的 MIME 类型。一个归档可以包含多个插件目录。
优先打开系统 DocumentsUI，避免第三方压缩软件接管却不返回文件；如系统入口有问题，
使用「其他文件选择器」。取消选择、空返回和读取失败都会显示状态，不再无反馈。

「导出插件包」支持多选并选择保存位置。导出的 TAR.GZ 包含插件实体和已有依赖，
可以直接在另一台 DSHA 中导入；无需公共下载目录的存储权限。
官方核心由 dsh 环境更新，不单独导出或通过第三方包替换。

同名插件导入会更新实体，保留此前禁用状态。新实体、依赖准备完成后才替换旧实体；
普通操作失败会复原原插件，不积累每次操作的备份。
成功写入后的进程强杀、系统断电等异常恢复未做完整事务保证。

在「插件管理」可按名称或描述搜索、只看第三方插件、按名称或启用状态排序；
每张卡片的「更多」按钮或长按卡片，都可以复制名称、来源链接、单独导出或删除第三方插件。
管理页不再显示链接安装区，页面统一滚动，名称与操作分行；点按操作状态可查看完整错误信息。

删除前会显示确认，移除该插件的安装目录、启用登记与来源记录，保留聊天、设置、其他插件、
外部导入源和共享依赖。删除后需重启 Web；如需留存，可以先单独导出。
内置插件及官方核心不允许删除，内置可选插件继续通过开关控制。

## 终端 npm 安装

重新打开终端后可直接使用 `npm` / `npx`，Python、npm、Git 与 curl 使用同一套随包证书。

```sh
# 普通依赖、命令行工具：保持 npm 的正常安装方式
npm install 包名
npm install -g 工具包名

# npm 发布的 dsh 插件：下载、校验并登记到插件管理
dsha-plugin install 插件包名
dsha-plugin install @作者/插件@1.0.0
```

`dsha-plugin install` 不执行包的安装脚本，要求发布包已构建且声明 dsh.bundle.patch。
普通 `npm install` 只安装包，不自动修改 dsh 的启用列表。安装 dsh 插件后重启 Web 生效。
作者只提供 GitHub 压缩包、没有发布到 npm 时，继续用链接或本地导入。

## 插件包要求

遵循当前内置 dsh 0.1.2-rc.1 的 bundle 契约：package.json 必须有合法 npm 名称与
dsh.bundle.patch，声明的 patch 文件、main / cordis.entry 入口必须存在。
普通 npm 库不会仅因为名字带 dsh 前缀就被启用为插件。

优先使用作者构建好的 Release 包或 npm pack 产物。依赖齐全可离线导入；
缺少 dependencies 时，在独立目录用 pnpm 安装生产依赖，然后再登记插件。
不会自动执行 prepare / build / install 脚本；依赖工作区源码、需要编译或缺少原生二进制的
插件，应由作者提供适合 Android 容器内 Linux arm64 的完整发布包。

压缩包上限 256 MiB，展开内容上限 768 MiB / 50000 个文件。
归档越界路径、包外软链接、同名冲突和缺失入口会给出明确原因。
一个包里部分安装成功时，会分别显示已安装项目和失败原因。

契约参考：[上游 dsh 插件命令](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.2-rc.1/apps/cli/src/plugin.ts)、
[pnpm install](https://pnpm.io/cli/install)。

## 本次验证范围

针对链接形态运行纯 Java 用例；scripts/test-plugin-manager.py 在独立临时目录验证作用域插件
导出再导入、多插件包、子目录定位、路径拒绝、失败复原、部分成功报告和作用域插件删除保护，不调用网络或 pnpm。
2026-09-05 在 Android 16 真机通过系统文件选择器完成 ZIP 导入、TAR.GZ 导出、删除和导出包重新导入；
还验证了禁用状态跨覆盖安装保留，以及带 npm 依赖的同名插件更新。
实际发现 pnpm 硬链接在 proot 下会导致复制失败，现已固定使用 `package-import-method=copy` 并复验通过。
GitHub 链接识别已在界面验证；各类远程链接的完整下载仍不能由这次验收覆盖。