@tencent-ai/codebuddy-code 2.97.5-next.c5a44af.20260523 → 2.98.1

package/dist/web-ui/docs/cn/cli/release-notes/v2.97.0.md

@@ -0,0 +1,186 @@
+# 🚀 CodeBuddy Code v2.97.0 发布
+
+## ✨ 新功能
+
+### 完整快捷键系统
+
+参考 Claude Code 架构实现快捷键系统，支持上下文条件、弦序列（如 Ctrl+X Ctrl+K）、用户自定义覆盖。
+
+- 配置文件：`~/.codebuddy/keybindings.json`
+- 16 个上下文（Global / Chat / Terminal / Autocomplete 等）、60+ 个动作
+- `/keybindings` 斜杠命令快速管理
+- Web UI 新增可视化配置（按上下文分组、搜索、录制、实时冲突检测）
+- REST API：`/api/v1/keybindings`（GET/PUT/POST reset/POST validate）
+
+### Skill / Subagent Frontmatter Hooks
+
+对齐 Claude Code 行为，支持在 `.codebuddy/agents/*.md` 与 `.codebuddy/skills/*/SKILL.md` 的 YAML frontmatter 中配置 `hooks:` 字段，子代理 / fork skill 生命周期内自动注册和清理。
+
+- 支持 `command` / `prompt` / `agent` / `http` 四种 hook 类型
+- `once: true` 自动移除、event matcher 语义
+- **默认安全闸门**：非 product 内置来源的 frontmatter hooks 默认禁用（含本地与插件市场），需在 `settings.json` 中开启 `allowUntrustedFrontmatterHooks: true` 才生效
+
+### Hook 事件全面对齐 Claude Code
+
+新增 20+ 个 hook 事件覆盖工具失败、子代理生命周期、任务管理、权限审批、文件监视等场景：
+
+- **生命周期**：PostToolUseFailure / SubagentStart / StopFailure / PostCompact / ConfigChange / InstructionsLoaded
+- **权限与任务**：PermissionRequest / PermissionDenied（可拦截审批）、TaskCreated / TaskCompleted、TeammateIdle、Setup
+- **文件监视**：FileChanged（声明 watchPaths）、CwdChanged（cwd 变化触发）
+- **新增 hook 类型**：`http`（POST 任意 URL）、`agent`（复用 prompt 路径）
+- **新增字段**：`if`（按工具名/参数匹配）、`shell`（切 PowerShell）、`once`（成功后不再触发）、`asyncRewake`、`allowedEnvVars`、`statusMessage`
+- **异步协议**：hook 输出 `{"async": true, "asyncTimeout": N}` 立即放行 fire-and-forget
+
+### Skills / 命令 / Subagent 变量占位符
+
+`.md` 文件中支持变量占位符替换：`${CODEBUDDY_PLUGIN_ROOT}` / `${CODEBUDDY_SKILL_DIR}` / `${CODEBUDDY_SESSION_ID}` 以及任意大写环境变量，支持 `${MY_ENV_VAR:-默认值}` 默认值语法。未设置的占位符原样保留，避免静默丢失配置。
+
+### 第三方插件市场自动更新
+
+新增 `autoUpdateThirdPartyMarketplaces` 产品配置和 `CODEBUDDY_AUTO_UPDATE_THIRD_PARTY_MARKETPLACES` 环境变量，支持全局启用第三方插件市场自动更新。市场配置项新增 `autoUpdate` 可选字段，可单独控制。
+
+### Remote Gateway 任务超时可配置
+
+`/api/v1/runs` 端点默认超时从 10 分钟提升到 **30 分钟**，长任务不再被强制中断：
+
+- 新增 `gateway.runTimeoutMs` settings 配置（毫秒）
+- 新增 HTTP header `X-Codebuddy-Run-Timeout` 单次覆盖
+- 设为 0 或负数关闭超时保护
+
+### Web UI PWA 自动检测新版本
+
+发布新版本后，已打开的 Web UI tab 不再需要手动强制刷新：
+
+- 每 15 分钟自动询问后端是否有新 Service Worker
+- 对话空闲时自动刷新切到新版本
+- 对话进行中弹 toast 保留"立即刷新"按钮，订阅运行状态在 Agent 空闲后自动刷新
+
+### UE 项目自动排除大仓噪声目录
+
+在 cwd 检测到 `*.uproject` 时，Grep / Glob 自动叠加 `!Intermediate/` `!DerivedDataCache/` `!Saved/` `!Binaries/` `!Build/` `!.vs/` 排除，避免 Unreal Engine 项目（典型 10W+ 源码 / 300W+ 总文件）的编译产物污染搜索结果；可通过 `settings.disableUEAutoExclude: true` 关闭。Grep 内容搜索新增 `--max-columns 500` 避免单行 MB 级内容打爆 stdout。
+
+### 桌面文件系统 ACP 方法
+
+在 ACP StreamManager 中实现完整 `fs/*` 方法（list / read / write / exists / makeDir / remove / rename / getInfo / watchDir / unwatch），使 WorkBuddy Desktop"全部文件"标签页正常工作。
+
+## 🔧 改进优化
+
+- **PowerShell 安全多层防御**：CLM 类型白名单（~90 类型）、Git 安全防护（裸仓库 / NTFS 8.3 / archive 提取器）、危险 Cmdlet 分类（7 集合 + 120+ 别名）、破坏性命令 UI 警告（16 种模式）、Unicode 破折号支持
+- **ACP 连接稳定性**：GET SSE 连接 30 秒心跳防止反向代理（cloudflared / nginx）回收；连接关闭时等待历史写入完成防止 JSONL 日志被截断
+- **Bash 工具 timeout 提示动态化**:工具描述中"最大 timeout"原先写死 600000ms，现动态注入与运行时实际 clamp 值保持一致
+- **TUI Ctrl+F / Ctrl+B 光标导航**:支持 bash readline 风格的左右移动一字符,与已有 Ctrl+A / Ctrl+E / Ctrl+K / Ctrl+U 一致,emoji 多字节字符移动正确
+- **Web UI 画布内嵌终端文字选择**:tile 聚焦后遮罩透传 pointerdown 给 xterm,支持选中复制;中键 / 右键 / Space + 左键仍走画布平移
+- **Channel 权限 deny_and_exit_plan**:微信 / 企微用户可通过回复 `q` 退出计划模式;ExitPlanMode 工具新增专用提示
+- **Request Purpose 标记**:新增 `X-Agent-Purpose` HTTP header 为不同类型 LLM 请求打分类标签,供 Langfuse 进行 trace 分析
+- **图片压缩拦截器**:对用户发送的 base64 图片统一进行长边 2000px 压缩,确保 ACP / TUI / plugin-chat 各来源图片都经过尺寸优化
+- **Worktree 目录切换**:创建或复用 worktree 后尽量保持进入与当前目录对应的相对子目录
+- **Session API 统一**:合并 `listWorkspaces` 和 `listAcrossProjects` 为统一的 `GET /api/v1/sessions` 端点,支持 `cwd` 查询参数
+- **模型权限错误自动恢复**:后端返回"模型不可用"时自动刷新产品配置并展示最新可用模型列表
+- **下架历史模型并刷新积分系数**:下掉 HY 2.0 系列(3 个)和 GPT-5.2/5.1 共 4 个旧模型;按最新官方定价表刷新模型积分(iOA / 国内版 / 云托管版)
+- **插件加载并发与缓存**:为市场插件列表 / 元数据 / 组件加载引入并发上限避免启动抖动;新增市场插件列表缓存与加载去重
+- **自动化任务 Langfuse 标签**:定时任务触发的请求自动携带 `automation` 标签便于筛选
+
+## 🐛 问题修复
+
+### ACP 协议与稳定性
+
+- **`/clear` 分隔符在重启后丢失**:修复 CBC / WorkBuddy Desktop 会话里插入的 `/clear` 分隔符在重启或 loadSession 回放后消失,以及随之出现的 400 错误
+- **`/compact` 在 IM 场景下生效**:WorkBuddy Desktop IM 的 `/compact`/`/总结`原先无效,现通过 `_meta` 短路调用压缩
+- **Cancel Barrier**:cancel 完成瞬间若有新 `session/prompt` 到达会被当作新对话启动,新增 500ms cancel barrier
+- **取消标记泄漏**:prompt 终态与 `session/cancel` 同时发生时 pending cancellation 标记未被消费导致后续轮次 AskUserQuestion 被误判为取消
+- **流式回复重复输出思考内容**:修复 WorkBuddy 对话流式回复重复输出思考内容
+- **AskUserQuestion 显示"未回答"**:ACP 模式下用户回答 AskUserQuestion 后 UI 显示"未回答"
+- **AskUserQuestion 误判为"拒绝回答"**:审批信号抢在工具执行路径建立等待者前到达导致答案被丢弃
+- **会话查找竞态**:`session/prompt` 改用 `getRuntimeSession` 优先查询活跃会话避免"Session not found"
+- **会话继承 CLI 启动参数**:`--serve` 模式下 ACP 创建的会话未继承 `--permission-mode` / `--model` 等参数
+- **`session/load` 超时**:部分 Windows 环境下出现超时,在协议入口层增加 25s 兜底
+- **模型切换不生效**:`unstable_setSessionModel` 立即把新模型写入 runtime session 不再只依赖订阅副作用
+- **不再把内置命令当 skill 暴露**:`/clear` `/help` `/model` `/theme` `/status` `/resume` `/rename` 不再混入 `Skill` 工具列表
+
+### 上下文压缩(Compact)
+
+- **自动取消循环**:压缩在某些场景出现"自动取消"假象后立刻又被重复触发,压缩调用等待上限从 60 秒放宽到 20 分钟
+- **残留 XML 标签**:任务异常结束时残留 `</conversation_history_summary>` 标签
+- **摘要与用户消息错位**:请求级自动预压缩场景下压缩摘要与用户原始消息在历史中错位
+- **退化摘要**:长会话自动压缩后缺少有效新增内容时仍可能再次压缩生成无效摘要
+- **失败卡住历史视图**:失败/取消后再次触发压缩仍被卡住
+- **超时死锁与取消**:子 Agent compact 超时后状态机卡死;用户主动取消时取消信号被吞掉
+- **自定义模型自动压缩窗口**:未配 `maxInputTokens` 时退回到 `CODEBUDDY_AUTO_COMPACT_WINDOW` 兜底窗口
+- **SDK 模式自动压缩断联**:SDK / headless 模式下压缩输出泄露到 stdout 导致断联
+- **自动压缩渲染裸 XML**:聊天界面被渲染为裸 `<conversation_history_summary>` 标签,与 `/compact` 走同一套渲染
+- **失败保留用户消息**:发送前自动压缩失败后会保存用户消息并展示明确失败提示
+- **历史 `Unknown content` 错误**:从历史会话继续对话时可能报 `Unknown content` 导致中断
+
+### 模型与请求处理
+
+- **PTL 上下文超长恢复**:新增按 API 轮次精确截断历史的兜底机制,覆盖主流模型错误文案
+- **空流自动重试**:识别上游网关只发占位/心跳帧后断开的"空流"场景,自动恢复
+- **请求体超限恢复**:axios 显式设 `maxBodyLength: Infinity`,避免 follow-redirects 默认 10MB 上限本地拦截
+- **`Tool X not found` 错误处理**:错误不再带产品实现细节的 agent 名;`ModelBehaviorError` 不再弹客户端错误框,走 `end_turn` 结束本轮
+- **自定义模型 Gzip 检测**:`custom-local:` 前缀剥离导致无法匹配 product.models 配置的问题
+- **自定义模型加载 400**:支持顶级数组和对象包裹两种 models.json 格式
+
+### 历史与会话
+
+- **首条用户消息丢失**:含隐藏上下文的用户首条消息在 UI 中消失
+- **Model error 渲染为助手回复**:因模型报错(6004/429)中断的轮次被当普通回答渲染
+- **Orphaned tool_call 回放**:对中断的工具调用跳过回放并注入系统通知
+- **老会话任务列表展示**:旧版本迁移的会话恢复后任务列表渲染为空
+- **图片消息标题污染**:在历史回放和会话标题生成场景中泄漏本地图片路径
+- **Plan 模式权限恢复**:从 Desktop 端启动 plan 模式时 `prePlanPermissionMode` 未正确传递
+
+### 工具与权限
+
+- **恢复 Grep/Glob 工具注册**:之前误将 Grep/Glob 从 5 份 product.json 中删除导致降级为 Bash+rg
+- **`--disallowedTools` 子命令规则**:带子命令的规则(如 `Bash(pkill:*)`)整个工具被移除
+- **工具过滤绕过漏洞**:ToolSearch lookup 模式和 DeferExecuteTool 不检查工具可用性
+- **Glob/Grep 空结果提示**:返回有意义的文本提示替代空数组
+- **rm 批量删除风险等级**:从 MEDIUM 提升至 HIGH 确保 IM 侧批量删除触发用户确认
+- **沙箱 strip_write 假成功**:静默丢弃写入/删除时不触发提权 UI
+
+### 配置目录
+
+- **Bash Sandbox 配置目录路径**:`CODEBUDDY_CONFIG_DIR` 自定义目录下 Bash 沙箱白名单失效
+- **Prompt 模板硬编码路径**:TeamCreate / TeamDelete / statusline-setup 工具描述模板通过 `{{codebuddyHome}}` 渲染实际目录
+- **UI 面板硬编码路径**:Permissions / Agents / Skills / Memory 面板显示真实路径
+- **沙盒开关存储层级**:Desktop 端沙盒开关从持久化改为内存层(session 级别)避免污染工作区目录
+
+### 插件市场
+
+- **MCP 静态 Authorization 被 OAuth 覆盖**:在 `headers.Authorization` 显式配置时仍触发 OAuth 流程的问题
+- **Marketplace 同名重复**:撞名出现两条同名套件且无法删除
+- **Marketplace 重复添加报错**:改为自动触发更新流程
+- **Marketplace 更新缓存未刷新**:`updateMarketplace` 后 `lastUpdated` 时间不更新
+- **GithubMarketplace 目录名对齐**:非标准仓库 URL 目录名与 manifest.name 不一致
+- **Git 不可用 ZIP 回退**:未安装 Git 的 Windows 环境下添加插件市场失败
+- **内置套件市场 ZIP 分发**:默认套件市场无内容、添加市场失败
+- **插件子代理描述刷新**:加载或切换插件子代理后描述未及时刷新
+- **Skill 扫描悬空符号链接**:之前会让整个目录扫描中断
+
+### Windows 兼容性
+
+- **PowerShell Office Automation**:Excel / Word / PowerPoint / Outlook 创建被安全策略误拦截
+- **PowerShell 命令行包装**:`rawCommand=true` 时跳过 bash 包装避免反斜杠/反引号被吞
+- **黑窗弹出**:`--bg` 后台会话以及 daemon 启动期间弹出 conhost / Git Bash 黑窗
+- **插件 commands 不显示**:`CODEBUDDY_PLUGIN_DIRS` 改用 `path.delimiter` 避免盘符被当分隔符
+- **Bash 工具中文乱码**:跨 chunk 拼回 UTF-8 多字节序列;Windows 注入 `PYTHONUTF8=1`
+
+### 其他
+
+- **Daemon 端口竞态**:重启时 `EADDRINUSE` 启动失败或长连接阻塞
+- **MessageQueueDeferredDispatch(Mode B)**:Agent 队列消息无法成功发送、"立刻发送"消息丢失
+- **Team 消息实时投递**:队长忙碌期间队员 SendMessage 卡在消息队列不被消费
+- **Playbook Team Spinner**:任务完成后左侧 agent 持续转圈
+- **专家内置 Skill 不可见**:`rebuildAgents` 完成后未失效 Skill / SlashCommand / ToolSearch 工具描述缓存
+- **会话标题与摘要触发**:确保标题更新、内容摘要、压缩前刷新按预期生效
+- **ImageGen / ImageEdit 取消支持**:取消后图片生成请求仍继续执行
+- **私有化部署检测**:配置企业端点但实际为云托管时错误标记为 Self-Hosted
+- **`anydev` 远程 IDE `/ide` 命令**:新增 `CODEBUDDY_IDE_PORT` / `CODEBUDDY_IDE_HOST` / `CODEBUDDY_IDE_SKIP_VALID_CHECK` 环境变量
+- **Web UI 编辑器保存清空文件**:`writeFile` 前端未显式设 Content-Type 被 body-parser 消费
+- **Gateway CORS 静态资源**:开启 CORS 白名单时同源 IP 访问静态资源被误拦
+- **Read 工具图片返回格式**:返回 image content block 格式
+- **Worktree 相对 cwd**:复用 worktree 时未正确进入相对目录
+
+## 📝 文档更新
+
+- **下线 sandboxing.md 文档**:相关链接指向 bash-sandboxing.md

