npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

koishi-plugin-local-package-upload

v0.0.1

Published

Koishi 本地插件上传

Readme

koishi-plugin-local-package-upload

项目介绍

这是一个为 Koishi 机器人框架开发的本地插件上传服务,自带控制台页面。

它负责四件事:分片接收归档、安全校验归档内容、按内容哈希落盘、调用包管理器完成安装。

用户只需在控制台拖入一个 npm pack 生成的 .tgz,即可安装到当前应用。

项目仓库

  • GitHub:https://github.com/Minecraft-1314/koishi-plugin-local-package-upload
  • Issues:https://github.com/Minecraft-1314/koishi-plugin-local-package-upload/issues

配置项说明

| 配置项 | 类型 | 默认值 | 说明 | |------|------|------|------| | enabled | boolean | true | 是否启用本地上传 | | chunkSize | number | 8192 | 上传分片大小,从下列档位中选择 | | maxSize | number | 67108864 | 单个归档大小上限(字节),即 64 MiB | | ttl | number | 900000 | 未完成上传的保留时间(毫秒),即 15 分钟 | | directory | string | .yarn/local | 归档落盘目录,相对应用根目录 | | prefix | string | package | 归档内清单所在目录,npm pack 生成的是 package | | maxSessions | number | 8 | 同时存在的上传会话上限 | | maxConcurrentChunks | number | 4 | 单个会话并发处理的分片上限 | | scanBudget | number | 30000 | 单个归档安全扫描的时间上限(毫秒) |

chunkSize 可选档位

| 档位 | 单条消息大小 | 建议 | |------|------|------| | 8 KiB(默认) | 约 11 KB | 兼容性最好,适用于任意受限链路 | | 16 KiB | 约 22 KB | 链路较宽松,分片数更少 | | 32 KiB | 约 44 KB | 仅链路确认可传 44 KB 以上时使用 | | 64 KiB | 约 87 KB | 仅链路确认可传 87 KB 以上时使用 | | 128 KiB | 约 175 KB | 仅链路确认无帧大小限制时使用 | | 256 KiB | 约 350 KB | 仅链路确认无帧大小限制时使用 | | 512 KiB | 约 683 KB | 兼容性最差,仅用于对照测试 |

分片越小兼容性越好,代价是分片数量增加。151 KB 归档在 8 KiB 分片下为 19 片,2 MiB 约 256 片。

控制台界面

启用插件后,控制台底部导航新增「本地上传」页面(路径 /local-upload,权限等级 4)。

页面自上而下分为五块:

| 区块 | 内容 | |------|------| | 标题区 | 页面标题、说明文字,以及「刷新」「选择文件」两个按钮 | | 状态卡片 | 归档大小、分片大小、上传进度三项实时状态 | | 拖拽区 | 拖入或点击选择 .tgz,上传中显示进度条与已传字节数 | | 校验结果 | 包名、版本、大小、哈希、描述,以及生命周期脚本警告 | | 操作说明 | 四步使用指引 |

校验完成后点击「安装」,会弹出全局安装进度窗口,逐条输出归档校验、落盘、生命周期脚本提示、包管理器执行等日志,完成后显示安装结果。安装进行中窗口不可关闭,避免误操作中断。

若归档包含 preinstall、install、postinstall、prepare 脚本,页面会显示黄色提示,说明安装时不会自动执行。

控制台接口

本插件不向外暴露任何服务,上传能力仅供自身界面使用。插件会在 Console 上注册以下接口,权限等级 4。

| 接口 | 参数 | 返回 | |------|------|------| | local-package-upload/start | { filename, size } | { uploadId, chunkSize, maxSize } | | local-package-upload/chunk | { uploadId, index, data } | { received, size } | | local-package-upload/finish | { uploadId } | 校验结果,含包名、版本、哈希、生命周期脚本 | | local-package-upload/commit | uploadId | { name, version, filename, request, size, hash } | | local-package-upload/cancel | uploadId | boolean | | local-package-upload/install | uploadId | { name, version, request },需要 installer 服务 |

