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

ai_agent/harness/process.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+_DEFAULT_TIMEOUT = 120
+_MAX_TIMEOUT = 600
+_MAX_OUTPUT_CHARS = 100_000
+
+
+def clamp_timeout(timeout_seconds: int) -> int:
+    if timeout_seconds <= 0:
+        return _DEFAULT_TIMEOUT
+    return min(timeout_seconds, _MAX_TIMEOUT)
+
+
+def format_process_result(
+    *,
+    exit_code: int,
+    stdout: str,
+    stderr: str,
+    timed_out: bool = False,
+) -> str:
+    parts: list[str] = []
+    if timed_out:
+        parts.append("状态: 超时")
+    else:
+        parts.append(f"退出码: {exit_code}")
+    if stdout:
+        parts.append("--- stdout ---")
+        parts.append(stdout)
+    if stderr:
+        parts.append("--- stderr ---")
+        parts.append(stderr)
+    text = "\n".join(parts)
+    if len(text) > _MAX_OUTPUT_CHARS:
+        overflow = len(text) - _MAX_OUTPUT_CHARS
+        text = text[:_MAX_OUTPUT_CHARS] + f"\n...（输出已截断，省略 {overflow} 字符）"
+    return text
+
+
+def run_shell(
+    command: str,
+    *,
+    work_dir: Path,
+    timeout_seconds: int = 0,
+) -> str:
+    command = command.strip()
+    if not command:
+        raise ValueError("command 不能为空")
+    timeout = clamp_timeout(timeout_seconds)
+    try:
+        completed = subprocess.run(
+            command,
+            shell=True,
+            cwd=work_dir,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+            stdin=subprocess.DEVNULL,
+        )
+    except subprocess.TimeoutExpired as exc:
+        stdout = (exc.stdout or "") if isinstance(exc.stdout, str) else ""
+        stderr = (exc.stderr or "") if isinstance(exc.stderr, str) else ""
+        return format_process_result(
+            exit_code=-1,
+            stdout=stdout,
+            stderr=stderr,
+            timed_out=True,
+        )
+    return format_process_result(
+        exit_code=completed.returncode,
+        stdout=completed.stdout,
+        stderr=completed.stderr,
+    )
+
+
+def run_python(
+    code: str,
+    *,
+    work_dir: Path,
+    timeout_seconds: int = 0,
+) -> str:
+    code = code.strip()
+    if not code:
+        raise ValueError("code 不能为空")
+    timeout = clamp_timeout(timeout_seconds)
+    try:
+        completed = subprocess.run(
+            [sys.executable, "-c", code],
+            cwd=work_dir,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+            stdin=subprocess.DEVNULL,
+        )
+    except subprocess.TimeoutExpired as exc:
+        stdout = (exc.stdout or "") if isinstance(exc.stdout, str) else ""
+        stderr = (exc.stderr or "") if isinstance(exc.stderr, str) else ""
+        return format_process_result(
+            exit_code=-1,
+            stdout=stdout,
+            stderr=stderr,
+            timed_out=True,
+        )
+    return format_process_result(
+        exit_code=completed.returncode,
+        stdout=completed.stdout,
+        stderr=completed.stderr,
+    )

ai_agent/harness/prompts.py

