┌──────────────────────────────────────────────────┐
│                  Agent Loop                       │
│                                                    │
│  用户输入 → [解析意图 → 推理决策 → 执行工具] × N → 输出  │
│                       ↑                              │
│                   [状态更新]                           │
└──────────────────────────────────────────────────┘

class AgentState:
    """Agent状态管理 - 分层存储模式"""

    def __init__(self, memory_system):
        self.system_prompt = ""        # 系统指令（不可变）
        self.short_term = []            # 当前会话上下文
        self.episodic = memory_system   # 跨会话记忆
        self.environment = {}           # 环境状态（文件系统、API等）
        self.execution_trace = []       # 执行轨迹（用于debug）

角色: 你是一个资深Python代码审查工程师
能力: 
  - 识别代码中的性能瓶颈和安全隐患
  - 提供符合PEP 8规范的优化建议
  - 理解异步编程和并发模型
约束:
  - 每次最多指出3个最重要的问题
  - 必须提供具体的代码示例
  - 不要修改项目的整体架构

请按以下步骤分析：
1. 首先，用一句话总结问题的核心
2. 列出解决问题所需的所有信息
3. 逐步推理每个子问题
4. 综合所有分析，给出最终答案

examples:
  - user: "查询上海的天气"
    assistant: |
      我将查询上海的天气信息。

      [工具调用: weather_api]
      参数: city="上海"

      根据查询结果，上海当前温度为22°C，晴转多云。
  - user: "帮我设置一个明天9点的会议提醒"
    assistant: |
      [工具调用: create_reminder]
      参数: time="2026-04-30 09:00", title="会议提醒"

      已为您设置明天上午9点的会议提醒。

你的输出必须符合以下JSON Schema:
{
  "action": "tool_name | respond",
  "parameters": { ... },
  "reasoning": "简短的中文推理过程"
}

PROMPT_REGISTRY = {
    "v1.0": {
        "system": "你是一个通用AI助手...",
        "temperature": 0.7,
        "metrics": {"accuracy": 0.82, "latency": 1.2}
    },
    "v1.1": {
        "system": "你是一个专业AI助手，擅长技术问答...",
        "temperature": 0.5,
        "metrics": {"accuracy": 0.87, "latency": 1.1}
    },
    "v2.0": {
        "system": "使用结构化CoT进行推理...",
        "temperature": 0.3,
        "metrics": {"accuracy": 0.91, "latency": 1.8}
    }
}

def build_dynamic_prompt(context):
    """根据当前上下文动态构建提示词"""

    prompt_parts = [
        ("base", BASE_SYSTEM_PROMPT),
    ]

    # 根据用户身份注入个性化指令
    if context.get("user_role") == "developer":
        prompt_parts.append(("role", DEVELOPER_INSTRUCTIONS))

    # 根据当前任务类型注入特定指令
    if context.get("task_type") == "code_review":
        prompt_parts.append(("task", CODE_REVIEW_INSTRUCTIONS))

    # 根据可用工具集注入工具描述
    if context.get("available_tools"):
        tools_doc = generate_tools_documentation(context["available_tools"])
        prompt_parts.append(("tools", tools_doc))

    # 根据历史对话注入上下文
    if context.get("conversation_history"):
        history = summarize_conversation(context["conversation_history"])
        prompt_parts.append(("history", history))

    return assemble_prompt(prompt_parts)

@tool(
    name="search_knowledge_base",
    description="在知识库中搜索相关信息，返回匹配的文档片段",
    parameters=[
        Parameter(name="query", type="string", required=True,
                  description="搜索关键词，建议使用简洁的关键词组合"),
        Parameter(name="top_k", type="integer", required=False,
                  default=5, description="返回结果数量"),
    ],
    timeout_ms=10000,
    retry_count=2,
    idempotent=True,  # 是否是幂等操作
)
def search_knowledge_base(query: str, top_k: int = 5) -> list:
    """在向量数据库中执行语义搜索"""
    ...

TOOL_CATEGORIES = {
    "query": ["search_knowledge_base", "read_file", ...],
    "edit": ["write_file", "patch", ...],
    "execute": ["terminal", "run_code", ...],
    "communicate": ["send_email", "send_message", ...],
}

def select_tools(query: str, all_tools: list, top_k: int = 5):
    """基于语义相似度选择最相关的工具"""
    query_embedding = embed(query)
    tool_embeddings = [embed(tool.description) for tool in all_tools]
    similarities = cosine_similarity(query_embedding, tool_embeddings)
    top_indices = np.argsort(similarities)[-top_k:][::-1]
    return [all_tools[i] for i in top_indices]

文件操作:
  - 读取文件 (read_file)
  - 写入文件 (write_file)
  - 搜索文件内容 (search_files)
  - 查找文件 (find_file)
网络操作:
  - 网页浏览 (browser_navigate)
  - Web搜索 (web_search)
  - API调用 (api_request)
代码操作:
  - 运行Python (execute_code)
  - 执行Shell命令 (terminal)
  - 安装依赖 (install_package)

class ToolExecutor:
    """工具执行器，含错误处理和重试逻辑"""

    async def execute(self, tool_call, max_retries=2):
        last_error = None

        for attempt in range(max_retries + 1):
            try:
                if attempt > 0:
                    # 指数退避
                    await asyncio.sleep(2 ** attempt)

                result = await tool_call.execute()

                if result.is_error:
                    # 判断是否可以重试
                    if result.error_type in ["timeout", "rate_limit", "transient"]:
                        continue
                    # 对于持久性错误，立即上报
                    return result

                return result

            except Exception as e:
                last_error = e
                log_warning(f"工具调用失败 (第{attempt+1}次尝试): {e}")

        # 所有重试均失败
        return ToolResult(
            is_error=True,
            error_type="max_retries_exceeded",
            error_message=str(last_error)
        )

