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

ai_agent/app/harness_io.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+_INCOMING_DIR = "incoming"
+
+
+def reset_harness_workspace(harness_root: Path) -> None:
+    """
+    清空 Harness 工作区并重建空目录。
+
+    Args:
+        harness_root: Harness 沙箱根
+    """
+    root = harness_root.resolve()
+    if root.is_dir():
+        shutil.rmtree(root)
+    root.mkdir(parents=True, exist_ok=True)
+
+
+def stage_input_files(
+    source_paths: tuple[str, ...],
+    harness_root: Path,
+) -> tuple[str, ...]:
+    """
+    将用户文件复制到 Harness 的 incoming/ 子目录。
+
+    Args:
+        source_paths: 源文件路径列表
+        harness_root: Harness 沙箱根
+
+    Returns:
+        复制后相对于 Harness 根的路径（incoming/文件名）
+
+    Raises:
+        ValueError: 源路径不存在或不是文件
+    """
+    if not source_paths:
+        return ()
+    incoming = harness_root / _INCOMING_DIR
+    incoming.mkdir(parents=True, exist_ok=True)
+    staged: list[str] = []
+    used_names: set[str] = set()
+    for raw in source_paths:
+        source = Path(raw).expanduser().resolve()
+        if not source.is_file():
+            raise ValueError(f"输入文件不存在或不是文件: {raw}")
+        name = source.name
+        if name in used_names:
+            stem = source.stem
+            suffix = source.suffix
+            index = 2
+            while name in used_names:
+                name = f"{stem}_{index}{suffix}"
+                index += 1
+        used_names.add(name)
+        target = incoming / name
+        shutil.copy2(source, target)
+        rel = f"{_INCOMING_DIR}/{name}"
+        staged.append(rel)
+    return tuple(staged)
+
+
+def resolve_output_files(
+    relative_paths: tuple[str, ...],
+    harness_root: Path,
+) -> tuple[str, ...]:
+    """
+    将模型给出的相对路径解析为存在的宿主机绝对路径。
+
+    Args:
+        relative_paths: 相对 Harness 根的路径
+        harness_root: Harness 沙箱根
+
+    Returns:
+        仅包含已存在常规文件的路径
+    """
+    root = harness_root.resolve()
+    resolved: list[str] = []
+    for raw in relative_paths:
+        cleaned = raw.strip().replace("\\", "/")
+        if not cleaned:
+            continue
+        if Path(cleaned).is_absolute():
+            candidate = Path(cleaned).resolve()
+            try:
+                candidate.relative_to(root)
+            except ValueError:
+                continue
+        else:
+            candidate = (root / cleaned).resolve()
+            try:
+                candidate.relative_to(root)
+            except ValueError:
+                continue
+        if candidate.is_file():
+            resolved.append(str(candidate))
+    return tuple(resolved)
+
+
+def format_input_files_context(staged_paths: tuple[str, ...]) -> str:
+    """生成拼入规划或用户消息的附件说明。"""
+    if not staged_paths:
+        return ""
+    lines = ["## 用户附件（位于 Harness 工作区内）"]
+    for rel in staged_paths:
+        lines.append(f"- {rel}")
+    return "\n".join(lines)

