Skip to content

feat(fel): 新增 You.com 联网搜索社区工具(fel-community/tool-youcom-search)#416

Open
Emos21 wants to merge 2 commits into
ModelEngine-Group:mainfrom
Cooperation-org:fel-feature-youcom-search
Open

feat(fel): 新增 You.com 联网搜索社区工具(fel-community/tool-youcom-search)#416
Emos21 wants to merge 2 commits into
ModelEngine-Group:mainfrom
Cooperation-org:fel-feature-youcom-search

Conversation

@Emos21

@Emos21 Emos21 commented Jul 8, 2026

Copy link
Copy Markdown

关联 Issue: #415

动机

FEL 已具备完善的工具机制与 fel-community 社区模块体系,但框架内尚无联网搜索工具。本 PR 新增 tool-youcom-search 社区模块,让基于 FEL 构建的智能体获得开箱即用、带来源引用的实时联网检索能力。纯增量改动,全部位于 fel-community 内(外加一行模块注册)。

变更内容

  • 新增 framework/fel/java/fel-community/tool-youcom-search 模块(模块结构、构建插件配置完全参照 model-openai
  • YouComSearchService — 标准工具定义:@Group + @ToolMethod(namespace="youcom", name="web_search") + @Genericable,参数 query(必填)/ count(默认 5,上限 20)/ freshness(可选),与 WeatherService 示例同构;已通过 Tool.Metadata.fromMethod 元数据解析测试,tool-discoverer 可正常发现注册
  • YouComSearchServiceImpl@Component @Fitable("default");调用 GET https://ydc-index.io/v1/searchX-API-Key 认证),API Key 取环境变量 YDC_API_KEY(新账户 $100 免费额度);网页与新闻双通道结果格式化为带编号的 标题/链接/摘录 文本
  • 配置:@AcceptConfigValues("fel.youcom-search") 仅暴露 apiBase 与超时(与 model-openai 的配置习惯一致);API Key 刻意不做配置项,避免密钥被写入配置文件
  • 未配置 Key 时返回友好中文提示(不抛异常、零影响);401/403/422/429/5xx/超时/解析失败均映射为简洁中文提示,Key 不出现在任何日志与返回文本中
  • 不引入任何新第三方依赖(仅 fit-api / fit-util / fit-http-classic / fit-http-protocol / tool-service 及兄弟模块已用的 test-scope 插件)
  • 版权头、公共 API 中文 Javadoc(@author / @SInCE)、Conventional Commits 及本仓库 .claude/CLAUDE.md 要求的 AI 生成标记均已遵循

测试

  • 19 个测试:15 个实现层离线单测(请求构造 / 结果映射 / count 上下限 / 未配置 Key / 401/429/500 / 异常 JSON / 超时)+ 3 个 FEL 工具元数据解析测试 + 1 个环境变量门控在线测试(未设置 YDC_API_KEY 自动跳过;已实测通过,返回真实检索结果)
  • fel-community 全模块回归:model-openai 18 / tokenizer-hanlp 1 全部通过,与 main 基线完全一致,零回归
mvn test -pl framework/fel/java/fel-community/tool-youcom-search -am
# 在线验证(可选,1 次真实调用)
export YDC_API_KEY=<你的 Key>   # 获取: https://you.com/platform/api-keys

开发中发现的两个框架层现象(与本 PR 无关,仅供参考)

  1. HttpClassicClientResponse#entityBytes() 在服务端返回 gzip 且客户端(OkHttp)自动解压、剥离 Content-Length 的场景下返回空字节(readBodyByLength(-1));改用惰性 entity() 路径(与 OpenAiModel 一致)可正常工作
  2. @MvcTest@EnabledIfEnvironmentVariable 组合会触发测试框架注解解析器异常(apiguardian @API 5.0/5.1 冲突,DefaultAnnotationTree.merge

如需要,两者都可以再单独提 Issue 详细复现。

标签建议:in: feltype: feature(需维护者添加)。


English summary: Adds a new fel-community module tool-youcom-search — the framework's first web-search tool. Standard FEL tool definition (@Group/@ToolMethod, verified to parse via Tool.Metadata.fromMethod so tool-discoverer registers it), implementation calling the You.com Search API with the YDC_API_KEY env var ($100 free signup credit), friendly Chinese guidance when unconfigured, no new third-party dependencies, 19 tests (offline + one env-gated live test, verified against the real API), zero regressions across fel-community. Also documents two framework-level observations (gzip vs entityBytes; @mvctest + @EnabledIfEnvironmentVariable annotation-resolver clash) discovered during development — happy to file separate issues for both.

Emos21 and others added 2 commits July 8, 2026 22:28
在 fel-community 下新增 tool-youcom-search 模块,提供标准
@ToolMethod 工具 youcom/web_search,供 FEL 智能体联网检索实时
信息。密钥仅从环境变量 YDC_API_KEY 读取;密钥缺失或调用失败时
返回中文提示字符串,不抛出异常,保证宿主流程不受影响。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
覆盖请求构造(路径、X-API-Key、查询参数)、网页与新闻结果映射、
可选字段缺失降级、条数默认值与上限截断、无密钥友好提示、
401/403/422/429/500 错误映射、非法 Json 与超时容错,并通过
Tool.Metadata.fromMethod 验证工具注解可被 FEL 框架正确解析。
另含一个由 YDC_API_KEY 环境变量门控的真实接口联调测试。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@CodeCasterX

Copy link
Copy Markdown
Member

你好,我是这个项目的maintainer,你可以通过readme中的联系方式加一下我的联系方式,我们聊一下相关改动吧?你这个是在什么场景下使用呢?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants