jsoncode/dsh-listen-npm

dsh-listen-npm

dsh-listen-npm 是基于 DeepSeek Harness（DSH）宿主的 npm 包监控插件。
查询任意 npm 包的完整信息 —— 突出显示每日安装量 —— 并监控自己指定的
npm 库的版本与下载量变化。

- 完整包信息：最新版本、dist-tags、描述、许可证、作者、维护者、链接、
发布时间、版本列表、依赖、README 摘要
- 每日安装量：最新单日 / 近 7 天 / 近 30 天 / 近一年下载量汇总 + 近 30 天
日粒度柱状图（日粒度数据直接来自官方 api.npmjs.org/downloads/range 接口）
- 监控列表：加入监控后插件按配置间隔自动轮询，记录快照与版本变更
（在「历史」tab 查看）、展示下载量趋势
- 模型工具：dsh_npm_info、dsh_npm_downloads、dsh_npm_watch
- 中英双语：界面跟随主界面语言切换

English

预览

侧边栏底部有常驻 npm 监控 按钮（右侧小胶囊显示监控数量）。
弹框含三个 tab：查询（搜索 + 完整详情）、监控、历史。

功能

- 查询 tab —— 输入包名（也支持粘贴 npmjs.com 链接）：registry 搜索接口
防抖联想，回车 / 点击展示完整详情：
- 下载量卡片：最新单日 / 近 7 天 / 近 30 天 / 近一年（最新单日为主焦点，
npm 数据延迟时标签自动写实际日期并标注滞后天数），
附 30 天日安装量柱状图（峰值标注、日均虚线、每柱原生 tooltip）
- 基本信息：首次发布、最近更新、最新版发布（含发布者）、版本总数、
解包大小、文件数、Node 要求、维护者
- dist-tags 标签、最近版本列表（固定高度滚动）、README 摘要（Markdown 渲染）
- 一键 加入监控
- 监控 tab —— 添加 / 移除监控；每行显示 latest 版本（就是普通版本号，不做
任何「有新版本」标记）、最新单日 / 近 7 天下载量（与上个快照对比的趋势箭头）、
右侧近 7 天每日安装量迷你柱状图（尾部尚未统计的日期灰柱占位、日期连续）、
上次刷新时间
- 历史 tab —— 每个包的快照时间线（加入监控与版本变更时自动记录）：
时间、版本、最新单日 / 近 7 天下载量、变更类型
- 入口显隐 —— 侧栏底部入口跟随「在菜单中显示」偏好（默认开启），可在
设置 → npm 监控 分区页或监控 tab 顶部切换。关闭后入口渲染 null（不占位），
宿主设置分区页仍保留 打开 npm 监控 按钮，弹框始终可达（两处同一个偏好源，
改一处即时同步）。
- 弹框配色 —— 与 dsh-get-balance 同一套：rgba(0,0,0,.32) 蒙版 + blur(12px) saturate(1.2)、
color-mix(bg-layer-1 78%) 玻璃面板 + border-l2 细描边 + 14px 圆角、border-l1 分隔线、
主按钮实心 button-primary-fill、选中 tab 为半透明主色胶囊（color-mix(button-primary-fill 18%)
+ 30% 描边，暗色主题下即偏白半透明；选中项 hover 不变色）、输入框与搜索浮层 bg-base、卡片 bg-layer-2、
状态色走 state- 令牌。
- 后台轮询 —— 轮询器与弹框生命周期解耦；每 refreshMinutes（宿主配置，
默认 10 分钟）刷新整个监控列表：每包 1 个轻量 dist-tags 请求 +
1 个 range/last-week 下载量请求（最新单日 / 近 7 天与迷你柱状图的日粒度序列
都由它推导）；发现新版本只写入快照与「历史」时间线，界面不做任何提醒
- 数据文件 —— 监控列表与快照持久化到
$DSH_HOME/dsh-listen-npm.json（原子写，损坏自动 .bak）
- HTTP API —— 浏览器半边经 /dsh-listen-npm/api（信任围栏 +
POST JSON）通信，轮询不会在会话中产生 command 节点；老宿主自动回退命令通道
- 模型工具 —— dsh_npm_info / dsh_npm_downloads / dsh_npm_watch
（list / add / remove / refresh）

