以 Memos 开源笔记应用为载体，演示如何通过 @tencent-ai/agent-sdk 将 CodeBuddy AI Agent 能力集成到第三方应用。用户可通过自然语言与 AI 助手对话，完成笔记的创建、查询、搜索、更新、删除等操作。

SDK 方案采用 嵌入式 (In-Process) 架构范式，Agent 作为库直接运行在宿主 Node.js 进程内，通过 query() 函数调用实现零延迟的 AI 能力集成。

┌──────────────────────────────────┐
│         用户浏览器 (Memos UI)      │
│                                  │
│   ┌──────────────────────────┐   │
│   │     AIChatPanel 组件      │   │
│   │   (SSE 流式连接 Gateway)  │   │
│   └────────────┬─────────────┘   │
└────────────────┼─────────────────┘
                 │ SSE (text_delta / tool_use / done)
                 ▼
┌──────────────────────────────────┐
│    AI Gateway (Node.js :3333)    │
│                                  │
│  ┌────────┐ ┌────────┐ ┌──────┐ │
│  │认证代理 │ │并发控制 │ │会话  │ │
│  │        │ │(信号量) │ │管理  │ │
│  └────────┘ └────────┘ └──────┘ │
│           │                      │
│           │ query() API 调用     │
│           ▼                      │
│  ┌──────────────────────────┐   │
│  │  @tencent-ai/agent-sdk    │   │
│  │                          │   │
│  │  AsyncGenerator 流式输出  │   │
│  │  原生 Session 管理        │   │
│  │  精细权限控制              │   │
│  └────────────┬─────────────┘   │
└───────────────┼──────────────────┘
                │ curl (由 Agent 自主执行)
                ▼
┌──────────────────────────────────┐
│    Memos 后端 (Go :5230)         │
│    REST API /api/v1/memos        │
└──────────────────────────────────┘

.
├── README.md                        # 本文件 — 项目总览
├── memos/                           # Memos 原始项目（基准代码，用于对比演示）
├── integration-sdk/                 # SDK 嵌入式集成 (In-Process)
│   ├── ai-gateway/src/
│   │   ├── index.ts                 #   服务入口 & SSE 路由
│   │   ├── sdk-agent.ts             #   核心：query() API + 流式处理
│   │   ├── auth-proxy.ts            #   Memos Token 认证代理
│   │   ├── system-prompt.ts         #   Agent 系统提示词
│   │   ├── session-manager.ts       #   会话管理
│   │   ├── semaphore.ts             #   并发控制信号量
│   │   └── config.ts                #   配置项
│   ├── web/src/components/
│   │   └── AIChatPanel.tsx          #   [新增] AI 对话面板组件
│   ├── start.sh / stop.sh           #   一键启停
│   ├── SDK集成方案详细文档.md         #   详细技术文档
│   └── README.md                    #   方案说明

确保本地已安装以下工具：

工具	最低版本	检查命令	说明
Go	1.22+	go version	编译 Memos 后端
Node.js	18+	node --version	运行 AI Gateway
pnpm	—	pnpm --version	前端包管理器
CodeBuddy CLI	—	which codebuddy	SDK 运行时依赖

@tencent-ai/agent-sdk 支持以下 3 种认证方式，任选其一即可：

最简单，适合本地快速验证。在终端执行交互式登录后，SDK 自动复用凭证：

codebuddy login

适用于未登录 CLI 或需要在服务端部署的场景。设置环境变量即可：

export CODEBUDDY_API_KEY="your-api-key"
# 中国版必须同时设置
export CODEBUDDY_INTERNET_ENVIRONMENT=internal

API Key 获取地址：

• 海外版：https://www.codebuddy.ai/profile/keys
• 中国版：https://copilot.tencent.com/profile/
• iOA 版：https://tencent.sso.copilot.tencent.com/profile/keys

也可以在代码中通过 options.env 传递（参见下方 SDK 核心用法）。

适用于购买了 CodeBuddy 旗舰版的企业用户，适合服务端应用和 CI/CD 场景：

1. 在 CodeBuddy 控制台创建应用，获取 Client ID 和 Client Secret
2. 向 Token 端点换取访问令牌：

   curl -X POST https://copilot.tencent.com/oauth2/token \
     -d "grant_type=client_credentials&client_id=<ID>&client_secret=<SECRET>"
   

3. 通过环境变量传入：

   export CODEBUDDY_AUTH_TOKEN="your-oauth-token"
   

cd integration-sdk
chmod +x start.sh stop.sh
./start.sh

启动脚本会自动完成以下步骤（首次启动需要编译，约 3-5 分钟；后续启动秒级）：

步骤	命令	说明
1	pnpm install	安装前端依赖
2	pnpm run release	构建前端（打包到 Go 后端的 static 目录）
3	go build -o memos-bin	编译 Memos Go 后端
4	npm install	安装 AI Gateway 依赖（含 @tencent-ai/agent-sdk）

