python-library-ai-agent 0.1.0__py3-none-any.whl

ai_agent/plan/models.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class PlanStep(BaseModel):
+    """计划中的单步，按顺序串行执行。"""
+
+    id: str = Field(description="步骤唯一标识，如 step-1")
+    title: str = Field(description="短标题")
+    objective: str = Field(description="本步须完成的目标")
+    optional: bool = Field(default=False, description="执行时可由模型判定跳过")
+    hint_tools: list[str] = Field(default_factory=list, description="建议使用的工具名")
+
+    @field_validator("hint_tools", mode="before")
+    @classmethod
+    def _hint_tools_none_as_empty(cls, value: object) -> object:
+        if value is None:
+            return []
+        return value
+
+    required_tool: str | None = Field(
+        default=None,
+        description="本步应调用的工具名；仅作规划提示，执行阶段不强制",
+    )
+
+
+class Plan(BaseModel):
+    """串行多步计划。"""
+
+    steps: list[PlanStep] = Field(min_length=1, description="按执行顺序排列")
+    summary: str | None = Field(default=None, description="规划说明，可选")
+
+
+class PlanRunResult(BaseModel):
+    """一次 run_with_plan 的完整结果。"""
+
+    plan: Plan
+    step_outputs: dict[str, str] = Field(description="步骤 id 到该步完整输出")
+    final_output: str = Field(description="返回给用户的最终文本")
+    skipped_step_ids: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="执行时判定跳过的可选步 id",
+    )

ai_agent/plan/parse.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from ai_agent.json_extract import extract_first_json_object
+from ai_agent.plan.models import Plan, PlanStep
+
+
+class PlanParseError(ValueError):
+    """规划结果无法解析为合法计划。"""
+
+
+def parse_plan_text(text: str) -> Plan:
+    """
+    从模型文本中解析计划 JSON。
+
+    Args:
+        text: 模型返回的原始文本
+
+    Returns:
+        校验后的计划对象
+
+    Raises:
+        PlanParseError: JSON 无效或缺少 steps
+    """
+    data = extract_first_json_object(text)
+    if data is None:
+        raise PlanParseError("规划输出不是合法 JSON 对象")
+    steps_raw = data.get("steps")
+    if not isinstance(steps_raw, list) or not steps_raw:
+        raise PlanParseError("steps 须为非空数组")
+    steps: list[PlanStep] = []
+    for item in steps_raw:
+        if not isinstance(item, dict):
+            raise PlanParseError("每个 step 须为对象")
+        steps.append(PlanStep.model_validate(item))
+    summary = data.get("summary")
+    return Plan(
+        summary=summary if isinstance(summary, str) else None,
+        steps=steps,
+    )