配置（宿主 config）

registryUrl: https://registry.npmjs.org   # 国内可换镜像 https://registry.npmmirror.com
downloadsUrl: https://api.npmjs.org/downloads
refreshMinutes: 10                        # 监控列表自动刷新间隔（分钟）

数据说明

- 日粒度数据来自 api.npmjs.org/downloads/range；npm 按自然日聚合下载量且
有 T+N 延迟（实测常为 3~4 天），因此最后一个有数据的自然日不一定就是昨天。
- 连续性：序列一律补齐到「昨天（本地时区）」——区间内 API 漏报的日期补 0，
尾部 npm 尚未统计的日期也补 0（标记 pending，图表里画成灰色虚线柱，最多补
14 天），日期轴不会「断在几天前」。补齐日只用于图表的日历连续。
- 聚合口径：最新单日 / 近 7 天 / 近 30 天只累计真实数据日（窗口截止到
最后一个有数据的日子），避免把 npm 的统计延迟算成 0 下载而虚低；卡片标签会
写出实际截止日期（真有昨日数据时才显示「昨日」），并用一行说明标出尚未统计
的日期区间。
- 完整支持 scoped 包（@scope/name）；registry 路径把斜杠编码为 %2F，
下载量 API 使用原始斜杠（实测两种服务接受形式不同）。
- 查询详情时拉一次 registry 全量文档（react 约 7 MB）—— curl 收集上限 32 MB。

文件结构

├── src/host/.ts         # 宿主半边源码：index.ts（入口）、npm.ts（curl 核心）、ops.ts（op 分发）、store.ts、fence.ts、types.ts
├── src/shared/.ts       # 两边共用的纯逻辑（daily.ts：日粒度序列的日历补齐）
├── src/client/.tsx      # 浏览器半边源码（React TSX）：plugin.tsx、i18n、styles、rpc、store、poller、components/*
├── lib/index.js          # 宿主半边构建产物（tsdown，ESM），提交 git 以支持 git 安装
├── lib/client.js         # 浏览器半边构建产物（tsdown → __ModuleLoader__ 工厂），提交 git
├── lib/types/            # 类型声明（tsc -b 生成）
├── scripts/              # verify-client.mjs（模拟宿主 seed 表校验产物）
├── tsdown.config.ts      # tsdown 构建配置（node half + client bundle banner 包装）
├── tsconfig.json         # solution：引用 tsconfig.host.json / tsconfig.client.json
├── cordis.patch.yml      # 组合包 patch：按包名引用插件行（无路径）
├── package.json          # dsh.bundle + dsh.client(web) manifest + peerDependencies
├── README.md             # 英文文档（默认）
└── README.zh.md          # 本文档

安装

本地开发
dsh plugin --profile web add ./dsh-listen-npm

发布后：npm / tarball / GitHub
dsh plugin --profile web add dsh-listen-npm
dsh plugin --profile web add ./dsh-listen-npm-0.1.0.tgz
dsh plugin --profile web add github:you/dsh-listen-npm#

dsh --profile web --dump-config   # 验证配置层
dsh --profile web                 # 启动（宿主半边需重启才生效）

本地开发依赖：宿主加载 index.js 时按 Node 原生 ESM 解析
@deepseek-ai/schemastery、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-settings，
因此插件目录内必须有可解析的 node_modules（已被 .gitignore 忽略）。
两种做法任选其一：
1. 在插件目录执行 pnpm install；
2. 或把宿主扁平回退目录对应包链接进来：
New-Item -ItemType Directory "$PWD\node_modules\@deepseek-ai" -Force
foreach ($p in 'schemastery','dsh-tools','dsh-settings') {
New-Item -ItemType Junction "$PWD\node_modules\@deepseek-ai\$p" -Target "$env:DSH_HOME\profiles\node_modules\@deepseek-ai\$p"
}

构建

pnpm install
npm run check    # tsc -b（两个 program）
npm run build    # tsc -b && tsdown（lib/index.js + lib/client.js）
npm run verify   # 模拟宿主加载 lib/client.js

License

MIT