halo-plugin-dev

Halo 插件开发

从目标插件开始工作，仅当任务需要 Halo 特定契约时才获取最新的 Halo 文档。不要依赖技能中嵌入的 API 细节或训练数据中的记忆。

确定目标

• 编辑前检查现有的 Gradle 文件、src/main/resources/plugin.yaml、UI 包清单和构建配置，以及附近的实现。
• 确定 Halo 平台依赖和 plugin.yaml 中的 spec.requires。不要擅自提高要求或切换 UI 构建格式。
• 保留现有插件的结构和工具链。对于新插件，优先使用官方的 pnpm create halo-plugin 脚手架，除非用户选择了其他起点。

按需获取文档

1. 当任务涉及 Halo 插件 API、配置、生命周期、UI、DevTools、安全或集成契约时，从插件文档索引开始。
2. 仅当文档路径不明确或任务涉及多个文档分区时，才使用完整的 Halo 文档索引。
3. 仅获取与当前任务相关的 Markdown 页面。默认不要加载 llms-full.txt。
4. 对于版本敏感的工作，还要阅读插件 API 更新日志，然后根据目标依赖、源码或现有调用方核实确切的签名和行为。目标版本优先于当前网站上的文档。

如果无法访问在线文档，尽可能根据目标检出代码和依赖源码继续，并说明哪些内容无法核实，而不是猜测。

Halo 特定边界

• 避免在响应式 WebFlux 路径上执行阻塞工作；遵循当前的响应式开发指南。
• 添加依赖或自定义替代方案之前，先复用 Halo 提供的 UI 组件、FormKit 输入组件、共享工具和项目已安装的构建工具。
• 普通插件设置使用 Setting YAML，不要重复创建设置路由。页面和模态框表单使用 FormKit；使用原生替代方案之前，先复用 Halo 的列表、搜索、模态框、反馈和权限组件；遵循当前的表单和页面组件指南。
• 使用项目的 generateApiClient 任务，根据自定义模型和文档化的 SpringdocRouteBuilder 端点生成 TypeScript 模型和 API 方法。复用 Halo 的 axiosInstance；不要手写生成的资源类型，也不要为 /api 或 /apis 创建单独的 Axios 客户端。遵循当前的 API 请求指南。
• 将生成的 API 客户端和构建后的 UI 资源视为生成文件：修改其输入，并使用项目的生成器或构建任务，而不是直接编辑输出文件。
• 密码、令牌、API 密钥和私钥应存储在 Halo Secret 中，绝不能放在 ConfigMap 或自定义模型规范中。附加凭据前，验证用户控制的出站目标，防范 SSRF 和重定向风险；如果配置加载失败，应关闭公共 API 或安全开关。遵循当前的出站 HTTP 指南。
• 仅在需要非超级管理员或匿名访问时添加 RoleTemplates；授予所需的最小权限。

验证

使用项目现有的 Gradle 和 UI 脚本。运行范围最小的相关测试和检查；如果清单、UI 输出或生成的资源会影响插件 JAR，则验证打包结果。如果有可运行的 Halo 实例，则对已更改的 Console、用户中心、API、生命周期或主题集成路径进行冒烟测试。