# 项目现状与改进方向

---

## 一、系统终极目标

**根据人设和模式，最终选出好的选题**

### 什么是"好的选题"？

一个好的选题需要满足以下标准：

1. **符合人设**（匹配度 > 0.7）
   - 与人设的实质维度、形式维度、意图维度高度匹配
   - 不是热点但不适合这个人设

2. **有市场热度**（外部验证得分 > 0.6）
   - 当前有用户关注和讨论
   - 不是库里有数据但已经过时的选题

3. **适合当前时间点**（时间性得分 > 0.7）
   - 符合当前季节、节日、公共事件
   - 不是随时都能发的常青内容（除非人设需要）

4. **有数据支撑**（来源可追溯）
   - 来自爆款库的 pattern（有历史成功案例）
   - OR 来自外部搜索验证（有当前热度证据）
   - 不是 AI 自行推测的选题

5. **推导路径清晰**（可解释、可复现）
   - 能说清楚"为什么选这个"
   - 能展示完整的推导过程
   - 能复现选题生成逻辑

### 综合评分公式

```
好选题综合得分 = 人设匹配度 × 0.4 + 市场热度 × 0.3 + 时间性 × 0.2 + 数据支撑度 × 0.1

其中：
- 人设匹配度 = (实质维度得分 × 0.4 + 形式维度得分 × 0.3 + 意图维度得分 × 0.3)
- 市场热度 = (内部库支持度 × 0.6 + 外部验证热度 × 0.4)
- 时间性 = 当前时间与选题的时间相关性得分
- 数据支撑度 = 是否有明确的来源证据（0 或 1）

阈值：综合得分 ≥ 0.75 才推荐
```

---

## 二、实现目标的核心能力要求

为了"选出好的选题"，系统需要实现以下核心能力：

### 1. 路径探索机制
**边探索边比较，比较后收敛，再探索再收敛**
- 多轮迭代而非一次性执行
- 每轮评估路径有效性并淘汰低效路径
- 基于比较结果调整探索方向

### 2. 时间性管理
识别和利用不同时间维度的创作机会：
- **创作可能性**：选题在当下的创作价值
- **创作方法**：不同时期适用的内容形式
- **公共事件**：可蹭的热点事件
- **周期性**：年度/季节性重复选题（如春节、高考）

### 3. 逻辑计算推导封装
把判断逻辑从 AI 黑盒中提取出来，形成可复用、可调优的计算模块

### 4. 内外双重判断
- **内部库判断**：基于爆款库数据和权重
- **外部验证**：到小红书/微博/知乎等平台验证热度
- 两者结合综合判断

### 5. 多样性探索
通过多种方式增加输出多样性：
- 测试不同模型的输出效果
- 引入票圈（朋友圈/社群）数据
- 扩展数据库来源
- 尝试不同 Agent 策略
- 自动化探索外部数据（trick 自动化 → agent 化）

---

## 三、当前系统现状

### 输入
人设画像描述（文本格式）

### 工作流程

基于 `PRD/create_process.md` 定义的流程：

```
步骤1：灵感生成，路径游走探索
   ├─ 库内路径：从 Pattern 库/案例库检索
   ├─ 外搜路径：使用外部热点搜索工具（MCP）
   └─ 模型补充路径：库与外搜无法支持时启用

步骤2：灵感与人设匹配度分析
   逐个分析灵感是否与人设匹配

步骤3：选题生成
   基于匹配的灵感 + 关联 pattern → 输出选题

步骤4：反馈沉淀与自我总结
   整合用户反馈与自动评估结论
```

### 已实现能力

**数据接入**：
- `tool/topic_search.py` 已接入爆款库 API（`http://192.168.81.89:8000/search`）
- 当前实现：根据关键词检索，返回最多 5 条结果，取第一条（第 37、95 行）

**执行控制**：
- `run.py` 实现交互式执行（第 324-445 行）
- 支持运行时暂停（`pause` 命令）、停止（`quit` 命令）
- 支持从已有 trace 恢复执行（`--trace` 参数，第 293-299 行）

**知识管理**：
- `config.py` 配置了知识沉淀框架（第 22-40 行）
- `enable_extraction=True`：压缩时提取
- `enable_completion_extraction=True`：任务完成后提取
- `enable_injection=True`：切换 goal 时自动注入

**模型配置**：
- `config.py` 第 14 行：`model="claude-sonnet-4.5"`
- `presets.json` 定义了默认 Agent，包含 `core`, `planning`, `research`, `browser`, `topic_search` 技能（第 5-10 行）

### 输出
选题结果保存至 `output_1/result.txt`，并生成 HTML 可视化报告

---

## 四、目标与现状的差距分析

### 差距 1：缺少路径比较和收敛机制

**代码证据**：

`PRD/create_process.md` 第 17-29 行定义了三条路径的探索方式，第 34 行直接进入"灵感与人设匹配度分析"，中间没有路径比较步骤。

