# 普通文案人味儿优化标签页设计

## 目标

在现有 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`。这属于服务本功能的局部整理，不改变现有业务行为。