dsh-pick 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# dsh-pick
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**帮你在 DSH 生态里选对插件。**
+
+说需求 → 找候选 → 多维比较 → 出结论。下载量只是证据，判断才算数。
+
+> 定位对比：`dsh-find-plugin` 负责「**找到**」（搜 GitHub 仓库，按 star 排）；
+> `dsh-pick` 负责「**挑对**」（算去噪指标，给首选 / 备选 / 不推荐）。
+> 一个 `find_dsh_plugin`，一个 `pick_plugin`。
+
+---
+
+## 为什么需要它
+
+npm 官网和各类 stat 站能看数字，但看数字回答不了「我该装哪个」。
+
+更麻烦的是，**npm 下载量是噪声极大的指标**：版本一发布，CI、镜像、npm 客户端缓存刷新会把当天数字推高一个数量级。按原始下载量排出来的「第一」，很可能只是「发版本最勤的那个」。
+
+所以 `dsh-pick` 的核心不是下载量，而是**去噪后的指标**：
+
+| 指标 | 含义 |
+|---|---|
+| 日常基线 | 扣掉发布日与次日后的每日中位数，最接近真实使用量 |
+| 近 7 日环比 | 在涨还是在凉 |
+| 版本节奏 | 平均几天发一个版本，维护者的投入度 |
+| 最近更新 | 是不是已经弃坑 |
+| 健康度 | 以上四项加权，基线 40% + 增速 25% + 新鲜度 20% + 节奏 15% |
+
+效果示例：`dshmarket` 周下载 160,042，日常基线只有 19,721 —— 相差 8 倍。
+
+---
+
+## 用法
+
+### 作为 DSH 插件（推荐）
+
+```sh
+dsh plugin --profile web add dsh-pick
+```
+
+装完重启 `dsh web`，打开 **设置 → dsh-pick**，就是完整的选插件面板。
+
+首次使用要先生成目录（在 dsh-pick 的安装目录下，或任意目录）：
+
+```sh
+npx dsh-pick build --deep 332
+```
+
+不跑也行——面板会提示「目录未生成」，排行榜和搜索会空着，但界面照常打开。
+
+### 作为命令行 / 独立网页
+
+```sh
+npm i -g dsh-pick      # 或 npx dsh-pick
+
+dsh-pick build --deep 332          # 抓目录 + 算去噪指标
+dsh-pick serve --port 8891         # 起本地服务，打开面板
+```
+
+装好后浏览器开 `http://127.0.0.1:8891/`。
+
+### 命令
+
+| 命令 | 作用 |
+|---|---|
+| `build [--deep N] [--pages N]` | 抓目录并算去噪指标 |
+| `build --deep-only` | 只补算缺失的去噪指标（不用重抓目录，省 5 分钟） |
+| `search "<需求>"` | 按需求描述找候选 |
+| `rank [--metric ...] [--cat ...]` | 排行榜，指标支持 `weekly` / `baseline` / `growth` / `score` |
+| `stats <pkg> [pkg...]` | 精确数据，目录没有就实时查 npm |
+| `serve [--port N]` | 本地预览面板 |
+
+示例：
+
+```sh
+dsh-pick search "我想装个数据库"
+dsh-pick search "任务完成时给我发微信通知"
+dsh-pick rank --metric baseline --cat 记忆与上下文 --limit 20
+```
+
+---
+
+## 结构
+
+```
+dsh-pick/
+├── package.json
+├── bin/dsh-pick.js     CLI 入口
+├── lib/
+│   ├── engine.js       数据引擎：抓目录、算指标、查询（一个引擎，多个入口）
+│   ├── classify.js     13 类 + 其他，关键词加权分类
+│   ├── metrics.js      去噪指标：基线 / 增速 / 节奏 / 新鲜度 / 健康度
+│   ├── words.js        需求 → 搜索词（同义词 + 中文二元切分），CLI 与面板共用
+│   └── normalize.js    （在 engine.js 内）排名与链接字段
+├── data/catalog.json   目录产物
+├── plugin/
+│   ├── index.js        DSH 宿主端：挂 /api-dsh-pick/* 路由
+│   ├── client.js       设置页面板（iframe 复用 web/panel.html）
+│   └── cordis.patch.yml 插进「设置 → dsh-pick」
+└── web/
+    ├── panel.html      选插件面板（独立调试用，也是插件内嵌的同一份）
+    └── panel.js        面板逻辑
+```
+
+面板只有一份代码，两种宿主都认：独立 `dsh-pick serve` 走根路径，插件内嵌走 `/api-dsh-pick` 前缀（`panel.html` 顶部的小加载器自动判断）。
+
+---
+
+## 数据口径
+
+- **来源**：`registry.npmjs.org`（元数据、版本发布历史）+ `api.npmjs.org/downloads`（下载量）
+- **滞后**：npm 统计约滞后 5 天，页面显示的「数据截止」是最后一个已汇总的完整日
+- **覆盖**：npm 上带 `dsh-plugin` 关键字的 2,250 个包（search 接口深分页上限约 2,250）
+- **去噪范围**：只有周下载 Top 332 会抓 30 天日序列和发布历史，其余只有周/月下载量
+- **下载量口径**：含 CI、镜像源、爬虫、缓存回源等非人类流量，**不等于用户数**
+
+---
+
+## 已实现 / 待做
+
+**已实现**
+- 目录构建（`build` / `build --deep-only`，带 3 轮补抓对付限流）
+- 13 类自动分类
+- 去噪指标 + 健康度
+- 需求搜索（同义词 + 中文二元切分）
+- 排行榜（4 种指标 × 分类筛选）
+- 选插件四步流程 + 规则版结论
+- 结论导出为独立网页
+- 我的监控（localStorage）
+
+**待做（见方案文档）**
+- DSH 插件形态：托管端 `plugin/index.js` + `plugin/client.js` + `cordis.patch.yml`
+- 5 + 2 个 AI 工具：`pick_ranking` / `pick_search` / `pick_stats` / `pick_compare` / `pick_trend` / `pick_recommend` / `pick_export`
+- skill `plugin-analyst`（意图路由 + 口径说明 + 禁止 AI 自己推算数字）
+- AI 语义分类，把「其他」从 29% 压到 10% 以内
+- 周报（可指定方向）
+- PDF 导出（DSH Desktop 可用 Electron `printToPDF`）
+
+---
+
+## 许可
+
+MIT

