better-dsh 0.2.4-a → 0.2.4-b

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

@@ -1,160 +0,0 @@
-# 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

@@ -1,328 +0,0 @@
----
-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

@@ -1,193 +0,0 @@
----
-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) — 通用插件系统概述