package/dist/web-ui/docs/cn/cli/release-notes/v2.97.1.md

@@ -0,0 +1,24 @@
+# 🚀 CodeBuddy Code v2.97.1 发布
+
+## 🐛 问题修复
+
+### /ide 自动连接稳定性修复
+
+修复了独立二进制版本（`bun build --compile`）下 `/ide` 自动连接可能报错 `Unexpected server response: 101` 的问题。
+
+该问题由 IDE WebSocket 握手在特定情况下被错误识别为普通 HTTP 响应引起，会导致所有匹配的 IDE 均无法连接。现在独立二进制版本改用 Bun 原生 WebSocket，绕开了底层兼容性问题；通过 npm 安装的版本继续使用原有实现，不受影响。
+
+同时对自动连接的工作区匹配逻辑进行了收紧：
+
+- 仅当恰好只有一个 IDE 的工作区路径覆盖当前目录时，才会自动发起连接
+- 若存在多个匹配 IDE，则静默跳过自动连接，您可以通过 `/ide` 命令手动选择
+- 连接前会自动清理已退出 IDE 进程残留的锁文件，避免连接到无效端口
+
+### 微信回复工具字段格式修复
+
+修复了部分模型在调用 `WeChatReply` 工具时，将回复正文内容错误地写入 `chat_id` 字段，导致工具反复报错 "Either text or file_path is required" 的问题。
+
+本次改进包括：
+
+- 补全工具描述与频道指令中的 JSON 调用示例，明确各字段含义
+- 当检测到正文内容被误填入 `chat_id` 字段时，给出清晰的纠错提示，引导模型使用正确的字段名重新调用

