v2.7.7 截断恢复增强与降级日志诊断

标题

v2.7.7 截断恢复增强与降级日志诊断

内容

更新亮点

本次版本重点解决了长内容工具调用容易被截断、日志看起来成功但实际体验不佳的问题，并同步优化了示例配置与文档说明。

核心改进

1. 长 Write/Edit 截断恢复增强

• 新增语义级截断检测
• 即使 json action 代码块已经闭合，只要长 Write/Edit 参数内容明显写到一半，仍会判定需要继续续写
• 减少“文件写残后再补写多轮”的问题

2. OpenAI 流式长工具调用恢复修复

• 修复 OpenAI 兼容流式路径下，长 Write 工具调用被截断后无法正确恢复的回归问题
• 现在会至少进行 1 次内部恢复尝试
• 可恢复完整多帧 tool_calls，避免工具调用退化成普通文本

3. 新增 degraded 降级状态

• 对“看似成功、实际体验较差”的请求新增 degraded 状态
• 可识别的典型场景包括：
  • 工具看起来可用，但实际没有真正调用
  • 响应触发 max_tokens，且没有自动续写
  • 模型自述“写到一半”“内容被截断”“正在补写”

4. 日志与可观测性增强

• 日志 summary 现在会正确记录 Anthropic 路径下的 toolCallsDetected
• Vue 日志页与旧版 /logs 页面均支持：
  • degraded 状态统计
  • 状态筛选
  • 降级原因展示

5. 示例配置与文档同步更新

• README.md 更新到 v2.7.7
• config.yaml.example 同步推荐配置：
  • max_history_tokens: 120000
  • compression.enabled: true
  • compression.level: 2
  • tools.schema_mode: compact
  • tools.description_max_length: 100
  • tools.passthrough: false
  • tools.disabled: false
• docker-compose.yml 注释示例同步更新
• README 额外注明：
  • Cursor IDE 通常需要 Cursor Pro
  • OPENAI_BASE_URL 需使用公网可访问域名，建议 HTTPS 反向代理

测试与验证

已完成以下验证：

• npm run build
• node test/unit-handler-truncation.mjs
• node test/unit-openai-stream-truncation.mjs

适合升级的人群

如果你正遇到以下问题，建议升级到 v2.7.7：

• 长文档写入时经常写到一半被截断
• OpenAI 兼容客户端下长工具调用容易损坏
• 日志里显示 success，但实际执行效果不好
• 想更快定位“工具没真调用”或“模型在补写自救”的请求

v2.7.6 — 工具透传 / 禁用模式、身份泄漏清洗增强

✨ 新功能

🔧 工具透传模式 (tools.passthrough: true)

• 跳过 few-shot 注入和工具格式改写，直接将工具定义以原始 JSON 嵌入 <tools> 标签
• 减少与 Cursor 内建身份的提示词冲突，解决「只有 read_file/read_dir」的错误
• 推荐 Roo Code / Cline 等非 Claude Code 客户端开启

🚫 工具禁用模式 (tools.disabled: true)

• 完全不注入工具定义和 few-shot 示例，极致节省上下文空间
• 模型凭自身训练记忆处理工具调用，响应中的 ```json action``` 块仍会被正常解析
• 适合已内化工具格式的场景

🛡️ 身份泄漏清洗增强

• 新增 Cursor 上下文泄漏检测规则（"currently in Cursor support assistant context" 等）
• 新增 4 条清洗正则，精准删除完整泄漏段落

💬 tool_choice=any 引导优化

• 将 "CRITICAL ERROR" 威胁语气改为协作引导语气，避免触发模型安全拒绝
• 使用 "I notice..." + "quick reminder" + "please go ahead" 等自然措辞
• 列出可用工具名 + 具体格式示例，流式和非流式路径保持一致

🔩 改进

