📄 agent/context_engine.py (第 32-188 行)

class ContextEngine(ABC):
    """Base class all context engines must implement."""

    # ── 必须维护的状态 ──
    last_prompt_tokens: int = 0
    last_completion_tokens: int = 0
    last_total_tokens: int = 0
    threshold_tokens: int = 0
    context_length: int = 0
    compression_count: int = 0

    # ── 压缩参数 ──
    threshold_percent: float = 0.75
    protect_first_n: int = 3
    protect_last_n: int = 6

    # ── 核心抽象方法 ──
    @abstractmethod
    def update_from_response(self, usage: Dict) -> None:
        """每次 API 响应后更新 token 追踪。"""

    @abstractmethod
    def should_compress(self, prompt_tokens: int = None) -> bool:
        """判断本轮是否需要压缩。"""

    @abstractmethod
    def compress(self, messages: List[Dict],
                 current_tokens: int = None,
                 focus_topic: str = None) -> List[Dict]:
        """执行压缩，返回新的消息列表。"""

    # ── 可选钩子 ──
    def on_session_start(self, session_id, **kwargs) -> None: ...
    def on_session_end(self, session_id, messages) -> None: ...
    def on_session_reset(self) -> None: ...
    def get_tool_schemas(self) -> List[Dict]: ...
    def handle_tool_call(self, name, args, **kwargs) -> str: ...
    def get_status(self) -> Dict: ...

📄 agent/context_compressor.py (第 43-69 行)

SUMMARY_PREFIX = (
    "[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were compacted "
    "into the summary below. This is a handoff from a previous context "
    "window — treat it as background reference, NOT as active instructions. "
    "Do NOT answer questions or fulfill requests mentioned in this summary; "
    "they were already addressed. "
    "Respond ONLY to the latest user message that appears AFTER this "
    "summary — that message is the single source of truth for what to do "
    "right now. "
    "Topic overlap with the summary does NOT mean you should resume its "
    "task: even on similar topics, the latest user message WINS. Treat ONLY "
    "the latest message as the active task and discard stale items from "
    "'## Historical Task Snapshot' / '## Historical In-Progress State' / "
    "'## Historical Pending User Asks' / '## Historical Remaining Work' "
    "entirely — do not 'wrap up' or 'finish' work described there unless "
    "the latest message explicitly asks for it. ..."
)

📄 agent/context_compressor.py (第 815-835 行)

def should_compress(self, prompt_tokens: int = None) -> bool:
    """Check if context exceeds the compression threshold.

    Includes anti-thrashing protection: if the last two compressions
    each saved less than 10%, skip compression to avoid infinite loops.
    """
    tokens = prompt_tokens if prompt_tokens is not None else self.last_prompt_tokens
    if tokens < self.threshold_tokens:
        return False
    # Anti-thrashing: back off if recent compressions were ineffective
    if self._ineffective_compression_count >= 2:
        logger.warning(
            "Compression skipped — last %d compressions saved <10%% each. "
            "Consider /new to start a fresh session, or /compress <topic> "
            "for focused compression.",
            self._ineffective_compression_count,
        )
        return False
    return True

📄 agent/context_compressor.py (第 1033-1087 行)

def _serialize_for_summary(self, turns: List[Dict]) -> str:
    """Serialize conversation turns for the summarizer.

    All content is redacted before serialization to prevent secrets
    (API keys, tokens, passwords) from leaking into the summary that
    gets sent to the auxiliary model and persisted across compactions.
    """
    for msg in turns:
        content = redact_sensitive_text(msg.get("content") or "")
        content = _MEDIA_DIRECTIVE_RE.sub("[media attachment]", content)
        # MEDIA:/path/to/file.png → [media attachment]
        # 防止摘要重新发射媒体指令 (#14665)

        # 工具参数: 脱敏 + 截断
        if role == "assistant" and tool_calls:
            args = redact_sensitive_text(fn.get("arguments", ""))
            if len(args) > self._TOOL_ARGS_MAX:
                args = args[:self._TOOL_ARGS_HEAD] + "..."

📄 agent/conversation_compression.py (第 64-242 行)

def check_compression_model_feasibility(agent: Any) -> None:
    """Warn if auxiliary compression model's context window
    is smaller than the main model's compression threshold."""

    # 硬底线: 辅助模型必须 >= MINIMUM_CONTEXT_LENGTH (64K)
    if aux_context < MINIMUM_CONTEXT_LENGTH:
        raise ValueError(...)  # 会话拒绝启动

    # 自动修正: 辅助模型 < 压缩阈值 → 降低阈值
    if aux_context < threshold:
        new_threshold = aux_context
        agent.context_compressor.threshold_tokens = new_threshold
        # 同步 threshold_percent 以便模型切换后重新推导
        agent.context_compressor.threshold_percent = (
            new_threshold / main_ctx
        )