package/dist/web-ui/docs/cn/cli/release-notes/v2.97.2.md

@@ -0,0 +1,16 @@
+# 🚀 CodeBuddy Code v2.97.2 发布
+
+## 🔧 改进优化
+
+- **警告抑制**：抑制 DEP0040（punycode）、NODE_TLS_REJECT_UNAUTHORIZED 和 AbortSignal MaxListenersExceeded 等无用警告，终端输出更干净
+- **自定义 Agent hooks 支持**：自定义 Agent 的 frontmatter 现在支持 hooks 配置，扩展自定义 Agent 的能力边界
+- **rm 命令风险评级调整**：非递归多文件 rm 从 HIGH 降级为 MEDIUM，减少不必要的权限确认弹窗
+
+## 🐛 问题修复
+
+- **ACP 模式下 MCP 工具不可见**：修复在 IDE 嵌入式 / Web UI / Workbuddy Desktop 等模式下，MCP 工具无法被发现和使用的问题。现在配置变化后会自动重新扫描，已连接的 server 不会重复建立连接
+- **IDE 集成子代理工具调用**：修复 IDE 集成模式下子代理调用 Read / Write / Edit / Bash 等工具时，客户端因会话标识不匹配而拒绝执行的问题
+- **会话启动钩子一致性**：统一各入口触发 SessionStart 钩子的路径，避免首条提示缺失上下文
+- **插件加载**：修复 headless / ACP 模式下 `--plugin-dir` 指定的插件无法被识别的问题
+- **插件解压权限**：解压插件 zip 时保留可执行位，修复附带脚本无法执行的问题
+- **tmux 环境输入乱码**：修复在 tmux 下 Kitty keyboard protocol 控制序列导致输入框出现乱码的问题

