first commit

docs/.vitepress/config.ts

@@ -0,0 +1,58 @@
+import { defineConfig } from "vitepress";
+
+export default defineConfig({
+  title: "AI回评",
+  description: "Halo AI回评插件文档",
+  lang: "zh-CN",
+  themeConfig: {
+    nav: [
+      { text: "指南", link: "/guide/introduction" },
+      { text: "配置", link: "/guide/settings" },
+    ],
+    sidebar: [
+      {
+        text: "开始",
+        items: [
+          { text: "插件介绍", link: "/guide/introduction" },
+          { text: "安装与更新", link: "/guide/installation" },
+        ],
+      },
+      {
+        text: "功能",
+        items: [
+          { text: "自动回复", link: "/guide/auto-reply" },
+          { text: "草稿模式", link: "/guide/draft-mode" },
+          { text: "情感分析", link: "/guide/sentiment" },
+          { text: "过滤规则", link: "/guide/filter" },
+          { text: "手动触发", link: "/guide/manual-trigger" },
+        ],
+      },
+      {
+        text: "配置",
+        items: [
+          { text: "插件设置", link: "/guide/settings" },
+          { text: "AI角色", link: "/guide/persona" },
+          { text: "Prompt模板", link: "/guide/prompt" },
+        ],
+      },
+      {
+        text: "其他",
+        items: [
+          { text: "常见问题", link: "/guide/faq" },
+        ],
+      },
+    ],
+    socialLinks: [
+      {
+        icon: "github",
+        link: "https://github.com/nxxy335/plugin-comment-ai-autopilot",
+      },
+    ],
+    search: {
+      provider: "local",
+    },
+    footer: {
+      message: "基于 GPL-3.0 许可发布",
+    },
+  },
+});

docs/guide/auto-reply.md

@@ -0,0 +1,34 @@
+# 自动回复
+
+自动回复是插件的核心功能，当有新评论发布时，插件会自动触发AI生成回复。
+
+## 工作原理
+
+插件通过 Halo 的 Reconciler 机制监听评论和回复的创建事件：
+
+- **CommentReconciler** — 监听新评论，触发首次AI回复
+- **ReplyReconciler** — 监听新回复，当回复者不是AI角色时，触发对话式AI回复
+
+## 去重机制
+
+为避免重复回复，插件实现了多层去重防护：
+
+1. **内存锁** — 使用 `ConcurrentHashMap` 防止同一评论并发处理
+2. **数据库检查** — 处理前查询是否已存在 `AiCommentReply` 记录
+3. **发布前检查** — 创建 Reply 前再次确认不存在重复
+
+## 历史评论过滤
+
+插件启动时间之前的评论不会触发自动回复，避免安装插件后对大量历史评论批量回复。
+
+## 对话式回复
+
+当评论者回复AI的评论时，插件会自动提取对话上下文（最近5条回复），让AI的回复更连贯自然。
+
+## 配置项
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| 自动回复 | 是否启用自动回复功能 | 开启 |
+| 自动发布 | AI回复是否自动发布，关闭则存为草稿 | 开启 |
+| 最大重试次数 | AI生成失败时的最大重试次数 | 3 |

docs/guide/draft-mode.md

@@ -0,0 +1,24 @@
+# 草稿模式
+
+草稿模式允许AI回复先存为草稿，管理员审核后再发布，适用于对AI回复质量有较高要求的场景。
+
+## 启用草稿模式
+
+在插件设置页面，将 **自动发布** 开关关闭即可启用草稿模式。
+
+## 审核流程
+
+1. 新评论到达后，AI生成回复内容
+2. 回复以草稿状态保存（`approved = false`）
+3. 在 **AI回复日志** 页面，草稿状态的记录会显示审核按钮
+4. 管理员可以：
+   - **审核通过** — 回复立即发布，访客可见
+   - **拒绝** — 删除草稿回复，记录标记为 REJECTED
+
+## 日志页面操作
+
+在AI回复日志页面：
+
+- 草稿记录显示 **审核通过** 和 **拒绝** 按钮
+- 已发布的记录显示正常状态
+- 被拒绝的记录显示 REJECTED 标签

docs/guide/faq.md