@@ -0,0 +1,38 @@
+PLANNING_SYSTEM_PROMPT = """\
+
+你是任务规划助手。根据用户请求与下文业务规则、技能及工具说明，输出一份严格串行、不可并行的执行计划。
+
+
+
+规则：
+
+
+
+- 若用户请求单一、无需工具，可只规划 1 步；较复杂或多阶段任务建议 2 到 6 步，每步只承担一个清晰目标；须体现规则与技能中的流程要求，用自然语言写 objective，勿套用应用外的硬性步骤模板。
+
+- 搜索后聊天短答类任务：固定 2 步（搜索 → 按技能改写交付终稿）；勿把 enable_skill 与阅读技能拆成两步，勿单独规划仅调用 builtin__current_time 的步骤——涉及时效时搜索步 objective 须写明「先调用 builtin__current_time 再搜索」，并将 builtin__current_time 写入 hint_tools；每一轮含时效的搜索步均须如此，不得因会话已用过时间工具而省略 hint_tools 或 objective 中的取时说明。
+
+- 终稿步 objective 须写明改写 skill 路径（如 skills/chat-search-answer）；框架会在该步预载技能正文，required_tool 勿填 enable_skill（填 null），改写须按该 skill 执行。用户要求简短、简要、一句话总结时，终稿步 objective 须写明按 chat-search-answer 的 brief 篇幅（约 80–160 汉字）。
+
+- 规划 objective 勿写死具体公历日期或年份；时间窗口由执行阶段在调用 builtin__current_time 后确定。勿在 objective 里写与业务规则可能冲突的年份字面量。执行阶段取时与搜索须分两回合发起，勿在同一助手回合并行 tool call。
+
+- 仅输出一个 JSON 对象，不要 Markdown 代码围栏，不要额外说明；summary 一句即可，勿在 JSON 外复述业务规则全文。
+
+- JSON 结构：
+
+  {"summary": "可选一句规划说明", "steps": [
+
+    {"id": "step-1", "title": "...", "objective": "...", "optional": false,
+
+     "hint_tools": [], "required_tool": null}
+
+  ]}
+
+- id 使用 step-1、step-2 等形式，互不重复。
+
+- optional 为 true 表示执行阶段可判定跳过（例如终稿改写已有足够短答时）。
+
+- hint_tools、required_tool 填对外工具名（如 server__tool）；无则空列表或 null。
+
+"""
+

ai_agent/harness/sandbox.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+
+_MAX_READ_BYTES = 512 * 1024
+
+
+class HarnessSandbox:
+    """将相对路径限定在构造时指定的工作区根目录内。"""
+
+    def __init__(self, workspace: Path) -> None:
+        root = workspace.expanduser().resolve()
+        root.mkdir(parents=True, exist_ok=True)
+        if not root.is_dir():
+            raise ValueError(f"工作区须为目录: {root}")
+        self._root = root
+
+    @property
+    def root(self) -> Path:
+        return self._root
+
+    def resolve_path(self, path: str) -> Path:
+        """
+        解析相对工作区的路径并拒绝越界。
+
+        Args:
+            path: 相对工作区根的路径；空字符串表示工作区根
+
+        Returns:
+            解析后的绝对路径
+
+        Raises:
+            ValueError: 路径非法或越出工作区
+        """
+        cleaned = path.strip()
+        if not cleaned or cleaned in (".", "./"):
+            return self._root
+        if Path(cleaned).is_absolute():
+            raise ValueError("path 须为相对工作区的路径")
+        target = (self._root / cleaned).resolve()
+        try:
+            target.relative_to(self._root)
+        except ValueError as exc:
+            raise ValueError(f"路径越出工作区: {path}") from exc
+        return target
+
+    def read_text_file(self, path: str, offset: int = 1, limit: int = 0) -> str:
+        """
+        读取文本文件片段。
+
+        Args:
+            path: 相对工作区路径
+            offset: 起始行号，从 1 起
+            limit: 最多读取行数；0 表示读到文件末尾
+
+        Returns:
+            带行号前缀的文本
+        """
+        if offset < 1:
+            raise ValueError("offset 须 >= 1")
+        if limit < 0:
+            raise ValueError("limit 须 >= 0")
+        target = self.resolve_path(path)
+        if not target.is_file():
+            raise ValueError(f"不是文件: {path}")
+        size = target.stat().st_size
+        if size > _MAX_READ_BYTES:
+            raise ValueError(f"文件过大（>{_MAX_READ_BYTES} 字节）: {path}")
+        lines = target.read_text(encoding="utf-8", errors="replace").splitlines()
+        start = offset - 1
+        if start >= len(lines):
+            return ""
+        if limit > 0:
+            chunk = lines[start : start + limit]
+        else:
+            chunk = lines[start:]
+        width = len(str(start + len(chunk)))
+        numbered: list[str] = []
+        for index, line in enumerate(chunk, start=offset):
+            numbered.append(f"{index:>{width}}|{line}")
+        return "\n".join(numbered)
+
+    def write_text_file(self, path: str, content: str, append: bool = False) -> str:
+        """
+        写入或追加文本文件。
+
+        Args:
+            path: 相对工作区路径
+            content: 写入内容
+            append: 为 True 时追加，否则覆盖
+
+        Returns:
+            简短结果说明
+        """
+        target = self.resolve_path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        mode = "a" if append else "w"
+        with target.open(mode, encoding="utf-8", newline="\n") as handle:
+            handle.write(content)
+        action = "已追加" if append else "已写入"
+        return f"{action} {len(content)} 字符到 {path}"
+
+    def list_entries(
+        self,
+        path: str = "",
+        *,
+        max_entries: int = 200,
+        pattern: str = "",
+    ) -> list[str]:
+        """
+        列出工作区内相对路径（文件与目录）。
+
+        Args:
+            path: 相对工作区根的子目录；空表示整棵工作区
+            max_entries: 最多返回条数
+            pattern: 可选 glob 片段，仅保留路径匹配者
+
+        Returns:
+            相对路径列表，字典序
+        """
+        if max_entries < 1:
+            raise ValueError("max_entries 须 >= 1")
+        base = self.resolve_path(path)
+        if not base.is_dir():
+            raise ValueError(f"不是目录: {path or '.'}")
+        entries: list[str] = []
+        for item in sorted(base.rglob("*")):
+            rel = item.relative_to(self._root).as_posix()
+            if item.is_dir():
+                rel = f"{rel}/"
+            if pattern.strip() and not fnmatch.fnmatch(rel, pattern.strip()):
+                continue
+            entries.append(rel)
+            if len(entries) >= max_entries:
+                break
+        if not path.strip() and not entries:
+            entries.append("./")
+        return entries