package/dist/web-ui/docs/cn/cli/release-notes/v2.97.3.md

@@ -0,0 +1,17 @@
+# 🚀 CodeBuddy Code v2.97.3 发布
+
+## 🔧 改进优化
+
+- **MCP 工具调用透传 Model ID**：MCP 工具调用时自动将当前模型 ID 通过 HTTP 请求头 `X-Model-ID` 透传到下游 MCP Server，便于下游服务识别调用来源模型，增强 MCP 集成场景的可追溯性
+
+## 🐛 问题修复
+
+- **专家团子智能体重名**：修复专家团中子智能体重名导致 spawn 失败的问题，提升多智能体协作的稳定性
+- **团队名冲突与 inbox 重试**：团队名冲突时自动重命名，inbox 轮询增加重试机制，减少团队协作中的异常中断
+- **遥测数据准确性**：修复 `chat_user_action` 上报时 `requestModelName` 字段错误的问题，确保遥测数据准确反映实际使用模型
+- **computer-use macOS Retina 坐标**：修复 macOS Retina 高分屏下 computer-use 坐标偏移与 scroll 操作异常，确保屏幕操作精确定位
+- **团队会话取消稳定性**：修复团队会话取消后队列残留拉活与列表状态闪回的问题，会话取消后状态更新更加稳定
+- **PowerShell 语法防护**：阻止 cmd 语法误入 PowerShell 执行，避免跨 shell 语法错误导致命令失败
+- **终端按键兼容性**：修复 SS3 方向键及 Ghostty 终端下 Shift+Enter 按键无响应的问题，提升终端兼容性
+- **MaxToken 压缩卡死**：修复 MaxToken 压缩取消后 ACP `forwardingPromise` 卡死的问题，避免会话因压缩取消而陷入无响应状态
+- **历史回放压缩记录**：修复消息压缩记录持久化及回放时 `<cb_summary>` 标签未过滤的问题，确保历史回放的准确性

