@tencent-ai/agent-sdk 0.3.99 → 0.3.101

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

@@ -0,0 +1,28 @@
+# 🚀 CodeBuddy Code v2.68.0 发布
+
+## ✨ 新功能
+
+### Web UI 文档查看器
+
+在 Web UI 中新增文档浏览功能，无需离开工作界面即可查阅 CLI 使用文档：
+
+- 支持全文搜索，快速定位所需内容
+- 中英文切换，满足不同语言偏好
+- 目录导航和 TOC，方便浏览长文档
+- API Reference 快捷链接，直接跳转到 Swagger UI
+- 支持在新标签页中独立全屏打开
+- 构建时自动打包 CLI 文档，支持离线查看
+
+## 🔧 改进优化
+
+- **HTTP API 标准化**：所有公开端点统一到 `/api/v1/` 前缀，支持版本控制；内部端点迁移到 `/internal/`，结构更清晰
+- **API 文档**：新增 Swagger UI（`/api/docs`）和 OpenAPI 规范（`/api/openapi.json`），方便开发者探索和调试 API
+- **统一响应格式**：公开端点采用标准 `{ data }` / `{ error: { code, message } }` 信封格式，提升 API 一致性
+- **ACP 端点迁移**：ACP 协议端点从 `/acp` 迁移到 `/api/v1/acp`，与 REST API 统一路由前缀
+- **凭证存储优化**：WeChat 和 WeCom 凭证统一为单文件 `instances.json` 格式，支持自动迁移旧格式
+- **API 响应兼容**：Web UI 适配统一信封格式，确保 REST 端点响应正确解析
+
+## 🐛 问题修复
+
+- **确认框显示**：修复 AskUserQuestion 确认框偶发不显示的问题，解决路由导航中的竞态条件
+- **文档链接格式**：修正 Channels 文档中 localhost 链接的格式

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

@@ -0,0 +1,16 @@
+# 🚀 CodeBuddy Code v2.7.0 发布
+
+## ✨ 新功能
+
+- Token 计数器显示控制：新增显示开关设置，可以根据个人偏好选择显示或隐藏 Token 使用统计信息
+
+## 🔧 改进优化
+
+- 会话标识符规则优化：放宽会话 ID 的格式限制，支持更灵活的自定义会话标识
+- 统计准确性提升：改进工具执行状态的统计逻辑，确保使用数据的准确性
+
+## 🐛 问题修复
+
+- 消息处理可靠性增强：增强消息类型校验机制，避免非法数据导致的处理异常
+- 错误反馈机制优化：改进异常信息的传递流程，提供更清晰的错误提示
+- 主题适配体验优化：优化颜色显示算法，自动适配暗色和亮色主题，提升视觉舒适度

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

@@ -0,0 +1,18 @@
+# 🚀 CodeBuddy Code v2.8.0 发布
+
+## ✨ 新功能
+
+- 编辑器原生集成：支持通过 ACP 协议与 Zed 等编辑器深度集成，带来更流畅的 AI 辅助开发体验
+- 智能安全防护：引入五级命令风险分级系统，覆盖文件操作、Git 管理、容器控制等 9 大类场景，高风险操作自动拦截确认，让 AI 自动化更安心
+
+## 🔧 改进优化
+
+- 危险操作智能识别：优化风险评估策略，自动识别可能丢失数据的 Git 操作并提升风险等级，主分支保护更严格
+- 安全模式增强：改进权限绕过模式的安全检查，交互场景下极高风险操作仍需确认，兼顾自动化与安全
+- 视觉提示升级：高风险命令确认界面使用警告色高亮，一眼识别潜在危险操作
+- 文档解析效率提升：优化 Markdown 文件处理性能，加载速度更快
+
+## 🐛 问题修复
+
+- 安全审批机制加固：修复高风险命令可能跳过确认的漏洞，确保所有危险操作都经过用户授权
+- 提示模板优化：消除系统提示中的重复内容，提升 AI 响应的准确性

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

