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

ai_agent/app/session_store.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ai_agent.context import ChatMessage
+
+_CONVERSATION_FILE = "conversation.json"
+
+
+def conversation_path(session_root: Path) -> Path:
+    """会话根目录下的对话持久化文件路径。"""
+    return session_root / _CONVERSATION_FILE
+
+
+def load_conversation(session_root: Path) -> list[ChatMessage]:
+    """
+    从磁盘读取对话历史。
+
+    Args:
+        session_root: 会话工作区根
+
+    Returns:
+        无文件或解析失败时返回空列表
+    """
+    path = conversation_path(session_root)
+    if not path.is_file():
+        return []
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return []
+    if not isinstance(raw, list):
+        return []
+    messages: list[ChatMessage] = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        role = item.get("role")
+        content = item.get("content")
+        if role not in ("system", "user", "assistant", "tool"):
+            continue
+        if not isinstance(content, str):
+            continue
+        name = item.get("name")
+        if name is not None and not isinstance(name, str):
+            name = None
+        messages.append(
+            ChatMessage(
+                role=role,
+                content=content,
+                name=name,
+            ),
+        )
+    return messages
+
+
+def save_conversation(session_root: Path, messages: list[ChatMessage]) -> None:
+    """
+    将会话对话历史写入磁盘。
+
+    Args:
+        session_root: 会话工作区根
+        messages: 待持久化的消息列表
+    """
+    session_root.mkdir(parents=True, exist_ok=True)
+    payload = [
+        {
+            "role": m.role,
+            "content": m.content,
+            **({"name": m.name} if m.name else {}),
+        }
+        for m in messages
+    ]
+    conversation_path(session_root).write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+
+def clear_conversation(session_root: Path) -> None:
+    """删除会话对话持久化文件（若存在）。"""
+    path = conversation_path(session_root)
+    if path.is_file():
+        path.unlink()

ai_agent/builtin_tools/__init__.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from ai_agent.builtin_tools.current_time import (
+    CURRENT_TIME_SHORT_NAME,
+    build_current_time_tool,
+    harness_current_time_tool_name,
+)
+from ai_agent.builtin_tools.pack import build_app_builtin_tools
+from ai_agent.builtin_tools.prefix import APP_BUILTIN_PREFIX, builtin_tool_name
+
+__all__ = [
+    "APP_BUILTIN_PREFIX",
+    "CURRENT_TIME_SHORT_NAME",
+    "build_app_builtin_tools",
+    "build_current_time_tool",
+    "builtin_tool_name",
+    "harness_current_time_tool_name",
+]

ai_agent/builtin_tools/current_time.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ai_agent.builtin_tools.prefix import builtin_tool_name
+from ai_agent.harness.current_time import get_current_time
+from ai_agent.tools import Tool
+
+CURRENT_TIME_SHORT_NAME = "current_time"
+
+_CURRENT_TIME_PARAMETERS: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "timezone": {
+            "type": "string",
+            "description": "IANA 时区名，如 Asia/Shanghai；省略则使用本机本地时区",
+        },
+    },
+    "additionalProperties": False,
+}
+
+
+def harness_current_time_tool_name() -> str:
+    """Harness 沙箱层同名工具的对外名，用于去重。"""
+    return "harness__current_time"
+
+
+def build_current_time_tool() -> Tool:
+    """构造 ``builtin__current_time``，不依赖 Harness 工作区。"""
+    return Tool(
+        name=builtin_tool_name(CURRENT_TIME_SHORT_NAME),
+        description="获取当前日期与时间（ISO 8601），可按 IANA 时区名指定时区。",
+        parameters=_CURRENT_TIME_PARAMETERS,
+        handler=_run_current_time,
+    )
+
+
+def _run_current_time(*, timezone: str = "") -> str:
+    return get_current_time(timezone)