ai_agent/plan/planner.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ai_agent.context import ChatMessage, RunPhase, RunPhaseKind
+from ai_agent.harness.prompts import PLANNING_SYSTEM_PROMPT
+from ai_agent.listener import AgentListener
+from ai_agent.llm import LLMClient
+from ai_agent.plan.complete import complete_text
+from ai_agent.plan.models import Plan
+from ai_agent.plan.parse import PlanParseError, parse_plan_text
+
+
+
+
+class PlanPlanner:
+
+    """
+
+    规划入口：用与执行相同的语言模型产出串行计划，不调用工具。
+
+
+
+    规划与执行共用 ``LLMClient``，由 ``PlanRunner`` 或测试注入。
+
+    """
+
+
+
+    def __init__(self, llm: LLMClient) -> None:
+
+        self._llm = llm
+
+        self._planning_system_prompt = PLANNING_SYSTEM_PROMPT.strip()
+
+
+
+    async def plan(
+        self,
+        *,
+        user_message: str,
+        business_system_prompt: str,
+        messages: list[ChatMessage],
+        extra_planning_context: str = "",
+        listeners: Sequence[AgentListener] | None = None,
+    ) -> Plan:
+
+        """
+
+        根据用户请求与对话历史生成计划。
+
+
+
+        Args:
+
+            user_message: 本轮用户输入（已可能在 messages 末尾）
+
+            business_system_prompt: 业务系统提示（含规则与技能等自然语言说明）
+
+            messages: 送入规划的历史（通常含本轮用户消息）
+
+            extra_planning_context: 附加说明（如附件摘要）
+
+
+
+        Returns:
+
+            解析后的串行计划
+
+
+
+        Raises:
+
+            PlanParseError: 模型输出无法解析且重试后仍失败
+
+        """
+
+        system = _build_planning_system(
+
+            self._planning_system_prompt,
+
+            business_system_prompt,
+
+            extra_planning_context,
+
+        )
+
+        history = _history_without_last_user(messages, user_message)
+
+        user_block = _format_planning_user(user_message, business_system_prompt)
+
+        last_error: PlanParseError | None = None
+
+        for attempt in range(2):
+
+            text = await complete_text(
+                self._llm,
+                system_prompt=system,
+                user_content=user_block
+                if attempt == 0
+                else f"{user_block}\n\n上次输出无法解析，请仅输出合法 JSON 对象。",
+                history=history,
+                listeners=listeners,
+                phase=RunPhase(kind=RunPhaseKind.PLANNING),
+                parse_from_answer_text_only=True,
+            )
+
+            try:
+
+                return parse_plan_text(text)
+
+            except PlanParseError as exc:
+
+                last_error = exc
+
+                continue
+
+        assert last_error is not None
+
+        raise last_error
+
+
+
+
+
+def _history_without_last_user(
+
+    messages: list[ChatMessage],
+
+    user_message: str,
+
+) -> list[ChatMessage]:
+
+    if not messages:
+
+        return []
+
+    last = messages[-1]
+
+    if last.role == "user" and last.content.strip() == user_message.strip():
+
+        return list(messages[:-1])
+
+    return list(messages)
+
+
+
+
+
+def _format_planning_user(user_message: str, business_system_prompt: str) -> str:
+
+    lines = [
+
+        "## 用户请求",
+
+        user_message.strip(),
+
+        "",
+
+        "## 业务系统提示（供规划参考，含规则与技能）",
+
+        business_system_prompt.strip() or "(无)",
+
+        "",
+
+        "请结合上文规则与技能说明分解步骤，输出 JSON 计划。",
+
+    ]
+
+    return "\n".join(lines)
+
+
+
+
+
+def _build_planning_system(
+
+    planning_base: str,
+
+    business_system_prompt: str,
+
+    extra_planning_context: str,
+
+) -> str:
+
+    parts = [planning_base]
+
+    if business_system_prompt.strip():
+
+        parts.append("")
+
+        parts.append("## 业务背景")
+
+        parts.append(business_system_prompt.strip())
+
+    if extra_planning_context.strip():
+
+        parts.append("")
+
+        parts.append(extra_planning_context.strip())
+
+    return "\n\n".join(parts)
+
+