@@ -0,0 +1,52 @@
+# 常见问题
+
+## 安装后没有自动回复？
+
+1. 确认插件已启用
+2. 确认 **自动回复** 开关已开启
+3. 确认 AI Foundation 插件已安装并正确配置（如果使用AI Foundation）
+4. 检查文章的 **启用AI回评** 开关是否开启（文章默认开启，页面默认关闭）
+5. 查看插件日志是否有错误信息
+
+## AI回复头像不显示？
+
+1. 确认在插件设置中填写了AI角色邮箱
+2. 邮箱需要在 [Gravatar](https://gravatar.com) 上注册并设置头像
+3. 插件使用 [Cravatar](https://cravatar.cn) 作为Gravatar镜像服务
+
+## 评论没有触发AI回复？
+
+可能的原因：
+
+1. **文章/页面开关关闭** — 检查编辑器中的"启用AI回评"开关
+2. **评论者在黑名单中** — 检查基本设置中的评论者黑名单
+3. **已有AI回复记录** — 同一评论不会重复触发
+4. **历史评论** — 插件启动前的评论不会自动触发，可使用手动触发
+5. **AI生成失败** — 检查AI模型配置和日志
+
+## 如何对历史评论触发AI回复？
+
+1. 进入后台 **评论** 管理页面
+2. 找到目标评论
+3. 点击右侧 **更多（…）** → **触发AI回复**
+
+## 草稿模式的回复在哪里审核？
+
+在插件管理页面的 **AI回复日志** 中，草稿状态的记录会显示"审核通过"和"拒绝"按钮。
+
+## 如何修改AI回复的语气风格？
+
+1. 在插件设置中修改 **AI角色人格提示词**
+2. 或修改 **自定义Prompt模板**
+
+## AI Foundation 插件是必须的吗？
+
+是的，AI Foundation 是本插件的必要依赖。本插件通过 AI Foundation 提供的 `AiModelService` 扩展点调用AI模型，请确保已安装并正确配置 AI Foundation 插件。
+
+## 如何完全禁用某个页面的AI回复？
+
+编辑页面，在元数据区域关闭 **启用AI回评** 开关。页面默认就是关闭的。
+
+## 插件升级后设置丢失了？
+
+插件升级不会丢失设置。如果遇到问题，请检查 ConfigMap 是否正确迁移。

docs/guide/filter.md

@@ -0,0 +1,44 @@
+# 过滤规则
+
+过滤规则控制哪些评论触发AI回复，包括文章/页面级开关和评论者黑名单。
+
+## 文章/页面级开关
+
+插件通过 Halo 的 AnnotationSetting 机制，在文章和页面编辑器的元数据区域添加了 **启用AI回评** 开关。
+
+### 默认行为
+
+| 类型 | 默认状态 |
+|------|---------|
+| 文章（Post） | 默认开启 |
+| 页面（SinglePage） | 默认关闭 |
+
+### 使用方法
+
+1. 编辑文章或页面
+2. 在编辑器侧边栏找到 **元数据** 区域
+3. 找到 **启用AI回评** 开关
+4. 根据需要开启或关闭
+
+::: tip
+新创建的文章默认启用AI回复，新创建的页面默认禁用。你可以在编辑器中随时修改。
+:::
+
+## 评论者黑名单
+
+评论者黑名单功能可以屏蔽指定评论者，使其评论不触发AI回复。
+
+### 配置方法
+
+1. 进入插件设置页面
+2. 在 **基本设置** 中找到 **评论者黑名单**
+3. 输入评论者的显示名称，多个用逗号分隔
+4. 保存设置
+
+### 示例
+
+```
+张三,李四,王五
+```
+
+黑名单中的评论者发布评论时，插件会跳过AI回复，并在日志中记录过滤原因。

docs/guide/installation.md

@@ -0,0 +1,44 @@
+# 安装与更新
+
+## 前置要求
+
+- Halo 2.23+
+- AI Foundation 插件（必须） — 本插件依赖 AI Foundation 提供的AI模型能力，请先安装并配置 AI Foundation
+
+## 安装
+
+### 方式一：从 Release 下载
+
+1. 前往 [GitHub Releases](https://github.com/nxxy335/plugin-comment-ai-autopilot/releases) 下载最新的 `.jar` 文件
+2. 登录 Halo 管理后台
+3. 进入 **插件** → **已安装** → 点击右上角 **安装** 按钮
+4. 选择下载的 `.jar` 文件上传
+5. 安装完成后启用插件
+
+### 方式二：从源码构建
+
+```bash
+# 克隆仓库
+git clone https://github.com/nxxy335/plugin-comment-ai-autopilot.git
+cd plugin-comment-ai-autopilot
+
+# 构建
+./gradlew build -x test
+
+# 构建产物位于 build/libs/ 目录
+```
+
+然后将生成的 `.jar` 文件通过 Halo 后台安装。
+
+## 更新
+
+1. 下载新版本的 `.jar` 文件
+2. 在 Halo 后台 **插件** 页面找到「AI回评」
+3. 点击插件卡片右上角的 **更多** → **更新**
+4. 选择新的 `.jar` 文件上传
+
+## 卸载
+
+1. 在 Halo 后台 **插件** 页面找到「AI回评」
+2. 先停用插件
+3. 点击 **更多** → **卸载**

docs/guide/introduction.md

@@ -0,0 +1,40 @@
+# 插件介绍
+
+AI回评（Comment AI Autopilot）是一个 Halo 博客系统的插件，能够自动为博客评论生成AI回复。
+
+## 核心功能
+
+- **自动回复** — 监听新评论，自动调用AI生成回复，支持多轮对话上下文
+- **情感分析** — 分析评论情感倾向（正面/中性/负面），根据情感调整回复语气
+- **草稿模式** — AI回复先存为草稿，管理员审核后再发布
+- **文章/页面级开关** — 在文章编辑器中直接控制是否启用AI回复，文章默认开启，页面默认关闭
+- **评论者黑名单** — 屏蔽指定评论者，不触发AI回复
+- **手动触发** — 在评论管理页面对历史评论手动触发AI回复
+- **AI角色** — 自定义AI回复者的昵称、人格提示词和Gravatar头像
+- **安全审核** — AI生成的内容经过安全审核，不合规内容自动拒绝
+- **AI Foundation 集成** — 必须安装 Halo AI Foundation 插件，使用其提供的AI模型能力
+
+## 工作流程
+
+```
+新评论 → 过滤检查 → 情感分析 → 构建Prompt → AI生成 → 安全审核 → 发布/草稿
+```
+
+1. **新评论到达** — Reconciler 监听到新评论创建事件
+2. **过滤检查** — 检查文章/页面是否启用AI回复、评论者是否在黑名单中
+3. **情感分析** — 调用AI分析评论情感倾向
+4. **构建Prompt** — 结合AI角色人格、情感提示、文章内容、评论上下文构建Prompt
+5. **AI生成** — 调用AI模型生成回复内容
+6. **安全审核** — 对生成内容进行安全审核
+7. **发布/草稿** — 根据设置自动发布或存为草稿等待审核
+
+## 前置要求
+
+- Halo 2.23+
+- AI Foundation 插件（必须） — 本插件依赖 AI Foundation 提供的AI模型能力
+
+## 技术栈
+
+- **后端**：Java + Spring WebFlux + Reactive
+- **前端**：Vue 3 + @halo-dev/components
+- **AI**：支持 AI Foundation 插件集成

docs/guide/manual-trigger.md

@@ -0,0 +1,39 @@
+# 手动触发
+
+手动触发功能允许对历史评论手动触发AI回复，适用于以下场景：
+
+- 安装插件前已存在的评论
+- 自动回复被过滤规则跳过的评论
+- AI生成失败需要重试的评论
+
+## 使用方法
+
+1. 进入 Halo 后台 **评论** 管理页面
+2. 找到需要触发AI回复的评论
+3. 点击评论右侧的 **更多（…）** 按钮
+4. 在下拉菜单中选择 **触发AI回复**
+5. 在确认对话框中点击 **确定**
+
+::: warning
+如果该评论已有AI回复记录，触发将返回冲突提示，不会重复生成。
+:::
+
+## API 接口
+
+插件提供了以下手动触发API：
+
+### 触发评论回复
+
+```
+POST /apis/console.api.comment-ai-autopilot.nxxy335.top/v1alpha1/comments/{commentName}/trigger
+```
+
+对指定评论触发首次AI回复。
+
+### 触发对话回复
+
+```
+POST /apis/console.api.comment-ai-autopilot.nxxy335.top/v1alpha1/replies/{replyName}/trigger-conversation
+```
+
+对指定回复触发对话式AI回复。

docs/guide/persona.md

@@ -0,0 +1,39 @@
+# AI角色
+
+AI角色定义了回复评论的虚拟身份，包括昵称、人格和头像。
+
+## 角色配置
+
+### 昵称
+
+AI回复者的显示名称，默认为「小回」。修改后新回复将使用新昵称，已有回复不受影响。
+
+### 人格提示词
+
+人格提示词定义了AI角色的性格和回复风格，是影响回复质量的关键配置。
+
+**默认提示词：**
+
+> 你是「小回」，一个友善的评论者。你的回复简洁自然，像朋友聊天一样。简短的评论就简短回复，有深度的讨论才展开回应。不要长篇大论，不要复述文章内容。
+
+**自定义示例：**
+
+```
+你是「小回」，一个博学多才的评论者。你的回复风格：
+- 对技术问题给出专业见解
+- 对生活感悟表达共鸣
+- 适当引用相关知识点
+- 保持谦逊友好的态度
+```
+
+### 邮箱与头像
+
+填写邮箱后，AI回复者的头像将通过 Gravatar 服务自动生成：
+
+1. 插件根据邮箱生成 SHA-256 哈希
+2. 构造 Gravatar URL：`https://cn.cravatar.com/avatar/{hash}`
+3. 头像URL存储在评论的 `owner.annotations["avatar"]` 中
+
+::: warning
+如果不填写邮箱，AI回复者将使用 Halo 默认头像。
+:::

docs/guide/prompt.md

@@ -0,0 +1,61 @@
+# Prompt模板
+
+Prompt模板控制AI生成回复时的完整提示词结构。
+
+## 默认模板
+
+```
+{{persona_prompt}}
+
+{{safety_prompt}}
+
+请回复以下评论。注意：
+- 回复长度应与评论长度匹配，简短问候简短回复
+- 不要复述或总结文章内容
+- 自然对话，不要写小作文
+- 只有评论涉及具体内容时才针对性回应
+
+文章（仅供理解上下文，不要复述）：
+{{article}}
+
+评论：
+{{comment}}
+```
+
+## 模板变量
+
+| 变量 | 说明 | 注入时机 |
+|------|------|---------|
+| `{{persona_prompt}}` | AI角色人格提示词 | 始终注入 |
+| `{{safety_prompt}}` | 安全规范提示词 | 始终注入 |
+| `{{sentiment_prompt}}` | 情感语气提示词 | 情感分析后自动注入，不在模板中显式使用 |
+| `{{article}}` | 文章/页面内容 | 始终注入 |
+| `{{comment}}` | 评论内容 | 始终注入 |
+| `{{conversation}}` | 对话上下文 | 多轮对话时注入 |
+
+## 情感提示
+
+情感提示由插件根据情感分析结果自动注入到Prompt中，不需要在模板中手动添加：
+
+- **正面** → "评论者情绪积极友好，请用热情友好的语气回复，表达感谢和共鸣。"
+- **负面** → "评论者情绪偏消极或不满，请用理性温和的语气回复，避免激化矛盾，适当表示理解。"
+- **中性** → 不注入额外提示
+
+## 安全提示
+
+安全提示词由插件内置，确保AI生成的内容符合规范：
+
+- 不生成违法、有害、歧视性内容
+- 不泄露个人隐私信息
+- 不生成虚假信息
+- 回复内容与评论相关
+
+## 自定义建议
+
+自定义Prompt模板时，建议：
+
+1. 保留 `{{persona_prompt}}` 和 `{{safety_prompt}}` 变量
+2. 保留 `{{article}}` 和 `{{comment}}` 变量
+3. 在变量之间添加清晰的分隔和指令
+4. 避免让AI复述文章内容
+5. 控制回复长度和风格

docs/guide/sentiment.md

@@ -0,0 +1,31 @@
+# 情感分析
+
+情感分析功能会自动分析评论的情感倾向，并根据分析结果调整AI回复的语气。
+
+## 情感分类
+
+| 分类 | 说明 | AI回复语气 |
+|------|------|-----------|
+| 正面 | 评论情绪积极、友好、感谢 | 热情友好，表达感谢和共鸣 |
+| 中性 | 评论情绪平淡、普通提问 | 正常语气回复，不加额外提示 |
+| 负面 | 评论情绪偏消极、不满、批评 | 理性温和，避免激化矛盾 |
+
+## 工作原理
+
+1. 评论通过过滤检查后，调用AI对评论内容进行情感分析
+2. AI返回情感分类结果（POSITIVE / NEUTRAL / NEGATIVE）
+3. 如果情感分析失败（如AI不可用），默认降级为 NEUTRAL
+4. 情感结果传入 PromptBuilder，在生成Prompt时注入对应的语气提示
+5. 情感结果同时记录在 `AiCommentReply` 的 `sentiment` 字段中
+
+## 日志展示
+
+在AI回复日志页面，每条记录会显示情感标签：
+
+- 🟢 **正面** — 绿色标签
+- ⚪ **中性** — 灰色标签
+- 🔴 **负面** — 红色标签
+
+## 性能影响
+
+情感分析会额外调用一次AI，如果对性能有顾虑，可以在代码中禁用此功能。

docs/guide/settings.md

@@ -0,0 +1,55 @@
+# 插件设置
+
+插件设置页面位于 **AI回评** → **插件设置**，包含以下配置组：
+
+## 基本设置
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| 自动回复 | 是否启用自动回复功能 | 开启 |
+| 自动发布 | AI回复是否自动发布 | 开启 |
+| 最大重试次数 | AI生成失败时的最大重试次数 | 3 |
+| 评论者黑名单 | 不触发AI回复的评论者显示名称，逗号分隔 | 空 |
+
+## AI角色设置
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| AI角色昵称 | AI回复者的显示名称 | 小回 |
+| AI角色人格提示词 | 定义AI角色的人格和回复风格 | 见下方 |
+| AI角色邮箱 | 用于Gravatar头像服务展示头像 | 空 |
+
+默认人格提示词：
+
+> 你是「小回」，一个友善的评论者。你的回复简洁自然，像朋友聊天一样。简短的评论就简短回复，有深度的讨论才展开回应。不要长篇大论，不要复述文章内容。
+
+::: tip Gravatar头像
+填写邮箱后，AI回复者的头像将通过 [Gravatar](https://gravatar.com) 服务自动生成。如果不填写邮箱，将使用默认头像。
+:::
+
+## 模型设置
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| AI模型名称 | 留空使用AI Foundation默认模型，填写AiModel资源名称可指定模型 | 空 |
+
+::: warning
+模型设置需要先安装 AI Foundation 插件。AI Foundation 是本插件的必要依赖，请确保已正确安装和配置。
+:::
+
+## Prompt设置
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| 自定义Prompt模板 | AI生成回复时使用的Prompt模板 | 见下方 |
+
+### 模板变量
+
+| 变量 | 说明 |
+|------|------|
+| `{{persona_prompt}}` | AI角色人格提示词 |
+| `{{safety_prompt}}` | 安全规范提示词 |
+| `{{sentiment_prompt}}` | 情感语气提示词（自动注入） |
+| `{{article}}` | 文章内容 |
+| `{{comment}}` | 评论内容 |
+| `{{conversation}}` | 对话上下文（多轮对话时） |

docs/index.md

@@ -0,0 +1,25 @@
+---
+layout: home
+
+hero:
+  name: AI回评
+  text: Halo 智能评论回复插件
+  tagline: 自动分析评论情感，生成自然、贴切的AI回复
+  actions:
+    - theme: brand
+      text: 开始使用
+      link: /guide/introduction
+    - theme: alt
+      text: 配置指南
+      link: /guide/settings
+
+features:
+  - title: 自动回复
+    details: 监听新评论，自动调用AI生成回复，支持对话式上下文
+  - title: 情感分析
+    details: 分析评论情感倾向，根据正面/中性/负面调整回复语气
+  - title: 草稿模式
+    details: AI回复先存为草稿，管理员审核后再发布
+  - title: 灵活过滤
+    details: 文章/页面级开关控制，评论者黑名单
+---

docs/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "docs",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "docs:dev": "vitepress dev",
+    "docs:build": "vitepress build",
+    "docs:preview": "vitepress preview"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "devDependencies": {
+    "vitepress": "^1.6.4"
+  }
+}