ai_agent/builtin_tools/pack.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from ai_agent.builtin_tools.current_time import build_current_time_tool
+from ai_agent.tools import Tool
+
+
+def build_app_builtin_tools(*, current_time: bool) -> list[Tool]:
+    """
+    组装 AgentApp 可选的应用级内置工具（与 Harness 沙箱无关）。
+
+    Args:
+        current_time: 是否注册 ``builtin__current_time``
+
+    Returns:
+        待并入 ToolRegistry 基础层的工具列表
+    """
+    tools: list[Tool] = []
+    if current_time:
+        tools.append(build_current_time_tool())
+    return tools

ai_agent/builtin_tools/prefix.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+APP_BUILTIN_PREFIX = "builtin"
+
+
+def builtin_tool_name(short: str) -> str:
+    """生成应用级内置工具对外名，形如 ``builtin__current_time``。"""
+    key = short.strip()
+    if not key:
+        raise ValueError("内置工具短名不能为空")
+    return f"{APP_BUILTIN_PREFIX}__{key}"

ai_agent/context.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from ai_agent.llm import LLMClient
+    from ai_agent.listener import AgentListener
+    from ai_agent.tools import ToolRegistry
+
+MessageRole = Literal["system", "user", "assistant", "tool"]
+
+
+class RunStatus(str, Enum):
+    """一轮运行的整体状态。"""
+
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    MAX_STEPS = "max_steps"
+
+
+class RunPhaseKind(str, Enum):
+    """监听回调所归属的运行阶段，供前端区分规划与逐步执行。"""
+
+    PLANNING = "planning"
+    STEP = "step"
+    DIRECT = "direct"
+
+
+@dataclass(frozen=True)
+class RunPhase:
+    """
+    单次 ReAct 或规划补全所处的阶段。
+
+    规划阶段仅 ``kind=PLANNING``；逐步执行时带 ``step_index`` 与 ``step_id``。
+    """
+
+    kind: RunPhaseKind
+    step_index: int | None = None
+    step_id: str | None = None
+
+
+@dataclass
+class AgentContext:
+    """
+    Agent 运行环境：语言模型、工具表与 ReAct 步数上限。
+
+    由 ``Agent`` 构造时创建；测试可替换 ``llm`` 等成员。
+    """
+
+    llm: LLMClient
+    tools: ToolRegistry
+    max_steps: int = 20
+    listeners: list[AgentListener] = field(default_factory=list)
+    on_run_begin: Callable[["RunContext"], None] | None = None
+    on_run_end: Callable[["RunContext"], None] | None = None
+
+
+@dataclass
+class ChatMessage:
+    """对话消息；用于历史记录与用户输入。"""
+
+    role: MessageRole
+    content: str
+    name: str | None = None
+
+    def to_api(self) -> dict[str, Any]:
+        item: dict[str, Any] = {"role": self.role, "content": self.content}
+        if self.name:
+            item["name"] = self.name
+        return item
+
+
+@dataclass
+class ToolInvocation:
+    """按顺序记录的一次工具调用；运行中更新思考与回答。"""
+
+    call_id: str
+    tool_name: str
+    arguments: dict[str, Any] = field(default_factory=dict)
+    thinking: str = ""
+    answer: str = ""
+    ok: bool = True
+
+
+@dataclass
+class RunContext:
+    """
+    单轮运行的上下文：输入、按序工具调用与最终输出。
+
+    运行上下文：系统提示与 messages；运行后读取 output 与 tool_invocations。
+    """
+
+    system_prompt: str = ""
+    ephemeral_skill_context: str = ""
+    messages: list[ChatMessage] = field(default_factory=list)
+    tool_invocations: list[ToolInvocation] = field(default_factory=list)
+    tool_turns: list[list[ToolInvocation]] = field(default_factory=list)
+    thinking: str = ""
+    output: str = ""
+    status: RunStatus = RunStatus.RUNNING
+    phase: RunPhase | None = None
+    def api_messages(self) -> list[dict[str, Any]]:
+        """组装送入语言模型的消息列表。"""
+        out: list[dict[str, Any]] = []
+        system = self._effective_system_prompt()
+        if system:
+            out.append({"role": "system", "content": system})
+        out.extend(m.to_api() for m in self.messages)
+        for turn in self.tool_turns:
+            tool_calls: list[dict[str, Any]] = []
+            for inv in turn:
+                tool_calls.append(
+                    {
+                        "id": inv.call_id,
+                        "type": "function",
+                        "function": {
+                            "name": inv.tool_name,
+                            "arguments": json.dumps(inv.arguments, ensure_ascii=False),
+                        },
+                    }
+                )
+            assistant: dict[str, Any] = {
+                "role": "assistant",
+                "content": turn[0].thinking or None,
+                "tool_calls": tool_calls,
+            }
+            out.append(assistant)
+            for inv in turn:
+                if inv.answer:
+                    out.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": inv.call_id,
+                            "content": inv.answer,
+                        }
+                    )
+        return out
+
+    def _effective_system_prompt(self) -> str:
+        base = self.system_prompt.strip()
+        extra = self.ephemeral_skill_context.strip()
+        if base and extra:
+            return f"{base}\n\n{extra}"
+        if extra:
+            return extra
+        return base

