用途：创建或修改 Halo CMS 主题，涉及 Thymeleaf 模板、theme.yaml、settings.yaml、Finder API、静态资源、Vite 集成与主题 UI。
主要能力与做法：先检查目标主题的 theme.yaml、settings.yaml、包清单、构建配置和代表性模板，确认 spec.requires 与实际 Halo 版本，判断模板是直接写在 templates/ 还是由 src/ 等源目录生成。不要凭训练数据记忆 Finder 签名、模板变量或配置字段。
按需获取文档：涉及主题配置、模板、Finder API、全局变量、资源、注解、i18n、打包或插件集成时，从主题文档索引开始；路由不清或跨章节时用完整文档索引；只取当前任务相关的 Markdown 页面，默认不加载 llms-full.txt。版本敏感时读主题 API 变更日志，并以目标版本或现有模板为准，目标版本优先于当前站点文档。在线文档不可用时，尽量基于目标检出与已安装依赖继续，并说明无法核实之处，不要猜测。
边界与限制：主题目录名需与 theme.yaml 的 metadata.name 一致。使用构建工具的主题应改源模板与资源后运行现有构建，不要手改生成的 templates/ 输出或带哈希资源。写表达式前读当前 Thymeleaf 指南；Halo 2.26 使用 Thymeleaf 3.1，#request、#response、#session、#servletContext 不可用，不要猜测表达式方法或从请求对象推导页面 URL。站点标识与全局注入默认由 Halo 负责，使用 site.logo、系统 SEO 设置、Halo 的 head 处理与 <halo:footer />；仅在主题特定覆盖且带系统回退时新增设置。不要重复 Halo 注入的 description 或 keywords；Canonical、Open Graph、Twitter Card 与结构化数据为可选能力，需遵循当前 SEO 指南并带冲突规避开关。保留项目既有 Thymeleaf 布局与资源约定，使用 Finder 方法、模板变量、Halo 工具、自定义标签或页面布局契约前查相关文档；集成官方前端组件时遵循插件集成指南中的配色方案契约。
起始模板：assets/theme-minimal/ 为零构建工具的最小主题，含标准路由模板，适合快速原型或简单主题；assets/theme-vite/ 为 Vite 项目模板，含 vite-plugin-halo-theme，推荐用于新主题，包含局部布局复用与 CSS 工具链。用法：将目录复制到 Halo 工作目录的 themes/ 下，确保文件夹名与 theme.yaml 中 metadata.name 一致，然后在 Console 中安装并激活。仅在创建新主题时使用，切勿用起始模板替换现有主题。
验证：适用时运行主题现有构建与打包检查；在兼容的 Halo 实例上测试每个改动的模板类型或集成路径，至少覆盖受影响路由及一个共享布局使用方，检查渲染 HTML、资源加载、分页或空状态及浏览器控制台错误。