ai_agent/app/output_format.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field, ValidationError
+
+from ai_agent.json_extract import extract_first_json_object
+
+_RUN_OUTPUT_INSTRUCTION = """
+## 最终交付格式（最后一步必须遵守）
+完成全部计划步骤后，你的**最终可见回复**必须是**仅含一个 JSON 对象**的文本，不要 Markdown 围栏，不要其它说明。字段：
+- ``answer``：面向用户的完整回答（字符串）
+- ``output_files``：需要交还给用户的文件路径数组，路径**相对 Harness 工作区根**（如 ``incoming/foo.xlsx``、``out/result.csv``）；无文件则 ``[]``
+
+格式硬性要求：
+- 整段输出必须是**合法 JSON**（可用单行，或仅在字符串内使用 ``\\n`` 表示换行）；``answer`` 内勿写入未转义的真实换行。
+- ``answer`` 字符串值内勿使用未转义的 ASCII 双引号（``"``）；须转义为 ``\\"`` 或改写为不含英文双引号的表述。
+- 除 JSON 外不要任何前后缀文字。
+""".strip()
+
+
+def run_output_instruction() -> str:
+    """返回须拼入计划最后一步用户消息末尾的交付格式说明。"""
+    return _RUN_OUTPUT_INSTRUCTION
+
+
+_STEP_INTERMEDIATE_INSTRUCTION = """
+## 本步产出要求
+本步不是计划的最后一步：勿输出最终交付用的 ``answer`` / ``output_files`` JSON。
+首行须写：``会话当前日期：YYYY-MM-DD（来源：builtin__current_time）``（本步已调用该工具时；日期取自工具返回）；首行前勿加 ``---`` 或其它前缀。
+其后用简洁中文记录本步**结论要点**（检索时间窗口、事实、条目），供后续步骤使用；条数贴近用户所要的条数，勿堆砌窗口外月份背景。
+本步各回合可见回复均用中文；勿写搜索重试过程、搜前搜后寒暄、「再搜一次」「进入下一步」等过程叙述；需要再搜时直接调用工具，勿先发文说明。
+同回合**禁止**与 ``builtin__current_time``（或 ``harness__current_time``）一并发起 ``bocha_search`` 等其它工具：须先单独一轮取时，待返回后再搜；并行发起时运行层只执行取时，搜索须下回合重写 query。
+若本步无可写产出可只回复「本步已完成」（已取时时仍保留首行日期行）。
+""".strip()
+
+
+def step_intermediate_instruction() -> str:
+    """返回拼入非最后计划步用户消息的产出说明。"""
+    return _STEP_INTERMEDIATE_INSTRUCTION
+
+
+class _StructuredRunBody(BaseModel):
+    answer: str = Field(description="面向用户的回答")
+    output_files: list[str] = Field(default_factory=list)
+
+
+def parse_structured_run_output(text: str) -> tuple[str, tuple[str, ...]]:
+    """
+    从模型最终文本解析结构化回答与输出文件列表。
+
+    Args:
+        text: 模型原始输出
+
+    Returns:
+        回答正文与相对 Harness 的文件路径元组；无法解析 JSON 时整段作为 answer
+    """
+    stripped = text.strip()
+    if not stripped:
+        return "", ()
+    payload = _extract_json_object(stripped)
+    if payload is None:
+        return stripped, ()
+    try:
+        body = _StructuredRunBody.model_validate(payload)
+    except ValidationError:
+        return stripped, ()
+    files = tuple(
+        p.strip()
+        for p in body.output_files
+        if isinstance(p, str) and p.strip()
+    )
+    return body.answer.strip() or stripped, files
+
+
+def _extract_json_object(text: str) -> dict[str, Any] | None:
+    return extract_first_json_object(text)

ai_agent/app/packet.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RunInputPacket(BaseModel):
+    """
+    应用运行入口的输入数据包。
+
+    由调用方构造并传入 ``AgentApp.run``；会话状态落在磁盘，单次调用结束后不保留会话实例。
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    user_name: str = Field(description="用户显示名，写入对话与记忆讲述者字段")
+    session_id: str = Field(description="会话标识，对应沙箱下 sessions/<id>/ 目录")
+    request: str = Field(description="本轮用户要求或任务说明")
+    input_files: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="用户传入的本地文件绝对或相对路径，将复制到本会话 Harness 的 incoming/ 下",
+    )
+    clear: bool = Field(
+        default=False,
+        description="为 True 时清空本会话 Harness 工作区、分层记忆存储与无 Memory 时的对话持久化",
+    )
+
+
+class RunOutputPacket(BaseModel):
+    """应用运行入口的输出数据包。"""
+
+    model_config = ConfigDict(extra="forbid")
+
+    user_name: str = Field(description="与输入包一致的用户名")
+    session_id: str = Field(description="与输入包一致的会话 id")
+    answer: str = Field(description="助手面向用户的最终文本")
+    output_files: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="模型声明须返回的文件路径（已解析为宿主机绝对路径且文件存在）",
+    )