ferret

环境要求

• 已安装 Go 工具链，终端可执行 go 命令
• 可访问 github.com 以拉取 Go 模块
• 明确使用场景：新项目用 Native v2 API，已有 v1 集成走 compat 迁移
• 注意当前分支是 v2 alpha，稳定版请使用 Ferret v1

安装与启动步骤

1. 1确认 Go 环境

   先确认本机已装 Go 且命令可用，版本过旧可能无法拉取 v2 模块。

   go version

   复制

2. 2初始化 Go 模块

   在空目录里创建自己的 Go module，作为后续引入 Ferret 的宿主工程。

   go mod init ferret-demo

   复制

3. 3拉取 Ferret v2

   按 README 的 Getting started 使用 go get 引入 v2 模块，会自动写入 go.mod。

   go get github.com/MontFerret/ferret/v2@latest

   复制

4. 4编写引擎入口

   新项目用 ferret.New(opts...) 做 Native 嵌入；使用 github.com/MontFerret/api 的集成改用 uapi.New(opts...) 创建并持有引擎。

5. 5整理并编译

   整理依赖树并编译工程，确认引入的模块路径与 API 可正常解析。

   go mod tidy
   go build ./...

   复制

6. 6可选：试用新语法

   README 提供在线 Playground，可先在上面验证 v2 查询语法再落到代码里。

关键配置

如何确认成功

go build ./... 编译无报错；代码中 ferret.New(opts...) 或 uapi.New(opts...) 能成功返回引擎实例。

常见问题

注意事项

• 本项目 README 只给出 go get 形式的安装说明，没有 CLI、Docker 或配置文件相关命令，本教程未虚构任何参数与端口。
• Ferret v2 仍处于 alpha 阶段，语法与 API 可能变动，重要项目请评估稳定性或使用 v1。
• CLI、测试运行器 lab、Web worker 均为独立仓库，使用前请单独查看对应仓库文档。
• 引擎、session、plan 的生命周期需按 README 描述的顺序释放，避免资源泄漏。