# 顺序执行（有依赖关系）
result_a = await execute_tool("fetch_data", ...)
result_b = await execute_tool("process_data", data=result_a)

# 并行执行（无依赖关系）
results = await asyncio.gather(
    execute_tool("search_web", query="深度学习趋势"),
    execute_tool("search_knowledge_base", query="深度学习"),
    execute_tool("read_file", path="notes/deep-learning.md"),
)

# 条件执行（基于前一步结果）
if results[0].found_new_info:
    await execute_tool("update_knowledge_base", data=results[0])

class AgentTelemetry:
    """Agent遥测系统"""

    def __init__(self, tracer):
        self.tracer = tracer
        self.metrics = MetricsRegistry()

    async def trace_execution(self, agent_session):
        """追踪Agent的完整执行轨迹"""

        with self.tracer.start_span("agent_execution") as span:
            span.set_attribute("user_id", agent_session.user_id)
            span.set_attribute("task_type", agent_session.task_type)

            for step in agent_session.execution_steps:
                with self.tracer.start_span(f"step_{step.id}") as step_span:
                    step_span.set_attribute("tool", step.tool_name)
                    step_span.set_attribute("duration_ms", step.duration_ms)
                    step_span.set_attribute("success", step.success)

                    if step.error:
                        step_span.set_attribute("error", str(step.error))
                        step_span.set_status(Status.ERROR)

                    self.metrics.record_step(step)

class SecurityPolicy:
    """Agent安全策略引擎"""

    PERMISSION_MATRIX = {
        "read_file": {"allowed": True, "path_restriction": "/workspace/*"},
        "write_file": {"allowed": True, "path_restriction": "/workspace/output/*"},
        "terminal": {"allowed": True, "timeout_sec": 30},
        "send_email": {"allowed": False},  # 默认禁止
        "network_request": {"allowed": True, "domain_whitelist": ["*.api.github.com"]},
    }

    def validate_tool_call(self, tool_name, params):
        """验证工具调用是否在安全策略范围内"""
        policy = self.PERMISSION_MATRIX.get(tool_name)
        if not policy or not policy["allowed"]:
            raise SecurityViolation(f"禁止调用工具: {tool_name}")

        # 检查路径限制
        if "path_restriction" in policy:
            if not self._match_path(params.get("path", ""), policy["path_restriction"]):
                raise SecurityViolation(f"路径不在许可范围内: {params['path']}")

        return True

class CodeReviewAgent:
    """代码审查Agent - 完整的实战案例"""

    def __init__(self, llm_client, repo_accessor):
        self.llm = llm_client
        self.repo = repo_accessor
        self.tools = [
            Tool("fetch_pr_diff", "获取PR的diff内容", 
                 params={"pr_number": int}),
            Tool("search_codebase", "搜索代码库中的相关函数定义",
                 params={"query": str, "file_pattern": str}),
            Tool("run_linter", "运行静态代码分析",
                 params={"file_path": str}),
            Tool("check_test_coverage", "检查测试覆盖率",
                 params={"file_path": str}),
            Tool("post_review_comment", "在PR上发布审查评论",
                 params={"pr_number": int, "comment": str, 
                         "file_path": str, "line": int}),
        ]

    async def review_pr(self, pr_number: int):
        """执行完整的PR审查流程"""

        # 步骤1: 获取PR基本信息（工具调用）
        pr_info = await self.tools["fetch_pr_diff"].execute(
            pr_number=pr_number
        )

        # 步骤2: 分析变更的文件（LLM推理）
        analysis = await self.llm.analyze([
            "分析以下代码变更，识别：",
            "- 可能存在的bug和安全隐患",
            "- 性能优化机会",
            "- 代码风格问题",
            "- 测试覆盖缺口",
            f"代码变更: {pr_info['diff'][:8000]}"
        ])

        # 步骤3: 对每个问题深入检查（工具+LLM循环）
        for issue in analysis["issues"]:
            if issue["requires_deeper_lookup"]:
                context = await self.tools["search_codebase"].execute(
                    query=issue["related_code"],
                    file_pattern=issue.get("file_pattern")
                )
                issue["context"] = context

        # 步骤4: 生成审查报告并发布
        report = await self._generate_review_report(analysis)
        await self.tools["post_review_comment"].execute(
            pr_number=pr_number,
            comment=report
        )

        return report

CODE_REVIEW_SYSTEM_PROMPT = """
你是一个专业的代码审查工程师，隶属于开源项目维护团队。

## 你的审查标准
1. **正确性**: 代码逻辑是否正确？是否存在边界条件错误？
2. **安全性**: 是否存在SQL注入、XSS、权限泄露等安全问题？
3. **性能**: 是否存在不必要的循环、冗余查询或内存泄漏？
4. **可维护性**: 代码是否清晰？命名是否规范？是否有足够的注释？
5. **测试**: 新增代码是否有对应的单元测试？

## 输出格式
请按以下JSON格式输出审查结果:
{
  "summary": "审查总体评价",
  "issues": [
    {
      "severity": "critical|major|minor|suggestion",
      "file": "文件路径",
      "line": 行号,
      "description": "问题描述",
      "suggestion": "修改建议（含代码示例）"
    }
  ],
  "approve": true|false,
  "test_coverage_ok": true|false
}
"""