@@ -0,0 +1,17 @@
+# 🚀 CodeBuddy Code v2.8.1 发布
+
+## 🔧 改进优化
+
+- **Plan 模式重构**：采用全新的 Sub-Agent 架构重构 Plan 模式，提供更智能、更稳定的任务规划和执行能力
+- **智能模型图片检测**：自动检测模型图片支持能力，在模型不支持时智能处理图片输入，提升跨模型使用的流畅度
+- **运行环境健康检查**：启动时自动检测 Node.js 版本，提前规避环境兼容性问题，确保工具稳定运行
+- **ACP 协议体验增强**：创建会话时自动推送命令列表，支持智能补全；优化认证方式，根据网络环境自动推荐最佳登录选项
+- **权限命令风险调整**：优化 sudo/su 等提权命令的风险分级策略，减少不必要的二次确认，在保障安全的前提下提升效率
+
+## 🐛 问题修复
+
+- **Git 操作安全增强**：优化危险命令检测规则，更精准地识别和拦截强制推送、删除分支等高风险 Git 操作
+- **Windows 路径兼容**：修复 Windows 系统下的路径大小写敏感问题，提升跨平台文件操作的稳定性
+- **非交互模式工具控制**：修复用户问答工具在非交互模式下的行为逻辑，确保自动化流程顺畅执行
+- **专享版环境适配**：修复专享版环境识别异常，确保配置加载的正确性
+- **剪贴板检测兼容性**：临时调整剪贴板检测策略，解决部分环境下的误触发问题，提升使用体验

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

@@ -0,0 +1,5 @@
+# 🚀 CodeBuddy Code v2.8.2 发布
+
+## 🔧 改进优化
+
+- **对话上下文增强**：改进对话消息处理机制，确保完整的上下文信息在多轮对话中正确保留和传递，提升 AI 响应的连贯性和准确性

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

@@ -0,0 +1,14 @@
+# 🚀 CodeBuddy Code v2.8.3 发布
+
+## 🔧 改进优化
+
+- **Gemini 模型支持扩展**：新增 Gemini-3.0-Pro 模型支持，为你提供更强大的推理能力和更大的上下文窗口，胜任更复杂的编程任务
+- **文件处理智能优化**：自动识别并跳过超大文件的引用处理，有效避免性能问题，提升大型项目的响应速度
+- **代码架构稳定性增强**：优化中间件依赖注入机制、服务初始化流程和会话类型定义，提升系统运行稳定性和代码维护性
+- **会话管理体验提升**：改进会话恢复面板的数据处理逻辑，提供更流畅的会话管理体验
+- **权限控制可靠性**：完善目录信任状态管理，让权限控制更精准、更可靠
+
+## 🐛 问题修复
+
+- **远程执行环境连接稳定性**：优化认证令牌处理机制，提升连接沙箱和远程执行环境时的稳定性
+- **Shell 命令兼容性**：改进命令执行环境，支持需要终端交互的工具命令，提升各类命令的执行成功率

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

@@ -0,0 +1,9 @@
+# 🚀 CodeBuddy Code v2.8.4 发布
+
+## 🔧 改进优化
+
+- 类型定义优化：改进代码组织结构，提升长期维护效率
+
+## 🐛 问题修复
+
+- 权限模式同步：修复子任务执行时权限设置未能正确应用的问题，确保批量操作权限控制的一致性

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

@@ -0,0 +1,5 @@
+# 🚀 CodeBuddy Code v2.8.5 发布
+
+## 📚 文档增强
+
+- GitLab CI/CD 集成指南：新增完整的 CI/CD 集成文档，帮助您在 GitLab 流水线中轻松使用 CodeBuddy Code，包含详细的配置示例、使用场景说明和常见问题解决方案

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

