@tencent-ai/codebuddy-code 2.67.0 → 2.68.0

package/dist/web-ui/docs/cn/cli/channels-reference.md

@@ -0,0 +1,293 @@
+# Channels 参考 [Beta]
+
+> **Beta 功能**：Channels 目前处于 Beta 阶段，协议和接口可能会根据反馈进行调整。
+
+Channel 是一种特殊的 MCP 服务器，可以将外部事件（Webhook、聊天消息、监控告警等）推送到 CodeBuddy Code 会话中，让 CodeBuddy Code 对终端外部发生的事情做出反应。
+
+## 概述
+
+Channel 运行在与 CodeBuddy Code 相同的机器上，通过 stdio 与 CodeBuddy Code 通信。CodeBuddy Code 将其作为子进程启动。
+
+典型的使用场景：
+
+- **聊天平台**（Telegram、Discord）：插件本地运行，轮询平台 API 获取新消息，转发给 CodeBuddy Code
+- **Webhook**（CI、监控）：服务器监听本地 HTTP 端口，接收外部系统的 POST 请求，推送给 CodeBuddy Code
+
+Channel 分为两种模式：
+
+| 模式 | 说明 |
+|------|------|
+| 单向 | 只转发事件给 CodeBuddy Code（告警、Webhook），在本地会话中处理 |
+| 双向 | 额外暴露 reply 工具，让 CodeBuddy Code 可以回复消息 |
+
+## 使用 Channel
+
+### 启动
+
+使用 `--channels` 参数指定要加载的 channel：
+
+```bash
+# 加载插件类型的 channel
+codebuddy --channels plugin:fakechat@claude-plugins-official
+
+# 加载 .mcp.json 中配置的 channel server
+codebuddy --channels server:webhook
+
+# 加载多个 channel（逗号分隔）
+codebuddy --channels plugin:telegram@claude-plugins-official,plugin:discord@claude-plugins-official
+```
+
+### 开发模式
+
+自定义 channel 在初始阶段使用 `--dangerously-load-development-channels` 标志来测试。此标志允许任何 channel 运行，无需在允许列表中：
+
+```bash
+codebuddy --dangerously-load-development-channels server:my-webhook
+```
+
+此标志仅绕过允许列表检查，`channelsEnabled` 组织策略仍然生效。一旦 channel 提交到官方市场并通过安全审查，就会被添加到允许列表，之后可以直接使用 `--channels` 加载。
+
+### 会话中的 Channel 消息
+
+Channel 消息以 `<channel>` 标签的形式注入到 CodeBuddy Code 的上下文中：
+
+```xml
+<channel source="fakechat" sender="web" chat_id="1">你好，请帮我看看这个问题</channel>
+```
+
+在 TUI 中，channel 消息以友好格式显示：
+
+```
+#fakechat · web: 你好，请帮我看看这个问题
+```
+
+### 设置
+
+在 `settings.json` 中可以控制 channel 功能：
+
+```json
+{
+  "channelsEnabled": true
+}
+```
+
+设为 `false` 可完全禁用 channel 功能。
+
+## 构建 Channel
+
+### 基本要求
+
+一个 channel server 需要：
+
+1. 声明 `claude/channel` capability，让 CodeBuddy Code 注册通知监听器
+2. 发送 `notifications/claude/channel` 事件
+3. 通过 stdio transport 连接（CodeBuddy Code 将其作为子进程启动）
+
+### 最小示例：Webhook 接收器
+
+```ts
+#!/usr/bin/env bun
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+const mcp = new Server(
+  { name: 'webhook', version: '0.0.1' },
+  {
+    capabilities: { experimental: { 'claude/channel': {} } },
+    instructions: '来自 webhook 的事件以 <channel source="webhook" ...> 标签到达。单向通道，只需阅读并处理。',
+  },
+)
+
+await mcp.connect(new StdioServerTransport())
+
+Bun.serve({
+  port: 8788,
+  hostname: '127.0.0.1',
+  async fetch(req) {
+    const body = await req.text()
+    await mcp.notification({
+      method: 'notifications/claude/channel',
+      params: {
+        content: body,
+        meta: { path: new URL(req.url).pathname, method: req.method },
+      },
+    })
+    return new Response('ok')
+  },
+})
+```
+
+注册到 `.mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "webhook": { "command": "bun", "args": ["./webhook.ts"] }
+  }
+}
+```
+
+## Server 配置选项
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `capabilities.experimental['claude/channel']` | `object` | **必填**。始终为 `{}`。声明后 CodeBuddy Code 注册通知监听器 |
+| `capabilities.experimental['claude/channel/permission']` | `object` | 可选。始终为 `{}`。声明此 channel 可以接收权限中继请求 |
+| `capabilities.tools` | `object` | 双向 channel 需要。始终为 `{}`。标准 MCP 工具能力 |
+| `instructions` | `string` | 推荐。注入到 system prompt，告诉 CodeBuddy Code 如何处理此 channel 的事件 |
+
+## 通知格式
+
+发送 `notifications/claude/channel` 通知时，params 包含两个字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `content` | `string` | 事件内容，成为 `<channel>` 标签的正文 |
+| `meta` | `Record<string, string>` | 可选。每个键值对成为 `<channel>` 标签的属性。键名仅允许字母、数字和下划线，包含连字符或其他字符的键会被静默丢弃 |
+
+示例：
+
+```ts
+await mcp.notification({
+  method: 'notifications/claude/channel',
+  params: {
+    content: 'build failed on main',
+    meta: { severity: 'high', run_id: '1234' },
+  },
+})
+```
+
+到达 CodeBuddy Code 时的格式：
+
+```xml
+<channel source="webhook" severity="high" run_id="1234">
+build failed on main
+</channel>
+```
+
+## 暴露 Reply 工具
+
+双向 channel 需要暴露标准 MCP 工具让 CodeBuddy Code 回复消息：
+
+```ts
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+
+mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [{
+    name: 'reply',
+    description: '通过此 channel 发送回复消息',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: '要回复的对话 ID' },
+        text: { type: 'string', description: '要发送的消息' },
+      },
+      required: ['chat_id', 'text'],
+    },
+  }],
+}))
+
+mcp.setRequestHandler(CallToolRequestSchema, async req => {
+  if (req.params.name === 'reply') {
+    const { chat_id, text } = req.params.arguments as { chat_id: string; text: string }
+    // 调用你的聊天平台 API 发送消息
+    await sendToPlatform(chat_id, text)
+    return { content: [{ type: 'text', text: 'sent' }] }
+  }
+  throw new Error(`unknown tool: ${req.params.name}`)
+})
+```
+
+## 发送者安全管控
+
+未设防的 channel 是 prompt 注入攻击向量。任何能访问你端点的人都可以向 CodeBuddy Code 注入文本。
+
+在调用 `mcp.notification()` 之前，必须检查发送者身份：
+
+```ts
+const allowed = new Set(loadAllowlist())
+
+// 在消息处理器中，发送通知之前：
+if (!allowed.has(message.from.id)) {  // 检查发送者 ID，而非群组 ID
+  return  // 静默丢弃
+}
+await mcp.notification({ ... })
+```
+
+**重要**：始终基于发送者身份（`message.from.id`）而非聊天室身份（`message.chat.id`）进行验证。在群聊中，这两个值不同，按群组验证会让群内任何人都能向会话注入消息。
+
+## 权限中继
+
+当 CodeBuddy Code 调用需要审批的工具（如 `Bash`、`Write`、`Edit`）时，本地终端会打开权限对话框。双向 channel 可以选择同时接收这个提示，让你在远程设备上审批或拒绝。
+
+本地终端和远程 channel 的对话框同时打开，**先到的回答生效**，另一个自动关闭。
+
+### 启用权限中继
+
+在 Server 构造器中添加 `claude/channel/permission`：
+
+```ts
+capabilities: {
+  experimental: {
+    'claude/channel': {},
+    'claude/channel/permission': {},  // 启用权限中继
+  },
+  tools: {},
+},
+```
+
+### 权限请求字段
+
+CodeBuddy Code 发送 `notifications/claude/channel/permission_request`，包含以下字段：
+
+| 字段 | 说明 |
+|------|------|
+| `request_id` | 5 个小写字母（排除 `l`），用于匹配回复 |
+| `tool_name` | CodeBuddy Code 要使用的工具名，如 `Bash`、`Write` |
+| `description` | 工具调用的可读描述 |
+| `input_preview` | 工具参数的 JSON 字符串，截断到 200 字符 |
+
+### 发送裁决
+
+你的 channel 需要发送 `notifications/claude/channel/permission` 通知：
+
+```ts
+await mcp.notification({
+  method: 'notifications/claude/channel/permission',
+  params: {
+    request_id: '<收到的 request_id>',
+    behavior: 'allow',  // 或 'deny'
+  },
+})
+```
+
+### 处理入站裁决
+
+在入站消息处理器中识别 `yes <id>` 或 `no <id>` 格式的回复：
+
+```ts
+// 匹配 "y abcde", "yes abcde", "n abcde", "no abcde"
+// [a-km-z] 是 CodeBuddy Code 使用的 ID 字母表（小写，跳过 'l'）
+const PERMISSION_REPLY_RE = /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i
+
+const m = PERMISSION_REPLY_RE.exec(message.text)
+if (m) {
+  await mcp.notification({
+    method: 'notifications/claude/channel/permission',
+    params: {
+      request_id: m[2].toLowerCase(),
+      behavior: m[1].toLowerCase().startsWith('y') ? 'allow' : 'deny',
+    },
+  })
+  return  // 作为裁决处理，不转发为聊天
+}
+```
+
+## 打包为插件
+
+将 channel 包装为插件可以方便分享和安装。用户通过 `/plugin install` 安装，然后用 `--channels plugin:<name>@<marketplace>` 启用。
+
+## 参考
+
+- [fakechat 示例](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/fakechat)：完整的双向 channel 实现，包含 Web UI、文件附件和 reply 工具
+- [MCP 协议](https://modelcontextprotocol.io)：channel 基于 MCP 协议实现

package/dist/web-ui/docs/cn/cli/channels.md

@@ -0,0 +1,215 @@
+# Channels：将外部事件推送到会话中 [Beta]
+
+> **Beta 功能**：Channels 目前处于 Beta 阶段，功能和接口可能会根据反馈进行调整。
+
+Channel 是一种 MCP 服务器，可以将消息、告警和 Webhook 推送到你正在运行的 CodeBuddy Code 会话中，让 CodeBuddy Code 在你不在终端时也能对外部事件做出反应。
+
+Channel 可以是双向的：CodeBuddy Code 读取事件后通过同一 channel 回复，就像一个聊天桥。事件仅在会话打开时到达，如需持续运行，可以在后台进程或持久终端中运行 CodeBuddy Code。
+
+你可以通过安装插件或使用内置 channel 来启用。微信、Telegram、Discord 以及 fakechat 演示都已支持。
+
+当 CodeBuddy Code 通过 channel 回复时，终端会显示工具调用和确认（如"sent"），实际回复内容出现在对应的聊天平台上。
+
+本页涵盖：
+
+* [支持的 Channel](#支持的-channel)：微信、Telegram、Discord 以及 fakechat 设置
+* [快速开始](#快速开始)：使用微信 channel 快速体验
+* [安全机制](#安全机制)：发送者白名单和配对流程
+* [组织管控](#组织管控)：为团队和企业启用 channel
+* [Channel 与其他功能的对比](#功能对比)
+
+要构建自己的 channel，请参阅 [Channels 参考](./channels-reference.md)。
+
+## 支持的 Channel
+
+### 微信（内置）
+
+微信 channel 是 CodeBuddy Code 内置的，无需安装插件。通过微信 ClawBot 实现双向消息通信，支持文本、图片和文件收发。
+
+**前提条件**：
+- 微信版本 iOS 8.0.70 及以上
+- 在微信中启用 ClawBot 插件（微信 → 我 → 设置 → 插件 → ClawBot）
+
+**扫码绑定**：
+
+1. 在 CodeBuddy Code 中执行 `/remote-control wechat` 或 `/remote-control` 选择 wechat
+2. 终端显示二维码（如果二维码显示异常，会提供浏览器链接）
+3. 用微信扫描二维码并确认
+4. 绑定成功后自动开始接收消息
+
+**使用**：
+
+绑定后，在微信 ClawBot 对话中发送消息，消息会自动出现在 CodeBuddy Code 会话中：
+
+```
+#wechat · user_id: 你好，帮我看一下这个 bug
+```
+
+CodeBuddy Code 会处理消息并通过 `WechatReply` 工具回复，回复内容出现在微信中。
+
+支持的消息类型：
+
+| 类型 | 接收 | 发送 |
+|------|------|------|
+| 文本 | 支持 | 支持 |
+| 图片 | 支持（自动下载解密到本地） | 支持（自动加密上传到 CDN） |
+| 文件 | 支持 | 支持 |
+
+**凭证管理**：
+
+扫码成功后凭证保存在 `~/.codebuddy/channels/wechat/credentials.json`。下次启动时自动使用已保存的凭证，无需重新扫码。
+
+```bash
+# 查看连接状态
+/remote-control wechat status
+
+# 断开连接
+/remote-control wechat stop
+
+# 重新连接（使用已保存凭证）
+/remote-control wechat start
+```
+
+### Telegram
+
+需要安装插件。查看完整 [Telegram 插件源码](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram)。
+
+1. 在 Telegram 中通过 [BotFather](https://t.me/BotFather) 创建一个 bot，获取 token
+2. 安装插件：`/plugin install telegram@claude-plugins-official`
+3. 配置 token：`/telegram:configure <token>`
+4. 启动：`codebuddy --channels plugin:telegram@claude-plugins-official`
+5. 向 bot 发消息获取配对码，执行 `/telegram:access pair <code>` 完成配对
+
+### Discord
+
+需要安装插件。查看完整 [Discord 插件源码](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord)。
+
+1. 在 [Discord 开发者门户](https://discord.com/developers/applications) 创建应用和 bot
+2. 启用 Message Content Intent，邀请 bot 到服务器
+3. 安装插件：`/plugin install discord@claude-plugins-official`
+4. 配置 token：`/discord:configure <token>`
+5. 启动：`codebuddy --channels plugin:discord@claude-plugins-official`
+6. DM bot 获取配对码，执行 `/discord:access pair <code>` 完成配对
+
+### fakechat（演示）
+
+fakechat 是官方支持的演示 channel，在 localhost 上运行一个聊天 UI，无需认证和外部服务。
+
+```bash
+# 安装
+/plugin install fakechat@claude-plugins-official
+
+# 启动
+codebuddy --channels plugin:fakechat@claude-plugins-official
+```
+
+打开 `http://localhost:8787` 即可开始聊天。
+
+## 快速开始
+
+以微信 channel 为例，快速体验完整的双向通信流程：
+
+**第 1 步：确保 ClawBot 已启用**
+
+在微信中打开 **我 → 设置 → 插件**，找到 ClawBot 并启用。
+
+**第 2 步：扫码绑定**
+
+启动 CodeBuddy Code，执行：
+
+```
+/remote-control wechat
+```
+
+终端显示二维码。用微信扫描并确认绑定。
+
+**第 3 步：发送消息**
+
+在微信 ClawBot 对话中发送：
+
+```
+帮我看一下当前目录有什么文件
+```
+
+消息到达 CodeBuddy Code 会话，显示为：
+
+```
+#wechat · user_id: 帮我看一下当前目录有什么文件
+```
+
+CodeBuddy Code 执行任务后通过 `WechatReply` 工具回复，回复内容出现在微信中。
+
+**第 4 步：发送图片**
+
+在微信中发一张截图给 ClawBot，CodeBuddy Code 会自动下载并识别图片内容。你可以要求它编辑图片并发回：
+
+```
+给图片中的人物加一顶帽子
+```
+
+CodeBuddy Code 使用 ImageEdit 工具处理图片，然后通过 `WechatReply` 将编辑后的图片发送回微信。
+
+## 安全机制
+
+### 微信
+
+微信 channel 通过 ClawBot 的扫码认证机制保证安全。只有扫码绑定的微信账号可以发送消息，其他人的消息会被静默丢弃。
+
+凭证（包含 bot_token 和 account_id）保存在本地，权限设为 600（仅所有者可读写）。
+
+### 插件 Channel
+
+Telegram 和 Discord 等插件 channel 维护一个发送者白名单。通过配对流程添加信任的发送者：
+
+1. 向 bot 发送任意消息
+2. bot 回复配对码
+3. 在 CodeBuddy Code 中确认配对码
+4. 发送者 ID 加入白名单
+
+白名单同时控制[权限中继](./channels-reference.md#权限中继)。通过 channel 回复的人可以审批或拒绝工具调用，因此只将信任的发送者加入白名单。
+
+### 其他安全要素
+
+- 仅在 `.mcp.json` 中配置不足以推送消息，还必须在 `--channels` 中指定
+- 组织可以通过 `channelsEnabled` 设置统一管控
+
+## 组织管控
+
+Channel 功能受 `channelsEnabled` 设置控制：
+
+| 计划类型 | 默认行为 |
+|---------|---------|
+| 个人用户 | 可用；用户通过 `--channels` 按会话启用 |
+| 团队/企业 | 默认禁用，管理员需显式启用 |
+
+### 为组织启用 Channel
+
+管理员可以在 `settings.json` 中设置：
+
+```json
+{
+  "channelsEnabled": true
+}
+```
+
+启用后，组织中的用户可以使用 `--channels` 将 channel 服务器接入各自的会话。如果设置被禁用，MCP 服务器仍然连接且工具可用，但 channel 消息不会到达。
+
+## 功能对比
+
+CodeBuddy Code 有多种连接外部系统的功能，各有适用场景：
+
+| 功能 | 作用 | 适用场景 |
+|------|------|---------|
+| 标准 MCP 服务器 | CodeBuddy Code 在任务中查询它；不推送到会话 | 按需读取或查询系统 |
+| Remote Control | 从远程控制本地会话 | 离开桌面时操控进行中的会话 |
+| **Channel** | **将外部事件推送到已运行的本地会话** | **聊天桥、Webhook 接收、告警响应** |
+
+Channel 通过将非 CodeBuddy Code 来源的事件推送到已运行的本地会话来填补空白：
+
+* **聊天桥**：通过微信向 CodeBuddy Code 提问，回答出现在微信中，而实际工作在你的机器上运行，使用你的真实文件
+* **Webhook 接收器**：CI、错误追踪器或部署管线的 Webhook 到达时，CodeBuddy Code 已经打开了你的文件并记住你在调试什么
+
+## 下一步
+
+* [构建自己的 Channel](./channels-reference.md)：为还没有插件的系统创建 channel
+* 使用 `/remote-control` 管理所有远程控制连接

package/dist/web-ui/docs/cn/cli/checkpointing.md

@@ -0,0 +1,51 @@
+# 检查点
+
+## 概述
+
+自动跟踪并回退 CodeBuddy 的编辑，快速恢复不需要的更改。
+
+CodeBuddy Code 在您工作时会自动跟踪 CodeBuddy 对文件的编辑，让您能够快速撤销更改，并在出现问题时回退到之前的状态。
+
+
+## 常见使用场景
+
+检查点在以下情况下特别有用：
+
+- **探索替代方案**：尝试不同的实现方式，而不会丢失起始点
+- **从错误中恢复**：快速撤销引入 bug 或破坏功能的更改
+- **功能迭代**：在知道可以恢复到可用状态的前提下，放心地进行各种尝试
+
+---
+
+## 限制
+
+### Bash 命令的更改不会被跟踪
+
+检查点不会跟踪通过 bash 命令修改的文件。例如，如果 CodeBuddy Code 运行：
+
+```
+rm file.txt
+mv old.txt new.txt
+cp source.txt dest.txt
+```
+
+这些文件修改无法通过回退功能撤销。只有通过 CodeBuddy 的文件编辑工具直接进行的编辑才会被跟踪。
+
+### 外部更改不会被跟踪
+
+检查点只跟踪在当前会话中被编辑过的文件。您在 CodeBuddy Code 之外手动对文件所做的更改，以及来自其他并发会话的编辑，通常不会被捕获，除非它们恰好修改了与当前会话相同的文件。
+
+### 不能替代版本控制
+
+检查点设计用于快速的会话级恢复。对于永久的版本历史和协作：
+
+- 继续使用版本控制（如 Git）来管理提交、分支和长期历史
+- 检查点是版本控制的补充，而非替代品
+- 可以将检查点理解为"本地撤销"，而 Git 是"永久历史"
+
+---
+
+## 另请参阅
+
+- **[交互模式](interactive-mode.md)** - 键盘快捷键和会话控制
+- **[斜杠命令](slash-commands.md)** - 使用 `/rewind` 访问检查点