# 项目开发指南

## PRD拆解结构

**PRD = 组件 + 工作流 + 数据结构**

1. **组件** (Components) - 实现具体业务功能
2. **工作流** (Workflow) - 编排组件执行顺序和流程逻辑  
3. **数据结构** (Data Structures) - 定义状态格式和数据传递规范

## 实现原则

**优先复用，其次修改，最后完全新增**

1. **优先复用** - 已有组件完全符合 → 直接复用 (import)
2. **其次修改** - 已有组件部分符合 → Copy并修改
3. **最后完全新增** - 没有合适组件 → 从Base组件新建文件

**重要提醒**: 判断组件是否符合需求，需要查看具体代码实现，而不仅仅是组件名称

## 开发约束

- **面向需求**：一切以PRD需求为准，已有的组件和工作流仅供参考

## 组件架构设计原则

### Agent vs Tool/Function 选择标准

**Agent组件特征**:
- 任务类型: 不确定性任务
- 核心能力: LLM智能能力 (内置多模态理解，无需额外工具支持)
- 处理内容: 推理、多模态理解、语义分析、语义对比、内容生成、模式识别、创意分析
- 依赖关系: 依赖LLM模型

*注：Agent 自身有多模态的能力，无需额外的tool支持*

**Tool/Function组件特征**:
- 任务类型: 确定性任务
- 核心能力: 数据处理
- 处理内容: 数值计算、数据转换、格式化、排序、统计、API调用、文件操作等代码能简单实现的任务
- 依赖关系: 无LLM依赖

### Tool vs Function 选择标准

**唯一区别：是否可以被Agent调用**

**Tool组件**:
- Agent调用: ✅ 可以被Agent调用
- 技术实现: `@tool`装饰器或继承`BaseTool`

**Function组件**:
- Agent调用: ❌ 不能被Agent调用  
- 技术实现: 普通函数或继承`BaseFunction`

*注：除了Agent调用能力外，Tool和Function在功能上没有本质区别*

## 开发建议

1. **需要LLM能力** → Agent
2. **需要Agent调用** → Tool  
3. **其他情况** → Function

**架构原则**: 非必要情况下，组件以Agent为主

## 现有组件清单

### Agent组件 (15个)

**agents/base.py** - BaseComponent/BaseAgent/BaseLLMAgent/BaseReactAgent/BaseGraphAgent
- 功能: Agent基础抽象类，提供四种Agent实现模式
- 核心类:
  - BaseComponent: 最基础的组件抽象，定义初始化和状态管理
  - BaseAgent: Agent通用接口，支持工具绑定和模型切换
  - BaseLLMAgent: 基于LLM的单轮对话Agent，适用于简单任务
  - BaseReactAgent: 基于LangGraph的ReAct模式Agent，支持工具调用和推理
  - BaseGraphAgent: 基于StateGraph的复杂工作流Agent，支持多节点编排

**agents/comment_analysis_agent.py** - CommentAnalysisAgent
- 功能: 从评论中提取帖子解构维度（两步法：评论过滤 → 维度提取）
- 核心流程:
  - 第1步: 过滤评论，只保留描述物理特征的相关评论
  - 第2步: 从相关评论中提取解构维度（处理状态、色彩特征、材质特征等）
- 输出: deconstruction_dimensions（解构维度列表）、filtered_comments（过滤后的评论）

**agents/content_filter_agent.py** - ContentFilterAgent
- 功能: 从bodytext中识别并移除与帖子主内容不相关的话题标签
- 判断方法: 双重验证（显性匹配检查 + 主题相关性检查）
- 输出: filtered_body（过滤后的bodytext）、removed_hashtags（移除的标签）、kept_hashtags（保留的标签）

**agents/content_weight_agent.py** - ContentWeightAgent
- 功能: 判断帖子中图片和文字的权重分配
- 评分维度: 信息量维度（0-10分）、独立理解性（0-10分）、核心价值承载（0-10分）
- 输出: image_weight（图片权重）、text_weight（文字权重）、primary_source（主要信息源：image/text/both）

**agents/inspiration_points_agent.py** - InspirationPointsAgent
- 功能: 从创作者视角提取触发创作的刺激源（7步流程）
- 核心流程:
  - Step1: 历史对比分析（三维度：共性内容、共性差异、全新内容）
  - Step2: 识别候选灵感点（按三种来源分类）
  - Step3: 逆向推导验证
  - Step4: 去重检查
  - Step5: 三维度评分（人设契合度、触发可能性、内容解释力）
  - Step6: 排序筛选
  - Step7: 组装最终输出
- 输出: 分类的灵感点字典（全新内容、共性差异、共性内容）+ 元数据

**agents/key_points_agent.py** - KeyPointsAgent
- 功能: 从消费者视角提取核心吸引点（5步流程）
- 维度体系: 形式（风格、关系）、实质（元素、分类）
- 核心流程:
  - Step1: 识别候选关键点
  - Step2: 第一轮去重（与灵感点、目的点去重）
  - Step3: 第二轮去重（关键点之间去重）
  - Step4: 构建层级关系（树形结构）
  - Step5: 组装最终输出
- 输出: 具有层级关系的关键点树形结构

**agents/knowledge_requirement_agent.py** - KnowledgeRequirementAgent
- 功能: 分析帖子需要的知识补充需求
- 输出: 知识需求列表（每个需求包含类别、描述、重要性等）

**agents/post_summary_deconstruction_agent.py** - PostSummaryDeconstructionAgent
- 功能: 帖子摘要解构
- 输出: 帖子的摘要解构结果

