如何快速向 Hister 提交第一个提取器：新手社区贡献完整指南
如何快速向 Hister 提交第一个提取器新手社区贡献完整指南【免费下载链接】histerYour own search engine项目地址: https://gitcode.com/GitHub_Trending/hi/histerHisterhister是一个完全私有化的个人搜索引擎它把网页、文件和本地笔记变成可全文搜索的文档库。本指南带你完成对 Hister 社区贡献的第一步为项目编写并提交第一个提取器Extractor——负责把特定网站的页面转换成高质量可搜索文本的核心组件。只要会写 Go 语言你就能走完这条从克隆仓库、使用提取器模板、编写测试到提交 PR 的完整路径。为什么提取器是最佳新手切入点提取器是 Hister 的内容处理器它把原始 HTML 变成干净的可搜索文本和精美的预览。通用解析会丢失结构信息而专门的提取器可以为特定站点做领域定制——丢弃广告和导航噪音、保留代码块与回答层级让搜索结果更精准。新手友好之处在于提取器互相独立每个提取器一个目录代码自成一体不会牵动核心架构。目前项目内置了 Reddit、Hacker News、Wikipedia、Twitter 等 19 个提取器参考实现丰富目录见 server/extractor/extractors/。贡献前请先通读社区规范CONTRIBUTING.md。贡献环境准备克隆仓库与本地构建克隆仓库git clone https://gitcode.com/GitHub_Trending/hi/hister cd hister一键构建并验证环境项目用manage.sh封装了常用命令完整命令见 webui/website/src/content/docs/developer.md./manage.sh build # 完整构建 go test ./... # 运行全部 Go 测试 golangci-lint run --fix ./... # 格式化 静态检查 提交前必须保证go test ./...全绿、lint 干净这是项目的硬性门槛。构建出的服务启动后你就可以在搜索界面实时验证自己的提取器效果找到提取器模板7 步创建新提取器项目内置了一个开箱即用的模板目录 server/extractor/extractors/_extractor_template/extractor.go它的注释就是官方教程。按文件头部说明操作把_extractor_template/复制为server/extractor/extractors/你的名字/去掉前缀_否则 Go 会忽略该目录修改包名与结构体名为描述性名称如MySiteExtractor改matchURLPrefix常量指向你的目标站点实现Extract产出可搜索文本和Preview产出预览 HTML在 server/extractor/registry.go 的DefaultExtractors()中注册你的提取器必须放在 readability 之前编写单元测试跑 lint 与测试后提交 PR模板核心逻辑标题 正文 元数据在 extractor.go 中用goquery解析 HTML改几行选择器就能适配大多数静态站点。理解提取器接口7 个必须实现的方法所有提取器都实现 sdk.Extractor 接口共 7 个方法职责非常直白方法职责Name()短名称小写后成为 YAML 配置键Description()功能描述会展示在 API 配置端点Capabilities()声明参与的阶段Extract/Preview/EnrichMatch(d)判断是否处理该文档要求快速前缀匹配即可Extract(d)填充d.Title和d.Text供全文索引Preview(d)返回净化后的 HTML 预览GetConfig()/SetConfig()嵌入sdk.ConfigSupport即可免费获得返回值是三种决定之一成功sdk.Extracted()、回退sdk.ExtractFallback(err)让链上下一个提取器接手、中止sdk.AbortExtraction(err)致命错误。解析失败时优先返回回退这是模板最重要的容错约定。 想看懂一个完整实现推荐读 Hacker News 提取器 server/extractor/extractors/hackernews/hackernews.go它演示了如何按 URL 解析精确匹配页面、用goquery提取帖子与评论树。为提取器编写测试用真实 HTML 片段做表驱动测试测试不是可选项。参考 hackernews_test.go 的写法在测试文件里内联一段镜像真实页面结构的 HTML 常量或放入testdata/目录用表驱动方式覆盖Match的各种 URL 变体带追踪参数、www前缀、尾斜杠、相似域名如example.com.example必须全部拒绝断言Extract产出的标题、正文和元数据另外项目还支持真实站点冒烟测试在 server/extractor/live_cases.yaml 里登记一条公开 URL即可通过./manage.sh run_extractor_tests对线上页面做端到端校验会遵循目标站点的 robots 规则。提交 PR 前检查清单与社区规范代码检查清单go test ./... # 全部测试通过 golangci-lint run --fix ./... # lint 干净配置见 .golangci.toml提交信息要解释为什么改而不只是改了什么一个 PR 只关注一件事大型架构改动请先开 issue 讨论再动手代码遵循goimportsgofumpt格式⚠️ AI 使用政策务必阅读CONTRIBUTING.md 对 AI 辅助贡献有明确政策新手尤其要注意必须披露使用了什么 AI 工具以及辅助程度你必须完全理解每一行代码并能解释其正确性AI 不能是 PR 的主要作者PR 结构由你决定Issue 和 PR 描述必须完全由人撰写禁止粘贴 LLM 生成的套话good first issue 类任务禁止用 AI 完成——它是给人类新人的平滑上手段 贡献代码自动采用项目的 AGPLv3 许可见 LICENSE。常见问题速答Q我的站点是纯 SPAJS 渲染提取器能拿到内容吗A需要配合chromedp或bidi爬虫后端让页面在浏览器中渲染后再进入提取链。可参考 Notion 提取器的做法server/extractor/extractors/notion/notion.go。Q不想做预览只做搜索索引行吗A可以。Preview直接返回sdk.PreviewFallback(nil)预览会自动交给通用提取器处理Capabilities()里只声明Extract: true即可。Q提取器里能发额外的网络请求吗A不建议。官方文档明确指出这会增加延迟与流量还可能失败——提取器应只处理已抓取的 HTML详见 developer.md 的提取器章节。Q从哪找选题A先看 webui/website/src/content/docs/extractors.md 列出的内置提取器避开已覆盖的站点如 Reddit、GitHub、Wikipedia你常用但搜出来很乱的网站就是好目标。总结向 Hister 提交第一个提取器的路径很清晰克隆仓库 → 复制_extractor_template→ 实现Match/Extract/Preview→ 表驱动测试 → 注册进DefaultExtractors→ lint 全绿后提 PR。提取器边界清晰、参考实现多是学习 Go 社区协作最好的起点。动手前记得通读 AI 政策与 PR 规范祝你顺利合并第一个 PR【免费下载链接】histerYour own search engine项目地址: https://gitcode.com/GitHub_Trending/hi/hister创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考