**现状描述**：
- 三条路径并行执行后直接使用结果
- 没有对路径质量进行评估的代码模块
- 没有淘汰低效路径的逻辑
- 工作流程为单轮执行，不支持"第 2 轮探索"

**与目标的差距**：
目标要求"边探索边比较，比较后收敛，再探索再收敛"，但当前流程是"一次探索 → 直接用结果"

---

### 差距 2：缺少时间维度能力

**代码证据**：

`tool/topic_search.py` 第 62-71 行定义的工具函数：
```python
async def topic_search(keywords: List[str]) -> ToolResult:
    """
    根据关键词检索数据库中已有帖子的选题

    Args:
        keywords: 关键词列表
    """
```

参数只有 `keywords`，没有时间相关参数。

第 22-33 行的 API 调用：
```python
payload = {"keywords": keywords}
```

**现状描述**：
- 工具只支持关键词检索
- API payload 中没有时间范围、事件类型、周期性等参数
- 无法筛选"最近 7 天"、"周期性"、"公共事件"等时间维度数据

**与目标的差距**：
目标要求识别时间性（创作可能性/创作方法/公共事件/周期性），但当前系统不支持时间维度查询

---

### 差距 3：计算逻辑在 AI 推理过程中

**代码证据**：

`run.py` 第 166-208 行 `_apply_prompt_placeholders` 函数将 PRD 文件内容注入 prompt：
```python
system_md_path = base_dir / "PRD" / "system.md"
system_content = system_md_path.read_text(encoding="utf-8")
prompt._messages["system"] = prompt._messages["system"].replace("{system}", system_content)
```

`PRD/create_process.md` 第 34 行要求"逐个分析灵感，是否与人设匹配，展示分析过程"，但这是通过 prompt 让 AI 执行，没有独立的计算模块。

**现状描述**：
- 匹配度计算、路径评估等逻辑通过 prompt 让 LLM 自行判断
- 没有独立的 Python 计算模块（如 `MatchScoreCalculator` 类）
- 判断过程在 AI 的推理过程中，无法独立调用或调优

**与目标的差距**：
目标要求逻辑计算推导封装为可复用模块，但当前逻辑耦合在 AI 推理过程中

---

### 差距 4：只使用内部库数据

**代码证据**：

`PRD/create_process.md` 第 24 行定义了"外搜路径：使用外部热点搜索工具（MCP）"，但在 `tool/` 目录下只有 `topic_search.py` 一个工具文件，该工具仅调用内部 API（`http://192.168.81.89:8000`）。

`presets.json` 第 9 行配置了 `"browser"` 技能，但在 `run.py` 中没有找到调用外部搜索的代码。

**现状描述**：
- 仅实现了内部爆款库检索（`topic_search` 工具）
- 外部搜索工具在配置中定义但未实际调用
- 没有"内部得分 × 权重 + 外部得分 × 权重"的综合判断逻辑
- 选题生成后不验证外部热度

**与目标的差距**：
目标要求"内部库权重 + 外部搜索验证"双重判断，但当前只使用内部库数据

---

### 差距 5：单一模型配置

**代码证据**：

`config.py` 第 14 行：
```python
model="claude-sonnet-4.5"
```

`run.py` 第 260-263 行：
```python
model_from_config = RUN_CONFIG.model
default_model = f"anthropic/{model_from_config}" if "/" not in model_from_config else model_from_config
model = model_from_prompt or default_model
```

**现状描述**：
- 配置文件中写死单一模型
- 没有多模型对比的代码逻辑
- 数据源仅有爆款库 API，没有票圈、评论区等其他数据源
- 没有自动化测试和对比机制

**与目标的差距**：
目标要求多样性（测模型/票圈/库/agent/trick 自动化），但当前系统为单一模型和数据源

---

## 五、改进方向

### 方向 1：建立多轮探索机制

**要实现的功能**：
"探索 → 比较 → 收敛 → 再探索"的迭代流程

**需要增加的模块**：
1. 路径评分模块（`agent/core/path_evaluator.py`）
   - 对每条路径的结果打分（灵感数量、匹配度、新颖性）
   - 输出各路径的质量排序

2. 收敛决策模块（`agent/core/path_filter.py`）
   - 设定质量阈值
   - 淘汰低分路径
   - 返回保留的路径列表

3. 修改工作流程（`PRD/create_process.md`）
   - 在步骤 1 和步骤 2 之间增加"路径比较与收敛"
   - 增加"第 2 轮探索"步骤
   - 定义迭代终止条件

**验证方式**：
执行后能在输出中看到：
- 各路径的评分（如：库内路径 0.8，外搜路径 0.3，模型补充 0.5）
- 收敛决策（如：淘汰得分 < 0.5 的路径）
- 第 2 轮探索结果

---

### 方向 2：增加时间性能力