ai_agent/harness/__init__.py

@@ -0,0 +1,3 @@
+from ai_agent.harness.harness import Harness
+
+__all__ = ["Harness"]

ai_agent/harness/current_time.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from datetime import datetime
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+
+def get_current_time(timezone: str = "") -> str:
+    """
+    返回当前日期与时间。
+
+    Args:
+        timezone: IANA 时区名，如 Asia/Shanghai；留空则用本机本地时区
+
+    Returns:
+        ISO 8601 格式的时间字符串
+    """
+    if timezone.strip():
+        try:
+            tz = ZoneInfo(timezone.strip())
+        except ZoneInfoNotFoundError as exc:
+            raise ValueError(f"未知时区: {timezone}") from exc
+        now = datetime.now(tz)
+    else:
+        now = datetime.now().astimezone()
+    return now.isoformat(timespec="seconds")

ai_agent/harness/harness.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from ai_agent.harness.current_time import get_current_time
+from ai_agent.harness.process import run_python, run_shell
+from ai_agent.harness.sandbox import HarnessSandbox
+from ai_agent.skill.manager import SkillManager
+from ai_agent.skill.skill_kit import SkillKit
+from ai_agent.tools import Tool
+
+_HARNESS_TOOL_PREFIX = "harness"
+
+
+class Harness:
+    """
+    隔离工作区上的文件与进程能力；与对话代理核分离，由调用方构造后导出为工具列表。
+
+    路径均相对工作区根；可挂载只读技能区。工具说明与返回值不向模型暴露宿主机绝对路径。
+
+    Args:
+        workspace: 沙箱工作区根目录
+        skill_roots: 只读技能仓库根；与 skill_kit 二选一
+        skill_kit: 已构造的 SkillKit；与 skill_roots 二选一
+    """
+
+    def __init__(
+        self,
+        workspace: Path | str,
+        *,
+        skill_roots: (
+            Mapping[str, Path | str] | Sequence[Path | str] | Path | str | None
+        ) = None,
+        skill_kit: SkillKit | None = None,
+    ) -> None:
+        if skill_kit is not None and skill_roots is not None:
+            raise ValueError("skill_kit 与 skill_roots 不可同时指定")
+        self._sandbox = HarnessSandbox(Path(workspace))
+        self._prefix = _HARNESS_TOOL_PREFIX
+        self._skill_kit: SkillKit | None = None
+        if skill_kit is not None:
+            self._skill_kit = skill_kit
+        elif skill_roots is not None:
+            self._skill_kit = SkillKit(skill_roots)
+
+    @property
+    def workspace(self) -> Path:
+        """沙箱工作区根目录（供应用侧配置与测试使用，勿写入模型可见文案）。"""
+        return self._sandbox.root
+
+    @property
+    def skill(self) -> SkillKit:
+        """已配置的 SkillKit；未配置 skill_roots 时访问会报错。"""
+        if self._skill_kit is None:
+            raise ValueError("未配置 skill_roots")
+        return self._skill_kit
+
+    def _tool_name(self, short: str) -> str:
+        return f"{self._prefix}__{short}"
+
+    def read_file(self, path: str, offset: int = 1, limit: int = 0) -> str:
+        """
+        读取工作区内文本文件。
+
+        Args:
+            path: 相对工作区根的路径
+            offset: 起始行号，从 1 起
+            limit: 最多读取行数；0 表示读到末尾
+        """
+        return self._sandbox.read_text_file(path, offset=offset, limit=limit)
+
+    def write_file(self, path: str, content: str, append: bool = False) -> str:
+        """
+        写入或追加工作区内文本文件。
+
+        Args:
+            path: 相对工作区根的路径
+            content: 文件内容
+            append: 为 True 时追加
+        """
+        return self._sandbox.write_text_file(path, content, append=append)
+
+    def list_files(
+        self,
+        path: str = "",
+        max_entries: int = 200,
+        pattern: str = "",
+    ) -> str:
+        """
+        扫描工作区内文件与目录。
+
+        Args:
+            path: 相对工作区根的子目录；留空则扫描整个工作区
+            max_entries: 最多返回条数
+            pattern: 可选 glob，如 *.py
+        """
+        entries = self._sandbox.list_entries(
+            path,
+            max_entries=max_entries,
+            pattern=pattern,
+        )
+        if not entries:
+            return "（空）"
+        truncated = len(entries) >= max_entries
+        lines = "\n".join(entries)
+        if truncated:
+            lines += f"\n...（已达上限 {max_entries} 条）"
+        return lines
+
+    def run_shell(self, command: str, cwd: str = "", timeout_seconds: int = 0) -> str:
+        """
+        在工作区内执行 shell 命令。
+
+        Args:
+            command: shell 命令
+            cwd: 相对工作区的子目录；留空则用工作区根
+            timeout_seconds: 超时秒数；0 则用默认
+        """
+        work_dir = (
+            self._sandbox.root
+            if not cwd.strip()
+            else self._sandbox.resolve_path(cwd)
+        )
+        if not work_dir.is_dir():
+            raise ValueError(f"cwd 不是目录: {cwd or '.'}")
+        return run_shell(
+            command,
+            work_dir=work_dir,
+            timeout_seconds=timeout_seconds,
+        )
+
+    def run_python(self, code: str, timeout_seconds: int = 0) -> str:
+        """
+        在工作区根目录下执行 Python 代码片段。
+
+        Args:
+            code: Python 源码
+            timeout_seconds: 超时秒数；0 则用默认
+        """
+        return run_python(
+            code,
+            work_dir=self._sandbox.root,
+            timeout_seconds=timeout_seconds,
+        )
+
+    def workspace_info(self) -> str:
+        """说明隔离工作区约束（不包含宿主机绝对路径）。"""
+        return (
+            "隔离工作区已启用。所有路径均相对于工作区根；"
+            "无法读取或写入工作区外的文件。"
+            "使用 list_files 查看目录结构。"
+        )
+
+    def current_time(self, timezone: str = "") -> str:
+        """
+        返回当前日期与时间。
+
+        Args:
+            timezone: IANA 时区名，如 Asia/Shanghai；留空则用本机本地时区
+        """
+        return get_current_time(timezone)
+
+    def build_skill_tools(self) -> list[Tool]:
+        """生成 skill 管理 Tool 列表；须已配置 skill_roots。"""
+        return self.skill.build_management_tools()
+
+    def build_all_tools(self) -> list[Tool]:
+        """合并沙箱、skill 管理与已启用子工具（未配置 skill_roots 时仅沙箱）。"""
+        tools = self.build_tools()
+        if self._skill_kit is not None:
+            tools = tools + self._skill_kit.build_all_flat_tools()
+        return tools
+
+    @property
+    def skill_manager(self) -> SkillManager:
+        """已配置的 SkillManager；未配置 skill_roots 时访问会报错。"""
+        return self.skill.manager
+
+    def build_tools(self) -> list[Tool]:
+        """生成沙箱区 Tool 列表。"""
+        specs: list[tuple[str, str, dict[str, Any], Any]] = [
+            (
+                "read_file",
+                "读取隔离工作区内文本文件，返回带行号的内容。",
+                {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": "相对工作区根的文件路径",
+                        },
+                        "offset": {
+                            "type": "integer",
+                            "description": "起始行号，从 1 起，默认 1",
+                        },
+                        "limit": {
+                            "type": "integer",
+                            "description": "最多读取行数；0 表示读到末尾",
+                        },
+                    },
+                    "required": ["path"],
+                    "additionalProperties": False,
+                },
+                self.read_file,
+            ),
+            (
+                "write_file",
+                "写入或追加隔离工作区内文本文件，必要时创建父目录。",
+                {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": "相对工作区根的文件路径",
+                        },
+                        "content": {"type": "string", "description": "要写入的文本"},
+                        "append": {
+                            "type": "boolean",
+                            "description": "为 true 时追加，否则覆盖",
+                        },
+                    },
+                    "required": ["path", "content"],
+                    "additionalProperties": False,
+                },
+                self.write_file,
+            ),
+            (
+                "list_files",
+                "扫描隔离工作区内的文件与目录，仅返回相对路径。",
+                {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": "相对工作区根的子目录；留空扫描整个工作区",
+                        },
+                        "max_entries": {
+                            "type": "integer",
+                            "description": "最多返回条数，默认 200",
+                        },
+                        "pattern": {
+                            "type": "string",
+                            "description": "可选 glob，如 *.txt",
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+                self.list_files,
+            ),
+            (
+                "run_shell",
+                "在隔离工作区内执行 shell 命令，返回退出码与标准输出/错误。",
+                {
+                    "type": "object",
+                    "properties": {
+                        "command": {"type": "string", "description": "shell 命令"},
+                        "cwd": {
+                            "type": "string",
+                            "description": "相对工作区的子目录；留空则用工作区根",
+                        },
+                        "timeout_seconds": {
+                            "type": "integer",
+                            "description": "超时秒数，默认 120，上限 600",
+                        },
+                    },
+                    "required": ["command"],
+                    "additionalProperties": False,
+                },
+                self.run_shell,
+            ),
+            (
+                "run_python",
+                "在隔离工作区根目录下执行 Python 代码片段。",
+                {
+                    "type": "object",
+                    "properties": {
+                        "code": {"type": "string", "description": "Python 源码"},
+                        "timeout_seconds": {
+                            "type": "integer",
+                            "description": "超时秒数，默认 120，上限 600",
+                        },
+                    },
+                    "required": ["code"],
+                    "additionalProperties": False,
+                },
+                self.run_python,
+            ),
+            (
+                "workspace_info",
+                "查看隔离工作区的使用约束。",
+                {
+                    "type": "object",
+                    "properties": {},
+                    "additionalProperties": False,
+                },
+                self.workspace_info,
+            ),
+            (
+                "current_time",
+                "获取当前日期与时间，可按 IANA 时区名指定时区。",
+                {
+                    "type": "object",
+                    "properties": {
+                        "timezone": {
+                            "type": "string",
+                            "description": "IANA 时区名，如 Asia/Shanghai；省略则使用本机本地时区",
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+                self.current_time,
+            ),
+        ]
+        return [
+            Tool(
+                name=self._tool_name(short),
+                description=description,
+                parameters=parameters,
+                handler=handler,
+            )
+            for short, description, parameters, handler in specs
+        ]