ai_agent/plan/runner.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from collections.abc import Sequence
+
+from ai_agent.app.output_format import (
+    run_output_instruction,
+    step_intermediate_instruction,
+)
+from ai_agent.context import ChatMessage, RunPhase, RunPhaseKind
+from ai_agent.listener import (
+    AgentListener,
+    notify_plan_ready,
+    notify_plan_start,
+    notify_plan_step_end,
+    notify_plan_step_start,
+)
+from ai_agent.llm import LLMClient
+from ai_agent.plan.models import Plan, PlanRunResult, PlanStep
+from ai_agent.plan.planner import PlanPlanner
+from ai_agent.plan.delivery import (
+    delivery_skill_refs_for_step,
+    plan_delivery_preload_note,
+)
+
+if TYPE_CHECKING:
+    from ai_agent.app.session import AgentSession
+
+SKIP_STEP_MARKER = "SKIP_STEP"
+
+
+class PlanStepFailedError(RuntimeError):
+    """某必做步骤未产生有效输出时抛出。"""
+
+
+class PlanRunner:
+    """
+    编排规划与逐步执行：先 ``PlanPlanner``，再对每步调用会话上的 ReAct。
+
+    步间上下文携带已完成步骤的完整 output；可选步由执行模型自行判定是否跳过。
+    """
+
+    def __init__(
+        self,
+        llm: LLMClient,
+        *,
+        listeners: Sequence[AgentListener] | None = None,
+    ) -> None:
+        self._planner = PlanPlanner(llm)
+        self._listeners: list[AgentListener] = list(listeners or [])
+
+    async def run(
+        self,
+        session: AgentSession,
+        *,
+        user_message: str,
+        speaker: str = "user",
+        extra_planning_context: str = "",
+    ) -> PlanRunResult:
+        """
+        规划并串行执行各步，返回最终回答。
+
+        Args:
+            session: 已装配 Harness 与工具的会话
+            user_message: 用户输入
+            speaker: 多用户场景下的讲述者名
+            extra_planning_context: 拼入规划阶段的附加说明
+
+        Returns:
+            计划、各步完整输出与最终文本
+
+        Raises:
+            PlanStepFailedError: 必做步骤无有效输出
+        """
+        full_system = session.build_system_prompt()
+        planning_messages, merged_system = session._prepare_plan_run(
+            user_message=user_message,
+            system_prompt=full_system,
+            speaker=speaker,
+        )
+        await notify_plan_start(self._listeners)
+        plan = await self._planner.plan(
+            user_message=user_message,
+            business_system_prompt=merged_system,
+            messages=planning_messages,
+            extra_planning_context=extra_planning_context,
+            listeners=self._listeners,
+        )
+        await notify_plan_ready(self._listeners, plan)
+        skill_manager = session.skill_manager
+        if skill_manager is not None:
+            skill_manager.begin_plan()
+        try:
+            step_outputs: dict[str, str] = {}
+            skipped: list[str] = []
+            for index, step in enumerate(plan.steps):
+                await notify_plan_step_start(
+                    self._listeners,
+                    step_index=index,
+                    step=step,
+                    plan=plan,
+                )
+                output = await self._run_step(
+                    session,
+                    base_system=full_system,
+                    plan=plan,
+                    step=step,
+                    step_index=index,
+                    user_message=user_message,
+                    prior_outputs=step_outputs,
+                )
+                skipped_step = step.optional and _is_skip_output(output)
+                if skipped_step:
+                    skipped.append(step.id)
+                elif not output.strip() and not step.optional:
+                    raise PlanStepFailedError(
+                        f"步骤 {step.id}（{step.title}）未产生输出"
+                    )
+                else:
+                    step_outputs[step.id] = output
+                await notify_plan_step_end(
+                    self._listeners,
+                    step_index=index,
+                    step=step,
+                    plan=plan,
+                    output=output,
+                    skipped=skipped_step,
+                )
+                if skipped_step:
+                    continue
+            final = _pick_final_output(plan, step_outputs, skipped)
+            session._finish_plan_run(
+                user_message=user_message,
+                final_output=final,
+                speaker=speaker,
+            )
+            return PlanRunResult(
+                plan=plan,
+                step_outputs=step_outputs,
+                final_output=final,
+                skipped_step_ids=tuple(skipped),
+            )
+        finally:
+            if skill_manager is not None:
+                skill_manager.end_plan()
+
+    async def _run_step(
+        self,
+        session: AgentSession,
+        *,
+        base_system: str,
+        plan: Plan,
+        step: PlanStep,
+        step_index: int,
+        user_message: str,
+        prior_outputs: dict[str, str],
+    ) -> str:
+        is_last_step = step_index + 1 >= len(plan.steps)
+        delivery_refs: tuple[str, ...] = ()
+        preloaded_delivery = False
+        skill_manager = session.skill_manager
+        if skill_manager is not None:
+            if is_last_step:
+                delivery_refs = delivery_skill_refs_for_step(step)
+                skill_manager.set_plan_delivery_skills(delivery_refs)
+                preloaded_delivery = bool(delivery_refs)
+            else:
+                skill_manager.set_plan_delivery_skills(())
+        step_system = _build_step_system(
+            base_system,
+            plan=plan,
+            step=step,
+            step_index=step_index,
+            prior_outputs=prior_outputs,
+            is_last_step=is_last_step,
+            preloaded_delivery=preloaded_delivery,
+            delivery_skill_refs=delivery_refs,
+        )
+        step_user = _build_step_user(
+            user_message=user_message,
+            step=step,
+            step_index=step_index,
+            total=len(plan.steps),
+            is_last_step=is_last_step,
+            preloaded_delivery=preloaded_delivery,
+        )
+        return await session.run_with_messages(
+            messages=[ChatMessage(role="user", content=step_user)],
+            system_prompt=step_system,
+            phase=RunPhase(
+                kind=RunPhaseKind.STEP,
+                step_index=step_index,
+                step_id=step.id,
+            ),
+        )
+
+
+def _is_skip_output(text: str) -> bool:
+    stripped = text.strip()
+    return stripped == SKIP_STEP_MARKER or stripped.startswith(f"{SKIP_STEP_MARKER}\n")
+
+
+def _pick_final_output(
+    plan: Plan,
+    step_outputs: dict[str, str],
+    skipped: list[str],
+) -> str:
+    skipped_set = set(skipped)
+    for step in reversed(plan.steps):
+        if step.id in skipped_set:
+            continue
+        out = step_outputs.get(step.id, "").strip()
+        if out:
+            return out
+    return ""
+
+
+def _build_step_system(
+    base_system: str,
+    *,
+    plan: Plan,
+    step: PlanStep,
+    step_index: int,
+    prior_outputs: dict[str, str],
+    is_last_step: bool,
+    preloaded_delivery: bool = False,
+    delivery_skill_refs: tuple[str, ...] = (),
+) -> str:
+    lines = [base_system.rstrip(), "", "## 当前计划摘要"]
+    if plan.summary:
+        lines.append(plan.summary.strip())
+    lines.append(f"共 {len(plan.steps)} 步，当前为第 {step_index + 1} 步。")
+    if prior_outputs:
+        lines.append("")
+        lines.append("## 已完成步骤的完整输出")
+        for sid, out in prior_outputs.items():
+            lines.append(f"### {sid}")
+            lines.append(out)
+    lines.append("")
+    lines.append("## 本步任务")
+    lines.append(f"**{step.title}**")
+    lines.append(step.objective.strip())
+    if step.hint_tools:
+        lines.append(f"建议工具：{', '.join(step.hint_tools)}")
+    if step.required_tool and not preloaded_delivery:
+        lines.append(f"若需要请使用工具：{step.required_tool}")
+    if preloaded_delivery and delivery_skill_refs:
+        joined = ", ".join(delivery_skill_refs)
+        lines.append(f"终稿改写技能已预载：{joined}；勿再调用 enable_skill。")
+    if step.optional:
+        lines.append(
+            f"本步为可选。若前述输出已足以回答用户，请仅回复 {SKIP_STEP_MARKER}，"
+            "不要调用工具。"
+        )
+    if not is_last_step:
+        lines.append("本步为中间步骤：勿按最终交付 JSON 格式回复用户。")
+    return "\n".join(lines)
+
+
+def _build_step_user(
+    *,
+    user_message: str,
+    step: PlanStep,
+    step_index: int,
+    total: int,
+    is_last_step: bool,
+    preloaded_delivery: bool = False,
+) -> str:
+    parts = [
+        f"用户原始请求：{user_message.strip()}",
+        "",
+        f"请完成计划第 {step_index + 1}/{total} 步：{step.title}",
+    ]
+    if is_last_step:
+        parts.extend(["", run_output_instruction()])
+        if preloaded_delivery:
+            parts.extend(["", plan_delivery_preload_note()])
+    else:
+        parts.extend(["", step_intermediate_instruction()])
+    return "\n\n".join(parts)

