better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/browser-supervisor.md

@@ -0,0 +1,160 @@
+# Browser CDP Supervisor — 设计文档
+
+**状态：** 已发布（PR 14540）
+**最后更新：** 2026-04-23
+**作者：** @teknium1
+
+## 问题
+
+原生 JS 对话框（`alert`/`confirm`/`prompt`/`beforeunload`）和 iframe 是我们浏览器工具中最大的两个缺口：
+
+1. **对话框会阻塞 JS 线程。** 页面上的任何操作都会挂起，直到对话框被处理。在此工作之前，agent 无法感知对话框是否已打开——后续的工具调用会挂起或抛出不透明的错误。
+2. **iframe 不可见。** Agent 可以在 DOM 快照中看到 iframe 节点，但无法在其中点击、输入或执行 eval——尤其是运行在独立 Chromium 进程中的跨域（OOPIF）iframe。
+
+[PR #12550](https://github.com/NousResearch/hermes-agent/pull/12550) 提出了一个无状态的 `browser_dialog` 包装器。该方案无法解决检测问题——它只是在 agent 已经（通过症状）知道对话框已打开时，提供了一个更简洁的 CDP 调用。已作为被取代方案关闭。
+
+## 后端能力矩阵（2026-04-23 实测验证）
+
+使用一次性探测脚本，针对一个在主框架和同源 srcdoc iframe 中触发 alert 的 data-URL 页面，以及一个跨域 `https://example.com` iframe 进行测试：
+
+| 后端 | 对话框检测 | 对话框响应 | 框架树 | OOPIF `Runtime.evaluate`（通过 `browser_cdp(frame_id=...)`） |
+|---|---|---|---|---|
+| 本地 Chrome（`--remote-debugging-port`）/ `/browser connect` | ✓ | ✓ 完整流程 | ✓ | ✓ |
+| Browserbase | ✓（通过 bridge） | ✓ 完整流程（通过 bridge） | ✓ | ✓（`document.title = "Example Domain"` 已在真实跨域 iframe 上验证） |
+| Camofox | ✗ 无 CDP（仅 REST） | ✗ | 通过 DOM 快照部分支持 | ✗ |
+
+**Browserbase 响应的工作原理。** Browserbase 的 CDP 代理在内部使用 Playwright，并在约 10ms 内自动关闭原生对话框，因此 `Page.handleJavaScriptDialog` 无法跟上。为解决此问题，supervisor 通过 `Page.addScriptToEvaluateOnNewDocument` 注入一个 bridge 脚本，将 `window.alert`/`confirm`/`prompt` 覆盖为向魔法主机（`hermes-dialog-bridge.invalid`）发起的同步 XHR。`Fetch.enable` 在这些 XHR 触达网络之前将其拦截——对话框变成 supervisor 捕获的 `Fetch.requestPaused` 事件，`respond_to_dialog` 通过 `Fetch.fulfillRequest` 以 JSON 响应体完成请求，注入的脚本对其进行解码。
+
+最终效果：从页面角度看，`prompt()` 仍然返回 agent 提供的字符串。从 agent 角度看，无论哪种方式，都是同一套 `browser_dialog(action=...)` API。已针对真实 Browserbase 会话进行端到端测试——4/4（alert/prompt/confirm-accept/confirm-dismiss）全部通过，包括值回传到页面 JS 的验证。
+
+Camofox 在本 PR 中暂不支持；计划在 `jo-inc/camofox-browser` 提交上游 issue，请求添加对话框轮询端点。
+
+## 架构
+
+### CDPSupervisor
+
+每个 Hermes `task_id` 对应一个在后台守护线程中运行的 `asyncio.Task`。持有一个到后端 CDP 端点的持久 WebSocket 连接。维护：
+
+- **对话框队列** — `List[PendingDialog]`，包含 `{id, type, message, default_prompt, session_id, opened_at}`
+- **框架树** — `Dict[frame_id, FrameInfo]`，包含父子关系、URL、origin，以及是否为跨域子会话
+- **会话映射** — `Dict[session_id, SessionInfo]`，供交互工具将操作路由到正确的已附加会话以执行 OOPIF 操作
+- **近期控制台错误** — 最近 50 条的环形缓冲区（用于 PR 2 诊断）
+
+附加时订阅：
+- `Page.enable` — `javascriptDialogOpening`、`frameAttached`、`frameNavigated`、`frameDetached`
+- `Runtime.enable` — `executionContextCreated`、`consoleAPICalled`、`exceptionThrown`
+- `Target.setAutoAttach {autoAttach: true, flatten: true}` — 暴露子 OOPIF target；supervisor 在每个上启用 `Page`+`Runtime`
+
+通过快照锁实现线程安全的状态访问；工具处理器（同步）读取冻结快照，无需 await。
+
+### 生命周期
+
+- **启动：** `SupervisorRegistry.get_or_start(task_id, cdp_url)` — 由 `browser_navigate`、Browserbase 会话创建、`/browser connect` 调用。幂等。
+- **停止：** 会话拆除或 `/browser disconnect`。取消 asyncio task，关闭 WebSocket，丢弃状态。
+- **重新绑定：** 若 CDP URL 变更（用户重新连接到新的 Chrome），停止旧 supervisor 并重新启动——绝不跨端点复用状态。
+
+### 对话框策略
+
+通过 `config.yaml` 中的 `browser.dialog_policy` 配置：
+
+- **`must_respond`**（默认）— 捕获，在 `browser_snapshot` 中呈现，等待显式的 `browser_dialog(action=...)` 调用。在 300s 安全超时后若无响应，则自动关闭并记录日志。防止有缺陷的 agent 永久挂起。
+- `auto_dismiss` — 记录并立即关闭；agent 事后通过 `browser_snapshot` 内的 `browser_state` 查看。
+- `auto_accept` — 记录并接受（适用于用户希望干净导航离开时的 `beforeunload`）。
+
+策略按 task 配置；v1 不支持按对话框覆盖。
+
+## Agent 接口（PR 1）
+
+### 一个新工具
+
+```
+browser_dialog(action, prompt_text=None, dialog_id=None)
+```
+
+- `action="accept"` / `"dismiss"` → 响应指定的或唯一待处理的对话框（必填）
+- `prompt_text=...` → 向 `prompt()` 对话框提供的文本
+- `dialog_id=...` → 当多个对话框排队时用于消歧（罕见）
+
+该工具仅用于响应。Agent 在调用前从 `browser_snapshot` 输出中读取待处理对话框。
+
+### `browser_snapshot` 扩展
+
+当 supervisor 已附加时，在现有快照输出中新增三个可选字段：
+
+```json
+{
+  "pending_dialogs": [
+    {"id": "d-1", "type": "alert", "message": "Hello", "opened_at": 1650000000.0}
+  ],
+  "recent_dialogs": [
+    {"id": "d-1", "type": "alert", "message": "...", "opened_at": 1650000000.0,
+     "closed_at": 1650000000.1, "closed_by": "remote"}
+  ],
+  "frame_tree": {
+    "top": {"frame_id": "FRAME_A", "url": "https://example.com/", "origin": "https://example.com"},
+    "children": [
+      {"frame_id": "FRAME_B", "url": "about:srcdoc", "is_oopif": false},
+      {"frame_id": "FRAME_C", "url": "https://ads.example.net/", "is_oopif": true, "session_id": "SID_C"}
+    ],
+    "truncated": false
+  }
+}
+```
+
+- **`pending_dialogs`**：当前阻塞页面 JS 线程的对话框。Agent 必须调用 `browser_dialog(action=...)` 进行响应。在 Browserbase 上为空，因为其 CDP 代理会在约 10ms 内自动关闭对话框。
+
+- **`recent_dialogs`**：最近关闭的最多 20 个对话框的环形缓冲区，带有 `closed_by` 标签——`"agent"`（我们响应了）、`"auto_policy"`（本地 auto_dismiss/auto_accept）、`"watchdog"`（must_respond 超时触发）或 `"remote"`（浏览器/后端主动关闭，例如 Browserbase）。这是 Browserbase 上的 agent 仍能了解发生了什么的方式。
+
+- **`frame_tree`**：框架结构，包括跨域（OOPIF）子框架。上限为 30 条 + OOPIF 深度 2，以限制广告密集页面上的快照大小。当达到限制时，`truncated: true` 会出现；需要完整树的 agent 可使用 `browser_cdp` 配合 `Page.getFrameTree`。
+
+以上均不新增工具 schema 接口——agent 从其已请求的快照中读取。
+
+### 可用性门控
+
+两个接口均通过 `_browser_cdp_check` 进行门控（supervisor 只能在 CDP 端点可达时运行）。在 Camofox / 无后端会话中，对话框工具被隐藏，快照省略新字段——不产生 schema 膨胀。
+
+## 跨域 iframe 交互
+
+在对话框检测工作的基础上，`browser_cdp(frame_id=...)` 通过 supervisor 已连接的 WebSocket，使用 OOPIF 的子 `sessionId` 路由 CDP 调用（尤其是 `Runtime.evaluate`）。Agent 从 `browser_snapshot.frame_tree.children[]` 中 `is_oopif=true` 的条目获取 frame_id，并将其传递给 `browser_cdp`。对于同源 iframe（无专用 CDP 会话），agent 改用顶层 `Runtime.evaluate` 中的 `contentWindow`/`contentDocument`——当 `frame_id` 属于非 OOPIF 时，supervisor 会返回指向该回退方案的错误。
+
+在 Browserbase 上，这是 iframe 交互的**唯一**可靠路径——无状态 CDP 连接（每次 `browser_cdp` 调用时打开）会遭遇签名 URL 过期，而 supervisor 的长连接则保持有效会话。
+
+## Camofox（后续跟进）
+
+计划向 `jo-inc/camofox-browser` 提交 issue，添加：
+- 每个会话的 Playwright `page.on('dialog', handler)`
+- `GET /tabs/:tabId/dialogs` 轮询端点
+- `POST /tabs/:tabId/dialogs/:id` 用于接受/关闭
+- 框架树内省端点
+
+## 涉及文件（PR 1）
+
+### 新增
+
+- `tools/browser_supervisor.py` — `CDPSupervisor`、`SupervisorRegistry`、`PendingDialog`、`FrameInfo`
+- `tools/browser_dialog_tool.py` — `browser_dialog` 工具处理器
+- `tests/tools/test_browser_supervisor.py` — 模拟 CDP WebSocket 服务器 + 生命周期/状态测试
+- `website/docs/developer-guide/browser-supervisor.md` — 本文件
+
+### 修改
+
+- `toolsets.py` — 在 `browser`、`hermes-acp`、`hermes-api-server`、核心工具集中注册 `browser_dialog`（通过 CDP 可达性门控）
+- `tools/browser_tool.py`
+  - `browser_navigate` 启动钩子：若 CDP URL 可解析，调用 `SupervisorRegistry.get_or_start(task_id, cdp_url)`
+  - `browser_snapshot`（约第 1536 行）：将 supervisor 状态合并到返回载荷
+  - `/browser connect` 处理器：以新端点重启 supervisor
+  - `_cleanup_browser_session` 中的会话拆除钩子
+- `hermes_cli/config.py` — 向 `DEFAULT_CONFIG` 添加 `browser.dialog_policy` 和 `browser.dialog_timeout_s`
+- 文档：`website/docs/user-guide/features/browser.md`、`website/docs/reference/tools-reference.md`、`website/docs/reference/toolsets-reference.md`
+
+## 非目标
+
+- Camofox 的检测/交互（上游缺口；单独跟踪）
+- 向用户实时流式传输对话框/框架事件（需要 gateway 钩子）
+- 跨会话持久化对话框历史（仅内存）
+- 按 iframe 配置对话框策略（agent 可通过 `dialog_id` 表达）
+- 替换 `browser_cdp`——它作为长尾场景（cookies、viewport、网络限速）的逃生舱口继续保留
+
+## 测试
+
+单元测试使用 asyncio 模拟 CDP 服务器，该服务器实现了足够的协议子集，以覆盖所有状态转换：附加、启用、导航、对话框触发、对话框关闭、框架附加/分离、子 target 附加、会话拆除。真实后端端到端测试（Browserbase + 本地 Chromium 系浏览器）为手动执行——通过 `/browser connect` 连接到实时 Chromium 系浏览器，并运行上述对话框/框架测试用例。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/context-compression-and-caching.md

@@ -0,0 +1,328 @@
+---
+title: 上下文压缩与缓存
+description: Hermes Agent 如何通过双重压缩系统和 Anthropic prompt 缓存高效管理上下文窗口。
+---
+
+# 上下文压缩与缓存
+
+Hermes Agent 使用双重压缩系统和 Anthropic prompt（提示词）缓存，在长对话中高效管理上下文窗口用量。
+
+源文件：`agent/context_engine.py`（ABC）、`agent/context_compressor.py`（默认引擎）、
+`agent/prompt_caching.py`、`gateway/run.py`（会话清理）、`run_agent.py`（搜索 `_compress_context`）
+
+
+## 可插拔上下文引擎
+
+上下文管理基于 `ContextEngine` ABC（`agent/context_engine.py`）构建。内置的 `ContextCompressor` 是默认实现，但插件可以用其他引擎替换它（例如无损上下文管理）。
+
+```yaml
+context:
+  engine: "compressor"    # default — built-in lossy summarization
+  engine: "lcm"           # example — plugin providing lossless context
+```
+
+引擎负责：
+- 决定何时触发压缩（`should_compress()`）
+- 执行压缩（`compress()`）
+- 可选地暴露 agent 可调用的工具（例如 `lcm_grep`）
+- 追踪 API 响应中的 token 用量
+
+通过 `config.yaml` 中的 `context.engine` 进行配置驱动选择。解析顺序：
+1. 检查 `plugins/context_engine/<name>/` 目录
+2. 检查通用插件系统（`register_context_engine()`）
+3. 回退到内置 `ContextCompressor`
+
+插件引擎**永远不会自动激活**——用户必须在 `context.engine` 中显式设置插件名称。默认的 `"compressor"` 始终使用内置实现。
+
+通过 `hermes plugins` → Provider Plugins → Context Engine 进行配置，或直接编辑 `config.yaml`。
+
+关于构建上下文引擎插件，请参阅 [Context Engine 插件](/developer-guide/context-engine-plugin)。
+
+## 双重压缩系统
+
+Hermes 有两个独立运行的压缩层：
+
+```
+                     ┌──────────────────────────┐
+  Incoming message   │   Gateway Session Hygiene │  Fires at 85% of context
+  ─────────────────► │   (pre-agent, rough est.) │  Safety net for large sessions
+                     └─────────────┬────────────┘
+                                   │
+                                   ▼
+                     ┌──────────────────────────┐
+                     │   Agent ContextCompressor │  Fires at 50% of context (default)
+                     │   (in-loop, real tokens)  │  Normal context management
+                     └──────────────────────────┘
+```
+
+### 1. Gateway 会话清理（85% 阈值）
+
+位于 `gateway/run.py`（搜索 `Session hygiene: auto-compress`）。这是一个**安全网**，在 agent 处理消息之前运行。它防止会话在两次交互之间增长过大时（例如 Telegram/Discord 中的隔夜积累）导致 API 失败。
+
+- **阈值**：固定为模型上下文长度的 85%
+- **Token 来源**：优先使用上一轮 API 实际报告的 token 数；回退到基于字符的粗略估算（`estimate_messages_tokens_rough`）
+- **触发条件**：仅当 `len(history) >= 4` 且压缩已启用时
+- **目的**：捕获逃过 agent 自身压缩器的会话
+
+Gateway 清理阈值有意高于 agent 压缩器的阈值。将其设置为 50%（与 agent 相同）会导致长 gateway 会话在每一轮都过早触发压缩。
+
+### 2. Agent ContextCompressor（50% 阈值，可配置）
+
+位于 `agent/context_compressor.py`。这是**主要压缩系统**，在 agent 的工具循环内运行，可访问准确的 API 报告 token 数。
+
+
+## 配置
+
+所有压缩设置从 `config.yaml` 的 `compression` 键读取：
+
+```yaml
+compression:
+  enabled: true              # Enable/disable compression (default: true)
+  threshold: 0.50            # Fraction of context window (default: 0.50 = 50%)
+  target_ratio: 0.20         # How much of threshold to keep as tail (default: 0.20)
+  tail_mode: legacy          # 尾部保留策略：legacy | lean（默认 legacy）
+  protect_last_n: 20         # Minimum protected tail messages (default: 20)
+
+# Summarization model/provider configured under auxiliary:
+auxiliary:
+  compression:
+    model: null              # Override model for summaries (default: auto-detect)
+    provider: auto           # Provider: "auto", "openrouter", "nous", "main", etc.
+    base_url: null           # Custom OpenAI-compatible endpoint
+```
+
+### 参数详情
+
+| 参数 | 默认值 | 范围 | 描述 |
+|-----------|---------|-------|-------------|
+| `threshold` | `0.50` | 0.0-1.0 | 当 prompt token 数 ≥ `threshold × context_length` 时触发压缩 |
+| `target_ratio` | `0.20` | 0.10-0.80 | 控制尾部保护 token 预算：`threshold_tokens × target_ratio` |
+| `tail_mode` | `legacy` | `legacy`、`lean` | 尾部保留策略。`legacy` 保留 `target_ratio` 大小的逐字尾部（大窗口模型约 100K+ token）。`lean` 保留截取后的尾部（窗口的 2.5%，下限 10K、上限 25K），并将连续性移入摘要：压缩区域的分块保标识符摘录、机械提取的锚点索引（PR 编号、SHA、路径、报错文本 — 正则提取，绝不改写）、逐字引用的全部真实用户消息，以及 `session_search` 恢复指引。在 500K token 的真实会话上：保留约 49K（对比 162K）。压缩边界会多出数次摘要模型调用。lean 尾部中较旧的工具输出会降级为带恢复指引的单行占位 |
+| `protect_last_n` | `20` | ≥1 | 始终保留的最近消息最小数量 |
+| `protect_first_n` | `3` | （硬编码）| 系统提示词 + 首次交互始终保留 |
+
+### 计算值（200K 上下文模型，默认参数）
+
+```
+context_length       = 200,000
+threshold_tokens     = 200,000 × 0.50 = 100,000
+tail_token_budget    = 100,000 × 0.20 = 20,000
+max_summary_tokens   = min(200,000 × 0.05, 12,000) = 10,000
+```
+
+
+## 压缩算法
+
+`ContextCompressor.compress()` 方法遵循 4 阶段算法：
+
+### 阶段 1：清除旧工具结果（廉价，无需 LLM 调用）
+
+保护尾部之外的旧工具结果（>200 字符）将被替换为：
+```
+[Old tool output cleared to save context space]
+```
+
+这是一个廉价的预处理步骤，可从冗长的工具输出（文件内容、终端输出、搜索结果）中节省大量 token。
+
+### 阶段 2：确定边界
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Message list                                               │
+│                                                             │
+│  [0..2]  ← protect_first_n (system + first exchange)        │
+│  [3..N]  ← middle turns → SUMMARIZED                        │
+│  [N..end] ← tail (by token budget OR protect_last_n)        │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+尾部保护基于 **token 预算**：从末尾向前遍历，累积 token 直到预算耗尽。如果预算保护的消息数少于固定的 `protect_last_n`，则回退到该固定数量。
+
+边界对齐以避免拆分 tool_call/tool_result 组。`_align_boundary_backward()` 方法会跳过连续的工具结果，找到父级 assistant 消息，保持组的完整性。
+
+### 阶段 3：生成结构化摘要
+
+:::warning 摘要模型上下文长度
+摘要模型的上下文窗口必须**至少与主 agent 模型一样大**。整个中间部分通过单次 `call_llm(task="compression")` 调用发送给摘要模型。如果摘要模型的上下文更小，API 将返回上下文长度错误——`_generate_summary()` 会捕获该错误，记录警告并返回 `None`。压缩器随后会**在没有摘要的情况下丢弃中间轮次**，静默丢失对话上下文。这是压缩质量下降最常见的原因。
+:::
+
+中间轮次使用辅助 LLM 以结构化模板进行摘要：
+
+```
+## Goal
+[What the user is trying to accomplish]
+
+## Constraints & Preferences
+[User preferences, coding style, constraints, important decisions]
+
+## Progress
+### Done
+[Completed work — specific file paths, commands run, results]
+### In Progress
+[Work currently underway]
+### Blocked
+[Any blockers or issues encountered]
+
+## Key Decisions
+[Important technical decisions and why]
+
+## Relevant Files
+[Files read, modified, or created — with brief note on each]
+
+## Next Steps
+[What needs to happen next]
+
+## Critical Context
+[Specific values, error messages, configuration details]
+```
+
+摘要预算随被压缩内容的量动态调整：
+- 公式：`content_tokens × 0.20`（`_SUMMARY_RATIO` 常量）
+- 最小值：2,000 token
+- 最大值：`min(context_length × 0.05, 12,000)` token
+
+### 阶段 4：组装压缩后的消息
+
+压缩后的消息列表为：
+1. 头部消息（首次压缩时在系统提示词后追加一条说明）
+2. 摘要消息（角色经过选择以避免连续相同角色违规）
+3. 尾部消息（未修改）
+
+`_sanitize_tool_pairs()` 清理孤立的 tool_call/tool_result 对：
+- 引用已删除调用的工具结果 → 删除
+- 结果已被删除的工具调用 → 注入存根结果
+
+### 迭代重压缩
+
+在后续压缩中，前一次摘要会连同指令一起传递给 LLM，要求其**更新**摘要而非从头摘要。这在多次压缩中保留了信息——条目从"进行中"移至"已完成"，新进展被添加，过时信息被删除。
+
+压缩器实例上的 `_previous_summary` 字段存储最后一次摘要文本以供此用途。
+
+
+## 压缩前后示例
+
+### 压缩前（45 条消息，约 95K token）
+
+```
+[0] system:    "You are a helpful assistant..." (system prompt)
+[1] user:      "Help me set up a FastAPI project"
+[2] assistant: <tool_call> terminal: mkdir project </tool_call>
+[3] tool:      "directory created"
+[4] assistant: <tool_call> write_file: main.py </tool_call>
+[5] tool:      "file written (2.3KB)"
+    ... 30 more turns of file editing, testing, debugging ...
+[38] assistant: <tool_call> terminal: pytest </tool_call>
+[39] tool:      "8 passed, 2 failed\n..."  (5KB output)
+[40] user:      "Fix the failing tests"
+[41] assistant: <tool_call> read_file: tests/test_api.py </tool_call>
+[42] tool:      "import pytest\n..."  (3KB)
+[43] assistant: "I see the issue with the test fixtures..."
+[44] user:      "Great, also add error handling"
+```
+
+### 压缩后（25 条消息，约 45K token）
+
+```
+[0] system:    "You are a helpful assistant...
+               [Note: Some earlier conversation turns have been compacted...]"
+[1] user:      "Help me set up a FastAPI project"
+[2] assistant: "[CONTEXT COMPACTION] Earlier turns were compacted...
+
+               ## Goal
+               Set up a FastAPI project with tests and error handling
+
+               ## Progress
+               ### Done
+               - Created project structure: main.py, tests/, requirements.txt
+               - Implemented 5 API endpoints in main.py
+               - Wrote 10 test cases in tests/test_api.py
+               - 8/10 tests passing
+
+               ### In Progress
+               - Fixing 2 failing tests (test_create_user, test_delete_user)
+
+               ## Relevant Files
+               - main.py — FastAPI app with 5 endpoints
+               - tests/test_api.py — 10 test cases
+               - requirements.txt — fastapi, pytest, httpx
+
+               ## Next Steps
+               - Fix failing test fixtures
+               - Add error handling"
+[3] user:      "Fix the failing tests"
+[4] assistant: <tool_call> read_file: tests/test_api.py </tool_call>
+[5] tool:      "import pytest\n..."
+[6] assistant: "I see the issue with the test fixtures..."
+[7] user:      "Great, also add error handling"
+```
+
+
+## Prompt 缓存（Anthropic）
+
+来源：`agent/prompt_caching.py`
+
+通过缓存对话前缀，在多轮对话中将输入 token 成本降低约 75%。使用 Anthropic 的 `cache_control` 断点。
+
+### 策略：system_and_3
+
+Anthropic 每次请求最多允许 4 个 `cache_control` 断点。Hermes 使用"system_and_3"策略：
+
+```
+Breakpoint 1: System prompt           (stable across all turns)
+Breakpoint 2: 3rd-to-last non-system message  ─┐
+Breakpoint 3: 2nd-to-last non-system message   ├─ Rolling window
+Breakpoint 4: Last non-system message          ─┘
+```
+
+### 工作原理
+
+`apply_anthropic_cache_control()` 深拷贝消息并注入 `cache_control` 标记：
+
+```python
+# Cache marker format
+marker = {"type": "ephemeral"}
+# Or for 1-hour TTL:
+marker = {"type": "ephemeral", "ttl": "1h"}
+```
+
+标记根据内容类型以不同方式应用：
+
+| 内容类型 | 标记位置 |
+|-------------|-------------------|
+| 字符串内容 | 转换为 `[{"type": "text", "text": ..., "cache_control": ...}]` |
+| 列表内容 | 添加到最后一个元素的字典中 |
+| None/空 | 作为 `msg["cache_control"]` 添加 |
+| 工具消息 | 作为 `msg["cache_control"]` 添加（仅限原生 Anthropic） |
+
+### 缓存感知设计模式
+
+1. **稳定的系统提示词**：系统提示词是断点 1，在所有轮次中缓存。避免在对话中途修改它（压缩仅在首次压缩时追加一条说明）。
+
+2. **消息顺序很重要**：缓存命中需要前缀匹配。在中间添加或删除消息会使其后所有内容的缓存失效。
+
+3. **压缩与缓存的交互**：压缩后，被压缩区域的缓存失效，但系统提示词缓存保留。滚动 3 消息窗口在 1-2 轮内重新建立缓存。
+
+4. **TTL 选择**：默认为 `5m`（5 分钟）。对于用户在轮次之间有较长间隔的长时间会话，使用 `1h`。
+
+### 启用 Prompt 缓存
+
+满足以下条件时，prompt 缓存自动启用：
+- 模型为 Anthropic Claude 模型（通过模型名称检测）
+- 提供商支持 `cache_control`（原生 Anthropic API 或 OpenRouter）
+
+```yaml
+# config.yaml — TTL is configurable (must be "5m" or "1h")
+prompt_caching:
+  cache_ttl: "5m"
+```
+
+CLI 在启动时显示缓存状态：
+```
+💾 Prompt caching: ENABLED (Claude via OpenRouter, 5m TTL)
+```
+
+
+## 上下文压力警告
+
+中间上下文压力警告已被移除（参见 `run_agent.py` 中的迭代预算块，其中注明："No intermediate pressure warnings — they caused models to 'give up' prematurely on complex tasks"）。压缩在 prompt token 达到配置的 `compression.threshold`（默认 50%）时触发，无需事先警告步骤；gateway 会话清理作为二级安全网在模型上下文窗口的 85% 处触发。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/context-engine-plugin.md

@@ -0,0 +1,193 @@
+---
+sidebar_position: 9
+title: "Context Engine 插件"
+description: "如何构建替换内置 ContextCompressor 的 context engine 插件"
+---
+
+# 构建 Context Engine 插件
+
+Context engine 插件用于替换内置的 `ContextCompressor`，以实现管理对话上下文的替代策略。例如，无损上下文管理（LCM）引擎通过构建知识 DAG 来替代有损摘要。
+
+## 工作原理
+
+Agent 的上下文管理基于 `ContextEngine` ABC（`agent/context_engine.py`）构建。内置的 `ContextCompressor` 是默认实现。插件引擎必须实现相同的接口。
+
+同一时间只能有**一个** context engine 处于激活状态。选择由配置驱动：
+
+```yaml
+# config.yaml
+context:
+  engine: "compressor"    # 默认内置
+  engine: "lcm"           # 激活名为 "lcm" 的插件引擎
+```
+
+插件引擎**永远不会自动激活** — 用户必须显式将 `context.engine` 设置为插件名称。
+
+## 目录结构
+
+每个 context engine 位于 `plugins/context_engine/<name>/`：
+
+```
+plugins/context_engine/lcm/
+├── __init__.py      # 导出 ContextEngine 子类
+├── plugin.yaml      # 元数据（name、description、version）
+└── ...              # 引擎所需的其他模块
+```
+
+## ContextEngine ABC
+
+你的引擎必须实现以下**必需**方法：
+
+```python
+from agent.context_engine import ContextEngine
+
+class LCMEngine(ContextEngine):
+
+    @property
+    def name(self) -> str:
+        """短标识符，例如 'lcm'。必须与 config.yaml 中的值匹配。"""
+        return "lcm"
+
+    def update_from_response(self, usage: dict) -> None:
+        """每次 LLM 调用后，以 usage dict 为参数调用。
+
+        从响应中更新 self.last_prompt_tokens、self.last_completion_tokens、
+        self.last_total_tokens。
+        """
+
+    def should_compress(self, prompt_tokens: int = None) -> bool:
+        """若本轮应触发压缩则返回 True。"""
+
+    def compress(self, messages: list, current_tokens: int = None,
+                 focus_topic: str = None) -> list:
+        """压缩消息列表并返回新的（可能更短的）列表。
+
+        返回的列表必须是有效的 OpenAI 格式消息序列。
+
+        ``focus_topic`` 是来自手动 ``/compress <focus>`` 的可选主题字符串；
+        支持引导式压缩的引擎应优先保留与其相关的信息，其他引擎可忽略。
+        """
+```
+
+### 引擎必须维护的类属性
+
+Agent 直接读取这些属性用于显示和日志记录：
+
+```python
+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       # compress() 已运行的次数
+```
+
+### 可选方法
+
+这些方法在 ABC 中有合理的默认实现，按需覆盖：
+
+| 方法 | 默认行为 | 何时覆盖 |
+|--------|---------|--------------|
+| `on_session_start(session_id, **kwargs)` | 空操作 | 需要加载持久化状态（DAG、DB）时 |
+| `on_session_end(session_id, messages)` | 空操作 | 需要刷新状态、关闭连接时 |
+| `on_session_reset()` | 重置 token 计数器 | 有需要清除的会话级状态时 |
+| `update_model(model, context_length, ...)` | 更新 context_length 和阈值 | 需要在切换模型时重新计算预算时 |
+| `get_tool_schemas()` | 返回 `[]` | 引擎提供 agent 可调用的工具时（例如 `lcm_grep`） |
+| `handle_tool_call(name, args, **kwargs)` | 返回错误 JSON | 实现工具处理器时 |
+| `should_compress_preflight(messages)` | 返回 `False` | 可在 API 调用前进行低成本预估时 |
+| `get_status()` | 标准 token/阈值字典 | 有自定义指标需要暴露时 |
+
+## 引擎工具
+
+Context engine 可以暴露 agent 直接调用的工具。从 `get_tool_schemas()` 返回 schema，并在 `handle_tool_call()` 中处理调用：
+
+```python
+def get_tool_schemas(self):
+    return [{
+        "name": "lcm_grep",
+        "description": "Search the context knowledge graph",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Search query"}
+            },
+            "required": ["query"],
+        },
+    }]
+
+def handle_tool_call(self, name, args, **kwargs):
+    if name == "lcm_grep":
+        results = self._search_dag(args["query"])
+        return json.dumps({"results": results})
+    return json.dumps({"error": f"Unknown tool: {name}"})
+```
+
+引擎工具在启动时注入到 agent 的工具列表中并自动分发 — 无需注册到注册表。
+
+## 注册
+
+### 通过目录（推荐）
+
+将引擎放置于 `plugins/context_engine/<name>/`。`__init__.py` 必须导出一个 `ContextEngine` 子类。发现系统会自动找到并实例化它。
+
+### 通过通用插件系统
+
+通用插件也可以注册 context engine：
+
+```python
+def register(ctx):
+    engine = LCMEngine(context_length=200000)
+    ctx.register_context_engine(engine)
+```
+
+只能注册一个引擎。第二个尝试注册的插件将被拒绝并发出警告。
+
+## 生命周期
+
+```
+1. 引擎实例化（插件加载或目录发现）
+2. on_session_start() — 对话开始
+3. update_from_response() — 每次 API 调用后
+4. should_compress() — 每轮检查
+5. compress() — 当 should_compress() 返回 True 时调用
+6. on_session_end() — 会话边界（CLI 退出、/reset、gateway 过期）
+```
+
+`on_session_reset()` 在 `/new` 或 `/reset` 时调用，用于清除会话级状态而不完全关闭。
+
+## 配置
+
+用户通过 `hermes plugins` → Provider Plugins → Context Engine 选择引擎，或直接编辑 `config.yaml`：
+
+```yaml
+context:
+  engine: "lcm"   # 必须与引擎的 name 属性匹配
+```
+
+`compression` 配置块（`compression.threshold`、`compression.protect_last_n` 等）专属于内置的 `ContextCompressor`。如有需要，你的引擎应定义自己的配置格式，并在初始化期间从 `config.yaml` 读取。
+
+## 测试
+
+```python
+from agent.context_engine import ContextEngine
+
+def test_engine_satisfies_abc():
+    engine = YourEngine(context_length=200000)
+    assert isinstance(engine, ContextEngine)
+    assert engine.name == "your-name"
+
+def test_compress_returns_valid_messages():
+    engine = YourEngine(context_length=200000)
+    msgs = [{"role": "user", "content": "hello"}]
+    result = engine.compress(msgs)
+    assert isinstance(result, list)
+    assert all("role" in m for m in result)
+```
+
+完整的 ABC 契约测试套件请参见 `tests/agent/test_context_engine.py`。
+
+## 另请参阅
+
+- [上下文压缩与缓存](/developer-guide/context-compression-and-caching) — 内置压缩器的工作原理
+- [Memory Provider 插件](/developer-guide/memory-provider-plugin) — 类似的单选插件系统（用于内存）
+- [插件](/user-guide/features/plugins) — 通用插件系统概述