初始化提交

backend/app/modules/agent/__init__.py

@@ -0,0 +1,19 @@
+"""通用 Agent 的纯领域契约。"""
+
+from app.modules.agent.definition import (
+    DEFAULT_CHAT_AGENT,
+    AgentDefinition,
+    ExecutionPolicy,
+    ToolPolicy,
+)
+from app.modules.agent.task import AgentTask, Plan, PlanStep
+
+__all__ = [
+    "DEFAULT_CHAT_AGENT",
+    "AgentDefinition",
+    "AgentTask",
+    "ExecutionPolicy",
+    "Plan",
+    "PlanStep",
+    "ToolPolicy",
+]

backend/app/modules/agent/definition.py

@@ -0,0 +1,44 @@
+"""通用 Agent 定义。
+
+定义保持纯数据；模型调用、工具执行与持久化仍由既有运行时负责。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class ExecutionPolicy:
+    """一次 Agent 运行的硬性边界。"""
+
+    max_iterations: int = 8
+
+    def __post_init__(self) -> None:
+        if self.max_iterations < 1:
+            raise ValueError("max_iterations 必须 >= 1")
+
+
+@dataclass(frozen=True)
+class ToolPolicy:
+    """本次运行允许暴露给模型的工具名称。空值表示沿用运行时默认工具集。"""
+
+    allowed_tools: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class AgentDefinition:
+    """可组合的 Agent 身份、提示、技能与执行边界。"""
+
+    name: str
+    system_prompt: str
+    model_hint: str | None = None
+    skill_refs: tuple[str, ...] = ()
+    tool_policy: ToolPolicy = field(default_factory=ToolPolicy)
+    execution_policy: ExecutionPolicy = field(default_factory=ExecutionPolicy)
+
+
+DEFAULT_CHAT_AGENT = AgentDefinition(
+    name="镜师",
+    system_prompt="你是魂镜当前默认人物。请使用中文，保持诚实、克制、清晰。",
+)

backend/app/modules/agent/task.py

@@ -0,0 +1,46 @@
+"""通用 Agent 的任务与计划纯领域契约。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+TaskStatus = Literal["queued", "running", "waiting_confirmation", "completed", "failed", "cancelled"]
+PlanStatus = Literal["draft", "approved", "running", "completed", "failed"]
+StepStatus = Literal["pending", "running", "completed", "failed", "skipped"]
+
+
+@dataclass(frozen=True)
+class PlanStep:
+    """可追踪的 Agent 计划步骤。"""
+
+    id: str
+    title: str
+    description: str = ""
+    tool: str | None = None
+    risk_level: str = "L2"
+    status: StepStatus = "pending"
+    result_summary: str | None = None
+
+
+@dataclass(frozen=True)
+class Plan:
+    """任务的显式执行计划。"""
+
+    steps: tuple[PlanStep, ...]
+    assumptions: tuple[str, ...] = ()
+    risks: tuple[str, ...] = ()
+    status: PlanStatus = "draft"
+
+
+@dataclass(frozen=True)
+class AgentTask:
+    """一次 Agent 执行的目标与可选计划。"""
+
+    id: str
+    objective: str
+    agent_name: str
+    run_id: str | None = None
+    status: TaskStatus = "queued"
+    plan: Plan | None = None
+    constraints: tuple[str, ...] = ()