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

agentchat_task_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: agentchat-task-agent
+Version: 0.1.0
+Summary: 自主任务 Agent：面向模糊长目标的多步自主执行引擎（LangGraph），零业务依赖
+Author: Zhuliqx
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Zhuliqx/task-agent
+Project-URL: Repository, https://github.com/Zhuliqx/task-agent
+Project-URL: Issues, https://github.com/Zhuliqx/task-agent/issues
+Project-URL: Changelog, https://github.com/Zhuliqx/task-agent/blob/main/CHANGELOG.md
+Keywords: llm,agent,langgraph,rag,autonomous-agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langgraph>=1.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: observability
+Requires-Dist: langfuse>=3.0; extra == "observability"
+Provides-Extra: all
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: langfuse>=3.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: pyright>=1.1; extra == "dev"
+Dynamic: license-file
+
+# 自主任务 Agent（task-agent）
+
+> 最后校验：2026-08-30（独立包；宿主集成见 Agentchat 主仓库）
+
+> 独立的**长任务自主执行器**：接收模糊复杂目标 → LLM 分解 / 每步重规划 → 循环执行（注入 Executor）→ 结构化交付。
+> 零业务依赖的独立 Python 包；宿主应用通过适配器注入 LLM / Checkpointer / 每步执行器。
+
+## 一句话
+
+面向"**模糊长目标**"的 Agentic 编排：把 LangGraph 的**交互式 HITL / 容错 / 时间旅行 / 状态管理**组合成一套可用的自主任务引擎。
+
+## 核心能力
+
+| 能力 | 说明 |
+|------|------|
+| 每步动态重规划 | `replan`（默认）；也可 `mode="fixed"` 一次计划 |
+| 独立完成度判断 | `check` 判是否达成 + `max_steps` 防循环 |
+| 信息源感知 | replan 标注 `expected_source`(kb/db/web/code)，宿主按源收紧开关 |
+| 节点级 HITL | `interrupt` / resume，proceed/edit/skip；无 checkpointer 自动降级全自主 |
+| verify 自检重试 | 子任务失败 → LLM 判是否重试（不计步数，`max_retries` 上限） |
+| 节点级容错 | `retry_policy` + `timeout` + `error_handler`（返回 `Command`） |
+| Time Travel | `list_task_history` + `checkpoint_id` 分叉 / 重放 |
+| 状态治理 | `findings` reducer 增量合并 |
+| 工具调用执行器 | `ToolCallingExecutor` + 内置 calculator/time/random（零依赖） |
+| 跨任务记忆 | 任务结论沉淀与召回（`InMemoryMemory` 或宿主实现 `TaskMemory`） |
+
+## 安装
+
+```bash
+pip install agentchat-task-agent       # 从 PyPI 安装（发行名）
+pip install 'agentchat-task-agent[all]'  # openai + observability（Langfuse）
+# 仓库内开发：
+pip install -e .                       # 或 pip install -e <仓库路径>
+```
+
+## 快速体验（离线 demo，无需 API key）
+
+```bash
+python -m task_agent.demo
+```
+
+输出 replan 全流程的 findings 与 final_answer。设置 `TASK_AGENT_OPENAI_API_KEY`（可选 `TASK_AGENT_OPENAI_BASE_URL` / `TASK_AGENT_OPENAI_MODEL`）后自动切换真实 OpenAI 兼容端点。
+
+## 编程接口
+
+```python
+from task_agent import TaskAgentConfig, build_agent
+from task_agent.executor import ExecuteRequest, StepResult
+
+async def my_executor(request: ExecuteRequest) -> StepResult:
+    # 宿主在此提供真实工具能力（检索/数据库/搜索/代码…）
+    return StepResult(answer=f"执行了 {request.action}")
+
+agent = build_agent(
+    config=TaskAgentConfig(mode="replan", hitl=True),
+    llm_factory=llm_factory,                      # Callable[[], LLM]
+    checkpointer_provider=checkpointer_provider,  # Callable[[], Any | None]
+    executor=my_executor,                         # 缺省为纯 LLM 直答
+    on_event=on_event,                            # 可选: (kind, data) 事件回调
+)
+result = await agent.ainvoke({"goal": "..."})     # -> {findings, final_answer, ...}
+```
+
+接口缝（详见 `src/task_agent/`）：
+- `TaskAgentConfig`：mode / hitl / max_retries / max_steps / llm_timeout / llm_max_retries /
+  findings_budget（findings 保留上限，超限自动压缩历史）；
+- `LLM` / `LLMFactory`：仅需 `async ainvoke(prompt)`；
+- `CheckpointerProvider`：返回 LangGraph checkpointer 或 None（无状态降级）；
+- `Executor` / `ExecuteRequest(action, source)` / `StepResult(answer)`：每步执行端口；
+- `memory`：可选跨任务记忆（`build_agent(..., memory=...)`）。
+
+## 工具调用执行器（开箱即用）
+
+不依赖宿主也能"自己干活"：`ToolCallingExecutor` 让 LLM 决定调工具或直答，内置纯计算工具
+（calculator / current_time / random_number，全部零依赖、AST 白名单求值）：
+
+```python
+from task_agent import TaskAgentConfig, build_agent
+from task_agent.tools import ToolCallingExecutor, builtin_tools
+
+agent = build_agent(
+    config=TaskAgentConfig(mode="replan", hitl=False),
+    llm_factory=llm_factory,
+    executor=ToolCallingExecutor(llm_factory, builtin_tools),
+)
+```
+
+宿主也可实现自己的 `Executor` 注入（接口缝不变）。工具声明用零依赖的 `Tool` dataclass
+（name / description / parameters / func），支持同步与异步函数。
+
+## CLI
+
+```bash
+task-agent run "介绍一下公司并计算质数和" --llm openai --tools --event --json
+task-agent run "目标" --mode fixed --findings-budget 5
+task-agent demo
+```
+
+`--llm fake`（默认）离线脚本化；`--tools` 启用内置工具；`--memory` 启用跨任务记忆；
+`--event` 打印执行过程。
+
+## 跨任务记忆
+
+`build_agent(..., memory=...)` 传入实现 `TaskMemory` 的对象：
+任务开始时按目标召回历史结论（注入 replan/plan 上下文），结束后把 `final_answer` 沉淀回记忆。
+内置 `InMemoryMemory`（关键词召回，进程内）；宿主可对接自己的 Store 实现。
+
+## 可观测
+
+`on_event` 是唯一接入点，可接任意可观测后端：
+
+```python
+from task_agent.telemetry import langfuse_event_sink
+
+agent = build_agent(..., on_event=langfuse_event_sink())  # 需 task-agent[observability]
+```
+
+未安装 Langfuse 时自动降级为控制台输出，不抛错。
+
+## 发布到 PyPI
+
+变更记录见 [CHANGELOG](https://github.com/Zhuliqx/task-agent/blob/main/CHANGELOG.md)。
+
+```bash
+python -m build
+python -m twine upload --repository testpypi dist/*   # 先发 TestPyPI 验证
+python -m twine upload dist/*                         # 正式 PyPI（项目级令牌）
+```
+
+发行名 `agentchat-task-agent`（import 名 `task_agent`，CLI 命令 `task-agent`）。
+打 `v*` 标签可触发 CI 自动发布（需在仓库 Secrets 配置 `PYPI_API_TOKEN`，见
+`.github/workflows/publish.yml`）。
+
+## 事件回调（过程可见）
+
+`build_agent(on_event=...)` 会收到生命周期事件：`plan / replan / execute / check / verify / hitl / final`，
+数据形如 `{"action": ..., "source": ..., "ok": ...}`。宿主可接 SSE 或日志：
+
+```python
+def on_event(kind: str, data: dict) -> None:
+    print(f"[{kind}] {data}")
+```
+
+## 长任务记忆治理（findings 压缩）
+
+长任务 `findings` 会持续累积。设 `TaskAgentConfig(findings_budget=N)` 后，超过 N 条时把历史
+交给 LLM 压缩进 `findings_summary`，仅保留最新一条——控制后续 replan/check/final 的上下文
+与 token 成本（LLM 失败自动退化为截断拼接，不中断执行）。
+
+## 基准与容错
+
+```bash
+cd task-agent
+python benchmarks/bench_task_agent.py                       # fixed vs replan 结构指标对比（离线）
+python benchmarks/bench_task_agent.py --judge               # 追加质量评估（离线=规则代理）
+python benchmarks/bench_task_agent.py --llm openai --judge --out results/bench.json  # 真实 LLM 指标 + LLM-judge 打分
+```
+
+离线模式统计完成率 / 答案命中 / 平均执行步数 / 平均重试 / 平均耗时；真实质量指标用
+`--llm openai`（配 `TASK_AGENT_OPENAI_API_KEY`）；`--judge` 开启 LLM-judge 质量评估
+（目标达成度 / 信息完整性 / 幻觉，0-1，见 `src/task_agent/judge.py`）。容错通过混沌测试验证
+（`tests/test_resilience.py`：执行器随机失败 / 永久失败 / LLM 永久失败均能收敛交付）。
+宿主侧评估（真实 LLM + judge）位于 Agentchat 主仓库的 `backend/scripts/eval_task_agent.py`，
+本仓库用 `python benchmarks/bench_task_agent.py --llm openai --judge` 做等价质量评估。
+
+### 实测快照（真实 LLM：DeepSeek-chat，3 自包含任务 × 2 轮，2026-08-29）
+
+| 模式 | 完成率 | 目标达成 | 信息完整 | 幻觉 | 平均步数 | 平均耗时 |
+|------|--------|----------|----------|------|----------|----------|
+| replan | 1.000 | 1.000 | 1.000 | 0.000 | **1.0** | **6.0s** |
+| fixed | 1.000 | 1.000 | 1.000 | 0.000 | 3.0 | 12.0s |
+
+**关键发现**：简单自包含任务上，replan 一步收敛（LLM 直答 → check 判完成），fixed 因
+"先拆计划"多出 2 个执行步、耗时翻倍；而离线脚本化基准中 fixed 反而更快（脚本化计划恰好 2 步）。
+结论：**脚本化基准只能测结构，真实 LLM 才能暴露行为差异**——两者都要跑，别只用离线数字下结论。
+
+## 目录
+
+```
+task-agent/
+├── pyproject.toml
+├── benchmarks/bench_task_agent.py  # fixed vs replan 基准
+├── src/task_agent/
+│   ├── config.py      # TaskAgentConfig（运行配置）
+│   ├── llm.py         # LLM 协议 + 文本抽取
+│   ├── executor.py    # ExecuteRequest / StepResult / Executor / DefaultExecutor
+│   ├── state.py       # TaskState（findings reducer）
+│   ├── prompts.py     # PLAN/FINAL/REPLAN/CHECK/VERIFY/COMPRESS 提示词
+│   ├── judge.py       # 任务级质量评估（LLM-judge，0-1 三指标）
+│   ├── tools.py       # ToolCallingExecutor + 内置工具（零依赖）
+│   ├── memory.py      # TaskMemory / InMemoryMemory（跨任务记忆）
+│   ├── telemetry.py   # 控制台 / Langfuse 事件接入
+│   ├── cli.py         # task-agent 命令行入口
+│   ├── nodes.py       # 节点（闭包注入 Runtime）
+│   ├── graph.py       # build_agent / list_task_history / 路由 / error_handler
+│   └── demo.py        # 离线 demo（脚本化 FakeLLM）
+└── tests/
+```
+
+## 测试
+
+```bash
+cd task-agent && pytest -q
+```
+
+覆盖：解析 / 路由 / HITL（含无 checkpointer 降级）/ verify / error_handler / 执行节点 /
+默认执行器 / Time Travel / fixed 全流程 / demo 离线全流程 / 容错混沌注入 / findings 压缩 / 事件流。
+
+## 宿主集成（Agentchat 主仓库）
+
+本包零业务依赖、可独立使用；作为 Agentchat 平台的"项目 2"，宿主通过适配器注入
+LLM / Checkpointer / 执行器，并提供 `/api/agent-tasks/run`、`/api/agent-tasks/run/stream`（SSE）、
+`/api/agent-tasks/history`、`/api/agent-tasks/confirm` 等 API。宿主仓库地址：
+`https://github.com/Zhuliqx/Agentchat`。

agentchat_task_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+agentchat_task_agent-0.1.0.dist-info/licenses/LICENSE,sha256=WZHe1XVNDnqb4kXlXmV0ab6Q0u27AfxWuf2Uq6iN3VE,1085
+task_agent/__init__.py,sha256=ZE8cik2PrD8_E8Cfm-zd5zIpZJtgzCTpVhqSrQW6DGo,1413
+task_agent/cli.py,sha256=67nbtDZkCRHMNR09dT_3ozRFHeJ9PWHrGGyxc7FRR8E,3500
+task_agent/config.py,sha256=PtZz85JkhUbtzkKzKncMNJ_hhQEkXmDRFelZ7-bRfDw,1734
+task_agent/demo.py,sha256=Bue9Nbxys5xYyYj7irLLtT0y-zbqLTIbVRn7UgNGvVw,4830
+task_agent/executor.py,sha256=TzGbvzoD03rsGU8jBTr-qQtz97soFem7q5pbIixhLJE,1339
+task_agent/graph.py,sha256=N1KsGRGaN-23cIfYCB2nrt9TFqTDvMPhkhrwGWtL274,11697
+task_agent/judge.py,sha256=ETcBs-_fOYIxc5ClgZKltsxpe0D_xXTXzzjMbYiJWiQ,1675
+task_agent/llm.py,sha256=8uZ564PrHg6FHkXTyGzyVU8xQqoN0hCoDECHV2STeVI,663
+task_agent/memory.py,sha256=rGQxgZ74dwQAwRaJehw3gwpZGOJxky2p61Oj6KnrxO8,1517
+task_agent/nodes.py,sha256=6CciGHwOIcQFFPvM_IM6vlcB7kSyH4DEFbqJvM357ZA,15804
+task_agent/prompts.py,sha256=uynTUF7EleLvLCSurb9z4_QzkrOGcv-eic0PAZFqmLk,3980
+task_agent/py.typed,sha256=wA_3LnN5vepX3IBp_v0QcoM3IcA_GbNzJJP8E8oHjAk,60
+task_agent/state.py,sha256=3xHNUmPIb7lp0Lu_UrXw4ooIcqQQljvjczqA8-RIHt0,1940
+task_agent/telemetry.py,sha256=xcF7rT9ezECIcQGBope68kkGdLzJjtOn0AKmcgoBXIw,1504
+task_agent/tools.py,sha256=jq4223kX03Pa4bVdoZOs5lbH8NPxi8ZmLmTvJEJb4w8,5915
+agentchat_task_agent-0.1.0.dist-info/METADATA,sha256=JxQl_5tq22jWmNLfmU2GbRe6arn9S8XI-t7hW-GaNMs,11793
+agentchat_task_agent-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agentchat_task_agent-0.1.0.dist-info/entry_points.txt,sha256=Exz9qttpb6NCkEGEHDPXGnS-NrxFF3uwM-gPY-Pq0pE,90
+agentchat_task_agent-0.1.0.dist-info/top_level.txt,sha256=3ddbQYmRr6d_vmp-nvGuLLxJWP7ckOHqOzd4waec6Uo,11
+agentchat_task_agent-0.1.0.dist-info/RECORD,,

agentchat_task_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentchat_task_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+task-agent = task_agent.cli:main
+task-agent-demo = task_agent.demo:main

agentchat_task_agent-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zhuliqx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentchat_task_agent-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+task_agent

task_agent/__init__.py

@@ -0,0 +1,44 @@
+"""自主任务 Agent（独立包，零业务依赖）。
+
+面向模糊长目标的多步自主执行引擎：接收目标 → 每步重规划（或一次计划）→
+循环执行（注入 Executor）→ 完成度检查 → 结构化交付。
+
+使用：
+    from task_agent import TaskAgentConfig, build_agent
+
+    agent = build_agent(
+        config=TaskAgentConfig(mode="replan"),
+        llm_factory=llm_factory,                      # Callable[[], LLM]
+        checkpointer_provider=checkpointer_provider,  # Callable[[], Any | None]
+        executor=executor,                            # Callable[[ExecuteRequest], Awaitable[StepResult]]
+    )
+    result = await agent.ainvoke({"goal": "..."})
+"""
+from task_agent.config import TaskAgentConfig
+from task_agent.executor import (
+    DefaultExecutor,
+    ExecuteRequest,
+    Executor,
+    SOURCE_KEYS,
+    StepResult,
+)
+from task_agent.graph import build_agent, list_task_history
+from task_agent.judge import judge_task
+from task_agent.memory import InMemoryMemory
+from task_agent.tools import Tool, ToolCallingExecutor, builtin_tools
+
+__all__ = [
+    "TaskAgentConfig",
+    "build_agent",
+    "list_task_history",
+    "ExecuteRequest",
+    "StepResult",
+    "Executor",
+    "DefaultExecutor",
+    "SOURCE_KEYS",
+    "Tool",
+    "ToolCallingExecutor",
+    "builtin_tools",
+    "InMemoryMemory",
+    "judge_task",
+]

task_agent/cli.py

@@ -0,0 +1,98 @@
+"""task-agent 命令行入口。
+
+用法：
+    task-agent run "目标" [--mode replan|fixed] [--llm fake|openai] [--tools] [--memory] [--event] [--json]
+    task-agent demo
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+from typing import Callable
+
+from task_agent.config import TaskAgentConfig
+from task_agent.demo import _OpenAICompatLLM, _ScriptedLLM
+from task_agent.graph import build_agent
+from task_agent.memory import InMemoryMemory
+from task_agent.tools import ToolCallingExecutor, builtin_tools
+
+
+def _llm_factory(kind: str):
+    if kind == "openai":
+        llm = _OpenAICompatLLM()
+        return lambda: llm
+    scripted = _ScriptedLLM()
+    return lambda: scripted
+
+
+async def run_task(goal: str, args: argparse.Namespace) -> dict:
+    """构建图并执行（供 CLI 与测试复用）。"""
+    config = TaskAgentConfig(
+        mode=args.mode,
+        hitl=args.hitl,
+        max_steps=args.max_steps,
+        findings_budget=args.findings_budget,
+    )
+    executor = (
+        ToolCallingExecutor(_llm_factory(args.llm), builtin_tools)
+        if args.tools
+        else None
+    )
+    on_event: Callable[[str, dict], None] | None = None
+    if args.event:
+
+        def _on_event(kind: str, data: dict) -> None:
+            print(f"  [event] {kind}: {data}")
+
+        on_event = _on_event
+
+    agent = build_agent(
+        config=config,
+        llm_factory=_llm_factory(args.llm),
+        checkpointer_provider=lambda: None,
+        executor=executor,
+        on_event=on_event,
+        memory=InMemoryMemory() if args.memory else None,
+    )
+    return await agent.ainvoke({"goal": goal})
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="task-agent", description="自主任务 Agent 命令行")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p_run = sub.add_parser("run", help="执行一个目标任务")
+    p_run.add_argument("goal")
+    p_run.add_argument("--mode", choices=["replan", "fixed"], default="replan")
+    p_run.add_argument("--hitl", action="store_true", help="开启节点级人工确认（需 checkpointer）")
+    p_run.add_argument("--max-steps", type=int, default=8)
+    p_run.add_argument("--findings-budget", type=int, default=None, help="findings 压缩上限")
+    p_run.add_argument("--llm", choices=["fake", "openai"], default="fake", help="fake=脚本化离线 / openai=真实端点")
+    p_run.add_argument("--tools", action="store_true", help="启用内置工具（calculator/time/random）")
+    p_run.add_argument("--memory", action="store_true", help="启用跨任务记忆（进程内）")
+    p_run.add_argument("--event", action="store_true", help="打印执行事件")
+    p_run.add_argument("--json", action="store_true", help="以 JSON 输出结果")
+
+    sub.add_parser("demo", help="离线 demo")
+
+    args = ap.parse_args(argv)
+    if args.cmd == "demo":
+        from task_agent.demo import main as demo_main
+
+        demo_main()
+        return 0
+
+    result = asyncio.run(run_task(args.goal, args))
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print("\nfindings:")
+        for i, f in enumerate(result.get("findings") or [], 1):
+            print(f"  [{i}] {f}")
+        print("\nfinal_answer:", result.get("final_answer"))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

task_agent/config.py

@@ -0,0 +1,32 @@
+"""任务 Agent 配置（替代原宿主 app.config 的硬依赖）。"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TaskAgentConfig:
+    """自主任务 Agent 运行配置。
+
+    与宿主环境变量的对应关系（由宿主适配器负责映射）：
+    - mode        ← TASK_AGENT_MODE
+    - hitl        ← TASK_AGENT_HITL
+    - max_retries ← TASK_AGENT_MAX_RETRIES
+    - llm_timeout / llm_max_retries ← 宿主 LLM_TIMEOUT / LLM_MAX_RETRIES（节点级重试策略）
+    """
+
+    mode: str = "replan"          # replan=每步动态重规划（默认） / fixed=一次性计划
+    hitl: bool = True             # 节点级人工确认（依赖 checkpointer，无则自动降级全自主）
+    max_retries: int = 2          # verify 容错：单个子任务失败后自检的最大重试次数
+    max_steps: int = 8            # replan 模式步数上限（防循环）
+    llm_timeout: float = 60.0     # 单次 LLM 调用超时（节点级 timeout 用）
+    llm_max_retries: int = 2      # 节点级瞬时错误重试次数
+    findings_budget: int | None = None  # findings 保留条数上限；超限把历史压缩进 findings_summary（None=不限）
+
+    def __post_init__(self) -> None:
+        if self.mode not in ("replan", "fixed"):
+            raise ValueError(f"未知任务模式: {self.mode!r}（支持 replan / fixed）")
+        if self.max_retries < 0 or self.max_steps <= 0:
+            raise ValueError("max_retries >= 0 且 max_steps > 0")
+        if self.findings_budget is not None and self.findings_budget <= 0:
+            raise ValueError("findings_budget 必须为正整数或 None（不限制）")

task_agent/demo.py

@@ -0,0 +1,132 @@
+"""离线可运行 demo（无需 API key，脚本化 LLM）。
+
+用法：
+    python -m task_agent.demo                          # 离线 FakeLLM
+    TASK_AGENT_OPENAI_API_KEY=xxx python -m task_agent.demo  # 真实 OpenAI 兼容端点
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from functools import lru_cache
+from types import SimpleNamespace
+from typing import Any
+
+from task_agent.config import TaskAgentConfig
+from task_agent.graph import build_agent
+from task_agent.llm import LLM
+
+DEMO_GOAL = "介绍一下公司（知识库）并计算 1 到 100 所有质数的和"
+
+
+class _ScriptedLLM:
+    """按提示词特征返回脚本化 JSON 的假 LLM（确定性、可离线复现）。"""
+
+    def __init__(self) -> None:
+        self._replan_calls = 0
+        self._check_calls = 0
+
+    async def ainvoke(self, prompt: str) -> Any:
+        if "可用信息来源" in prompt:  # REPLAN_PROMPT 特征
+            self._replan_calls += 1
+            if self._replan_calls == 1:
+                return SimpleNamespace(
+                    content='{"next_action": "查询知识库中公司的成立年份", "expected_source": "kb"}'
+                )
+            return SimpleNamespace(
+                content='{"next_action": "计算 1 到 100 所有质数的和", "expected_source": "code"}'
+            )
+        if "完成度检查员" in prompt:  # CHECK_PROMPT 特征
+            self._check_calls += 1
+            return SimpleNamespace(
+                content='{"done": false}'
+                if self._check_calls == 1
+                else '{"done": true}'
+            )
+        if "结果整合器" in prompt:  # FINAL_PROMPT 特征
+            return SimpleNamespace(
+                content="已完成目标：公司成立于 2020 年；1 到 100 质数和为 1060。"
+            )
+        if "可用工具" in prompt:  # TOOLCALL_PROMPT 特征 → 直接回答
+            return SimpleNamespace(
+                content='{"answer": "根据知识库，公司成立于 2020 年；质数和为 1060。"}'
+            )
+        # 执行步（DefaultExecutor 直答）
+        return SimpleNamespace(content="根据知识库，公司成立于 2020 年；质数和为 1060。")
+
+
+class _OpenAICompatLLM:
+    """可选：配置了 TASK_AGENT_OPENAI_API_KEY 时使用真实 OpenAI 兼容端点。"""
+
+    def __init__(self) -> None:
+        from openai import AsyncOpenAI
+
+        self._client = AsyncOpenAI(
+            api_key=os.environ.get("TASK_AGENT_OPENAI_API_KEY"),
+            base_url=os.environ.get("TASK_AGENT_OPENAI_BASE_URL")
+            or "https://api.deepseek.com",
+        )
+        self._model = os.environ.get("TASK_AGENT_OPENAI_MODEL") or "deepseek-chat"
+
+    async def ainvoke(self, prompt: str) -> Any:
+        resp = await self._client.chat.completions.create(
+            model=self._model,
+            messages=[{"role": "user", "content": prompt}],
+            temperature=0.0,
+        )
+        return SimpleNamespace(content=resp.choices[0].message.content or "")
+
+
+@lru_cache(maxsize=1)
+def _openai_llm() -> _OpenAICompatLLM:
+    return _OpenAICompatLLM()
+
+
+async def run_demo_flow(
+    goal: str = DEMO_GOAL, on_event=None
+) -> dict:
+    """跑一遍完整 replan 流程（无 checkpointer → 无 HITL）。返回图执行结果。"""
+    scripted = _ScriptedLLM()
+
+    def _factory() -> LLM:
+        if os.environ.get("TASK_AGENT_OPENAI_API_KEY"):
+            return _openai_llm()
+        return scripted
+
+    agent = build_agent(
+        config=TaskAgentConfig(mode="replan", hitl=False),
+        llm_factory=_factory,
+        checkpointer_provider=lambda: None,
+        on_event=on_event,
+    )
+    return await agent.ainvoke({"goal": goal})
+
+
+def main() -> None:
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+    print("== task-agent demo（自主任务 Agent）==")
+    print(f"目标: {DEMO_GOAL}")
+    if os.environ.get("TASK_AGENT_OPENAI_API_KEY"):
+        print("LLM: OpenAI 兼容端点（TASK_AGENT_OPENAI_*）")
+    else:
+        print("LLM: 脚本化 FakeLLM（离线，无需 key）")
+    def _on_event(kind: str, data: dict) -> None:
+        payload = " ".join(f"{k}={v}" for k, v in data.items())
+        print(f"  [event] {kind}: {payload}")
+
+    print("\n执行过程：")
+    result = asyncio.run(run_demo_flow(on_event=_on_event))
+    print("\nfindings:")
+    for i, f in enumerate(result.get("findings") or [], 1):
+        print(f"  [{i}] {f}")
+    print("\nfinal_answer:", result.get("final_answer"))
+
+
+if __name__ == "__main__":
+    main()

task_agent/executor.py

@@ -0,0 +1,42 @@
+"""每步执行接口与默认实现（纯 LLM 直答）。"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+from task_agent.llm import LLMFactory, llm_text
+
+Source = Literal["kb", "db", "web", "code", "default"]
+SOURCE_KEYS: tuple[Source, ...] = ("kb", "db", "web", "code", "default")
+
+
+@dataclass(frozen=True)
+class ExecuteRequest:
+    """一步动作及其信息源提示（供宿主决定启用哪些工具/开关）。"""
+
+    action: str
+    source: Source = "default"
+
+
+@dataclass(frozen=True)
+class StepResult:
+    """一步执行的结构化结果（answer 为供整合的文本）。"""
+
+    answer: str
+
+
+class Executor(Protocol):
+    """执行一步动作。失败应抛异常（由节点捕获并标记为该步失败）。"""
+
+    async def __call__(self, request: ExecuteRequest) -> StepResult: ...
+
+
+class DefaultExecutor:
+    """默认执行器：不调用任何工具，直接由 LLM 回答当前动作（纯 LLM 直答）。"""
+
+    def __init__(self, llm_factory: LLMFactory) -> None:
+        self._llm_factory = llm_factory
+
+    async def __call__(self, request: ExecuteRequest) -> StepResult:
+        answer = (await llm_text(self._llm_factory(), request.action)).strip()
+        return StepResult(answer=answer)