# Content Finder Agent 使用指南

## 快速开始

### 1. 环境准备

```bash
# 进入项目根目录
cd /Users/heyu/work/TZLD/project/Agent

# 安装依赖（如果还没安装）
pip install -r requirements.txt
```

### 2. 配置环境变量

```bash
# 进入 content_finder 目录
cd examples/content_finder

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填入你的 API Key
# 主要需要配置：
# - OPENROUTER_API_KEY: OpenRouter API Key
# - KNOWHUB_API: 知识库服务地址（可选）
```

### 3. 运行示例

#### 示例1：抗日娃娃军内容寻找

```bash
python run.py
```

这会使用默认的 `content_finder.prompt`，执行"孩子军抗日，让人感动。找这样的视频。"的任务。

#### 示例2：养生内容寻找

修改 `run.py` 中的 prompt 路径：

```python
# 将这一行
prompt_path = base_dir / "content_finder.prompt"

# 改为
prompt_path = base_dir / "example_health.prompt"
```

然后运行：

```bash
python run.py
```

### 4. 交互控制

运行过程中，你可以：

- **暂停执行**：输入 `p` 或 `pause`
- **停止执行**：输入 `q` 或 `quit`

暂停后可以：
- 查看当前执行状态
- 插入干预消息
- 查看 GoalTree
- 触发经验总结

### 5. 恢复已有任务

如果任务中断或想继续之前的执行：

```bash
python run.py --trace <trace_id>
```

Trace ID 可以在执行结束时看到，或者在 `.trace/` 目录中查找。

## 工作流程示例

Agent 会按照以下流程工作：

```
1. 理解需求
   ↓
2. 查询内容库（knowledge_search）
   ↓
3. 搜索平台内容（search_posts）
   ↓
4. 分析搜索结果
   ↓
5. 获取搜索建议词（get_search_suggestions）
   ↓
6. 扩展搜索策略
   ↓
7. 使用浏览器工具验证数据（可选）
   ↓
8. 保存有价值的策略（knowledge_save）
   ↓
9. 迭代优化...
```

## 自定义任务

### 方法1：修改 prompt 文件

编辑 `content_finder.prompt` 或创建新的 `.prompt` 文件：

```markdown
---
model: sonnet-4.6
temperature: 0.3
---

$system$
你是一个专业的内容寻找Agent...

$user$
需求："你的自定义需求"
```

### 方法2：通过交互模式插入消息

运行 Agent 后，按 `p` 暂停，然后选择"插入干预消息"，输入新的需求。

## 查看执行结果

### 1. 文本结果

执行结果保存在 `output/result.txt`

### 2. 可视化查看

启动 API Server：

```bash
# 在项目根目录
cd /Users/heyu/work/TZLD/project/Agent
python api_server.py
```

浏览器访问：
```
http://localhost:8000/api/traces
```

可以看到：
- 完整的执行轨迹
- 每一步的工具调用
- GoalTree 结构
- 成本统计

## 可用工具说明

### 搜索工具

1. **search_posts**: 在各平台搜索帖子
   - 支持平台：抖音、小红书、B站、知乎、微博等
   - 返回：标题、内容、点赞数、发布时间等

2. **get_search_suggestions**: 获取搜索建议词
   - 用于扩展搜索关键词
   - 发现相关话题

### 知识管理

1. **knowledge_search**: 搜索知识库
   - 查找相关的搜索策略
   - 学习历史经验

2. **knowledge_save**: 保存知识
   - 保存有效的搜索策略
   - 记录发现的规律

### 浏览器工具

- **browser_navigate_to_url**: 访问网页
- **browser_extract_content**: 提取网页内容
- **browser_search_web**: 网页搜索
- 等等...

## 配置说明

### config.py

```python
RUN_CONFIG = RunConfig(
    model="claude-sonnet-4.5",      # 使用的模型
    temperature=0.3,                 # 温度参数
    max_iterations=1000,             # 最大迭代次数

    knowledge=KnowledgeConfig(
        enable_extraction=True,      # 启用知识提取
        enable_injection=True,       # 启用知识注入
        default_tags={...},          # 默认标签
    )
)
```

## 常见问题

### Q: Agent 执行太慢怎么办？

A: 可以调整配置：
- 减少 `max_iterations`
- 在 prompt 中明确限制搜索范围
- 使用更快的模型

### Q: 如何让 Agent 搜索特定平台？

A: 在 prompt 中明确指定：
```
需求："在抖音平台上找老年人喜欢的养生视频"
```

### Q: 如何查看 Agent 的思考过程？

A:
1. 查看终端输出的 `[Assistant]` 消息
2. 使用 API Server 可视化查看
3. 查看 `.trace/` 目录中的详细记录

### Q: 知识库服务如何启动？

A:
```bash
# 在项目根目录
python knowhub/server.py
```

## 进阶使用

### 1. 添加自定义工具

在 `examples/content_finder/tool/` 目录下创建自定义工具：

```python
from agent.tools import tool, ToolResult

@tool(description="你的工具描述")
async def my_custom_tool(param: str) -> ToolResult:
    # 你的实现
    return ToolResult(output="结果")
```

### 2. 添加领域 Skills

在 `examples/content_finder/skills/` 目录下创建 `.md` 文件：

```markdown
---
name: content-finder-skill
description: 内容寻找领域知识
---

## 搜索策略

- 策略1：...
- 策略2：...
```

### 3. 配置预设 Agent

创建 `presets.json`：

```json
{
  "content_analyzer": {
    "model": "claude-sonnet-4.5",
    "temperature": 0.2,
    "system_prompt": "你是内容分析专家..."
  }
}
```

## 贡献

如果你发现了有效的搜索策略或改进建议，欢迎：
1. 保存到知识库
2. 提交 PR
3. 分享经验

## 许可

遵循项目主许可协议。