ai_agent/json_extract.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+_JSON_DECODER = json.JSONDecoder()
+
+_FENCE_RE = re.compile(
+    r"```(?:json)?\s*([\s\S]*?)\s*```",
+    re.IGNORECASE,
+)
+
+
+def extract_first_json_value(text: str) -> Any | None:
+    """
+    从可能含说明文字、围栏或多个 JSON 的文本中解析第一个完整 JSON 值。
+
+    Args:
+        text: 模型原始输出
+
+    Returns:
+        解析到的对象或数组；无法解析时为 None
+    """
+    stripped = text.strip()
+    if not stripped:
+        return None
+    candidates: list[str] = []
+    for match in _FENCE_RE.finditer(stripped):
+        inner = match.group(1).strip()
+        if inner:
+            candidates.append(inner)
+    candidates.append(stripped)
+    for candidate in candidates:
+        value = _decode_first_json(candidate)
+        if value is not None:
+            return value
+    return None
+
+
+def extract_first_json_object(text: str) -> dict[str, Any] | None:
+    """
+    解析第一个 JSON 对象（dict）。
+
+    Args:
+        text: 模型原始输出
+
+    Returns:
+        根节点为对象时返回该 dict，否则 None
+    """
+    value = extract_first_json_value(text)
+    if isinstance(value, dict):
+        return value
+    return None
+
+
+def _decode_first_json(text: str) -> Any | None:
+    idx = 0
+    length = len(text)
+    while idx < length:
+        ch = text[idx]
+        if ch in "{[":
+            try:
+                value, _end = _JSON_DECODER.raw_decode(text, idx)
+            except json.JSONDecodeError:
+                idx += 1
+                continue
+            return value
+        idx += 1
+    return None