package/dist/web-ui/docs/cn/cli/release-notes/v2.97.4.md

@@ -0,0 +1,9 @@
+# 🚀 CodeBuddy Code v2.97.4 发布
+
+## 🔧 改进优化
+
+- **模型兼容性目录驱动**：模型请求的兼容性处理改为目录驱动架构，新增模型时只需更新模型目录即可完成适配，无需修改代码。自定义模型也会自动补齐 `maxInputTokens`、`maxOutputTokens`、`supportsReasoning`、`thinkingLevelMap` 等能力字段，降低模型接入成本
+
+## 🐛 问题修复
+
+- **--debug hooks 输出**：修复 `--debug` 参数未输出 hooks 执行详情的问题，现在可通过 `--debug hooks` 查看 hooks 的完整执行流程

package/dist/web-ui/docs/cn/cli/release-notes/v2.97.5.md

@@ -0,0 +1,20 @@
+# 🚀 CodeBuddy Code v2.97.5 发布
+
+## 📦 版本信息
+
+| 组件 | 版本 |
+|------|------|
+| CodeBuddy Code CLI | v2.97.5 |
+| Agent SDK JS | v0.3.155 |
+| Agent SDK Python | v0.3.154 |
+
+## 🐛 问题修复
+
+- **专家团多类卡死/无产物/异常结束**：集中修复了多个用户在使用专家团（"腾讯自选股"、"一人公司"、"专业文档生成"、"深度研究"等）时反馈的异常问题，包括任务异常结束无产物、子成员已完成但主会话卡在"思考中"、专家团运行中途自行结束导致制品丢失等场景
+- **Team 成员已完成时 shutdown 无回应**：成员任务已完成后 team-lead 发起 shutdown_request，过去会因绕过 `ShutdownCoordinator` 导致 lead 永远等不到回执；现已统一短路处理，确保 lead 端及时解锁
+- **并发 spawn 时消息丢失**：主 lead 短时间内并发拉起多个成员时，旧逻辑会因找不到对端报错丢消息；现采用 "writeToMailbox first, resolve later" 策略，并附带降级刷新与 notice 提示
+- **成员被错误识别为 team-lead**：修复 respawn 边界下成员消息 `from` 字段串号导致协作错乱的问题，强制 materialise session.meta 并校验 lead 身份
+- **同毫秒并发 shutdown ID 冲突**：lead 并发 shutdown 多成员时 ID 撞车导致回执被覆盖，现使用 `recipient + 时间戳 + 随机数` 形式
+- **进程退出兜底清理**：补齐 session-team 的退出清理，避免长期累积 20+ 个孤儿目录
+- **Fork subagent 递归爆炸**：新增环境变量 `CODEBUDDY_DISABLE_FORK_SUBAGENT`，启用后从工具描述层和运行时层一致禁用 fork subagent，并对历史调用降级为 `general-purpose`，避免请求量爆炸与报错
+- **HTTP User-Agent 头部修复**：修复缺少 `productName` 时 User-Agent 回退为 `WorkBuddy/unknown` 污染下游统计的问题，现仅在产品名存在时才拼入对应段

package/dist/web-ui/docs/en/cli/codebuddy-dir.md