编译完成后自动启动两个服务：

服务	地址	说明
Memos 后端	http://localhost:5230	笔记应用主界面
AI Gateway	http://localhost:3333	AI Agent 中间层

1. 浏览器访问 http://localhost:5230
2. 首次访问进入注册页面，填写用户名和密码创建账号
3. 注册完成后自动登录进入 Memos 主界面

curl http://localhost:3333/api/ai/status

正常返回：

{
  "status": "running",
  "mode": "sdk",
  "concurrent": 0,
  "maxConcurrency": 5,
  "queued": 0,
  "activeSessions": 0,
  "memosUrl": "http://localhost:5230"
}

方式 A — 通过 UI：在 Memos 界面点击右下角 ✨ 按钮打开 AI 对话面板，输入自然语言即可。

方式 B — 通过 curl 直接调用 API（需要 Memos Access Token）：

# Token 可从浏览器开发者工具 (F12) → Network → 任意 API 请求的 Authorization 头中获取
curl -N -X POST http://localhost:3333/api/ai/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <你的 memos_access_token>" \
  -d '{"message": "帮我记一条笔记：明天下午 3 点开会"}'

返回 SSE 流，会看到逐条推送的 text_delta、tool_use、done 等事件。

./stop.sh

问题	排查方式
Memos 启动失败	查看日志：cat integration-sdk/memos.log
AI Gateway 启动失败	查看日志：cat integration-sdk/ai-gateway.log
Go 版本不兼容	修改 integration-sdk/go.mod 中 go x.x.x 为本地版本
SDK 认证失败	确认已执行 codebuddy login 或设置了 CODEBUDDY_API_KEY 环境变量
端口被占用	检查端口：lsof -i :5230 或 lsof -i :3333
前端构建失败	确认 pnpm 已安装：npm install -g pnpm

接口	方法	说明
/api/ai/chat	POST	核心对话接口，返回 SSE 流（需 Authorization: Bearer <memos_token>）
/api/ai/reset	POST	重置用户会话（开始新对话）
/api/ai/status	GET	查看 Gateway 运行状态（无需认证）

SSE 事件类型：

事件	说明
text_delta	增量文本（逐字推送）
tool_use	Agent 调用工具（如 curl 调用 Memos API）
tool_result	工具执行结果
done	对话完成，返回 sessionId 用于多轮对话
error	错误信息

import { query } from "@tencent-ai/agent-sdk";

const q = query({
  prompt: "查看我最近的笔记",
  options: {
    cwd: "/tmp/sandbox",
    permissionMode: "bypassPermissions",
    systemPrompt: "你是 Memos 智能助手...",
    persistSession: true,
    resume: "previous-session-id",   // 可选：恢复会话
    // 认证配置（API Key 方式，也可通过环境变量设置）
    env: {
      CODEBUDDY_API_KEY: process.env.CODEBUDDY_API_KEY,
      CODEBUDDY_INTERNET_ENVIRONMENT: "internal",  // 中国版必填
    },
  },
});

for await (const message of q) {
  switch (message.type) {
    case "assistant":
      // 处理完整消息（含 tool_use）
      break;
    case "partial_assistant":
      // 处理增量文本（逐字推送）
      break;
    case "result":
      // 对话完成
      break;
  }
}

变量	默认值	说明
CODEBUDDY_API_KEY	—	CodeBuddy API Key（认证方式二）
CODEBUDDY_INTERNET_ENVIRONMENT	—	SDK 环境标识：中国版 internal、iOA 版 ioa、海外版不设置
CODEBUDDY_AUTH_TOKEN	—	OAuth 访问令牌（认证方式三，企业版）
MEMOS_URL	http://localhost:5230	Memos 后端地址
MAX_CONCURRENCY	5	最大并发 Agent 会话数
SESSION_TTL	1800000	会话过期时间 (ms, 默认 30 分钟)
SANDBOX_ROOT	/tmp/memos-ai-sandboxes	Agent 沙箱根目录

在 AI 对话面板中可以直接用自然语言操作：

• "帮我记一条笔记：明天下午 3 点开会"
• "查看我最近的笔记"
• "搜索关于 Python 的笔记"
• "分析下我这个月的笔记内容"
• "删掉那条关于开会的笔记"

文档	说明
SDK 集成方案详细文档	SDK 模式的架构设计、源码解读、踩坑记录

层级	技术
前端	React + TypeScript + Vite
AI Gateway	Node.js + Express + TypeScript
后端	Go (Memos 原生)
数据库	SQLite (Memos 默认)
AI Agent	CodeBuddy Agent SDK (@tencent-ai/agent-sdk)

本演示项目基于 Memos（MIT License）进行修改。