ai_agent/listener.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable, Iterable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from ai_agent.context import RunContext, ToolInvocation
+
+if TYPE_CHECKING:
+    from ai_agent.app.packet import RunOutputPacket
+    from ai_agent.plan.models import Plan, PlanStep
+
+ListenerCallback = Callable[..., Any] | Callable[..., Awaitable[Any]]
+
+
+@dataclass
+class AgentListener:
+    """
+    规划、逐步执行与应用交付的可选回调集合。
+
+    流式思考与回答经 ``on_thinking_delta`` / ``on_output_delta`` 推送，
+    调用方可读 ``RunContext.phase`` 区分规划、计划步与直连 ReAct。
+    各钩子未设置时不调用；回调可为同步或 async 函数。
+    """
+
+    on_run_start: ListenerCallback | None = None
+    on_run_end: ListenerCallback | None = None
+    on_thinking_delta: ListenerCallback | None = None
+    on_output_delta: ListenerCallback | None = None
+    on_tool_start: ListenerCallback | None = None
+    on_tool_end: ListenerCallback | None = None
+    on_plan_start: ListenerCallback | None = None
+    on_plan_ready: ListenerCallback | None = None
+    on_plan_step_start: ListenerCallback | None = None
+    on_plan_step_end: ListenerCallback | None = None
+    on_app_run_end: ListenerCallback | None = None
+
+
+def normalize_listeners(
+    listeners: AgentListener | Iterable[AgentListener] | None,
+) -> list[AgentListener]:
+    """
+    将单个或多个 listener 规范为列表。
+
+    Args:
+        listeners: 单个 ``AgentListener``、序列，或 ``None``
+
+    Returns:
+        供 ``AgentContext`` 使用的 listener 列表
+    """
+    if listeners is None:
+        return []
+    if isinstance(listeners, AgentListener):
+        return [listeners]
+    return list(listeners)
+
+
+async def _invoke(callback: ListenerCallback, *args: Any) -> None:
+    result = callback(*args)
+    if inspect.isawaitable(result):
+        await result
+
+
+async def notify_run_start(listeners: Sequence[AgentListener], run: RunContext) -> None:
+    for listener in listeners:
+        if listener.on_run_start is not None:
+            await _invoke(listener.on_run_start, run)
+
+
+async def notify_run_end(listeners: Sequence[AgentListener], run: RunContext) -> None:
+    for listener in listeners:
+        if listener.on_run_end is not None:
+            await _invoke(listener.on_run_end, run)
+
+
+async def notify_thinking_delta(
+    listeners: Sequence[AgentListener],
+    delta: str,
+    run: RunContext,
+) -> None:
+    if not delta:
+        return
+    for listener in listeners:
+        if listener.on_thinking_delta is not None:
+            await _invoke(listener.on_thinking_delta, delta, run)
+
+
+async def notify_output_delta(
+    listeners: Sequence[AgentListener],
+    delta: str,
+    run: RunContext,
+) -> None:
+    if not delta:
+        return
+    for listener in listeners:
+        if listener.on_output_delta is not None:
+            await _invoke(listener.on_output_delta, delta, run)
+
+
+async def notify_tool_start(
+    listeners: Sequence[AgentListener],
+    invocation: ToolInvocation,
+    run: RunContext,
+) -> None:
+    for listener in listeners:
+        if listener.on_tool_start is not None:
+            await _invoke(listener.on_tool_start, invocation, run)
+
+
+async def notify_tool_end(
+    listeners: Sequence[AgentListener],
+    invocation: ToolInvocation,
+    run: RunContext,
+) -> None:
+    for listener in listeners:
+        if listener.on_tool_end is not None:
+            await _invoke(listener.on_tool_end, invocation, run)
+
+
+async def notify_plan_start(listeners: Sequence[AgentListener]) -> None:
+    for listener in listeners:
+        if listener.on_plan_start is not None:
+            await _invoke(listener.on_plan_start)
+
+
+async def notify_plan_ready(listeners: Sequence[AgentListener], plan: Plan) -> None:
+    for listener in listeners:
+        if listener.on_plan_ready is not None:
+            await _invoke(listener.on_plan_ready, plan)
+
+
+async def notify_plan_step_start(
+    listeners: Sequence[AgentListener],
+    *,
+    step_index: int,
+    step: PlanStep,
+    plan: Plan,
+) -> None:
+    for listener in listeners:
+        if listener.on_plan_step_start is not None:
+            await _invoke(listener.on_plan_step_start, step_index, step, plan)
+
+
+async def notify_plan_step_end(
+    listeners: Sequence[AgentListener],
+    *,
+    step_index: int,
+    step: PlanStep,
+    plan: Plan,
+    output: str,
+    skipped: bool,
+) -> None:
+    for listener in listeners:
+        if listener.on_plan_step_end is not None:
+            await _invoke(
+                listener.on_plan_step_end,
+                step_index,
+                step,
+                plan,
+                output,
+                skipped,
+            )
+
+
+async def notify_app_run_end(
+    listeners: Sequence[AgentListener],
+    packet: RunOutputPacket,
+) -> None:
+    for listener in listeners:
+        if listener.on_app_run_end is not None:
+            await _invoke(listener.on_app_run_end, packet)