**要实现的功能**：
支持时间维度的选题检索和判断

**需要修改的模块**：
1. 扩展 `tool/topic_search.py`
   - 增加参数：`time_range`（如 "recent_7d", "recent_30d", "all"）
   - 增加参数：`event_type`（如 "public_event", "evergreen"）
   - 增加参数：`recurrence`（如 "annual", "seasonal", "one_time"）
   - 修改 API payload 传递这些参数

2. 后端 API 改造
   - 爆款库需要支持时间范围查询
   - 数据库需要增加事件类型和周期性字段

**验证方式**：
能成功调用：
```python
topic_search(
    keywords=["养生"],
    time_range="recent_7d",
    event_type="public_event"
)
```

---

### 方向 3：封装计算逻辑

**要实现的功能**：
把判断逻辑从 prompt 中提取为独立 Python 模块

**需要增加的模块**：
1. 匹配度计算器（`agent/core/match_calculator.py`）
   ```python
   class PersonaMatchCalculator:
       def __init__(self, weights: dict):
           self.weights = weights

       def calculate(self, persona: dict, inspiration: dict) -> float:
           # 计算实质维度得分
           # 计算形式维度得分
           # 计算意图维度得分
           # 加权求和
           return score
   ```

2. 路径比较器（`agent/core/path_comparator.py`）
   ```python
   class PathComparator:
       def score_path(self, path_result: dict) -> float:
           # 评估路径质量
           return score

       def rank_paths(self, all_paths: list) -> list:
           # 排序路径
           return sorted_paths
   ```

**验证方式**：
- 能独立调用计算模块
- 输出时展示计算过程和公式
- 修改权重配置后立即生效

---

### 方向 4：建立内外双重判断

**要实现的功能**：
在内部库判断基础上增加外部热度验证

**需要增加的模块**：
1. 外部热度验证工具（`tool/external_heat_check.py`）
   ```python
   @tool
   async def check_external_heat(
       topic: str,
       platforms: List[str] = ["xiaohongshu", "weibo", "zhihu"]
   ) -> ToolResult:
       # 到各平台搜索关键词
       # 返回：帖子数、互动量、最新讨论时间
       return heat_score
   ```

2. 综合判断模块（`agent/core/综合评分.py`）
   ```python
   class CombinedScorer:
       def calculate(self, internal_score, external_score):
           return internal_score * 0.6 + external_score * 0.4
   ```

3. 修改工作流程
   - 在步骤 3"选题生成"后增加外部验证步骤
   - 输出时展示内部和外部数据

**验证方式**：
选题输出包含：
- 内部库数据（如：该 pattern 历史成功率 80%）
- 外部热度数据（如：小红书近 7 天 1200 条相关帖子）
- 综合得分

---

### 方向 5：增加多样性

**要实现的功能**：
支持多模型对比和多数据源

**需要增加的模块**：
1. 多模型对比脚本（`tools/multi_model_runner.py`）
   ```python
   async def compare_models(persona, models):
       results = {}
       for model in models:
           results[model] = await run_with_model(persona, model)
       return comparison_report
   ```

2. 扩展数据源配置（`config.py`）
   ```python
   DATA_SOURCES = {
       "pattern_library": "http://192.168.81.89:8000",
       "moments": "待配置",
       "comments": "待配置",
   }
   ```

3. 自动化测试流程（`tests/run_batch_test.py`）
   - 准备标准测试用例（`tests/test_cases.json`）
   - 批量执行不同配置
   - 生成对比报告（`tests/results/comparison.html`）

**验证方式**：
能看到多模型对比报告，包含：
- Claude 生成的 5 个选题
- GPT 生成的 5 个选题
- DeepSeek 生成的 5 个选题
- 差异分析

---

## 六、总结

**系统终极目标**：根据人设和模式，选出好的选题（综合得分 ≥ 0.75）

**当前状态**：
- 已实现人设到选题的基础流程
- 已接入内部爆款库 API
- 支持交互式执行和知识沉淀框架
- 单一模型、单一数据源、单轮执行

**为什么现在选不出"好的选题"**（主要差距）：
1. 工作流程为单轮执行，缺少路径比较和收敛机制 → 无法找到最优选题
2. 工具只支持关键词检索，不支持时间维度查询 → 选题可能不适合当前时间点
3. 计算逻辑通过 prompt 让 AI 执行，没有独立的计算模块 → 评分不透明、无法调优
4. 只使用内部库数据，外部搜索未实际调用 → 无法验证市场热度
5. 单一模型配置，无多模型对比能力 → 选题质量无法对比优化

**如何才能选出"好的选题"**（改进优先级）：
1. **P0**：建立路径比较和收敛机制（方向 1）
2. **P1**：增加时间性能力（方向 2）+ 建立内外双重判断（方向 4）
3. **P2**：封装计算逻辑（方向 3）+ 增加多样性（方向 5）