@@ -0,0 +1,14 @@
+# 🚀 CodeBuddy Code v2.8.6 发布
+
+## 🔧 改进优化
+
+- 终端输入处理增强：改进跨平台输入解析机制，提升终端使用的稳定性和兼容性
+- 粘贴体验优化：完善大段文本粘贴处理，自动识别粘贴模式，提升文本输入便捷性
+- 消息处理机制优化：重构内部消息队列，提升对话响应速度和系统稳定性
+- 界面渲染性能提升：优化应用主界面和聊天视图的渲染效率，提供更流畅的交互体验
+- 命令执行流程简化：优化终端命令执行逻辑，提升执行效率
+
+## 🐛 问题修复
+
+- 协议模式配置保持：修复客户端协议模式下多轮会话中配置丢失的问题，确保会话稳定性
+- tmux 剪贴板粘贴：修复在 tmux 终端环境中无法粘贴剪贴板图片的问题

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

@@ -0,0 +1,5 @@
+# 🚀 CodeBuddy Code v2.9.0 发布
+
+## ✨ 新功能
+
+- 认证成功通知：新增用户登录成功后的 Hook 通知事件，支持在认证完成时触发自定义脚本，实现登录后的自动化工作流

package/cli/dist/web-ui/docs/cn/cli/remote-control.md

