liuhuayong 7e90ae7e14 fix: add actual files (remove submodule refs)

2026-06-13 13:48:51 +08:00

5.5 KiB

Raw Blame History

Dev-Assistant 集成指南

本文档指导如何将 @dev-assistant/bridge 和 @dev-assistant/web-sdk 集成到你的 Java 或 Node.js 项目。

目录结构

your-project/
├── backend/          # Java/Spring Boot 或 Node.js 后端
│   ├── pom.xml          # 如果 Java
│   └── ...
│
├── frontend/          # React/Vue/Angular 前端
│   ├── package.json
│   └── src/
│       └── main.tsx  # 主应用文件
│
└── Dockerfile
│       └── docker-compose.yml

1. 后端集成

1.1 依赖安装（Java 示例）

编辑 pom.xml，添加依赖：

<dependency>
  <groupId>com.devassistant</groupId>
  <artifactId>dev-assistant-spring-boot-starter</artifactId>
  <version>1.0.0</version>
</dependency>

1.2 配置文件

编辑 application.yml（或 application.properties）：

dev-assistant:
  enabled: true
  bridge-url: http://localhost:9020
  log-dir: logs

1.3 启动服务

# 后端服务会自动注册以下组件：
# - MdcUserFilter - 注入 userId/roles/requestId 到 MDC
# - JsonLogAppender - 输出 JSON 格式日志
# - DevAssistantHealthIndicator - 健康检查 bridge 服务

1.4 验证安装

确保后端有 /api/auth/me 或类似的认证端点：

@GetMapping("/api/auth/me")
public ApiResponse<CurrentUserResponse> me(Authentication authentication) {
  // 返回当前用户信息，包含 roles
  return ApiResponse.success(authenticationService.getCurrentUser(authentication));
}

2. 前端集成

2.1 依赖安装

cd frontend
npm install @dev-assistant/web-sdk

2.2 配置文件

创建 .env.development 文件：

VITE_DEV_ASSISTANT_HTTP=http://localhost:9020
VITE_DEV_ASSISTANT_WS=ws://localhost:9020/copilot

2.3 集成组件

编辑主应用文件（例如 frontend/src/main.tsx）：

import { mountDevAssistant } from '@dev-assistant/web-sdk';
import '@dev-assistant/web-sdk/styles.css';

useEffect(() => {
  mountDevAssistant({
    bridgeHttpUrl: import.meta.env.VITE_DEV_ASSISTANT_HTTP,
    bridgeWsUrl: import.meta.env.VITE_DEV_ASSISTANT_WS,
    roles: ['ROLE_ADMIN'],
    userIdentifier: getCurrentUser()?.username,
    token: getAuthToken(),
  });
}, []);

function getCurrentUser() {
  // 从你的认证状态获取当前用户
  return localStorage.getItem('user');
}

function getAuthToken() {
  // 从你的 JWT 获取 token
  return localStorage.getItem('authToken');
}

2.4 安全建议

不要在客户端硬编码 API Key
JWT Token 通过后端获取，前端不直接处理敏感信息
Role 检查：在前端再次验证用户角色

// 使用前端的角色检查，确保只有管理员可以看到 AI 助手
if (!roles.some(r => r === 'ROLE_ADMIN')) {
  mountDevAssistant.unmount();
  return;
}

3. Docker 部署

3.1 基础架构

┌─────────────┐
│   前端           │
│   └── AI Bridge      │
└─────────────┘

流量路由：

前端 ↔ AI Bridge（WebSocket + HTTP）
AI Bridge ↔ Claude Agent SDK（内部）

配置方式：

Bridge 配置：dev-assistant.yaml
应用配置：环境变量或配置文件

3.2 部署选项

选项 A：独立 Docker 容器

使用提供的 docker-compose.yml 示例。

选项 B：Docker Compose 集成到现有 docker-compose

在你的现有 docker-compose.yml 中添加：

services:
  bridge:
    image: dev-assistant/dev-assistant-bridge:1.0.0
    ports:
      - "9020:9020"
    environment:
      - DEV_ASSISTANT_WORKSPACE_ROOT=.
    volumes:
      - ./backend:./backend/src

3.3 配置说明

详见配置参考文档。

4. 故障排查

4.1 常见问题

问题：连接被拒绝（401/403）

排查：
1. 检查 JWT token 是否有效
2. 检查用户角色是否包含 ROLE_ADMIN
3. 查看后端 /api/auth/me 是否可访问
4. 查看 Bridge 日志：docker logs bridge

问题：工具执行失败

排查：
1. 查看 Bridge 配置：dev-assistant.yaml 中的 workspace.allowWrite 是否包含你的项目路径
2. 检查工具审批设置

4.2 日志位置

Bridge 日志：

docker logs -f dev-assistant-bridge

应用日志：

docker logs -f your-app

5. 高级用法

5.1 自定义场景

在你的 Bridge 配置中添加自定义场景：

project:
  name: my-custom-app
  systemPrompt: "你是一个自定义的应用..."

scenarios:
  my-scenario:
    label: 自定义场景
    requireSelection: false
    systemPrompt: "当用户选择此场景时，使用以下系统提示..."

5.2 多角色支持

如果你的应用有多个角色，可以配置不同角色的可见场景：

project:
  scenarios:
    viewer:
      label: 查看者模式
      systemPrompt: "你是查看者助手，只能回答问题不能修改..."

    editor:
      label: 编辑者模式
      requireSelection: true
      allowWrite: ['docs/**/*.md']

6. 版本兼容性

组件	版本	兼容性说明
Bridge	1.0.0	支持 Java 21+、Node.js 20
Web SDK	1.0.0	支持 React 18+、Vue 3、Next.js 14
Spring Boot Starter	1.0.0	支持 Spring Boot 3.x

5.5 KiB Raw Blame History Unescape Escape