Skip to content
Back to search

DevToolRadar

把"我要做什么"翻译成"用哪个工具" — 开发工具选型索引,按场景检索,零依赖离线可用。Describe what you want to do, get the right dev tool.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/madcarrot9527-ui--devtoolradar/badge.svg)](/listings/madcarrot9527-ui--devtoolradar)

HTML

<a href="/listings/madcarrot9527-ui--devtoolradar"><img src="/api/listings/madcarrot9527-ui--devtoolradar/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 708 lines · 1 finding marked
  1. # DevToolRadar — 开发工具雷达
  2. 按「你想干什么」找开发工具,而不是按技术栈。覆盖 GitHub 高星项目、awesome 人工精选清单、国内 SaaS/AI 产品,每天自动刷新。
  3. **在线版(不用装任何东西)**:[devtool-radar.app.workbuddy.host](https://devtool-radar.app.workbuddy.host/?sharecode=UDQEOOEBY5)
  4. 现在是 **6575 个工具**,82 个场景标签。**每一条都有自己的一句话说明**,没有一条是空的、也没有两条共用同一段说明。
  5. > 上面这个数字不是手改的:每轮刷新的最后一步会跑 `src/sync_readme.py`,把首屏计数对齐 `data/stats.json`。
  6. > 想知道当前值:`python src/cli.py stats`。下面正文里的数字属于当时那次实验的记录,不随刷新变化。
  7. ![检索页](docs/screenshot.png)
  8. **零第三方依赖**——只用 Python 标准库(`urllib`、`concurrent.futures`、手写的单文件网页和 stdio MCP 协议),
  9. 装个 Python 就能跑,不需要 `pip install`。需要 Python 3.9+,实测过 3.11 / 3.13 / 3.14。
  10. ## 一分钟上手
  11. **只想搜工具的话,双击仓库根目录的「打开雷达.cmd」。** 浏览器直接打开检索页,
  12. 6575 条随你搜。
  13. 不用装 Python、不用联网、不用起服务——网页里带着全部数据。macOS / Linux 双击
  14. `site/index.html`,或者 `open site/index.html`。
  15. 然后在搜索框里写你想干的事,不用想关键词:
  16. | 你可以这样写 | 结果 |
  17. |---|---|
  18. | `抓包` / `我想抓手机上的包` | mitmproxy、sniffnet、bettercap… |
  19. | `我要做一个后台管理系统` | mall、vue3-antdv-admin、RuoYi-Vue-Pro… |
  20. | `怎么把 PDF 转成文字` | Stirling-PDF、PDFMathTranslate、OCRmyPDF… |
  21. | `造点测试数据` | miragejs、mockserver、microcks… |
  22. 点卡片就打开它的 GitHub 页(国内产品打开官网)。名字旁边是星数、语言、最近更新;
  23. 下面那排彩色小标签可以点,点一下就切到那个场景,看同类还有什么。
  24. **搜不到时它会明说**「没有完全匹配的,下面按字面最接近的排」——那句话出现时,
  25. 结果只是沾边,换个更短的词更准。
  26. ## 快速开始(想自己跑数据的人看)
  27. ```bash
  28. git clone https://github.com/<your-name>/DevToolRadar.git
  29. cd DevToolRadar
  30. ```
  31. clone 完先跑一次刷新,索引和网页就有了:
  32. ```bash
  33. python src/refresh.py # 约 20-50 分钟;配了 token 约 5 分钟
  34. ```
  35. 之后 `site/index.html` 直接双击打开即可搜索——离线、零外部请求、不需要服务器。
  36. (索引和网页都是刷新的产物,不入库,原因见文末「哪些东西入库」。)
  37. 想要命令行:
  38. ```bash
  39. python src/cli.py find "造测试数据" # Windows 也可以直接双击 tool.cmd
  40. ./tool find "造测试数据" # macOS / Linux
  41. ```
  42. **想把数据刷新到当天**,跑一次完整抓取:
  43. ```bash
  44. python src/refresh.py # 三源全抓 → 打标 → 建站 → 自检,约 20-50 分钟
  45. python src/refresh.py --daily # 只抓 GitHub,awesome/cn 沿用上次缓存,约 15-25 分钟
  46. ```
  47. `--daily` 是给定时任务用的日常模式:awesome 的 12 个清单和国内 167 个站点是周/月级数据,
  48. 每天重抓纯属白费请求(这两块的数据变化速度比 GitHub 慢一个数量级)。跳过的源会读
  49. `data/raw_*.json` 沿用上次结果,索引条数不会因此变少,只是 `stats.json` 里记成 `skipped`。
  50. 建议每天 `--daily`、每周跑一次完整刷新。
  51. 第一次跑会重建全部三个源,速度卡在 GitHub 未认证限流(搜索 API 10 次/分钟)。
  52. 配个 token 能快 5 倍:
  53. ```bash
  54. export GITHUB_TOKEN=ghp_xxxx # Windows: setx GITHUB_TOKEN "ghp_xxxx"(重开终端生效)
  55. ```
  56. **只重建网页(改完 config 之后)**:
  57. ```bash
  58. python src/update.py --only-site # 约 1 秒
  59. python src/refresh.py --fast # 不联网,用 data/raw_*.json 重建,约 7 秒
  60. ```
  61. > `--fast` 需要 `data/raw_*.json`,那三个文件**不入库**(可重新抓取,且每天刷新会产生几 MB 的
  62. > diff)。刚 clone 下来没有它们,直接跑 `--fast` 会中止并提示你先跑完整刷新——这是故意的,
  63. > 没有缓存时重建会把几千条换成空索引。
  64. 抓取不发遥测、不写注册表、不装任何东西;除了 `data/`、`site/`、`logs/`,代码不往仓库外写文件。
  65. ## 怎么用
  66. 四种入口,共用同一份数据。同一个查询在哪儿搜都是同样的结果。
  67. ### 1. MCP —— 一次配置,所有 AI 客户端通用 ★
  68. 这是「换哪个大模型都能用」的正解。MCP(Model Context Protocol)是开放协议,
  69. 不绑任何厂商:Claude Desktop、Cursor、Cline、Windsurf、Continue、Codex CLI、
  70. VSCode Copilot、Zed 都支持。
  71. 配置一次之后,你在任何客户端里问「有没有能 mock 接口的工具」,模型都会主动查这个索引,
  72. 而不是凭记忆编。
  73. **配置方式**:把下面这段填进客户端的 MCP 配置,两处路径换成你自己的(绝对路径,用正斜杠):
  74. ```json
  75. {
  76. "mcpServers": {
  77. "devtoolradar": {
  78. "command": "python",
  79. "args": ["/absolute/path/to/DevToolRadar/src/mcp_server.py"]
  80. }
  81. }
  82. }
  83. ```
  84. `command` 写 `python` 也行——只要它在 PATH 上。路径不在 PATH 上就写完整路径,
  85. Windows 上是 `C:/Users/<you>/AppData/Local/Programs/Python/Python311/python.exe` 这种形式。
    • Warning: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 122 on GitHub
  86. **没有虚拟环境要激活,没有包要装**:`mcp_server.py` 只用标准库,手写了 stdio 上的 JSON-RPC 帧。
  87. 各客户端的配置文件位置:
  88. - **Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json`
  89. - **Codex CLI** — `~/.codex/config.toml` 的 `[mcp_servers.devtoolradar]`
  90. - **Cursor** — `~/.cursor/mcp.json`
  91. - **Cline / Roo Code**(VSCode 扩展)— 扩展设置里的 MCP Servers,或 `cline_mcp_settings.json`
  92. - **Windsurf** — `~/.codeium/windsurf/mcp_config.json`
  93. - **Continue** — `~/.continue/config.json` 的 `mcpServers`
  94. - **Zed** — `~/.config/zed/settings.json` 的 `context_servers`
  95. > VSCode 的格式略有不同:用 `"servers"` 而不是 `"mcpServers"`,且每项要加 `"type": "stdio"`。
  96. MCP server 提供五个工具:
  97. - `find_tool` — 自然语言查**一个**工具(支持 query / tag / source / chinese_only / limit)。
  98. 一句话命中多个能力位时,它会在结果末尾直接给出 `compose_stack(slots=[...])` 的建议
  99. - `compose_stack` — 一次查**多个能力位**:你自己把需求拆成 2-6 格(脚手架 / 登录鉴权 /
  100. 数据库 / 部署),它按格给候选、报缺口、跨格去重。用户说「我要做个 X」时用这个,
  101. 而不是只挑一个工具交差。slots 里也可以直接写用户原话,「美术设计」会自动展开成六格
  102. - `compare_tools` — 并排比两三个候选
  103. - `list_scenarios` — 全部能力位(当前 82 个,以输出为准),每个带一句话说明和当前最强的两条
  104. - `get_stats` — 数据总量与新鲜度
  105. **验证是否生效**:重启客户端后问两句——
  106. 「用什么工具能压缩图片」应该调 `find_tool`;「我想做个后台管理系统」应该调
  107. `compose_stack` 并分格给出脚手架/鉴权/存储/部署。两条都通,才算真的接上了。
  108. **之后改代码不用重启。** 服务每次处理请求前会比对 `src/*.py` 和 `config/*.json` 的
  109. mtime,变了就地重载(改配置、改检索逻辑、改工具实现都算)。只有装依赖或改启动方式
  110. 才需要重启。要验证这条能力还在,跑 `python tools/test_mcp_hotreload.py`——
  111. 它用两个探针做「改 → 变 → 改回 → 变回」,任何一步不动就 FAIL。
  112. > 热重载有三条静默失败路径,都实测踩过:`reload(__main__)` 抛 spec not found(reload
  113. > 内部会用 `_find_spec` 覆盖 `__spec__`)、`exec` 重进模块后监控基线被重置导致第二次
  114. > 改动被吃成新基线、没有启动闸时 `exec` 会重进 `main()` 抛 SystemExit。脚本就是守这个的。
  115. 配好之后跑一次 `python src/cli.py doctor`,第 4 项会去读这三个配置文件、检查里面写的
  116. python 路径和 `mcp_server.py` 路径**是不是真的存在**——换解释器、挪目录这类会让客户端
  117. 静默失效的改动,当场就能露出来。没装的客户端会被记为「跳过」,不算问题。
  118. ### 2. 网页(最常用)
  119. 双击 `site/index.html`,或者:
  120. ```bash
  121. python src/update.py --only-site # 重新生成后打开
  122. ```
  123. - 数据内联在 HTML 里,**不需要服务器,离线可用**
  124. - 可拖到浏览器书签栏,或「安装为应用」放到桌面
  125. - 快捷键:`/` 聚焦搜索、`j`/`k` 上下选择、`Enter` 打开、`Esc` 清空
  126. - 查询可以写进链接直接打开:`index.html?q=抓包`、`index.html?q=部署&tag=自托管`。
  127. 搜索结果能存书签、能发给人
  128. - 同名工具(`bun`、`tabby`、`goose`)名字旁边有灰底的 `owner/repo`,不然两行长得一样分不清
  129. ### 3. 命令行
  130. ```bash
  131. tool find "造测试数据" # 自然语言提问即可
  132. tool find -t "内网穿透" # 按场景列全量
  133. tool find "截图" -s cn -n 20 # 只看国内,返回 20 条
  134. tool compose 脚手架 登录鉴权 数据库 部署 # 一件事要几样东西配合时用这个
  135. tool compose 笔记 搜索 文档协作 -n 3 # 每格取 3 条
  136. tool tags # 看有哪些场景
  137. tool stats # 看数据总量和刷新状态
  138. tool open # 打开网页
  139. tool doctor # 自检:数据/MCP/客户端配置/网页 是否都还正常
  140. ```
  141. `tool` 只是个转接脚本,等价于 `python src/cli.py <命令>`。两个平台各有一份:
  142. | 平台 | 入口 | 用法 |
  143. |---|---|---|
  144. | Windows | `tool.cmd` | 双击,或把仓库目录加进 PATH 后用 `tool find ...` |
  145. | macOS / Linux | `tool`(带执行位) | `./tool find ...`;想要全局就 `ln -s "$PWD/tool" /usr/local/bin/tool` |
  146. **不想折腾 PATH**:`python src/cli.py find "造测试数据"` 一模一样的输出,任何平台都能跑。
  147. 想指定解释器(比如系统里有多个 Python):设环境变量 `DEVTOOLRADAR_PYTHON` 指向它,
  148. 两个入口都会优先用它。
  149. 把仓库目录加进 PATH(Windows):
  150. ```powershell
  151. $p = [Environment]::GetEnvironmentVariable("Path","User")
  152. [Environment]::SetEnvironmentVariable("Path", "$p;$PWD", "User")
  153. ```
  154. ### 4. 对话里直接问(仅 WorkBuddy)
  155. 已注册为 skill `dev-tool-radar`。作为 MCP 之外的兜底——万一某个客户端还没配 MCP,
  156. 在 WorkBuddy 里仍可直接问「找个能 mock 接口的工具」。
  157. ## 它凭什么准
  158. 难点不是「收集工具」,是「让『造数据』这种说法命中『接口 Mock』这个标签」。三层机制:
  159. **第一层:场景标签,不按技术栈**
  160. 82 个标签全部是「你要干什么」——接口 Mock、内网穿透、性能压测、抠图、截图录屏。不是 React / Python / Go。
  161. **第二层:口语 → 标签的别名表**
  162. 你问「造测试数据」「定时任务」「让外面访问我的本地服务」,配置里各标签的 `alias` 把这些说法翻译成场景。只取最长匹配,避免「本地大模型」同时命中「模型服务」和「大模型应用」。
  163. **第三层:中英术语映射**
  164. 根本矛盾是**你用中文问,GitHub 工具描述是英文**,字面匹配永远是 0,排序就只剩看 star。`config/terms.json` 把「压缩」展开成 compress/compression/minify,让真正做压缩的工具盖过 star 更多的 OCR 工具。多词短语用词袋判断,所以「抠图」能命中 desc 里写 `remove images background` 的 rembg。
  165. ## 检索质量怎么保证
  166. 打分是个牵一发动全身的东西:改一处权重,全库排名都动。所以有 `tools/eval_search.py`:
  167. 32 条固定查询,每条写明「哪些工具该出现在前 3」,跑一次给出命中率。
  168. ```
  169. python tools/eval_search.py # 30/32 = 93%
  170. python tools/eval_search.py -v # 逐条看实际结果
  171. ```
  172. **没有这个评测集,改打分就是碰运气。** 实测过一次:为了修「查我的 IP 搜出菜谱项目」,
  173. 第一版给所有英文词加了词边界,30 条查询里 16 条变差——`日志` 的第一名变成 `swift-log`,
  174. `docker` 丢掉 lazydocker,`k8s` 丢掉 k8sgpt。
  175. 现在的规则是分开的:
  176. - **名字用子串**:名字是标识符,复合词很正常(`ImgCompress`、`jsonhero`、`spdlog`)
  177. - **描述用词边界**:描述是自然语言,词是分好的。`diff` 不该命中 `different`,
  178. 否则整库一半条目都沾分,按 star 一排,第一名就是体量最大的不相干项目
  179. - **只对 2 字符的缩写强制边界**:`ip` 命中 `VoIP`、`os` 命中 `postgres` 是纯误伤,
  180. 但 `log` 命中 `logging` 是正常的词根匹配
  181. 另外两条规则是配套的:
  182. - **中文查询的「整串命中」降权**:中文描述里出现「对比」「限流」这两个字太容易
  183. (画图工具写「左右对比」、小红书运营工具写「限流自查」),而英文正牌工具只能靠
  184. 术语翻译拿六成分,不平权就是中文小工具站稳定压过正牌。所以中文整串命中名字只给
  185. 180(英文 260),命中描述不给整串分(仍算分词分)。
  186. - **术语展开取最长匹配**:查「数据库客户端」时,如果同时展开「数据库」→ database/sql,
  187. sqlmap(SQL 注入工具)会靠名字里的 sql 挤进前三。
  188. - **名字命中和标签命中不叠加(仅中文)**:两者说的是同一件事——「这条属于这个品类」。
  189. 叠加的后果是 ★3 的「草灰笔记」靠名字拿 180、靠标签再拿 305,搜「笔记」排第一。
  190. 英文查询不适用这条:用户打英文多半就是在点名,名字命中是独立证据。
  191. - **同义词表里不放品牌名**:「笔记」原来展开成 note / notes / notebook / **obsidian** /
  192. **logseq** / second brain。后果是任何提到 Obsidian 的插件、技能包、发版页都拿到
  193. 「笔记」相关分,搜「笔记」第一名成了 `claude-obsidian`(一个 Obsidian 插件,★16k)。
  194. 品牌名不是同义词,已剔除。
  195. **两端同源是要验的,不是要说的。** 网页是另一份 JS 实现,改完在 node 里把网页脚本
  196. 抽出来跑,逐条对比同一个查询下每条的分数:10 个查询 × 2784 个(查询,条目)组合,
  197. **不一致 0 处**。此前网页端少了「中文名字整串降权」「中文描述整串不给分」「星数加成」
  198. 三条规则——缺的后果是网页上 ★3 的工具能排第一,而命令行不是。
  199. 还剩 2 条没过:
  200. - **`k8s 管理`**:前六名全是「容器与 K8s」里的工具,按星数排,k9s 排第 7。品类对、顺序不理想。
  201. - **`笔记`**:前三名(vnote / note-gen / fsnotes)都是真笔记工具,但它们的名字里带 note,
  202. 因此拿到英文名命中分;joplin(★57k)排第 7。这条是「相关度优先于星数」这条设计原则的
  203. 直接后果,不是数据错误——想改就得重新定义这条原则,代价见下面「已知限制」。
  204. ## 数据完整性怎么保证
  205. 排序再好,条目不齐也没用。所以有两条独立的线:**有没有**、**齐不齐**。
  206. 一条命令看现状:
  207. ```bash
  208. python tools/audit_data.py # 说明、字段、场景各缺多少
  209. python tools/audit_data.py -d desc # 细看说明缺口
  210. python tools/find.py -e bun # 看单条的全部字段
  211. ```
  212. ### 说明:6575 条全都有,没有一条是空的
  213. 这件事不是自然发生的。有三类条目天生没有说明:
  214. **1. 作者就没写。** GitHub 仓库的 description 字段是 null,抓一万次也还是 null。
  215. `Unity-Technologies/EntityComponentSystemSamples`(8212 星)就是这种。这类只能人读 README 再写一句,
  216. 落在 `config/manual_desc.json`,按 URL 索引,无条件覆盖抓来的任何说明——这张表是人写的,
  217. 可信度天然高于自动摘要。目前 105 条。
  218. **2. 名字本身就是说明。** `sdras/awesome-actions` 整个列表都是这个形态,条目叫
  219. 「Deploy to Netlify」,说明就到此为止。66 条全是这样,只能逐条翻译成中文动作描述。
  220. **3. 中文说明比英文短,被长度比较判成「更短」。** 这个坑真踩过:
  221. 「自托管的碎片笔记应用…」35 个字,被原版英文 43 个字符判成「不如原文长」而不覆盖。
  222. 中英文按字符数比长度本来就没可比性,所以改成无条件覆盖。
  223. 另外,**同一段说明挂在两条上**也算不合格。`lxd` 和 `incus` 共用一句「Powerful system
  224. container and virtual machine manager」——因为 incus 是 lxd 的分叉,README 直接沿用了。
  225. 这类必须写清区别,否则用户看不出该选哪个。doctor 里有一条专门查这个。
  226. ### 下架:确认不是工具的直接剔掉
  227. awesome 列表是按「文章/资源」组织的,解析器只认 markdown 列表项,于是教程、面试题、
  228. 产品需求投票板全被抓了进来。查「React」冒出一篇官方教程,点进去发现不是工具——这比缺一条更伤。
  229. `config/drop.json` 是下架表,判定标准很严,不确定的一律不删:
  230. - 内容是讲解/教程/面试题/速查表,不是可运行的东西
  231. - 页面是需求投票板、反馈看板这类根本不是产品的东西
  232. - 页面是某个工具的官方文档片段,不是工具本身
  233. 已剔除 8 条。**`awesome-xxx` 这类清单仓库不在下架范围内**——它们虽然也是资源索引,
  234. 但确实指向一批工具,留着比删掉有用。
  235. ### 同名:95 组重名,197 条带上了 slug
  236. `bun` 既是 JS 运行时(oven-sh)又是 Go ORM(uptrace),`tabby` 既是终端又是 AI 编码助手,
  237. `goose` 有三条完全不同的东西(AI agent / 数据库迁移 / 压测)。列表里两行长得一模一样,
  238. 用户没法判断点哪个。
  239. 修法是在数据里算一次 slug(GitHub 用 `owner/repo`,其他站用域名),网页、CLI、MCP 三端
  240. 直接读同一个字段,不各自去猜。只在「slug 真的不同」时才标——同域名下的不同路径区分不了,
  241. 那类交给官网合并逻辑处理。
  242. 但「有 slug」和「该显示」是两件事:197 条里 138 条的 slug 尾段和名字一模一样
  243. (redis 的 slug 是 `redis/redis`、psf/requests 的 slug 是 `psf/requests`),
  244. 原样拼上去就是「redis redis/redis」,把名字写了两遍。所以显示前过一道判断:
  245. 尾段等于名字就不打,只有 `redis (redis/redis-py)`、`ollama (ollama/ollama-python)`
  246. 这种分得清的才显示。
  247. **顺便说一个没做的事**:`joplin` 的官网是 `joplinapp.org`、`micro` 是 `micro-editor.github.io`、
  248. `jenkins` 是 `jenkins-ci.org`,域名主体和工具名对不齐,所以官网条目和仓库条目没合并,两组都在。
  249. 试过放开成「域名主体以名字开头」,多合并 13 条,其中 4 条是错的:`sentinelguard.io`(阿里限流组件)
  250. 并进了 `cartalyst/sentinel`(PHP 权限库),`coralproject.net`(Vox Media 评论系统)并进了另一个 CORAL。
  251. 又试过加一道「两条说明得有共同词」的门槛,还是失败——两个无关项目都写 code / source,套话让判据失效。
  252. 结论是这件事规则做不了。宁可留两条重复(现在有 slug 能分清),也不能把两个真产品并成一个。
  253. ### 搬家:9 个换了组织/改了名的仓库,旧地址已并进新地址
  254. 这件事是被补星数引出来的。旧组织那半边原来 star=0,被质量分压在几千名下面,看不见;
  255. 星数补齐后两边同时浮上来——搜「终端」,`jwilm/alacritty` 和 `alacritty/alacritty`
  256. 并排第 2、3 名,说明还是两种措辞(「Cross-platform, GPU-accelerated…」/「A cross-platform,
  257. OpenGL…」),用户会当成两个工具。
  258. 判据只有一条是硬的:**GitHub 自己的 301**。仓库换组织或改名之后,旧地址会跳到新地址;
  259. `fetch_gh_meta.py --moved` 只探「名字看起来是同一个仓库」的组——包括去掉连字符后同名的
  260. (`oh-my-zsh` vs `ohmyzsh`,换组织的同时还改了名,第一批只按名字全等分组时漏掉了,两条并排
  261. 在搜「终端」的第三、四名)。58 组 128 个地址,一次 36 秒,把跳转记进 `data/gh_moved.json`,
  262. 归一化时按记录合并,留新地址那条。
  263. 星数接近、名字相同都不能当判据,试过就知道:`express-typescript` 有两条,星数 ★1247 和
  264. ★1259,仓库名一字不差,但它们确实是两个不同项目(edwinhern 和 GeekyAnts 各写了一个)。
  265. 只靠「像不像」去合,迟早把两个真产品并成一个。
  266. 合并时精选身份要保住:旧地址那条如果来自精选清单,`origin` 提上来(`[精选]` 标记和
  267. 5 分质量分都在它身上),名字、分类、人工说明也优先留人工写的那份——`Alacritty` 比
  268. `alacritty` 更像人写的。旧地址记进索引的 `moved_from` 字段,doctor 每次自检都反过来核对
  269. 「记录里的旧地址有没有真的并走」,记了 9 条就查 9 条。
  270. ## 打标签的那些坑(已处理)
  271. - **topic 滥用**:项目会为了被搜到而滥打热门 topic,一个仪表盘也标 docker/kubernetes。所以字段权重是 `名字 3.0 > 分类 1.5 > topics 1.35 > 描述 1.0`。
  272. - **"支持 docker 部署" ≠ "是容器工具"**:`容器与 K8s`、`部署托管`、`自托管`、`CI/CD`、`学习资源`、`工作流自动化` 六个标签标了 `weak`,判定阈值更严,且**已有业务归属的工具不再加这些标签**。这一条把容器类从 484 条收敛到 263 条。
  273. - **描述顺带一提不足以归类**:次要标签必须有名字/分类/topics 支撑。
  274. ## 目录
  275. ```
  276. DevToolRadar/
  277. ├── config/ ← 只改这里,不用碰代码
  278. │ ├── sources.json 抓哪些 GitHub topic、解析哪些 awesome 仓库、必收录白名单
  279. │ ├── scenarios.json 场景标签:kw 打标用、alias 翻译口语、weak 严判
  280. │ ├── terms.json 中英术语映射
  281. │ ├── why_map.json 清单栏目名 → 场景标签(栏目标是维护者分的,比作者自述可靠)
  282. │ ├── concepts.json 上位说法 → 一组能力位(「美术设计」横跨六格,不是一格)
  283. │ ├── ambiguous_kw.json 多义词:只认名字/topics,描述里出现只算「提到了」
  284. │ ├── tags_fallback.json 第四档兜底归属,规则全部沉默时才查
  285. │ ├── eval_queries.json 检索评测集:查询 → 该出现的工具
  286. │ ├── manual_tags.json 人工判读表:每条 URL 该归哪个场景(写 null = 确认无场景)
  287. │ ├── manual_desc.json 人工说明表:作者没写简介的条目,人补一句话
  288. │ ├── drop.json 下架表:确认不是工具的(教程、面试题、需求投票板)
  289. │ ├── topic_map.json 任务型 topic → 场景的显式映射
  290. │ └── cn_tools.json 国内工具种子清单(167 条,人工维护)
  291. ├── src/
  292. │ ├── refresh.py 刷新入口(抓取 → 打标 → 建站 → 自检,全程写日志)
  293. │ ├── update.py 刷新主体:抓源 + 归一化 + 建站
  294. │ ├── mcp_server.py MCP server(零依赖,stdio)← 跨客户端通用
  295. │ ├── fetch_github.py GitHub Search API + 必收录白名单
  296. │ ├── fetch_awesome.py awesome README 解析(含阮一峰周刊)
  297. │ ├── fetch_cn.py 国内清单 + 官网存活校验
  298. │ ├── normalize.py 去重、打标、质量分 —— 系统的心脏
  299. │ ├── build_site.py 生成单文件检索页
  300. │ ├── search.py 检索核心(CLI/MCP/skill 共用)
  301. │ └── cli.py 命令行入口
  302. ├── data/
  303. │ ├── tools.json 归一化后的索引(当前 6575 条)
  304. │ ├── stats.json 刷新时间、各源状态、分布统计
  305. │ └── raw_*.json 各源原始落盘(单源故障时的回退)
  306. ├── tools/
  307. │ ├── eval_search.py 检索评测:跑固定查询集,看期望工具在不在前 3
  308. │ ├── audit_data.py 数据体检:说明、字段、场景各缺多少,一条命令看清
  309. │ └── find.py 按名字精确找一条,看它的全部字段
  310. ├── site/index.html 检索网页(单文件,约 1.3 MB)
  311. ├── docs/screenshot.png README 用的截图
  312. ├── logs/ 刷新日志(refresh.log 追加式,update-YYYY-MM.log 按月,不入库)
  313. ├── tool / tool.cmd 命令行入口(POSIX / Windows)
  314. ├── refresh / refresh.cmd 手动刷新(内部调 src/refresh.py)
  315. ├── LICENSE MIT
  316. └── .gitignore
  317. ```
  318. **哪些东西入库**:代码、`config/`、`docs/`、少量低频变动的元数据缓存。
  319. **哪些不入库**:`data/tools.json`(索引本体,约 2.5 MB)、`site/index.html`(约 1.8 MB)、
  320. `data/raw_*.json`(抓取中间产物)、`logs/`、`data/health.json`、`data/.cache/`。
  321. 后两个大文件不入库是 2026-11-19 改的。它们每天刷新都会变,而 git 存的是版本不是快照:
  322. 入库 33 个提交就已经攒下 24 个 `index.html` 版本和 18 个 `tools.json` 版本,合计约 72 MB
  323. 原始对象、26 MB 仓库体积,且只会继续变大。
  324. 所以 clone 下来**没有索引**,第一次 `./tool find` 会提示「还没有数据,已在后台开始首次抓取」
  325. 并自动跑一次刷新(15-50 分钟,取决于有没有配 token)。也可以自己先跑
  326. `python src/refresh.py`。
  327. ## 更新机制
  328. 三个触发点,最后都汇到同一个脚本 `src/refresh.py`:抓取 → 补 GitHub 元数据 / 查仓库搬家 → 打标 → 建站 → 自检。
  329. **自动:** 不需要什么框架,任何能定时跑命令的东西指向 `python src/refresh.py` 就行:
  330. ```bash
  331. # Linux / macOS:crontab -e
  332. 0 3 * * * cd /path/to/DevToolRadar && ./refresh >> logs/cron.log 2>&1
  333. ```
  334. - **Windows** — 任务计划程序,操作填 `python`,参数 `src\refresh.py`,起始于仓库目录。
  335. 如果 `schtasks` 被安全软件拦住了,用图形界面建同样的任务即可。
  336. - **GitHub Actions** — 可行,但要把 `data/` 提交回仓库,得给 workflow 写权限;
  337. 每天的自动提交会让提交历史变得很吵,是否值得自己权衡。
  338. **自愈:** 每次用 `tool` 查东西时会检查数据新鲜度,超过 3 天自动在后台起一次 `refresh.py`,不阻塞你的查询。输出丢给 DEVNULL,但过程照样写进 `logs/refresh.log`。
  339. **自检:** 抓完自动跑一次 `tool doctor`,结论写进 `data/health.json`。没过的话,`tool find` 开头会直接提示,MCP 的 `get_stats` 也会带一句——不需要你记得去翻日志。
  340. ```bash
  341. tool doctor # 22 项:数据新鲜度 / 索引完整性 / 说明覆盖率 / MCP 握手 / 三个客户端配置 / 网页同步 / 检索冒烟
  342. ```
  343. 检查的是「配置指向的文件真的存在」而不是「字符串跟这边一样」,所以换解释器、挪目录这类会让客户端静默失效的改动会当场露出来。
  344. **手动:**
  345. ```bash
  346. python src/refresh.py # 完整刷新 + 自检,约 20-50 分钟(每周一次)
  347. python src/refresh.py --daily # 只抓 GitHub,awesome/cn 沿用缓存,约 15-25 分钟(每天)
  348. python src/refresh.py --fast # 不联网,用缓存重建,约 7 秒(改完 config 用这个)
  349. ```
  350. 双击 `refresh.cmd` 等价于第一条。日志头部会写 `mode: full / daily / fast`,「awesome 是 skipped」到底是本次轻量模式的设计还是抓取失败,看这一行就能分清。每次运行都往 `logs/refresh.log` 追加一段,含 python 路径、工作目录、每一步的退出码和耗时,输出是流式的——跑一半卡住也能看出卡在哪。
  351. **为什么不用 `update.py` 直接跑**:它只负责抓数据和建站,不跑自检。以前三个触发点都只调它,于是 `health.json` 永远是旧的,坏了也没人知道。`refresh.py` 是唯一入口,这条缝已经堵上。
  352. **部分更新:**
  353. ```bash
  354. python src/update.py --no-github # 只更 awesome + 国内(约 40 秒)
  355. python src/update.py --only-site # 只重新生成网页(1 秒)
  356. python src/update.py --no-cn # 不动国内清单
  357. ```
  358. **抓取失败不会毁掉索引**,三道防线:
  359. 1. **单源回退**:某个源这次抓挂了,沿用 `data/raw_*.json` 里上次的结果,`stats.json` 里标 `cached`。
  360. 这一条原来只对整个 `awesome` 生效——它下面挂了 12 个列表,失败 2、3 个时总数照样非零,
  361. 回退不触发,那几百条就被静默删掉了。2026-11-03 真发生过:`awesome-vscode`(SSL 全断)、
  362. `terminals-are-sexy`(403)、`awesome-cli-apps` 三个源失败,索引从 5417 掉到 5152,
  363. 而自检全绿。现在回退按**源**粒度走,失败的那个列表用它上次落盘的条目顶上。
  364. 2. **骤降拒写**:归一化后的总数比上一版少 10% 以上,判定为抓取故障,**不写盘**、返回退出码 3,
  365. 保留上一版索引等人来看日志。正常日间波动在 1% 以内,10% 只可能是大面积失败。
  366. 3. **自检**:`doctor` 把结论写进 `data/health.json`,`tool find` 开头和 MCP 的 `get_stats` 都会带一句。
  367. ## 想加工具 / 加场景
  368. **加一个国内产品**:往 `config/cn_tools.json` 的 `tools` 里加一条,`tags` 用 `scenarios.json` 里的标签名。
  369. **加一个新的"你想干什么"**:往 `config/scenarios.json` 加:
  370. ```json
  371. {
  372. "label": "视频转码",
  373. "desc": "格式转换、压缩、加水印",
  374. "kw": ["transcode", "video conversion", "转码"],
  375. "alias": ["视频转码", "转格式", "压缩视频"]
  376. }
  377. ```
  378. `kw` 用于给工具打标签,`alias` 用于理解你的问法。改完跑一次 `python src/update.py`。
  379. **加一批 GitHub 仓库**:`config/sources.json` 的 `github.queries` 加 topic;如果某个核心工具怎么都搜不到,加到 `pinned.repos` 白名单。白名单不是可有可无的补充,是主力:2026-11-04 那次刷新里,73 个白名单仓库中有 **40 个** 不在任何一次 topic 检索结果里(`llama.cpp`、`Fabric`、`electron` 本体都是靠白名单才进来的)。topic 检索适合捞「一大片相似的东西」,白名单负责「少一个都不行」的那批。
  380. **补「工具自己标了功能、但没被收进来」的场景**:`config/topic_map.json`。GitHub 的 topics 多数是技术栈(python/docker/cli),但有一批词说的就是功能本身(`image-processing`、`text-to-speech`、`note-taking`),这张表把这类 topic 映射到场景。约束是只补空——已有标签的条目一律不碰,所以是纯增量。加新键前先按注释里的验收方法抽查,`tunnel`、`mock`、`web-scraping` 三个键就是抽查后删掉的。
  381. **人工判定某个工具的归属**:`config/manual_tags.json`。按 URL 索引,值写场景名;写 `null` 表示「确认它不属于任何场景」。**这张表的优先级高于任何规则**——有值时用人工结论,`null` 时清空规则结果,没记录才走规则。什么时候用它:作者的自述用的是词表里没有的说法(jq 说自己是「JSON processor」、pandoc 说自己是「markup converter」),规则匹配不到,人读一眼就知道;反过来,规则把「名字带 log 但不是日志系统」的东西捞错了(TeslaMate、Wavelog),也靠它否决。这个文件不参与自动更新,新的高星无标签项目需要人工追加——跑 `python src/refresh.py --fast` 会打印「人工判读表:补标签 N 条,确认无场景 M 条」。
  382. **人工补一条说明**:`config/manual_desc.json`。按 URL 索引,值是中文说明,**无条件覆盖**抓来的任何描述。什么时候用它:作者压根没写 description(GitHub 上是 null,抓不到)、或者说明是营销口号(`vercel` 写「Develop. Preview. Ship.」)、或者干脆是公告(`BookStack` 写「NOW MANAGED ON CODEBERG」)、或者只是把名字换个写法又说了一遍(`mongo` 写「The MongoDB Database」)。写的时候说清「它是什么 + 用来干什么」,别复述名字。改完跑 `python src/update.py --no-github --no-awesome --no-cn`,日志会打印「人工说明表:补写 N 条」。
  383. **下架一个不是工具的条目**:`config/drop.json`。教程、面试题、需求投票板、某个工具的文档片段——这些被抓进来只会污染检索。判定标准见文件头的注释,很严,不确定就别加。
  384. **检查补得对不对**:`python tools/audit_data.py` 看缺多少,`python tools/find.py -e 名字` 看单条。`tool doctor` 里也有三项守着:说明覆盖率、说明重复、人工表是否对得上索引。
  385. ## 已知限制
  386. - **兜底检索只看字面,理解不了所有说法**。主判定(词表 + 场景翻译)一条都没命中时,会退到
  387. 「按字面最接近」:把查询拆成相邻二字词和单字、按稀有度加权比对整条记录,再拿 82 个场景名
  388. 做一层意图推断(「我想抓手机上的包」→ 拆成 抓/手/机/包 → 场景名「抓包代理」同时含「抓」「包」)。
  389. 12 条口语问法实测都能给出可用的前 3 条,但它不懂「帮我搞定证书」是要 Let's Encrypt 客户端。
  390. 结果上方出现「没有完全匹配的」那行灰字时,就是这套在兜底。
  391. - **零件还是不够细**。`桌面应用开发` 这一格已经建起来了(50 条,Electron / Tauri / Wails / PyQt /
  392. Nuitka / PyInstaller / electron-builder 都在,见下一条),但它只覆盖「用什么写、怎么打包」,
  393. 不覆盖「托盘图标、自动更新、代码签名」这类具体能力——问「客户端怎么自动更新」仍然没有对应场景。
  394. 另外 `topic:electron` 那 334 个仓库(绝大多数是「用 Electron 做出来的成品」)故意没抓:
  395. 加进来只会让这一格从「零件」再次混成「成品」,而那批东西 `桌面与系统工具` 已经在装了。
  396. - **`构建打包` 还是只装前端打包器**:vite ★84k、webpack ★66k、esbuild 在这格,而单文件打包
  397. (PyInstaller ★13k、Nuitka ★15k、auto-py-to-exe ★5.0k、pyfuze、nexe)归到了 `桌面应用开发`。
  398. 没给它们单开一格,是因为「把 Python 打成 exe」本来就是桌面程序交付的最后一步,拆走会把
  399. pyinstaller 从「写桌面程序」那一格里拔出来。代价是 `构建打包` 这个词仍然歧义:
  400. 问「打包成 exe」现在能落到 exe 那批(走别名),问「打包」还是优先给前端打包器。
  401. - **泛词查询的排序一般**:问「部署」,前几条是 terraform、jhipster 这类描述里频繁出现「部署」
  402. 的项目,而不是 dokploy、coolify 这些部署平台本体;问「部署托管」这个场景名才准。原因是
  403. 「部署」在几十条描述里都是顺带一提,分档区分不开,同档里就按星数排了。这类属于
  404. 「顺序不理想、领域正确」,没动主判定——动它会把 32 条评测里已经对的那些挤掉。
  405. - **GitHub 未认证限流**:全量刷新约 10 分钟(搜索 API 10 请求/分钟)。配一个 token 能提速 5 倍并把覆盖抓得更深:
  406. ```powershell
  407. setx GITHUB_TOKEN "ghp_xxxx" # 新开终端生效
  408. ```
  409. - **awesome 条目丢弃率约 52%**:无法归入任何场景的条目会被丢掉(2600 条左右)。这是刻意的——没有 star 背书又没有场景归属的条目,对"找工具"没价值。
  410. - **还有 1.7%(90 条)缺场景归属,全部是人工读过、确认不归任何场景的**:这类条目描述里没有出现任何场景词汇,或者只出现在长描述末尾的「我还支持 X」清单里。后者用「命中词在描述前 90 字内」区分定位句和支持清单,能救回 fzf、plane、AFFiNE、crewAI 这类把定位句写在开头、后面拖一串用途的项目;但代价是个别误判会浮上来(问「漏洞扫描」时 ECC 排第一,它其实是 agent 工具)。
  411. 剩下这批里,多数条目的 topics 其实指向正确场景,只是描述里没出现关键词而被整条弃用(body 过滤器)。这类证据不参与主判定(一放行就重演连锁改判),只在「完全无标签」时兜底补一个:要求同一场景至少命中 2 个 topic;数据库/认证鉴权/监控告警/部署托管/自托管/性能压测这 6 个「人人能沾」的场景提高到 3 个。
  412. 最后一档是 `config/manual_tags.json`,五批读完 868 条,表里最终留 614 条结论:518 条补上场景,96 条写 `null` 确认「本来就没有场景」(这 96 条里有 6 条在合并同产品重复入口时被吞掉,所以数据里实际剩 90 条无场景,第六批又从中收走 it-tools,现在 89 条)。第一批 52 条是 3 万星以上仍无归属的;第二批 52 条是「规则差一点」的(命中了但只有一个词沾边、分数 1.0,被单次命中过滤挡在门外);第三批 559 条是规则完全够不到的——一个关键词都匹配不到,因为类目不在当时的 52 个场景里。
  413. 能补上的是因为作者自述用的是词表外的说法:jq 写「Command-line JSON processor」、pandoc 写「Universal markup converter」、bubbletea 写「TUI framework」;mikro-orm 的「数据库」其实拿了 5.0 分、命中 5 个词,但全在 topics 里,正文一个都没出现,于是被「只靠 topics 不算数」的规则整条弃用——人读一眼就知道它是 ORM。第三批里同类情况很多:ORM(ent / efcore / Exposed / PetaPoco / nhibernate)、接口 Mock(nock / mockk / miragejs / ng-mocks / Cuckoo / mockolo)、消息队列(bull / liftbridge / Rebus / blazingmq / sqs-consumer)、代理客户端(ClashMac / mieru / GreenTunnel / glider)、测试框架(jasmine / Quick / doctest / spock / TUnit / tox)。
  414. 确认为空的包括 vscode / lapce(编辑器本体,场景里的「编辑器插件」指插件)、node / deno(语言运行时)、django(Web 框架)、nhost / trailbase(Firebase 替代,没有「后端服务」这一类)、以及 CMS、加密货币、生物信息、DNS 服务器、静态站点生成器、各类语言/框架运行时这些没有对应类目的项目。表里记为 `null` 的表示「读过了、确认不归任何场景」。
  415. 第四批 80 条是「开了新类目才有地方去」的:补了 14 个场景(Web 框架、CMS 与建站、代码生成、包管理与仓库、
  416. 调试与剖析、对象存储、数据分析与实验、编译器与虚拟机、代码编辑器、语言运行时、区块链、CRM 与 ERP、
  417. Markdown 处理、桌面与系统工具),一次性收进 300 多条,无标签从 267 降到 207,剩下 80 条逐条读完。
  418. 第五批 125 条是收尾:38 条归进现有场景(服务发现 Consul、防火墙 OPNsense、Windows 兼容层 winapps / winboat、
  419. BaaS nhost / trailbase / floci、容器底层 CRIU / toolbox / dragonfly、多平台发布 Wechatsync 这类之前散在外面的),
  420. 88 条判 `null`。判空的几乎全是「库 / 零件 / SDK」——HTTP 客户端(got、wretch、mande、pycurl、dart-lang/http、
  421. node-fetch、async-http-client、fuel、beast、gun)、各家 API 的官方封装(notion-sdk-js、ruby-openai、binance、
  422. Mastodon.py、pyowm、wechatpay-go、huggingface.js、两个 Firebase SDK)、单点小库(DOMPurify、valtio、click、
  423. go-cmp、easyjson、tsdoc)。这些是「装进项目里的零件」,不是「拿来就用的工具」——按场景浏览时出现只会稀释列表,
  424. 所以不建类目、也不硬塞。
  425. 第六批 10 条是那次「能不能生成 uuid」的问诊引出的:这类工具是「一堆小工具的合集」,
  426. 天生没有场景可归,于是中文查询永远落不到它身上(中文问法要先翻成场景标签)。为此补了第 68 个场景
  427. `开发者工具箱`,收 it-tools(41k)、DevToys(32k)、omni-tools(11k) 等 10 条,
  428. 并在 alias 里挂了 uuid / 正则 / base64 / 哈希 / 时间戳 / json 格式化 这些具体功能词。
  429. 现在问「uuid」直接出 it-tools,问「正则」出的是在线工具箱而不是空白。
  430. - **第 53 个场景「日志与追踪」是后补的**:前三轮读下来发现日志类无处可去,spdlog(29.7k)、logrus(25.7k)、zap(24.6k)、loguru(24.1k) 四个 2-3 万星的项目全悬空,因为 52 个场景里没有「日志」。补上之后一次收进 42 条(全是日志库/日志平台),另改判 14 条(kail、kubetail、khi、logging-operator 这类 K8s 日志工具从「容器与 K8s」移到日志场景更准)。
  431. 开新场景的代价要正视:`logging`、`logger` 这类词的语义太宽——**「记录数据的软件」全都符合**。实测捞进过 TeslaMate(特斯拉车辆数据记录)、Wavelog(业余无线电通联日志)、wger(健身记录)、gpslogger(GPS 轨迹)、SignalTo(交易信号转发)。这批已在人工表里逐个否决,并因此改了代码:人工表的否决权现在**压过规则**,不再只在规则沉默时才有话语权。否则新场景每加一个词,都会带进来一批「名字带 log、但不是日志系统」的东西。
  432. - **后补的 14 个场景,有三个是在「词太泛」上翻过车的**:第一版叫「运行时与编译器」,`runtime` 把 bun(运行时)、herdr(agent runtime)、ray(AI 计算引擎)、tamagui(UI 库)、falco(运行时安全)全捞进来,改成「编译器与虚拟机」并删掉 `runtime` 才干净;「数据分析与 Notebook」的 `notebook` 把纸质笔记本 PDF 生成器、dnote(笔记应用)也收进来了,改叫「数据分析与实验」,只留 `jupyter` / `experiment tracking` / `feature store`;「代码生成」的 `boilerplate` 把 SaaS-Boilerplate、vuesion 这类启动模板源码当成了代码生成器。教训是**别用能描述「一类东西的形态」的词做关键词**,只用描述「功能」的词。
  433. - **2 字符缩写会命中别的单词内部**:查「查我的 IP」时 `ip` 会命中 `VoIP`(Vo-IP)和 `Recipes`(rec-ip-es),
  434. 结果第一名是一个 SIP 监控工具和一个菜谱项目;`os` 会命中 `postgres`。修法是**只对 2 字符的英文词要求词边界**,
  435. 3 字符以上仍按子串——因为 `log` 必须能命中 `spdlog`/`logrus`,`k8s` 要命中 `k8sgpt`,`json` 要命中 `jsonhero`,
  436. `docker` 要命中 `lazydocker`。全上词边界会让「日志」的第一名变成 `swift-log`(实测)。
  437. 改完 30 条查询里只有「查我的 IP」变了,其余 29 条逐条一致,没有副作用。
  438. 网页端是另一份 JS 实现(`build_site.py` 里的 `score()`),这条规则两边都改了。
  439. **注意:当时两边并不真的完全一致**——JS 少了三条中文规则和星数加成,这个洞直到 2026-10-30
  440. 才补上并逐条核对(见「检索质量怎么保证」里 2784 个组合 0 差异那段)。凡是改打分,两端都要验。
  441. - **「工具箱」这类目,kw 一个都不能信**:实测 `toolbox` 会吸进 mcp-toolbox(数据库 MCP)、ImageToolbox(图片编辑)、
  442. lemo-opuscar(大模型素材);`utilities` 吸进 enzyme、react-testing-library(都是测试工具);中文 `工具箱` 吸进
  443. PDF补丁丁、这图能改、匠工具箱——全是「专用工具箱」,不是「开发者日常小工具合集」。所以这个场景只在 kw 里留了
  444. `online tools`(全库只命中 it-tools 和它的 fork,干净),成员**全部由人工表列**,没让规则猜。
  445. 顺带发现库里缺了 CyberChef(编码解码事实标准),已加进 `sources.json` 的 `pinned.repos`,下次抓取进来。
  446. - **`语言运行时` 只有 3 条(node / deno / bun),是全库最窄的场景**:留着是因为它答的问题是「我想跑 JS,用哪个」,这三条就是全部答案,硬塞别的反而错。`bun` 同时是打包器、测试器和包管理器,这里按它的头号身份归到运行时。
  447. - **国内清单靠人工**:167 条是国内 SaaS/AI,没有可枚举的公开 API,只能人工维护 + 每次探活。探活失败的会标「站点不可达」但仍保留(可能是临时故障)。
  448. - **同名不同物不会被合并,但会带上标识**:`tabby` 既是终端也是 AI 编码器,`bun` 既是运行时也是 ORM,`ollama` 官方仓库和 Python 客户端也是两回事。只有真能证明是同一个东西的才合并成一条:name 和 desc 完全相同(项目换组织留下的双份,v2ray→v2fly、ginuerzh/gost→go-gost,2 组),或者 GitHub 把旧地址 301 到新地址(9 组,见上一节)。全库共 11 组。
  449. 剩下 95 组重名不合并(合并会把两个真产品并成一个),改在名字旁边显示 `owner/repo`,让人能分清。只在 slug 真的不同时才标,同域名下不同路径区分不了。
  450. - **`lang` 缺 44.5%、`pushed_at` 缺 24.3%,两个字段的处境完全不同**:
  451. | 字段 | GitHub 源(3110 条) | 精选清单源(2149 条) | 国内源(167 条) |
  452. |---|---|---|---|
  453. | `lang` | 缺 4.1% | 缺 99.5% | 缺 85.6% |
  454. | `pushed_at` | 缺 0% | 缺 55.5% | 缺 75.4% |
  455. `pushed_at` 原来是缺 42%,这一轮补到 24.3%:`fetch_gh_meta.py` 用 ungh 代理把精选清单里
  456. 1001 个 GitHub 仓库的星数、更新时间补了一遍(一次跑完 943 条,失败 0)。剩下 1192 条是
  457. 官网 / App Store / Chrome 商店,这些页面没有「最后一次提交」这个概念。
  458. `lang` 补不动:ungh 代理的返回里根本没有 `language` 字段;GitHub 仓库页面的语言区块是
  459. React 骨架屏,HTML 里拿不到实际值;只剩 GitHub API 一条路,而无 token 只有 60 次/小时。
  460. 剩下 1129 条按星数降序排进每日刷新。2026-11-19 起这 60 次不再全给 language:预留 40 次
  461. 给必收录抓取(`--reserve-core 40`),每天补 20 条,约 50 天补完 —— 语言标签只是展示字段,
  462. 优先级低于「工具本身在不在库里」。
  463. 补元数据的直接后果是**排序整体变了**,不是补信息:当时 5426 条里 5405 条发生位移,718 条位移
  464. 超过 1000 名。上升最猛的是原本被当成 0 星的:`oh-my-zsh`(19 万星)从 5331 名到 23 名,
  465. `Terminus`(7.5 万星)从 5377 到 32 —— 19 万星排 5331 名本身就是荒谬的。
  466. 检索评测从 87% 升到 93%,「文件同步」「shell 美化」两条自己就好了。
  467. - **泛类词仍按「名字贴合度」优先于星数**:搜「笔记」,前三名是 vnote / note-gen / fsnotes
  468. (★7.5k–13k),joplin(★57k)第 7。这不是数据错误,是设计取向的直接后果:`score()` 里
  469. 星数只是最多 120 分的微调,而「名字里含这个词」值 62 分,刚好能跨一个 100 分的档。
  470. 想把星数抬上去只有两个旋钮,两个都试过、都赔:
  471. - 放宽档位到 150/180:评测从 30 掉到 25/24(终端、容器、去广告、压缩图片一起坏)
  472. - 去掉名字命中的分(或降到 30):掉到 22–25,`压缩图片`、`向量检索`、`代码格式化` 全塌
  473. 根子在于这两条路都是在改「相关度优先于影响力」这个全局原则,不是修某个局部错误。
  474. 要动它得先决定产品取向:泛类词到底是「按品类热度排」还是「按命名贴合度排」,两者不能兼得。
  475. - **评测集自己也不自洽,只能看趋势,不能当唯一裁判**:`终端` 期望 alacritty / kitty 进前三,
  476. 而它们能进前三靠的恰恰是名字里含 `tty`——和 `vnote` 里含 `note` 是同一种字母巧合。
  477. 同一类证据,在一个查询里是期望答案,在另一个查询里是噪声。所以别拿 32 条去换一个
  478. 「调参调绿」,那只会把错误挪个位置。
  479. - **`category` 缺失 53.5%,但它不是问题**:这个字段在网页里只参与算分、**从不展示**,CLI 和 MCP
  480. 完全不读它。它只是打标的第二高权重证据(1.5,仅次于名字的 3.0)。GitHub 源没有它,靠 name、
  481. topics、desc 三个证据照样能打准。把它当「缺字段」是错的口径。
  482. - **90 条无场景不是缺失,是结论**:其中 89 条是人工逐条读过后明确写 `null` 的(「读过了,
  483. 确认不属于任何场景」),1 条是补说明后标签归空、已补记。这批里多数是「库」而不是「工具」——
  484. xstate(状态机)、click(CLI 库)、got(HTTP 客户端)、DOMPurify(XSS 过滤)是装进项目里的零件。
  485. 场景表按「你想干什么」设计,没有「基础库」这个类目,硬建一个只会把列表稀释掉。
  486. 它们照样能被搜到,只是不出现在场景导航里。
  487. - **「学习资源」原来是收容所,2026-11-03 逐条清过一遍**。病根是场景词表里的两个泛词:
  488. 「学习资源」的 `learn` 和 `awesome`,在 awesome 清单的分类名里子串命中——
  489. 分类叫 `Machine Learning` 的(`pytorch`、`keras`、`jax`、`xgboost`、`optuna`)变成「学习」,
  490. 分类叫 `React Awesome Components` 的(`swiper` 这类组件)变成「学习资源」。
  491. 当时 220 条的唯一标签是它,混着一大堆库和组件。
  492. 处理方式是把这 220 条逐条读完,按「这个工具被用来干什么」判到现有场景,一条一个:
  493. | 去向 | 条数 | 例子 |
  494. |---|---|---|
  495. | 模型服务 | 9 | `pytorch`、`tensorflow`、`keras`、`jax`、`transformers`、`pytorch-lightning` |
  496. | 数据分析与实验 | 16 | `scikit-learn`、`xgboost`、`optuna`、`sktime`、`statsforecast`、`Netron` |
  497. | 前端 UI | 22 | `swiper`、`react-select`、`taiga-ui`、`vue-i18n`、`react-big-calendar` |
  498. | 终端增强 | 10 | `tldr`、`navi`、`cheat`、`autojump`、`z.lua`、`howdoi`、`explainshell` |
  499. | CI/CD | 5 | ML 流水线动作、`cml` |
  500. | 其他 | 13 | `mockey`/`respx`→单元测试、`autopep8`→代码质量、`grobid`→PDF、`letta`→大模型应用… |
  501. 改判 75 条,剩下的 145 条确实是教程、路线图、awesome 清单、速查表、面试题、技术媒体,保持原样。
  502. **根因有两个,修掉了一个。**
  503. 已修(2026-11-03):`category` 不再给「学习资源」作证。章节标题说的是「这条被归在清单的哪一节」,
  504. 不是「这个工具是干什么用的」——`Machine Learning`、`Command Line Learning`、`React Tutorials`
  505. 这三节把整节内容判成教程,就是这么来的。开关在 `src/normalize.py` 的 `NO_CATEGORY_LABELS`,
  506. 按「哪个场景不该读 category」声明,不写死在算法里。
  507. | 方案 | 结果 | 结论 |
  508. |---|---|---|
  509. | 把 `learn` 改成整词匹配 | 少 30 条,`pytorch` 自己掉标签 | 不可取 |
  510. | 整词 + 高星无场景条目保留 | 5426 条,但产出 102 条无场景条目 | 要为它们另写一套显示逻辑,收益不抵 |
  511. | **只让该场景不读 category** | **5426 → 5425,其余条目标签改动 0** | 采用 |
  512. 最后一行是隔离实测:只改这一个变量、并把那唯一受影响条目的人工记录摘掉后重跑全库,
  513. 差异只有 `bulletproof-react`(React 参考架构,确实偏教学,已在人工表里补上归属)。
  514. 未修:`learn` 这个词本身。它同时也是 `learning` 的词根,**删不得**——实测删掉只少 4 条,
  515. 但会让 16 条改判,其中 8 条真教程(`learn-go-with-tests`、`machine-learning-zoomcamp`、
  516. `90DaysOfDevOps`、`ml-retreat`、`professional-programming`)变成无场景,在场景导航里直接消失。
  517. `awesome` 同理,删掉会打掉一堆真的 awesome 清单。
  518. 所以剩下的一半仍是人工活:名字或描述里恰好带 `learning` 的库,靠 `config/manual_tags.json` 纠。
  519. 规则负责覆盖量,人工表负责纠错,两者不互相冒充。清完这一轮抽查过:145 条唯一标签是
  520. 「学习资源」的条目里,名字触发的 11 条、描述触发的 96 条(去重前),逐条看下去全是清单、
  521. 课程、手册、速查表,没有库混在里面。
  522. - **网页已经过截图验证**:无头 Chrome `--headless=new --screenshot` 可用,注意 `--screenshot=` 必须给
  523. Windows 绝对路径,相对路径会报「拒绝访问 0x5」。
  524. ## 想贡献
  525. 这个仓库的价值一半在代码,一半在 `config/` 里那几张人工表——它们不需要写代码就能改,
  526. 而且比改算法安全(规则动一处,全库排名都动;表加一行,只影响那一行)。
  527. - **补一个工具的场景归属** → `config/manual_tags.json`,按 URL 索引,写 `null` 表示「读过了,确认不属于任何场景」
  528. - **补一条说明** → `config/manual_desc.json`,无条件覆盖抓来的描述
  529. - **加一个国内产品** → `config/cn_tools.json`
  530. - **加一个「你想干什么」** → `config/scenarios.json`,`kw` 用于打标、`alias` 用于理解问法
  531. - **下架一个不是工具的东西** → `config/drop.json`
  532. 改完跑 `python tools/audit_data.py` 看缺多少,`python src/cli.py doctor` 看有没有破规则。
  533. **动打分之前先跑评测**:`python tools/eval_search.py`(当前 30/32 = 93%)。
  534. 改一处权重,全库排名都动——没有评测集,改打分就是碰运气。而且**两端都要验**:
  535. 网页里是另一份 JS 实现(`build_site.py` 的 `score()`),改完得逐条对比。
  536. ## 许可
  537. MIT,见 `LICENSE`。工具元数据来自各项目的公开信息(GitHub API、awesome 清单、
  538. 各产品官网),版权归各自所有者。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.