新增普通文案优化设计

2026-06-25 14:46:25 +08:00
parent b453800494
commit c47036d28d
1 changed files with 265 additions and 0 deletions
@@ -0,0 +1,265 @@
+# 普通文案人味儿优化标签页设计
+
+## 目标
+
+在现有 GEO 智能文章优化器中增加一个简化版标签页，用于普通文案的轻量优化。用户粘贴一段文案后，可以直接得到更自然、更少 AI 味的版本，同时看到每一处改动说明和改后检查结果。
+
+这个功能参考 `github.com/orange2ai/renwei-writing` 的写作方法论，但不把该仓库作为运行时依赖，也不复制其完整 skill 内容到本仓库。实现时只吸收核心原则：少动、保留作者手迹、不新增事实或场景、不写过度金句、改后检查被改动句子的 AI 味痕迹。
+
+## 现状
+
+当前首页 `src/app/page.tsx` 是单页工作台，包含：
+
+- 文章输入。
+- 候选事实卡确认。
+- GEO 文章优化。
+- 质量报告。
+- 发布表现校准。
+
+这条主流程适合 GEO 文章，但对普通文案过重。普通文案优化不需要事实卡、任务 ID、QA 门禁、导出文件或发布表现记录。
+
+## 方案
+
+在首页顶部增加应用级标签：
+
+- `GEO 文章优化`：保持现有流程不变，仍作为默认标签。
+- `普通文案优化`：新增独立小工具。
+
+普通文案优化采用轻量 API，不落库、不创建 job、不生成导出文件。它复用现有 API 访问密钥校验和 LLM 客户端边界，保持本地与线上部署模型一致。
+
+## 用户流程
+
+```mermaid
+flowchart TD
+  A["打开首页"] --> B["切换到普通文案优化"]
+  B --> C["粘贴原始文案"]
+  C --> D["选择修改强度和优化目标"]
+  D --> E["点击优化文案"]
+  E --> F["后端调用 LLM 生成结构化结果"]
+  F --> G["展示优化后文案"]
+  G --> H["展示逐处改动说明"]
+  G --> I["展示 AI 味检查"]
+  G --> J["复制结果"]
+```
+
+## 页面设计
+
+### 顶部标签
+
+标签放在标题区域下方或工作区上方，使用普通按钮样式即可。切换标签只影响页面内容，不改变访问密钥输入框的位置。
+
+要求：
+
+- 默认展示 `GEO 文章优化`。
+- 切到 `普通文案优化` 后隐藏现有主流程面板，显示简化工具。
+- 切回 `GEO 文章优化` 时保留原来输入状态。
+
+### 普通文案优化工具
+
+采用双栏布局，移动端降为单栏。
+
+左侧输入区：
+
+- `原始文案`：必填 textarea。
+- `优化目标`：普通文本输入，默认值为 `保留原意，减少 AI 味`。
+- `修改强度`：select，选项为 `轻微整理`、`适度润色`、`更口语自然`，默认 `轻微整理`。
+- `补充要求`：可选 textarea，例如不要营销腔、保留口语、适合朋友圈等。
+- `优化文案` 按钮。
+
+右侧结果区：
+
+- `优化后文案`：显示结构化返回中的 `optimized_text`。
+- `复制结果` 按钮。
+- `改动说明`：逐条列出原句、改后句、原因和是否可还原。
+- `AI 味检查`：列出检查项状态、证据和建议。
+
+空状态文案保持克制，例如 `优化结果会显示在这里。`
+
+## API 设计
+
+新增路由：
+
+```text
+POST /api/copy/renwei-optimize
+```
+
+请求头：
+
+- 继续使用现有 `x-api-key` 访问密钥规则。
+
+请求体：
+
+```json
+{
+  "source_text": "原始文案",
+  "goal": "保留原意，减少 AI 味",
+  "intensity": "light",
+  "user_instructions": "保留作者语气"
+}
+```
+
+字段规则：
+
+- `source_text` 必填，去掉首尾空白后不能为空。
+- `goal` 可选，空值时使用默认目标。
+- `intensity` 只能是 `light`、`medium`、`conversational`。
+- `user_instructions` 可选。
+
+响应体：
+
+```json
+{
+  "result": {
+    "optimized_text": "优化后的文案",
+    "change_notes": [
+      {
+        "original": "原句",
+        "revised": "改后句",
+        "reason": "改动原因",
+        "confidence": "confident",
+        "revertible": false
+      }
+    ],
+    "ai_taste_checks": [
+      {
+        "rule_id": "promotion_tone",
+        "status": "pass",
+        "evidence": "未发现宣传腔新增",
+        "suggestion": ""
+      }
+    ],
+    "warnings": []
+  }
+}
+```
+
+## 数据模型
+
+新增前后端共享类型：
+
+```ts
+type CopyOptimizationIntensity = "light" | "medium" | "conversational";
+
+interface CopyOptimizationRequest {
+  source_text: string;
+  goal?: string;
+  intensity: CopyOptimizationIntensity;
+  user_instructions?: string;
+}
+
+interface CopyChangeNote {
+  original: string;
+  revised: string;
+  reason: string;
+  confidence: "confident" | "uncertain";
+  revertible: boolean;
+}
+
+interface CopyAiTasteCheck {
+  rule_id:
+    | "meaning_inflation"
+    | "promotion_tone"
+    | "formulaic_sentence"
+    | "format_trace"
+    | "chat_trace"
+    | "filler_hedging";
+  status: "pass" | "warn";
+  evidence: string;
+  suggestion: string;
+}
+
+interface CopyOptimizationResult {
+  optimized_text: string;
+  change_notes: CopyChangeNote[];
+  ai_taste_checks: CopyAiTasteCheck[];
+  warnings: string[];
+}
+```
+
+不新增数据库表，不写入 D1/SQLite/R2。
+
+## Prompt 设计
+
+新增 prompt builder，例如：
+
+```text
+buildRenweiCopyOptimizationPrompt(input)
+```
+
+系统提示目标：
+
+- 你是中文普通文案编辑，不是营销代笔工具。
+- 只改真正打绊的地方，默认少动。
+- 保留作者的位置、语气、口头习惯和可识别手迹。
+- 不凭空新增时间、地点、数字、案例、情绪或场景。
+- 不把普通句子改成宣传腔、排比、格言、万能展望或过度金句。
+- 拿不准时白描，不拔高。
+- 改后只检查被改动句子是否引入 AI 味。
+- 必须逐处说明改了什么、为什么改。
+- 拿不准的改动标记为 `confidence: "uncertain"` 和 `revertible: true`。
+- 返回 JSON，不返回 Markdown 代码块或解释性闲聊。
+
+强度解释：
+
+- `light`：尽量只修顺病句、错别字、明显卡顿。
+- `medium`：允许调整句序和连接，但不改变作者表达的粗糙感。
+- `conversational`：让口吻更像真人说话，但不凭空增加表演性口语。
+
+## 错误处理
+
+- 缺少或错误访问密钥：沿用现有 `401` 行为。
+- `source_text` 为空：返回 `400` 和中文错误 `请输入需要优化的文案`。
+- LLM 未配置或调用失败：返回明确错误，不静默生成伪结果。
+- LLM 返回结构不合法：通过现有结构化校验路径报错，提示 `文案优化结果格式不正确，请重试`。
+
+## 测试计划
+
+单元测试：
+
+- Prompt 包含少动、保留作者手迹、不新增事实、逐处说明、AI 味检查等关键规则。
+- 请求体验证会拒绝空文案和非法强度。
+- LLM 结果校验能接受合法结构，拒绝缺少 `optimized_text` 或数组字段类型错误的结果。
+
+API 测试：
+
+- 未提供访问密钥时返回 `401`。
+- 空文案返回 `400`。
+- mock LLM 返回合法结果时，API 返回 `result.optimized_text`、`change_notes` 和 `ai_taste_checks`。
+- LLM 抛错时错误向前端显式暴露。
+
+E2E 测试：
+
+- 首页默认仍显示 GEO 文章优化。
+- 用户切换到 `普通文案优化`。
+- 填入文案并点击 `优化文案`。
+- 页面显示 `优化后文案`、`改动说明`、`AI 味检查`。
+
+验证命令：
+
+```bash
+npm run lint
+npm test
+npm run build
+```
+
+## 不做范围
+
+- 不做历史记录。
+- 不做批量文案。
+- 不生成 Markdown、DOCX 或 QA JSON 导出。
+- 不接入发布表现校准。
+- 不把普通文案优化结果写入数据库。
+- 不自动安装或 vendor `renwei-writing` 仓库。
+- 不复制参考 skill 的完整文本到本项目。
+- 不做多轮对话式改稿。
+
+## 实现边界
+
+优先复用现有结构：
+
+- API 访问控制复用 `src/lib/api/auth.ts`。
+- LLM 调用复用 `src/lib/llm/client.ts` 的结构化 JSON 路径。
+- Prompt 与现有 `src/lib/llm/prompts.ts` 同层维护。
+- 页面组件放在 `src/components`，避免继续膨胀 `src/app/page.tsx`。
+
+为了保持首页可维护，实施时建议顺手把现有 GEO 主流程抽成一个组件，例如 `GeoArticleOptimizerWorkspace`，再新增 `RenweiCopyOptimizerPanel`。这属于服务本功能的局部整理，不改变现有业务行为。