langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/loop/model/tool_transcript_guard.py

@@ -0,0 +1,225 @@
+"""
+发往 LLM 前的 tool 消息管线修复（对齐 Claude Code `ensureToolResultPairing` 的 LangChain 子集）。
+
+实例（消息序列在干什么）
+------------------------
+
+下面用简写：AI = AIMessage（含 tool_calls），T = ToolMessage（对应一次 tool 结果）。
+
+**例 A — 同一条对话里 `call_id` 出现两次（压缩/重放后常见）**
+
+  修复前::
+
+    AI(call_id=foo) → T(foo) → AI(call_id=foo 又写一遍) → T(foo)
+
+  问题：第二次 AI 再声明 `foo`，提供商常报「tool_use id 必须唯一」。
+
+  修复后::
+
+    AI(call_id=foo) → T(foo) → AI(第二次不再带 foo) → 紧跟的那条 T(foo) 因对不上本轮 tool_calls，当孤儿删掉
+
+    （结果里只保留「第一轮」的 AI→T 配对，避免 id 重复上送 API。）
+
+**例 B — 同一次工具结果来了两遍（同一 `call_id` 两条 T）**
+
+  修复前::
+
+    AI(call_id=bar) → T(bar, 内容A) → T(bar, 内容B)
+
+  修复后：只保留**最后一条** T(bar)（内容B）。
+
+**例 C — AI 叫了工具但没等到结果（中断/丢消息）**
+
+  修复前::
+
+    AI(call_id=baz) → （没有 T(baz)）
+
+  修复后：在 T 的位置**补一条 synthetic ToolMessage(baz)**，让下一轮模型调用合法，不 400。
+
+**好处（为何放在 invoke 前，而不是靠提示词）：**
+- 提供商/SDK 对「同一 tool_call_id 重复」「tool_result 无对应 tool_use」「重复 tool_result」
+  往往直接 400；这是**协议约束**，与模型是否“注意”某段 System 提示无关。
+- 在绑定模型调用前做一次确定性清洗，可避免因压缩/重放/中断导致的会话卡死，属于 **Harness 工程**，
+  而不是对模型的软劝导。
+
+本模块只做 LangChain `AIMessage.tool_calls` + `ToolMessage` 序列可表达的修复：
+- 跨多条 assistant 消息按**首次出现**保留 `tool_call_id`，后续重复从 `tool_calls` 中剔除；
+- 紧跟某条 `AIMessage` 的连续 `ToolMessage` 中，同一 `tool_call_id` **只保留最后一条**；
+- 剔除不属于当前轮 `tool_calls` 的孤儿 `ToolMessage`；
+- 对仍缺少 `ToolMessage` 的 `tool_call`，追加与 `orphan_tool_results` 一致的 synthetic 占位。
+
+不修改图状态：仅作用于本次 `invoke/ainvoke` 使用的消息列表副本，每次进模型都会再修一遍，
+因此无需把修复结果写回 checkpoint 也能持续生效。
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from langchain_core.messages import AIMessage, ToolMessage
+
+from .orphan_tool_results import synthetic_tool_messages_for_orphan_tool_calls
+
+_DEFAULT_SYNTHETIC = (
+    "[Tool transcript repair: missing tool result; synthetic placeholder.]"
+)
+
+
+def _tool_call_id(tc: Any) -> str | None:
+    if isinstance(tc, dict):
+        tid = tc.get("id")
+        return str(tid) if tid is not None and str(tid) != "" else None
+    tid = getattr(tc, "id", None)
+    return str(tid) if tid is not None and str(tid) != "" else None
+
+
+def _tool_call_name(tc: Any) -> str:
+    if isinstance(tc, dict):
+        n = tc.get("name")
+        return str(n) if n else "unknown_tool"
+    n = getattr(tc, "name", None)
+    return str(n) if n else "unknown_tool"
+
+
+def _normalize_tool_call_dict(tc: Any) -> dict[str, Any]:
+    if isinstance(tc, dict):
+        return deepcopy(tc)
+    tid = _tool_call_id(tc)
+    return {
+        "name": _tool_call_name(tc),
+        "args": getattr(tc, "args", {}) or {},
+        "id": tid or "",
+        "type": "tool_call",
+    }
+
+
+def _copy_ai_with_tool_calls(m: AIMessage, new_calls: list[dict[str, Any]]) -> AIMessage:
+    if hasattr(m, "model_copy"):
+        try:
+            return m.model_copy(update={"tool_calls": new_calls})
+        except Exception:
+            pass
+    kwargs: dict[str, Any] = {"content": m.content, "tool_calls": new_calls}
+    for key in ("additional_kwargs", "response_metadata", "usage_metadata", "id", "name"):
+        if hasattr(m, key):
+            kwargs[key] = getattr(m, key)
+    return AIMessage(**kwargs)
+
+
+def repair_messages_for_llm_invoke(
+    messages: list[Any],
+    *,
+    synthetic_content_template: str = _DEFAULT_SYNTHETIC,
+) -> tuple[list[Any], dict[str, Any]]:
+    """返回 (修复后的消息列表, 统计信息)。输入不会被原地修改。"""
+    stats: dict[str, Any] = {
+        "repaired": False,
+        "dropped_duplicate_ai_tool_calls": 0,
+        "deduped_tool_messages": 0,
+        "dropped_orphan_tool_messages": 0,
+        "added_synthetic_tool_messages": 0,
+    }
+
+    if not messages:
+        return [], stats
+
+    out: list[Any] = []
+    seen_global_ids: set[str] = set()
+    i = 0
+    n = len(messages)
+
+    while i < n:
+        m = messages[i]
+        if isinstance(m, AIMessage) and getattr(m, "tool_calls", None):
+            raw_calls = list(m.tool_calls)
+            new_calls: list[dict[str, Any]] = []
+            for tc in raw_calls:
+                tid = _tool_call_id(tc)
+                if not tid:
+                    continue
+                if tid in seen_global_ids:
+                    stats["dropped_duplicate_ai_tool_calls"] += 1
+                    stats["repaired"] = True
+                    continue
+                seen_global_ids.add(tid)
+                new_calls.append(_normalize_tool_call_dict(tc))
+
+            ai2 = _copy_ai_with_tool_calls(m, new_calls)
+            out.append(ai2)
+            i += 1
+
+            batch: list[ToolMessage] = []
+            while i < n and isinstance(messages[i], ToolMessage):
+                batch.append(messages[i])
+                i += 1
+
+            last_by_id: dict[str, ToolMessage] = {}
+            for tm in batch:
+                raw_tid = getattr(tm, "tool_call_id", None)
+                if raw_tid is None:
+                    stats["dropped_orphan_tool_messages"] += 1
+                    stats["repaired"] = True
+                    continue
+                tid = str(raw_tid)
+                if tid in last_by_id:
+                    stats["deduped_tool_messages"] += 1
+                    stats["repaired"] = True
+                last_by_id[tid] = tm
+
+            valid_ids = {tid for tid in (_tool_call_id(tc) for tc in new_calls) if tid}
+
+            for tm in batch:
+                raw_tid = getattr(tm, "tool_call_id", None)
+                if raw_tid is None:
+                    continue
+                if str(raw_tid) not in valid_ids:
+                    stats["dropped_orphan_tool_messages"] += 1
+                    stats["repaired"] = True
+
+            ordered_tool_messages: list[ToolMessage] = []
+            for tc in new_calls:
+                tid = _tool_call_id(tc)
+                if not tid or tid not in valid_ids:
+                    continue
+                if tid not in last_by_id:
+                    continue
+                ordered_tool_messages.append(last_by_id[tid])
+
+            result_ids = {
+                str(tm.tool_call_id)
+                for tm in ordered_tool_messages
+                if getattr(tm, "tool_call_id", None) is not None
+            }
+
+            for tm in ordered_tool_messages:
+                out.append(tm)
+
+            pending_dicts: list[dict[str, Any]] = []
+            for tc in new_calls:
+                tid = _tool_call_id(tc)
+                if tid and tid not in result_ids:
+                    pending_dicts.append({"id": tid, "name": _tool_call_name(tc)})
+            if pending_dicts:
+                synth = synthetic_tool_messages_for_orphan_tool_calls(
+                    pending_tool_calls=pending_dicts,
+                    content_template=synthetic_content_template,
+                )
+                out.extend(synth)
+                stats["added_synthetic_tool_messages"] += len(synth)
+                stats["repaired"] = True
+            continue
+
+        if isinstance(m, ToolMessage):
+            stats["dropped_orphan_tool_messages"] += 1
+            stats["repaired"] = True
+            i += 1
+            continue
+
+        out.append(m)
+        i += 1
+
+    return out, stats
+
+
+__all__ = ["repair_messages_for_llm_invoke"]

langchain_agentx/loop/prompt/__init__.py

@@ -0,0 +1,95 @@
+"""loop.prompt — 系统提示词管理。
+
+提供三层能力：
+1. Section 注册表（sections.py）— 段的定义、记忆化、解析
+2. 优先级链（builder.py）— override → base → sections → append
+3. 内置 section 工厂（builtin.py）— 环境信息、语言偏好、时间、Git 安全等
+4. 压缩提示词（compact.py）— 上下文压缩用的提示词模板与格式化
+
+公开 API：
+    # 核心机制
+    SystemPromptSection  — 段数据类
+    section()            — 创建 session 级缓存的提示词段
+    volatile_section()   — 创建每轮重算的提示词段
+    resolve_sections()   — 解析段列表，返回文本列表
+    build_effective_system_prompt() — 优先级链构建器
+
+    # 内置 section 工厂
+    env_section()        — 环境信息（OS/Python/工作目录）
+    language_section()   — 语言偏好
+    time_section()       — 当前时间（volatile）
+    token_budget_section() — Token 预算提示
+    git_safety_section() — Git 安全红线（禁止 force-push 等危险操作）
+    tool_routing_guard_section() — 专用工具优先（系统级冗余强化）
+    actions_safety_section() — 高风险动作确认与可逆性优先
+    failure_diagnosis_section() — 失败后先诊断，不盲重试
+    task_execution_baseline_section() — 任务执行基线（先读后改、忠实汇报）
+    get_coding_sections() — 编码场景推荐 section 组合
+    tools_summary_section() — 工具列表摘要（volatile）
+
+    # 压缩提示词
+    get_compact_prompt() — 全量压缩提示词
+    get_partial_compact_prompt() — 部分压缩提示词
+    build_autocompact_llm_instruction_prompt() — 按类型选择压缩提示词
+    format_compact_summary() — 格式化压缩摘要
+    get_compact_user_summary_message() — 用户续写消息包装
+"""
+
+from .builder import build_effective_system_prompt
+from .builtin import (
+    env_section,
+    actions_safety_section,
+    failure_diagnosis_section,
+    get_coding_sections,
+    git_safety_section,
+    language_section,
+    task_execution_baseline_section,
+    time_section,
+    token_budget_section,
+    tool_routing_guard_section,
+    tools_summary_section,
+)
+from .compact import (
+    AutocompactLlmPromptKind,
+    PartialCompactDirection,
+    build_autocompact_llm_instruction_prompt,
+    format_compact_summary,
+    get_compact_prompt,
+    get_compact_user_summary_message,
+    get_partial_compact_prompt,
+)
+from .sections import (
+    SystemPromptSection,
+    resolve_sections,
+    section,
+    volatile_section,
+)
+
+__all__ = [
+    # 核心机制
+    "SystemPromptSection",
+    "section",
+    "volatile_section",
+    "resolve_sections",
+    "build_effective_system_prompt",
+    # 内置 section 工厂
+    "actions_safety_section",
+    "env_section",
+    "failure_diagnosis_section",
+    "get_coding_sections",
+    "git_safety_section",
+    "language_section",
+    "task_execution_baseline_section",
+    "time_section",
+    "token_budget_section",
+    "tool_routing_guard_section",
+    "tools_summary_section",
+    # 压缩提示词
+    "AutocompactLlmPromptKind",
+    "PartialCompactDirection",
+    "get_compact_prompt",
+    "get_partial_compact_prompt",
+    "build_autocompact_llm_instruction_prompt",
+    "format_compact_summary",
+    "get_compact_user_summary_message",
+]

langchain_agentx/loop/prompt/builder.py

@@ -0,0 +1,61 @@
+"""系统提示词优先级链构建器。
+
+对标 Claude  Code：
+  buildEffectiveSystemPrompt() → build_effective_system_prompt()
+
+优先级（从高到低）：
+  1. override_system_prompt  — 存在时直接返回，完全忽略其他所有来源
+  2. system_prompt           — 基础提示词
+  3. dynamic_sections        — session 级动态段（按列表顺序追加）
+  4. append_system_prompt    — 追加在最后
+
+注意：override 存在时，append_system_prompt 同样被忽略（与 CC 行为一致）。
+"""
+
+from __future__ import annotations
+
+from .sections import SystemPromptSection, resolve_sections
+
+
+def build_effective_system_prompt(
+    *,
+    system_prompt: str | None,
+    override_system_prompt: str | None,
+    append_system_prompt: str | None,
+    dynamic_sections: list[SystemPromptSection],
+    section_cache: dict[str, str | None],
+) -> str | None:
+    """构建当前轮次实际生效的系统提示词字符串。
+
+    优先级规则：
+    1. override 存在 → 直接返回，其余全部忽略（含 append）。
+    2. 否则：base + sections + append 按顺序拼接，段间以双换行分隔。
+    3. 全部为空 → 返回 None（不注入系统消息）。
+
+    Args:
+        system_prompt:          基础提示词字符串（已由 factory 从 str|SystemMessage 转换）。
+        override_system_prompt: 最高优先级覆盖提示词，存在时完全替换其他来源。
+        append_system_prompt:   追加在有效提示词末尾的字符串（override 时不追加）。
+        dynamic_sections:       session 级动态段列表，由 resolve_sections 解析。
+        section_cache:          来自 AgentState.section_cache，session 生命周期，
+                                函数内部通过 resolve_sections 原地更新。
+
+    Returns:
+        最终的系统提示词字符串，或 None（不注入任何系统消息）。
+    """
+    # 优先级 1：override 直接返回
+    if override_system_prompt is not None:
+        return override_system_prompt
+
+    # 优先级 2-3：解析动态 sections（session 级记忆化）
+    section_texts = resolve_sections(dynamic_sections, section_cache)
+
+    # 优先级 4：拼装 base + sections + append
+    parts: list[str] = []
+    if system_prompt:
+        parts.append(system_prompt)
+    parts.extend(section_texts)
+    if append_system_prompt:
+        parts.append(append_system_prompt)
+
+    return "\n\n".join(parts) if parts else None

langchain_agentx/loop/prompt/builtin.py

@@ -0,0 +1,218 @@
+"""内置 SystemPromptSection 工厂函数。
+
+提供框架级常用 section，供 create_loop_agent 与容器层组合使用。
+
+设计原则：
+- 每个工厂函数返回一个 SystemPromptSection
+- volatile=False 的 section 在 session 内只计算一次（环境信息、语言偏好等）
+- volatile=True 的 section 每轮重算（当前时间、动态工具列表等）
+- 所有文本内容写在代码中（暂不引入 templates/ 目录）
+"""
+
+from __future__ import annotations
+
+import platform
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from .sections import SystemPromptSection, section, volatile_section
+
+if TYPE_CHECKING:
+    from typing import Any
+
+
+def env_section() -> SystemPromptSection:
+    """环境信息 section（session 级缓存）。
+
+    包含：操作系统、Python 版本、工作目录。
+    """
+
+    def compute() -> str:
+        import os
+
+        return f"""# Environment
+You have been invoked in the following environment:
+ - Platform: {platform.system().lower()}
+ - OS Version: {platform.platform()}
+ - Python: {platform.python_version()}
+ - Working Directory: {os.getcwd()}"""
+
+    return section(name="env_info", compute=compute)
+
+
+def language_section(lang: str = "en") -> SystemPromptSection:
+    """语言偏好 section（session 级缓存）。
+
+    Args:
+        lang: 语言代码（"en" / "zh" / "ja" 等）
+    """
+
+    def compute() -> str | None:
+        if lang == "en":
+            return None  # 默认英文，不注入额外提示
+        if lang == "zh":
+            return "# Language\nRespond in Simplified Chinese (简体中文) unless the user explicitly requests another language."
+        if lang == "ja":
+            return "# Language\nRespond in Japanese (日本語) unless the user explicitly requests another language."
+        # 其他语言可按需扩展
+        return f"# Language\nRespond in {lang} unless the user explicitly requests another language."
+
+    return section(name="language", compute=compute)
+
+
+def time_section() -> SystemPromptSection:
+    """当前时间 section（volatile，每轮重算）。
+
+    用于需要时间感知的场景（如日志分析、时间敏感任务）。
+    """
+
+    def compute() -> str:
+        now = datetime.now()
+        return f"""# Current Time
+Current date and time: {now.strftime('%Y-%m-%d %H:%M:%S')}"""
+
+    return volatile_section(
+        name="current_time",
+        compute=compute,
+        reason="时间每轮变化，不能缓存",
+    )
+
+
+def token_budget_section(limit: int) -> SystemPromptSection:
+    """Token 预算提示 section（session 级缓存）。
+
+    Args:
+        limit: Token 预算上限
+    """
+
+    def compute() -> str:
+        return f"""# Token Budget
+You have a token budget of approximately {limit:,} tokens for this conversation. Be concise and efficient in your responses."""
+
+    return section(name="token_budget", compute=compute)
+
+
+def git_safety_section() -> SystemPromptSection:
+    """Git 安全红线 section（session 级缓存）。
+
+    说明：
+    - 该 section 仅提供规则文本，不负责决定是否注入。
+    - 是否启用由调用方在 dynamic_sections 装配阶段决定（例如编码模式下启用）。
+    """
+
+    def compute() -> str:
+        return """# Git Safety Protocol
+When using git-related commands, follow these safety constraints:
+- NEVER update git config unless the user explicitly requests it.
+- NEVER run destructive commands (e.g. push --force, reset --hard, checkout --, restore ., clean -f, branch -D) unless the user explicitly requests them.
+- NEVER skip hooks or signing checks (--no-verify, --no-gpg-sign, etc.) unless the user explicitly requests it.
+- NEVER force-push to main/master; warn the user if they request it.
+- Prefer creating a new commit instead of amending. If pre-commit hooks fail, fix issues and create a new commit rather than amending a previous commit.
+- Prefer safer alternatives before destructive operations."""
+
+    return section(name="git_safety", compute=compute)
+
+
+def tool_routing_guard_section() -> SystemPromptSection:
+    """系统级工具路由护栏 section（session 级缓存）。
+
+    作用：对 Bash 工具描述中的“专用工具优先”规则做冗余强化（defense in depth）。
+    """
+
+    def compute() -> str:
+        return """# Dedicated Tool Routing (Critical)
+Do NOT use bash when a relevant dedicated tool is available.
+Using dedicated tools improves user reviewability and execution safety.
+
+- To read files, use read_file instead of cat/head/tail.
+- To search file content, use grep instead of grep/rg via bash.
+- To search files by pattern, use glob instead of find/ls.
+- Reserve bash primarily for terminal operations that require shell execution (e.g., git/gh/system commands)."""
+
+    return section(name="tool_routing_guard", compute=compute)
+
+
+def actions_safety_section() -> SystemPromptSection:
+    """高风险操作确认与可逆性优先 section（session 级缓存）。"""
+
+    def compute() -> str:
+        return """# Executing Actions With Care
+Carefully consider reversibility and blast radius before acting.
+
+- Prefer local and reversible actions by default.
+- For risky or hard-to-reverse actions, confirm with the user before proceeding.
+- Do not use destructive commands as shortcuts when blocked; diagnose root causes first.
+- If you encounter unexpected state, investigate before deleting or overwriting."""
+
+    return section(name="actions_safety", compute=compute)
+
+
+def failure_diagnosis_section() -> SystemPromptSection:
+    """失败诊断优先 section（session 级缓存）。"""
+
+    def compute() -> str:
+        return """# Failure Diagnosis
+If an approach fails, diagnose why before switching tactics.
+
+- Read the error and verify assumptions.
+- Do not blindly retry the exact same failing action.
+- Prefer a focused fix over broad destructive workarounds."""
+
+    return section(name="failure_diagnosis", compute=compute)
+
+
+def task_execution_baseline_section() -> SystemPromptSection:
+    """任务执行基线 section（session 级缓存）。"""
+
+    def compute() -> str:
+        return """# Task Execution Baseline
+- Understand first: read relevant files and existing patterns before changing code.
+- Keep scope tight: avoid adding features or abstractions beyond the request.
+- Report outcomes faithfully: if checks fail, say they fail; if not run, say not run."""
+
+    return section(name="task_execution_baseline", compute=compute)
+
+
+def get_coding_sections() -> list[SystemPromptSection]:
+    """编码场景推荐 section 组合（仅返回列表，是否注入由调用方决定）。"""
+    return [
+        tool_routing_guard_section(),
+        git_safety_section(),
+        actions_safety_section(),
+        failure_diagnosis_section(),
+        task_execution_baseline_section(),
+    ]
+
+
+def tools_summary_section(tools: list[Any]) -> SystemPromptSection:
+    """工具列表摘要 section（volatile，工具可能动态变化）。
+
+    Args:
+        tools: 当前可用的工具列表
+    """
+
+    def compute() -> str:
+        tool_names = [getattr(t, "name", str(t)) for t in tools]
+        return f"""# Available Tools
+You have access to the following tools: {', '.join(tool_names)}"""
+
+    return volatile_section(
+        name="tools_summary",
+        compute=compute,
+        reason="工具列表可能在 session 中动态变化（Skill 激活/MCP 加载）",
+    )
+
+
+__all__ = [
+    "actions_safety_section",
+    "env_section",
+    "failure_diagnosis_section",
+    "get_coding_sections",
+    "git_safety_section",
+    "language_section",
+    "task_execution_baseline_section",
+    "time_section",
+    "token_budget_section",
+    "tool_routing_guard_section",
+    "tools_summary_section",
+]