@@ -0,0 +1,309 @@
+# .codebuddy Directory Structure
+
+> A deep dive into the files and subdirectories under CodeBuddy Code's configuration directory `~/.codebuddy` and the project-level `.codebuddy` directory.
+
+CodeBuddy Code uses two configuration directories:
+
+- **Global directory** `~/.codebuddy/`: stores user-level configuration, history, runtime data, etc., affecting all projects
+- **Project directory** `.codebuddy/` (located at the project root): stores project-level configuration, rules, skills, commands, etc., shared with the team via version control
+
+
+### User-Level Extension Directories
+
+#### `agents/`
+
+Stores user-level custom sub-agents that take effect across all projects. Each agent is a single `.md` file:
+
+```
+~/.codebuddy/agents/
+├── code-reviewer.md      # Code review agent
+└── translator.md         # Translation agent
+```
+
+File format (YAML frontmatter + system prompt):
+
+```markdown
+---
+name: code-reviewer
+description: Code review expert; use proactively after writing code
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are a senior code reviewer focused on code quality, security, and best practices...
+```
+
+See [Sub-Agent Documentation](sub-agents.md) for details.
+
+#### `rules/`
+
+Stores user-level rule files that take effect across all projects. All `.md` files are loaded automatically; subdirectories are supported:
+
+```
+~/.codebuddy/rules/
+├── preferences.md        # Personal coding preferences
+└── workflows.md          # Common workflow conventions
+```
+
+Rule files support frontmatter to control loading behavior:
+
+```markdown
+---
+alwaysApply: false
+paths: src/**/*.ts
+---
+
+# TypeScript Conventions
+
+- Prefer `interface` over `type`
+- Disallow `any`
+```
+
+See [Memory Management - Rule System](memory.md#using-codebuddyrules-for-modular-rules) for details.
+
+#### `skills/`
+
+Stores user-level skills that take effect across all projects. Each skill is a self-contained directory containing a `SKILL.md`:
+
+```
+~/.codebuddy/skills/
+└── pdf/
+    └── SKILL.md
+```
+
+See [Skills Documentation](skills.md) for details.
+
+---
+
+### Runtime Data Directories
+
+These directories are maintained automatically by CodeBuddy Code and typically do not require manual operation:
+
+| Directory | Description |
+|------|------|
+| `projects/` | Per-project runtime data, including session records (`.jsonl`) and sub-agent tool output (`tool-results/`) |
+| `sessions/` | Active session data |
+| `plans/` | Plan files generated in plan mode |
+| `logs/` | Runtime logs grouped by date and process |
+| `traces/` | OpenTelemetry execution trace data |
+| `file-history/` | Snapshots of files operated on within each session, used by `/rewind` |
+| `history.jsonl` | Global conversation history (used by `/resume`) |
+| `blobs/` | Binary resources such as images and screenshots, stored by content hash |
+| `tasks/` | Task management system data (TaskCreate/TaskUpdate) |
+| `teams/` | Agent team (TeamCreate) runtime data |
+| `shell-snapshots/` | Bash sandbox startup snapshots that speed up sandbox creation |
+| `plugins/` | File contents of installed plugins |
+| `local_storage/` | CLI internal key-value persistent storage (`.info` files named by content hash) |
+
+---
+
+## Project Directory `.codebuddy/`
+
+Located at the project root and intended to be committed to version control so the team can share it:
+
+```
+.codebuddy/
+├── settings.json              # Project shared configuration
+├── settings.local.json        # Local personal configuration (auto-ignored by .gitignore)
+├── CODEBUDDY.md               # Project-level memory file
+│
+├── agents/                    # Project-level custom sub-agents
+├── rules/                     # Project-level rule files
+├── skills/                    # Project-level skills
+├── commands/                  # Custom slash commands
+```
+
+### Configuration Files
+
+#### `settings.json`
+
+Project shared configuration synced with the team via version control. Suitable for setting team-wide model, permission rules, plugins, and so on:
+
+```json
+{
+  "permissions": {
+    "allow": ["Read", "Edit", "Bash(git:*)", "Bash(npm:*)"],
+    "deny": ["Read(./.env)", "Read(./secrets/**)"]
+  },
+  "enabledPlugins": {
+    "pr-review-toolkit@company-tools": true
+  },
+  "extraKnownMarketplaces": {
+    "company-tools": {
+      "source": {
+        "source": "github",
+        "repo": "myorg/codebuddy-plugins"
+      }
+    }
+  }
+}
+```
+
+#### `settings.local.json`
+
+Local personal configuration. CodeBuddy Code automatically adds it to `.gitignore`. Suitable for personal overrides (such as local debug ports or personal keys) that should not affect other team members.
+
+#### `CODEBUDDY.md`
+
+Project-level memory file shared via version control. Stores team knowledge such as project architecture, conventions, and common commands:
+
+```markdown
+# Project Overview
+
+This project is a TypeScript monorepo (Yarn workspaces).
+
+## Common Commands
+
+- `yarn build` — build all packages
+- `yarn test` — run all tests
+
+## Architectural Conventions
+
+- Uses the CellJS dependency injection framework
+- Protocol definitions live in `*-protocol.ts` files
+```
+
+> **Tip**: You can also place the memory file at the project root as `CODEBUDDY.md` (outside the `.codebuddy/` directory). Both locations are equivalent.
+
+---
+
+### Project-Level Extension Directories
+
+#### `agents/`
+
+Stores project-specific sub-agents, which take precedence over user-level agents. When names collide, the project-level agent overrides the user-level one.
+
+```
+.codebuddy/agents/
+├── blog-translator.md     # Blog translation agent
+└── docs-reviewer.md       # Documentation review agent
+```
+
+#### `rules/`
+
+Stores project-level rules shared via version control. Suitable for team-wide code conventions, workflow agreements, etc. Subdirectories are supported:
+
+```
+.codebuddy/rules/
+├── code-style.md          # Code style conventions
+├── testing.md             # Testing conventions
+├── security.md            # Security requirements
+└── frontend/
+    ├── react.md           # React component conventions
+    └── styles.md          # Styling conventions
+```
+
+All `.md` files are recursively loaded automatically.
+
+#### `skills/`
+
+Stores project-level skills. Each skill is its own directory containing a `SKILL.md` and optional supporting files:
+
+```
+.codebuddy/skills/
+├── case-executor/
+│   ├── SKILL.md           # Skill definition
+│   ├── scripts/           # Helper scripts
+│   └── references/        # Reference materials
+└── cnb-api/
+    └── SKILL.md
+```
+
+`SKILL.md` format:
+
+```markdown
+---
+name: case-executor
+description: Executes JSON test cases and generates reports
+allowed-tools: Read, Write, Bash
+---
+
+You are a test execution expert responsible for running UI test cases in JSON format...
+```
+
+See [Skills Documentation](skills.md) for details.
+
+#### `commands/`
+
+Stores custom slash commands invoked via `/command-name`. Nested directories are supported (invoked using `/group:command`):
+
+```
+.codebuddy/commands/
+├── deploy.md              # /deploy command
+├── team/
+│   ├── issue-start.md     # /team:issue-start command
+│   └── create-issue.md    # /team:create-issue command
+└── openspec/
+    └── propose.md         # /openspec:propose command
+```
+
+Command file format:
+
+```markdown
+---
+description: Create a new Issue
+argument-hint: "<description> ; <type> ; <product>"
+allowed-tools: Bash
+---
+
+Create an Issue based on the following description: $ARGUMENTS
+```
+
+See [Slash Command Documentation](slash-commands.md) for details.
+
+---
+
+## Configuration Priority
+
+Multi-layer configuration is applied with the following priority (higher priority overrides lower priority):
+
+```
+Command-line arguments              (highest priority)
+    ↓
+.codebuddy/settings.local.json    (project local, not committed)
+    ↓
+.codebuddy/settings.json          (project shared, team-wide)
+    ↓
+~/.codebuddy/settings.json        (user global, personal preferences)
+    ↓
+Built-in product defaults           (lowest priority)
+```
+
+Priority for agents/skills/rules: **project-level > user-level > plugin-level**. When names collide, the project level wins.
+
+## Memory Loading Order
+
+```
+1. User-level memory: ~/.codebuddy/CODEBUDDY.md
+2. User-level rules: ~/.codebuddy/rules/*.md (recursive)
+3. Project-level memory: CODEBUDDY.md (searched recursively upward from cwd)
+4. Project-level rules: .codebuddy/rules/*.md (cwd only, no upward search)
+5. Project local memory: CODEBUDDY.local.md
+6. Subdirectory memory: dynamically loaded `CODEBUDDY.md` from a subdirectory when tools operate on files there
+```
+
+## Version Control Recommendations
+
+| File / Directory | Commit to VCS | Notes |
+|-----------|:---:|------|
+| `.codebuddy/settings.json` | ✅ Recommended | Team shared configuration |
+| `.codebuddy/settings.local.json` | ❌ Do not commit | Auto-added to .gitignore |
+| `CODEBUDDY.md` / `.codebuddy/CODEBUDDY.md` | ✅ Recommended | Team shared knowledge |
+| `CODEBUDDY.local.md` | ❌ Do not commit | Auto-added to .gitignore |
+| `.codebuddy/agents/` | ✅ Recommended | Team shared sub-agents |
+| `.codebuddy/rules/` | ✅ Recommended | Team shared rules |
+| `.codebuddy/skills/` | ✅ Recommended | Team shared skills |
+| `.codebuddy/commands/` | ✅ Recommended | Team shared commands |
+
+## Related Resources
+
+- [Settings](settings.md) — Complete configuration field reference
+- [Memory Management](memory.md) — Detailed guide to CODEBUDDY.md and the rule system
+- [Sub-Agents](sub-agents.md) — Create and use custom sub-agents
+- [Skills Documentation](skills.md) — In-depth guide to the skill system
+- [Slash Commands](slash-commands.md) — Custom command reference
+- [MCP Documentation](mcp.md) — MCP server configuration
+
+---
+
+*Use the `.codebuddy` directory wisely to help CodeBuddy Code better understand your project and team conventions.*

package/dist/web-ui/docs/en/cli/env-vars.md

@@ -39,8 +39,10 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for long-running bash commands (default: 120000) |
 | `BASH_MAX_OUTPUT_LENGTH` | Maximum characters of bash output retained in memory (default: 30000, max: 150000). Content exceeding the limit is mid-truncated (keeping head 20% + tail 80%), and the full output is automatically saved to disk |
 | `BASH_MAX_TIMEOUT_MS` | Maximum timeout the model can set for long-running bash commands (default: 600000) |
-| `CODEBUDDY_BASH_ASSISTANT_BUDGET_MS` | Main conversation response budget (milliseconds, default `0`=off). When set to `>0`, foreground Bash/PowerShell commands in the main session that exceed this duration are automatically converted into background tasks to keep the conversation responsive. Sub-agents are not affected by this budget. Aligns with Claude Code's `ASSISTANT_BLOCKING_BUDGET_MS` (CC's official default value `15000`) |
+| `CODEBUDDY_BASH_ASSISTANT_BUDGET_MS` | Main conversation response budget (milliseconds, default `0`=off). When set to `>0`, foreground Bash/PowerShell commands in the main session that exceed this duration are automatically converted into background tasks to keep the conversation responsive. Sub-agents are not affected by this budget. Aligns with CodeBuddy Code's `ASSISTANT_BLOCKING_BUDGET_MS` (the official default value is `15000`) |
 | `CODEBUDDY_BASH_AUTO_BACKGROUND_DISABLED` | Set to `1` to disable timeout auto-backgrounding; foreground commands fall back to the old SIGTERM/kill hard-kill behavior on timeout. Only used for debugging or temporary rollback when encountering regressions; keep the default (unset) in normal scenarios |
