Agents-Flex

Appearance

Agents-Flex 交流与贡献 ​

Agents-Flex 是一个面向 Java 开发者的开源项目。无论你是在接入模型、排查 Agent 问题，还是希望改进代码和文档，都可以通过下面的渠道与社区协作。

交流渠道 ​

微信交流群 ​

扫码加入微信群，适合讨论使用经验、模型适配、架构设计和新功能想法。

二维码失效或群人数已满时，可以先在代码仓库提交 Issue，留下可公开联系的方式， 并说明希望加入 Agents-Flex 社区，我们会在合适的渠道回复。

代码仓库 ​

  • GitHub 仓库：源码、Issue、Pull Request 和版本记录。
  • Gitee 仓库：国内访问更方便，也可以提交 Issue 和 Pull Request。
  • 更新记录：查看版本变更、兼容性调整和已发布能力。

仓库中的讨论应尽量保留在公开页面，便于其他开发者搜索和复用答案。涉及密钥、客户数据、 内部地址或安全漏洞的内容不要直接贴到群聊、Issue 或日志中。

如何提问，才能更快得到帮助 ​

提交问题前，建议先搜索 ChatModel 快速开始、常见概念 以及相关模块文档。一个可复现、信息完整的问题通常比一段长日志更容易定位。

提问时请尽量包含：

  1. Agents-Flex 版本、JDK 版本、操作系统和使用的模块。
  2. 模型提供商、模型名称、Endpoint 类型；API Key 请使用占位符。
  3. 期望行为、实际行为，以及同步调用还是流式调用。
  4. 最小可运行代码或脱敏后的 Prompt、异常堆栈和相关日志。
  5. 是否可以稳定复现，以及已经尝试过的排查方式。

可以使用下面的结构组织 Issue：

text
### 环境
- Agents-Flex:
- JDK:
- 模块与模型:

### 复现步骤
1.
2.

### 期望结果

### 实际结果

### 日志或最小示例

不要在问题中上传真实 API Key、完整 Authorization Header、用户隐私、生产 Prompt 或未脱敏的业务数据。需要共享较长日志时，只保留从请求开始到第一次异常的相关片段。

报告 Bug 和提出需求 ​

Bug 报告 ​

请在 GitHub Issues 或 Gitee Issues 中提交 Bug。标题应直接描述 影响，例如“RoutedChatModel 在流式失败后未切换备用节点”，而不是“有问题请帮忙看看”。

如果问题与具体模型供应商有关，请同时确认该请求是否能通过供应商原生接口复现，并附上 脱敏后的 HTTP 状态码、错误类型和请求阶段。这样可以区分配置问题、供应商错误和框架行为。

功能建议 ​

功能建议请说明要解决的场景、当前 workaround、受影响的模块和兼容性要求。对于新的模型或 向量库适配，最好补充：协议文档、认证方式、同步/流式能力、工具调用或多模态支持情况， 以及是否有可公开使用的测试账号或 Mock 响应。

参与代码和文档贡献 ​

开始前 ​

  1. Fork 仓库并创建独立分支，分支名建议体现目的，例如 docs/chat-model-routing 或 fix/stream-retry。
  2. 先在 Issue 中说明较大的改动，确认范围后再实现，避免重复工作。
  3. 保持一次提交解决一个主题，不要把无关格式化、依赖升级和功能修改混在一起。

代码贡献 ​

代码改动应尽量遵循现有模块边界和 API 风格。新增行为通常需要同时补充测试，尤其是：

  • 同步与流式路径是否一致；
  • 超时、重试、取消和异常是否符合现有契约；
  • 多线程或共享实例场景下是否存在可变状态；
  • 新增供应商能力是否在不支持时给出清晰错误。

提交 Pull Request 时请写清楚改动目的、实现方式、测试命令和已知限制。涉及公开 API 的改动， 还应同步更新对应中文文档；如果行为影响英文用户，也请注明英文文档是否需要跟进。

文档贡献 ​

文档中的示例应能与当前代码和版本对应。修正文档时请优先补充“适用场景、前置条件、完整示例、 常见错误和下一步链接”，并检查相对链接、代码块语言标记和中英文术语的一致性。

本地预览文档：

bash
cd docs
npm install
npm run docs:dev

发布前构建检查：

bash
cd docs
npm run docs:build

代码改动则请在仓库根目录运行相应的 Maven 测试；至少确认受影响模块可以编译，必要时再运行 完整测试。Pull Request 描述中请粘贴实际执行过的命令和结果，不要只写“已测试”。

Pull Request 检查清单 ​

  • [ ] 改动范围与 Issue 或需求一致，没有混入无关文件。
  • [ ] 新增或修改的行为有测试，或说明为什么不适合自动化测试。
  • [ ] 文档、示例、导航和版本说明已同步。
  • [ ] 未提交 API Key、个人信息、构建产物和本地 IDE 文件。
  • [ ] 已执行受影响模块的测试，以及 npm run docs:build（如果修改了文档）。
  • [ ] PR 描述包含背景、方案、验证方式和兼容性影响。

维护者可能会请求补充测试、拆分提交或调整 API 命名。请直接在 PR 中继续讨论，必要时更新 描述，让后续读者能理解最终决定。

安全问题 ​

安全漏洞不应公开提交到 Issue。请通过仓库维护者提供的私下渠道报告，并包含受影响版本、 复现条件、潜在影响和建议的修复方向。报告中不要发送真实凭据或生产数据；可以使用最小化的 PoC 和占位符。公开披露时间和修复版本由维护者与报告者共同确认。

社区协作原则 ​

请尊重不同技术背景和使用场景，围绕事实、代码和可复现结果讨论。对模型供应商、框架设计或 实现方案有不同意见时，优先给出可验证的示例和权衡，而不是只给结论。这样既能帮助当前问题， 也能让讨论沉淀为下一位开发者可以直接使用的文档。

感谢每一份反馈、示例、测试和文档修订。Agents-Flex 的稳定性和可用性，来自用户在真实项目 中的实践，也来自社区持续把这些实践反馈回代码和文档。