openwebui-extensions copilot-instructions.md

Copilot Instructions for openwebui-extensions

本文档定义了 OpenWebUI 插件开发的标准规范和最佳实践。Copilot 在生成代码或文档时应遵循这些准则。

This document defines the standard conventions and best practices for OpenWebUI plugin development. Copilot should follow these guidelines when generating code or documentation.

---

🏗️ 项目结构与命名 (Project Structure & Naming)

1. 语言与代码规范 (Language & Code Requirements)

插件代码 (Plugin Code)

每个插件必须采用单文件国际化 (i18n) 设计。严禁为不同语言创建独立的源代码文件（如 _cn.py）。

1. 单代码文件: plugins/{type}/{name}/{name}.py
2. 内置 i18n: 必须在代码中根据前端传来的用户语言（如 __user__ 中的 language 或通过 get_user_language 脚本读取）动态切换界面显示、提示词和状态日志。

示例目录结构：

plugins/actions/export_to_docx/
├── export_to_word.py      # 单个代码文件，内置多语言支持
├── README.md               # 英文文档 (English documentation)
└── README_CN.md            # 中文文档

文档 (Documentation)

尽管代码是合一的，但为了市场展示和 SEO，每个插件目录仍必须包含双语 README 文件：

• README.md - English documentation
• README_CN.md - 中文文档

文档交付与审阅 (Documentation Delivery for Review)

当任务涉及文档类内容时，例如 README、Guide、Post、Release Notes、Announcement、Development Docs：

• 必须同时提供英文版与中文版，方便审阅与校对。
• 若仓库最终只提交英文文件，也必须在对话中额外提供中文版草稿给维护者 review。
• 若用户未明确指定只保留单语文件，默认按双语交付处理。
• 中文版的目标是便于审阅，应忠实对应英文原意，可在表达上自然调整，但不得遗漏风险、限制、步骤或结论。

README 结构规范 (README Structure Standard)

所有插件 README 必须遵循以下统一结构顺序：

1. 标题 (Title): 插件名称，带 Emoji 图标
2. 元数据 (Metadata): 作者、版本、项目链接 (一行显示)
   • 格式: **Author:** [Fu-Jie](https://github.com/Fu-Jie) | **Version:** x.x.x | **Project:** [OpenWebUI Extensions](https://github.com/Fu-Jie/openwebui-extensions)
   • 注意: Author 和 Project 为固定值，仅需更新 Version 版本号
3. 描述 (Description): 一句话功能介绍
4. 最新更新 (What's New): 必须放在描述之后，仅展示最近 1 次更新
5. 核心特性 (Key Features): 使用 Emoji + 粗体标题 + 描述格式
6. 使用方法 (How to Use): 按步骤说明
7. 配置参数 (Configuration/Valves): 使用表格格式，包含参数名、默认值、描述
8. 支持 (Support): 必须包含，放在配置参数之后、故障排除之前
   • English: If this plugin has been useful, a star on [OpenWebUI Extensions](https://github.com/Fu-Jie/openwebui-extensions) is a big motivation for me. Thank you for the support.
   • 中文: 如果这个插件对你有帮助，欢迎到 [OpenWebUI Extensions](https://github.com/Fu-Jie/openwebui-extensions) 点个 Star，这将是我持续改进的动力，感谢支持。
9. 其他 (Others): 支持的模板类型、语法示例、故障排除等
   • Changelog: 统一指向 GitHub 项目历史，不在 README 中列出具体变更