video_decode/CLAUDE.md

项目开发指南

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

---