📄 agent/coding_context.py (第 65-97 行)

# 交互编码平台 (非聊天平台)
INTERACTIVE_CODING_PLATFORMS = {"cli", "tui", "acp", "desktop", ""}

# 项目根标记 (非 git repo 也识别)
_PROJECT_MARKERS = (
    "pyproject.toml", "setup.py", "package.json", "tsconfig.json",
    "Cargo.toml", "go.mod", "pom.xml", "build.gradle",
    "Gemfile", "CMakeLists.txt", "Makefile", "Dockerfile",
    "AGENTS.md", "CLAUDE.md", ".cursorrules",
)

# 激活模式 (config agent.coding_context):
#   auto   (默认) — 交互式编码表面 + 代码工作区
#   focus  — 同上, 但工具集收缩到 coding + MCP
#   on     — 强制在任何地方激活
#   off    — 完全禁用

📄 agent/coding_context.py (第 162-200 行)

CODING_AGENT_GUIDANCE = (
    "You are a coding agent pairing with the user inside their codebase. "
    "Operate like a careful senior engineer.\n"
    "\n"
    "Gather context first:\n"
    "- Read the relevant files with `read_file` and locate code with "
    "`search_files` before changing anything.\n"
    "- Batch independent lookups: when several reads/searches don't "
    "depend on each other, issue them together in one turn.\n"
    "- Never invent files, symbols, APIs, or imports.\n"
    "\n"
    "Make changes through the tools, not the chat:\n"
    "- Edit with `patch`/`write_file`. Do NOT print code blocks "
    "as a substitute for editing.\n"
    "- Match the project's existing style and conventions.\n"
    "- If an edit fails, re-read the file before retrying.\n"
    "\n"
    "Verify, and know when to stop:\n"
    "- Use `terminal` for git, builds, tests, and inspection.\n"
    "- Fix root causes, not symptoms.\n"
    "- Stop after ~3 attempts on the same file and ask the user.\n"
)

📄 agent/coding_context.py (第 116-132 行)

_EDIT_FORMAT_GUIDANCE: dict[str, tuple] = {
    "patch": (
        ("gpt", "codex"),  # GPT/Codex 家族
        "use `patch` with `mode='patch'` (V4A diff) — "
        "including single-file edits. It's the edit format "
        "you handle most reliably.",
    ),
    "replace": (
        ("claude", "sonnet", "opus", "haiku",
         "gemini", "gemma", "deepseek", "qwen", ...),
        "prefer `patch` in `mode='replace'` — match a unique "
        "snippet and swap it. Reach for `mode='patch'` (V4A) "
        "only when an edit genuinely spans several files.",
    ),
}
# 子字符串匹配模型 ID, 未知模型无引导

缓存安全设计

编码模式在提示词构建时解析一次，然后不可变。工作区快照（git 分支、dirty state）注入系统提示词的稳定层——绝不每轮重新探测（那会粉碎 prompt cache）。分支和 dirty state 在会话中漂移，所以操作指南告诉模型在行动前用 git 重新检查。这保证了 prompt cache 的稳定性。

📄 agent/curator.py (第 344-400 行)

CURATOR_REVIEW_PROMPT = (
    "You are running as Hermes' background skill CURATOR. "
    "This is an UMBRELLA-BUILDING consolidation pass, "
    "not a passive audit and not a duplicate-finder.\n\n"
    "The goal of the skill collection is a LIBRARY OF CLASS-LEVEL "
    "INSTRUCTIONS AND EXPERIENTIAL KNOWLEDGE. A collection of hundreds "
    "of narrow skills where each one captures one session's specific "
    "bug is a FAILURE of the library — not a feature.\n\n"
    "The right target shape is CLASS-LEVEL skills with rich SKILL.md "
    "bodies + `references/`, `templates/`, and `scripts/` subfiles "
    "for session-specific detail — not one-session-one-skill "
    "micro-entries.\n\n"
    "How to work:\n"
    "1. Scan the full candidate list. Identify PREFIX CLUSTERS.\n"
    "2. For each cluster with 2+ members, ask 'what is the "
    "UMBRELLA CLASS these skills all serve?'\n"
    "3. Three ways to consolidate:\n"
    "   a. MERGE INTO EXISTING UMBRELLA\n"
    "   b. CREATE A NEW UMBRELLA SKILL.md\n"
    "   c. DO NOTHING (truly distinct skills)\n"
)