@tencent-ai/codebuddy-code 2.67.0 → 2.68.0

package/dist/web-ui/docs/cn/cli/sdk-demos.md

@@ -0,0 +1,347 @@
+# SDK 示例项目
+
+本文档介绍 CodeBuddy Agent SDK 的官方示例项目，帮助你快速了解 SDK 的各种使用场景。
+
+## 示例仓库
+
+所有示例代码托管在官方仓库：
+
+**仓库地址**：<https://cnb.cool/codebuddy/agent-sdk-demos>
+
+```bash
+git clone https://cnb.cool/codebuddy/agent-sdk-demos.git
+cd agent-sdk-demos
+```
+
+## 示例概览
+
+| 示例 | 语言 | 核心功能 | 适用场景 |
+|------|------|---------|---------|
+| quick-start | TypeScript | 基础 API、消息流、Hooks | SDK 入门 |
+| multi-turn-session | TypeScript | 多轮对话、会话恢复 | 交互式应用 |
+| research-assistant | Python | 多 Agent 协作 | 复杂任务分解 |
+| profile-builder | TypeScript | 网络搜索、文档生成 | 信息收集 |
+| chat-demo | TypeScript | WebSocket、流式响应 | Web 应用 |
+| mail-assistant | TypeScript | MCP 协议、自定义工具 | 业务系统对接 |
+| spreadsheet-assistant | TypeScript | Electron IPC | 桌面应用 |
+
+## 环境准备
+
+### 前置条件
+
+- [Bun](https://bun.sh) 或 Node.js 18+
+- Python 3.10+（Python 示例）
+- 已完成 CodeBuddy CLI 登录认证
+
+### 安装 SDK
+
+::: code-group
+
+```bash [TypeScript]
+npm install @tencent-ai/agent-sdk
+```
+
+```bash [Python]
+pip install codebuddy-agent-sdk
+```
+
+:::
+
+### 认证方式
+
+SDK 支持多种认证方式：
+
+1. **复用 CLI 登录态**：如果已通过 `codebuddy` 命令登录，SDK 自动使用现有凭据
+2. **API Key 认证**：通过环境变量配置
+
+详细的认证配置请参阅 [设置配置 - 认证相关](settings.md#认证相关)
+
+## 基础示例
+
+### quick-start：SDK 入门
+
+演示 `query()` API 的基本用法，包括消息流处理和 Hooks 机制。
+
+```typescript
+import { query } from '@tencent-ai/agent-sdk';
+
+const conversation = query({
+  prompt: '你好！请介绍一下你能做什么。',
+  options: {
+    model: 'claude-4.5',
+    maxTurns: 100,
+    allowedTools: ['Read', 'Write', 'Bash', 'Glob', 'Grep'],
+  },
+});
+
+for await (const message of conversation) {
+  if (message.type === 'assistant') {
+    const text = message.message.content.find(c => c.type === 'text');
+    if (text) console.log(text.text);
+  }
+  if (message.type === 'result') {
+    console.log(`完成，耗时 ${message.duration_ms}ms`);
+  }
+}
+```
+
+**运行示例**：
+
+```bash
+cd quick-start
+npm install
+npx tsx quick-start.ts
+```
+
+### multi-turn-session：多轮对话
+
+演示 Session API 实现多轮对话和会话恢复。
+
+```typescript
+import { unstable_v2_createSession, unstable_v2_resumeSession } from '@tencent-ai/agent-sdk';
+
+// 创建会话
+await using session = unstable_v2_createSession({ model: 'claude-4.5' });
+
+// 第一轮
+await session.send('今年是哪一年？');
+for await (const msg of session.stream()) { /* ... */ }
+
+// 第二轮（保持上下文）
+await session.send('再往后推 10 年是哪一年？');
+for await (const msg of session.stream()) { /* ... */ }
+```
+
+**运行示例**：
+
+```bash
+cd multi-turn-session
+npm install
+npx tsx examples.ts basic        # 基础会话
+npx tsx examples.ts multi-turn   # 多轮对话
+npx tsx examples.ts resume       # 会话恢复
+```
+
+## 进阶示例
+
+### research-assistant：多 Agent 协作
+
+Python 示例，展示如何定义多个专业化子 Agent 协作完成复杂任务。
+
+**工作流程**：
+
+1. **主 Agent** 将研究请求拆分为子任务
+2. **研究员** 使用 WebSearch 搜索信息，保存到 `files/research_notes/`
+3. **数据分析师** 从研究笔记提取数据，生成图表到 `files/charts/`
+4. **报告撰写者** 整合内容，生成 PDF 报告到 `files/reports/`
+
+```python
+from codebuddy_agent_sdk import CodeBuddySDKClient, CodeBuddyAgentOptions, AgentDefinition
+
+agents = {
+    "researcher": AgentDefinition(
+        description="使用网络搜索收集研究信息",
+        tools=["WebSearch", "Write"],
+        model="claude-haiku-4.5"
+    ),
+    "data-analyst": AgentDefinition(
+        description="从研究笔记提取数据并生成图表",
+        tools=["Glob", "Read", "Bash", "Write"],
+        model="claude-haiku-4.5"
+    ),
+    "report-writer": AgentDefinition(
+        description="整合研究和数据生成 PDF 报告",
+        tools=["Skill", "Glob", "Read", "Write", "Bash"],
+        model="claude-haiku-4.5"
+    )
+}
+
+options = CodeBuddyAgentOptions(
+    allowed_tools=["Task"],  # 主 Agent 只能委托任务
+    agents=agents,
+    model="claude-haiku-4.5"
+)
+
+async with CodeBuddySDKClient(options=options) as client:
+    await client.query("研究 2025 年量子计算发展")
+    async for msg in client.receive_response():
+        # 处理消息
+```
+
+**运行示例**：
+
+```bash
+cd research-assistant
+uv sync
+uv run python research_agent/agent.py
+```
+
+### profile-builder：信息收集与文档生成
+
+演示 WebSearch 工具和文档生成能力。
+
+```typescript
+const q = query({
+  prompt: `搜索 "${personName}" 的资料，创建一份专业简历`,
+  options: {
+    allowedTools: ['WebSearch', 'WebFetch', 'Bash', 'Write', 'Read'],
+    systemPrompt: '你是简历撰写专家...',
+  },
+});
+```
+
+**运行示例**：
+
+```bash
+cd profile-builder
+npm install
+npm start "姓名"
+# 输出：agent/custom_scripts/resume.docx
+```
+
+## Web 应用集成
+
+### chat-demo：流式响应架构
+
+演示如何将 SDK 集成到 Web 应用，通过 WebSocket 实现流式响应。
+
+**架构**：
+
+```
+Browser (React) ←─ WebSocket ─→ Express Server ←─ SDK query()
+```
+
+**服务端封装**：
+
+```typescript
+import { query } from "@tencent-ai/agent-sdk";
+
+export class Agent {
+  async sendMessage(content: string) {
+    this.stream = query({
+      prompt: content,
+      options: {
+        maxTurns: 1,
+        allowedTools: ['Bash', 'Read', 'Write', 'WebSearch'],
+      },
+    })[Symbol.asyncIterator]();
+  }
+
+  async *getOutputStream() {
+    while (true) {
+      const { value, done } = await this.stream.next();
+      if (done) break;
+      yield value;
+    }
+  }
+}
+```
+
+**运行示例**：
+
+```bash
+cd chat-demo
+npm install
+npm run dev
+# 后端：http://localhost:3001
+# 前端：http://localhost:5173
+```
+
+### mail-assistant：MCP 工具扩展
+
+演示通过 MCP 协议扩展 Agent 能力，实现邮件系统操作。
+
+```typescript
+const q = query({
+  prompt: '查找本周未读的重要邮件',
+  options: {
+    allowedTools: [
+      'Read', 'Write', 'Bash',
+      'mcp__email__search_inbox',   // MCP 工具
+      'mcp__email__read_emails'
+    ],
+    mcpServers: {
+      "email": customEmailServer
+    },
+  },
+});
+```
+
+**运行示例**：
+
+```bash
+cd mail-assistant
+cp .env.example .env  # 配置 IMAP 凭据
+bun install
+bun run dev
+# 访问 http://localhost:3000
+```
+
+## 桌面应用集成
+
+### spreadsheet-assistant：Electron 集成
+
+演示在 Electron 应用中通过 IPC 集成 SDK。
+
+**主进程**：
+
+```typescript
+import { query } from '@tencent-ai/agent-sdk';
+
+ipcMain.on('agent:query', async (event, data) => {
+  for await (const message of query({ prompt: data.content, options })) {
+    event.reply('agent:response', message);
+  }
+});
+```
+
+**渲染进程**：
+
+```typescript
+window.electron.ipcRenderer.on('agent:response', (message) => {
+  // 更新 UI
+});
+
+window.electron.ipcRenderer.sendMessage('agent:query', { content: '创建销售报表' });
+```
+
+**运行示例**：
+
+```bash
+cd spreadsheet-assistant
+npm install
+npm start
+```
+
+## Hooks 安全控制
+
+所有示例都支持通过 Hooks 实现安全控制：
+
+```typescript
+const q = query({
+  prompt: '...',
+  options: {
+    hooks: {
+      PreToolUse: [{
+        matcher: 'Write|Edit',
+        hooks: [async (input) => {
+          const filePath = input.tool_input.file_path;
+          // 限制写入目录
+          if (!filePath.startsWith('/allowed/path/')) {
+            return { decision: 'block', stopReason: '路径不允许' };
+          }
+          return { continue: true };
+        }]
+      }]
+    }
+  }
+});
+```
+
+## 相关文档
+
+- [SDK 概览](sdk.md) - SDK 完整介绍
+- [TypeScript SDK 参考](sdk-typescript.md) - TypeScript API 详细文档
+- [Python SDK 参考](sdk-python.md) - Python API 详细文档
+- [MCP 集成](mcp.md) - MCP 服务器配置
+- [子 Agent 系统](sub-agents.md) - 多 Agent 协作详解