agentchat-task-agent 0.1.0__py3-none-any.whl

task_agent/nodes.py

@@ -0,0 +1,394 @@
+"""自主任务 Agent 的图节点（通过 Runtime 闭包注入配置/LLM/执行器）。
+
+- plan_node           ：LLM 把目标拆成子任务列表（fixed 一期）；
+- execute_node        ：对当前子任务调用一次 executor（fixed 一期；顺序、含失败标记）；
+- final_node          ：整合所有子任务结果，输出最终交付；
+- replan_node         ：每步动态决定下一步动作 + 标注信息来源（replan 二期）；
+- execute_action_node ：按来源路由执行当前动作（调用注入的 Executor）；
+- check_node          ：判断是否充分达成目标；
+- verify_node         ：子任务失败后的自检（是否值得重试）——节点容错；
+- human_confirm_node  ：节点级 HITL——让用户确认/编辑/跳过下一步动作（可关）。
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
+
+from langgraph.types import interrupt
+
+from task_agent.config import TaskAgentConfig
+from task_agent.executor import SOURCE_KEYS, ExecuteRequest, Executor
+from task_agent.llm import LLMFactory, llm_text
+from task_agent.memory import TaskMemory
+from task_agent.prompts import (
+    CHECK_PROMPT,
+    COMPRESS_PROMPT,
+    FINAL_PROMPT,
+    PLAN_PROMPT,
+    REPLAN_PROMPT,
+    VERIFY_PROMPT,
+)
+
+
+@dataclass(frozen=True)
+class Runtime:
+    """构建图时注入的运行上下文（配置 + LLM 工厂 + 执行器 + checkpointer 提供者 + 事件回调）。"""
+
+    config: TaskAgentConfig
+    llm_factory: LLMFactory
+    executor: Executor
+    checkpointer_provider: Callable[[], Any | None] = lambda: None
+    on_event: Callable[[str, dict], None] | None = None
+    memory: TaskMemory | None = None
+
+    def emit(self, kind: str, data: dict | None = None) -> None:
+        """发事件（如 plan/replan/execute/check/verify/final/hitl），供宿主/日志观测。"""
+        if self.on_event is not None:
+            self.on_event(kind, data or {})
+
+
+Node = Callable[[dict], Awaitable[dict]]
+
+
+def make_nodes(runtime: Runtime) -> dict[str, Node]:
+    """按 Runtime 生成全部节点（闭包注入，避免全局可变状态）。"""
+    config = runtime.config
+
+    async def plan_node(state: dict) -> dict:
+        mem = await _memory_ctx(runtime, state["goal"])
+        plan = _parse_plan(
+            await llm_text(
+                runtime.llm_factory(),
+                PLAN_PROMPT.format(goal=state["goal"], memory=mem),
+            )
+        )
+        fallback = False
+        if not plan:
+            fallback = True
+            plan = [
+                {
+                    "id": "1",
+                    "desc": "请直接回答：" + state["goal"],
+                    "status": "pending",
+                    "result": "",
+                }
+            ]
+        runtime.emit("plan", {"subtasks": len(plan), "fallback": fallback})
+        return {"plan": plan, "current_idx": 0, "findings": []}
+
+    async def execute_node(state: dict) -> dict:
+        idx = state["current_idx"]
+        plan = [dict(p) for p in state["plan"]]
+        if idx >= len(plan):
+            return {"current_idx": idx}
+        task = plan[idx]
+        try:
+            result = await runtime.executor(
+                ExecuteRequest(action=task["desc"], source="default")
+            )
+            finding = (result.answer or "（子任务无输出）")[:800]
+            ok = bool(finding and finding.strip() and finding != "（子任务无输出）")
+            plan[idx]["status"] = "done" if ok else "failed"
+        except Exception as exc:  # noqa: BLE001 - 单子任务失败不中断整个任务
+            finding = f"子任务失败：{exc}"
+            plan[idx]["status"] = "failed"
+            ok = False
+        plan[idx]["result"] = finding
+        runtime.emit("execute", {"subtask": task["desc"], "ok": ok})
+        out: dict = {"plan": plan, "current_idx": idx + 1}
+        out.update(await _append_finding(runtime, state, finding))
+        return out
+
+    async def final_node(state: dict) -> dict:
+        goal = state["goal"]
+        findings = "\n\n".join(
+            f"[{i + 1}] {f[:400]}"
+            for i, f in enumerate(state.get("findings", []))
+        )
+        summary = state.get("findings_summary") or ""
+        if summary:
+            findings = f"历史摘要：{summary}\n\n{findings}"
+        final = (
+            await llm_text(
+                runtime.llm_factory(),
+                FINAL_PROMPT.format(goal=goal, findings=findings or "（无）"),
+            )
+        ).strip()
+        if runtime.memory is not None:
+            try:
+                await runtime.memory.remember(goal, final)
+            except Exception:  # noqa: BLE001 - 记忆失败不影响交付
+                pass
+        runtime.emit("final", {"answer": final})
+        return {"final_answer": final}
+
+    async def replan_node(state: dict) -> dict:
+        goal = state["goal"]
+        findings = state.get("findings") or []
+        mem = await _memory_ctx(runtime, goal)
+        action, source = _parse_next_action(
+            await llm_text(
+                runtime.llm_factory(),
+                REPLAN_PROMPT.format(
+                    goal=goal,
+                    findings=_fmt_findings(findings) or "（尚无）",
+                    memory=mem,
+                ),
+            )
+        )
+        if not action:
+            # 无下一步 → 视为可完成
+            runtime.emit("replan", {"action": "", "source": source})
+            return {"current_action": "", "done": True, "retries": 0}
+        runtime.emit("replan", {"action": action, "source": source})
+        return {"current_action": action, "expected_source": source, "retries": 0}
+
+    async def execute_action_node(state: dict) -> dict:
+        action = state.get("current_action") or ""
+        retries = int(state.get("retries") or 0)
+        is_retry = retries > 0
+        if not action:
+            # 空动作：跳过执行只推进步数
+            return {"step": int(state.get("step") or 0) + 1}
+        try:
+            result = await runtime.executor(
+                ExecuteRequest(
+                    action=action,
+                    source=state.get("expected_source") or "default",
+                )
+            )
+            finding = (result.answer or "（子任务无输出）")[:800]
+            # 空答案视为失败：否则 verify 判重试后 retries 又被归零，形成无限循环
+            ok = bool(finding and finding.strip() and finding != "（子任务无输出）")
+            new_retries = 0 if ok else retries
+        except Exception as exc:  # noqa: BLE001 - 单步失败不中断
+            finding = f"子任务失败：{exc}"
+            new_retries = retries  # 失败 → 保留计数(由 verify 决定是否 +1 / 放弃)
+            ok = False
+        step = int(state.get("step") or 0) + (0 if is_retry else 1)
+        runtime.emit("execute", {"action": action, "source": state.get("expected_source") or "default", "ok": ok})
+        out: dict = {"step": step, "retries": new_retries}
+        out.update(await _append_finding(runtime, state, finding))
+        return out
+
+    async def check_node(state: dict) -> dict:
+        step = int(state.get("step") or 0)
+        if step >= config.max_steps:
+            return {"done": True}
+        goal = state["goal"]
+        findings = state.get("findings") or []
+        done = _parse_done(
+            await llm_text(
+                runtime.llm_factory(),
+                CHECK_PROMPT.format(
+                    goal=goal, findings=_fmt_findings(findings) or "（尚无）"
+                ),
+            )
+        )
+        runtime.emit("check", {"done": done, "step": step})
+        return {"done": done}
+
+    async def verify_node(state: dict) -> dict:
+        goal = state["goal"]
+        action = state.get("current_action") or ""
+        findings = state.get("findings") or []
+        finding = findings[-1] if findings else ""
+        retries = int(state.get("retries") or 0)
+        if retries >= config.max_retries:
+            return {"should_retry": False, "retries": retries}
+        data = _jump_json(
+            await llm_text(
+                runtime.llm_factory(),
+                VERIFY_PROMPT.format(
+                    goal=goal,
+                    action=action,
+                    finding=finding,
+                    findings=_fmt_findings(findings) or "（无）",
+                ),
+            )
+        )
+        retry = bool(data.get("retry", False))
+        runtime.emit("verify", {"retry": retry, "retries": retries + 1 if retry else retries})
+        if retry:
+            return {"should_retry": True, "retries": retries + 1}
+        return {"should_retry": False, "retries": 0}
+
+    async def human_confirm_node(state: dict) -> dict:
+        """节点级 HITL：replan 产出下一步后让用户确认/编辑/跳过。
+
+        - 关闭(config.hitl=False) → 透传 proceed,不 interrupt；
+        - 开启 → interrupt 暂停,宿主经 resume(decision) 恢复；
+        - 依赖 checkpointer 持久化；无 checkpointer 时禁用，避免中断后无法恢复
+          → 降级为全自主(与关闭 HITL 一致)。
+        """
+        if not config.hitl:
+            return {"_confirm_verb": "proceed"}
+        if runtime.checkpointer_provider() is None:
+            return {"_confirm_verb": "proceed"}
+        runtime.emit(
+            "hitl",
+            {
+                "next_action": state.get("current_action") or "",
+                "expected_source": state.get("expected_source") or "default",
+                "step": state.get("step") or 0,
+            },
+        )
+        decision = interrupt(
+            {
+                "type": "task_confirm",
+                "goal": state.get("goal", ""),
+                "next_action": state.get("current_action") or "",
+                "expected_source": state.get("expected_source") or "default",
+                "step": state.get("step") or 0,
+                "findings": state.get("findings") or [],
+            }
+        )
+        return _apply_confirm(
+            decision,
+            state.get("current_action") or "",
+            state.get("expected_source") or "default",
+        )
+
+    return {
+        "plan_node": plan_node,
+        "execute_node": execute_node,
+        "final_node": final_node,
+        "replan_node": replan_node,
+        "execute_action_node": execute_action_node,
+        "check_node": check_node,
+        "verify_node": verify_node,
+        "human_confirm_node": human_confirm_node,
+    }
+
+
+# ---------------- 纯函数辅助（便于单测） ----------------
+
+
+def _parse_plan(text: str) -> list[dict]:
+    """从 LLM 输出解析子任务数组；失败返回空（由下游标记为空计划）。"""
+    s = text.strip()
+    if s.startswith("```"):
+        s = "\n".join(l for l in s.splitlines() if not l.strip().startswith("```"))
+    try:
+        begin, end = s.index("["), s.rindex("]")
+        data = json.loads(s[begin : end + 1])
+    except (ValueError, json.JSONDecodeError):
+        return []
+    out = []
+    for i, item in enumerate(data or []):
+        if isinstance(item, dict) and item.get("desc"):
+            out.append(
+                {
+                    "id": str(item.get("id") or i + 1),
+                    "desc": item["desc"],
+                    "status": "pending",
+                    "result": "",
+                }
+            )
+    return out
+
+
+def _fmt_findings(findings: list[str]) -> str:
+    """把结果列表格式化为 replan/check 的上下文文本(截断)。"""
+    return "\n\n".join(
+        f"[{i + 1}] {f[:400]}" for i, f in enumerate(findings or [])
+    )
+
+
+async def _compress_findings(
+    runtime: Runtime, findings: list[str], summary: str
+) -> tuple[list[str], str]:
+    """超预算压缩：保留最新一条，历史交给 LLM 压缩进 findings_summary。
+
+    LLM 失败时退化为截断拼接（不中断执行）。返回 (保留的 findings, 新摘要)。
+    """
+    keep = findings[-1:]
+    older = findings[:-1]
+    try:
+        text = (
+            await llm_text(
+                runtime.llm_factory(),
+                COMPRESS_PROMPT.format(
+                    summary=summary or "（无）",
+                    findings=_fmt_findings(older),
+                ),
+            )
+        ).strip()
+    except Exception:  # noqa: BLE001 - 压缩失败降级为截断
+        text = ""
+    if not text:
+        text = "；".join(older)[:500]
+    new_summary = f"{summary}；{text}" if summary else text
+    return keep, new_summary[:1500]
+
+
+async def _append_finding(runtime: Runtime, state: dict, finding: str) -> dict:
+    """构造 findings 增量：未超预算 → 普通追加；超预算 → 整体替换 + 压缩摘要。"""
+    budget = runtime.config.findings_budget
+    existing = list(state.get("findings") or [])
+    if budget is None or len(existing) + 1 <= budget:
+        return {"findings": [finding]}
+    keep, summary = await _compress_findings(
+        runtime, existing + [finding], str(state.get("findings_summary") or "")
+    )
+    return {"findings": {"_replace": keep}, "findings_summary": summary}
+
+
+async def _memory_ctx(runtime: Runtime, goal: str) -> str:
+    """把跨任务记忆召回结果格式化为提示词上下文（无记忆/失败 → （无））。"""
+    if runtime.memory is None:
+        return "（无）"
+    try:
+        items = await runtime.memory.recall(goal)
+    except Exception:  # noqa: BLE001 - 记忆不可用不影响执行
+        return "（无）"
+    return "\n".join(f"- {s}" for s in items) or "（无）"
+
+
+def _jump_json(text: str) -> dict:
+    """剥离代码围栏后提取第一个 JSON 对象。"""
+    s = (text or "").strip()
+    if s.startswith("```"):
+        s = "\n".join(l for l in s.splitlines() if not l.strip().startswith("```"))
+    try:
+        begin, end = s.index("{"), s.rindex("}")
+        data = json.loads(s[begin : end + 1])
+        return data if isinstance(data, dict) else {}
+    except (ValueError, json.JSONDecodeError):
+        return {}
+
+
+def _parse_next_action(text: str) -> tuple[str, str]:
+    data = _jump_json(text)
+    action = str(data.get("next_action", "") or "").strip()
+    source = str(data.get("expected_source", "") or "").strip().lower()
+    return action, source if source in SOURCE_KEYS else "default"
+
+
+def _parse_done(text: str) -> bool:
+    return bool(_jump_json(text).get("done", False))
+
+
+def _is_failed_finding(finding: str) -> bool:
+    """规则预筛：判断一条子任务结果是否属失败/无输出（触发 verify 自检）。"""
+    f = (finding or "").strip()
+    return not f or f.startswith("子任务失败") or f == "（子任务无输出）"
+
+
+def _apply_confirm(decision: dict, current_action: str, expected_source: str) -> dict:
+    """把 HITL 决策落到 state 增量(纯函数,便于单测)。"""
+    verb = str((decision or {}).get("verb") or "proceed").lower()
+    if verb == "edit":
+        return {
+            "_confirm_verb": "edit",
+            "current_action": str(
+                (decision or {}).get("action") or current_action or ""
+            ),
+            "expected_source": str(
+                (decision or {}).get("source") or expected_source or "default"
+            ),
+        }
+    if verb == "skip":
+        return {"_confirm_verb": "skip"}
+    return {"_confirm_verb": "proceed"}

task_agent/prompts.py

@@ -0,0 +1,120 @@
+"""自主任务 Agent 的提示词（纯函数式常量）。"""
+from __future__ import annotations
+
+PLAN_PROMPT = """你是任务规划器。把用户目标分解为 2~8 个可独立执行的子任务。
+要求：
+1. 每个子任务是一个明确的、可独立完成的问题或动作；
+2. 子任务按执行顺序排列（前面的先做）；
+3. 只输出 JSON 数组，形如：[{{"id": "1", "desc": "..."}}, ...]，不要解释。
+
+历史任务知识（仅作参考，不得编造）：
+{memory}
+
+用户目标：
+{goal}
+"""
+
+FINAL_PROMPT = """你是结果整合器。基于已完成的子任务结果，回答用户的原始目标。
+要求：
+1. 引用各子任务结果，条理清晰、结构化；
+2. 若某子任务无有效结果，明确说明；
+3. 用中文，直接给出最终答案。
+
+原始目标：
+{goal}
+
+子任务结果：
+{findings}
+"""
+REPLAN_PROMPT = """你是自主任务的执行规划器。基于原始目标与已完成的步骤结果，决定**下一步**做什么。
+可用信息来源：
+- kb：自有知识库（公司/产品/文档等内部资料）——**优先**用它；
+- db：数据库/时间/外部工具；
+- web：实时/最新资讯（联网）；
+- code：计算/代码执行。
+要求：
+1. 公司/产品/内部资料信息优先选 kb，不要联网去查真实企业；
+2. 只输出 JSON：{{"next_action": "具体下一步", "expected_source": "kb|db|web|code|default"}}；
+3. 已无必要动作时把 next_action 设为空字符串。
+
+原始目标：
+{goal}
+
+已完成的发现：
+{findings}
+
+历史任务知识（仅作参考，不得编造）：
+{memory}
+"""
+CHECK_PROMPT = """你是任务完成度检查员。判断是否已**充分达成**原始目标(可基于已有发现回答)。
+要求：只输出 JSON：{{"done": true/false}}，不要解释。
+
+原始目标：
+{goal}
+
+已有发现：
+{findings}
+"""
+VERIFY_PROMPT = """你是子任务结果的质检员。上一步子任务**失败**了,判断是否值得重试。
+规则：
+1. 失败是临时性(网络/超时/工具未就绪/偶发生成错误) → "retry": true；
+2. 失败是确定性(方法本身不可行/信息不存在/违反事实) → "retry": false；
+3. 已重试多次仍失败、换方法成本更高 → "retry": false。
+只输出 JSON：{{"retry": true/false, "reason": "一句话原因"}}，不要解释。
+
+原始目标：
+{goal}
+
+当前动作：
+{action}
+
+失败结果：
+{finding}
+
+已完成发现：
+{findings}
+"""
+
+COMPRESS_PROMPT = """你是任务执行记录的压缩器。把已完成的子任务结果压缩成一段简短摘要，保留关键事实与结论。
+要求：
+1. 中文，≤150 字；
+2. 保留数字、专名、结论，不编造新信息；
+3. 只输出摘要正文，不要解释。
+
+已有摘要：
+{summary}
+
+新结果：
+{findings}
+"""
+
+EVAL_PROMPT = """你是自主任务执行质量的评估员。根据原始目标、执行记录与最终交付，给出质量评分。
+评分维度（每项 0-5 分，只输出 JSON）：
+- goal_attainment：最终交付在多大程度上达成原始目标（0=完全未达成，5=充分达成）
+- info_completeness：关键信息是否完整（缺失关键数字/结论要扣分）
+- hallucination：交付中是否存在执行记录无法支撑的编造内容（0=无幻觉，5=严重幻觉）
+- comment：一句话评价（中文）
+
+原始目标：
+{goal}
+
+执行记录（findings）：
+{findings}
+
+最终交付：
+{final_answer}
+
+只输出 JSON：{{"goal_attainment": 0-5, "info_completeness": 0-5, "hallucination": 0-5, "comment": "..."}}
+"""
+
+TOOLCALL_PROMPT = """你是任务执行器。针对当前动作，选择调用工具或直接回答。
+可用工具：
+{tools}
+
+输出 JSON（只输出一个）：
+- 调用工具：{{"tool": "工具名", "args": {{参数名: 值}}}}
+- 直接回答：{{"answer": "回答内容"}}
+
+当前动作：
+{action}
+"""

task_agent/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561: package ships inline type hints.

task_agent/state.py

@@ -0,0 +1,36 @@
+"""自主任务 Agent 的图状态（TaskState）。"""
+from __future__ import annotations
+
+from typing import Annotated, Optional, TypedDict
+
+
+def _append_findings(a: Optional[list[str]], b: object) -> list[str]:
+    """findings 的 reducer：以增量方式合并状态（节点返回新增片段，而非每次回写全量）。
+
+    特殊值 `{"_replace": [...]}`：超预算压缩时整体替换（见 nodes._append_finding）。
+    """
+    if isinstance(b, dict) and b.get("_replace") is not None:
+        return list(b["_replace"])
+    return (a or []) + (b if isinstance(b, list) else [])
+
+
+class TaskState(TypedDict):
+    """Plan→Execute→Final 与 Replan→Execute→Check 循环的共享状态。"""
+
+    goal: str                              # 用户目标
+    # [fixed] 一次性计划：子任务列表 + 当前索引
+    plan: Optional[list[dict]]             # [{id, desc, status, result}]
+    current_idx: Optional[int]             # 当前子任务索引(fixed 用)
+    # [replan] 每步动态：当前动作 + 步数
+    current_action: Optional[str]          # 下一步执行的动作(replan 用)
+    step: Optional[int]                    # 已完成步数(replan 用)
+    done: Optional[bool]                   # check/replan 判定是否完成
+    expected_source: Optional[str]         # replan 标注的信息来源(kb/db/web/code/default)
+    # [verify 容错] 当前子任务失败后的重试次数(成功即归零,上限 MAX_RETRIES)
+    retries: Optional[int]
+    # [HITL 内部] 计划确认结果: proceed / edit / skip(仅节点内路由用,不下发)
+    _confirm_verb: Optional[str]
+    # 共有
+    findings: Annotated[list[str], _append_findings]  # 已完成结果(节点只回增量,reducer 拼接)
+    findings_summary: Optional[str]                   # 超预算压缩后的历史摘要(默认空)
+    final_answer: Optional[str]            # 最终交付

task_agent/telemetry.py

@@ -0,0 +1,45 @@
+"""可观测适配：把 on_event 接到控制台 / Langfuse（可选 extra）。"""
+from __future__ import annotations
+
+import logging
+from typing import Callable
+
+logger = logging.getLogger(__name__)
+
+EventSink = Callable[[str, dict], None]
+
+
+def console_event_sink() -> EventSink:
+    """控制台事件输出（零依赖）。"""
+
+    def sink(kind: str, data: dict) -> None:
+        print(f"[task-agent:{kind}] {data}")
+
+    return sink
+
+
+def langfuse_event_sink() -> EventSink:
+    """Langfuse span 上报（需 `task-agent[observability]`）。
+
+    未安装 / 未配置时自动降级为控制台输出，不抛错。
+    """
+    try:
+        from langfuse import Langfuse
+
+        lf = Langfuse()
+
+        def sink(kind: str, data: dict) -> None:
+            try:
+                if lf.get_current_observation_id() is None:
+                    return  # 无活动 trace 上下文，跳过以避免 Langfuse 噪音日志
+                with lf.start_as_current_observation(
+                    name=f"task_agent.{kind}", type="SPAN", input=data
+                ):
+                    pass
+            except Exception:  # noqa: BLE001 - 观测失败不影响执行
+                logger.debug("langfuse span 跳过: %s", kind, exc_info=True)
+
+        return sink
+    except Exception:  # noqa: BLE001 - 依赖缺失降级
+        logger.warning("langfuse 未安装或未配置，事件降级为控制台输出")
+        return console_event_sink()