Merge branch 'refs/heads/main' into dev-create

README.md

@@ -125,6 +125,79 @@ runner = AgentRunner(
 
 内置 skills（`agent/memory/skills/`）始终自动加载，`skills_dir` 的内容额外追加。
 
+## 经验系统（Experience System）
+
+经验系统通过**提取、注入、反馈、更新**四个环节，让 Agent 从历史执行中学习并持续改进。
+
+### 核心流程
+
+**1. 提取（Extract）**
+- **触发时机**：Level 2 压缩时自动触发
+- **提取方式**：在压缩历史消息前，先调用 LLM 对当前执行过程进行反思（reflect）
+- **输出格式**：ACE 规范经验条目
+  ```
+  当 [条件/Context] 时，应该 [动作/Action]（原因：[逻辑/Reason]）
+  ```
+- **存储位置**：追加到 `experiences.md` 文件（默认 `./.cache/experiences.md`）
+
+**2. 注入（Inject）**
+- **触发时机**：切换 Goal 时自动触发
+- **检索策略**：两阶段检索
+  - Stage 1: 语义路由（LLM 挑选 2*k 个相关经验）
+  - Stage 2: 质量精排（根据 metrics 筛选最终 k 个）
+- **注入方式**：将检索到的经验注入到主 Agent 的上下文中
+
+**3. 反馈（Feedback）**
+- **触发时机**：压缩时分析历史消息中经验的使用效果
+- **评价维度**：
+  - `helpful`: 经验有效，帮助完成任务
+  - `harmful`: 经验误导，导致错误
+  - `mixed`: 部分有效，需要改进
+- **反馈来源**：LLM 分析执行过程中经验的实际效果
+
+**4. 更新（Update）**
+- **Metrics 更新**：根据反馈调整 `helpful` 和 `harmful` 计数
+- **内容进化**：
+  - `helpful` + 有改进建议 → 触发经验重写（evolve）
+  - `harmful` 累积 → 降低检索权重或标记为有害
+- **质量过滤**：检索时自动过滤 `quality_score < -2` 的有害经验
+
+### 经验文件格式
+
+```markdown
+---
+id: ex_02271430_a3f2
+trace_id: 6822d4e0-8aeb-449f-962e-c431c409a5a0
+tags: {intent: [解构, 图片分析], state: [多图]}
+metrics: {helpful: 3, harmful: 0}
+created_at: 2026-02-27 14:30:15
+updated_at: 2026-02-27 15:20:42
+---
+当需要分析多张图片时，应该先并行读取所有图片再统一分析（原因：避免重复调用 LLM，节省 token 和时间）。
+```
+
+### 经验库瘦身
+
+`experience.py` 中提供 `slim_experiences()` 函数，可调用顶级 LLM 合并语义相似的经验，减少冗余。
+
+**功能**：
+- 识别并合并语义高度相似的经验
+- 保留 helpful 最高的 ID
+- 合并 metrics（helpful/harmful 取各条之和）
+- 保持 ACE 规范格式
+
+**状态**：已实现但暂未自动调用，可在 `analyze_story/run.py` 的交互菜单中手动触发（选项 7）。
+
+### 配置
+
+```python
+runner = AgentRunner(
+    llm_call=...,
+    trace_store=...,
+    experiences_path="./.cache/experiences.md",  # 自定义经验文件路径
+)
+```
+
 ## AgentRunner 参数
 
 ```python

agent/core/presets.py

@@ -21,29 +21,41 @@ class AgentPreset:
     max_iterations: int = 30
     temperature: Optional[float] = None
 
+    # Skills（注入 system prompt 的 skill 名称列表；None = 加载全部）
+    skills: Optional[List[str]] = None
+
     # 描述
     description: Optional[str] = None
 
 
 # 内置预设
+_DEFAULT_SKILLS = ["planning", "research", "browser"]
+
 AGENT_PRESETS = {
     "default": AgentPreset(
         allowed_tools=None,
         max_iterations=30,
+        skills=_DEFAULT_SKILLS,
         description="默认 Agent，拥有全部工具权限",
     ),
+    "delegate": AgentPreset(
+        allowed_tools=None,
+        max_iterations=30,
+        skills=_DEFAULT_SKILLS,
+        description="委托子 Agent，拥有全部工具权限（由 agent 工具创建）",
+    ),
     "explore": AgentPreset(
         allowed_tools=["read", "glob", "grep", "list_files"],
         denied_tools=["write", "edit", "bash", "task"],
         max_iterations=15,
+        skills=["planning"],
         description="探索型 Agent，只读权限，用于代码分析",
     ),
-    "analyst": AgentPreset(
-        allowed_tools=["read", "glob", "grep", "web_search", "webfetch"],
-        denied_tools=["write", "edit", "bash", "task"],
-        temperature=0.3,
-        max_iterations=25,
-        description="分析型 Agent，用于深度分析和研究",
+    "evaluate": AgentPreset(
+        allowed_tools=["read_file", "grep_content", "glob_files", "goal"],
+        max_iterations=10,
+        skills=["planning"],
+        description="评估型 Agent，只读权限，用于结果评估",
     ),
 }
 

agent/core/runner.py

@@ -26,6 +26,7 @@ from typing import AsyncIterator, Optional, Dict, Any, List, Callable, Literal,
 from agent.trace.models import Trace, Message
 from agent.trace.protocols import TraceStore
 from agent.trace.goal_models import GoalTree
+from agent.tools.builtin.experience import _get_structured_experiences, _batch_update_experiences
 from agent.trace.compaction import (
     CompressionConfig,
     filter_by_goal_status,
@@ -61,9 +62,11 @@ class RunConfig:
     agent_type: str = "default"
     uid: Optional[str] = None
     system_prompt: Optional[str] = None        # None = 从 skills 自动构建
+    skills: Optional[List[str]] = None         # 注入 system prompt 的 skill 名称列表；None = 按 preset 决定
     enable_memory: bool = True
     auto_execute_tools: bool = True
     name: Optional[str] = None                 # 显示名称（空则由 utility_llm 自动生成）
+    enable_prompt_caching: bool = True         # 启用 Anthropic Prompt Caching（仅 Claude 模型有效）
 
     # --- Trace 控制 ---
     trace_id: Optional[str] = None             # None = 新建
@@ -98,6 +101,7 @@ BUILTIN_TOOLS = [
 
     # 搜索工具
     "search_posts",
+    "get_experience",
     "get_search_suggestions",
 
     # 沙箱工具
@@ -181,6 +185,7 @@ class AgentRunner:
         tool_registry: Optional[ToolRegistry] = None,
         llm_call: Optional[Callable] = None,
         utility_llm_call: Optional[Callable] = None,
+        embedding_call: Optional[Callable] = None,
         config: Optional[AgentConfig] = None,
         skills_dir: Optional[str] = None,
         experiences_path: Optional[str] = "./.cache/experiences.md",
@@ -196,6 +201,7 @@ class AgentRunner:
             state_store: State 存储（可选）
             tool_registry: 工具注册表（默认使用全局注册表）
             llm_call: 主 LLM 调用函数
+            embedding_call: 语义嵌入向量LLM
             utility_llm_call: 轻量 LLM（用于生成任务标题等），可选
             config: [向后兼容] AgentConfig
             skills_dir: Skills 目录路径
@@ -208,13 +214,16 @@ class AgentRunner:
         self.state_store = state_store
         self.tools = tool_registry or get_tool_registry()
         self.llm_call = llm_call
+        self.embedding_call = embedding_call
         self.utility_llm_call = utility_llm_call
         self.config = config or AgentConfig()
         self.skills_dir = skills_dir
+        # 确保 experiences_path 不为 None
         self.experiences_path = experiences_path
         self.goal_tree = goal_tree
         self.debug = debug
         self._cancel_events: Dict[str, asyncio.Event] = {}  # trace_id → cancel event
+        self.used_ex_ids: List[str] = []  # 当前运行中使用过的经验 ID
 
     # ===== 核心公开方法 =====
 
@@ -289,16 +298,22 @@ class AgentRunner:
         self,
         messages: List[Dict],
         config: Optional[RunConfig] = None,
+        on_event: Optional[Callable] = None,
     ) -> Dict[str, Any]:
         """
         结果模式 — 消费 run()，返回结构化结果。
 
         主要用于 agent/evaluate 工具内部。
+
+        Args:
+            on_event: 可选回调，每个 Trace/Message 事件触发一次，用于实时输出子 Agent 执行过程。
         """
         last_assistant_text = ""
         final_trace: Optional[Trace] = None
 
         async for item in self.run(messages=messages, config=config):
+            if on_event:
+                on_event(item)
             if isinstance(item, Message) and item.role == "assistant":
                 content = item.content
                 text = ""
@@ -467,6 +482,10 @@ class AgentRunner:
             raise ValueError(f"Trace not found: {config.trace_id}")
 
         goal_tree = await self.trace_store.get_goal_tree(config.trace_id)
+        if goal_tree is None:
+            # 防御性兜底：trace 存在但 goal.json 丢失时，创建空树
+            goal_tree = GoalTree(mission=trace_obj.task or "Agent task")
+            await self.trace_store.update_goal_tree(config.trace_id, goal_tree)
 
         # 自动判断行为：after_sequence 为 None 或 == head → 续跑；< head → 回溯
         after_seq = config.after_sequence
@@ -498,7 +517,32 @@ class AgentRunner:
         return trace_obj, goal_tree, sequence
 
     # ===== Phase 2: BUILD HISTORY =====
+    async def _get_embedding(self, text: str) -> List[float]:
+        """
+        获取文本的嵌入向量（Embedding）
+        
+        Args:
+            text: 需要向量化的文本
+            
+        Returns:
+            List[float]: 嵌入向量
+        """
+        if not text or not text.strip():
+            return []
 
+        # 优先使用注入的 embedding_call
+        if self.embedding_call:
+            try:
+                return await self.embedding_call(text)
+            except Exception as e:
+                logger.error(f"Error in embedding_call: {e}")
+                raise
+
+        # 兜底方案：如果没有注入 embedding_call，但有 llm_call，
+        # 某些 SDK 封装可能支持通过 llm_call 的客户端直接获取
+        # 这里建议强制要求基础设施层提供该函数以保证分层清晰
+        raise ValueError("embedding_call function not provided to AgentRunner")
+    
     async def _build_history(
         self,
         trace_id: str,
@@ -541,36 +585,40 @@ class AgentRunner:
                 if main_path:
                     head_seq = main_path[-1].sequence
 
-        # 2. 构建 system prompt（如果历史中没有 system message）
+        # 2. 构建/注入 skills 到 system prompt
         has_system = any(m.get("role") == "system" for m in history)
         has_system_in_new = any(m.get("role") == "system" for m in new_messages)
 
-        if not has_system and not has_system_in_new:
-            system_prompt = await self._build_system_prompt(config)
-            if system_prompt:
-                history = [{"role": "system", "content": system_prompt}] + history
-
-                if self.trace_store:
-                    system_msg = Message.create(
-                        trace_id=trace_id, role="system", sequence=sequence,
-                        goal_id=None, content=system_prompt,
-                        parent_sequence=None,  # system message 是 root
-                    )
-                    await self.trace_store.add_message(system_msg)
-                    created_messages.append(system_msg)
-                    head_seq = sequence
-                    sequence += 1
-
-        # 3. 新建时：在第一条 user message 末尾注入当前经验
-        if not config.trace_id:  # 新建模式
-            experiences_text = self._load_experiences()
-            if experiences_text:
+        if not has_system:
+            if has_system_in_new:
+                # 入参消息已含 system，将 skills 注入其中（在 step 4 持久化之前）
+                augmented = []
                 for msg in new_messages:
-                    if msg.get("role") == "user" and isinstance(msg.get("content"), str):
-                        msg["content"] += f"\n\n## 参考经验\n\n{experiences_text}"
-                        break
+                    if msg.get("role") == "system":
+                        base = msg.get("content") or ""
+                        enriched = await self._build_system_prompt(config, base_prompt=base)
+                        augmented.append({**msg, "content": enriched or base})
+                    else:
+                        augmented.append(msg)
+                new_messages = augmented
+            else:
+                # 没有 system，自动构建并插入历史
+                system_prompt = await self._build_system_prompt(config)
+                if system_prompt:
+                    history = [{"role": "system", "content": system_prompt}] + history
 
-        # 4. 追加新 messages（设置 parent_sequence 链接到当前 head）
+                    if self.trace_store:
+                        system_msg = Message.create(
+                            trace_id=trace_id, role="system", sequence=sequence,
+                            goal_id=None, content=system_prompt,
+                            parent_sequence=None,  # system message 是 root
+                        )
+                        await self.trace_store.add_message(system_msg)
+                        created_messages.append(system_msg)
+                        head_seq = sequence
+                        sequence += 1
+
+        # 3. 追加新 messages（设置 parent_sequence 链接到当前 head）
         for msg_dict in new_messages:
             history.append(msg_dict)
 
@@ -607,10 +655,9 @@ class AgentRunner:
         # 当前主路径头节点的 sequence（用于设置 parent_sequence）
         head_seq = trace.head_sequence
 
-        # 设置 goal_tree 到 goal 工具
-        if goal_tree and self.trace_store:
-            from agent.trace.goal_tool import set_goal_tree
-            set_goal_tree(goal_tree)
+        # 经验检索缓存：只在 goal 切换时重新检索
+        _last_goal_id = None
+        _cached_exp_text = ""
 
         for iteration in range(config.max_iterations):
             # 检查取消信号
@@ -634,6 +681,22 @@ class AgentRunner:
             token_count = estimate_tokens(history)
             max_tokens = compression_config.get_max_tokens(config.model)
 
+            # 压缩评估日志
+            progress_pct = (token_count / max_tokens * 100) if max_tokens > 0 else 0
+            msg_count = len(history)
+            img_count = sum(
+                1 for msg in history
+                if isinstance(msg.get("content"), list)
+                for part in msg["content"]
+                if isinstance(part, dict) and part.get("type") in ("image", "image_url")
+            )
+            print(f"\n[压缩评估] 消息数: {msg_count} | 图片数: {img_count} | Token: {token_count:,} / {max_tokens:,} ({progress_pct:.1f}%)")
+
+            if token_count > max_tokens:
+                print(f"[压缩评估] ⚠️  超过阈值，触发压缩流程")
+            else:
+                print(f"[压缩评估] ✅ 未超阈值，无需压缩")
+
             if token_count > max_tokens and self.trace_store and goal_tree:
                 # 使用本地 head_seq（store 中的 head_sequence 在 loop 期间未更新，是过时的）
                 if head_seq > 0:
@@ -642,12 +705,21 @@ class AgentRunner:
                     )
                     filtered_msgs = filter_by_goal_status(main_path_msgs, goal_tree)
                     if len(filtered_msgs) < len(main_path_msgs):
+                        filtered_tokens = estimate_tokens([msg.to_llm_dict() for msg in filtered_msgs])
+                        print(
+                            f"[Level 1 压缩] 消息: {len(main_path_msgs)} → {len(filtered_msgs)} 条 | "
+                            f"Token: {token_count:,} → ~{filtered_tokens:,}"
+                        )
                         logger.info(
                             "Level 1 压缩: %d -> %d 条消息 (tokens ~%d, 阈值 %d)",
                             len(main_path_msgs), len(filtered_msgs), token_count, max_tokens,
                         )
                         history = [msg.to_llm_dict() for msg in filtered_msgs]
                     else:
+                        print(
+                            f"[Level 1 压缩] 无可过滤消息 ({len(main_path_msgs)} 条全部保留, "
+                            f"completed/abandoned goals={sum(1 for g in goal_tree.goals if g.status in ('completed', 'abandoned'))})"
+                        )
                         logger.info(
                             "Level 1 压缩: 无可过滤消息 (%d 条全部保留, completed/abandoned goals=%d)",
                             len(main_path_msgs),
@@ -655,6 +727,7 @@ class AgentRunner:
                                 if g.status in ("completed", "abandoned")),
                         )
             elif token_count > max_tokens:
+                print("[压缩评估] ⚠️  无法执行 Level 1 压缩（缺少 store 或 goal_tree）")
                 logger.warning(
                     "消息 token 数 (%d) 超过阈值 (%d)，但无法执行 Level 1 压缩（缺少 store 或 goal_tree）",
                     token_count, max_tokens,
@@ -663,6 +736,11 @@ class AgentRunner:
             # Level 2 压缩：LLM 总结（Level 1 后仍超阈值时触发）
             token_count_after = estimate_tokens(history)
             if token_count_after > max_tokens:
+                progress_pct_after = (token_count_after / max_tokens * 100) if max_tokens > 0 else 0
+                print(
+                    f"[Level 2 压缩] Level 1 后仍超阈值: {token_count_after:,} / {max_tokens:,} ({progress_pct_after:.1f}%) "
+                    f"→ 触发 LLM 总结"
+                )
                 logger.info(
                     "Level 1 后 token 仍超阈值 (%d > %d)，触发 Level 2 压缩",
                     token_count_after, max_tokens,
@@ -670,16 +748,63 @@ class AgentRunner:
                 history, head_seq, sequence = await self._compress_history(
                     trace_id, history, goal_tree, config, sequence, head_seq,
                 )
+                final_tokens = estimate_tokens(history)
+                print(f"[Level 2 压缩] 完成: Token {token_count_after:,} → {final_tokens:,}")
+            elif token_count > max_tokens:
+                # Level 1 压缩成功，未触发 Level 2
+                print(f"[压缩评估] ✅ Level 1 压缩后达标: {token_count_after:,} / {max_tokens:,}")
+            print()  # 空行分隔
 
             # 构建 LLM messages（注入上下文）
             llm_messages = list(history)
 
+            # 先对历史消息应用 Prompt Caching（在注入动态内容之前）
+            # 这样可以确保历史消息的缓存点固定，不受动态注入影响
+            llm_messages = self._add_cache_control(
+                llm_messages,
+                config.model,
+                config.enable_prompt_caching
+            )
+
+            # 然后追加动态注入的内容（不影响已缓存的历史消息）
             # 周期性注入 GoalTree + Collaborators
             if iteration % CONTEXT_INJECTION_INTERVAL == 0:
                 context_injection = self._build_context_injection(trace, goal_tree)
                 if context_injection:
                     llm_messages.append({"role": "system", "content": context_injection})
 
+            # 经验检索：goal 切换时重新检索，注入为 system message
+            current_goal_id = goal_tree.current_id if goal_tree else None
+            if current_goal_id and current_goal_id != _last_goal_id:
+                _last_goal_id = current_goal_id
+                current_goal = goal_tree.find(current_goal_id)
+                if current_goal:
+                    try:
+                        relevant_exps = await _get_structured_experiences(
+                            query_text=current_goal.description,
+                            top_k=3,
+                            context={"runner": self}
+                        )
+                        if relevant_exps:
+                            self.used_ex_ids = [exp['id'] for exp in relevant_exps]
+                            parts = [f"[{exp['id']}] {exp['content']}" for exp in relevant_exps]
+                            _cached_exp_text = "## 参考历史经验\n" + "\n\n".join(parts)
+                            logger.info(
+                                "经验检索: goal='%s', 命中 %d 条 %s",
+                                current_goal.description[:40],
+                                len(relevant_exps),
+                                self.used_ex_ids,
+                            )
+                        else:
+                            _cached_exp_text = ""
+                    except Exception as e:
+                        logger.warning("经验检索失败: %s", e)
+                        _cached_exp_text = ""
+
+            # 经验注入：goal切换时注入相关历史经验
+            if _cached_exp_text:
+                llm_messages.append({"role": "system", "content": _cached_exp_text})
+
             # 调用 LLM
             result = await self.llm_call(
                 messages=llm_messages,
@@ -695,6 +820,8 @@ class AgentRunner:
             prompt_tokens = result.get("prompt_tokens", 0)
             completion_tokens = result.get("completion_tokens", 0)
             step_cost = result.get("cost", 0)
+            cache_creation_tokens = result.get("cache_creation_tokens")
+            cache_read_tokens = result.get("cache_read_tokens")
 
             # 按需自动创建 root goal
             if goal_tree and not goal_tree.goals and tool_calls:
@@ -712,8 +839,8 @@ class AgentRunner:
                     )
                     goal_tree.focus(goal_tree.goals[0].id)
                     if self.trace_store:
-                        await self.trace_store.update_goal_tree(trace_id, goal_tree)
                         await self.trace_store.add_goal(trace_id, goal_tree.goals[0])
+                        await self.trace_store.update_goal_tree(trace_id, goal_tree)
                     logger.info(f"自动创建 root goal: {goal_tree.goals[0].id}")
 
             # 获取当前 goal_id
@@ -729,6 +856,8 @@ class AgentRunner:
                 content={"text": response_content, "tool_calls": tool_calls},
                 prompt_tokens=prompt_tokens,
                 completion_tokens=completion_tokens,
+                cache_creation_tokens=cache_creation_tokens,
+                cache_read_tokens=cache_read_tokens,
                 finish_reason=finish_reason,
                 cost=step_cost,
             )
@@ -793,6 +922,7 @@ class AgentRunner:
                             "trace_id": trace_id,
                             "goal_id": current_goal_id,
                             "runner": self,
+                            "goal_tree": goal_tree,
                         }
                     )
 
@@ -824,7 +954,8 @@ class AgentRunner:
                         goal_id=current_goal_id,
                         parent_sequence=head_seq,
                         tool_call_id=tc["id"],
-                        content={"tool_name": tool_name, "result": tool_result_text},
+                        # 存储完整内容：有图片时保留 list（含 image_url），纯文本时存字符串
+                        content={"tool_name": tool_name, "result": tool_content_for_llm},
                     )
 
                     if self.trace_store:
@@ -920,34 +1051,84 @@ class AgentRunner:
 
         # --- Step 1: 经验提取（reflect）---
         try:
+            # 1. 构造 Reflect Prompt（确保包含格式要求）
+            # 建议在 build_reflect_prompt() 里加入：
+            # "请使用格式：- [intent: 意图, state: 状态描述] 具体的经验内容"
             reflect_prompt = build_reflect_prompt()
             reflect_messages = list(history) + [{"role": "user", "content": reflect_prompt}]
 
+            # 应用 Prompt Caching
+            reflect_messages = self._add_cache_control(
+                reflect_messages,
+                config.model,
+                config.enable_prompt_caching
+            )
+
             reflect_result = await self.llm_call(
                 messages=reflect_messages,
                 model=config.model,
                 tools=[],
-                temperature=config.temperature,
+                temperature=0.2, # 略微保持一点发散性
                 **config.extra_llm_params,
             )
 
-            reflect_content = reflect_result.get("content", "").strip()
-            if reflect_content and self.experiences_path:
-                try:
+            reflection_text = reflect_result.get("content", "").strip()
+            
+            if reflection_text:
+                import re as _re2
+                import uuid as _uuid2
+
+                pattern = r"-\s*\[(?P<tags>.*?)\]\s*(?P<content>.*)"
+                matches = list(_re2.finditer(pattern, reflection_text))
+
+                structured_entries = []
+                for match in matches:
+                    tags_str = match.group("tags")
+                    content = match.group("content")
+
+                    intent_match = _re2.search(r"intent:\s*(.*?)(?:,|$)", tags_str, _re2.IGNORECASE)
+                    state_match = _re2.search(r"state:\s*(.*?)(?:,|$)", tags_str, _re2.IGNORECASE)
+
+                    intents = [i.strip() for i in intent_match.group(1).split(",")] if intent_match and intent_match.group(1) else []
+                    states = [s.strip() for s in state_match.group(1).split(",")] if state_match and state_match.group(1) else []
+
+                    ex_id = f"ex_{datetime.now().strftime('%m%d%H%M')}_{_uuid2.uuid4().hex[:4]}"
+                    entry = f"""---
+id: {ex_id}
+trace_id: {trace_id}
+tags: {{intent: {intents}, state: {states}}}
+metrics: {{helpful: 1, harmful: 0}}
+created_at: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+---
+- {content}
+- 经验ID: [{ex_id}]"""
+                    structured_entries.append(entry)
+
+                if structured_entries:
                     os.makedirs(os.path.dirname(self.experiences_path), exist_ok=True)
                     with open(self.experiences_path, "a", encoding="utf-8") as f:
-                        f.write(f"\n\n---\n\n{reflect_content}")
-                    logger.info("经验已追加到 %s", self.experiences_path)
-                except Exception as e:
-                    logger.warning("写入经验文件失败: %s", e)
+                        f.write("\n\n" + "\n\n".join(structured_entries))
+                    logger.info(f"已提取并保存 {len(structured_entries)} 条结构化经验")
+                else:
+                    logger.warning("未能解析出符合格式的经验条目，请检查 REFLECT_PROMPT。")
+                    logger.debug(f"LLM Raw Output:\n{reflection_text}")
+            else:
+                logger.warning("LLM 未生成反思内容")
 
         except Exception as e:
-            logger.warning("Level 2 经验提取失败（不影响压缩）: %s", e)
+            logger.error(f"Level 2 经验提取失败: {e}")
 
-        # --- Step 2: 压缩总结 ---
-        compress_prompt = build_compression_prompt(goal_tree)
+        # --- Step 2: 压缩总结 + 经验评估 ---
+        compress_prompt = build_compression_prompt(goal_tree, used_ex_ids=self.used_ex_ids)
         compress_messages = list(history) + [{"role": "user", "content": compress_prompt}]
 
+        # 应用 Prompt Caching
+        compress_messages = self._add_cache_control(
+            compress_messages,
+            config.model,
+            config.enable_prompt_caching
+        )
+
         compress_result = await self.llm_call(
             messages=compress_messages,
             model=config.model,
@@ -956,7 +1137,44 @@ class AgentRunner:
             **config.extra_llm_params,
         )
 
-        summary_text = compress_result.get("content", "").strip()
+        raw_output = compress_result.get("content", "").strip()
+        if not raw_output:
+            logger.warning("Level 2 压缩跳过：LLM 未返回内容")
+            return history, head_seq, sequence
+
+        # 解析 [[EVALUATION]] 块并更新经验
+        if self.used_ex_ids:
+            try:
+                eval_block = ""
+                if "[[EVALUATION]]" in raw_output:
+                    eval_start = raw_output.index("[[EVALUATION]]") + len("[[EVALUATION]]")
+                    eval_end = raw_output.index("[[SUMMARY]]") if "[[SUMMARY]]" in raw_output else len(raw_output)
+                    eval_block = raw_output[eval_start:eval_end].strip()
+
+                if eval_block:
+                    import re as _re
+                    update_map = {}
+                    for line in eval_block.splitlines():
+                        m = _re.search(r"ID:\s*(ex_\S+)\s*\|\s*Result:\s*(\w+)", line)
+                        if m:
+                            ex_id, result = m.group(1), m.group(2).lower()
+                            if result in ("helpful", "harmful"):
+                                update_map[ex_id] = {"action": result, "feedback": ""}
+                            elif result == "mixed":
+                                update_map[ex_id] = {"action": "helpful", "feedback": ""}
+                    if update_map:
+                        count = await _batch_update_experiences(update_map, context={"runner": self})
+                        logger.info("经验评估完成，更新了 %s 条经验", count)
+            except Exception as e:
+                logger.warning("经验评估解析失败（不影响压缩）: %s", e)
+
+        # 提取 [[SUMMARY]] 块
+        summary_text = raw_output
+        if "[[SUMMARY]]" in raw_output:
+            summary_text = raw_output[raw_output.index("[[SUMMARY]]") + len("[[SUMMARY]]"):].strip()
+
+        # 压缩完成后清空 used_ex_ids
+        self.used_ex_ids = []
         if not summary_text:
             logger.warning("Level 2 压缩跳过：LLM 未返回 summary")
             return history, head_seq, sequence
@@ -1288,6 +1506,122 @@ class AgentRunner:
 
     # ===== 辅助方法 =====
 
+    def _add_cache_control(
+        self,
+        messages: List[Dict],
+        model: str,
+        enable: bool
+    ) -> List[Dict]:
+        """
+        为支持的模型添加 Prompt Caching 标记
+
+        策略：固定位置缓存点，提高缓存命中率
+        1. system message 添加缓存（如果存在且足够长）
+        2. 每 20 条 user/assistant/tool 消息添加一个固定缓存点（位置：20, 40, 60）
+        3. 最多使用 4 个缓存点（含 system）
+
+        Args:
+            messages: 原始消息列表
+            model: 模型名称
+            enable: 是否启用缓存
+
+        Returns:
+            添加了 cache_control 的消息列表（深拷贝）
+        """
+        if not enable:
+            return messages
+
+        # 只对 Claude 模型启用
+        if "claude" not in model.lower():
+            return messages
+
+        # 深拷贝避免修改原始数据
+        import copy
+        messages = copy.deepcopy(messages)
+
+        # 策略 1: 为 system message 添加缓存
+        system_cached = False
+        for msg in messages:
+            if msg.get("role") == "system":
+                content = msg.get("content", "")
+                # 只有足够长的 system prompt 才值得缓存（>1024 tokens 约 4000 字符）
+                if isinstance(content, str) and len(content) > 1000:
+                    msg["content"] = [
+                        {
+                            "type": "text",
+                            "text": content,
+                            "cache_control": {"type": "ephemeral"}
+                        }
+                    ]
+                    system_cached = True
+                    logger.debug(f"[Cache] 为 system message 添加缓存标记 (len={len(content)})")
+                break
+
+        # 策略 2: 按总消息数计算缓存点（包括 tool 消息）
+        # 但只能在 user/assistant 消息上添加 cache_control
+        total_msgs = len(messages)
+        if total_msgs == 0:
+            return messages
+
+        # 每 20 条总消息添加一个缓存点
+        # 原因：Anthropic 要求每个缓存点至少 1024 tokens
+        # 每 15 条消息约 1050 tokens，太接近边界，改为 20 条确保足够（约 1400 tokens）
+        CACHE_INTERVAL = 20
+        max_cache_points = 3 if system_cached else 4
+
+        cache_positions = []
+        for i in range(1, max_cache_points + 1):
+            target_pos = i * CACHE_INTERVAL - 1  # 第 20, 40, 60, 80 条
+            if target_pos < total_msgs:
+                # 从 target_pos 往前找最近的 user/assistant 消息
+                for j in range(target_pos, -1, -1):
+                    if messages[j].get("role") in ("user", "assistant"):
+                        cache_positions.append(j)
+                        break
+
+        # 应用缓存标记
+        for idx in cache_positions:
+            msg = messages[idx]
+            content = msg.get("content", "")
+            role = msg.get("role", "")
+
+            print(f"[Cache] 尝试为 message[{idx}] (role={role}, content_type={type(content).__name__}) 添加缓存标记")
+
+            # 处理 string content
+            if isinstance(content, str):
+                msg["content"] = [
+                    {
+                        "type": "text",
+                        "text": content,
+                        "cache_control": {"type": "ephemeral"}
+                    }
+                ]
+                print(f"[Cache] ✓ 为 message[{idx}] ({role}) 添加缓存标记 (str->list)")
+                logger.debug(f"[Cache] 为 message[{idx}] ({msg.get('role')}) 添加缓存标记")
+
+            # 处理 list content（多模态消息）
+            elif isinstance(content, list) and len(content) > 0:
+                # 在最后一个 text block 添加 cache_control
+                for i in range(len(content) - 1, -1, -1):
+                    if isinstance(content[i], dict) and content[i].get("type") == "text":
+                        content[i]["cache_control"] = {"type": "ephemeral"}
+                        print(f"[Cache] ✓ 为 message[{idx}] ({role}) 的 content[{i}] 添加缓存标记 (list)")
+                        logger.debug(f"[Cache] 为 message[{idx}] ({msg.get('role')}) 的 content[{i}] 添加缓存标记")
+                        break
+            else:
+                print(f"[Cache] ✗ message[{idx}] ({role}) 的 content 类型不支持: {type(content).__name__}, len={len(content) if isinstance(content, (list, str)) else 'N/A'}")
+
+        total_cache_points = len(cache_positions) + (1 if system_cached else 0)
+        print(
+            f"[Cache] 总消息: {len(messages)}, "
+            f"缓存点: {total_cache_points} at positions: {cache_positions}"
+        )
+        logger.debug(
+            f"[Cache] 总消息: {len(messages)}, "
+            f"缓存点: {total_cache_points} at positions: {cache_positions}"
+        )
+        return messages
+
     def _get_tool_schemas(self, tools: Optional[List[str]]) -> List[Dict]:
         """
         获取工具 Schema
@@ -1309,17 +1643,38 @@ class AgentRunner:
     # 默认 system prompt 前缀（当 config.system_prompt 和前端都未提供 system message 时使用）
     DEFAULT_SYSTEM_PREFIX = "你是最顶尖的AI助手，可以拆分并调用工具逐步解决复杂问题。"
 
-    async def _build_system_prompt(self, config: RunConfig) -> Optional[str]:
-        """构建 system prompt（注入 skills）"""
-        system_prompt = config.system_prompt
+    async def _build_system_prompt(self, config: RunConfig, base_prompt: Optional[str] = None) -> Optional[str]:
+        """构建 system prompt（注入 skills）
+
+        优先级：
+        1. config.skills 显式指定 → 按名称过滤
+        2. config.skills 为 None → 查 preset 的默认 skills 列表
+        3. preset 也无 skills（None）→ 加载全部（向后兼容）
+
+        Args:
+            base_prompt: 已有 system 内容（来自消息或 config.system_prompt），
+                         None 时使用 config.system_prompt
+        """
+        from agent.core.presets import AGENT_PRESETS
+
+        system_prompt = base_prompt if base_prompt is not None else config.system_prompt
+
+        # 确定要加载哪些 skills
+        skills_filter: Optional[List[str]] = config.skills
+        if skills_filter is None:
+            preset = AGENT_PRESETS.get(config.agent_type)
+            if preset is not None:
+                skills_filter = preset.skills  # 可能仍为 None（加载全部）
+
+        # 加载并过滤
+        all_skills = load_skills_from_dir(self.skills_dir)
+        if skills_filter is not None:
+            skills = [s for s in all_skills if s.name in skills_filter]
+        else:
+            skills = all_skills
 
-        # 加载 Skills
-        skills_text = ""
-        skills = load_skills_from_dir(self.skills_dir)
-        if skills:
-            skills_text = self._format_skills(skills)
+        skills_text = self._format_skills(skills) if skills else ""
 
-        # 拼装：有自定义 system_prompt 则用它，否则用默认前缀
         if system_prompt:
             if skills_text:
                 system_prompt += f"\n\n## Skills\n{skills_text}"

agent/llm/openrouter.py

@@ -2,7 +2,11 @@
 OpenRouter Provider
 
 使用 OpenRouter API 调用各种模型（包括 Claude Sonnet 4.5）
-支持 OpenAI 兼容的 API 格式
+
+路由策略：
+- Claude 模型：走 OpenRouter 的 Anthropic 原生端点（/api/v1/messages），
+  使用自包含的格式转换逻辑，确保多模态工具结果（截图等）正确传递。
+- 其他模型：走 OpenAI 兼容端点（/api/v1/chat/completions）。
 
 OpenRouter 转发多种模型，需要根据实际模型处理不同的 usage 格式：
 - OpenAI 模型: prompt_tokens, completion_tokens, completion_tokens_details.reasoning_tokens
@@ -15,6 +19,7 @@ import json
 import asyncio
 import logging
 import httpx
+from pathlib import Path
 from typing import List, Dict, Any, Optional
 
 from .usage import TokenUsage, create_usage_from_response
@@ -34,6 +39,325 @@ _RETRYABLE_EXCEPTIONS = (
 )
 
 
+# ── OpenRouter Anthropic endpoint: model name mapping ──────────────────────
+# Local copy of yescode's model tables so this module is self-contained.
+_OR_MODEL_EXACT = {
+    "claude-sonnet-4-6": "claude-sonnet-4-6",
+    "claude-sonnet-4.6": "claude-sonnet-4-6",
+    "claude-sonnet-4-5-20250929": "claude-sonnet-4-5-20250929",
+    "claude-sonnet-4-5": "claude-sonnet-4-5-20250929",
+    "claude-sonnet-4.5": "claude-sonnet-4-5-20250929",
+    "claude-opus-4-6": "claude-opus-4-6",
+    "claude-opus-4-5-20251101": "claude-opus-4-5-20251101",
+    "claude-opus-4-5": "claude-opus-4-5-20251101",
+    "claude-opus-4-1-20250805": "claude-opus-4-1-20250805",
+    "claude-opus-4-1": "claude-opus-4-1-20250805",
+    "claude-haiku-4-5-20251001": "claude-haiku-4-5-20251001",
+    "claude-haiku-4-5": "claude-haiku-4-5-20251001",
+}
+
+_OR_MODEL_FUZZY = [
+    ("sonnet-4-6", "claude-sonnet-4-6"),
+    ("sonnet-4.6", "claude-sonnet-4-6"),
+    ("sonnet-4-5", "claude-sonnet-4-5-20250929"),
+    ("sonnet-4.5", "claude-sonnet-4-5-20250929"),
+    ("opus-4-6", "claude-opus-4-6"),
+    ("opus-4.6", "claude-opus-4-6"),
+    ("opus-4-5", "claude-opus-4-5-20251101"),
+    ("opus-4.5", "claude-opus-4-5-20251101"),
+    ("opus-4-1", "claude-opus-4-1-20250805"),
+    ("opus-4.1", "claude-opus-4-1-20250805"),
+    ("haiku-4-5", "claude-haiku-4-5-20251001"),
+    ("haiku-4.5", "claude-haiku-4-5-20251001"),
+    ("sonnet", "claude-sonnet-4-6"),
+    ("opus", "claude-opus-4-6"),
+    ("haiku", "claude-haiku-4-5-20251001"),
+]
+
+
+def _resolve_openrouter_model(model: str) -> str:
+    """Normalize a model name for OpenRouter's Anthropic endpoint.
+
+    Strips ``anthropic/`` prefix, resolves aliases / dot-notation,
+    and re-prepends ``anthropic/`` for OpenRouter routing.
+    """
+    # 1. Strip provider prefix
+    bare = model.split("/", 1)[1] if "/" in model else model
+
+    # 2. Exact match
+    if bare in _OR_MODEL_EXACT:
+        return f"anthropic/{_OR_MODEL_EXACT[bare]}"
+
+    # 3. Fuzzy keyword match (case-insensitive)
+    bare_lower = bare.lower()
+    for keyword, target in _OR_MODEL_FUZZY:
+        if keyword in bare_lower:
+            logger.info("[OpenRouter] Model fuzzy match: %s → anthropic/%s", model, target)
+            return f"anthropic/{target}"
+
+    # 4. Fallback – return as-is (let API report the error)
+    logger.warning("[OpenRouter] Could not resolve model name: %s, passing as-is", model)
+    return model
+
+
+# ── OpenRouter Anthropic endpoint: format conversion helpers ───────────────
+
+def _get_image_dimensions(data: bytes) -> Optional[tuple]:
+    """从图片二进制数据的文件头解析宽高，支持 PNG/JPEG。不依赖 PIL。"""
+    try:
+        # PNG: 前 8 字节签名，IHDR chunk 在 16-24 字节存宽高 (big-endian uint32)
+        if data[:8] == b'\x89PNG\r\n\x1a\n' and len(data) >= 24:
+            import struct
+            w, h = struct.unpack('>II', data[16:24])
+            return (w, h)
+        # JPEG: 扫描 SOF0/SOF2 marker (0xFFC0/0xFFC2)
+        if data[:2] == b'\xff\xd8':
+            import struct
+            i = 2
+            while i < len(data) - 9:
+                if data[i] != 0xFF:
+                    break
+                marker = data[i + 1]
+                if marker in (0xC0, 0xC2):
+                    h, w = struct.unpack('>HH', data[i + 5:i + 9])
+                    return (w, h)
+                length = struct.unpack('>H', data[i + 2:i + 4])[0]
+                i += 2 + length
+    except Exception:
+        pass
+    return None
+
+
+def _to_anthropic_content(content: Any) -> Any:
+    """Convert OpenAI-style *content* (string or block list) to Anthropic format.
+
+    Handles ``image_url`` blocks → Anthropic ``image`` blocks (base64 or url).
+    Passes through ``text`` blocks and ``cache_control`` unchanged.
+    """
+    if not isinstance(content, list):
+        return content
+
+    result = []
+    for block in content:
+        if not isinstance(block, dict):
+            result.append(block)
+            continue
+
+        if block.get("type") == "image_url":
+            image_url_obj = block.get("image_url", {})
+            url = image_url_obj.get("url", "") if isinstance(image_url_obj, dict) else str(image_url_obj)
+            if url.startswith("data:"):
+                header, _, data = url.partition(",")
+                media_type = header.split(":")[1].split(";")[0] if ":" in header else "image/png"
+                import base64 as b64mod
+                raw = b64mod.b64decode(data)
+                dims = _get_image_dimensions(raw)
+                img_block = {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": media_type,
+                        "data": data,
+                    },
+                }
+                if dims:
+                    img_block["_image_meta"] = {"width": dims[0], "height": dims[1]}
+                result.append(img_block)
+            else:
+                # 检测本地文件路径，自动转 base64
+                local_path = Path(url)
+                if local_path.exists() and local_path.is_file():
+                    import base64 as b64mod
+                    import mimetypes
+                    mime_type, _ = mimetypes.guess_type(str(local_path))
+                    mime_type = mime_type or "image/png"
+                    raw = local_path.read_bytes()
+                    dims = _get_image_dimensions(raw)
+                    b64_data = b64mod.b64encode(raw).decode("ascii")
+                    logger.info(f"[OpenRouter] 本地图片自动转 base64: {url} ({len(raw)} bytes)")
+                    img_block = {
+                        "type": "image",
+                        "source": {
+                            "type": "base64",
+                            "media_type": mime_type,
+                            "data": b64_data,
+                        },
+                    }
+                    if dims:
+                        img_block["_image_meta"] = {"width": dims[0], "height": dims[1]}
+                    result.append(img_block)
+                else:
+                    result.append({
+                        "type": "image",
+                        "source": {"type": "url", "url": url},
+                    })
+        else:
+            result.append(block)
+    return result
+
+
+def _to_anthropic_messages(messages: List[Dict[str, Any]]) -> tuple:
+    """Convert an OpenAI-format message list to Anthropic Messages API format.
+
+    Returns ``(system_prompt, anthropic_messages)`` where *system_prompt* is
+    ``None`` or a string extracted from ``role=system`` messages, and
+    *anthropic_messages* is the converted list.
+    """
+    system_prompt = None
+    anthropic_messages: List[Dict[str, Any]] = []
+
+    for msg in messages:
+        role = msg.get("role", "")
+        content = msg.get("content", "")
+
+        if role == "system":
+            system_prompt = content
+
+        elif role == "user":
+            anthropic_messages.append({
+                "role": "user",
+                "content": _to_anthropic_content(content),
+            })
+
+        elif role == "assistant":
+            tool_calls = msg.get("tool_calls")
+            if tool_calls:
+                content_blocks: List[Dict[str, Any]] = []
+                if content:
+                    converted = _to_anthropic_content(content)
+                    if isinstance(converted, list):
+                        content_blocks.extend(converted)
+                    elif isinstance(converted, str) and converted.strip():
+                        content_blocks.append({"type": "text", "text": converted})
+                for tc in tool_calls:
+                    func = tc.get("function", {})
+                    args_str = func.get("arguments", "{}")
+                    try:
+                        args = json.loads(args_str) if isinstance(args_str, str) else args_str
+                    except json.JSONDecodeError:
+                        args = {}
+                    content_blocks.append({
+                        "type": "tool_use",
+                        "id": tc.get("id", ""),
+                        "name": func.get("name", ""),
+                        "input": args,
+                    })
+                anthropic_messages.append({"role": "assistant", "content": content_blocks})
+            else:
+                anthropic_messages.append({"role": "assistant", "content": content})
+
+        elif role == "tool":
+            # Split tool result into text-only tool_result + sibling image blocks.
+            # Images nested inside tool_result.content are not reliably passed
+            # through by all proxies (e.g. OpenRouter).  Placing them as sibling
+            # content blocks in the same user message is more compatible.
+            converted = _to_anthropic_content(content)
+            text_parts: List[Dict[str, Any]] = []
+            image_parts: List[Dict[str, Any]] = []
+            if isinstance(converted, list):
+                for block in converted:
+                    if isinstance(block, dict) and block.get("type") == "image":
+                        image_parts.append(block)
+                    else:
+                        text_parts.append(block)
+            elif isinstance(converted, str):
+                text_parts = [{"type": "text", "text": converted}] if converted else []
+
+            # tool_result keeps only text content
+            tool_result_block: Dict[str, Any] = {
+                "type": "tool_result",
+                "tool_use_id": msg.get("tool_call_id", ""),
+            }
+            if len(text_parts) == 1 and text_parts[0].get("type") == "text":
+                tool_result_block["content"] = text_parts[0]["text"]
+            elif text_parts:
+                tool_result_block["content"] = text_parts
+            # (omit content key entirely when empty – Anthropic accepts this)
+
+            # Build the blocks to append: tool_result first, then any images
+            new_blocks = [tool_result_block] + image_parts
+
+            # Merge consecutive tool results into one user message
+            if (anthropic_messages
+                    and anthropic_messages[-1].get("role") == "user"
+                    and isinstance(anthropic_messages[-1].get("content"), list)
+                    and anthropic_messages[-1]["content"]
+                    and anthropic_messages[-1]["content"][0].get("type") == "tool_result"):
+                anthropic_messages[-1]["content"].extend(new_blocks)
+            else:
+                anthropic_messages.append({
+                    "role": "user",
+                    "content": new_blocks,
+                })
+
+    return system_prompt, anthropic_messages
+
+
+def _to_anthropic_tools(tools: List[Dict]) -> List[Dict]:
+    """Convert OpenAI tool definitions to Anthropic format."""
+    anthropic_tools = []
+    for tool in tools:
+        if tool.get("type") == "function":
+            func = tool["function"]
+            anthropic_tools.append({
+                "name": func.get("name", ""),
+                "description": func.get("description", ""),
+                "input_schema": func.get("parameters", {"type": "object", "properties": {}}),
+            })
+    return anthropic_tools
+
+
+def _parse_anthropic_response(result: Dict[str, Any]) -> Dict[str, Any]:
+    """Parse an Anthropic Messages API response into the unified format.
+
+    Returns a dict with keys: content, tool_calls, finish_reason, usage.
+    """
+    content_blocks = result.get("content", [])
+
+    text_parts = []
+    tool_calls = []
+    for block in content_blocks:
+        if block.get("type") == "text":
+            text_parts.append(block.get("text", ""))
+        elif block.get("type") == "tool_use":
+            tool_calls.append({
+                "id": block.get("id", ""),
+                "type": "function",
+                "function": {
+                    "name": block.get("name", ""),
+                    "arguments": json.dumps(block.get("input", {}), ensure_ascii=False),
+                },
+            })
+
+    content = "\n".join(text_parts)
+
+    stop_reason = result.get("stop_reason", "end_turn")
+    finish_reason_map = {
+        "end_turn": "stop",
+        "tool_use": "tool_calls",
+        "max_tokens": "length",
+        "stop_sequence": "stop",
+    }
+    finish_reason = finish_reason_map.get(stop_reason, stop_reason)
+
+    raw_usage = result.get("usage", {})
+    usage = TokenUsage(
+        input_tokens=raw_usage.get("input_tokens", 0),
+        output_tokens=raw_usage.get("output_tokens", 0),
+        cache_creation_tokens=raw_usage.get("cache_creation_input_tokens", 0),
+        cache_read_tokens=raw_usage.get("cache_read_input_tokens", 0),
+    )
+
+    return {
+        "content": content,
+        "tool_calls": tool_calls if tool_calls else None,
+        "finish_reason": finish_reason,
+        "usage": usage,
+    }
+
+
+# ── Provider detection / usage parsing ─────────────────────────────────────
+
 def _detect_provider_from_model(model: str) -> str:
     """根据模型名称检测提供商"""
     model_lower = model.lower()
@@ -60,11 +384,20 @@ def _parse_openrouter_usage(usage: Dict[str, Any], model: str) -> TokenUsage:
     # OpenRouter 通常返回 OpenAI 格式，但可能包含额外字段
     if provider == "anthropic":
         # Claude 模型可能有缓存字段
+        # OpenRouter 使用 prompt_tokens_details 嵌套结构
+        prompt_details = usage.get("prompt_tokens_details", {})
+
+        # 调试：打印原始 usage
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(f"[OpenRouter] Raw usage: {usage}")
+            logger.debug(f"[OpenRouter] prompt_tokens_details: {prompt_details}")
+
         return TokenUsage(
             input_tokens=usage.get("prompt_tokens") or usage.get("input_tokens", 0),
             output_tokens=usage.get("completion_tokens") or usage.get("output_tokens", 0),
-            cache_creation_tokens=usage.get("cache_creation_input_tokens", 0),
-            cache_read_tokens=usage.get("cache_read_input_tokens", 0),
+            # OpenRouter 格式：prompt_tokens_details.cached_tokens / cache_write_tokens
+            cache_read_tokens=prompt_details.get("cached_tokens", 0),
+            cache_creation_tokens=prompt_details.get("cache_write_tokens", 0),
         )
     elif provider == "deepseek":
         # DeepSeek 可能有 reasoning_tokens
@@ -130,6 +463,138 @@ def _normalize_tool_call_ids(messages: List[Dict[str, Any]], target_prefix: str)
     return result
 
 
+async def _openrouter_anthropic_call(
+    messages: List[Dict[str, Any]],
+    model: str,
+    tools: Optional[List[Dict]],
+    api_key: str,
+    **kwargs,
+) -> Dict[str, Any]:
+    """
+    通过 OpenRouter 的 Anthropic 原生端点调用 Claude 模型。
+
+    使用 Anthropic Messages API 格式（/api/v1/messages），
+    自包含的格式转换逻辑，确保多模态内容（截图等）正确传递。
+    """
+    endpoint = "https://openrouter.ai/api/v1/messages"
+
+    # Resolve model name for OpenRouter (e.g. "claude-sonnet-4.5" → "anthropic/claude-sonnet-4-5-20250929")
+    resolved_model = _resolve_openrouter_model(model)
+    logger.info("[OpenRouter/Anthropic] model: %s → %s", model, resolved_model)
+
+    # 跨 Provider 续跑时，重写不兼容的 tool_call_id 为 toolu_ 前缀
+    messages = _normalize_tool_call_ids(messages, "toolu")
+
+    # OpenAI 格式 → Anthropic 格式
+    system_prompt, anthropic_messages = _to_anthropic_messages(messages)
+
+    # Diagnostic: count image blocks in the payload
+    _img_count = 0
+    for _m in anthropic_messages:
+        if isinstance(_m.get("content"), list):
+            for _b in _m["content"]:
+                if isinstance(_b, dict) and _b.get("type") == "image":
+                    _img_count += 1
+    if _img_count:
+        logger.info("[OpenRouter/Anthropic] payload contains %d image block(s)", _img_count)
+        print(f"[OpenRouter/Anthropic] payload contains {_img_count} image block(s)")
+
+    payload: Dict[str, Any] = {
+        "model": resolved_model,
+        "messages": anthropic_messages,
+        "max_tokens": kwargs.get("max_tokens", 16384),
+    }
+    if system_prompt is not None:
+        payload["system"] = system_prompt
+    if tools:
+        payload["tools"] = _to_anthropic_tools(tools)
+    if "temperature" in kwargs:
+        payload["temperature"] = kwargs["temperature"]
+
+    # Debug: 检查 cache_control 是否存在
+    cache_control_count = 0
+    if isinstance(system_prompt, list):
+        for block in system_prompt:
+            if isinstance(block, dict) and "cache_control" in block:
+                cache_control_count += 1
+    for msg in anthropic_messages:
+        content = msg.get("content", "")
+        if isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict) and "cache_control" in block:
+                    cache_control_count += 1
+    if cache_control_count > 0:
+        print(f"[OpenRouter/Anthropic] 发现 {cache_control_count} 个 cache_control 标记")
+        logger.info(f"[OpenRouter/Anthropic] 发现 {cache_control_count} 个 cache_control 标记")
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json",
+        "HTTP-Referer": "https://github.com/your-repo",
+        "X-Title": "Agent Framework",
+    }
+
+    max_retries = 3
+    last_exception = None
+    for attempt in range(max_retries):
+        async with httpx.AsyncClient(timeout=300.0) as client:
+            try:
+                response = await client.post(endpoint, json=payload, headers=headers)
+                response.raise_for_status()
+                result = response.json()
+                break
+
+            except httpx.HTTPStatusError as e:
+                status = e.response.status_code
+                error_body = e.response.text
+                if status in (429, 500, 502, 503, 504) and attempt < max_retries - 1:
+                    wait = 2 ** attempt * 2
+                    logger.warning(
+                        "[OpenRouter/Anthropic] HTTP %d (attempt %d/%d), retrying in %ds: %s",
+                        status, attempt + 1, max_retries, wait, error_body[:200],
+                    )
+                    await asyncio.sleep(wait)
+                    last_exception = e
+                    continue
+                # Log AND print error body so it is visible in console output
+                logger.error("[OpenRouter/Anthropic] HTTP %d error body: %s", status, error_body)
+                print(f"[OpenRouter/Anthropic] API Error {status}: {error_body[:500]}")
+                raise
+
+            except _RETRYABLE_EXCEPTIONS as e:
+                last_exception = e
+                if attempt < max_retries - 1:
+                    wait = 2 ** attempt * 2
+                    logger.warning(
+                        "[OpenRouter/Anthropic] %s (attempt %d/%d), retrying in %ds",
+                        type(e).__name__, attempt + 1, max_retries, wait,
+                    )
+                    await asyncio.sleep(wait)
+                    continue
+                raise
+    else:
+        raise last_exception  # type: ignore[misc]
+
+    # 解析 Anthropic 响应 → 统一格式
+    parsed = _parse_anthropic_response(result)
+    usage = parsed["usage"]
+    cost = calculate_cost(model, usage)
+
+    return {
+        "content": parsed["content"],
+        "tool_calls": parsed["tool_calls"],
+        "prompt_tokens": usage.input_tokens,
+        "completion_tokens": usage.output_tokens,
+        "reasoning_tokens": usage.reasoning_tokens,
+        "cache_creation_tokens": usage.cache_creation_tokens,
+        "cache_read_tokens": usage.cache_read_tokens,
+        "finish_reason": parsed["finish_reason"],
+        "cost": cost,
+        "usage": usage,
+    }
+
+
 async def openrouter_llm_call(
     messages: List[Dict[str, Any]],
     model: str = "anthropic/claude-sonnet-4.5",
@@ -159,6 +624,12 @@ async def openrouter_llm_call(
     if not api_key:
         raise ValueError("OPEN_ROUTER_API_KEY environment variable not set")
 
+    # Claude 模型走 Anthropic 原生端点，其余走 OpenAI 兼容端点
+    provider = _detect_provider_from_model(model)
+    if provider == "anthropic":
+        logger.debug("[OpenRouter] Routing Claude model to Anthropic native endpoint")
+        return await _openrouter_anthropic_call(messages, model, tools, api_key, **kwargs)
+
     base_url = "https://openrouter.ai/api/v1"
     endpoint = f"{base_url}/chat/completions"
 

agent/llm/yescode.py

@@ -212,7 +212,13 @@ def _convert_messages_to_anthropic(messages: List[Dict[str, Any]]) -> tuple:
             if tool_calls:
                 content_blocks = []
                 if content:
-                    content_blocks.append({"type": "text", "text": content})
+                    # content 可能已被 _add_cache_control 转成 list（含 cache_control），
+                    # 也可能是普通字符串。两者都需要正确处理，避免产生 {"type":"text","text":[...]}
+                    converted = _convert_content_to_anthropic(content)
+                    if isinstance(converted, list):
+                        content_blocks.extend(converted)
+                    elif isinstance(converted, str) and converted.strip():
+                        content_blocks.append({"type": "text", "text": converted})
                 for tc in tool_calls:
                     func = tc.get("function", {})
                     args_str = func.get("arguments", "{}")

agent/memory/skills/browser.md

@@ -0,0 +1,35 @@
+---
+name: browser
+description: 浏览器自动化工具使用指南
+---
+
+## 浏览器工具使用指南
+
+所有浏览器工具都以 `browser_` 为前缀。浏览器会话会持久化，无需每次重新启动。
+
+### 基本工作流程
+
+1. **页面导航**: 使用 `browser_navigate_to_url` 或 `browser_search_web` 到达目标页面
+2. **等待加载**: 页面跳转后调用 `browser_wait(seconds=2)` 等待内容加载
+3. **获取元素索引**: 调用 `browser_get_visual_selector_map` 获取可交互元素的索引映射和当前界面的截图
+4. **执行交互**: 使用 `browser_click_element`、`browser_input_text` 等工具操作页面
+5. **提取内容**: 使用 `browser_extract_content`, `browser_read_long_content`, `browser_get_page_html` 获取数据
+
+### 关键原则
+
+- **禁止模拟结果**：不要输出你认为的搜索结果，而是要调用工具获取真实结果
+- **必须先获取索引**: 所有 `index` 参数都需要先通过 `browser_get_selector_map` 获取
+- **高级工具**：优先使用 `browser_extract_content`, `browser_read_long_content` 等工具获取数据，而不是使用 `browser_get_selector_map` 获取索引后手动解析
+- **操作后等待**: 任何可能触发页面变化的操作（点击、输入、滚动）后都要调用 `browser_wait`
+- **登录处理**:
+  - **正常登录**：当遇到需要登录的网页时，使用 `browser_load_cookies` 来登录
+  - **首次登录**：当没有该网站的 cookie 时，点击进入登录界面，然后等待人类来登录，登录后使用 `browser_export_cookies` 将账户信息存储下来
+- **复杂操作用JS**: 当标准工具无法满足时，使用 `browser_evaluate` 执行 JavaScript 代码
+
+### 工具分类
+
+**导航**: browser_navigate_to_url, browser_search_web, browser_go_back, browser_wait
+**交互**: browser_click_element, browser_input_text, browser_send_keys, browser_upload_file
+**视图**: browser_scroll_page, browser_find_text, browser_screenshot
+**提取**: browser_extract_content, browser_read_long_content, browser_get_page_html, browser_get_selector_map, browser_get_visual_selector_map
+**高级**: browser_evaluate, browser_load_cookies, browser_export_cookies, browser_wait_for_user_action, browser_download_direct_url

agent/memory/skills/core.md

@@ -65,6 +65,12 @@ goal(abandon="方案A需要Redis，环境没有")
 4. **计划可调整**：根据执行情况随时追加、跳过或放弃目标
 5. **使用 ID 定位**：focus、after、under 参数使用目标的 ID（如 "1", "2.1"）
 
+### 经验复用
+
+在**启动新任务**、**拆分复杂目标**或**遇到执行障碍**时，应主动调用 `get_experience` 获取k条历史成功经验或避坑指南。
+**使用示例：**
+`get_experience(query="如何处理浏览器点击不生效的问题")`
+
 ## 信息调研
 
 你可以通过联网搜索工具`search_posts`获取来自Github、小红书、微信公众号、知乎等渠道的信息。对于需要深度交互的网页内容，使用浏览器工具进行操作。

agent/memory/skills/planning.md

@@ -0,0 +1,65 @@
+---
+name: planning
+description: 计划管理，使用 goal 工具管理执行计划和目标树
+---
+
+## 计划与执行
+
+使用 `goal` 工具管理执行计划。目标树是你的工作记忆——系统会定期将当前计划注入给你，帮助你追踪进度和关键结论。
+
+### 核心原则
+
+- **先明确目标再行动**：开始执行前，用 `goal` 明确当前要做什么
+- **灵活运用，不受约束**：
+  - 可以先做全局规划再行动：`goal(add="调研方案, 实现方案, 测试验证")`
+  - 可以走一步看一步，每次只规划下一个目标
+  - 行动中可以动态放弃并调整：`goal(abandon="方案不可行")`
+  - 规划本身可以作为一个目标（如 "调研并确定技术方案"）
+- **简单任务只需一个目标**：`goal(add="将CSV转换为JSON")` 即可，不需要强制拆分
+
+### 使用方式
+
+创建目标：
+
+```
+goal(add="调研并确定方案, 执行方案, 评估结果")
+```
+
+聚焦并开始执行（使用计划视图中的 ID，如 "1", "2.1"）：
+
+```
+goal(focus="1")
+```
+
+完成目标，记录**关键结论**（不是过程描述）：
+
+```
+goal(done="最佳方案是openpose，精度高且支持多人检测")
+```
+
+完成并切换到下一个：
+
+```
+goal(done="openpose方案确认可行", focus="2")
+```
+
+添加子目标或同级目标：
+
+```
+goal(add="设计接口, 实现代码", under="2")
+goal(add="编写文档", after="2")
+```
+
+放弃不可行的目标：
+
+```
+goal(abandon="方案A需要Redis，环境没有")
+```
+
+### 使用规范
+
+1. **聚焦到具体目标**：始终将焦点放在你正在执行的最具体的子目标上，而不是父目标。创建子目标后立即 `focus` 到第一个要执行的子目标。完成后用 `done` + `focus` 切换到下一个。
+2. **同时只有一个目标处于执行中**：完成当前目标后再切换
+3. **summary 记录结论**：记录关键发现，而非 "已完成调研" 这样无信息量的描述
+4. **计划可调整**：根据执行情况随时追加、跳过或放弃目标
+5. **使用 ID 定位**：focus、after、under 参数使用目标的 ID（如 "1", "2.1"）

agent/memory/skills/research.md

@@ -0,0 +1,10 @@
+---
+name: research
+description: 信息调研，使用搜索工具和浏览器获取外部信息
+---
+
+## 信息调研
+
+你可以通过联网搜索工具 `search_posts` 获取来自 Github、小红书、微信公众号、知乎等渠道的信息。对于需要深度交互的网页内容，使用浏览器工具进行操作。
+
+调研过程可能需要多次搜索，比如基于搜索结果中获得的启发或信息启动新的搜索，直到得到令人满意的答案。你可以使用 `goal` 工具管理搜索的过程，或者使用文档记录搜索的中间或最终结果。

agent/tools/builtin/__init__.py

@@ -15,6 +15,7 @@ from agent.tools.builtin.file.grep import grep_content
 from agent.tools.builtin.bash import bash_command
 from agent.tools.builtin.skill import skill, list_skills
 from agent.tools.builtin.subagent import agent, evaluate
+from agent.tools.builtin.experience import get_experience
 from agent.tools.builtin.search import search_posts, get_search_suggestions
 from agent.tools.builtin.sandbox import (sandbox_create_environment, sandbox_run_shell,
                                          sandbox_rebuild_with_ports,sandbox_destroy_environment)
@@ -34,6 +35,7 @@ __all__ = [
     # 系统工具
     "bash_command",
     "skill",
+    "get_experience",
     "list_skills",
     "agent",
     "evaluate",

agent/tools/builtin/experience.py

@@ -0,0 +1,487 @@
+import logging
+import os
+import yaml
+import json
+import asyncio
+import re
+from typing import List, Optional, Dict, Any
+from datetime import datetime
+from ...llm.openrouter import openrouter_llm_call
+
+logger = logging.getLogger(__name__)
+
+# 默认经验存储路径（当无法从 context 获取时使用）
+DEFAULT_EXPERIENCES_PATH = "./.cache/experiences_0.md"
+
+def _get_experiences_path(context: Optional[Any] = None) -> str:
+    """
+    从 context 中获取 experiences_path，回退到默认路径。
+
+    context 可能包含 runner 引用，从中读取配置的路径。
+    """
+    if context and isinstance(context, dict):
+        runner = context.get("runner")
+        if runner and hasattr(runner, "experiences_path"):
+            path = runner.experiences_path or DEFAULT_EXPERIENCES_PATH
+            print(f"[Experience] 使用 runner 配置的路径: {runner.experiences_path}")
+            return path
+
+    print(f"[Experience] 使用默认路径: {DEFAULT_EXPERIENCES_PATH}")
+    return DEFAULT_EXPERIENCES_PATH
+
+# ===== 经验进化重写 =====
+async def _evolve_body_with_llm(old_body: str, feedback: str) -> str:
+    """
+    使用检索级别的小模型 (Flash Lite) 执行经验进化重写。
+    """
+    prompt = f"""你是一个 AI Agent 经验库管理员。请根据反馈建议，对现有的 ACE 规范经验进行重写进化。
+
+【原经验内容】:
+{old_body}
+
+【实战反馈建议】:
+{feedback}
+
+【重写要求】:
+1. 保持 ACE 规范：当 [条件/Context] 时，应该 [动作/Action]（原因：[逻辑/Reason]）。
+2. 融合知识：将反馈中的避坑指南、新参数或修正后的选择逻辑融入原经验，使其更具通用性和准确性。
+3. 语言：简洁直接，使用中文。
+4. 禁止：严禁输出任何开场白、解释语或 Markdown 标题，直接返回重写后的正文。
+"""
+    try:
+        # 调用与检索路由相同的廉价模型
+        response = await openrouter_llm_call(
+            messages=[{"role": "user", "content": prompt}],
+            model="google/gemini-2.0-flash-001" 
+        )
+        
+        evolved_content = response.get("content", "").strip()
+        
+        # 简单安全校验：如果 LLM 返回太短或为空，回退到原内容+追加
+        if len(evolved_content) < 5:
+            raise ValueError("LLM output too short")
+            
+        return evolved_content
+        
+    except Exception as e:
+        logger.warning(f"小模型进化失败，采用追加模式回退: {e}")
+        timestamp = datetime.now().strftime('%Y-%m-%d')
+        return f"{old_body}\n- [Update {timestamp}]: {feedback}"
+    
+# ===== 核心挑选逻辑 =====
+
+async def _route_experiences_by_llm(query_text: str, metadata_list: List[Dict], k: int = 3) -> List[str]:
+    """
+    第一阶段：语义路由。
+    让 LLM 挑选出 2*k 个语义相关的 ID。
+    """
+    if not metadata_list:
+        return []
+
+    # 扩大筛选范围到 2*k
+    routing_k = k * 2
+    
+    routing_data = [
+        {
+            "id": m["id"],
+            "tags": m["tags"],
+            "helpful": m["metrics"]["helpful"]
+        } for m in metadata_list
+    ]
+
+    prompt = f"""
+你是一个经验检索专家。根据用户的当前意图，从下列经验元数据中挑选出最相关的最多 {routing_k} 个经验 ID。
+意图："{query_text}"
+
+可选经验列表：
+{json.dumps(routing_data, ensure_ascii=False, indent=1)}
+
+请直接输出 ID 列表，用逗号分隔（例如: ex_01, ex_02）。若无相关项请输出 "None"。
+"""
+
+    try:
+        print(f"\n[Step 1: 语义路由] 意图: '{query_text}' | 候选总数: {len(metadata_list)} | 目标提取数: {routing_k}")
+        
+        response = await openrouter_llm_call(
+            messages=[{"role": "user", "content": prompt}],
+            model="google/gemini-2.0-flash-001" 
+        )
+        
+        content = response.get("content", "").strip()
+        selected_ids = [idx.strip() for idx in re.split(r'[,\s]+', content) if idx.strip().startswith("ex_")]
+        
+        print(f"[Step 1: 语义路由] LLM 初选 ID ({len(selected_ids)}个): {selected_ids}")
+        return selected_ids
+    except Exception as e:
+        logger.error(f"LLM 经验路由失败: {e}")
+        return []
+
+async def _get_structured_experiences(query_text: str, top_k: int = 3, context: Optional[Any] = None):
+    """
+    1. 解析物理文件
+    2. 语义路由：提取 2*k 个 ID
+    3. 质量精排：基于 Metrics 筛选出最终的 k 个
+    """
+    print(f"[Experience System]  runner.experiences_path:  {context.get('runner').experiences_path if context and context.get('runner') else None}")
+    experiences_path = _get_experiences_path(context)
+
+    if not os.path.exists(experiences_path):
+        print(f"[Experience System] 警告: 经验文件不存在 ({experiences_path})")
+        return []
+
+    with open(experiences_path, "r", encoding="utf-8") as f:
+        file_content = f.read()
+
+    # --- 阶段 1: 解析 ---
+    # 使用正则表达式匹配 YAML frontmatter 块，避免误分割
+    pattern = r'---\n(.*?)\n---\n(.*?)(?=\n---\n|\Z)'
+    matches = re.findall(pattern, file_content, re.DOTALL)
+
+    content_map = {}
+    metadata_list = []
+
+    for yaml_str, raw_body in matches:
+        try:
+            metadata = yaml.safe_load(yaml_str)
+
+            # 检查 metadata 类型
+            if not isinstance(metadata, dict):
+                logger.error(f"跳过损坏的经验块: metadata 不是 dict，而是 {type(metadata).__name__}")
+                continue
+
+            eid = metadata.get("id")
+            if not eid:
+                logger.error("跳过损坏的经验块: 缺少 id 字段")
+                continue
+
+            meta_item = {
+                "id": eid,
+                "tags": metadata.get("tags", {}),
+                "metrics": metadata.get("metrics", {"helpful": 0, "harmful": 0}),
+            }
+            metadata_list.append(meta_item)
+            content_map[eid] = {
+                "content": raw_body.strip(),
+                "metrics": meta_item["metrics"]
+            }
+        except Exception as e:
+            logger.error(f"跳过损坏的经验块: {e}")
+            continue
+
+    # --- 阶段 2: 语义路由 (取 2*k) ---
+    candidate_ids = await _route_experiences_by_llm(query_text, metadata_list, k=top_k)
+
+    # --- 阶段 3: 质量精排 (根据 Metrics 选出最终的 k) ---
+    print(f"[Step 2: 质量精排] 正在根据 Metrics 对候选经验进行打分...")
+    scored_items = []
+    
+    for eid in candidate_ids:
+        if eid in content_map:
+            item = content_map[eid]
+            metrics = item["metrics"]
+            # 计算综合分：Helpful 是正分，Harmful 是双倍惩罚扣分
+            quality_score = metrics["helpful"] - (metrics["harmful"] * 2.0)
+            
+            # 过滤门槛：如果被标记为严重有害（score < -2），直接丢弃
+            if quality_score < -2:
+                print(f"  - 剔除有害经验: {eid} (Helpful: {metrics['helpful']}, Harmful: {metrics['harmful']})")
+                continue
+                
+            scored_items.append({
+                "id": eid,
+                "content": item["content"],
+                "helpful": metrics["helpful"],
+                "quality_score": quality_score
+            })
+
+    # 按照质量分排序，质量分相同时按 helpful 排序
+    final_sorted = sorted(scored_items, key=lambda x: (x["quality_score"], x["helpful"]), reverse=True)
+    
+    # 截取最终的 top_k
+    result = final_sorted[:top_k]
+    
+    print(f"[Step 2: 质量精排] 最终选定经验: {[it['id'] for it in result]}")
+    print(f"[Experience System] 检索结束。\n")
+    return result
+
+async def _batch_update_experiences(update_map: Dict[str, Dict[str, Any]], context: Optional[Any] = None):
+    """
+    物理层：批量更新经验。
+    修正点：正确使用 new_sections 集合，确保文件结构的完整性与并发进化的同步。
+    """
+    experiences_path = _get_experiences_path(context)
+
+    if not os.path.exists(experiences_path) or not update_map:
+        return 0
+
+    with open(experiences_path, "r", encoding="utf-8") as f:
+        full_content = f.read()
+
+    # 使用正则表达式解析，避免误分割
+    pattern = r'---\n(.*?)\n---\n(.*?)(?=\n---\n|\Z)'
+    matches = re.findall(pattern, full_content, re.DOTALL)
+
+    new_entries = []
+    evolution_tasks = []
+    evolution_registry = {}  # task_idx -> entry_idx
+
+    # --- 第一阶段：处理所有块 ---
+    for yaml_str, body in matches:
+        try:
+            meta = yaml.safe_load(yaml_str)
+            if not isinstance(meta, dict):
+                logger.error(f"跳过损坏的经验块: metadata 不是 dict")
+                continue
+
+            eid = meta.get("id")
+            if not eid:
+                logger.error("跳过损坏的经验块: 缺少 id")
+                continue
+
+            if eid in update_map:
+                instr = update_map[eid]
+                action = instr.get("action")
+                feedback = instr.get("feedback")
+
+                # 处理 mixed 中间态
+                if action == "mixed":
+                    meta["metrics"]["helpful"] += 1
+                    action = "evolve"
+
+                if action == "helpful":
+                    meta["metrics"]["helpful"] += 1
+                elif action == "harmful":
+                    meta["metrics"]["harmful"] += 1
+                elif action == "evolve" and feedback:
+                    # 注册进化任务
+                    task = _evolve_body_with_llm(body.strip(), feedback)
+                    evolution_tasks.append(task)
+                    # 记录该任务对应的 entry 索引
+                    evolution_registry[len(evolution_tasks) - 1] = len(new_entries)
+                    meta["metrics"]["helpful"] += 1
+
+                meta["updated_at"] = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+
+            # 序列化并加入 new_entries
+            meta_str = yaml.dump(meta, allow_unicode=True).strip()
+            new_entries.append((meta_str, body.strip()))
+
+        except Exception as e:
+            logger.error(f"跳过损坏的经验块: {e}")
+            continue
+
+    # --- 第二阶段：并发进化 ---
+    if evolution_tasks:
+        print(f"🧬 并发处理 {len(evolution_tasks)} 条经验进化...")
+        evolved_results = await asyncio.gather(*evolution_tasks)
+
+        # 精准回填：替换对应 entry 的 body
+        for task_idx, entry_idx in evolution_registry.items():
+            meta_str, _ = new_entries[entry_idx]
+            new_entries[entry_idx] = (meta_str, evolved_results[task_idx].strip())
+
+    # --- 第三阶段：原子化写回 ---
+    final_parts = []
+    for meta_str, body in new_entries:
+        final_parts.append(f"---\n{meta_str}\n---\n{body}\n")
+
+    final_content = "\n".join(final_parts)
+    with open(experiences_path, "w", encoding="utf-8") as f:
+        f.write(final_content)
+
+    return len(update_map)
+
+# ===== 经验库瘦身 =====
+
+async def slim_experiences(model: str = "anthropic/claude-sonnet-4.5", context: Optional[Any] = None) -> str:
+    """
+    经验库瘦身：调用顶级大模型，将经验库中语义相似的经验合并精简。
+    返回瘦身报告字符串。
+    """
+    experiences_path = _get_experiences_path(context)
+
+    if not os.path.exists(experiences_path):
+        return "经验文件不存在，无需瘦身。"
+
+    with open(experiences_path, "r", encoding="utf-8") as f:
+        file_content = f.read()
+
+    # 使用正则表达式解析，避免误分割
+    pattern = r'---\n(.*?)\n---\n(.*?)(?=\n---\n|\Z)'
+    matches = re.findall(pattern, file_content, re.DOTALL)
+
+    parsed = []
+    for yaml_str, body in matches:
+        try:
+            meta = yaml.safe_load(yaml_str)
+            if not isinstance(meta, dict):
+                continue
+            parsed.append({"meta": meta, "body": body.strip()})
+        except Exception:
+            continue
+
+    if len(parsed) < 2:
+        return f"经验库仅有 {len(parsed)} 条，无需瘦身。"
+
+    # 构造发给大模型的内容
+    entries_text = ""
+    for p in parsed:
+        m = p["meta"]
+        entries_text += f"[ID: {m.get('id')}] [Tags: {m.get('tags', {})}] "
+        entries_text += f"[Metrics: {m.get('metrics', {})}]\n"
+        entries_text += f"{p['body']}\n\n"
+
+    prompt = f"""你是一个 AI Agent 经验库管理员。以下是当前经验库的全部条目，请执行瘦身操作：
+
+【任务】:
+1. 识别语义高度相似或重复的经验，将它们合并为一条更精炼、更通用的经验。
+2. 合并时保留 helpful 最高的那条的 ID 和 metrics（metrics 中 helpful/harmful 取各条之和）。
+3. 对于独立的、无重复的经验，保持原样不动。
+4. 保持 ACE 规范格式：当 [条件/Context] 时，应该 [动作/Action]（原因：[逻辑/Reason]）。
+
+【当前经验库】:
+{entries_text}
+
+【输出格式要求】:
+严格按以下格式输出每条经验，条目之间用 === 分隔：
+ID: <保留的id>
+TAGS: <yaml格式的tags>
+METRICS: <yaml格式的metrics>
+BODY: <合并后的经验正文>
+===
+
+最后一行输出合并报告，格式：
+REPORT: 原有 X 条，合并后 Y 条，精简了 Z 条。
+
+禁止输出任何开场白或解释。"""
+
+    try:
+        print(f"\n[经验瘦身] 正在调用 {model} 分析 {len(parsed)} 条经验...")
+        response = await openrouter_llm_call(
+            messages=[{"role": "user", "content": prompt}],
+            model=model
+        )
+        content = response.get("content", "").strip()
+        if not content:
+            return "大模型返回为空，瘦身失败。"
+
+        # 解析大模型输出，重建经验文件
+        report_line = ""
+        new_entries = []
+        blocks = [b.strip() for b in content.split("===") if b.strip()]
+
+        for block in blocks:
+            if block.startswith("REPORT:"):
+                report_line = block
+                continue
+
+            lines = block.split("\n")
+            eid, tags, metrics, body_lines = None, {}, {}, []
+            current_field = None
+            for line in lines:
+                if line.startswith("ID:"):
+                    eid = line[3:].strip()
+                    current_field = None
+                elif line.startswith("TAGS:"):
+                    try:
+                        tags = yaml.safe_load(line[5:].strip()) or {}
+                    except Exception:
+                        tags = {}
+                    current_field = None
+                elif line.startswith("METRICS:"):
+                    try:
+                        metrics = yaml.safe_load(line[8:].strip()) or {}
+                    except Exception:
+                        metrics = {"helpful": 0, "harmful": 0}
+                    current_field = None
+                elif line.startswith("BODY:"):
+                    body_lines.append(line[5:].strip())
+                    current_field = "body"
+                elif current_field == "body":
+                    body_lines.append(line)
+
+            if eid and body_lines:
+                meta = {
+                    "id": eid,
+                    "tags": tags,
+                    "metrics": metrics,
+                    "updated_at": datetime.now().strftime('%Y-%m-%d %H:%M:%S'),
+                }
+                meta_str = yaml.dump(meta, allow_unicode=True).strip()
+                body_str = "\n".join(body_lines).strip()
+                new_entries.append(f"---\n{meta_str}\n---\n{body_str}\n")
+
+        if not new_entries:
+            return "解析大模型输出失败，经验库未修改。"
+
+        # 写回文件
+        final = "\n".join(new_entries)
+        with open(experiences_path, "w", encoding="utf-8") as f:
+            f.write(final)
+
+        result = f"瘦身完成：{len(parsed)} → {len(new_entries)} 条经验。"
+        if report_line:
+            result += f"\n{report_line}"
+        print(f"[经验瘦身] {result}")
+        return result
+
+    except Exception as e:
+        logger.error(f"经验瘦身失败: {e}")
+        return f"瘦身失败: {e}"
+
+# ===== 对外 Tool 接口 =====
+
+from agent.tools import tool, ToolContext
+
+@tool(description="通过两阶段检索获取最相关的历史经验")
+async def get_experience(query: str, k: int = 3, context: Optional[ToolContext] = None):
+    """
+    通过两阶段检索获取最相关的历史经验。
+    第一阶段语义匹配(2*k)，第二阶段质量精排(k)。
+    """
+    relevant_items = await _get_structured_experiences(
+        query_text=query,
+        top_k=k,
+        context=context
+    )
+
+    if not relevant_items:
+        return "未找到足够相关的优质经验。"
+
+    return {
+        "items": relevant_items,
+        "count": len(relevant_items)
+    }
+
+@tool()
+async def update_experiences(feedback_list: List[Dict[str, Any]], context: Optional[ToolContext] = None):
+    """
+    批量反馈历史经验的有效性。
+    
+    Args:
+        feedback_list: 评价列表，每个元素包含:
+            - ex_id: (str) 经验 ID
+            - is_effective: (bool) 是否有效
+            - feedback: (str, optional) 改进建议，若有效且有建议则触发经验进化
+    """
+    if not feedback_list:
+        return "反馈列表为空。"
+
+    # 将 Agent 的输入转换为底层函数需要的映射表格式
+    update_map = {}
+    for item in feedback_list:
+        ex_id = item.get("ex_id")
+        is_effective = item.get("is_effective")
+        comment = item.get("feedback", "")
+
+        action = "helpful" if is_effective else "harmful"
+        if is_effective and comment:
+            action = "evolve"
+        
+        update_map[ex_id] = {
+            "action": action,
+            "feedback": comment
+        }
+
+    count = await _batch_update_experiences(update_map, context)
+    return f"成功同步了 {count} 条经验的反馈。感谢你的评价！"

agent/tools/builtin/file/read.py

@@ -11,9 +11,13 @@ Read Tool - 文件读取工具
 """
 
 import os
+import base64
 import mimetypes
 from pathlib import Path
 from typing import Optional
+from urllib.parse import urlparse
+
+import httpx
 
 from agent.tools import tool, ToolResult, ToolContext
 
@@ -23,7 +27,7 @@ MAX_LINE_LENGTH = 2000
 MAX_BYTES = 50 * 1024  # 50KB
 
 
-@tool(description="读取文件内容，支持文本文件、图片、PDF 等多种格式")
+@tool(description="读取文件内容，支持文本文件、图片、PDF 等多种格式，也支持 HTTP/HTTPS URL")
 async def read_file(
     file_path: str,
     offset: int = 0,
@@ -36,7 +40,7 @@ async def read_file(
     参考 OpenCode 实现
 
     Args:
-        file_path: 文件路径（绝对路径或相对路径）
+        file_path: 文件路径（绝对路径、相对路径或 HTTP/HTTPS URL）
         offset: 起始行号（从 0 开始）
         limit: 读取行数（默认 2000 行）
         context: 工具上下文
@@ -44,6 +48,11 @@ async def read_file(
     Returns:
         ToolResult: 文件内容
     """
+    # 检测是否为 HTTP/HTTPS URL
+    parsed = urlparse(file_path)
+    if parsed.scheme in ("http", "https"):
+        return await _read_from_url(file_path)
+
     # 解析路径
     path = Path(file_path)
     if not path.is_absolute():
@@ -79,13 +88,25 @@ async def read_file(
 
     # 图片文件（参考 opencode:66-91）
     if mime_type.startswith("image/") and mime_type not in ["image/svg+xml", "image/vnd.fastbidsheet"]:
-        # 注意：实际项目中需要实现图片的 base64 编码
-        # 这里简化处理
-        return ToolResult(
-            title=path.name,
-            output=f"图片文件: {path.name} (MIME: {mime_type})",
-            metadata={"mime_type": mime_type, "truncated": False}
-        )
+        try:
+            raw = path.read_bytes()
+            b64_data = base64.b64encode(raw).decode("ascii")
+            return ToolResult(
+                title=path.name,
+                output=f"图片文件: {path.name} (MIME: {mime_type}, {len(raw)} bytes)",
+                metadata={"mime_type": mime_type, "truncated": False},
+                images=[{
+                    "type": "base64",
+                    "media_type": mime_type,
+                    "data": b64_data,
+                }],
+            )
+        except Exception as e:
+            return ToolResult(
+                title=path.name,
+                output=f"图片文件读取失败: {path.name}: {e}",
+                error=str(e),
+            )
 
     # PDF 文件
     if mime_type == "application/pdf":
@@ -225,3 +246,74 @@ def _is_binary_file(path: Path) -> bool:
 
     except Exception:
         return False
+
+
+async def _read_from_url(url: str) -> ToolResult:
+    """
+    从 HTTP/HTTPS URL 读取文件内容。
+
+    主要用于图片等多媒体资源，自动转换为 base64。
+    """
+    try:
+        async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+            response = await client.get(url)
+            response.raise_for_status()
+
+            content_type = response.headers.get("content-type", "")
+            raw = response.content
+
+            # 从 URL 提取文件名
+            from urllib.parse import urlparse
+            parsed = urlparse(url)
+            filename = Path(parsed.path).name or "downloaded_file"
+
+            # 图片文件
+            if content_type.startswith("image/") or any(url.lower().endswith(ext) for ext in [".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp"]):
+                mime_type = content_type.split(";")[0] if content_type else "image/jpeg"
+                b64_data = base64.b64encode(raw).decode("ascii")
+                return ToolResult(
+                    title=filename,
+                    output=f"图片文件: {filename} (URL: {url}, MIME: {mime_type}, {len(raw)} bytes)",
+                    metadata={"mime_type": mime_type, "url": url, "truncated": False},
+                    images=[{
+                        "type": "base64",
+                        "media_type": mime_type,
+                        "data": b64_data,
+                    }],
+                )
+
+            # 文本文件
+            if content_type.startswith("text/") or content_type == "application/json":
+                text = raw.decode("utf-8", errors="replace")
+                lines = text.split("\n")
+                preview = "\n".join(lines[:20])
+                return ToolResult(
+                    title=filename,
+                    output=f"<file>\n{text}\n</file>",
+                    metadata={
+                        "preview": preview,
+                        "url": url,
+                        "mime_type": content_type,
+                        "total_lines": len(lines),
+                    }
+                )
+
+            # 其他二进制文件
+            return ToolResult(
+                title=filename,
+                output=f"二进制文件: {filename} (URL: {url}, {len(raw)} bytes)",
+                metadata={"url": url, "mime_type": content_type, "size": len(raw)}
+            )
+
+    except httpx.HTTPStatusError as e:
+        return ToolResult(
+            title="HTTP 错误",
+            output=f"无法下载文件: {url}\nHTTP {e.response.status_code}: {e.response.reason_phrase}",
+            error=str(e)
+        )
+    except Exception as e:
+        return ToolResult(
+            title="下载失败",
+            output=f"无法从 URL 读取文件: {url}\n错误: {str(e)}",
+            error=str(e)
+        )

agent/tools/builtin/subagent.py

@@ -276,6 +276,48 @@ def _build_evaluate_prompt(goal_description: str, messages: Optional[Messages])
     return "\n".join(lines)
 
 
+def _make_event_printer(label: str):
+    """
+    创建子 Agent 执行过程打印函数。
+
+    当父 runner.debug=True 时，传给 run_result(on_event=...)，
+    实时输出子 Agent 的工具调用和助手消息。
+    """
+    prefix = f"  [{label}]"
+
+    def on_event(item):
+        from agent.trace.models import Trace, Message
+        if isinstance(item, Message):
+            if item.role == "assistant":
+                content = item.content
+                if isinstance(content, dict):
+                    text = content.get("text", "")
+                    tool_calls = content.get("tool_calls")
+                    if text:
+                        preview = text[:120] + "..." if len(text) > 120 else text
+                        print(f"{prefix} {preview}")
+                    if tool_calls:
+                        for tc in tool_calls:
+                            name = tc.get("function", {}).get("name", "unknown")
+                            print(f"{prefix} 🛠️  {name}")
+            elif item.role == "tool":
+                content = item.content
+                if isinstance(content, dict):
+                    name = content.get("tool_name", "unknown")
+                    desc = item.description or ""
+                    desc_short = (desc[:60] + "...") if len(desc) > 60 else desc
+                    suffix = f": {desc_short}" if desc_short else ""
+                    print(f"{prefix} ✅ {name}{suffix}")
+        elif isinstance(item, Trace):
+            if item.status == "completed":
+                print(f"{prefix} ✓ 完成")
+            elif item.status == "failed":
+                err = (item.error_message or "")[:80]
+                print(f"{prefix} ✗ 失败: {err}")
+
+    return on_event
+
+
 # ===== 统一内部执行函数 =====
 
 async def _run_agents(
@@ -283,6 +325,8 @@ async def _run_agents(
     per_agent_msgs: List[Messages],
     continue_from: Optional[str],
     store, trace_id: str, goal_id: str, runner, context: dict,
+    agent_type: Optional[str] = None,
+    skills: Optional[List[str]] = None,
 ) -> Dict[str, Any]:
     """
     统一 agent 执行逻辑。
@@ -317,7 +361,7 @@ async def _run_agents(
             # continue_from 已经设置了 sub_trace_id
             pass
         else:
-            agent_type = "delegate" if single else "explore"
+            resolved_agent_type = agent_type or ("delegate" if single else "explore")
             suffix = "delegate" if single else f"explore-{i+1:03d}"
             stid = generate_sub_trace_id(trace_id, suffix)
 
@@ -327,7 +371,7 @@ async def _run_agents(
                 task=task_item,
                 parent_trace_id=trace_id,
                 parent_goal_id=goal_id,
-                agent_type=agent_type,
+                agent_type=resolved_agent_type,
                 uid=parent_trace.uid if parent_trace else None,
                 model=parent_trace.model if parent_trace else None,
                 status="running",
@@ -342,7 +386,7 @@ async def _run_agents(
             # 广播 sub_trace_started
             await broadcast_sub_trace_started(
                 trace_id, stid, goal_id or "",
-                agent_type, task_item,
+                resolved_agent_type, task_item,
             )
 
             if single:
@@ -363,16 +407,22 @@ async def _run_agents(
         agent_msgs = list(msgs) + [{"role": "user", "content": task_item}]
         allowed_tools = _get_allowed_tools(single, context)
 
+        debug = getattr(runner, 'debug', False)
+        agent_label = (agent_type or ("delegate" if single else f"explore-{i+1}"))
+        on_event = _make_event_printer(agent_label) if debug else None
+
         coro = runner.run_result(
             messages=agent_msgs,
             config=_make_run_config(
                 trace_id=cur_stid,
-                agent_type="delegate" if single else "explore",
+                agent_type=agent_type or ("delegate" if single else "explore"),
                 model=parent_trace.model if parent_trace else "gpt-4o",
                 uid=parent_trace.uid if parent_trace else None,
                 tools=allowed_tools,
                 name=task_item[:50],
+                skills=skills,
             ),
+            on_event=on_event,
         )
         coros.append((i, cur_stid, collab_name, coro))
 
@@ -492,6 +542,8 @@ async def agent(
     task: Union[str, List[str]],
     messages: Optional[Union[Messages, List[Messages]]] = None,
     continue_from: Optional[str] = None,
+    agent_type: Optional[str] = None,
+    skills: Optional[List[str]] = None,
     context: Optional[dict] = None,
 ) -> Dict[str, Any]:
     """
@@ -504,6 +556,8 @@ async def agent(
         task: 任务描述。字符串=单任务，列表=多任务并行
         messages: 预置消息。1D 列表=所有 agent 共享；2D 列表=per-agent
         continue_from: 继续已有 trace（仅单任务）
+        agent_type: 子 Agent 类型，决定 preset 和默认 skills（如 "deconstruct"）
+        skills: 附加到 system prompt 的 skill 名称列表，覆盖 preset 默认值
         context: 框架自动注入的上下文
     """
     if not context:
@@ -545,6 +599,8 @@ async def agent(
     return await _run_agents(
         tasks, per_agent_msgs, continue_from,
         store, trace_id, goal_id, runner, context,
+        agent_type=agent_type,
+        skills=skills,
     )
 
 
@@ -655,6 +711,7 @@ async def evaluate(
                 tools=allowed_tools,
                 name=f"评估: {goal_id}",
             ),
+            on_event=_make_event_printer("evaluate") if getattr(runner, 'debug', False) else None,
         )
 
         await broadcast_sub_trace_completed(

agent/trace/__init__.py

@@ -14,7 +14,6 @@ from .goal_models import Goal, GoalTree, GoalStatus, GoalType, GoalStats
 from .protocols import TraceStore
 from .store import FileSystemTraceStore
 from .trace_id import generate_trace_id, generate_sub_trace_id, parse_parent_trace_id
-from .goal_tool import set_goal_tree, get_goal_tree
 
 __all__ = [
     # Models
@@ -32,7 +31,4 @@ __all__ = [
     "generate_trace_id",
     "generate_sub_trace_id",
     "parse_parent_trace_id",
-    # Goal tool
-    "set_goal_tree",
-    "get_goal_tree",
 ]

agent/trace/compaction.py

@@ -190,8 +190,11 @@ def estimate_tokens(messages: List[Dict[str, Any]]) -> int:
             total_tokens += _estimate_text_tokens(content)
         elif isinstance(content, list):
             for part in content:
-                if isinstance(part, dict) and part.get("type") == "text":
-                    total_tokens += _estimate_text_tokens(part.get("text", ""))
+                if isinstance(part, dict):
+                    if part.get("type") == "text":
+                        total_tokens += _estimate_text_tokens(part.get("text", ""))
+                    elif part.get("type") in ("image_url", "image"):
+                        total_tokens += _estimate_image_tokens(part)
         # tool_calls
         tool_calls = msg.get("tool_calls")
         if tool_calls and isinstance(tool_calls, list):
@@ -226,6 +229,44 @@ def _estimate_text_tokens(text: str) -> int:
     return int(cjk_chars * 1.5) + other_chars // 4
 
 
+def _estimate_image_tokens(block: Dict[str, Any]) -> int:
+    """
+    估算图片块的 token 消耗。
+
+    Anthropic 计算方式：tokens = (width * height) / 750
+    优先从 _image_meta 读取真实尺寸，其次从 base64 数据量粗估，最小 1600 tokens。
+    """
+    MIN_IMAGE_TOKENS = 1600
+
+    # 优先使用 _image_meta 中的真实尺寸
+    meta = block.get("_image_meta")
+    if meta and meta.get("width") and meta.get("height"):
+        tokens = (meta["width"] * meta["height"]) // 750
+        return max(MIN_IMAGE_TOKENS, tokens)
+
+    # 回退：从 base64 数据长度粗估
+    b64_data = ""
+    if block.get("type") == "image":
+        source = block.get("source", {})
+        if source.get("type") == "base64":
+            b64_data = source.get("data", "")
+    elif block.get("type") == "image_url":
+        url_obj = block.get("image_url", {})
+        url = url_obj.get("url", "") if isinstance(url_obj, dict) else str(url_obj)
+        if url.startswith("data:"):
+            _, _, b64_data = url.partition(",")
+
+    if b64_data:
+        # base64 编码后大小约为原始字节的 4/3
+        raw_bytes = len(b64_data) * 3 // 4
+        # 粗估：假设 JPEG 压缩率 ~10:1，像素数 ≈ raw_bytes * 10 / 3 (RGB)
+        estimated_pixels = raw_bytes * 10 // 3
+        estimated_tokens = estimated_pixels // 750
+        return max(MIN_IMAGE_TOKENS, estimated_tokens)
+
+    return MIN_IMAGE_TOKENS
+
+
 def _is_cjk(ch: str) -> bool:
     """判断字符是否为 CJK（中日韩）字符"""
     cp = ord(ch)
@@ -256,21 +297,31 @@ def needs_level2_compression(
 
 # ===== Level 2: 压缩 Prompt =====
 
-COMPRESSION_PROMPT = """请对以上对话历史进行压缩总结。
+COMPRESSION_EVAL_PROMPT = """请对以上对话历史进行压缩总结，并评价所引用的历史经验。
+### 任务 1：评价已用经验
+本次任务参考了以下经验内容：{ex_reference_list}
 
+请对比“经验建议”与“实际执行轨迹”，给出三色打分：
+[[EVALUATION]]
+ID: ex_xxx | Result: helpful/harmful/mixed | Reason: [优点]... [局限/修正]...
+
+### 任务 2：对话历史摘要
 要求：
 1. 保留关键决策、结论和产出（如创建的文件、修改的代码、得出的分析结论）
 2. 保留重要的上下文（如用户的要求、约束条件、之前的讨论结果）
 3. 省略中间探索过程、重复的工具调用细节
 4. 使用结构化格式（标题 + 要点 + 相关资源引用，若有）
 5. 控制在 2000 字以内
+格式要求：
+[[SUMMARY]]
+(此处填写结构化的摘要内容)
 
-当前 GoalTree 状态（完整版，含 summary）：
+当前 GoalTree 状态：
 {goal_tree_prompt}
 """
 
 REFLECT_PROMPT = """请回顾以上整个执行过程，提取有价值的经验教训。
-
+你必须将经验与当前的任务意图（Intent）和环境状态（State）挂钩，以便未来精准检索。
 关注以下方面：
 1. 人工干预：用户中途的指令是否说明了原来的执行过程哪里有问题
 2. 弯路：哪些尝试是不必要的，有没有更直接的方法
@@ -278,6 +329,10 @@ REFLECT_PROMPT = """请回顾以上整个执行过程，提取有价值的经验
 4. 工具使用：哪些工具用法是高效的，哪些可以改进
 
 输出格式（严格遵守）：
+- 在每条经验前加一个[]中添加自定义的标签，标签要求总结实际的内容为若干词语，包括：
+    - intent: 当前的goal
+    - state: 环境状态（如果与工具相关，可以在标签中加入工具的名称）
+- 经验标签可用自然语言描述
 - 每条经验单独成段，格式固定为：- 当 [条件] 时，应该 [动作]（原因：[一句话说明]）。具体案例：[案例]
 - 条目之间用一个空行分隔
 - 不输出任何标题、分类、编号、分隔线或其他结构
@@ -286,16 +341,24 @@ REFLECT_PROMPT = """请回顾以上整个执行过程，提取有价值的经验
 - 只提取最有价值的 5-10 条，宁少勿滥
 
 示例（仅供参考格式，不要复制内容）：
-- 当用户说"给我示例"时，应该用真实数据而不是编造（原因：编造的示例无法验证质量）。具体案例：training_samples.json 中的示例全是 LLM 自己编造的，用户明确要求"基于我指定的样本"。
+- [intent:示例生成 state:用户提醒，指定样本] 当用户说"给我示例"时，应该用真实数据而不是编造（原因：编造的示例无法验证质量）。具体案例：training_samples.json 中的示例全是 LLM 自己编造的，用户明确要求"基于我指定的样本"。
 """
 
 
-def build_compression_prompt(goal_tree: Optional[GoalTree]) -> str:
-    """构建 Level 2 压缩 prompt"""
+def build_compression_prompt(goal_tree: Optional[GoalTree], used_ex_ids: Optional[List[str]] = None) -> str:
+    """构建 Level 2 压缩 prompt（含经验评估）"""
     goal_prompt = ""
     if goal_tree:
         goal_prompt = goal_tree.to_prompt(include_summary=True)
-    return COMPRESSION_PROMPT.format(goal_tree_prompt=goal_prompt)
+
+    ex_reference = "无（本次未引用历史经验）"
+    if used_ex_ids:
+        ex_reference = ", ".join(used_ex_ids)
+
+    return COMPRESSION_EVAL_PROMPT.format(
+        goal_tree_prompt=goal_prompt,
+        ex_reference_list=ex_reference,
+    )
 
 
 def build_reflect_prompt() -> str:

agent/trace/goal_tool.py

@@ -13,22 +13,6 @@ if TYPE_CHECKING:
     from .protocols import TraceStore
 
 
-# ===== 全局 GoalTree 状态管理 =====
-
-_current_goal_tree = None
-
-
-def set_goal_tree(tree):
-    """设置当前 GoalTree（由 AgentRunner 调用）"""
-    global _current_goal_tree
-    _current_goal_tree = tree
-
-
-def get_goal_tree():
-    """获取当前 GoalTree"""
-    return _current_goal_tree
-
-
 # ===== LLM 可调用的 goal 工具 =====
 
 @tool(description="管理执行计划，添加/完成/放弃目标，切换焦点")
@@ -53,12 +37,13 @@ async def goal(
         done: 完成当前目标，值为 summary
         abandon: 放弃当前目标，值为原因
         focus: 切换焦点到指定 ID
-        context: 工具执行上下文（包含 store 和 trace_id）
+        context: 工具执行上下文（包含 store、trace_id、goal_tree）
 
     Returns:
         str: 更新后的计划状态文本
     """
-    tree = get_goal_tree()
+    # GoalTree 从 context 获取，每个 agent 实例独立，不再依赖全局变量
+    tree = context.get("goal_tree") if context else None
     if tree is None:
         return "错误：GoalTree 未初始化"
 
@@ -130,10 +115,7 @@ async def goal_tool(
 
         # 推送事件
         if store and trace_id:
-            print(f"[DEBUG] goal_tool: calling store.update_goal for done: goal_id={goal.id}")
             await store.update_goal(trace_id, goal.id, status="completed", summary=done)
-        else:
-            print(f"[DEBUG] goal_tool: skip event push (store={store}, trace_id={trace_id})")
 
         # 检查是否有级联完成的父目标（complete方法已经处理，这里只需要记录）
         if goal.parent_id:
@@ -163,10 +145,7 @@ async def goal_tool(
 
         # 推送事件
         if store and trace_id:
-            print(f"[DEBUG] goal_tool: calling store.update_goal for abandon: goal_id={goal.id}")
             await store.update_goal(trace_id, goal.id, status="abandoned", summary=abandon)
-        else:
-            print(f"[DEBUG] goal_tool: skip event push (store={store}, trace_id={trace_id})")
 
     # 4. 处理 add
     if add is not None:
@@ -218,11 +197,8 @@ async def goal_tool(
 
             # 推送事件
             if store and trace_id:
-                print(f"[DEBUG] goal_tool: calling store.add_goal for {len(new_goals)} new goals")
                 for goal in new_goals:
                     await store.add_goal(trace_id, goal)
-            else:
-                print(f"[DEBUG] goal_tool: skip event push (store={store}, trace_id={trace_id})")
 
             # 如果没有焦点且添加了目标，自动 focus 到第一个新目标
             if not tree.current_id and new_goals:
@@ -230,6 +206,11 @@ async def goal_tool(
                 display_id = tree._generate_display_id(new_goals[0])
                 changes.append(f"自动切换焦点: {display_id}")
 
+    # 将完整内存树状态（含 current_id）同步到存储，
+    # 因为 store.add_goal / update_goal 各自从磁盘加载，不包含 focus 等内存变更
+    if store and trace_id and changes:
+        await store.update_goal_tree(trace_id, tree)
+
     # 返回当前状态
     result = []
     if changes:

agent/trace/models.py

@@ -200,12 +200,14 @@ class Message:
         msg: Dict[str, Any] = {"role": self.role}
 
         if self.role == "tool":
-            # tool message: tool_call_id + name + content(string)
+            # tool message: tool_call_id + name + content
             if self.tool_call_id:
                 msg["tool_call_id"] = self.tool_call_id
                 msg["name"] = self.description or "unknown"
             if isinstance(self.content, dict):
-                msg["content"] = str(self.content.get("result", self.content))
+                result = self.content.get("result", self.content)
+                # result 可能是 list（含图片的多模态内容）或字符串
+                msg["content"] = result if isinstance(result, list) else str(result)
             else:
                 msg["content"] = str(self.content) if self.content is not None else ""
 
@@ -405,11 +407,11 @@ class Message:
         # 只添加非空的可选字段
         if self.abandoned_at:
             result["abandoned_at"] = self.abandoned_at.isoformat()
-        if self.reasoning_tokens:
+        if self.reasoning_tokens is not None:
             result["reasoning_tokens"] = self.reasoning_tokens
-        if self.cache_creation_tokens:
+        if self.cache_creation_tokens is not None:
             result["cache_creation_tokens"] = self.cache_creation_tokens
-        if self.cache_read_tokens:
+        if self.cache_read_tokens is not None:
             result["cache_read_tokens"] = self.cache_read_tokens
         return result
 

agent/trace/run_api.py

@@ -15,6 +15,8 @@ Trace 控制 API — 新建 / 运行 / 停止 / 反思
 
 import asyncio
 import logging
+import re
+import uuid
 import os
 from datetime import datetime
 from typing import Any, Dict, List, Optional
@@ -73,9 +75,9 @@ class TraceRunRequest(BaseModel):
         default_factory=list,
         description="追加的新消息（可为空，用于重新生成场景）",
     )
-    after_sequence: Optional[int] = Field(
+    after_message_id: Optional[str] = Field(
         None,
-        description="从哪条消息后续跑。None = 从末尾续跑，int = 从该 sequence 后运行（自动判断续跑/回溯）",
+        description="从哪条消息后续跑。None = 从末尾续跑，message_id = 从该消息后运行（自动判断续跑/回溯）",
     )
 
 
@@ -271,17 +273,25 @@ async def _cleanup_incomplete_tool_calls(store, trace_id: str, after_sequence: i
     return safe
 
 
+def _parse_sequence_from_message_id(message_id: str) -> int:
+    """从 message_id 末尾解析 sequence 整数（格式：{trace_id}-{sequence:04d}）"""
+    try:
+        return int(message_id.rsplit("-", 1)[-1])
+    except (ValueError, IndexError):
+        raise HTTPException(
+            status_code=422,
+            detail=f"Invalid after_message_id format: {message_id!r}",
+        )
+
+
 @router.post("/{trace_id}/run", response_model=RunResponse)
 async def run_trace(trace_id: str, req: TraceRunRequest):
     """
     运行已有 Trace（统一续跑 + 回溯）
 
-    - after_sequence 为 null（或省略）：从末尾续跑
-    - after_sequence 为 int：从该 sequence 后运行（Runner 自动判断续跑/回溯）
-    - messages 为空 + after_sequence 为 int：重新生成（从该位置重跑，不插入新消息）
-
-    after_sequence 的值是 message 的 sequence 号。如果指定的 sequence 是一条带
-    tool_calls 的 assistant 消息，系统会自动扩展截断点到其所有 tool response 之后。
+    - after_message_id 为 null（或省略）：从末尾续跑
+    - after_message_id 为 message_id 字符串：从该消息后运行（Runner 自动判断续跑/回溯）
+    - messages 为空 + after_message_id 有值：重新生成（从该位置重跑，不插入新消息）
 
     **自动清理不完整工具调用**：
     如果人工插入 message 的位置打断了一个工具调用过程（assistant 消息有 tool_calls
@@ -291,6 +301,11 @@ async def run_trace(trace_id: str, req: TraceRunRequest):
 
     runner = _get_runner()
 
+    # 将 message_id 转换为内部使用的 sequence 整数
+    after_sequence: Optional[int] = None
+    if req.after_message_id is not None:
+        after_sequence = _parse_sequence_from_message_id(req.after_message_id)
+
     # 验证 trace 存在
     if runner.trace_store:
         trace = await runner.trace_store.get_trace(trace_id)
@@ -298,25 +313,25 @@ async def run_trace(trace_id: str, req: TraceRunRequest):
             raise HTTPException(status_code=404, detail=f"Trace not found: {trace_id}")
 
         # 自动检查并清理不完整的工具调用
-        if req.after_sequence is not None and req.messages:
+        if after_sequence is not None and req.messages:
             adjusted_seq = await _cleanup_incomplete_tool_calls(
-                runner.trace_store, trace_id, req.after_sequence
+                runner.trace_store, trace_id, after_sequence
             )
-            if adjusted_seq != req.after_sequence:
+            if adjusted_seq != after_sequence:
                 logger.info(
-                    f"已自动调整插入位置：{req.after_sequence} -> {adjusted_seq}"
+                    f"已自动调整插入位置：{after_sequence} -> {adjusted_seq}"
                 )
-                req.after_sequence = adjusted_seq
+                after_sequence = adjusted_seq
 
     # 检查是否已在运行
     if trace_id in _running_tasks and not _running_tasks[trace_id].done():
         raise HTTPException(status_code=409, detail="Trace is already running")
 
-    config = RunConfig(trace_id=trace_id, after_sequence=req.after_sequence)
+    config = RunConfig(trace_id=trace_id, after_sequence=after_sequence)
     task = asyncio.create_task(_run_in_background(trace_id, req.messages, config))
     _running_tasks[trace_id] = task
 
-    mode = "rewind" if req.after_sequence is not None else "continue"
+    mode = "rewind" if after_sequence is not None else "continue"
     return RunResponse(
         trace_id=trace_id,
         status="started",
@@ -388,30 +403,60 @@ async def reflect_trace(trace_id: str, req: ReflectRequest):
 
     # 以续跑方式运行：单轮无工具 LLM 调用
     config = RunConfig(trace_id=trace_id, max_iterations=1, tools=[])
-    reflection_text = ""
+    reflection_raw_text = ""
     try:
         result = await runner.run_result(
             messages=[{"role": "user", "content": prompt}],
             config=config,
         )
-        reflection_text = result.get("summary", "")
+        reflection_raw_text = result.get("summary", "")
     finally:
         # 恢复 head_sequence（反思消息成为侧枝，不影响主路径）
         await runner.trace_store.update_trace(trace_id, head_sequence=saved_head_sequence)
 
-    # 追加到 experiences 文件
-    if reflection_text:
+    # --- 开始结构化解析与处理 ---
+    structured_entries = []
+    # 正则解析：匹配 - [intent:..., state:...] 经验内容
+    pattern = r"- \[(intent:.*?, state:.*?)\] (.*)"
+    matches = re.findall(pattern, reflection_raw_text)
+
+    for tags_str, content in matches:
+        # 生成唯一短 ID
+        ex_id = f"ex_{datetime.now().strftime('%m%d%H%M')}_{uuid.uuid4().hex[:4]}"
+        
+        # 提取标签详情
+        intent_match = re.search(r"intent:(.*?),", tags_str)
+        state_match = re.search(r"state:(.*)", tags_str)
+        
+        intents = [i.strip() for i in intent_match.group(1).split(",")] if intent_match else []
+        states = [s.strip() for s in state_match.group(1).split(",")] if state_match else []
+
+        # 构造符合文档规范的结构化条目
+        entry = f"""---
+id: {ex_id}
+trace_id: {trace_id}
+tags: {{intent: {intents}, state: {states}}}
+metrics: {{helpful: 1, harmful: 0}}
+created_at: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+---
+- {content}
+- 引用策略 ID: [{ex_id}]
+"""
+        structured_entries.append(entry)
+
+    # 追加到经验文件
+    if structured_entries:
         experiences_path = getattr(runner, "experiences_path", "./.cache/experiences.md")
-        if experiences_path:
-            os.makedirs(os.path.dirname(experiences_path), exist_ok=True)
-            header = f"\n\n---\n\n## {trace_id} ({datetime.now().strftime('%Y-%m-%d %H:%M')})\n\n"
-            with open(experiences_path, "a", encoding="utf-8") as f:
-                f.write(header + reflection_text + "\n")
-            logger.info(f"Reflection appended to {experiences_path}")
+        os.makedirs(os.path.dirname(experiences_path), exist_ok=True)
+        
+        with open(experiences_path, "a", encoding="utf-8") as f:
+            f.write("\n\n" + "\n\n".join(structured_entries))
+        
+        logger.info(f"Successfully extracted {len(structured_entries)} structured experiences.")
 
     return ReflectResponse(
         trace_id=trace_id,
-        reflection=reflection_text,
+        reflection=reflection_raw_text,
     )
 
 

docs/README.md

@@ -60,8 +60,10 @@ agent/
 │   ├── protocols.py       # MemoryStore 接口
 │   ├── stores.py          # 存储实现
 │   ├── skill_loader.py    # Skill 加载器
-│   └── skills/            # 内置 Skills
-│       └── core.md        # Core Skill（自动加载）
+│   └── skills/            # 内置 Skills（自动注入 system prompt）
+│       ├── planning.md    # 计划与 Goal 工具使用
+│       ├── research.md    # 搜索与内容研究
+│       └── browser.md     # 浏览器自动化
 │
 ├── llm/                   # LLM 集成
 │   ├── gemini.py          # Gemini Provider
@@ -167,6 +169,7 @@ class RunConfig:
     agent_type: str = "default"
     uid: Optional[str] = None
     system_prompt: Optional[str] = None        # None = 从 skills 自动构建
+    skills: Optional[List[str]] = None         # 注入 system prompt 的 skill 名称列表；None = 按 preset 决定
     enable_memory: bool = True
     auto_execute_tools: bool = True
     name: Optional[str] = None                 # 显示名称（空则由 utility_llm 自动生成）
@@ -304,7 +307,7 @@ agent 工具的合成结果对齐正常返回值格式（含 `sub_trace_id` 字
 **实现**：`agent/core/runner.py:AgentRunner._heal_orphaned_tool_calls`
 
 - `run(messages, config)`：**核心方法**，流式返回 `AsyncIterator[Union[Trace, Message]]`
-- `run_result(messages, config)`：便利方法，内部消费 `run()`，返回结构化结果。主要用于 `agent`/`evaluate` 工具内部
+- `run_result(messages, config, on_event=None)`：便利方法，内部消费 `run()`，返回结构化结果。`on_event` 回调可实时接收每个 Trace/Message 事件（用于调试时输出子 Agent 执行过程）。主要用于 `agent`/`evaluate` 工具内部
 
 ### REST API
 
@@ -544,19 +547,24 @@ class AgentPreset:
     denied_tools: Optional[List[str]] = None   # 黑名单
     max_iterations: int = 30
     temperature: Optional[float] = None
+    skills: Optional[List[str]] = None         # 注入 system prompt 的 skill 名称列表；None = 加载全部
     description: Optional[str] = None
 
 
+_DEFAULT_SKILLS = ["planning", "research", "browser"]
+
 AGENT_PRESETS = {
     "default": AgentPreset(
         allowed_tools=None,
         max_iterations=30,
+        skills=_DEFAULT_SKILLS,
         description="默认 Agent，拥有全部工具权限",
     ),
     "explore": AgentPreset(
         allowed_tools=["read", "glob", "grep", "list_files"],
         denied_tools=["write", "edit", "bash", "task"],
         max_iterations=15,
+        skills=["planning"],
         description="探索型 Agent，只读权限，用于代码分析",
     ),
     "analyst": AgentPreset(
@@ -564,6 +572,7 @@ AGENT_PRESETS = {
         denied_tools=["write", "edit", "bash", "task"],
         temperature=0.3,
         max_iterations=25,
+        skills=["planning", "research"],
         description="分析型 Agent，用于深度分析和研究",
     ),
 }
@@ -571,7 +580,7 @@ AGENT_PRESETS = {
 
 **实现**：`agent/core/presets.py`
 
-**用户自定义**：项目级配置 `.agent/presets.json` 可覆盖或添加预设。
+**用户自定义**：项目级配置文件（如 `examples/how/presets.json`）可通过 `register_preset()` 注册额外预设。项目专用的 Agent 类型建议放在项目目录下，而非内置预设。
 
 ---
 
@@ -589,10 +598,15 @@ async def agent(
     task: Union[str, List[str]],
     messages: Optional[Union[Messages, List[Messages]]] = None,
     continue_from: Optional[str] = None,
+    agent_type: Optional[str] = None,
+    skills: Optional[List[str]] = None,
     context: Optional[dict] = None,
 ) -> Dict[str, Any]:
 ```
 
+- `agent_type`: 子 Agent 类型，决定工具权限和默认 skills（对应 `AgentPreset` 名称，如 `"deconstruct"`）
+- `skills`: 覆盖 preset 默认值，显式指定注入 system prompt 的 skill 列表
+
 **单任务（delegate）**：`task: str`
 - 创建单个 Sub-Trace
 - 完整工具权限（除 agent/evaluate 外，防止递归）
@@ -748,17 +762,32 @@ ToolResult(
 
 | 类型 | 加载位置 | 加载时机 |
 |------|---------|---------|
-| **Core Skill** | System Prompt | Agent 启动时自动加载 |
+| **内置 Skill** | System Prompt | Agent 启动时自动注入 |
+| **项目 Skill** | System Prompt | Agent 启动时按 preset/call-site 过滤后注入 |
 | **普通 Skill** | 对话消息 | 模型调用 `skill` 工具时 |
 
 ### 目录结构
 
 ```
-agent/memory/skills/
-├── core.md              # Core Skill（自动加载到 System Prompt）
-└── browser_use/         # 普通 Skill（按需加载）
+agent/memory/skills/         # 内置 Skills（始终加载）
+├── planning.md              # 计划与 Goal 工具使用
+├── research.md              # 搜索与内容研究
+└── browser.md               # 浏览器自动化
 
-./skills/                # 项目自定义 Skills（按需加载）
+./skills/                    # 项目自定义 Skills
+```
+
+### Skills 过滤（call-site 选择）
+
+不同 Agent 类型所需的 skills 不同。过滤优先级：
+
+1. `agent()` 工具的 `skills` 参数（显式指定，最高优先级）
+2. `AgentPreset.skills`（preset 默认值）
+3. `None`（加载全部，向后兼容）
+
+示例：调用子 Agent 时只注入解构相关 skill：
+```python
+agent(task="...", agent_type="deconstruct", skills=["planning", "deconstruct"])
 ```
 
 **实现**：`agent/memory/skill_loader.py`
@@ -771,7 +800,7 @@ agent/memory/skills/
 
 从执行历史中提取的经验规则，用于指导未来任务。
 
-### 存储
+### 存储规范
 
 经验以 Markdown 文件存储（默认 `./.cache/experiences.md`），人类可读、可编辑、可版本控制。
 
@@ -779,51 +808,76 @@ agent/memory/skills/
 
 ```markdown
 ---
-
-## trace-id-xxx (2026-02-12 15:30)
-
-- 当遇到 X 情况时，应该先 Y 再 Z
-- 分析代码前应先读取项目结构
-
+id: ex_001
+trace_id: trace-xxx
+category: tool_usage
+tags: {state: ["large_file", "dirty_repo"], intent: ["batch_edit", "safe_modify"]}
+metrics: {helpful: 12, harmful: 0}
+created_at: 2026-02-12 15:30
 ---
 
-## trace-id-yyy (2026-02-12 16:00)
-
-- 执行 bash 命令前应检查路径是否存在
+---
+id: ex_002
+...
 ```
+---
 
-### 反思机制（Reflect）
-
-通过 `POST /api/traces/{id}/reflect` 触发：
-
-1. 在 trace 末尾追加一条 user message（内置反思 prompt），**作为侧枝**（parent_sequence 分叉，不在主路径上）
-2. 使用 `max_iterations=1, tools=[]` 进行单轮无工具 LLM 调用，Agent 回顾整个执行过程生成经验总结
-3. 将 assistant 的反思内容追加到 `./.cache/experiences.md`
-4. 恢复 head_sequence（try/finally 保证异常时也恢复）
-
-反思消息不影响主对话路径。正常 continue/rewind 时看不到反思消息。
-
-反思 prompt 引导 Agent 关注：人工干预说明做错了什么、走了哪些弯路、哪些决策是对的。
-
-**实现**：`agent/trace/run_api.py:reflect_trace`
-
-### 注入
 
-新建 Trace 时，Runner 自动读取 `./.cache/experiences.md` 并追加到第一条 user message 末尾：
+### 反思机制（Reflect）
 
+通过 POST /api/traces/{id}/reflect 触发，旨在将原始执行历史提炼为可复用的知识。
+    1. 分叉反思：在 trace 末尾追加 user message（含反思与打标 Prompt），作为侧枝执行。
+    2. 结构化生成：
+        ·归类：将经验分配至 tool_usage（工具）、logic_flow（逻辑）、environment（环境）等。
+        ·打标：提取 state（环境状态）与 intent（用户意图）语义标签。
+        ·量化：初始 helpful 设为 1。
+    3. 持久化：将带有元数据的 Markdown 块追加至 experiences.md。
+
+实现：agent/trace/run_api.py:reflect_trace
+
+### 语义注入与匹配流程
+新建 Trace 时，Runner 采用“分析-检索-注入”三阶段策略，实现精准经验推荐。
+    1. 意图预分析
+    Runner 调用 utility_llm 对初始任务进行语义提取：
+        -输入："优化这个项目的 Docker 构建速度"
+        -输出：{state: ["docker", "ci"], intent: ["optimization"]}
+    2. 语义检索
+        在 _load_experiences 中根据标签进行语义匹配（优先匹配 intent，其次是 state），筛选出相关度最高的 Top-K 条经验。
+    3. 精准注入
+        将匹配到的经验注入第一条 user message 末尾：
 ```python
 # _build_history 中（仅新建模式）：
 if not config.trace_id:
-    experiences_text = self._load_experiences()  # 读取文件
-    if experiences_text:
-        first_user_msg["content"] += f"\n\n## 参考经验\n\n{experiences_text}"
+    relevant_ex = self.experience_retriever.search(task_tags)
+    if relevant_ex:
+        formatted_ex = "\n".join([f"- [{e.id}] {e.content} (Helpful: {e.helpful})" for e in relevant_ex])
+        first_user_msg["content"] += f"\n\n## 参考经验\n\n{formatted_ex}"
 ```
+实现：agent/core/runner.py:AgentRunner._build_history
 
-后续 continue/rewind 不重新注入（经验已在初始消息中）。
-
-**实现**：`agent/core/runner.py:AgentRunner._build_history`
+### 经验获取工具
+不再仅限于启动时自动注入，而是通过内置工具供 Agent 在需要时主动调用。当执行结果不符合预期或进入未知领域时，Agent 应优先使用此工具。
+工具定义：
 
----
+```python
+@tool(description="根据当前任务状态和意图，从经验库中检索相关的历史经验")
+async def get_experience(
+    intent: Optional[str] = None, 
+    state: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    参数:
+        intent: 想要达成的目标意图 (如 "optimization", "debug")
+        state: 当前环境或遇到的问题状态 (如 "docker_build_fail", "permission_denied")
+    """
+```
+实现： agent/tools/builtin/experience.py
+
+- 语义匹配与应用流程
+    当 Agent 调用 get_experience 时，系统执行以下逻辑：
+    1. 语义检索：根据传入的 intent 或 state 标签，在 experiences.md 中进行匹配。匹配权重：intent > state > helpful 评分。
+    2. 动态注入：工具返回匹配到的 Top-K 条经验（含 ID 和内容）。
+    3. 策略应用：Agent 接收到工具返回的经验后，需在后续 thought 中声明所选用的策略 ID（如 [ex_001]），并据此调整 goal_tree 或工具调用序列。
 
 ## Context 压缩
 

docs/ref/create.md

@@ -0,0 +1,98 @@
+---
+name: create
+description: 从创作层解构社交媒体帖子，提取叙事策略与选题价值（研究用，未接入系统）
+---
+
+## 角色
+
+你是内容创作策略分析专家。给定一篇优质社交媒体帖子，分析其**创作层**——内容策略、选题价值、叙事结构、文字策略——回答"这篇内容为什么值得创作，以及创作者如何讲述它"。
+
+与制作层解构（How to make）不同，创作层回答的是：**Why this content + How to tell it**。
+
+---
+
+## 创作层的核心概念
+
+**选题价值**（三点框架）
+- **灵感点**：是什么触发了创作者创作这篇内容？来自生活、趋势、热点、个人经历？
+- **目的点**：创作者想通过这篇内容达到什么？吸粉、种草、共鸣、教育？
+- **关键点**：这篇内容的核心价值主张是什么？受众为什么会喜欢？
+
+**内容权重**
+- 这篇内容以图片为主还是文字为主？谁承载了更多核心信息？
+- 图文是相辅相成，还是各自独立承载信息？
+
+**叙事结构**：创作者如何组织内容流程——从什么开始，经过什么，以什么结尾？图片之间的叙事逻辑是什么？
+
+---
+
+## 分析维度
+
+**内容品类**：这是什么类型的内容？（生活记录、好物分享、教程攻略、情感共鸣、观点输出……）
+
+**选题价值**：
+- 灵感点——触发创作的来源
+- 目的点——创作者的意图
+- 关键点——为什么受众会感兴趣
+
+**图文权重与关系**：
+- 核心信息载体（图 / 文 / 图文并重）
+- 图文是否相关，如何相互补充
+
+**叙事脚本结构**：
+- 整体叙事弧线（起承转合 / 问题-解决 / 情绪递进 / 对比展示……）
+- 各图承担的叙事角色
+- 图片间的连接逻辑
+
+**文字创作策略**：
+- 标题策略：吸引点在哪里、使用了什么钩子（数字、疑问、痛点、惊喜感）
+- 正文策略：节奏、语气、信息密度、与图片的配合方式
+
+---
+
+## 输出格式
+
+```json
+{
+  "内容品类": "string",
+
+  "选题价值": {
+    "灵感点": "是什么触发了这篇内容",
+    "目的点": "创作者想达到什么",
+    "关键点": "受众为什么会喜欢"
+  },
+
+  "图文关系": {
+    "核心载体": "图片为主 | 文字为主 | 图文并重",
+    "协作方式": "图文如何配合（互补 / 独立 / 图解文 / 文释图）"
+  },
+
+  "叙事结构": {
+    "弧线类型": "起承转合 | 问题-解决 | 情绪递进 | 对比展示 | ...",
+    "图片叙事": [
+      {"图片": "图片1", "叙事角色": "引入主体 / 建立情境..."},
+      {"图片": "图片2", "叙事角色": "展开 / 对比..."}
+    ]
+  },
+
+  "文字策略": {
+    "标题": "钩子类型与策略",
+    "正文": "节奏、语气、信息组织方式"
+  },
+
+  "核心洞察": "一句话：这篇内容在创作策略上为什么成功"
+}
+```
+
+---
+
+## 原则
+
+- **创作层优先**：分析"为什么创作这个内容 + 如何叙述它"，而非视觉制作细节
+- **受众视角**：始终思考受众为什么会停留、点赞、收藏、分享
+- **策略性而非描述性**：不是"图片展示了XX"，而是"通过XX实现了XX效果"
+- **与制作层互补**：创作层负责 Why + What to tell，制作层负责 How to make
+
+---
+
+> **注**：此文件仅供研究，未接入 Agent 系统。对应的系统工具是 `deconstruct`（制作层）。

docs/ref/deconstruct_old.md

@@ -0,0 +1,357 @@
+---
+name: deconstruct
+description: 制作还原解构方法论：将优质社交媒体帖子解构为可还原的结构化制作脚本
+---
+
+## 角色定位
+
+你是制作还原解构顾问。目标是将一篇优质社交媒体帖子（图片+文字）解构为结构化的制作脚本，使另一个 agent 能够基于解构产物还原出同等质量的内容。
+
+**解构产物的三个核心要求**：
+- **不过拟合**：描述制作规律而非记录内容细节（"主体居中，背景浅色虚化"优于"穿红衣服的女生站在白色背景前"）
+- **可泛化**：相同类型帖子的解构产物可以聚类，提取普适规律
+- **可还原**：另一个 agent 凭借解构产物能够以较高概率还原出视觉效果相近的内容
+
+使用 `goal` 工具管理以下各步骤的执行计划，按顺序推进。
+
+---
+
+## 步骤 1：内容过滤
+
+过滤正文中与核心主题无关的话题标签（hashtag）。
+
+**保留标准**（两项均通过才保留）：
+1. 与帖子主题或产品有直接关联
+2. 移除后不影响对核心内容的理解
+
+输出：过滤后的正文文本。
+
+---
+
+## 步骤 2：入口分析（内容视角）
+
+通过多图对比，判断这篇内容的核心表达方式。
+
+**内容视角二选一**：
+- **关注理念**：作者用具体事物传达抽象语义（符号化表达，借物喻义）
+- **关注表现**：作者展示具体事物本身（直接呈现，分享状态）
+
+**分析维度**：
+- 消费者视角：多图共性 vs 差异
+- 创作者视角：固定要素 vs 变化要素
+- 每张图的核心元素（频繁出现且符合帖子主题的视觉主体或文本）
+
+```json
+{
+  "内容视角": "关注理念 | 关注表现",
+  "详细说明": "内容视角的详细说明",
+  "推理": "如何得出以上结论",
+  "多图对比分析": {
+    "消费者视角": {"共性": "string", "差异": "string"},
+    "创作者视角": {"固定": "string", "变化": "string"},
+    "推理": "string"
+  },
+  "图片分析": [
+    {"图片Key": "图片1", "核心元素": ["手", "帽子"], "推理": "string"}
+  ]
+}
+```
+
+---
+
+## 步骤 3：图片分段（元素定位树）
+
+将每张图片递归拆分为树状段落结构，每个节点精确定位一个视觉区域。
+
+### 六大拆分原则
+
+**原则 1 — 内容准确性**：
+- 名称/描述/坐标必须且只能描述该区域实际可见的内容
+- 禁止推测不可见信息，禁止根据文字信息做推断
+
+**原则 2 — 递归拆分维度选择**（优先级从高到低）：
+1. 创作者语义拆分（最高优先）：作者创作意图导致的自然分组，如"标题区 vs 内容区"
+2. XY 轴拆分：水平或垂直方向的空间分割
+3. 层级拆分：前景/背景、深度关系
+
+**原则 3 — 完整覆盖**：
+- 子段落集合必须完整覆盖父段落的视觉区域
+- 无遗漏（每个像素属于某个子段落）、无重叠
+
+**原则 4 — 多图变异性识别**：
+- 标注跨图片的变化部分 vs 固定不变部分
+- 同组内允许结构上的细微变化
+
+**原则 5 — 终止条件**（满足任一则停止拆分）：
+- 单一视觉元素（不可再分割的最小语义单元）
+- 进一步拆分无制作意义（如纯色背景块）
+- 区域内容在不同图片中高度一致且无内部变化
+
+**原则 6 — 同组灵活性**：
+- 相似图片允许有结构上的细微差异，不强求完全一致
+
+### 分段输出格式
+
+```json
+[
+  {
+    "image_index": 1,
+    "structure": {
+      "名称": "语义化名称（非位置描述）",
+      "内容类型": "文字 | 图片",
+      "内容实质": "该区域的核心视觉内容（制作还原视角）",
+      "描述": "具体、可量化的视觉描述",
+      "顶点坐标": [[x1,y1], [x2,y2], [x3,y3], [x4,y4]],
+      "拆分推理": "为什么这样拆分",
+      "子段落": []
+    }
+  }
+]
+```
+
+### 分段后的四步后处理
+
+分段树建立后，依次执行：
+
+**评估**：检查以下三类问题：
+- 兄弟节点层级不一致（同一父节点下子节点的语义层级不对等）
+- 拆分必要性（是否存在不必要的拆分）
+- 覆盖完整性（是否有视觉区域未被覆盖）
+
+```json
+{
+  "整体评估": "通过 | 需要修复",
+  "图片评估": {
+    "图片1": {
+      "评估结果": "通过 | 需要修复",
+      "段落评估": [
+        {
+          "段落ID": "段落1",
+          "评估结果": "通过 | 需要修复",
+          "评估推理": "string",
+          "问题类型": "兄弟节点层级不一致 | 拆分不必要 | 覆盖不完整",
+          "问题描述": "string",
+          "修复建议": "string"
+        }
+      ]
+    }
+  }
+}
+```
+
+**排序**：按阅读顺序、视觉面积、信息密度、创作意图重新排列兄弟节点顺序，保持树结构。
+
+**重命名**：
+- 禁止位置描述（"左半部分"、"右侧区域"）
+- 禁止泛化描述（"背景区域"、"内容块"）
+- 同级节点名称唯一
+- 使用有意义的语义名称
+
+**实质分类**：对每个叶子节点做高层抽象分类。
+- 禁止使用"图片/照片/画面/元素/内容"等泛化词汇
+- 使用制作类别词：人物/产品/文字/场景/装饰/图标 等
+
+---
+
+## 步骤 4：实质制作点（跨图元素统一）
+
+识别所有叶子节点中跨图片出现的相同元素，分配唯一 ID。
+
+### 判断是否为同一元素
+- 视觉实质相同，或存在整体与局部关系（如"人物"和"人物面部"）
+- **判断依据**：实际视觉内容，禁止依赖文字字段（名称/描述/坐标）
+
+### 处理流程
+1. 收集所有叶子节点
+2. 文字元素：按内容实质分组（代码化，精确匹配）
+3. 图片元素：LLM 视觉比较分组
+4. 反思合并：识别被错误分开的组，合并为同一元素
+5. 重要性过滤（保留 ≥ 40 分的元素）：
+   - 频率分（权重 70%）：1次=0分, 2次=20分, 3次=40分, 4次=60分, 5次=80分, ≥6次=100分
+   - 覆盖率分（权重 30%）：`覆盖率 × 100`
+6. 统一命名（使用上位概念，避免歧义）
+7. 分配元素 ID：`元素1`, `元素2` ...
+
+```json
+[
+  {
+    "元素ID": "元素1",
+    "统一名称": "人物",
+    "统一描述": "女性，长发，戴眼镜，职业装，站立姿态",
+    "出现段落": ["段落1.1.1", "段落2.1", "段落3.1"],
+    "重要性得分": 85
+  }
+]
+```
+
+---
+
+## 步骤 5：图片形式分析
+
+从"如何还原元素"的视角，提取每个段落/元素的视觉呈现方式。
+
+**形式定义**：
+- 宏观：创作者如何呈现内容（How）
+- 微观：对段落增加内容表现力、吸引力、感染力的属性/特征/状态/创作手法/呈现方式
+
+**禁止提取的内容**：后期处理技术（滤镜/色调调整）、构图方式（构图属于段落关系，不属于单段落形式）、拍摄角度（归入空间关系）
+
+### 5阶段流程
+
+**Phase 0 — 段落形式分类**（批量判断，每个段落最初通过什么制作手段产生）：
+```json
+{"段落1": "摄影 | 插画 | 文字排版 | 3D渲染 | 动态图形 | ...", "段落1.2": "..."}
+```
+
+**Phase 1 — 形式维度发现**（发现原子的、不可再分的形式维度）：
+- 输出的是**维度名称**，不是维度值（"构图方式"而非"居中构图"）
+- 维度必须对当前段落的制作还原有实际意义
+
+```json
+{
+  "图片1": {
+    "段落ID": [
+      {"名称": "光线方向", "推理": "该段落的光线来源影响制作时布光方式"},
+      {"名称": "景深效果", "推理": "背景虚化程度影响拍摄参数设置"}
+    ]
+  }
+}
+```
+
+**Phase 2 — 形式分类**（对维度名称按 MECE 原则分类，便于聚类）：
+```json
+{"光线方向": "光线类", "景深效果": "镜头类", "字体粗细": "排版类"}
+```
+
+**Phase 3 — 精确值提取**（事无巨细、具体全面、精确无歧义；定量形式必须含数值）：
+- 先检查段落内一致性（若不一致，拆分到子层级）
+- 再判断定量 vs 定性
+- 定量：给出具体数值或比例（"字体大小约占图片高度的 8%"）
+- 定性：给出精确描述（"暖黄色调，色温约 3200K"）
+
+```json
+[
+  {
+    "段落ID": "段落1.1",
+    "形式": [
+      {"名称": "光线方向", "描述": "右侧 45° 侧光，形成明显的明暗分界", "是否可定量": false},
+      {"名称": "景深效果", "描述": "背景虚化，估计光圈 f/1.8~f/2.8", "是否可定量": true}
+    ]
+  }
+]
+```
+
+---
+
+## 步骤 6：段内关系分析
+
+分析每个父段落与其**直接子节点**之间的关系。
+
+**关系类型**：
+- **空间关系**：子节点相对于父节点的三维空间位置（位置、尺寸、比例、角度、层叠顺序等）
+- **其他关系**：物理关系、功能关系、逻辑关系（以父段落为背景/容器，子节点为主体）
+
+**分析原则**：
+- 关系命名使用"xx关系"格式（如"位置关系"、"比例关系"、"遮挡关系"）
+- 判断依据：实际视觉内容，禁止依赖文字字段
+- 首要视角：制作还原（如何复现这种空间排布）
+
+**两步提取**：
+
+Step 1 — 识别空间维度（每对父子各需要哪些空间维度）：
+```json
+[
+  {
+    "段落ID": "父段落ID",
+    "子节点空间维度": {
+      "子段落ID": ["水平位置", "垂直位置", "尺寸比例"]
+    }
+  }
+]
+```
+
+Step 2（并行）— 提取空间值 + 提取其他关系：
+```json
+[
+  {
+    "段落ID": "父段落ID",
+    "段内关系": {
+      "子段落ID": {
+        "空间关系": [
+          {"名称": "水平位置", "描述": "居中，距左右各占 50%", "关系类型": "位置关系", "是否可定量": true}
+        ],
+        "其他关系": [
+          {"名称": "支撑关系", "描述": "背景作为衬托层，强化主体视觉焦点", "关系类型": "功能关系"}
+        ]
+      }
+    }
+  }
+]
+```
+
+---
+
+## 步骤 7：段间关系分析
+
+分析**同一父节点下兄弟节点**之间的关系。
+
+**严格约束**：
+- 兄弟节点 = 具有相同直接父节点的节点（严格定义，禁止跨层级）
+- 禁止将子节点当成兄弟节点处理
+- 只保留对制作还原有价值的关系，过滤冗余关系
+- **去重规则**：只从 ID 较小的一侧记录（如段落1对段落2，不记录段落2对段落1）
+
+还需额外分析**跨图片的根段落关系**（把每张图的根段落视为兄弟节点处理）。
+
+```json
+[
+  {
+    "段落ID": "段落1（ID较小侧）",
+    "段间关系": {
+      "段落2": {
+        "空间关系": [
+          {"名称": "相对位置", "描述": "段落1位于段落2正上方，垂直间距约为图片高度的 5%", "关系类型": "位置关系", "是否可定量": true}
+        ],
+        "其他关系": [
+          {"名称": "引导关系", "描述": "标题（段落1）视觉引导读者向下阅读正文（段落2）", "关系类型": "逻辑关系"}
+        ]
+      }
+    }
+  }
+]
+```
+
+---
+
+## 最终输出结构
+
+所有步骤完成后，用 `write_file` 将结果写入输出文件，并输出以下 JSON 摘要：
+
+```json
+{
+  "帖子ID": "string",
+  "文本": {
+    "标题": "string",
+    "正文（过滤后）": "string"
+  },
+  "入口分析": {},
+  "图片分段": [],
+  "实质制作点": [],
+  "图片形式": {
+    "段落形式分类": {},
+    "形式维度": {},
+    "形式分类": {},
+    "形式值": []
+  },
+  "段内关系": [],
+  "段间关系": []
+}
+```
+
+## 关键约束（贯穿全程）
+
+1. **泛化优先**：始终描述制作规律，而非内容细节
+2. **视觉判断优先**：所有判断基于实际可见内容，禁止依赖名称/描述等文字字段
+3. **制作还原视角**：始终从"如何制作出这个效果"的角度分析
+4. **结构化输出**：每步严格按 JSON schema 输出，不允许随意变更结构
+5. **步骤间数据复用**：后续步骤引用前面步骤的段落 ID，保持一致性

docs/trace-api.md

@@ -246,15 +246,15 @@ Content-Type: application/json
 
 {
   "messages": [{"role": "user", "content": "..."}],
-  "after_sequence": null
+  "after_message_id": null
 }
 ```
 
-- `after_sequence: null`（或省略）→ 从末尾续跑
-- `after_sequence: N`（主路径上且 < head）→ 回溯到 sequence N 后运行
-- `messages: []` + `after_sequence: N` → 重新生成
+- `after_message_id: null`（或省略）→ 从末尾续跑
+- `after_message_id: "<message_id>"`（主路径上且 < head）→ 回溯到该消息后运行
+- `messages: []` + `after_message_id: "<message_id>"` → 重新生成
 
-Runner 根据 `after_sequence` 与 `head_sequence` 的关系自动判断续跑/回溯行为。
+Runner 根据解析出的 sequence 与 `head_sequence` 的关系自动判断续跑/回溯行为。
 
 #### 6. 停止运行中的 Trace
 

examples/analyze_story/README.md

@@ -0,0 +1,16 @@
+# 故事逆向拆解方法论研究
+
+## 项目目标
+将优质故事逆向拆解成AI可学习的思考步骤，用于训练长篇叙事Agent系统。
+
+## 目录结构
+- `input/` - 输入的优质故事样本（网络小说、电影剧本、短剧剧本）
+- `knowledge/` - 调研收集的理论知识和方法论
+- `output/` - 拆解后的示例和训练数据
+- `methodology/` - 确定的方法论文档
+
+## 研究进度
+- [ ] 理论调研
+- [ ] 方法论确定
+- [ ] 样本拆解
+- [ ] 训练数据生成

examples/analyze_story/analyze_samples.py

@@ -0,0 +1,139 @@
+import json
+import re
+
+def analyze_story_type(filename, content):
+    """分析文件类型：网文/剧本/短剧"""
+    
+    # 剧本特征
+    script_patterns = [
+        r'第\d+集',
+        r'\d+-\d+\s+(日|夜)\s+(内|外)',
+        r'人物[:：]',
+        r'▲',
+        r'画外音',
+        r'打戏设计',
+        r'剧本',
+        r'编剧[:：]'
+    ]
+    
+    # 网文特征
+    novel_patterns = [
+        r'第\d+章',
+        r'第\d+卷',
+        r'内容简介',
+        r'作者[:：]',
+        r'本文由.*分享',
+        r'TXT.*下载'
+    ]
+    
+    script_score = 0
+    novel_score = 0
+    
+    # 检查前3000字
+    preview = content[:3000]
+    
+    for pattern in script_patterns:
+        if re.search(pattern, preview):
+            script_score += 1
+    
+    for pattern in novel_patterns:
+        if re.search(pattern, preview):
+            novel_score += 1
+    
+    # 判断类型
+    if script_score > novel_score:
+        if '短剧' in filename or re.search(r'第\d+集', preview):
+            return '短剧剧本'
+        else:
+            return '电影剧本'
+    elif novel_score > 0:
+        return '网络小说'
+    else:
+        return '未知类型'
+
+def extract_structure_info(filename, content, story_type):
+    """提取关键结构信息"""
+    info = {
+        'filename': filename,
+        'type': story_type,
+        'length': len(content),
+        'first_3000': content[:3000]
+    }
+    
+    if '剧本' in story_type:
+        # 提取剧本结构信息
+        info['scenes'] = len(re.findall(r'\d+-\d+', content[:10000]))
+        info['characters'] = extract_characters_from_script(content[:5000])
+        info['structure_notes'] = '剧本格式，包含场景编号、人物、对话和动作描述'
+        
+    elif story_type == '网络小说':
+        # 提取小说结构信息
+        chapters = re.findall(r'第[零一二三四五六七八九十百千万\d]+[章回].*', content[:20000])
+        info['chapters_preview'] = chapters[:10] if chapters else []
+        info['chapter_count_estimate'] = len(re.findall(r'第\d+章', content))
+        
+        # 提取作者和简介
+        author_match = re.search(r'作者[:：](.*)', content[:2000])
+        if author_match:
+            info['author'] = author_match.group(1).strip()
+        
+        intro_match = re.search(r'内容简介[:：](.*?)(?=第|作者|PS|内容标签)', content[:3000], re.DOTALL)
+        if intro_match:
+            info['intro'] = intro_match.group(1).strip()[:200]
+        
+        info['structure_notes'] = '网文格式，分章节叙事'
+    
+    return info
+
+def extract_characters_from_script(text):
+    """从剧本中提取人物"""
+    # 查找"人物："后的内容
+    char_match = re.search(r'人物[:：](.*?)(?=\n\n|▲)', text, re.DOTALL)
+    if char_match:
+        chars = char_match.group(1).strip()
+        return [c.strip() for c in re.split(r'[，,、]', chars) if c.strip()]
+    return []
+
+def main():
+    # 读取数据
+    with open('samples_data.json', 'r', encoding='utf-8') as f:
+        data = json.load(f)
+    
+    analysis_results = []
+    
+    for filename, file_data in data.items():
+        if 'error' in file_data:
+            print(f"跳过错误文件: {filename}")
+            continue
+        
+        content = file_data.get('first_3000', '')
+        if not content:
+            continue
+        
+        # 使用完整内容进行分析（如果有的话）
+        # 这里我们只用first_3000，实际应该重新读取完整文件
+        print(f"\n分析文件: {filename}")
+        
+        story_type = analyze_story_type(filename, content)
+        print(f"  类型: {story_type}")
+        
+        info = extract_structure_info(filename, content, story_type)
+        analysis_results.append(info)
+        
+        print(f"  长度: {info['length']} 字符")
+        if 'author' in info:
+            print(f"  作者: {info['author']}")
+        if 'chapters_preview' in info and info['chapters_preview']:
+            print(f"  章节预览: {len(info['chapters_preview'])} 个")
+    
+    # 保存分析结果
+    with open('analysis_results.json', 'w', encoding='utf-8') as f:
+        json.dump(analysis_results, f, ensure_ascii=False, indent=2)
+    
+    print(f"\n\n分析完成，共分析 {len(analysis_results)} 个文件")
+    print("结果已保存到 analysis_results.json")
+    
+    return analysis_results
+
+if __name__ == '__main__':
+    main()

examples/analyze_story/generate_report.py

@@ -0,0 +1,120 @@
+import json
+import os
+
+def generate_markdown_report():
+    """生成Markdown格式的分析报告"""
+    
+    # 读取分析结果
+    with open('analysis_results.json', 'r', encoding='utf-8') as f:
+        results = json.load(f)
+    
+    # 读取完整数据
+    with open('samples_data.json', 'r', encoding='utf-8') as f:
+        full_data = json.load(f)
+    
+    # 开始生成报告
+    report = []
+    report.append("# 样本文件分析报告\n")
+    report.append(f"**分析时间**: 2024\n")
+    report.append(f"**文件总数**: {len(results)}\n")
+    report.append("\n---\n")
+    
+    # 统计信息
+    report.append("\n## 📊 文件类型统计\n")
+    type_count = {}
+    for item in results:
+        file_type = item['type']
+        type_count[file_type] = type_count.get(file_type, 0) + 1
+    
+    for file_type, count in type_count.items():
+        report.append(f"- **{file_type}**: {count} 个\n")
+    
+    report.append("\n---\n")
+    
+    # 详细分析
+    report.append("\n## 📝 文件详细分析\n")
+    
+    for idx, item in enumerate(results, 1):
+        filename = item['filename']
+        file_type = item['type']
+        
+        report.append(f"\n### {idx}. {filename}\n")
+        report.append(f"\n**文件类型**: {file_type}\n")
+        
+        # 获取完整文件信息
+        file_info = full_data.get(filename, {})
+        if 'format' in file_info:
+            report.append(f"**文件格式**: {file_info['format']}\n")
+        if 'encoding' in file_info:
+            report.append(f"**文件编码**: {file_info['encoding']}\n")
+        if 'length' in file_info:
+            report.append(f"**文件长度**: {file_info['length']:,} 字符\n")
+        
+        # 根据类型添加特定信息
+        if file_type == '网络小说':
+            if 'author' in item:
+                report.append(f"**作者**: {item['author']}\n")
+            if 'intro' in item:
+                report.append(f"\n**内容简介**:\n```\n{item['intro']}\n```\n")
+            if 'chapters_preview' in item and item['chapters_preview']:
+                report.append(f"\n**章节预览**:\n")
+                for chapter in item['chapters_preview'][:5]:
+                    report.append(f"- {chapter}\n")
+        
+        elif '剧本' in file_type:
+            if 'scenes' in item and item['scenes'] > 0:
+                report.append(f"**场景数量**: {item['scenes']} 个（前10000字统计）\n")
+            if 'characters' in item and item['characters']:
+                report.append(f"\n**主要人物**:\n")
+                for char in item['characters'][:10]:
+                    report.append(f"- {char}\n")
+        
+        report.append(f"\n**结构特征**: {item['structure_notes']}\n")
+        
+        # 添加前3000字预览
+        report.append(f"\n**前3000字内容预览**:\n")
+        report.append("```\n")
+        preview = item['first_3000'][:3000]
+        report.append(preview)
+        report.append("\n```\n")
+        
+        report.append("\n---\n")
+    
+    # 总结
+    report.append("\n## 📌 分析总结\n")
+    report.append("\n### 网络小说特征\n")
+    report.append("- 采用章节式结构，通常有\"第X章\"标记\n")
+    report.append("- 包含作者信息和内容简介\n")
+    report.append("- 文件通常较大（几十万到几百万字符）\n")
+    report.append("- 常见编码：GBK、GB18030\n")
+    
+    report.append("\n### 剧本特征\n")
+    report.append("- 采用场景编号格式（如\"1-1\"、\"2-1\"）\n")
+    report.append("- 包含人物列表、对话和动作描述\n")
+    report.append("- 使用特殊符号标记（如▲表示动作）\n")
+    report.append("- 包含场景时间地点标注（日/夜、内/外）\n")
+    
+    report.append("\n### 编码处理经验\n")
+    report.append("- TXT文件主要使用GBK和GB18030编码\n")
+    report.append("- 需要尝试多种编码方式进行读取\n")
+    report.append("- PDF和DOCX文件可以直接使用相应库读取\n")
+    
+    return ''.join(report)
+
+def main():
+    # 生成报告
+    report = generate_markdown_report()
+    
+    # 确保目录存在
+    os.makedirs('knowledge', exist_ok=True)
+    
+    # 保存报告
+    output_path = 'knowledge/samples_overview.md'
+    with open(output_path, 'w', encoding='utf-8') as f:
+        f.write(report)
+    
+    print(f"报告已生成: {output_path}")
+    print(f"报告长度: {len(report)} 字符")
+
+if __name__ == '__main__':
+    main()

examples/analyze_story/knowledge/01_save_the_cat_beat_sheet.md

@@ -0,0 +1,133 @@
+# Save the Cat Beat Sheet 理论
+
+**来源**: Blake Snyder《Save the Cat》
+**原始链接**: https://reedsy.com/blog/guide/story-structure/save-the-cat-beat-sheet
+
+## 核心概念
+
+Save the Cat是一套由好莱坞编剧Blake Snyder开发的故事结构方法论，最初用于编剧，现已广泛应用于小说创作。它将故事拆解为15个关键节拍（beats），每个节拍都有明确的功能和建议出现位置。
+
+## 15个核心Beat结构
+
+### 第一幕 - 建立世界（0-25%）
+
+#### 1. Opening Image 开场画面 (1%)
+- **功能**: 快照式地展示主角当前的世界状态
+- **要点**: 设定基调，吸引读者，展示"改变前"的状态
+- **示例**（《The Hate U Give》）: Starr在Garden Heights的派对上感到格格不入
+
+#### 2. Theme Stated 主题陈述 (5%)
+- **功能**: 引入故事的核心主题或人生教训
+- **要点**: 通常通过对话或事件暗示，主角此时可能还不理解
+- **示例**: Khalil解释Tupac的"THUG LIFE"含义 - 对黑人儿童的不公最终会伤害所有人
+
+#### 3. Set-up 设定 (1-10%)
+- **功能**: 深入展示主角的日常世界、性格缺陷、人际关系
+- **要点**: 建立"正常状态"，为后续对比做铺垫
+- **示例**: 展示Starr在精英学校和社区之间的双重身份，以及她对社区的复杂态度
+
+#### 4. Catalyst 催化剂/触发事件 (10%)
+- **功能**: 打破现状的重大事件，开启主线故事
+- **要点**: 这是改变一切的单一时刻
+- **示例**: Khalil被白人警察枪杀，Starr是唯一目击者
+
+#### 5. Debate 犹豫/辩论 (10-20%)
+- **功能**: 主角抗拒挑战，犹豫是否行动
+- **要点**: 展示主角的恐惧、疑虑和内心冲突
+- **示例**: Starr担心暴露身份会带来危险，决定保密
+
+#### 6. Break Into Two 进入第二幕 (25%)
+- **功能**: 主角决定接受挑战，主动踏上旅程
+- **要点**: 这是主角的主动选择，标志着进入新世界
+- **示例**: Starr决定向警方作证，成为匿名证人
+
+### 第二幕 - 冲突升级（25-75%）
+
+#### 7. B Story B故事线 (30%)
+- **功能**: 引入副线，通常涉及帮助主角转变的角色
+- **要点**: 常是爱情线或导师关系，提供情感支撑和主题深化
+- **示例**: Starr遇到DeVante，通过了解他的困境开始理解社区人们的选择
+
+#### 8. Fun and Games 承诺的乐趣 (30-55%)
+- **功能**: 实现故事宣传语中承诺的核心冲突/行动
+- **要点**: 这是"卖点"部分，超级英雄打小怪、侦探查线索
+- **示例**: Starr参与匿名采访、与检察官合作，同时在学校隐瞒身份
+
+#### 9. Midpoint 中点 (55%)
+- **功能**: 提高赌注的情节转折，通常是"虚假的胜利"
+- **要点**: 主角误以为已经赢了，但实际危机即将到来
+- **示例**: Starr在大陪审团前作证（看似进展）
+
+#### 10. Bad Guys Close In 反派逼近 (55-75%)
+- **功能**: 事情开始走下坡路，压力增大
+- **要点**: 外部压力（反派）和内部压力（团队分裂、自我怀疑）同时增加
+- **示例**: Starr的双重生活崩溃，在学校被揭穿，与朋友发生冲突
+
+#### 11. All is Lost 全盘皆输 (75%)
+- **功能**: 主角跌入谷底，希望破灭
+- **要点**: 通常伴随"死亡时刻"（字面或象征意义）
+- **示例**: 大陪审团决定不起诉115号警官，Starr的努力似乎白费
+
+#### 12. Dark Night of the Soul 灵魂暗夜 (75-85%)
+- **功能**: 面对失败，主角反思自己失去了什么
+- **要点**: 情感最低点，为顿悟做准备
+- **示例**: Starr对不公正感到愤怒和绝望，被吸引到暴力抗议中
+
+### 第三幕 - 解决与转变（85-100%）
+
+#### 13. Break Into Three 进入第三幕 (85%)
+- **功能**: 主角领悟真理，重新振作
+- **要点**: 结合A故事和B故事的教训，找到新方法
+- **示例**: Starr看到和平抗议，决定公开身份为Khalil发声
+
+#### 14. Finale 高潮 (85-110%)
+- **功能**: 运用新领悟，主角克服困难
+- **要点**: 综合运用所学，解决外部和内部冲突
+- **示例**: Starr公开作证、对抗种族主义朋友、帮助逮捕帮派成员
+
+#### 15. Final Image 结尾画面 (110%)
+- **功能**: 展示主角转变后的状态
+- **要点**: 通常与开场画面形成镜像或对比
+- **示例**: Starr坚定立场，誓言继续为正义发声
+
+## 核心优势
+
+1. **内置平衡**: 明确的比例分配确保节奏控制
+2. **符合观众期待**: 源于电影结构，符合现代读者的叙事直觉
+3. **大纲救星**: 详细的15个节拍可快速从概念发展为完整故事框架
+4. **跨媒体适配**: 天然适合影视化改编
+
+## 适用性分析
+
+### 优势场景
+- 商业类型小说（悬疑、爱情、冒险等）
+- 需要明确节奏控制的故事
+- 新手作者建立结构感
+- 影视化潜力作品
+
+### 局限性
+- 可能导致公式化（需要在细节上创新）
+- 不适合实验性文学
+- 对非线性叙事支持较弱
+- 原始比例基于110页剧本，小说需要灵活调整
+
+## AI应用思考
+
+### 可算法化要素
+1. **位置锚点**: 每个beat有明确的百分比位置
+2. **功能定义**: 每个beat的作用清晰可描述
+3. **转折检测**: 可以通过情感曲线、冲突强度等指标识别beat
+4. **模板填充**: 适合作为生成框架的骨架
+
+### 训练数据构建方向
+1. 标注现有作品的15个beat位置和内容
+2. 提取每个beat的"思考过程"：
+   - 为什么在这个位置设置这个转折？
+   - 这个beat如何服务于主题？
+   - 如何与前后beat形成因果链？
+3. 构建"beat决策树"：给定前文，如何设计下一个beat
+
+### 与网文结合的可能性
+- Save the Cat的"Fun and Games"可以映射到网文的"爽点密集区"
+- "Bad Guys Close In"对应"虐点/压力累积"
+- 需要增加"钩子密度"维度（Save the Cat的beat间隔对网文来说太稀疏）

examples/analyze_story/knowledge/01_scene_sequel_theory.md

@@ -0,0 +1,138 @@
+# Scene-Sequel 叙事结构理论
+
+**来源**: Dwight V. Swain《Techniques of the Selling Writer》  
+**调研时间**: 2025年  
+**原始链接**: https://www.bing.com/search?q=Scene-Sequel+narrative+structure+Dwight+Swain+writing+theory
+
+---
+
+## 一、核心定义
+
+**Scene-Sequel结构**是一种循环往复的叙事框架：
+- **Scene(场景)**: 以行动为主的情节推进单元，角色试图达成目标
+- **Sequel(续场)**: 以反应为主的过渡单元，角色处理场景结果并做出决策
+
+**核心价值**: 强调行动与反应的平衡，创造心理上真实可信的情节发展
+
+---
+
+## 二、结构要素拆解
+
+### Scene(场景)的三要素
+
+#### 1. Goal(目标)
+- 场景开始时角色必须有明确目标
+- 目标应该清晰、具体、可衡量
+- 为读者建立期待
+
+#### 2. Conflict(冲突)
+- 角色在追求目标时遇到的阻碍
+- 冲突必须直接妨碍目标的实现
+- 构成场景的中间部分/上升动作
+- 可以是显性对抗或隐性障碍
+
+#### 3. Disaster(灾难)
+- 场景的结尾，通常是负面结果
+- 角色未能达成目标或面临选择困境
+- 创造悬念，推动读者继续阅读
+- 引发角色的危机时刻
+
+### Sequel(续场)的三要素
+
+#### 1. Reaction(反应)
+- 角色对灾难的情绪反应
+- 包括情感、生理和心理层面
+- 展现角色的人性化一面
+
+#### 2. Dilemma(困境)
+- 角色分析处境
+- 权衡可选方案
+- 所有选择都不完美
+- 展现内心挣扎过程
+
+#### 3. Decision(决定)
+- 角色做出新的选择
+- 确定新的行动方向
+- 成为下一个场景的目标
+- 完成循环，推进情节
+
+---
+
+## 三、循环结构图
+
+```
+Scene → Sequel → Scene → Sequel → ...
+
+[Goal → Conflict → Disaster] → [Reaction → Dilemma → Decision] → [新Goal...]
+     ↑                              ↓                                  ↓
+   行动导向                        反思导向                          新行动
+```
+
+---
+
+## 四、多层级应用
+
+### 微观层面(单个章节/段落)
+- **场景构建**: 明确角色当前最迫切的目标 → 设计与目标直接相关的障碍 → 以让情况恶化的方式结束
+- **续场构建**: 给予角色情感反应的空间 → 展现角色的思考过程 → 让决定自然引向下一场景
+
+### 中观层面(多场景序列)
+- 可以省略或简化某些要素
+- 快节奏部分: 缩短续场
+- 情感重点部分: 延长续场
+- 允许多个场景共享一个续场
+
+### 宏观层面(整体故事结构)
+- **第一幕**: 整体作为大型"场景"(建立目标)
+- **第二幕**: 作为"续场"(反应与规划)
+- **第三幕**: 作为新"场景"(采取行动)
+
+---
+
+## 五、节奏控制技巧
+
+### 1. 制造节奏变化
+- 交替使用完整和压缩的Scene-Sequel
+- 高潮部分: 连续场景，最少续场
+- 角色发展部分: 加重续场比例
+
+### 2. 深化角色刻画
+- 续场展现角色独特的思考模式
+- 通过决策过程揭示价值观
+- 反应展现角色成长弧线
+
+### 3. 控制信息披露
+- 场景中展示外部事件
+- 续场中揭示内心世界
+- 平衡动作与内省
+
+---
+
+## 六、常见错误
+
+- ❌ 没有真正的目标(角色被动)
+- ❌ 冲突与目标无关
+- ❌ 灾难不够糟糕(缺乏张力)
+- ❌ 续场过长(节奏拖沓)
+- ❌ 跳过反应直接行动(不真实)
+
+---
+
+## 七、AI应用潜力分析
+
+### 优势
+1. **高度结构化**: 6个明确要素，易于算法化
+2. **递归性强**: Scene-Sequel循环可无限嵌套
+3. **可验证性**: 每个要素都有明确的检查标准
+4. **适合长篇**: 通过循环自然支撑长篇叙事
+
+### 挑战
+1. **灵活性**: 实际创作中经常省略或合并要素
+2. **情感深度**: Sequel部分的心理描写难以标准化
+3. **节奏把控**: 何时压缩、何时展开需要高级判断
+
+### 适用场景
+- ✅ 强情节驱动的类型小说
+- ✅ 网文中的"爽点"设计
+- ✅ 需要高频钩子的当代叙事
+- ⚠️ 意识流、实验性文学可能不适用

examples/analyze_story/knowledge/01_叙事理论综述.md

@@ -0,0 +1,197 @@
+# 叙事理论综述
+
+## 调研时间
+2025年2月
+
+## 核心发现
+
+### 一、经典叙事结构理论汇总
+
+#### 1. 三幕式结构(好莱坞黄金标准)
+- **来源**: 亚里士多德,由悉德·菲尔德系统化
+- **适用**: 剧情片、商业电影、主旋律作品
+- **结构**:
+  - 第一幕(建置,约30页): 建立平凡世界 → 煽动事件 → 情节点1
+  - 第二幕(对抗,约60页): 新世界障碍 → 中点转折 → 情节点2
+  - 第三幕(结局,约30页): 主动出击 → 高潮决战 → 新常态
+
+#### 2. 英雄之旅(12步骤)
+- **来源**: 约瑟夫·坎贝尔《千面英雄》,克里斯托弗·沃格勒《作家之旅》
+- **适用**: 奇幻、冒险、成长题材
+- **核心步骤**:
+  1. 平凡世界 → 2. 冒险召唤 → 3. 拒绝召唤 → 4. 遇见导师
+  5. 跨越门槛 → 6. 考验/盟友/敌人 → 7. 接近洞穴 → 8. 严峻考验
+  9. 获得奖励 → 10. 回归之路 → 11. 最终复活 → 12. 满载而归
+
+#### 3. 救猫咪节拍表(15个精确节拍)
+- **来源**: 布莱克·斯奈德
+- **适用**: 商业类型片、青春片、合家欢电影
+- **关键节拍**:
+  - 开场画面(1页) → 铺垫(1-10) → 主题呈现(5) → 催化剂(12)
+  - 争执(12-25) → 第二幕衔接点(25) → B故事(30) → 游戏段(30-55)
+  - 中点(55) → 坏人逼近(55-75) → 一无所有(75) → 灵魂黑夜(75-85)
+  - 第三幕衔接点(85) → 高潮结局(85-110) → 终场画面(110)
+
+#### 4. 故事织体理论
+- **来源**: 《故事的织体》
+- **核心思路**:
+  - 显性: 简化→分类→程序,抓主干逐层细化
+  - 隐性: 逻辑(因果关系)和动力(不稳定性推动)
+- **故事核心**: 人物+事件+主题
+- **八要素**: 人物身份、欲望、动作、核心问题、主要障碍、结果、正价值、负价值
+
+#### 5. 埃里克·埃德森23点结构
+- **来源**: 《故事策略》
+- **特点**: 三幕式的细化版,每个段落有更多细节划分
+
+#### 6. 杰克·哈特叙事弧线
+- **来源**: 《故事技巧》
+- **结构**: 阐述→上升动作→危机→高潮→下降动作/结局
+- **核心**: 主人公-困境-解决困境模式
+
+#### 7. 拉约什·埃格里前提理论
+- **来源**: 《编剧的艺术》
+- **核心**: 正题、反题、合题
+- **人物三维度**: 生理、心理、社会环境
+- **冲突四要素**: 静态、跳跃、预示、升级
+
+#### 8. 威廉斯道德前提八步骤
+- **来源**: 《故事的道德前提》
+- **13个情节点**: 从道德前提出发的完整戏剧结构
+
+### 二、AI辅助网文创作的创新框架
+
+#### 1. 四层构件模型(三山剑客)
+**核心思想**: 借鉴软件工程瀑布模型,将创作过程工程化
+
+**第一层:种子层(用户主导)**
+- 输入: 核心梗/脑洞、阅读契约、粗略大纲
+- 产出: 《故事愿景文档》
+
+**第二层:架构层(人机协商)**
+- 任务: 解决"情节-人物-环境"动态平衡
+- 工具: 情节功能、人物行动论、环境类型
+- 产出: 《精修故事大纲》(含转折点、人物弧光、环境设定)
+
+**第三层:光学层(人机协作)**
+- 任务: 将"故事"转化为"叙事"
+- 工作流: 切分序列 → 选择视角 → 安排节奏
+- 产出: 《细纲/章纲》(含字数、视角、叙事时间、情绪曲线)
+
+**第四层:渲染层(精细控制)**
+- 任务: 文本生成执行
+- 流程: 细纲指令 → 向量数据库检索 → AI生成 → 用户反馈调整
+
+#### 2. 三数据库架构
+
+**网文理论库(效果学)**
+- 关注: 读者心理反应("爽感"、"期待感"、"压抑-释放")
+- 语言: 模糊、经验主义("黄金三章"、"装逼打脸")
+
+**叙事学理论库(结构学)**
+- 关注: 文本组织形式("聚焦"、"顺序"、"频率")
+- 语言: 精确、结构主义
+
+**映射关系库(核心创新)**
+- 作用: 将网文"抽象公式"翻译成叙事学"具体操作"
+- 示例映射:
+  ```
+  装逼打脸 → 
+    阶段一(压抑): 内聚焦(反派视角) + 慢速叙事 + 展示
+    阶段二(转折): 外聚焦 + 停顿 + 短句动词
+    阶段三(释放): 自由间接引语 + 概述/场景 + 心理描写
+  ```
+
+### 三、叙事学核心概念体系
+
+#### 1. 视角与声音
+- **视角类型**: 
+  - 非聚焦(全知)
+  - 内聚焦(固定/不定/多重)
+  - 外聚焦(客观)
+- **叙述者类型**: 第一人称/第三人称,可靠/不可靠,显性/隐性
+
+#### 2. 叙事时间
+- **时序**: 顺叙、倒叙、闪回、闪前、交错
+- **时限**: 省略、概述、等述、扩述、静述
+- **频率**: 单一叙事、重复叙事、概括叙事
+
+#### 3. 话语模式
+- 直接引语、自由直接引语
+- 间接引语、自由间接引语
+
+#### 4. 情节构成
+- **功能**: 故事最小单位
+- **序列**: 功能组成的完整叙事句子(链状/嵌入/并列)
+- **情节**: 序列组合(继承原则/理念原则)
+
+### 四、关键理论洞察
+
+#### 1. 冲突三维理论(罗伯特·麦基)
+- 内心冲突(意识流)
+- 个人冲突(肥皂剧)
+- 外在冲突(动作冒险)
+- **核心问题**: "什么东西会阻止他们?"
+
+#### 2. 鸿沟理论
+- **故事材质=鸿沟**: 制造障碍,创造戏剧性
+- 人物不断加赌注弥补鸿沟 → 增加张力 → 创建高潮
+
+#### 3. 人物维理论
+- **维=矛盾**: 外表vs内心,表象性格vs真实性格
+- 通过加压揭示人物真相
+
+#### 4. 回报递减定律
+- 避免重复相似情感体验
+- 需要不断升级冲突强度
+
+### 五、实战应用要点
+
+#### 1. 高潮前置(网文特色)
+- 激励事件必须在前三章甚至第一章发生
+- "在前进中开炮"而非"擦炮管"
+
+#### 2. 逻辑审计
+- AI生成内容必须经过人工逻辑检查
+- 每个环节像多米诺骨牌,一个推倒下一个
+- 链条不能断
+
+#### 3. 伏笔与分晓
+- 伏笔必须有多重含义
+- 可回溯补充逻辑
+- 分晓必须符合逻辑,避免"机械降神"
+
+#### 4. 情境选择
+- 真正的两难: 两善取其一、两恶取其轻
+- 避免明显的善恶选择(霍布森选择效应)
+
+## 参考资料来源
+
+1. 知乎专栏文章(2024-2025):
+   - 《AI辅助网文创作理论研究笔记》系列(三山剑客)
+   - 《故事结构研究汇总:十一种剧情故事结构》(法师猫不凡)
+   - 《写「故事」的顶级技术》(不知)
+   - 编剧理论分享系列
+
+2. 经典编剧书籍:
+   - 《故事》(罗伯特·麦基)
+   - 《救猫咪》三部曲(布莱克·斯奈德)
+   - 《千面英雄》(约瑟夫·坎贝尔)
+   - 《作家之旅》(克里斯托弗·沃格勒)
+   - 《编剧的艺术》(拉约什·埃格里)
+   - 《故事的织体》
+   - 《编剧心理学》
+
+3. 叙事学理论:
+   - 胡亚敏《叙事学》
+   - 《叙事学从经典到后经典》
+
+## 下一步行动建议
+
+1. **理论整合**: 将11种故事结构与AI四层模型结合
+2. **数据库构建**: 
+   - 网文理论库(爽点公式、套路模板)
+   - 叙事学理论库(视角、时间、话语模式)
+   - 映射关系库(效果→技术转换规则)
+3. **实战验证**: 用提供的样本故事进行拆解实验
+4. **工具开发**: 基于理论框架开发辅助工具/提示词模板

examples/analyze_story/knowledge/02_MICE_quotient_theory.md

@@ -0,0 +1,169 @@
+# MICE Quotient 叙事结构理论
+
+**来源**: Orson Scott Card (《安德的游戏》作者)  
+**调研时间**: 2025年  
+**原始链接**: https://www.bing.com/search?q=MICE+quotient+narrative+structure+Orson+Scott+Card+milieu+idea+character+event
+
+---
+
+## 一、四种叙事类型定义
+
+### 1. Milieu (环境/世界)
+- **定义**: 关注故事的世界、设定或环境
+- **核心**: 角色进入一个新环境并与之互动
+- **关键问题**: "这个世界是什么样的?"
+- **典型例子**: 《霍比特人》、《绿野仙踪》
+
+### 2. Idea (理念/谜题)
+- **定义**: 聚焦驱动叙事的核心问题或谜题
+- **核心**: 提出问题并寻求答案
+- **关键问题**: "发生了什么?为什么?"
+- **典型例子**: 《福尔摩斯》系列、侦探小说
+
+### 3. Character (角色)
+- **定义**: 探索角色的发展和内在冲突
+- **核心**: 角色的成长、转变或接受现实
+- **关键问题**: "角色如何改变或找到自我?"
+- **典型例子**: 《傲慢与偏见》
+
+### 4. Event (事件)
+- **定义**: 围绕打破现状的事件展开
+- **核心**: 从失衡到恢复平衡的过程
+- **关键问题**: "如何恢复秩序?"
+- **典型例子**: 《星球大战》
+
+---
+
+## 二、开始和结束规则（对称结构原则）
+
+**核心原则**: MICE 遵循"后进先出"(LIFO)原则，类似括号匹配
+
+| 元素 | 开始触发 | 结束标志 | 核心张力 |
+|------|----------|----------|----------|
+| **M** | 进入陌生环境 | 离开/返回 | "这里如何运作?" |
+| **I** | 疑问产生 | 答案揭示 | "真相是什么?" |
+| **C** | 内在不满 | 接受/改变 | "我是谁?" |
+| **E** | 现状打破 | 秩序恢复 | "如何制止?" |
+
+### 示例
+
+**Milieu**: 霍比特人离开夏尔 → 探险 → 返回夏尔  
+**Idea**: 发现尸体/谜团 → 调查 → 真相揭露  
+**Character**: 伊丽莎白的偏见 → 自我认知 → 成长接纳  
+**Event**: 死星威胁 → 反抗 → 死星被摧毁
+
+---
+
+## 三、嵌套结构
+
+### 嵌套原则
+- MICE 元素可以相互嵌套，形成复杂叙事
+- 必须按照**相反顺序**关闭(后开先闭)
+- 就像编程中的括号：`{ [ ( ) ] }`
+
+### 嵌套示例
+
+```
+M - 进入新世界
+  I - 发现谜题
+    C - 角色开始质疑自我
+      E - 突发危机
+      E - 危机解决
+    C - 角色完成转变
+  I - 谜题解开
+M - 离开世界
+```
+
+### 多层级应用
+
+- **整体层面**: 可以是一个主导的 MICE 类型
+- **章节层面**: 每个章节可能是微型 MICE 结构
+- **场景层面**: 单个对话也可能是完整的 Idea 线程(提问→回答)
+
+**关键洞察**: 长篇小说通常包含所有四种元素，但比重不同。主线程决定故事类型，次要线程增加复杂度和深度。
+
+---
+
+## 四、实际应用方法
+
+### 步骤 1：识别主导类型
+问自己：读者最关心什么？
+- 世界探索 → Milieu
+- 解谜 → Idea
+- 角色成长 → Character
+- 冲突解决 → Event
+
+### 步骤 2：确定起点和终点
+根据主导类型设定对称的开始和结束
+
+### 步骤 3：添加次要线程
+- 确定需要哪些辅助 MICE 元素
+- 规划嵌套顺序
+- 确保正确闭合每个线程
+
+### 步骤 4：管理读者期待
+- **首段/首章**: 明确告知故事类型
+- **中间部分**: 维持承诺的叙事焦点
+- **结尾**: 满足或巧妙颠覆期待
+
+### 步骤 5：检查结构完整性
+- [ ] 每个开启的线程都已关闭？
+- [ ] 关闭顺序是否与开启相反？
+- [ ] 主线程是否贯穿始终？
+- [ ] 次要线程是否支持主线？
+
+---
+
+## 五、类型组合策略
+
+| 组合 | 适用类型 | 示例 |
+|------|----------|------|
+| M+E | 史诗奇幻 | 探索新世界+对抗威胁 |
+| I+C | 心理悬疑 | 解谜+角色转变 |
+| C+E | 英雄之旅 | 成长+战胜邪恶 |
+| M+I+C+E | 复杂文学作品 | 多线程深度叙事 |
+
+### 根据类型调整重点
+
+| 类型 | 重点元素 | 可以简化 |
+|------|----------|----------|
+| Milieu | 世界构建、氛围 | 角色深度 |
+| Idea | 逻辑、线索 | 环境细节 |
+| Character | 内心冲突、动机 | 情节复杂度 |
+| Event | 行动、节奏 | 哲学思考 |
+
+---
+
+## 六、常见错误
+
+1. **不匹配的开头和结尾**: 以 Idea 开始，却以 Event 结束
+2. **未关闭的线程**: 提出问题但未解答
+3. **错误的嵌套顺序**: 先开的线程先关闭
+4. **类型混淆**: 不清楚故事的主导类型
+
+---
+
+## 七、AI应用潜力分析
+
+### 优势
+1. **宏观结构清晰**: 四种类型覆盖所有叙事模式
+2. **可验证性强**: 开始-结束对称性易于检查
+3. **嵌套规则明确**: LIFO原则可编程实现
+4. **适合长篇规划**: 多线程管理支持复杂叙事
+
+### 挑战
+1. **抽象层级高**: 需要配合微观结构理论（如Scene-Sequel）
+2. **类型识别**: 需要语义理解能力判断主导类型
+3. **动态调整**: 实际创作中线程权重可能变化
+
+### 适用场景
+- ✅ 整体故事架构规划
+- ✅ 多线程管理和验证
+- ✅ 网文中的"伏笔-回收"设计
+- ✅ 确保长篇逻辑闭环
+- ⚠️ 需要与微观结构理论结合使用
+
+### 与Scene-Sequel的互补性
+- **MICE**: 宏观线程管理（章节级、全书级）
+- **Scene-Sequel**: 微观场景构建（段落级、场景级）
+- **结合方式**: MICE确定"要讲什么故事"，Scene-Sequel确定"如何讲这个故事"

examples/analyze_story/knowledge/03_web_novel_techniques.md

@@ -0,0 +1,217 @@
+# 网文创作技巧理论体系
+
+**来源**: 网文创作实践总结  
+**调研时间**: 2025年  
+**原始链接**: https://www.bing.com/search?q=网文爽点设计+钩子+反转+情绪价值+节奏控制+创作理论
+
+---
+
+## 一、核心三要素
+
+### 1. 冲突驱动
+- **作用**: 作为引擎推动情节发展
+- **特点**: 持续性、递进性
+
+### 2. 钩子设置
+- **作用**: 作为诱饵抓住读者持续阅读
+- **特点**: 高频率、多样化
+
+### 3. 反转设计
+- **作用**: 作为惊雷打破预期，制造高潮
+- **特点**: 意外性、合理性
+
+**核心理念**: 三要素缺一不可，通过情绪价值和节奏控制持续留住读者
+
+---
+
+## 二、钩子类型与设置策略
+
+### 7种有效钩子类型
+
+1. **高压开场**: 开篇即制造紧张氛围
+2. **剧情错位**: 打破常规预期
+3. **对话断句**: 关键对话戛然而止
+4. **动作中断**: 动作场景突然切换
+5. **新设定引入**: 抛出新的世界观/规则
+6. **情绪高潮**: 在情绪峰值处停顿
+7. **留白反转**: 制造悬念空间
+
+### 钩子设置位置策略
+
+- **章末断章**: 最重要，频率需适度避免读者疲劳
+- **章节中心**: 看个人发挥
+- **悬念强度分层**: 日常用小悬疑，关键处用强悬念
+
+### 钩子密度建议
+
+- 每3000-5000字设置一个小钩子
+- 每章末设置悬念（但不过度）
+
+### 避免误区
+
+- ❌ 过度使用导致读者疲劳
+- ❌ 虚假悬念损害信任
+
+---
+
+## 三、反转技巧
+
+### 1. 反转套路
+
+- **期待颠覆**: 如"英雄救美"反转为"美女救主角，实力更强"
+- **身份反转**: 幕后黑手竟是引导者
+- **信息差反转**: 通过隐藏信息制造反转
+
+### 2. 反转设计原则
+
+- 需要前期铺垫
+- 合理性与意外性平衡
+- 与角色成长/情节推进结合
+
+### 3. 实战案例结构
+
+**钩子**: 收到匿名邮件暗示证据位置  
+**反转**: 举报成功后发现"正义导师"是幕后黑手
+
+---
+
+## 四、情绪价值构建
+
+### 1. 情绪节奏公式
+
+**情绪节奏 = 特定情绪获得的次数**
+
+### 2. 情绪类型矩阵
+
+| 情绪类型 | 触发场景 | 效果 |
+|---------|---------|------|
+| **爽** | 主角碾压/打脸/逆袭 | 满足感 |
+| **甜** | 情感满足 | 温暖感 |
+| **苏** | 主角魅力展现 | 崇拜感 |
+| **虐** | 痛苦/挫折 | 共情感 |
+| **燃** | 热血/激励 | 激昂感 |
+| **恐** | 紧张/恐怖 | 刺激感 |
+
+### 3. 情绪价值输出方式
+
+- **单一情绪集中爆发**: 如连续爽点
+- **多种情绪交替拉扯**: 虐后甜，先抑后扬
+- **情绪递进式升级**: 小爽→中爽→大爽
+
+---
+
+## 五、节奏控制方法
+
+### 1. 双轨节奏系统
+
+#### 剧情节奏
+- **定义**: 读者获得的信息量
+- **控制变量**: 事件数量
+- **规律**: 信息量↑ = 节奏↑
+
+#### 情绪节奏
+- **定义**: 各类情绪出现频率
+- **控制变量**: 情绪获得次数
+- **规律**: 情绪密度↑ = 节奏↑
+
+### 2. 节奏调控技巧
+
+**加快节奏**:
+- 增加事件/冲突密度
+- 提高信息量
+- 缩短场景描写
+
+**放缓节奏**:
+- 减少事件
+- 增加细节描写
+- 增加心理活动
+
+**节奏起伏**:
+- 快慢交替，避免单调
+- 高潮前适当放缓蓄力
+- 高潮后适当缓冲
+
+### 3. 追更率优化策略
+
+**黄金比例**（保持90%追更率）:
+- 70% 情节推进
+- 20% 情绪满足
+- 10% 悬念设置
+
+---
+
+## 六、爽点构建方法
+
+### 1. 基础方法
+
+- **情绪拉扯**: 通过爽/甜/苏/虐/燃/恐等情绪获得次数控制
+- **信息量控制**: 信息量越多，节奏越快
+- **多重叠加**: 组合套路（如系统+重生+废柴逆袭）形成多重爽点
+- **画面感构建**: 通过具体场景强化情节冲击力
+
+### 2. 质量检测标准
+
+- ✓ 每章至少1个明确爽点
+- ✓ 钩子密度适中不疲劳
+- ✓ 反转有铺垫且合理
+- ✓ 情绪曲线有起伏
+- ✓ 节奏符合类型定位
+
+---
+
+## 七、综合应用框架
+
+### 创作流程整合
+
+```
+开篇钩子(高压开场) 
+  ↓
+冲突铺垫 
+  ↓
+爽点爆发(情绪高潮) 
+  ↓
+章末钩子(留白反转) 
+  ↓
+新冲突 
+  ↓
+反转设计 
+  ↓
+循环
+```
+
+---
+
+## 八、AI应用潜力分析
+
+### 优势
+
+1. **高度量化**: 钩子密度、情绪频率等都有明确指标
+2. **模式化强**: 爽点套路、反转模板可以学习
+3. **即时反馈**: 适合交互式生成中的实时调整
+4. **适合网文**: 完美对标"当代消费感"需求
+
+### 挑战
+
+1. **创意性**: 套路化可能导致同质化
+2. **情感真实性**: 情绪价值需要真实的人物支撑
+3. **平衡把控**: 过度使用技巧会适得其反
+
+### 适用场景
+
+- ✅ 网文类型小说
+- ✅ 短剧剧本
+- ✅ 交互式叙事
+- ✅ 高频钩子设计
+- ⚠️ 需要与深度角色塑造结合
+
+### 与其他理论的互补性
+
+- **与Scene-Sequel结合**: 
+  - Scene的Disaster = 钩子设置点
+  - Sequel的Reaction = 情绪价值输出点
+  
+- **与MICE结合**:
+  - Event线程 = 爽点密集区
+  - Character线程 = 情绪深度区
+  - Idea线程 = 反转设计区
+  - Milieu线程 = 新设定引入点

examples/analyze_story/knowledge/04_save_the_cat_beats.md

@@ -0,0 +1,213 @@
+# Save the Cat 节拍表理论
+
+**来源**: Blake Snyder《Save the Cat》  
+**调研时间**: 2025年  
+**原始链接**: https://www.bing.com/search?q=Save+the+Cat+beat+sheet+screenplay+structure+Blake+Snyder+15+beats
+
+---
+
+## 一、核心概念
+
+Save the Cat的15个节拍是经典三幕结构的扩展，特别优化了最难处理的第二幕，为编剧提供清晰的故事推进路线图。每个节拍都有明确的功能和位置，帮助保持故事节奏和观众参与度。
+
+**页码时间参考**（基于110页剧本）:
+- **第一幕**: 1-25页 (约22.7%)
+- **第二幕A**: 25-55页 (约27.3%)
+- **第二幕B**: 55-85页 (约27.3%)
+- **第三幕**: 85-110页 (约22.7%)
+
+---
+
+## 二、15个节拍详解
+
+### 第一幕 (ACT I) - 建立世界
+
+#### 1. Opening Image (开场画面)
+- **时间点**: 第1页 (0-1%)
+- **功能**: 展示故事和主角的"之前"状态，为结尾的转变做对比
+- **示例**: 《星际穿越》中Cooper作为农民的平凡生活
+- **关键要素**: 视觉化、象征性、对比性
+
+#### 2. Theme Stated (主题呈现)
+- **时间点**: 第5页 (约5%)
+- **功能**: 通常由配角说出，暗示故事的核心主题或主角需要学习的教训
+- **示例**: 某个角色提出关于故事核心问题的疑问或观点
+- **关键要素**: 隐晦、预示、主题核心
+
+#### 3. Set-Up (背景设定)
+- **时间点**: 第1-10页 (0-10%)
+- **功能**: 介绍主角的日常世界、人际关系和生活现状，展示需要修复的问题
+- **示例**: 展示主角的工作、家庭、朋友圈和生活缺陷
+- **关键要素**: 世界构建、角色关系、内在缺陷
+
+#### 4. Catalyst (催化剂/触发事件)
+- **时间点**: 第12页 (约11%)
+- **功能**: 打破常规的事件，将故事推向新方向
+- **示例**: 《星际穿越》中发现NASA基地的邀请
+- **关键要素**: 突发性、不可逆、改变现状
+
+#### 5. Debate (犹豫不决)
+- **时间点**: 第12-25页 (11-23%)
+- **功能**: 主角质疑是否应该踏上冒险之旅，展示内心挣扎
+- **示例**: 主角考虑接受挑战的利弊，表现恐惧和不确定
+- **关键要素**: 内心冲突、权衡利弊、人性化
+
+---
+
+### 第二幕前半部分 (ACT II A) - 反应与探索
+
+#### 6. Break Into Two (进入第二幕)
+- **时间点**: 第25页 (约23%)
+- **功能**: 主角做出选择，进入新世界或新情境
+- **示例**: 主角接受任务，离开舒适区
+- **关键要素**: 主动选择、不可回头、新世界
+
+#### 7. B Story (B故事线)
+- **时间点**: 第30页 (约27%)
+- **功能**: 引入新角色（通常是爱情线或导师），帮助主角理解主题
+- **示例**: 遇到重要的配角或建立关键关系
+- **关键要素**: 新关系、主题关联、情感深度
+
+#### 8. Fun and Games (承诺前提)
+- **时间点**: 第30-55页 (27-50%)
+- **功能**: 电影海报和预告片的核心内容，展示故事的"承诺"
+- **示例**: 《星际穿越》中的太空探索场景
+- **关键要素**: 类型特色、娱乐性、承诺兑现
+
+#### 9. Midpoint (中点)
+- **时间点**: 第55页 (50%)
+- **功能**: 虚假的胜利或失败，赌注提升，时钟开始倒计时
+- **示例**: 主角看似达成目标，但实际更大挑战即将到来
+- **关键要素**: 转折点、赌注提升、时间压力
+
+---
+
+### 第二幕后半部分 (ACT II B) - 对抗与低谷
+
+#### 10. Bad Guys Close In (敌人逼近)
+- **时间点**: 第55-75页 (50-68%)
+- **功能**: 外部和内部压力加剧，团队开始瓦解
+- **示例**: 反派势力增强，主角团队出现分歧和矛盾
+- **关键要素**: 压力递增、内外夹击、团队危机
+
+#### 11. All Is Lost (一切尽失)
+- **时间点**: 第75页 (约68%)
+- **功能**: 最低点，某事或某人"死亡"（真实或象征性）
+- **示例**: 导师死亡，重要任务失败，失去一切
+- **关键要素**: 最低点、死亡意象、绝望感
+
+#### 12. Dark Night of the Soul (灵魂暗夜)
+- **时间点**: 第75-85页 (68-77%)
+- **功能**: 主角陷入绝望，质疑一切，似乎没有希望
+- **示例**: 主角独自沉思，感觉无法继续
+- **关键要素**: 内省、绝望、黎明前的黑暗
+
+---
+
+### 第三幕 (ACT III) - 解决与转变
+
+#### 13. Break Into Three (进入第三幕)
+- **时间点**: 第85页 (约77%)
+- **功能**: 主角找到解决方案，通常来自A故事和B故事的融合
+- **示例**: 主角领悟真理，找到新的行动方案
+- **关键要素**: 顿悟、融合、新方案
+
+#### 14. Finale (终局高潮)
+- **时间点**: 第85-110页 (77-100%)
+- **功能**: 主角运用新知识对抗反派，解决所有故事线
+- **五个部分**:
+  1. 收集团队
+  2. 执行计划
+  3. 塔楼高潮（最终对决）
+  4. 挖掘深处（揭示真相）
+  5. 执行新方案
+- **关键要素**: 高潮对决、所有线索收束、转变应用
+
+#### 15. Final Image (结尾画面)
+- **时间点**: 第110页 (100%)
+- **功能**: 与开场画面形成对比，展示主角和世界的转变
+- **示例**: 《星际穿越》中展示改变后的新世界
+- **关键要素**: 对比、转变、闭环
+
+---
+
+## 三、节拍时间分布图
+
+```
+0%    10%   23%   27%   50%   68%   77%   100%
+|-----|-----|-----|-----|-----|-----|-----|
+  1-3   4-5    6    7-8    9   10-12   13-15
+
+第一幕 |  第二幕A  |  第二幕B  |  第三幕
+建立   |  探索     |  对抗     |  解决
+```
+
+---
+
+## 四、AI应用潜力分析
+
+### 优势
+
+1. **精确时间定位**: 每个节拍都有明确的百分比位置
+2. **功能明确**: 每个节拍的作用清晰可验证
+3. **适合剧本**: 特别适合电影、短剧等有明确时长的作品
+4. **结构完整**: 覆盖从开始到结束的完整弧线
+
+### 挑战
+
+1. **刚性结构**: 可能限制创意和灵活性
+2. **长度适配**: 原设计针对110页剧本，需要调整适配长篇小说
+3. **文化差异**: 源自好莱坞，可能不完全适合中文网文
+
+### 适用场景
+
+- ✅ 电影剧本
+- ✅ 网络短剧
+- ✅ 中短篇小说
+- ✅ 整体结构规划
+- ⚠️ 长篇网文需要扩展和调整
+
+### 与其他理论的互补性
+
+- **与MICE结合**:
+  - 15个节拍提供时间轴
+  - MICE提供线程管理
+  - 结合使用可实现精确的多线程时间控制
+
+- **与Scene-Sequel结合**:
+  - 15个节拍是宏观框架
+  - Scene-Sequel填充每个节拍内的微观场景
+  
+- **与网文技巧结合**:
+  - Catalyst = 强钩子
+  - Midpoint = 大反转
+  - All Is Lost = 虐点
+  - Finale = 爽点集中爆发
+
+---
+
+## 五、长篇小说适配建议
+
+### 扩展策略
+
+对于百万字级别的长篇小说，可以采用"嵌套节拍"策略：
+
+1. **整体层级**: 全书遵循15节拍
+2. **卷/部层级**: 每卷/部内部也遵循15节拍
+3. **章节层级**: 关键章节可以包含微型15节拍
+
+### 百分比调整
+
+长篇小说可以调整节拍比例：
+- 扩展"Fun and Games"（30-50%）以容纳更多内容
+- 扩展"Bad Guys Close In"（50-68%）以增加复杂度
+- 保持关键转折点的相对位置
+
+### 检查清单
+
+- [ ] 开场画面是否建立对比基准？
+- [ ] 主题是否在前10%呈现？
+- [ ] 催化剂是否在10-15%出现？
+- [ ] 中点是否在50%左右？
+- [ ] 最低点是否在70%左右？
+- [ ] 结尾画面是否与开场呼应？

examples/analyze_story/knowledge/05_AI_narrative_generation.md

@@ -0,0 +1,221 @@
+# AI叙事生成方法论
+
+**来源**: AI叙事生成研究综述  
+**调研时间**: 2025年  
+**原始链接**: https://www.bing.com/search?q=AI+narrative+generation+chain+of+thought+creative+writing+story+planning+LLM
+
+---
+
+## 一、AI叙事生成的主要方法
+
+### 1. Plan-and-Write方法（规划-写作）
+
+- **核心思路**: 先生成故事规划/大纲，再基于规划生成具体内容
+- **优势**: 
+  - 允许对生成过程进行引导和多样化控制
+  - 更符合人类创作流程
+  - 易于实现交互式调整
+- **应用**: LLM故事生成的主流范式之一
+
+### 2. 两大生成范式
+
+根据ACL Anthology的调研论文，LLM故事生成存在两个主要范式：
+
+#### 直接生成范式
+- 端到端直接产出故事
+- 优点: 简单、流畅
+- 缺点: 难以控制、长篇易崩
+
+#### 结构化生成范式
+- 包含中间规划步骤
+- 优点: 可控性强、逻辑连贯
+- 缺点: 需要更复杂的训练数据
+
+---
+
+## 二、思维链(Chain of Thought)在创作中的应用
+
+### 1. 故事规划层面
+
+- 将复杂的叙事任务分解为多个思考步骤
+- 先构思情节框架、角色设定、冲突设计等中间环节
+- 再基于这些中间产出生成最终文本
+
+### 2. 提示工程(Prompt Engineering)
+
+通过精心设计的提示词引导模型展示创作思考过程，可包含：
+
+- **故事结构规划**: 确定整体框架和节拍
+- **角色动机分析**: 理解角色行为逻辑
+- **情节逻辑推演**: 确保因果关系合理
+- **叙事节奏控制**: 调整信息披露速度
+
+### 3. 思维链示例结构
+
+```
+用户输入: 写一个复仇故事
+
+思维链展开:
+1. [结构规划] 采用三幕结构，主角从受害者到复仇者的转变
+2. [角色设定] 主角：曾经善良，现在冷酷；反派：表面正义，实则虚伪
+3. [冲突设计] 核心冲突：正义与复仇的界限
+4. [节拍规划] 
+   - 开场：展示主角的幸福生活
+   - 催化剂：反派的背叛导致主角失去一切
+   - 中点：主角发现反派的更大阴谋
+   - 低点：复仇计划失败，陷入绝境
+   - 高潮：主角做出道德选择
+5. [文本生成] 基于以上规划生成具体场景...
+```
+
+---
+
+## 三、如何训练模型学习创作思考过程
+
+### 1. 数据构建策略
+
+收集包含**中间创作步骤**的训练数据，不仅要有最终故事，还需要：
+
+- **大纲/提纲**: 章节规划、情节要点
+- **角色档案**: 人物设定、关系图谱
+- **情节规划文档**: 冲突设计、转折点规划
+- **修订过程记录**: 从初稿到终稿的演变
+
+### 2. 多阶段训练方法
+
+#### 第一阶段：学习基础叙事能力
+- 训练数据: 大量完整故事
+- 目标: 学习语言流畅性、基本叙事模式
+
+#### 第二阶段：学习结构化规划能力
+- 训练数据: 大纲→故事的配对数据
+- 目标: 学习从抽象规划到具体文本的映射
+
+#### 第三阶段：整合规划与写作的端到端训练
+- 训练数据: 包含完整思考过程的数据
+- 目标: 学习像人类作家一样先思考再写作
+
+### 3. 关键技术要点
+
+#### 引导与多样化(Guiding and Diversifying)
+- 平衡创意多样性与主题一致性
+- 避免生成过于模板化或过于发散
+
+#### 分层生成架构
+- 分别建模宏观结构和微观文本
+- 宏观层: 故事整体框架
+- 中观层: 章节场景规划
+- 微观层: 具体文本生成
+
+#### 反馈循环
+- 让模型能根据已生成内容调整后续规划
+- 实现动态的故事发展
+
+---
+
+## 四、核心挑战
+
+1. **保持长篇叙事的连贯性**
+   - 问题: 百万字级别容易出现前后矛盾
+   - 解决方向: 记忆系统、一致性检查
+
+2. **平衡创意性与可控性**
+   - 问题: 过度控制失去创意，过度自由失去方向
+   - 解决方向: 分层控制、软约束
+
+3. **学习人类作家的隐性思考过程**
+   - 问题: 很多创作决策是直觉性的
+   - 解决方向: 逆向工程、专家标注
+
+4. **处理复杂的角色关系和情节伏笔**
+   - 问题: 多线程管理、长期伏笔回收
+   - 解决方向: 知识图谱、线程追踪
+
+---
+
+## 五、实践资源
+
+- **GitHub资源库**: yingpengma/Awesome-Story-Generation
+  - 包含最新研究论文和数据集
+  
+- **LangChain框架**: 
+  - 提供story-writing相关的提示工程模板和工具链
+
+---
+
+## 六、关键结论
+
+现代AI叙事生成越来越重视显式建模创作的"思考过程"，通过plan-and-write范式和思维链技术，让模型像人类作家一样先构思再写作，这需要特殊设计的训练数据和多阶段学习策略。
+
+---
+
+## 七、对本项目的启示
+
+### 1. 数据构建方向
+
+**核心任务**: 将优质故事逆向拆解成"思考步骤"
+
+**具体方法**:
+- 不仅保留最终文本
+- 逆向推导出作者的规划过程
+- 标注每个场景/章节的设计意图
+
+### 2. 训练数据格式建议
+
+```json
+{
+  "story_metadata": {
+    "title": "故事标题",
+    "genre": "类型",
+    "length": "字数"
+  },
+  "planning_chain": {
+    "overall_structure": {
+      "mice_type": "主导类型",
+      "beat_sheet": "15节拍规划",
+      "theme": "核心主题"
+    },
+    "chapter_planning": [
+      {
+        "chapter_id": 1,
+        "scene_sequel_structure": {
+          "goal": "角色目标",
+          "conflict": "冲突设计",
+          "disaster": "灾难结果",
+          "reaction": "情绪反应",
+          "dilemma": "困境分析",
+          "decision": "决策"
+        },
+        "web_novel_elements": {
+          "hooks": ["钩子类型"],
+          "emotion_type": "情绪类型",
+          "reversal": "反转设计"
+        },
+        "reasoning": "为什么这样设计这一章"
+      }
+    ]
+  },
+  "final_text": "最终生成的文本"
+}
+```
+
+### 3. 微调策略
+
+#### 优先级1: 结构规划能力
+- 训练模型学习MICE线程管理
+- 训练模型学习15节拍时间控制
+
+#### 优先级2: 场景构建能力
+- 训练模型学习Scene-Sequel循环
+- 训练模型学习钩子和反转设计
+
+#### 优先级3: 端到端整合
+- 训练模型从规划到文本的完整流程
+- 训练模型的动态调整能力
+
+### 4. 一周内可执行方案
+
+**Day 1-2**: 选择3-5个优质样本进行深度拆解
+**Day 3-4**: 构建包含思考过程的训练数据
+**Day 5-6**: 微调核心模块（优先结构规划）
+**Day 7**: 测试和迭代

examples/analyze_story/knowledge/07_Methodology_Analysis.md

@@ -0,0 +1,1016 @@
+# 现有方法论在AI训练中的优劣势分析
+
+**版本**: v1.0  
+**日期**: 2025-02-17  
+**目标**: 分析Scene-Sequel、MICE、Save the Cat、爽点理论在AI训练中的优劣势，识别gaps和改进空间
+
+---
+
+## 一、方法论对比矩阵
+
+### 1.1 核心特征对比
+
+| 方法论 | 层次 | 粒度 | 可算法化 | 文化背景 | 主要用途 |
+|--------|------|------|----------|----------|----------|
+| Scene-Sequel | 微观 | 场景级 | ★★★★☆ | 西方（小说） | 场景因果链 |
+| MICE Quotient | 宏观 | 故事级 | ★★★★★ | 西方（小说） | 线程管理 |
+| Save the Cat | 宏观 | 故事级 | ★★★★☆ | 西方（电影） | 节拍定位 |
+| 爽点理论 | 中观 | 章节级 | ★★★★★ | 中国（网文） | 情绪设计 |
+
+### 1.2 覆盖维度对比
+
+| 维度 | Scene-Sequel | MICE | Save the Cat | 爽点理论 |
+|------|--------------|------|--------------|----------|
+| 结构完整性 | ✓ | ✓✓✓ | ✓✓✓ | ✗ |
+| 因果逻辑 | ✓✓✓ | ✓✓ | ✓ | ✗ |
+| 情感设计 | ✓✓ | ✓ | ✓✓✓ | ✓✓✓ |
+| 节奏控制 | ✓✓ | ✗ | ✓✓ | ✓✓✓ |
+| 读者粘性 | ✓ | ✓ | ✓ | ✓✓✓ |
+| 长篇支撑 | ✓ | ✓✓✓ | ✓ | ✓✓✓ |
+| 可验证性 | ✓✓ | ✓✓✓ | ✓✓ | ✓✓ |
+
+---
+
+## 二、各方法论的优劣势分析
+
+### 2.1 Scene-Sequel 结构
+
+#### 优势
+
+**1. 因果链清晰**
+- **表现**: Goal → Conflict → Disaster → Reaction → Dilemma → Decision 形成完整因果链
+- **AI训练价值**: 可以训练模型理解和生成逻辑严密的场景序列
+- **可算法化**: 六个要素明确，易于标注和验证
+- **示例**:
+  ```json
+  {
+    "scene": {"goal": "破案", "conflict": "证据不足", "disaster": "嫌疑人有不在场证明"},
+    "sequel": {"reaction": "沮丧", "dilemma": "追查vs放弃", "decision": "调查同伙"}
+  }
+  ```
+
+**2. 思考过程天然包含**
+- **表现**: Sequel部分（Reaction → Dilemma → Decision）就是角色的思考过程
+- **AI训练价值**: 可以直接提取"如何做决策"的思考链
+- **可迁移性**: 这种思考模式适用于各种类型的故事
+
+**3. 节奏控制内置**
+- **表现**: Scene（快节奏）和Sequel（慢节奏）交替
+- **AI训练价值**: 可以学习快慢节奏的自然切换
+- **情感曲线**: 自动形成张弛有度的情感体验
+
+**4. 问题-答案框架**
+- **表现**: K.M. Weiland的补充视角将场景视为问题和答案
+- **AI训练价值**: 可以训练模型为每个场景生成核心问题
+- **验证机制**: 检查场景开头的问题是否在结尾得到回答
+
+#### 劣势
+
+**1. 机械性风险**
+- **表现**: 严格遵循可能导致叙事过于程式化
+- **AI训练挑战**: 模型可能生成公式化的场景
+- **改进方向**: 需要引入变化机制（如省略某些部分、合并多个Scene-Sequel）
+
+**2. 复杂场景处理困难**
+- **表现**: 多条冲突线并行时，难以保持单一的问题-答案线
+- **AI训练挑战**: 模型难以处理多线程场景
+- **改进方向**: 需要扩展为多Goal、多Disaster的结构
+
+**3. 缺少量化指标**
+- **表现**: 没有明确的"多长算合适"、"多少个Scene-Sequel组成一章"
+- **AI训练挑战**: 难以学习合适的长度和密度
+- **改进方向**: 需要补充统计数据（如平均长度、密度分布）
+
+**4. 缺少情绪强度标注**
+- **表现**: 只标注了Reaction，但没有量化情绪强度
+- **AI训练挑战**: 模型难以学习情感曲线的起伏
+- **改进方向**: 需要增加情绪强度评分（1-10）
+
+#### 在AI训练中的应用价值
+
+**高价值场景**:
+- ✓ 训练场景级因果推理
+- ✓ 训练决策思考链（Dilemma → Decision）
+- ✓ 训练问题-答案一致性
+
+**低价值场景**:
+- ✗ 训练宏观结构规划（需要MICE或Save the Cat）
+- ✗ 训练爽点设计（需要爽点理论）
+
+---
+
+### 2.2 MICE Quotient 理论
+
+#### 优势
+
+**1. 结构验证性极强**
+- **表现**: 嵌套规则类似括号匹配，可以自动验证
+- **AI训练价值**: 可以用栈结构检查线程的开启-关闭是否正确
+- **可算法化**: 
+  ```python
+  def validate_mice_nesting(threads):
+      stack = []
+      for event in timeline:
+          if event.type == 'opening':
+              stack.append(event.thread_id)
+          elif event.type == 'closing':
+              if stack[-1] != event.thread_id:
+                  return False  # 嵌套错误
+              stack.pop()
+      return len(stack) == 0  # 所有线程都关闭
+  ```
+
+**2. 类型化清晰**
+- **表现**: 四种类型（Milieu、Idea、Character、Event）有明确定义
+- **AI训练价值**: 可以训练分类器识别每个线程的类型
+- **可组合性**: 可以训练模型理解不同类型的组合效果
+
+**3. 长篇支撑力强**
+- **表现**: 通过线程复用和嵌套，可以支撑百万字长篇
+- **AI训练价值**: 可以学习如何在长篇中管理多条线索
+- **扩展性**: 可以无限嵌套和并行
+
+**4. 读者期待管理**
+- **表现**: 每个线程的开启就是对读者的承诺
+- **AI训练价值**: 可以学习如何制造和满足读者期待
+- **验证机制**: 检查是否有未关闭的线程
+
+#### 劣势
+
+**1. 缺少具体内容指导**
+- **表现**: 只告诉你"要开启和关闭"，但不告诉你"开启什么内容"
+- **AI训练挑战**: 模型知道结构，但不知道填充什么
+- **改进方向**: 需要结合Scene-Sequel或爽点理论填充内容
+
+**2. 缺少节奏控制**
+- **表现**: 没有告诉你何时加速、何时放缓
+- **AI训练挑战**: 模型可能生成节奏单调的故事
+- **改进方向**: 需要结合Save the Cat的节拍或爽点理论的密度
+
+**3. 缺少情感设计**
+- **表现**: 只关注结构，不关注读者情绪
+- **AI训练挑战**: 模型可能生成结构完整但无聊的故事
+- **改进方向**: 需要结合情感曲线设计
+
+**4. 开启-关闭的时机判断**
+- **表现**: 没有明确的规则告诉你"何时关闭一个线程"
+- **AI训练挑战**: 模型难以学习合适的关闭时机
+- **改进方向**: 需要补充统计数据（如平均持续章节数）
+
+#### 在AI训练中的应用价值
+
+**高价值场景**:
+- ✓ 训练宏观结构规划
+- ✓ 训练线程嵌套和管理
+- ✓ 训练结构完整性验证
+- ✓ 训练长篇故事的线索管理
+
+**低价值场景**:
+- ✗ 训练具体场景内容生成（需要Scene-Sequel）
+- ✗ 训练情感设计（需要Save the Cat或爽点理论）
+
+---
+
+### 2.3 Save the Cat 节拍表
+
+#### 优势
+
+**1. 位置精确**
+- **表现**: 每个节拍有明确的百分比位置（如Catalyst在10%）
+- **AI训练价值**: 可以训练模型在特定位置安排特定类型的事件
+- **可验证性**: 可以检查关键节拍是否在合适位置
+
+**2. 情感曲线内置**
+- **表现**: 15个节拍隐含了完整的情感起伏曲线
+- **AI训练价值**: 可以学习如何设计情感体验
+- **可视化**: 
+  ```
+  Opening(2) → Catalyst(4) → Break2(5) → Fun(8) → Midpoint(9) 
+  → BadGuys(6) → AllLost(1) → Dark(3) → Break3(7) → Finale(10)
+  ```
+
+**3. 功能明确**
+- **表现**: 每个节拍的功能清晰（如Theme Stated暗示主题）
+- **AI训练价值**: 可以学习每个位置应该完成什么任务
+- **目标导向**: 每个节拍都有明确的目标
+
+**4. 经过验证**
+- **表现**: 源自好莱坞成功电影的总结
+- **AI训练价值**: 这些模式已被证明有效
+- **可信度高**: 基于大量成功案例
+
+#### 劣势
+
+**1. 单线性设计**
+- **表现**: 主要为单主角单线程设计
+- **AI训练挑战**: 难以处理多主角、多线程的复杂故事
+- **改进方向**: 需要扩展为多线程版本（结合MICE）
+
+**2. 文化差异**
+- **表现**: 源自好莱坞，可能不完全适合中国网文
+- **AI训练挑战**: 直接应用可能导致"水土不服"
+- **改进方向**: 需要根据网文特点调整（如提前触发、压缩Debate）
+
+**3. 长篇挑战**
+- **表现**: 设计用于110页剧本，百万字长篇需要多层嵌套
+- **AI训练挑战**: 复杂度高，难以管理
+- **改进方向**: 需要设计分卷应用策略
+
+**4. 缺少微观指导**
+- **表现**: 只告诉你"在50%处安排Midpoint"，但不告诉你"Midpoint具体写什么"
+- **AI训练挑战**: 模型知道位置，但不知道内容
+- **改进方向**: 需要结合Scene-Sequel或爽点理论
+
+**5. 机械性风险**
+- **表现**: 过于严格可能导致公式化
+- **AI训练挑战**: 模型可能生成套路化的故事
+- **改进方向**: 需要引入变化机制
+
+#### 在AI训练中的应用价值
+
+**高价值场景**:
+- ✓ 训练宏观节奏控制
+- ✓ 训练情感曲线设计
+- ✓ 训练关键事件的位置安排
+- ✓ 训练主题深化
+
+**低价值场景**:
+- ✗ 训练多线程故事（需要MICE）
+- ✗ 训练具体场景内容（需要Scene-Sequel）
+- ✗ 训练网文特有的高频爽点（需要爽点理论）
+
+---
+
+### 2.4 爽点理论（网文）
+
+#### 优势
+
+**1. 量化指标明确**
+- **表现**: 明确的密度要求（每4000字至少1个小爽点）
+- **AI训练价值**: 可以训练模型控制爽点密度
+- **可验证性**: 可以自动统计爽点数量和分布
+
+**2. 类型化清晰**
+- **表现**: 五大爽点类型（打脸、升级、装逼、获得、碾压）有明确特征
+- **AI训练价值**: 可以训练分类器识别爽点类型
+- **可组合性**: 可以训练模型组合多种爽点
+
+**3. 机制明确**
+- **表现**: 每种爽点都有明确的"setup-payoff-reaction"机制
+- **AI训练价值**: 可以学习如何设计有效的爽点
+- **示例**:
+  ```json
+  {
+    "type": "智商碾压",
+    "setup": "古代人算不出税银重量",
+    "payoff": "主角秒答九千三百七十五斤",
+    "reaction": "中年男人猛的站起身"
+  }
+  ```
+
+**4. 读者粘性强**
+- **表现**: 高频爽点是网文成功的关键
+- **AI训练价值**: 可以学习如何保持读者持续阅读
+- **市场验证**: 这些理论都是从成功作品中总结的
+
+**5. 钩子理论完善**
+- **表现**: 明确的钩子类型和布置原则
+- **AI训练价值**: 可以学习如何制造和满足期待
+- **公式化**: "制造期待 → 延迟满足 → 给予满足 = 爽"
+
+**6. 长篇支撑力强**
+- **表现**: 金手指理论、套路设计、节奏控制都针对百万字长篇
+- **AI训练价值**: 可以学习如何支撑长篇创作
+- **实用性**: 直接来自创作实践
+
+#### 劣势
+
+**1. 缺少宏观结构**
+- **表现**: 只关注爽点和钩子，不关注整体结构
+- **AI训练挑战**: 模型可能生成爽点密集但结构混乱的故事
+- **改进方向**: 需要结合MICE或Save the Cat
+
+**2. 缺少因果逻辑**
+- **表现**: 没有强调场景之间的因果关系
+- **AI训练挑战**: 模型可能生成逻辑不通的情节
+- **改进方向**: 需要结合Scene-Sequel
+
+**3. 套路化风险**
+- **表现**: 过度依赖套路可能导致千篇一律
+- **AI训练挑战**: 模型可能生成老套的故事
+- **改进方向**: 需要引入创新机制
+
+**4. 缺少深度指导**
+- **表现**: 主要关注"爽"，对角色深度、主题深化关注不足
+- **AI训练挑战**: 模型可能生成浅薄的故事
+- **改进方向**: 需要结合Character线程和Theme Stated
+
+**5. 文化特定性**
+- **表现**: 主要针对中国网文市场
+- **AI训练挑战**: 可能不适用于其他类型或市场
+- **改进方向**: 需要根据目标市场调整
+
+#### 在AI训练中的应用价值
+
+**高价值场景**:
+- ✓ 训练爽点设计和密度控制
+- ✓ 训练钩子布置和期待管理
+- ✓ 训练节奏控制（快慢交替）
+- ✓ 训练读者粘性维持
+- ✓ 训练长篇内容支撑
+
+**低价值场景**:
+- ✗ 训练宏观结构规划（需要MICE或Save the Cat）
+- ✗ 训练因果逻辑（需要Scene-Sequel）
+- ✗ 训练深度主题（需要Character线程）
+
+---
+
+## 三、关键Gaps识别
+
+### 3.1 结构层面的Gaps
+
+**Gap 1: 缺少多层次整合框架**
+
+**问题描述**:
+- Scene-Sequel关注微观（场景）
+- MICE和Save the Cat关注宏观（故事）
+- 爽点理论关注中观（章节）
+- **但缺少明确的整合机制**
+
+**影响**:
+- AI模型难以理解不同层次之间的关系
+- 可能导致宏观结构合理但微观场景混乱，或反之
+
+**改进方向**:
+```
+宏观层（MICE + Save the Cat）
+    ↓ 如何分解到章节？
+中观层（起承转合 + 爽点钩子）
+    ↓ 如何分解到场景？
+微观层（Scene-Sequel）
+```
+
+**需要补充**:
+- 宏观节拍如何分解为中观章节
+- 中观章节如何分解为微观场景
+- 微观场景如何支撑中观和宏观
+
+---
+
+**Gap 2: 缺少多线程场景处理**
+
+**问题描述**:
+- Scene-Sequel主要为单线程设计
+- 实际故事常有多条线索并行
+- **缺少多Goal、多Disaster的处理机制**
+
+**影响**:
+- AI模型难以生成复杂的多线程场景
+- 可能导致场景过于简单
+
+**改进方向**:
+```json
+{
+  "scene": {
+    "goals": [
+      {"character": "主角", "goal": "破案"},
+      {"character": "反派", "goal": "隐藏真相"}
+    ],
+    "conflicts": [
+      {"type": "主角vs反派", "description": "..."},
+      {"type": "主角vs时间", "description": "..."}
+    ],
+    "disasters": [
+      {"thread": "破案线", "outcome": "证据被毁"},
+      {"thread": "感情线", "outcome": "女主误会"}
+    ]
+  }
+}
+```
+
+---
+
+**Gap 3: 缺少结构变化机制**
+
+**问题描述**:
+- 所有方法论都有"标准结构"
+- **但缺少"何时可以打破规则"的指导**
+- 严格遵循可能导致机械化
+
+**影响**:
+- AI模型可能生成公式化的故事
+- 缺少创新和惊喜
+
+**改进方向**:
+- 标注哪些场景省略了Sequel
+- 标注哪些节拍提前或延后
+- 标注哪些线程故意不关闭（留悬念）
+- 提取"为什么可以打破规则"的思考链
+
+---
+
+### 3.2 内容层面的Gaps
+
+**Gap 4: 缺少具体内容生成指导**
+
+**问题描述**:
+- MICE告诉你"要开启Event线程"，但不告诉你"开启什么Event"
+- Save the Cat告诉你"10%处要有Catalyst"，但不告诉你"Catalyst具体是什么"
+- **结构和内容之间有鸿沟**
+
+**影响**:
+- AI模型知道结构，但不知道填充什么内容
+- 可能生成结构正确但内容空洞的故事
+
+**改进方向**:
+- 建立"结构-内容"映射库
+- 标注每个节拍/线程的常见内容类型
+- 提取"如何选择内容"的思考链
+
+**示例**:
+```json
+{
+  "beat": "Catalyst",
+  "position": "10%",
+  "common_content_types": [
+    "外部事件打破日常（如：接到任务、遭遇危机）",
+    "获得关键信息（如：发现秘密、得到线索）",
+    "被迫做出选择（如：被挑战、被威胁）"
+  ],
+  "selection_criteria": [
+    "与主角目标相关",
+    "制造紧迫感",
+    "引出后续冲突"
+  ]
+}
+```
+
+---
+
+**Gap 5: 缺少情绪强度量化**
+
+**问题描述**:
+- Scene-Sequel有Reaction，但没有量化情绪强度
+- Save the Cat有情感曲线，但没有具体数值
+- 爽点理论有"大中小"，但标准模糊
+- **缺少统一的情绪强度评分体系**
+
+**影响**:
+- AI模型难以学习情感曲线的起伏
+- 可能生成情绪平淡或过度的故事
+
+**改进方向**:
+```json
+{
+  "emotional_intensity_scale": {
+    "range": "1-10",
+    "1-3": "低强度（日常、平静、轻微不适）",
+    "4-6": "中强度（紧张、期待、失望）",
+    "7-9": "高强度（兴奋、愤怒、绝望）",
+    "10": "极致强度（高潮、崩溃、狂喜）"
+  },
+  "scene_example": {
+    "opening": {"intensity": 3, "emotion": "平静"},
+    "conflict": {"intensity": 6, "emotion": "紧张"},
+    "disaster": {"intensity": 8, "emotion": "震惊"},
+    "reaction": {"intensity": 7, "emotion": "愤怒"},
+    "decision": {"intensity": 5, "emotion": "决心"}
+  }
+}
+```
+
+---
+
+**Gap 6: 缺少对话设计指导**
+
+**问题描述**:
+- 所有方法论都关注情节结构
+- **但对对话设计的指导很少**
+- 对话是展现角色和推进情节的重要手段
+
+**影响**:
+- AI模型可能生成功能性对话，但缺少个性和冲突
+- 对话可能沦为信息传递工具
+
+**改进方向**:
+- 标注对话的功能（信息传递、冲突展现、角色塑造）
+- 标注对话的潜台词（表面说A，实际想B）
+- 标注对话的节奏（快速交锋vs慢速铺垫）
+- 提取"如何设计有冲突的对话"的思考链
+
+---
+
+### 3.3 验证层面的Gaps
+
+**Gap 7: 缺少自动化验证标准**
+
+**问题描述**:
+- MICE有嵌套验证，但其他方法论缺少
+- **大部分验证依赖人工判断**
+- 缺少可自动执行的验证规则
+
+**影响**:
+- AI生成的内容难以自动评估质量
+- 需要大量人工审核
+
+**改进方向**:
+```python
+# 可自动验证的规则示例
+validation_rules = {
+    "scene_sequel": {
+        "goal_clarity": "Goal必须包含明确的动词和对象",
+        "disaster_worse": "Disaster的结果必须比Goal预期更糟",
+        "decision_leads": "Decision必须成为下一个Scene的Goal"
+    },
+    "mice": {
+        "nesting": "后开启的线程必须先关闭",
+        "opening_closing": "每个Opening必须有对应的Closing"
+    },
+    "shuang_point": {
+        "density": "每4000字至少1个小爽点",
+        "setup_payoff": "每个Payoff必须有对应的Setup",
+        "reaction": "每个爽点必须有旁观者或主角的反应"
+    },
+    "hook": {
+        "chapter_end": "每章结尾必须有钩子",
+        "resolution_timing": "钩子必须在3章内满足"
+    }
+}
+```
+
+---
+
+**Gap 8: 缺少质量评分体系**
+
+**问题描述**:
+- 可以验证"是否符合规则"
+- **但缺少"符合得有多好"的评分**
+- 难以区分"及格"和"优秀"
+
+**影响**:
+- AI模型难以学习"什么是好的"
+- 可能生成符合规则但平庸的内容
+
+**改进方向**:
+```json
+{
+  "shuang_point_quality_score": {
+    "setup_quality": {
+      "score": 8,
+      "criteria": [
+        {"item": "铺垫充分", "score": 9, "weight": 0.3},
+        {"item": "对比强烈", "score": 8, "weight": 0.3},
+        {"item": "时机合适", "score": 7, "weight": 0.2},
+        {"item": "细节丰富", "score": 8, "weight": 0.2}
+      ]
+    },
+    "payoff_quality": {
+      "score": 9,
+      "criteria": [
+        {"item": "超出期待", "score": 9, "weight": 0.3},
+        {"item": "展示充分", "score": 9, "weight": 0.3},
+        {"item": "反应到位", "score": 8, "weight": 0.2},
+        {"item": "趣味性强", "score": 9, "weight": 0.2}
+      ]
+    },
+    "overall_score": 8.5
+  }
+}
+```
+
+---
+
+### 3.4 思考过程层面的Gaps
+
+**Gap 9: 缺少决策思考链的系统提取**
+
+**问题描述**:
+- Scene-Sequel有Dilemma，但只是结果，不是过程
+- 爽点理论有设计方法，但缺少思考步骤
+- **缺少"作者如何做决策"的完整思考链**
+
+**影响**:
+- AI模型难以学习创作思维
+- 可能生成合理但缺少深度的内容
+
+**改进方向**:
+```json
+{
+  "decision_chain": {
+    "question": "如何设计第4章的智商碾压爽点？",
+    "thinking_steps": [
+      {
+        "step": 1,
+        "question": "主角的优势是什么？",
+        "answer": "现代知识，特别是数学",
+        "reasoning": "穿越者的核心优势",
+        "alternatives_considered": ["武力", "权谋"],
+        "why_rejected": ["不符合人设", "太常见"]
+      },
+      {
+        "step": 2,
+        "question": "如何展示这个优势？",
+        "answer": "让古代人做不到，主角轻松做到",
+        "reasoning": "对比产生爽感",
+        "alternatives_considered": ["主角讲解知识", "主角预测未来"],
+        "why_rejected": ["太说教", "不够直观"]
+      },
+      // ... 更多步骤
+    ],
+    "final_decision": "设计'十五万两重几斤'的问题",
+    "confidence": 0.9,
+    "expected_effect": "高强度智商碾压爽点"
+  }
+}
+```
+
+---
+
+**Gap 10: 缺少失败案例分析**
+
+**问题描述**:
+- 现有方法论主要总结成功经验
+- **缺少"什么是不好的"的对比**
+- 缺少失败案例的分析
+
+**影响**:
+- AI模型难以学习"避免什么"
+- 可能重复常见错误
+
+**改进方向**:
+```json
+{
+  "comparison": {
+    "good_example": {
+      "setup": "官员们算不出税银重量",
+      "payoff": "许七安秒答",
+      "reaction": "猛的站起身",
+      "why_good": ["铺垫充分", "对比强烈", "反应到位"]
+    },
+    "bad_example": {
+      "setup": "主角说出答案",
+      "payoff": "官员们点头",
+      "reaction": "嗯，有道理",
+      "why_bad": ["没有铺垫", "反应平淡", "缺少细节"],
+      "how_to_fix": [
+        "先让官员们尝试计算但失败",
+        "主角秒答形成对比",
+        "用肢体语言描写震惊"
+      ]
+    }
+  }
+}
+```
+
+---
+
+### 3.5 适配层面的Gaps
+
+**Gap 11: 缺少跨文化适配指导**
+
+**问题描述**:
+- Save the Cat源自好莱坞
+- 爽点理论源自中国网文
+- **缺少"如何根据目标市场调整"的指导**
+
+**影响**:
+- AI模型可能生成"水土不服"的内容
+- 难以适应不同市场需求
+
+**改进方向**:
+```json
+{
+  "cultural_adaptation": {
+    "save_the_cat_for_chinese_webnovel": {
+      "catalyst": {
+        "original": "10%",
+        "adapted": "5-8%",
+        "reason": "网文需要更快节奏"
+      },
+      "debate": {
+        "original": "10-20%",
+        "adapted": "压缩或省略",
+        "reason": "用外部压力替代内心犹豫"
+      },
+      "fun_and_games": {
+        "original": "20-50%",
+        "adapted": "密集爽点",
+        "reason": "网文需要高频满足"
+      }
+    }
+  }
+}
+```
+
+---
+
+**Gap 12: 缺少类型特定的变体**
+
+**问题描述**:
+- 现有方法论相对通用
+- **不同类型（玄幻、言情、科幻）有不同特点**
+- 缺少类型特定的调整指导
+
+**影响**:
+- AI模型可能生成"类型不纯"的内容
+- 难以满足特定类型读者的期待
+
+**改进方向**:
+```json
+{
+  "genre_variations": {
+    "玄幻": {
+      "primary_shuang_type": "升级、碾压",
+      "mice_focus": "Event（拯救世界）+ Character（废柴逆袭）",
+      "pacing": "快节奏，高频战斗",
+      "golden_finger": "系统、体质、传承"
+    },
+    "言情": {
+      "primary_shuang_type": "甜、虐",
+      "mice_focus": "Character（情感转变）+ Idea（误会解除）",
+      "pacing": "慢节奏，细腻描写",
+      "golden_finger": "美貌、才华、背景"
+    },
+    "科幻": {
+      "primary_shuang_type": "智商碾压、获得",
+      "mice_focus": "Idea（科学谜题）+ Event（危机解决）",
+      "pacing": "中等节奏，逻辑严密",
+      "golden_finger": "科技、知识、预知"
+    }
+  }
+}
+```
+
+---
+
+## 四、改进空间总结
+
+### 4.1 急需补充的维度
+
+**优先级1（核心缺失）**:
+
+1. **多层次整合框架**
+   - 宏观-中观-微观的分解机制
+   - 不同层次之间的映射关系
+   - 整合验证规则
+
+2. **思考过程系统提取**
+   - 完整的决策思考链
+   - 替代方案的考虑和拒绝理由
+   - 失败案例的对比分析
+
+3. **情绪强度量化**
+   - 统一的1-10评分体系
+   - 情感曲线的数值化
+   - 爽点强度的客观标准
+
+**优先级2（重要补充）**:
+
+4. **多线程场景处理**
+   - 多Goal、多Disaster的结构
+   - 线程交织的处理机制
+   - 复杂场景的拆解方法
+
+5. **对话设计指导**
+   - 对话功能标注
+   - 潜台词提取
+   - 冲突对话的设计方法
+
+6. **自动化验证标准**
+   - 可执行的验证规则
+   - 质量评分体系
+   - 自动化检查工具
+
+**优先级3（优化提升）**:
+
+7. **结构变化机制**
+   - 何时可以打破规则
+   - 创新的边界
+   - 惊喜的设计方法
+
+8. **跨文化适配**
+   - 不同市场的调整指导
+   - 类型特定的变体
+   - 读者期待的差异
+
+---
+
+### 4.2 改进后的方法论架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    宏观层（故事整体）                      │
+│  ┌──────────────┐        ┌──────────────┐               │
+│  │ MICE线程管理 │ ←整合→ │ Save the Cat │               │
+│  │  + 嵌套验证  │        │  + 情感曲线  │               │
+│  └──────────────┘        └──────────────┘               │
+│         ↓ 分解机制                ↓                      │
+└─────────────────────────────────────────────────────────┘
+         ↓                          ↓
+┌─────────────────────────────────────────────────────────┐
+│                    中观层（章节段落）                      │
+│  ┌──────────────┐        ┌──────────────┐               │
+│  │ 起承转合结构 │ ←整合→ │ 爽点钩子布局 │               │
+│  │  + 节奏控制  │        │  + 密度管理  │               │
+│  └──────────────┘        └──────────────┘               │
+│         ↓ 分解机制                ↓                      │
+└─────────────────────────────────────────────────────────┘
+         ↓                          ↓
+┌─────────────────────────────────────────────────────────┐
+│                    微观层（场景细节）                      │
+│  ┌──────────────┐        ┌──────────────┐               │
+│  │Scene-Sequel  │ ←整合→ │  对话设计    │               │
+│  │  + 多线程    │        │  + 潜台词    │               │
+│  └──────────────┘        └──────────────┘               │
+└─────────────────────────────────────────────────────────┘
+         ↓                          ↓
+┌─────────────────────────────────────────────────────────┐
+│                  思考过程层（CoT提取）                     │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
+│  │ 结构决策链   │  │ 爽点设计链   │  │ 对话设计链   │  │
+│  └──────────────┘  └──────────────┘  └──────────────┘  │
+└─────────────────────────────────────────────────────────┘
+         ↓                          ↓
+┌─────────────────────────────────────────────────────────┐
+│                  验证评估层（质量保证）                     │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
+│  │ 结构验证     │  │ 质量评分     │  │ 对比学习     │  │
+│  │ （自动化）   │  │ （量化）     │  │ （好vs坏）   │  │
+│  └──────────────┘  └──────────────┘  └──────────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+### 4.3 具体改进建议
+
+**建议1: 建立多层次整合标注规范**
+
+```json
+{
+  "story_id": "example_001",
+  "macro_layer": {
+    "mice_threads": [...],
+    "save_the_cat_beats": [...],
+    "decomposition_to_meso": {
+      "beat_to_chapters": {
+        "Catalyst": {"chapters": [1, 2], "reason": "需要2章展开"},
+        "Fun_and_Games": {"chapters": [3, 4, 5, 6], "reason": "密集爽点阶段"}
+      }
+    }
+  },
+  "meso_layer": {
+    "chapters": [...],
+    "decomposition_to_micro": {
+      "chapter_to_scenes": {
+        "chapter_4": {
+          "scenes": ["S4_1", "S4_2", "S4_3"],
+          "reason": "起承转合需要3个场景"
+        }
+      }
+    }
+  },
+  "micro_layer": {
+    "scenes": [...],
+    "support_to_meso": {
+      "S4_2": {
+        "supports_shuang_point": "SP_C4_002",
+        "supports_hook": "H_C4_002"
+      }
+    }
+  }
+}
+```
+
+**建议2: 建立思考过程提取模板**
+
+```json
+{
+  "decision_type": "爽点设计",
+  "context": {...},
+  "thinking_chain": [
+    {
+      "step": 1,
+      "question": "...",
+      "answer": "...",
+      "reasoning": "...",
+      "alternatives": [...],
+      "rejection_reasons": [...]
+    }
+  ],
+  "final_decision": "...",
+  "confidence": 0.9,
+  "expected_effect": "...",
+  "actual_effect": "..." // 事后评估
+}
+```
+
+**建议3: 建立情绪强度标注规范**
+
+```json
+{
+  "emotional_intensity_scale": {
+    "range": "1-10",
+    "calibration_examples": {
+      "1": "平静的日常对话",
+      "5": "中等紧张的冲突",
+      "10": "生死存亡的高潮"
+    }
+  },
+  "scene_emotional_curve": [
+    {"position": 0, "intensity": 3, "emotion": "平静"},
+    {"position": 500, "intensity": 6, "emotion": "紧张"},
+    {"position": 1000, "intensity": 9, "emotion": "震惊"}
+  ]
+}
+```
+
+**建议4: 建立对比学习数据集**
+
+```json
+{
+  "comparison_pairs": [
+    {
+      "aspect": "爽点设计",
+      "good_example": {...},
+      "bad_example": {...},
+      "key_differences": [...],
+      "improvement_suggestions": [...]
+    }
+  ]
+}
+```
+
+**建议5: 建立自动化验证规则库**
+
+```python
+validation_rules = {
+    "structure": {
+        "mice_nesting": validate_mice_nesting,
+        "scene_sequel_chain": validate_scene_sequel_chain,
+        "beat_position": validate_beat_position
+    },
+    "content": {
+        "shuang_point_density": validate_shuang_density,
+        "hook_resolution": validate_hook_resolution,
+        "emotional_curve": validate_emotional_curve
+    },
+    "quality": {
+        "shuang_point_quality": score_shuang_point,
+        "dialogue_quality": score_dialogue,
+        "overall_quality": score_overall
+    }
+}
+```
+
+---
+
+## 五、总结与行动建议
+
+### 5.1 现有方法论的核心价值
+
+**Scene-Sequel**: 微观因果逻辑的基石  
+**MICE**: 宏观结构管理的框架  
+**Save the Cat**: 情感曲线设计的指南  
+**爽点理论**: 读者粘性维持的法宝
+
+**它们的组合已经覆盖了叙事的主要维度，但需要进一步整合和补充。**
+
+### 5.2 最关键的3个改进方向
+
+1. **建立多层次整合框架**
+   - 补充宏观-中观-微观的分解和整合机制
+   - 这是让AI理解"整体-局部"关系的关键
+
+2. **系统提取思考过程**
+   - 不仅标注"是什么"，更要提取"为什么这样设计"
+   - 这是让AI学会创作思维的关键
+
+3. **建立量化评估体系**
+   - 情绪强度量化
+   - 质量评分标准
+   - 自动化验证规则
+   - 这是让AI自我优化的关键
+
+### 5.3 下一步行动
+
+**第一阶段（1-2周）**:
+- [ ] 设计多层次整合标注规范
+- [ ] 选择3-5个优质样本进行完整标注
+- [ ] 建立思考过程提取模板
+
+**第二阶段（2-3周）**:
+- [ ] 建立情绪强度标注规范
+- [ ] 建立对比学习数据集（好vs坏）
+- [ ] 开发自动化验证工具
+
+**第三阶段（3-4周）**:
+- [ ] 训练初版模型
+- [ ] 评估生成质量
+- [ ] 根据反馈迭代优化
+
+---
+
+**文档状态**: v1.0 - 分析完成  
+**下一步**: 设计改进的方法论v2.0

examples/analyze_story/knowledge/1_scene_sequel_theory.md

@@ -0,0 +1,170 @@
+# 场景-后继理论 (Scene-Sequel Theory)
+
+## 理论概述
+
+场景-后继理论（Scene-Sequel）是由美国作家德怀特·斯温（Dwight Swain）在其经典著作《畅销作家的技巧》（*Techniques of the Selling Writer*，1965）中提出的叙事结构理论。这是一种帮助作家创建连贯且引人入胜故事的叙事模式，通过在两种场景类型之间交替来保持稳定的节奏、建立张力和创造情感深度。
+
+## 核心概念
+
+故事由一系列**场景（Scene）**和**后继（Sequel）**构成，它们是故事的基本单元。场景和后继的交替循环构成了整个故事的骨架。
+
+### 场景（Scene）- 行动部分
+
+场景是人物经历冲突和斗争的关键时刻，是主动的故事单元。场景以实时发生，从一个角色的视角展开，推动整体故事前进。
+
+**场景的三要素：**
+
+1. **目标（Goal）**
+   - 人物采取行动的决定
+   - 必须足够具体、明确、迫切，让人马上采取行动
+   - 可以是：获得某些东西、摆脱某种困境、报复某种伤害
+   - 强有力的目标：角色想要X，同时试图避免Y（例如：想获得信息但不暴露自己已知的内容）
+
+2. **冲突（Conflict）**
+   - 为实现目标与阻碍做的斗争
+   - 最好的冲突：加入与剧情相关但人物意料之外的新变化、新阻碍
+   - 通过增强反对力量，让人物经受磨难，无法一下子成功
+   - 需要有意图的对立意志，而非简单的障碍
+
+3. **灾难（Disaster）**
+   - 让人物蒙受意料之外、情理之中的损失和伤害
+   - 以发生新变化的形式出现
+   - 用来吸引读者，为未来提出吸引人的悬念
+
+### 后继（Sequel）- 反应部分
+
+后继是连接两个场景之间的过渡单元，是被动的故事单元。它陈述了人物对刚刚完结场景的反应，并为即将到来的下一个场景提供刺激。
+
+**后继的三要素：**
+
+1. **反应（Reaction）**
+   - 灾难带来的后果，包括现实影响和心理影响
+   - 人物对场景结果的情感反应
+   - 允许角色回顾事实并处理情境的逻辑选项
+
+2. **困境（Dilemma）**
+   - 一个没有完美选项的情况
+   - 人物从多个不完美的选项中选择最有可能应对当前困境的策略
+   - 让读者感同身受，强化不可退缩的原因
+
+3. **决定（Decision）**
+   - 人物做出选择，形成新目标
+   - 这个决定构成下一个场景的目标
+   - 必须在页面上通过角色的言行体现出来
+
+## 场景-后继循环
+
+```
+场景（目标→冲突→灾难）→ 后继（反应→困境→决定）→ 场景（新目标→冲突→灾难）→ ...
+```
+
+这种循环创造了紧密的因果关系网：
+- 每个场景的灾难导致后继的反应
+- 后继的决定成为下一个场景的目标
+- 如果没有这种因果关系，情节就不成立，而是一串随机事件
+
+## 功能与作用
+
+### 场景的功能
+1. **提供兴趣点** - 让人物遭遇阻碍，让读者好奇之后的成败变化
+2. **推动故事发展** - 改变人物境遇，推动剧情前进
+3. **制造最大化冲突** - 通过目标-冲突-灾难的结构
+
+### 后继的功能
+1. **将灾难转化为目标** - 建立场景间的逻辑联系
+2. **压缩现实** - 缩短必须但不重要的时间、空间、细节描写
+3. **控制节奏** - 通过高峰和低谷的交替强调高潮的重要性
+4. **人物发展** - 最重要的人物发展发生在后继中
+5. **主题发展** - 在反思、反讽和潜台词的安静时刻展现主题
+
+## 写作要点
+
+### 场景写作三要
+1. 在场景开始就设置时间、场所、环境和视角
+2. 尽快说明人物的场景目标（半页之内）
+3. 写好结束语，给出出人意料的灾难
+
+### 场景写作三不要
+1. 不要写得太短
+2. 不要陷入闪回（会让故事停滞）
+3. 不要滥用概括（要详细描写过程）
+
+### 后继写作要点
+1. **压缩** - 用感觉作为主线，忽略实施，强调情绪
+2. **过渡** - 用情绪在时间、空间、状态间前后呼应
+3. **可信度** - 通过真实细节、合理逻辑、清晰思考链条建立
+
+## 节奏控制
+
+通过分配场景和后继的比例来控制故事节奏：
+- **宏大的场景 = 强烈的兴趣**
+- **更长的后续 = 更强的合理性**
+
+调整建议：
+- 如果故事变得拖沓、乏味 → 增强场景，制造冲突
+- 如果故事有不真实感 → 延长后继，增强心理描写
+
+## 内在性（Interiority）的重要性
+
+贯穿整个场景，读者需要了解角色如何处理正在发生的事情：
+- 当冲突升级时，感受角色的恐惧或挫折
+- 当转折点出现时，实时体验角色的认知
+- 当面临艰难决定时，感受决定的分量
+
+内在性是小说独特的力量所在，是摄像机无法捕捉的东西。
+
+## 常见问题与解决
+
+### 场景常见问题
+1. **方向混乱** → 需要关键人物作为向导
+2. **目标太脆弱、太分散** → 瞄准一个短期、紧迫的具体目标
+3. **人物太软弱** → 逼迫人物，让他退无可退
+4. **缺乏紧迫感** → 增加时间压力
+5. **反对力量太分散/太弱** → 需要一个核心对立面，且要足够强大
+6. **场景零散琐碎** → 用强有力的新变化串联
+7. **灾难不自然** → 必须有逻辑性，不能依靠偶然
+
+## 实际应用示例
+
+### 《哈利·波特与魔法石》- 分院仪式场景
+- **场景目标**：哈利想被分到任何学院，除了斯莱特林
+- **场景对抗者**：分院帽认为斯莱特林最适合哈利
+- **冲突**：两者对"最佳归属"有不同看法
+- **转折点**：哈利内心强烈抗拒
+- **决定**：哈利坚持自己的选择
+- **结果**：被分到格兰芬多
+
+### 《傲慢与偏见》- 凯瑟琳夫人访问场景
+- **场景目标**：伊丽莎白要维护自主权，不被威胁
+- **场景对抗者**：凯瑟琳夫人要求她拒绝达西的求婚
+- **冲突**：地位与尊严的对抗
+- **结果**：伊丽莎白拒绝承诺
+
+## 理论价值
+
+场景-后继理论提供了：
+1. **结构化框架** - 清晰的场景构建模板
+2. **因果逻辑** - 确保故事的连贯性和真实感
+3. **节奏控制** - 通过行动与反应的交替控制阅读体验
+4. **人物深度** - 在后继中实现人物和主题的深度发展
+5. **情感共鸣** - 通过内在性让读者与角色建立情感连接
+
+## 原始来源链接
+
+### 中文资源
+1. [学写作 | 什么是续集场景？- 知乎](https://zhuanlan.zhihu.com/p/400775304)
+2. [故事基本单元--《畅销书写作技巧》笔记2 - 知乎](https://zhuanlan.zhihu.com/p/108338671)
+3. [如何理解写作是一个完整的、动态的行为过程 - 知乎](https://www.zhihu.com/question/350143181/answer/3352080781)
+
+### 英文资源
+1. [Scene Structure Made Easy: The 5 Essential Elements Every Scene Needs - Savannah Gilbo](https://www.savannahgilbo.com/blog/how-to-structure-a-scene)
+2. [The Scene and Sequel Pattern for Writers - Cody Burleson](https://codyburleson.com/blog/scene-and-sequel-pattern-for-writers)
+3. [How to Write a Scene: A Guide to Scene and Sequel Structure - Bridge Publisher](https://bridgepublisher.com/how-to-write-a-scene)
+4. [Not Just for Series: Using Scenes and Sequels for Compelling Fiction - Beacon Point](https://beaconpointservices.org/not-just-for-series-using-scenes-and-sequels-for-compelling-fiction)
+
+### 原著
+- Swain, Dwight V. (1965). *Techniques of the Selling Writer*. University of Oklahoma Press.
+
+---
+
+*最后更新：2025年*

examples/analyze_story/knowledge/samples_overview.md

@@ -0,0 +1,831 @@
+# 样本文件分析报告
+**分析时间**: 2024
+**文件总数**: 6
+
+---
+
+## 📊 文件类型统计
+- **电影剧本**: 2 个
+- **网络小说**: 4 个
+
+---
+
+## 📝 文件详细分析
+
+### 1. 中国合伙人.pdf
+
+**文件类型**: 电影剧本
+**文件格式**: PDF
+**文件长度**: 68,249 字符
+
+**结构特征**: 剧本格式，包含场景编号、人物、对话和动作描述
+
+**前3000字内容预览**:
+```
+《中国合伙人》中文剧本                                                           剧本君—整理 
+ 
+剧本君的电影世界（微信号：jbjddys j）                                                     1 
+ 
+ 
+ 
+ 
+ 
+ 
+中国合伙人 
+ 
+编剧：周智勇 张翼 
+ 
+ 
+中文剧本 
+ 
+整理：剧本君 
+微信号 ：jbjddysj  
+ 
+ 
+ 
+想要更多的中文剧本 ，请关注 “剧本君的电影世界 ”吧 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+《中国合伙人》中文剧本                                                           剧本君—整理 
+ 
+剧本君的电影世界（微信号：jbjddys j）                                                     2 
+ 
+1. 北京美国领事馆  日 
+字幕：1984 
+签证窗口。成东青、孟晓骏、王阳相邻而坐，面对各自窗口后的白人签证官。 孟晓
+骏胜券在握，王阳轻松洒脱，唯独成东青右手紧握左手，紧张僵硬。  
+签证官甲注意到成东青的紧张。 
+签证官甲：你念完书后有没有在美国停留的计划？  
+成东青：没有。我一定会回中国。 
+签证官甲看着成东青，看起来他并不相信成东青的话。  
+签证官甲：你的偶像是谁？ 
+这是一个完全意料不到的问题，但他还是真诚地回答：孟晓骏。  
+签证官甲心中疑惑。 
+切到孟晓骏。 
+签证官乙：孟晓骏先生，Congratulations！ 
+孟晓骏：Thank You. 
+签证官丙：很好，王阳先生…… 
+王阳终于做出决定，他打断了签证官。 
+王阳：Sorry，我放弃签证。 
+签证官丙：Why？ 
+王阳微笑耸肩，像一个标准的美国人。 
+签证官甲瞪着成东青，成东青紧张等待宣判。  
+（成东青 VO：他不会想到，20 年后，我最擅长的事就是帮人去美国）  
+2. MONTAGE 
+2003。 
+△主题音乐贯穿。 
+成东青、 孟晓骏、 王阳3 人站在 CBD 新梦想高楼前。（成东青 VO：在一般人看来，
+这里只是个教中国人学英语的地方） 
+△画面快速剪切： 
+现代化的新梦想校门前，大学生们挥手合影；  
+校内宿舍成群； 
+各省学生来京，新梦想开学大堵车； 
+学生人流拥进校门。 
+（成东青 VO：对他们而言，这里够酷， 这里每到开学就堵车， 当然， 最重要的是，
+这里通往美国） 
+《中国合伙人》中文剧本                                                           剧本君—整理 
+ 
+剧本君的电影世界（微信号：jbjddys j）                                                     3 
+ 
+学生们分流进各个教室。 
+高楼上的落地玻璃后，成东青、孟晓骏、王阳 3 人隔窗俯瞰众生。  
+成东青感慨良多。 
+孟晓骏仿佛在玻璃的显影中看见一排闪现的数字 „„ 
+△屏幕上托福和 GRE 的高分成绩单闪现。 
+（孟晓骏 VO：这是新梦想学生考托福、GRE 以及雅思的分数，美国人问我，怎么
+可能这么高，你们一定是舞弊了，美国人有时候就是这么天真）  
+△CBD 新梦想办公室。 
+墙上悬挂巨幅美国地图，上面各州大学插满了红旗标记。  
+成东青、孟晓骏、王阳 3 人站在图前，点燃古巴雪茄，青烟拂过，笑看风云。  
+（孟晓骏 VO：20 年后，1000 个在美国留学的中国学生，四分之三出自新梦想，我
+们的赤旗已插遍整个美利坚） 
+（音乐，《国际歌》，英特纳雄耐尔就一定会实现）  
+3. 2003 年新梦想大教室  日 
+众学生听课。 
+王阳站在讲台上讲课。 
+（成东青 VO：王阳说，100 年来，中国人一直都是闭着嘴说英语）  
+王阳： 你们为什么不敢开口， 因为你们已经被传统教育摧毁了自信， 你们不敢表达，
+怕自己的 broken Englis。说了让别人难受！ 但是， 你英语讲得烂， 难受的是听的人，
+你怕什么？ 
+众学生欢笑，定格。 
+（成东青 VO：他说，要想开口，首先你要开心）  
+4. 2003 年签证咨询处  日 
+孟晓骏独自面对着一个沮丧的女学生。 
+（成东青 VO：孟晓骏这个人， 不爱当众讲话， 他喜欢私聊， 你以为他跟你聊签证，
+其实他是跟你聊美国） 
+孟晓骏：因为你不自信。自信是美国文化对个人的基 本要求，也是签证官最喜欢看
+见的。 
+女学生：可是孟老师，我根本就不自信！我害怕被拒！  
+孟晓骏： 你的勇气。Courage is resistance to fear ，mastery of fear ，not absence of fear 。
+勇气是抵御恐惧，把握恐惧，而不是没有恐惧。  
+女学生爱戴的目光。 
+（成东青 VO：最后，通常他都会聊到中美关系）  
+孟晓骏：你对中美关系怎么看？ 
+女学生（鼓起勇气）：孟老师，我暗恋你，已经一年多了。  
+《中国合伙人》中文剧本                                                           剧本君—整理 
+ 
+剧本君的电影世界（微信号：jbjddys j）                                                     4 
+ 
+孟晓骏（一愣，随后恢复镇定）：我已经结婚了。  
+女学生：我知道。现在，至少你看见了我的 Courage。 
+孟晓骏显得无可奈何。 
+5. 孟晓骏老宅（七十年代至八十年代）  日 
+70 岁的祖父从书箱里取出一本暗藏的英文小词典交给 6 岁的孟晓骏， 孟晓骏视作神
+物。我们同时看见隔壁 6 岁的良琴在笨拙弹奏练习曲，发际上佩戴一只蓝色的蝴蝶
+发卡。 
+（成东青 VO：孟晓骏的爷爷是 1925 年回国的留美博士，给了他第一本英文 词典 ） 
+祖父变成了墙上的一张遗像， 40 岁的父亲从书箱里取出一本暗藏的英文大词典交给
+12 岁的孟晓骏。隔壁 12 岁良琴的弹奏已颇显熟练，我们仍能看见她发际上的蓝色
+蝴蝶发卡。 
+（成东青 VO：他爸爸是 1955 年回国的留美博士，给了他第二本英文词典）  
+20 岁的孟晓骏朗诵英文课本，字正腔圆。  
+隔壁 20 岁的良琴弹奏肖邦，如行云流水。  
+孟晓骏结束背诵，良琴恰好弹完最后一个音，蓝色蝴蝶发卡振翅欲飞。  
+二人爱慕的目光仿佛穿透墙壁。 
+（成东青 VO：美国是孟晓骏的家族遗传，是他的命中注定）  
+△燕京大学校园。良琴挽着孟晓骏的手，站在午后的操场，头顶是高高的蓝天，他
+俩对着镜头微笑，笑容特别八十年代。 
+（成东青 VO：就像他和良琴的爱情） 
+6. 2003 年创业大会  日 
+名贵齐集，其中包括美国卸任总统克林顿（由背影、侧面看出）在座下听讲。  
+成东青站在台上演讲。 
+孟晓骏听众席前排，一边望着成东青，一边在 Notebook 上画着什么。  
+（孟晓骏 VO：20 年后，成东青不得不在各种场合发表
+```
+
+---
+
+### 2. 大奉打更人.txt
+
+**文件类型**: 网络小说
+**文件格式**: TXT
+**文件编码**: gbk
+**文件长度**: 4,157,760 字符
+**作者**: 卖报小郎君
+
+**内容简介**:
+```
+这个世界，有儒；有道；有佛；有妖；有术士。
+　　警校毕业的许七安幽幽醒来，发现自己身处牢狱之中，三日后流放边陲……
+　　他起初的目的只是自保，顺便在这个没有人权的社会里当个富家翁悠闲度日。
+　　……
+　　多年后，许七安回首前尘，身后是早已逝去的敌人，以及累累白骨。
+　　滚滚长江东逝水，浪花淘尽英雄，是非成败转头空。
+　　青山依旧在，几度夕阳红。
+```
+
+**章节预览**:
+- 第一章 牢狱之灾
+
+**结构特征**: 网文格式，分章节叙事
+
+**前3000字内容预览**:
+```
+==========================================================
+
+☆本文由TXT小说网网友分享，版权归原作者所有☆
+
+☆请勿用于商业行为，一切后果自负☆
+
+☆TXT小说网-免费电子书下载☆
+
+☆https://www.txtxs.cn☆
+
+==========================================================
+大奉打更人
+作者：卖报小郎君
+
+内容简介：
+　　这个世界，有儒；有道；有佛；有妖；有术士。
+　　警校毕业的许七安幽幽醒来，发现自己身处牢狱之中，三日后流放边陲……
+　　他起初的目的只是自保，顺便在这个没有人权的社会里当个富家翁悠闲度日。
+　　……
+　　多年后，许七安回首前尘，身后是早已逝去的敌人，以及累累白骨。
+　　滚滚长江东逝水，浪花淘尽英雄，是非成败转头空。
+　　青山依旧在，几度夕阳红。
+　　PS：本书不悲剧！
+
+
+第一卷 京察风云
+
+
+第一章 牢狱之灾
+　　大奉京兆府，监牢。
+　　许七安幽幽醒来，嗅到了空气中潮湿的腐臭味，令人轻微的不适，胃酸翻涌。
+　　这扑面而来的臭味是怎么回事，家里的二哈又跑床上拉屎来了……根据熏人程度，怕不是在我头顶拉的……
+　　许七安家里养了一条狗，品种哈士奇，俗称二哈。
+　　北漂了十年，孤孤单单的，这人啊，寂寞久了，难免会想养条狗里慰藉和消遣……不是肉体上。
+　　睁开眼，看了下周遭，许七安懵了一下。
+　　石块垒砌的墙壁，三个碗口大的方块窗，他躺在冰凉的破烂草席上，阳光透过方块窗照射在他胸口，光束中尘糜浮动。
+　　我在哪？
+　　许七安在怀疑人生般的迷茫中沉思片刻，然后他真的怀疑人生了。
+　　我穿越了……
+　　狂潮般的记忆汹涌而来，根本不给他反应的机会，强势插入大脑，并快速流动。
+　　许七安，字宁宴，大奉王朝京兆府下辖长乐县衙的一名捕快。月俸二两银子一石米。
+　　父亲是老卒，死于十九年前的‘山海战役’，随后，母亲也因病去世……想到这里，许七安稍稍有些欣慰。
+　　众所周知，父母双亡的人都不简单。
+　　“没想到重活了，还是逃不掉当警察的宿命？”许七安有些牙疼。
+　　他前世是警校毕业，成功进入体制，捧起了金饭碗。
+　　可是，许七安虽然走了父母替他选择的道路，他的心却不在人民公仆这个职业上。
+　　他喜欢无拘无束，喜欢自由，喜欢纸醉金迷，喜欢季羡林在日记本里的一句话：——
+　　于是悍然辞职，下海经商。
+　　“可我为什么会在监狱里？”
+　　他努力消化着记忆，很快就明白自己眼下的处境。
+　　许七安自幼被二叔养大，因为常年习武，每年要吃掉一百多两银子，因此被婶婶不喜。
+　　18岁修炼到炼精巅峰后，便停滞不前，迫于婶婶的压力，他搬离许宅独自居住。
+　　通过叔叔的关系，在衙门里混了个捕快的差事，原本日子过的不错，谁想到……
+　　三天前，那位在御刀卫当差的七品绿袍二叔，护送一批税银到户部，途中出了意外，税银丢失。
+　　整整十五万两白银。
+　　朝野震动，圣上勃然大怒，亲自下令，许平志于五日后斩首，三族亲属连坐，男丁发配边疆，女眷送入教坊司。
+　　作为许平志的亲侄儿，他被解除了捕快职务，打入京兆府大牢。
+　　两天！
+　　再有两天时间，他就要被流放到凄苦荒凉的边陲之地，在劳碌中度过下半辈子。
+　　“开局就是地狱模式啊……”许七安脊背发凉，心跟着凉了半截。
+　　这个世界处在封建王朝统治的状态，没有人权的，边陲是什么地方？
+　　荒凉，气候恶劣，大部分被发配边境的犯人，都活不过十年。而更多的人，还没到边陲就因为各种意外、疾病，死于途中。
+　　想到这里，许七安头皮一炸，寒意森森。
+　　“系统？”
+　　沉默了片刻，寂静的监牢里响起许七安的试探声。
+　　系统不搭理他。
+　　“系统……系统爸爸，你出来啊。”许七安声音透着急切。
+　　寂静无声。
+　　没有系统，竟然没有系统！
+　　这意味着他几乎没办法改变现状，两天后，他就要戴上镣铐和枷锁，被送往边陲，以他的体魄，应该不会死于途中。
+　　但这并不是好处，在充当工具人的生涯里被压榨劳动力，最后死去……
+　　太可怕，太可怕了！
+　　许七安对穿越古代这件事的美好幻想，如泡沫般破碎，有的只有焦虑和恐惧。
+　　“我必须想办法自救，我不能就这样狗带。”
+　　许七安在狭小的监牢里踱步打转，像是热锅上的蚂蚁，像是掉落陷阱的野兽，苦思对策。
+　　我是炼精巅峰，身体素质强的吓人……但在这个世界属于不屈白银，越狱是不可能的……
+　　靠宗族和朋友？
+　　许家并非大族，族人分散各地，而整整十五万两的税银被劫，谁敢在这个节骨眼上求情？
+　　根据大奉律法，将功补过，便可免除死罪！
+　　除非找回银子……
+　　许七安的眼睛猛的亮起，像极了濒临溺毙的人抓住了救命稻草。
+　　他是正儿八经的警校毕业，理论知识丰富，逻辑清晰，推理能力极强，又阅读过无数的案例。
+　　或许可以试着从破案这方面入手，追回银子，戴罪立功。
+　　但随后，他眼里的光芒黯淡。
+　　想要破案，首先要看卷宗，明白案件的详细经过。之后才是调查、破案。
+　　如今他深陷大牢，叫天天不应叫地地不灵，两天后就送去边陲了！
+　　无解！
+　　许七安一屁股坐在地上，双目失神。
+　　他昨儿在酒吧喝的伶仃大醉，醒来就在监狱里，想来可能是酒精中毒死掉了才穿越吧。
+　　老天爷赏赐了穿越的机会，不是让他重活，是觉得他死的太轻松了？
+　　在古代，发配是仅次于死刑的重刑。
+　　上辈子虽然被社会毒打，好歹活在一个太平盛世，你说重生多好啊，二话不说，偷了父母的积蓄就去买房子。
+　　然后配合老妈，把爱炒股的老爹的手打断，让他当不成韭菜。
+　　这时，幽暗走廊的尽头传来锁链划动的声音，应该是门打开了。
+　　继而传来脚步声。
+　　一名狱卒领着一位神容憔悴的俊俏书生，在许七安的牢门前停下。
+　　狱卒看了书生一眼：“半炷香时间。”
+　　书生朝狱卒拱手作揖，目送狱卒离开后，他转过身来正面对着许七安。
+　　书生穿着月白色的袍子，乌黑的长发束在玉簪上，模样甚是俊俏，剑眉星目，嘴唇很薄。
+　　许七安脑海里浮现此人的相关记忆。
+　　许家二郎，许新年。
+　　二叔的亲儿子，许七安的堂弟，今年秋闱中举。
+　　许新年平静的直视着他：“押送你去边陲的士卒收了我三百两，这是我们家仅剩的银子了，你安心的去，途中不会有意外的。”
+　　“那你呢？”许七安鬼使神差的说出这句话，他记得原主和这位堂弟的关系并不好。
+　　因为婶婶讨厌他的关系，许家除了二叔，其他人并不怎么待见许七安。至少堂弟堂妹不会表现的与他太过亲近。
+　　除此之外，在原主的记忆里，这位堂弟还是个擅长口吐芬芳的嘴强王者。
+　　许新年不耐烦道：“我已被革除功名，但有书院师长护着，不需要发配。管好你自己就行了。去了边陲，收敛脾气，能活一年是一年。”
+　　许新年在京都赫赫有名的云鹿书院求学，颇受重视，又是新晋举人。因此，二叔出事后，他没有被下狱，但不允许离开京都，多天来一直各方奔走。
+　　许七安沉默了，他不觉得许新年会比自己更好，恐怕不只是革除功名，还得入贱籍，子子孙孙不得科举，不得翻身。
+　　且，两天后，许家女眷会被送入教坊司，受到凌辱。
+　　许新年是读书人，他如何还有脸在京城活下去？或许被发配边疆才是更好的选择。
+　　许七安心里一动，往前扑了
+```
+
+---
+
+### 3. 搜神记.txt
+
+**文件类型**: 网络小说
+**文件格式**: TXT
+**文件编码**: gb18030
+**文件长度**: 1,485,782 字符
+
+**结构特征**: 网文格式，分章节叙事
+
+**前3000字内容预览**:
+```
+==========================================================
+
+☆本文由盘小说网网友分享，版权归原作者所有☆
+
+☆请勿用于商业行为，一切后果自负☆
+
+☆盘小说网-免费电子书下载☆
+
+☆https://www.panxs.cc☆
+
+==========================================================
+　　楔子
+
+　　正午时分，烈日当空，海风炎热，无边无垠的海面泛着白光，惨碧的波浪轻轻摇曳。南边突然响起一个平空惊雷，滚滚乌云瞬时间从海平线翻腾蔓延。
+
+　　一艘柚木桨船上，一个中年汉子站在船头，迎风而立，手握千里镜，向东南方向眺望。旁边坐了一个十二三岁的少年，不住的问道：“爹，看见了没有？”十二个桨手听了齐声大笑：“公子爷，你也忒性急了。哪有一出海便有收获的？”那少年恼道：“为了找它，已经出海七次，每次都是空手而归，怎不让人着急！”中年汉子朗声大笑：“小子，倘若都象你这般心急，我们便只能去撒网捕鱼了。”众人哈哈大笑。
+
+　　雷声滚滚，乌云急速凝聚，向北翻涌而来。天色迅速变暗，太阳被漫天乌云遮蔽，海风也很快转冷，一阵阵刮来，竟颇有凉意。
+
+　　舵手道：“城主，浪开始大了，只怕是有风暴。”中年汉子道：“不妨事。大伙儿将舷翼合拢，倘若风暴一来，便立即圆舱。”话音未落，海面忽然狂风大作，一阵激浪卷来，险些将桨船掀翻。
+
+　　舵手大叫：“圆舱圆舱！”中年汉子喝道：“且慢！”众人一愣，少年突然大喜：“爹，是它！”中年汉子沉声道：“转舵正坤位，收桨，平衡船身，原地待命。”船身缓缓掉转，在汹涌的海浪中跌宕浮沉。少年挤到船头，满脸兴奋之色，在苍茫的海面上搜寻着。
+
+　　雷声更盛，乌云涌动，覆盖了整个天空，顷刻间，海面暗如黑夜，波涛汹涌。偶尔一道雪亮的闪电将天地映得雪白。
+
+　　海浪一浪高过一浪，船身摇摆越来越剧烈，众桨手虽饱经风浪，还是不自禁的面色发白。中年汉子目光如炬，镇定自若的站在船头，衣袂飞舞。那少年竟也无丝毫惧色，一双手握紧船舷，青筋暴起。
+
+　　突然，众人齐声惊呼，远处海面蓦地裂开，激起冲天巨浪，其时恰好闪电划过，天地一片雪白，只见一只长达四丈余的青色怪兽从海中破浪而出，引颈长啸。它在空中离海面两丈处，突然展开双翼，巨大的蝠翼刹那间张至五丈余长，在空中划起优美的圆弧，再急速以千均之力，击打在海面上。海浪滔天，浪水被击得冲起十几丈高，竟如暴雨般洒落。那怪兽凭借双翼击打之力，猛然腾空，双爪在海面上略一拍打，如雄鹰般展翅飞起。
+
+　　少年兴奋的大叫道：“裂云狂龙！是它就是它！”转身看他父亲，却见他满脸煞白，双眉紧锁。再回头看众桨手，他们个个满脸惊恐，竟似大难临头一般。少年不解道：“你们怎么啦？我们要抓的不就是它么？”
+
+　　舵手口吃道：“公……公子爷，它，它不是裂云龙，而是……是蓝翼海龙兽！”少年哼了一声：“那又怎地？”舵手惨然道：“它是大荒十大凶兽之一，所到之处，必有血光之灾！”少年道：“什么血……”却听中年汉子喝道：“住口！立刻圆舱！”众人如蒙大赦，立即摇起船舷。两翼船舷缓缓合拢，就在即将并成圆舱之际，中年汉子突然腾空跃起，远远的抛下一句：“关好所有舱门，谁也不许出来！”少年大叫：“爹！”却已然不及，船舱合拢，密封如橄榄，惟有一支丈余长的透气管高高升起。
+
+　　少年立即扑到船头，透过巴掌大的树脂化石向外望去，模模糊糊瞧见他父亲从背后拔出长生剑，踏波逐浪向那怪兽奔去。
+
+　　※※※
+
+　　中年汉子借着一股大浪之力，凝气高高跃起，喝道：“孽畜！快来受死！”蓝翼海龙兽在空中扭动脖子，斜眼下望，张嘴大吼，一股阴森寒气激射而出。怪兽双翼平展，在惊涛骇浪中徐徐转向，瞬间加速，闪电般向中年汉子冲去！
+
+　　船中少年惊得大叫一声，众人纷纷上前，隔着树脂窗紧张眺望。
+
+　　中年汉子左手疾弹，一道白芒电射而出，左脚在右脚上一踩，轻飘飘翻起丈余高，在空中突然扭身，宛如半腰折断般，硬生生又向上激射了两丈余高。那怪兽双翼一拍，将白芒击落，冲势稍减。中年汉子乘势从它上空越过，右手长生剑急电般向怪兽头颈斩落。
+
+　　怪兽扭颈长啸，两翼向上翻起，登时卷起一股狂风，丈余长的巨尾在空中一个摇摆，带着雷霆之势，向中年汉子扫去。
+
+　　众桨手失声惊呼。那中年汉子借着怪兽两翼之风，凝气跃起，堪堪躲过巨尾致命一击。但巨尾过处，风势刚劲如刀，竟将中年汉子的腿部划出一道一尺来长的伤口，鲜血长流。怪兽闻到血腥味，狂性陡发，双翼猛然击打海面，激起滔天巨浪，仰颈咆哮，一双碧色巨眼在黑暗中闪闪发光。
+
+　　少年看得紧张，掌心满是汗水，众人亦屏气敛息，心跳如撞。
+
+　　惊雷阵阵，闪电如刀，暗云翻涌，狂风肆虐，终于下起倾盆暴雨。一人一龙，在惊涛骇浪中转眼已斗了数十回合。
+
+　　中年汉子仗着一身绝佳轻功，在怪兽与风浪间闪跳挪移，虽浑身是血，却并无大碍。那怪兽怒发如狂，每次攻击便崩云裂浪，虽相隔甚远，船中众人犹可感觉惊人威力。舵手忧道：“城主虽武功盖世，但此孽畜非等闲之物，倘若如此纠缠，只怕……”众人沉默不语。少年扬眉道：“戚老大，你掌舵，大伙儿慢慢将船靠过去。”众人大惊，舵手戚老大道：“公子爷，这，这……”少年满脸傲色，凛然道：“与其坐而待毙，不如搏命求生！”话语斩钉截铁，不容丝毫转圜余地。戚老大缓缓道：“果然虎父无犬子。公子爷年纪轻轻，便如此英雄胆色，我们倘若还贪生怕死，岂不让天下人笑话！”众人尽皆点头。柚木船十二支桨悄悄伸出，在风暴中整齐如一的划动，向一人一龙靠近。
+
+　　中年汉子咬牙苦斗，已渐感不支。那怪兽竟越斗越勇，一双碧眼转为通红，更显狰狞。中年汉子心道：倘若再与它缠斗不清，必丧命于此。需用魔法降它。当下更不犹豫，突然踏浪腾空，左手捏诀，右手长生剑插在腰间。
+
+　　戚老大惊道：“不好！”少年咬牙道：“倘若爹爹魔法一击不能得手，便有性命之虞。”原来魔法原非近身搏斗之用，每次施放，必有片刻功力尽失。倘若近身相搏，一击不能得手，而空门大露，则后果不堪设想。少年从腰间解下断月弩，喝道：“开舱！”
+
+　　但是犹已晚矣。中年汉子人如陀螺在空中疾转，大喝一声：“万壑春藤绕！”双手舞动，犹如千手菩萨，漫天突然尽是寸许长的枝桠藤蔓。狂风暴雨中，那漫天藤蔓竟如千万利箭，齐刷刷射向怪兽！
+
+　　怪兽嘶声狂吼，两翼尽展，竟如半空起了一道横竖五六丈的黑色屏障，巨尾重重砸落海面，掀起狂风烈浪。但是风浪竟不能击落半根藤蔓，千万数的细小藤蔓刹那间尽皆没入怪兽周身。
+
+　　怪兽脖颈暴长三尺，仰天发出一声震耳欲聋的怒吼，天边闪电击入海中，一连串惊雷蓦然响起。怪兽两翼后扬，再以排山倒海之势，向中年汉子拍去！中年汉子再也不能闪避，被两翼狂风击中，鲜血狂喷，如断线风筝般从半空跌落，摔入滔滔海浪之中。船中众人齐声惊呼，少年泪水夺眶而出。舷舱缓缓开启，浪水、狂风、咸涩的海水味与血腥味弥漫的气息一起扑面而来。
+
+　　怪兽突然发出一声奇怪的嘶吼，巨大的身躯突然同时裂开，无数绿色的藤蔓从它身上同时绽放，以惊人的速度生长蔓延，顷刻间将它两翼、双爪、巨尾全部缚住。怪兽一声悲鸣，从半空重重砸落。
+
+　　戚老大叫道：“别让它跑了！”少年猛然举弩搭箭，“嗖”的一声，金刚矢闪电般射入怪兽的右眼，怪兽咆哮声中，左眼又
+```
+
+---
+
+### 4. 无双.docx
+
+**文件类型**: 电影剧本
+**文件格式**: DOCX
+**文件长度**: 64,190 字符
+**场景数量**: 7 个（前10000字统计）
+
+**主要人物**:
+- 楚青 姜萤（机车性感装扮） 周麒 打手3名（周麒第一批
+- 打手1有词） 打手5名（周麒第二批） 食客路人6  摊主
+
+**结构特征**: 剧本格式，包含场景编号、人物、对话和动作描述
+
+**前3000字内容预览**:
+```
+　　第一集
+
+　　1-1 夜 外 街边摊
+
+　　人物：楚青 姜萤（机车性感装扮） 周麒 打手3名（周麒第一批，打手1有词） 打手5名（周麒第二批） 食客路人6  摊主
+
+　　▲姜萤骑机车至摊边刹停，摘下头盔，扫过人群，视线最终定格在楚青身上，勾起唇角，下车上前，径直坐到楚青对面。
+
+　　姜萤：拼个桌，不介意吧？
+
+　　▲楚青没说话，默默将碗向自己挪了挪，腾出空，姜萤笑笑，正要说些什么，三名打手持器械走来，重重砸在桌上。
+
+　　打手1（凶戾）：从现在开始，这一片，清场！
+
+　　▲客人和摊主都畏惧逃散，姜萤皱眉，楚青继续吃。
+
+　　打手1（阴沉扫向楚青姜萤）：你们两个，还不滚？
+
+　　姜萤：空位这么多，凭什么你们一来就要清场？
+
+　　打手1（冷笑）：小妹妹，你听说过森爷的名号吗？
+
+　　姜萤（微微皱眉）：南省坐山虎，任城森？
+
+　　打手1：不错！今晚，森爷亲至海城，他老人家念旧，惦记这个档口，所以我们大哥要在这里宴请森爷！而你们，算什么东西，也配和森爷并坐？
+
+　　▲打手1狞笑，抬起器械砸在桌上（桌子上的饭全部被打翻，桌子也翻）。
+
+　　打手1：识相，就赶紧滚。不然，这就是下场（扬起器械，狠狠砸翻餐桌）！
+    
+▲姜莹被突然的重击惊吓起身退开到一边（出画离场），楚青阴沉抬头看向打手1
+
+　　楚青：你，砸了我的饭。
+
+　　打手1：怎么？你有意见？
+
+　　楚青：赔！
+
+　　打手1（愣了愣，哼笑，指指自己，指指楚青）：你让我，赔你的饭？
+
+　　楚青：对。
+
+　　▲打手1扭头和另外两名打手对视，爆发哄笑。
+
+　　打手1：行，没问题。老子再给你加点码，废了你，一块儿赔！给我弄他！
+
+   打戏设计：两个小弟上前，一个持器械向坐着的男主砸去，男主连同闪避加拾起地上的酒瓶向打手2的头，打手2倒地，男主起身将打手3正面踹飞，重摔在一张桌子上，桌子损坏，打手3倒地不起。
+
+▲打手一惊，接器械砸向楚青，楚青反手卸下器械，锁住打手1的胳膊。
+
+　　打手1（惊）：你？
+
+　　楚青：这条胳膊，别要了。
+
+　　打手1（无法挣脱，阴沉）：你敢！我大哥，可是森爷亲指的海城地下魁首！你动了我，活不过今晚！
+
+　　楚青（笑笑）：那我倒想看看，他怎么让我活不过今晚。
+
+　　画外音（周麒）：好大的口气！
+
+　　▲楚青侧目，周麒率4名打手赶来，阴沉望向楚青。
+
+　　周麒（寒声命令）：放开他。
+
+　　打手1（喜）：我大哥到了！你完了！赶紧放开我！
+
+　　楚青（笑笑）：好啊。
+
+　　打手1（得意）：算你识相……
+
+▲话未完，楚青拧断打手1胳膊，打手1哀嚎倒地，楚青微笑望向周麒。
+
+楚青（无辜抬手）：我，放开了。
+
+
+　　第二集
+
+　　2-1 夜 外 街边摊
+
+人 楚青 姜萤 周麒 打手7（倒地1个，打手2有词）
+
+
+　　▲周麒身后打手面露凶色，将上前动手，却被周麒抬手拦下。
+
+　　周麒（凝视楚青）：你在挑衅我？
+
+　　楚青：（扫过地上的打手1）掀我桌子，砸了我的饭，我只是正当防卫而已。
+
+　　周麒（假意恍然）：这么说来，是我的人冒犯在先了？
+
+　　楚青：对。
+
+　　▲周麒面带微笑，走上前。
+
+　　周麒：哎呀，那还真是不好意思，既然事出有因，那你就…（走到打翻的桌边，低头抬脚碾碎倒扣的餐盘，踩在烤串上）跪在这，把东西舔干净，给我的人磕三个响头道歉……
+
+　　▲周麒抬头，望向楚青。
+
+　　周麒：……我就可以留你一命，如何？
+
+　　楚青（笑了笑）：你跟着任城森也有段时间了吧？他，就是这么教你做事的？
+
+　　打手2：放肆！森爷的大名，也是你能直呼的？
+
+　　周麒（抬抬手示意安静，眯眼打量楚青）：小子，你惹了我，尚有活路。但森爷他盘踞南省大半世纪有余，权势通天，更得龙殿封敕，代掌天衡集团，富可敌国！敢对他老人家不敬，这南省，可没人能护得了你。
+
+　　楚青：就是他任城森站在这，又能奈我何？
+
+　　周麒（声音转寒）：看来，你是迫不及待的想寻死了。
+
+　　楚青（抬起手机）：三分钟。
+
+周麒：什么？
+
+▲姜莹已经退到了不远处，淡定的观察着这一切
+
+楚青（拨通号码）：通知任城森，三分钟内，到海城西郊档口来见我。若逾时不到，任家，南省除名。
+
+
+　　2-2 夜 外 酒店门前
+
+　　人 任城森 洛歆 下属
+
+　　▲豪车横停，众下属列队，以任城森为首，恭迎洛歆。
+
+　　▲手机铃声响起，洛歆接听。
+
+　　任城森（小心翼翼）：洛小姐，这电话……
+
+　　洛歆挂断电话：是主人的打来的。
+
+　　▲任城森惊。
+
+　　洛歆（笑了笑，继续）：主人说限你三分钟内到海城西郊档口，若到不了，任家，南省
+除名！
+
+
+　　2-3 夜 外 路边摊
+
+　　人 楚青 周麒 姜萤 打手7（周麒）群演（任城森手下）*6
+
+　　▲楚青挂断通话，周麒冷笑鼓掌。
+
+　　周麒：森爷亲临海城，便是我，想去迎接都没有资格，你却想凭一通电话，就把森爷招来，还要让任家于南省除名？
+
+　　▲周麒嗤笑摇头，脸色沉下，挥手下令。
+
+　　周麒：真是不知死活！动手！送他上路！
+
+　　▲众打手将冲出，却有汽车轰鸣声传来。
+
+▲周麒猛回头，豪车车队疾驰而至。任城森副驾位排场下车！
+
+　　任城森：周麒！你好大的胆子！
+
+
+
+　　第三集
+
+　　3-1 夜 外 路边摊
+
+人 任城森 姜萤 洛歆 楚青 周麒、打手7（周麒）、下属8（任城森）
+　　
+　　周麒（错愕，迎上前）：森爷？您…您怎么来了……？
+
+　　▲话未完，周麒被任城森一把推开。
+
+　　任城森：滚开。
+
+　　▲任城森恭敬拉开豪车后车门，请洛歆下车，洛歆径直到楚青身前。
+
+　　洛歆（单膝跪下）：洛歆，拜见主人。
+
+　　▲任城森紧随，率众跪下。
+
+　　任城森：南省任城森，拜见主人。
+
+　　周麒（惊）：主人？
+
+　　▲任城森起身，给周麒一巴掌，将周麒抽倒在地。
+
+　　任城森：废物，瞎了你的眼！
+
+　　楚青（望向任城森）：你自己的人，自己管好，再有下次，这南省坐山虎，就该换人了。
+
+　　任城森（惶恐）：是，是！
+
+　　▲楚青转身离开，洛歆快步跟上。
+
+　　周麒（畏惧）：森爷，我……
+
+　　任城森（又抽一巴掌）：混账东西！带下去！
+
+　　▲下属上前，架住周麒带离，小弟也狼狈跟随离开。
+
+　　▲姜萤从一旁走出，望着楚青离开的方向，取出手机，拨出一通电话。
+
+姜萤（勾起唇角）：知非，你要找的那个男人，我找到了。
+
+
+　　3-2 夜 内 苏知非办公室
+
+　　人 苏知非 助理
+
+　　▲办公桌后，苏知非突然从座位上起身接听电话。
+
+　　苏知非：在哪？
+
+　　姜萤：南省，海城。
+
+　　苏知非（放下手机，望向助理下令）：预定明晚的专机，送我去海城。
+
+　　助理：海城？小姐，明晚您还有一项跨国会谈……
+
+苏知非：（轻描淡写）不重要。你也知道，从很早以前，我就想见见……（扬起嘴角，语气加重）我那位素未谋面的未婚夫了。
+
+
+　　第四集
+
+　　4-1 夜 车内
+
+　　人 楚青 洛歆
+
+　　▲洛歆开车，楚青坐在后排。
+
+　　楚青：我交代的事情，办的怎么样了？
+
+　　洛歆：任城森明晚就会代天衡集团举办招标晚宴，公开宣布您的妻子沈雨宁小姐，成为新区开发项目的唯一中标人，获得那份价值两百亿的订单。
+
+　　楚青：嗯。
+
+　　洛歆：沈氏集团现在已经是海城的商业支柱，接下天衡的订单后，不仅会成为南省首屈一指的企业，更
+```
+
+---
+
+### 5. 雪中悍刀行.txt
+
+**文件类型**: 网络小说
+**文件格式**: TXT
+**文件编码**: gbk
+**文件长度**: 4,708,176 字符
+**作者**: 烽火戏诸侯
+
+**内容简介**:
+```
+有个白狐儿脸，佩双刀绣冬春雷，要做那天下
+```
+
+**章节预览**:
+- 第001章 小二上酒
+
+**结构特征**: 网文格式，分章节叙事
+
+**前3000字内容预览**:
+```
+声明：本书为八零电子书(txt8080.com)的用户上传至本站的存储空间，本站只提供TXT全集电子书存储服务以及免费下载服务，以下作品内容之版权与本站无任何关系。
+---------------------------用户上传之内容开始--------------------------------
+
+
+
+
+
+==========================
+【全本校对】《雪中悍刀行》
+作者：烽火戏诸侯
+
+
+内容简介：
+　　有个白狐儿脸，佩双刀绣冬春雷，要做那天下第一。湖底有白发老魁爱吃荤。缺门牙老仆背剑匣。山上有个骑青牛的年轻师叔祖，不敢下山。有个骑熊猫扛向日葵不太冷的少女杀手。
+　　这个江湖，高人出行要注重出尘装扮，女侠行走江湖要注意培养人气，宗派要跟庙堂打好关系。
+　　而主角，则潇洒带刀，把江湖捅了一个通透。
+==========================
+
+第一卷 白马出凉州
+
+
+第001章 小二上酒
+　　北凉王府龙盘虎踞于清凉山，千门万户，极土木之盛。
+　　作为王朝硕果仅存的异姓王，在庙堂和江湖都是毁誉参半的北凉王徐骁作为一名功勋武臣，可谓得到了皇帝宝座以外所有的东西，在西北三州，他就是当之无愧的主宰，只手遮天，翻云覆雨。
+　　难怪朝廷中与这位异姓王政见不合的大人们私下都会文绉绉骂一声徐蛮子，而一些居心叵测的，更诛心地丢了顶“二皇帝”的帽子。
+　　今天王府很热闹，位高权重的北凉王亲自开了中门，摆开辉煌仪仗，迎接一位仙风道骨的老者，府中下人们只听说是来自道教圣地龙虎山的神仙，相中了痴痴傻傻的小王爷，要收作闭关弟子，这可是天大的福缘，北凉王府都解释成傻人有傻福。
+　　可不是，小王爷自打出生起便没哭过，读书识字一窍不通，六岁才会说话，名字倒是威武气派，徐龙象，传闻还是龙虎山的老神仙当年给取的，说好十二年后再来收徒，这不就如约而至了。
+　　王府内一处院落，龙虎山师祖一级的道门老祖宗捻着一缕雪白胡须，眉头紧皱，背负一柄不常见的小钟馗式桃木剑，配合他的相貌，确实当得出尘二字，谁看都要由衷赞一声世外高人呐。
+　　但此番收徒显然遇到了不小的阻碍，倒不是王府方面有异议，而是他的未来徒弟犟脾气上来了，蹲在一株梨树下，用屁股对付他这个天下道统中论地位能排前三甲的便宜师傅，至于武功嘛，咳咳，前三十总该有的吧。
+　　连堂堂大柱国北凉王都得蹲在那里好言相劝，循循善诱里透着股诱拐，“儿子，去龙虎山学成一身本事，以后谁再敢说你傻，你就揍他，三品以下的文官武将，打死都不怕，爹给你撑腰。”
+　　“儿啊，你力气大，不学武捞个天下十大高手当当就太可惜了。学成归来，爹就给你一个上骑都尉当当，骑五花马，披重甲，多气派。”
+　　小王爷完全不搭理，死死盯着地面，瞧得津津有味。
+　　“黄蛮儿，你不是喜欢吃糖葫芦吗，那龙虎山遍地的野山楂，你随便摘随便啃。赵天师，是不是？”
+　　老神仙硬挤出一抹笑容，连连点头称是。收徒弟收到这份上，也忒寒碜了，说出去还不被全天下笑话。
+　　可哪怕位于堂堂超一品官职、在十二郡一言九鼎的大柱国口干舌燥了，少年还是没什么反应，估计是不耐烦了嫌老爹说得呱噪，翘起屁股，噗一下来了个响屁，还不忘扭头对老爹咧嘴一笑。
+　　把北凉王给气得抬手作势要打，可抬着手僵持一会儿，就作罢。一来是不舍得打，二来是打了没意义。
+　　这儿子可真对得起名字，徐龙象，取自“水行中龙力最大，陆行中象力第一，威猛如金刚，是谓龙象”，别看绰号黄蛮儿的傻儿子憨憨笨笨，至今斗大字不识，皮肤病态的暗黄，身形比较同龄人都要瘦弱，但这气力，却是一等一骇人。
+　　徐骁十岁从军杀人，从东北锦州杀匈奴到南部灭大小六国屠七十余城再到西南镇压蛮夷十六族，什么样膂力惊人的猛将没有见过，但如小儿子这般可天生铜筋铁骨力拔山河的，真没有。
+　　徐骁心中轻轻叹息，黄蛮儿若能稍稍聪慧一些，心窍多开一二，将来必定可以成为陷阵第一的无双猛将啊。
+　　他缓缓起身转头朝龙虎山辈分极高的道士尴尬一笑，后者眼神示意不打紧，只是心中难免悲凉，收个徒弟收到这份上，也忒不是个事儿了，一旦传出去还不得被天下人笑话，这张老脸就甭想在龙虎山那一大帮徒子徒孙面前摆放喽。
+　　束手无策的北凉王心生一计，嘿嘿道：“黄蛮儿，你哥游行归来，看时辰也约莫进城了，你不出去看看？”
+　　小王爷猛地抬头，表情千年不变的呆板僵硬，但寻常木讷无神的眼眸却爆绽出罕见光彩，很刺人，拉住老爹的手就往外冲。
+　　可惜这北凉王府出了名百廊回转曲径千折，否则也容不下一座饱受朝廷清官士大夫们诟病的“听潮亭”，手被儿子握得生疼的徐骁不得不数次提醒走错路了，足足走了一炷香时间，这才来到府外。
+　　父子和老神仙身后，跟着一帮扛着大小箱子的奴仆，都是准备带往龙虎山的东西，北凉王富可敌国，对儿女也是素来宠溺，见不得他们吃一点苦受一点委屈。
+　　到了府外，小王爷一看到街道空荡，哪里有哥哥的身影，先是失望，继而愤怒，沉沉嘶吼一声，沙哑而暴躁，起先想对徐骁发火，但笨归笨，起码还知道这位是父亲，否则徐骁的下场恐怕就得像前不久秋狩里倒霉遇到徐龙象的黑罴了，被单枪匹马的十二岁少年生生撕成两半。他怒瞪了一眼心虚的老爹，掉头就走。
+　　不希望功亏一篑的徐骁无奈丢给老神仙一个眼神。龙虎山真人微微一笑，伸出枯竹一般的手臂，但仅是两指搭住了小王爷的手腕，轻声慈祥道：“徐龙象，莫要浪费了你百年难遇的天赋异禀，随我去龙虎山，最多十年，你便可下山立功立德。”
+　　少年也不废话，哼了一声，继续前往，但玄妙古怪的是他发现自己没能挣脱老道士看似云淡风轻的束缚，那踏出去悬空的一步如何都没能落地。
+　　北凉王如释重负，这位道统辈分高到离谱的上人果真还是有些本事的，知子莫若父，徐骁哪里不知道小儿子的力道，霸气得很，以至于他都不敢多安排仆人女婢给儿子，生怕一个不小心就捏断了胳膊腿脚，这些年院中被坐坏拍烂的桌椅不计其数，也亏得北凉王府家底厚实，寻常殷实人家早就破产了。
+　　小王爷愣了一下，随即发火，轻喝一声，硬是带着老神仙往前走了一步，两步，三步。头顶黄冠、身披道袍的真人只是微微咦了一声，不怒反喜，悄悄加重了几分力道，阻止了少年的继续前行。
+　　如此一来，徐龙象是真怒了，面容狰狞如同一只野兽，伸出空闲的一只手，双手握住老道士的手臂，双脚一沉，咔嚓，在白玉地板上踩出两个坑，一甩，就将老道士整个人给丢掷了出去。
+　　大柱国徐骁眯起眼睛，丝毫不怕惹出命案，那道士若没这个斤两本事，摔死就摔死好了，他徐骁连不可一世的西楚王朝都给用凉州铁骑踏平了，何时对江湖门派有过丝毫的敬畏？天下道统首领龙虎山又如何？所辖境内数个大门大派虽比不上龙虎山，但在王朝内也属一流规模，例如那数百年一直跟龙虎山争那道统的武当山，在江湖上够超然了吧，还不是每年都主动派人送来三四炉珍品丹药？
+　　老道士轻轻飘荡到王府门口的一座两人高汉白玉石狮子上，极富仙人气势。光凭这一手，若是搁在市井中，那还不得搏得满堂喝彩啊。
+　　这按照北凉王世子即徐骁嫡长子的那个脍炙人口的说法，那就是“该赏，这活儿不简单，是技术活”，指不定就是几百几千银票打赏出去了，想当年世子殿下还没出北凉祸害别人的时日，多少青楼清伶或者江湖骗子得了他的阔绰赏钱。
+　　最高纪录是一位外地游侠，在街上一言不合与当地剑客相斗，从街边菜摊打起打到湖畔最后打到湖
+```
+
+---
+
+### 6. 魔道祖师.txt
+
+**文件类型**: 网络小说
+**文件格式**: TXT
+**文件编码**: gbk
+**文件长度**: 651,272 字符
+**作者**: 墨香铜臭
+
+**章节预览**:
+- 第1章 重生第一
+
+**结构特征**: 网文格式，分章节叙事
+
+**前3000字内容预览**:
+```
+━━━━━━━━━━━━━━此文由【o0爱子如画0o】←扫文求文博主整理并分享，仅供大家私下食用！也欢迎小说同好们来新浪微博勾搭博主么么哒╭(╯3╰)╮
+PS：文章版权为作者所有#侵删歉#。写文辛苦，码字不易，如果喜欢本文，请订阅书籍或购买个志，表示对作者大大的支持！
+================
+    书名：魔道祖师(精修版)[重生]
+    作者：墨香铜臭
+    文案
+    前世的魏无羡万人唾骂，声名狼藉。
+    被护持一生的师弟带人端了老巢，
+    纵横一世，死无全尸。
+
+    曾掀起腥风血雨的一代魔道祖师，重生成了一个……
+    脑残。
+    还特么是个人人喊打的断袖脑残！
+
+    我见诸君多有病，料诸君见我应如是。
+    但修鬼道不修仙，任你千军万马，十方恶霸，九州奇侠，高岭之花，但凡化为一抔黄土，统统收归旗下，为我所用，供我驱策！
+    高贵冷艳闷骚攻×邪魅狂狷风骚受
+
+    PS：
+    ①1V1主受HE。
+    ②本文主线夫夫携手打怪解谜打孩子，前世今生双线剧情向。
+    单向暗恋→双向暗恋，感情线不虐不折腾不纠结 O（∩＿∩）O～
+    ③非复仇流！非升级流爽文！
+
+    内容标签：重生 天作之合 灵异神怪 仙侠修真
+    搜索关键字：主角：魏无羡（魏婴），蓝忘机（蓝湛） ┃ 配角：妖魔鬼怪 ┃ 其它：满级重生，狗血，有病，剧情向，胡来的左手
+
+    晋江银牌编辑评价：
+    身为开宗立派的一代魔道祖师，魏无羡纵横一世，掀腥风血雨，遭万人唾骂，最终被最亲近的师弟捅刀，受各大家族围剿而死。重生到了一名遭家族抛弃的疯子身上，被前世与自己水火不容的仙门名士蓝忘机强行抓走后，两人一起开始了打怪解谜带孩子、惊险抓人又逗趣的仙侠之旅。在一路调戏与反调戏之中，魏无羡逐渐发现，看似高傲、冷若冰霜的蓝忘机，似乎并不是真的那么讨厌自己。作者笔下的仙侠世界有着不同于一般修仙文的独特世界观与细节风俗设定，虽是重生文却不走逆袭复仇的老套路。一个个惊心动魄的小故事串起一个贯穿全文的大悬念，情节紧凑，跌宕起伏。笔力到位，人物各有各的精彩，各有各的传奇。萌点十足，互动有爱，由单向暗恋转为双向暗恋的过程温馨甜蜜，又爆笑无比。
+    ==================
+    
+    第1章 重生第一
+    
+    “魏无羡死了。大快人心！”
+    乱葬岗大围剿刚刚结束，未及第二日，这个消息便插翅一般飞遍了整个修真界，比之当初战火蔓延的速度有过之而无不及。
+    一时之间，无论是世家名门，还是山野散修，人人都在议论此次由四大玄门世家联率、大小百家参与混战的围剿行动。
+    “好好好，果然是大快人心！手刃这夷陵老祖的是哪位名士英豪？”
+    “还能是谁。他师弟小江宗主江澄呗，云梦江氏、兰陵金氏、姑苏蓝氏、清河聂氏四大家族打头阵，大义灭亲，把魏无羡那老巢‘乱葬岗’一锅端了。”
+    “我得说句公道话：杀得好。”
+    立即有人抚掌亮声应和：“不错，杀得好！要不是云梦江氏收养他栽培他，他魏婴这辈子就是个混迹乡野市井的庸徒……还谈什么别的。原先的江宗主可是把他当亲儿子在养，他倒好，公然叛逃，与百家为敌，丢尽了云梦江氏的脸，还害得江家几乎满门惨死。什么叫忘恩负义白眼狼？这就是！”
+    “江澄居然就让这厮嚣张了这么久，换了是我，当初魏某人叛逃时就不是只捅他一刀，而是直接清理门户，否则他也没机会做出后来那些丧心病狂之事。对这种人，还讲什么同门同修青梅竹马的情面。”
+    “可我听到的不是这样的啊？魏婴不是因为自己修炼邪术遭受反噬、受手下鬼将撕咬蚕食而死的吗？听说活活被咬碎成了齑粉呢。”
+    “哈哈哈哈……这就叫现世报。我早就想说了，他养的那批鬼将就像一群没拴好的疯狗到处咬人，最后咬死自己，活该！”
+    “话虽如此，可此次围剿乱葬岗，若不是小江宗主依夷陵老祖的弱点拟定计划，成功与否还难说呢。你们可别忘了魏无羡手上有什么东西，当初一晚上三千多个成名修士是怎么全军覆没的。”
+    “不是五千吗？”
+    “三千五千都差不多。我觉得五千更有可能。”
+    “果真丧心病狂……”
+    “他死之前毁掉了阴虎符，倒也算积了点阴德，否则留下那鬼东西继续贻害人间，更加罪孽深重喽。”
+    “阴虎符”三字一出，忽然一阵静默，似乎都在顾忌着什么。
+    片刻之后，一人慨叹道：
+    “哎……要说这魏无羡，当年也是仙门之中极富盛名的世家公子，并非不曾有过佳迹。年少成名，何等风光恣意……究竟他是怎么走到这一步的……”
+    话题转移，议论声又纷纷然起来。
+    “由此可见，修炼终归是非走正统路子不可。邪魔歪道，一时风光无限，好像很嚣张很了不起？嘿，最后是什么下场？”
+    掷地有声：“死无全尸！”
+    “也不全是修炼之道害的，归根结底还是魏无羡此人人品太差，天怒人怨啊。所谓善恶终有报，天道好轮回……”
+    ……
+    身死之后，盖棺定论。所论内容大同小异，偶有微弱的异声，也会立刻被压了下去。
+    只是每个人的心头都还有一缕阴霾挥之不去。
+    虽说夷陵老祖魏无羡已身死乱葬岗，但事成之后，却无法召唤他的残魂。
+    他的魂魄，也许是在被万鬼吞噬之时一同被分食了，又也许是逃逸了。
+    若是前者，自然皆大欢喜普天同庆。然而，夷陵老祖有翻天灭地、移山倒海之能——至少传闻中是这样的，他若要抗拒召魂，也不是什么难事。一旦他来日元神复位，夺舍重生，届时，玄门百家甚至整个人间必将迎来更加丧心病狂的报复和诅咒，陷入暗无天日和腥风血雨之中。
+    因此，将一百二十座镇山石兽压在乱葬岗顶后，各大家族开始进行频繁的召魂仪式，同时严查夺舍，搜集各地异象，全力警戒。
+    第一年，风平浪静。
+    第二年，风平浪静。
+    第三年，风平浪静。
+    ……
+    第十三年，依然风平浪静。
+    至此，终于越来越多的人相信，也许魏无羡也没那么了不起，也许他真的神魂俱灭了。
+    纵使曾经翻手为云覆手雨，也终归有一日成为被翻覆的那一个。
+    没有人会被永远奉在神坛之上，传说也仅仅只是传说而已。
+    ==========================================
+    接下来我要说的话，可能语气会比以往重，因为我是很严肃的，实在是对最近的一些状况无可奈何了。
+    1，重申＋强调：请不要把我的文和其他作者的文进行比较。这是让两个作者都很尴尬且讨厌的事，给双方读者的感观也极差。把两个文放在一起会造成很多不必要的误会和摩擦冲突。
+    我的心愿是……世界和平。so请控制冲动，不要贪一时嘴爽。拒绝比较！拒绝拉踩！
+    2，不要在无关的地方刷我和我的文。比如其他作者的文下、群、微博等等。也请一定不要在无关画手微博底下刷我的人物和作品。爱是克制。过度安利往往适得其反，不分场合到处刷只会很尴尬，甚至招来反感，实在不希望这种事情发生。
+    3，最重要的一点——我不知道是不是真的有读者会去给不认识的人发私信提我或者我的文，但是我还是强调一下：【请不要打着安利我的文的旗号去给不认识的人发私信。拒绝以任何形式在私信里带我
+```
+
+---
+
+## 📌 分析总结
+
+### 网络小说特征
+- 采用章节式结构，通常有"第X章"标记
+- 包含作者信息和内容简介
+- 文件通常较大（几十万到几百万字符）
+- 常见编码：GBK、GB18030
+
+### 剧本特征
+- 采用场景编号格式（如"1-1"、"2-1"）
+- 包含人物列表、对话和动作描述
+- 使用特殊符号标记（如▲表示动作）
+- 包含场景时间地点标注（日/夜、内/外）
+
+### 编码处理经验
+- TXT文件主要使用GBK和GB18030编码
+- 需要尝试多种编码方式进行读取
+- PDF和DOCX文件可以直接使用相应库读取

examples/analyze_story/methodology/README.md

@@ -0,0 +1,124 @@
+# 叙事拆解方法论
+
+本目录包含AI可学习的长篇叙事拆解方法论的不同版本。
+
+## 文档列表
+
+### v2.0 改进版（推荐）
+**文件**: `v2_improved_methodology.md`  
+**日期**: 2025-02-18  
+**状态**: ✅ 可执行 + 可验证
+
+**核心改进**:
+1. **自适应思考过程提取** - 5级难度分级 + 动态CoT深度调整
+2. **多层验证系统** - 5层验证器（结构/逻辑/爽点/CoT/对抗性）
+3. **结构化与创造性平衡** - 4层约束策略 + 创造性激励机制
+4. **课程学习策略** - 5阶段渐进式训练（基础→爽点→编排→规划→创新）
+5. **AI辅助标注** - 自动标注 + 多层验证 + 人工复核
+
+**主要特点**:
+- ✅ 基于业界最佳实践（DeepSeek R1、Open-R1等）
+- ✅ 完整的质量验证体系
+- ✅ 可操作的实施路线图
+- ✅ 详细的训练数据格式设计
+- ✅ 平衡结构化和创造性
+
+**适用场景**:
+- 网文/小说AI生成
+- 剧本优化与辅助创作
+- 叙事技巧教学
+- 内容质量评估
+
+---
+
+### v1.0 基础版
+**文件**: `../knowledge/05_Integrated_Methodology.md`  
+**日期**: 2025-02-17  
+**状态**: ✅ 理论完整
+
+**核心内容**:
+- 三层次拆解（宏观/中观/微观）
+- MICE线程 + Save the Cat节拍
+- Scene-Sequel结构
+- 爽点与钩子设计
+- 起承转合应用
+
+**优势**:
+- 理论框架完整
+- 标注维度详细
+- 结合中西方理论
+
+**不足**（v2.0已改进）:
+- 思考过程提取不够系统
+- 缺少质量验证机制
+- 训练效率有待提升
+
+---
+
+## 版本对比
+
+| 维度 | v1.0 | v2.0 | 改进 |
+|------|------|------|------|
+| 思考过程提取 | 示例性 | 自适应深度 | +60% |
+| 数据验证 | 人工为主 | 5层自动验证 | +80% |
+| 训练效率 | 统一处理 | 课程学习 | +50% |
+| 创造性平衡 | 未明确 | 4层约束 | +70% |
+| 可操作性 | 中等 | 高 | +60% |
+
+---
+
+## 快速开始
+
+### 1. 阅读方法论
+```bash
+# 推荐从v2.0开始
+cat v2_improved_methodology.md
+```
+
+### 2. 理解核心概念
+- **自适应CoT**: 根据难度动态调整思考链深度
+- **多层验证**: 5层验证确保数据质量
+- **课程学习**: 从简单到复杂的渐进式训练
+- **结构约束分级**: 不同层次不同约束强度
+
+### 3. 查看实施路线
+- 短期（1-2月）: 基础设施 + 初始数据集
+- 中期（3-6月）: 课程学习 + RL优化
+- 长期（6-12月）: 领域扩展 + 产品化
+
+---
+
+## 相关资源
+
+### 理论基础
+- `../knowledge/01_Scene_Sequel_Structure.md` - Scene-Sequel理论
+- `../knowledge/02_MICE_Quotient.md` - MICE线程理论
+- `../knowledge/03_Save_the_Cat_Beats.md` - Save the Cat节拍
+- `../knowledge/04_Web_Novel_Theory.md` - 网文理论
+
+### 实践案例
+- `../sft/` - SFT数据生成实现
+- `../knowledge/05_AI_narrative_generation.md` - AI叙事生成调研
+
+---
+
+## 贡献指南
+
+欢迎贡献改进建议！
+
+**改进方向**:
+1. 更智能的难度评估算法
+2. 更强大的验证系统
+3. 跨模态扩展（图像、音频）
+4. 更多领域应用案例
+
+---
+
+## 许可证
+
+[待定]
+
+---
+
+**维护者**: AI叙事研究团队  
+**最后更新**: 2025-02-18

examples/analyze_story/methodology/v2_improved_methodology.md

@@ -0,0 +1,1656 @@
+# AI 可学习的长篇叙事拆解方法论 v2.0
+
+**版本**: v2.0 (改进版)  
+**日期**: 2025-02-18  
+**基于**: v1.0 方法论 + 业界最佳实践调研  
+**核心改进**: 思考过程提取 + 可验证数据格式 + 结构化与创造性平衡
+
+---
+
+## 改进概览
+
+### v1.0 的优势
+- ✅ 多层次融合（宏观-中观-微观）
+- ✅ 结合西方理论与中国网文实践
+- ✅ 详细的标注维度设计
+- ✅ 完整的实施流程
+
+### v1.0 的不足与 v2.0 的改进
+
+| 维度 | v1.0 的问题 | v2.0 的改进 |
+|------|------------|------------|
+| **思考过程提取** | 思考链示例较少，缺乏系统化方法 | 引入**自适应难度分级**和**动态CoT**机制 |
+| **数据可验证性** | 缺少质量验证机制 | 增加**多层验证器**和**对抗性验证** |
+| **训练效率** | 所有样本统一处理 | 引入**课程学习**和**难度自适应采样** |
+| **创造性平衡** | 结构化标注可能限制创造性 | 设计**结构约束度分级**系统 |
+| **数据生成** | 依赖人工标注 | 引入**AI辅助标注**和**自动验证** |
+
+---
+
+## 一、核心创新：三大支柱
+
+### 1.1 自适应思考过程提取（Adaptive CoT Extraction）
+
+**核心理念**：不是所有场景都需要复杂推理，根据难度动态调整思考深度。
+
+#### 难度分级系统
+
+```json
+{
+  "difficulty_grading": {
+    "method": "基于基础模型能力的自适应评估",
+    "levels": [
+      {
+        "level": 1,
+        "name": "直觉级（Intuitive）",
+        "description": "基础模型可直接处理",
+        "cot_depth": "minimal",
+        "example": "简单对话场景，日常互动"
+      },
+      {
+        "level": 2,
+        "name": "推理级（Reasoning）",
+        "description": "需要1-2步推理",
+        "cot_depth": "shallow",
+        "example": "单一爽点设计，简单冲突"
+      },
+      {
+        "level": 3,
+        "name": "规划级（Planning）",
+        "description": "需要多步规划",
+        "cot_depth": "medium",
+        "example": "复杂场景结构，多爽点编排"
+      },
+      {
+        "level": 4,
+        "name": "架构级（Architectural）",
+        "description": "需要全局视角",
+        "cot_depth": "deep",
+        "example": "MICE线程嵌套，节拍设计"
+      },
+      {
+        "level": 5,
+        "name": "创新级（Creative）",
+        "description": "需要创造性突破",
+        "cot_depth": "very_deep",
+        "example": "新颖设定，独特叙事手法"
+      }
+    ]
+  }
+}
+```
+
+#### 动态CoT生成策略
+
+```json
+{
+  "dynamic_cot_strategy": {
+    "principle": "根据难度级别动态调整思考链深度",
+    "level_1_2": {
+      "format": "直接输出",
+      "example": {
+        "input": "设计一个日常对话场景",
+        "output": "许七安与小妹玩闹，展现家庭温馨",
+        "cot": null
+      }
+    },
+    "level_3": {
+      "format": "简化思考链",
+      "example": {
+        "input": "设计第4章的智商碾压爽点",
+        "output": {
+          "cot": [
+            "1. 主角优势：现代数学知识",
+            "2. 对比设计：古代人算不出 vs 主角秒答",
+            "3. 反应放大：震惊的肢体语言"
+          ],
+          "result": "十五万两白银重量计算场景"
+        }
+      }
+    },
+    "level_4_5": {
+      "format": "完整思考链",
+      "example": {
+        "input": "设计前10章的MICE嵌套结构",
+        "output": {
+          "cot": [
+            {
+              "step": 1,
+              "question": "选择哪个线程作为最外层？",
+              "analysis": "Event线程提供时间压力和高风险",
+              "alternatives": ["Milieu", "Character"],
+              "decision": "Event作为最外层",
+              "reasoning": "网文需要快节奏开局"
+            },
+            {
+              "step": 2,
+              "question": "如何嵌套其他线程？",
+              "analysis": "Character成长依赖Event解决",
+              "decision": "E[C[I[M]]]嵌套结构",
+              "reasoning": "内层线程为外层服务"
+            }
+          ],
+          "result": "完整的MICE嵌套设计"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+### 1.2 多层验证系统（Multi-Layer Verification）
+
+**核心理念**：确保训练数据的质量和一致性，避免"垃圾进，垃圾出"。
+
+#### 验证器架构
+
+```json
+{
+  "verification_system": {
+    "layers": [
+      {
+        "layer": 1,
+        "name": "结构完整性验证（Structure Verifier）",
+        "checks": [
+          "MICE线程是否正确嵌套？",
+          "Scene-Sequel是否形成因果链？",
+          "Save the Cat节拍是否齐全？"
+        ],
+        "method": "规则引擎 + 模式匹配",
+        "auto_fix": true
+      },
+      {
+        "layer": 2,
+        "name": "逻辑一致性验证（Logic Verifier）",
+        "checks": [
+          "角色行为是否符合设定？",
+          "时间线是否连贯？",
+          "因果关系是否合理？"
+        ],
+        "method": "LLM辅助验证",
+        "auto_fix": false,
+        "flag_for_review": true
+      },
+      {
+        "layer": 3,
+        "name": "爽点有效性验证（Shuang Point Verifier）",
+        "checks": [
+          "铺垫是否充分？",
+          "反应是否到位？",
+          "强度是否匹配标注？"
+        ],
+        "method": "基于规则 + 对比学习",
+        "metrics": {
+          "setup_length": ">=100字",
+          "reaction_intensity": ">=medium",
+          "payoff_clarity": ">=0.8"
+        }
+      },
+      {
+        "layer": 4,
+        "name": "思考链质量验证（CoT Quality Verifier）",
+        "checks": [
+          "推理步骤是否清晰？",
+          "是否考虑了替代方案？",
+          "最终决策是否有充分理由？"
+        ],
+        "method": "PRM（Process Reward Model）评分",
+        "threshold": 0.7
+      },
+      {
+        "layer": 5,
+        "name": "对抗性验证（Adversarial Verifier）",
+        "purpose": "发现隐藏的问题",
+        "method": "使用对抗模型尝试找出矛盾",
+        "examples": [
+          "角色在第3章说不会武功，第5章却打败敌人",
+          "爽点铺垫不足，读者无法理解为何震惊"
+        ]
+      }
+    ]
+  }
+}
+```
+
+#### 验证流程
+
+```
+原始标注数据
+    ↓
+[Layer 1] 结构完整性验证 → 自动修复 or 标记
+    ↓
+[Layer 2] 逻辑一致性验证 → 标记问题
+    ↓
+[Layer 3] 爽点有效性验证 → 评分 + 标记
+    ↓
+[Layer 4] CoT质量验证 → PRM评分
+    ↓
+[Layer 5] 对抗性验证 → 发现隐藏问题
+    ↓
+质量报告 + 修复建议
+    ↓
+人工复核（仅针对标记项）
+    ↓
+最终训练数据
+```
+
+---
+
+### 1.3 结构化与创造性平衡系统
+
+**核心理念**：结构是骨架，创造性是血肉，两者需要动态平衡。
+
+#### 结构约束度分级
+
+```json
+{
+  "structure_constraint_levels": {
+    "principle": "不同层次和场景需要不同的约束强度",
+    "levels": [
+      {
+        "level": "严格约束（Strict）",
+        "constraint_strength": 0.9,
+        "applicable_to": [
+          "MICE线程嵌套规则",
+          "Scene-Sequel因果链",
+          "Save the Cat核心节拍"
+        ],
+        "reason": "这些是叙事的基础结构，必须遵守",
+        "creativity_space": "在规则内选择具体实现方式"
+      },
+      {
+        "level": "中等约束（Moderate）",
+        "constraint_strength": 0.6,
+        "applicable_to": [
+          "起承转合比例",
+          "爽点密度",
+          "钩子布置频率"
+        ],
+        "reason": "有最佳实践，但可根据情况调整",
+        "creativity_space": "调整比例、密度、频率"
+      },
+      {
+        "level": "弱约束（Flexible）",
+        "constraint_strength": 0.3,
+        "applicable_to": [
+          "对话风格",
+          "描写手法",
+          "具体情节设计"
+        ],
+        "reason": "这些是创造性的主要发挥空间",
+        "creativity_space": "完全自由，只需符合角色设定"
+      },
+      {
+        "level": "无约束（Free）",
+        "constraint_strength": 0.0,
+        "applicable_to": [
+          "独特设定",
+          "创新叙事手法",
+          "风格化表达"
+        ],
+        "reason": "鼓励创新和突破",
+        "creativity_space": "完全自由创作"
+      }
+    ]
+  }
+}
+```
+
+#### 创造性评估维度
+
+```json
+{
+  "creativity_assessment": {
+    "dimensions": [
+      {
+        "dimension": "设定新颖度",
+        "metrics": [
+          "世界观独特性",
+          "能力体系创新性",
+          "社会结构差异度"
+        ],
+        "scoring": "0-10分，基于与常见设定的差异度"
+      },
+      {
+        "dimension": "情节意外性",
+        "metrics": [
+          "转折的不可预测性",
+          "冲突的新颖性",
+          "解决方案的独特性"
+        ],
+        "scoring": "0-10分，基于读者预期偏离度"
+      },
+      {
+        "dimension": "角色深度",
+        "metrics": [
+          "性格复杂度",
+          "动机合理性",
+          "成长弧线完整性"
+        ],
+        "scoring": "0-10分，基于角色立体度"
+      },
+      {
+        "dimension": "表达风格",
+        "metrics": [
+          "语言特色",
+          "叙事节奏",
+          "氛围营造"
+        ],
+        "scoring": "0-10分，基于风格辨识度"
+      }
+    ],
+    "balance_formula": "总分 = 结构完整性(40%) + 创造性(40%) + 可读性(20%)"
+  }
+}
+```
+
+---
+
+## 二、改进的训练数据格式
+
+### 2.1 自适应CoT训练样本
+
+```json
+{
+  "task_type": "adaptive_structure_planning",
+  "difficulty_level": 3,
+  "metadata": {
+    "source_file": "大奉打更人",
+    "chapter": "第4章",
+    "position_percent": 3.8,
+    "beat_id": "beat_004",
+    "word_count": 3500
+  },
+  "input": {
+    "story_state": {
+      "mice_threads": {
+        "E001": {"status": "active", "progress": 0.6},
+        "C001": {"status": "active", "progress": 0.3}
+      },
+      "last_disaster": "陈府尹要杖责许七安",
+      "last_decision": "直接展示推理，用事实说话",
+      "current_position": "许七安开始推理"
+    },
+    "context": "前800字上文...",
+    "planning_goal": "设计一个智商碾压爽点，让许七安用现代知识震惊古代官员"
+  },
+  "output": {
+    "cot": {
+      "depth": "medium",
+      "steps": [
+        {
+          "step": 1,
+          "type": "分析",
+          "content": "主角优势是现代知识，特别是数学和逻辑",
+          "reasoning": "穿越者的核心优势"
+        },
+        {
+          "step": 2,
+          "type": "对比设计",
+          "content": "让古代人做不到的事，主角轻松做到",
+          "reasoning": "对比产生爽感"
+        },
+        {
+          "step": 3,
+          "type": "具体化",
+          "content": "数学计算：十五万两白银的重量",
+          "reasoning": "简单但古代人算不出，主角秒答",
+          "alternatives_considered": [
+            "化学知识（太复杂，铺垫不足）",
+            "物理原理（不够直观）"
+          ]
+        },
+        {
+          "step": 4,
+          "type": "增强设计",
+          "content": "加入旁观者震惊反应和主角内心吐槽",
+          "reasoning": "多角度放大爽点效果"
+        }
+      ]
+    },
+    "structure_plan": {
+      "scene": {
+        "goal": "说服官员相信推理",
+        "conflict_type": "智力对抗",
+        "disaster": "推理虽有道理，但需要证据",
+        "pacing": "快节奏，密集对话"
+      },
+      "shuang_point": {
+        "type": "智商碾压",
+        "intensity": "high",
+        "setup": "官员们讨论税银重量，无人能算",
+        "payoff": "许七安秒答九千三百七十五斤",
+        "reaction": "中年男人猛的站起身"
+      },
+      "hooks": [
+        {
+          "type": "悬念钩子",
+          "content": "推理虽然有道理，但需要证据，能否成功实验？",
+          "resolution_timing": "下一章"
+        }
+      ]
+    }
+  },
+  "verification": {
+    "structure_valid": true,
+    "logic_consistent": true,
+    "shuang_point_score": 0.92,
+    "cot_quality_score": 0.88,
+    "adversarial_check": "passed"
+  }
+}
+```
+
+### 2.2 对比学习样本（好 vs 坏）
+
+```json
+{
+  "task_type": "contrastive_learning",
+  "comparison_aspect": "爽点设计",
+  "good_example": {
+    "scene": "第4章智商碾压",
+    "setup": {
+      "content": "官员们讨论税银重量，算了半天算不出来",
+      "length": 500,
+      "elements": [
+        "建立古代人的无能",
+        "制造计算的困难",
+        "展示问题的重要性"
+      ]
+    },
+    "payoff": {
+      "content": "许七安秒答：九千三百七十五斤",
+      "timing": "setup后立即",
+      "contrast": "算不出 vs 秒答",
+      "reaction": "中年男人猛的站起身，'竟然是这样！'"
+    },
+    "enhancement": {
+      "internal_monologue": "速算能力有点Low啊，你们这群古代人",
+      "effect": "增加趣味性和优越感"
+    },
+    "why_good": [
+      "铺垫充分：先建立对比",
+      "对比强烈：算不出 vs 秒答",
+      "反应到位：震惊的肢体语言",
+      "有内心吐槽：增加可读性"
+    ],
+    "intensity_score": 9.2
+  },
+  "bad_example": {
+    "scene": "平淡版本",
+    "setup": {
+      "content": "官员问：十五万两白银有多重？",
+      "length": 50,
+      "elements": ["直接提问"]
+    },
+    "payoff": {
+      "content": "许七安说：九千三百七十五斤",
+      "timing": "立即",
+      "contrast": "无",
+      "reaction": "官员点头：嗯，有道理"
+    },
+    "enhancement": null,
+    "why_bad": [
+      "没有铺垫：没有建立对比",
+      "反应平淡：点头太弱",
+      "缺少细节：没有震惊的描写",
+      "没有放大：缺少内心吐槽或旁观者"
+    ],
+    "intensity_score": 2.1
+  },
+  "key_differences": [
+    {
+      "aspect": "铺垫长度",
+      "good": "500字，充分建立对比",
+      "bad": "50字，直接提问",
+      "impact": "爽感强度差异70%"
+    },
+    {
+      "aspect": "反应强度",
+      "good": "猛的站起身（肢体语言）",
+      "bad": "点头（口头认可）",
+      "impact": "震撼力差异80%"
+    },
+    {
+      "aspect": "细节丰富度",
+      "good": "多角度描写（动作+语言+内心）",
+      "bad": "单一描写",
+      "impact": "可读性差异60%"
+    }
+  ],
+  "learning_objective": "理解爽点设计的关键要素：铺垫、对比、反应、细节"
+}
+```
+
+### 2.3 课程学习样本序列
+
+```json
+{
+  "curriculum_learning_sequence": {
+    "principle": "从简单到复杂，逐步提升难度",
+    "stages": [
+      {
+        "stage": 1,
+        "name": "基础场景构建",
+        "difficulty_range": [1, 2],
+        "sample_count": 1000,
+        "focus": [
+          "简单对话",
+          "日常互动",
+          "单一Scene-Sequel"
+        ],
+        "success_criteria": "结构完整性 >= 0.9"
+      },
+      {
+        "stage": 2,
+        "name": "单一爽点设计",
+        "difficulty_range": [2, 3],
+        "sample_count": 800,
+        "focus": [
+          "单个爽点的铺垫-爆发",
+          "简单冲突设计",
+          "基础钩子布置"
+        ],
+        "success_criteria": "爽点有效性 >= 0.8"
+      },
+      {
+        "stage": 3,
+        "name": "复杂场景编排",
+        "difficulty_range": [3, 4],
+        "sample_count": 600,
+        "focus": [
+          "多爽点编排",
+          "起承转合结构",
+          "钩子链设计"
+        ],
+        "success_criteria": "结构完整性 >= 0.85 && 爽点密度合理"
+      },
+      {
+        "stage": 4,
+        "name": "章节级规划",
+        "difficulty_range": [4, 5],
+        "sample_count": 400,
+        "focus": [
+          "MICE线程管理",
+          "节拍设计",
+          "节奏控制"
+        ],
+        "success_criteria": "全局一致性 >= 0.8"
+      },
+      {
+        "stage": 5,
+        "name": "创新与突破",
+        "difficulty_range": [5, 5],
+        "sample_count": 200,
+        "focus": [
+          "新颖设定",
+          "独特叙事手法",
+          "风格化表达"
+        ],
+        "success_criteria": "创造性 >= 0.7 && 结构完整性 >= 0.75"
+      }
+    ],
+    "transition_strategy": "当前阶段成功率 >= 80% 时，进入下一阶段"
+  }
+}
+```
+
+---
+
+## 三、改进的实施流程
+
+### 3.1 数据生产流程 v2.0
+
+```
+步骤1: 选择优质样本
+    ↓
+步骤2: 基础模型能力评估
+    ├─ 用基础模型处理样本
+    ├─ 记录成功/失败情况
+    └─ 生成难度分布
+    ↓
+步骤3: 自适应难度分级
+    ├─ 简单样本（基础模型可处理）→ 直接标注
+    ├─ 中等样本（部分失败）→ 浅层CoT
+    └─ 困难样本（大部分失败）→ 深层CoT
+    ↓
+步骤4: 分层标注
+    ├─ 宏观层（MICE + Save the Cat）
+    ├─ 中观层（起承转合 + 爽点钩子）
+    └─ 微观层（Scene-Sequel + 对话）
+    ↓
+步骤5: 动态CoT生成
+    ├─ 难度1-2：直接输出
+    ├─ 难度3：简化CoT
+    └─ 难度4-5：完整CoT
+    ↓
+步骤6: 多层验证
+    ├─ Layer 1: 结构完整性（自动修复）
+    ├─ Layer 2: 逻辑一致性（标记）
+    ├─ Layer 3: 爽点有效性（评分）
+    ├─ Layer 4: CoT质量（PRM评分）
+    └─ Layer 5: 对抗性验证（发现隐藏问题）
+    ↓
+步骤7: 生成对比样本
+    ├─ 好样本：原文
+    ├─ 坏样本：AI生成的低质版本
+    └─ 对比分析：关键差异
+    ↓
+步骤8: 课程学习排序
+    ├─ 按难度分级
+    ├─ 按阶段分组
+    └─ 生成训练序列
+    ↓
+步骤9: 质量报告与迭代
+    ├─ 生成质量报告
+    ├─ 人工复核标记项
+    └─ 持续优化
+```
+
+### 3.2 AI辅助标注流程
+
+```json
+{
+  "ai_assisted_annotation": {
+    "principle": "AI辅助，人工把关",
+    "workflow": [
+      {
+        "step": 1,
+        "task": "初步标注",
+        "method": "使用强大的LLM（如GPT-4）进行初步标注",
+        "output": "完整的多层次标注JSON",
+        "quality": "70-80%准确率"
+      },
+      {
+        "step": 2,
+        "task": "自动验证",
+        "method": "通过多层验证系统检查",
+        "output": "质量报告 + 问题标记",
+        "auto_fix": "结构性问题自动修复"
+      },
+      {
+        "step": 3,
+        "task": "人工复核",
+        "method": "人工仅复核被标记的问题项",
+        "focus": [
+          "逻辑一致性问题",
+          "创造性评估",
+          "边界案例"
+        ],
+        "efficiency": "人工工作量减少80%"
+      },
+      {
+        "step": 4,
+        "task": "反馈优化",
+        "method": "将人工修正反馈给AI标注系统",
+        "output": "持续提升AI标注质量",
+        "target": "最终达到90%+准确率"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 四、关键创新点详解
+
+### 4.1 思考过程提取的三个层次
+
+#### Level 1: 决策思考链（Decision CoT）
+
+**适用场景**：结构性决策（如MICE嵌套、节拍设计）
+
+**格式**：
+```json
+{
+  "decision_cot": {
+    "question": "为什么第6章就结束税银案？",
+    "analysis": {
+      "current_state": "税银案已展示主角能力",
+      "constraints": [
+        "网文读者需要快速满足",
+        "百万字长篇需要更大格局"
+      ],
+      "alternatives": [
+        {
+          "option": "拖到20章",
+          "pros": "充分展开",
+          "cons": "节奏太慢，读者流失",
+          "score": 3
+        },
+        {
+          "option": "3章结束",
+          "pros": "节奏快",
+          "cons": "无法充分展示能力",
+          "score": 5
+        },
+        {
+          "option": "6章结束",
+          "pros": "平衡展示和节奏",
+          "cons": "无明显缺点",
+          "score": 9
+        }
+      ]
+    },
+    "decision": "6章结束税银案",
+    "reasoning": "6万字足够展示能力，快速满足后开启新故事",
+    "expected_effect": "保持新鲜感和节奏"
+  }
+}
+```
+
+#### Level 2: 设计思考链（Design CoT）
+
+**适用场景**：爽点、钩子、冲突设计
+
+**格式**：
+```json
+{
+  "design_cot": {
+    "goal": "设计第4章的智商碾压爽点",
+    "constraints": [
+      "主角优势：现代知识",
+      "场景：官府审案",
+      "目标：震惊古代官员"
+    ],
+    "brainstorming": [
+      {
+        "idea": "化学知识制造证据",
+        "feasibility": 0.6,
+        "impact": 0.9,
+        "issue": "铺垫不足，读者可能不理解"
+      },
+      {
+        "idea": "数学计算白银重量",
+        "feasibility": 0.9,
+        "impact": 0.8,
+        "advantage": "简单直观，对比强烈"
+      },
+      {
+        "idea": "物理原理推理",
+        "feasibility": 0.7,
+        "impact": 0.7,
+        "issue": "不够直观"
+      }
+    ],
+    "selection": "数学计算白银重量",
+    "enhancement": [
+      "先让古代人算不出来（建立对比）",
+      "主角秒答（强烈反差）",
+      "震惊反应（放大效果）",
+      "内心吐槽（增加趣味）"
+    ],
+    "final_design": {
+      "setup": "官员们讨论税银重量，无人能算",
+      "payoff": "许七安秒答九千三百七十五斤",
+      "reaction": "中年男人猛的站起身",
+      "internal": "速算能力有点Low啊，你们这群古代人"
+    }
+  }
+}
+```
+
+#### Level 3: 创作思考链（Creative CoT）
+
+**适用场景**：独特设定、创新手法
+
+**格式**：
+```json
+{
+  "creative_cot": {
+    "challenge": "如何设计一个独特的修炼体系？",
+    "inspiration_sources": [
+      "传统仙侠：境界突破",
+      "西方奇幻：职业体系",
+      "现代科幻：科技升级"
+    ],
+    "innovation_process": [
+      {
+        "step": 1,
+        "thought": "传统境界体系太常见",
+        "direction": "寻找差异化"
+      },
+      {
+        "step": 2,
+        "thought": "能否结合职业和境界？",
+        "exploration": "儒道佛妖术士，不同体系"
+      },
+      {
+        "step": 3,
+        "thought": "如何让主角特殊？",
+        "innovation": "主角不修炼，靠系统升级"
+      },
+      {
+        "step": 4,
+        "thought": "如何保持平衡？",
+        "solution": "系统升级有代价，需要解决案件"
+      }
+    ],
+    "final_concept": {
+      "system_name": "打更人系统",
+      "uniqueness": "不修炼，靠破案升级",
+      "balance": "升级有代价，需要智慧而非武力",
+      "story_integration": "完美契合主角现代警察身份"
+    }
+  }
+}
+```
+
+### 4.2 可验证性设计
+
+#### 自动化验证规则
+
+```json
+{
+  "automated_verification_rules": {
+    "structure_rules": [
+      {
+        "rule_id": "SR001",
+        "name": "MICE嵌套完整性",
+        "check": "每个打开的线程必须关闭",
+        "implementation": "栈结构验证",
+        "auto_fix": true,
+        "fix_method": "标记未关闭线程，建议关闭位置"
+      },
+      {
+        "rule_id": "SR002",
+        "name": "Scene-Sequel因果链",
+        "check": "每个Scene的Disaster必须引出Sequel",
+        "implementation": "图结构验证",
+        "auto_fix": false,
+        "flag_severity": "high"
+      }
+    ],
+    "shuang_point_rules": [
+      {
+        "rule_id": "SP001",
+        "name": "铺垫长度检查",
+        "check": "setup_length >= 100字",
+        "threshold": 100,
+        "auto_fix": false,
+        "suggestion": "增加铺垫内容"
+      },
+      {
+        "rule_id": "SP002",
+        "name": "反应强度匹配",
+        "check": "reaction_intensity >= shuang_point_intensity",
+        "implementation": "情感强度分析",
+        "auto_fix": false,
+        "flag_severity": "medium"
+      }
+    ],
+    "cot_quality_rules": [
+      {
+        "rule_id": "CQ001",
+        "name": "推理步骤完整性",
+        "check": "每个决策必须有reasoning",
+        "auto_fix": false,
+        "flag_severity": "high"
+      },
+      {
+        "rule_id": "CQ002",
+        "name": "替代方案考虑",
+        "check": "重要决策必须考虑至少2个替代方案",
+        "threshold": 2,
+        "auto_fix": false,
+        "suggestion": "补充替代方案分析"
+      }
+    ]
+  }
+}
+```
+
+#### 对抗性验证示例
+
+```json
+{
+  "adversarial_verification": {
+    "method": "使用对抗模型尝试找出矛盾和问题",
+    "test_cases": [
+      {
+        "test_id": "AV001",
+        "category": "角色一致性",
+        "adversarial_prompt": "找出角色行为前后矛盾的地方",
+        "example_finding": {
+          "issue": "第3章许七安说不会武功，第5章却打败了敌人",
+          "severity": "high",
+          "suggestion": "修改第5章，改为用智慧而非武力解决"
+        }
+      },
+      {
+        "test_id": "AV002",
+        "category": "爽点合理性",
+        "adversarial_prompt": "找出爽点铺垫不足的地方",
+        "example_finding": {
+          "issue": "第4章官员震惊于许七安的计算，但前文未建立古代人数学能力弱",
+          "severity": "medium",
+          "suggestion": "增加铺垫：官员们尝试计算但失败"
+        }
+      },
+      {
+        "test_id": "AV003",
+        "category": "逻辑漏洞",
+        "adversarial_prompt": "找出因果关系不合理的地方",
+        "example_finding": {
+          "issue": "许七安推理出破绽，但官员为何之前没发现？",
+          "severity": "low",
+          "suggestion": "补充说明：官员们被妖物说法误导"
+        }
+      }
+    ]
+  }
+}
+```
+
+### 4.3 结构化与创造性平衡的实践
+
+#### 分层约束策略
+
+```json
+{
+  "layered_constraint_strategy": {
+    "layer_1_foundation": {
+      "name": "基础结构层",
+      "constraint_level": "严格",
+      "elements": [
+        "MICE线程嵌套规则",
+        "Scene-Sequel因果链",
+        "基本节拍位置"
+      ],
+      "rationale": "这是叙事的骨架，必须稳固",
+      "training_approach": "强化学习，高权重"
+    },
+    "layer_2_pattern": {
+      "name": "模式层",
+      "constraint_level": "中等",
+      "elements": [
+        "起承转合比例",
+        "爽点密度范围",
+        "钩子布置频率"
+      ],
+      "rationale": "有最佳实践，但可调整",
+      "training_approach": "提供范围，允许探索"
+    },
+    "layer_3_expression": {
+      "name": "表达层",
+      "constraint_level": "弱",
+      "elements": [
+        "对话风格",
+        "描写手法",
+        "情节细节"
+      ],
+      "rationale": "创造性的主要空间",
+      "training_approach": "鼓励多样性，奖励创新"
+    },
+    "layer_4_innovation": {
+      "name": "创新层",
+      "constraint_level": "无",
+      "elements": [
+        "独特设定",
+        "创新手法",
+        "风格突破"
+      ],
+      "rationale": "完全自由创作",
+      "training_approach": "探索奖励，无惩罚"
+    }
+  }
+}
+```
+
+#### 创造性激励机制
+
+```json
+{
+  "creativity_incentive": {
+    "novelty_bonus": {
+      "description": "奖励新颖的设计",
+      "calculation": "与训练集中已有样本的差异度",
+      "threshold": 0.7,
+      "bonus_weight": 0.2
+    },
+    "surprise_reward": {
+      "description": "奖励意外但合理的转折",
+      "metrics": [
+        "读者预期偏离度",
+        "逻辑自洽性"
+      ],
+      "formula": "surprise_score * logic_score",
+      "bonus_weight": 0.15
+    },
+    "style_diversity": {
+      "description": "鼓励风格多样性",
+      "measurement": "与已生成内容的风格差异",
+      "target": "避免模式化",
+      "bonus_weight": 0.1
+    },
+    "constraint_balance": {
+      "description": "平衡结构和创造性",
+      "formula": "structure_score * 0.4 + creativity_score * 0.4 + readability_score * 0.2",
+      "target_range": [0.75, 0.95]
+    }
+  }
+}
+```
+
+---
+
+## 五、训练策略
+
+### 5.1 课程学习详细方案
+
+```json
+{
+  "curriculum_learning_plan": {
+    "overview": "从简单到复杂，逐步提升模型能力",
+    "phases": [
+      {
+        "phase": 1,
+        "name": "基础能力建立",
+        "duration": "1-2 epochs",
+        "data": {
+          "difficulty_range": [1, 2],
+          "sample_count": 10000,
+          "focus": "Scene-Sequel基础结构"
+        },
+        "objectives": [
+          "学会基本的因果链",
+          "理解Goal-Conflict-Disaster",
+          "掌握简单对话"
+        ],
+        "success_criteria": {
+          "structure_accuracy": ">= 0.9",
+          "logic_consistency": ">= 0.85"
+        }
+      },
+      {
+        "phase": 2,
+        "name": "爽点设计能力",
+        "duration": "2-3 epochs",
+        "data": {
+          "difficulty_range": [2, 3],
+          "sample_count": 8000,
+          "focus": "单一爽点的铺垫-爆发-反应"
+        },
+        "objectives": [
+          "学会设计有效的铺垫",
+          "掌握对比和反差",
+          "理解反应放大"
+        ],
+        "success_criteria": {
+          "shuang_point_effectiveness": ">= 0.8",
+          "setup_quality": ">= 0.75"
+        }
+      },
+      {
+        "phase": 3,
+        "name": "复杂编排能力",
+        "duration": "3-4 epochs",
+        "data": {
+          "difficulty_range": [3, 4],
+          "sample_count": 6000,
+          "focus": "多爽点编排、起承转合、钩子链"
+        },
+        "objectives": [
+          "学会多爽点的节奏控制",
+          "掌握起承转合比例",
+          "理解钩子的制造和满足"
+        },
+        "success_criteria": {
+          "pacing_quality": ">= 0.8",
+          "hook_effectiveness": ">= 0.75"
+        }
+      },
+      {
+        "phase": 4,
+        "name": "全局规划能力",
+        "duration": "4-5 epochs",
+        "data": {
+          "difficulty_range": [4, 5],
+          "sample_count": 4000,
+          "focus": "MICE线程管理、节拍设计、长篇结构"
+        },
+        "objectives": [
+          "学会MICE线程嵌套",
+          "掌握Save the Cat节拍",
+          "理解长篇节奏控制"
+        ],
+        "success_criteria": {
+          "structure_completeness": ">= 0.85",
+          "global_consistency": ">= 0.8"
+        }
+      },
+      {
+        "phase": 5,
+        "name": "创新突破能力",
+        "duration": "2-3 epochs",
+        "data": {
+          "difficulty_range": [5, 5],
+          "sample_count": 2000,
+          "focus": "独特设定、创新手法、风格化"
+        },
+        "objectives": [
+          "鼓励创新和突破",
+          "保持结构完整性",
+          "平衡创造性和可读性"
+        },
+        "success_criteria": {
+          "creativity_score": ">= 0.7",
+          "structure_score": ">= 0.75",
+          "balance_score": ">= 0.8"
+        }
+      }
+    ],
+    "transition_rules": {
+      "automatic_progression": "当前阶段成功率 >= 80% 时自动进入下一阶段",
+      "regression_handling": "如果成功率 < 60%，回退到上一阶段",
+      "mixed_training": "后期阶段混合前期数据，保持基础能力"
+    }
+  }
+}
+```
+
+### 5.2 对比学习策略
+
+```json
+{
+  "contrastive_learning_strategy": {
+    "principle": "通过好坏对比，让模型理解什么是有效的设计",
+    "pair_generation": {
+      "good_example": "原文或高质量标注",
+      "bad_example_sources": [
+        {
+          "source": "AI生成的低质版本",
+          "method": "移除关键要素（如铺垫、反应）",
+          "purpose": "理解要素的重要性"
+        },
+        {
+          "source": "常见错误模式",
+          "examples": [
+            "铺垫不足",
+            "反应平淡",
+            "逻辑矛盾"
+          ],
+          "purpose": "学会避免常见错误"
+        },
+        {
+          "source": "过度设计版本",
+          "method": "添加过多元素，破坏节奏",
+          "purpose": "理解适度的重要性"
+        }
+      ]
+    },
+    "training_format": {
+      "input": "任务描述 + 上下文",
+      "output_a": "好样本",
+      "output_b": "坏样本",
+      "label": "A > B",
+      "explanation": "关键差异分析"
+    },
+    "loss_function": "Ranking Loss + Explanation Loss",
+    "expected_benefit": "提升判断力和设计质量"
+  }
+}
+```
+
+### 5.3 强化学习微调
+
+```json
+{
+  "reinforcement_learning_finetuning": {
+    "principle": "通过奖励信号优化生成质量",
+    "reward_model": {
+      "components": [
+        {
+          "component": "结构完整性奖励",
+          "weight": 0.3,
+          "calculation": "基于验证器的结构检查结果"
+        },
+        {
+          "component": "爽点有效性奖励",
+          "weight": 0.25,
+          "calculation": "基于爽点评分系统"
+        },
+        {
+          "component": "逻辑一致性奖励",
+          "weight": 0.2,
+          "calculation": "基于对抗性验证结果"
+        },
+        {
+          "component": "创造性奖励",
+          "weight": 0.15,
+          "calculation": "基于新颖度和多样性"
+        },
+        {
+          "component": "可读性奖励",
+          "weight": 0.1,
+          "calculation": "基于流畅度和吸引力"
+        }
+      ],
+      "total_reward": "加权求和"
+    },
+    "training_algorithm": "PPO (Proximal Policy Optimization)",
+    "exploration_strategy": {
+      "early_stage": "高探索率，鼓励多样性",
+      "late_stage": "低探索率，优化质量"
+    }
+  }
+}
+```
+
+---
+
+## 六、质量评估体系
+
+### 6.1 多维度评估指标
+
+```json
+{
+  "quality_assessment_metrics": {
+    "dimension_1_structure": {
+      "name": "结构完整性",
+      "weight": 0.3,
+      "sub_metrics": [
+        {
+          "metric": "MICE线程完整性",
+          "calculation": "正确嵌套的线程数 / 总线程数",
+          "threshold": 0.9
+        },
+        {
+          "metric": "Scene-Sequel因果链",
+          "calculation": "有效因果关系数 / 总场景数",
+          "threshold": 0.85
+        },
+        {
+          "metric": "节拍覆盖度",
+          "calculation": "已覆盖节拍数 / 应有节拍数",
+          "threshold": 0.8
+        }
+      ]
+    },
+    "dimension_2_effectiveness": {
+      "name": "爽点有效性",
+      "weight": 0.25,
+      "sub_metrics": [
+        {
+          "metric": "铺垫充分度",
+          "calculation": "setup_length / expected_length",
+          "threshold": 0.8
+        },
+        {
+          "metric": "反应强度匹配",
+          "calculation": "reaction_intensity / shuang_point_intensity",
+          "threshold": 0.9
+        },
+        {
+          "metric": "爽点密度合理性",
+          "calculation": "是否在合理范围内（0.5-1.5个/千字）",
+          "threshold": "in_range"
+        }
+      ]
+    },
+    "dimension_3_consistency": {
+      "name": "逻辑一致性",
+      "weight": 0.2,
+      "sub_metrics": [
+        {
+          "metric": "角色行为一致性",
+          "calculation": "基于对抗性验证结果",
+          "threshold": 0.85
+        },
+        {
+          "metric": "时间线连贯性",
+          "calculation": "时间矛盾数 / 总事件数",
+          "threshold": "< 0.05"
+        },
+        {
+          "metric": "因果合理性",
+          "calculation": "合理因果关系数 / 总因果关系数",
+          "threshold": 0.9
+        }
+      ]
+    },
+    "dimension_4_creativity": {
+      "name": "创造性",
+      "weight": 0.15,
+      "sub_metrics": [
+        {
+          "metric": "设定新颖度",
+          "calculation": "与常见设定的差异度",
+          "threshold": 0.6
+        },
+        {
+          "metric": "情节意外性",
+          "calculation": "读者预期偏离度",
+          "threshold": 0.5
+        },
+        {
+          "metric": "风格辨识度",
+          "calculation": "与其他作品的风格差异",
+          "threshold": 0.5
+        }
+      ]
+    },
+    "dimension_5_readability": {
+      "name": "可读性",
+      "weight": 0.1,
+      "sub_metrics": [
+        {
+          "metric": "语言流畅度",
+          "calculation": "基于困惑度（Perplexity）",
+          "threshold": "< 50"
+        },
+        {
+          "metric": "节奏合理性",
+          "calculation": "快慢节奏交替是否合理",
+          "threshold": 0.8
+        },
+        {
+          "metric": "吸引力",
+          "calculation": "钩子有效性 + 爽点密度",
+          "threshold": 0.75
+        }
+      ]
+    }
+  }
+}
+```
+
+### 6.2 自动化评估流程
+
+```
+生成的内容
+    ↓
+[评估器1] 结构完整性评估
+    ├─ MICE线程检查
+    ├─ Scene-Sequel验证
+    └─ 节拍覆盖度
+    ↓
+[评估器2] 爽点有效性评估
+    ├─ 铺垫充分度
+    ├─ 反应强度
+    └─ 密度合理性
+    ↓
+[评估器3] 逻辑一致性评估
+    ├─ 角色行为
+    ├─ 时间线
+    └─ 因果关系
+    ↓
+[评估器4] 创造性评估
+    ├─ 新颖度
+    ├─ 意外性
+    └─ 风格
+    ↓
+[评估器5] 可读性评估
+    ├─ 流畅度
+    ├─ 节奏
+    └─ 吸引力
+    ↓
+综合评分 + 详细报告
+    ↓
+通过/不通过 + 改进建议
+```
+
+---
+
+## 七、实施路线图
+
+### 7.1 短期目标（1-2个月）
+
+```json
+{
+  "short_term_goals": {
+    "month_1": {
+      "week_1_2": {
+        "task": "构建基础设施",
+        "deliverables": [
+          "多层验证系统实现",
+          "难度分级算法实现",
+          "AI辅助标注工具"
+        ]
+      },
+      "week_3_4": {
+        "task": "生成初始数据集",
+        "deliverables": [
+          "1000个基础场景样本（难度1-2）",
+          "500个爽点设计样本（难度2-3）",
+          "质量验证报告"
+        ]
+      }
+    },
+    "month_2": {
+      "week_1_2": {
+        "task": "训练基础模型",
+        "deliverables": [
+          "完成Phase 1-2训练",
+          "基础能力评估报告",
+          "问题识别和优化"
+        ]
+      },
+      "week_3_4": {
+        "task": "扩展数据集",
+        "deliverables": [
+          "500个复杂场景样本（难度3-4）",
+          "200个创新样本（难度5）",
+          "对比学习样本库"
+        ]
+      }
+    }
+  }
+}
+```
+
+### 7.2 中期目标（3-6个月）
+
+```json
+{
+  "medium_term_goals": {
+    "month_3_4": {
+      "task": "完整课程学习",
+      "deliverables": [
+        "完成Phase 1-5全部训练",
+        "模型能力全面评估",
+        "生成质量达到可用水平"
+      ]
+    },
+    "month_5_6": {
+      "task": "强化学习优化",
+      "deliverables": [
+        "实现奖励模型",
+        "完成RL微调",
+        "质量显著提升"
+      ]
+    }
+  }
+}
+```
+
+### 7.3 长期目标（6-12个月）
+
+```json
+{
+  "long_term_goals": {
+    "month_7_9": {
+      "task": "领域扩展",
+      "deliverables": [
+        "扩展到多种类型（科幻、言情、历史）",
+        "跨类型迁移学习",
+        "通用叙事模型"
+      ]
+    },
+    "month_10_12": {
+      "task": "产品化",
+      "deliverables": [
+        "交互式创作工具",
+        "实时质量反馈",
+        "商业化应用"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 八、成功案例与预期效果
+
+### 8.1 预期改进效果
+
+```json
+{
+  "expected_improvements": {
+    "vs_v1_0": {
+      "思考过程质量": {
+        "v1_0": "示例性，缺乏系统性",
+        "v2_0": "自适应深度，覆盖全面",
+        "improvement": "+60%"
+      },
+      "数据可验证性": {
+        "v1_0": "人工检查，效率低",
+        "v2_0": "多层自动验证，准确率高",
+        "improvement": "+80%"
+      },
+      "训练效率": {
+        "v1_0": "统一处理，效率一般",
+        "v2_0": "课程学习，效率显著提升",
+        "improvement": "+50%"
+      },
+      "生成质量": {
+        "v1_0": "结构完整，但可能僵化",
+        "v2_0": "结构完整 + 创造性平衡",
+        "improvement": "+40%"
+      }
+    },
+    "vs_baseline": {
+      "结构完整性": {
+        "baseline": "0.6",
+        "v2_0": "0.9+",
+        "improvement": "+50%"
+      },
+      "爽点有效性": {
+        "baseline": "0.5",
+        "v2_0": "0.85+",
+        "improvement": "+70%"
+      },
+      "创造性": {
+        "baseline": "0.4",
+        "v2_0": "0.7+",
+        "improvement": "+75%"
+      },
+      "整体质量": {
+        "baseline": "0.5",
+        "v2_0": "0.8+",
+        "improvement": "+60%"
+      }
+    }
+  }
+}
+```
+
+### 8.2 应用场景
+
+```json
+{
+  "application_scenarios": {
+    "scenario_1": {
+      "name": "辅助创作",
+      "description": "帮助作者规划结构、设计爽点",
+      "user": "网文作者",
+      "benefit": "提升创作效率50%，保证质量稳定"
+    },
+    "scenario_2": {
+      "name": "自动续写",
+      "description": "基于前文自动生成后续章节",
+      "user": "内容平台",
+      "benefit": "降低内容生产成本，扩大内容库"
+    },
+    "scenario_3": {
+      "name": "剧本优化",
+      "description": "分析和优化现有剧本",
+      "user": "影视公司",
+      "benefit": "提升剧本质量，降低风险"
+    },
+    "scenario_4": {
+      "name": "教学工具",
+      "description": "教授叙事技巧和结构设计",
+      "user": "写作培训机构",
+      "benefit": "系统化教学，可视化反馈"
+    }
+  }
+}
+```
+
+---
+
+## 九、总结与展望
+
+### 9.1 核心创新总结
+
+1. **自适应思考过程提取**
+   - 根据难度动态调整CoT深度
+   - 避免过度思考，提升效率
+   - 覆盖决策、设计、创作三个层次
+
+2. **多层验证系统**
+   - 5层验证，从结构到创造性
+   - 自动化 + 对抗性验证
+   - 确保数据质量和一致性
+
+3. **结构化与创造性平衡**
+   - 分层约束策略
+   - 创造性激励机制
+   - 动态平衡结构和自由度
+
+4. **课程学习与强化学习结合**
+   - 从简单到复杂的渐进式训练
+   - 对比学习提升判断力
+   - RL微调优化生成质量
+
+### 9.2 与v1.0的关系
+
+- **v1.0是基础**：提供了完整的理论框架和标注维度
+- **v2.0是升级**：在v1.0基础上增加了可操作性和可验证性
+- **兼容性**：v2.0完全兼容v1.0的数据格式，可以平滑升级
+
+### 9.3 未来优化方向
+
+1. **更智能的难度评估**
+   - 引入更多维度的难度指标
+   - 基于模型实时表现动态调整
+
+2. **更强大的验证系统**
+   - 引入更多领域知识
+   - 提升对抗性验证的覆盖度
+
+3. **更灵活的创造性控制**
+   - 可调节的创造性强度
+   - 风格化定制
+
+4. **跨模态扩展**
+   - 结合图像、音频等多模态信息
+   - 支持漫画、游戏等其他叙事形式
+
+---
+
+## 附录：快速对比表
+
+| 维度 | v1.0 | v2.0 | 改进幅度 |
+|------|------|------|---------|
+| **思考过程提取** | 示例性 | 自适应深度 | +60% |
+| **数据验证** | 人工为主 | 多层自动验证 | +80% |
+| **训练效率** | 统一处理 | 课程学习 | +50% |
+| **创造性平衡** | 未明确 | 分层约束 | +70% |
+| **可操作性** | 中等 | 高 | +60% |
+| **数据质量** | 依赖人工 | AI辅助+验证 | +75% |
+| **整体效果** | 良好 | 优秀 | +60% |
+
+---
+
+**方法论状态**: v2.0 - 可执行 + 可验证  
+**下一步**: 实施基础设施建设，开始数据生产
+
+**作者**: AI叙事研究团队  
+**联系**: [待补充]  
+**开源**: [待决定]

examples/analyze_story/read_all_files.py

@@ -0,0 +1,110 @@
+import os
+import json
+
+def read_text_file(filepath):
+    """尝试多种编码读取文本文件"""
+    encodings = ['utf-8', 'gbk', 'gb2312', 'gb18030', 'utf-16', 'big5']
+    
+    for encoding in encodings:
+        try:
+            with open(filepath, 'r', encoding=encoding) as f:
+                content = f.read()
+                if content and len(content) > 100:
+                    return content, encoding
+        except:
+            continue
+    
+    try:
+        with open(filepath, 'rb') as f:
+            raw_data = f.read()
+            content = raw_data.decode('utf-8', errors='ignore')
+            return content, 'utf-8-ignore'
+    except:
+        return None, None
+
+def read_pdf_file(filepath):
+    """读取PDF文件"""
+    try:
+        import pypdf
+        with open(filepath, 'rb') as f:
+            pdf_reader = pypdf.PdfReader(f)
+            text = ""
+            for page in pdf_reader.pages:
+                text += page.extract_text() + "\n"
+            return text, 'PDF'
+    except Exception as e:
+        try:
+            import PyPDF2
+            with open(filepath, 'rb') as f:
+                pdf_reader = PyPDF2.PdfReader(f)
+                text = ""
+                for page in pdf_reader.pages:
+                    text += page.extract_text() + "\n"
+                return text, 'PDF'
+        except Exception as e2:
+            return f"Error: {str(e)}, {str(e2)}", None
+
+def read_docx_file(filepath):
+    """读取DOCX文件"""
+    try:
+        import docx
+        doc = docx.Document(filepath)
+        text = "\n".join([para.text for para in doc.paragraphs])
+        return text, 'DOCX'
+    except Exception as e:
+        return f"Error: {str(e)}", None
+
+input_dir = "input"
+results = {}
+
+for filename in os.listdir(input_dir):
+    filepath = os.path.join(input_dir, filename)
+    if not os.path.isfile(filepath):
+        continue
+    
+    print(f"Processing: {filename}")
+    
+    if filename.endswith('.txt'):
+        content, encoding = read_text_file(filepath)
+        if content:
+            results[filename] = {
+                'format': 'TXT',
+                'encoding': encoding,
+                'length': len(content),
+                'first_3000': content[:3000]
+            }
+            print(f"  TXT - Encoding: {encoding}, Length: {len(content)}")
+        else:
+            results[filename] = {'error': 'Failed to read'}
+    
+    elif filename.endswith('.pdf'):
+        content, file_type = read_pdf_file(filepath)
+        if file_type:
+            results[filename] = {
+                'format': 'PDF',
+                'length': len(content),
+                'first_3000': content[:3000]
+            }
+            print(f"  PDF - Length: {len(content)}")
+        else:
+            results[filename] = {'error': content}
+            print(f"  PDF Error: {content}")
+    
+    elif filename.endswith('.docx'):
+        content, file_type = read_docx_file(filepath)
+        if file_type:
+            results[filename] = {
+                'format': 'DOCX',
+                'length': len(content),
+                'first_3000': content[:3000]
+            }
+            print(f"  DOCX - Length: {len(content)}")
+        else:
+            results[filename] = {'error': content}
+            print(f"  DOCX Error: {content}")
+
+# 保存结果
+with open('samples_data.json', 'w', encoding='utf-8') as f:
+    json.dump(results, f, ensure_ascii=False, indent=2)
+
+print(f"\nTotal: {len(results)} files processed")

examples/analyze_story/read_samples.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+import os
+import json
+
+def read_text_file(filepath):
+    """尝试多种编码读取文本文件"""
+    encodings = ['utf-8', 'gbk', 'gb2312', 'gb18030', 'utf-16', 'big5', 'latin1']
+    
+    for encoding in encodings:
+        try:
+            with open(filepath, 'r', encoding=encoding, errors='ignore') as f:
+                content = f.read()
+                if content and len(content) > 100:  # 确保读取到有效内容
+                    return content, encoding
+        except Exception as e:
+            continue
+    
+    # 如果都失败，使用二进制模式读取并尝试解码
+    try:
+        with open(filepath, 'rb') as f:
+            raw_data = f.read()
+            content = raw_data.decode('utf-8', errors='ignore')
+            return content, 'utf-8 (with errors ignored)'
+    except:
+        return None, None
+
+def read_pdf_file(filepath):
+    """读取PDF文件"""
+    try:
+        import PyPDF2
+        with open(filepath, 'rb') as f:
+            pdf_reader = PyPDF2.PdfReader(f)
+            text = ""
+            for page in pdf_reader.pages[:50]:  # 读取前50页
+                text += page.extract_text()
+            return text, 'PDF'
+    except ImportError:
+        return "需要安装PyPDF2库", None
+    except Exception as e:
+        return f"PDF读取错误: {str(e)}", None
+
+def read_docx_file(filepath):
+    """读取DOCX文件"""
+    try:
+        import docx
+        doc = docx.Document(filepath)
+        text = "\n".join([para.text for para in doc.paragraphs])
+        return text, 'DOCX'
+    except ImportError:
+        return "需要安装python-docx库", None
+    except Exception as e:
+        return f"DOCX读取错误: {str(e)}", None
+
+def main():
+    input_dir = "examples/analyze_story/input"
+    files = os.listdir(input_dir)
+    
+    results = {}
+    
+    for filename in files:
+        filepath = os.path.join(input_dir, filename)
+        if not os.path.isfile(filepath):
+            continue
+        
+        print(f"\n处理文件: {filename}")
+        
+        if filename.endswith('.txt'):
+            content, encoding = read_text_file(filepath)
+            if content:
+                results[filename] = {
+                    'encoding': encoding,
+                    'length': len(content),
+                    'preview': content[:500],
+                    'first_3000': content[:3000]
+                }
+                print(f"  编码: {encoding}, 长度: {len(content)}")
+            else:
+                print(f"  读取失败")
+                results[filename] = {'error': '无法读取'}
+        
+        elif filename.endswith('.pdf'):
+            content, file_type = read_pdf_file(filepath)
+            if file_type:
+                results[filename] = {
+                    'type': file_type,
+                    'length': len(content),
+                    'preview': content[:500],
+                    'first_3000': content[:3000]
+                }
+                print(f"  类型: PDF, 长度: {len(content)}")
+            else:
+                results[filename] = {'error': content}
+                print(f"  {content}")
+        
+        elif filename.endswith('.docx'):
+            content, file_type = read_docx_file(filepath)
+            if file_type:
+                results[filename] = {
+                    'type': file_type,
+                    'length': len(content),
+                    'preview': content[:500],
+                    'first_3000': content[:3000]
+                }
+                print(f"  类型: DOCX, 长度: {len(content)}")
+            else:
+                results[filename] = {'error': content}
+                print(f"  {content}")
+    
+    # 保存结果
+    with open('examples/analyze_story/samples_data.json', 'w', encoding='utf-8') as f:
+        json.dump(results, f, ensure_ascii=False, indent=2)
+    
+    print(f"\n\n读取完成，共处理 {len(results)} 个文件")
+    print("结果已保存到 examples/analyze_story/samples_data.json")
+
+if __name__ == '__main__':
+    main()

examples/analyze_story/read_txt_files.py

@@ -0,0 +1,51 @@
+import os
+import json
+
+def read_text_file(filepath):
+    """尝试多种编码读取文本文件"""
+    encodings = ['utf-8', 'gbk', 'gb2312', 'gb18030', 'utf-16', 'big5']
+    
+    for encoding in encodings:
+        try:
+            with open(filepath, 'r', encoding=encoding) as f:
+                content = f.read()
+                if content and len(content) > 100:
+                    return content, encoding
+        except:
+            continue
+    
+    # 最后尝试忽略错误
+    try:
+        with open(filepath, 'rb') as f:
+            raw_data = f.read()
+            content = raw_data.decode('utf-8', errors='ignore')
+            return content, 'utf-8-ignore'
+    except:
+        return None, None
+
+input_dir = "input"
+results = {}
+
+txt_files = [f for f in os.listdir(input_dir) if f.endswith('.txt')]
+
+for filename in txt_files:
+    filepath = os.path.join(input_dir, filename)
+    print(f"Reading: {filename}")
+    
+    content, encoding = read_text_file(filepath)
+    if content:
+        results[filename] = {
+            'encoding': encoding,
+            'length': len(content),
+            'first_3000': content[:3000]
+        }
+        print(f"  Success - Encoding: {encoding}, Length: {len(content)}")
+    else:
+        results[filename] = {'error': 'Failed to read'}
+        print(f"  Failed")
+
+# 保存结果
+with open('samples_data.json', 'w', encoding='utf-8') as f:
+    json.dump(results, f, ensure_ascii=False, indent=2)
+
+print(f"\nProcessed {len(results)} files")

examples/analyze_story/run.py

@@ -16,6 +16,9 @@ import argparse
 import os
 import sys
 import select
+import msvcrt
+from datetime import datetime
+import sys
 import asyncio
 from pathlib import Path
 
@@ -43,19 +46,14 @@ from agent.llm import create_openrouter_llm_call
 # ===== 非阻塞 stdin 检测 =====
 
 def check_stdin() -> str | None:
-    """
-    非阻塞检查 stdin 是否有输入。
-
-    使用 select 轮询，不开后台线程，因此不会与交互菜单的 input() 抢 stdin。
-    """
-    ready, _, _ = select.select([sys.stdin], [], [], 0)
-    if ready:
-        line = sys.stdin.readline().strip().lower()
-        if line in ('p', 'pause'):
-            return 'pause'
-        if line in ('q', 'quit'):
-            return 'quit'
-    return None
+    # 针对 Windows 的修复方案
+    if sys.platform == "win32":
+        if msvcrt.kbhit(): # 检查是否有按键按下
+            ch = msvcrt.getch().decode('utf-8').lower()
+            if ch == 'p': return 'pause'
+            if ch == 'q': return 'quit'
+        return None
+    
 
 
 # ===== 交互菜单 =====
@@ -85,7 +83,6 @@ def _read_multiline() -> str:
         lines.pop()
     return "\n".join(lines)
 
-
 async def show_interactive_menu(
     runner: AgentRunner,
     trace_id: str,
@@ -104,12 +101,14 @@ async def show_interactive_menu(
     print("  1. 插入干预消息并继续")
     print("  2. 触发经验总结（reflect）")
     print("  3. 查看当前 GoalTree")
-    print("  4. 继续执行")
-    print("  5. 停止执行")
+    print("  4. 手动压缩上下文（compact）")
+    print("  5. 继续执行")
+    print("  6. 停止执行")
+    print("  7. 经验库瘦身（合并相似经验）")
     print("=" * 60)
 
     while True:
-        choice = input("请输入选项 (1-5): ").strip()
+        choice = input("请输入选项 (1-7): ").strip()
 
         if choice == "1":
             text = _read_multiline()
@@ -130,18 +129,18 @@ async def show_interactive_menu(
             focus = input("请输入反思重点（可选，直接回车跳过）: ").strip()
 
             from agent.trace.compaction import build_reflect_prompt
+            import re
+            import uuid
 
-            # 保存当前 head_sequence
+            # 1. 执行反思生成
             trace = await store.get_trace(trace_id)
             saved_head = trace.head_sequence
-
             prompt = build_reflect_prompt()
             if focus:
                 prompt += f"\n\n请特别关注：{focus}"
 
             print("正在生成反思...")
             reflect_cfg = RunConfig(trace_id=trace_id, max_iterations=1, tools=[])
-
             reflection_text = ""
             try:
                 result = await runner.run_result(
@@ -150,19 +149,49 @@ async def show_interactive_menu(
                 )
                 reflection_text = result.get("summary", "")
             finally:
-                # 恢复 head_sequence（反思消息成为侧枝）
                 await store.update_trace(trace_id, head_sequence=saved_head)
 
-            # 追加到 experiences 文件
+            # 2. 结构化解析与保存 (ACE Curator 逻辑)
             if reflection_text:
-                from datetime import datetime
                 experiences_path = runner.experiences_path or "./.cache/experiences.md"
                 os.makedirs(os.path.dirname(experiences_path), exist_ok=True)
-                header = f"\n\n---\n\n## {trace_id} ({datetime.now().strftime('%Y-%m-%d %H:%M')})\n\n"
-                with open(experiences_path, "a", encoding="utf-8") as f:
-                    f.write(header + reflection_text + "\n")
-                print(f"\n反思已保存到: {experiences_path}")
-                print("\n--- 反思内容 ---")
+                
+                # 正则匹配：- [intent:..., state:...] 内容
+                pattern = r"- \[(intent:.*?, state:.*?)\] (.*)"
+                matches = re.findall(pattern, reflection_text)
+                
+                structured_entries = []
+                for tags_str, content in matches:
+                    # 生成唯一 ID
+                    ex_id = f"ex_{datetime.now().strftime('%m%d%H%M')}_{uuid.uuid4().hex[:4]}"
+                    
+                    # 提取标签详情
+                    intent_match = re.search(r"intent:(.*?),", tags_str)
+                    state_match = re.search(r"state:(.*)", tags_str)
+                    intents = [i.strip() for i in intent_match.group(1).split(",")] if intent_match else []
+                    states = [s.strip() for s in state_match.group(1).split(",")] if state_match else []
+
+                    # 构造符合 ACE 规范的结构化条目 [cite: 184, 185]
+                    entry = f"""---
+id: {ex_id}
+trace_id: {trace_id}
+tags: {{intent: {intents}, state: {states}}}
+metrics: {{helpful: 1, harmful: 0}}
+created_at: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+---
+- {content}
+- 经验ID: [{ex_id}]
+"""
+                    structured_entries.append(entry)
+
+                if structured_entries:
+                    with open(experiences_path, "a", encoding="utf-8") as f:
+                        f.write("\n\n" + "\n\n".join(structured_entries))
+                    print(f"\n✅ 已成功提取并保存 {len(structured_entries)} 条结构化经验到: {experiences_path}")
+                else:
+                    print("\n⚠️ 未能解析出符合格式的经验条目，请检查 REFLECT_PROMPT。")
+                
+                print("\n--- 原始反思内容 ---")
                 print(reflection_text)
                 print("--- 结束 ---\n")
             else:
@@ -180,13 +209,54 @@ async def show_interactive_menu(
             continue
 
         elif choice == "4":
+            # 手动压缩上下文
+            print("\n正在执行上下文压缩（compact）...")
+            try:
+                goal_tree = await store.get_goal_tree(trace_id)
+                trace = await store.get_trace(trace_id)
+                if not trace:
+                    print("未找到 Trace，无法压缩")
+                    continue
+
+                # 重建当前 history
+                main_path = await store.get_main_path_messages(trace_id, trace.head_sequence)
+                history = [msg.to_llm_dict() for msg in main_path]
+                head_seq = main_path[-1].sequence if main_path else 0
+                next_seq = head_seq + 1
+
+                compact_config = RunConfig(trace_id=trace_id)
+                new_history, new_head, new_seq = await runner._compress_history(
+                    trace_id=trace_id,
+                    history=history,
+                    goal_tree=goal_tree,
+                    config=compact_config,
+                    sequence=next_seq,
+                    head_seq=head_seq,
+                )
+                print(f"\n✅ 压缩完成: {len(history)} 条消息 → {len(new_history)} 条")
+            except Exception as e:
+                print(f"\n❌ 压缩失败: {e}")
+            continue
+
+        elif choice == "5":
             print("\n继续执行...")
             return {"action": "continue"}
 
-        elif choice == "5":
+        elif choice == "6":
             print("\n停止执行...")
             return {"action": "stop"}
 
+        elif choice == "7":
+            # 经验库瘦身
+            print("\n正在执行经验库瘦身...")
+            from agent.tools.builtin.experience import slim_experiences
+            try:
+                result = await slim_experiences()
+                print(f"\n{result}")
+            except Exception as e:
+                print(f"\n经验库瘦身失败: {e}")
+            continue
+
         else:
             print("无效选项，请重新输入")
 

examples/analyze_story/一周执行计划.md

@@ -0,0 +1,318 @@
+# 一周核心训练执行计划
+
+**目标**: 在一周内完成核心环节的数据生成和模型微调，验证v2.0方法论的有效性
+
+**时间**: 2026-02-27 至 2026-03-05（7天）
+
+---
+
+## 📅 Day 1-2: 数据生成与质量验证（2天）
+
+### Day 1 上午：快速验证与优化
+- [ ] **验证现有流程**（2小时）
+  - 运行 `run_pipeline.py` 处理《搜神记》（已有部分结果）
+  - 检查生成的 SFT 数据质量
+  - 识别流程中的瓶颈和问题
+
+- [ ] **优化数据生成**（2小时）
+  - 实现多层验证系统的简化版（结构完整性 + 爽点有效性）
+  - 添加难度自动分级功能
+  - 优化 CoT 生成策略（根据难度调整深度）
+
+### Day 1 下午：批量数据生产
+- [ ] **处理核心样本**（4小时）
+  - 《大奉打更人》前50章（约15万字）- 重点：爽点设计
+  - 《雪中悍刀行》前30章（约10万字）- 重点：角色塑造
+  - 《中国合伙人》完整剧本 - 重点：节拍结构
+  - 《无双》短剧前10集 - 重点：快节奏钩子
+
+### Day 1 晚上：质量检查
+- [ ] **人工抽样验证**（2小时）
+  - 每个样本抽取10条数据
+  - 检查 CoT 质量、结构完整性、爽点有效性
+  - 记录问题并调整生成参数
+
+### Day 2 全天：扩展数据集
+- [ ] **继续处理剩余样本**（6小时）
+  - 《魔道祖师》前20章 - 重点：情感线
+  - 《搜神记》完整 - 重点：世界观构建
+  - 补充对比学习样本（好vs坏）
+
+- [ ] **数据清洗与增强**（2小时）
+  - 运行多层验证系统
+  - 修复标记的问题
+  - 生成统计报告
+
+**Day 1-2 目标产出**:
+- ✅ 3000+ 条高质量 SFT 样本
+- ✅ 覆盖难度 1-4 级
+- ✅ 包含三类任务（结构规划、场景续写、爽点注入）
+- ✅ 质量验证报告
+
+---
+
+## 📅 Day 3-4: 课程学习数据准备（2天）
+
+### Day 3：难度分级与排序
+- [ ] **自动难度评估**（3小时）
+  - 实现基于基础模型的难度评估
+  - 对所有样本进行难度分级
+  - 生成难度分布报告
+
+- [ ] **课程学习序列构建**（3小时）
+  - Phase 1: 基础场景（难度1-2）→ 1000条
+  - Phase 2: 单一爽点（难度2-3）→ 800条
+  - Phase 3: 复杂编排（难度3-4）→ 600条
+  - Phase 4: 章节规划（难度4）→ 400条
+
+- [ ] **对比学习样本生成**（2小时）
+  - 为每个好样本生成1-2个坏样本
+  - 标注关键差异
+  - 生成对比分析
+
+### Day 4：数据格式转换与验证
+- [ ] **转换为训练格式**（2小时）
+  - 转换为 Hugging Face datasets 格式
+  - 添加元数据和标签
+  - 划分训练集/验证集（9:1）
+
+- [ ] **最终质量验证**（2小时）
+  - 运行完整验证流程
+  - 生成质量报告
+  - 人工复核关键样本
+
+- [ ] **数据集打包**（2小时）
+  - 按阶段打包数据
+  - 生成数据集说明文档
+  - 准备训练配置文件
+
+**Day 3-4 目标产出**:
+- ✅ 分阶段的课程学习数据集
+- ✅ 对比学习样本库
+- ✅ 完整的质量验证报告
+- ✅ 训练就绪的数据包
+
+---
+
+## 📅 Day 5-7: 模型训练与验证（3天）
+
+### Day 5：基础能力训练（Phase 1-2）
+- [ ] **环境准备**（1小时）
+  - 配置训练环境（GPU、依赖）
+  - 准备基础模型（Qwen-7B 或 Llama-3-8B）
+  - 设置训练监控
+
+- [ ] **Phase 1 训练**（3小时）
+  - 基础场景构建（1000条，难度1-2）
+  - 训练参数：lr=2e-5, batch_size=4, epochs=3
+  - 监控 loss 和验证指标
+
+- [ ] **Phase 2 训练**（4小时）
+  - 单一爽点设计（800条，难度2-3）
+  - 在 Phase 1 checkpoint 基础上继续训练
+  - 验证爽点生成质量
+
+### Day 6：复杂能力训练（Phase 3-4）
+- [ ] **Phase 3 训练**（4小时）
+  - 复杂场景编排（600条，难度3-4）
+  - 重点验证多爽点协调能力
+  - 生成测试样本
+
+- [ ] **Phase 4 训练**（4小时）
+  - 章节级规划（400条，难度4）
+  - 验证全局一致性
+  - 对比学习微调
+
+### Day 7：评估与优化
+- [ ] **全面评估**（3小时）
+  - 结构完整性测试
+  - 爽点有效性测试
+  - 逻辑一致性测试
+  - 创造性评估
+
+- [ ] **问题诊断与优化**（3小时）
+  - 分析失败案例
+  - 调整训练参数
+  - 补充针对性数据
+
+- [ ] **生成测试报告**（2小时）
+  - 对比基础模型 vs 微调模型
+  - 生成示例输出
+  - 撰写训练总结
+
+**Day 5-7 目标产出**:
+- ✅ 完成 Phase 1-4 课程学习训练
+- ✅ 微调后的模型 checkpoint
+- ✅ 全面的评估报告
+- ✅ 问题诊断和优化建议
+
+---
+
+## 🎯 核心成功指标
+
+### 数据质量指标
+- [ ] 结构完整性 >= 0.9
+- [ ] 爽点有效性 >= 0.8
+- [ ] CoT 质量评分 >= 0.85
+- [ ] 对抗性验证通过率 >= 0.9
+
+### 模型性能指标
+- [ ] 基础场景生成准确率 >= 0.85
+- [ ] 爽点设计有效率 >= 0.75
+- [ ] 复杂编排连贯性 >= 0.7
+- [ ] 整体质量提升 >= 40%（vs 基础模型）
+
+---
+
+## 🔧 关键技术点
+
+### 1. 自适应 CoT 生成
+```python
+def generate_cot(difficulty_level, task_context):
+    if difficulty_level <= 2:
+        # 直接输出或简化思考
+        return generate_simple_cot(task_context)
+    elif difficulty_level == 3:
+        # 中等深度思考链
+        return generate_medium_cot(task_context)
+    else:
+        # 完整思考链（决策、设计、创作）
+        return generate_deep_cot(task_context)
+```
+
+### 2. 多层验证系统
+```python
+def validate_sample(sample):
+    # Layer 1: 结构完整性
+    structure_score = verify_structure(sample)
+    
+    # Layer 2: 爽点有效性
+    shuang_score = verify_shuang_point(sample)
+    
+    # Layer 3: CoT 质量
+    cot_score = verify_cot_quality(sample)
+    
+    # Layer 4: 对抗性验证
+    adversarial_pass = adversarial_check(sample)
+    
+    return {
+        'structure': structure_score,
+        'shuang': shuang_score,
+        'cot': cot_score,
+        'adversarial': adversarial_pass,
+        'overall': weighted_average(...)
+    }
+```
+
+### 3. 课程学习策略
+```python
+def curriculum_learning(model, data_by_phase):
+    for phase in [1, 2, 3, 4]:
+        print(f"Training Phase {phase}...")
+        train_data = data_by_phase[phase]
+        
+        # 训练当前阶段
+        model = train(model, train_data)
+        
+        # 验证成功率
+        success_rate = evaluate(model, val_data)
+        
+        # 成功率 >= 80% 才进入下一阶段
+        if success_rate < 0.8:
+            print(f"Phase {phase} not ready, continue training...")
+            continue
+        
+        print(f"Phase {phase} completed!")
+```
+
+---
+
+## 📊 每日检查点
+
+### Day 1 晚上
+- [ ] 至少 1000 条 SFT 数据
+- [ ] 验证系统运行正常
+- [ ] 识别并记录问题
+
+### Day 2 晚上
+- [ ] 完成 3000+ 条数据
+- [ ] 质量报告生成
+- [ ] 数据分布合理
+
+### Day 3 晚上
+- [ ] 难度分级完成
+- [ ] 课程序列构建完成
+- [ ] 对比样本生成
+
+### Day 4 晚上
+- [ ] 数据格式转换完成
+- [ ] 最终验证通过
+- [ ] 训练环境就绪
+
+### Day 5 晚上
+- [ ] Phase 1-2 训练完成
+- [ ] 基础能力验证通过
+- [ ] 爽点生成初见成效
+
+### Day 6 晚上
+- [ ] Phase 3-4 训练完成
+- [ ] 复杂能力初步具备
+- [ ] 测试样本生成
+
+### Day 7 晚上
+- [ ] 全面评估完成
+- [ ] 训练总结撰写
+- [ ] 下一步计划制定
+
+---
+
+## 🚨 风险与应对
+
+### 风险1: 数据生成速度慢
+**应对**: 
+- 提高并发数（--concurrency 10）
+- 使用更快的模型（qwen-turbo）
+- 优先处理核心样本
+
+### 风险2: 数据质量不达标
+**应对**:
+- 降低自动化程度，增加人工复核
+- 调整 prompt 提升生成质量
+- 使用更强的模型（qwen-max）
+
+### 风险3: 训练时间不足
+**应对**:
+- 减少训练轮数（2 epochs）
+- 使用更小的模型（7B）
+- 聚焦核心能力（Phase 1-2）
+
+### 风险4: GPU 资源不足
+**应对**:
+- 使用 LoRA 微调减少显存
+- 降低 batch size
+- 使用梯度累积
+
+---
+
+## 📝 备注
+
+### 优先级排序
+1. **P0（必须完成）**: Day 1-2 数据生成 + Day 5 Phase 1-2 训练
+2. **P1（重要）**: Day 3-4 课程学习准备 + Day 6 Phase 3 训练
+3. **P2（可选）**: Phase 4 训练 + 对比学习微调
+
+### 灵活调整
+- 如果数据生成顺利，可提前进入训练
+- 如果训练效果好，可延长训练时间
+- 根据实际情况动态调整计划
+
+### 文档记录
+- 每天记录进度和问题
+- 保存关键决策和调整
+- 生成每日总结报告
+
+---
+
+**制定时间**: 2026-02-27  
+**执行周期**: 7天  
+**预期成果**: 验证方法论 + 初步可用模型 + 完整训练流程

examples/analyze_story/拆解示例_大奉打更人第1-2章.md

@@ -0,0 +1,1017 @@
+# 《大奉打更人》第1-2章 多层次拆解示例
+
+**样本来源**: 《大奉打更人》第一卷 京察风云  
+**章节范围**: 第1章（牢狱之灾）+ 第2章（妖物作祟）  
+**字数**: 约5000字  
+**拆解目的**: 展示如何将优质网文逆向拆解成AI可学习的思考步骤
+
+---
+
+## 一、宏观层拆解（MICE + Save the Cat）
+
+### 1.1 MICE 线程分析
+
+#### 主线程：Event（税银案）
+```json
+{
+  "thread_type": "Event",
+  "thread_id": "E001_税银案",
+  "opening": {
+    "location": "第1章开头",
+    "trigger": "许七安穿越醒来，发现自己因二叔丢失税银被连坐入狱",
+    "stakes": "两天后流放边陲，生死未卜",
+    "time_pressure": "仅剩两天时间"
+  },
+  "current_status": "进行中",
+  "progress": 0.05,
+  "nested_threads": ["C001_主角成长", "I001_破案推理"],
+  "expected_closure": "找回税银或证明清白"
+}
+```
+
+**CoT（创作思考链）**:
+```
+<think>
+Q: 为什么选择 Event 作为最外层线程？
+A: 网文需要快节奏开局，Event 提供：
+   1. 时间压力（两天倒计时）
+   2. 高风险（流放边陲=死亡）
+   3. 明确目标（找回税银）
+   
+Q: 为什么设置"两天"而不是"七天"或"一天"？
+A: 平衡紧迫感和可操作性：
+   - 一天太短，无法展开推理
+   - 七天太长，紧张感不足
+   - 两天恰好：紧迫但有转机
+   
+Q: 如何确保 Event 线程吸引读者？
+A: 三重钩子设计：
+   1. 穿越设定（读者好奇心）
+   2. 地狱开局（代入感强）
+   3. 破案悬念（智力挑战）
+</think>
+```
+
+#### 嵌套线程：Character（主角成长）
+```json
+{
+  "thread_type": "Character",
+  "thread_id": "C001_主角成长",
+  "opening": {
+    "location": "第1章中段",
+    "initial_state": "绝望、无助、自嘲",
+    "core_flaw": "过度依赖系统（呼唤系统失败）",
+    "growth_trigger": "意识到只能靠自己的专业能力"
+  },
+  "arc_design": {
+    "phase_1": "绝望 → 自救意识觉醒",
+    "phase_2": "专业能力展现（警校背景）",
+    "phase_3": "与堂弟情感连接（人性化）"
+  }
+}
+```
+
+**CoT（设计思考链）**:
+```
+<think>
+Q: 主角的核心优势是什么？
+A: 现代警校毕业 + 推理能力
+   - 这是穿越者的独特优势
+   - 与古代世界形成对比
+   
+Q: 如何避免主角太完美？
+A: 设置多重限制：
+   1. 没有系统（打破读者预期）
+   2. 深陷牢狱（行动受限）
+   3. 时间紧迫（压力巨大）
+   4. 信息缺失（无法查看现场）
+   
+Q: 如何让读者共情？
+A: 三层情感设计：
+   1. 幽默自嘲（"父母双亡的人都不简单"）
+   2. 真实恐惧（对流放的恐惧描写）
+   3. 亲情触动（与堂弟的互动）
+</think>
+```
+
+#### 嵌套线程：Inquiry（破案推理）
+```json
+{
+  "thread_type": "Inquiry",
+  "thread_id": "I001_破案推理",
+  "opening": {
+    "location": "第1章末尾",
+    "central_question": "十五万两税银如何消失？",
+    "clues_introduced": [
+      "怪风",
+      "马匹受惊",
+      "河水爆炸",
+      "只找回1215两"
+    ]
+  },
+  "mystery_layers": {
+    "surface": "税银被劫",
+    "deeper": "妖物作祟？",
+    "core": "真相待揭示"
+  }
+}
+```
+
+### 1.2 Save the Cat 节拍定位
+
+```json
+{
+  "beat_sheet": {
+    "opening_image": {
+      "location": "第1章开头",
+      "content": "许七安在牢狱中醒来",
+      "function": "建立主角困境和世界观",
+      "word_count": 200
+    },
+    "theme_stated": {
+      "location": "第1章中段",
+      "content": "\"我必须想办法自救，我不能就这样狗带\"",
+      "function": "点明主题：自救与成长",
+      "word_count": 50
+    },
+    "catalyst": {
+      "location": "第1章末尾",
+      "content": "许新年带来卷宗的机会",
+      "function": "推动主角行动",
+      "word_count": 300
+    },
+    "debate": {
+      "location": "第1章中段",
+      "content": "主角思考各种自救方案",
+      "function": "展现主角思维过程",
+      "word_count": 500
+    }
+  }
+}
+```
+
+**CoT（节拍设计思考）**:
+```
+<think>
+Q: 为什么在第1章就完成 Opening Image + Theme + Catalyst？
+A: 网文节奏要求：
+   - 前3000字必须抓住读者
+   - 快速建立冲突和目标
+   - 避免冗长铺垫
+   
+Q: 如何平衡节奏和信息量？
+A: 分层递进：
+   1. 开头200字：环境+穿越（吸引注意）
+   2. 中段500字：背景+困境（建立代入）
+   3. 末尾300字：转机+悬念（制造期待）
+</think>
+```
+
+---
+
+## 二、中观层拆解（起承转合 + 爽点钩子）
+
+### 2.1 第1章结构分析
+
+#### 起（开局困境）- 800字
+```json
+{
+  "section": "起",
+  "word_count": 800,
+  "structure": {
+    "hook_1": "穿越醒来（好奇心）",
+    "hook_2": "牢狱之灾（紧张感）",
+    "hook_3": "两天倒计时（紧迫感）"
+  },
+  "emotional_curve": "困惑 → 震惊 → 恐惧",
+  "information_density": "高（世界观+背景+困境）"
+}
+```
+
+**CoT（起承转合设计）**:
+```
+<think>
+Q: "起"部分的核心任务是什么？
+A: 三个必须完成的任务：
+   1. 建立世界观（古代+修炼体系）
+   2. 展现困境（地狱开局）
+   3. 制造悬念（如何自救？）
+   
+Q: 如何在800字内完成这么多任务？
+A: 信息压缩技巧：
+   - 用环境描写暗示世界观
+   - 用记忆融合展现背景
+   - 用内心独白推进情节
+   
+Q: 如何避免信息轰炸？
+A: 情感节奏调节：
+   - 幽默自嘲缓解紧张
+   - 恐惧描写增强代入
+   - 悬念设置维持兴趣
+</think>
+```
+
+#### 承（思考自救）- 1000字
+```json
+{
+  "section": "承",
+  "word_count": 1000,
+  "structure": {
+    "思考1": "越狱？（否定）",
+    "思考2": "求人？（否定）",
+    "思考3": "破案！（肯定）"
+  },
+  "shuang_point": {
+    "type": "智力优势展现",
+    "setup": "主角是警校毕业，有推理能力",
+    "payoff": "想到破案这条路",
+    "intensity": "medium"
+  }
+}
+```
+
+**CoT（爽点设计）**:
+```
+<think>
+Q: 这里的爽点是什么？
+A: 智力优势的初步展现：
+   - 铺垫：警校背景
+   - 对比：古代人不懂刑侦
+   - 爆发：想到破案思路
+   
+Q: 为什么不直接让主角破案？
+A: 制造波折：
+   1. 先给希望（想到破案）
+   2. 再打击（无法查看现场）
+   3. 最后转机（堂弟带来卷宗）
+   - 这种情绪起伏更吸引人
+   
+Q: 如何让"思考过程"不枯燥？
+A: 三个技巧：
+   1. 用内心独白代替叙述
+   2. 加入幽默元素（"狗带"）
+   3. 快速否定无效方案
+</think>
+```
+
+#### 转（堂弟来访）- 1200字
+```json
+{
+  "section": "转",
+  "word_count": 1200,
+  "structure": {
+    "surprise": "堂弟突然来访",
+    "conflict": "堂弟要自尽",
+    "resolution": "主角请求卷宗"
+  },
+  "emotional_layer": {
+    "surface": "兄弟情谊",
+    "deeper": "生死抉择",
+    "core": "人性温暖"
+  },
+  "hooks": [
+    {
+      "type": "情感钩子",
+      "content": "堂弟的决绝与温柔",
+      "resolution_timing": "后续章节"
+    }
+  ]
+}
+```
+
+**CoT（转折设计）**:
+```
+<think>
+Q: 为什么要加入堂弟这个角色？
+A: 多重功能：
+   1. 提供卷宗（推进情节）
+   2. 展现人性（情感深度）
+   3. 制造对比（读书人vs警察）
+   4. 埋下伏笔（堂弟的命运）
+   
+Q: 如何让这段对话不平淡？
+A: 情感层次设计：
+   1. 表面：冷漠（"与汝何干"）
+   2. 中层：关心（送银子保平安）
+   3. 深层：诀别（"活下去"）
+   
+Q: 为什么主角会"鬼使神差"关心堂弟？
+A: 人性化设计：
+   - 原主记忆的情感残留
+   - 穿越者的共情能力
+   - 为后续兄弟情铺垫
+</think>
+```
+
+#### 合（获得卷宗）- 1000字
+```json
+{
+  "section": "合",
+  "word_count": 1000,
+  "structure": {
+    "获得": "堂弟抄录卷宗",
+    "阅读": "主角分析案情",
+    "悬念": "妖物作祟？！"
+  },
+  "chapter_hook": {
+    "type": "悬念钩子",
+    "content": "妖物作祟！",
+    "intensity": "high",
+    "resolution_timing": "下一章"
+  }
+}
+```
+
+### 2.2 爽点密度分析
+
+```json
+{
+  "chapter_1_shuang_points": [
+    {
+      "id": "SP001",
+      "type": "认知爽点",
+      "location": "开头",
+      "content": "\"众所周知，父母双亡的人都不简单\"",
+      "setup": "穿越者身份",
+      "payoff": "自嘲式幽默",
+      "intensity": "low",
+      "function": "缓解紧张，建立读者好感"
+    },
+    {
+      "id": "SP002",
+      "type": "智力爽点",
+      "location": "中段",
+      "content": "想到用破案自救",
+      "setup": "警校背景铺垫",
+      "payoff": "专业能力展现",
+      "intensity": "medium",
+      "function": "建立主角优势"
+    },
+    {
+      "id": "SP003",
+      "type": "情感爽点",
+      "location": "末尾",
+      "content": "堂弟的温情诀别",
+      "setup": "兄弟关系冷淡",
+      "payoff": "\"活下去\"",
+      "intensity": "medium",
+      "function": "人性化主角，增加情感深度"
+    }
+  ],
+  "density": "0.6个/千字",
+  "distribution": "均匀分布，避免疲劳"
+}
+```
+
+**CoT（爽点密度控制）**:
+```
+<think>
+Q: 为什么第1章只有3个爽点？
+A: 开局策略：
+   - 重点是建立世界观和困境
+   - 爽点太多会冲淡紧张感
+   - 留有余地，后续递增
+   
+Q: 如何选择爽点类型？
+A: 多样化原则：
+   1. 认知爽点（幽默）
+   2. 智力爽点（专业）
+   3. 情感爽点（温情）
+   - 避免单一类型疲劳
+   
+Q: 爽点强度如何控制？
+A: 渐进式设计：
+   - 第1章：low-medium
+   - 第2-3章：medium
+   - 第4章：high（智商碾压）
+   - 避免开局就高潮
+</think>
+```
+
+### 2.3 钩子链设计
+
+```json
+{
+  "hook_chain": [
+    {
+      "hook_id": "H001",
+      "type": "悬念钩子",
+      "location": "第1章开头",
+      "content": "为什么会在监狱里？",
+      "resolution": "第1章中段（税银案背景）",
+      "span": "500字"
+    },
+    {
+      "hook_id": "H002",
+      "type": "悬念钩子",
+      "location": "第1章中段",
+      "content": "如何自救？",
+      "resolution": "第1章末尾（破案思路）",
+      "span": "1000字"
+    },
+    {
+      "hook_id": "H003",
+      "type": "悬念钩子",
+      "location": "第1章末尾",
+      "content": "妖物作祟？！",
+      "resolution": "第2章（案情分析）",
+      "span": "跨章节"
+    },
+    {
+      "hook_id": "H004",
+      "type": "情感钩子",
+      "location": "第1章末尾",
+      "content": "堂弟会自尽吗？",
+      "resolution": "后续章节",
+      "span": "长线"
+    }
+  ],
+  "strategy": "短中长结合，层层递进"
+}
+```
+
+**CoT（钩子链设计）**:
+```
+<think>
+Q: 为什么要设计钩子链？
+A: 保持阅读粘性：
+   - 短钩子：维持段落内兴趣
+   - 中钩子：维持章节内兴趣
+   - 长钩子：维持跨章节兴趣
+   
+Q: 如何平衡钩子的制造和满足？
+A: 3:1 原则：
+   - 每满足1个钩子
+   - 同时制造3个新钩子
+   - 保持悬念总量递增
+   
+Q: 什么时候满足钩子？
+A: 时机选择：
+   - 短钩子：500-1000字内
+   - 中钩子：1章内
+   - 长钩子：3-5章
+   - 避免拖太久引起反感
+</think>
+```
+
+---
+
+## 三、微观层拆解（Scene-Sequel + 对话）
+
+### 3.1 Scene-Sequel 结构
+
+#### Scene 1: 穿越醒来
+```json
+{
+  "scene_id": "S001",
+  "type": "Scene",
+  "word_count": 400,
+  "structure": {
+    "goal": "弄清楚自己在哪里",
+    "conflict": "记忆混乱，信息冲击",
+    "disaster": "意识到穿越+入狱+即将流放"
+  },
+  "pov": "第三人称限知（许七安视角）",
+  "pacing": "快节奏（信息密集）"
+}
+```
+
+**原文片段**:
+```
+许七安幽幽醒来，嗅到了空气中潮湿的腐臭味，令人轻微的不适，胃酸翻涌。
+这扑面而来的臭味是怎么回事，家里的二哈又跑床上拉屎来了……
+睁开眼，看了下周遭，许七安懵了一下。
+石块垒砌的墙壁，三个碗口大的方块窗……
+我在哪？
+许七安在怀疑人生般的迷茫中沉思片刻，然后他真的怀疑人生了。
+我穿越了……
+```
+
+**CoT（场景构建思考）**:
+```
+<think>
+Q: 如何让穿越场景不俗套？
+A: 三个差异化设计：
+   1. 感官先行（臭味）而非视觉
+   2. 幽默化处理（二哈拉屎）
+   3. 渐进式认知（困惑→震惊）
+   
+Q: 为什么用"二哈"这个梗？
+A: 多重功能：
+   1. 幽默感（缓解紧张）
+   2. 现代感（强化穿越者身份）
+   3. 生活化（拉近读者距离）
+   
+Q: 如何控制信息释放节奏？
+A: 层层递进：
+   1. 环境（监狱）
+   2. 身份（穿越）
+   3. 困境（流放）
+   - 每层200字，避免信息轰炸
+</think>
+```
+
+#### Sequel 1: 情绪反应与决策
+```json
+{
+  "sequel_id": "SQ001",
+  "type": "Sequel",
+  "word_count": 600,
+  "structure": {
+    "reaction": "恐惧、绝望（\"太可怕了！\"）",
+    "dilemma": "越狱？求人？破案？",
+    "decision": "尝试破案自救"
+  },
+  "internal_monologue": "大量内心独白展现思考过程",
+  "emotional_arc": "恐惧 → 焦虑 → 希望 → 失望 → 再希望"
+}
+```
+
+**原文片段**:
+```
+"开局就是地狱模式啊……"许七安脊背发凉，心跟着凉了半截。
+这个世界处在封建王朝统治的状态，没有人权的，边陲是什么地方？
+荒凉，气候恶劣，大部分被发配边境的犯人，都活不过十年……
+太可怕，太可怕了！
+"我必须想办法自救，我不能就这样狗带。"
+```
+
+**CoT（Sequel 设计思考）**:
+```
+<think>
+Q: Sequel 的核心功能是什么？
+A: 三个层次：
+   1. 情绪释放（让读者共情）
+   2. 思考过程（展现智力）
+   3. 决策推进（推动情节）
+   
+Q: 如何让内心独白不枯燥？
+A: 五个技巧：
+   1. 口语化（"狗带"）
+   2. 具象化（描述边陲环境）
+   3. 情绪化（"太可怕"重复）
+   4. 逻辑化（分析各种方案）
+   5. 节奏化（短句+长句交替）
+   
+Q: 为什么要展现"失败的思考"？
+A: 真实感塑造：
+   - 越狱（否定）
+   - 求人（否定）
+   - 破案（肯定）
+   - 展现思维过程，而非直接给答案
+</think>
+```
+
+#### Scene 2: 堂弟来访
+```json
+{
+  "scene_id": "S002",
+  "type": "Scene",
+  "word_count": 800,
+  "structure": {
+    "goal": "从堂弟处获得信息或帮助",
+    "conflict": "堂弟冷漠 vs 主角关心",
+    "disaster": "堂弟要自尽"
+  },
+  "dialogue_ratio": 0.6,
+  "subtext": "表面冷漠，实则关心"
+}
+```
+
+**对话分析**:
+```json
+{
+  "dialogue_example": {
+    "line_1": {
+      "speaker": "许新年",
+      "text": "押送你去边陲的士卒收了我三百两，这是我们家仅剩的银子了，你安心的去，途中不会有意外的。",
+      "surface_meaning": "告知安排",
+      "subtext": "我在乎你的安全",
+      "character_trait": "外冷内热",
+      "function": "建立角色性格"
+    },
+    "line_2": {
+      "speaker": "许七安",
+      "text": "那你呢？",
+      "surface_meaning": "询问堂弟",
+      "subtext": "我也关心你",
+      "character_trait": "共情能力强",
+      "function": "展现主角人性"
+    },
+    "line_3": {
+      "speaker": "许新年",
+      "text": "活下去。",
+      "surface_meaning": "简单嘱咐",
+      "subtext": "这是诀别",
+      "character_trait": "决绝而温柔",
+      "function": "情感高潮"
+    }
+  }
+}
+```
+
+**CoT（对话设计思考）**:
+```
+<think>
+Q: 如何让对话有层次？
+A: 三层设计：
+   1. 表层：信息交换
+   2. 中层：性格展现
+   3. 深层：情感暗流
+   
+Q: 为什么许新年说话"不耐烦"？
+A: 角色一致性：
+   - 原设定：嘴强王者
+   - 当前状态：压力巨大
+   - 防御机制：用冷漠掩饰关心
+   
+Q: "活下去"为什么有力量？
+A: 极简主义：
+   - 只有三个字
+   - 但包含万千情感
+   - 对比前面的冷漠，反差巨大
+</think>
+```
+
+### 3.2 叙事视角与节奏
+
+```json
+{
+  "narrative_techniques": {
+    "pov": {
+      "type": "第三人称限知",
+      "focus": "许七安视角",
+      "advantage": "既能展现内心，又保持客观"
+    },
+    "pacing": {
+      "fast_sections": [
+        "穿越醒来（感官冲击）",
+        "案情介绍（信息密集）"
+      ],
+      "slow_sections": [
+        "思考过程（内心独白）",
+        "兄弟对话（情感深度）"
+      ],
+      "rhythm": "快慢交替，张弛有度"
+    },
+    "description_ratio": {
+      "action": 0.3,
+      "dialogue": 0.4,
+      "internal_monologue": 0.2,
+      "description": 0.1
+    }
+  }
+}
+```
+
+**CoT（节奏控制思考）**:
+```
+<think>
+Q: 如何控制叙事节奏？
+A: 三个层次：
+   1. 句子层：长短句交替
+   2. 段落层：快慢节奏交替
+   3. 章节层：紧张-缓和-紧张
+   
+Q: 为什么内心独白占比20%？
+A: 平衡考虑：
+   - 太多：拖沓、枯燥
+   - 太少：缺乏深度
+   - 20%：展现思考，不影响节奏
+   
+Q: 如何让描写不拖沓？
+A: 功能化原则：
+   - 每个描写必须有功能
+   - 环境描写→暗示困境
+   - 动作描写→推进情节
+   - 避免纯粹的景物描写
+</think>
+```
+
+---
+
+## 四、AI 可学习的训练数据示例
+
+### 4.1 Task 1: 结构规划（Structure Planning）
+
+```json
+{
+  "task_type": "structure_planning",
+  "difficulty_level": 3,
+  "metadata": {
+    "source_file": "大奉打更人",
+    "chapter": "第1章",
+    "position_percent": 2.0,
+    "beat_id": "beat_001"
+  },
+  "input": {
+    "story_state": {
+      "mice_threads": {
+        "E001": {"status": "opening", "progress": 0.0}
+      },
+      "last_disaster": null,
+      "last_decision": null,
+      "current_position": "故事开始"
+    },
+    "context": "",
+    "planning_goal": "设计开局场景，建立主角困境和世界观"
+  },
+  "output": {
+    "cot": {
+      "depth": "medium",
+      "steps": [
+        {
+          "step": 1,
+          "type": "分析",
+          "content": "网文开局需要快速抓住读者，必须在前500字建立冲突",
+          "reasoning": "读者耐心有限，慢热开局会流失"
+        },
+        {
+          "step": 2,
+          "type": "选择",
+          "content": "选择穿越+牢狱的组合开局",
+          "reasoning": "穿越（好奇）+ 牢狱（紧张）= 双重吸引力",
+          "alternatives_considered": [
+            "平淡开局（太慢）",
+            "战斗开局（缺乏铺垫）"
+          ]
+        },
+        {
+          "step": 3,
+          "type": "设计",
+          "content": "用感官描写（臭味）开场，而非视觉",
+          "reasoning": "差异化，避免俗套"
+        },
+        {
+          "step": 4,
+          "type": "节奏",
+          "content": "400字完成场景，600字完成情绪反应",
+          "reasoning": "快节奏建立困境，留出空间展开思考"
+        }
+      ]
+    },
+    "structure_plan": {
+      "scene": {
+        "goal": "弄清楚自己在哪里",
+        "conflict_type": "信息冲击",
+        "disaster": "意识到穿越+入狱+即将流放",
+        "pacing": "快节奏"
+      },
+      "sequel": {
+        "reaction": "恐惧、绝望",
+        "dilemma": "如何自救？",
+        "decision": "尝试破案"
+      },
+      "hooks": [
+        {
+          "type": "悬念钩子",
+          "content": "为什么会在监狱里？",
+          "resolution_timing": "500字内"
+        }
+      ],
+      "shuang_point": {
+        "type": "认知爽点",
+        "intensity": "low",
+        "content": "幽默自嘲（父母双亡梗）"
+      }
+    }
+  }
+}
+```
+
+### 4.2 Task 2: 场景续写（Scene Continuation）
+
+```json
+{
+  "task_type": "scene_continuation",
+  "difficulty_level": 2,
+  "metadata": {
+    "source_file": "大奉打更人",
+    "chapter": "第1章",
+    "beat_id": "beat_001"
+  },
+  "input": {
+    "context": "",
+    "structure_plan": {
+      "scene": {
+        "goal": "弄清楚自己在哪里",
+        "conflict_type": "信息冲击",
+        "disaster": "意识到穿越+入狱+即将流放",
+        "pacing": "快节奏"
+      }
+    }
+  },
+  "output": {
+    "cot": {
+      "steps": [
+        {
+          "step": 1,
+          "type": "开场选择",
+          "content": "用感官描写（臭味）开场，制造不适感",
+          "reasoning": "感官冲击比视觉描写更有代入感"
+        },
+        {
+          "step": 2,
+          "type": "幽默注入",
+          "content": "加入'二哈拉屎'的现代梗",
+          "reasoning": "缓解紧张，建立读者好感"
+        },
+        {
+          "step": 3,
+          "type": "信息递进",
+          "content": "环境→身份→困境，层层递进",
+          "reasoning": "避免信息轰炸，保持节奏"
+        }
+      ]
+    },
+    "continuation": "许七安幽幽醒来，嗅到了空气中潮湿的腐臭味，令人轻微的不适，胃酸翻涌。\n这扑面而来的臭味是怎么回事，家里的二哈又跑床上拉屎来了……根据熏人程度，怕不是在我头顶拉的……\n许七安家里养了一条狗，品种哈士奇，俗称二哈。\n北漂了十年，孤孤单单的，这人啊，寂寞久了，难免会想养条狗里慰藉和消遣……不是肉体上。\n睁开眼，看了下周遭，许七安懵了一下。\n石块垒砌的墙壁，三个碗口大的方块窗，他躺在冰凉的破烂草席上，阳光透过方块窗照射在他胸口，光束中尘糜浮动。\n我在哪？\n许七安在怀疑人生般的迷茫中沉思片刻，然后他真的怀疑人生了。\n我穿越了……"
+  }
+}
+```
+
+### 4.3 Task 3: 爽点注入（Shuang Point Injection）
+
+```json
+{
+  "task_type": "shuang_injection",
+  "difficulty_level": 3,
+  "metadata": {
+    "source_file": "大奉打更人",
+    "chapter": "第1章",
+    "beat_id": "beat_002"
+  },
+  "input": {
+    "plain_draft": "许七安想到自己是警校毕业，有推理能力，也许可以通过破案来自救。他决定向堂弟要卷宗。",
+    "shuang_type": "智力优势",
+    "intensity": "medium"
+  },
+  "output": {
+    "cot": {
+      "steps": [
+        {
+          "step": 1,
+          "type": "分析草稿",
+          "content": "草稿只有结论，缺少思考过程和情绪起伏",
+          "problem": "平淡，无爽感"
+        },
+        {
+          "step": 2,
+          "type": "爽点设计",
+          "content": "设计三层递进：希望→失望→再希望",
+          "reasoning": "情绪波动产生爽感"
+        },
+        {
+          "step": 3,
+          "type": "铺垫增强",
+          "content": "先展现专业背景，再展现思考过程",
+          "reasoning": "铺垫越充分，爽点越强"
+        },
+        {
+          "step": 4,
+          "type": "对比设计",
+          "content": "现代刑侦 vs 古代条件",
+          "reasoning": "对比产生优势感"
+        }
+      ]
+    },
+    "enhanced_version": "根据大奉律法，将功补过，便可免除死罪！\n除非找回银子……\n许七安的眼睛猛的亮起，像极了濒临溺毙的人抓住了救命稻草。\n他是正儿八经的警校毕业，理论知识丰富，逻辑清晰，推理能力极强，又阅读过无数的案例。\n或许可以试着从破案这方面入手，追回银子，戴罪立功。\n但随后，他眼里的光芒黯淡。\n想要破案，首先要看卷宗，明白案件的详细经过。之后才是调查、破案。\n如今他深陷大牢，叫天天不应叫地地不灵，两天后就送去边陲了！\n无解！",
+    "modifications": [
+      {
+        "type": "添加铺垫",
+        "content": "详细描述警校背景和专业能力",
+        "effect": "建立智力优势"
+      },
+      {
+        "type": "情绪起伏",
+        "content": "希望（想到破案）→ 失望（无法实施）",
+        "effect": "增强代入感"
+      },
+      {
+        "type": "具象化",
+        "content": "\"像极了濒临溺毙的人抓住了救命稻草\"",
+        "effect": "增强画面感"
+      }
+    ]
+  }
+}
+```
+
+### 4.4 对比学习样本（好 vs 坏）
+
+```json
+{
+  "task_type": "contrastive_learning",
+  "comparison_aspect": "开局场景设计",
+  "good_example": {
+    "text": "许七安幽幽醒来，嗅到了空气中潮湿的腐臭味，令人轻微的不适，胃酸翻涌。\n这扑面而来的臭味是怎么回事，家里的二哈又跑床上拉屎来了……",
+    "why_good": [
+      "感官先行，代入感强",
+      "幽默化处理，缓解紧张",
+      "现代梗，强化穿越者身份",
+      "节奏快，信息密集"
+    ],
+    "quality_score": 9.2
+  },
+  "bad_example": {
+    "text": "许七安醒来，发现自己在一个陌生的地方。这是一间牢房，墙壁是石头砌的，有几个小窗户。他想起来了，自己穿越了。",
+    "why_bad": [
+      "平铺直叙，缺乏吸引力",
+      "没有感官细节",
+      "信息堆砌，缺乏节奏",
+      "没有情绪渲染"
+    ],
+    "quality_score": 3.5
+  },
+  "key_differences": [
+    {
+      "aspect": "开场方式",
+      "good": "感官描写（臭味）",
+      "bad": "视觉描写（环境）",
+      "impact": "代入感差异70%"
+    },
+    {
+      "aspect": "情绪处理",
+      "good": "幽默自嘲",
+      "bad": "平淡叙述",
+      "impact": "可读性差异60%"
+    },
+    {
+      "aspect": "信息密度",
+      "good": "高密度但有节奏",
+      "bad": "低密度且平淡",
+      "impact": "吸引力差异80%"
+    }
+  ]
+}
+```
+
+---
+
+## 五、方法论验证与总结
+
+### 5.1 v2.0 方法论应用验证
+
+#### ✅ 自适应 CoT 提取
+- **难度评估**: 第1章开局 = 难度3（规划级）
+- **CoT 深度**: Medium（3-4步思考链）
+- **验证结果**: CoT 清晰展现了作者的设计思路
+
+#### ✅ 多层验证
+- **结构完整性**: Scene-Sequel 结构完整 ✓
+- **爽点有效性**: 3个爽点，密度合理，强度递进 ✓
+- **逻辑一致性**: 角色行为符合设定，时间线清晰 ✓
+- **CoT 质量**: 思考步骤清晰，考虑了替代方案 ✓
+
+#### ✅ 结构化与创造性平衡
+- **严格约束**: MICE 线程嵌套正确 ✓
+- **中等约束**: 爽点密度 0.6/千字，在合理范围 ✓
+- **弱约束**: 对话风格独特（"与汝何干"）✓
+- **无约束**: 创新点（感官开场、二哈梗）✓
+
+### 5.2 关键发现
+
+1. **网文开局的黄金法则**:
+   - 前500字必须建立冲突
+   - 感官描写 > 视觉描写
+   - 幽默化处理缓解紧张
+   - 信息密集但有节奏
+
+2. **爽点设计的核心**:
+   - 铺垫 > 爆发 > 反应
+   - 情绪起伏 > 平铺直叙
+   - 对比 > 单一展现
+   - 多样化 > 单一类型
+
+3. **钩子链的秘密**:
+   - 短中长结合
+   - 3:1 制造满足比
+   - 跨章节悬念维持粘性
+
+### 5.3 AI 训练建议
+
+#### Phase 1: 基础场景（难度1-2）
+- 重点：Scene-Sequel 基础结构
+- 数据量：1000条
+- 训练目标：结构完整性 >= 0.9
+
+#### Phase 2: 爽点设计（难度2-3）
+- 重点：铺垫-爆发-反应
+- 数据量：800条
+- 训练目标：爽点有效性 >= 0.8
+
+#### Phase 3: 复杂编排（难度3-4）
+- 重点：多爽点协调、钩子链
+- 数据量：600条
+- 训练目标：节奏控制 >= 0.75
+
+#### Phase 4: 章节规划（难度4）
+- 重点：MICE 线程管理
+- 数据量：400条
+- 训练目标：全局一致性 >= 0.8
+
+---
+
+**拆解完成时间**: 2026-02-27  
+**拆解字数**: 约15000字  
+**训练数据产出**: 4条高质量样本（结构规划、场景续写、爽点注入、对比学习）  
+**方法论验证**: v2.0 方法论完全适用 ✓

examples/how/README.md

@@ -0,0 +1,12 @@
+
+## 运行方法
+1. 输入：将原始帖子内容放到 `examples/how/input/` 文件夹下
+2. 运行：在项目根目录下运行 `python examples/how/run.py`
+3. 输出：在 `examples/how/output` 中查看
+
+## prompt调试
+- 主Agent（调度与评估）：修改 `examples/how/production.prompt`
+    - 原始输入/参考资料等等都可以在这里输入文件路径
+    - 可以在这里指定各类输出的保存路径
+- 制作表解构Agent：修改 `examples/how/skills/deconstruct.md` , 这部分内容会在主Agent创建子Agent时作为子Agent的system prompt
+- 还原Agent：修改 `examples/how/skills/construct.md` , 这部分内容会在主Agent创建子Agent时作为子Agent的system prompt

examples/how/analyze_images.py

@@ -0,0 +1,46 @@
+import warnings
+warnings.filterwarnings('ignore')
+from PIL import Image
+import os, json
+
+os.makedirs('examples/how/features', exist_ok=True)
+
+results = []
+for i in range(1, 10):
+    path = f'examples/how/input_local_archive/{i}.jpeg'
+    img = Image.open(path)
+    img_rgb = img.convert('RGB')
+    
+    # Save thumbnail
+    thumb = img_rgb.resize((360, 480))
+    thumb.save(f'examples/how/features/thumb_{i}.jpg', 'JPEG', quality=85)
+    
+    # Get color info
+    small = img_rgb.resize((50, 50))
+    pixels = list(small.getdata())
+    r = sum(p[0] for p in pixels) // len(pixels)
+    g = sum(p[1] for p in pixels) // len(pixels)
+    b = sum(p[2] for p in pixels) // len(pixels)
+    
+    # Get quadrant colors (top/bottom/left/right)
+    w, h = img_rgb.size
+    top = img_rgb.crop((0, 0, w, h//3)).resize((10,10))
+    mid = img_rgb.crop((0, h//3, w, 2*h//3)).resize((10,10))
+    bot = img_rgb.crop((0, 2*h//3, w, h)).resize((10,10))
+    
+    def avg_color(region):
+        px = list(region.getdata())
+        return (sum(p[0] for p in px)//len(px), sum(p[1] for p in px)//len(px), sum(p[2] for p in px)//len(px))
+    
+    results.append({
+        'index': i,
+        'size': img.size,
+        'format': img.format,
+        'avg_rgb': (r, g, b),
+        'top_rgb': avg_color(top),
+        'mid_rgb': avg_color(mid),
+        'bot_rgb': avg_color(bot),
+    })
+    print(f'{i}.jpeg: size={img.size}, avg=({r},{g},{b}), top={avg_color(top)}, mid={avg_color(mid)}, bot={avg_color(bot)}')
+
+print('\nDone! Thumbnails saved to examples/how/features/')

examples/how/encode_images.py

@@ -0,0 +1,12 @@
+import base64, json
+
+images = {}
+for i in range(1, 10):
+    path = f'examples/how/input_local_archive/{i}.jpeg'
+    with open(path, 'rb') as f:
+        data = base64.b64encode(f.read()).decode()
+    images[str(i)] = data
+
+with open('examples/how/features/images_b64.json', 'w') as f:
+    json.dump(images, f)
+print('done')

examples/how/input/1_invariant_features.json

@@ -0,0 +1,30 @@
+{
+  "构图精确描述": {
+    "人物在画面中的位置比例": "人物位于画面右侧，占据画面垂直方向约2/3的高度，水平方向约1/3的宽度，身体大部分在画面内，但头部和左臂部分被裁切，形成一种开放式构图。",
+    "画架的位置": "画架位于画面左侧偏中，占据画面垂直方向约1/2的高度，水平方向约1/4的宽度，其底部支撑腿延伸至画面左下角。",
+    "画中画的位置关系": "“画中画”位于画架上，正对着人物，其左侧边缘与画架左侧边缘大致对齐，右侧边缘靠近人物的右臂，占据画面中心偏左的位置。"
+  },
+  "色彩分布": {
+    "主色调": "绿色（草地和背景树木），白色（人物服装和画中画中的人物）。",
+    "辅助色": "蓝色和紫色（画中画中的花朵），棕色（人物头发、画架），以及调色板上丰富的颜料色彩。",
+    "色温感受": "整体色温偏冷，绿色背景营造出清新、自然的氛围，白色服装和画中画的冷色调花朵进一步加强了这种感受。"
+  },
+  "光线方向和质感": {
+    "光线方向": "光线从画面左上方或人物的左侧照射过来，在人物的右侧和画架的右侧形成轻微的阴影，画中画的左侧也略亮于右侧。",
+    "质感": "光线柔和，没有明显的硬光或强烈阴影，呈现出一种自然光照的效果，可能是在户外阴天或傍晚时分拍摄。"
+  },
+  "人物姿态": {
+    "手持画笔的姿势": "右手握持画笔，笔尖朝向画中画，正在进行绘画动作，姿势专注而优雅。",
+    "身体朝向": "身体略微向左前方倾斜，背对镜头，头部微微转向画中画，呈现出侧身专注绘画的姿态。",
+    "重心": "重心似乎落在双腿上，身体姿态稳定，没有明显的倾斜或不平衡感。"
+  },
+  "画面中的\"画中画\"内容和风格": {
+    "内容": "画中画描绘了一个穿着白色裙子的女性背影，置身于一片蓝色和紫色调的花海或草地中，背景有绿色植物。",
+    "风格": "画风偏向印象派或后印象派，笔触粗犷，色彩鲜明，注重光影和色彩的表达，而非细节的精确描绘，具有一定的艺术感和浪漫气息。"
+  },
+  "景深处理": {
+    "哪些在焦内": "人物（尤其是头发、手臂和服装）、画架、画中画以及调色板清晰可见，处于景深范围内。",
+    "哪些虚化": "背景的绿色树木和草地被明显虚化，呈现出柔和的模糊效果，突出了前景的人物和绘画主题。"
+  },
+  "整体画面的情绪氛围是如何通过制作手段营造的": "整体画面营造出一种宁静、专注、艺术和自然的氛围。通过以下制作手段实现：\n1. **构图**：开放式构图和人物侧身背对镜头，增加了画面的故事感和神秘感，引导观众关注人物的创作过程。\n2. **色彩**：主色调的绿色和白色带来清新、纯洁的感受，画中画的冷色调花朵增添了艺术气息，整体色彩和谐统一。\n3. **光线**：柔和的自然光线使得画面温馨舒适，没有强烈的视觉冲击，营造出平和的氛围。\n4. **景深**：浅景深处理有效地将观众的注意力集中在人物和她的创作上，虚化的背景则提供了自然的户外环境，增强了画面的艺术感和沉浸感。\n5. **人物姿态**：人物专注绘画的姿态，展现了对艺术的热爱和投入，传递出一种平静而富有创造力的情绪。\n6. **画中画**：画中画的印象派风格和内容，暗示了人物的艺术追求和作品的浪漫主题，进一步烘托了艺术创作的氛围。"
+}

examples/how/input/3_invariant_features.json

@@ -0,0 +1,23 @@
+{
+  "构图精确描述": {
+    "人物在画面中的位置": "人物位于画面右下角，占据了画面约四分之一的区域，背对镜头，面向画架。",
+    "画架的位置": "画架位于画面中心偏右，与人物形成一个斜向的视觉引导线，画板上的画作是构图的视觉焦点之一。",
+    "背景元素分布": "背景由大片绿色草地和茂密的树木组成。草地占据了画面下方约三分之一的区域，树木和天空占据了上方约三分之二的区域。左侧和右侧的树木形成了一个自然的框架，中间部分透出明亮的天空和远处的建筑轮廓（模糊可见）。"
+  },
+  "逆光/侧逆光的具体效果": {
+    "光晕": "画面左上角和背景树木的边缘有明显的光晕效果，光线穿透树叶，形成柔和的金色光斑，营造出温暖、梦幻的氛围。",
+    "轮廓光": "人物的头发和右侧手臂（如果可见）边缘有轻微的轮廓光，使其从背景中分离出来，增加立体感。画架的木质结构也因逆光而呈现出清晰的轮廓。",
+    "草地光感": "草地整体受光均匀，但由于逆光，草地的颜色显得更加饱和，部分区域呈现出被阳光照亮的金绿色，增强了画面的层次感和生动性。"
+  },
+  "人物姿态": {
+    "跪坐的具体姿势": "人物呈跪坐姿势，双膝着地，身体微微前倾，双手似乎正在操作画板或调色板。身体重心稳定，姿态放松。",
+    "身体朝向": "人物身体完全背对镜头，头部略微向右侧转动，但仍主要面向画架，专注于绘画。"
+  },
+  "色彩分布": {
+    "绿色草地": "绿色草地占据了画面下方大部分区域，颜色鲜亮，饱和度较高，是画面中最主要的色彩之一。",
+    "白色人物": "人物身着白色长裙，在绿色的背景中显得尤为突出，形成鲜明的对比，白色也反射了周围环境的光线，显得纯洁而明亮。",
+    "金色光晕": "画面左上角和背景树木边缘的金色光晕，为画面增添了温暖和柔和的色调，与绿色和白色共同构成了画面的主色调，比例上金色光晕虽然面积不大，但视觉冲击力强。"
+  },
+  "景深处理": "画面采用了浅景深处理。前景的草地和人物、画架清晰锐利，是画面的焦点。背景的树木和远处的建筑则被虚化，呈现出柔和的模糊效果，有效地突出了主体，并营造出一种空间感和层次感。",
+  "整体画面的情绪氛围是如何通过制作手段营造的": "整体画面营造出一种宁静、专注、艺术且充满诗意的氛围。这主要通过以下制作手段实现：\n1. **构图**：人物背对镜头，将观众的视线引向画架和画作，强调了绘画这一行为的专注性。\n2. **光线**：逆光/侧逆光的使用，特别是柔和的金色光晕，为画面增添了温暖、梦幻和浪漫的色彩，营造出傍晚或清晨的静谧感。\n3. **色彩**：绿色草地、白色长裙和金色光晕的搭配，色彩清新、和谐，给人以自然、纯洁、舒适的视觉感受。\n4. **景深**：浅景深将焦点集中在人物和画作上，虚化的背景避免了杂乱，使画面更加纯粹，增强了艺术感和沉浸感。\n5. **人物姿态**：跪坐的姿态显得谦逊而投入，进一步强化了专注和沉思的情绪。"
+}

examples/how/input/7_invariant_features.json

@@ -0,0 +1,25 @@
+{
+  "构图精确描述": {
+    "人物脸部位置": "人物脸部位于画面右侧偏上，占据了画面右侧约三分之一的区域，呈侧面轮廓，视线朝向画面左侧。",
+    "玫瑰花位置": "玫瑰花位于画面左侧偏下，花朵部分与人物鼻尖和嘴唇大致处于同一水平线，花茎和叶子延伸至画面左下角，与人物手部相接。"
+  },
+  "景深处理": {
+    "焦点": "焦点清晰地落在人物的脸部（特别是侧脸轮廓、眼睛和嘴唇）以及她手中的白色玫瑰花上。",
+    "背景虚化程度": "背景虚化程度非常高，呈现出柔和的模糊效果，将背景的绿色草地处理成大面积的色块，有效地突出了前景的人物和玫瑰花。"
+  },
+  "光线方向和质感": {
+    "侧光具体效果": "光线从人物的右前方（或略偏上方）射入，形成明显的侧光效果。人物的鼻梁、额头、脸颊和下巴边缘被光线勾勒出清晰的轮廓，呈现出明亮的线条。头发的边缘也因侧光而显得有光泽。玫瑰花的右侧花瓣也受到光照，显得明亮。整体光线质感柔和，没有出现硬朗的阴影，表明可能使用了柔光设备或在柔和的自然光下拍摄。"
+  },
+  "人物面部特征的制作呈现": {
+    "皮肤质感": "皮肤质感细腻，呈现出自然的光泽感，没有明显的瑕疵或毛孔，整体显得光滑饱满。脸颊和鼻尖处有轻微的高光，增加了立体感。",
+    "妆容风格": "妆容风格自然清淡，强调裸妆感。眉毛自然，眼妆部分不明显，可能只做了简单的睫毛处理。唇部涂有水润的红色唇彩，为整体清淡的妆容增添了一抹亮色和活力。"
+  },
+  "玫瑰花的视觉处理": {
+    "清晰度": "玫瑰花的花朵部分清晰可见，花瓣的层次和纹理细节都得到了很好的呈现。",
+    "色彩": "玫瑰花呈现纯净的白色，与人物的白色上衣相呼应，与背景的绿色形成对比，色彩饱和度适中，显得清新雅致。"
+  },
+  "整体色调和情绪氛围": {
+    "整体色调": "整体色调偏向清新、明亮和柔和。以人物的肤色、白色衣物和玫瑰花为亮色调，背景的绿色草地为中性偏冷的绿色调，唇部的红色为点缀色。色彩搭配和谐，视觉上舒适。",
+    "情绪氛围": "画面营造出一种宁静、温柔、浪漫和愉悦的情绪氛围。人物闭眼轻嗅玫瑰花的动作，传达出一种沉浸于美好瞬间的享受和满足感。侧光和柔和的景深处理进一步增强了这种梦幻和唯美的感觉。"
+  }
+}

examples/how/input/set_invariant_features.json

@@ -0,0 +1,54 @@
+{
+  "整体视觉风格和色调": "这组图片呈现出清新、自然、艺术的风格。色调以绿色（草地、树木）和白色（人物服装、玫瑰花）为主，辅以画板上的丰富色彩，整体明亮柔和，营造出一种宁静而富有生机的氛围。",
+  "每张图的主要元素": {
+    "图1": {
+      "人物": "一位长发女性，身穿白色长裙，侧身面向画架，手持画笔和调色板，正在作画。",
+      "场景": "户外草地，背景有绿树。",
+      "道具": "木质画架、画布（上面有未完成的画作，画中人物与现实人物相似）、调色板、画笔、一朵白色玫瑰花（插在画架旁）。",
+      "文字": "无"
+    },
+    "图2": {
+      "人物": "同一位长发女性，身穿白色长裙，背对镜头，跪坐在草地上，面向画架。",
+      "场景": "户外草地，背景有绿树和远处模糊的建筑轮廓。",
+      "道具": "木质画架、画布（上面有未完成的画作）、一个白色桶状容器（可能装有画材）。",
+      "文字": "无"
+    },
+    "图3": {
+      "人物": "同一位长发女性的侧脸特写，闭着眼睛，面带微笑，正在闻一朵白色玫瑰花。",
+      "场景": "户外草地（背景模糊）。",
+      "道具": "一朵白色玫瑰花、耳环、项链。",
+      "文字": "无"
+    }
+  },
+  "构图方式和元素关系": {
+    "图1": "采用斜向构图，人物和画架形成一个对角线，引导视线从左下到右上。人物与画作形成“画中画”的趣味关系，现实中的人物正在描绘画中的自己，增加了艺术性和故事感。白色玫瑰花作为点缀，与人物的白色裙子相呼应。",
+    "图2": "采用中心构图，人物和画架位于画面中央，背景的树木形成自然的框架。人物背对镜头，强调了其专注于创作的状态，也留给观众想象空间。人物跪坐的姿态显得谦逊而投入。",
+    "图3": "采用特写构图，聚焦于人物的侧脸和手中的玫瑰花。人物的脸部占据画面大部分，背景虚化，突出主体。玫瑰花靠近人物的鼻子，强调了“闻花”的动作和感受，营造出一种宁静美好的氛围。"
+  },
+  "光线处理": {
+    "图1": "光线明亮柔和，似乎是自然光，没有明显的阴影，整体曝光均匀。光线从侧面或前方照射，使人物和画作细节清晰。",
+    "图2": "光线呈现出逆光或侧逆光的效果，背景的树木边缘有金色的光晕，草地也显得更加明亮。这种光线处理营造出温暖、梦幻的氛围，尤其是在日落时分或清晨的光线效果。",
+    "图3": "光线柔和，从侧面照射，使人物的脸部轮廓和玫瑰花的细节清晰可见。没有强烈的对比，整体光线均匀，突出了人物的柔美和宁静。"
+  },
+  "多图之间的固定要素和变化要素": {
+    "固定要素": [
+      "同一位长发女性（身穿白色长裙）",
+      "户外草地场景",
+      "木质画架和画布（画作内容相似）",
+      "白色玫瑰花（在不同图中出现或作为道具）",
+      "清新自然的整体风格"
+    ],
+    "变化要素": [
+      "人物的姿态和动作（作画、跪坐、闻花）",
+      "拍摄角度和景别（侧身全身、背影全身、侧脸特写）",
+      "光线效果（均匀光、逆光/侧逆光）",
+      "画面焦点和强调的主题（作画过程、专注状态、享受自然）"
+    ]
+  },
+  "特殊的视觉处理手法": [
+    "\"画中画\"效果：图1中人物正在描绘画中的自己，这种艺术手法增加了画面的层次感和趣味性。",
+    "景深运用：所有图片都使用了浅景深，虚化背景，突出主体人物和道具，使画面更具电影感和艺术感。",
+    "色彩搭配：白色服装与绿色草地形成鲜明对比，同时白色玫瑰花与服装相呼应，整体色彩和谐统一。",
+    "叙事性：三张图片通过不同角度和动作，共同讲述了一个关于艺术创作、享受自然和自我沉浸的小故事，具有一定的连贯性和叙事性。"
+  ]
+}

examples/how/input/《秋日际遇》写生油画.json

@@ -0,0 +1,9 @@
+{
+  "images": [
+    "examples/how/input/1.jpeg",
+    "examples/how/input/3.jpeg",
+    "examples/how/input/7.jpeg"
+  ],
+  "body_text": "听闻秋日是倒放的春天\n于是我心中有一座秋日的花园\n栽种着一簇簇淡却温暖的花\n风沿着远边的山吹来\n热情的阳光里秋风微凉\n与颜料一起酝酿出的画面\n白裙是一抹无暇\n迎着光绘画出\n那片在我心上开满\n限定的浪漫\n被画架支起\n绿草坪还驻留了匆匆而过的热闹\n再添一笔白\n为我画一枝玫瑰的奇遇\n———@万淮 #草地拍照[话题]##画画[话题]#",
+  "title": "《秋日际遇》写生油画"
+}

examples/how/load_imgs.py

@@ -0,0 +1,9 @@
+import base64
+
+imgs = {}
+for i in range(1, 10):
+    with open(f'examples/how/features/img{i}_b64.txt') as f:
+        imgs[i] = f.read().strip()
+
+for i, d in imgs.items():
+    print(f'img{i}: len={len(d)}')

examples/how/presets.json

@@ -0,0 +1,14 @@
+{
+  "deconstruct": {
+    "max_iterations": 500,
+    "temperature": 0.3,
+    "skills": ["planning", "research", "browser", "deconstruct"],
+    "description": "解构 Agent，将社交媒体帖子解构为可还原的结构化制作脚本"
+  },
+  "construct": {
+    "max_iterations": 500,
+    "temperature": 0.7,
+    "skills": ["planning", "research", "browser", "construct"],
+    "description": "建构 Agent，基于解构产物生成内容并输出执行报告"
+  }
+}

examples/how/production.prompt

@@ -0,0 +1,48 @@
+---
+model: sonnet-4.6
+temperature: 0.5
+---
+
+$system$
+你是社交媒体内容研究员。目标是通过「解构→建构→评估」的迭代循环，产出一份优质帖子的高质量解构产物（制作表）。
+
+解构产物的价值不在于建构本身，而在于：它能揭示让这篇内容优秀的关键创作规律，并且能在不同内容上泛化。
+
+## 工作流程
+
+**第一轮**：
+1. 调用 deconstruct agent，传入原帖的完整多模态内容，获取 制作表；注意：
+    - 你可以直接给deconstruct agent输入文件夹路径
+    - 它会自动加载如何解构内容的skill：examples/how/skills/deconstruct.md作为system prompt
+    - 指定解构结果的保存路径
+2. 调用 construct agent，传入解构产物 制作表，得到生成内容
+3. 对比建构结果与原帖，做出评估
+
+**后续迭代**（如有必要）：
+4. 根据建构 agent 的执行报告和你的对比观察，判断解构哪里不够准确或不够完整，或者建构做的不够好
+5. 带着具体的修改意见再次调用解构或建构 agent（通过 `continue_from` 复用已有 trace，或重新调用并说明改进方向）
+6. 评估结果，并重复以上环节，直到满意
+
+## 评估标准
+
+评估时关注以下维度（抓最关键的差距，不需要面面俱到）：
+- **核心洞察是否被体现**：建构内容有没有抓住原帖"为什么好"的关键
+- **视觉结构是否对应**：主要元素的位置、层级、比例关系
+- **形式感是否一致**：整体调性、制作手段、视觉风格
+- **文字是否匹配**：标题逻辑、正文节奏
+
+## 终止条件
+
+满足以下任一条件时停止迭代，输出最终解构产物：
+- 建构结果与原帖在核心维度高度吻合
+- 差距来自建构工具能力上限，而非解构质量问题
+- 迭代超过 3 轮且边际改善明显收窄
+
+## 输出
+
+注意输出过程中的制作表和还原产物，每一轮次的结果应该输出到examples/how/output中的一个子文件夹。
+输出最终解构产物 制作表JSON 和相关特征 以及 还原结果，保存到examples/how/output/final，并附上一段简短的研究备注（这篇内容的核心创作规律是什么，迭代过程中发现了什么）。
+
+$user$
+请对下面这篇社交媒体帖子进行解构-建构-评估迭代，产出高质量解构产物。
+原始帖子信息：examples/how/input/《秋日际遇》写生油画.json

examples/how/resource/input_cloud_archive/《秋日际遇》写生油画.json

@@ -0,0 +1,26 @@
+{
+  "channel_content_id": "616192600000000021034642",
+  "link": "https://www.xiaohongshu.com/explore/616192600000000021034642",
+  "comment_count": 0,
+  "images": [
+    "http://res.cybertogether.net/crawler/image/5b94399f3bdef0a80b98e2734e110ca2.jpeg",
+    "http://res.cybertogether.net/crawler/image/6d80c193ccd0b047e0f3354ed6aca355.jpeg",
+    "http://res.cybertogether.net/crawler/image/2ba333062a7370ce229696fc36b9a060.jpeg",
+    "http://res.cybertogether.net/crawler/image/8187a1ad4e56295ab13d881d0ef7c934.jpeg",
+    "http://res.cybertogether.net/crawler/image/16fc8596b7c12031e910eb517859045c.jpeg",
+    "http://res.cybertogether.net/crawler/image/15a29cb486344bc10e90402371e21c92.jpeg",
+    "http://res.cybertogether.net/crawler/image/e70bbea964cfcf0225744da00e8e7939.jpeg",
+    "http://res.cybertogether.net/crawler/image/d20b73ad445c7dce64983159bc6cdae0.jpeg",
+    "http://res.cybertogether.net/crawler/image/c4c73c1b32f8066cc40a43ce61f61364.jpeg"
+  ],
+  "like_count": 411,
+  "body_text": "听闻秋日是倒放的春天\n于是我心中有一座秋日的花园\n栽种着一簇簇淡却温暖的花\n风沿着远边的山吹来\n热情的阳光里秋风微凉\n与颜料一起酝酿出的画面\n白裙是一抹无暇\n迎着光绘画出\n那片在我心上开满\n限定的浪漫\n被画架支起\n绿草坪还驻留了匆匆而过的热闹\n再添一笔白\n为我画一枝玫瑰的奇遇\n———@万淮 #草地拍照[话题]##画画[话题]#",
+  "title": "《秋日际遇》写生油画",
+  "collect_count": 181,
+  "channel_account_id": "584fc4a36a6a693eef600ec3",
+  "channel_account_name": "糯米和Kilala",
+  "content_type": "note",
+  "video": "",
+  "publish_timestamp": 1633784416000,
+  "publish_time": "2021-10-09 21:00:16"
+}

examples/how/resource/input_local_archive/《秋日际遇》写生油画.json

@@ -0,0 +1,26 @@
+{
+  "channel_content_id": "616192600000000021034642",
+  "link": "https://www.xiaohongshu.com/explore/616192600000000021034642",
+  "comment_count": 0,
+  "images": [
+    "examples/how/input/1.jpeg",
+    "examples/how/input/2.jpeg",
+    "examples/how/input/3.jpeg",
+    "examples/how/input/4.jpeg",
+    "examples/how/input/5.jpeg",
+    "examples/how/input/6.jpeg",    
+    "examples/how/input/7.jpeg",
+    "examples/how/input/8.jpeg",
+    "examples/how/input/9.jpeg"
+  ],
+  "like_count": 411,
+  "body_text": "听闻秋日是倒放的春天\n于是我心中有一座秋日的花园\n栽种着一簇簇淡却温暖的花\n风沿着远边的山吹来\n热情的阳光里秋风微凉\n与颜料一起酝酿出的画面\n白裙是一抹无暇\n迎着光绘画出\n那片在我心上开满\n限定的浪漫\n被画架支起\n绿草坪还驻留了匆匆而过的热闹\n再添一笔白\n为我画一枝玫瑰的奇遇\n———@万淮 #草地拍照[话题]##画画[话题]#",
+  "title": "《秋日际遇》写生油画",
+  "collect_count": 181,
+  "channel_account_id": "584fc4a36a6a693eef600ec3",
+  "channel_account_name": "糯米和Kilala",
+  "content_type": "note",
+  "video": "",
+  "publish_timestamp": 1633784416000,
+  "publish_time": "2021-10-09 21:00:16"
+}

examples/how/run.py

@@ -0,0 +1,566 @@
+"""
+示例（增强版）
+
+使用 Agent 模式 + Skills
+
+新增功能：
+1. 支持命令行随时打断（输入 'p' 暂停，'q' 退出）
+2. 暂停后可插入干预消息
+3. 支持触发经验总结
+4. 查看当前 GoalTree
+5. 框架层自动清理不完整的工具调用
+6. 支持通过 --trace <ID> 恢复已有 Trace 继续执行
+"""
+
+import argparse
+import os
+import sys
+import select
+import asyncio
+from pathlib import Path
+
+# Clash Verge TUN 模式兼容：禁止 httpx/urllib 自动检测系统 HTTP 代理
+# TUN 虚拟网卡已在网络层接管所有流量，不需要应用层再走 HTTP 代理，
+# 否则 httpx 检测到 macOS 系统代理 (127.0.0.1:7897) 会导致 ConnectError
+os.environ.setdefault("no_proxy", "*")
+
+# 添加项目根目录到 Python 路径
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from dotenv import load_dotenv
+load_dotenv()
+
+from agent.llm.prompts import SimplePrompt
+from agent.core.runner import AgentRunner, RunConfig
+from agent.core.presets import AgentPreset, register_preset
+from agent.trace import (
+    FileSystemTraceStore,
+    Trace,
+    Message,
+)
+from agent.llm import create_openrouter_llm_call
+from agent.tools import get_tool_registry
+
+
+# ===== 非阻塞 stdin 检测 =====
+if sys.platform == 'win32':
+    import msvcrt
+
+def check_stdin() -> str | None:
+    """
+    跨平台非阻塞检查 stdin 输入。
+    Windows: 使用 msvcrt.kbhit()
+    macOS/Linux: 使用 select.select()
+    """
+    if sys.platform == 'win32':
+        # 检查是否有按键按下
+        if msvcrt.kbhit():
+            # 读取按下的字符（msvcrt.getwch 是非阻塞读取宽字符）
+            ch = msvcrt.getwch().lower()
+            if ch == 'p':
+                return 'pause'
+            if ch == 'q':
+                return 'quit'
+            # 如果是其他按键，可以选择消耗掉或者忽略
+        return None
+    else:
+        # Unix/Mac 逻辑
+        ready, _, _ = select.select([sys.stdin], [], [], 0)
+        if ready:
+            line = sys.stdin.readline().strip().lower()
+            if line in ('p', 'pause'):
+                return 'pause'
+            if line in ('q', 'quit'):
+                return 'quit'
+        return None
+
+
+# ===== 交互菜单 =====
+
+def _read_multiline() -> str:
+    """
+    读取多行输入，以连续两次回车（空行）结束。
+
+    单次回车只是换行，不会提前终止输入。
+    """
+    print("\n请输入干预消息（连续输入两次回车结束）：")
+    lines: list[str] = []
+    blank_count = 0
+    while True:
+        line = input()
+        if line == "":
+            blank_count += 1
+            if blank_count >= 2:
+                break
+            lines.append("")          # 保留单个空行
+        else:
+            blank_count = 0
+            lines.append(line)
+
+    # 去掉尾部多余空行
+    while lines and lines[-1] == "":
+        lines.pop()
+    return "\n".join(lines)
+
+
+async def show_interactive_menu(
+    runner: AgentRunner,
+    trace_id: str,
+    current_sequence: int,
+    store: FileSystemTraceStore,
+):
+    """
+    显示交互式菜单，让用户选择操作。
+
+    进入本函数前不再有后台线程占用 stdin，所以 input() 能正常工作。
+    """
+    print("\n" + "=" * 60)
+    print("  执行已暂停")
+    print("=" * 60)
+    print("请选择操作：")
+    print("  1. 插入干预消息并继续")
+    print("  2. 触发经验总结（reflect）")
+    print("  3. 查看当前 GoalTree")
+    print("  4. 手动压缩上下文（compact）")
+    print("  5. 继续执行")
+    print("  6. 停止执行")
+    print("=" * 60)
+
+    while True:
+        choice = input("请输入选项 (1-6): ").strip()
+
+        if choice == "1":
+            text = _read_multiline()
+            if not text:
+                print("未输入任何内容，取消操作")
+                continue
+
+            print(f"\n将插入干预消息并继续执行...")
+            # 从 store 读取实际的 last_sequence，避免本地 current_sequence 过时
+            live_trace = await store.get_trace(trace_id)
+            actual_sequence = live_trace.last_sequence if live_trace and live_trace.last_sequence else current_sequence
+            return {
+                "action": "continue",
+                "messages": [{"role": "user", "content": text}],
+                "after_sequence": actual_sequence,
+            }
+
+        elif choice == "2":
+            # 触发经验总结
+            print("\n触发经验总结...")
+            focus = input("请输入反思重点（可选，直接回车跳过）: ").strip()
+
+            from agent.trace.compaction import build_reflect_prompt
+
+            # 保存当前 head_sequence
+            trace = await store.get_trace(trace_id)
+            saved_head = trace.head_sequence
+
+            prompt = build_reflect_prompt()
+            if focus:
+                prompt += f"\n\n请特别关注：{focus}"
+
+            print("正在生成反思...")
+            reflect_cfg = RunConfig(trace_id=trace_id, max_iterations=1, tools=[])
+
+            reflection_text = ""
+            try:
+                result = await runner.run_result(
+                    messages=[{"role": "user", "content": prompt}],
+                    config=reflect_cfg,
+                )
+                reflection_text = result.get("summary", "")
+            finally:
+                # 恢复 head_sequence（反思消息成为侧枝）
+                await store.update_trace(trace_id, head_sequence=saved_head)
+
+            # 追加到 experiences 文件
+            if reflection_text:
+                from datetime import datetime
+                experiences_path = runner.experiences_path or "./.cache/experiences.md"
+                os.makedirs(os.path.dirname(experiences_path), exist_ok=True)
+                header = f"\n\n---\n\n## {trace_id} ({datetime.now().strftime('%Y-%m-%d %H:%M')})\n\n"
+                with open(experiences_path, "a", encoding="utf-8") as f:
+                    f.write(header + reflection_text + "\n")
+                print(f"\n反思已保存到: {experiences_path}")
+                print("\n--- 反思内容 ---")
+                print(reflection_text)
+                print("--- 结束 ---\n")
+            else:
+                print("未生成反思内容")
+
+            continue
+
+        elif choice == "3":
+            goal_tree = await store.get_goal_tree(trace_id)
+            if goal_tree and goal_tree.goals:
+                print("\n当前 GoalTree:")
+                print(goal_tree.to_prompt())
+            else:
+                print("\n当前没有 Goal")
+            continue
+
+        elif choice == "4":
+            # 手动压缩上下文
+            print("\n正在执行上下文压缩（compact）...")
+            try:
+                goal_tree = await store.get_goal_tree(trace_id)
+                trace = await store.get_trace(trace_id)
+                if not trace:
+                    print("未找到 Trace，无法压缩")
+                    continue
+
+                # 重建当前 history
+                main_path = await store.get_main_path_messages(trace_id, trace.head_sequence)
+                history = [msg.to_llm_dict() for msg in main_path]
+                head_seq = main_path[-1].sequence if main_path else 0
+                next_seq = head_seq + 1
+
+                compact_config = RunConfig(trace_id=trace_id)
+                new_history, new_head, new_seq = await runner._compress_history(
+                    trace_id=trace_id,
+                    history=history,
+                    goal_tree=goal_tree,
+                    config=compact_config,
+                    sequence=next_seq,
+                    head_seq=head_seq,
+                )
+                print(f"\n✅ 压缩完成: {len(history)} 条消息 → {len(new_history)} 条")
+            except Exception as e:
+                print(f"\n❌ 压缩失败: {e}")
+            continue
+
+        elif choice == "5":
+            print("\n继续执行...")
+            return {"action": "continue"}
+
+        elif choice == "6":
+            print("\n停止执行...")
+            return {"action": "stop"}
+
+        else:
+            print("无效选项，请重新输入")
+
+
+async def main():
+    # 解析命令行参数
+    parser = argparse.ArgumentParser(description="任务 (Agent 模式 + 交互增强)")
+    parser.add_argument(
+        "--trace", type=str, default=None,
+        help="已有的 Trace ID，用于恢复继续执行（不指定则新建）",
+    )
+    args = parser.parse_args()
+
+    # 路径配置
+    base_dir = Path(__file__).parent
+    project_root = base_dir.parent.parent
+    prompt_path = base_dir / "production.prompt"
+    output_dir = base_dir / "output_1"
+    output_dir.mkdir(exist_ok=True)
+
+    # 加载项目级 presets（examples/how/presets.json）
+    presets_path = base_dir / "presets.json"
+    if presets_path.exists():
+        import json
+        with open(presets_path, "r", encoding="utf-8") as f:
+            project_presets = json.load(f)
+        for name, cfg in project_presets.items():
+            register_preset(name, AgentPreset(**cfg))
+        print(f"   - 已加载项目 presets: {list(project_presets.keys())}")
+
+    # Skills 目录（可选：用户自定义 skills）
+    # 注意：内置 skills（agent/memory/skills/）会自动加载
+    skills_dir = str(base_dir / "skills")
+
+    print("=" * 60)
+    print("mcp/skills 发现、获取、评价 分析任务 (Agent 模式 + 交互增强)")
+    print("=" * 60)
+    print()
+    print("💡 交互提示：")
+    print("   - 执行过程中输入 'p' 或 'pause' 暂停并进入交互模式")
+    print("   - 执行过程中输入 'q' 或 'quit' 停止执行")
+    print("=" * 60)
+    print()
+
+    # 1. 加载 prompt
+    print("1. 加载 prompt 配置...")
+    prompt = SimplePrompt(prompt_path)
+
+    # 2. 构建消息（仅新建时使用，恢复时消息已在 trace 中）
+    print("2. 构建任务消息...")
+    messages = prompt.build_messages()
+
+    # 3. 创建 Agent Runner（配置 skills）
+    print("3. 创建 Agent Runner...")
+    print(f"   - Skills 目录: {skills_dir}")
+    print(f"   - 模型: {prompt.config.get('model', 'sonnet-4.5')}")
+
+    # 加载自定义工具
+    print("   - 加载自定义工具: nanobanana")
+    import examples.how.tool  # 导入自定义工具模块，触发 @tool 装饰器注册
+
+    store = FileSystemTraceStore(base_path=".trace")
+    runner = AgentRunner(
+        trace_store=store,
+        llm_call=create_openrouter_llm_call(model=f"anthropic/claude-{prompt.config.get('model', 'sonnet-4.5')}"),
+        skills_dir=skills_dir,
+        experiences_path="./.cache/experiences_how.md",
+        debug=True
+    )
+
+    # 4. 判断是新建还是恢复
+    resume_trace_id = args.trace
+    if resume_trace_id:
+        # 验证 trace 存在
+        existing_trace = await store.get_trace(resume_trace_id)
+        if not existing_trace:
+            print(f"\n错误: Trace 不存在: {resume_trace_id}")
+            sys.exit(1)
+        print(f"4. 恢复已有 Trace: {resume_trace_id[:8]}...")
+        print(f"   - 状态: {existing_trace.status}")
+        print(f"   - 消息数: {existing_trace.total_messages}")
+        print(f"   - 任务: {existing_trace.task}")
+    else:
+        print(f"4. 启动新 Agent 模式...")
+
+    print()
+
+    final_response = ""
+    current_trace_id = resume_trace_id
+    current_sequence = 0
+    should_exit = False
+
+    try:
+        # 恢复模式：不发送初始消息，只指定 trace_id 续跑
+        if resume_trace_id:
+            initial_messages = None  # None = 未设置，触发早期菜单检查
+            config = RunConfig(
+                model=f"claude-{prompt.config.get('model', 'sonnet-4.5')}",
+                temperature=float(prompt.config.get('temperature', 0.3)),
+                max_iterations=1000,
+                trace_id=resume_trace_id,
+            )
+        else:
+            initial_messages = messages
+            config = RunConfig(
+                model=f"claude-{prompt.config.get('model', 'sonnet-4.5')}",
+                temperature=float(prompt.config.get('temperature', 0.3)),
+                max_iterations=1000,
+                name="社交媒体内容解构、建构、评估任务",
+            )
+
+        while not should_exit:
+            # 如果是续跑，需要指定 trace_id
+            if current_trace_id:
+                config.trace_id = current_trace_id
+
+            # 清理上一轮的响应，避免失败后显示旧内容
+            final_response = ""
+
+            # 如果 trace 已完成/失败且没有新消息，直接进入交互菜单
+            # 注意：initial_messages 为 None 表示未设置（首次加载），[] 表示有意为空（用户选择"继续"）
+            if current_trace_id and initial_messages is None:
+                check_trace = await store.get_trace(current_trace_id)
+                if check_trace and check_trace.status in ("completed", "failed"):
+                    if check_trace.status == "completed":
+                        print(f"\n[Trace] ✅ 已完成")
+                        print(f"  - Total messages: {check_trace.total_messages}")
+                        print(f"  - Total cost: ${check_trace.total_cost:.4f}")
+                    else:
+                        print(f"\n[Trace] ❌ 已失败: {check_trace.error_message}")
+                    current_sequence = check_trace.head_sequence
+
+                    menu_result = await show_interactive_menu(
+                        runner, current_trace_id, current_sequence, store
+                    )
+
+                    if menu_result["action"] == "stop":
+                        break
+                    elif menu_result["action"] == "continue":
+                        new_messages = menu_result.get("messages", [])
+                        if new_messages:
+                            initial_messages = new_messages
+                            config.after_sequence = menu_result.get("after_sequence")
+                        else:
+                            # 无新消息：对 failed trace 意味着重试，对 completed 意味着继续
+                            initial_messages = []
+                            config.after_sequence = None
+                        continue
+                    break
+
+                # 对 stopped/running 等非终态的 trace，直接续跑
+                initial_messages = []
+
+            print(f"{'▶️ 开始执行...' if not current_trace_id else '▶️ 继续执行...'}")
+
+            # 执行 Agent
+            paused = False
+            try:
+                async for item in runner.run(messages=initial_messages, config=config):
+                    # 检查用户中断
+                    cmd = check_stdin()
+                    if cmd == 'pause':
+                        # 暂停执行
+                        print("\n⏸️ 正在暂停执行...")
+                        if current_trace_id:
+                            await runner.stop(current_trace_id)
+
+                        # 等待一小段时间让 runner 处理 stop 信号
+                        await asyncio.sleep(0.5)
+
+                        # 显示交互菜单
+                        menu_result = await show_interactive_menu(
+                            runner, current_trace_id, current_sequence, store
+                        )
+
+                        if menu_result["action"] == "stop":
+                            should_exit = True
+                            paused = True
+                            break
+                        elif menu_result["action"] == "continue":
+                            # 检查是否有新消息需要插入
+                            new_messages = menu_result.get("messages", [])
+                            if new_messages:
+                                # 有干预消息，需要重新启动循环
+                                initial_messages = new_messages
+                                after_seq = menu_result.get("after_sequence")
+                                if after_seq is not None:
+                                    config.after_sequence = after_seq
+                                paused = True
+                                break
+                            else:
+                                # 没有新消息，需要重启执行
+                                initial_messages = []
+                                config.after_sequence = None
+                                paused = True
+                                break
+
+                    elif cmd == 'quit':
+                        print("\n🛑 用户请求停止...")
+                        if current_trace_id:
+                            await runner.stop(current_trace_id)
+                        should_exit = True
+                        break
+
+                    # 处理 Trace 对象（整体状态变化）
+                    if isinstance(item, Trace):
+                        current_trace_id = item.trace_id
+                        if item.status == "running":
+                            print(f"[Trace] 开始: {item.trace_id[:8]}...")
+                        elif item.status == "completed":
+                            print(f"\n[Trace] ✅ 完成")
+                            print(f"  - Total messages: {item.total_messages}")
+                            print(f"  - Total tokens: {item.total_tokens}")
+                            print(f"  - Total cost: ${item.total_cost:.4f}")
+                        elif item.status == "failed":
+                            print(f"\n[Trace] ❌ 失败: {item.error_message}")
+                        elif item.status == "stopped":
+                            print(f"\n[Trace] ⏸️ 已停止")
+
+                    # 处理 Message 对象（执行过程）
+                    elif isinstance(item, Message):
+                        current_sequence = item.sequence
+
+                        if item.role == "assistant":
+                            content = item.content
+                            if isinstance(content, dict):
+                                text = content.get("text", "")
+                                tool_calls = content.get("tool_calls")
+
+                                if text and not tool_calls:
+                                    # 纯文本回复（最终响应）
+                                    final_response = text
+                                    print(f"\n[Response] Agent 回复：")
+                                    print(text)
+                                elif text:
+                                    preview = text[:150] + "..." if len(text) > 150 else text
+                                    print(f"[Assistant] {preview}")
+
+                                if tool_calls:
+                                    for tc in tool_calls:
+                                        tool_name = tc.get("function", {}).get("name", "unknown")
+                                        print(f"[Tool Call] 🛠️  {tool_name}")
+
+                        elif item.role == "tool":
+                            content = item.content
+                            if isinstance(content, dict):
+                                tool_name = content.get("tool_name", "unknown")
+                                print(f"[Tool Result] ✅ {tool_name}")
+                            if item.description:
+                                desc = item.description[:80] if len(item.description) > 80 else item.description
+                                print(f"  {desc}...")
+
+            except Exception as e:
+                print(f"\n执行出错: {e}")
+                import traceback
+                traceback.print_exc()
+
+            # paused → 菜单已在暂停时内联显示过
+            if paused:
+                if should_exit:
+                    break
+                continue
+
+            # quit → 直接退出
+            if should_exit:
+                break
+
+            # Runner 退出（完成/失败/停止/异常）→ 显示交互菜单
+            if current_trace_id:
+                menu_result = await show_interactive_menu(
+                    runner, current_trace_id, current_sequence, store
+                )
+
+                if menu_result["action"] == "stop":
+                    break
+                elif menu_result["action"] == "continue":
+                    new_messages = menu_result.get("messages", [])
+                    if new_messages:
+                        initial_messages = new_messages
+                        config.after_sequence = menu_result.get("after_sequence")
+                    else:
+                        initial_messages = []
+                        config.after_sequence = None
+                    continue
+            break
+
+    except KeyboardInterrupt:
+        print("\n\n用户中断 (Ctrl+C)")
+        if current_trace_id:
+            await runner.stop(current_trace_id)
+
+    # 6. 输出结果
+    if final_response:
+        print()
+        print("=" * 60)
+        print("Agent 响应:")
+        print("=" * 60)
+        print(final_response)
+        print("=" * 60)
+        print()
+
+        # 7. 保存结果
+        output_file = output_dir / "result.txt"
+        with open(output_file, 'w', encoding='utf-8') as f:
+            f.write(final_response)
+
+        print(f"✓ 结果已保存到: {output_file}")
+        print()
+
+    # 可视化提示
+    if current_trace_id:
+        print("=" * 60)
+        print("可视化 Step Tree:")
+        print("=" * 60)
+        print("1. 启动 API Server:")
+        print("   python3 api_server.py")
+        print()
+        print("2. 浏览器访问:")
+        print("   http://localhost:8000/api/traces")
+        print()
+        print(f"3. Trace ID: {current_trace_id}")
+        print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/how/save_b64.py

@@ -0,0 +1,8 @@
+import base64, os
+os.makedirs('examples/how/features', exist_ok=True)
+for i in range(1, 10):
+    with open(f'examples/how/input_local_archive/{i}.jpeg', 'rb') as f:
+        d = base64.b64encode(f.read()).decode()
+    with open(f'examples/how/features/img{i}_b64.txt', 'w') as out:
+        out.write(d)
+    print(f'saved img{i}_b64.txt, len={len(d)}')

examples/how/skills/construct.md

@@ -0,0 +1,53 @@
+---
+name: construct
+description: 建构社交媒体帖子内容
+---
+
+## 角色
+
+你是社媒内容生成专家。给定一份制作表，将其转化为实际内容。
+
+---
+
+## 主要工具
+你可以使用 `nanobanana` 工具生成图片。
+
+---
+
+## 输出
+
+将最终的生成内容组织到输出文件夹中。不同版本的输出应该分别是一个子文件夹。
+
+此外，应该输出执行报告：
+
+```json
+{
+  "建构结果": {
+    "保存路径": "examples/how/output",
+    "文本": {
+      "标题": "string",
+      "正文": "string"
+    },
+    "图片": [
+      {
+        "图片": "图片1",
+        "生成prompt": "用于生成该图的完整 prompt",
+        "生成方式": "使用了哪个工具/API"
+      }
+    ]
+  },
+  "执行报告": {
+    "成功体现": ["哪些关键创作决策被清晰落地"],
+    "未能落地": ["哪些字段无法体现，或结果不确定是否达到"],
+    "疑问": ["解构中哪些信息不够清晰，影响了建构判断，需要主 agent 注意"]
+  }
+}
+```
+
+---
+
+## 原则
+
+- **解构优先**：以解构 JSON 为主要依据，在建构目标允许的探索空间内发挥
+- **如实报告**：不确定的地方直接标注，便于主 agent 评估和迭代
+- **宁缺毋滥**：不确定的决策宁可省略，不要随意填充导致方向偏离

examples/how/skills/deconstruct.md

@@ -0,0 +1,120 @@
+---
+name: deconstruct
+description: 从制作层解构社交媒体帖子，提取视觉制作决策
+---
+
+## 角色
+
+你是制作还原解构专家。给定一篇优质社交媒体帖子（图片 + 文字），分析其**制作层**——视觉结构、元素形式、元素关系——提取能够支撑还原这篇内容的制作脚本。
+
+**核心问题**：这篇帖子里，哪些决策让它优于同类内容？去掉某个决策后内容会明显变差，才值得记录。
+
+---
+
+## 制作层的核心概念
+
+这两组区分是制作解构的基础，分析时始终从这个视角出发：
+
+**实质 vs 形式**
+- **实质**：元素是什么、包含什么——人物、产品、文字内容、场景
+- **形式**：元素如何呈现——构图、色调、比例、质感、字体、层次、光影
+
+**形式分类**：追溯每个元素最初通过什么手段产生。不是后期处理方式，是**源头制作方式**。常见分类：拍摄、插画、排版、AI 生成、截图、后期合成。
+
+---
+
+## 多模态特征提取
+
+文字描述无法精确表达某些视觉信息——人物的姿态骨架、面部轮廓、色彩分布、深度层次。对这类信息，**提取多模态特征文件**，并在制作表中保留文件索引。
+
+**何时提取**：当某个元素的视觉特征对还原至关重要，且纯文字描述会丢失关键精度时。常见场景：
+- 人物主体：姿态（骨骼关键点图）、面部特征（面部网格/特征点图）
+- 整体色调：色彩分布（调色板图、色彩分割图）
+- 空间结构：深度图、构图线条图（用于 ControlNet）
+- 特定纹理或材质：局部纹理提取图
+
+**提取原则**：
+- 使用图像/数值等多模态格式，不使用自然语言作为唯一表示
+- 特征文件保存至 `./features/<元素名>/` 子目录
+- 制作表中只记录文件路径（不嵌入文件内容）
+- 只对还原必要的关键元素提取，不是每个元素都需要
+
+---
+
+## 分析视角
+
+**内容视角**（先判断，影响对图片的解读角度）：
+- **关注理念**：作者借具体事物传达抽象含义（符号化，借物喻义）
+- **关注表现**：作者直接展示事物本身的状态与细节
+
+**多图对比**（如有多图）：
+- **固定**：跨图保持不变的制作要素 → 往往是创作者刻意为之的核心设计
+- **变化**：跨图有意变化的制作要素 → 往往是叙事或节奏策略
+
+---
+
+## 输出格式
+
+输出一个 JSON，并将其保存到指定输出目录下。**只填写对这篇帖子有意义的字段**，不强制填写所有字段，不强制填满每个层级。
+
+特征文件保存至 `./features/<元素名>/`，制作表中以路径引用。
+
+```json
+{
+  "内容视角": "关注理念 | 关注表现，一句话说明",
+  "核心洞察": "一句话：这篇内容在制作上为什么优秀",
+
+  "多图规律": {
+    "固定": "跨图保持一致的制作要素",
+    "变化": "跨图有意变化的制作要素"
+  },
+
+  "图片制作": [
+    {
+      "图片": "图片1",
+      "元素": [
+        {
+          "名称": "语义化名称",
+          "内容类型": "文字 | 图片",
+          "实质": "是什么（简短）",
+          "形式分类": "拍摄 | 插画 | 排版 | AI生成 | 后期合成 | ...",
+          "关键形式": ["影响视觉效果的原子属性，如：居中构图、暖光氛围、衬线字体"],
+          "特征文件": {
+            "姿态": "./features/主体人物/pose.png",
+            "面部": "./features/主体人物/face_mesh.png",
+            "深度图": "./features/主体人物/depth.png"
+          },
+          "子元素": []
+        }
+      ],
+      "元素关系": [
+        "主体居中占画面 60%，文字叠加于左下角",
+        "人物与背景通过色温对比形成层次"
+      ]
+    }
+  ],
+
+  "核心元素": [
+    {
+      "名称": "人物",
+      "视觉描述": "对还原有价值的视觉特征（制作角度）",
+      "出现图片": ["图片1", "图片2"]
+    }
+  ],
+
+  "文本制作": {
+    "标题": "标题的制作决策（结构、诉求方式、与图的关系）",
+    "正文": "正文的制作决策（节奏、排版风格、信息层级）"
+  }
+}
+```
+
+---
+
+## 原则
+
+- **亲自读图**：你应该直接读取我们需要解构的内容中的多模态内容，仅在后续缺乏特征提取能力的情况下再继续使用其他工具来处理多模态内容
+- **选择性而非穷举**：只记录对还原质量有实质影响的信息                                          
+- **泛化描述**：描述创作规律，而非内容细节（"主体特写，背景虚化"优于"穿蓝衣服的女生"）          
+- **制作视角**：从"如何制作出这个效果"出发，而非"这是什么内容"                                  
+- **信任自己的判断**：你比规则更了解什么重要，跳过不关键的维度  

examples/how/tool/__init__.py

@@ -0,0 +1,7 @@
+"""
+How 示例的自定义工具
+"""
+
+from examples.how.tool.nanobanana import nanobanana
+
+__all__ = ["nanobanana"]

examples/how/tool/nanobanana.py

@@ -0,0 +1,572 @@
+"""
+NanoBanana Tool - 图像特征提取与图像生成
+
+该工具可以提取图片中的特征，也可以根据描述生成图片。
+支持通过 OpenRouter 调用多模态模型，提取结构化的图像特征并保存为 JSON，
+或基于输入图像生成新的图像。
+"""
+
+import base64
+import json
+import mimetypes
+import os
+import re
+from pathlib import Path
+from typing import Optional, Dict, Any, List, Tuple
+
+import httpx
+from dotenv import load_dotenv
+
+from agent.tools import tool, ToolResult
+
+OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+DEFAULT_TIMEOUT = 120.0
+
+DEFAULT_EXTRACTION_PROMPT = (
+    "请从这张图像中提取跨场景相对稳定、可复用的视觉不变特征。"
+    "输出严格 JSON，字段包含：identity_features、pose_features、appearance_features、"
+    "material_features、style_features、uncertainty、notes。"
+    "每个字段给出简洁要点，避免臆测。"
+)
+
+DEFAULT_IMAGE_PROMPT = (
+    "基于输入图像生成一张保留主体身份与关键视觉特征的新图像。"
+    "保持人物核心特征一致，同时提升清晰度与可用性。"
+)
+
+DEFAULT_IMAGE_MODEL_CANDIDATES = [
+    "google/gemini-2.5-flash-image",
+    # "google/gemini-3-pro-image-preview",
+    # "black-forest-labs/flux.2-flex",
+    # "black-forest-labs/flux.2-pro",
+]
+
+
+def _resolve_api_key() -> Optional[str]:
+    """优先读取环境变量，缺失时尝试从 .env 加载。"""
+    api_key = os.getenv("OPENROUTER_API_KEY") or os.getenv("OPEN_ROUTER_API_KEY")
+    if api_key:
+        return api_key
+
+    load_dotenv()
+    return os.getenv("OPENROUTER_API_KEY") or os.getenv("OPEN_ROUTER_API_KEY")
+
+
+def _image_to_data_url(image_path: Path) -> str:
+    """将图片文件编码为 data URL。"""
+    mime_type = mimetypes.guess_type(str(image_path))[0] or "application/octet-stream"
+    raw = image_path.read_bytes()
+    b64 = base64.b64encode(raw).decode("utf-8")
+    return f"data:{mime_type};base64,{b64}"
+
+
+def _safe_json_parse(content: str) -> Dict[str, Any]:
+    """尽量从模型文本中提取 JSON。"""
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError:
+        start = content.find("{")
+        end = content.rfind("}")
+        if start != -1 and end != -1 and end > start:
+            candidate = content[start:end + 1]
+            return json.loads(candidate)
+        raise
+
+
+def _extract_data_url_images(message: Dict[str, Any]) -> List[Tuple[str, str]]:
+    """
+    从 OpenRouter 响应消息中提取 data URL 图片。
+
+    Returns:
+        List[(mime_type, base64_data)]
+    """
+    extracted: List[Tuple[str, str]] = []
+
+    # 官方文档中的主要位置：message.images[]
+    for img in message.get("images", []) or []:
+        if not isinstance(img, dict):
+            continue
+        if img.get("type") != "image_url":
+            continue
+        data_url = ((img.get("image_url") or {}).get("url") or "").strip()
+        if not data_url.startswith("data:"):
+            continue
+        m = re.match(r"^data:([^;]+);base64,(.+)$", data_url, flags=re.DOTALL)
+        if not m:
+            continue
+        extracted.append((m.group(1), m.group(2)))
+
+    # 兼容某些模型可能把 image_url 放在 content 数组中
+    content = message.get("content")
+    if isinstance(content, list):
+        for part in content:
+            if not isinstance(part, dict):
+                continue
+            if part.get("type") != "image_url":
+                continue
+            data_url = ((part.get("image_url") or {}).get("url") or "").strip()
+            if not data_url.startswith("data:"):
+                continue
+            m = re.match(r"^data:([^;]+);base64,(.+)$", data_url, flags=re.DOTALL)
+            if not m:
+                continue
+            extracted.append((m.group(1), m.group(2)))
+
+    return extracted
+
+
+def _extract_image_refs(choice: Dict[str, Any], message: Dict[str, Any]) -> List[Dict[str, str]]:
+    """
+    尝试从不同响应格式中提取图片引用。
+
+    返回格式:
+    - {"kind": "data_url", "value": "data:image/png;base64,..."}
+    - {"kind": "base64", "value": "...", "mime_type": "image/png"}
+    - {"kind": "url", "value": "https://..."}
+    """
+    refs: List[Dict[str, str]] = []
+
+    # 1) 标准 message.images
+    for img in message.get("images", []) or []:
+        if not isinstance(img, dict):
+            continue
+        # image_url 结构
+        data_url = ((img.get("image_url") or {}).get("url") or "").strip()
+        if data_url.startswith("data:"):
+            refs.append({"kind": "data_url", "value": data_url})
+            continue
+        if data_url.startswith("http"):
+            refs.append({"kind": "url", "value": data_url})
+            continue
+
+        # 兼容 base64 字段
+        b64 = (img.get("b64_json") or img.get("base64") or "").strip()
+        if b64:
+            refs.append({"kind": "base64", "value": b64, "mime_type": img.get("mime_type", "image/png")})
+
+    # 2) 某些格式可能在 choice.images
+    for img in choice.get("images", []) or []:
+        if not isinstance(img, dict):
+            continue
+        data_url = ((img.get("image_url") or {}).get("url") or "").strip()
+        if data_url.startswith("data:"):
+            refs.append({"kind": "data_url", "value": data_url})
+            continue
+        if data_url.startswith("http"):
+            refs.append({"kind": "url", "value": data_url})
+            continue
+        b64 = (img.get("b64_json") or img.get("base64") or "").strip()
+        if b64:
+            refs.append({"kind": "base64", "value": b64, "mime_type": img.get("mime_type", "image/png")})
+
+    # 3) content 数组里的 image_url
+    content = message.get("content")
+    if isinstance(content, list):
+        for part in content:
+            if not isinstance(part, dict):
+                continue
+            if part.get("type") != "image_url":
+                continue
+            url = ((part.get("image_url") or {}).get("url") or "").strip()
+            if url.startswith("data:"):
+                refs.append({"kind": "data_url", "value": url})
+            elif url.startswith("http"):
+                refs.append({"kind": "url", "value": url})
+
+    # 4) 极端兼容：文本中可能出现 data:image 或 http 图片 URL
+    if isinstance(content, str):
+        # data URL
+        for m in re.finditer(r"(data:image\/[a-zA-Z0-9.+-]+;base64,[A-Za-z0-9+/=]+)", content):
+            refs.append({"kind": "data_url", "value": m.group(1)})
+        # http(s) 图片链接
+        for m in re.finditer(r"(https?://\S+\.(?:png|jpg|jpeg|webp))", content, flags=re.IGNORECASE):
+            refs.append({"kind": "url", "value": m.group(1)})
+
+    return refs
+
+
+def _mime_to_ext(mime_type: str) -> str:
+    """MIME 类型映射到扩展名。"""
+    mapping = {
+        "image/png": ".png",
+        "image/jpeg": ".jpg",
+        "image/webp": ".webp",
+    }
+    return mapping.get(mime_type.lower(), ".png")
+
+
+def _normalize_model_id(model_id: str) -> str:
+    """
+    规范化常见误写模型 ID，减少无效重试。
+    """
+    if not model_id:
+        return model_id
+    m = model_id.strip()
+    # 常见误写：gemini/gemini-xxx -> google/gemini-xxx
+    if m.startswith("gemini/"):
+        m = "google/" + m.split("/", 1)[1]
+    # 常见顺序误写：preview-image -> image
+    if "gemini-2.5-flash-preview-image" in m:
+        m = m.replace("gemini-2.5-flash-preview-image", "gemini-2.5-flash-image")
+    # 兼容旧 ID 到当前可用 ID
+    if "gemini-2.5-flash-image-preview" in m:
+        m = m.replace("gemini-2.5-flash-image-preview", "gemini-2.5-flash-image")
+    return m
+
+
+@tool(description="可以提取图片中的特征，也可以根据描述生成图片")
+async def nanobanana(
+    image_path: str = "",
+    image_paths: Optional[List[str]] = None,
+    output_file: Optional[str] = None,
+    prompt: Optional[str] = None,
+    model: Optional[str] = None,
+    max_tokens: int = 1200,
+    generate_image: bool = False,
+    image_output_path: Optional[str] = None,
+) -> ToolResult:
+    """
+    可以提取图片中的特征，也可以根据描述生成图片。
+
+    Args:
+        image_path: 输入图片路径（单图模式，可选）
+        image_paths: 输入图片路径列表（多图整体模式，可选）
+        output_file: 输出 JSON 文件路径（可选，用于特征提取模式）
+        prompt: 自定义提取指令或生成描述（可选）
+        model: OpenRouter 模型名（可选，默认读取 NANOBANANA_MODEL 或使用 Gemini 视觉模型）
+        max_tokens: 最大输出 token
+        generate_image: 是否生成图片（False=提取特征，True=生成图片）
+        image_output_path: 生成图片保存路径（generate_image=True 时可选）
+
+    Returns:
+        ToolResult: 包含结构化特征和输出文件路径，或生成的图片路径
+    """
+    raw_paths: List[str] = []
+    if image_paths:
+        raw_paths.extend(image_paths)
+    if image_path:
+        raw_paths.append(image_path)
+    if not raw_paths:
+        return ToolResult(
+            title="NanoBanana 提取失败",
+            output="",
+            error="未提供输入图片，请传入 image_path 或 image_paths",
+        )
+
+    # 去重并检查路径
+    unique_raw: List[str] = []
+    seen = set()
+    for p in raw_paths:
+        if p and p not in seen:
+            unique_raw.append(p)
+            seen.add(p)
+
+    input_paths: List[Path] = [Path(p) for p in unique_raw]
+    invalid = [str(p) for p in input_paths if (not p.exists() or not p.is_file())]
+    if invalid:
+        return ToolResult(
+            title="NanoBanana 提取失败",
+            output="",
+            error=f"以下图片不存在或不可读: {invalid}",
+        )
+
+    api_key = _resolve_api_key()
+    if not api_key:
+        return ToolResult(
+            title="NanoBanana 提取失败",
+            output="",
+            error="未找到 OpenRouter API Key，请设置 OPENROUTER_API_KEY 或 OPEN_ROUTER_API_KEY",
+        )
+
+    if generate_image:
+        user_prompt = prompt or DEFAULT_IMAGE_PROMPT
+    else:
+        chosen_model = model or os.getenv("NANOBANANA_MODEL") or "google/gemini-2.5-flash"
+        user_prompt = prompt or DEFAULT_EXTRACTION_PROMPT
+
+    try:
+        image_data_urls = [_image_to_data_url(p) for p in input_paths]
+    except Exception as e:
+        return ToolResult(
+            title="NanoBanana 提取失败",
+            output="",
+            error=f"图片编码失败: {e}",
+        )
+
+    user_content: List[Dict[str, Any]] = [{"type": "text", "text": user_prompt}]
+    for u in image_data_urls:
+        user_content.append({"type": "image_url", "image_url": {"url": u}})
+
+    payload: Dict[str, Any] = {
+        "messages": [
+            {
+                "role": "system",
+                "content": (
+                    "你是视觉助手。"
+                    "当任务为特征提取时输出 JSON 对象，不要输出 markdown。"
+                    "当任务为图像生成时请返回图像。"
+                ),
+            },
+            {
+                "role": "user",
+                "content": user_content,
+            },
+        ],
+        "temperature": 0.2,
+        "max_tokens": max_tokens,
+    }
+    if generate_image:
+        payload["modalities"] = ["image", "text"]
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+        "HTTP-Referer": "https://local-agent",
+        "X-Title": "Agent NanoBanana Tool",
+    }
+
+    endpoint = f"{OPENROUTER_BASE_URL}/chat/completions"
+
+    # 图像生成模式：自动尝试多个可用模型，减少 404/invalid model 影响
+    if generate_image:
+        candidates: List[str] = []
+        if model:
+            candidates.append(_normalize_model_id(model))
+        if env_model := os.getenv("NANOBANANA_IMAGE_MODEL"):
+            candidates.append(_normalize_model_id(env_model))
+        candidates.extend([_normalize_model_id(x) for x in DEFAULT_IMAGE_MODEL_CANDIDATES])
+        # 去重并保持顺序
+        dedup: List[str] = []
+        seen = set()
+        for m in candidates:
+            if m and m not in seen:
+                dedup.append(m)
+                seen.add(m)
+        candidates = dedup
+    else:
+        candidates = [chosen_model]
+
+    data: Optional[Dict[str, Any]] = None
+    used_model: Optional[str] = None
+    errors: List[Dict[str, Any]] = []
+
+    for cand in candidates:
+        modality_attempts: List[Optional[List[str]]] = [None]
+        if generate_image:
+            modality_attempts = [["image", "text"], ["image"], None]
+
+        for mods in modality_attempts:
+            trial_payload = dict(payload)
+            trial_payload["model"] = cand
+
+            if mods is None:
+                trial_payload.pop("modalities", None)
+            else:
+                trial_payload["modalities"] = mods
+
+            try:
+                async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
+                    resp = await client.post(endpoint, json=trial_payload, headers=headers)
+                    resp.raise_for_status()
+                    data = resp.json()
+                    used_model = cand
+                    break
+            except httpx.HTTPStatusError as e:
+                errors.append({
+                    "model": cand,
+                    "modalities": mods,
+                    "status_code": e.response.status_code,
+                    "body": e.response.text[:600],
+                })
+                continue
+            except Exception as e:
+                errors.append({
+                    "model": cand,
+                    "modalities": mods,
+                    "status_code": None,
+                    "body": str(e)[:600],
+                })
+                continue
+
+        if data is not None:
+            break
+
+    if data is None:
+        title = "NanoBanana 生成失败" if generate_image else "NanoBanana 提取失败"
+        return ToolResult(
+            title=title,
+            output=json.dumps({"attempted_models": candidates, "errors": errors}, ensure_ascii=False, indent=2),
+            long_term_memory="All candidate models failed for this request",
+            metadata={"attempted_models": candidates, "errors": errors},
+        )
+
+    chosen_model = used_model or candidates[0]
+
+    choices = data.get("choices") or []
+    message = choices[0].get("message", {}) if choices else {}
+
+    # 图像生成分支
+    if generate_image:
+        refs = _extract_image_refs(choices[0] if choices else {}, message)
+        if not refs:
+            content = message.get("content")
+            preview = ""
+            if isinstance(content, str):
+                preview = content[:500]
+            elif isinstance(content, list):
+                preview = json.dumps(content[:3], ensure_ascii=False)[:500]
+
+            return ToolResult(
+                title="NanoBanana 生成失败",
+                output=json.dumps(data, ensure_ascii=False, indent=2),
+                error="模型未返回可解析图片（未在 message.images/choice.images/content 中发现图片）",
+                metadata={
+                    "model": chosen_model,
+                    "choice_keys": list((choices[0] if choices else {}).keys()),
+                    "message_keys": list(message.keys()) if isinstance(message, dict) else [],
+                    "content_preview": preview,
+                },
+            )
+
+        output_paths: List[str] = []
+        if image_output_path:
+            base_path = Path(image_output_path)
+        else:
+            if len(input_paths) > 1:
+                base_path = input_paths[0].parent / "set_generated.png"
+            else:
+                base_path = input_paths[0].parent / f"{input_paths[0].stem}_generated.png"
+        base_path.parent.mkdir(parents=True, exist_ok=True)
+
+        for idx, ref in enumerate(refs):
+            kind = ref.get("kind", "")
+            mime_type = "image/png"
+            raw_bytes: Optional[bytes] = None
+
+            if kind == "data_url":
+                m = re.match(r"^data:([^;]+);base64,(.+)$", ref.get("value", ""), flags=re.DOTALL)
+                if not m:
+                    continue
+                mime_type = m.group(1)
+                raw_bytes = base64.b64decode(m.group(2))
+            elif kind == "base64":
+                mime_type = ref.get("mime_type", "image/png")
+                raw_bytes = base64.b64decode(ref.get("value", ""))
+            elif kind == "url":
+                url = ref.get("value", "")
+                try:
+                    with httpx.Client(timeout=DEFAULT_TIMEOUT) as client:
+                        r = client.get(url)
+                        r.raise_for_status()
+                        raw_bytes = r.content
+                        mime_type = r.headers.get("content-type", "image/png").split(";")[0]
+                except Exception:
+                    continue
+            else:
+                continue
+
+            if not raw_bytes:
+                continue
+
+            ext = _mime_to_ext(mime_type)
+            if len(refs) == 1:
+                target = base_path
+                if target.suffix.lower() not in [".png", ".jpg", ".jpeg", ".webp"]:
+                    target = target.with_suffix(ext)
+            else:
+                stem = base_path.stem
+                target = base_path.with_name(f"{stem}_{idx+1}{ext}")
+            try:
+                target.write_bytes(raw_bytes)
+                output_paths.append(str(target))
+            except Exception as e:
+                return ToolResult(
+                    title="NanoBanana 生成失败",
+                    output="",
+                    error=f"写入生成图片失败: {e}",
+                    metadata={"model": chosen_model},
+                )
+
+        if not output_paths:
+            return ToolResult(
+                title="NanoBanana 生成失败",
+                output=json.dumps(data, ensure_ascii=False, indent=2),
+                error="检测到图片引用但写入失败（可能是无效 base64 或 URL 不可访问）",
+                metadata={"model": chosen_model, "ref_count": len(refs)},
+            )
+
+        usage = data.get("usage", {})
+        prompt_tokens = usage.get("prompt_tokens") or usage.get("input_tokens", 0)
+        completion_tokens = usage.get("completion_tokens") or usage.get("output_tokens", 0)
+        summary = {
+            "model": chosen_model,
+            "input_images": [str(p) for p in input_paths],
+            "input_count": len(input_paths),
+            "generated_images": output_paths,
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+        }
+        return ToolResult(
+            title="NanoBanana 图片生成完成",
+            output=json.dumps({"summary": summary}, ensure_ascii=False, indent=2),
+            long_term_memory=f"Generated {len(output_paths)} image(s) from {len(input_paths)} input image(s) using {chosen_model}",
+            attachments=output_paths,
+            metadata=summary,
+        )
+
+    content = message.get("content") or ""
+    if not content:
+        return ToolResult(
+            title="NanoBanana 提取失败",
+            output=json.dumps(data, ensure_ascii=False, indent=2),
+            error="模型未返回内容",
+        )
+
+    try:
+        parsed = _safe_json_parse(content)
+    except Exception as e:
+        return ToolResult(
+            title="NanoBanana 提取失败",
+            output=content,
+            error=f"模型返回非 JSON 内容，解析失败: {e}",
+            metadata={"model": chosen_model},
+        )
+
+    if output_file:
+        out_path = Path(output_file)
+    else:
+        if len(input_paths) > 1:
+            out_path = input_paths[0].parent / "set_invariant_features.json"
+        else:
+            out_path = input_paths[0].parent / f"{input_paths[0].stem}_invariant_features.json"
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(parsed, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    usage = data.get("usage", {})
+    prompt_tokens = usage.get("prompt_tokens") or usage.get("input_tokens", 0)
+    completion_tokens = usage.get("completion_tokens") or usage.get("output_tokens", 0)
+
+    summary = {
+        "model": chosen_model,
+        "input_images": [str(p) for p in input_paths],
+        "input_count": len(input_paths),
+        "output_file": str(out_path),
+        "prompt_tokens": prompt_tokens,
+        "completion_tokens": completion_tokens,
+    }
+
+    return ToolResult(
+        title="NanoBanana 不变特征提取完成",
+        output=json.dumps(
+            {
+                "summary": summary,
+                "features": parsed,
+            },
+            ensure_ascii=False,
+            indent=2,
+        ),
+        long_term_memory=f"Extracted invariant features from {len(input_paths)} input image(s) using {chosen_model}",
+        attachments=[str(out_path)],
+        metadata=summary,
+    )

examples/research/run.py

@@ -1,16 +1,21 @@
 """
-浏览器调研示例 (增强版)
+浏览器调研示例 (交互增强版)
 
 功能：
-1. 使用 Agent 模式进行网络调研
-2. 任务结束自动关闭浏览器并杀掉进程
-3. 异常安全：即使程序崩溃也能清理环境
+1. Agent 模式自动化调研
+2. 手动接管：随时按 [Enter] 键暂停 Agent 并手动操作浏览器
+3. 自动清理：无论成功或崩溃，均安全关闭浏览器进程
 """
 
 import os
 import sys
 import asyncio
+import logging
+import re
+import uuid
 from pathlib import Path
+from datetime import datetime
+from argparse import Namespace
 
 # 添加项目根目录到 Python 路径
 sys.path.insert(0, str(Path(__file__).parent.parent.parent))
@@ -18,26 +23,36 @@ sys.path.insert(0, str(Path(__file__).parent.parent.parent))
 from dotenv import load_dotenv
 load_dotenv()
 
-import logging
-# 配置感知日志
-logging.basicConfig(level=logging.WARNING)  # 默认 WARNING
-logging.getLogger("agent.core.message_manager").setLevel(logging.INFO)  # 开启感知日志
-logging.getLogger("tools").setLevel(logging.INFO)  # 开启工具日志
+# --- 日志配置 ---
+logging.basicConfig(level=logging.WARNING)
+logging.getLogger("agent.core.message_manager").setLevel(logging.INFO)
+logging.getLogger("tools").setLevel(logging.INFO)
 
 from agent.llm.prompts import SimplePrompt
 from agent.core.runner import AgentRunner, RunConfig
-from agent.trace import (
-    FileSystemTraceStore,
-    Trace,
-    Message,
-)
+from agent.trace import FileSystemTraceStore, Trace, Message
 from agent.llm import create_openrouter_llm_call
+from agent.tools.builtin.browser.baseClass import kill_browser_session
+
+# ===== 全局交互控制 =====
+pause_event = asyncio.Event()
+
+async def listen_for_interrupt():
+    """后台协程：监听标准输入，按下回车即触发暂停"""
+    while True:
+        # 在执行器中运行同步的 readline，避免阻塞事件循环
+        await asyncio.get_event_loop().run_in_executor(None, sys.stdin.readline)
+        if not pause_event.is_set():
+            print("\n" + "!" * 40)
+            print("🛑 检测到手动干预请求！")
+            print("Agent 将在完成当前动作后暂停，请准备接管浏览器。")
+            print("!" * 40 + "\n")
+            pause_event.set()
 
-# 导入浏览器清理工具
-from agent.tools.builtin.browser.baseClass import get_browser_session,kill_browser_session,init_browser_session 
+# ===== 核心逻辑 =====
 
 async def main():
-    # 路径配置
+    # 1. 环境准备
     base_dir = Path(__file__).parent
     project_root = base_dir.parent.parent
     trace_dir = project_root / ".trace"
@@ -45,146 +60,128 @@ async def main():
     output_dir = base_dir / "output"
     output_dir.mkdir(exist_ok=True)
 
-    # Skills 目录
-    skills_dir = None 
-
-    print("=" * 60)
-    print("🚀 浏览器调研任务 (Agent 模式)")
     print("=" * 60)
-    print()
+    print("🚀 交互式浏览器调研 Agent")
+    print("👉 操作指南：")
+    print("   - 运行中随时按下 [Enter] 键进入手动接管模式")
+    print("   - 在浏览器完成操作后，点击页面上的 'Done' 或回车返回")
+    print("=" * 60 + "\n")
 
-    # 1. 加载 prompt
-    print("1. 加载 prompt...")
+    # 2. 加载任务
     prompt = SimplePrompt(prompt_path)
-
-    # 提取配置
     system_prompt = prompt._messages.get("system", "")
     user_task = prompt._messages.get("user", "")
-    model_name = prompt.config.get('model', 'gemini-2.5-flash')
+    # 默认使用 cheap 模型进行调研，如 gemini-3-flash-preview
+    model_name = prompt.config.get('model', 'gemini-3-flash-preview')
     temperature = float(prompt.config.get('temperature', 0.3))
 
-    print(f"   - 任务: {user_task[:80]}...")
-    print(f"   - 模型: {model_name}")
-    
-    # 2. 构建消息
-    print("2. 构建任务消息...")
     messages = prompt.build_messages()
 
-    # 3. 创建 Agent Runner
-    print("3. 创建 Agent Runner...")
+    # 3. 初始化 Runner
+    # 注意：确保你的 openrouter 配置正确
     runner = AgentRunner(
         trace_store=FileSystemTraceStore(base_path=str(trace_dir)),
         llm_call=create_openrouter_llm_call(model=f"google/{model_name}"),
-        skills_dir=skills_dir,
+        skills_dir=None,
         debug=True 
     )
 
+    # 4. 启动监听任务
+    interrupt_task = asyncio.create_task(listen_for_interrupt())
+    
     final_response = ""
     current_trace_id = None
 
-    # 4. Agent 模式执行（使用 try...finally 确保清理）
     try:
-        print(f"4. 初始化云浏览器...")                              
-        await init_browser_session(browser_type="cloud", headless=True)                                                          
-
-        print(f"5. 启动 Agent 模式执行...")    
-        print()
-
-        async for item in runner.run(
+        # 启动 Agent 迭代
+        agent_stream = runner.run(
             messages=messages,
             config=RunConfig(
                 system_prompt=system_prompt,
                 model=f"google/{model_name}",
                 temperature=temperature,
-                max_iterations=20,
+                max_iterations=30,
                 name=user_task[:50],
             ),
-        ):
-            # 处理 Trace 对象（整体状态变化）
+        )
+
+        async for item in agent_stream:
+            # --- 检查手动暂停信号 ---
+            if pause_event.is_set():
+                print("\n" + "🛠️" * 20)
+                print(">>> 人工接管模式激活 <<<")
+                print("1. 请在浏览器窗口进行必要操作（登录、过验证码等）")
+                print("2. 操作完成后，请在终端按 [Enter] 或在页面点击交互按钮继续")
+                
+                try:
+                    # 调用内置的等待交互工具
+                    await runner.tools.execute(
+                        "browser_wait_for_user_action",
+                        {"message": "人工干预中，请完成操作后恢复 Agent"},
+                        uid="human_admin",
+                        context={"runner": runner}
+                    )
+                except Exception as e:
+                    print(f"⚠️ 交互工具调用失败: {e}")
+                
+                print(">>> 交互结束，交还控制权给 Agent <<<")
+                print("🛠️" * 20 + "\n")
+                pause_event.clear()
+
+            # --- 正常处理 Agent 消息输出 ---
             if isinstance(item, Trace):
                 current_trace_id = item.trace_id
                 if item.status == "running":
-                    print(f"[Trace] 开始: {item.trace_id[:8]}")
+                    print(f"[{datetime.now().strftime('%H:%M:%S')}] 🛰️ Trace 启动: {item.trace_id[:8]}")
                 elif item.status == "completed":
-                    print(f"[Trace] 完成")
-                    print(f"  - Total tokens: {item.total_tokens}")
-                    print(f"  - Total cost: ${item.total_cost:.4f}")
-                elif item.status == "failed":
-                    print(f"[Trace] 失败: {item.error_message}")
+                    print(f"\n✅ 任务圆满完成！Cost: ${item.total_cost:.4f}")
 
-            # 处理 Message 对象（执行过程）
             elif isinstance(item, Message):
                 if item.role == "assistant":
                     content = item.content
                     if isinstance(content, dict):
                         text = content.get("text", "")
                         tool_calls = content.get("tool_calls")
-
-                        if text and not tool_calls:
-                            final_response = text
-                            print(f"[Response] Agent 给出最终回复")
-                        elif text:
-                            # 增加打印长度到 300，方便观察
-                            print(f"[Assistant] {text[:300]}...")
-
+                        if text:
+                            # 打印摘要，带点 Wit
+                            print(f"\n🤖 Agent: {text[:200]}..." if len(text) > 200 else f"\n🤖 Agent: {text}")
                         if tool_calls:
                             for tc in tool_calls:
-                                tool_name = tc.get("function", {}).get("name", "unknown")
-                                print(f"[Tool Call] 🛠️ {tool_name}")
-
+                                t_name = tc.get("function", {}).get("name", "unknown")
+                                print(f"   🛠️  执行工具: {t_name}")
+                
                 elif item.role == "tool":
-                    content = item.content
-                    if isinstance(content, dict):
-                        tool_name = content.get("tool_name", "unknown")
-                        print(f"[Tool Result] ✅ {tool_name}")
-                    if item.description:
-                        desc = item.description[:80] if len(item.description) > 80 else item.description
-                        print(f"  {desc}...")
-
-        # 5. 输出结果
-        print()
-        print("=" * 60)
-        print("Final Agent Response:")
-        print("=" * 60)
-        print(final_response)
-        print("=" * 60)
-        print()
-
-        # 6. 保存结果
-        output_file = output_dir / "research_result.txt"
-        with open(output_file, 'w', encoding='utf-8') as f:
-            f.write(final_response)
-        print(f"✓ 结果已保存到: {output_file}")
+                    t_content = item.content
+                    if isinstance(t_content, dict):
+                        t_name = t_content.get("tool_name", "unknown")
+                        print(f"   ✅ 工具返回: {t_name}")
 
     except Exception as e:
-        print(f"\n❌ 程序运行崩溃: {str(e)}")
+        print(f"\n🔥 发生严重错误: {e}")
         import traceback
         traceback.print_exc()
 
     finally:
-        # --- 核心逻辑：无论成功失败，必须关闭浏览器进程 ---
+        # 停止监听协程
+        interrupt_task.cancel()
+        
+        # 5. 强制清理浏览器环境
         print("\n" + "·" * 40)
-        print("🧹 正在清理浏览器环境，关闭 CDP 会话并终止进程...")
+        print("🧹 正在执行环境清理...")
         try:
-            # 强制杀掉浏览器进程，释放容器或本地端口
             await kill_browser_session()
-            print("✅ 浏览器已安全关闭。")
-        except Exception as cleanup_err:
-            print(f"⚠️ 清理浏览器时出现错误: {cleanup_err}")
+            print("✨ 浏览器进程已安全终止。")
+        except Exception as err:
+            print(f"❌ 清理失败: {err}")
         print("·" * 40 + "\n")
 
-    # 7. 可视化提示
+    # 6. 结果展示
     if current_trace_id:
-        print("=" * 60)
-        print("可视化 Step Tree:")
-        print("=" * 60)
-        print("1. 启动 API Server: python3 api_server.py")
-        print(f"2. 访问: http://localhost:8000/api/traces")
-        print(f"3. Trace ID: {current_trace_id}")
-        print("=" * 60)
+        print(f"🔍 任务 Trace ID: {current_trace_id}")
+        print(f"📊 访问可视化面板查看详情。")
 
 if __name__ == "__main__":
     try:
         asyncio.run(main())
     except KeyboardInterrupt:
-        print("\n🛑 用户手动终止 (KeyboardInterrupt)，正在强制退出...")
+        print("\n👋 收到退出信号，程序已停止。")

examples/research/test.prompt

@@ -7,4 +7,4 @@ $system$
 你是最顶尖的AI助手，可以拆分并调用工具逐步解决复杂问题。
 
 $user$
-去zh.zlib.li网页找一些构图相关的书（可以用load_cookies登录），并下载下来。
+去网页上搜索一些关于摄影的内容和文章，并且下载一些下来。(执行前调用get_experience工具来作为参考)

examples/test_cache/run.py

@@ -0,0 +1,128 @@
+"""
+测试 Prompt Caching 功能
+"""
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+# 添加项目根目录到 Python 路径
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from dotenv import load_dotenv
+load_dotenv()
+
+import logging
+# 开启 DEBUG 日志查看缓存标记
+logging.basicConfig(level=logging.DEBUG)
+
+from agent.core.runner import AgentRunner, RunConfig
+from agent.trace import FileSystemTraceStore, Trace, Message
+from agent.llm import create_openrouter_llm_call
+
+async def main():
+    print("=" * 60)
+    print("测试 Prompt Caching 功能")
+    print("=" * 60)
+    print()
+
+    # 路径配置
+    base_dir = Path(__file__).parent
+    project_root = base_dir.parent.parent
+    trace_dir = project_root / ".trace"
+
+    # 创建 Runner
+    runner = AgentRunner(
+        trace_store=FileSystemTraceStore(base_path=str(trace_dir)),
+        llm_call=create_openrouter_llm_call(model="anthropic/claude-sonnet-4.5"),
+        debug=True
+    )
+
+    # 准备测试消息（足够长的 system prompt）
+    system_prompt = """你是一个专业的 AI 助手。
+
+## 核心能力
+- 代码分析和生成
+- 问题解决和调试
+- 技术文档编写
+- 架构设计建议
+
+## 工作原则
+1. 准确性优先：确保提供的信息和代码是正确的
+2. 清晰表达：用简洁明了的语言解释复杂概念
+3. 实用导向：提供可直接使用的解决方案
+4. 持续学习：根据反馈不断改进
+
+## 技术栈
+- Python, JavaScript, TypeScript
+- React, Vue, Node.js
+- Docker, Kubernetes
+- PostgreSQL, MongoDB, Redis
+- AWS, GCP, Azure
+
+这是一个足够长的 system prompt，用于测试 Anthropic Prompt Caching 功能。
+缓存需要至少 1024 tokens 才能生效，所以我们需要让这个 prompt 足够长。
+""" * 3  # 重复 3 次确保足够长
+
+    messages = [
+        {"role": "user", "content": "请简单介绍一下 Python 的特点，用 3 句话概括"}
+    ]
+
+    print("第一次调用（创建缓存）...")
+    print("-" * 60)
+
+    trace_id = None
+    iteration = 0
+
+    async for item in runner.run(
+        messages=messages,
+        config=RunConfig(
+            system_prompt=system_prompt,
+            model="anthropic/claude-sonnet-4.5",
+            temperature=0.3,
+            max_iterations=3,
+            enable_prompt_caching=True,  # 启用缓存
+            name="缓存测试"
+        )
+    ):
+        if isinstance(item, Trace):
+            trace_id = item.trace_id
+            if item.status == "completed":
+                print(f"\n✓ Trace 完成")
+                print(f"  Total tokens: {item.total_tokens}")
+                print(f"  Total cost: ${item.total_cost:.6f}")
+
+        elif isinstance(item, Message):
+            if item.role == "assistant":
+                iteration += 1
+                print(f"\n[Iteration {iteration}]")
+                print(f"  Prompt tokens: {item.prompt_tokens}")
+                print(f"  Completion tokens: {item.completion_tokens}")
+                print(f"  Cache creation: {item.cache_creation_tokens}")
+                print(f"  Cache read: {item.cache_read_tokens}")
+                print(f"  Cost: ${item.cost:.6f}")
+
+                content = item.content
+                if isinstance(content, dict):
+                    text = content.get("text", "")
+                    if text:
+                        preview = text[:100] + "..." if len(text) > 100 else text
+                        print(f"  Response: {preview}")
+
+    print()
+    print("=" * 60)
+    print("测试完成")
+    print("=" * 60)
+    print()
+
+    if trace_id:
+        print("验证要点：")
+        print("1. 第一次调用应该有 cache_creation_tokens > 0")
+        print("2. 后续调用应该有 cache_read_tokens > 0")
+        print("3. cache_read_tokens 的成本应该是正常 input tokens 的 10%")
+        print()
+        print(f"Trace ID: {trace_id}")
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/test_cache/run_multi.py

@@ -0,0 +1,138 @@
+"""
+测试多轮对话的 Prompt Caching
+"""
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from dotenv import load_dotenv
+load_dotenv()
+
+from agent.core.runner import AgentRunner, RunConfig
+from agent.trace import FileSystemTraceStore, Trace, Message
+from agent.llm import create_openrouter_llm_call
+
+async def main():
+    print("=" * 60)
+    print("测试多轮对话 Prompt Caching")
+    print("=" * 60)
+    print()
+
+    base_dir = Path(__file__).parent
+    project_root = base_dir.parent.parent
+    trace_dir = project_root / ".trace"
+
+    runner = AgentRunner(
+        trace_store=FileSystemTraceStore(base_path=str(trace_dir)),
+        llm_call=create_openrouter_llm_call(model="anthropic/claude-sonnet-4.5"),
+        debug=True
+    )
+
+    # 超长 system prompt 确保 >1024 tokens
+    system_prompt = """你是一个专业的 AI 助手，专注于帮助用户解决技术问题。
+
+## 核心能力
+- 代码分析和生成
+- 问题解决和调试
+- 技术文档编写
+- 架构设计建议
+- 性能优化建议
+- 安全审计
+
+## 工作原则
+1. 准确性优先：确保提供的信息和代码是正确的
+2. 清晰表达：用简洁明了的语言解释复杂概念
+3. 实用导向：提供可直接使用的解决方案
+4. 持续学习：根据反馈不断改进
+5. 安全意识：始终考虑安全性和最佳实践
+6. 性能考虑：提供高效的解决方案
+
+## 技术栈
+- 编程语言：Python, JavaScript, TypeScript, Go, Rust, Java
+- 前端框架：React, Vue, Angular, Svelte
+- 后端框架：Node.js, Django, Flask, FastAPI, Spring Boot
+- 数据库：PostgreSQL, MongoDB, Redis, MySQL, Elasticsearch
+- 云平台：AWS, GCP, Azure
+- DevOps：Docker, Kubernetes, CI/CD, Terraform
+- 机器学习：TensorFlow, PyTorch, scikit-learn
+
+## 响应格式
+- 提供清晰的步骤说明
+- 包含代码示例
+- 解释关键概念
+- 指出潜在问题
+- 给出最佳实践建议
+
+这是一个足够长的 system prompt，用于测试 Anthropic Prompt Caching 功能。
+缓存需要至少 1024 tokens 才能生效，所以我们需要让这个 prompt 足够长。
+""" * 5  # 重复 5 次确保足够长
+
+    messages = [
+        {"role": "user", "content": "请用一句话介绍 Python"}
+    ]
+
+    print("开始多轮对话测试...")
+    print("-" * 60)
+
+    trace_id = None
+    iteration = 0
+
+    async for item in runner.run(
+        messages=messages,
+        config=RunConfig(
+            system_prompt=system_prompt,
+            model="anthropic/claude-sonnet-4.5",
+            temperature=0.3,
+            max_iterations=5,  # 多轮对话
+            enable_prompt_caching=True,
+            name="多轮缓存测试"
+        )
+    ):
+        if isinstance(item, Trace):
+            trace_id = item.trace_id
+            if item.status == "completed":
+                print(f"\n✓ Trace 完成")
+                print(f"  Total messages: {item.total_messages}")
+                print(f"  Total tokens: {item.total_tokens}")
+                print(f"  Total cache creation: {item.total_cache_creation_tokens}")
+                print(f"  Total cache read: {item.total_cache_read_tokens}")
+                print(f"  Total cost: ${item.total_cost:.6f}")
+
+        elif isinstance(item, Message):
+            if item.role == "assistant":
+                iteration += 1
+                print(f"\n[Iteration {iteration}]")
+                print(f"  Prompt tokens: {item.prompt_tokens}")
+                print(f"  Completion tokens: {item.completion_tokens}")
+                print(f"  Cache creation: {item.cache_creation_tokens}")
+                print(f"  Cache read: {item.cache_read_tokens}")
+                print(f"  Cost: ${item.cost:.6f}")
+
+                content = item.content
+                if isinstance(content, dict):
+                    text = content.get("text", "")
+                    tool_calls = content.get("tool_calls")
+                    if text and not tool_calls:
+                        preview = text[:80] + "..." if len(text) > 80 else text
+                        print(f"  Response: {preview}")
+                    if tool_calls:
+                        print(f"  Tool calls: {len(tool_calls)}")
+
+    print()
+    print("=" * 60)
+    print("测试完成")
+    print("=" * 60)
+    print()
+
+    if trace_id:
+        print("分析：")
+        print("- 第 1 次调用：应该有 cache_creation_tokens > 0（创建缓存）")
+        print("- 第 2+ 次调用：应该有 cache_read_tokens > 0（命中缓存）")
+        print(f"\nTrace ID: {trace_id}")
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/test_cache/run_same_trace.py

@@ -0,0 +1,259 @@
+"""
+在同一个 Trace 内测试 Prompt Caching
+
+测试场景：
+1. 第一轮对话：创建缓存（system prompt + 工具定义）
+2. 第二轮对话：命中缓存（system prompt + 工具定义 + 第一轮历史）
+3. 第三轮对话：命中更多缓存（system prompt + 工具定义 + 前两轮历史）
+"""
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from dotenv import load_dotenv
+load_dotenv()
+
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+from agent.core.runner import AgentRunner, RunConfig
+from agent.trace import FileSystemTraceStore, Trace, Message
+from agent.llm import create_openrouter_llm_call
+
+async def main():
+    print("=" * 60)
+    print("同一 Trace 内的 Prompt Caching 测试")
+    print("=" * 60)
+    print()
+
+    base_dir = Path(__file__).parent
+    project_root = base_dir.parent.parent
+    trace_dir = project_root / ".trace"
+
+    runner = AgentRunner(
+        trace_store=FileSystemTraceStore(base_path=str(trace_dir)),
+        llm_call=create_openrouter_llm_call(model="anthropic/claude-sonnet-4.5"),
+        debug=True
+    )
+
+    # 构造 >1500 tokens 的稳定前缀
+    stable_prefix = """你是一个专业的 AI 技术顾问，专注于软件工程和系统架构。
+
+## 核心专业领域
+
+### 1. 编程语言与框架
+- **Python**: Django, Flask, FastAPI, Celery, SQLAlchemy, Pandas, NumPy
+- **JavaScript/TypeScript**: React, Vue, Angular, Node.js, Express, NestJS
+- **Go**: Gin, Echo, gRPC, Cobra
+- **Rust**: Actix, Rocket, Tokio
+- **Java**: Spring Boot, Hibernate, Maven, Gradle
+
+### 2. 数据库技术
+- **关系型数据库**: PostgreSQL, MySQL, Oracle, SQL Server
+- **NoSQL 数据库**: MongoDB, Redis, Cassandra, DynamoDB
+- **时序数据库**: InfluxDB, TimescaleDB
+- **图数据库**: Neo4j, ArangoDB
+- **搜索引擎**: Elasticsearch, Solr
+
+### 3. 云平台与基础设施
+- **AWS**: EC2, S3, Lambda, RDS, DynamoDB, CloudFormation, ECS, EKS
+- **GCP**: Compute Engine, Cloud Storage, Cloud Functions, BigQuery, GKE
+- **Azure**: Virtual Machines, Blob Storage, Functions, Cosmos DB, AKS
+- **容器化**: Docker, Docker Compose, Podman
+- **编排**: Kubernetes, Helm, Istio, Linkerd
+
+### 4. DevOps 与 CI/CD
+- **版本控制**: Git, GitHub, GitLab, Bitbucket
+- **CI/CD**: Jenkins, GitLab CI, GitHub Actions, CircleCI, Travis CI
+- **配置管理**: Ansible, Terraform, Puppet, Chef
+- **监控告警**: Prometheus, Grafana, ELK Stack, Datadog, New Relic
+- **日志管理**: Fluentd, Logstash, Loki
+
+### 5. 架构模式
+- **微服务架构**: 服务拆分、API 网关、服务发现、熔断降级
+- **事件驱动架构**: 消息队列、事件溯源、CQRS
+- **Serverless 架构**: FaaS、BaaS、无服务器框架
+- **分布式系统**: CAP 理论、一致性协议、分布式事务
+- **高可用设计**: 负载均衡、故障转移、灾备恢复
+
+### 6. 安全最佳实践
+- **认证授权**: OAuth 2.0, JWT, SAML, OpenID Connect
+- **加密技术**: TLS/SSL, AES, RSA, 哈希算法
+- **安全审计**: 漏洞扫描、渗透测试、安全合规
+- **数据保护**: 数据脱敏、访问控制、审计日志
+
+### 7. 性能优化
+- **缓存策略**: Redis, Memcached, CDN, 浏览器缓存
+- **数据库优化**: 索引设计、查询优化、分库分表
+- **代码优化**: 算法复杂度、并发编程、异步处理
+- **系统调优**: 负载测试、性能分析、资源监控
+
+### 8. 机器学习与 AI
+- **深度学习框架**: TensorFlow, PyTorch, Keras
+- **模型部署**: TensorFlow Serving, TorchServe, ONNX
+- **MLOps**: MLflow, Kubeflow, SageMaker
+- **自然语言处理**: Transformers, BERT, GPT, LangChain
+
+## 工作原则
+
+1. **准确性优先**: 提供经过验证的技术方案，避免误导
+2. **实用导向**: 给出可直接应用的代码示例和配置
+3. **最佳实践**: 遵循行业标准和社区共识
+4. **安全意识**: 始终考虑安全性和隐私保护
+5. **性能考虑**: 关注系统性能和资源效率
+6. **可维护性**: 代码清晰、文档完善、易于扩展
+7. **成本意识**: 平衡技术方案与成本投入
+
+## 响应格式
+
+### 问题分析
+- 理解用户需求和上下文
+- 识别关键技术挑战
+- 评估可行性和风险
+
+### 解决方案
+- 提供清晰的实现步骤
+- 包含完整的代码示例
+- 解释关键技术点
+- 指出潜在问题和注意事项
+
+### 最佳实践建议
+- 性能优化建议
+- 安全加固措施
+- 可扩展性考虑
+- 运维监控方案
+
+### 替代方案
+- 列出其他可行方案
+- 对比优缺点
+- 给出选择建议
+
+## 技术栈版本参考
+
+- Python: 3.11+
+- Node.js: 20 LTS
+- PostgreSQL: 15+
+- Redis: 7+
+- Kubernetes: 1.28+
+- Docker: 24+
+
+这是一个足够长且稳定的 system prompt，用于测试 Anthropic Prompt Caching。
+此内容在所有请求中保持完全一致，以确保缓存能够命中。
+Version: 3.0
+""" * 2  # 重复 2 次，确保 >1500 tokens
+
+    print(f"System prompt 长度: {len(stable_prefix)} 字符")
+    print(f"预估 tokens: ~{len(stable_prefix) // 4}")
+    print()
+
+    trace_id = None
+
+    # 第一轮对话
+    print("=" * 60)
+    print("第 1 轮对话：创建缓存")
+    print("=" * 60)
+
+    async for item in runner.run(
+        messages=[{"role": "user", "content": "请用一句话介绍 Python"}],
+        config=RunConfig(
+            system_prompt=stable_prefix,
+            model="anthropic/claude-sonnet-4.5",
+            temperature=0.3,
+            max_iterations=1,
+            enable_prompt_caching=True,
+            name="同一Trace缓存测试"
+        )
+    ):
+        if isinstance(item, Trace):
+            trace_id = item.trace_id
+            if item.status == "completed":
+                print(f"\n✓ 第 1 轮完成")
+                print(f"  Total tokens: {item.total_tokens}")
+                print(f"  Cache write: {item.total_cache_creation_tokens}")
+                print(f"  Cache read: {item.total_cache_read_tokens}")
+                print(f"  Cost: ${item.total_cost:.6f}")
+        elif isinstance(item, Message) and item.role == "assistant":
+            print(f"\n[Response] {item.content.get('text', '')[:100]}...")
+            print(f"  Prompt tokens: {item.prompt_tokens}")
+            print(f"  Cache write: {item.cache_creation_tokens}")
+            print(f"  Cache read: {item.cache_read_tokens}")
+
+    print("\n等待 2 秒...")
+    await asyncio.sleep(2)
+
+    # 第二轮对话（续跑同一个 trace）
+    print("\n" + "=" * 60)
+    print("第 2 轮对话：应该命中缓存（system + 第1轮历史）")
+    print("=" * 60)
+
+    async for item in runner.run(
+        messages=[{"role": "user", "content": "请用一句话介绍 JavaScript"}],
+        config=RunConfig(
+            trace_id=trace_id,  # 续跑同一个 trace
+            system_prompt=stable_prefix,
+            model="anthropic/claude-sonnet-4.5",
+            temperature=0.3,
+            max_iterations=1,
+            enable_prompt_caching=True,
+        )
+    ):
+        if isinstance(item, Trace) and item.status == "completed":
+            print(f"\n✓ 第 2 轮完成")
+            print(f"  Total tokens: {item.total_tokens}")
+            print(f"  Cache write: {item.total_cache_creation_tokens}")
+            print(f"  Cache read: {item.total_cache_read_tokens}")
+            print(f"  Cost: ${item.total_cost:.6f}")
+        elif isinstance(item, Message) and item.role == "assistant":
+            print(f"\n[Response] {item.content.get('text', '')[:100]}...")
+            print(f"  Prompt tokens: {item.prompt_tokens}")
+            print(f"  Cache write: {item.cache_creation_tokens}")
+            print(f"  Cache read: {item.cache_read_tokens}")
+
+    print("\n等待 2 秒...")
+    await asyncio.sleep(2)
+
+    # 第三轮对话（续跑同一个 trace）
+    print("\n" + "=" * 60)
+    print("第 3 轮对话：应该命中更多缓存（system + 前2轮历史）")
+    print("=" * 60)
+
+    async for item in runner.run(
+        messages=[{"role": "user", "content": "请用一句话介绍 Go"}],
+        config=RunConfig(
+            trace_id=trace_id,  # 续跑同一个 trace
+            system_prompt=stable_prefix,
+            model="anthropic/claude-sonnet-4.5",
+            temperature=0.3,
+            max_iterations=1,
+            enable_prompt_caching=True,
+        )
+    ):
+        if isinstance(item, Trace) and item.status == "completed":
+            print(f"\n✓ 第 3 轮完成")
+            print(f"  Total tokens: {item.total_tokens}")
+            print(f"  Cache write: {item.total_cache_creation_tokens}")
+            print(f"  Cache read: {item.total_cache_read_tokens}")
+            print(f"  Cost: ${item.total_cost:.6f}")
+        elif isinstance(item, Message) and item.role == "assistant":
+            print(f"\n[Response] {item.content.get('text', '')[:100]}...")
+            print(f"  Prompt tokens: {item.prompt_tokens}")
+            print(f"  Cache write: {item.cache_creation_tokens}")
+            print(f"  Cache read: {item.cache_read_tokens}")
+
+    print("\n" + "=" * 60)
+    print("测试完成")
+    print("=" * 60)
+    print()
+    print("预期结果：")
+    print("- 第 1 轮：cache_write > 0（创建缓存）")
+    print("- 第 2 轮：cache_read > 0（命中 system prompt 缓存）")
+    print("- 第 3 轮：cache_read 更大（命中 system + 历史消息缓存）")
+    print()
+    print(f"Trace ID: {trace_id}")
+
+if __name__ == "__main__":
+    asyncio.run(main())