• 启动日志现在显示工具模式状态：disabled / passthrough / schema=full
• 请求日志标记工具处理方式：tools=98(跳过) / tools=98(透传) / tools=98
• 新增环境变量 TOOLS_PASSTHROUGH 和 TOOLS_DISABLED，Docker 部署无需挂载配置文件即可开启
• config.yaml.example 和 docker-compose.yml 同步更新

📁 变更文件

文件	说明
src/converter.ts	透传模式 + 禁用模式核心实现
src/handler.ts	身份泄漏清洗 + tool_choice=any 引导优化
src/constants.ts	新增 Cursor 上下文泄漏检测正则
src/types.ts	新增 passthrough / disabled 类型字段
src/config.ts	配置解析 + 环境变量覆盖
src/index.ts	启动日志显示工具模式
src/logger.ts	请求日志标记工具处理方式
config.yaml.example	新增两个选项的详细注释
docker-compose.yml	新增 TOOLS_PASSTHROUGH / TOOLS_DISABLED 环境变量

⚙️ 配置方式

# config.yaml
tools:
  passthrough: true   # 透传模式（Roo Code / Cline 推荐）
  # disabled: true    # 禁用模式（极致省上下文）

v2.7.5 — 常量集中管理 + 自定义拒绝规则 + 响应清洗开关

🏗️ 常量集中管理

• 新增 constants.ts：将 REFUSAL_PATTERNS（50+ 条拒绝检测规则）、IDENTITY_PROBE_PATTERNS、TOOL_CAPABILITY_PATTERNS、CLAUDE_IDENTITY_RESPONSE、CLAUDE_TOOLS_RESPONSE 及自定义拒绝规则逻辑从 handler.ts 提取到独立文件
• 提升可维护性：贡献者修改内置规则时只需查看 constants.ts，无需翻阅 2000 行的 handler 业务逻辑
• isRefusal() 函数统一导出：内置规则 + 自定义规则合并检测，所有调用点自动生效

🔧 自定义拒绝检测规则

• config.yaml 新增 refusal_patterns 字段：用户可添加自定义正则匹配规则，追加到内置列表之后（不替换），匹配到即触发重试逻辑
• 无效正则容错：无效的正则表达式自动退化为字面量匹配，不会导致服务报错
• 缓存编译：自定义规则只在配置变更时重新编译 RegExp，运行时零开销
• 热重载支持：修改后下一次请求即生效

# config.yaml 示例
refusal_patterns:
  - "我无法协助"
  - "this violates our"
  - "I must decline"

v2.7.4: 截断安全 · 代理续写禁用 · 日志提示词对比视图

🛡️ 截断安全 — 防止损坏的工具调用

• 截断时跳过工具解析：当响应被截断（stop_reason=max_tokens）时，不再尝试解析不完整的 json action 块，避免生成损坏的工具调用（如写入半截文件）
• 纯文本回退：截断响应中的不完整工具块被自动剥离，剩余文本作为纯文本返回，由客户端（Claude Code）原生续写
• 默认禁用代理续写：maxAutoContinue 默认值改为 0，让 Claude Code 原生处理续写（体验更好、进度可见），配置同步更新至 config.yaml、config.yaml.example、docker-compose.yml

🧹 提示词注入防御增强

• 身份声明清除：自动剥离系统提示词中的 Claude Code / Anthropic 身份声明（You are Claude Code、I'm Claude, made by Anthropic 等），防止模型将其判定为 prompt injection 并拒绝服务
• 流式热身窗口扩大：混合流式模式的 warmupChars 从 96 增至 300 字符，确保拒绝检测完成前不释放任何文本给客户端

📊 日志查看器增强

• 提示词对比视图：「💬 提示词」tab 重命名为「💬 提示词对比」，分区展示原始请求 vs 转换后的 Cursor 消息
• 转换摘要面板：顶部新增 6 格摘要（原始工具数 → Cursor 工具数 0、工具指令占用字符数、消息数变化、总上下文大小）
• 工具去向提示：当有工具时显示黄色提示「⚠️ Cursor API 不支持原生 tools 参数，N 个工具已转换为文本指令嵌入 user #1」
• 标题提取优化：通用 XML 标签清除（覆盖所有注入标签）+ 清除 Respond with the appropriate action 引导语

