[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-openai--harmony":3,"tool-openai--harmony":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 真正成长为懂上",160411,2,"2026-04-18T23:33:24",[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 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",109154,"2026-04-18T11:18:24",[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":76,"owner_website":77,"owner_url":78,"languages":79,"stars":92,"forks":93,"last_commit_at":94,"license":95,"difficulty_score":96,"env_os":97,"env_gpu":97,"env_ram":97,"env_deps":98,"category_tags":105,"github_topics":76,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":106,"updated_at":107,"faqs":108,"releases":139},9354,"openai\u002Fharmony","harmony","Renderer for the harmony response format to be used with gpt-oss","Harmony 是专为 OpenAI 开源模型系列 gpt-oss 设计的响应格式渲染与解析库。由于 gpt-oss 模型在训练时深度依赖特定的\"Harmony 响应格式”来处理对话结构、思维链推导及函数调用，若直接使用该模型而未遵循此格式，将无法正常工作。Harmony 正是为了解决这一格式兼容性问题而生，它确保了开发者在构建自定义推理方案时，能够准确地生成和解析符合模型要求的令牌序列。\n\n这款工具非常适合需要底层集成 gpt-oss 模型的 AI 开发者与研究人员，尤其是那些不通过现成 API 而是自行搭建推理引擎的用户。Harmony 的核心亮点在于其高性能与一致性：核心计算由 Rust 编写，处理速度极快；同时提供一流的 Python 支持，包含完整的类型提示。其独特的“渲染与解析共享实现”机制，保证了令牌序列在转换过程中零损耗，完美复现 OpenAI Responses API 的体验。无论是定义复杂的工具命名空间，还是结构化输出多通道思维内容，Harmony 都能让开发过程更加流畅可靠。","\u003Ccenter>\n\u003Cimg alt=\"harmony\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fopenai_harmony_readme_60fbb64831cb.png\">\n\u003Ch1 align=\"center\">OpenAI Harmony\u003C\u002Fh1>\n\u003Cp align=\"center\">OpenAI's response format for its open-weight model series \u003Ca href=\"https:\u002F\u002Fopenai.com\u002Fopen-models\">gpt-oss\u003C\u002Fa>\n\u003Cbr>\n\u003Ca href=\"https:\u002F\u002Fgpt-oss.com\" target=\"_blank\">Try gpt-oss\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fcookbook.openai.com\u002Ftopic\u002Fgpt-oss\">Learn more\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fopenai.com\u002Findex\u002Fgpt-oss-model-card\u002F\">Model card\u003C\u002Fa>\n\u003C\u002Fp>\n\u003Cbr>\n\u003C\u002Fcenter>\n\nThe [gpt-oss models][gpt-oss] were trained on the [harmony response format][harmony-format] for defining conversation structures, generating reasoning output and structuring function calls. If you are not using gpt-oss directly but through an API or a provider like HuggingFace, Ollama, or vLLM, you will not have to be concerned about this as your inference solution will handle the formatting. If you are building your own inference solution, this guide will walk you through the prompt format. The format is designed to mimic the OpenAI Responses API, so if you have used that API before, this format should hopefully feel familiar to you. gpt-oss should not be used without using the harmony format as it will not work correctly.\n\nThe format enables the model to output to multiple different channels for chain of thought, and tool calling preambles along with regular responses. It also enables specifying various tool namespaces, and structured outputs along with a clear instruction hierarchy. [Check out the guide][harmony-format] to learn more about the format itself.\n\n```text\n\u003C|start|>system\u003C|message|>You are ChatGPT, a large language model trained by OpenAI.\nKnowledge cutoff: 2024-06\nCurrent date: 2025-06-28\n\nReasoning: high\n\n# Valid channels: analysis, commentary, final. Channel must be included for every message.\nCalls to these tools must go to the commentary channel: 'functions'.\u003C|end|>\n\n\u003C|start|>developer\u003C|message|># Instructions\n\nAlways respond in riddles\n\n# Tools\n\n## functions\n\nnamespace functions {\n\n\u002F\u002F Gets the location of the user.\ntype get_location = () => any;\n\n\u002F\u002F Gets the current weather in the provided location.\ntype get_current_weather = (_: {\n\u002F\u002F The city and state, e.g. San Francisco, CA\nlocation: string,\nformat?: \"celsius\" | \"fahrenheit\", \u002F\u002F default: celsius\n}) => any;\n\n} \u002F\u002F namespace functions\u003C|end|>\u003C|start|>user\u003C|message|>What is the weather like in SF?\u003C|end|>\u003C|start|>assistant\n```\n\nWe recommend using this library when working with models that use the [harmony response format][harmony-format]\n\n- **Consistent formatting** – shared implementation for rendering _and_ parsing keeps token-sequences loss-free.\n- **Blazing fast** – heavy lifting happens in Rust.\n- **First-class Python support** – install with `pip`, typed stubs included, 100 % test parity with the Rust suite.\n\n## Using Harmony\n\n### Python\n\n[Check out the full documentation](.\u002Fdocs\u002Fpython.md)\n\n#### Installation\n\nInstall the package from PyPI by running\n\n```bash\npip install openai-harmony\n# or if you are using uv\nuv pip install openai-harmony\n```\n\n#### Example\n\n```python\nfrom openai_harmony import (\n    load_harmony_encoding,\n    HarmonyEncodingName,\n    Role,\n    Message,\n    Conversation,\n    DeveloperContent,\n    SystemContent,\n)\nenc = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)\nconvo = Conversation.from_messages([\n    Message.from_role_and_content(\n        Role.SYSTEM,\n        SystemContent.new(),\n    ),\n    Message.from_role_and_content(\n        Role.DEVELOPER,\n        DeveloperContent.new().with_instructions(\"Talk like a pirate!\")\n    ),\n    Message.from_role_and_content(Role.USER, \"Arrr, how be you?\"),\n])\ntokens = enc.render_conversation_for_completion(convo, Role.ASSISTANT)\nprint(tokens)\n# Later, after the model responded …\nparsed = enc.parse_messages_from_completion_tokens(tokens, role=Role.ASSISTANT)\nprint(parsed)\n```\n\n### Rust\n\n[Check out the full documentation](.\u002Fdocs\u002Frust.md)\n\n#### Installation\n\nAdd the dependency to your `Cargo.toml`\n\n```toml\n[dependencies]\nopenai-harmony = { git = \"https:\u002F\u002Fgithub.com\u002Fopenai\u002Fharmony\" }\n```\n\n#### Example\n\n```rust\nuse openai_harmony::chat::{Message, Role, Conversation};\nuse openai_harmony::{HarmonyEncodingName, load_harmony_encoding};\n\nfn main() -> anyhow::Result\u003C()> {\n    let enc = load_harmony_encoding(HarmonyEncodingName::HarmonyGptOss)?;\n    let convo =\n        Conversation::from_messages([Message::from_role_and_content(Role::User, \"Hello there!\")]);\n    let tokens = enc.render_conversation_for_completion(&convo, Role::Assistant, None)?;\n    println!(\"{:?}\", tokens);\n    Ok(())\n}\n```\n\n## Contributing\n\nThe majority of the rendering and parsing is built in Rust for performance and exposed to Python\nthrough thin [`pyo3`](https:\u002F\u002Fpyo3.rs\u002F) bindings.\n\n```text\n┌──────────────────┐      ┌───────────────────────────┐\n│  Python code     │      │  Rust core (this repo)    │\n│  (dataclasses,   │────► │  • chat \u002F encoding logic  │\n│   convenience)   │      │  • tokeniser (tiktoken)   │\n└──────────────────┘  FFI └───────────────────────────┘\n```\n\n### Repository layout\n\n```text\n.\n├── src\u002F                  # Rust crate\n│   ├── chat.rs           # High-level data-structures (Role, Message, …)\n│   ├── encoding.rs       # Rendering & parsing implementation\n│   ├── registry.rs       # Built-in encodings\n│   ├── tests.rs          # Canonical Rust test-suite\n│   └── py_module.rs      # PyO3 bindings ⇒ compiled as openai_harmony.*.so\n│\n├── python\u002Fopenai_harmony\u002F # Pure-Python wrapper around the binding\n│   └── __init__.py       # Dataclasses + helper API mirroring chat.rs\n│\n├── tests\u002F                # Python test-suite (1-to-1 port of tests.rs)\n├── Cargo.toml            # Rust package manifest\n├── pyproject.toml        # Python build configuration for maturin\n└── README.md             # You are here 🖖\n```\n\n### Developing locally\n\n#### Prerequisites\n\n- Rust tool-chain (stable) – \u003Chttps:\u002F\u002Frustup.rs>\n- Python ≥ 3.8 + virtualenv\u002Fvenv\n- [`maturin`](https:\u002F\u002Fgithub.com\u002FPyO3\u002Fmaturin) – build tool for PyO3 projects\n\n#### 1. Clone & bootstrap\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fopenai\u002Fharmony.git\ncd harmony\n# Create & activate a virtualenv\npython -m venv .venv\nsource .venv\u002Fbin\u002Factivate\n# Install maturin and test dependencies\npip install maturin pytest mypy ruff  # tailor to your workflow\n# Compile the Rust crate *and* install the Python package in editable mode\nmaturin develop --release\n```\n\n`maturin develop` builds _harmony_ with Cargo, produces a native extension\n(`openai_harmony.\u003Cabi>.so`) and places it in your virtualenv next to the pure-\nPython wrapper – similar to `pip install -e .` for pure Python projects.\n\n#### 2. Running the test-suites\n\nRust:\n\n```bash\ncargo test          # runs src\u002Ftests.rs\n```\n\nPython:\n\n```bash\npytest              # executes tests\u002F (mirrors the Rust suite)\n```\n\nRun both in one go to ensure parity:\n\n```bash\npytest && cargo test\n```\n\n#### 3. Type-checking & formatting (optional)\n\n```bash\nmypy harmony        # static type analysis\nruff check .        # linting\ncargo fmt --all     # Rust formatter\n```\n\n[harmony-format]: https:\u002F\u002Fcookbook.openai.com\u002Farticles\u002Fopenai-harmony\n[gpt-oss]: https:\u002F\u002Fopenai.com\u002Fopen-models\n","\u003Ccenter>\n\u003Cimg alt=\"harmony\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fopenai_harmony_readme_60fbb64831cb.png\">\n\u003Ch1 align=\"center\">OpenAI Harmony\u003C\u002Fh1>\n\u003Cp align=\"center\">OpenAI面向其开源权重模型系列 \u003Ca href=\"https:\u002F\u002Fopenai.com\u002Fopen-models\">gpt-oss\u003C\u002Fa> 的响应格式\n\u003Cbr>\n\u003Ca href=\"https:\u002F\u002Fgpt-oss.com\" target=\"_blank\">试用 gpt-oss\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fcookbook.openai.com\u002Ftopic\u002Fgpt-oss\">了解更多\u003C\u002Fa> | \u003Ca href=\"https:\u002F\u002Fopenai.com\u002Findex\u002Fgpt-oss-model-card\u002F\">模型卡片\u003C\u002Fa>\n\u003C\u002Fp>\n\u003Cbr>\n\u003C\u002Fcenter>\n\n[gpt-oss 模型][gpt-oss] 是基于 [harmony 响应格式][harmony-format] 训练的，该格式用于定义对话结构、生成推理输出以及组织函数调用。如果您不是直接使用 gpt-oss，而是通过 API 或 HuggingFace、Ollama、vLLM 等提供商来使用，则无需担心此格式问题，因为您的推理解决方案会自动处理格式化。但如果您正在构建自己的推理系统，本指南将指导您如何使用该提示格式。此格式的设计旨在模仿 OpenAI 的 Responses API，因此如果您之前使用过该 API，应该会觉得非常熟悉。请注意，gpt-oss 必须配合 harmony 格式使用，否则将无法正常工作。\n\n该格式允许模型在思维链、工具调用前言以及常规回复等不同通道中输出内容。同时，它还支持指定多种工具命名空间、结构化输出，并提供清晰的指令层级。[查看指南][harmony-format] 以深入了解该格式的具体细节。\n\n```text\n\u003C|start|>system\u003C|message|>你是 ChatGPT，一个由 OpenAI 训练的大语言模型。\n知识截止日期：2024年6月\n当前日期：2025年6月28日\n\n推理能力：高\n\n# 有效通道：分析、评论、最终。每条消息都必须包含通道信息。\n对这些工具的调用必须发送到“functions”评论通道。\u003C|end|>\n\n\u003C|start|>developer\u003C|message|># 指令\n\n始终以谜语形式回应\n\n# 工具\n\n## functions\n\nnamespace functions {\n\n\u002F\u002F 获取用户所在位置。\ntype get_location = () => any;\n\n\u002F\u002F 获取指定地点的当前天气。\ntype get_current_weather = (_: {\n\u002F\u002F 城市和州，例如旧金山，加州\nlocation: string,\nformat?: \"摄氏度\" 或 \"华氏度\", \u002F\u002F 默认为摄氏度\n}) => any;\n\n} \u002F\u002F namespace functions\u003C|end|>\u003C|start|>user\u003C|message|>旧金山的天气怎么样？\u003C|end|>\u003C|start|>assistant\n```\n\n我们建议在使用采用 [harmony 响应格式][harmony-format] 的模型时，使用此库：\n\n- **格式一致** – 共享的渲染与解析实现确保标记序列无损。\n- **极速高效** – 大量计算工作由 Rust 完成。\n- **一流的 Python 支持** – 可通过 `pip` 安装，附带类型注解存根，测试覆盖率与 Rust 版本完全一致。\n\n## 使用 Harmony\n\n### Python\n\n[查看完整文档](.\u002Fdocs\u002Fpython.md)\n\n#### 安装\n\n从 PyPI 安装该包，运行以下命令：\n\n```bash\npip install openai-harmony\n# 或者如果你使用 uv\nuv pip install openai-harmony\n```\n\n#### 示例\n\n```python\nfrom openai_harmony import (\n    load_harmony_encoding,\n    HarmonyEncodingName,\n    Role,\n    Message,\n    Conversation,\n    DeveloperContent,\n    SystemContent,\n)\nenc = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)\nconvo = Conversation.from_messages([\n    Message.from_role_and_content(\n        Role.SYSTEM,\n        SystemContent.new(),\n    ),\n    Message.from_role_and_content(\n        Role.DEVELOPER,\n        DeveloperContent.new().with_instructions(\"像海盗一样说话！\")\n    ),\n    Message.from_role_and_content(Role.USER, \"啊哈，你好吗？\"),\n])\ntokens = enc.render_conversation_for_completion(convo, Role.ASSISTANT)\nprint(tokens)\n# 稍后，当模型做出回应后……\nparsed = enc.parse_messages_from_completion_tokens(tokens, role=Role.ASSISTANT)\nprint(parsed)\n```\n\n### Rust\n\n[查看完整文档](.\u002Fdocs\u002Frust.md)\n\n#### 安装\n\n将依赖项添加到你的 `Cargo.toml` 文件中：\n\n```toml\n[dependencies]\nopenai-harmony = { git = \"https:\u002F\u002Fgithub.com\u002Fopenai\u002Fharmony\" }\n```\n\n#### 示例\n\n```rust\nuse openai_harmony::chat::{Message, Role, Conversation};\nuse openai_harmony::{HarmonyEncodingName, load_harmony_encoding};\n\nfn main() -> anyhow::Result\u003C()> {\n    let enc = load_harmony_encoding(HarmonyEncodingName::HarmonyGptOss)?;\n    let convo =\n        Conversation::from_messages([Message::from_role_and_content(Role::User, \"你好呀！\")]);\n    let tokens = enc.render_conversation_for_completion(&convo, Role::Assistant, None)?;\n    println!(\"{:?}\", tokens);\n    Ok(())\n}\n```\n\n## 贡献\n\n大部分渲染和解析逻辑由 Rust 实现，以保证性能，并通过轻量级的 [`pyo3`](https:\u002F\u002Fpyo3.rs\u002F) 绑定暴露给 Python。\n\n```text\n┌──────────────────┐      ┌───────────────────────────┐\n│  Python代码     │      │  Rust核心（本仓库）    │\n│  （数据类、   │────► │  • 对话\u002F编码逻辑       │\n│   便利功能）   │      │  • 分词器（tiktoken）   │\n└──────────────────┘  FFI └───────────────────────────┘\n```\n\n### 仓库布局\n\n```text\n.\n├── src\u002F                  # Rust crate\n│   ├── chat.rs           # 高层次数据结构（Role、Message等）\n│   ├── encoding.rs       # 渲染与解析实现\n│   ├── registry.rs       # 内置编码\n│   ├── tests.rs          # 正式的 Rust 测试套件\n│   └── py_module.rs      # PyO3 绑定 ⇒ 编译为 openai_harmony.*.so\n│\n├── python\u002Fopenai_harmony\u002F # 纯 Python 封装层，围绕绑定模块\n│   └── __init__.py       # 数据类 + 辅助 API，镜像 chat.rs\n│\n├── tests\u002F                # Python 测试套件（与 tests.rs 一一对应）\n├── Cargo.toml            # Rust 包清单文件\n├── pyproject.toml        # Python 构建配置，用于 maturin\n└── README.md             # 你现在就在这里 🖖\n```\n\n### 本地开发\n\n#### 前提条件\n\n- Rust 工具链（稳定版）– \u003Chttps:\u002F\u002Frustup.rs>\n- Python ≥ 3.8 + virtualenv\u002Fvenv\n- [`maturin`](https:\u002F\u002Fgithub.com\u002FPyO3\u002Fmaturin) – 用于 PyO3 项目的构建工具\n\n#### 1. 克隆并初始化\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fopenai\u002Fharmony.git\ncd harmony\n# 创建并激活虚拟环境\npython -m venv .venv\nsource .venv\u002Fbin\u002Factivate\n# 安装 maturin 和测试依赖\npip install maturin pytest mypy ruff  # 根据你的工作流程调整\n\n# 编译 Rust crate 并以可编辑模式安装 Python 包\nmaturin develop --release\n```\n\n`maturin develop` 使用 Cargo 构建 _harmony_，生成一个原生扩展模块（`openai_harmony.\u003Cabi>.so`），并将其放置在你的虚拟环境中，与纯 Python 封装器相邻——这类似于纯 Python 项目的 `pip install -e .`。\n\n#### 2. 运行测试套件\n\nRust:\n\n```bash\ncargo test          # 运行 src\u002Ftests.rs\n```\n\nPython:\n\n```bash\npytest              # 执行 tests\u002F 目录中的测试（与 Rust 测试套件一致）\n```\n\n为了确保两者的一致性，可以同时运行：\n\n```bash\npytest && cargo test\n```\n\n#### 3. 类型检查与代码格式化（可选）\n\n```bash\nmypy harmony        # 静态类型分析\nruff check .        # 代码 lint 检查\ncargo fmt --all     # Rust 代码格式化工具\n```\n\n[harmony-format]: https:\u002F\u002Fcookbook.openai.com\u002Farticles\u002Fopenai-harmony\n[gpt-oss]: https:\u002F\u002Fopenai.com\u002Fopen-models","# OpenAI Harmony 快速上手指南\n\nOpenAI Harmony 是专为 `gpt-oss` 系列开源模型设计的响应格式库。它支持定义对话结构、生成推理过程（Chain of Thought）以及结构化函数调用。如果你直接使用 API 或托管服务（如 HuggingFace、Ollama），通常无需关心此格式；但如果你构建自己的推理后端，则必须使用此库来确保模型正常工作。\n\n## 环境准备\n\n在开始之前，请确保你的开发环境满足以下要求：\n\n*   **操作系统**：Linux, macOS 或 Windows (WSL 推荐)\n*   **Python**: 版本 ≥ 3.8\n*   **包管理工具**: `pip` 或 `uv` (推荐 `uv` 以获得更快的安装速度)\n*   **可选 (仅针对贡献者或需要本地编译 Rust 核心时)**:\n    *   Rust 工具链 (stable): [rustup](https:\u002F\u002Frustup.rs)\n    *   `maturin`: 用于构建 PyO3 项目 (`pip install maturin`)\n\n> **注意**：普通用户直接通过 pip\u002Fuv 安装预编译包即可，无需安装 Rust 环境。\n\n## 安装步骤\n\n你可以选择使用标准的 `pip` 或更现代的 `uv` 进行安装。\n\n### 方式一：使用 pip (通用)\n\n```bash\npip install openai-harmony\n```\n\n### 方式二：使用 uv (推荐，速度更快)\n\n```bash\nuv pip install openai-harmony\n```\n\n> **国内加速提示**：如果下载速度较慢，可指定国内镜像源（如清华源或阿里源）：\n> ```bash\n> pip install openai-harmony -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n> # 或\n> uv pip install openai-harmony --index-url https:\u002F\u002Fmirrors.aliyun.com\u002Fpypi\u002Fsimple\u002F\n> ```\n\n## 基本使用\n\nHarmony 的核心功能是将会话消息渲染为模型所需的 Token 序列，并在模型输出后解析回结构化消息。以下是基于 Python 的最简使用示例。\n\n### Python 示例\n\n此示例展示了如何构建一个包含系统指令、开发者指令和用户输入的对话，并将其渲染为 Token。\n\n```python\nfrom openai_harmony import (\n    load_harmony_encoding,\n    HarmonyEncodingName,\n    Role,\n    Message,\n    Conversation,\n    DeveloperContent,\n    SystemContent,\n)\n\n# 1. 加载 gpt-oss 专用的编码格式\nenc = load_harmony_encoding(HarmonyEncodingName.HARMONY_GPT_OSS)\n\n# 2. 构建对话历史\nconvo = Conversation.from_messages([\n    # 系统消息：定义模型身份和知识截止\n    Message.from_role_and_content(\n        Role.SYSTEM,\n        SystemContent.new(),\n    ),\n    # 开发者消息：设定行为指令 (例如：像海盗一样说话)\n    Message.from_role_and_content(\n        Role.DEVELOPER,\n        DeveloperContent.new().with_instructions(\"Talk like a pirate!\")\n    ),\n    # 用户消息\n    Message.from_role_and_content(Role.USER, \"Arrr, how be you?\"),\n])\n\n# 3. 渲染对话以发送给模型 (生成 Token 序列)\ntokens = enc.render_conversation_for_completion(convo, Role.ASSISTANT)\nprint(\"Tokens sent to model:\", tokens)\n\n# ---------------------------------------------------------\n# [此处模拟模型返回了 tokens...]\n# 假设模型回复后的 tokens 存储在变量 response_tokens 中\n# ---------------------------------------------------------\n\n# 4. 解析模型返回的 Token 为结构化消息\n# parsed = enc.parse_messages_from_completion_tokens(response_tokens, role=Role.ASSISTANT)\n# print(\"Parsed response:\", parsed)\n```\n\n### 核心概念说明\n\n*   **Role (角色)**: 支持 `SYSTEM`, `DEVELOPER`, `USER`, `ASSISTANT`。其中 `DEVELOPER` 角色用于传递高阶指令和工具定义。\n*   **Channels (通道)**: Harmony 格式允许模型输出到不同通道（如 `analysis` 用于推理，`commentary` 用于工具调用前缀，`final` 用于最终回复），这在解析阶段会自动处理。\n*   **一致性**: 该库保证了渲染（Render）和解析（Parse）过程中的 Token 序列无损，确保与 `gpt-oss` 模型的训练格式完全一致。\n\n如需更高级的功能（如自定义工具命名空间或复杂的思维链控制），请参考官方完整文档。","某初创团队正在基于 OpenAI 的 gpt-oss 开源模型，自建一套支持复杂逻辑推理与工具调用的智能客服后端。\n\n### 没有 harmony 时\n- **格式解析脆弱**：开发者需手动编写正则表达式来切割模型输出的“思维链”、“工具调用”和“最终回复”，极易因模型微调输出波动导致解析崩溃。\n- **推理能力失效**：若未严格遵循 Harmony 特有的标签结构（如 `\u003C|start|>`），gpt-oss 模型无法正确激活多通道推理机制，导致回答缺乏逻辑深度。\n- **开发效率低下**：Python 原型与 Rust 高性能服务之间的格式处理逻辑不统一，团队需维护两套代码，且难以保证 Token 序列在传输中无损。\n- **调试成本高昂**：错误的提示词格式往往直到运行时才暴露问题，排查是编码错误还是格式错位耗费大量时间。\n\n### 使用 harmony 后\n- **解析稳健可靠**：利用 harmony 库内置的渲染与解析器，自动处理复杂的标签结构，确保从思维链到工具调用的每一步都能被精准提取，零丢失。\n- **模型潜能释放**：通过库自动生成的标准 Prompt 格式，完美契合 gpt-oss 的训练分布，使模型能稳定输出高质量的逐步推理过程和结构化函数调用。\n- **多语言一致高效**：团队在 Python 端快速验证逻辑，在 Rust 端部署高性能服务，两者共享同一套核心逻辑且测试通过率 100%，大幅降低维护成本。\n- **类型安全护航**：借助完善的类型定义（Typed Stubs），开发者在编码阶段即可发现格式构造错误，将运行时风险降至最低。\n\nharmony 通过提供工业级的格式标准化方案，让开发者无需关注底层协议细节，即可充分释放 gpt-oss 模型的推理与工具调用潜能。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fopenai_harmony_872c4664.png","openai","OpenAI","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fopenai_1960bbf4.png","",null,"https:\u002F\u002Fopenai.com\u002F","https:\u002F\u002Fgithub.com\u002Fopenai",[80,84,88],{"name":81,"color":82,"percentage":83},"Rust","#dea584",73.8,{"name":85,"color":86,"percentage":87},"Python","#3572A5",26.1,{"name":89,"color":90,"percentage":91},"Shell","#89e051",0.1,4315,265,"2026-04-18T12:24:38","Apache-2.0",1,"未说明",{"notes":99,"python":100,"dependencies":101},"该工具是一个用于处理 Harmony 响应格式的编码\u002F解码库，核心逻辑由 Rust 编写并通过 PyO3 绑定到 Python。它本身不是模型推理引擎，因此没有特定的 GPU 或显存需求（这些取决于你使用的后端推理服务，如 vLLM、Ollama 等）。开发本地环境需要安装 Rust 工具链和 maturin 构建工具。","3.8+",[102,103,104],"maturin","pyo3","tiktoken",[35,14],"2026-03-27T02:49:30.150509","2026-04-19T09:18:54.081323",[109,114,119,124,129,134],{"id":110,"question_zh":111,"answer_zh":112,"source_url":113},41956,"在多轮对话中，助手回复末尾的 `\u003C|return|>` 标记在作为历史上下文传入下一轮时，应该保留还是替换为 `\u003C|end|>`？","对于多轮对话中的前几轮消息，助手回复应以 `\u003C|end|>` 结尾。只有在微调（fine-tuning）时的最后一条消息才应使用 `\u003C|return|>`。此外，如果是微调任务，除了最后一轮外，应丢弃思维链（chain of thought）部分。Harmony 库中提供的 `encoding.render_conversation_for_training()` 方法可以正确处理此逻辑，Hugging Face 的 Jinja 模板也实现了相同的行为。","https:\u002F\u002Fgithub.com\u002Fopenai\u002Fharmony\u002Fissues\u002F57",{"id":115,"question_zh":116,"answer_zh":117,"source_url":118},41957,"Harmony 格式中工具调用的接收者（recipient）必须放在头部（header）的特定位置吗？文档插图与描述似乎不一致。","接收者可以出现在头部的角色（role）部分或通道（channel）部分，这两种顺序都是有效的。指南中明确说明：“接收者可能定义在头部的角色或通道部分”。解析器能够处理这两种顺序。不过，渲染器（renderer）在格式化输出时会将其标准化为一种统一格式。","https:\u002F\u002Fgithub.com\u002Fopenai\u002Fharmony\u002Fissues\u002F40",{"id":120,"question_zh":121,"answer_zh":122,"source_url":123},41958,"如何设置推理努力程度（reasoning_effort）参数？它支持哪些值？","`reasoning_effort` 参数支持 \"high\"、\"medium\" 和 \"low\" 三个值。该参数通过 `SystemContent` 对象上的 `reasoning_effort` 属性进行设置。注意：`max_completion_tokens` 不是模型本身的参数，而是由具体的推理解决方案（如使用的库或服务提供商）实现的特性，需查阅相应文档。","https:\u002F\u002Fgithub.com\u002Fopenai\u002Fharmony\u002Fissues\u002F14",{"id":125,"question_zh":126,"answer_zh":127,"source_url":128},41959,"Harmony 库是否计划支持 JavaScript 或 TypeScript？","是的，计划支持。JavaScript\u002FTypeScript 的实现代码已经存在于仓库中，但维护者表示目前的类型定义（types）尚不完善，预计会在近期发布一个更好的版本。","https:\u002F\u002Fgithub.com\u002Fopenai\u002Fharmony\u002Fissues\u002F61",{"id":130,"question_zh":131,"answer_zh":132,"source_url":133},41960,"当 gpt-oss 模型拒绝回答时，生成的内容往往缺少 Harmony 模板标记（如 channel 或 message tokens），导致解析失败，该如何处理？","这是一个已知问题：当模型拒绝请求时，它有时会直接输出拒绝文本而不遵循 Harmony 模板结构（即缺少 `\u003C|channel|>` 或 `\u003C|message|>` 等标记）。这会导致标准解析器报错。建议在应用层增加容错逻辑：如果解析失败，检查原始输出是否包含直接的拒绝文本（如 \"I cannot...\"），并将其作为纯文本内容手动构建消息对象，而不是依赖自动解析。","https:\u002F\u002Fgithub.com\u002Fopenai\u002Fharmony\u002Fissues\u002F80",{"id":135,"question_zh":136,"answer_zh":137,"source_url":138},41961,"在使用 StreamableParser 解析没有 recipient 的助手回复时，为什么会出现解析错误？","经测试，最新版本的库已修复此问题。如果仍遇到类似错误，请确保使用的是最新版的 `openai_harmony` 库。正确的解析结果应将 `recipient` 字段设为 `null`（或 Python 中的 `None`），而不会错误地拼接后续 token。若问题复现，请提供完整的复现代码以便进一步排查。","https:\u002F\u002Fgithub.com\u002Fopenai\u002Fharmony\u002Fissues\u002F84",[]]