@@ -0,0 +1,247 @@
+# 远程控制（Remote Control）
+
+> **Beta**：远程控制功能目前处于 Beta 阶段，功能和接口可能会在后续版本中发生变化。欢迎试用并反馈问题。
+
+通过 Remote Control，您可以从手机、平板或任意浏览器远程访问本地运行的 CodeBuddy Code 会话。会话始终在您的本机执行，Web 界面只是一个远程窗口。
+
+## 概述
+
+Remote Control 在本地启动一个 Gateway 服务，通过 Cloudflare Tunnel 或局域网暴露一个 Web UI，让您可以从任何设备连接到正在运行的 CodeBuddy Code 会话。
+
+使用 Remote Control，您可以：
+
+- **远程使用完整的本地环境**：文件系统、MCP 服务器、工具配置全部保持可用
+- **通过 Web UI 与 Agent 交互**：在浏览器中发送消息、查看对话、监控工具执行
+- **从多设备接入**：手机扫码即可连接，支持局域网和公网访问
+- **通过终端管理会话**：在终端和 Web 端同时工作，对话保持同步
+
+## 前置条件
+
+- 已安装并登录 CodeBuddy Code（运行 `codebuddy` 后使用 `/login` 登录）
+- 若需要公网访问，需安装 [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)（可选）
+
+## 启动远程控制
+
+在 CodeBuddy Code 会话中使用 `/gateway` 命令启动远程控制服务：
+
+```
+/gateway
+```
+
+启动成功后，终端会显示连接信息：
+
+```
+Gateway started
+
+  ├─ Status   connected
+  ├─ Mode     tunnel
+  ├─ Local    http://127.0.0.1:8321
+  ├─ Tunnel   https://xxx-xxx-xxx.trycloudflare.com
+  ├─ Web UI   https://xxx-xxx-xxx.trycloudflare.com/?password=<token>
+  └─ Webhook  https://xxx-xxx-xxx.trycloudflare.com/gateway/webhook/:platform
+
+  Scan to open Web UI:
+
+  [QR Code]
+```
+
+### 连接方式
+
+Gateway 启动后，有以下几种方式从其他设备连接：
+
+- **扫描二维码**：用手机扫描终端中显示的二维码，直接打开 Web UI
+- **复制 Web UI 链接**：将带有认证 token 的 URL 在任意浏览器中打开
+- **局域网访问**：同一网络中的设备可直接访问 Local 地址（如 `http://10.x.x.x:8321`）
+
+### 子命令
+
+| 命令 | 说明 |
+|:-----|:-----|
+| `/gateway` | 启动 Gateway（默认带 Tunnel） |
+| `/gateway status` | 查看当前 Gateway 状态 |
+| `/gateway stop` | 停止 Gateway |
+| `/gateway token` | 重新生成认证 token |
+| `/gateway tunnel` | 启动带 Tunnel 的 Gateway |
+
+## 网络模式
+
+Gateway 支持两种网络模式，适应不同的使用场景：
+
+### Tunnel 模式（默认）
+
+通过 Cloudflare Quick Tunnel 自动分配一个临时公网域名（`*.trycloudflare.com`），无需任何额外配置即可从公网访问。
+
+适用场景：
+- 从外部网络（如手机移动网络）远程访问
+- 不想配置端口转发或 VPN
+
+需要安装 `cloudflared`：
+
+```bash
+# macOS
+brew install cloudflared
+
+# Debian/Ubuntu
+curl -L https://pkg.cloudflare.com/cloudflared-stable-linux-amd64.deb -o cloudflared.deb
+sudo dpkg -i cloudflared.deb
+
+# Windows
+winget install Cloudflare.cloudflared
+```
+
+### 局域网模式
+
+当 `cloudflared` 未安装或 Tunnel 启动失败时，Gateway 自动回退到局域网模式。此模式下，仅同一网络中的设备可以访问。
+
+- 默认监听端口：`8321`
+- 监听地址：`0.0.0.0`（所有网络接口）
+
+## 安全机制
+
+### 认证
+
+Gateway 启动时会自动生成一个随机密码（token），访问 Web UI 和 API 均需要通过认证。支持以下认证方式：
+
+| 方式 | 说明 |
+|:-----|:-----|
+| URL 参数 | `?password=<token>`，适合快速分享链接 |
+| Cookie | 登录后自动设置，后续访问无需重复认证 |
+| Bearer Token | `Authorization: Bearer <token>`，适合 API 调用 |
+
+密码可通过 `/gateway token` 命令重新生成。重新生成后，之前的密码立即失效。
+
+### 登录限流
+
+为防止暴力破解，认证中间件内置了登录限流机制：
+
+- 每分钟最多允许 2 次失败尝试
+- 每小时额外允许 12 次失败尝试
+- 超出限制后将暂时拒绝登录请求
+
+### 权限
+
+通过远程控制执行的任务自动以 `bypassPermissions` 模式运行，即工具执行不需要逐一审批。这是因为远程场景下无法进行交互式审批。请确保仅将访问链接分享给受信任的人。
+
+### CORS 策略
+
+Gateway 默认允许以下来源的跨域请求：
+
+- 本地回环地址（`localhost`、`127.0.0.1`、`[::1]`）
+- Tunnel 分配的公网地址
+- 通过 `gateway.corsOrigins` 配置的额外来源
+
+## Web UI
+
+Web UI 提供了完整的 CodeBuddy Code 交互界面，包括：
+
+- **对话界面**：发送消息、查看 Agent 回复、监控工具调用
+- **终端面板**：内置 Web 终端，直接在浏览器中操作远程终端
+- **实例管理**：查看和管理多个 CodeBuddy Code 实例
+- **主题切换**：支持亮色/暗色主题
+- **多语言**：支持中英文界面切换
+
+Web UI 基于 ACP（Agent Client Protocol）与本地 Agent 通信，保证了与终端交互完全一致的体验。
+
+## 配置
+
+### Settings 配置
+
+在 `~/.codebuddy/settings.json` 中可以配置 Gateway 相关选项：
+
+```json
+{
+  "gateway": {
+    "auth": "password",
+    "password": "your-custom-password",
+    "corsOrigins": ["https://your-domain.com"],
+    "maxConnections": 5,
+    "tokenTtlMs": 86400000
+  }
+}
+```
+
+| 配置键 | 说明 | 默认值 |
+|:------|:-----|:------|
+| `auth` | 认证模式，`"password"` 或 `"none"` | `"none"` |
+| `password` | 自定义密码。为空时首次启动自动生成 | 自动生成 |
+| `corsOrigins` | 额外允许的 CORS 来源列表 | `[]` |
+| `maxConnections` | ACP 最大并发连接数 | `5` |
+| `tokenTtlMs` | ACP Session Token 有效期（毫秒） | `86400000`（24 小时） |
+
+### 环境变量
+
+| 环境变量 | 说明 |
+|:---------|:-----|
+| `CODEBUDDY_CORS_ORIGINS` | 额外的 CORS 允许来源（逗号分隔） |
+
+## 实例管理
+
+当您在多个项目目录中运行 CodeBuddy Code 时，每个实例会自动注册到本地实例注册表（`~/.codebuddy/instances.json`）。Web UI 的实例管理面板可以查看所有活跃的实例，并在它们之间切换。
+
+实例信息包括：
+
+- 工作目录
+- 本地/Tunnel 地址
+- 操作系统和架构
+- 启动时间和运行状态
+
+## 第三方平台集成（Webhook）
+
+Gateway 提供了 Webhook 端点，支持接入企业通讯平台机器人：
+
+```
+{gateway-url}/gateway/webhook/:platform
+```
+
+支持的平台适配器：
+
+| 平台 | 标识 |
+|:-----|:-----|
+| 企业微信 | `wecom` |
+| 钉钉 | `dingtalk` |
+| 飞书 | `feishu` |
+| 通用 | `generic` |
+
+配置企业机器人的 Webhook 回调地址为上述端点后，即可通过企业通讯平台向 CodeBuddy Code 发送消息并接收回复。
+
+## 连接与安全
+
+- Gateway 仅在本地启动 HTTP 服务，不会在您的机器上打开入站端口
+- 公网访问通过 Cloudflare Tunnel 的出站连接实现
+- 所有 Tunnel 流量通过 Cloudflare 的 TLS 加密传输
+- 使用固定端口启动时，Quick Tunnel 域名可跨 CLI 重启保持不变（参见[保持 Tunnel 域名稳定](#保持-tunnel-域名稳定)）
+
+## 限制
+
+- **每个会话一个 Gateway**：每个 CodeBuddy Code 实例同时只支持一个 Gateway 服务
+- **终端需保持运行**：Gateway 作为本地进程运行。关闭终端或停止 CodeBuddy Code 进程后，远程连接会断开。使用 `/gateway` 重新启动
+- **Quick Tunnel 域名临时性**：Quick Tunnel 域名在 cloudflared 进程存活期间保持不变。使用固定端口启动可以跨 CLI 重启复用 cloudflared 进程（参见[保持 Tunnel 域名稳定](#保持-tunnel-域名稳定)）。如果 cloudflared 进程退出（如机器重启），域名将重新分配。如需永久固定域名，可使用 Named Tunnel（需要 Cloudflare 账号）
+- **局域网模式限制**：未安装 `cloudflared` 时仅限同一网络内的设备访问
+
+## 保持 Tunnel 域名稳定
+
+Quick Tunnel 默认每次启动 cloudflared 都会分配一个新的随机域名。通过指定固定端口，可以让域名在多次 CLI 重启之间保持不变。
+
+### 使用固定端口
+
+使用 `--port` 参数指定固定端口启动 CLI：
+
+```bash
+codebuddy --port 8321
+```
+
+这样每次启动都使用相同端口，`/gateway` 会自动复用上一次的 cloudflared 进程和域名。
+
+> 如果不指定 `--port`，系统会随机分配端口，每次端口不同导致无法匹配已有的 cloudflared 进程。
+
+### 停止 Tunnel
+
+执行 `/gateway stop` 会终止 cloudflared 进程并清理状态。下次启动将分配新域名。
+
+如果只是退出 CLI（Ctrl+C 或 `/exit`），cloudflared 进程会继续运行，等待下次 CLI 启动时复用。
+
+## 相关文档
+
+- [设置配置](settings.md)：配置 Gateway 相关选项
+- [Hooks](hooks.md)：配置工具执行前后的自定义命令
+- [权限管理](iam.md)：了解权限模式和规则