ai_agent/llm.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, AsyncIterator, Protocol
+
+from ai_agent.context import RunContext
+
+
+class StreamKind(str, Enum):
+    """语言模型流式片段类型（库内统一）。"""
+
+    TEXT = "text"
+    REASONING = "reasoning"
+    TOOL_CALL = "tool_call"
+    DONE = "done"
+
+
+@dataclass
+class StreamChunk:
+    """语言模型流式输出的一段；各适配器均映射为本类型。"""
+
+    kind: StreamKind
+    delta: str = ""
+    tool_call_id: str | None = None
+    tool_name: str | None = None
+    tool_arguments: dict[str, Any] | None = None
+
+
+class LLMClient(Protocol):
+    """语言模型流式接口；库内由 OpenAILLM 实现。"""
+
+    async def stream(
+        self,
+        context: RunContext,
+        *,
+        tools: list[dict[str, Any]] | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """按当前上下文流式请求语言模型。"""

ai_agent/llm_openai.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator
+
+from ai_agent.context import RunContext
+from ai_agent.llm import StreamChunk, StreamKind
+
+
+def _merge_extra_body(kwargs: dict[str, Any], patch: dict[str, Any]) -> None:
+    extra = dict(kwargs.get("extra_body") or {})
+    extra.update(patch)
+    kwargs["extra_body"] = extra
+
+
+def _apply_thinking_kwargs(kwargs: dict[str, Any], *, base_url: str) -> None:
+    """按网关形态写入思考模式参数（DeepSeek 用 extra_body，其余兼容端用 enable_thinking）。"""
+    if "deepseek" in base_url.lower():
+        _merge_extra_body(kwargs, {"thinking": {"type": "enabled"}})
+        return
+    kwargs["enable_thinking"] = True
+
+
+class OpenAILLM:
+    """库内：包装 ``AsyncOpenAI``，将官方流式事件映射为 ``StreamChunk``。"""
+
+    def __init__(
+        self,
+        client: Any,
+        *,
+        model: str,
+        base_url: str = "",
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        thinking_enabled: bool = False,
+    ) -> None:
+        self._client = client
+        self.model = model
+        self._base_url = base_url.strip()
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.thinking_enabled = thinking_enabled
+
+    async def stream(
+        self,
+        context: RunContext,
+        *,
+        tools: list[dict[str, Any]] | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        kwargs: dict[str, Any] = {
+            "model": self.model,
+            "messages": context.api_messages(),
+            "stream": True,
+        }
+        if tools:
+            kwargs["tools"] = tools
+        if self.temperature is not None:
+            kwargs["temperature"] = self.temperature
+        if self.max_tokens is not None:
+            kwargs["max_tokens"] = self.max_tokens
+        if self.thinking_enabled:
+            _apply_thinking_kwargs(kwargs, base_url=self._base_url)
+
+        stream = await self._client.chat.completions.create(**kwargs)
+        tool_bufs: dict[int, dict[str, Any]] = {}
+
+        async for event in stream:
+            if not event.choices:
+                continue
+            choice = event.choices[0]
+            delta = choice.delta
+
+            if delta.content:
+                yield StreamChunk(kind=StreamKind.TEXT, delta=delta.content)
+
+            reasoning = getattr(delta, "reasoning_content", None)
+            if reasoning:
+                yield StreamChunk(kind=StreamKind.REASONING, delta=reasoning)
+
+            if delta.tool_calls:
+                for tc in delta.tool_calls:
+                    idx = int(tc.index or 0)
+                    buf = tool_bufs.setdefault(
+                        idx,
+                        {"id": "", "name": "", "arguments": ""},
+                    )
+                    if tc.id:
+                        buf["id"] = tc.id
+                    if tc.function and tc.function.name:
+                        buf["name"] = tc.function.name
+                    if tc.function and tc.function.arguments:
+                        buf["arguments"] += tc.function.arguments
+
+            if choice.finish_reason == "tool_calls":
+                async for chunk in _flush_tool_bufs(tool_bufs):
+                    yield chunk
+                tool_bufs.clear()
+
+        async for chunk in _flush_tool_bufs(tool_bufs):
+            yield chunk
+        yield StreamChunk(kind=StreamKind.DONE)
+
+
+async def _flush_tool_bufs(tool_bufs: dict[int, dict[str, Any]]) -> AsyncIterator[StreamChunk]:
+    for buf in tool_bufs.values():
+        args_raw = buf.get("arguments") or "{}"
+        try:
+            args = json.loads(args_raw)
+        except json.JSONDecodeError:
+            args = {}
+        if buf.get("id") and buf.get("name"):
+            yield StreamChunk(
+                kind=StreamKind.TOOL_CALL,
+                tool_call_id=buf["id"],
+                tool_name=buf["name"],
+                tool_arguments=args if isinstance(args, dict) else {},
+            )