---

完整更新日志: CHANGELOG.md

v2.7.3 — 统一 Thinking 剥离 + 拒绝检测增强 + Docker 部署优化

🔧 核心改进：统一 Thinking 剥离逻辑

重大架构优化：无论客户端是否请求 thinking，现在都始终剥离 <thinking> 标签，避免 thinking 内容泄漏到最终输出文本中。

• 之前：只有客户端显式请求 thinking 时才剥离标签，否则保留在正文中
• 现在：始终剥离，差异仅在于客户端请求 thinking 时发送 thinking content block，否则静默丢弃
• 修复流式响应中 leadingBuffer 未 flush 导致极短响应丢失内容的问题
• 重试后也正确剥离 thinking 标签，避免重试响应中遗留标签

🛡️ 拒绝检测增强

• 拒绝检测现在始终在 thinking-stripped 文本上执行，消除 thinking 中反思性语言的误判
• 移除冗余的 getTextForRefusalCheck() / stripThinkingTags() 调用，逻辑更清晰
• sanitizeResponse() 新增 "accidentally called Cursor tool" 幻觉清洗规则
• converter.ts 扩展历史上下文清洗正则：增加 accidentally called/calling、Cursor documentation 模式

🐳 Docker 部署优化

• Dockerfile：不再将 config.yaml 打包进镜像，改为通过 volume 挂载（更安全、更灵活）
• Dockerfile：新增 /app/logs 日志目录创建和 VOLUME 声明
• docker-compose.yml：新增日志持久化 volume 挂载 (./logs:/app/logs)
• docker-compose.yml：补全所有环境变量注释说明（AUTH_TOKEN、THINKING_ENABLED、COMPRESSION、LOG、FP 等）

📋 包含的提交