+| `CODEBUDDY_BASH_BG_MAX_OUTPUT_BYTES` | Total byte limit for the on-disk file of stdout+stderr for background bash tasks (default `52428800` = 50MB). When exceeded, the size watchdog fires `SIGKILL` and marks the task as `killed`, with a notice injected at the end of stderr. CodeBuddy Code in `ShellCommand.ts` hardcodes the equivalent threshold as a constant; here it is exposed as an env var for operators to tune. Only effective in file fd mode (in pipe mode, child process output is not persisted to disk) |
+| `CODEBUDDY_BASH_BG_PIPE_MODE` | Set to `1` to force background tasks back to pipe mode (not using file fds), for rollback or debugging. The default (unset) uses file fd mode, which solves the zombie process issue caused by grandchild processes (e.g., spawned via `nohup`) holding parent pipe fds; the sandbox path automatically falls back to pipe and does not require explicit setting. There is no equivalent toggle elsewhere; this is a CodeBuddy Code fallback to remain compatible with legacy sandbox/PTY paths |
 
 ## Tool Output Externalization
 
@@ -64,6 +66,7 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `CODEBUDDY_DEFER_TOOL_LOADING` | Set to `false` or `0` to disable MCP tool deferred loading |
 | `CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS` | Set to `true` or `1` to show full descriptions for all deferred tools |
 | `CODEBUDDY_DISABLE_CRON` | Set to `1` to disable scheduled tasks |
