Merge branch 'main' of https://git.yishihui.com/howard/Agent

agent/core/runner.py

@@ -531,6 +531,25 @@ class AgentRunner:
                 step_tokens = prompt_tokens + completion_tokens
                 step_cost = result.get("cost", 0)
 
+                # 按需自动创建 root goal：LLM 有 tool 调用但未主动创建目标时兜底
+                if goal_tree and not goal_tree.goals and tool_calls:
+                    has_goal_call = any(
+                        tc.get("function", {}).get("name") == "goal"
+                        for tc in tool_calls
+                    )
+                    if not has_goal_call:
+                        root_desc = goal_tree.mission[:200] if len(goal_tree.mission) > 200 else goal_tree.mission
+                        goal_tree.add_goals(
+                            descriptions=[root_desc],
+                            reasons=["系统自动创建：Agent 未显式创建目标"],
+                            parent_id=None
+                        )
+                        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])
+                        logger.info(f"自动创建 root goal: {goal_tree.goals[0].id}")
+
                 # 获取当前 goal_id
                 current_goal_id = goal_tree.current_id if (goal_tree and goal_tree.current_id) else None
 

agent/memory/skills/core.md

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

agent/trace/goal_tool.py

@@ -247,15 +247,21 @@ def create_goal_tool_schema() -> dict:
     """创建 goal 工具的 JSON Schema"""
     return {
         "name": "goal",
-        "description": """管理执行计划。
+        "description": """管理执行计划。目标工具是灵活的支持系统，帮助你组织和追踪工作进度。
 
+使用策略（按需选择）：
+- 全局规划：先规划所有目标，再逐个执行
+- 渐进规划：走一步看一步，每次只创建下一个目标
+- 动态调整：行动中随时 abandon 不可行的目标，创建新目标
+
+参数：
 - add: 添加目标（逗号分隔多个）
-- reason: 创建理由（逗号分隔多个，与 add 一一对应）。说明为什么要做这些目标。
-- after: 在指定目标后面添加（同层级）。使用目标的 ID。
-- under: 为指定目标添加子目标。使用目标的 ID。如已有子目标，追加到最后。
-- done: 完成当前目标，值为 summary
-- abandon: 放弃当前目标，值为原因（会触发 context 压缩）
-- focus: 切换焦点到指定目标。使用目标的 ID。
+- reason: 创建理由（逗号分隔，与 add 一一对应）
+- after: 在指定目标后面添加同级目标。使用目标 ID。
+- under: 为指定目标添加子目标。使用目标 ID。如已有子目标，追加到最后。
+- done: 完成当前目标，值为 summary（记录关键结论）
+- abandon: 放弃当前目标，值为原因
+- focus: 切换焦点到指定目标。使用目标 ID。
 
 位置控制（优先使用 after）：
 - 不指定 after/under: 添加到当前 focus 下作为子目标（无 focus 时添加到顶层）

docs/README.md

@@ -129,21 +129,29 @@ async def run(task: str, agent_type: str = "default") -> AsyncIterator[Union[Tra
 
     # 4. ReAct 循环
     for step in range(max_iterations):
-        # 注入当前计划
-        plan_text = goal_tree.to_prompt()
+        # 注入当前计划（如果有 goals）
+        if goal_tree.goals:
+            inject_plan(goal_tree.to_prompt())
 
         # 调用 LLM
         response = await llm.chat(
             messages=messages,
-            system=system_prompt + plan_text,
+            system=system_prompt,
             tools=tool_registry.to_schema()
         )
 
-        # 记录 assistant Message
+        # 按需自动创建 root goal：LLM 有 tool 调用但未主动创建目标时兜底
+        if not goal_tree.goals and response.tool_calls:
+            if "goal" not in [tc.name for tc in response.tool_calls]:
+                goal_tree.add_goals([mission[:200]])
+                goal_tree.focus(goal_tree.goals[0].id)
+
+        # 记录 assistant Message（goal_id = goal_tree.current_id）
         await store.add_message(Message.create(
             trace_id=trace.trace_id,
             role="assistant",
             sequence=next_seq,
+            goal_id=goal_tree.current_id,
             content=response
         ))
         yield assistant_msg
@@ -159,6 +167,7 @@ async def run(task: str, agent_type: str = "default") -> AsyncIterator[Union[Tra
                 trace_id=trace.trace_id,
                 role="tool",
                 sequence=next_seq,
+                goal_id=goal_tree.current_id,
                 content=result
             ))
             yield tool_msg
@@ -297,7 +306,7 @@ class Message:
     trace_id: str
     role: Literal["system", "user", "assistant", "tool"]
     sequence: int                            # 全局顺序
-    goal_id: Optional[str] = None            # 关联的 Goal ID
+    goal_id: Optional[str] = None            # 关联的 Goal ID（初始消息为 None，系统会按需自动创建 root goal 兜底）
     description: str = ""                    # 系统自动生成的摘要
     tool_call_id: Optional[str] = None
     content: Any = None

docs/decisions.md

@@ -667,3 +667,48 @@ execution trace v2.0 引入了 Blob 存储系统用于处理大输出和图片
 
 ---
 
+## Goal 按需自动创建
+
+**日期**: 2026-02-10
+
+### 问题
+
+Agent（含 sub-agent）有时不创建 goal 就直接执行工具调用，导致 message 的 goal_id 为 null。这造成：
+1. 统计信息丢失（`_update_goal_stats` 跳过 null goal_id）
+2. 可视化缺失结构（前端降级为合成 "START" 节点）
+3. LLM 缺少 context 锚点（goals 为空时不注入计划）
+
+### 方案对比
+
+| 方案 | 优点 | 缺点 |
+|------|------|------|
+| **预创建 root goal** | 保证非 null | 复杂任务多一层无意义嵌套，需要溶解逻辑 |
+| **全面接受 null** | 无改动 | 丢失统计、可视化、context 锚点 |
+| **按需自动创建** | 仅在需要时兜底，不干扰正常规划 | 首轮含 goal() 调用时该轮消息仍为 null（可接受） |
+
+### 决策
+
+**选择：按需自动创建 + prompt 引导**
+
+**触发条件**（三个 AND）：
+1. `goal_tree.goals` 为空（尚无任何目标）
+2. LLM 返回了 `tool_calls`（正在执行操作）
+3. `tool_calls` 中不包含 `goal()` 调用（LLM 未自行创建目标）
+
+**触发时机**：LLM 返回后、记录消息前（`runner.py` agent loop 中）
+
+**行为**：从 `goal_tree.mission` 截取前 200 字符作为 root goal description，创建并 focus。
+
+**Prompt 配合**：`core.md` 引导 LLM "先明确目标再行动"，但不强制。
+
+**实现**：`agent/core/runner.py:AgentRunner.run`
+
+### 理由
+
+1. **不干扰 LLM 自主规划**：LLM 创建目标时，树结构完全由 LLM 控制，无多余嵌套
+2. **兜底覆盖遗漏**：LLM 跳过目标直接行动时，系统自动补位
+3. **实现简单**：无需 `is_auto_root` 标记、溶解逻辑或 display ID 特殊处理
+4. **可接受的 gap**：首轮含 `goal()` 调用时该轮消息 goal_id 为 null，仅影响一轮，属于规划阶段的过渡消息
+
+---
+