• 70d8da2 feat: implement proper OpenAI Responses API streaming format for Codex compatibility
• 85d8666 fix: 修复纯字符串 content 中的图片路径无法提取的根因 (#39)
• 292c8c4 fix: 修复 CC 自动压缩后模型丢失任务上下文的问题
• e2acdd1 fix: 修复 OpenClaw/Telegram 等客户端图片处理失败问题 (#39)

---

Full Changelog: v2.7.2...v2.7.3

v2.7.2 — 日志查看器升级 + 工程化改进

🖥️ 日志查看器全面升级

• 前端重构为独立静态文件：logs.html / logs.css / logs.js 分离到 public/ 目录，告别单文件嵌入，更易维护
• 🌙 日/夜主题切换：一键切换明暗主题（☀️/🌙），自动检测系统偏好，选择持久化到 localStorage
• 暗色主题完整适配：深蓝渐变背景，所有 UI 元素（标签、状态灯、代码块、JSON 高亮）均有独立暗色配色
• 标题提取修复：过滤 <system-reminder> 注入内容和 Claude Code 引导语，确保标题显示用户真实提问
• 登录页同步更新：独立 login.html，视觉风格与日志页一致

🧹 工程化改进

• 移除 WELL_KNOWN_TOOLS 白名单：所有工具统一保留描述（截取前 50 字符），简化逻辑
• config.yaml 停止追踪：含敏感 token 的配置文件加入 .gitignore，不再上传
• 新增 config.yaml.example：配置模板，安全默认值，用户只需 cp config.yaml.example config.yaml
• Thinking 默认关闭：thinking.enabled 默认值改为 false
• Express v5 兼容：修复 path-to-regexp 通配符路由报错

📝 README 大幅更新

• 新增日志查看器功能介绍（特性列表 + 鉴权说明）
• 新增配置项速查表格
• 新增环境变量参考表
• 项目结构补充 public/ 目录说明

⚠️ 升级注意

首次升级到 v2.7.2 的用户：config.yaml 已从版本控制中移除。如果你是新部署，请执行：

cp config.yaml.example config.yaml

已有 config.yaml 的用户不受影响，本地文件不会被删除。

---

Full Changelog: v2.7.1...v2.7.2

v2.7.1: 智能压缩算法 + 可配置压缩系统 + 日志鉴权 + Thinking 修复

v2.7.1 (2026-03-16)

🗜️ 智能历史压缩算法

• 修复 JSON Action 块截断：之前朴素的 substring 截断会切断 ```json action 代码块，产生未闭合标记和不完整 JSON，严重误导模型。现在对包含工具调用的 assistant 消息，提取工具名生成摘要（如 [Executed: Write, Read]），不再做子串截断
• 工具结果头尾保留：工具结果截断从"只保留头部"改为 60% 头 + 40% 尾，确保错误信息、stack trace 等末尾关键内容不丢失
• 修复非工具模式偏移量：few-shot 消息跳过偏移量从硬编码 +2 改为动态计算 hasTools ? 2 : 0，修复非工具模式下前2条消息无法参与压缩的问题
• 自然边界截断：普通文本在换行符处截断，避免切断单词或代码

⚙️ 可配置压缩系统

• 新增 compression 配置段（config.yaml），支持：
  • enabled：压缩开关（true/false），关闭后所有消息原样保留
  • level：压缩级别 1-3（轻度/中等/激进），每级预设不同的保留消息数和字符限制
  • keep_recent：高级选项，覆盖级别预设的保留消息数
  • early_msg_max_chars：高级选项，覆盖级别预设的早期消息字符上限
• 支持环境变量 COMPRESSION_ENABLED / COMPRESSION_LEVEL，方便 Docker 部署

🔐 日志查看器鉴权

• 配置了 auth_tokens 后，访问 /logs 及所有 /api/logs* 端点需要验证身份
• 精美的登录页面，输入 token 后通过 /api/stats 验证有效性
• Token 存入 localStorage，刷新页面无需重新输入
• 支持 query 参数 ?token=xxx、Authorization header、x-api-key 三种传入方式
• 页面右上角显示退出按钮，清除缓存并跳回登录页
• 未配置 auth_tokens 时保持完全开放（向后兼容）

🧠 Thinking 拒绝误判修复

• 修复 thinking 触发拒绝检测：模型的 <thinking> 内容中包含反思性语言（如 "haven't given a specific task"），被拒绝检测正则误判为拒绝响应
• 拒绝检测现在先剥离 <thinking> 标签内容，仅对实际输出文本进行检测
• 流式和非流式路径均已修复

🧠 OpenAI 格式 Thinking 默认启用

• OpenAI Chat Completions 协议不再依赖模型名包含 thinking 或传入 reasoning_effort 才启用
• 所有 OpenAI 格式请求默认启用 thinking，确保 Claude Code 等客户端始终获得推理内容

V2.7.0-基于 v2.5.6 稳定版本，精选移植 v2.6.x 核心改进

v2.7.0 (2026-03-16)

基于 v2.5.6 稳定版本，精选移植 v2.6.x 核心改进 + 新增 API 鉴权和 Thinking 支持。

🔐 API Token 鉴权

• 公网部署安全：新增 auth_tokens 配置项，支持 Bearer token 鉴权
• 支持多 token（数组格式）、环境变量 AUTH_TOKEN、x-api-key 头
• 未配置时全部放行（向后兼容），GET 请求和 /health 端点无需鉴权
• 启动 banner 显示鉴权状态

🧠 Thinking 支持（客户端驱动）

• Anthropic 协议：请求体传 thinking.type = "enabled" 即启用
• OpenAI 协议：模型名含 thinking 或传 reasoning_effort 参数即启用
• 系统提示词注入 <thinking> 引导，模型输出自动提取
• Anthropic 返回 thinking content block，OpenAI 返回 reasoning_content 字段
• 提取在拒绝检测之前执行，防止 thinking 内容触发误判
• 未启用时仍会剥离 thinking 标签（防误判），但内容不返回

🔧 已知工具跳过描述

• WELL_KNOWN_TOOLS 集合中的 17 个常用工具（Read、Write、Bash 等）不再生成描述文本
• 减少约 30% 工具指令输入，节省上下文空间

📊 动态工具结果预算

• getToolResultBudget() 替代固定 15K 限制
• 根据当前上下文大小动态调整：小上下文 20K → 大上下文 8K
• setCurrentContextChars() 跟踪实际上下文字符数

🛡️ isTruncated 重写

• 重新实现截断检测逻辑，正确处理工具调用 JSON 中的反引号
• 优先检查 ```json action 代码块，避免 JSON 字符串值内的反引号导致误判
• 消除因误判导致的无限重试

📦 response_format 支持

• OpenAIChatRequest 新增 response_format 字段（json_object / json_schema）
• JSON 格式请求自动追加格式指令到最后一条用户消息
• stripMarkdownJsonWrapper() 自动剥离响应中的 markdown 代码块包装
• 流式和非流式路径均支持

🧹 计费头清除

• 自动清除系统提示词中的 x-anthropic-billing-header
• 防止模型将其判定为恶意伪造并触发注入警告

🌐 Vision 独立代理

• 新增 vision.proxy 配置项，图片分析 API 单独走代理
• Cursor API 保持直连（国内可用），不因代理影响响应速度
• 未配置时回退到全局 proxy

🛡️ 新增拒绝模式

• 补充 4 个 Cursor 新拒绝措辞：isn't something I can help with、not something I can help with、scoped to answering questions about Cursor、falls outside

V2.6.7 真流式架构重构 — 流式 Thinking 解析器 + 流式工具解析器 + converter/handler 大规模重构

1. 真流式架构 — 无工具对话场景首字延迟大幅降低
2. 两个全新状态机解析器 — StreamingThinkingParser+ StreamingToolParser
3. 智能分流 — 有工具走缓冲模式保证解析准确，无工具走真流式极速响应

v2.6.6: response_format 支持 + Thinking 误判修复 + 上下文压缩策略重构

✨ 新功能
response_format 完整支持
支持 OpenAI 标准的 response_format 参数（json_object / json_schema）
自动将 JSON 格式约束追加到用户消息末尾，引导模型输出合规 JSON
支持 json_schema 模式：自动附带 Schema 定义供模型参考
后处理自动剥离：模型返回 Markdown 代码块包裹的 JSON 时，自动剥离 json 包裹，确保下游直接拿到可解析的 JSON 字符串
流式和非流式响应均支持
上下文压缩策略可配置化
新增 enableSummary 配置项：控制 AI 摘要压缩（用额外 API 调用对旧消息进行摘要压缩）
新增 enableProgressiveTruncation 配置项：控制渐进式截断（保留最近消息完整，仅截短早期超长消息）
两种策略可独立启用/禁用，灵活适配不同使用场景
🐛 修复
Thinking 提取顺序修复（非流式模式）
问题： 块中的内容可能包含触发拒绝检测的关键词，导致正常响应被误判为"拒绝"并触发不必要的重试
修复：将 Thinking 提取逻辑移到拒绝检测之前执行，确保 isRefusal() 只检测实际输出内容
重试响应同样先提取 Thinking 再进行拒绝检测
提示词中性化优化
进一步优化 converter.ts 中的提示词策略，减少模型拒绝率
调整上下文压缩逻辑的代码结构，提升可读性和可维护性
📦 配置变更
config.yaml 新增字段：

yaml

AI 摘要压缩（质量不稳定，默认关闭）

enableSummary: false

渐进式截断（默认开启）

enableProgressiveTruncation: true
📝 其他
简化 README 稳定性排名描述，避免频繁更新版本号
代码结构优化：上下文压缩策略从单一 if-else 重构为独立分支，逻辑更清晰