[
{
"path": ".editorconfig",
"content": "root = true\n\n[*]\ncharset = utf-8\nend_of_line = lf\ninsert_final_newline = true\nindent_style = space\nindent_size = 4\n\n[*.md]\ntrim_trailing_whitespace = false"
},
{
"path": ".github/workflows/docs-build.yml",
"content": "name: docs-build\n\non:\n pull_request:\n paths:\n - 'docs-site/**'\n - '.github/workflows/docs-build.yml'\n push:\n branches: [main, dev]\n paths:\n - 'docs-site/**'\n - '.github/workflows/docs-build.yml'\n\njobs:\n build:\n runs-on: ubuntu-latest\n defaults:\n run:\n working-directory: docs-site\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Setup Node\n uses: actions/setup-node@v4\n with:\n node-version: '20'\n cache: 'npm'\n cache-dependency-path: docs-site/package-lock.json\n\n - name: Install dependencies\n run: npm ci\n\n - name: Build docs\n run: npm run build\n"
},
{
"path": ".github/workflows/docs-pages.yml",
"content": "name: docs-pages\n\non:\n push:\n branches: [main]\n paths:\n - 'docs-site/**'\n - '.github/workflows/docs-pages.yml'\n workflow_dispatch:\n\npermissions:\n contents: read\n pages: write\n id-token: write\n\nconcurrency:\n group: docs-pages\n cancel-in-progress: true\n\njobs:\n build:\n runs-on: ubuntu-latest\n defaults:\n run:\n working-directory: docs-site\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Setup Node\n uses: actions/setup-node@v4\n with:\n node-version: '20'\n cache: 'npm'\n cache-dependency-path: docs-site/package-lock.json\n\n - name: Configure Pages\n uses: actions/configure-pages@v5\n\n - name: Install dependencies\n run: npm ci\n\n - name: Build docs\n env:\n GITHUB_PAGES: 'true'\n run: npm run build\n\n - name: Upload artifact\n uses: actions/upload-pages-artifact@v3\n with:\n path: docs-site/build\n\n deploy:\n runs-on: ubuntu-latest\n needs: build\n environment:\n name: github-pages\n url: ${{ steps.deployment.outputs.page_url }}\n steps:\n - name: Deploy to GitHub Pages\n id: deployment\n uses: actions/deploy-pages@v4\n"
},
{
"path": ".gitignore",
"content": "target/\n!.mvn/wrapper/maven-wrapper.jar\n!**/src/main/**/target/\n!**/src/test/**/target/\n\n### IntelliJ IDEA ###\n.idea/modules.xml\n.idea/jarRepositories.xml\n.idea/compiler.xml\n.idea/libraries/\n*.iws\n*.iml\n*.ipr\n\n### Eclipse ###\n.apt_generated\n.classpath\n.factorypath\n.project\n.settings\n.springBeans\n.sts4-cache\n\n### NetBeans ###\n/nbproject/private/\n/nbbuild/\n/dist/\n/nbdist/\n/.nb-gradle/\nbuild/\n!**/src/main/**/build/\n!**/src/test/**/build/\n\n### VS Code ###\n.vscode/\n\n### Local tooling ###\n.claude/\nAGENTS.md\nnode_modules/\ndist/\n.rsbuild/\n.turbo/\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\npnpm-debug.log*\n\n### Scratch / temp ###\n*.class\n.tmp*/\n.tmp*\ntmp/\ntmp-*/\ntmp-*.png\ntmp-*.txt\ntmp-*.log\n\n**/.flattened-pom.xml\n\n### Mac OS ###\n.DS_Store\n/.idea/\n/ai4j/.gitignore\n/ai4j/src/main/resources/新建文本文档 (2).txt\n/ai4j-spring-boot-stater/.gitignore\n.ai4j/\n.docs/\ndocs/\nAPIResponse.md\nAGENT.md\nai4j-release-package.log\njavadoc-ai4j.log\n"
},
{
"path": "LICENSE",
"content": " Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\n Copyright [yyyy] [name of copyright owner]\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License."
},
{
"path": "README-EN.md",
"content": "\n
\n\n\n \n \n \n \n \n \n
\n\n# ai4j\nA Java AI Agentic development toolkit for JDK 8+, combining foundational AI capabilities with higher-level agent development capabilities. \nIt covers multi-provider model access, unified I/O, Tool Calling, MCP, RAG, unified `VectorStore`, ChatMemory, agent runtime, coding agent, CLI / TUI / ACP, FlowGram integration, and integration with published AgentFlow endpoints such as Dify, Coze, and n8n, helping Java applications grow from basic model integration to more complete agentic application development.\n\nThis repository has evolved into a multi-module SDK. In addition to the core `ai4j` module, it now provides `ai4j-agent`, `ai4j-coding`, `ai4j-cli`, `ai4j-spring-boot-starter`, `ai4j-flowgram-spring-boot-starter`, and `ai4j-bom`. If you only need the basic LLM integration layer, start with `ai4j`. If you need agent runtime, coding agent, CLI / ACP, Spring Boot, or FlowGram integration, add the corresponding modules.\n\n## Positioning Compared with Common Java AI Options\n\n| Option | Java baseline | Application style | Primary focus |\n| --- | --- | --- | --- |\n| `ai4j` | `JDK 8+` | Plain Java / Spring | Unified model access, Tool / MCP / RAG, agent runtime, coding agent, CLI / TUI / ACP |\n| `Spring AI` | `Java 17+` | `Spring Boot 3.x` | Spring-native AI integration, model access, Tool Calling, MCP, and RAG |\n| `Spring AI Alibaba` | `Java 17+` | `Spring Boot 3.x` | Spring and Alibaba Cloud AI ecosystem integration |\n| `LangChain4j` | `Java 17+` | Plain Java / Spring / Quarkus and more | General Java abstractions for LLM, agent, and RAG integration, plus AI Services |\n\n## Supported platforms\n+ OpenAi\n+ Jina (Rerank / Jina-compatible Rerank)\n+ Zhipu\n+ DeepSeek\n+ Moonshot\n+ Tencent Hunyuan\n+ Lingyi AI\n+ Ollama\n+ MiniMax\n+ Baichuan\n\n## Supported services\n+ Chat Completions（streaming and non-streaming）\n+ Responses\n+ Embedding\n+ Rerank\n+ Audio\n+ Image\n+ Realtime\n\n## Supported AgentFlow / hosted workflow platforms\n+ Dify (chat / workflow)\n+ Coze (chat / workflow)\n+ n8n (webhook workflow)\n\n## Features\n+ Supports Spring and ordinary Java applications. Supports applications above Java 8.\n+ Multi-platform and multi-service.\n+ Provides `AgentFlow` support for integrating published Agent / Workflow endpoints from Dify, Coze, and n8n.\n+ Provides `ai4j-agent` as the general agent runtime, with ReAct, subagents, agent teams, memory, tracing, and tool loop support.\n+ Built-in Coding Agent CLI / TUI with interactive repository sessions, provider profiles, workspace model override, and session/process management.\n+ Provides `ai4j-coding` as the coding agent runtime, with workspace-aware tools, outer loop, checkpoint compaction, subagent, and team collaboration support.\n+ Provides `ai4j-flowgram-spring-boot-starter` for integrating FlowGram workflows and trace in Spring Boot applications.\n+ Provides `ai4j-bom` for version alignment across multiple ai4j modules.\n+ Unified input and output.\n+ Unified error handling.\n+ Supports streaming output. Supports streaming output of function call parameters.\n+ Easily use Tool Calls.\n+ Supports simultaneous calls of multiple functions (Zhipu does not support this).\n+ Supports stream_options, and directly obtains statistical token usage through streaming output.\n+ Supports RAG. Built-in vector database support: Pinecone.\n+ Uses Tika to read files.\n+ Token statistics`TikTokensUtil.java`\n\n\n## Tutorial documents\n+ [Quick access to Spring Boot, access to streaming and non-streaming and function calls.](http://t.csdnimg.cn/iuIAW)\n+ [Quick access to open source large models such as qwen2.5 and llama3.1 on the Ollama platform in Java.](https://blog.csdn.net/qq_35650513/article/details/142408092?spm=1001.2014.3001.5501)\n+ [Build a legal AI assistant in Java and quickly implement RAG applications.](https://blog.csdn.net/qq_35650513/article/details/142568177?fromshare=blogdetail&sharetype=blogdetail&sharerId=142568177&sharerefer=PC&sharesource=qq_35650513&sharefrom=from_link)\n\n## Coding Agent CLI / TUI\n\nAI4J now includes `ai4j-cli`, which can be used directly as a local coding agent. Current capabilities include:\n\n+ one-shot and persistent sessions\n+ CLI and TUI interaction modes\n+ provider profile persistence\n+ workspace-level model override\n+ subagent and agent team collaboration\n+ session persistence, resume, fork, history, tree, events, replay\n+ team board, team messages, and team resume for collaboration visibility\n+ process management and buffered logs\n\n### Install\n\n```bash\ncurl -fsSL https://lnyo-cly.github.io/ai4j/install.sh | sh\n```\n\n```powershell\nirm https://lnyo-cly.github.io/ai4j/install.ps1 | iex\n```\n\nThe installer downloads `ai4j-cli` from Maven Central and creates the `ai4j` command. Java 8+ must already be installed on the machine.\n\n### one-shot example\n\n```powershell\nai4j code `\n --provider openai `\n --protocol responses `\n --model gpt-5-mini `\n --prompt \"Read README and summarize the project structure\"\n```\n\n### interactive CLI example\n\n```powershell\nai4j code `\n --provider zhipu `\n --protocol chat `\n --model glm-4.7 `\n --base-url https://open.bigmodel.cn/api/coding/paas/v4 `\n --workspace .\n```\n\n### TUI example\n\n```powershell\nai4j tui `\n --provider zhipu `\n --protocol chat `\n --model glm-4.7 `\n --base-url https://open.bigmodel.cn/api/coding/paas/v4 `\n --workspace .\n```\n\n### ACP example\n\n```powershell\nai4j acp `\n --provider openai `\n --protocol responses `\n --model gpt-5-mini `\n --workspace .\n```\n\n### Build from source (optional)\n\n```powershell\nmvn -pl ai4j-cli -am -DskipTests package\n```\n\nArtifact:\n\n```text\nai4j-cli/target/ai4j-cli--jar-with-dependencies.jar\n```\n\nIf you want to run the locally built artifact directly:\n\n```powershell\njava -jar .\\ai4j-cli\\target\\ai4j-cli--jar-with-dependencies.jar code --help\n```\n\n### Current protocol rules\n\nThe CLI currently exposes only two protocol families:\n\n+ `chat`\n+ `responses`\n\nIf `--protocol` is omitted, the CLI resolves a default locally from provider/baseUrl:\n\n+ `openai` + official OpenAI host -> `responses`\n+ `openai` + custom compatible `baseUrl` -> `chat`\n+ `doubao` / `dashscope` -> `responses`\n+ other providers -> `chat`\n\nNotes:\n\n+ `auto` is no longer exposed to users\n+ legacy `auto` values in existing config files are normalized to explicit protocols on load\n\n### provider profile locations\n\n+ global config: `~/.ai4j/providers.json`\n+ workspace config: `/.ai4j/workspace.json`\n\nRecommended workflow:\n\n+ keep reusable long-term runtime profiles in the global config\n+ let each workspace reference one `activeProfile`\n+ use workspace `modelOverride` for temporary model switching\n\n### Common commands\n\n+ `/providers`\n+ `/provider`\n+ `/provider use `\n+ `/provider save `\n+ `/provider add --provider [--protocol ] [--model ] [--base-url ] [--api-key ]`\n+ `/provider edit [--provider ] [--protocol ] [--model |--clear-model] [--base-url |--clear-base-url] [--api-key |--clear-api-key]`\n+ `/provider default `\n+ `/provider remove `\n+ `/model`\n+ `/model `\n+ `/model reset`\n+ `/stream [on|off]`\n+ `/processes`\n+ `/process status|follow|logs|write|stop ...`\n+ `/resume ` / `/load ` / `/fork ...`\n\n### Documentation entry points\n\n+ [Coding Agent CLI Quickstart](docs-site/docs/getting-started/coding-agent-cli-quickstart.md)\n+ [Coding Agent CLI and TUI](docs-site/docs/agent/coding-agent-cli.md)\n+ [Multi-Provider Profiles](docs-site/docs/agent/multi-provider-profiles.md)\n+ [Coding Agent Command Reference](docs-site/docs/agent/coding-agent-command-reference.md)\n+ [Provider Configuration Examples](docs-site/docs/agent/provider-config-examples.md)\n\n## Other support\n+ [[Low-cost transit platform] Low-cost ApiKey - Limited-time special offer 0.7:1 - Supports the latest o1 model.](https://api.trovebox.online/)\n\n# Quick start\n## Import\n### Module selection\n+ Use `ai4j` for the core LLM / Tool Call / MCP / RAG capabilities\n+ Use `ai4j-agent` for the general agent runtime\n+ Use `ai4j-coding` for coding agent, workspace tools, and outer loop\n+ Use `ai4j-cli` for the local CLI / TUI / ACP host\n+ Use `ai4j-spring-boot-starter` for Spring Boot auto-configuration\n+ Use `ai4j-flowgram-spring-boot-starter` for FlowGram workflow integration\n+ Use `ai4j-bom` when you want version alignment across multiple modules\n\n### Gradle\n```groovy\nimplementation platform(\"io.github.lnyo-cly:ai4j-bom:${project.version}\")\nimplementation \"io.github.lnyo-cly:ai4j\"\nimplementation \"io.github.lnyo-cly:ai4j-agent\"\n```\n\n```groovy\nimplementation group: 'io.github.lnyo-cly', name: 'ai4j', version: '${project.version}'\n```\n\n```groovy\nimplementation group: 'io.github.lnyo-cly', name: 'ai4j-spring-boot-starter', version: '${project.version}'\n```\n\n\n### Maven\n```xml\n\n \n \n io.github.lnyo-cly \n ai4j-bom \n ${project.version} \n pom \n import \n \n \n \n```\n\n```xml\n\n\n io.github.lnyo-cly \n ai4j-agent \n \n\n\n io.github.lnyo-cly \n ai4j-coding \n \n```\n\n```xml\n\n\n io.github.lnyo-cly \n ai4j \n ${project.version} \n \n\n```\n```xml\n\n\n io.github.lnyo-cly \n ai4j-spring-boot-starter \n ${project.version} \n \n```\n\n## Obtain AI service instance\n\n### Obtaining without Spring\n```java\n public void test_init(){\n OpenAiConfig openAiConfig = new OpenAiConfig();\n\n Configuration configuration = new Configuration();\n configuration.setOpenAiConfig(openAiConfig);\n\n HttpLoggingInterceptor httpLoggingInterceptor = new HttpLoggingInterceptor();\n httpLoggingInterceptor.setLevel(HttpLoggingInterceptor.Level.HEADERS);\n\n OkHttpClient okHttpClient = new OkHttpClient\n .Builder()\n .addInterceptor(httpLoggingInterceptor)\n .addInterceptor(new ErrorInterceptor())\n .connectTimeout(300, TimeUnit.SECONDS)\n .writeTimeout(300, TimeUnit.SECONDS)\n .readTimeout(300, TimeUnit.SECONDS)\n .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress(\"127.0.0.1\",10809)))\n .build();\n configuration.setOkHttpClient(okHttpClient);\n\n AiService aiService = new AiService(configuration);\n\n embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);\n chatService = aiService.getChatService(PlatformType.getPlatform(\"OPENAI\"));\n\n }\n```\n### Obtaining with Spring\n```yml\n# Domestic access usually requires a proxy by default.\nai:\n openai:\n api-key: \"api-key\"\n okhttp:\n proxy-port: 10809\n proxy-url: \"127.0.0.1\"\n zhipu:\n api-key: \"xxx\"\n #other...\n```\n\n```java\n// Inject Ai service\n@Autowired\nprivate AiService aiService;\n\n// Obtain the required service instance\nIChatService chatService = aiService.getChatService(PlatformType.OPENAI);\nIEmbeddingService embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);\n// ......\n```\n\n## Chat service\n\n### Synchronous request call\n```java\n\npublic void test_chat() throws Exception {\n // Obtain chat service instance\n IChatService chatService = aiService.getChatService(PlatformType.OPENAI);\n\n // Build request parameters\n ChatCompletion chatCompletion = ChatCompletion.builder()\n .model(\"gpt-4o-mini\")\n .message(ChatMessage.withUser(\"鲁迅为什么打周树人\"))\n .build();\n\n // Send dialogue request\n ChatCompletionResponse response = chatService.chatCompletion(chatCompletion);\n\n System.out.println(response);\n}\n\n```\n\n### Streaming call\n```java\npublic void test_chat_stream() throws Exception {\n // Obtain chat service instance\n IChatService chatService = aiService.getChatService(PlatformType.OPENAI);\n\n // Construct request parameters\n ChatCompletion chatCompletion = ChatCompletion.builder()\n .model(\"gpt-4o-mini\")\n .message(ChatMessage.withUser(\"查询北京明天的天气\"))\n .functions(\"queryWeather\")\n .build();\n\n\n // Construct listener\n SseListener sseListener = new SseListener() {\n @Override\n protected void send() {\n System.out.println(this.getCurrStr());\n }\n };\n // Display function parameters. Default is not to display.\n sseListener.setShowToolArgs(true);\n\n // Send SSE request\n chatService.chatCompletionStream(chatCompletion, sseListener);\n\n System.out.println(sseListener.getOutput());\n\n}\n```\n\n### Image recognition\n\n```java\npublic void test_chat_image() throws Exception {\n // Obtain chat service instance\n IChatService chatService = aiService.getChatService(PlatformType.OPENAI);\n\n // Build request parameters\n ChatCompletion chatCompletion = ChatCompletion.builder()\n .model(\"gpt-4o-mini\")\n .message(ChatMessage.withUser(\"图片中有什么东西\", \"https://cn.bing.com/images/search?view=detailV2&ccid=r0OnuYkv&id=9A07DE578F6ED50DB59DFEA5C675AC71845A6FC9&thid=OIP.r0OnuYkvsbqBrYk3kUT53AHaKX&mediaurl=https%3a%2f%2fimg.zcool.cn%2fcommunity%2f0104c15cd45b49a80121416816f1ec.jpg%401280w_1l_2o_100sh.jpg&exph=1792&expw=1280&q=%e5%b0%8f%e7%8c%ab%e5%9b%be%e7%89%87&simid=607987191780608963&FORM=IRPRST&ck=12127C1696CF374CB9D0F09AE99AFE69&selectedIndex=2&itb=0&qpvt=%e5%b0%8f%e7%8c%ab%e5%9b%be%e7%89%87\"))\n .build();\n\n // Send dialogue request\n ChatCompletionResponse response = chatService.chatCompletion(chatCompletion);\n\n System.out.println(response);\n}\n```\n\n### Function call\n\n```java\npublic void test_chat_tool_call() throws Exception {\n // Obtain chat service instance\n IChatService chatService = aiService.getChatService(PlatformType.OPENAI);\n\n // Build request parameters\n ChatCompletion chatCompletion = ChatCompletion.builder()\n .model(\"gpt-4o-mini\")\n .message(ChatMessage.withUser(\"今天北京天气怎么样\"))\n .functions(\"queryWeather\")\n .build();\n\n // Send dialogue request\n ChatCompletionResponse response = chatService.chatCompletion(chatCompletion);\n\n System.out.println(response);\n}\n```\n#### Define function\n```java\n@FunctionCall(name = \"queryWeather\", description = \"查询目标地点的天气预报\")\npublic class QueryWeatherFunction implements Function {\n\n @Data\n @FunctionRequest\n public static class Request{\n @FunctionParameter(description = \"需要查询天气的目标位置, 可以是城市中文名、城市拼音/英文名、省市名称组合、IP 地址、经纬度\")\n private String location;\n @FunctionParameter(description = \"需要查询未来天气的天数, 最多15日\")\n private int days = 15;\n @FunctionParameter(description = \"预报的天气类型，daily表示预报多天天气、hourly表示预测当天24天气、now为当前天气实况\")\n private Type type;\n }\n\n public enum Type{\n daily,\n hourly,\n now\n }\n\n @Override\n public String apply(Request request) {\n final String key = \"\";\n\n String url = String.format(\"https://api.seniverse.com/v3/weather/%s.json?key=%s&location=%s&days=%d\",\n request.type.name(),\n key,\n request.location,\n request.days);\n\n\n OkHttpClient client = new OkHttpClient();\n\n okhttp3.Request http = new okhttp3.Request.Builder()\n .url(url)\n .get()\n .build();\n\n try (Response response = client.newCall(http).execute()) {\n if (response.isSuccessful()) {\n // 解析响应体\n return response.body() != null ? response.body().string() : \"\";\n } else {\n return \"获取天气失败 当前天气未知\";\n }\n } catch (Exception e) {\n // 处理异常\n e.printStackTrace();\n return \"获取天气失败 当前天气未知\";\n }\n }\n\n}\n```\n\n## Embedding service\n\n```java\npublic void test_embed() throws Exception {\n // Obtain embedding service instance\n IEmbeddingService embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);\n\n // Build request parameters\n Embedding embeddingReq = Embedding.builder().input(\"1+1\").build();\n\n // Send embedding request\n EmbeddingResponse embeddingResp = embeddingService.embedding(embeddingReq);\n\n System.out.println(embeddingResp);\n}\n```\n\n## RAG\n### Configure vector database\n```yml\nai:\n vector:\n pinecone:\n url: \"\"\n key: \"\"\n```\n### Obtain instance\n```java\n@Autowired\nprivate PineconeService pineconeService;\n```\n### Insert into vector database\n```java\npublic void test_insert_vector_store() throws Exception {\n // Obtain embedding service instance\n IEmbeddingService embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);\n\n // Read file content using Tika\n String fileContent = TikaUtil.parseFile(new File(\"D:\\\\data\\\\test\\\\test.txt\"));\n\n // Split text content\n RecursiveCharacterTextSplitter recursiveCharacterTextSplitter = new RecursiveCharacterTextSplitter(1000, 200);\n List contentList = recursiveCharacterTextSplitter.splitText(fileContent);\n\n // Convert to vector\n Embedding build = Embedding.builder()\n .input(contentList)\n .model(\"text-embedding-3-small\")\n .build();\n EmbeddingResponse embedding = embeddingService.embedding(build);\n List> vectors = embedding.getData().stream().map(EmbeddingObject::getEmbedding).collect(Collectors.toList());\n VertorDataEntity vertorDataEntity = new VertorDataEntity();\n vertorDataEntity.setVector(vectors);\n vertorDataEntity.setContent(contentList);\n\n // Vector storage\n Integer count = pineconeService.insert(vertorDataEntity, \"userId\");\n\n}\n```\n### Query from vector database\n```java\npublic void test_query_vector_store() throws Exception {\n // // Obtain embedding service instance\n IEmbeddingService embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);\n\n // Build the question to be queried and convert it to a vector\n Embedding build = Embedding.builder()\n .input(\"question\")\n .model(\"text-embedding-3-small\")\n .build();\n EmbeddingResponse embedding = embeddingService.embedding(build);\n List question = embedding.getData().get(0).getEmbedding();\n\n // Build the query object for the vector database\n PineconeQuery pineconeQueryReq = PineconeQuery.builder()\n .namespace(\"userId\")\n .vector(question)\n .build();\n\n String result = pineconeService.query(pineconeQueryReq, \" \");\n \n // Carry the result and have a conversation with the chat service.\n // ......\n}\n```\n\n### Delete data from vector database\n```java\npublic void test_delete_vector_store() throws Exception {\n // Build parameters\n PineconeDelete pineconeDelete = PineconeDelete.builder()\n .deleteAll(true)\n .namespace(\"userId\")\n .build();\n // Delete\n Boolean res = pineconeService.delete(pineconeDelete);\n}\n```\n\n\n\n# Contribute to ai4j\nYou are welcome to provide suggestions, report issues, or contribute code to ai4j. You can contribute to ai4j in the following ways:\n\n## Issue feedback\nPlease use the GitHub Issue page to report issues. Describe as specifically as possible how to reproduce your issue, including detailed information such as the operating system, Java version, and any relevant log traces.\n## PR\n1. Fork this repository and create your branch.\n2. Write your code and test it.\n3. Ensure that your code conforms to the existing style.\n4. Write clear log information when submitting. For small changes, a single line of information is sufficient, but for larger changes, there should be a detailed description.\n5. Complete the pull request form and ensure that changes are made on the `dev` branch and link to the issue that your PR addresses.\n\n# Support\nIf you find this project helpful to you, please give it a star⭐。\n\n"
},
{
"path": "README.md",
"content": "\n
\n\n\n \n \n \n \n \n \n
\n\n# ai4j\n一款面向 JDK8+ 的 Java AI Agentic 开发套件，既提供统一的大模型调用与常用 AI 基座能力，也提供更完善的智能体式 Agent 开发能力。 \n覆盖多平台模型接入、统一输入输出、Tool Call、MCP、RAG、统一 `VectorStore`、ChatMemory、Agent Runtime、Coding Agent、CLI / TUI / ACP、FlowGram 集成，以及 Dify / Coze / n8n 等已发布 AgentFlow 端点接入能力，帮助 Java 应用从基础模型接入扩展到更完整的 agentic 应用开发。\n\n当前仓库已经演进为多模块 SDK，除核心 `ai4j` 外，还提供 `ai4j-agent`、`ai4j-coding`、`ai4j-cli`、`ai4j-spring-boot-starter`、`ai4j-flowgram-spring-boot-starter`、`ai4j-bom`。如果只需要基础大模型调用，优先引入 `ai4j`；如果需要 Agent、Coding Agent、CLI / ACP、Spring Boot 或 FlowGram 集成，再按模块引入对应能力。\n\n## 适用场景与常见方案对比\n\n| 方案 | Java 基线 | 应用形态 | 能力侧重点 |\n| --- | --- | --- | --- |\n| `ai4j` | `JDK8+` | 普通 Java / Spring | 统一大模型接入、Tool / MCP / RAG、Agent Runtime、Coding Agent、CLI / TUI / ACP |\n| `Spring AI` | `Java 17+` | `Spring Boot 3.x` | Spring 原生 AI 集成、模型访问、Tool Calling、MCP、RAG |\n| `Spring AI Alibaba` | `Java 17+` | `Spring Boot 3.x` | Spring 与阿里云 AI 生态整合 |\n| `LangChain4j` | `Java 17+` | 普通 Java / Spring / Quarkus 等 | 通用 Java LLM / Agent / RAG 抽象、AI Services、多框架集成 |\n\n## 支持的平台\n+ OpenAi(包含与OpenAi请求格式相同/兼容的平台)\n+ Jina（Rerank / Jina-compatible Rerank）\n+ Zhipu(智谱)\n+ DeepSeek(深度求索)\n+ Moonshot(月之暗面)\n+ Hunyuan(腾讯混元)\n+ Lingyi(零一万物)\n+ Ollama\n+ MiniMax\n+ Baichuan\n\n## 支持的服务\n+ Chat Completions（流式与非流式）\n+ Responses\n+ Embedding\n+ Rerank\n+ Audio\n+ Image\n+ Realtime\n\n## 已适配的 AgentFlow / 工作流平台\n+ Dify（Chat / Workflow）\n+ Coze（Chat / Workflow）\n+ n8n（Webhook Workflow）\n\n## 特性\n+ 支持MCP服务，内置MCP网关，支持建立动态MCP数据源。\n+ 支持Spring以及普通Java应用、支持Java 8以上的应用\n+ 多平台、多服务\n+ 提供 `AgentFlow` 能力，可直接接入 Dify、Coze、n8n 等已发布 Agent / Workflow 端点\n+ 提供 `ai4j-agent` 通用 Agent 运行时，支持 ReAct、subagent、agent teams、memory、trace 与 tool loop\n+ 内置 Coding Agent CLI / TUI，支持本地代码仓交互式会话、provider profile、workspace model override、session/process 管理\n+ 提供 `ai4j-coding` Coding Agent 运行时，支持 workspace tools、outer loop、checkpoint compaction、subagent 与 team 协作\n+ 提供 `ai4j-flowgram-spring-boot-starter`，便于在 Spring Boot 中接入 FlowGram 工作流与 trace\n+ 提供 `ai4j-bom`，便于多模块项目统一版本管理\n+ 统一的输入输出\n+ 统一的错误处理\n+ 支持SPI机制，可自定义Dispatcher和ConnectPool\n+ 支持服务增强，例如增加websearch服务\n+ 支持流式输出。支持函数调用参数流式输出.\n+ 简洁的多模态调用方式，例如vision识图\n+ 轻松使用Tool Calls\n+ 支持多个函数同时调用（智谱不支持）\n+ 支持stream_options，流式输出直接获取统计token usage\n+ 内置 `ChatMemory`，支持基础多轮会话上下文维护，可同时适配 Chat / Responses\n+ 支持RAG，内置统一 `VectorStore` 抽象，当前支持: Pinecone、Qdrant、pgvector、Milvus\n+ 内置 `IngestionPipeline`，统一串联 `DocumentLoader -> Chunker -> MetadataEnricher -> Embedding -> VectorStore.upsert`\n+ 内置 `DenseRetriever`、`Bm25Retriever`、`HybridRetriever`，可按语义检索、关键词检索、混合检索方式组合知识库召回\n+ `HybridRetriever` 支持 `RrfFusionStrategy`、`RsfFusionStrategy`、`DbsfFusionStrategy`，默认使用 RRF；融合排序与 `Reranker` 语义精排解耦\n+ 支持统一 `IRerankService`，当前可接 Jina / Jina-compatible、Ollama、Doubao(方舟知识库重排)；可通过 `ModelReranker` 无缝接入 RAG 精排\n+ RAG 运行时可直接拿到 `rank/retrieverSource/retrievalScore/fusionScore/rerankScore/scoreDetails/trace`，并可通过 `RagEvaluator` 计算 `Precision@K/Recall@K/F1@K/MRR/NDCG`\n+ 使用Tika读取文件\n+ Token统计`TikTokensUtil.java`\n\n## 官方文档站\n+ 在线文档站：`https://lnyo-cly.github.io/ai4j/`\n+ 文档站源码位于 `docs-site/`\n+ 适合直接使用者的入口：`docs-site/docs/coding-agent/`\n+ 适合 SDK 接入的入口：`docs-site/docs/getting-started/` 与 `docs-site/docs/ai-basics/`\n+ 适合协议与扩展集成的入口：`docs-site/docs/mcp/`、`docs-site/docs/agent/`\n\n推荐阅读顺序：\n\n+ `docs-site/docs/intro.md`\n+ `docs-site/docs/getting-started/installation.md`\n+ `docs-site/docs/coding-agent/overview.md`\n+ `docs-site/docs/ai-basics/overview.md`\n+ `docs-site/docs/mcp/overview.md`\n\n基础会话上下文新增入口：\n\n+ `docs-site/docs/ai-basics/chat/chat-memory.md`\n+ `docs-site/docs/ai-basics/services/rerank.md`\n+ `docs-site/docs/ai-basics/rag/ingestion-pipeline.md`\n\n本地运行文档站：\n\n```powershell\ncd .\\docs-site\nnpm install\nnpm run start\n```\n\n```powershell\ncd .\\docs-site\nnpm run build\n```\n\n## 更新日志\n+ [2026-03-28] 修复 Coding Agent ACP 流式场景下纯空白 chunk 被 runtime 过滤的问题；ACP 保持透传原始 delta，不做 chunk 聚合；补充 CLI/文档中的流式语义说明\n+ [2026-03-26] 新增 Coding Agent CLI / TUI 文档与能力说明，覆盖交互式会话、provider profile、workspace model override、命令参考与配置样例\n+ [2025-08-19] 修复传递有验证参数的sse-url时，key丢失问题\n+ [2025-08-08] OpenAi: max_tokens字段现已废弃，推荐使用max_completion_tokens(GPT-5已经不支持max_tokens字段)\n+ [2025-08-08] 支持MCP协议，支持STDIO,SSE,Streamable HTTP; 支持MCP Server与MCP Client; 支持MCP网关; 支持自定义MCP数据源; 支持MCP自动重连\n+ [2025-06-23] 修复ollama的流式错误；修复ollama函数调用的错误；修复moonshot请求时错误；修复ollama embedding错误；修复思考无内容；修复日志冲突；新增自定义异常方法。\n+ [2025-02-28] 新增对Ollama平台的embedding接口的支持。\n+ [2025-02-17] 新增对DeepSeek平台推理模型的适配。\n+ [2025-02-12] 为Ollama平台添加Authorization\n+ [2025-02-11] 实现自定义的Jackson序列化，解决OpenAi已经无法通过Json String来直接实现多模态接口的问题。\n+ [2024-12-12] 使用装饰器模式增强Chat服务，支持SearXNG网络搜索增强，无需模型支持内置搜索以及function_call。\n+ [2024-10-17] 支持SPI机制，可自定义Dispatcher和ConnectPool。新增百川Baichuan平台Chat接口支持。\n+ [2024-10-16] 增加MiniMax平台Chat接口对接\n+ [2024-10-15] 增加realtime服务\n+ [2024-10-12] 修复早期遗忘的小bug; 修复错误拦截器导致的音频字节流异常错误问题; 增加OpenAi Audio服务。\n+ [2024-10-10] 增强对SSE输出的获取，新加入`currData`属性，记录当前消息的整个对象。而原先的`currStr`为当前消息的content内容，保留不变。\n+ [2024-09-26] 修复有关Pinecone向量数据库的一些问题。发布0.6.3版本\n+ [2024-09-20] 增加对Ollama平台的支持，并修复一些bug。发布0.6.2版本\n+ [2024-09-19] 增加错误处理链，统一处理为openai错误类型; 修复部分情况下URL拼接问题，修复拦截器中response重复调用而导致的关闭问题。发布0.5.3版本\n+ [2024-09-12] 修复上个问题OpenAi参数导致错误的遗漏，发布0.5.2版本\n+ [2024-09-12] 修复SpringBoot 2.6以下导致OkHttp变为3.14版本的报错问题；修复OpenAi参数`parallel_tool_calls`在tools为null时的异常问题。发布0.5.1版本。\n+ [2024-09-09] 新增零一万物大模型支持、发布0.5.0版本。\n+ [2024-09-02] 新增腾讯混元Hunyuan平台支持（注意：所需apiKey 属于SecretId与SecretKey的拼接，格式为 {SecretId}.{SecretKey}），发布0.4.0版本。\n+ [2024-08-30] 新增对Moonshot(Kimi)平台的支持，增加`OkHttpUtil.java`实现忽略SSL证书的校验。\n+ [2024-08-29] 新增对DeepSeek平台的支持、新增stream_options可以直接统计usage、新增错误拦截器`ErrorInterceptor.java`、发布0.3.0版本。\n+ [2024-08-29] 修改SseListener以兼容智谱函数调用。\n+ [2024-08-28] 添加token统计、添加智谱AI的Chat服务、优化函数调用可以支持多轮多函数。\n+ [2024-08-17] 增强SseListener监听器功能。发布0.2.0版本。\n\n## 教程文档\n+ [快速接入SpringBoot、接入流式与非流式以及函数调用](http://t.csdnimg.cn/iuIAW)\n+ [Java快速接入qwen2.5、llama3.1等Ollama平台开源大模型](https://blog.csdn.net/qq_35650513/article/details/142408092?spm=1001.2014.3001.5501)\n+ [Java搭建法律AI助手，快速实现RAG应用](https://blog.csdn.net/qq_35650513/article/details/142568177?fromshare=blogdetail&sharetype=blogdetail&sharerId=142568177&sharerefer=PC&sharesource=qq_35650513&sharefrom=from_link)\n+ [大模型不支持联网搜索？为Deepseek、Qwen、llama等本地模型添加网络搜索](https://blog.csdn.net/qq_35650513/article/details/144572824)\n+ [java快速接入mcp以及结合mysql动态管理](https://blog.csdn.net/qq_35650513/article/details/150532784?fromshare=blogdetail&sharetype=blogdetail&sharerId=150532784&sharerefer=PC&sharesource=qq_35650513&sharefrom=from_link)\n\n## Coding Agent CLI / TUI\n\nAI4J 目前已经内置 `ai4j-cli`，可以直接作为本地 coding agent 使用，支持：\n\n+ one-shot 与持续会话\n+ CLI / TUI 两种交互模式\n+ provider profile 持久化\n+ workspace 级 model override\n+ subagent 与 agent teams 协作\n+ session 持久化、resume、fork、history、tree、events、replay\n+ team board、team messages、team resume 等协作观测能力\n+ process 管理与日志查看\n\n### 安装\n\n```bash\ncurl -fsSL https://lnyo-cly.github.io/ai4j/install.sh | sh\n```\n\n```powershell\nirm https://lnyo-cly.github.io/ai4j/install.ps1 | iex\n```\n\n安装脚本会从 Maven Central 下载 `ai4j-cli` 并生成 `ai4j` 命令，前提是本机已经安装 Java 8+。\n\n### one-shot 示例\n\n```powershell\nai4j code `\n --provider openai `\n --protocol responses `\n --model gpt-5-mini `\n --prompt \"Read README and summarize the project structure\"\n```\n\n### 交互式 CLI 示例\n\n```powershell\nai4j code `\n --provider zhipu `\n --protocol chat `\n --model glm-4.7 `\n --base-url https://open.bigmodel.cn/api/coding/paas/v4 `\n --workspace .\n```\n\n### TUI 示例\n\n```powershell\nai4j tui `\n --provider zhipu `\n --protocol chat `\n --model glm-4.7 `\n --base-url https://open.bigmodel.cn/api/coding/paas/v4 `\n --workspace .\n```\n\n### ACP 示例\n\n```powershell\nai4j acp `\n --provider openai `\n --protocol responses `\n --model gpt-5-mini `\n --workspace .\n```\n\n### 源码构建（可选）\n\n```powershell\nmvn -pl ai4j-cli -am -DskipTests package\n```\n\n产物示例：\n\n```text\nai4j-cli/target/ai4j-cli--jar-with-dependencies.jar\n```\n\n如果你需要直接运行本地构建产物：\n\n```powershell\njava -jar .\\ai4j-cli\\target\\ai4j-cli--jar-with-dependencies.jar code --help\n```\n\n### 当前协议规则\n\n当前 CLI 对用户只暴露两种协议：\n\n+ `chat`\n+ `responses`\n\n如果省略 `--protocol`，会按 provider/baseUrl 在本地推导默认值：\n\n+ `openai` + 官方 OpenAI host -> `responses`\n+ `openai` + 自定义兼容 `baseUrl` -> `chat`\n+ `doubao` / `dashscope` -> `responses`\n+ 其他 provider -> `chat`\n\n注意：\n\n+ 不再对用户暴露 `auto`\n+ 旧配置中的 `auto` 会在读取时自动归一化为显式协议\n\n### provider profile 配置位置\n\n+ 全局配置：`~/.ai4j/providers.json`\n+ 工作区配置：`/.ai4j/workspace.json`\n\n推荐工作流：\n\n+ 全局保存长期可复用 profile\n+ workspace 只引用当前 activeProfile\n+ 临时切模型时使用 workspace 的 `modelOverride`\n\n`workspace.json` 也可以显式挂载额外 skill 目录：\n\n```json\n{\n \"activeProfile\": \"openai-main\",\n \"modelOverride\": \"gpt-5-mini\",\n \"enabledMcpServers\": [\"fetch\"],\n \"skillDirectories\": [\n \".ai4j/skills\",\n \"C:/skills/team\",\n \"../shared-skills\"\n ]\n}\n```\n\nskill 发现规则：\n\n+ 默认扫描 `/.ai4j/skills`\n+ 默认扫描 `~/.ai4j/skills`\n+ `skillDirectories` 中的相对路径按 workspace 根目录解析\n+ 进入 CLI 后可用 `/skills` 查看当前发现到的 skill\n+ 可用 `/skills ` 查看某个 skill 的路径、来源、描述和扫描 roots，不打印 `SKILL.md` 正文\n\n### `/stream`、`Esc` 与状态提示\n\n当前 `/stream` 的语义是“当前 CLI 会话里的模型请求是否启用 `stream`”，不是单纯的 transcript 渲染开关：\n\n+ 作用域是当前 CLI 会话\n+ `/stream on|off` 会切换请求级 `stream=true|false`，并立即重建当前 session runtime\n+ `on` 时 provider 响应按增量到达，assistant 文本也按增量呈现\n+ `off` 时等待完整响应后再输出整理后的完成块\n+ 流式 event 粒度由上游 provider/SSE 决定，不保证“一个 event = 一个 token”\n+ 如果通过 ACP/IDE 接入，宿主应按收到的 chunk 顺序渲染，并保留换行与空白\n\n当前交互壳层里：\n\n+ `Esc` 在活跃 turn 中断当前任务；空闲时关闭 palette 或清空输入\n+ 状态栏会显示 `Thinking`、`Connecting`、`Responding`、`Working`、`Retrying`\n+ 一段时间没有新进展会升级为 `Waiting`\n+ 更久没有新进展会显示 `Stalled`，并提示 `press Esc to interrupt`\n\n### 常用命令\n\n+ `/providers`\n+ `/provider`\n+ `/provider use `\n+ `/provider save `\n+ `/provider add --provider [--protocol ] [--model ] [--base-url ] [--api-key ]`\n+ `/provider edit [--provider ] [--protocol ] [--model |--clear-model] [--base-url |--clear-base-url] [--api-key |--clear-api-key]`\n+ `/provider default `\n+ `/provider remove `\n+ `/model`\n+ `/model `\n+ `/model reset`\n+ `/skills`\n+ `/skills `\n+ `/stream [on|off]`\n+ `/processes`\n+ `/process status|follow|logs|write|stop ...`\n+ `/resume ` / `/load ` / `/fork ...`\n\n### 文档入口\n\n+ [Coding Agent 总览](docs-site/docs/coding-agent/overview.md)\n+ [Coding Agent 快速开始](docs-site/docs/coding-agent/quickstart.md)\n+ [CLI / TUI 使用指南](docs-site/docs/coding-agent/cli-and-tui.md)\n+ [会话、流式与进程](docs-site/docs/coding-agent/session-runtime.md)\n+ [配置体系](docs-site/docs/coding-agent/configuration.md)\n+ [Tools 与审批机制](docs-site/docs/coding-agent/tools-and-approvals.md)\n+ [Skills 使用与组织](docs-site/docs/coding-agent/skills.md)\n+ [MCP 对接](docs-site/docs/coding-agent/mcp-integration.md)\n+ [ACP 集成](docs-site/docs/coding-agent/acp-integration.md)\n+ [TUI 定制与主题](docs-site/docs/coding-agent/tui-customization.md)\n+ [命令参考](docs-site/docs/coding-agent/command-reference.md)\n\n## 其它支持\n+ [[低价中转平台] 低价ApiKey—限时特惠 ](https://api.trovebox.online/)\n+ [[在线平台] 每日白嫖额度-所有模型均可使用 ](https://chat.trovebox.online/)\n\n# 快速开始\n## 导入\n### 模块选型\n+ 只需要基础 LLM / Tool Call / MCP / RAG 能力：引入 `ai4j`\n+ 需要通用 Agent 运行时：引入 `ai4j-agent`\n+ 需要 Coding Agent、workspace tools、outer loop：引入 `ai4j-coding`\n+ 需要本地 CLI / TUI / ACP 宿主：引入 `ai4j-cli`\n+ 需要 Spring Boot 自动配置：引入 `ai4j-spring-boot-starter`\n+ 需要 FlowGram 工作流集成：引入 `ai4j-flowgram-spring-boot-starter`\n+ 同时引入多个模块：建议额外引入 `ai4j-bom`\n\n### Gradle\n```groovy\nimplementation platform(\"io.github.lnyo-cly:ai4j-bom:${project.version}\")\nimplementation \"io.github.lnyo-cly:ai4j\"\nimplementation \"io.github.lnyo-cly:ai4j-agent\"\n```\n\n```groovy\nimplementation group: 'io.github.lnyo-cly', name: 'ai4j', version: '${project.version}'\n```\n\n```groovy\nimplementation group: 'io.github.lnyo-cly', name: 'ai4j-spring-boot-starter', version: '${project.version}'\n```\n\n\n### Maven\n```xml\n\n \n \n io.github.lnyo-cly \n ai4j-bom \n ${project.version} \n pom \n import \n \n \n \n```\n\n```xml\n\n\n io.github.lnyo-cly \n ai4j-agent \n \n\n\n io.github.lnyo-cly \n ai4j-coding \n \n```\n\n```xml\n\n\n io.github.lnyo-cly \n ai4j \n ${project.version} \n \n\n```\n```xml\n\n\n io.github.lnyo-cly \n ai4j-spring-boot-starter \n ${project.version} \n \n```\n\n## 获取AI服务实例\n\n### 非Spring获取\n```java\n public void test_init(){\n OpenAiConfig openAiConfig = new OpenAiConfig();\n\n Configuration configuration = new Configuration();\n configuration.setOpenAiConfig(openAiConfig);\n\n HttpLoggingInterceptor httpLoggingInterceptor = new HttpLoggingInterceptor();\n httpLoggingInterceptor.setLevel(HttpLoggingInterceptor.Level.HEADERS);\n\n OkHttpClient okHttpClient = new OkHttpClient\n .Builder()\n .addInterceptor(httpLoggingInterceptor)\n .addInterceptor(new ErrorInterceptor())\n .connectTimeout(300, TimeUnit.SECONDS)\n .writeTimeout(300, TimeUnit.SECONDS)\n .readTimeout(300, TimeUnit.SECONDS)\n .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress(\"127.0.0.1\",10809)))\n .build();\n configuration.setOkHttpClient(okHttpClient);\n\n AiService aiService = new AiService(configuration);\n\n embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);\n chatService = aiService.getChatService(PlatformType.getPlatform(\"OPENAI\"));\n\n }\n```\n### Spring获取\n```yml\n# 国内访问默认需要代理\nai:\n openai:\n api-key: \"api-key\"\n okhttp:\n proxy-port: 10809\n proxy-url: \"127.0.0.1\"\n zhipu:\n api-key: \"xxx\"\n #other...\n```\n\n```java\n// 注入Ai服务\n@Autowired\nprivate AiService aiService;\n\n// 获取需要的服务实例\nIChatService chatService = aiService.getChatService(PlatformType.OPENAI);\nIEmbeddingService embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);\n// ......\n```\n\n## Chat服务\n\n### 同步请求调用\n```java\n\npublic void test_chat() throws Exception {\n // 获取chat服务实例\n IChatService chatService = aiService.getChatService(PlatformType.OPENAI);\n\n // 构建请求参数\n ChatCompletion chatCompletion = ChatCompletion.builder()\n .model(\"gpt-4o-mini\")\n .message(ChatMessage.withUser(\"鲁迅为什么打周树人\"))\n .build();\n\n // 发送对话请求\n ChatCompletionResponse response = chatService.chatCompletion(chatCompletion);\n\n System.out.println(response);\n}\n\n```\n\n### 流式调用\n```java\npublic void test_chat_stream() throws Exception {\n // 获取chat服务实例\n IChatService chatService = aiService.getChatService(PlatformType.OPENAI);\n\n // 构造请求参数\n ChatCompletion chatCompletion = ChatCompletion.builder()\n .model(\"gpt-4o-mini\")\n .message(ChatMessage.withUser(\"查询北京明天的天气\"))\n .functions(\"queryWeather\")\n .build();\n\n\n // 构造监听器\n SseListener sseListener = new SseListener() {\n @Override\n protected void send() {\n System.out.println(this.getCurrStr());\n }\n };\n // 显示函数参数，默认不显示\n sseListener.setShowToolArgs(true);\n\n // 发送SSE请求\n chatService.chatCompletionStream(chatCompletion, sseListener);\n\n System.out.println(sseListener.getOutput());\n\n}\n```\n\n### 图片识别\n\n```java\npublic void test_chat_image() throws Exception {\n // 获取chat服务实例\n IChatService chatService = aiService.getChatService(PlatformType.OPENAI);\n\n // 构建请求参数\n ChatCompletion chatCompletion = ChatCompletion.builder()\n .model(\"gpt-4o-mini\")\n .message(ChatMessage.withUser(\"图片中有什么东西\", \"https://cn.bing.com/images/search?view=detailV2&ccid=r0OnuYkv&id=9A07DE578F6ED50DB59DFEA5C675AC71845A6FC9&thid=OIP.r0OnuYkvsbqBrYk3kUT53AHaKX&mediaurl=https%3a%2f%2fimg.zcool.cn%2fcommunity%2f0104c15cd45b49a80121416816f1ec.jpg%401280w_1l_2o_100sh.jpg&exph=1792&expw=1280&q=%e5%b0%8f%e7%8c%ab%e5%9b%be%e7%89%87&simid=607987191780608963&FORM=IRPRST&ck=12127C1696CF374CB9D0F09AE99AFE69&selectedIndex=2&itb=0&qpvt=%e5%b0%8f%e7%8c%ab%e5%9b%be%e7%89%87\"))\n .build();\n\n // 发送对话请求\n ChatCompletionResponse response = chatService.chatCompletion(chatCompletion);\n\n System.out.println(response);\n}\n```\n\n### 函数调用\n\n```java\npublic void test_chat_tool_call() throws Exception {\n // 获取chat服务实例\n IChatService chatService = aiService.getChatService(PlatformType.OPENAI);\n\n // 构建请求参数\n ChatCompletion chatCompletion = ChatCompletion.builder()\n .model(\"gpt-4o-mini\")\n .message(ChatMessage.withUser(\"今天北京天气怎么样\"))\n .functions(\"queryWeather\")\n .build();\n\n // 发送对话请求\n ChatCompletionResponse response = chatService.chatCompletion(chatCompletion);\n\n System.out.println(response);\n}\n```\n\n### 内置 ChatMemory\n\n如果你只是做基础多轮对话，不想自己每轮维护完整上下文，可以直接使用 `ChatMemory`：\n\n```java\nIChatService chatService = aiService.getChatService(PlatformType.OPENAI);\n\nChatMemory memory = new InMemoryChatMemory(new MessageWindowChatMemoryPolicy(12));\nmemory.addSystem(\"你是一个简洁的 Java 助手\");\nmemory.addUser(\"请用三点介绍 AI4J\");\n\nChatCompletion request = ChatCompletion.builder()\n .model(\"gpt-4o-mini\")\n .messages(memory.toChatMessages())\n .build();\n\nChatCompletionResponse response = chatService.chatCompletion(request);\nString answer = response.getChoices().get(0).getMessage().getContent().getText();\n\nmemory.addAssistant(answer);\n```\n\n同一份 `memory` 也可以直接给 `Responses`：\n\n```java\nIResponsesService responsesService = aiService.getResponsesService(PlatformType.DOUBAO);\n\nResponseRequest request = ResponseRequest.builder()\n .model(\"doubao-seed-1-8-251228\")\n .input(memory.toResponsesInput())\n .build();\n```\n#### 定义函数\n```java\n@FunctionCall(name = \"queryWeather\", description = \"查询目标地点的天气预报\")\npublic class QueryWeatherFunction implements Function {\n\n @Data\n @FunctionRequest\n public static class Request{\n @FunctionParameter(description = \"需要查询天气的目标位置, 可以是城市中文名、城市拼音/英文名、省市名称组合、IP 地址、经纬度\")\n private String location;\n @FunctionParameter(description = \"需要查询未来天气的天数, 最多15日\")\n private int days = 15;\n @FunctionParameter(description = \"预报的天气类型，daily表示预报多天天气、hourly表示预测当天24天气、now为当前天气实况\")\n private Type type;\n }\n\n public enum Type{\n daily,\n hourly,\n now\n }\n\n @Override\n public String apply(Request request) {\n final String key = \"\";\n\n String url = String.format(\"https://api.seniverse.com/v3/weather/%s.json?key=%s&location=%s&days=%d\",\n request.type.name(),\n key,\n request.location,\n request.days);\n\n\n OkHttpClient client = new OkHttpClient();\n\n okhttp3.Request http = new okhttp3.Request.Builder()\n .url(url)\n .get()\n .build();\n\n try (Response response = client.newCall(http).execute()) {\n if (response.isSuccessful()) {\n // 解析响应体\n return response.body() != null ? response.body().string() : \"\";\n } else {\n return \"获取天气失败 当前天气未知\";\n }\n } catch (Exception e) {\n // 处理异常\n e.printStackTrace();\n return \"获取天气失败 当前天气未知\";\n }\n }\n\n}\n```\n\n## Embedding服务\n\n```java\npublic void test_embed() throws Exception {\n // 获取embedding服务实例\n IEmbeddingService embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);\n\n // 构建请求参数\n Embedding embeddingReq = Embedding.builder().input(\"1+1\").build();\n\n // 发送embedding请求\n EmbeddingResponse embeddingResp = embeddingService.embedding(embeddingReq);\n\n System.out.println(embeddingResp);\n}\n```\n\n## Rerank服务\n\n### 直接调用统一重排服务\n\n```java\nIRerankService rerankService = aiService.getRerankService(PlatformType.JINA);\n\nRerankRequest request = RerankRequest.builder()\n .model(\"jina-reranker-v2-base-multilingual\")\n .query(\"哪段最适合回答 Java 8 为什么仍然常见\")\n .documents(Arrays.asList(\n RerankDocument.builder().id(\"doc-1\").text(\"Java 8 仍是很多传统系统的默认运行时\").build(),\n RerankDocument.builder().id(\"doc-2\").text(\"AI4J 提供统一 Chat、Responses 和 RAG 接口\").build(),\n RerankDocument.builder().id(\"doc-3\").text(\"历史中间件和升级成本让很多企业延后 JDK 升级\").build()\n ))\n .topN(2)\n .build();\n\nRerankResponse response = rerankService.rerank(request);\nSystem.out.println(response.getResults());\n```\n\n### 作为 RAG 精排器接入\n\n```java\nReranker reranker = aiService.getModelReranker(\n PlatformType.JINA,\n \"jina-reranker-v2-base-multilingual\",\n 5,\n \"优先保留制度原文、版本说明和编号明确的片段\"\n);\n```\n\n## RAG\n### 推荐：使用统一 IngestionPipeline 入库\n\n```java\nVectorStore vectorStore = aiService.getQdrantVectorStore();\n\nIngestionPipeline ingestionPipeline = aiService.getIngestionPipeline(\n PlatformType.OPENAI,\n vectorStore\n);\n\nIngestionResult ingestResult = ingestionPipeline.ingest(IngestionRequest.builder()\n .dataset(\"kb_docs\")\n .embeddingModel(\"text-embedding-3-small\")\n .document(RagDocument.builder()\n .sourceName(\"员工手册\")\n .sourcePath(\"/docs/employee-handbook.md\")\n .tenant(\"acme\")\n .biz(\"hr\")\n .version(\"2026.03\")\n .build())\n .source(IngestionSource.text(\"第一章 假期政策。第二章 报销政策。\"))\n .build());\n\nSystem.out.println(ingestResult.getUpsertedCount());\n```\n\n如果你已经走 Pinecone，也可以直接：\n\n```java\nIngestionPipeline ingestionPipeline = aiService.getPineconeIngestionPipeline(PlatformType.OPENAI);\n```\n\n推荐主线是：\n\n1. `IngestionPipeline` 负责文档入库\n2. `VectorStore` 负责底层向量存储\n3. `DenseRetriever / HybridRetriever / ModelReranker / RagService` 负责查询阶段\n\n完整说明见：\n\n+ `docs-site/docs/ai-basics/rag/ingestion-pipeline.md`\n+ `docs-site/docs/ai-basics/rag/overview.md`\n\n### 配置向量数据库\n```yml\nai:\n vector:\n pinecone:\n host: \"\"\n key: \"\"\n```\n### 推荐：Pinecone 也走统一 `VectorStore + IngestionPipeline`\n\n```java\nVectorStore vectorStore = aiService.getPineconeVectorStore();\n\nIngestionPipeline ingestionPipeline = aiService.getPineconeIngestionPipeline(PlatformType.OPENAI);\n\nIngestionResult ingestResult = ingestionPipeline.ingest(IngestionRequest.builder()\n .dataset(\"tenant_a_hr_v202603\")\n .embeddingModel(\"text-embedding-3-small\")\n .document(RagDocument.builder()\n .sourceName(\"员工手册\")\n .sourcePath(\"/docs/employee-handbook.pdf\")\n .tenant(\"tenant_a\")\n .biz(\"hr\")\n .version(\"2026.03\")\n .build())\n .source(IngestionSource.file(new File(\"D:/data/employee-handbook.pdf\")))\n .build());\n\nSystem.out.println(\"upserted=\" + ingestResult.getUpsertedCount());\n```\n\n### 查询阶段：直接走统一 `RagService`\n\n```java\nRagService ragService = aiService.getRagService(\n PlatformType.OPENAI,\n vectorStore\n);\n\nRagQuery ragQuery = RagQuery.builder()\n .query(\"年假如何计算\")\n .dataset(\"tenant_a_hr_v202603\")\n .embeddingModel(\"text-embedding-3-small\")\n .topK(5)\n .build();\n\nRagResult ragResult = ragService.search(ragQuery);\n\nSystem.out.println(ragResult.getContext());\nSystem.out.println(ragResult.getCitations());\n```\n\n### 如果需要更高精度，再接 Rerank\n\n```java\nReranker reranker = aiService.getModelReranker(\n PlatformType.JINA,\n \"jina-reranker-v2-base-multilingual\",\n 5,\n \"优先制度原文、章节标题和编号明确的片段\"\n);\n\nRagService ragService = new DefaultRagService(\n new DenseRetriever(\n aiService.getEmbeddingService(PlatformType.OPENAI),\n vectorStore\n ),\n reranker,\n new DefaultRagContextAssembler()\n);\n```\n\n### 什么时候还需要直接用已废弃的 `PineconeService`（Deprecated）\n\n`PineconeService` 目前在文档层已视为 Deprecated。只有在你明确需要 Pinecone 特有的底层控制时，才建议继续直接用：\n\n+ namespace 级底层操作\n+ 兼容旧项目里已经写死的 `PineconeQuery / PineconeDelete`\n+ 你就是在做 Pinecone 专用封装，而不是面向统一 RAG 抽象开发\n\n## 内置联网\n\n### SearXNG\n\n#### 配置\n```java\n// 非spring应用\nSearXNGConfig searXNGConfig = new SearXNGConfig();\nsearXNGConfig.setUrl(\"http://127.0.0.1:8080/search\");\n\nConfiguration configuration = new Configuration();\nconfiguration.setSearXNGConfig(searXNGConfig);\n```\n\n```YML\n# spring应用\nai:\n websearch:\n searxng:\n url: http://127.0.0.1:8080/search\n\n```\n\n#### 使用\n\n```java\n\n// ...\n\nwebEnhance = aiService.webSearchEnhance(chatService);\n\n// ...\n\n\n@Test\npublic void test_chatCompletions_common_websearch_enhance() throws Exception {\n ChatCompletion chatCompletion = ChatCompletion.builder()\n .model(\"qwen2.5:7b\")\n .message(ChatMessage.withUser(\"鸡你太美是什么梗\"))\n .build();\n\n System.out.println(\"请求参数\");\n System.out.println(chatCompletion);\n\n ChatCompletionResponse chatCompletionResponse = webEnhance.chatCompletion(chatCompletion);\n\n System.out.println(\"请求成功\");\n System.out.println(chatCompletionResponse);\n\n}\n```\n\n\n# 为AI4J提供贡献\n欢迎您对AI4J提出建议、报告问题或贡献代码。您可以按照以下的方式为AI4J提供贡献: \n\n## 问题反馈\n请使用GitHub Issue页面报告问题。尽可能具体地说明如何重现您的问题，包括操作系统、Java版本和任何相关日志跟踪等详细信息。\n\n## PR\n1. Fork 本仓库并创建您的分支（建议命名：feature/功能名、fix/问题名 或 docs/文档优化）。\n2. 编写代码或修改内容（如更新文档），并完成测试（确保功能正常或文档无误）。\n3. 确保您的代码符合现有的样式。\n4. 提交时编写清晰的日志信息。对于小的改动，单行信息就可以了，但较大的改动应该有详细的描述。\n5. 完成拉取请求表单，确保在`dev`分支进行改动，链接到您的 PR 解决的问题。\n\n# 支持\n如果您觉得这个项目对您有帮助，请点一个star⭐。\n\n# Buy Me a Coffee\n您的支持是我更新的最大的动力。\n\n\n\n# 贡献者\n\n\n\n\n\n\n\n\n\n\n\n \n\n\n# ⭐️ Star History\n\n \n \n \n\n"
},
{
"path": "ai4j/pom.xml",
"content": "\n\n 4.0.0 \n\n io.github.lnyo-cly \n ai4j \n jar \n 2.3.0 \n\n ai4j \n ai4j 核心 Java SDK，提供统一大模型接入、Tool Call、RAG 与 MCP 能力。 Core Java SDK for unified LLM access, tool calling, RAG, and MCP integration. \n\n\n \n 8 \n 8 \n UTF-8 \n true \n 20.3.4 \n ${graalvm.version} \n 15.6 \n \n \n \n The Apache License, Version 2.0 \n https://www.apache.org/licenses/LICENSE-2.0.txt \n \n \n\n \n GitHub \n https://github.com/LnYo-Cly/ai4j/issues \n \n\n https://github.com/LnYo-Cly/ai4j \n \n \n LnYo-Cly \n LnYo-Cly \n lnyocly@gmail.com \n https://github.com/LnYo-Cly/ai4j \n +8 \n \n \n\n \n \n https://github.com/LnYo-Cly/ai4j \n \n scm:git:https://github.com/LnYo-Cly/ai4j.git \n \n scm:git:https://github.com/LnYo-Cly/ai4j.git \n \n\n \n \n \n org.slf4j \n slf4j-simple \n 1.7.30 \n \n \n \n org.apache.tika \n tika-core \n 2.9.2 \n \n \n org.apache.tika \n tika-parsers-standard-package \n 2.8.0 \n \n \n com.knuddels \n jtokkit \n 1.1.0 \n \n \n org.projectlombok \n lombok \n 1.18.30 \n \n \n \n org.slf4j \n slf4j-api \n 1.7.30 \n \n\n \n org.reflections \n reflections \n 0.10.2 \n \n \n junit \n junit \n 4.13.2 \n test \n \n \n com.h2database \n h2 \n 2.2.224 \n test \n \n \n com.squareup.okhttp3 \n mockwebserver \n 4.12.0 \n test \n \n \n \n com.alibaba.fastjson2 \n fastjson2 \n 2.0.43 \n \n \n \n com.fasterxml.jackson.core \n jackson-annotations \n 2.16.0 \n \n \n com.fasterxml.jackson.core \n jackson-databind \n 2.14.2 \n \n\n \n \n com.squareup.okhttp3 \n okhttp \n 4.12.0 \n \n \n \n com.squareup.okhttp3 \n okhttp-sse \n 4.12.0 \n \n \n \n com.squareup.okhttp3 \n logging-interceptor \n 4.12.0 \n \n \n \n com.google.guava \n guava \n 33.0.0-jre \n \n \n org.apache.commons \n commons-lang3 \n 3.12.0 \n \n \n \n com.auth0 \n java-jwt \n 4.4.0 \n \n \n cn.hutool \n hutool-core \n 5.8.38 \n \n \n com.alibaba \n dashscope-sdk-java \n compile \n 2.19.0 \n \n \n org.jetbrains \n annotations \n 13.0 \n \n\n \n \n org.graalvm.sdk \n graal-sdk \n ${graalsdk.version} \n \n \n\n \n ${project.name}-${project.version} \n \n \n org.apache.maven.plugins \n maven-surefire-plugin \n 2.12.4 \n \n ${skipTests} \n \n \n \n org.apache.maven.plugins \n maven-compiler-plugin \n 3.8.1 \n \n 1.8 \n 1.8 \n UTF8 \n \n -parameters \n \n true \n \n \n org.projectlombok \n lombok \n 1.18.30 \n \n \n \n \n\n \n \n\n\n\n \n \n nashorn-runtime \n \n [15,) \n \n \n \n org.openjdk.nashorn \n nashorn-core \n ${nashorn.version} \n runtime \n \n \n \n \n graalpy-runtime \n \n [17,) \n \n \n 24.1.2 \n \n \n \n org.graalvm.python \n python-community \n ${graalsdk.version} \n pom \n runtime \n \n \n \n\n \n release \n \n \n \n \n org.apache.maven.plugins \n maven-source-plugin \n 3.3.1 \n \n \n attach-sources \n \n jar-no-fork \n \n \n \n \n\n \n \n org.apache.maven.plugins \n maven-javadoc-plugin \n 3.6.3 \n \n \n attach-javadocs \n \n jar \n \n \n none \n false \n \n \n Author \n a \n Author:\n \n \n Description \n a \n Description:\n \n \n Date \n a \n Date:\n \n \n \n \n\n \n \n\n \n \n org.apache.maven.plugins \n maven-gpg-plugin \n 1.6 \n \n D:\\Develop\\DevelopEnv\\GnuPG\\bin\\gpg.exe \n cly \n \n \n \n sign-artifacts \n verify \n \n sign \n \n \n \n \n\n \n \n org.sonatype.central \n central-publishing-maven-plugin \n 0.4.0 \n true \n \n LnYo-Cly \n true \n \n \n \n \n \n \n\n \n\n\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/AgentFlow.java",
"content": "package io.github.lnyocly.ai4j.agentflow;\n\nimport io.github.lnyocly.ai4j.agentflow.chat.AgentFlowChatService;\nimport io.github.lnyocly.ai4j.agentflow.chat.CozeAgentFlowChatService;\nimport io.github.lnyocly.ai4j.agentflow.chat.DifyAgentFlowChatService;\nimport io.github.lnyocly.ai4j.agentflow.workflow.AgentFlowWorkflowService;\nimport io.github.lnyocly.ai4j.agentflow.workflow.CozeAgentFlowWorkflowService;\nimport io.github.lnyocly.ai4j.agentflow.workflow.DifyAgentFlowWorkflowService;\nimport io.github.lnyocly.ai4j.agentflow.workflow.N8nAgentFlowWorkflowService;\nimport io.github.lnyocly.ai4j.service.Configuration;\n\npublic class AgentFlow {\n\n private final Configuration configuration;\n private final AgentFlowConfig config;\n\n public AgentFlow(Configuration configuration, AgentFlowConfig config) {\n if (configuration == null) {\n throw new IllegalArgumentException(\"configuration is required\");\n }\n if (config == null) {\n throw new IllegalArgumentException(\"agentFlowConfig is required\");\n }\n this.configuration = configuration;\n this.config = config;\n }\n\n public Configuration getConfiguration() {\n return configuration;\n }\n\n public AgentFlowConfig getConfig() {\n return config;\n }\n\n public AgentFlowChatService chat() {\n if (config.getType() == AgentFlowType.DIFY) {\n return new DifyAgentFlowChatService(configuration, config);\n }\n if (config.getType() == AgentFlowType.COZE) {\n return new CozeAgentFlowChatService(configuration, config);\n }\n throw new IllegalArgumentException(\"Chat is not supported for agent flow type: \" + config.getType());\n }\n\n public AgentFlowWorkflowService workflow() {\n if (config.getType() == AgentFlowType.DIFY) {\n return new DifyAgentFlowWorkflowService(configuration, config);\n }\n if (config.getType() == AgentFlowType.COZE) {\n return new CozeAgentFlowWorkflowService(configuration, config);\n }\n if (config.getType() == AgentFlowType.N8N) {\n return new N8nAgentFlowWorkflowService(configuration, config);\n }\n throw new IllegalArgumentException(\"Workflow is not supported for agent flow type: \" + config.getType());\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/AgentFlowConfig.java",
"content": "package io.github.lnyocly.ai4j.agentflow;\n\nimport io.github.lnyocly.ai4j.agentflow.trace.AgentFlowTraceListener;\nimport lombok.AccessLevel;\nimport lombok.AllArgsConstructor;\nimport lombok.Builder;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\nimport lombok.NonNull;\n\nimport java.util.Collections;\nimport java.util.List;\nimport java.util.Map;\n\n@Data\n@Builder(toBuilder = true)\n@NoArgsConstructor(access = AccessLevel.PRIVATE)\n@AllArgsConstructor(access = AccessLevel.PRIVATE)\npublic class AgentFlowConfig {\n\n @NonNull\n private AgentFlowType type;\n\n private String baseUrl;\n\n private String webhookUrl;\n\n private String apiKey;\n\n private String botId;\n\n private String workflowId;\n\n private String appId;\n\n private String userId;\n\n private String conversationId;\n\n @Builder.Default\n private Long pollIntervalMillis = 1_000L;\n\n @Builder.Default\n private Long pollTimeoutMillis = 60_000L;\n\n @Builder.Default\n private Map headers = Collections.emptyMap();\n\n @Builder.Default\n private List traceListeners = Collections.emptyList();\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/AgentFlowException.java",
"content": "package io.github.lnyocly.ai4j.agentflow;\n\npublic class AgentFlowException extends RuntimeException {\n\n public AgentFlowException(String message) {\n super(message);\n }\n\n public AgentFlowException(String message, Throwable cause) {\n super(message, cause);\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/AgentFlowType.java",
"content": "package io.github.lnyocly.ai4j.agentflow;\n\npublic enum AgentFlowType {\n DIFY,\n COZE,\n N8N\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/AgentFlowUsage.java",
"content": "package io.github.lnyocly.ai4j.agentflow;\n\nimport lombok.AccessLevel;\nimport lombok.AllArgsConstructor;\nimport lombok.Builder;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n@Data\n@Builder(toBuilder = true)\n@NoArgsConstructor(access = AccessLevel.PRIVATE)\n@AllArgsConstructor(access = AccessLevel.PRIVATE)\npublic class AgentFlowUsage {\n\n private Integer inputTokens;\n\n private Integer outputTokens;\n\n private Integer totalTokens;\n\n private Object raw;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/chat/AgentFlowChatEvent.java",
"content": "package io.github.lnyocly.ai4j.agentflow.chat;\n\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowUsage;\nimport lombok.AccessLevel;\nimport lombok.AllArgsConstructor;\nimport lombok.Builder;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n@Data\n@Builder(toBuilder = true)\n@NoArgsConstructor(access = AccessLevel.PRIVATE)\n@AllArgsConstructor(access = AccessLevel.PRIVATE)\npublic class AgentFlowChatEvent {\n\n private String type;\n\n private String contentDelta;\n\n private String conversationId;\n\n private String messageId;\n\n private String taskId;\n\n private boolean done;\n\n private AgentFlowUsage usage;\n\n private Object raw;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/chat/AgentFlowChatListener.java",
"content": "package io.github.lnyocly.ai4j.agentflow.chat;\n\npublic interface AgentFlowChatListener {\n\n void onEvent(AgentFlowChatEvent event);\n\n default void onOpen() {\n }\n\n default void onError(Throwable throwable) {\n }\n\n default void onComplete(AgentFlowChatResponse response) {\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/chat/AgentFlowChatRequest.java",
"content": "package io.github.lnyocly.ai4j.agentflow.chat;\n\nimport lombok.AccessLevel;\nimport lombok.AllArgsConstructor;\nimport lombok.Builder;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\nimport lombok.NonNull;\n\nimport java.util.Collections;\nimport java.util.Map;\n\n@Data\n@Builder(toBuilder = true)\n@NoArgsConstructor(access = AccessLevel.PRIVATE)\n@AllArgsConstructor(access = AccessLevel.PRIVATE)\npublic class AgentFlowChatRequest {\n\n @NonNull\n private String prompt;\n\n @Builder.Default\n private Map inputs = Collections.emptyMap();\n\n private String userId;\n\n private String conversationId;\n\n @Builder.Default\n private Map metadata = Collections.emptyMap();\n\n @Builder.Default\n private Map extraBody = Collections.emptyMap();\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/chat/AgentFlowChatResponse.java",
"content": "package io.github.lnyocly.ai4j.agentflow.chat;\n\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowUsage;\nimport lombok.AccessLevel;\nimport lombok.AllArgsConstructor;\nimport lombok.Builder;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n@Data\n@Builder(toBuilder = true)\n@NoArgsConstructor(access = AccessLevel.PRIVATE)\n@AllArgsConstructor(access = AccessLevel.PRIVATE)\npublic class AgentFlowChatResponse {\n\n private String content;\n\n private String conversationId;\n\n private String messageId;\n\n private String taskId;\n\n private AgentFlowUsage usage;\n\n private Object raw;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/chat/AgentFlowChatService.java",
"content": "package io.github.lnyocly.ai4j.agentflow.chat;\n\npublic interface AgentFlowChatService {\n\n AgentFlowChatResponse chat(AgentFlowChatRequest request) throws Exception;\n\n void chatStream(AgentFlowChatRequest request, AgentFlowChatListener listener) throws Exception;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/chat/CozeAgentFlowChatService.java",
"content": "package io.github.lnyocly.ai4j.agentflow.chat;\n\nimport com.alibaba.fastjson2.JSON;\nimport com.alibaba.fastjson2.JSONArray;\nimport com.alibaba.fastjson2.JSONObject;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowConfig;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowException;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowUsage;\nimport io.github.lnyocly.ai4j.agentflow.support.AgentFlowSupport;\nimport io.github.lnyocly.ai4j.agentflow.trace.AgentFlowTraceContext;\nimport io.github.lnyocly.ai4j.service.Configuration;\nimport okhttp3.Request;\nimport okhttp3.Response;\nimport okhttp3.sse.EventSource;\nimport okhttp3.sse.EventSourceListener;\nimport org.jetbrains.annotations.NotNull;\nimport org.jetbrains.annotations.Nullable;\n\nimport java.util.Collections;\nimport java.util.LinkedHashMap;\nimport java.util.Map;\nimport java.util.concurrent.CountDownLatch;\nimport java.util.concurrent.TimeUnit;\nimport java.util.concurrent.atomic.AtomicBoolean;\nimport java.util.concurrent.atomic.AtomicReference;\n\npublic class CozeAgentFlowChatService extends AgentFlowSupport implements AgentFlowChatService {\n\n public CozeAgentFlowChatService(Configuration configuration, AgentFlowConfig agentFlowConfig) {\n super(configuration, agentFlowConfig);\n }\n\n @Override\n public AgentFlowChatResponse chat(AgentFlowChatRequest request) throws Exception {\n AgentFlowTraceContext traceContext = startTrace(\"chat\", false, request);\n try {\n JSONObject createResponse = executeObject(buildCreateRequest(request, false));\n assertCozeSuccess(createResponse);\n\n JSONObject createData = createResponse.getJSONObject(\"data\");\n String chatId = createData == null ? null : createData.getString(\"id\");\n String conversationId = firstNonBlank(\n createData == null ? null : createData.getString(\"conversation_id\"),\n defaultConversationId(request.getConversationId())\n );\n if (isBlank(chatId)) {\n throw new AgentFlowException(\"Coze chat id is missing\");\n }\n\n JSONObject chatData = pollChat(conversationId, chatId);\n String status = chatData.getString(\"status\");\n if (!\"completed\".equals(status)) {\n throw new AgentFlowException(\"Coze chat finished with status: \" + status);\n }\n\n JSONObject messageResponse = executeObject(buildMessageListRequest(conversationId, chatId));\n assertCozeSuccess(messageResponse);\n\n JSONArray messages = messageResponse.getJSONArray(\"data\");\n StringBuilder content = new StringBuilder();\n String messageId = null;\n if (messages != null) {\n for (int i = messages.size() - 1; i >= 0; i--) {\n JSONObject message = messages.getJSONObject(i);\n if (message == null) {\n continue;\n }\n if (!\"assistant\".equals(message.getString(\"role\"))) {\n continue;\n }\n String messageContent = message.getString(\"content\");\n if (!isBlank(messageContent)) {\n if (content.length() > 0) {\n content.insert(0, \"\\n\");\n }\n content.insert(0, messageContent);\n if (messageId == null) {\n messageId = message.getString(\"id\");\n }\n }\n }\n }\n\n Map raw = new LinkedHashMap();\n raw.put(\"chat\", chatData);\n raw.put(\"messages\", messages);\n\n AgentFlowChatResponse chatResponse = AgentFlowChatResponse.builder()\n .content(content.toString())\n .conversationId(conversationId)\n .messageId(messageId)\n .taskId(chatId)\n .usage(usageFromCoze(chatData.getJSONObject(\"usage\")))\n .raw(raw)\n .build();\n traceComplete(traceContext, chatResponse);\n return chatResponse;\n } catch (Exception ex) {\n traceError(traceContext, ex);\n throw ex;\n }\n }\n\n @Override\n public void chatStream(AgentFlowChatRequest request, final AgentFlowChatListener listener) throws Exception {\n if (listener == null) {\n throw new IllegalArgumentException(\"listener is required\");\n }\n final AgentFlowTraceContext traceContext = startTrace(\"chat\", true, request);\n Request httpRequest = buildCreateRequest(request, true);\n\n final CountDownLatch latch = new CountDownLatch(1);\n final AtomicReference failure = new AtomicReference();\n final AtomicReference chatIdRef = new AtomicReference();\n final AtomicReference conversationIdRef = new AtomicReference();\n final AtomicReference messageIdRef = new AtomicReference();\n final AtomicReference usageRef = new AtomicReference();\n final AtomicReference completionRef = new AtomicReference();\n final StringBuilder content = new StringBuilder();\n final AtomicBoolean closed = new AtomicBoolean(false);\n final AtomicBoolean sawDelta = new AtomicBoolean(false);\n\n eventSourceFactory.newEventSource(httpRequest, new EventSourceListener() {\n @Override\n public void onOpen(@NotNull EventSource eventSource, @NotNull Response response) {\n listener.onOpen();\n }\n\n @Override\n public void onEvent(@NotNull EventSource eventSource,\n @Nullable String id,\n @Nullable String type,\n @NotNull String data) {\n try {\n String eventType = type;\n JSONObject payload = parseObjectOrNull(data);\n\n if (\"done\".equals(eventType)) {\n AgentFlowChatEvent event = AgentFlowChatEvent.builder()\n .type(eventType)\n .conversationId(conversationIdRef.get())\n .messageId(messageIdRef.get())\n .taskId(chatIdRef.get())\n .done(true)\n .usage(usageRef.get())\n .raw(data)\n .build();\n listener.onEvent(event);\n traceEvent(traceContext, event);\n\n AgentFlowChatResponse responsePayload = AgentFlowChatResponse.builder()\n .content(content.toString())\n .conversationId(conversationIdRef.get())\n .messageId(messageIdRef.get())\n .taskId(chatIdRef.get())\n .usage(usageRef.get())\n .raw(data)\n .build();\n completionRef.set(responsePayload);\n listener.onComplete(responsePayload);\n traceComplete(traceContext, responsePayload);\n closed.set(true);\n eventSource.cancel();\n latch.countDown();\n return;\n }\n\n if (\"error\".equals(eventType)) {\n throw new AgentFlowException(\"Coze stream error: \" + data);\n }\n\n String delta = null;\n if (eventType != null && eventType.startsWith(\"conversation.chat.\")) {\n conversationIdRef.set(firstNonBlank(\n payload == null ? null : payload.getString(\"conversation_id\"),\n conversationIdRef.get()\n ));\n chatIdRef.set(firstNonBlank(\n payload == null ? null : payload.getString(\"id\"),\n chatIdRef.get()\n ));\n AgentFlowUsage usage = payload == null ? null : usageFromCoze(payload.getJSONObject(\"usage\"));\n if (usage != null) {\n usageRef.set(usage);\n }\n if (\"conversation.chat.failed\".equals(eventType) || \"conversation.chat.requires_action\".equals(eventType)) {\n throw new AgentFlowException(\"Coze chat status event: \" + eventType);\n }\n } else if (eventType != null && eventType.startsWith(\"conversation.message.\")) {\n conversationIdRef.set(firstNonBlank(\n payload == null ? null : payload.getString(\"conversation_id\"),\n conversationIdRef.get()\n ));\n chatIdRef.set(firstNonBlank(\n payload == null ? null : payload.getString(\"chat_id\"),\n chatIdRef.get()\n ));\n messageIdRef.set(firstNonBlank(\n payload == null ? null : payload.getString(\"id\"),\n messageIdRef.get()\n ));\n String contentValue = payload == null ? null : payload.getString(\"content\");\n if (\"conversation.message.delta\".equals(eventType)) {\n delta = contentValue;\n if (!isBlank(delta)) {\n content.append(delta);\n sawDelta.set(true);\n }\n } else if (\"conversation.message.completed\".equals(eventType)) {\n if (!sawDelta.get() && !isBlank(contentValue)) {\n content.append(contentValue);\n }\n }\n }\n\n AgentFlowChatEvent event = AgentFlowChatEvent.builder()\n .type(eventType)\n .contentDelta(delta)\n .conversationId(conversationIdRef.get())\n .messageId(messageIdRef.get())\n .taskId(chatIdRef.get())\n .usage(usageRef.get())\n .raw(payload == null ? data : payload)\n .build();\n listener.onEvent(event);\n traceEvent(traceContext, event);\n } catch (Throwable ex) {\n failure.set(ex);\n traceError(traceContext, ex);\n listener.onError(ex);\n closed.set(true);\n eventSource.cancel();\n latch.countDown();\n }\n }\n\n @Override\n public void onClosed(@NotNull EventSource eventSource) {\n if (closed.compareAndSet(false, true)) {\n AgentFlowChatResponse responsePayload = completionRef.get();\n if (responsePayload == null) {\n responsePayload = AgentFlowChatResponse.builder()\n .content(content.toString())\n .conversationId(conversationIdRef.get())\n .messageId(messageIdRef.get())\n .taskId(chatIdRef.get())\n .usage(usageRef.get())\n .build();\n completionRef.set(responsePayload);\n listener.onComplete(responsePayload);\n traceComplete(traceContext, responsePayload);\n }\n latch.countDown();\n }\n }\n\n @Override\n public void onFailure(@NotNull EventSource eventSource, @Nullable Throwable t, @Nullable Response response) {\n Throwable error = t;\n if (error == null && response != null) {\n error = new AgentFlowException(\"Coze stream failed: HTTP \" + response.code());\n }\n if (error == null) {\n error = new AgentFlowException(\"Coze stream failed\");\n }\n failure.set(error);\n traceError(traceContext, error);\n listener.onError(error);\n closed.set(true);\n latch.countDown();\n }\n });\n\n if (!latch.await(pollTimeoutMillis(), TimeUnit.MILLISECONDS)) {\n throw new AgentFlowException(\"Coze stream timed out\");\n }\n if (failure.get() != null) {\n if (failure.get() instanceof Exception) {\n throw (Exception) failure.get();\n }\n throw new AgentFlowException(\"Coze stream failed\", failure.get());\n }\n }\n\n private JSONObject pollChat(String conversationId, String chatId) throws Exception {\n long deadline = System.currentTimeMillis() + pollTimeoutMillis();\n while (true) {\n String url = appendQuery(\n joinedUrl(requireBaseUrl(), \"v3/chat/retrieve\"),\n query(conversationId, chatId)\n );\n JSONObject retrieveResponse = executeObject(jsonRequestBuilder(url).get().build());\n assertCozeSuccess(retrieveResponse);\n JSONObject chatData = retrieveResponse.getJSONObject(\"data\");\n String status = chatData == null ? null : chatData.getString(\"status\");\n if (\"completed\".equals(status) || \"failed\".equals(status) || \"canceled\".equals(status) || \"requires_action\".equals(status)) {\n return chatData == null ? new JSONObject() : chatData;\n }\n if (System.currentTimeMillis() >= deadline) {\n throw new AgentFlowException(\"Coze chat poll timed out\");\n }\n sleep(pollIntervalMillis());\n }\n }\n\n private Request buildCreateRequest(AgentFlowChatRequest request, boolean stream) {\n String conversationId = defaultConversationId(request.getConversationId());\n String url = appendQuery(\n joinedUrl(requireBaseUrl(), \"v3/chat\"),\n queryConversation(conversationId)\n );\n return jsonRequestBuilder(url).post(jsonBody(buildCreateBody(request, stream))).build();\n }\n\n private JSONObject buildCreateBody(AgentFlowChatRequest request, boolean stream) {\n JSONObject body = new JSONObject();\n body.put(\"bot_id\", requireBotId());\n body.put(\"user_id\", defaultUserId(request.getUserId()));\n body.put(\"stream\", stream);\n body.put(\"additional_messages\", Collections.singletonList(userMessage(request.getPrompt())));\n if (request.getInputs() != null && !request.getInputs().isEmpty()) {\n body.put(\"parameters\", request.getInputs());\n }\n if (request.getMetadata() != null && !request.getMetadata().isEmpty()) {\n body.put(\"meta_data\", toStringMap(request.getMetadata()));\n }\n if (!stream && !body.containsKey(\"auto_save_history\")) {\n body.put(\"auto_save_history\", true);\n }\n if (request.getExtraBody() != null && !request.getExtraBody().isEmpty()) {\n body.putAll(request.getExtraBody());\n }\n return body;\n }\n\n private Request buildMessageListRequest(String conversationId, String chatId) {\n String url = appendQuery(\n joinedUrl(requireBaseUrl(), \"v1/conversation/message/list\"),\n queryConversation(conversationId)\n );\n JSONObject body = new JSONObject();\n body.put(\"conversation_id\", conversationId);\n body.put(\"chat_id\", chatId);\n body.put(\"order\", \"asc\");\n body.put(\"limit\", 50);\n if (!isBlank(agentFlowConfig.getBotId())) {\n body.put(\"bot_id\", agentFlowConfig.getBotId());\n }\n return jsonRequestBuilder(url).post(jsonBody(body)).build();\n }\n\n private JSONObject userMessage(String prompt) {\n JSONObject message = new JSONObject();\n message.put(\"role\", \"user\");\n message.put(\"type\", \"question\");\n message.put(\"content\", prompt);\n message.put(\"content_type\", \"text\");\n return message;\n }\n\n private JSONObject parseObjectOrNull(String data) {\n if (isBlank(data)) {\n return null;\n }\n try {\n Object parsed = JSON.parse(data);\n return parsed instanceof JSONObject ? (JSONObject) parsed : null;\n } catch (Exception ex) {\n return null;\n }\n }\n\n private Map queryConversation(String conversationId) {\n Map values = new LinkedHashMap();\n if (!isBlank(conversationId)) {\n values.put(\"conversation_id\", conversationId);\n }\n return values;\n }\n\n private Map query(String conversationId, String chatId) {\n Map values = queryConversation(conversationId);\n if (!isBlank(chatId)) {\n values.put(\"chat_id\", chatId);\n }\n return values;\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/chat/DifyAgentFlowChatService.java",
"content": "package io.github.lnyocly.ai4j.agentflow.chat;\n\nimport com.alibaba.fastjson2.JSON;\nimport com.alibaba.fastjson2.JSONObject;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowConfig;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowException;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowUsage;\nimport io.github.lnyocly.ai4j.agentflow.support.AgentFlowSupport;\nimport io.github.lnyocly.ai4j.agentflow.trace.AgentFlowTraceContext;\nimport io.github.lnyocly.ai4j.service.Configuration;\nimport okhttp3.Request;\nimport okhttp3.Response;\nimport okhttp3.sse.EventSource;\nimport okhttp3.sse.EventSourceListener;\nimport org.jetbrains.annotations.NotNull;\nimport org.jetbrains.annotations.Nullable;\n\nimport java.util.Collections;\nimport java.util.concurrent.CountDownLatch;\nimport java.util.concurrent.TimeUnit;\nimport java.util.concurrent.atomic.AtomicBoolean;\nimport java.util.concurrent.atomic.AtomicReference;\n\npublic class DifyAgentFlowChatService extends AgentFlowSupport implements AgentFlowChatService {\n\n public DifyAgentFlowChatService(Configuration configuration, AgentFlowConfig agentFlowConfig) {\n super(configuration, agentFlowConfig);\n }\n\n @Override\n public AgentFlowChatResponse chat(AgentFlowChatRequest request) throws Exception {\n AgentFlowTraceContext traceContext = startTrace(\"chat\", false, request);\n try {\n JSONObject body = buildRequestBody(request, \"blocking\");\n String url = joinedUrl(requireBaseUrl(), \"v1/chat-messages\");\n JSONObject response = executeObject(jsonRequestBuilder(url).post(jsonBody(body)).build());\n AgentFlowChatResponse chatResponse = mapBlockingResponse(response);\n traceComplete(traceContext, chatResponse);\n return chatResponse;\n } catch (Exception ex) {\n traceError(traceContext, ex);\n throw ex;\n }\n }\n\n @Override\n public void chatStream(AgentFlowChatRequest request, final AgentFlowChatListener listener) throws Exception {\n if (listener == null) {\n throw new IllegalArgumentException(\"listener is required\");\n }\n final AgentFlowTraceContext traceContext = startTrace(\"chat\", true, request);\n JSONObject body = buildRequestBody(request, \"streaming\");\n String url = joinedUrl(requireBaseUrl(), \"v1/chat-messages\");\n Request httpRequest = jsonRequestBuilder(url).post(jsonBody(body)).build();\n\n final CountDownLatch latch = new CountDownLatch(1);\n final AtomicReference failure = new AtomicReference();\n final AtomicReference completion = new AtomicReference();\n final AtomicReference conversationIdRef = new AtomicReference();\n final AtomicReference messageIdRef = new AtomicReference();\n final AtomicReference taskIdRef = new AtomicReference();\n final AtomicReference usageRef = new AtomicReference();\n final StringBuilder content = new StringBuilder();\n final AtomicBoolean closed = new AtomicBoolean(false);\n\n eventSourceFactory.newEventSource(httpRequest, new EventSourceListener() {\n @Override\n public void onOpen(@NotNull EventSource eventSource, @NotNull Response response) {\n listener.onOpen();\n }\n\n @Override\n public void onEvent(@NotNull EventSource eventSource,\n @Nullable String id,\n @Nullable String type,\n @NotNull String data) {\n try {\n JSONObject payload = parseObjectOrNull(data);\n String eventType = firstNonBlank(type, payload == null ? null : payload.getString(\"event\"));\n if (isBlank(eventType) || \"ping\".equals(eventType)) {\n return;\n }\n\n String conversationId = payload == null ? null : payload.getString(\"conversation_id\");\n String messageId = payload == null ? null : firstNonBlank(payload.getString(\"message_id\"), payload.getString(\"id\"));\n String taskId = payload == null ? null : payload.getString(\"task_id\");\n if (!isBlank(conversationId)) {\n conversationIdRef.set(conversationId);\n }\n if (!isBlank(messageId)) {\n messageIdRef.set(messageId);\n }\n if (!isBlank(taskId)) {\n taskIdRef.set(taskId);\n }\n\n AgentFlowUsage usage = payload == null ? null : usageFromDify(metadataUsage(payload));\n if (usage != null) {\n usageRef.set(usage);\n }\n\n String delta = null;\n if (\"message\".equals(eventType) || \"agent_message\".equals(eventType)) {\n delta = payload == null ? null : payload.getString(\"answer\");\n if (!isBlank(delta)) {\n content.append(delta);\n }\n }\n\n boolean done = \"message_end\".equals(eventType);\n AgentFlowChatEvent event = AgentFlowChatEvent.builder()\n .type(eventType)\n .contentDelta(delta)\n .conversationId(conversationIdRef.get())\n .messageId(messageIdRef.get())\n .taskId(taskIdRef.get())\n .done(done)\n .usage(usageRef.get())\n .raw(payload == null ? data : payload)\n .build();\n listener.onEvent(event);\n traceEvent(traceContext, event);\n\n if (\"error\".equals(eventType)) {\n throw new AgentFlowException(\"Dify stream error: \" + (payload == null ? data : payload.toJSONString()));\n }\n if (done) {\n AgentFlowChatResponse responsePayload = AgentFlowChatResponse.builder()\n .content(content.toString())\n .conversationId(conversationIdRef.get())\n .messageId(messageIdRef.get())\n .taskId(taskIdRef.get())\n .usage(usageRef.get())\n .raw(payload)\n .build();\n completion.set(responsePayload);\n listener.onComplete(responsePayload);\n traceComplete(traceContext, responsePayload);\n closed.set(true);\n eventSource.cancel();\n latch.countDown();\n }\n } catch (Throwable ex) {\n failure.set(ex);\n traceError(traceContext, ex);\n listener.onError(ex);\n closed.set(true);\n eventSource.cancel();\n latch.countDown();\n }\n }\n\n @Override\n public void onClosed(@NotNull EventSource eventSource) {\n if (closed.compareAndSet(false, true)) {\n AgentFlowChatResponse responsePayload = completion.get();\n if (responsePayload == null) {\n responsePayload = AgentFlowChatResponse.builder()\n .content(content.toString())\n .conversationId(conversationIdRef.get())\n .messageId(messageIdRef.get())\n .taskId(taskIdRef.get())\n .usage(usageRef.get())\n .build();\n completion.set(responsePayload);\n listener.onComplete(responsePayload);\n traceComplete(traceContext, responsePayload);\n }\n latch.countDown();\n }\n }\n\n @Override\n public void onFailure(@NotNull EventSource eventSource, @Nullable Throwable t, @Nullable Response response) {\n Throwable error = t;\n if (error == null && response != null) {\n error = new AgentFlowException(\"Dify stream failed: HTTP \" + response.code());\n }\n if (error == null) {\n error = new AgentFlowException(\"Dify stream failed\");\n }\n failure.set(error);\n traceError(traceContext, error);\n listener.onError(error);\n closed.set(true);\n latch.countDown();\n }\n });\n\n if (!latch.await(pollTimeoutMillis(), TimeUnit.MILLISECONDS)) {\n throw new AgentFlowException(\"Dify stream timed out\");\n }\n if (failure.get() != null) {\n if (failure.get() instanceof Exception) {\n throw (Exception) failure.get();\n }\n throw new AgentFlowException(\"Dify stream failed\", failure.get());\n }\n }\n\n private JSONObject buildRequestBody(AgentFlowChatRequest request, String responseMode) {\n JSONObject body = new JSONObject();\n body.put(\"query\", request.getPrompt());\n body.put(\"inputs\", request.getInputs() == null ? Collections.emptyMap() : request.getInputs());\n body.put(\"user\", defaultUserId(request.getUserId()));\n body.put(\"response_mode\", responseMode);\n String conversationId = defaultConversationId(request.getConversationId());\n if (!isBlank(conversationId)) {\n body.put(\"conversation_id\", conversationId);\n }\n if (request.getExtraBody() != null && !request.getExtraBody().isEmpty()) {\n body.putAll(request.getExtraBody());\n }\n return body;\n }\n\n private AgentFlowChatResponse mapBlockingResponse(JSONObject response) {\n return AgentFlowChatResponse.builder()\n .content(firstNonBlank(response.getString(\"answer\"), response.getString(\"message\")))\n .conversationId(response.getString(\"conversation_id\"))\n .messageId(firstNonBlank(response.getString(\"message_id\"), response.getString(\"id\")))\n .taskId(response.getString(\"task_id\"))\n .usage(usageFromDify(metadataUsage(response)))\n .raw(response)\n .build();\n }\n\n private JSONObject metadataUsage(JSONObject payload) {\n JSONObject metadata = payload == null ? null : payload.getJSONObject(\"metadata\");\n return metadata == null ? null : metadata.getJSONObject(\"usage\");\n }\n\n private JSONObject parseObjectOrNull(String data) {\n if (isBlank(data)) {\n return null;\n }\n try {\n Object parsed = JSON.parse(data);\n return parsed instanceof JSONObject ? (JSONObject) parsed : null;\n } catch (Exception ex) {\n return null;\n }\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/support/AgentFlowSupport.java",
"content": "package io.github.lnyocly.ai4j.agentflow.support;\n\nimport com.alibaba.fastjson2.JSON;\nimport com.alibaba.fastjson2.JSONObject;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowConfig;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowException;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowUsage;\nimport io.github.lnyocly.ai4j.agentflow.trace.AgentFlowTraceContext;\nimport io.github.lnyocly.ai4j.agentflow.trace.AgentFlowTraceListener;\nimport io.github.lnyocly.ai4j.constant.Constants;\nimport io.github.lnyocly.ai4j.network.UrlUtils;\nimport io.github.lnyocly.ai4j.service.Configuration;\nimport okhttp3.HttpUrl;\nimport okhttp3.MediaType;\nimport okhttp3.OkHttpClient;\nimport okhttp3.Request;\nimport okhttp3.RequestBody;\nimport okhttp3.Response;\nimport okhttp3.ResponseBody;\nimport okhttp3.sse.EventSource;\n\nimport java.io.IOException;\nimport java.util.Collections;\nimport java.util.LinkedHashMap;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.UUID;\n\npublic abstract class AgentFlowSupport {\n\n protected static final MediaType JSON_MEDIA_TYPE = MediaType.get(Constants.APPLICATION_JSON);\n\n protected final Configuration configuration;\n protected final AgentFlowConfig agentFlowConfig;\n protected final OkHttpClient okHttpClient;\n protected final EventSource.Factory eventSourceFactory;\n\n protected AgentFlowSupport(Configuration configuration, AgentFlowConfig agentFlowConfig) {\n if (configuration == null) {\n throw new IllegalArgumentException(\"configuration is required\");\n }\n if (configuration.getOkHttpClient() == null) {\n throw new IllegalArgumentException(\"OkHttpClient configuration is required\");\n }\n if (agentFlowConfig == null) {\n throw new IllegalArgumentException(\"agentFlowConfig is required\");\n }\n this.configuration = configuration;\n this.agentFlowConfig = agentFlowConfig;\n this.okHttpClient = configuration.getOkHttpClient();\n this.eventSourceFactory = configuration.createRequestFactory();\n }\n\n protected String defaultUserId(String requestUserId) {\n if (!isBlank(requestUserId)) {\n return requestUserId;\n }\n if (!isBlank(agentFlowConfig.getUserId())) {\n return agentFlowConfig.getUserId();\n }\n return \"default-user\";\n }\n\n protected String defaultConversationId(String requestConversationId) {\n if (!isBlank(requestConversationId)) {\n return requestConversationId;\n }\n return agentFlowConfig.getConversationId();\n }\n\n protected String requireBaseUrl() {\n if (isBlank(agentFlowConfig.getBaseUrl())) {\n throw new IllegalArgumentException(\"baseUrl is required\");\n }\n return agentFlowConfig.getBaseUrl();\n }\n\n protected String requireWebhookUrl() {\n if (isBlank(agentFlowConfig.getWebhookUrl())) {\n throw new IllegalArgumentException(\"webhookUrl is required\");\n }\n return agentFlowConfig.getWebhookUrl();\n }\n\n protected String requireApiKey() {\n if (isBlank(agentFlowConfig.getApiKey())) {\n throw new IllegalArgumentException(\"apiKey is required\");\n }\n return agentFlowConfig.getApiKey();\n }\n\n protected String requireBotId() {\n if (isBlank(agentFlowConfig.getBotId())) {\n throw new IllegalArgumentException(\"botId is required\");\n }\n return agentFlowConfig.getBotId();\n }\n\n protected String requireWorkflowId(String requestWorkflowId) {\n if (!isBlank(requestWorkflowId)) {\n return requestWorkflowId;\n }\n if (!isBlank(agentFlowConfig.getWorkflowId())) {\n return agentFlowConfig.getWorkflowId();\n }\n throw new IllegalArgumentException(\"workflowId is required\");\n }\n\n protected String joinedUrl(String baseUrl, String path) {\n return UrlUtils.concatUrl(baseUrl, path);\n }\n\n protected String appendQuery(String url, Map queryParameters) {\n HttpUrl parsed = HttpUrl.parse(url);\n if (parsed == null) {\n throw new IllegalArgumentException(\"Invalid URL: \" + url);\n }\n HttpUrl.Builder builder = parsed.newBuilder();\n if (queryParameters != null) {\n for (Map.Entry entry : queryParameters.entrySet()) {\n if (!isBlank(entry.getValue())) {\n builder.addQueryParameter(entry.getKey(), entry.getValue());\n }\n }\n }\n return builder.build().toString();\n }\n\n protected RequestBody jsonBody(Object body) {\n return RequestBody.create(JSON.toJSONString(body), JSON_MEDIA_TYPE);\n }\n\n protected Request.Builder jsonRequestBuilder(String url) {\n Request.Builder builder = new Request.Builder().url(url);\n builder.header(\"Content-Type\", Constants.APPLICATION_JSON);\n if (!isBlank(agentFlowConfig.getApiKey())) {\n builder.header(\"Authorization\", \"Bearer \" + agentFlowConfig.getApiKey());\n }\n if (agentFlowConfig.getHeaders() != null) {\n for (Map.Entry entry : agentFlowConfig.getHeaders().entrySet()) {\n if (!isBlank(entry.getKey()) && entry.getValue() != null) {\n builder.header(entry.getKey(), entry.getValue());\n }\n }\n }\n return builder;\n }\n\n protected String execute(Request request) throws IOException {\n try (Response response = okHttpClient.newCall(request).execute()) {\n return readResponse(request, response);\n }\n }\n\n protected JSONObject executeObject(Request request) throws IOException {\n String body = execute(request);\n if (isBlank(body)) {\n return new JSONObject();\n }\n Object parsed = JSON.parse(body);\n if (parsed instanceof JSONObject) {\n return (JSONObject) parsed;\n }\n throw new AgentFlowException(\"Expected JSON object response but got: \" + body);\n }\n\n protected Object parseJsonOrText(String body) {\n if (isBlank(body)) {\n return null;\n }\n try {\n return JSON.parse(body);\n } catch (Exception ex) {\n return body;\n }\n }\n\n protected String readResponse(Request request, Response response) throws IOException {\n ResponseBody body = response.body();\n String content = body == null ? \"\" : body.string();\n if (!response.isSuccessful()) {\n throw new AgentFlowException(\"HTTP \" + response.code() + \" calling \" + request.url() + \": \" + abbreviate(content));\n }\n return content;\n }\n\n protected void assertCozeSuccess(JSONObject response) {\n Integer code = response == null ? null : response.getInteger(\"code\");\n if (code != null && code.intValue() != 0) {\n throw new AgentFlowException(\"Coze request failed: code=\" + code + \", msg=\" + response.getString(\"msg\"));\n }\n }\n\n protected Map mutableMap(Map source) {\n if (source == null || source.isEmpty()) {\n return new LinkedHashMap();\n }\n return new LinkedHashMap(source);\n }\n\n protected Map toStringMap(Map source) {\n if (source == null || source.isEmpty()) {\n return Collections.emptyMap();\n }\n Map result = new LinkedHashMap();\n for (Map.Entry entry : source.entrySet()) {\n if (entry.getKey() != null && entry.getValue() != null) {\n result.put(entry.getKey(), String.valueOf(entry.getValue()));\n }\n }\n return result;\n }\n\n protected String extractText(Object value) {\n if (value == null) {\n return null;\n }\n if (value instanceof String) {\n return (String) value;\n }\n if (value instanceof JSONObject) {\n JSONObject jsonObject = (JSONObject) value;\n String direct = firstNonBlank(\n jsonObject.getString(\"answer\"),\n jsonObject.getString(\"output\"),\n jsonObject.getString(\"text\"),\n jsonObject.getString(\"content\"),\n jsonObject.getString(\"result\"),\n jsonObject.getString(\"message\")\n );\n if (!isBlank(direct)) {\n return direct;\n }\n if (jsonObject.size() == 1) {\n Map.Entry entry = jsonObject.entrySet().iterator().next();\n return extractText(entry.getValue());\n }\n return JSON.toJSONString(jsonObject);\n }\n return String.valueOf(value);\n }\n\n protected AgentFlowUsage usageFromDify(JSONObject usage) {\n if (usage == null || usage.isEmpty()) {\n return null;\n }\n return AgentFlowUsage.builder()\n .inputTokens(usage.getInteger(\"prompt_tokens\"))\n .outputTokens(usage.getInteger(\"completion_tokens\"))\n .totalTokens(usage.getInteger(\"total_tokens\"))\n .raw(usage)\n .build();\n }\n\n protected AgentFlowUsage usageFromCoze(JSONObject usage) {\n if (usage == null || usage.isEmpty()) {\n return null;\n }\n return AgentFlowUsage.builder()\n .inputTokens(firstNonNullInteger(usage.getInteger(\"input_tokens\"), usage.getInteger(\"input_count\")))\n .outputTokens(firstNonNullInteger(usage.getInteger(\"output_tokens\"), usage.getInteger(\"output_count\")))\n .totalTokens(usage.getInteger(\"token_count\"))\n .raw(usage)\n .build();\n }\n\n protected Integer firstNonNullInteger(Integer first, Integer second) {\n return first != null ? first : second;\n }\n\n protected String firstNonBlank(String first, String second) {\n return firstNonBlank(first, second, null, null, null, null);\n }\n\n protected String firstNonBlank(String first,\n String second,\n String third,\n String fourth,\n String fifth,\n String sixth) {\n String[] values = new String[]{first, second, third, fourth, fifth, sixth};\n for (String value : values) {\n if (!isBlank(value)) {\n return value;\n }\n }\n return null;\n }\n\n protected long pollIntervalMillis() {\n Long value = agentFlowConfig.getPollIntervalMillis();\n return value == null || value.longValue() <= 0L ? 1_000L : value.longValue();\n }\n\n protected long pollTimeoutMillis() {\n Long value = agentFlowConfig.getPollTimeoutMillis();\n return value == null || value.longValue() <= 0L ? 60_000L : value.longValue();\n }\n\n protected void sleep(long millis) throws InterruptedException {\n if (millis > 0L) {\n Thread.sleep(millis);\n }\n }\n\n protected String abbreviate(String value) {\n if (value == null) {\n return null;\n }\n if (value.length() <= 500) {\n return value;\n }\n return value.substring(0, 500) + \"...\";\n }\n\n protected boolean isBlank(String value) {\n return value == null || value.trim().isEmpty();\n }\n\n protected AgentFlowTraceContext startTrace(String operation, boolean streaming, Object request) {\n AgentFlowTraceContext context = AgentFlowTraceContext.builder()\n .executionId(UUID.randomUUID().toString())\n .type(agentFlowConfig.getType())\n .operation(operation)\n .streaming(streaming)\n .startedAt(System.currentTimeMillis())\n .baseUrl(agentFlowConfig.getBaseUrl())\n .webhookUrl(agentFlowConfig.getWebhookUrl())\n .botId(agentFlowConfig.getBotId())\n .workflowId(agentFlowConfig.getWorkflowId())\n .appId(agentFlowConfig.getAppId())\n .configuredUserId(agentFlowConfig.getUserId())\n .configuredConversationId(agentFlowConfig.getConversationId())\n .request(request)\n .build();\n notifyTraceStart(context);\n return context;\n }\n\n protected void traceEvent(AgentFlowTraceContext context, Object event) {\n List listeners = traceListeners();\n if (context == null || event == null || listeners.isEmpty()) {\n return;\n }\n for (AgentFlowTraceListener listener : listeners) {\n if (listener == null) {\n continue;\n }\n try {\n listener.onEvent(context, event);\n } catch (Throwable ignored) {\n // Trace listeners must never break the primary AgentFlow call path.\n }\n }\n }\n\n protected void traceComplete(AgentFlowTraceContext context, Object response) {\n List listeners = traceListeners();\n if (context == null || listeners.isEmpty()) {\n return;\n }\n for (AgentFlowTraceListener listener : listeners) {\n if (listener == null) {\n continue;\n }\n try {\n listener.onComplete(context, response);\n } catch (Throwable ignored) {\n // Trace listeners must never break the primary AgentFlow call path.\n }\n }\n }\n\n protected void traceError(AgentFlowTraceContext context, Throwable throwable) {\n List listeners = traceListeners();\n if (context == null || throwable == null || listeners.isEmpty()) {\n return;\n }\n for (AgentFlowTraceListener listener : listeners) {\n if (listener == null) {\n continue;\n }\n try {\n listener.onError(context, throwable);\n } catch (Throwable ignored) {\n // Trace listeners must never break the primary AgentFlow call path.\n }\n }\n }\n\n private void notifyTraceStart(AgentFlowTraceContext context) {\n List listeners = traceListeners();\n if (context == null || listeners.isEmpty()) {\n return;\n }\n for (AgentFlowTraceListener listener : listeners) {\n if (listener == null) {\n continue;\n }\n try {\n listener.onStart(context);\n } catch (Throwable ignored) {\n // Trace listeners must never break the primary AgentFlow call path.\n }\n }\n }\n\n private List traceListeners() {\n List listeners = agentFlowConfig.getTraceListeners();\n return listeners == null ? Collections.emptyList() : listeners;\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/trace/AgentFlowTraceContext.java",
"content": "package io.github.lnyocly.ai4j.agentflow.trace;\n\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowType;\nimport lombok.AccessLevel;\nimport lombok.AllArgsConstructor;\nimport lombok.Builder;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n@Data\n@Builder(toBuilder = true)\n@NoArgsConstructor(access = AccessLevel.PRIVATE)\n@AllArgsConstructor(access = AccessLevel.PRIVATE)\npublic class AgentFlowTraceContext {\n\n private String executionId;\n\n private AgentFlowType type;\n\n private String operation;\n\n private boolean streaming;\n\n private long startedAt;\n\n private String baseUrl;\n\n private String webhookUrl;\n\n private String botId;\n\n private String workflowId;\n\n private String appId;\n\n private String configuredUserId;\n\n private String configuredConversationId;\n\n private Object request;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/trace/AgentFlowTraceListener.java",
"content": "package io.github.lnyocly.ai4j.agentflow.trace;\n\npublic interface AgentFlowTraceListener {\n\n default void onStart(AgentFlowTraceContext context) {\n }\n\n default void onEvent(AgentFlowTraceContext context, Object event) {\n }\n\n default void onComplete(AgentFlowTraceContext context, Object response) {\n }\n\n default void onError(AgentFlowTraceContext context, Throwable throwable) {\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/workflow/AgentFlowWorkflowEvent.java",
"content": "package io.github.lnyocly.ai4j.agentflow.workflow;\n\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowUsage;\nimport lombok.AccessLevel;\nimport lombok.AllArgsConstructor;\nimport lombok.Builder;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\nimport java.util.Collections;\nimport java.util.Map;\n\n@Data\n@Builder(toBuilder = true)\n@NoArgsConstructor(access = AccessLevel.PRIVATE)\n@AllArgsConstructor(access = AccessLevel.PRIVATE)\npublic class AgentFlowWorkflowEvent {\n\n private String type;\n\n private String status;\n\n private String outputText;\n\n @Builder.Default\n private Map outputs = Collections.emptyMap();\n\n private String taskId;\n\n private String workflowRunId;\n\n private boolean done;\n\n private AgentFlowUsage usage;\n\n private Object raw;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/workflow/AgentFlowWorkflowListener.java",
"content": "package io.github.lnyocly.ai4j.agentflow.workflow;\n\npublic interface AgentFlowWorkflowListener {\n\n void onEvent(AgentFlowWorkflowEvent event);\n\n default void onOpen() {\n }\n\n default void onError(Throwable throwable) {\n }\n\n default void onComplete(AgentFlowWorkflowResponse response) {\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/workflow/AgentFlowWorkflowRequest.java",
"content": "package io.github.lnyocly.ai4j.agentflow.workflow;\n\nimport lombok.AccessLevel;\nimport lombok.AllArgsConstructor;\nimport lombok.Builder;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\nimport java.util.Collections;\nimport java.util.Map;\n\n@Data\n@Builder(toBuilder = true)\n@NoArgsConstructor(access = AccessLevel.PRIVATE)\n@AllArgsConstructor(access = AccessLevel.PRIVATE)\npublic class AgentFlowWorkflowRequest {\n\n @Builder.Default\n private Map inputs = Collections.emptyMap();\n\n private String userId;\n\n private String workflowId;\n\n @Builder.Default\n private Map metadata = Collections.emptyMap();\n\n @Builder.Default\n private Map extraBody = Collections.emptyMap();\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/workflow/AgentFlowWorkflowResponse.java",
"content": "package io.github.lnyocly.ai4j.agentflow.workflow;\n\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowUsage;\nimport lombok.AccessLevel;\nimport lombok.AllArgsConstructor;\nimport lombok.Builder;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\nimport java.util.Collections;\nimport java.util.Map;\n\n@Data\n@Builder(toBuilder = true)\n@NoArgsConstructor(access = AccessLevel.PRIVATE)\n@AllArgsConstructor(access = AccessLevel.PRIVATE)\npublic class AgentFlowWorkflowResponse {\n\n private String status;\n\n private String outputText;\n\n @Builder.Default\n private Map outputs = Collections.emptyMap();\n\n private String taskId;\n\n private String workflowRunId;\n\n private AgentFlowUsage usage;\n\n private Object raw;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/workflow/AgentFlowWorkflowService.java",
"content": "package io.github.lnyocly.ai4j.agentflow.workflow;\n\npublic interface AgentFlowWorkflowService {\n\n AgentFlowWorkflowResponse run(AgentFlowWorkflowRequest request) throws Exception;\n\n void runStream(AgentFlowWorkflowRequest request, AgentFlowWorkflowListener listener) throws Exception;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/workflow/CozeAgentFlowWorkflowService.java",
"content": "package io.github.lnyocly.ai4j.agentflow.workflow;\n\nimport com.alibaba.fastjson2.JSON;\nimport com.alibaba.fastjson2.JSONObject;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowConfig;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowException;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowUsage;\nimport io.github.lnyocly.ai4j.agentflow.support.AgentFlowSupport;\nimport io.github.lnyocly.ai4j.agentflow.trace.AgentFlowTraceContext;\nimport io.github.lnyocly.ai4j.service.Configuration;\nimport okhttp3.Request;\nimport okhttp3.Response;\nimport okhttp3.sse.EventSource;\nimport okhttp3.sse.EventSourceListener;\nimport org.jetbrains.annotations.NotNull;\nimport org.jetbrains.annotations.Nullable;\n\nimport java.util.Collections;\nimport java.util.LinkedHashMap;\nimport java.util.Map;\nimport java.util.concurrent.CountDownLatch;\nimport java.util.concurrent.TimeUnit;\nimport java.util.concurrent.atomic.AtomicBoolean;\nimport java.util.concurrent.atomic.AtomicReference;\n\npublic class CozeAgentFlowWorkflowService extends AgentFlowSupport implements AgentFlowWorkflowService {\n\n public CozeAgentFlowWorkflowService(Configuration configuration, AgentFlowConfig agentFlowConfig) {\n super(configuration, agentFlowConfig);\n }\n\n @Override\n public AgentFlowWorkflowResponse run(AgentFlowWorkflowRequest request) throws Exception {\n AgentFlowTraceContext traceContext = startTrace(\"workflow\", false, request);\n try {\n JSONObject response = executeObject(buildRunRequest(request, false));\n assertCozeSuccess(response);\n\n Object dataValue = response.get(\"data\");\n Object parsedData = parseWorkflowData(dataValue);\n Map outputs = parsedData instanceof JSONObject\n ? new LinkedHashMap((JSONObject) parsedData)\n : Collections.emptyMap();\n\n AgentFlowWorkflowResponse workflowResponse = AgentFlowWorkflowResponse.builder()\n .status(\"completed\")\n .outputText(extractText(parsedData))\n .outputs(outputs)\n .workflowRunId(response.getString(\"execute_id\"))\n .usage(usageFromCoze(response.getJSONObject(\"usage\")))\n .raw(response)\n .build();\n traceComplete(traceContext, workflowResponse);\n return workflowResponse;\n } catch (Exception ex) {\n traceError(traceContext, ex);\n throw ex;\n }\n }\n\n @Override\n public void runStream(AgentFlowWorkflowRequest request, final AgentFlowWorkflowListener listener) throws Exception {\n if (listener == null) {\n throw new IllegalArgumentException(\"listener is required\");\n }\n final AgentFlowTraceContext traceContext = startTrace(\"workflow\", true, request);\n\n Request httpRequest = buildRunRequest(request, true);\n final CountDownLatch latch = new CountDownLatch(1);\n final AtomicReference failure = new AtomicReference();\n final AtomicReference completion = new AtomicReference();\n final AtomicReference usageRef = new AtomicReference();\n final StringBuilder content = new StringBuilder();\n final AtomicBoolean closed = new AtomicBoolean(false);\n\n eventSourceFactory.newEventSource(httpRequest, new EventSourceListener() {\n @Override\n public void onOpen(@NotNull EventSource eventSource, @NotNull Response response) {\n listener.onOpen();\n }\n\n @Override\n public void onEvent(@NotNull EventSource eventSource,\n @Nullable String id,\n @Nullable String type,\n @NotNull String data) {\n try {\n String eventType = type;\n JSONObject payload = parseObjectOrNull(data);\n boolean done = false;\n String outputText = null;\n\n if (\"Message\".equals(eventType)) {\n outputText = payload == null ? null : payload.getString(\"content\");\n if (!isBlank(outputText)) {\n content.append(outputText);\n }\n AgentFlowUsage usage = payload == null ? null : usageFromCoze(payload.getJSONObject(\"usage\"));\n if (usage != null) {\n usageRef.set(usage);\n }\n } else if (\"Interrupt\".equals(eventType)) {\n throw new AgentFlowException(\"Coze workflow interrupted: \" + data);\n } else if (\"Error\".equals(eventType)) {\n throw new AgentFlowException(\"Coze workflow stream error: \" + data);\n } else if (\"Done\".equals(eventType)) {\n done = true;\n }\n\n AgentFlowWorkflowEvent event = AgentFlowWorkflowEvent.builder()\n .type(eventType)\n .status(done ? \"completed\" : null)\n .outputText(outputText)\n .done(done)\n .usage(usageRef.get())\n .raw(payload == null ? data : payload)\n .build();\n listener.onEvent(event);\n traceEvent(traceContext, event);\n\n if (done) {\n AgentFlowWorkflowResponse responsePayload = AgentFlowWorkflowResponse.builder()\n .status(\"completed\")\n .outputText(content.toString())\n .usage(usageRef.get())\n .raw(payload == null ? data : payload)\n .build();\n completion.set(responsePayload);\n listener.onComplete(responsePayload);\n traceComplete(traceContext, responsePayload);\n closed.set(true);\n eventSource.cancel();\n latch.countDown();\n }\n } catch (Throwable ex) {\n failure.set(ex);\n traceError(traceContext, ex);\n listener.onError(ex);\n closed.set(true);\n eventSource.cancel();\n latch.countDown();\n }\n }\n\n @Override\n public void onClosed(@NotNull EventSource eventSource) {\n if (closed.compareAndSet(false, true)) {\n AgentFlowWorkflowResponse responsePayload = completion.get();\n if (responsePayload == null) {\n responsePayload = AgentFlowWorkflowResponse.builder()\n .status(\"completed\")\n .outputText(content.toString())\n .usage(usageRef.get())\n .build();\n completion.set(responsePayload);\n listener.onComplete(responsePayload);\n traceComplete(traceContext, responsePayload);\n }\n latch.countDown();\n }\n }\n\n @Override\n public void onFailure(@NotNull EventSource eventSource, @Nullable Throwable t, @Nullable Response response) {\n Throwable error = t;\n if (error == null && response != null) {\n error = new AgentFlowException(\"Coze workflow stream failed: HTTP \" + response.code());\n }\n if (error == null) {\n error = new AgentFlowException(\"Coze workflow stream failed\");\n }\n failure.set(error);\n traceError(traceContext, error);\n listener.onError(error);\n closed.set(true);\n latch.countDown();\n }\n });\n\n if (!latch.await(pollTimeoutMillis(), TimeUnit.MILLISECONDS)) {\n throw new AgentFlowException(\"Coze workflow stream timed out\");\n }\n if (failure.get() != null) {\n if (failure.get() instanceof Exception) {\n throw (Exception) failure.get();\n }\n throw new AgentFlowException(\"Coze workflow stream failed\", failure.get());\n }\n }\n\n private Request buildRunRequest(AgentFlowWorkflowRequest request, boolean stream) {\n String path = stream ? \"v1/workflow/stream_run\" : \"v1/workflow/run\";\n String url = joinedUrl(requireBaseUrl(), path);\n return jsonRequestBuilder(url).post(jsonBody(buildRequestBody(request))).build();\n }\n\n private JSONObject buildRequestBody(AgentFlowWorkflowRequest request) {\n JSONObject body = new JSONObject();\n body.put(\"workflow_id\", requireWorkflowId(request.getWorkflowId()));\n body.put(\"parameters\", request.getInputs() == null ? Collections.emptyMap() : request.getInputs());\n if (!isBlank(agentFlowConfig.getBotId())) {\n body.put(\"bot_id\", agentFlowConfig.getBotId());\n }\n if (!isBlank(agentFlowConfig.getAppId())) {\n body.put(\"app_id\", agentFlowConfig.getAppId());\n }\n if (request.getMetadata() != null && !request.getMetadata().isEmpty()) {\n body.put(\"ext\", toStringMap(request.getMetadata()));\n }\n if (request.getExtraBody() != null && !request.getExtraBody().isEmpty()) {\n body.putAll(request.getExtraBody());\n }\n return body;\n }\n\n private Object parseWorkflowData(Object dataValue) {\n if (dataValue == null) {\n return null;\n }\n if (!(dataValue instanceof String)) {\n return dataValue;\n }\n String text = (String) dataValue;\n if (isBlank(text)) {\n return null;\n }\n try {\n return JSON.parse(text);\n } catch (Exception ex) {\n return text;\n }\n }\n\n private JSONObject parseObjectOrNull(String data) {\n if (isBlank(data)) {\n return null;\n }\n try {\n Object parsed = JSON.parse(data);\n return parsed instanceof JSONObject ? (JSONObject) parsed : null;\n } catch (Exception ex) {\n return null;\n }\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/workflow/DifyAgentFlowWorkflowService.java",
"content": "package io.github.lnyocly.ai4j.agentflow.workflow;\n\nimport com.alibaba.fastjson2.JSON;\nimport com.alibaba.fastjson2.JSONObject;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowConfig;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowException;\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowUsage;\nimport io.github.lnyocly.ai4j.agentflow.support.AgentFlowSupport;\nimport io.github.lnyocly.ai4j.agentflow.trace.AgentFlowTraceContext;\nimport io.github.lnyocly.ai4j.service.Configuration;\nimport okhttp3.Request;\nimport okhttp3.Response;\nimport okhttp3.sse.EventSource;\nimport okhttp3.sse.EventSourceListener;\nimport org.jetbrains.annotations.NotNull;\nimport org.jetbrains.annotations.Nullable;\n\nimport java.util.Collections;\nimport java.util.LinkedHashMap;\nimport java.util.Map;\nimport java.util.concurrent.CountDownLatch;\nimport java.util.concurrent.TimeUnit;\nimport java.util.concurrent.atomic.AtomicBoolean;\nimport java.util.concurrent.atomic.AtomicReference;\n\npublic class DifyAgentFlowWorkflowService extends AgentFlowSupport implements AgentFlowWorkflowService {\n\n public DifyAgentFlowWorkflowService(Configuration configuration, AgentFlowConfig agentFlowConfig) {\n super(configuration, agentFlowConfig);\n }\n\n @Override\n public AgentFlowWorkflowResponse run(AgentFlowWorkflowRequest request) throws Exception {\n AgentFlowTraceContext traceContext = startTrace(\"workflow\", false, request);\n try {\n JSONObject body = buildRequestBody(request, \"blocking\");\n String url = joinedUrl(requireBaseUrl(), \"v1/workflows/run\");\n JSONObject response = executeObject(jsonRequestBuilder(url).post(jsonBody(body)).build());\n AgentFlowWorkflowResponse workflowResponse = mapWorkflowResponse(response);\n traceComplete(traceContext, workflowResponse);\n return workflowResponse;\n } catch (Exception ex) {\n traceError(traceContext, ex);\n throw ex;\n }\n }\n\n @Override\n public void runStream(AgentFlowWorkflowRequest request, final AgentFlowWorkflowListener listener) throws Exception {\n if (listener == null) {\n throw new IllegalArgumentException(\"listener is required\");\n }\n final AgentFlowTraceContext traceContext = startTrace(\"workflow\", true, request);\n\n JSONObject body = buildRequestBody(request, \"streaming\");\n String url = joinedUrl(requireBaseUrl(), \"v1/workflows/run\");\n Request httpRequest = jsonRequestBuilder(url).post(jsonBody(body)).build();\n\n final CountDownLatch latch = new CountDownLatch(1);\n final AtomicReference failure = new AtomicReference();\n final AtomicReference completion = new AtomicReference();\n final AtomicReference taskIdRef = new AtomicReference();\n final AtomicReference workflowRunIdRef = new AtomicReference();\n final AtomicReference usageRef = new AtomicReference();\n final AtomicReference> outputsRef = new AtomicReference>(Collections.emptyMap());\n final StringBuilder content = new StringBuilder();\n final AtomicBoolean closed = new AtomicBoolean(false);\n\n eventSourceFactory.newEventSource(httpRequest, new EventSourceListener() {\n @Override\n public void onOpen(@NotNull EventSource eventSource, @NotNull Response response) {\n listener.onOpen();\n }\n\n @Override\n public void onEvent(@NotNull EventSource eventSource,\n @Nullable String id,\n @Nullable String type,\n @NotNull String data) {\n try {\n JSONObject payload = parseObjectOrNull(data);\n String eventType = firstNonBlank(type, payload == null ? null : payload.getString(\"event\"));\n if (isBlank(eventType) || \"ping\".equals(eventType)) {\n return;\n }\n\n if (payload != null) {\n taskIdRef.set(firstNonBlank(payload.getString(\"task_id\"), taskIdRef.get()));\n workflowRunIdRef.set(firstNonBlank(payload.getString(\"workflow_run_id\"), workflowRunIdRef.get()));\n }\n\n String outputText = null;\n String status = null;\n Map outputs = outputsRef.get();\n boolean done = false;\n\n if (\"workflow_finished\".equals(eventType)) {\n done = true;\n JSONObject dataObject = payload == null ? null : payload.getJSONObject(\"data\");\n status = dataObject == null ? null : dataObject.getString(\"status\");\n JSONObject outputObject = dataObject == null ? null : dataObject.getJSONObject(\"outputs\");\n outputs = outputObject == null\n ? Collections.emptyMap()\n : new LinkedHashMap(outputObject);\n outputsRef.set(outputs);\n outputText = extractText(outputObject);\n if (!isBlank(outputText)) {\n content.setLength(0);\n content.append(outputText);\n }\n AgentFlowUsage usage = usageFromDify(dataObject == null ? null : dataObject.getJSONObject(\"usage\"));\n if (usage != null) {\n usageRef.set(usage);\n }\n } else if (\"message\".equals(eventType) || \"text_chunk\".equals(eventType)) {\n outputText = payload == null ? null : firstNonBlank(payload.getString(\"answer\"), payload.getString(\"text\"));\n if (!isBlank(outputText)) {\n content.append(outputText);\n }\n } else if (\"error\".equals(eventType)) {\n throw new AgentFlowException(\"Dify workflow stream error: \" + (payload == null ? data : payload.toJSONString()));\n }\n\n AgentFlowWorkflowEvent event = AgentFlowWorkflowEvent.builder()\n .type(eventType)\n .status(status)\n .outputText(outputText)\n .outputs(outputs)\n .taskId(taskIdRef.get())\n .workflowRunId(workflowRunIdRef.get())\n .done(done)\n .usage(usageRef.get())\n .raw(payload == null ? data : payload)\n .build();\n listener.onEvent(event);\n traceEvent(traceContext, event);\n\n if (done) {\n AgentFlowWorkflowResponse responsePayload = AgentFlowWorkflowResponse.builder()\n .status(status)\n .outputText(content.toString())\n .outputs(outputsRef.get())\n .taskId(taskIdRef.get())\n .workflowRunId(workflowRunIdRef.get())\n .usage(usageRef.get())\n .raw(payload)\n .build();\n completion.set(responsePayload);\n listener.onComplete(responsePayload);\n traceComplete(traceContext, responsePayload);\n closed.set(true);\n eventSource.cancel();\n latch.countDown();\n }\n } catch (Throwable ex) {\n failure.set(ex);\n traceError(traceContext, ex);\n listener.onError(ex);\n closed.set(true);\n eventSource.cancel();\n latch.countDown();\n }\n }\n\n @Override\n public void onClosed(@NotNull EventSource eventSource) {\n if (closed.compareAndSet(false, true)) {\n AgentFlowWorkflowResponse responsePayload = completion.get();\n if (responsePayload == null) {\n responsePayload = AgentFlowWorkflowResponse.builder()\n .outputText(content.toString())\n .outputs(outputsRef.get())\n .taskId(taskIdRef.get())\n .workflowRunId(workflowRunIdRef.get())\n .usage(usageRef.get())\n .build();\n completion.set(responsePayload);\n listener.onComplete(responsePayload);\n traceComplete(traceContext, responsePayload);\n }\n latch.countDown();\n }\n }\n\n @Override\n public void onFailure(@NotNull EventSource eventSource, @Nullable Throwable t, @Nullable Response response) {\n Throwable error = t;\n if (error == null && response != null) {\n error = new AgentFlowException(\"Dify workflow stream failed: HTTP \" + response.code());\n }\n if (error == null) {\n error = new AgentFlowException(\"Dify workflow stream failed\");\n }\n failure.set(error);\n traceError(traceContext, error);\n listener.onError(error);\n closed.set(true);\n latch.countDown();\n }\n });\n\n if (!latch.await(pollTimeoutMillis(), TimeUnit.MILLISECONDS)) {\n throw new AgentFlowException(\"Dify workflow stream timed out\");\n }\n if (failure.get() != null) {\n if (failure.get() instanceof Exception) {\n throw (Exception) failure.get();\n }\n throw new AgentFlowException(\"Dify workflow stream failed\", failure.get());\n }\n }\n\n private JSONObject buildRequestBody(AgentFlowWorkflowRequest request, String responseMode) {\n JSONObject body = new JSONObject();\n body.put(\"inputs\", request.getInputs() == null ? Collections.emptyMap() : request.getInputs());\n body.put(\"user\", defaultUserId(request.getUserId()));\n body.put(\"response_mode\", responseMode);\n if (request.getExtraBody() != null && !request.getExtraBody().isEmpty()) {\n body.putAll(request.getExtraBody());\n }\n return body;\n }\n\n private AgentFlowWorkflowResponse mapWorkflowResponse(JSONObject response) {\n JSONObject data = response.getJSONObject(\"data\");\n JSONObject outputs = data == null ? null : data.getJSONObject(\"outputs\");\n Map outputMap = outputs == null\n ? Collections.emptyMap()\n : new LinkedHashMap(outputs);\n return AgentFlowWorkflowResponse.builder()\n .status(data == null ? null : data.getString(\"status\"))\n .outputText(extractText(outputs))\n .outputs(outputMap)\n .taskId(response.getString(\"task_id\"))\n .workflowRunId(firstNonBlank(response.getString(\"workflow_run_id\"), data == null ? null : data.getString(\"id\")))\n .usage(usageFromDify(data == null ? null : data.getJSONObject(\"usage\")))\n .raw(response)\n .build();\n }\n\n private JSONObject parseObjectOrNull(String data) {\n if (isBlank(data)) {\n return null;\n }\n try {\n Object parsed = JSON.parse(data);\n return parsed instanceof JSONObject ? (JSONObject) parsed : null;\n } catch (Exception ex) {\n return null;\n }\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/agentflow/workflow/N8nAgentFlowWorkflowService.java",
"content": "package io.github.lnyocly.ai4j.agentflow.workflow;\n\nimport io.github.lnyocly.ai4j.agentflow.AgentFlowConfig;\nimport io.github.lnyocly.ai4j.agentflow.support.AgentFlowSupport;\nimport io.github.lnyocly.ai4j.agentflow.trace.AgentFlowTraceContext;\nimport io.github.lnyocly.ai4j.service.Configuration;\nimport okhttp3.Request;\n\nimport java.util.Collections;\nimport java.util.LinkedHashMap;\nimport java.util.Map;\n\npublic class N8nAgentFlowWorkflowService extends AgentFlowSupport implements AgentFlowWorkflowService {\n\n public N8nAgentFlowWorkflowService(Configuration configuration, AgentFlowConfig agentFlowConfig) {\n super(configuration, agentFlowConfig);\n }\n\n @Override\n @SuppressWarnings(\"unchecked\")\n public AgentFlowWorkflowResponse run(AgentFlowWorkflowRequest request) throws Exception {\n AgentFlowTraceContext traceContext = startTrace(\"workflow\", false, request);\n try {\n Map payload = new LinkedHashMap();\n if (request.getInputs() != null) {\n payload.putAll(request.getInputs());\n }\n if (request.getMetadata() != null && !request.getMetadata().isEmpty()) {\n payload.put(\"_metadata\", request.getMetadata());\n }\n if (request.getExtraBody() != null && !request.getExtraBody().isEmpty()) {\n payload.putAll(request.getExtraBody());\n }\n\n Request httpRequest = jsonRequestBuilder(requireWebhookUrl()).post(jsonBody(payload)).build();\n String responseBody = execute(httpRequest);\n Object raw = parseJsonOrText(responseBody);\n Map outputs = raw instanceof Map\n ? new LinkedHashMap((Map) raw)\n : Collections.emptyMap();\n\n AgentFlowWorkflowResponse workflowResponse = AgentFlowWorkflowResponse.builder()\n .status(\"completed\")\n .outputText(extractText(raw))\n .outputs(outputs)\n .raw(raw)\n .build();\n traceComplete(traceContext, workflowResponse);\n return workflowResponse;\n } catch (Exception ex) {\n traceError(traceContext, ex);\n throw ex;\n }\n }\n\n @Override\n public void runStream(AgentFlowWorkflowRequest request, AgentFlowWorkflowListener listener) {\n throw new UnsupportedOperationException(\"n8n workflow streaming is not supported yet\");\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/annotation/FunctionCall.java",
"content": "package io.github.lnyocly.ai4j.annotation;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\n/**\n * @Author cly\n * @Description TODO\n * @Date 2024/8/12 15:50\n */\n@Retention(RetentionPolicy.RUNTIME)\n@Target(ElementType.TYPE)\npublic @interface FunctionCall {\n String name();\n String description();\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/annotation/FunctionParameter.java",
"content": "package io.github.lnyocly.ai4j.annotation;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\n/**\n * @Author cly\n * @Description TODO\n * @Date 2024/8/12 15:55\n */\n@Retention(RetentionPolicy.RUNTIME)\n@Target(ElementType.FIELD)\npublic @interface FunctionParameter {\n String description();\n boolean required() default true;\n}"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/annotation/FunctionRequest.java",
"content": "package io.github.lnyocly.ai4j.annotation;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\n/**\n * @Author cly\n * @Description TODO\n * @Date 2024/8/12 15:55\n */\n@Retention(RetentionPolicy.RUNTIME)\n@Target(ElementType.TYPE)\npublic @interface FunctionRequest {\n String description() default \"\";\n}"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/auth/BearerTokenUtils.java",
"content": "package io.github.lnyocly.ai4j.auth;\n\nimport com.auth0.jwt.JWT;\nimport com.auth0.jwt.algorithms.Algorithm;\nimport com.google.common.cache.Cache;\nimport com.google.common.cache.CacheBuilder;\n\nimport javax.crypto.Mac;\nimport javax.crypto.spec.SecretKeySpec;\nimport javax.xml.bind.DatatypeConverter;\nimport java.nio.charset.StandardCharsets;\nimport java.security.MessageDigest;\nimport java.text.SimpleDateFormat;\nimport java.util.Date;\nimport java.util.HashMap;\nimport java.util.Map;\nimport java.util.TimeZone;\nimport java.util.concurrent.TimeUnit;\n\n\npublic class BearerTokenUtils {\n // 过期时间；默认24小时\n private static final long EXPIRE_MILLIS = 24 * 60 * 60 * 1000L;\n\n // 缓存服务\n public static Cache cache = CacheBuilder.newBuilder()\n .initialCapacity(100)\n .expireAfterWrite(EXPIRE_MILLIS - (60 * 1000L), TimeUnit.MILLISECONDS)\n .build();\n\n /**\n * 对 API Key 进行签名\n * 新版机制中平台颁发的 API Key 同时包含 “用户标识 id” 和 “签名密钥 secret”，即格式为 {id}.{secret}\n *\n * @param apiKey 智谱APIkey\n * @return Token\n */\n public static String getToken(String apiKey) {\n // 分割APIKEY\n String[] args = apiKey.split(\"\\\\.\");\n if (args.length != 2) {\n throw new IllegalArgumentException(\"API Key 格式错误\");\n }\n String id = args[0];\n String secret = args[1];\n // 缓存Token\n String token = cache.getIfPresent(apiKey);\n if (null != token) return token;\n // 创建Token\n Algorithm algorithm = Algorithm.HMAC256(secret.getBytes(StandardCharsets.UTF_8));\n Map payload = new HashMap<>();\n payload.put(\"api_key\", id);\n payload.put(\"exp\", System.currentTimeMillis() + EXPIRE_MILLIS);\n payload.put(\"timestamp\", System.currentTimeMillis());\n Map headerClaims = new HashMap<>();\n headerClaims.put(\"alg\", \"HS256\");\n headerClaims.put(\"sign_type\", \"SIGN\");\n token = JWT.create().withPayload(payload).withHeader(headerClaims).sign(algorithm);\n cache.put(id, token);\n return token;\n }\n\n /**\n * apiKey 属于SecretId与SecretKey的拼接，格式为 {SecretId}.{SecretKey}\n *\n * @param apiKey 腾讯混元APIkey\n * @return\n */\n public static String getAuthorization(String apiKey, String action, String payloadJson) throws Exception {\n String[] args = apiKey.split(\"\\\\.\");\n if (args.length != 2) {\n throw new IllegalArgumentException(\"API Key 格式错误\");\n }\n String id = args[0];\n String key = args[1];\n\n String algorithm = \"TC3-HMAC-SHA256\";\n String service = \"hunyuan\";\n String host = \"hunyuan.tencentcloudapi.com\";\n String timestamp = String.valueOf(System.currentTimeMillis() / 1000);\n SimpleDateFormat sdf = new SimpleDateFormat(\"yyyy-MM-dd\");\n // 注意时区，否则容易出错\n sdf.setTimeZone(TimeZone.getTimeZone(\"UTC\"));\n String date = sdf.format(new Date(Long.valueOf(timestamp + \"000\")));\n\n // ************* 步骤 1：拼接规范请求串 *************\n String httpRequestMethod = \"POST\";\n String canonicalUri = \"/\";\n String canonicalQueryString = \"\";\n String canonicalHeaders = \"content-type:application/json; charset=utf-8\\n\" + \"host:\" + host + \"\\n\" + \"x-tc-action:\" + action.toLowerCase() + \"\\n\";\n String signedHeaders = \"content-type;host;x-tc-action\";\n String hashedRequestPayload = sha256Hex(payloadJson);\n\n String canonicalRequest = httpRequestMethod + \"\\n\" + canonicalUri + \"\\n\" + canonicalQueryString + \"\\n\"\n + canonicalHeaders + \"\\n\" + signedHeaders + \"\\n\" + hashedRequestPayload;\n\n // ************* 步骤 2：拼接待签名字符串 *************\n String credentialScope = date + \"/\" + service + \"/\" + \"tc3_request\";\n String hashedCanonicalRequest = sha256Hex(canonicalRequest);\n\n String stringToSign = algorithm + \"\\n\" + timestamp + \"\\n\" + credentialScope + \"\\n\" + hashedCanonicalRequest;\n\n // ************* 步骤 3：计算签名 *************\n byte[] secretDate = hmac256((\"TC3\" + key).getBytes(StandardCharsets.UTF_8), date);\n byte[] secretService = hmac256(secretDate, service);\n byte[] secretSigning = hmac256(secretService, \"tc3_request\");\n\n String signature = DatatypeConverter.printHexBinary(hmac256(secretSigning, stringToSign)).toLowerCase();\n\n // ************* 步骤 4：拼接 Authorization *************\n String authorization = algorithm + \" \" + \"Credential=\" + id + \"/\" + credentialScope + \", \"\n + \"SignedHeaders=\" + signedHeaders + \", \" + \"Signature=\" + signature;\n return authorization;\n }\n\n private static byte[] hmac256(byte[] key, String msg) throws Exception {\n Mac mac = Mac.getInstance(\"HmacSHA256\");\n SecretKeySpec secretKeySpec = new SecretKeySpec(key, mac.getAlgorithm());\n mac.init(secretKeySpec);\n return mac.doFinal(msg.getBytes(StandardCharsets.UTF_8));\n }\n\n private static String sha256Hex(String s) throws Exception {\n MessageDigest md = MessageDigest.getInstance(\"SHA-256\");\n byte[] d = md.digest(s.getBytes(StandardCharsets.UTF_8));\n return DatatypeConverter.printHexBinary(d).toLowerCase();\n }\n\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/AiPlatform.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.Data;\n\n@Data\npublic class AiPlatform {\n private String id;\n private String platform;\n private String apiHost;\n private String apiKey;\n private String chatCompletionUrl;\n private String embeddingUrl;\n private String speechUrl;\n private String transcriptionUrl;\n private String translationUrl;\n private String realtimeUrl;\n private String rerankApiHost;\n private String rerankUrl;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/BaichuanConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class BaichuanConfig {\n\n private String apiHost = \"https://api.baichuan-ai.com/\";\n private String apiKey = \"\";\n private String chatCompletionUrl = \"v1/chat/completions\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/DashScopeConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description OpenAi骞冲彴閰嶇疆鏂囦欢淇℃伅\n * @Date 2024/8/8 0:18\n */\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class DashScopeConfig {\n private String apiHost = \"https://dashscope.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1/\";\n private String responsesUrl = \"responses\";\n private String apiKey = \"\";\n}\n\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/DeepSeekConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description DeepSeek 配置文件\n * @Date 2024/8/29 10:31\n */\n\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class DeepSeekConfig {\n\n private String apiHost = \"https://api.deepseek.com/\";\n private String apiKey = \"\";\n private String chatCompletionUrl = \"chat/completions\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/DoubaoConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description 璞嗗寘(鐏北寮曟搸鏂硅垷) 閰嶇疆鏂囦欢\n */\n\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class DoubaoConfig {\n\n private String apiHost = \"https://ark.cn-beijing.volces.com/api/v3/\";\n private String apiKey = \"\";\n private String chatCompletionUrl = \"chat/completions\";\n private String imageGenerationUrl = \"images/generations\";\n private String responsesUrl = \"responses\";\n private String rerankApiHost = \"https://api-knowledgebase.mlp.cn-beijing.volces.com/\";\n private String rerankUrl = \"api/knowledge/service/rerank\";\n}\n\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/HunyuanConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description 腾讯混元配置\n * @Date 2024/8/30 19:50\n */\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class HunyuanConfig {\n private String apiHost = \"https://hunyuan.tencentcloudapi.com/\";\n /**\n * apiKey 属于SecretId与SecretKey的拼接，格式为 {SecretId}.{SecretKey}\n */\n private String apiKey = \"\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/JinaConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class JinaConfig {\n\n private String apiHost = \"https://api.jina.ai/\";\n\n private String apiKey = \"\";\n\n private String rerankUrl = \"v1/rerank\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/LingyiConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description 零一万物大模型\n * @Date 2024/9/9 22:53\n */\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class LingyiConfig {\n private String apiHost = \"https://api.lingyiwanwu.com/\";\n private String apiKey = \"\";\n private String chatCompletionUrl = \"v1/chat/completions\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/McpConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.Data;\n\n/**\n * @Author cly\n * @Description MCP (Model Context Protocol) 配置类\n */\n@Data\npublic class McpConfig {\n \n /**\n * MCP服务器地址\n */\n private String serverUrl;\n \n /**\n * MCP服务器端口\n */\n private Integer serverPort = 3000;\n \n /**\n * 连接超时时间（毫秒）\n */\n private Long connectTimeout = 30000L;\n \n /**\n * 读取超时时间（毫秒）\n */\n private Long readTimeout = 60000L;\n \n /**\n * 写入超时时间（毫秒）\n */\n private Long writeTimeout = 60000L;\n \n /**\n * 是否启用SSL\n */\n private Boolean enableSsl = false;\n \n /**\n * 认证令牌\n */\n private String authToken;\n \n /**\n * 客户端名称\n */\n private String clientName = \"ai4j-mcp-client\";\n \n /**\n * 客户端版本\n */\n private String clientVersion = \"1.0.0\";\n \n /**\n * 最大重连次数\n */\n private Integer maxRetries = 3;\n \n /**\n * 重连间隔（毫秒）\n */\n private Long retryInterval = 5000L;\n \n /**\n * 是否启用心跳检测\n */\n private Boolean enableHeartbeat = true;\n \n /**\n * 心跳间隔（毫秒）\n */\n private Long heartbeatInterval = 30000L;\n \n /**\n * 消息队列大小\n */\n private Integer messageQueueSize = 1000;\n \n /**\n * 是否启用消息压缩\n */\n private Boolean enableCompression = false;\n \n /**\n * 传输类型：stdio, http, websocket\n */\n private String transportType = \"http\";\n \n /**\n * 获取完整的服务器URL\n */\n public String getFullServerUrl() {\n if (serverUrl == null) {\n return null;\n }\n \n String protocol = enableSsl ? \"https\" : \"http\";\n if (serverUrl.startsWith(\"http://\") || serverUrl.startsWith(\"https://\")) {\n return serverUrl;\n }\n \n return String.format(\"%s://%s:%d\", protocol, serverUrl, serverPort);\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/MilvusConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\nimport java.util.Arrays;\nimport java.util.List;\n\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class MilvusConfig {\n\n private boolean enabled = false;\n\n private String host = \"http://localhost:19530\";\n\n private String token = \"\";\n\n private String dbName = \"\";\n\n private String partitionName = \"\";\n\n private String idField = \"id\";\n\n private String vectorField = \"vector\";\n\n private String contentField = \"content\";\n\n private List outputFields = Arrays.asList(\n \"id\",\n \"content\",\n \"documentId\",\n \"sourceName\",\n \"sourcePath\",\n \"sourceUri\",\n \"pageNumber\",\n \"sectionTitle\",\n \"chunkIndex\"\n );\n\n private String upsert = \"/v2/vectordb/entities/upsert\";\n\n private String search = \"/v2/vectordb/entities/search\";\n\n private String delete = \"/v2/vectordb/entities/delete\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/MinimaxConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author : isxuwl\n * @Date: 2024/10/15 16:08\n * @Model Description:\n * @Description:\n */\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class MinimaxConfig {\n private String apiHost = \"https://api.minimax.chat/\";\n private String apiKey = \"\";\n private String chatCompletionUrl = \"v1/text/chatcompletion_v2\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/MoonshotConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description 月之暗面配置\n * @Date 2024/8/29 23:00\n */\n\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class MoonshotConfig {\n private String apiHost = \"https://api.moonshot.cn/\";\n private String apiKey = \"\";\n private String chatCompletionUrl = \"v1/chat/completions\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/OkHttpConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\nimport okhttp3.logging.HttpLoggingInterceptor;\n\n/**\n * @Author cly\n * @Description OkHttp配置信息\n * @Date 2024/8/11 0:11\n */\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class OkHttpConfig {\n\n private HttpLoggingInterceptor.Level log = HttpLoggingInterceptor.Level.HEADERS;\n private int connectTimeout = 300;\n private int writeTimeout = 300;\n private int readTimeout = 300;\n private int proxyPort = 10809;\n private String proxyHost = \"\";\n\n\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/OllamaConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description Ollama配置文件\n * @Date 2024/9/20 11:07\n */\n\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class OllamaConfig {\n private String apiHost = \"http://localhost:11434/\";\n private String apiKey = \"\";\n private String chatCompletionUrl = \"api/chat\";\n private String embeddingUrl = \"api/embed\";\n private String rerankUrl = \"api/rerank\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/OpenAiConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description OpenAi骞冲彴閰嶇疆鏂囦欢淇℃伅\n * @Date 2024/8/8 0:18\n */\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class OpenAiConfig {\n private String apiHost = \"https://api.openai.com/\";\n private String apiKey = \"\";\n private String chatCompletionUrl = \"v1/chat/completions\";\n private String embeddingUrl = \"v1/embeddings\";\n private String speechUrl = \"v1/audio/speech\";\n private String transcriptionUrl = \"v1/audio/transcriptions\";\n private String translationUrl = \"v1/audio/translations\";\n private String realtimeUrl = \"v1/realtime\";\n private String imageGenerationUrl = \"v1/images/generations\";\n private String responsesUrl = \"v1/responses\";\n\n}\n\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/PgVectorConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class PgVectorConfig {\n\n private boolean enabled = false;\n\n private String jdbcUrl = \"jdbc:postgresql://localhost:5432/postgres\";\n\n private String username = \"\";\n\n private String password = \"\";\n\n private String tableName = \"ai4j_vectors\";\n\n private String idColumn = \"id\";\n\n private String datasetColumn = \"dataset\";\n\n private String vectorColumn = \"embedding\";\n\n private String contentColumn = \"content\";\n\n private String metadataColumn = \"metadata\";\n\n private String distanceOperator = \"<=>\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/PineconeConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description Pinecone向量数据配置文件\n * @Date 2024/8/16 16:37\n */\n\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class PineconeConfig {\n private String host = \"https://xxx.svc.xxx.pinecone.io\";\n private String key = \"\";\n\n private String upsert = \"/vectors/upsert\";\n private String query = \"/query\";\n private String delete = \"/vectors/delete\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/QdrantConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class QdrantConfig {\n\n private boolean enabled = false;\n\n private String host = \"http://localhost:6333\";\n\n private String apiKey = \"\";\n\n private String vectorName = \"\";\n\n private String upsert = \"/collections/%s/points\";\n\n private String query = \"/collections/%s/points/query\";\n\n private String delete = \"/collections/%s/points/delete\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/config/ZhipuConfig.java",
"content": "package io.github.lnyocly.ai4j.config;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description 智谱AI平台配置信息\n * @Date 2024/8/27 22:12\n */\n@Data\n@NoArgsConstructor\n@AllArgsConstructor\npublic class ZhipuConfig {\n\n private String apiHost = \"https://open.bigmodel.cn/api/paas/\";\n private String apiKey = \"\";\n private String chatCompletionUrl = \"v4/chat/completions\";\n private String embeddingUrl= \"v4/embeddings\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/constant/Constants.java",
"content": "package io.github.lnyocly.ai4j.constant;\n\n/**\n * @Author cly\n * @Description TODO\n * @Date 2024/8/11 0:19\n */\npublic class Constants {\n public static final String SSE_CONTENT_TYPE = \"text/event-stream\";\n public static final String DEFAULT_USER_AGENT = \"Mozilla/4.0 (compatible; MSIE 5.0; Windows NT; DigExt)\";\n public static final String APPLICATION_JSON = \"application/json\";\n public static final String JSON_CONTENT_TYPE = APPLICATION_JSON + \"; charset=utf-8\";\n public static final String METADATA_KEY = \"content\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/convert/audio/AudioParameterConvert.java",
"content": "package io.github.lnyocly.ai4j.convert.audio;\n\n/**\n * @Author cly\n * @Description 处理请求参数。 由统一的OpenAi音频格式--->其它模型格式\n * @Date 2024/10/12 13:36\n */\npublic interface AudioParameterConvert {\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/convert/audio/AudioResultConvert.java",
"content": "package io.github.lnyocly.ai4j.convert.audio;\n\n/**\n * @Author cly\n * @Description 返回结果统一处理。 其它模型音频返回格式--->统一的OpenAi返回格式\n * @Date 2024/10/12 13:35\n */\npublic interface AudioResultConvert {\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/convert/chat/ParameterConvert.java",
"content": "package io.github.lnyocly.ai4j.convert.chat;\n\nimport io.github.lnyocly.ai4j.platform.openai.chat.entity.ChatCompletion;\n\n/**\n * @Author cly\n * @Description 处理请求参数 统一的OpenAi格式--->其它模型格式\n * @Date 2024/8/12 1:04\n */\npublic interface ParameterConvert {\n T convertChatCompletionObject(ChatCompletion chatCompletion);\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/convert/chat/ResultConvert.java",
"content": "package io.github.lnyocly.ai4j.convert.chat;\n\nimport io.github.lnyocly.ai4j.listener.SseListener;\nimport io.github.lnyocly.ai4j.platform.openai.chat.entity.ChatCompletionResponse;\nimport okhttp3.sse.EventSourceListener;\n\n/**\n * @Author cly\n * @Description 处理结果输出 其它模型格式--->统一的OpenAi格式\n * @Date 2024/8/12 1:05\n */\npublic interface ResultConvert {\n EventSourceListener convertEventSource(SseListener eventSourceListener);\n ChatCompletionResponse convertChatCompletionResponse(T t);\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/convert/embedding/EmbeddingParameterConvert.java",
"content": "package io.github.lnyocly.ai4j.convert.embedding;\n\n\nimport io.github.lnyocly.ai4j.platform.openai.embedding.entity.Embedding;\n\n/**\n * EmbeddingParameterConvert\n * @param \n */\npublic interface EmbeddingParameterConvert {\n T convertEmbeddingRequest(Embedding embeddingRequest);\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/convert/embedding/EmbeddingResultConvert.java",
"content": "package io.github.lnyocly.ai4j.convert.embedding;\n\nimport io.github.lnyocly.ai4j.platform.openai.embedding.entity.EmbeddingResponse;\n\n\n/**\n * @Author cly\n * @param \n */\npublic interface EmbeddingResultConvert {\n EmbeddingResponse convertEmbeddingResponse(T t);\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/document/RecursiveCharacterTextSplitter.java",
"content": "package io.github.lnyocly.ai4j.document;\n\nimport lombok.extern.slf4j.Slf4j;\nimport java.util.ArrayList;\nimport java.util.Arrays;\nimport java.util.List;\n\n/**\n * @Author cly\n * @Description 分词器\n * @Date 2024/8/2 22:59\n */\n@Slf4j\npublic class RecursiveCharacterTextSplitter {\n private List separators;\n private int chunkSize = 500;\n private int chunkOverlap = 50;\n\n // 构造函数，接受分隔符列表、块大小和块重叠作为参数\n public RecursiveCharacterTextSplitter(List separators, int chunkSize, int chunkOverlap) {\n // 如果分隔符列表为null，则使用默认值\n if (separators == null) {\n this.separators = Arrays.asList(\"\\n\\n\", \"\\n\", \" \", \"\");\n } else {\n this.separators = separators;\n }\n this.chunkSize = chunkSize;\n this.chunkOverlap = chunkOverlap;\n }\n\n public RecursiveCharacterTextSplitter(int chunkSize, int chunkOverlap) {\n this.separators = Arrays.asList(\"\\n\\n\", \"\\n\", \" \", \"\");\n this.chunkSize = chunkSize;\n this.chunkOverlap = chunkOverlap;\n }\n\n // 将文本分割成块的方法\n public List splitText(String text) {\n // 声明一个空的字符串列表，用于存储最终的文本块\n List finalChunks = new ArrayList<>();\n String separator = separators.get(separators.size() - 1);\n\n // 循环遍历分隔符列表，找到可以在文本中找到的最合适的分隔符\n for (String s : separators) {\n if (text.contains(s) || s.isEmpty()) {\n separator = s;\n break;\n }\n }\n\n List splits = Arrays.asList(text.split(separator));\n\n // 声明一个空的字符串列表，用于存储长度小于块大小的子字符串\n List goodSplits = new ArrayList<>();\n // 循环遍历子字符串列表，将较短的子字符串添加到goodSplits列表中，将较长的子字符串递归地传递给splitText方法\n for (String s : splits) {\n if (s.length() < chunkSize) {\n goodSplits.add(s);\n } else {\n if (!goodSplits.isEmpty()) {\n // 将goodSplits列表中的子字符串合并为一个文本块，并将其添加到最终的文本块列表中\n List mergedText = mergeSplits(goodSplits, separator);\n finalChunks.addAll(mergedText);\n goodSplits.clear();\n }\n // 递归地将较长的子字符串传递给splitText方法\n List otherInfo = splitText(s);\n finalChunks.addAll(otherInfo);\n }\n }\n\n if (!goodSplits.isEmpty()) {\n List mergedText = mergeSplits(goodSplits, separator);\n finalChunks.addAll(mergedText);\n }\n\n return finalChunks;\n }\n\n private List mergeSplits(List splits, String separator) {\n int separatorLen = separator.length();\n\n List docs = new ArrayList<>();\n List currentDoc = new ArrayList<>();\n int total = 0;\n\n for (String d : splits) {\n int len = d.length();\n if (total + len + (separatorLen > 0 && !currentDoc.isEmpty() ? separatorLen : 0) > chunkSize) {\n if (total > chunkSize) {\n log.warn(\"Warning: Created a chunk of size {}, which is longer than the specified {}\", total, chunkSize);\n }\n if (!currentDoc.isEmpty()) {\n String doc = joinDocs(currentDoc, separator);\n if (doc != null) {\n docs.add(doc);\n }\n // 通过移除currentDoc中的文档，将currentDoc的长度减小到指定的文档重叠长度chunkOverlap或更小, 结果存到下一个chunk的开始位置\n while (total > chunkOverlap || (total + len + (separatorLen > 0 && !currentDoc.isEmpty() ? separatorLen : 0) > chunkSize && total > 0)) {\n total -= currentDoc.get(0).length() + (separatorLen > 0 && currentDoc.size() > 1 ? separatorLen : 0);\n currentDoc.remove(0);\n }\n }\n }\n currentDoc.add(d);\n total += len + (separatorLen > 0 && currentDoc.size() > 1 ? separatorLen : 0);\n }\n\n String doc = joinDocs(currentDoc, separator);\n if (doc != null) {\n docs.add(doc);\n }\n\n return docs;\n }\n\n private String joinDocs(List docs, String separator) {\n if (docs.isEmpty()) {\n return null;\n }\n StringBuilder sb = new StringBuilder();\n for (int i = 0; i < docs.size(); i++) {\n sb.append(docs.get(i));\n if (i < docs.size() - 1) {\n sb.append(separator);\n }\n }\n return sb.toString();\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/document/TikaUtil.java",
"content": "package io.github.lnyocly.ai4j.document;\n\nimport org.apache.tika.Tika;\nimport org.apache.tika.exception.TikaException;\nimport org.apache.tika.metadata.Metadata;\nimport org.apache.tika.parser.AutoDetectParser;\nimport org.apache.tika.parser.ParseContext;\nimport org.apache.tika.sax.BodyContentHandler;\nimport org.xml.sax.SAXException;\n\nimport java.io.File;\nimport java.io.IOException;\nimport java.io.InputStream;\n\npublic class TikaUtil {\n\n private static final Tika tika = new Tika();\n\n /**\n * 解析File文件，返回文档内容\n * @param file 要解析的文件\n * @return 解析后的文档内容\n * @throws IOException\n * @throws TikaException\n * @throws SAXException\n */\n public static String parseFile(File file) throws IOException, TikaException, SAXException {\n try (InputStream stream = file.toURI().toURL().openStream()) {\n return parseInputStream(stream);\n }\n }\n\n /**\n * 解析InputStream输入流，返回文档内容\n * @param stream 要解析的输入流\n * @return 解析后的文档内容\n * @throws IOException\n * @throws TikaException\n * @throws SAXException\n */\n public static String parseInputStream(InputStream stream) throws IOException, TikaException, SAXException {\n BodyContentHandler handler = new BodyContentHandler();\n Metadata metadata = new Metadata();\n AutoDetectParser parser = new AutoDetectParser();\n ParseContext context = new ParseContext();\n\n parser.parse(stream, handler, metadata, context);\n return handler.toString();\n }\n\n /**\n * 使用Tika简单接口解析文件，返回文档内容\n * @param file 要解析的文件\n * @return 解析后的文档内容\n * @throws IOException\n * @throws TikaException\n */\n public static String parseFileWithTika(File file) throws IOException, TikaException {\n return tika.parseToString(file);\n }\n\n /**\n * 解析InputStream输入流，使用Tika简单接口，返回文档内容\n * @param stream 要解析的输入流\n * @return 解析后的文档内容\n * @throws IOException\n * @throws TikaException\n */\n public static String parseInputStreamWithTika(InputStream stream) throws IOException, TikaException {\n return tika.parseToString(stream);\n }\n\n /**\n * 检测File文件的MIME类型\n * @param file 要检测的文件\n * @return MIME类型\n * @throws IOException\n */\n public static String detectMimeType(File file) throws IOException {\n return tika.detect(file);\n }\n\n /**\n * 检测InputStream输入流的MIME类型\n * @param stream 要检测的输入流\n * @return MIME类型\n * @throws IOException\n */\n public static String detectMimeType(InputStream stream) throws IOException {\n return tika.detect(stream);\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/exception/Ai4jException.java",
"content": "package io.github.lnyocly.ai4j.exception;\n\n/**\n * Base runtime exception for ai4j shared abstractions.\n */\npublic class Ai4jException extends RuntimeException {\n\n public Ai4jException(String message) {\n super(message);\n }\n\n public Ai4jException(String message, Throwable cause) {\n super(message, cause);\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/exception/CommonException.java",
"content": "package io.github.lnyocly.ai4j.exception;\n\n/**\n * Legacy exception kept for 1.x compatibility.\n */\npublic class CommonException extends Ai4jException {\n\n public CommonException(String msg) {\n super(msg);\n }\n}\n\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/exception/chain/AbstractErrorHandler.java",
"content": "package io.github.lnyocly.ai4j.exception.chain;\n\nimport io.github.lnyocly.ai4j.exception.error.Error;\nimport io.github.lnyocly.ai4j.exception.error.OpenAiError;\n\n/**\n * @Author cly\n * @Description 错误处理抽象\n * @Date 2024/9/18 20:57\n */\npublic abstract class AbstractErrorHandler implements IErrorHandler{\n protected IErrorHandler nextHandler;\n\n @Override\n public void setNext(IErrorHandler handler) {\n this.nextHandler = handler;\n }\n\n protected Error handleNext(String errorInfo) {\n if (nextHandler != null) {\n return nextHandler.parseError(errorInfo);\n }\n return null;\n }\n\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/exception/chain/ErrorHandler.java",
"content": "package io.github.lnyocly.ai4j.exception.chain;\n\nimport io.github.lnyocly.ai4j.exception.chain.impl.HunyuanErrorHandler;\nimport io.github.lnyocly.ai4j.exception.chain.impl.OpenAiErrorHandler;\nimport io.github.lnyocly.ai4j.exception.chain.impl.UnknownErrorHandler;\nimport io.github.lnyocly.ai4j.exception.error.Error;\n\nimport java.util.ArrayList;\nimport java.util.List;\n\n/**\n * @Author cly\n * @Description 创建错误处理的单例\n * @Date 2024/9/18 21:09\n */\npublic class ErrorHandler {\n private List handlers;\n private IErrorHandler chain;\n\n private ErrorHandler() {\n handlers = new ArrayList<>();\n // 添加错误处理器\n handlers.add(new OpenAiErrorHandler());\n handlers.add(new HunyuanErrorHandler());\n\n // 兜底的错误处理\n handlers.add(new UnknownErrorHandler());\n\n // 组装链\n this.assembleChain();\n }\n\n private void assembleChain(){\n chain = handlers.get(0);\n IErrorHandler curr = handlers.get(0);\n for (int i = 1; i < handlers.size(); i++) {\n curr.setNext(handlers.get(i));\n curr = handlers.get(i);\n }\n }\n\n private static class ErrorHandlerHolder {\n private static final ErrorHandler INSTANCE = new ErrorHandler();\n }\n\n public static ErrorHandler getInstance() {\n return ErrorHandlerHolder.INSTANCE;\n }\n\n public Error process(String errorSring){\n return chain.parseError(errorSring);\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/exception/chain/IErrorHandler.java",
"content": "package io.github.lnyocly.ai4j.exception.chain;\n\nimport io.github.lnyocly.ai4j.exception.error.Error;\nimport io.github.lnyocly.ai4j.exception.error.OpenAiError;\n\n/**\n * @Author cly\n * @Description 错误处理接口\n * @Date 2024/9/18 20:55\n */\npublic interface IErrorHandler {\n void setNext(IErrorHandler handler);\n Error parseError(String errorInfo);\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/exception/chain/impl/HunyuanErrorHandler.java",
"content": "package io.github.lnyocly.ai4j.exception.chain.impl;\n\nimport com.alibaba.fastjson2.JSON;\nimport io.github.lnyocly.ai4j.exception.CommonException;\nimport io.github.lnyocly.ai4j.exception.chain.AbstractErrorHandler;\nimport io.github.lnyocly.ai4j.exception.error.Error;\nimport io.github.lnyocly.ai4j.exception.error.HunyuanError;\nimport io.github.lnyocly.ai4j.exception.error.OpenAiError;\nimport org.apache.commons.lang3.ObjectUtils;\n\n/**\n * @Author cly\n * @Description 混元错误处理\n * @Date 2024/9/18 23:59\n */\npublic class HunyuanErrorHandler extends AbstractErrorHandler {\n @Override\n public Error parseError(String errorInfo) {\n // 解析json字符串\n try{\n HunyuanError hunyuanError = JSON.parseObject(errorInfo, HunyuanError.class);\n\n HunyuanError.Response response = hunyuanError.getResponse();\n\n if(ObjectUtils.isEmpty(response)){\n // 交给下一个节点处理\n return nextHandler.parseError(errorInfo);\n }\n\n HunyuanError.Response.Error error = response.getError();\n if(ObjectUtils.isEmpty(error)){\n // 交给下一个节点处理\n return nextHandler.parseError(errorInfo);\n }\n\n return new Error(error.getMessage(),error.getCode(),null,error.getCode());\n }catch (Exception e){\n throw new CommonException(errorInfo);\n }\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/exception/chain/impl/OpenAiErrorHandler.java",
"content": "package io.github.lnyocly.ai4j.exception.chain.impl;\n\nimport com.alibaba.fastjson2.JSON;\nimport io.github.lnyocly.ai4j.exception.CommonException;\nimport io.github.lnyocly.ai4j.exception.chain.AbstractErrorHandler;\nimport io.github.lnyocly.ai4j.exception.error.Error;\nimport io.github.lnyocly.ai4j.exception.error.OpenAiError;\nimport org.apache.commons.lang3.ObjectUtils;\n\n/**\n * @Author cly\n * @Description OpenAi错误处理\n *\n * [openai, zhipu, deepseek, lingyi, moonshot] 错误返回类似，这里共用一个处理类\n *\n * @Date 2024/9/18 21:01\n */\npublic class OpenAiErrorHandler extends AbstractErrorHandler {\n\n @Override\n public Error parseError(String errorInfo) {\n // 解析json字符串\n try{\n OpenAiError openAiError = JSON.parseObject(errorInfo, OpenAiError.class);\n\n Error error = openAiError.getError();\n if(ObjectUtils.isEmpty(error)){\n // 交给下一个节点处理\n return nextHandler.parseError(errorInfo);\n }\n return error;\n }catch (Exception e){\n throw new CommonException(errorInfo);\n }\n\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/exception/chain/impl/UnknownErrorHandler.java",
"content": "package io.github.lnyocly.ai4j.exception.chain.impl;\n\nimport io.github.lnyocly.ai4j.exception.chain.AbstractErrorHandler;\nimport io.github.lnyocly.ai4j.exception.error.Error;\n\n/**\n * @Author cly\n * @Description 未知的错误处理，用于兜底处理\n * @Date 2024/9/18 21:08\n */\npublic class UnknownErrorHandler extends AbstractErrorHandler {\n @Override\n public Error parseError(String errorInfo) {\n Error error = new Error();\n\n error.setParam(null);\n error.setType(\"Unknown Type\");\n error.setCode(\"Unknown Code\");\n error.setMessage(errorInfo);\n\n return error;\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/exception/error/Error.java",
"content": "package io.github.lnyocly.ai4j.exception.error;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description 基础错误实体\n * @Date 2024/9/18 23:50\n */\n@Data\n@AllArgsConstructor\n@NoArgsConstructor\npublic class Error {\n private String message;\n private String type;\n private String param;\n private String code;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/exception/error/HunyuanError.java",
"content": "package io.github.lnyocly.ai4j.exception.error;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description 腾讯混元错误实体\n *\n * {\"Response\":{\"RequestId\":\"e4650694-f018-4490-b4d0-d5242cd68106\",\"Error\":{\"Code\":\"InvalidParameterValue.Model\",\"Message\":\"模型不存在\"}}}\n *\n * @Date 2024/9/18 21:28\n */\n@Data\n@AllArgsConstructor\n@NoArgsConstructor\npublic class HunyuanError {\n private Response Response;\n\n @Data\n @AllArgsConstructor\n @NoArgsConstructor\n public class Response{\n private Error Error;\n\n @Data\n @AllArgsConstructor\n @NoArgsConstructor\n public class Error{\n private String Code;\n private String Message;\n }\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/exception/error/OpenAiError.java",
"content": "package io.github.lnyocly.ai4j.exception.error;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Data;\nimport lombok.Getter;\nimport lombok.NoArgsConstructor;\n\n/**\n * @Author cly\n * @Description OpenAi错误返回实体类\n *\n * {\n * \"error\": {\n * \"message\": \"Incorrect API key provided: sk-proj-*************************************************************************************************************************8YA1. You can find your API key at https://platform.openai.com/account/api-keys.\",\n * \"type\": \"invalid_request_error\",\n * \"param\": null,\n * \"code\": \"invalid_api_key\"\n * }\n * }\n *\n * @Date 2024/9/18 18:44\n */\n@Data\n@AllArgsConstructor\n@NoArgsConstructor\npublic class OpenAiError {\n private Error error;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/interceptor/ContentTypeInterceptor.java",
"content": "package io.github.lnyocly.ai4j.interceptor;\n\nimport okhttp3.Interceptor;\nimport okhttp3.MediaType;\nimport okhttp3.Response;\nimport okhttp3.ResponseBody;\nimport okio.Buffer;\nimport okio.BufferedSource;\n\nimport java.io.IOException;\nimport java.nio.charset.StandardCharsets;\n\n/**\n * @Author cly\n * @Description TODO\n * @Date 2024/9/20 18:56\n */\npublic class ContentTypeInterceptor implements Interceptor {\n\n private static final MediaType EVENT_STREAM_MEDIA_TYPE = MediaType.get(\"text/event-stream\");\n private static final String NDJSON_CONTENT_TYPE = \"application/x-ndjson\";\n private static final String SSE_CONTENT_TYPE = \"text/event-stream\";\n\n @Override\n public Response intercept(Chain chain) throws IOException {\n Response response = chain.proceed(chain.request());\n if (!isNdjsonResponse(response)) {\n return response;\n }\n\n ResponseBody responseBody = response.body();\n if (responseBody == null) {\n return response;\n }\n\n return response.newBuilder()\n .header(\"Content-Type\", SSE_CONTENT_TYPE)\n .body(ResponseBody.create(toSseBody(readBody(responseBody)), EVENT_STREAM_MEDIA_TYPE))\n .build();\n }\n\n private boolean isNdjsonResponse(Response response) {\n String contentType = response.header(\"Content-Type\");\n return contentType != null && contentType.contains(NDJSON_CONTENT_TYPE);\n }\n\n private String readBody(ResponseBody responseBody) throws IOException {\n BufferedSource source = responseBody.source();\n source.request(Long.MAX_VALUE);\n Buffer buffer = source.getBuffer();\n return buffer.clone().readString(StandardCharsets.UTF_8);\n }\n\n private String toSseBody(String ndjsonBody) {\n StringBuilder sseBody = new StringBuilder();\n String[] ndjsonLines = ndjsonBody.split(\"\\n\");\n for (String jsonLine : ndjsonLines) {\n if (!jsonLine.trim().isEmpty()) {\n sseBody.append(\"data: \").append(jsonLine).append(\"\\n\\n\");\n }\n }\n return sseBody.toString();\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/interceptor/ErrorInterceptor.java",
"content": "package io.github.lnyocly.ai4j.interceptor;\n\nimport com.alibaba.fastjson2.JSON;\nimport com.alibaba.fastjson2.JSONObject;\nimport io.github.lnyocly.ai4j.exception.CommonException;\nimport io.github.lnyocly.ai4j.exception.chain.ErrorHandler;\nimport io.github.lnyocly.ai4j.exception.error.Error;\nimport lombok.extern.slf4j.Slf4j;\nimport okhttp3.Interceptor;\nimport okhttp3.MediaType;\nimport okhttp3.Request;\nimport okhttp3.Response;\nimport okhttp3.ResponseBody;\nimport org.jetbrains.annotations.NotNull;\nimport okio.Buffer;\n\nimport java.io.IOException;\nimport java.nio.charset.StandardCharsets;\n\n/**\n * Intercepts API responses and raises provider-specific exceptions only when\n * the payload contains structured error objects.\n */\n@Slf4j\npublic class ErrorInterceptor implements Interceptor {\n\n @NotNull\n @Override\n public Response intercept(@NotNull Chain chain) throws IOException {\n Request original = chain.request();\n Response response = chain.proceed(original);\n\n if (isStreamingResponse(response)) {\n return response;\n }\n\n ResponseBody responseBody = response.body();\n byte[] contentBytes = getResponseBodyBytes(responseBody);\n String content = new String(contentBytes, StandardCharsets.UTF_8);\n boolean streamingRequest = isStreamingRequest(original);\n\n if (!response.isSuccessful() && response.code() != 100 && response.code() != 101) {\n if (streamingRequest) {\n return rebuildResponse(response, responseBody, contentBytes);\n }\n throw buildCommonException(response.code(), response.message(), content);\n }\n\n if (containsStructuredError(content)) {\n if (streamingRequest) {\n return rebuildResponse(response, responseBody, contentBytes);\n }\n ErrorHandler errorHandler = ErrorHandler.getInstance();\n Error error = errorHandler.process(content);\n log.error(\"AI request failed: {}\", error.getMessage());\n throw new CommonException(error.getMessage());\n }\n\n return rebuildResponse(response, responseBody, contentBytes);\n }\n\n private CommonException buildCommonException(int code, String message, String payload) {\n String errorMsg = payload == null ? \"\" : payload;\n if (errorMsg.trim().isEmpty()) {\n errorMsg = code + \" \" + message;\n log.error(\"AI request failed: {}\", errorMsg);\n return new CommonException(errorMsg);\n }\n\n try {\n JSONObject object = JSON.parseObject(errorMsg);\n if (object != null) {\n ErrorHandler errorHandler = ErrorHandler.getInstance();\n Error error = errorHandler.process(errorMsg);\n log.error(\"AI request failed: {}\", error.getMessage());\n return new CommonException(error.getMessage());\n }\n } catch (Exception ignored) {\n // Keep raw payload for unknown providers or non-JSON responses.\n }\n\n log.error(\"AI request failed: {}\", errorMsg);\n return new CommonException(errorMsg);\n }\n\n private boolean containsStructuredError(String content) {\n if (content == null || content.trim().isEmpty()) {\n return false;\n }\n\n JSONObject object;\n try {\n object = JSON.parseObject(content);\n } catch (Exception e) {\n return false;\n }\n if (object == null) {\n return false;\n }\n\n Object openAiError = object.get(\"error\");\n if (openAiError instanceof JSONObject) {\n return true;\n }\n if (openAiError instanceof String && !((String) openAiError).trim().isEmpty()) {\n return true;\n }\n\n JSONObject hunyuanResponse = object.getJSONObject(\"Response\");\n if (hunyuanResponse != null) {\n Object hunyuanError = hunyuanResponse.get(\"Error\");\n if (hunyuanError instanceof JSONObject) {\n return true;\n }\n if (hunyuanError instanceof String && !((String) hunyuanError).trim().isEmpty()) {\n return true;\n }\n }\n\n String status = object.getString(\"status\");\n return \"failed\".equalsIgnoreCase(status);\n }\n\n private boolean isStreamingResponse(Response response) {\n ResponseBody body = response.body();\n if (body == null) {\n return false;\n }\n MediaType contentType = body.contentType();\n if (contentType == null) {\n return false;\n }\n String type = contentType.toString();\n return type.contains(\"text/event-stream\") || type.contains(\"application/x-ndjson\");\n }\n\n private boolean isStreamingRequest(Request request) {\n if (request == null) {\n return false;\n }\n String accept = request.header(\"Accept\");\n if (accept != null) {\n String normalizedAccept = accept.toLowerCase();\n if (normalizedAccept.contains(\"text/event-stream\") || normalizedAccept.contains(\"application/x-ndjson\")) {\n return true;\n }\n }\n if (request.body() == null) {\n return false;\n }\n try {\n Buffer buffer = new Buffer();\n request.body().writeTo(buffer);\n String body = buffer.readString(StandardCharsets.UTF_8);\n String normalizedBody = body == null ? \"\" : body.toLowerCase();\n return normalizedBody.contains(\"\\\"stream\\\":true\") || normalizedBody.contains(\"\\\"stream\\\": true\");\n } catch (Exception ignored) {\n return false;\n }\n }\n\n private Response rebuildResponse(Response response, ResponseBody responseBody, byte[] contentBytes) {\n MediaType contentType = responseBody == null ? null : responseBody.contentType();\n ResponseBody newBody = ResponseBody.create(contentType, contentBytes);\n return response.newBuilder().body(newBody).build();\n }\n\n private byte[] getResponseBodyBytes(ResponseBody responseBody) throws IOException {\n if (responseBody == null) {\n return new byte[0];\n }\n return responseBody.bytes();\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/listener/AbstractManagedStreamListener.java",
"content": "package io.github.lnyocly.ai4j.listener;\n\nimport io.github.lnyocly.ai4j.exception.CommonException;\nimport lombok.Getter;\nimport okhttp3.Response;\nimport okhttp3.sse.EventSource;\nimport okhttp3.sse.EventSourceListener;\nimport org.jetbrains.annotations.NotNull;\nimport org.jetbrains.annotations.Nullable;\n\nimport java.util.concurrent.CountDownLatch;\nimport java.util.concurrent.TimeUnit;\nimport java.util.concurrent.TimeoutException;\n\nabstract class AbstractManagedStreamListener extends EventSourceListener implements ManagedStreamListener {\n\n @Getter\n private volatile CountDownLatch countDownLatch = new CountDownLatch(1);\n\n @Getter\n private EventSource eventSource;\n\n private volatile boolean cancelRequested = false;\n private volatile Throwable failure;\n private volatile Response failureResponse;\n private volatile long openedAtEpochMs;\n private volatile long lastActivityAtEpochMs;\n private volatile boolean receivedEvent;\n\n @Override\n public void onOpen(@NotNull EventSource eventSource, @NotNull Response response) {\n attachEventSource(eventSource);\n cancelRequested = false;\n openedAtEpochMs = System.currentTimeMillis();\n lastActivityAtEpochMs = openedAtEpochMs;\n receivedEvent = false;\n }\n\n @Override\n public void onFailure(@NotNull EventSource eventSource, @Nullable Throwable t, @Nullable Response response) {\n attachEventSource(eventSource);\n if (cancelRequested) {\n finishAttempt();\n return;\n }\n recordFailure(resolveFailure(t, response), response);\n finishAttempt();\n }\n\n public void cancelStream() {\n cancelRequested = true;\n cancelActiveEventSource();\n finishAttempt();\n }\n\n @Override\n public void awaitCompletion(StreamExecutionOptions options) throws InterruptedException {\n CountDownLatch latch = countDownLatch;\n long firstTokenTimeoutMs = options == null ? 0L : options.normalizedFirstTokenTimeoutMs();\n long idleTimeoutMs = options == null ? 0L : options.normalizedIdleTimeoutMs();\n if (openedAtEpochMs <= 0L) {\n long now = System.currentTimeMillis();\n openedAtEpochMs = now;\n lastActivityAtEpochMs = now;\n }\n while (true) {\n if (latch.await(100L, TimeUnit.MILLISECONDS)) {\n return;\n }\n if (cancelRequested) {\n return;\n }\n if (Thread.currentThread().isInterrupted()) {\n cancelStream();\n throw new InterruptedException(\"Model stream interrupted\");\n }\n long now = System.currentTimeMillis();\n if (!receivedEvent\n && firstTokenTimeoutMs > 0L\n && openedAtEpochMs > 0L\n && now - openedAtEpochMs >= firstTokenTimeoutMs) {\n recordFailure(new TimeoutException(\n \"Timed out waiting for first model stream event after \" + firstTokenTimeoutMs + \" ms\"\n ));\n cancelActiveEventSource();\n finishAttempt(latch);\n return;\n }\n if (receivedEvent\n && idleTimeoutMs > 0L\n && lastActivityAtEpochMs > 0L\n && now - lastActivityAtEpochMs >= idleTimeoutMs) {\n recordFailure(new TimeoutException(\n \"Timed out waiting for model stream activity after \" + idleTimeoutMs + \" ms\"\n ));\n cancelActiveEventSource();\n finishAttempt(latch);\n return;\n }\n }\n }\n\n @Override\n public Throwable getFailure() {\n return failure;\n }\n\n @Override\n public void recordFailure(Throwable failure) {\n recordFailure(failure, null);\n }\n\n public void dispatchFailure() {\n Throwable currentFailure = failure;\n if (currentFailure == null) {\n return;\n }\n Response response = failureResponse;\n clearFailure();\n error(currentFailure, response);\n }\n\n @Override\n public void clearFailure() {\n failure = null;\n failureResponse = null;\n }\n\n @Override\n public void prepareForRetry() {\n clearFailure();\n eventSource = null;\n cancelRequested = false;\n openedAtEpochMs = 0L;\n lastActivityAtEpochMs = 0L;\n receivedEvent = false;\n resetRetryState();\n }\n\n @Override\n public boolean hasReceivedEvent() {\n return receivedEvent;\n }\n\n @Override\n public boolean isCancelRequested() {\n return cancelRequested;\n }\n\n @Override\n public void onRetrying(Throwable failure, int attempt, int maxAttempts) {\n retry(failure, attempt, maxAttempts);\n }\n\n protected void error(Throwable t, Response response) {\n }\n\n protected void retry(Throwable t, int attempt, int maxAttempts) {\n }\n\n protected void resetRetryState() {\n }\n\n protected Throwable resolveFailure(@Nullable Throwable t, @Nullable Response response) {\n if (t != null && t.getMessage() != null && !t.getMessage().trim().isEmpty()) {\n return t;\n }\n if (response != null) {\n String message = (response.code() + \" \" + (response.message() == null ? \"\" : response.message())).trim();\n if (!message.isEmpty()) {\n return new CommonException(message);\n }\n }\n return t == null ? new CommonException(\"stream request failed\") : t;\n }\n\n protected final void attachEventSource(EventSource eventSource) {\n this.eventSource = eventSource;\n }\n\n protected final void clearCancelRequested() {\n cancelRequested = false;\n }\n\n protected final void markActivity() {\n long now = System.currentTimeMillis();\n if (openedAtEpochMs <= 0L) {\n openedAtEpochMs = now;\n }\n lastActivityAtEpochMs = now;\n receivedEvent = true;\n }\n\n protected final void finishAttempt() {\n finishAttempt(countDownLatch);\n }\n\n protected final void finishAttempt(CountDownLatch latch) {\n CountDownLatch release = advanceLatch(latch);\n release.countDown();\n }\n\n protected final void cancelActiveEventSource() {\n EventSource activeEventSource = eventSource;\n if (activeEventSource != null) {\n try {\n activeEventSource.cancel();\n } catch (Exception ignored) {\n // Best effort cancel so the waiting caller can continue unwinding.\n }\n }\n }\n\n private void recordFailure(Throwable failure, Response response) {\n this.failure = failure;\n this.failureResponse = response;\n }\n\n private synchronized CountDownLatch advanceLatch(CountDownLatch expected) {\n CountDownLatch current = countDownLatch;\n if (expected != null && current != expected) {\n return expected;\n }\n countDownLatch = new CountDownLatch(1);\n return current;\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/listener/ImageSseListener.java",
"content": "package io.github.lnyocly.ai4j.listener;\n\nimport io.github.lnyocly.ai4j.platform.openai.image.entity.ImageData;\nimport io.github.lnyocly.ai4j.platform.openai.image.entity.ImageGenerationResponse;\nimport io.github.lnyocly.ai4j.platform.openai.image.entity.ImageStreamEvent;\nimport lombok.Getter;\nimport okhttp3.Response;\nimport okhttp3.sse.EventSourceListener;\nimport org.jetbrains.annotations.NotNull;\nimport org.jetbrains.annotations.Nullable;\n\nimport java.util.ArrayList;\nimport java.util.List;\nimport java.util.concurrent.CountDownLatch;\n\n/**\n * @Author cly\n * @Description 图片生成流式监听器\n * @Date 2026/1/31\n */\npublic abstract class ImageSseListener extends EventSourceListener {\n\n /**\n * 异常回调\n */\n protected void error(Throwable t, Response response) {}\n\n /**\n * 事件回调\n */\n protected abstract void onEvent();\n\n @Getter\n private final List events = new ArrayList<>();\n\n @Getter\n private ImageStreamEvent currEvent;\n\n @Getter\n private final ImageGenerationResponse response = new ImageGenerationResponse();\n\n @Getter\n private CountDownLatch countDownLatch = new CountDownLatch(1);\n\n public void accept(ImageStreamEvent event) {\n this.currEvent = event;\n this.events.add(event);\n appendResponse(event);\n this.onEvent();\n }\n\n private void appendResponse(ImageStreamEvent event) {\n if (event == null) {\n return;\n }\n if (event.getUsage() != null) {\n response.setUsage(event.getUsage());\n }\n if (event.getCreatedAt() != null && response.getCreated() == null) {\n response.setCreated(event.getCreatedAt());\n }\n if (shouldAppendImage(event)) {\n if (response.getData() == null) {\n response.setData(new ArrayList<>());\n }\n ImageData imageData = new ImageData();\n imageData.setUrl(event.getUrl());\n imageData.setB64Json(event.getB64Json());\n imageData.setSize(event.getSize());\n response.getData().add(imageData);\n }\n }\n\n private boolean shouldAppendImage(ImageStreamEvent event) {\n if (event == null) {\n return false;\n }\n if (event.getUrl() == null && event.getB64Json() == null) {\n return false;\n }\n String type = event.getType();\n return type == null || !type.contains(\"partial_image\");\n }\n\n public void complete() {\n countDownLatch.countDown();\n countDownLatch = new CountDownLatch(1);\n }\n\n public void onError(Throwable t, Response response) {\n this.error(t, response);\n }\n\n @Override\n public void onFailure(@NotNull okhttp3.sse.EventSource eventSource, @Nullable Throwable t, @Nullable Response response) {\n this.error(t, response);\n complete();\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/listener/ManagedStreamListener.java",
"content": "package io.github.lnyocly.ai4j.listener;\n\npublic interface ManagedStreamListener {\n\n void awaitCompletion(StreamExecutionOptions options) throws InterruptedException;\n\n Throwable getFailure();\n\n void recordFailure(Throwable failure);\n\n void clearFailure();\n\n void prepareForRetry();\n\n boolean hasReceivedEvent();\n\n boolean isCancelRequested();\n\n void onRetrying(Throwable failure, int attempt, int maxAttempts);\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/listener/RealtimeListener.java",
"content": "package io.github.lnyocly.ai4j.listener;\n\nimport lombok.extern.slf4j.Slf4j;\nimport okhttp3.Response;\nimport okhttp3.WebSocket;\nimport okhttp3.WebSocketListener;\nimport okio.ByteString;\nimport org.jetbrains.annotations.NotNull;\nimport org.jetbrains.annotations.Nullable;\n\n/**\n * @Author cly\n * @Description RealtimeListener, 用于统一处理WebSocket的事件（Realtime客户端专用）\n * @Date 2024/10/12 16:33\n */\n@Slf4j\npublic abstract class RealtimeListener extends WebSocketListener {\n\n protected abstract void onOpen(WebSocket webSocket);\n protected abstract void onMessage(ByteString bytes);\n protected abstract void onMessage(String text);\n protected abstract void onFailure();\n\n @Override\n public void onOpen(@NotNull WebSocket webSocket, @NotNull Response response) {\n log.info(\"WebSocket Opened: \" + response.message());\n this.onOpen(webSocket);\n }\n\n @Override\n public void onMessage(@NotNull WebSocket webSocket, @NotNull ByteString bytes) {\n log.info(\"Receive Byte Message: \" + bytes.toString());\n this.onMessage(bytes);\n }\n\n @Override\n public void onMessage(@NotNull WebSocket webSocket, @NotNull String text) {\n log.info(\"Receive String Message: \" + text);\n this.onMessage(text);\n }\n\n @Override\n public void onFailure(@NotNull WebSocket webSocket, @NotNull Throwable t, @Nullable Response response) {\n log.error(\"WebSocket Error: \", t);\n }\n\n @Override\n public void onClosing(@NotNull WebSocket webSocket, int code, @NotNull String reason) {\n }\n\n @Override\n public void onClosed(@NotNull WebSocket webSocket, int code, @NotNull String reason) {\n log.info(\"WebSocket Closed: \" + reason);\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/listener/ResponseSseListener.java",
"content": "package io.github.lnyocly.ai4j.listener;\n\nimport io.github.lnyocly.ai4j.platform.openai.response.entity.Response;\nimport io.github.lnyocly.ai4j.platform.openai.response.entity.ResponseStreamEvent;\nimport lombok.Getter;\nimport okhttp3.sse.EventSource;\nimport org.jetbrains.annotations.NotNull;\n\nimport java.util.ArrayList;\nimport java.util.List;\n\n\npublic abstract class ResponseSseListener extends AbstractManagedStreamListener {\n\n \n @Override\n protected void error(Throwable t, okhttp3.Response response) {\n }\n\n \n protected abstract void onEvent();\n\n @Getter\n private final List events = new ArrayList<>();\n\n @Getter\n private ResponseStreamEvent currEvent;\n\n @Getter\n private final Response response = new Response();\n\n @Getter\n private final StringBuilder outputText = new StringBuilder();\n\n @Getter\n private final StringBuilder reasoningSummary = new StringBuilder();\n\n @Getter\n private final StringBuilder functionArguments = new StringBuilder();\n\n @Getter\n private String currText = \"\";\n\n @Getter\n private String currFunctionArguments = \"\";\n\n public void accept(ResponseStreamEvent event) {\n this.currEvent = event;\n this.events.add(event);\n this.currText = \"\";\n this.currFunctionArguments = \"\";\n markActivity();\n applyEvent(event);\n this.onEvent();\n }\n\n private void applyEvent(ResponseStreamEvent event) {\n if (event == null) {\n return;\n }\n if (event.getResponse() != null) {\n mergeResponse(event.getResponse());\n }\n String type = event.getType();\n if (type == null) {\n return;\n }\n\n switch (type) {\n case \"response.output_text.delta\":\n if (event.getDelta() != null) {\n outputText.append(event.getDelta());\n currText = event.getDelta();\n }\n break;\n case \"response.output_text.done\":\n if (outputText.length() == 0 && event.getText() != null) {\n outputText.append(event.getText());\n currText = event.getText();\n }\n break;\n case \"response.reasoning_summary_text.delta\":\n if (event.getDelta() != null) {\n reasoningSummary.append(event.getDelta());\n }\n break;\n case \"response.reasoning_summary_text.done\":\n if (reasoningSummary.length() == 0 && event.getText() != null) {\n reasoningSummary.append(event.getText());\n }\n break;\n case \"response.function_call_arguments.delta\":\n if (event.getDelta() != null) {\n functionArguments.append(event.getDelta());\n currFunctionArguments = event.getDelta();\n }\n break;\n case \"response.function_call_arguments.done\":\n if (functionArguments.length() == 0 && event.getArguments() != null) {\n functionArguments.append(event.getArguments());\n currFunctionArguments = event.getArguments();\n }\n break;\n default:\n break;\n }\n }\n\n private void mergeResponse(Response source) {\n if (source == null) {\n return;\n }\n if (source.getId() != null) {\n response.setId(source.getId());\n }\n if (source.getObject() != null) {\n response.setObject(source.getObject());\n }\n if (source.getCreatedAt() != null) {\n response.setCreatedAt(source.getCreatedAt());\n }\n if (source.getModel() != null) {\n response.setModel(source.getModel());\n }\n if (source.getStatus() != null) {\n response.setStatus(source.getStatus());\n }\n if (source.getOutput() != null) {\n response.setOutput(source.getOutput());\n }\n if (source.getError() != null) {\n response.setError(source.getError());\n }\n if (source.getIncompleteDetails() != null) {\n response.setIncompleteDetails(source.getIncompleteDetails());\n }\n if (source.getInstructions() != null) {\n response.setInstructions(source.getInstructions());\n }\n if (source.getMaxOutputTokens() != null) {\n response.setMaxOutputTokens(source.getMaxOutputTokens());\n }\n if (source.getPreviousResponseId() != null) {\n response.setPreviousResponseId(source.getPreviousResponseId());\n }\n if (source.getUsage() != null) {\n response.setUsage(source.getUsage());\n }\n if (source.getMetadata() != null) {\n response.setMetadata(source.getMetadata());\n }\n if (source.getContextManagement() != null) {\n response.setContextManagement(source.getContextManagement());\n }\n }\n\n public void complete() {\n finishAttempt();\n }\n\n public void onError(Throwable t, okhttp3.Response response) {\n this.error(t, response);\n }\n\n @Override\n public void onClosed(@NotNull EventSource eventSource) {\n attachEventSource(eventSource);\n complete();\n }\n\n @Override\n protected void retry(Throwable t, int attempt, int maxAttempts) {\n }\n}\n\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/listener/SseListener.java",
"content": "package io.github.lnyocly.ai4j.listener;\n\nimport cn.hutool.core.util.StrUtil;\nimport com.fasterxml.jackson.core.JsonProcessingException;\nimport com.fasterxml.jackson.databind.JsonNode;\nimport com.fasterxml.jackson.databind.ObjectMapper;\nimport io.github.lnyocly.ai4j.exception.CommonException;\nimport io.github.lnyocly.ai4j.platform.openai.chat.entity.ChatCompletionResponse;\nimport io.github.lnyocly.ai4j.platform.openai.chat.entity.ChatMessage;\nimport io.github.lnyocly.ai4j.platform.openai.chat.entity.Choice;\nimport io.github.lnyocly.ai4j.platform.openai.chat.enums.ChatMessageType;\nimport io.github.lnyocly.ai4j.platform.openai.tool.ToolCall;\nimport io.github.lnyocly.ai4j.platform.openai.usage.Usage;\nimport lombok.Getter;\nimport lombok.Setter;\nimport lombok.extern.slf4j.Slf4j;\nimport okhttp3.Response;\nimport okhttp3.sse.EventSource;\nimport org.apache.commons.lang3.StringUtils;\nimport org.jetbrains.annotations.NotNull;\nimport org.jetbrains.annotations.Nullable;\n\nimport java.util.ArrayList;\nimport java.util.List;\n\n/**\n * @Author cly\n * @Description SseListener\n * @Date 2024/8/13 23:25\n */\n\n@Slf4j\npublic abstract class SseListener extends AbstractManagedStreamListener {\n /**\n * 异常回调\n */\n protected void error(Throwable t, Response response) {}\n\n protected abstract void send();\n /**\n * 最终的消息输出\n */\n @Getter\n private final StringBuilder output = new StringBuilder();\n\n /**\n * 流式输出，当前消息的内容(回答消息、函数参数)\n */\n @Getter\n private String currStr = \"\";\n\n /**\n * 流式输出，当前单条SSE消息对象，即ChatCompletionResponse对象\n */\n @Getter\n private String currData = \"\";\n\n /**\n * 记录当前所调用函数工具的名称\n */\n @Getter\n private String currToolName = \"\";\n\n /**\n * 记录当前是否为思考状态reasoning\n */\n @Getter\n private boolean isReasoning = false;\n\n /**\n * 思考内容的输出\n */\n @Getter\n private final StringBuilder reasoningOutput = new StringBuilder();\n\n /**\n * 是否显示每个函数调用输出的参数文本\n */\n @Getter\n @Setter\n private boolean showToolArgs = false;\n\n /**\n * 花费token\n */\n @Getter\n private final Usage usage = new Usage();\n\n @Setter\n @Getter\n private List toolCalls = new ArrayList<>();\n\n @Setter\n @Getter\n private ToolCall toolCall;\n\n /**\n * 最终的函数调用参数\n */\n private final StringBuilder argument = new StringBuilder();\n @Getter\n @Setter\n private String finishReason = null;\n\n @Override\n public void onEvent(@NotNull EventSource eventSource, @Nullable String id, @Nullable String type, @NotNull String data) {\n // 封装SSE消息对象\n currData = data;\n markActivity();\n if (getEventSource() == null) {\n attachEventSource(eventSource);\n }\n\n if (\"[DONE]\".equalsIgnoreCase(data)) {\n // 整个对话结束，结束前将SSE最后一条“DONE”消息发送出去\n currStr = \"\";\n this.send();\n\n return;\n }\n\n ObjectMapper objectMapper = new ObjectMapper();\n ChatCompletionResponse chatCompletionResponse = null;\n try {\n chatCompletionResponse = objectMapper.readValue(data, ChatCompletionResponse.class);\n } catch (JsonProcessingException e) {\n throw new CommonException(\"read data error\");\n }\n\n // 统计token，当设置include_usage = true时，最后一条消息会携带usage, 其他消息中usage为null\n Usage currUsage = chatCompletionResponse.getUsage();\n if(currUsage != null){\n usage.setPromptTokens(usage.getPromptTokens() + currUsage.getPromptTokens());\n usage.setCompletionTokens(usage.getCompletionTokens() + currUsage.getCompletionTokens());\n usage.setTotalTokens(usage.getTotalTokens() + currUsage.getTotalTokens());\n }\n\n\n List choices = chatCompletionResponse.getChoices();\n\n if((choices == null || choices.isEmpty()) && chatCompletionResponse.getUsage() != null){\n this.currStr = \"\";\n this.send();\n return;\n }\n\n if(choices == null || choices.isEmpty()){\n return;\n }\n ChatMessage responseMessage = choices.get(0).getDelta();\n if (responseMessage == null) {\n return;\n }\n List messageToolCalls = responseMessage.getToolCalls();\n ToolCall firstMessageToolCall = firstToolCall(messageToolCalls);\n\n finishReason = choices.get(0).getFinishReason();\n\n // Ollama 在工具调用时返回 stop 而非 tool_calls\n if(\"stop\".equals(finishReason)\n && responseMessage.getContent()!=null\n && \"\".equals(responseMessage.getContent().getText())\n && !toolCalls.isEmpty()){\n finishReason = \"tool_calls\";\n }\n\n\n // tool_calls回答已经结束\n if(\"tool_calls\".equals(finishReason)){\n if (toolCall != null) {\n consumeFragmentedToolCalls(messageToolCalls);\n finalizeCurrentToolCall();\n } else if (shouldTreatAsCompleteToolCalls(responseMessage, messageToolCalls)) {\n addCompleteToolCalls(messageToolCalls);\n } else {\n consumeFragmentedToolCalls(messageToolCalls);\n finalizeCurrentToolCall();\n }\n return;\n }\n // 消息回答完毕\n if (\"stop\".equals(finishReason)) {\n\n // ollama 最后一条消息只到stop\n if(responseMessage.getContent() != null && responseMessage.getContent().getText() != null) {\n currStr = responseMessage.getContent().getText();\n output.append(currStr);\n }else {\n currStr = \"\";\n }\n this.send();\n\n\n return;\n }\n\n if(ChatMessageType.ASSISTANT.getRole().equals(responseMessage.getRole())\n && (responseMessage.getContent()==null || StringUtils.isEmpty(responseMessage.getContent().getText()))\n && StringUtils.isEmpty(responseMessage.getReasoningContent())\n && isEmpty(messageToolCalls)){\n // 空消息忽略\n return;\n }\n\n\n if(isEmpty(messageToolCalls)) {\n\n\n // 判断是否为混元的tool最后一条说明性content，用于忽略\n // :{\"Role\":\"assistant\",\"Content\":\"计划使用get_current_weather工具来获取北京和深圳的当前天气。\\n\\t\\n\\t用户想要知道北京和深圳今天的天气情况。用户的请求是关于天气的查询，需要使用天气查询工具来获取信息。\"}\n if(toolCall !=null && StringUtils.isNotEmpty(argument)&& \"assistant\".equals(responseMessage.getRole()) && (responseMessage.getContent()!=null && StringUtils.isNotEmpty(responseMessage.getContent().getText())) ){\n return;\n }\n\n\n // 响应回答\n // 包括content和reasoning_content\n if(StringUtils.isNotEmpty(responseMessage.getReasoningContent())){\n isReasoning = true;\n // reasoningOutput 与 output 分离，目前仅用于deepseek\n reasoningOutput.append(responseMessage.getReasoningContent());\n //output.append(responseMessage.getReasoningContent());\n currStr = responseMessage.getReasoningContent();\n\n }else {\n isReasoning = false;\n if (responseMessage.getContent() == null) {\n this.send();\n return;\n }\n output.append(responseMessage.getContent().getText());\n currStr = responseMessage.getContent().getText();\n }\n\n this.send();\n\n\n }else{\n // 函数调用回答\n if (shouldTreatAsCompleteToolCalls(responseMessage, messageToolCalls)) {\n addCompleteToolCalls(messageToolCalls);\n } else {\n consumeFragmentedToolCalls(messageToolCalls);\n }\n }\n\n\n\n //log.info(\"测试结果：{}\", chatCompletionResponse);\n }\n\n @Override\n public void onClosed(@NotNull EventSource eventSource) {\n attachEventSource(eventSource);\n finishAttempt();\n clearCancelRequested();\n\n }\n\n @Override\n protected void resetRetryState() {\n finishReason = null;\n currData = \"\";\n currStr = \"\";\n currToolName = \"\";\n }\n\n private ToolCall firstToolCall(List calls) {\n if (isEmpty(calls)) {\n return null;\n }\n return calls.get(0);\n }\n\n private String safeToolArguments(ToolCall call) {\n if (call == null || call.getFunction() == null) {\n return \"\";\n }\n return StrUtil.emptyIfNull(call.getFunction().getArguments());\n }\n\n private String safeToolName(ToolCall call) {\n if (call == null || call.getFunction() == null) {\n return \"\";\n }\n return StrUtil.emptyIfNull(call.getFunction().getName());\n }\n\n private boolean isEmpty(List values) {\n return values == null || values.isEmpty();\n }\n\n private boolean shouldTreatAsCompleteToolCalls(ChatMessage responseMessage, List messageToolCalls) {\n if (responseMessage == null || responseMessage.getContent() == null) {\n return false;\n }\n if (!\"\".equals(responseMessage.getContent().getText()) || isEmpty(messageToolCalls)) {\n return false;\n }\n for (ToolCall call : messageToolCalls) {\n if (!hasToolName(call) || !hasStructuredJsonObjectArguments(call)) {\n return false;\n }\n }\n return true;\n }\n\n private void addCompleteToolCalls(List completeToolCalls) {\n if (isEmpty(completeToolCalls)) {\n return;\n }\n for (ToolCall completeToolCall : completeToolCalls) {\n if (completeToolCall == null || completeToolCall.getFunction() == null || !hasToolName(completeToolCall)) {\n continue;\n }\n currToolName = safeToolName(completeToolCall);\n toolCalls.add(completeToolCall);\n if (showToolArgs) {\n this.currStr = StrUtil.emptyIfNull(completeToolCall.getFunction().getArguments());\n this.send();\n }\n }\n argument.setLength(0);\n currToolName = \"\";\n }\n\n private void consumeFragmentedToolCalls(List messageToolCalls) {\n if (isEmpty(messageToolCalls)) {\n return;\n }\n for (ToolCall currentToolCall : messageToolCalls) {\n if (currentToolCall == null || currentToolCall.getFunction() == null) {\n continue;\n }\n String argumentsDelta = StrUtil.emptyIfNull(safeToolArguments(currentToolCall));\n if (hasToolIdentity(currentToolCall)) {\n if (toolCall == null) {\n startToolCall(currentToolCall, argumentsDelta);\n } else if (isSameToolCall(toolCall, currentToolCall)) {\n mergeToolIdentity(toolCall, currentToolCall);\n argument.append(argumentsDelta);\n } else {\n finalizeCurrentToolCall();\n startToolCall(currentToolCall, argumentsDelta);\n }\n if (showToolArgs) {\n this.currStr = argumentsDelta;\n this.send();\n }\n continue;\n }\n if (toolCall != null) {\n argument.append(argumentsDelta);\n if (showToolArgs) {\n this.currStr = argumentsDelta;\n this.send();\n }\n }\n }\n }\n\n private void startToolCall(ToolCall currentToolCall, String argumentsDelta) {\n toolCall = currentToolCall;\n argument.setLength(0);\n argument.append(StrUtil.emptyIfNull(argumentsDelta));\n currToolName = safeToolName(currentToolCall);\n }\n\n private void finalizeCurrentToolCall() {\n if (toolCall == null) {\n argument.setLength(0);\n currToolName = \"\";\n return;\n }\n if (toolCall.getFunction() != null) {\n toolCall.getFunction().setArguments(argument.toString());\n }\n toolCalls.add(toolCall);\n toolCall = null;\n argument.setLength(0);\n currToolName = \"\";\n }\n\n private void mergeToolIdentity(ToolCall target, ToolCall source) {\n if (target == null || source == null) {\n return;\n }\n if (StrUtil.isBlank(target.getId()) && StrUtil.isNotBlank(source.getId())) {\n target.setId(source.getId());\n }\n if (StrUtil.isBlank(target.getType()) && StrUtil.isNotBlank(source.getType())) {\n target.setType(source.getType());\n }\n if (target.getFunction() == null || source.getFunction() == null) {\n return;\n }\n if (StrUtil.isBlank(target.getFunction().getName()) && StrUtil.isNotBlank(source.getFunction().getName())) {\n target.getFunction().setName(source.getFunction().getName());\n }\n }\n\n private boolean hasToolIdentity(ToolCall call) {\n return call != null\n && (StrUtil.isNotBlank(call.getId()) || hasToolName(call));\n }\n\n private boolean hasToolName(ToolCall call) {\n return call != null\n && call.getFunction() != null\n && StrUtil.isNotBlank(call.getFunction().getName());\n }\n\n private boolean isSameToolCall(ToolCall left, ToolCall right) {\n if (left == null || right == null) {\n return false;\n }\n if (StrUtil.isNotBlank(left.getId()) && StrUtil.isNotBlank(right.getId())) {\n return left.getId().equals(right.getId());\n }\n if (left.getFunction() == null || right.getFunction() == null) {\n return false;\n }\n return StrUtil.isNotBlank(left.getFunction().getName())\n && left.getFunction().getName().equals(right.getFunction().getName());\n }\n\n private boolean hasStructuredJsonObjectArguments(ToolCall call) {\n String arguments = safeToolArguments(call);\n if (StringUtils.isBlank(arguments)) {\n return false;\n }\n try {\n JsonNode node = new ObjectMapper().readTree(arguments);\n return node != null && node.isObject();\n } catch (Exception ignored) {\n return false;\n }\n }\n\n @Override\n protected Throwable resolveFailure(@Nullable Throwable t, @Nullable Response response) {\n if (t != null && StringUtils.isNotBlank(t.getMessage())) {\n return t;\n }\n String message = resolveFailureMessage(t, response);\n if (StringUtils.isBlank(message)) {\n return t == null ? new CommonException(\"stream request failed\") : t;\n }\n return new CommonException(message);\n }\n\n protected String resolveFailureMessage(@Nullable Throwable t, @Nullable Response response) {\n if (t != null && StringUtils.isNotBlank(t.getMessage())) {\n return t.getMessage().trim();\n }\n String responseMessage = responseMessage(response);\n if (StringUtils.isNotBlank(responseMessage)) {\n return responseMessage;\n }\n if (response != null) {\n String statusLine = (response.code() + \" \" + StrUtil.emptyIfNull(response.message())).trim();\n if (StringUtils.isNotBlank(statusLine)) {\n return statusLine;\n }\n }\n return t == null ? \"stream request failed\" : t.getClass().getSimpleName();\n }\n\n private String responseMessage(@Nullable Response response) {\n if (response == null) {\n return null;\n }\n try {\n okhttp3.ResponseBody peekedBody = response.peekBody(8192L);\n if (peekedBody == null) {\n return null;\n }\n String payload = StringUtils.trimToNull(peekedBody.string());\n if (payload == null) {\n return null;\n }\n String extracted = extractStructuredErrorMessage(payload);\n return extracted == null ? StringUtils.abbreviate(payload, 320) : extracted;\n } catch (Exception ignored) {\n return null;\n }\n }\n\n private String extractStructuredErrorMessage(String payload) {\n if (StringUtils.isBlank(payload)) {\n return null;\n }\n try {\n JsonNode root = new ObjectMapper().readTree(payload);\n String message = firstJsonText(\n root.path(\"error\").path(\"message\"),\n root.path(\"error\"),\n root.path(\"message\"),\n root.path(\"msg\"),\n root.path(\"detail\"),\n root.path(\"Response\").path(\"Error\").path(\"Message\"),\n root.path(\"Response\").path(\"Error\"),\n root.path(\"error_msg\")\n );\n return StringUtils.trimToNull(message);\n } catch (Exception ignored) {\n return null;\n }\n }\n\n private String firstJsonText(JsonNode... nodes) {\n if (nodes == null) {\n return null;\n }\n for (JsonNode node : nodes) {\n if (node == null || node.isMissingNode() || node.isNull()) {\n continue;\n }\n if (node.isTextual()) {\n String text = StringUtils.trimToNull(node.asText());\n if (text != null) {\n return text;\n }\n continue;\n }\n if (node.isObject()) {\n String text = firstJsonText(node.path(\"message\"), node.path(\"Message\"), node.path(\"msg\"), node.path(\"detail\"));\n if (text != null) {\n return text;\n }\n }\n }\n return null;\n }\n\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/listener/StreamExecutionOptions.java",
"content": "package io.github.lnyocly.ai4j.listener;\n\nimport lombok.AllArgsConstructor;\nimport lombok.Builder;\nimport lombok.Data;\nimport lombok.NoArgsConstructor;\n\n@Data\n@Builder(toBuilder = true)\n@NoArgsConstructor\n@AllArgsConstructor\npublic class StreamExecutionOptions {\n\n @Builder.Default\n private long firstTokenTimeoutMs = 0L;\n\n @Builder.Default\n private long idleTimeoutMs = 0L;\n\n @Builder.Default\n private int maxRetries = 0;\n\n @Builder.Default\n private long retryBackoffMs = 0L;\n\n public long normalizedFirstTokenTimeoutMs() {\n return Math.max(0L, firstTokenTimeoutMs);\n }\n\n public long normalizedIdleTimeoutMs() {\n return Math.max(0L, idleTimeoutMs);\n }\n\n public int normalizedMaxRetries() {\n return Math.max(0, maxRetries);\n }\n\n public long normalizedRetryBackoffMs() {\n return Math.max(0L, retryBackoffMs);\n }\n\n public int totalAttempts() {\n return normalizedMaxRetries() + 1;\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/listener/StreamExecutionSupport.java",
"content": "package io.github.lnyocly.ai4j.listener;\n\npublic final class StreamExecutionSupport {\n\n public static final String DEFAULT_FIRST_TOKEN_TIMEOUT_PROPERTY = \"ai4j.stream.default.first-token-timeout-ms\";\n public static final String DEFAULT_IDLE_TIMEOUT_PROPERTY = \"ai4j.stream.default.idle-timeout-ms\";\n public static final String DEFAULT_MAX_RETRIES_PROPERTY = \"ai4j.stream.default.max-retries\";\n public static final String DEFAULT_RETRY_BACKOFF_PROPERTY = \"ai4j.stream.default.retry-backoff-ms\";\n\n public static final long DEFAULT_FIRST_TOKEN_TIMEOUT_MS = 30_000L;\n public static final long DEFAULT_IDLE_TIMEOUT_MS = 30_000L;\n public static final int DEFAULT_MAX_RETRIES = 0;\n public static final long DEFAULT_RETRY_BACKOFF_MS = 0L;\n\n private StreamExecutionSupport() {\n }\n\n public interface StreamStarter {\n void start() throws Exception;\n }\n\n public static void execute(ManagedStreamListener listener,\n StreamExecutionOptions options,\n StreamStarter starter) throws Exception {\n if (listener == null) {\n throw new IllegalArgumentException(\"listener is required\");\n }\n if (starter == null) {\n throw new IllegalArgumentException(\"starter is required\");\n }\n\n StreamExecutionOptions resolved = resolveOptions(options);\n\n int maxAttempts = Math.max(1, resolved.totalAttempts());\n int attempt = 1;\n while (true) {\n listener.clearFailure();\n try {\n starter.start();\n } catch (Exception ex) {\n listener.recordFailure(ex);\n }\n\n listener.awaitCompletion(resolved);\n\n Throwable failure = listener.getFailure();\n if (failure == null || listener.isCancelRequested() || Thread.currentThread().isInterrupted()) {\n return;\n }\n if (listener.hasReceivedEvent() || attempt >= maxAttempts) {\n return;\n }\n\n int nextAttempt = attempt + 1;\n listener.onRetrying(failure, nextAttempt, maxAttempts);\n listener.prepareForRetry();\n long backoffMs = resolved.normalizedRetryBackoffMs();\n if (backoffMs > 0L) {\n try {\n Thread.sleep(backoffMs);\n } catch (InterruptedException ex) {\n Thread.currentThread().interrupt();\n return;\n }\n }\n attempt = nextAttempt;\n }\n }\n\n static StreamExecutionOptions resolveOptions(StreamExecutionOptions options) {\n if (options != null) {\n return options;\n }\n return StreamExecutionOptions.builder()\n .firstTokenTimeoutMs(longProperty(DEFAULT_FIRST_TOKEN_TIMEOUT_PROPERTY, DEFAULT_FIRST_TOKEN_TIMEOUT_MS))\n .idleTimeoutMs(longProperty(DEFAULT_IDLE_TIMEOUT_PROPERTY, DEFAULT_IDLE_TIMEOUT_MS))\n .maxRetries(intProperty(DEFAULT_MAX_RETRIES_PROPERTY, DEFAULT_MAX_RETRIES))\n .retryBackoffMs(longProperty(DEFAULT_RETRY_BACKOFF_PROPERTY, DEFAULT_RETRY_BACKOFF_MS))\n .build();\n }\n\n private static long longProperty(String key, long fallback) {\n String value = System.getProperty(key);\n if (value == null || value.trim().isEmpty()) {\n return fallback;\n }\n try {\n return Long.parseLong(value.trim());\n } catch (NumberFormatException ignored) {\n return fallback;\n }\n }\n\n private static int intProperty(String key, int fallback) {\n String value = System.getProperty(key);\n if (value == null || value.trim().isEmpty()) {\n return fallback;\n }\n try {\n return Integer.parseInt(value.trim());\n } catch (NumberFormatException ignored) {\n return fallback;\n }\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/mcp/annotation/McpParameter.java",
"content": "package io.github.lnyocly.ai4j.mcp.annotation;\n\nimport java.lang.annotation.*;\n\n/**\n * @Author cly\n * @Description MCP参数注解，用于标记MCP工具方法的参数\n */\n@Target(ElementType.PARAMETER)\n@Retention(RetentionPolicy.RUNTIME)\n@Documented\npublic @interface McpParameter {\n\n /**\n * 参数名称，如果不指定则使用参数名\n */\n String name() default \"\";\n\n /**\n * 参数描述\n */\n String description() default \"\";\n\n /**\n * 是否必需参数\n */\n boolean required() default true;\n\n /**\n * 参数默认值\n * 在MCP工具调用时使用\n */\n String defaultValue() default \"\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/mcp/annotation/McpPrompt.java",
"content": "package io.github.lnyocly.ai4j.mcp.annotation;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\n/**\n * @Author cly\n * @Description MCP提示词注解，用于标记MCP服务中的提示词方法\n */\n@Target(ElementType.METHOD)\n@Retention(RetentionPolicy.RUNTIME)\npublic @interface McpPrompt {\n \n /**\n * 提示词名称\n */\n String name();\n \n /**\n * 提示词描述\n */\n String description() default \"\";\n \n /**\n * 提示词类型 (user, assistant, system)\n */\n String role() default \"user\";\n \n /**\n * 是否支持动态参数\n */\n boolean dynamic() default true;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/mcp/annotation/McpPromptParameter.java",
"content": "package io.github.lnyocly.ai4j.mcp.annotation;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\n/**\n * @Author cly\n * @Description MCP提示词参数注解，用于标记MCP提示词方法的参数\n */\n@Target(ElementType.PARAMETER)\n@Retention(RetentionPolicy.RUNTIME)\npublic @interface McpPromptParameter {\n \n /**\n * 参数名称\n */\n String name();\n \n /**\n * 参数描述\n */\n String description() default \"\";\n \n /**\n * 是否必需\n */\n boolean required() default true;\n\n /**\n * 默认值\n */\n String defaultValue() default \"\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/mcp/annotation/McpResource.java",
"content": "package io.github.lnyocly.ai4j.mcp.annotation;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\n/**\n * @Author cly\n * @Description MCP资源注解，用于标记MCP服务中的资源方法\n */\n@Target(ElementType.METHOD)\n@Retention(RetentionPolicy.RUNTIME)\npublic @interface McpResource {\n \n /**\n * 资源URI模板，支持参数占位符\n * 例如: \"file://{path}\", \"database://users/{id}\"\n */\n String uri();\n \n /**\n * 资源名称\n */\n String name();\n \n /**\n * 资源描述\n */\n String description() default \"\";\n \n /**\n * 资源MIME类型\n */\n String mimeType() default \"\";\n \n /**\n * 是否支持订阅变更通知\n */\n boolean subscribable() default false;\n \n /**\n * 资源大小（字节），-1表示未知\n */\n long size() default -1L;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/mcp/annotation/McpResourceParameter.java",
"content": "package io.github.lnyocly.ai4j.mcp.annotation;\n\nimport java.lang.annotation.ElementType;\nimport java.lang.annotation.Retention;\nimport java.lang.annotation.RetentionPolicy;\nimport java.lang.annotation.Target;\n\n/**\n * @Author cly\n * @Description MCP资源参数注解，用于标记MCP资源方法的参数\n */\n@Target(ElementType.PARAMETER)\n@Retention(RetentionPolicy.RUNTIME)\npublic @interface McpResourceParameter {\n \n /**\n * 参数名称，对应URI模板中的占位符\n */\n String name();\n \n /**\n * 参数描述\n */\n String description() default \"\";\n \n /**\n * 是否必需\n */\n boolean required() default true;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/mcp/annotation/McpService.java",
"content": "package io.github.lnyocly.ai4j.mcp.annotation;\n\nimport java.lang.annotation.*;\n\n/**\n * @Author cly\n * @Description MCP服务注解，用于标记MCP服务类\n */\n@Target(ElementType.TYPE)\n@Retention(RetentionPolicy.RUNTIME)\n@Documented\npublic @interface McpService {\n\n /**\n * 服务名称\n */\n String name() default \"\";\n\n /**\n * 服务版本\n */\n String version() default \"1.0.0\";\n\n /**\n * 服务描述\n */\n String description() default \"\";\n\n /**\n * 服务端口（仅HTTP传输时使用）\n */\n int port() default 3000;\n\n /**\n * 传输类型：stdio, sse, streamable_http\n */\n String transport() default \"stdio\";\n\n /**\n * 是否自动启动\n */\n boolean autoStart() default true;\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/mcp/annotation/McpTool.java",
"content": "package io.github.lnyocly.ai4j.mcp.annotation;\n\nimport java.lang.annotation.*;\n\n/**\n * @Author cly\n * @Description MCP工具注解，用于标记MCP服务中的工具方法\n */\n@Target(ElementType.METHOD)\n@Retention(RetentionPolicy.RUNTIME)\n@Documented\npublic @interface McpTool {\n\n /**\n * 工具名称，如果不指定则使用方法名\n */\n String name() default \"\";\n\n /**\n * 工具描述\n */\n String description() default \"\";\n\n /**\n * 工具输入Schema的JSON字符串\n * 如果不指定，将根据方法参数自动生成\n */\n String inputSchema() default \"\";\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/mcp/client/McpClient.java",
"content": "package io.github.lnyocly.ai4j.mcp.client;\n\nimport com.alibaba.fastjson2.JSON;\nimport io.github.lnyocly.ai4j.mcp.entity.*;\nimport io.github.lnyocly.ai4j.mcp.entity.McpMessage;\nimport io.github.lnyocly.ai4j.mcp.entity.McpToolDefinition;\nimport io.github.lnyocly.ai4j.mcp.transport.McpTransport;\nimport io.github.lnyocly.ai4j.mcp.transport.McpTransportSupport;\nimport org.slf4j.Logger;\nimport org.slf4j.LoggerFactory;\n\nimport java.io.IOException;\nimport java.util.ArrayList;\nimport java.util.HashMap;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.concurrent.*;\nimport java.util.concurrent.atomic.AtomicBoolean;\nimport java.util.concurrent.atomic.AtomicLong;\n\n/**\n * @Author cly\n * @Description MCP客户端核心类\n */\npublic class McpClient implements McpTransport.McpMessageHandler {\n\n private static final Logger log = LoggerFactory.getLogger(McpClient.class);\n private static final long HEARTBEAT_INTERVAL_MINUTES = 10L;\n\n private final String clientName;\n private final String clientVersion;\n private final McpTransport transport;\n private final boolean autoReconnect;\n private final AtomicBoolean initialized;\n private final AtomicBoolean connected;\n private final AtomicLong messageIdCounter;\n // 在 McpClient 类中添加以下成员变量\n private final AtomicBoolean isReconnecting = new AtomicBoolean(false);\n private final ScheduledExecutorService reconnectExecutor = Executors.newSingleThreadScheduledExecutor();\n\n // 存储待响应的请求\n private final Map> pendingRequests;\n\n // 缓存的服务器工具列表\n private volatile List availableTools;\n private volatile List availableResources;\n private volatile List availablePrompts;\n\n private ScheduledExecutorService heartbeatExecutor;\n\n public McpClient(String clientName, String clientVersion, McpTransport transport) {\n this(clientName, clientVersion, transport, true);\n }\n\n public McpClient(String clientName, String clientVersion, McpTransport transport, boolean autoReconnect) {\n this.clientName = clientName;\n this.clientVersion = clientVersion;\n this.transport = transport;\n this.autoReconnect = autoReconnect;\n this.initialized = new AtomicBoolean(false);\n this.connected = new AtomicBoolean(false);\n this.messageIdCounter = new AtomicLong(0);\n this.pendingRequests = new ConcurrentHashMap<>();\n\n // 设置传输层消息处理器\n transport.setMessageHandler(this);\n }\n\n /**\n * 连接到MCP服务器\n */\n public CompletableFuture connect() {\n return CompletableFuture.runAsync(() -> {\n if (!connected.get()) {\n log.info(\"连接到MCP服务器: {} v{}\", clientName, clientVersion);\n\n try {\n // 启动传输层，添加超时\n transport.start().get(30, java.util.concurrent.TimeUnit.SECONDS);\n log.debug(\"传输层启动成功\");\n\n // 发送初始化请求，添加超时\n initialize().get(30, java.util.concurrent.TimeUnit.SECONDS);\n log.debug(\"初始化请求完成\");\n\n connected.set(true); // 在所有步骤成功后再设置\n log.debug(\"MCP客户端连接成功\");\n if (transport.needsHeartbeat()) {\n log.debug(\"正在启动心跳服务...\");\n startHeartbeat();\n }\n } catch (Exception e) {\n log.debug(\"连接MCP服务器失败: {}\", McpTransportSupport.safeMessage(e), e);\n // 确保在失败时状态被重置\n connected.set(false);\n initialized.set(false);\n throw new RuntimeException(McpTransportSupport.safeMessage(e), e);\n }\n }\n });\n }\n\n /**\n * 断开连接\n */\n public CompletableFuture disconnect() {\n return CompletableFuture.runAsync(() -> {\n if (connected.get() || transport.isConnected()) {\n if (transport.needsHeartbeat() && connected.get()) {\n log.debug(\"正在停止心跳服务...\");\n stopHeartbeat();\n }\n connected.set(false);\n initialized.set(false);\n availableTools = null;\n availableResources = null;\n availablePrompts = null;\n try {\n // 先停止传输层，避免触发新的回调\n transport.stop().join();\n\n // 取消所有待响应的请求\n pendingRequests.values().forEach(future ->\n future.completeExceptionally(new RuntimeException(\"连接已断开\")));\n pendingRequests.clear();\n\n log.debug(\"MCP客户端已断开连接\");\n } catch (Exception e) {\n log.error(\"断开连接时发生错误\", e);\n }\n }\n\n // 最后关闭重连调度器，确保传输层已完全停止\n reconnectExecutor.shutdownNow();\n });\n }\n\n private void startHeartbeat() {\n if (heartbeatExecutor == null || heartbeatExecutor.isShutdown()) {\n heartbeatExecutor = Executors.newSingleThreadScheduledExecutor();\n }\n\n // 长连接传输由底层连接自行保活；这里仅保留低频兜底检查。\n heartbeatExecutor.scheduleAtFixedRate(() -> {\n if (isConnected()) {\n log.debug(\"执行MCP心跳检查\");\n this.getAvailableTools().exceptionally(e -> {\n log.warn(\"心跳请求失败: {}\", e.getMessage());\n // 如果心跳失败，也可以考虑触发重连\n this.onError(new IOException(\"Heartbeat failed, connection assumed lost.\", e));\n return null;\n });\n }\n }, HEARTBEAT_INTERVAL_MINUTES, HEARTBEAT_INTERVAL_MINUTES, TimeUnit.MINUTES);\n }\n\n private void stopHeartbeat() {\n if (heartbeatExecutor != null && !heartbeatExecutor.isShutdown()) {\n heartbeatExecutor.shutdown();\n heartbeatExecutor = null;\n }\n }\n /**\n * 检查是否已连接\n */\n public boolean isConnected() {\n return connected.get() && transport.isConnected();\n }\n\n /**\n * 检查是否已初始化\n */\n public boolean isInitialized() {\n return initialized.get();\n }\n\n /**\n * 获取可用工具列表\n */\n public CompletableFuture> getAvailableTools() {\n if (availableTools != null) {\n return CompletableFuture.completedFuture(availableTools);\n }\n\n return sendRequest(\"tools/list\", null)\n .thenApply(response -> {\n try {\n if (response.isSuccessResponse() && response.getResult() != null) {\n List parsedTools = McpClientResponseSupport.parseToolsListResponse(response.getResult());\n availableTools = parsedTools;\n return parsedTools;\n } else {\n log.warn(\"获取工具列表失败: {}\", response.getError());\n return new ArrayList();\n }\n } catch (Exception e) {\n log.error(\"解析工具列表响应失败\", e);\n return new ArrayList();\n }\n });\n }\n\n /**\n * 获取可用资源列表\n */\n public CompletableFuture> getAvailableResources() {\n if (availableResources != null) {\n return CompletableFuture.completedFuture(availableResources);\n }\n\n return sendRequest(\"resources/list\", null)\n .thenApply(response -> {\n try {\n if (response.isSuccessResponse() && response.getResult() != null) {\n List parsedResources = McpClientResponseSupport.parseResourcesListResponse(response.getResult());\n availableResources = parsedResources;\n return parsedResources;\n } else {\n log.warn(\"获取资源列表失败: {}\", response.getError());\n return new ArrayList();\n }\n } catch (Exception e) {\n log.error(\"解析资源列表响应失败\", e);\n return new ArrayList();\n }\n });\n }\n\n /**\n * 读取资源内容\n */\n public CompletableFuture readResource(String uri) {\n if (uri == null || uri.trim().isEmpty()) {\n CompletableFuture future = new CompletableFuture();\n future.completeExceptionally(new IllegalArgumentException(\"uri is required\"));\n return future;\n }\n\n Map params = new HashMap();\n params.put(\"uri\", uri);\n\n return sendRequest(\"resources/read\", params)\n .thenApply(response -> {\n try {\n if (response.isSuccessResponse() && response.getResult() != null) {\n return McpClientResponseSupport.parseResourceReadResponse(response.getResult());\n } else {\n log.warn(\"读取资源失败: {}\", response.getError());\n return null;\n }\n } catch (Exception e) {\n log.error(\"解析资源读取响应失败\", e);\n return null;\n }\n });\n }\n\n /**\n * 获取可用提示模板列表\n */\n public CompletableFuture> getAvailablePrompts() {\n if (availablePrompts != null) {\n return CompletableFuture.completedFuture(availablePrompts);\n }\n\n return sendRequest(\"prompts/list\", null)\n .thenApply(response -> {\n try {\n if (response.isSuccessResponse() && response.getResult() != null) {\n List parsedPrompts = McpClientResponseSupport.parsePromptsListResponse(response.getResult());\n availablePrompts = parsedPrompts;\n return parsedPrompts;\n } else {\n log.warn(\"获取提示模板列表失败: {}\", response.getError());\n return new ArrayList();\n }\n } catch (Exception e) {\n log.error(\"解析提示模板列表响应失败\", e);\n return new ArrayList();\n }\n });\n }\n\n /**\n * 获取提示模板渲染结果\n */\n public CompletableFuture getPrompt(String name) {\n return getPrompt(name, null);\n }\n\n /**\n * 获取提示模板渲染结果\n */\n public CompletableFuture getPrompt(String name, Map arguments) {\n if (name == null || name.trim().isEmpty()) {\n CompletableFuture future = new CompletableFuture();\n future.completeExceptionally(new IllegalArgumentException(\"name is required\"));\n return future;\n }\n\n Map params = new HashMap();\n params.put(\"name\", name);\n if (arguments != null && !arguments.isEmpty()) {\n params.put(\"arguments\", arguments);\n }\n\n return sendRequest(\"prompts/get\", params)\n .thenApply(response -> {\n try {\n if (response.isSuccessResponse() && response.getResult() != null) {\n return McpClientResponseSupport.parsePromptGetResponse(name, response.getResult());\n } else {\n log.warn(\"获取提示模板失败: {}\", response.getError());\n return null;\n }\n } catch (Exception e) {\n log.error(\"解析提示模板响应失败\", e);\n return null;\n }\n });\n }\n\n\n /**\n * 调用工具\n */\n public CompletableFuture callTool(String toolName, Object arguments) {\n if (!isConnected() || !isInitialized()) {\n CompletableFuture future = new CompletableFuture<>();\n String errorMsg = \"客户端未连接或未初始化，无法调用工具。Connected: \" + isConnected() + \", Initialized: \" + isInitialized();\n log.warn(errorMsg);\n future.completeExceptionally(new IllegalStateException(errorMsg));\n return future;\n }\n\n Map params = new HashMap<>();\n params.put(\"name\", toolName);\n params.put(\"arguments\", arguments);\n\n return sendRequest(\"tools/call\", params)\n .thenApply(response -> {\n try {\n if (response.isSuccessResponse() && response.getResult() != null) {\n // 解析工具调用结果\n return McpClientResponseSupport.parseToolCallResponse(response.getResult());\n } else {\n log.warn(\"工具调用失败: {}\", response.getError());\n return \"工具调用失败: \" + (response.getError() != null ? response.getError().getMessage() : \"未知错误\");\n }\n } catch (Exception e) {\n log.error(\"解析工具调用响应失败\", e);\n return \"工具调用解析失败: \" + e.getMessage();\n }\n }) .exceptionally(ex -> {\n log.error(\"调用工具 '{}' 失败，根本原因: {}\", toolName, ex.getMessage());\n // 将原始异常重新包装或转换为一个更具体的业务异常\n throw new RuntimeException(ex.getMessage(), ex);\n });\n }\n\n @Override\n public void handleMessage(McpMessage message) {\n try {\n log.debug(\"处理消息: {}\", message);\n\n if (message.isResponse()) {\n handleResponse(message);\n } else if (message.isNotification()) {\n handleNotification(message);\n } else if (message.isRequest()) {\n handleRequest(message);\n } else {\n log.warn(\"收到未知类型的消息: {}\", message);\n }\n\n } catch (Exception e) {\n log.error(\"处理消息时发生错误\", e);\n }\n }\n\n @Override\n public void onConnected() {\n log.debug(\"MCP传输层连接已建立\");\n connected.set(true);\n }\n\n @Override\n public void onDisconnected(String reason) {\n log.debug(\"MCP传输层连接已断开: {}\", reason);\n if (connected.get()) { // 增加一个判断，避免重复执行\n connected.set(false);\n initialized.set(false);\n\n // 清除缓存，因为重新连接后工具列表可能变化\n availableTools = null;\n // 停止心跳\n stopHeartbeat();\n\n // 停止并清理传输层，这将清除旧的 endpointUrl\n try {\n transport.stop().join(); // 使用 join() 确保传输层已完全停止\n } catch (Exception e) {\n log.warn(\"在 onDisconnected 期间停止传输层失败\", e);\n }\n\n // 取消所有待处理的请求\n pendingRequests.values().forEach(future ->\n future.completeExceptionally(new RuntimeException(reason)));\n pendingRequests.clear();\n\n // 触发异步重连\n if (autoReconnect) {\n scheduleReconnection();\n } else {\n log.debug(\"自动重连已禁用，跳过MCP重连: {}\", clientName);\n }\n }\n }\n\n @Override\n public void onError(Throwable error) {\n log.debug(\"MCP传输层发生错误: {}\", McpTransportSupport.safeMessage(error), error);\n // 将传输层错误视为一次断开连接事件。\n this.onDisconnected(McpTransportSupport.safeMessage(error));\n }\n /**\n * 调度一个异步的重连任务\n */\n private void scheduleReconnection() {\n // 检查线程池是否已关闭\n if (reconnectExecutor.isShutdown()) {\n log.debug(\"重连调度器已关闭，跳过重连\");\n return;\n }\n\n if (isReconnecting.compareAndSet(false, true)) {\n log.debug(\"将在5秒后尝试重新连接...\");\n try {\n reconnectExecutor.schedule(() -> {\n try {\n log.debug(\"开始执行重连...\");\n connect().get(60, TimeUnit.SECONDS); // 使用 get() 来等待重连完成\n log.debug(\"MCP客户端重连成功\");\n } catch (Exception e) {\n log.error(\"重连失败，将安排下一次重连\", e);\n // 如果这次重连失败，再次调度\n isReconnecting.set(false); // 重置标志以便下次可以重连\n scheduleReconnection(); // 简单起见，这里直接再次调度。实际中可引入指数退避策略。\n } finally {\n // 无论成功与否，最终都重置标志位\n // 如果成功，下一次断线时可以再次触发重连\n // 如果失败，下一次调度时也可以继续\n isReconnecting.set(false);\n }\n }, 5, TimeUnit.SECONDS); // 延迟5秒后执行\n } catch (RejectedExecutionException e) {\n log.debug(\"重连调度器已关闭，无法调度重连任务\");\n isReconnecting.set(false);\n }\n }\n }\n /**\n * 发送初始化请求\n */\n private CompletableFuture initialize() {\n log.debug(\"开始MCP初始化流程\");\n\n // 构建客户端能力 - 使用更完整的配置\n Map capabilities = new HashMap<>();\n // 添加sampling能力\n capabilities.put(\"sampling\", new HashMap<>());\n\n // 添加roots能力\n Map roots = new HashMap<>();\n roots.put(\"listChanged\", true);\n capabilities.put(\"roots\", roots);\n\n // 添加tools能力\n Map tools = new HashMap<>();\n tools.put(\"listChanged\", true);\n capabilities.put(\"tools\", tools);\n\n // 添加resources能力\n Map resources = new HashMap<>();\n resources.put(\"listChanged\", true);\n resources.put(\"subscribe\", true);\n capabilities.put(\"resources\", resources);\n\n // 添加prompts能力\n Map prompts = new HashMap<>();\n prompts.put(\"listChanged\", true);\n capabilities.put(\"prompts\", prompts);\n\n Map clientInfo = new HashMap<>();\n clientInfo.put(\"name\", clientName);\n clientInfo.put(\"version\", clientVersion);\n\n Map params = new HashMap<>();\n // 使用与服务器兼容的协议版本\n params.put(\"protocolVersion\", \"2025-03-26\");\n params.put(\"capabilities\", capabilities);\n params.put(\"clientInfo\", clientInfo);\n\n return sendRequest(\"initialize\", params)\n .thenCompose(response -> {\n log.debug(\"收到初始化响应，发送initialized通知\");\n // 发送初始化完成通知 - 使用空对象而不是null\n return sendNotification(\"notifications/initialized\", new HashMap<>());\n })\n .thenRun(() -> {\n initialized.set(true);\n log.debug(\"MCP客户端初始化完成\");\n });\n }\n\n /**\n * 发送请求消息\n */\n private CompletableFuture sendRequest(String method, Object params) {\n long messageId = nextMessageId();\n\n // 创建请求消息\n McpRequest request = new McpRequest(method, messageId, params);\n\n // 添加详细日志\n log.debug(\"发送MCP请求: method={}, id={}, params={}\", method, messageId, JSON.toJSONString(params));\n\n CompletableFuture future = new CompletableFuture<>();\n pendingRequests.put(messageId, future);\n\n // 发送消息\n transport.sendMessage(request);\n\n return future;\n }\n\n\n /**\n * 发送通知消息\n */\n private CompletableFuture sendNotification(String method, Object params) {\n // 创建通知消息\n McpNotification notification = new McpNotification(method, params);\n\n log.debug(\"发送通知: method={}\", method);\n\n return transport.sendMessage(notification)\n .thenRun(() -> {\n log.debug(\"通知发送完成: method={}\", method);\n })\n .exceptionally(throwable -> {\n log.error(\"发送通知失败: method={}\", method, throwable);\n throw new RuntimeException(\"发送通知失败\", throwable);\n });\n }\n\n /**\n * 处理响应消息\n */\n private void handleResponse(McpMessage message) {\n Object messageId = message.getId();\n\n // 记录完整的响应消息用于调试\n log.debug(\"收到MCP响应: id={}, 完整消息={}\", messageId, JSON.toJSONString(message));\n\n // 尝试不同的ID类型匹配\n CompletableFuture future = pendingRequests.remove(messageId);\n if (future == null && messageId instanceof Number) {\n // 如果直接匹配失败，尝试转换为long类型匹配\n long longId = ((Number) messageId).longValue();\n future = pendingRequests.remove(longId);\n }\n\n if (future != null) {\n if (message.isSuccessResponse()) {\n future.complete(message);\n } else {\n log.error(\"MCP请求失败详情: id={}, error={}, 完整错误消息={}\",\n messageId, message.getError(), JSON.toJSONString(message));\n future.completeExceptionally(new RuntimeException(\"请求失败: \" + message.getError()));\n }\n } else {\n log.warn(\"收到未知请求的响应: {}\", messageId);\n }\n }\n\n /**\n * 处理通知消息\n */\n private void handleNotification(McpMessage message) {\n String method = message.getMethod();\n log.debug(\"收到通知: {}\", method);\n\n // 处理各种标准MCP通知\n switch (method) {\n case \"notifications/tools/list_changed\":\n // 工具列表变更通知\n log.debug(\"服务器工具列表已变更，清除缓存\");\n availableTools = null; // 清除缓存\n break;\n case \"notifications/resources/list_changed\":\n // 资源列表变更通知\n log.debug(\"服务器资源列表已变更\");\n availableResources = null;\n break;\n case \"notifications/prompts/list_changed\":\n // 提示列表变更通知\n log.debug(\"服务器提示列表已变更\");\n availablePrompts = null;\n break;\n case \"notifications/progress\":\n // 进度通知\n log.debug(\"收到进度通知: {}\", message.getParams());\n break;\n default:\n log.debug(\"收到未处理的通知: {}\", method);\n break;\n }\n }\n\n /**\n * 处理请求消息（服务器向客户端发送的请求）\n */\n private void handleRequest(McpMessage message) {\n String method = message.getMethod();\n log.debug(\"收到服务器请求: {}\", method);\n\n // 这里可以处理服务器向客户端发送的请求\n // 比如sampling/createMessage等\n }\n\n /**\n * 生成下一个消息ID\n */\n private long nextMessageId() {\n return messageIdCounter.incrementAndGet();\n }\n}\n"
},
{
"path": "ai4j/src/main/java/io/github/lnyocly/ai4j/mcp/client/McpClientResponseSupport.java",
"content": "package io.github.lnyocly.ai4j.mcp.client;\n\nimport com.alibaba.fastjson2.JSON;\nimport io.github.lnyocly.ai4j.mcp.entity.McpPrompt;\nimport io.github.lnyocly.ai4j.mcp.entity.McpPromptResult;\nimport io.github.lnyocly.ai4j.mcp.entity.McpResource;\nimport io.github.lnyocly.ai4j.mcp.entity.McpResourceContent;\nimport io.github.lnyocly.ai4j.mcp.entity.McpToolDefinition;\n\nimport java.util.ArrayList;\nimport java.util.HashMap;\nimport java.util.List;\nimport java.util.Map;\n\n/**\n * MCP 客户端响应解析辅助类\n */\npublic final class McpClientResponseSupport {\n\n private McpClientResponseSupport() {\n }\n\n public static List parseToolsListResponse(Object result) {\n List tools = new ArrayList();\n\n try {\n Map resultMap = asMap(result);\n if (resultMap != null) {\n List toolsList = asList(resultMap.get(\"tools\"));\n for (Object toolObj : toolsList) {\n Map toolMap = asMap(toolObj);\n if (toolMap != null) {\n McpToolDefinition tool = McpToolDefinition.builder()\n .name((String) toolMap.get(\"name\"))\n .description((String) toolMap.get(\"description\"))\n .inputSchema(asMap(toolMap.get(\"inputSchema\")))\n .build();\n tools.add(tool);\n }\n }\n }\n } catch (Exception ignored) {\n }\n\n return tools;\n }\n\n public static String parseToolCallResponse(Object result) {\n try {\n Map resultMap = asMap(result);\n if (resultMap != null) {\n Object content = resultMap.get(\"content\");\n if (content != null) {\n List contentList = asList(content);\n if (!contentList.isEmpty()) {\n StringBuilder resultText = new StringBuilder();\n for (Object item : contentList) {\n Map itemMap = asMap(item);\n if (itemMap != null) {\n Object text = itemMap.get(\"text\");\n if (text != null) {\n resultText.append(text.toString());\n }\n }\n }\n return resultText.toString();\n }\n return content.toString();\n }\n\n return JSON.toJSONString(result);\n }\n\n return result != null ? result.toString() : \"\";\n } catch (Exception e) {\n return \"解析结果失败: \" + e.getMessage();\n }\n }\n\n public static List parseResourcesListResponse(Object result) {\n List resources = new ArrayList();\n try {\n Map resultMap = asMap(result);\n if (resultMap == null) {\n return resources;\n }\n List resourceList = asList(resultMap.get(\"resources\"));\n for (Object resourceObj : resourceList) {\n Map resourceMap = asMap(resourceObj);\n if (resourceMap == null) {\n continue;\n }\n resources.add(McpResource.builder()\n .uri(stringValue(resourceMap.get(\"uri\")))\n .name(stringValue(resourceMap.get(\"name\")))\n .description(stringValue(resourceMap.get(\"description\")))\n .mimeType(stringValue(resourceMap.get(\"mimeType\")))\n .size(longValue(resourceMap.get(\"size\")))\n .build());\n }\n } catch (Exception ignored) {\n }\n return resources;\n }\n\n public static McpResourceContent parseResourceReadResponse(Object result) {\n try {\n Map resultMap = asMap(result);\n if (resultMap == null) {\n return null;\n }\n List contentList = asList(resultMap.get(\"contents\"));\n if (contentList.isEmpty()) {\n return null;\n }\n if (contentList.size() == 1) {\n return parseSingleResourceContent(contentList.get(0));\n }\n\n List contents = new ArrayList(contentList.size());\n String uri = null;\n String mimeType = null;\n for (Object contentObj : contentList) {\n Map itemMap = asMap(contentObj);\n if (itemMap == null) {\n continue;\n }\n if (uri == null) {\n uri = stringValue(itemMap.get(\"uri\"));\n }\n if (mimeType == null) {\n mimeType = stringValue(itemMap.get(\"mimeType\"));\n }\n Object extracted = extractResourceContent(itemMap);\n contents.add(extracted == null ? itemMap : extracted);\n }\n return McpResourceContent.builder()\n .uri(uri)\n .mimeType(mimeType)\n .contents(contents)\n .build();\n } catch (Exception ignored) {\n return null;\n }\n }\n\n public static List parsePromptsListResponse(Object result) {\n List prompts = new ArrayList();\n try {\n Map resultMap = asMap(result);\n if (resultMap == null) {\n return prompts;\n }\n List ![\"Maven](\"https://img.shields.io/maven-central/v/io.github.lnyo-cly/ai4j?color=2E86C1&label=Maven%20Central\")
![\"Docs\"](\"https://img.shields.io/badge/Docs-GitHub%20Pages-0A7EA4\"){kind=icon}
![\"License\"](\"https://img.shields.io/badge/License-Apache%202.0-1F6FEB\"){kind=icon}
![\"JDK](\"https://img.shields.io/badge/JDK-8%2B-2EA043\"){kind=icon}
![\"Agentic](\"https://img.shields.io/badge/Agentic-Enabled-6F42C1\"){kind=icon}
![\"MCP](\"https://img.shields.io/badge/MCP-Supported-0F766E\"){kind=icon}
![\"RAG](\"https://img.shields.io/badge/RAG-Built--in-B45309\"){kind=icon}
![\"CLI](\"https://img.shields.io/badge/CLI%20%2F%20TUI%20%2F%20ACP-Built--in-475569\"){kind=icon}