客户端必须按 start 返回的 chunkSize 切片,分片 index 从 0 递增且不可跳号。

安全校验

上传的归档在落盘前会经过完整扫描。任一项不通过即拒绝,不写入任何文件。

文件名

| 检查项 | 说明 | |------|------| | 扩展名 | 必须是 .tgz | | 路径 | basename 必须等于自身,拒绝任何路径分隔符 | | 长度 | 不超过 214 字符 | | 保留名 | 拒绝 con、prn、aux、nul、com1-9、lpt1-9 | | 控制字符 | 拒绝 \x00-\x1f、\x7f | | 路径穿越 | 拒绝包含 .. |

归档结构

| 检查项 | 上限 | |------|------| | 条目类型 | 仅允许文件、目录与 POSIX 元数据;拒绝符号链接、硬链接、设备文件、FIFO | | 条目数量 | 8192 | | 解压总大小 | 256 MiB | | 单文件大小 | 64 MiB | | 压缩比 | 1000 | | 路径长度 | 512 字符 | | 路径片段长度 | 128 字符 | | 路径层级 | 32 层 | | 绝对路径 | 拒绝 / 开头与盘符开头 | | 路径穿越 | 拒绝 .、.. 片段 | | 清单唯一性 | package/package.json 有且仅有一个 | | 清单大小 | 1 MiB | | 扫描时长 | scanBudget 毫秒,超时中止 |

package.json

| 检查项 | 说明 | |------|------| | 结构 | 必须是对象,嵌套深度不超过 16 | | 循环引用 | 直接拒绝 | | 字段总数 | 单层不超过 512 | | 字段名 | 长度与控制字符校验 | | name | 必须是 Koishi 插件命名,支持 @scope/ | | version | 必须是合法 SemVer | | bin | 拒绝路径穿越与绝对路径,条目不超过 64 | | scripts | 键名合法、内容为字符串、不超过 128 项 | | 依赖字段 | dependencies 等四项的值必须是字符串 | | description / license / author / homepage / main / module | 长度与控制字符校验 | | engines | 必须是对象,值为字符串 |

生命周期脚本

识别 preinstall、install、postinstall、prepare、prepublish、prepack 并在界面标注,不会自动执行。

会话防护

| 检查项 | 默认 | |------|------| | 会话数量上限 | 8,超出时回收最旧会话 | | 单会话并发上限 | 4,超出直接拒绝 | | 分片顺序 | 必须从 0 连续递增,不可跳号 | | 分片大小 | 不得超过 chunkSize 与剩余字节数的较小值 | | base64 | 长度合法、字符集合法、回编码一致 | | 会话 ID | 必须匹配 UUID 格式 | | 落盘路径 | 必须位于落盘目录的直接子级 | | 内容冲突 | 同名文件哈希不一致时拒绝覆盖 | | 过期清理 | 每 5 分钟清理超时会话与孤立临时文件 |

故障排查

上传卡在 0 B 后超时

链路限制了单帧大小。把 chunkSize 调到更小的档位(例如 4096 需自行在配置中指定)后重启。

提示「本地插件上传分块编码无效」

客户端发送的分片超过了服务端配置的 chunkSize。确认客户端读取的是 start 返回的分片大小,而不是自己写死的值。

提示「本地插件归档中缺少 package/package.json」

归档不是 npm pack 生成的,或者顶层目录不是 package。用 npm pack 重新生成即可。

项目贡献者

| 贡献者 | 贡献内容 | |------|------| | Minecraft-1314 | 插件完整开发 |

欢迎通过 Issues 或 PR 加入贡献者列表。

许可协议

本项目采用 MIT 许可证,详情参见 LICENSE 文件。

支持我们

如果这个项目对您有帮助,欢迎点亮右上角的 Star 支持我们!