feat(trace): 将 after_sequence 参数改为 after_message_id

- 在 run API 中将 after_sequence 整数参数改为 after_message_id 字符串参数，提高接口易用性
- 新增 _parse_sequence_from_message_id 函数从 message_id 解析 sequence
- 更新文档和示例代码以反映此变更
- 新增增强版示例脚本，支持交互式暂停、干预消息插入和经验总结

agent/trace/run_api.py

@@ -73,9 +73,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 +271,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 +299,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 +311,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",

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/how/run.py

@@ -0,0 +1,503 @@
+"""
+示例（增强版）
+
+使用 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.trace import (
+    FileSystemTraceStore,
+    Trace,
+    Message,
+)
+from agent.llm import create_yescode_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
+
+
+# ===== 交互菜单 =====
+
+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. 继续执行")
+    print("  5. 停止执行")
+    print("=" * 60)
+
+    while True:
+        choice = input("请输入选项 (1-5): ").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继续执行...")
+            return {"action": "continue"}
+
+        elif choice == "5":
+            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 / "test.prompt"
+    output_dir = base_dir / "output_1"
+    output_dir.mkdir(exist_ok=True)
+
+    # Skills 目录（可选：用户自定义 skills）
+    # 注意：内置 skills（agent/skills/core.md）会自动加载
+    skills_dir = None  # 或者指定自定义 skills 目录，如: project_root / "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')}")
+
+    store = FileSystemTraceStore(base_path=".trace")
+    runner = AgentRunner(
+        trace_store=store,
+        llm_call=create_yescode_llm_call(model=f"claude-{prompt.config.get('model', 'sonnet-4.5')}"),
+        skills_dir=skills_dir,
+        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="mcp/skills 发现、获取、评价 分析任务",
+            )
+
+        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/test.prompt

@@ -0,0 +1,14 @@
+---
+model: sonnet-4.6
+temperature: 0.3
+---
+
+$system$
+你是最顶尖的AI助手，可以拆分并调用工具逐步解决复杂问题。
+
+$user$
+帮我调研一下现在有哪些优质的agent skills以及mcp；以及可以通过哪些渠道发现/评估/获取它们。
+- 要有可靠的依据（例如行业大牛的博客、榜单等等），要尽量全面，而不是随便选择一个平台深入
+- 我希望你在需要时能够打开浏览器做调研，并将调研收获在 examples/tool_research/knowledge/ 目录下组织维护好，注意保留原始来源的URL
+- 调研过程中注意记录，以免意外中止时候失去所有进展；过程结果和最终结果要清晰整理好
+- **禁止降级解决**：不允许为了方便而使用效果显著更差的简单方案。你应该拆解子目标逐步完成，或者转交给sub agent解决某一项适合拆分的子任务