+| `CODEBUDDY_DISABLE_FORK_SUBAGENT` | Set to `1` to disable the Agent tool's fork sub-agent mode (`subagent_type="fork"`). When enabled, the fork-mode section is automatically hidden from the Agent tool description, so the model will not see this feature; if the model still passes `subagent_type="fork"`, the runtime falls back to a custom agent named `fork` (e.g., one defined by the user at `.codebuddy/agents/fork.md`), or otherwise rewrites it to a `general-purpose` regular sub-agent. Useful for host scenarios that need to avoid request amplification caused by recursive fork spawning |
 | `CODEBUDDY_REHYDRATE_IMAGE_BLOB_REFS` | Set to `true` to rehydrate image blob references to full base64 data in `-p` mode streaming output. Useful for downstream integrations that need direct access to image data |
 
 ## Context and Memory
@@ -145,6 +148,24 @@ CodeBuddy Code supports environment variables to control its behavior. These var
 | `DISABLE_AUTOUPDATER` | Set to `1` to disable auto-updates |
 | `DISABLE_FEEDBACK_COMMAND` | Set to `1` to disable the `/feedback` command |
 
+### OpenTelemetry Custom Reporting (traces)
+
+CodeBuddy Code supports reporting internal traces to your own Collector via the OTLP protocol. Environment variables follow the [OpenTelemetry specification](https://opentelemetry.io/docs/specs/otel/protocol/exporter/). For detailed usage, see [Monitoring](monitoring.md).
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_CODE_ENABLE_TELEMETRY` | Set to `1` to enable OTel custom reporting; the legacy alias `CLAUDE_CODE_ENABLE_TELEMETRY` is also accepted for backward compatibility |
+| `OTEL_TRACES_EXPORTER` | `otlp` (default) / `console` (output to logs, useful for debugging) / `none` (off) |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Generic OTLP endpoint; the tool automatically appends `/v1/traces` |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Traces-specific endpoint, used as a complete URL; takes priority over the generic variable |
+| `OTEL_EXPORTER_OTLP_HEADERS` | OTLP request headers in the format `k1=v1,k2=v2`; values support URL encoding |
+| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | Traces-specific request headers; takes priority over the generic variable |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` | Only `http/protobuf` (default) is supported; other values (such as `grpc`, `http/json`) fall back and emit a warning |
+| `OTEL_SERVICE_NAME` | Override the default `service.name` |
+| `OTEL_RESOURCE_ATTRIBUTES` | Resource attributes in the format `k1=v1,k2=v2`; merged into the trace resource |
+
+> When `DISABLE_TELEMETRY=1`, OTel reporting is turned off regardless of the variables above.
+
 ## Tasks and Background Work
 
 | Environment Variable | Description |
@@ -257,7 +278,7 @@ codebuddy --model your-model-name
 
 #### Connecting to DeepSeek Example
 
-To connect to any third-party model service compatible with the Anthropic protocol (such as DeepSeek), you only need to configure the Base URL, API Key, and model variables — no additional `models.json` modifications are required:
+To connect to any third-party model service compatible with the protocol (such as DeepSeek), you only need to configure the Base URL, API Key, and model variables — no additional `models.json` modifications are required:
 
 ```bash
 # Endpoint and key