**agents/post_understanding_agent.py** - PostUnderstandingAgent
- 功能: 帖子理解与分析
- 输出: 帖子理解结果

**agents/purpose_point_agent.py** - PurposePointAgent
- 功能: 从创作者视角提取创作目的
- 输出: 创作目的点列表（包含维度、目的点、描述等）

**agents/recursive_image_deconstruction_agent.py** - RecursiveImageDeconstructionAgent
- 功能: 递归解构图像（多层级深度分析）
- 输出: 图像的递归解构结果

**agents/recursive_text_deconstruction_agent.py** - RecursiveTextDeconstructionAgent
- 功能: 递归解构文本（多层级深度分析）
- 输出: 文本的递归解构结果

**agents/script_section_division_agent.py** - ScriptSectionDivisionAgent
- 功能: 脚本段落划分 - 分析已有帖子的分段结构，理解创作者是如何组织内容的
- 核心流程: 根据图文权重策略识别创作者的分段逻辑
- 输出: 段落列表（树状结构）、内容品类

**agents/script_element_extraction_agent.py** - ScriptElementExtractionAgent
- 功能: 脚本元素提取 - 从已有帖子内容中提取核心元素（实质性+概念性）
- 核心流程（4步）:
  - Step1: 候选元素识别（实质性元素+概念性元素）
  - Step2: 双维度评分（主题支撑性+多段落共性，分视角分析）
  - Step3: 严格筛选（阈值6.0）
  - Step4: 去重与整合（生成树状结构）
- 输出: 元素列表（树状结构）

**agents/topic_selection_understanding_agent.py** - TopicSelectionUnderstandingAgent
- 功能: 选题理解与分析
- 输出: 选题理解结果

### Tool组件 (4个)

**tools/base.py** - BaseTool
- 功能: Tool基础抽象类
- 特性: 可被Agent调用，使用@tool装饰器或继承BaseTool

**tools/knowledge_retrieval_tools.py** - 知识检索工具集
- 功能: 根据Query词查询知识库
- 核心工具: knowledge_search（知识搜索）

**tools/nanobanana_tools.py** - NanoBanana图像生成与编辑工具
- 功能: 图像生成、图像编辑、图片融合、图片元素提取
- 核心工具: generate_image、edit_image、merge_images、extract_elements

**tools/segment_tools.py** - 图像分割工具
- 功能: 图像分割与目标检测
- 核心工具: segment_image（图像分割）

### Function组件 (3个)

**functions/base.py** - BaseFunction
- 功能: Function基础抽象类
- 特性: 不能被Agent调用，适用于纯函数式数据处理

**functions/json_utils.py** - JSON处理函数集
- 功能: JSON格式化、解析、验证
- 核心函数: format_json、parse_json、validate_json

**functions/result_aggregation_function.py** - ResultAggregationFunction
- 功能: 聚合多个组件的处理结果，生成最终输出
- 核心方法: aggregate（结果聚合）

### 公共组件 (Utils)

**utils/json_extractor.py** - JSONExtractor
- 功能: JSON提取和解析工具类
- 核心方法:
  - extract_json_from_response: 从LLM响应中提取JSON内容（支持markdown代码块）
  - safe_parse_json: 安全解析JSON，失败时返回默认值
  - extract_and_parse: 一步完成提取和解析

**utils/logger.py** - DeconstructionLogger
- 功能: 解构系统专用日志器（单例模式）
- 核心方法:
  - get_logger: 获取指定名称的子日志器
  - log_agent_start: 记录Agent开始执行
  - log_agent_finish: 记录Agent完成执行
  - log_tool_call: 记录工具调用
  - log_validation_result: 记录验证结果
  - log_error_with_context: 记录带上下文的错误
- 特性: 文件日志+控制台日志，自动创建日志目录

**utils/llm_invoker.py** - LLMInvoker
- 功能: LLM调用封装工具类
- 核心方法:
  - safe_invoke: 安全的LLM调用，支持自动初始化、JSON解析、降级处理

**utils/utils.py** - 通用工具函数集
- 功能: 提供常用工具函数
- 核心方法:
  - remove_duplicates: 去重并保持元素顺序
  - oss_resize_image: OSS图片URL尺寸调整

## 现有工作流

### WhatDeconstructionWorkflow
- 数据结构: WhatDeconstructionState
- 功能: What业务递归解构工作流
- 核心流程:
  1. 内容过滤（ContentFilterAgent）- 过滤bodytext中的无关标签
  2. 内容权重判断（ContentWeightAgent）- 判断图文权重
  3. 评论分析（CommentAnalysisAgent）- 提取解构维度
  4. 灵感点提取（InspirationPointsAgent）- 创作者视角的触发源
  5. 目的点提取（PurposePointAgent）- 创作者视角的创作目的
  6. 关键点提取（KeyPointsAgent）- 消费者视角的吸引点
  7. 选题理解（TopicSelectionUnderstandingAgent）- 选题分析
  8. 知识需求分析（KnowledgeRequirementAgent）- 知识补充需求
  9. 结果汇总（ResultAggregationFunction）- 聚合所有结果
- 依赖组件:
  - Agent: ContentFilterAgent、ContentWeightAgent、CommentAnalysisAgent、InspirationPointsAgent、PurposePointAgent、KeyPointsAgent、TopicSelectionUnderstandingAgent、KnowledgeRequirementAgent
  - Function: ResultAggregationFunction

---