快速上手

本指南带你从全新的检出开始，运行起带有你自己排名的 Web 应用，并演示如何查询它的 HTTP API。本指南描述的是 0.1.2 版本。架构指南解释了每一步的作用。

前置条件

Python 3
moonc 0.10 或更高版本的 MoonBit 工具链
Node.js 20.16、22.3 或更高版本，以及 npm
~/.moon/registry/index/user 下的本地 MoonBit 注册表快照；moon update 会创建或刷新它

1. 构建数据库

先构建为包评分的 cli 命令，再在启用 mooncakes 实时下载量查询的情况下构建数据库：

moon update
moon build src/cli --target js
python3 scripts/build_index.py --db data/mooncake.db

这个命令会：

读取本地注册表下的所有 *.index 记录
从头重建 SQLite schema
在未禁用时从 mooncakes 拉取缺失的下载量
计算包之间的边、反向依赖计数、分数快照（通过 MoonBit cli 命令）以及 FTS 索引

不访问 mooncakes、离线构建：

python3 scripts/build_index.py --db data/mooncake.db --skip-mooncakes-downloads

叠加本地下载量覆盖文件：

python3 scripts/build_index.py \
  --db data/mooncake.db \
  --downloads-json data/downloads.json

覆盖文件必须是一个以完整包名为键的 JSON 对象：

{
  "owner/package": 1234
}

2. 运行本地应用

先安装依赖：

npm install

启动 Next.js 全栈应用：

MOONCAKE_DB_PATH=data/mooncake.db npm run dev -- --hostname 127.0.0.1 --port 3000

然后打开 http://127.0.0.1:3000。

当前应用提供：

/：包榜单浏览界面
/search：主搜索结果页
/advanced-search：支持条件分组与原生表达式的图形化高级检索页
/api/*：直接读取 SQLite 的 JSON API

3. 调用 API

搜索：

GET /api/search?q=io&limit=20

支持的搜索参数：

ast：供高级检索构建器使用的序列化查询 AST
expr：会被编译到共享查询 AST 的原生布尔表达式
q：全局全文检索，支持 AND、OR、NOT、括号、引号短语，以及 owner:、author:、package:、keyword:、description:、name: 等字段前缀
owner、package、keyword、description：字段级全文检索，彼此按 AND 组合
license、repository：元数据子串过滤
rank: S, A, B, C, D
momentum: Rising, Hot, Stable
min_score, max_score
min_dependents, min_recent_dependents, min_downloads
from_year, to_year
has_repository、has_license：true 或 false
sort: relevance, score, growth, downloads, dependents, recent, updated, name
order：asc 或 desc
limit：最大 100

字段语义：

owner 表示本地注册表元数据里的包命名空间所有者。
author: 目前只是 owner: 的别名。
当前索引还没有单独的作者列表、维护者列表或机构字段。

示例：

GET /api/search?expr=(owner:gmlewis OR keyword:json) AND score>=180
GET /api/search?ast=<serialized-query-ast>
GET /api/search?q=owner:gmlewis AND "http client"&limit=20
GET /api/search?q=author:gmlewis AND keyword:json
GET /api/search?keyword=json&min_score=180&min_downloads=500&sort=downloads
GET /api/search?description=parser&from_year=2024&to_year=2026&has_repository=true&sort=updated
GET /api/search?rank=A&momentum=Rising&min_dependents=5&sort=growth

榜单：

GET /api/feeds/top?limit=50
GET /api/feeds/hot?limit=24
GET /api/feeds/rising?limit=24

包分析：

GET /api/packages/<owner>/<packageName>/analysis

4. 验证改动

moon fmt
moon check --target all
moon test --target js
moon test src/score --target all
python3 -m unittest scripts/build_index_test.py
npm run typecheck
npm run build
npm test

仓库快捷命令：

just build-db
just build-db-with-downloads data/downloads.json
just build-db-offline
just web-typecheck
just web-build
just serve
just dev

说明

每次构建索引都会从头重建 SQLite 数据库。
下载量可能来自在线 mooncakes 响应、data/download_cache.json 或本地覆盖文件。
当 sort=relevance 且存在任意全文条件时，搜索结果会优先按 SQLite bm25 相关性排序。
图形化高级检索和原生 expr 输入都会编译到同一套共享查询 AST。
静态发布（npm run build:static-data、npm run build:static）在 static_search 教程中介绍。