package/bin/dsh-pick.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// bin/dsh-pick.js — dsh-pick 命令行
+//
+//   dsh-pick build [--deep 200] [--pages 9]   抓取目录并算去噪指标
+//   dsh-pick search "我想装个数据库"           按需求找候选
+//   dsh-pick rank [--metric weekly|baseline|growth|score] [--cat 分类] [--limit 30]
+//   dsh-pick stats <pkg> [pkg...]             精确数据（目录没有就实时查）
+//   dsh-pick serve [--port 8891]              起本地服务，预览面板
+
+import { createServer } from 'node:http'
+import { readFile } from 'node:fs/promises'
+import { join, extname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { buildCatalog, loadCatalog, searchByNeed, rank, stats, normalize } from '../lib/engine.js'
+
+const PKG_ROOT = fileURLToPath(new URL('..', import.meta.url))
+const [, , cmd = 'help', ...rest] = process.argv
+
+function arg(name, dflt) {
+  const i = rest.indexOf('--' + name)
+  return i >= 0 && rest[i + 1] && !rest[i + 1].startsWith('--') ? rest[i + 1] : dflt
+}
+const has = name => rest.includes('--' + name)
+// 位置参数：把 `--flag 值` 整对踢掉，剩下的才是需求文本
+const positionals = (() => {
+  const out = []
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i].startsWith('--')) { if (rest[i + 1] && !rest[i + 1].startsWith('--')) i++; continue }
+    out.push(rest[i])
+  }
+  return out
+})()
+
+const pad = (s, n) => String(s).padEnd(n)
+const padL = (s, n) => String(s).padStart(n)
+const num = n => (n === null || n === undefined) ? '—' : Number(n).toLocaleString('en-US')
+const pct = n => n === null || n === undefined ? '—' : (n >= 0 ? '+' : '') + (n * 100).toFixed(0) + '%'
+
+async function main() {
+  switch (cmd) {
+    case 'build': {
+      const deep = Number(arg('deep', 200))
+      const pages = Number(arg('pages', 9))
+      await buildCatalog({ deep, pages, deepOnly: has('deep-only'), onProgress: m => console.log('·', m) })
+      break
+    }
+
+    case 'search': {
+      const need = positionals.join(' ') || arg('need', '')
+      const cat = await loadCatalog()
+      const limit = Number(arg('limit', 12))
+      const r = searchByNeed(cat, need, { limit })
+      if (!r.length) { console.log('没找到候选。目录需先跑 `dsh-pick build`。'); break }
+      console.log(`\n需求：「${need}」  候选 ${r.length} 个（相关性 / 评分 / 周下载 / 日常基线 / 环比 / 最近更新）\n`)
+      for (const x of r) {
+        const d = x.deep
+        console.log(
+          pad(x.name, 34) + padL(x.relevance + '%', 6) +
+          ' ' + padL(num(x.weekly), 9) + ' ' +
+          (d ? padL(num(d.baseline), 9) + ' ' + padL(pct(d.growth), 8) + ' ' + pad(d.ageDays + 'd', 6) : pad('—', 25)) +
+          '  ' + x.category
+        )
+        if (x.description) console.log('   ' + x.description.slice(0, 100))
+      }
+      console.log()
+      break
+    }
+
+    case 'rank': {
+      const cat = await loadCatalog()
+      const metric = arg('metric', 'weekly')
+      const category = arg('cat', null)
+      const limit = Number(arg('limit', 30))
+      const rows = rank(cat, { metric, category, limit })
+      console.log(`\n榜单：${category || '全部'} · 指标 ${metric} · 截止 ${cat.anchor}  共 ${cat.total} 个包\n`)
+      console.log(pad('排名', 5) + pad('插件', 34) + padL('周下载', 10) + padL('月下载', 10) + ' ' + padL('基线', 9) + ' ' + padL('环比', 8) + ' ' + pad('更新', 6) + '分类')
+      rows.forEach((r, i) => {
+        const d = r.deep
+        console.log(
+          padL(i + 1, 4) + ' ' + pad(r.n, 34) + padL(num(r.w), 10) + padL(num(r.m), 10) + ' ' +
+          (d ? padL(num(d.base), 9) + ' ' + padL(pct(d.growth), 8) + ' ' + pad(d.age + 'd', 6) : pad('—', 24) + ' ') +
+          r.cat
+        )
+      })
+      console.log()
+      break
+    }
+
+    case 'stats': {
+      const names = positionals
+      if (!names.length) { console.log('用法：dsh-pick stats <pkg> [pkg...]'); break }
+      const cat = await loadCatalog()
+      const rows = await stats(cat, names)
+      for (const r of rows) {
+        if (r.source === 'not-found') { console.log(`\n${r.name}：npm 上不存在或无名下数据`); continue }
+        const d = r.deep
+        console.log(`\n${r.name} ${r.version || ''}  [${r.category || '未分类'}]  (${r.source})`)
+        if (r.description) console.log('  ' + r.description.slice(0, 120))
+        console.log(`  周 ${num(r.weekly)} · 月 ${num(r.monthly)}${r.total != null ? ' · 累计 ' + num(r.total) : ''}`)
+        if (d) console.log(`  日常基线 ${num(d.baseline)} · 环比 ${pct(d.growth)} · ${d.versions} 个版本 · ${d.cadence} 天/版 · ${d.ageDays} 天前更新 · 评分 ${d.score}`)
+      }
+      console.log()
+      break
+    }
+
+    case 'serve': {
+      const port = Number(arg('port', 8891))
+      const types = { '.html': 'text/html', '.json': 'application/json', '.js': 'text/javascript' }
+      const extName = f => f.slice(f.lastIndexOf('.'))
+      // 只放行这三个目录：面板、目录数据、共享词典
+      const ROOTS = {
+        '/web/': join(PKG_ROOT, 'web'),
+        '/data/': join(PKG_ROOT, 'data'),
+        '/lib/': join(PKG_ROOT, 'lib'),
+      }
+      const server = createServer(async (req, res) => {
+        try {
+          let p = decodeURIComponent(new URL(req.url, 'http://x').pathname)
+          if (p === '/') p = '/web/panel.html'
+          const prefix = Object.keys(ROOTS).find(k => p.startsWith(k))
+          if (!prefix) { res.writeHead(403).end('forbidden'); return }
+          let buf
+          if (prefix === '/data/') {
+            // 目录要走一遍归一化，补上排名与链接字段
+            buf = Buffer.from(JSON.stringify(await loadCatalog()), 'utf8')
+          } else {
+            buf = await readFile(join(ROOTS[prefix], p.slice(prefix.length)))
+          }
+          res.writeHead(200, {
+            'content-type': (types[extName(p)] || 'text/plain') + '; charset=utf-8',
+            'cache-control': 'no-store',
+          })
+          res.end(buf)
+        } catch {
+          res.writeHead(404).end('not found')
+        }
+      })
+      server.listen(port, '127.0.0.1', () => console.log(`dsh-pick 面板 → http://127.0.0.1:${port}/`))
+      break
+    }
+
+    default:
+      console.log(`
+dsh-pick — DSH 插件选型助手
+
+  build   抓取目录并算去噪指标        --deep 200 --pages 9
+  search  按需求描述找候选            --limit 12
+  rank    排行榜                      --metric weekly|baseline|growth|score --cat 分类 --limit 30
+  stats   精确数据（实时兜底）          dsh-pick stats <pkg> [pkg...]
+  serve   本地预览面板                 --port 8891
+`)
+  }
+}
+
+main().catch(e => { console.error('失败：', e.message); process.exit(1) })