[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-dzhng--zod-gpt":3,"tool-dzhng--zod-gpt":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",159636,2,"2026-04-17T23:33:34",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":76,"owner_twitter":72,"owner_website":77,"owner_url":78,"languages":79,"stars":92,"forks":93,"last_commit_at":94,"license":95,"difficulty_score":32,"env_os":96,"env_gpu":97,"env_ram":97,"env_deps":98,"category_tags":103,"github_topics":76,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":104,"updated_at":105,"faqs":106,"releases":132},8995,"dzhng\u002Fzod-gpt","zod-gpt","Get structured, fully typed, and validated JSON outputs from OpenAI and Anthropic models.","zod-gpt 是一款专为开发者设计的开源库，旨在让 OpenAI 和 Anthropic 等大语言模型输出结构严谨、类型安全且经过验证的 JSON 数据。在大模型应用中，直接获取格式完美的结构化数据往往充满挑战，模型容易产生格式错误或幻觉，导致后续程序解析失败。zod-gpt 巧妙解决了这一痛点，它底层利用函数调用机制引导模型规范回答，并结合强大的 Zod 库进行实时模式定义与数据校验。\n\n其核心亮点在于“自动修复”能力：当模型返回的数据不符合预设架构时，zod-gpt 能自动触发自我反思机制，请求模型修正错误，直至输出合法数据，极大提升了系统的稳定性。此外，它还内置了智能重试策略，能优雅地处理速率限制等 API 错误。使用时，开发者只需通过简单的代码定义数据骨架（Schema），即可轻松获得完全类型化的响应对象，无需再编写繁琐的正则表达式或手动解析逻辑。无论是构建需要精确数据交互的后端服务，还是开发依赖可靠结构化输出的 AI 应用，zod-gpt 都能帮助 TypeScript 开发者高效、安心地将大模型能力集成到生产环境中。","# ✨ ZodGPT\n\n[![test](https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fzod-gpt\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg?branch=main&event=push)](https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fzod-gpt\u002Factions\u002Fworkflows\u002Ftest.yml)\n\nGet structured, fully typed, and validated JSON outputs from OpenAI and Anthropic models.\n\nUnder the hood, `zod-gpt` uses functions to coerce the model to always respond as function calls. Add self-reflection for reliability and zod for parsing & typing.\n\n- [Introduction](#-introduction)\n- [Usage](#-usage)\n  - [Install](#install)\n  - [Request](#request)\n  - [Auto Healing](#-auto-healing)\n  - [Text Slicing](#-text-slicing)\n- [Debugging](#-debugging)\n- [API Reference](#-api-reference)\n\n## 👋 Introduction\n\nZodGPT is a library for\n\n- Receiving structured outputs from models with complete type safety. All responses are fully validated & typed, works with [zod](https:\u002F\u002Fgithub.com\u002Fcolinhacks\u002Fzod) as a peer dep.\n- Schema definition, serialization \u002F parsing, and **automatically asking the model to correct outputs**.\n- Handle rate limit and any other API errors as gracefully as possible (e.g. exponential backoff for rate-limit) via [llm-api](https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fllm-api).\n\nWith `zod-gpt`, you can simply query OpenAI's ChatGPT model like so:\n\n```typescript\nimport { OpenAIChatApi } from 'llm-api';\nimport { completion } from 'zod-gpt';\n\nconst openai = new OpenAIChatApi({ apiKey: 'YOUR_OPENAI_KEY' });\n\nconst response = await completion(openai, 'Generate a startup idea', {\n  schema: z.object({\n    name: z.string().describe('The name of the startup'),\n    description: z.string().describe('What does this startup do?'),\n  }),\n});\n\n\u002F\u002F data will be typed as { name: string; description: string }\nconsole.log(response.data);\n```\n\nAnthropic is also supported via `llm-api`:\n\n```typescript\nimport { AnthropicChatApi } from 'llm-api';\nimport { completion } from 'zod-gpt';\n\nconst client = new AnthropicChatApi({ apiKey: 'YOUR_ANTHROPIC_KEY' });\nconst response = await completion(client, ...);\n```\n\n## 🔨 Usage\n\n### Install\n\nThis package is hosted on npm:\n\n```\nnpm i zod-gpt\n```\n\n```\nyarn add zod-gpt\n```\n\nTo setup in your codebase, initialize a new instance with the model you want via the `llm-api` peer dep. Note that `zod-gpt` is designed to work with any models that implements the `CompletionApi` interface, so you can also import your own API wrapper.\n\n```typescript\nimport { OpenAIChatApi } from 'llm-api';\n\nconst openai = new OpenAIChatApi(\n  { apiKey: 'YOUR_OPENAI_KEY' },\n  { model: 'gpt-4-0613' },\n);\n```\n\n### Request\n\nTo send a standard completion request with a given model, simply call the `completion` method.\n\n```typescript\nconst response = await completion(openai, 'hello');\n\n\u002F\u002F data will be typed as string\nconsole.log(response.data);\n```\n\nTo add schema parsing and typing, simply add a `schema` key in the options argument. **Make sure to add a description to each key via the `describe` method.** The descriptions will be fed into the model to ensure that it understand exactly what data is requested for each key. Try to error on the side of being over descriptive to ensure the model understands exactly.\n\n```typescript\nconst response = await completion(\n  openai,\n  'Generate a step by step plan on how to run a hackathon',\n  {\n    schema: z.object({\n      plan: z.array(\n        z.object({\n          reason: z.string().describe('Name the reasoning for this step'),\n          id: z.string().describe('Unique step id'),\n          task: z\n            .string()\n            .describe('What is the task to be done for this step?'),\n        }),\n      ),\n    }),\n  },\n);\n\n\u002F\u002F data will be typed as { plan: { reason: string; id: string; task: string }[] }\nconsole.info('Response:', response.data);\n```\n\nNOTE: the `schema` key ONLY takes object type schemas - this is a limitation of the `functions` API. If you need to generate arrays or other type of reponses, simply wrap them in an object like the above example.\n\n### 🧑‍⚕️ Auto Healing\n\nBy default, `zod-gpt` has logic to automatically detect and heal any schema errors via self-reflection (e.g. if the function api is not being used correctly, if the schema has parse errors.. etc). This means whenever these types of errors happen, `zod-gpt` will send a new message to re-ask the model to correct its own output, together with any error messages it gathered from parsing.\n\nThe logic is simple but incredabily powerful, and adds a layer of reliability to model outputs. I suggest leaving this flag set to true (its default setting), unless if token usage or response time becomes a real issue.\n\n### 📃 Text Slicing\n\nA common way to handle token limit issues is to split your content. `zod-gpt` provides an `autoSlice` option to automatically split your text when a token overflow error from `llm-api` is detected. It's smart enough to only split your text if it determines that it is above the token limit, and will try to preserve as much of the original text as possible.\n\n```typescript\nconst openai = new OpenAIChatApi(\n  { apiKey: 'YOUR_OPENAI_KEY' },\n  \u002F\u002F make sure `contextSize` is set to enable throwing TokenErrors\n  { model: 'gpt-4-0613', contextSize: 8129 },\n);\n\nconst response = await completion(\n  openai,\n  'hello world, testing overflow logic',\n  { autoSlice: true },\n);\n```\n\n## 🤓 Debugging\n\n`zod-gpt` uses the `debug` module for logging & error messages. To run in debug mode, set the `DEBUG` env variable:\n\n`DEBUG=zod-gpt:* yarn playground`\n\nYou can also specify different logging types via:\n\n`DEBUG=zod-gpt:error yarn playground`\n`DEBUG=zod-gpt:log yarn playground`\n\n## ✅ API Reference\n\n### LLM Provider Support\n\n`zod-gpt` currently users the [llm-api](https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fllm-api) library to support multiple LLM providers. Check the `llm-api` documentation on how to configure model parameters.\n\n#### Completion\n\nTo send a completion request to a model:\n\n```typescript\nconst res: Response = await completion(model, prompt, options: RequestOptions);\n```\n\n**options**\nYou can override the default request options via this parameter. The `RequestOptions` object extends the request options defined in `llm-api`.\n\n```typescript\ntype RequestOptions = {\n  \u002F\u002F set a zod schema to enable JSON output\n  schema?: T;\n\n  \u002F\u002F set to enable automatically slicing the prompt on token overflow. prompt will be sliced starting from the last character\n  \u002F\u002F default: false\n  autoSlice?: boolean;\n\n  \u002F\u002F attempt to auto heal the output via reflection\n  \u002F\u002F default: true\n  autoHeal?: boolean;\n\n  \u002F\u002F set message history, useful if you want to continue an existing conversation\n  messageHistory?: ChatRequestMessage[];\n\n  \u002F\u002F the number of time to retry this request due to rate limit or recoverable API errors\n  \u002F\u002F default: 3\n  retries?: number;\n  \u002F\u002F default: 30s\n  retryInterval?: number;\n  \u002F\u002F default: 60s\n  timeout?: number;\n\n  \u002F\u002F the minimum amount of tokens to allocate for the response. if the request is predicted to not have enough tokens, it will automatically throw a 'TokenError' without sending the request\n  \u002F\u002F default: 200\n  minimumResponseTokens?: number;\n};\n```\n\n#### Response\n\nCompletion responses extends the model responses from `llm-api`, specifically adding a `data` field for the pased JSON that's automatically typed according to the input `zod` schema.\n\n```typescript\ninterface Response\u003CT extends z.ZodType> {\n  \u002F\u002F parsed and typecasted data from the model\n  data: z.infer\u003CT>;\n\n  \u002F\u002F raw response from the completion API\n  content?: string;\n  name?: string;\n  arguments?: JsonValue;\n  usage?: {\n    promptTokens: number;\n    completionTokens: number;\n    totalTokens: number;\n  };\n}\n```\n\n### Misc\n\n#### Text Splitting\n\nIf you need to split long text into multiple chunks before calling the llm, few text splitters are also exported in `text-spitter.ts`. Try to default to `RecursiveTextSplitter` unless if there is a specific reason to use the other text splitters, as it is the most widely used text splitter.\n","# ✨ ZodGPT\n\n[![测试](https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fzod-gpt\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg?branch=main&event=push)](https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fzod-gpt\u002Factions\u002Fworkflows\u002Ftest.yml)\n\n从 OpenAI 和 Anthropic 模型获取结构化、完全类型化的验证过的 JSON 输出。\n\n在底层，`zod-gpt` 使用函数来强制模型始终以函数调用的形式响应。通过自我反思提高可靠性，并使用 zod 进行解析和类型检查。\n\n- [简介](#-introduction)\n- [使用方法](#-usage)\n  - [安装](#install)\n  - [请求](#request)\n  - [自动修复](#-auto-healing)\n  - [文本切分](#-text-slicing)\n- [调试](#-debugging)\n- [API 参考](#-api-reference)\n\n## 👋 简介\n\nZodGPT 是一个用于以下功能的库：\n\n- 接收具有完整类型安全性的结构化模型输出。所有响应都经过完全验证和类型化，可与 `zod`（作为 peer dep）一起使用。\n- 定义模式、序列化\u002F解析，以及**自动要求模型纠正输出**。\n- 通过 `llm-api` 尽可能优雅地处理速率限制和其他 API 错误（例如，针对速率限制的指数退避策略）。\n\n使用 `zod-gpt`，您可以像这样简单地查询 OpenAI 的 ChatGPT 模型：\n\n```typescript\nimport { OpenAIChatApi } from 'llm-api';\nimport { completion } from 'zod-gpt';\n\nconst openai = new OpenAIChatApi({ apiKey: 'YOUR_OPENAI_KEY' });\n\nconst response = await completion(openai, '生成一个创业想法', {\n  schema: z.object({\n    name: z.string().describe('创业公司的名称'),\n    description: z.string().describe('这家公司是做什么的？'),\n  }),\n});\n\n\u002F\u002F data 将被类型化为 { name: string; description: string }\nconsole.log(response.data);\n```\n\nAnthropic 也可以通过 `llm-api` 支持：\n\n```typescript\nimport { AnthropicChatApi } from 'llm-api';\nimport { completion } from 'zod-gpt';\n\nconst client = new AnthropicChatApi({ apiKey: 'YOUR_ANTHROPIC_KEY' });\nconst response = await completion(client, ...);\n```\n\n## 🔨 使用方法\n\n### 安装\n\n此包托管在 npm 上：\n\n```\nnpm i zod-gpt\n```\n\n```\nyarn add zod-gpt\n```\n\n要在您的代码库中设置，请通过 `llm-api` peer dep 初始化您想要使用的模型的新实例。请注意，`zod-gpt` 旨在与任何实现 `CompletionApi` 接口的模型一起工作，因此您也可以导入自己的 API 包装器。\n\n```typescript\nimport { OpenAIChatApi } from 'llm-api';\n\nconst openai = new OpenAIChatApi(\n  { apiKey: 'YOUR_OPENAI_KEY' },\n  { model: 'gpt-4-0613' },\n);\n```\n\n### 请求\n\n要使用给定的模型发送标准完成请求，只需调用 `completion` 方法。\n\n```typescript\nconst response = await completion(openai, 'hello');\n\n\u002F\u002F data 将被类型化为 string\nconsole.log(response.data);\n```\n\n要添加模式解析和类型化，只需在选项参数中添加 `schema` 键。**请务必通过 `describe` 方法为每个键添加描述。** 这些描述将被输入到模型中，以确保它准确理解每个键所需的数据。尽量多加描述，以确保模型能够完全理解。\n\n```typescript\nconst response = await completion(\n  openai,\n  '生成一个关于如何举办黑客马拉松的分步计划',\n  {\n    schema: z.object({\n      plan: z.array(\n        z.object({\n          reason: z.string().describe('这一步的理由'),\n          id: z.string().describe('唯一的步骤 ID'),\n          task: z\n            .string()\n            .describe('这一步需要完成的任务是什么？'),\n        }),\n      ),\n    }),\n  },\n);\n\n\u002F\u002F data 将被类型化为 { plan: { reason: string; id: string; task: string }[] }\nconsole.info('响应:', response.data);\n```\n\n注意：`schema` 键仅接受对象类型的模式——这是 `functions` API 的限制。如果您需要生成数组或其他类型的响应，只需像上述示例一样将其包装在对象中。\n\n### 🧑‍⚕️ 自动修复\n\n默认情况下，`zod-gpt` 具有通过自我反思自动检测和修复任何模式错误的逻辑（例如，如果函数 API 使用不正确，如果模式存在解析错误等）。这意味着每当发生这些类型的错误时，`zod-gpt` 都会发送一条新消息，重新要求模型纠正其自身输出，并附上从解析中收集到的所有错误信息。\n\n这种逻辑简单但非常强大，为模型输出增加了一层可靠性。建议将此标志保持为 true（默认设置），除非令牌使用量或响应时间成为真正的问题。\n\n### 📃 文本切分\n\n处理令牌限制问题的一种常见方法是分割内容。`zod-gpt` 提供了 `autoSlice` 选项，当检测到来自 `llm-api` 的令牌溢出错误时，会自动分割您的文本。它足够智能，只有在确定文本超过令牌限制时才会进行分割，并会尽可能保留原始文本的内容。\n\n```typescript\nconst openai = new OpenAIChatApi(\n  { apiKey: 'YOUR_OPENAI_KEY' },\n  \u002F\u002F 确保设置 contextSize 以启用 TokenErrors 抛出\n  { model: 'gpt-4-0613', contextSize: 8129 },\n);\n\nconst response = await completion(\n  openai,\n  'hello world, 测试溢出逻辑',\n  { autoSlice: true },\n);\n```\n\n## 🤓 调试\n\n`zod-gpt` 使用 `debug` 模块进行日志记录和错误消息输出。要在调试模式下运行，请设置 `DEBUG` 环境变量：\n\n`DEBUG=zod-gpt:* yarn playground`\n\n您还可以通过以下方式指定不同的日志记录类型：\n\n`DEBUG=zod-gpt:error yarn playground`\n`DEBUG=zod-gpt:log yarn playground`\n\n## ✅ API 参考\n\n### 大模型提供商支持\n\n`zod-gpt` 当前使用 [llm-api](https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fllm-api) 库来支持多个大模型提供商。请查阅 `llm-api` 的文档，了解如何配置模型参数。\n\n#### 补全请求\n\n要向模型发送补全请求，可以这样做：\n\n```typescript\nconst res: Response = await completion(model, prompt, options: RequestOptions);\n```\n\n**options**\n您可以通过此参数覆盖默认的请求选项。`RequestOptions` 对象扩展了 `llm-api` 中定义的请求选项。\n\n```typescript\ntype RequestOptions = {\n  \u002F\u002F 设置 Zod 模式以启用 JSON 输出\n  schema?: T;\n\n  \u002F\u002F 启用自动按 token 溢出切分 prompt 的功能。prompt 将从最后一个字符开始切分\n  \u002F\u002F 默认：false\n  autoSlice?: boolean;\n\n  \u002F\u002F 尝试通过自省机制自动修复输出\n  \u002F\u002F 默认：true\n  autoHeal?: boolean;\n\n  \u002F\u002F 设置消息历史，如果您想继续现有的对话，这将非常有用\n  messageHistory?: ChatRequestMessage[];\n\n  \u002F\u002F 因限流或可恢复的 API 错误而重试此请求的次数\n  \u002F\u002F 默认：3\n  retries?: number;\n  \u002F\u002F 默认：30 秒\n  retryInterval?: number;\n  \u002F\u002F 默认：60 秒\n  timeout?: number;\n\n  \u002F\u002F 为响应分配的最小 token 数量。如果预测请求所需的 token 不足，将自动抛出 'TokenError' 而不会发送请求。\n  \u002F\u002F 默认：200\n  minimumResponseTokens?: number;\n};\n```\n\n#### 响应\n\n补全响应扩展了 `llm-api` 中的模型响应，特别添加了一个 `data` 字段，用于存储已解析的 JSON 数据，并根据传入的 `Zod` 模式自动进行类型推断和转换。\n\n```typescript\ninterface Response\u003CT extends z.ZodType> {\n  \u002F\u002F 从模型中解析并类型转换后的数据\n  data: z.infer\u003CT>;\n\n  \u002F\u002F 来自补全 API 的原始响应\n  content?: string;\n  name?: string;\n  arguments?: JsonValue;\n  usage?: {\n    promptTokens: number;\n    completionTokens: number;\n    totalTokens: number;\n  };\n}\n```\n\n### 其他\n\n#### 文本分割\n\n如果您需要在调用大模型之前将长文本拆分为多个块，`text-spitter.ts` 中也导出了几种文本分割器。除非有特殊原因，否则建议优先使用 `RecursiveTextSplitter`，因为它是最常用的文本分割器。","# ZodGPT 快速上手指南\n\nZodGPT 是一个用于从 OpenAI 和 Anthropic 等大模型获取结构化、完全类型化且经过验证的 JSON 输出的 TypeScript 库。它利用 Zod 进行模式定义与解析，并具备自动修复输出错误的能力。\n\n## 环境准备\n\n- **运行时环境**: Node.js (推荐 v16+)\n- **包管理器**: npm, yarn 或 pnpm\n- **前置依赖**:\n  - `zod`: 用于定义数据模式（作为 peer dependency）。\n  - `llm-api`: 用于连接不同的 LLM 提供商（如 OpenAI, Anthropic）。\n- **API Key**: 需要准备好 OpenAI 或 Anthropic 的 API Key。\n\n> **国内开发者提示**：如果访问 npm 官方源较慢，建议使用国内镜像源加速安装。\n> ```bash\n> # 临时使用淘宝镜像\n> npm config set registry https:\u002F\u002Fregistry.npmmirror.com\n> ```\n\n## 安装步骤\n\n在项目目录中执行以下命令安装核心库及依赖：\n\n```bash\nnpm i zod-gpt zod llm-api\n```\n\n或使用 yarn：\n\n```bash\nyarn add zod-gpt zod llm-api\n```\n\n## 基本使用\n\n### 1. 初始化客户端\n\n首先，通过 `llm-api` 初始化你的模型客户端。\n\n```typescript\nimport { OpenAIChatApi } from 'llm-api';\nimport { completion } from 'zod-gpt';\nimport { z } from 'zod';\n\nconst openai = new OpenAIChatApi(\n  { apiKey: 'YOUR_OPENAI_KEY' },\n  { model: 'gpt-4-0613' },\n);\n```\n\n### 2. 发送带模式的请求\n\n定义一个 Zod schema 来指定期望的输出结构。**注意**：务必使用 `.describe()` 为每个字段添加详细描述，这将帮助模型准确理解所需数据。\n\n```typescript\nconst response = await completion(\n  openai,\n  'Generate a step by step plan on how to run a hackathon',\n  {\n    schema: z.object({\n      plan: z.array(\n        z.object({\n          reason: z.string().describe('Name the reasoning for this step'),\n          id: z.string().describe('Unique step id'),\n          task: z\n            .string()\n            .describe('What is the task to be done for this step?'),\n        }),\n      ),\n    }),\n  },\n);\n\n\u002F\u002F response.data 已被自动推断类型：{ plan: { reason: string; id: string; task: string }[] }\nconsole.info('Response:', response.data);\n```\n\n### 3. 核心特性说明\n\n- **自动修复 (Auto Healing)**: 默认开启 (`autoHeal: true`)。如果模型返回的数据不符合 Schema，ZodGPT 会自动将错误信息反馈给模型并要求其重新生成，无需手动干预。\n- **文本切片 (Text Slicing)**: 若输入内容过长导致 Token 溢出，可设置 `autoSlice: true` 自动分割文本。需确保初始化 `OpenAIChatApi` 时设置了 `contextSize`。\n- **类型安全**: 返回的 `response.data` 会根据你定义的 Zod schema 自动获得完整的 TypeScript 类型支持。\n\n> **注意**: `schema` 选项仅接受对象类型 (`z.object`)。如果需要返回数组或其他类型，请将其包裹在一个对象中（如上例所示）。","某电商公司的后端工程师正在开发一个智能客服系统，需要让大模型从用户杂乱的投诉文本中提取出结构化的订单问题数据，以便直接存入数据库。\n\n### 没有 zod-gpt 时\n- **数据格式不可控**：模型返回的 JSON 经常缺少括号、键名拼写错误或包含多余的解释性文字，导致 `JSON.parse()` 频繁报错。\n- **类型安全缺失**：提取出的字段（如订单号、金额）在代码中被视为任意类型，必须在业务层编写大量冗余的代码进行手动校验和类型转换。\n- **错误处理复杂**：一旦模型输出不符合预期，开发者需要自行设计复杂的重试逻辑或正则清洗规则，甚至要手动引导模型“自我修正”。\n- **维护成本高**：当数据结构需求变更时，不仅要修改提示词（Prompt），还需要同步更新解析逻辑和类型定义，极易出现不一致。\n\n### 使用 zod-gpt 后\n- **输出严格结构化**：通过定义 Zod Schema，zod-gpt 强制模型以函数调用形式返回完全符合规范的 JSON，彻底杜绝格式错误。\n- **端到端类型安全**：响应数据自动具备完整的 TypeScript 类型推断，开发者可直接使用 `response.data`，无需任何手动类型断言。\n- **内置自动修复机制**：当模型首次输出不合规时，zod-gpt 会自动利用自我反思机制请求模型重新生成，大幅降低失败率。\n- **开发效率提升**：只需修改一处 Schema 定义，提示词、验证逻辑和类型声明同步更新，让数据结构变更变得简单可靠。\n\nzod-gpt 通过将模式定义转化为模型的强约束，实现了从非结构化文本到可信结构化数据的无缝流转，让大模型集成像调用普通 API 一样稳健。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fdzhng_zod-gpt_5042edfd.png","dzhng","David Zhang","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fdzhng_8363bc63.jpg","Co-founder & CEO @ Duet (duet.so)",null,"https:\u002F\u002Fduet.so","https:\u002F\u002Fgithub.com\u002Fdzhng",[80,84,88],{"name":81,"color":82,"percentage":83},"TypeScript","#3178c6",95.4,{"name":85,"color":86,"percentage":87},"JavaScript","#f1e05a",4.4,{"name":89,"color":90,"percentage":91},"Shell","#89e051",0.3,627,15,"2026-04-11T20:52:28","MIT","","未说明",{"notes":99,"python":97,"dependencies":100},"该工具是一个 TypeScript\u002FJavaScript 库，需通过 npm 或 yarn 安装。它本身不运行本地模型，而是作为客户端调用 OpenAI 或 Anthropic 的 API，因此无需本地 GPU、特定 Python 版本或大量内存。主要依赖 'zod' 进行数据验证和 'llm-api' 处理 API 交互。使用时需配置相应的 API Key。",[101,102],"zod","llm-api",[35,14],"2026-03-27T02:49:30.150509","2026-04-18T17:04:13.141203",[107,112,117,122,127],{"id":108,"question_zh":109,"answer_zh":110,"source_url":111},40357,"README 文档中的导入语句 `import { OpenAIChatApi } from 'zod-gpt';` 是否正确？","不正确，这是一个文档笔误。正确的导入方式应该是从 `llm-api` 包中导入，即：`import { OpenAIChatApi } from \"llm-api\";`。","https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fzod-gpt\u002Fissues\u002F3",{"id":113,"question_zh":114,"answer_zh":115,"source_url":116},40353,"如何使用该库调用内部函数（Function Calling）？","可以通过 companion 库 `llm-api` (https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fllm-api) 来实现。它支持通过 OpenAILegacy 进行函数调用，也支持新的工具调用（tool calling）API。","https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fzod-gpt\u002Fissues\u002F8",{"id":118,"question_zh":119,"answer_zh":120,"source_url":121},40354,"遇到 'fetch is not defined' 错误且提示缺少 Web Fetch API 类型怎么办？","这通常是因为 Node.js 版本过低。请将 Node.js 升级到 18 或更高版本，因为较低版本（如 Node 16）默认不包含所需的 fetch API。","https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fzod-gpt\u002Fissues\u002F9",{"id":123,"question_zh":124,"answer_zh":125,"source_url":126},40355,"Zod schema 中的 `describe` 字段内容会传递给大语言模型吗？","是的，会传递。底层的 `zod-to-json-schema` 包会自动处理这一逻辑，将描述信息包含在生成的 schema 中供模型使用。建议参考 README 中的示例。","https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fzod-gpt\u002Fissues\u002F7",{"id":128,"question_zh":129,"answer_zh":130,"source_url":131},40356,"如果数据解析失败，是否还能获取原始的响应数据？","可以。你可以通过访问 `response.content` 来获取原始数据，这将允许你访问底层 `llm-api` 返回的类型和内容。","https:\u002F\u002Fgithub.com\u002Fdzhng\u002Fzod-gpt\u002Fissues\u002F4",[]]