ai_agent/react_tool_turn.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from ai_agent.builtin_tools.current_time import (
+    CURRENT_TIME_SHORT_NAME,
+    harness_current_time_tool_name,
+)
+from ai_agent.builtin_tools.prefix import builtin_tool_name
+from ai_agent.context import ToolInvocation
+
+_BUILTIN_CURRENT_TIME = builtin_tool_name(CURRENT_TIME_SHORT_NAME)
+_HARNESS_CURRENT_TIME = harness_current_time_tool_name()
+
+_SAME_TURN_DEFERRED_TOOL_REPLY = (
+    "未执行：本回合已与取时工具同时发起。请先阅读同回合取时工具的返回，"
+    "再在下一回合单独调用本工具并据取时结果重写参数（勿复用本回合已生成的 query）。"
+)
+
+
+def is_current_time_tool(tool_name: str) -> bool:
+    """是否为应用或 Harness 的取时工具对外名。"""
+    return tool_name in (_BUILTIN_CURRENT_TIME, _HARNESS_CURRENT_TIME)
+
+
+def batch_includes_current_time(batch: list[ToolInvocation]) -> bool:
+    return any(is_current_time_tool(inv.tool_name) for inv in batch)
+
+
+def should_defer_tool_in_batch(inv: ToolInvocation, batch: list[ToolInvocation]) -> bool:
+    """
+    同回合若同时请求取时与其它工具，仅执行取时；其它工具返回说明性结果供下回合重试。
+    """
+    if is_current_time_tool(inv.tool_name):
+        return False
+    return batch_includes_current_time(batch)
+
+
+def deferred_tool_reply() -> str:
+    """推迟执行时写入 ``ToolInvocation.answer`` 的固定说明。"""
+    return _SAME_TURN_DEFERRED_TOOL_REPLY

ai_agent/rule/__init__.py

@@ -0,0 +1,3 @@
+from ai_agent.rule.rules import RuleSet
+
+__all__ = ["RuleSet"]

ai_agent/rule/rules.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+
+class RuleSet:
+    """
+    会话级规则：由调用方指定文本文件路径，启动时读入并拼成系统提示。
+
+    与 skill 不同，规则不注册工具，每轮运行固定注入模型上下文。
+    """
+
+    def __init__(self, paths: Sequence[Path | str] | None = None) -> None:
+        self._segments: list[tuple[Path, str]] = []
+        for raw in paths or ():
+            path = Path(raw).expanduser().resolve()
+            if not path.is_file():
+                raise ValueError(f"rule 文件不存在或不是文件: {path}")
+            text = path.read_text(encoding="utf-8").strip()
+            self._segments.append((path, text))
+
+    @property
+    def paths(self) -> tuple[Path, ...]:
+        """已加载的规则文件绝对路径。"""
+        return tuple(path for path, _ in self._segments)
+
+    def build_system_prompt(self) -> str:
+        """
+        将各规则文件正文按顺序拼接为系统提示。
+
+        Returns:
+            无规则或文件均为空时返回空字符串
+        """
+        parts = [text for _, text in self._segments if text]
+        return "\n\n".join(parts)

ai_agent/skill/__init__.py

@@ -0,0 +1,5 @@
+from ai_agent.skill.builtin_registry import BuiltinToolRegistry
+from ai_agent.skill.manager import SkillManager
+from ai_agent.skill.skill_kit import SkillKit
+
+__all__ = ["BuiltinToolRegistry", "SkillKit", "SkillManager"]