# https://github.com/dingdawg/dingdawg-agent-1 项目说明书

生成时间：2026-05-27 17:20:51 UTC

## 目录

- [项目介绍](#page-intro)
- [快速开始](#page-quickstart)
- [系统架构](#page-architecture)
- [数据流与状态管理](#page-data-flow)
- [七大创新特性](#page-innovations)
- [安全模型](#page-security)
- [代理宪法配置指南](#page-constitution)
- [后端API系统](#page-backend-api)
- [AI模型集成](#page-ai-integration)
- [前端组件与界面](#page-frontend)

<a id='page-intro'></a>

## 项目介绍

### 相关页面

相关主题：[系统架构](#page-architecture), [七大创新特性](#page-innovations), [快速开始](#page-quickstart)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [gateway/frontend/src/app/privacy/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/privacy/page.tsx)
- [gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx)
- [gateway/frontend/src/app/dashboard/ceo/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/dashboard/ceo/page.tsx)
- [gateway/isg_agent/api/routes/public.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/api/routes/public.py)
- [dashboard/index.html](https://github.com/dingdawg/dingdawg-agent-1/blob/main/dashboard/index.html)
- [gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)
- [gateway/frontend/src/app/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/integrations/page.tsx)
- [gateway/frontend/src/app/explore/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/explore/page.tsx)
- [gateway/frontend/src/app/onboarding/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/onboarding/page.tsx)
- [gateway/frontend/scripts/generate-screenshots.js](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/scripts/generate-screenshots.js)
- [gateway/frontend/src/app/terms/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/terms/page.tsx)
- [gateway/frontend/src/app/hospitality/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/hospitality/page.tsx)
</details>

# 项目介绍

## 概述

DingDawg Agent-1 是一个通用人工智能代理平台，代号为 "ISG Agent 1"，旨在为企业和个人提供多渠道智能客服解决方案。该平台支持通过聊天组件（Chat Widget）、Discord、Telegram、WebSocket 等多种渠道部署 AI 代理，实现统一的客户交互体验。资料来源：[dashboard/index.html:1-10]()

### 核心定位

DingDawg 定位为 **"Universal AI Agent Platform"**，口号为 "Yeah! We've Got An Agent For That!"，强调其快速部署和行业适配能力。平台提供 28+ 行业模板，涵盖医疗、法律、房地产、餐饮等多个垂直领域，用户可在数分钟内完成代理配置，而非传统的数周开发周期。资料来源：[gateway/frontend/scripts/generate-screenshots.js:1-50]()

## 技术架构

### 整体架构图

```mermaid
graph TB
    subgraph 前端层["前端层 (Next.js)"]
        A[用户界面] --> B[Onboarding 引导流程]
        A --> C[Dashboard 管理面板]
        A --> D[Explore 代理市场]
        A --> E[Integrations 集成管理]
    end
    
    subgraph 网关层["网关层 (Gateway)"]
        F[Public API] --> G[Agent Card 代理卡片]
        F --> H[Agent Discovery 代理发现]
    end
    
    subgraph 后端服务层["后端服务层 (ISG Agent)"]
        I[Public Routes] --> J[LLM Providers]
        K[Stripe 支付] --> L[Webhook 处理]
    end
    
    subgraph 渠道层["多渠道接入"]
        M[Chat Widget]
        N[Discord]
        O[Telegram]
        P[WebSocket]
    end
    
    A --> F
    C --> I
    M --> F
    N --> F
    O --> F
    P --> F
```

### 目录结构

| 目录/路径 | 说明 | 资料来源 |
|-----------|------|----------|
| `gateway/frontend/` | Next.js 前端应用，包含所有用户界面组件 | [gateway/frontend/src/app/privacy/page.tsx:1]() |
| `gateway/isg_agent/` | 后端 Python 服务，提供 API 和代理逻辑 | [gateway/isg_agent/api/routes/public.py:1]() |
| `dashboard/` | 独立监控和管理仪表板 | [dashboard/index.html:1-10]() |

## 核心功能模块

### 1. 用户引导流程 (Onboarding)

用户引导流程是 DingDawg 平台的核心用户体验入口，通过分步骤向导帮助用户快速创建和配置 AI 代理。

```mermaid
graph LR
    A[选择模板] --> B[配置营业时间]
    B --> C[设置 @handle]
    C --> D[选择套餐等级]
    D --> E[激活代理]
```

#### 模板选择

平台提供 28+ 行业模板，每个模板包含预设的系统提示词、对话流程和行业知识。用户可以选择热门模板快速启动，也可以从空白模板开始自定义配置。模板卡片包含图标（emoji）、名称、是否标记为"热门"等元数据。资料来源：[gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx:1-80]()

#### 营业时间配置

代理支持配置工作时段，系统会显示周一至周日的 7 天时间选择器，每个时段包含开始时间和结束时间两个输入框。用户可以启用"仅在营业时间响应"开关，启用后系统仅在设定时段内回复客户，非营业时间将返回预设提示。资料来源：[gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx:80-150]()

| 配置项 | 类型 | 说明 |
|--------|------|------|
| `hoursEnabled` | boolean | 是否启用营业时间限制 |
| `hours[day].open` | string (HH:mm) | 每日开始时间 |
| `hours[day].close` | string (HH:mm) | 每日结束时间 |

#### @handle 唯一标识

每个代理拥有唯一的 `@handle`，作为公开身份标识符。该标识符在创建后不可更改，具有永久性。用户输入 handle 时，系统会实时检查可用性状态（可用/已占用），并在用户确认选择后锁定。资料来源：[gateway/frontend/src/app/onboarding/page.tsx:1-100]()

### 2. 代理市场 (Explore)

代理市场是一个公开浏览和发现平台，用户可以搜索和查看所有公开可用的 AI 代理。

```mermaid
graph TB
    A[Explore 页面] --> B{用户登录状态}
    B -->|已登录| C[AppShell 完整界面]
    B -->|未登录| D[公开浏览界面]
    C --> E[搜索代理]
    D --> E
    E --> F[按行业分类过滤]
    F --> G[查看代理详情]
```

代理数据通过 `/api/v1/public/agents` 端点获取，支持分页和筛选。代理列表项包含名称、描述、问候语、行业分类等字段。资料来源：[gateway/frontend/src/app/explore/page.tsx:1-100]()

| API 端点 | 方法 | 说明 |
|----------|------|------|
| `/api/v1/public/agents` | GET | 获取公开代理列表 |
| `/api/v1/public/agents?limit=100` | GET | 获取前 100 个代理 |
| `/api/v1/public/agents/{handle}/card` | GET | 获取单个代理的卡片信息 |

### 3. 管理仪表板 (Dashboard)

#### CEO 仪表板

CEO 仪表板提供商业智能概览，包含以下核心指标区域：

- **产品下载统计**：显示每日下载量、版本号和下载排行榜
- **市场健康度**：支付链接状态、系统负载（CPU/RAM）仪表盘
- **客户活动流**：实时用户活动动态列表
- **外展追踪器**：邮件回复率、Demo 申请数、销售转化数

资料来源：[gateway/frontend/src/app/dashboard/ceo/page.tsx:1-150]()

#### 系统管理面板

系统管理面板位于 `/admin/system`，提供平台运维所需的集成自检功能。

```mermaid
graph LR
    A[运行自检] --> B[数据库连接]
    A --> C[表结构验证]
    A --> D[LLM 提供商]
    A --> E[Stripe 支付]
    A --> F[路由检查]
    A --> G[安全层验证]
```

自检功能验证以下组件的可用性和状态：

| 组件 | 检查内容 |
|------|----------|
| 数据库 | 连接状态、表存在性 |
| LLM 提供商 | API 密钥有效性、响应延迟 |
| Stripe | 支付通道状态 |
| 路由 | API 端点可达性 |
| 安全层 | 认证、授权、速率限制 |

资料来源：[gateway/frontend/src/app/admin/system/page.tsx:1-100]()

### 4. 集成管理 (Integrations)

DingDawg 支持与多个第三方服务集成，当前版本包含以下可用集成：

| 集成名称 | 类别 | 功能 |
|----------|------|------|
| Google | 身份认证 | OAuth 登录 |
| SendGrid | 邮件 | 事务性邮件发送 |
| Twilio | 通信 | SMS/语音 |
| VAPI | 语音 | 语音代理 |

"即将推出"区域显示待开发的集成功能，用户可通过配置模态框进行连接、断开、测试和 Webhook 管理。资料来源：[gateway/frontend/src/app/integrations/page.tsx:1-100]()

### 5. 营销代理 (Marketing)

营销管理页面提供邮件活动追踪功能，包括：

- 活动列表与状态展示
- 部署 @dingdawg-marketing 代理 CTA
- 发送外展邮件功能

资料来源：[gateway/frontend/src/app/admin/marketing/page.tsx:1-100]()

### 6. 行业垂直页面

平台为特定行业提供专属落地页，以餐饮 hospitality 行业为例：

- 展示三个套餐等级：Free ($0)、Pro ($49.99)、Enterprise ($199.99)
- 强调"50 免费操作、60 秒配置、无需信用卡"等卖点
- 渐变金色边框 CTA 组件

资料来源：[gateway/frontend/src/app/hospitality/page.tsx:1-100]()

## 公开 API 设计

### 代理卡片 (Agent Card)

代理卡片是 DingDawg 的公开元数据格式，用于在外部平台展示代理信息。

```mermaid
graph TD
    A[GET /api/v1/public/agents/{handle}/card] --> B[生成 HTML 卡片]
    B --> C[Meta 标签优化]
    B --> D[Open Graph 预览]
    B --> E[Twitter Card]
```

卡片 HTML 包含：

- 标准 meta 标签（title、description）
- Open Graph 属性（og:title、og:description、og:type、og:url）
- Twitter Card 标签（twitter:card、twitter:title、twitter:description）
- Google Fonts 预连接优化

资料来源：[gateway/isg_agent/api/routes/public.py:1-50]()

## 安全与合规

### 数据隐私

平台收集以下用户数据用于服务提供：

| 数据类别 | 收集内容 |
|----------|----------|
| 账户数据 | 邮箱、密码哈希、认证令牌 |
| 代理数据 | @handle、名称、行业、模板选择 |
| 对话日志 | 消息内容、关联账户、保留策略 |
| 使用分析 | 页面访问、功能使用、API 调用统计 |
| 支付信息 | 信用卡详情（由 Stripe 处理） |

资料来源：[gateway/frontend/src/app/privacy/page.tsx:1-50]()

### 服务条款

使用条款明确以下关键约束：

- 禁止构建与 DingDawg 核心功能实质性竞争的产品的
- 自动请求必须遵守速率限制
- 不得干扰平台稳定性或可用性
- ISG 可撤销违规账户的 API 访问权限

AI 生成内容的责任由用户承担，平台不保证输出的准确性、完整性或适用性，AI 输出不构成专业建议。资料来源：[gateway/frontend/src/app/terms/page.tsx:1-100]()

### 错误处理

AdminErrorBoundary 组件为管理界面提供优雅的错误降级：

```mermaid
graph TB
    A[渲染组件] --> B{发生错误?}
    B -->|否| C[正常显示]
    B -->|是| D[显示错误边界]
    D --> E[红色错误消息框]
    D --> F[堆栈跟踪折叠面板]
    D --> G[重载按钮]
```

资料来源：[gateway/frontend/src/components/admin/AdminErrorBoundary.tsx:1-80]()

## 快速开始

### 环境要求

- Node.js 18+
- Python 3.10+
- npm 或 yarn

### 安装步骤

```bash
# 克隆仓库
git clone https://github.com/dingdawg/dingdawg-agent-1.git
cd dingdawg-agent-1

# 安装前端依赖
cd gateway/frontend
npm install

# 启动前端开发服务器
npm run dev
```

### 配置环境变量

在 `gateway/frontend/` 目录下创建 `.env.local` 文件：

| 变量名 | 说明 | 示例 |
|--------|------|------|
| `NEXT_PUBLIC_API_URL` | API 基础 URL | `http://localhost:8000` |
| `STRIPE_PUBLIC_KEY` | Stripe 公钥 | `pk_live_...` |
| `GOOGLE_CLIENT_ID` | Google OAuth 客户端 ID | `xxx.apps.googleusercontent.com` |

## 常见问题

### 代理响应延迟

**问题**：代理响应时间过长
**可能原因**：

- LLM 提供商 API 限速
- Webhook 回调失败率过高
- 系统负载过重

**排查步骤**：

1. 检查 Admin System 页面的自检结果
2. 查看 Webhook 成功率指标
3. 监控 CPU/RAM 负载

### @Handle 不可用

**问题**：选择的 handle 显示已占用
**说明**：@handle 采用先到先得原则，一旦创建即永久锁定，无法释放或转让。

### 集成连接失败

**问题**：第三方服务连接失败
**排查步骤**：

1. 确认 API 密钥配置正确
2. 检查 Webhook URL 可达性
3. 在 Integrations 页面运行测试功能

## See Also

- [架构文档](https://github.com/dingdawg/dingdawg-agent-1/blob/main/ARCHITECTURE.md)
- [API 参考文档](https://github.com/dingdawg/dingdawg-agent-1/blob/main/docs/api.md)
- [部署指南](https://github.com/dingdawg/dingdawg-agent-1/blob/main/docs/deployment.md)
- [贡献指南](https://github.com/dingdawg/dingdawg-agent-1/blob/main/CONTRIBUTING.md)

---

<a id='page-quickstart'></a>

## 快速开始

### 相关页面

相关主题：[后端API系统](#page-backend-api)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [gateway/frontend/src/app/onboarding/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/onboarding/page.tsx)
- [gateway/frontend/src/app/admin/deploy/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/deploy/page.tsx)
- [gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx)
- [gateway/frontend/src/app/agents/[handle]/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/agents/%5Bhandle%5D/page.tsx)
- [gateway/frontend/src/components/dashboard/DashboardHeader.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/dashboard/DashboardHeader.tsx)
- [gateway/frontend/src/app/admin/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/integrations/page.tsx)
</details>

# 快速开始

DingDawg Agent 是一个通用 AI Agent 平台，专为小型企业设计，提供预约预订、发票发送、支付收款、客户管理和对话处理等功能。本文档将帮助您快速了解平台的完整上手流程，从账户创建到第一个 AI Agent 部署。

## 前提条件

在开始之前，请确保满足以下基本要求：

| 要求项 | 说明 |
|--------|------|
| Node.js | 推荐 Node.js 18.x 或更高版本 |
| 包管理器 | npm 或 yarn |
| 浏览器 | 现代浏览器（Chrome、Firefox、Safari、Edge） |
| 网络 | 稳定的互联网连接，用于调用 LLM API |

资料来源：[gateway/frontend/src/app/onboarding/page.tsx:1-50]()

## 整体流程概览

新用户从注册到成功部署 AI Agent 需要经历以下阶段：

```mermaid
graph TD
    A[用户访问平台] --> B[注册账户]
    B --> C[填写 Agent 基本信息]
    C --> D[验证 @handle 可用性]
    D --> E[选择行业模板]
    E --> F[配置业务时间]
    F --> G[选择套餐等级]
    G --> H{选择免费套餐?}
    H -->|是| I[直接激活 Agent]
    H -->|否| J[完成支付]
    J --> I
    I --> K[Agent 部署完成]
    K --> L[访问管理后台]
    L --> M[配置集成服务]
```

资料来源：[gateway/frontend/src/app/onboarding/page.tsx:100-200]()

## 第一步：创建 Agent

### 访问入职引导页面

首次登录后，系统会自动引导您进入入职引导流程。在入职引导页面中，您需要完成 Agent 基础信息的配置：

- **Agent 名称**：为您的 AI Agent 起一个易于识别的名称
- **@handle**：唯一的公共标识符，一旦确定不可更改
- **行业部门**：选择 Agent 所属的行业分类

资料来源：[gateway/frontend/src/app/onboarding/page.tsx:200-280]()

### Handle 验证机制

系统会实时验证您输入的 @handle 是否可用：

```typescript
// Handle 验证状态类型
type HandleStatus = 
  | 'idle'      // 未验证
  | 'checking'  // 验证中
  | 'available' // 可用
  | 'taken'     // 已被占用
  | 'invalid';  // 格式无效
```

| 状态 | 颜色标识 | 用户操作 |
|------|----------|----------|
| `idle` | 灰色 | 等待用户输入 |
| `checking` | 加载动画 | 验证中，请稍候 |
| `available` | 绿色 | 可使用 |
| `taken` | 红色 | 需要更换其他名称 |
| `invalid` | 红色 | 格式不符合要求 |

资料来源：[gateway/frontend/src/app/onboarding/page.tsx:280-350]()

## 第二步：选择行业模板

DingDawg Agent 提供了丰富的行业模板，帮助您快速启动符合业务需求的 Agent：

| 模板分类 | 说明 | 图标 |
|----------|------|------|
| 通用客服 | 适用于各类企业的基础客服场景 | 💬 |
| 预约管理 | 适用于需要预约管理的服务行业 | 📅 |
| 电商助手 | 适用于电商平台的商品咨询和订单处理 | 🛒 |
| 健康咨询 | 适用于医疗健康领域的初步咨询 | 🏥 |
| 法律顾问 | 适用于法律服务的初步问答 | ⚖️ |

每个模板都预置了相应的系统提示词、技能配置和工作流程，您可以在部署后根据实际需求进行调整。

资料来源：[gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx:50-120]()

## 第三步：配置业务时间

如果您的业务有固定的营业时间，可以开启业务时间强制模式：

```typescript
// 业务时间配置结构
interface BusinessHours {
  mon: { open: string; close: string };  // 周一
  tue: { open: string; close: string };  // 周二
  wed: { open: string; close: string };  // 周三
  thu: { open: string; close: string };  // 周四
  fri: { open: string; close: string };  // 周五
  sat: { open: string; close: string };  // 周六
  sun: { open: string; close: string };  // 周日
}
```

开启业务时间强制后，Agent 只会在您设定的营业时间内响应客户咨询，非营业时间将自动切换到预设的非工作时间处理逻辑。

资料来源：[gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx:120-200]()

## 第四步：选择套餐

DingDawg Agent 提供多种套餐等级以满足不同规模企业的需求：

| 套餐名称 | 价格 | 功能限制 | 适用场景 |
|----------|------|----------|----------|
| Free | 免费 | 基本对话功能 | 个人试用、小型测试 |
| Pro | 付费 | 高级技能、优先支持 | 中小企业正式使用 |
| Enterprise | 定制 | 完整功能、专属集成 | 大型企业、复杂需求 |

在激活页面，您可以查看当前套餐的详细信息，并根据需要切换到其他套餐等级。

资料来源：[gateway/frontend/src/app/onboarding/page.tsx:350-420]()

## 第五步：Agent 激活与部署

完成上述配置后，点击"激活 Agent"按钮即可完成部署：

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant A as Agent 服务
    participant DB as 数据库

    U->>F: 点击"激活 Agent"
    F->>A: 发送激活请求
    A->>DB: 保存 Agent 配置
    DB-->>A: 确认保存
    A-->>F: 激活成功响应
    F->>U: 显示成功页面
    U->>F: 访问 Agent 主页
    F->>A: 获取 Agent 信息
    A-->>F: 返回公开卡片信息
    F-->>U: 渲染 Agent 公开页面
```

资料来源：[gateway/frontend/src/app/onboarding/page.tsx:420-500]()

激活成功后，系统会为您的 Agent 生成一个公开的访问页面，格式为：`/agents/{handle}`。您可以将此链接分享给客户或嵌入到您的网站中。

资料来源：[gateway/frontend/src/app/agents/[handle]/page.tsx:50-100]()

## Agent 公开页面结构

每个已激活的 Agent 都有一个对应的公开展示页面，包含以下核心元素：

| 元素 | 说明 |
|------|------|
| Agent 头像与名称 | 使用您配置的名称和颜色 |
| 行业标识 | 显示 Agent 所属的行业分类 |
| 功能描述 | 展示 Agent 的主要能力 |
| 对话入口 | 用户可以直接开始与 Agent 对话 |
| 开发者信息 | 可选显示的技术配置信息 |

资料来源：[gateway/frontend/src/app/agents/[handle]/page.tsx:100-180]()

## 管理后台概览

Agent 激活后，您可以访问管理后台进行日常运营管理：

```mermaid
graph LR
    A[管理后台] --> B[仪表盘]
    A --> C[Agent 部署]
    A --> D[集成管理]
    A --> E[系统设置]
    A --> F[数据分析]

    B --> B1[统计数据]
    B --> B2[集成状态]
    B --> B3[最近活动]

    C --> C1[模板选择]
    C --> C2[快速部署]
    C --> C3[部署历史]

    D --> D1[已连接服务]
    D --> D2[Webhook 配置]
    D --> D3[健康检查]

    E --> E1[Agent 配置]
    E --> E2[安全设置]
    E --> E3[自我修复]
```

### 仪表盘

管理后台的仪表盘提供了 Agent 运营的核心指标：

- **对话数量**：显示已处理的会话总数
- **活跃任务数**：当前正在进行的任务数
- **活跃技能数**：已启用的技能数量
- **集成状态**：各第三方服务的连接状态

资料来源：[gateway/frontend/src/components/dashboard/DashboardHeader.tsx:1-80]()

### 快速部署

如果您需要部署额外的 Agent 或重新配置现有 Agent，可以使用快速部署功能：

- 选择已有的行业模板作为基础
- 自定义 Agent 的基本配置
- 一键部署到生产环境
- 跟踪部署历史记录

资料来源：[gateway/frontend/src/app/admin/deploy/page.tsx:50-120]()

## 集成配置

DingDawg Agent 支持与多种第三方服务集成，扩展 Agent 的能力边界：

### 支持的集成类型

| 集成类别 | 服务示例 | 功能说明 |
|----------|----------|----------|
| 通信 | Twilio、Vapi | 电话和短信功能 |
| 邮件 | SendGrid | 邮件发送和接收 |
| 日历 | Google Calendar | 预约日程同步 |
| 支付 | Stripe | 在线支付收款 |
| 消息 | Discord、Telegram | 多渠道消息接入 |

### 集成健康检查

系统会自动监控各集成的运行状态，并在管理后台显示健康状态：

```typescript
// 集成健康检查结果结构
interface IntegrationHealth {
  name: string;
  status: 'connected' | 'disconnected' | 'error' | 'unknown';
  last_webhook: string | null;
  connected_agents: number;
  webhook_success_rate: number | null;
  last_test_result: 'pass' | 'fail' | null;
  last_test_response_ms: number | null;
}
```

| 状态值 | 含义 | 颜色标识 |
|--------|------|----------|
| `connected` | 已连接且正常工作 | 绿色 |
| `disconnected` | 已断开连接 | 灰色 |
| `error` | 连接错误 | 红色 |
| `unknown` | 状态未知 | 黄色 |

资料来源：[gateway/frontend/src/app/admin/integrations/page.tsx:80-150]()

## 常见问题排查

### Handle 不可用

如果您在注册时遇到 @handle 已被占用的情况：
1. 尝试添加数字或下划线变体
2. 使用您的企业名称拼音或缩写
3. 联系支持团队协助处理

### 激活失败

如果 Agent 激活过程出现错误：
1. 检查网络连接是否稳定
2. 确认所有必填信息已填写完整
3. 查看系统页面的错误提示信息
4. 如问题持续存在，请联系技术支持

### 集成连接问题

第三方服务集成失败时：
1. 确认 API 密钥配置正确
2. 检查 Webhook URL 是否正确设置
3. 查看集成服务的配额限制
4. 使用管理后台的"测试集成"功能进行诊断

资料来源：[gateway/frontend/src/app/admin/integrations/page.tsx:150-200]()

## 下一步

完成快速开始后，建议您进一步了解以下内容：

- **技能配置**：学习如何为 Agent 添加和配置特定技能
- **API 参考**：了解如何通过 API 与 Agent 进行程序化交互
- **高级配置**：探索安全设置、自我修复机制等高级功能
- **模板开发**：学习如何创建自定义的行业模板

## 相关链接

- [入职引导流程](./onboarding-guide.md)
- [Agent 管理后台](./admin-dashboard.md)
- [集成配置指南](./integrations.md)
- [API 参考文档](./api-reference.md)
- [隐私政策](./privacy.md)

---

<a id='page-architecture'></a>

## 系统架构

### 相关页面

相关主题：[项目介绍](#page-intro), [数据流与状态管理](#page-data-flow), [后端API系统](#page-backend-api)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ARCHITECTURE.md](https://github.com/dingdawg/dingdawg-agent-1/blob/main/ARCHITECTURE.md)
- [gateway/isg_agent/app.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/app.py)
- [gateway/isg_agent/api/app.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/api/app.py)
- [gateway/frontend/src/app/layout.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/layout.tsx)
- [gateway/isg_agent/config.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/config.py)
- [gateway/isg_agent/schemas/agents.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/schemas/agents.py)
- [gateway/isg_agent/api/routes/integrations/__init__.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/api/routes/integrations/__init__.py)
- [gateway/frontend/src/app/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/integrations/page.tsx)
- [dashboard/index.html](https://github.com/dingdawg/dingdawg-agent-1/blob/main/dashboard/index.html)
- [gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)

</details>

# 系统架构

本文档详细描述 DingDawg Agent 1（dingdawg-agent-1）项目的系统架构，涵盖前端、后端、API 设计、数据库模型、集成系统以及安全机制等核心组件。

## 1. 架构概述

DingDawg Agent 1 是一个 Universal AI Agent Platform（通用人工智能代理平台），旨在为用户提供创建、部署和管理 AI 代理的能力。该平台采用现代化的微服务架构，将前端用户界面与后端 API 服务分离，同时通过统一的网关层进行请求路由和安全控制。

```mermaid
graph TB
    subgraph 前端层["前端层 (React/Next.js)"]
        FE[前端应用]
        ADMIN[管理后台]
        DASHBOARD[监控仪表盘]
    end
    
    subgraph 网关层["网关层 (ISG Agent Gateway)"]
        GW[FastAPI 网关]
        AUTH[认证中间件]
        CORS[CORS 配置]
    end
    
    subgraph 后端服务["后端服务层"]
        API[API 路由]
        INTEGRATIONS[集成模块]
        AGENTS[Agent 管理]
    end
    
    subgraph 数据层["数据层"]
        DB[(数据库)]
        CONFIG[配置管理]
    end
    
    FE --> GW
    ADMIN --> GW
    DASHBOARD --> GW
    GW --> AUTH
    AUTH --> API
    API --> INTEGRATIONS
    API --> AGENTS
    AGENTS --> DB
    INTEGRATIONS --> DB
    CONFIG -.-> GW
```

资料来源：[gateway/isg_agent/app.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/app.py)

## 2. 技术栈概览

DingDawg Agent 1 项目的技术选型遵循现代化全栈开发标准，前端采用 React 生态，后端采用 Python FastAPI 框架。

| 层次 | 技术选型 | 说明 |
|------|---------|------|
| 前端框架 | Next.js / React | 用户界面和单页应用 |
| 后端框架 | FastAPI | 高性能 Python Web 框架 |
| 编程语言 | TypeScript (前端) / Python (后端) | 强类型保障与灵活性 |
| 数据库 | 关系型数据库 | 通过 SQLAlchemy ORM 访问 |
| 配置管理 | Pydantic Settings | 环境变量驱动的配置系统 |
| 状态管理 | Zustand | 前端轻量级状态管理 |
| API 文档 | OpenAPI / Swagger | 自动生成的 API 文档 |

资料来源：[gateway/frontend/src/app/layout.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/layout.tsx)、[gateway/isg_agent/config.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/config.py)

## 3. 前端架构

### 3.1 应用结构

前端应用位于 `gateway/frontend` 目录下，采用 Next.js App Router 架构。核心页面包括用户引导、代理探索、集成管理、管理后台等模块。

```mermaid
graph LR
    subgraph 页面路由
        ONBOARDING[/onboarding]
        EXPLORE[/explore]
        INTEGRATIONS[/integrations]
        ADMIN_SYSTEM[/admin/system]
        ADMIN_MARKETING[/admin/marketing]
        CEO[/dashboard/ceo]
    end
    
    subgraph 共享组件
        APPSHELL[AppShell]
        AUTHSORE[useAuthStore]
    end
    
    ONBOARDING --> AUTHSORE
    EXPLORE --> APPSHELL
    INTEGRATIONS --> APPSHELL
    ADMIN_SYSTEM --> APPSHELL
    ADMIN_MARKETING --> APPSHELL
    CEO --> APPSHELL
```

资料来源：[gateway/frontend/src/app/onboarding/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/onboarding/page.tsx)、[gateway/frontend/src/app/explore/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/explore/page.tsx)

### 3.2 核心页面模块

| 模块路径 | 功能描述 | 依赖组件 |
|---------|---------|---------|
| `/onboarding` | 用户引导流程，创建第一个 AI 代理 | OnboardingChatStream、StepHandle |
| `/explore` | 代理市场浏览，发现公开代理 | AgentCard、CategoryFilter |
| `/integrations` | 第三方服务集成配置 | IntegrationCard、IntegrationConfigModal |
| `/admin/system` | 系统状态监控与自愈 | SelfTest、ErrorRow、StatusDot |
| `/admin/marketing` | 营销活动管理与分析 | CampaignTable |
| `/dashboard/ceo` | CEO 仪表盘，关键指标展示 | ProductGrid、PaymentLinks |

资料来源：[gateway/frontend/src/app/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/integrations/page.tsx)、[gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)

### 3.3 认证与状态管理

前端使用 Zustand 进行全局状态管理，核心状态存储包括：

- **AuthStore**：用户认证状态，包括 `isAuthenticated` 属性判断用户登录状态
- **代理配置状态**：在引导流程中管理代理创建状态

```typescript
// 典型认证检查模式
const { isAuthenticated } = useAuthStore();

if (isAuthenticated) {
  return (
    <AppShell>
      <ExploreContent />
    </AppShell>
  );
}

return <ExploreContent />;
```

资料来源：[gateway/frontend/src/app/explore/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/explore/page.tsx)

## 4. 后端架构

### 4.1 应用入口

后端应用位于 `gateway/isg_agent` 目录，主入口文件为 `app.py`。应用使用 FastAPI 框架构建，提供 RESTful API 接口。

```python
# Pydantic Settings 配置示例
model_config = {
    "env_prefix": "ISG_AGENT_",        # 环境变量前缀
    "env_nested_delimiter": "__",       # 嵌套分隔符
    "populate_by_name": True,           # 允许按名称填充
    "extra": "ignore",                  # 忽略额外字段
    "env_file": ".env",                 # 环境文件
    "env_file_encoding": "utf-8",       # 文件编码
}
```

资料来源：[gateway/isg_agent/config.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/config.py)

### 4.2 配置管理系统

配置系统采用 Pydantic Settings，支持环境变量注入和验证：

| 配置项 | 环境变量 | 说明 |
|-------|---------|------|
| `log_level` | `ISG_AGENT_LOG_LEVEL` | 日志级别（DEBUG/INFO/WARNING/ERROR/CRITICAL） |
| `secret_key` | `ISG_AGENT_SECRET_KEY` | 加密密钥 |
| `allowed_origins` | `ISG_AGENT_ALLOWED_ORIGINS` | CORS 允许的来源（逗号分隔） |

日志级别验证器确保只有有效值被接受：

```python
@field_validator("log_level")
@classmethod
def _normalise_log_level(cls, v: str) -> str:
    """标准化日志级别为大写"""
    normalised = v.upper().strip()
    valid_levels = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
    if normalised not in valid_levels:
        raise ValueError(
            f"Invalid log_level {v!r}; must be one of {sorted(valid_levels)}"
        )
    return normalised
```

资料来源：[gateway/isg_agent/config.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/config.py)

### 4.3 API 路由结构

API 路由采用模块化设计，主要路由模块包括：

```mermaid
graph TB
    API_APP[API App] --> PUBLIC_ROUTES[public.py]
    API_APP --> INTEGRATIONS_ROUTES[integrations/]
    API_APP --> AGENTS_ROUTES[agents/]
    API_APP --> ADMIN_ROUTES[admin/]
    
    INTEGRATIONS_ROUTES --> DDMAIN[DDMain Bridge Router]
    INTEGRATIONS_ROUTES --> EMAIL[email]
    INTEGRATIONS_ROUTES --> SMS[sms]
    INTEGRATIONS_ROUTES --> VAPI[vapi]
    INTEGRATIONS_ROUTES --> GOOGLE_CALENDAR[google_calendar]
    INTEGRATIONS_ROUTES --> STATUS[status]
    INTEGRATIONS_ROUTES --> MANAGEMENT[management]
```

集成路由模块结构：

```python
"""Per-agent integration sub-modules.

This package replaces the old ``integrations.py`` flat file.
The DDMain bridge router (previously the sole content of 
``integrations.py``) is re-exported here:

    from isg_agent.api.routes.integrations import router as integrations_router
"""
from isg_agent.api.routes.integrations._ddmain import router

__all__ = ["router"]
```

资料来源：[gateway/isg_agent/api/routes/integrations/__init__.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/api/routes/integrations/__init__.py)

## 5. 数据模型

### 5.1 Agent 实体

Agent（代理）是平台的核心实体，包含以下关键属性：

| 字段 | 类型 | 说明 |
|-----|------|------|
| `id` | str | 唯一 UUID 标识符 |
| `user_id` | str | 所有者用户 ID |
| `handle` | str | 唯一 @handle 公共标识符 |
| `name` | str | 显示名称 |
| `agent_type` | str | 类型：personal 或 business |
| `industry_type` | Optional[str] | 行业分类 |
| `template_id` | Optional[str] | 创建时使用的模板 UUID |
| `status` | str | 生命周期状态：active/suspended/archived |
| `subscription_tier` | str | 计费层级：free/starter/pro/enterprise |
| `config_json` | Optional[str] | 代理配置的 JSON 字符串 |
| `branding_json` | Optional[str] | 品牌/主题设置的 JSON 字符串 |
| `created_at` | str | ISO 8601 UTC 创建时间戳 |
| `updated_at` | str | ISO 8601 UTC 最后更新时间戳 |

```python
class AgentResponse(BaseModel):
    """Response representing a single agent."""
    
    id: str                          # 唯一 UUID
    user_id: str                     # 所有者用户 ID
    handle: str                      # 唯一 @handle
    name: str                        # 显示名称
    agent_type: str                  # "personal" 或 "business"
    industry_type: Optional[str] = None
    template_id: Optional[str] = None
    config_json: Optional[str] = None
    branding_json: Optional[str] = None
    status: str                     # active/suspended/archived
    subscription_tier: str          # free/starter/pro/enterprise
    created_at: str                  # ISO 8601 UTC
    updated_at: str                  # ISO 8601 UTC
```

资料来源：[gateway/isg_agent/schemas/agents.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/schemas/agents.py)

### 5.2 订阅层级

平台支持四级订阅体系：

| 层级 | 标识 | 典型用途 |
|-----|------|---------|
| Free | `free` | 个人试用、小规模使用 |
| Starter | `starter` | 小团队入门 |
| Pro | `pro` | 专业用户、商业应用 |
| Enterprise | `enterprise` | 大型企业定制需求 |

资料来源：[gateway/frontend/src/app/onboarding/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/onboarding/page.tsx)

## 6. 集成系统

### 6.1 集成模块架构

DingDawg Agent 1 支持多种第三方服务集成，采用模块化架构设计：

```mermaid
graph LR
    USER[用户请求] --> INTEGRATION[集成配置]
    
    subgraph 集成类型
        EMAIL[Email<br/>SendGrid]
        SMS[SMS<br/>Twilio]
        VOICE[Voice<br/>VAPI]
        CALENDAR[Google Calendar]
        WEBHOOK[Webhook]
    end
    
    INTEGRATION --> EMAIL
    INTEGRATION --> SMS
    INTEGRATION --> VOICE
    INTEGRATION --> CALENDAR
    INTEGRATION --> WEBHOOK
```

### 6.2 VAPI 语音集成

VAPI 集成提供语音代理能力，支持多种语音模型：

| 语音模型 | 说明 |
|---------|------|
| Browser TTS | 浏览器内置语音合成 |
| vapi-xxx | VAPI 平台语音模型 |

配置参数包括：
- `Vapi API Key`：VAPI 平台密钥
- `Voice Model`：语音模型选择
- `Status`：连接状态
- `last_webhook`：最后接收的 Webhook 时间戳

```typescript
interface VapiConfig {
  api_key?: string;
  voice_model?: "Browser TTS" | "vapi-xxx";
  connected?: boolean;
  voice_model?: string;
}
```

资料来源：[gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx)

### 6.3 Webhook 管理

集成系统支持自定义 Webhook，允许用户：

- 添加新的 Webhook 端点
- 删除现有 Webhook
- 测试集成连接
- 查看最后 Webhook 接收时间

```typescript
interface Webhook {
  id: string;
  url: string;
  events: string[];
  created_at: string;
  last_triggered?: string;
}
```

资料来源：[gateway/frontend/src/app/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/integrations/page.tsx)

## 7. 监控与自愈系统

### 7.1 系统状态监控

管理后台提供全面的系统状态监控功能，包括：

| 监控类别 | 监控项 |
|---------|-------|
| 组件状态 | 数据库、表、LLM 提供商、Stripe、路由 |
| 安全层 | 安全组件状态指示 |
| 电路断路器 | 服务熔断状态 |
| 自动恢复 | 自动修复事件记录 |

```mermaid
graph TD
    SUBTEST[Self-Test 开始] --> DBCheck{数据库检查}
    DBCheck -->|成功| TablesCheck{表检查}
    DBCheck -->|失败| DBFail[标记失败]
    
    TablesCheck -->|成功| LLMCheck{LLM 提供商}
    TablesCheck -->|失败| TableFail[标记失败]
    
    LLMCheck -->|成功| StripeCheck{Stripe}
    LLMCheck -->|失败| LLMFail[标记失败]
    
    StripeCheck -->|成功| RouteCheck{路由检查}
    StripeCheck -->|失败| StripeFail[标记失败]
    
    RouteCheck -->|成功| SecurityCheck{安全层}
    RouteCheck -->|失败| RouteFail[标记失败]
    
    SecurityCheck -->|成功| AllPass[全部通过]
    SecurityCheck -->|失败| SecurityFail[标记失败]
```

资料来源：[gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)

### 7.2 自愈机制

系统具备自动恢复能力，记录自动修复事件：

```typescript
interface SelfHealingEvent {
  issue: string;      // 问题描述
  action: string;    // 执行的操作
  timestamp: string; // ISO 8601 时间戳
  auto_recovered?: SelfHealingEvent[];
}
```

自愈功能包括：
- 电路断路器状态追踪
- 自动恢复事件记录
- 实时错误日志展示
- 错误详情展开/折叠查看

资料来源：[gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)

## 8. 引导流程架构

### 8.1 用户引导步骤

新用户引导流程包含多个步骤，每步聚焦特定配置：

```mermaid
graph LR
    START[开始] --> STEP1[1. 基础信息]
    STEP1 --> STEP2[2. 行业选择]
    STEP2 --> STEP3[3. 模板选择]
    STEP3 --> STEP4[4. @Handle 设置]
    STEP4 --> STEP5[5. 激活配置]
    STEP5 --> COMPLETE[完成]
```

### 8.2 引导状态管理

```typescript
interface WizardState {
  step: number;
  agentName: string;
  handle: string;
  sector: Sector | null;
  templateId: string | null;
  hoursEnabled: boolean;
  hours: BusinessHours;
  tier: TierId | null;
}
```

业务时间配置支持按星期设置开放时间：

```typescript
type DayOfWeek = "mon" | "tue" | "wed" |thu" | "fri" | "sat" | "sun";

interface BusinessHours {
  [key: DayOfWeek]: {
    open: string;  // HH:mm 格式
    close: string; // HH:mm 格式
  };
}
```

资料来源：[gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx)、[gateway/frontend/src/app/onboarding/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/onboarding/page.tsx)

### 8.3 @Handle 策略

@Handle 是代理的唯一公共标识符，具有以下特性：

| 特性 | 说明 |
|-----|------|
| 唯一性 | 每个 @Handle 在平台上唯一，不可重复认领 |
| 永久性 | 一旦认领，不可更改、转让或出售 |
| 所有权 | 用户不得出售、租赁或转让 @Handle |

资料来源：[gateway/frontend/src/app/terms/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/terms/page.tsx)

## 9. 监控仪表盘

### 9.1 CEO 仪表盘

独立的监控仪表盘位于 `dashboard/` 目录，提供关键业务指标展示：

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta name="description" content="ISG Agent 1 — Monitoring and Management Dashboard" />
    <title>ISG Agent 1 Dashboard</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
```

资料来源：[dashboard/index.html](https://github.com/dingdawg/dingdawg-agent-1/blob/main/dashboard/index.html)

### 9.2 产品与支付管理

CEO 仪表盘展示核心产品指标：

| 指标 | 说明 |
|-----|------|
| `downloads` | 每日下载量 |
| `version` | 当前版本号 |
| `status` | 产品状态（live/beta） |
| `slug` | NPM 包标识符 |
| Payment Links | 支付链接管理 |

资料来源：[gateway/frontend/src/app/dashboard/ceo/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/dashboard/ceo/page.tsx)

## 10. 安全机制

### 10.1 认证与授权

系统采用多层认证机制：

- **CORS 配置**：支持跨域请求控制，通过 `allowed_origins` 配置允许的来源
- **环境变量密钥**：`secret_key` 通过环境变量注入，支持自动生成
- **会话管理**：使用 AuthStore 管理用户认证状态

```python
# CORS 配置示例
allowed_origins: str = ""  # 逗号分隔的来源列表

def allowed_origins_list(self) -> list[str]:
    """解析 allowed_origins 为列表"""
    return [o.strip() for o in self.allowed_origins.split(",") if o.strip()]
```

### 10.2 企业级安全特性

平台强调的企业级安全包括：

- **Prompt Armor**：提示词防护
- **Extraction Defense**：数据提取防御
- **4-Layer Auth**：四层认证体系

> "Enterprise Security: Prompt armor, extraction defense, 4-layer auth. Your data is safe."

资料来源：[gateway/frontend/scripts/generate-screenshots.js](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/scripts/generate-screenshots.js)

### 10.3 隐私与数据保护

系统收集和处理以下用户数据：

| 数据类别 | 收集内容 | 用途 |
|---------|---------|------|
| 账户信息 | @handle、代理名称、行业、模板选择 | 账户管理 |
| 代理配置 | 系统提示词定制 | 个性化服务 |
| 对话日志 | 消息记录 | 历史记录、服务改进 |
| 使用分析 | 访问页面、功能使用、API 调用统计 | 产品优化 |
| 设备信息 | 设备类型、浏览器类型、操作系统（匿名化） | 兼容性优化 |

资料来源：[gateway/frontend/src/app/privacy/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/privacy/page.tsx)

## 11. 公共 API

### 11.1 公开代理卡片

系统提供公开的代理信息访问接口，支持 Open Graph 元数据：

```html
<!DOCTYPE html>
<html>
  <head>
    <title>{name} — DingDawg Agent</title>
    <meta name="description" content="{description or greeting}">
    <meta property="og:title" content="{name} — DingDawg Agent">
    <meta property="og:description" content="{description or greeting}">
    <meta property="og:type" content="website">
    <meta property="og:url" content="{base_url}/api/v1/public/agents/{handle}/card">
    <meta name="twitter:card" content="summary">
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
  </head>
</html>
```

资料来源：[gateway/isg_agent/api/routes/public.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/api/routes/public.py)

### 11.2 API 端点

| 端点 | 方法 | 说明 |
|-----|------|------|
| `/api/v1/public/agents` | GET | 获取公开代理列表 |
| `/api/v1/public/agents/{handle}/card` | GET | 获取代理公开卡片 |

## 12. 常见故障与排查

### 12.1 集成连接失败

当集成连接失败时，系统会显示：

1. 连接状态变为断开
2. 提示用户检查 API Key 配置
3. 提供重新配置入口

### 12.2 引导流程中断

引导流程中断的常见原因：

| 问题 | 原因 | 解决方案 |
|-----|------|---------|
| @Handle 不可用 | 已被认领 | 选择其他 Handle |
| 模板加载失败 | 网络问题 | 刷新页面重试 |
| 激活超时 | 服务繁忙 | 稍后重试 |

### 12.3 自测试失败

自测试模块会按顺序检查：

1. 数据库连接
2. 必需表是否存在
3. LLM 提供商配置
4. Stripe 支付集成
5. API 路由注册
6. 安全中间件状态

资料来源：[gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)

## 13. See Also

- [快速开始指南](./快速开始指南.md) - 了解如何快速部署第一个代理
- [API 参考文档](./API-Reference.md) - 完整的 API 端点文档
- [集成配置](./集成配置.md) - 第三方服务集成详细配置
- [部署指南](./部署指南.md) - 生产环境部署说明
- [安全白皮书](./安全白皮书.md) - 平台安全机制详解

---

<a id='page-data-flow'></a>

## 数据流与状态管理

### 相关页面

相关主题：[系统架构](#page-architecture), [后端API系统](#page-backend-api), [前端组件与界面](#page-frontend)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [gateway/isg_agent/config.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/config.py)
- [gateway/isg_agent/db/schema.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/db/schema.py)
- [gateway/isg_agent/db/queries.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/db/queries.py)
- [gateway/isg_agent/db/engine.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/db/engine.py)
- [gateway/isg_agent/templates/template_registry.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/templates/template_registry.py)
- [gateway/frontend/src/store/sessionStore.ts](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/store/sessionStore.ts)
- [gateway/frontend/src/store/chatStore.ts](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/store/chatStore.ts)
- [gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)
</details>

# 数据流与状态管理

本文档详细介绍 DingDawg Agent 平台中的数据流架构和状态管理机制，涵盖后端数据库层、业务逻辑层以及前端状态管理商店的核心实现。

---

## 1. 概述

DingDawg Agent 是一个 AI 智能体平台，为小型企业提供预约预订、发票发送、收款处理、客户管理以及客户对话等功能。系统的数据流与状态管理跨越前后端多个层级，确保数据一致性、实时性和可靠性。

核心架构采用以下设计模式：

- **后端**：基于 Python 的 FastAPI 后端，使用 SQLite 数据库存储持久化数据
- **前端**：React + TypeScript 前端，使用 Zustand 进行状态管理
- **通信**：RESTful API 配合环境变量配置的前缀约定

资料来源：[gateway/isg_agent/config.py:34-42]()

---

## 2. 后端数据层架构

### 2.1 数据库引擎

DingDawg 后端使用 SQLite 作为主数据库，通过 `aiosqlite` 实现异步数据库操作。数据库引擎模块负责连接管理、事务控制和连接池化。

```mermaid
graph TD
    A[FastAPI 应用] --> B[数据库引擎 engine.py]
    B --> C[aiosqlite 连接]
    C --> D[SQLite 数据库文件]
    
    B --> E[连接池管理]
    E --> F[自动关闭机制]
    E --> G[上下文管理器]
```

数据库配置通过环境变量 `ISG_AGENT_` 前缀进行注入，支持嵌套配置：

| 配置项 | 环境变量 | 说明 |
|--------|----------|------|
| 数据库路径 | `ISG_AGENT_DB_PATH` | SQLite 数据库文件路径 |
| 日志级别 | `ISG_AGENT_LOG_LEVEL` | DEBUG/INFO/WARNING/ERROR/CRITICAL |
| 密钥 | `ISG_AGENT_SECRET_KEY` | 会话加密密钥 |
| 允许来源 | `ISG_AGENT_ALLOWED_ORIGINS` | CORS 允许的域名列表 |

资料来源：[gateway/isg_agent/config.py:34-42]()

### 2.2 数据模式（Schema）

数据库模式定义了所有核心实体的结构，包括用户、智能体、会话、消息等关键表。

**TemplateRecord** 数据结构用于描述智能体模板：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | str | UUID 唯一标识符 |
| `name` | str | 模板名称（如 "Restaurant"） |
| `agent_type` | str | "personal" 或 "business" |
| `industry_type` | Optional[str] | 行业标识（如 "restaurant"） |
| `system_prompt_template` | str | Python str.format_map 兼容的提示词模板 |
| `flow_json` | str | 对话流程图 JSON |
| `capabilities` | str | 智能体能力 JSON 数组 |
| `created_at` | str | ISO 8601 UTC 时间戳 |

资料来源：[gateway/isg_agent/templates/template_registry.py:44-71]()

### 2.3 查询层

数据库查询模块封装了所有数据库操作，提供类型安全的查询接口。查询层采用以下设计原则：

1. **异步优先**：所有数据库操作均为异步，使用 `aiosqlite`
2. **连接管理**：使用上下文管理器自动管理数据库连接
3. **错误处理**：统一的异常处理和日志记录

```python
# 典型查询流程
async with get_db_connection() as db:
    row = await db.execute(query, params)
    return TemplateRecord.from_row(row)
```

---

## 3. 前端状态管理

### 3.1 状态管理架构概览

前端采用 Zustand 进行状态管理，这是一种轻量级、无样板代码的状态管理解决方案。

```mermaid
graph LR
    A[React 组件] --> B[Zustand Store]
    B --> C[sessionStore]
    B --> D[chatStore]
    
    C --> E[用户会话状态]
    D --> F[对话历史状态]
    
    B --> G[中间件]
    G --> H[持久化]
    G --> I[日志/调试]
```

### 3.2 会话商店（SessionStore）

`sessionStore` 管理用户的认证状态和应用级配置。核心职责包括：

| 状态字段 | 类型 | 说明 |
|----------|------|------|
| `isAuthenticated` | boolean | 用户登录状态 |
| `user` | User object | 当前用户对象 |
| `token` | string | 认证令牌 |

**关键方法**：

- `login(credentials)` - 用户登录流程
- `logout()` - 清除会话状态
- `checkAuth()` - 验证当前令牌有效性

### 3.3 对话商店（ChatStore）

`chatStore` 管理与 AI 智能体的对话状态，包括：

| 状态字段 | 类型 | 说明 |
|----------|------|------|
| `messages` | Message[] | 对话消息列表 |
| `activeAgent` | Agent object | 当前对话的智能体 |
| `isStreaming` | boolean | 流式响应状态 |
| `errors` | Error[] | 错误消息列表 |

**对话流程状态机**：

```mermaid
stateDiagram-v2
    [*] --> Idle: 初始状态
    Idle --> Typing: 用户输入
    Typing --> Streaming: 发送消息
    Streaming --> Idle: 响应完成
    Streaming --> Error: 请求失败
    Error --> Idle: 错误处理完成
    Idle --> Typing: 新消息
```

---

## 4. 数据流模式

### 4.1 API 请求-响应流

前端通过 RESTful API 与后端通信，数据流向如下：

```mermaid
sequenceDiagram
    participant FE as 前端组件
    participant Store as Zustand Store
    participant API as API 客户端
    participant BE as FastAPI 后端
    participant DB as SQLite
    
    FE->>Store: 用户操作触发 action
    Store->>API: 调用 API 函数
    API->>BE: HTTP 请求
    BE->>DB: 数据库查询
    DB-->>BE: 查询结果
    BE-->>API: JSON 响应
    API-->>Store: 更新状态
    Store-->>FE: 触发重新渲染
```

### 4.2 公开 API 端点

公开 API 路由处理面向公众的智能体信息展示：

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/public/agents` | GET | 获取智能体列表 |
| `/api/v1/public/agents/{handle}/card` | GET | 获取智能体名片 HTML |

公开端点返回的数据结构：

```typescript
interface PublicAgent {
  handle: string;        // 智能体句柄
  name: string;          // 智能体名称
  description?: string;  // 描述/问候语
  industry?: string;     // 所属行业
  primary_color?: string;// 主色调
}
```

资料来源：[gateway/frontend/src/app/explore/page.tsx:67-72]()

### 4.3 管理后台数据流

管理后台 (`/admin/system`) 展示系统组件状态，包括：

| 组件类别 | 监控内容 |
|----------|----------|
| 数据库 | SQLite 连接状态、查询延迟 |
| LLM 提供商 | 各 AI 提供商配置状态 |
| 安全性 | 安全层状态指示器 |
| 自愈机制 | 断路器状态、自动恢复事件 |

```mermaid
graph TD
    A[Admin System Page] --> B[获取系统状态 API]
    B --> C{数据源检查}
    
    C -->|数据库| D[SQLite 健康检查]
    C -->|LLM| E[提供商连接测试]
    C -->|安全| F[安全层验证]
    
    D --> G[状态展示组件]
    E --> G
    F --> G
    
    G --> H[StatusDot 组件]
    H --> I[彩色状态指示器]
```

状态颜色映射：

| 状态值 | 颜色 | 含义 |
|--------|------|------|
| `active` | 绿色 | 正常运行 |
| `unavailable` | 红色 | 不可用 |
| `warning` | 黄色 | 警告状态 |

资料来源：[gateway/frontend/src/app/admin/system/page.tsx:45-60]()

---

## 5. 配置与验证

### 5.1 环境变量配置

系统使用 Pydantic Settings 进行配置管理，支持以下验证机制：

```python
@field_validator("log_level")
@classmethod
def _normalise_log_level(cls, v: str) -> str:
    """标准化日志级别为大写"""
    normalised = v.upper().strip()
    valid_levels = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
    if normalised not in valid_levels:
        raise ValueError(
            f"Invalid log_level {v!r}; must be one of {sorted(valid_levels)}"
        )
    return normalised
```

### 5.2 密钥管理

`secret_key` 配置项采用以下策略：

- **生产环境**：拒绝弱密钥，强制使用强随机密钥
- **开发环境**：自动生成安全的随机密钥
- **存储**：通过环境变量注入，不硬编码

### 5.3 CORS 配置

跨域资源共享通过 `allowed_origins_list` 属性管理：

```python
@property
def allowed_origins_list(self) -> list[str]:
    """解析逗号分隔的来源字符串"""
    return [o.strip() for o in self.allowed_origins.split(",") if o.strip()]
```

配置示例：

```bash
ISG_AGENT_ALLOWED_ORIGINS="http://localhost:3002, https://app.example.com"
```

资料来源：[gateway/isg_agent/config.py:12-26]()

---

## 6. 集成状态管理

### 6.1 集成配置模态框

集成配置组件 (`IntegrationConfigModal`) 管理第三方服务连接状态：

```mermaid
graph LR
    A[集成列表] --> B[配置模态框]
    B --> C[输入凭证]
    B --> D[连接测试]
    B --> E[保存配置]
    
    C --> F[API Key 输入]
    D --> G{测试结果}
    G -->|成功| H[更新状态]
    G -->|失败| I[显示错误]
```

### 6.2 Webhook 管理

系统支持 webhook 事件订阅，配置状态包括：

| 字段 | 说明 |
|------|------|
| `name` | Webhook 名称 |
| `url` | 回调 URL |
| `events` | 订阅事件类型 |
| `last_webhook` | 最后触发时间 |

资料来源：[gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx:28-40]()

---

## 7. 常见失败模式与排查

### 7.1 数据库连接问题

| 症状 | 可能原因 | 解决方案 |
|------|----------|----------|
| 查询延迟过高 | SQLite 文件锁 | 检查并发写入 |
| 连接超时 | 文件路径错误 | 验证 `ISG_AGENT_DB_PATH` |

### 7.2 前端状态不同步

| 症状 | 可能原因 | 解决方案 |
|------|----------|----------|
| 页面数据不更新 | Store 未正确触发更新 | 检查 Zustand action 返回 |
| 登录状态丢失 | Token 过期 | 实现自动刷新机制 |

### 7.3 API 请求失败

| 症状 | 可能原因 | 解决方案 |
|------|----------|----------|
| CORS 错误 | 来源未在白名单 | 检查 `allowed_origins` 配置 |
| 401 未授权 | Token 无效或过期 | 重新登录获取新 Token |

---

## 8. 安全考虑

### 8.1 数据隔离

- 每个智能体拥有独立的配置空间
- 用户数据通过认证层隔离
- 敏感配置通过环境变量管理，不存储于代码库

### 8.2 密钥轮换

生产环境应定期轮换 `secret_key`，通过以下流程：

1. 生成新密钥
2. 更新环境变量
3. 重启服务
4. 验证所有会话正常

### 8.3 输入验证

所有用户输入通过 Pydantic 模型进行验证：

```python
model_config = {
    "env_prefix": "ISG_AGENT_",
    "env_nested_delimiter": "__",
    "populate_by_name": True,
    "extra": "ignore",  # 忽略未知字段
    "env_file": ".env",
}
```

---

## 9. See Also

- [配置管理](./配置管理) - 详细的环境变量配置说明
- [API 参考](./API参考) - 所有 REST API 端点文档
- [集成指南](./集成指南) - 第三方服务集成说明
- [部署文档](./部署文档) - 生产环境部署指南

---

<a id='page-innovations'></a>

## 七大创新特性

### 相关页面

相关主题：[代理宪法配置指南](#page-constitution), [安全模型](#page-security)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [gateway/frontend/src/app/dashboard/ceo/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/dashboard/ceo/page.tsx)
- [gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)
- [gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx)
- [gateway/frontend/src/app/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/integrations/page.tsx)
- [gateway/frontend/src/app/pricing/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/pricing/page.tsx)
- [gateway/frontend/src/components/admin/AdminErrorBoundary.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/admin/AdminErrorBoundary.tsx)
</details>

# 七大创新特性

DingDawg Agent 是一个功能丰富的 AI Agent 构建与部署平台，其核心创新体现在七个关键领域。本页详细介绍这些创新特性，帮助开发者和技术决策者理解平台的技术优势与设计理念。

---

## 1. 智能引导式入职系统

### 概述

DingDawg Agent 采用 **流式对话式入职向导**，通过模拟实时聊天的交互方式，引导用户完成 Agent 的创建与配置。这种设计参考了 Slack、Notion、Figma 等顶级产品的成功经验，将传统的表单式配置转化为更具参与感的对话体验。

### 核心组件

| 组件 | 文件位置 | 功能描述 |
|------|----------|----------|
| `OnboardingChatStream.tsx` | `gateway/frontend/src/components/onboarding/` | 流式聊天消息渲染与状态管理 |
| `onboarding/page.tsx` | `gateway/frontend/src/app/` | 入职流程主页面与步骤控制 |
| `StepHandle` | `gateway/frontend/src/components/onboarding/` | @handle 唯一性校验与实时状态反馈 |

### 工作流程

```mermaid
graph TD
    A[用户进入入职向导] --> B[选择行业领域]
    B --> C{是否选择模板}
    C -->|有模板| D[应用模板配置]
    C -->|无模板| E[创建空白 Agent]
    D --> F[设置 Agent 名称与 @handle]
    E --> F
    F --> G[校验 handle 唯一性]
    G -->|可用| H[显示成功脉冲动画]
    G -->|不可用| I[提示重新输入]
    H --> J[选择订阅层级]
    J --> K[激活 Agent]
```

### 关键技术细节

在 `OnboardingChatStream.tsx` 中，系统实现了 **回复流式渲染** 效果，用户可以看到 AI 逐步"输入"回复的动态过程：

```typescript
// 流式回复渲染示例
const streamedReplies = wizard.replies.map((reply, idx) => (
  <span
    key={idx}
    className="px-1.5 py-0.5 rounded text-sm"
    style={{ background: "rgba(246,180,0,0.08)" }}
  >
    {reply}
  </span>
));
```

### 商业时段配置

系统支持精细化的 **营业时间配置**，允许 Agent 在非营业时段自动切换响应模式：

```typescript
// 工作时间配置数据结构
const days = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"] as const;
const range = wizard.hours[day]; // { open: "09:00", close: "18:00" }
```

资料来源：[gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx:52-68]()

---

## 2. 自愈式系统架构

### 概述

平台内置 **自愈式系统架构**，通过断路器模式（Circuit Breaker）和自动恢复机制，确保系统在面对外部服务故障时能够保持稳定运行。这一特性特别适用于依赖多个第三方服务的复杂场景。

### 架构组件

| 组件名称 | 功能 | 状态指示 |
|----------|------|----------|
| 数据库连接 | PostgreSQL 主数据库健康检查 | `healthy` / `degraded` / `down` |
| LLM 提供商 | OpenAI/Anthropic 等模型服务 | 独立的断路器监控 |
| Stripe 集成 | 支付与订阅管理 | 独立断路器监控 |
| 路由服务 | Agent 消息路由 | 独立断路器监控 |
| 安全层 | 认证与授权验证 | 多层状态显示 |

### 断路器状态机

```mermaid
stateDiagram-v2
    [*] --> Closed: 初始状态
    Closed --> Open: 失败率超过阈值
    Open --> HalfOpen: 冷却时间结束
    HalfOpen --> Closed: 健康检查通过
    HalfOpen --> Open: 健康检查失败
    Open --> [*]: 手动重置
```

### 自动恢复事件

系统记录所有自动恢复操作，便于运维人员审计和分析：

```typescript
interface RecoveryEvent {
  issue: string;        // 问题描述
  action: string;       // 执行的操作
  timestamp: string;    // 恢复时间戳
}

// UI 展示恢复历史
<div className="bg-[#080f18] rounded-lg px-3 py-2">
  <p className="text-xs text-emerald-400 font-medium">{rec.issue}</p>
  <p className="text-xs text-gray-400 mt-0.5">{rec.action}</p>
</div>
```

### 自测试机制

管理员可以手动触发 **集成自测试**，验证以下组件的健康状态：

1. 数据库连接与表结构
2. LLM 提供商可用性
3. Stripe 支付服务
4. 路由配置正确性
5. 安全层完整性

```typescript
// 自测试执行函数
async function handleSelfTest() {
  setSelfTestRunning(true);
  try {
    const results = await post("/api/admin/self-test");
    setSelfHealing(results);
  } finally {
    setSelfTestRunning(false);
  }
}
```

资料来源：[gateway/frontend/src/app/admin/system/page.tsx:1-150]()

---

## 3. 统一集成管理平台

### 概述

DingDawg Agent 提供 **统一的集成管理平台**，支持多种第三方服务的连接、配置与状态监控。集成系统采用模块化设计，便于扩展新的服务提供商。

### 支持的集成类型

| 类别 | 集成名称 | 功能描述 | 状态 |
|------|----------|----------|------|
| 通信 | Twilio | SMS/WhatsApp 消息发送 | 可配置 |
| 语音 | Vapi | AI 语音通话服务 | 可配置 |
| 邮件 | SendGrid | 批量邮件发送 | 可配置 |
| 日历 | Google Calendar | 日程同步 | 即将推出 |
| CRM | HubSpot | 客户关系管理 | 即将推出 |
| 分析 | Google Analytics | 流量分析 | 即将推出 |

### Webhook 管理

集成平台提供完整的 **Webhook 配置与管理** 功能：

```typescript
interface Webhook {
  id: string;
  url: string;
  events: string[];      // 触发事件列表
  created_at: string;
  last_triggered?: string;
  success_rate?: number; // 成功率百分比
}
```

### 连接状态监控

```mermaid
graph LR
    A[Agent] -->|发送消息| B{连接检查}
    B -->|正常| C[第三方服务]
    B -->|失败| D[显示红色指示]
    D --> E[显示上次成功时间]
    E --> F[显示响应时间]
```

### 速率限制显示

系统实时显示 Webhook 的 **成功率统计**：

```typescript
// 成功率条形图组件
function RateBar({ rate }: { rate: number }) {
  const color = rate > 90 ? "bg-emerald-400" 
               : rate > 70 ? "bg-amber-400" 
               : "bg-red-400";
  return (
    <div className="w-full h-1.5 bg-gray-800 rounded-full overflow-hidden">
      <div className={cn("h-full rounded-full", color)} 
           style={{ width: `${rate}%` }} />
    </div>
  );
}
```

资料来源：[gateway/frontend/src/app/integrations/page.tsx:1-80]()

---

## 4. CEO 战略仪表盘

### 概述

平台为高层管理者提供 **CEO 战略仪表盘**，整合市场数据、用户活动、收入指标和运营健康度，提供一目了然的业务全景视图。

### 仪表盘模块

| 模块 | 数据指标 | 更新频率 |
|------|----------|----------|
| 市场健康度 | npm 下载量、版本分布 | 实时 |
| 支付链接 | Stripe 支付状态 | 实时 |
| 用户活动 | 最新用户动态时间线 | 实时 |
| 外展追踪 | 邮件发送/响应/演示/销售漏斗 | 实时 |
| 系统负载 | CPU/内存使用率 | 实时 |

### 用户活动时间线

```mermaid
graph TD
    A[新用户注册] --> B[创建第一个 Agent]
    B --> C[配置集成]
    C --> D[首次对话]
    D --> E[分享 public agent card]
    E --> F[订阅升级]
```

### 外展追踪漏斗

CEO 仪表盘包含 **完整的外展追踪系统**，用于监控营销活动效果：

```typescript
const metrics = [
  { label: '发送邮件', val: emailsSent },
  { label: '回复数', val: 0 },
  { label: '演示请求', val: 0 },
  { label: '成交', val: 0 },
];

// 进度条可视化
<div className="w-full h-2 bg-gray-800 rounded-full overflow-hidden">
  <div 
    className="h-full bg-blue-400 rounded-full transition-all duration-500"
    style={{ width: `${(emailsSent / 10) * 100}%` }}
  />
</div>
```

### 产品展示卡片

仪表盘展示所有已发布产品的 **npm 下载统计**，包含版本分布和状态指示：

```typescript
interface Product {
  slug: string;       // 包名称
  version: string;     // 当前版本
  downloads: number;  // 日下载量
  status: 'live' | 'beta' | 'deprecated';
}
```

资料来源：[gateway/frontend/src/app/dashboard/ceo/page.tsx:1-200]()

---

## 5. 分层订阅定价体系

### 概述

DingDawg Agent 采用 **多层级订阅模式**，为不同规模和使用场景的用户提供灵活的选择。定价页面清晰展示各层级的功能差异和价格信息。

### 定价层级

| 层级 | 价格 | 计费周期 | 目标用户 | 特色功能 |
|------|------|----------|----------|----------|
| Free | $0 | 永久 | 个人开发者 | 基础 Agent 创建 |
| Pro | $29 | 月付/年付 | 小型团队 | 高级集成、优先支持 |
| Enterprise | 自定义 | 定制 | 大型企业 | 私有部署、专属 SLA |

### 价格展示组件

```typescript
interface Tier {
  id: string;
  name: string;
  price: number | null;  // null 表示自定义价格
  period: string;        // "month" | "year" | "custom"
  actions: string;       // 操作次数描述
  features: string[];     // 功能列表
  highlight: boolean;    // 是否高亮显示
  cta: string;           // CTA 按钮文本
  ctaHref: string;       // CTA 链接
}
```

### 定价卡片布局

```mermaid
graph TD
    A[用户访问 /pricing] --> B{当前登录状态}
    B -->|已登录| C[显示用户当前层级]
    B -->|未登录| D[显示公开定价]
    C --> E[高亮当前层级卡片]
    D --> F[显示所有层级对比]
    E --> G[CTA: 管理订阅]
    F --> H[CTA: 选择层级]
```

### 14 天退款保证

所有付费层级均提供 **14 天无理由退款保证**，并在页面底部明确说明：

```typescript
<p className="text-center text-xs text-[var(--color-muted)] mt-10">
  All plans include a 14-day money-back guarantee.
  <Link href="/billing" className="underline hover:text-[var(--foreground)]">
    Manage your plan
  </Link> anytime in your account.
</p>
```

资料来源：[gateway/frontend/src/app/pricing/page.tsx:1-100]()

---

## 6. Agent 公共名片系统

### 概述

每个 DingDawg Agent 都有一个 **公共名片页面**，可通过唯一的 `@handle` 访问。名片包含 Agent 的名称、描述、行业分类和直接对话入口。

### 公共 Agent API

系统提供 RESTful API 供第三方应用查询 Agent 信息：

```
GET /api/v1/public/agents
GET /api/v1/public/agents/{handle}
GET /api/v1/public/agents/{handle}/card
```

### 名片页面生成

`public.py` 中的 `/api/v1/public/agents/{handle}/card` 端点生成 **静态 HTML 名片页面**：

```python
# Open Graph 元标签优化社交分享
<meta property="og:title" content="{name} — DingDawg Agent">
<meta property="og:description" content="{description or greeting}">
<meta property="og:type" content="website">

# Twitter Card 支持
<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="{name} — DingDawg Agent">
```

### 名片页面样式

名片采用渐变背景设计，品牌颜色动态应用：

```css
body {
    background: linear-gradient(
        135deg, 
        {color}22 0%, 
        #f8f9fa 50%, 
        {color}11 100%
    );
    min-height: 100vh;
    display: flex;
    align-items: center;
    justify-content: center;
}
```

### 探索页面

平台提供 **探索页面**（`/explore`），用户可以浏览和搜索所有公开的 Agent：

```typescript
interface PublicAgent {
  handle: string;
  name: string;
  description?: string;
  greeting?: string;
  industry?: string;
  category: Category;
}

// 按行业分类
function industryToCategory(industry: string): Category {
  // 映射逻辑
}
```

资料来源：[gateway/isg_agent/api/routes/public.py:1-50]()
资料来源：[gateway/frontend/src/app/explore/page.tsx:1-80]()

---

## 7. 错误边界与容错设计

### 概述

前端采用 **React 错误边界（Error Boundary）** 模式，确保局部组件错误不会导致整个应用崩溃。错误边界提供友好的错误提示和调试信息。

### AdminErrorBoundary 组件

```typescript
class AdminErrorBoundary extends React.Component<
  Props,
  State
> {
  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error: error.message };
  }

  componentDidCatch(error: Error, info: React.ErrorInfo) {
    console.error("Admin panel error:", error, info);
    this.setState({ stack: info.componentStack });
  }
}
```

### 错误展示层级

```mermaid
graph TD
    A[组件渲染错误] --> B[ErrorBoundary 捕获]
    B --> C{错误类型}
    C -->|有堆栈| D[显示堆栈追踪]
    C -->|无堆栈| E[显示通用错误消息]
    D --> F[显示重新加载按钮]
    E --> F
    F --> G[用户点击重试]
    G --> H[重新渲染组件]
```

### 错误展示样式

错误信息采用红色警示样式，堆栈信息可折叠展开：

```typescript
// 错误消息框
<div style={{
  background: "rgba(239,68,68,0.08)",
  border: "1px solid rgba(239,68,68,0.2)",
  borderRadius: 12,
  padding: "12px 16px",
}}>
  <p style={{ color: "#f87171", fontWeight: 600 }}>
    {this.state.error || "Unknown render error"}
  </p>
</div>

// 可折叠的堆栈信息
<details>
  <summary>Stack trace</summary>
  <pre style={{
    fontSize: 11,
    color: "#9ca3af",
    background: "#0a1520",
    borderRadius: 8,
  }}>
    {this.state.stack}
  </pre>
</details>
```

### 全局状态恢复

错误边界支持状态重置，允许用户在不刷新页面的情况下恢复应用：

```typescript
try {
  // 渲染可能出错的组件
  return <Dashboard stats={stats} />;
} catch {
  // 降级 UI
  return <ErrorFallback onRetry={this.resetError} />;
}
```

资料来源：[gateway/frontend/src/components/admin/AdminErrorBoundary.tsx:1-100]()

---

## 技术架构总览

```mermaid
graph TB
    subgraph 前端层
        A[Next.js 应用]
        A --> B[CEO 仪表盘]
        A --> C[Admin 系统管理]
        A --> D[入职向导]
        A --> E[集成管理]
        A --> F[探索页面]
        A --> G[错误边界]
    end

    subgraph 网关层
        H[API 网关]
        H --> I[Public Agent API]
        H --> J[Admin API]
    end

    subgraph 服务层
        K[Agent 核心服务]
        K --> L[自愈系统]
        K --> M[断路器]
        K --> N[自动恢复]
    end

    subgraph 集成层
        O[Twilio]
        P[Vapi]
        Q[SendGrid]
        R[Stripe]
    end

    I --> O
    I --> P
    I --> Q
    J --> R
    K -.->|健康检查| L
    L -->|触发| M
    M -->|恢复| N
```

---

## 相关文档

- [系统管理指南](./admin-system.md) — 管理员面板详细操作手册
- [集成配置参考](./integrations.md) — 第三方服务配置教程
- [入职流程说明](./onboarding.md) — 用户引导配置指南
- [定价与订阅](./pricing.md) — 层级功能对比详解
- [公共 API 文档](./public-api.md) — Agent 名片与发现 API

---

<a id='page-security'></a>

## 安全模型

### 相关页面

相关主题：[七大创新特性](#page-innovations), [代理宪法配置指南](#page-constitution), [后端API系统](#page-backend-api)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)
- [gateway/frontend/src/app/privacy/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/privacy/page.tsx)
- [gateway/frontend/src/app/terms/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/terms/page.tsx)
- [gateway/isg_agent/config.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/config.py)
- [gateway/frontend/src/app/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/integrations/page.tsx)
- [gateway/frontend/src/app/billing/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/billing/page.tsx)
</details>

# 安全模型

## 概述

DingDawg 平台采用多层安全架构来保护用户数据、AI 代理配置和系统交互。该安全模型涵盖了前端界面、API 网关、认证机制以及数据存储等核心组件，通过状态监控、权限验证和安全策略配置来确保平台的安全性。

DingDawg 的安全设计理念围绕以下几个核心目标：

- **数据保护**：确保用户隐私数据、代理配置和对话日志的安全存储与传输
- **身份认证**：通过多层验证机制确保用户身份的真实性和访问权限的合理性
- **内容安全**：防止提示词注入攻击和敏感信息泄露
- **金融安全**：保护支付信息和账单数据的安全
- **系统弹性**：通过自愈机制和健康检查确保系统的持续稳定运行

资料来源：[gateway/frontend/src/app/admin/system/page.tsx:1-50]()

## 安全架构总览

```mermaid
graph TD
    subgraph 前端层["前端安全层"]
        A[用户界面] --> B[认证状态管理]
        B --> C[API 请求拦截]
        C --> D[敏感数据脱敏]
    end
    
    subgraph 网关层["API 网关安全"]
        E[路由层] --> F[依赖注入验证]
        F --> G[认证中间件]
        G --> H[速率限制]
    end
    
    subgraph 业务层["业务逻辑安全"]
        I[代理配置验证] --> J[提示词安全检查]
        J --> K[Webhook 签名验证]
    end
    
    subgraph 数据层["数据安全"]
        L[加密存储] --> M[访问控制]
        M --> N[审计日志]
    end
    
    A --> E
    E --> I
    I --> L
```

## 安全配置管理

### 配置架构

DingDawg 使用 Pydantic Settings 进行配置管理，所有安全相关的配置项都以 `ISG_AGENT_` 为前缀的环境变量进行设置。这种设计确保了配置与代码的分离，便于在不同环境下进行安全配置的管理。

资料来源：[gateway/isg_agent/config.py:1-100]()

### 配置验证机制

系统对关键安全配置项实施了严格的验证机制：

| 配置项 | 类型 | 验证规则 | 默认值 | 说明 |
|--------|------|----------|--------|------|
| `log_level` | 字符串 | 必须为 DEBUG/INFO/WARNING/ERROR/CRITICAL 之一 | INFO | 日志级别控制 |
| `secret_key` | 字符串 | 生产环境必须为强密钥 | 自动生成 | 会话加密密钥 |
| `allowed_origins` | 字符串 | CORS 允许的源列表 | localhost:3002 | 跨域请求控制 |

资料来源：[gateway/isg_agent/config.py:100-150]()

```python
@field_validator("log_level")
@classmethod
def _normalise_log_level(cls, v: str) -> str:
    """Normalise log level to uppercase."""
    normalised = v.upper().strip()
    valid_levels = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
    if normalised not in valid_levels:
        raise ValueError(
            f"Invalid log_level {v!r}; must be one of {sorted(valid_levels)}"
        )
    return normalised
```

上述代码展示了系统如何通过 Pydantic 验证器确保日志级别配置的合法性和一致性。

## 认证与授权

### 多层认证策略

DingDawg 平台实施了分层认证机制，确保只有经过验证的用户才能访问相应功能：

```mermaid
graph LR
    A[用户请求] --> B{认证检查}
    B -->|未登录| C[公开端点]
    B -->|已登录| D{权限检查}
    D -->|管理员| E[管理后台]
    D -->|普通用户| F[用户面板]
    D -->|API Token| G[API 接口]
```

### 身份验证流程

系统通过以下步骤完成用户身份的验证：

1. **会话验证**：检查用户会话的有效性和过期时间
2. **角色识别**：确定用户的角色类型（管理员、代理所有者、访客等）
3. **权限匹配**：验证用户是否有权访问请求的资源
4. **操作授权**：检查用户是否有权执行特定操作

资料来源：[gateway/frontend/src/app/admin/system/page.tsx:30-80]()

## 数据安全保护

### 用户数据分类

根据隐私政策，系统将用户数据分为以下几个类别进行差异化保护：

| 数据类别 | 包含内容 | 存储要求 | 访问控制 |
|----------|----------|----------|----------|
| 账户信息 | 用户名、邮箱、密码哈希 | 加密存储 | 仅账户所有者 |
| 代理数据 | @handle、代理名称、行业配置 | 标准存储 | 账户所有者 + 公开展示 |
| 对话日志 | 用户与 AI 代理的消息记录 | 标准存储 | 账户所有者 |
| 使用分析 | 访问统计、性能指标 | 聚合存储 | 管理员 |
| 支付信息 | 支付卡详情、账单记录 | 第三方处理 | 仅 Stripe |

资料来源：[gateway/frontend/src/app/privacy/page.tsx:1-60]()

### 敏感信息处理

系统在处理敏感信息时遵循以下原则：

- **最小化原则**：只收集和存储业务必需的数据
- **加密原则**：敏感数据在传输和存储过程中均采用加密处理
- **隔离原则**：支付信息由 Stripe 第三方处理，平台不存储完整的支付卡信息
- **访问审计**：所有敏感数据的访问都会被记录和监控

资料来源：[gateway/frontend/src/app/privacy/page.tsx:60-100]()

## AI 内容安全

### 提示词防护

DingDawg 平台实施了多层次的提示词防护机制来防止提示词注入攻击：

1. **输入验证**：对用户输入进行安全检查，过滤潜在的恶意指令
2. **系统提示隔离**：确保系统级提示词与用户输入隔离，防止角色扮演攻击
3. **输出过滤**：对 AI 生成的内容进行敏感信息检查

### AI 生成内容免责声明

平台明确告知用户 AI 生成内容可能存在的局限性：

资料来源：[gateway/frontend/src/app/terms/page.tsx:1-50]()

> AI 生成的输出可能包含不准确、错误或过时的信息。用户有责任在使用前审查和验证任何内容。
>
> ISG 不保证任何 AI 生成响应的准确性、完整性或特定用途的适用性。
>
> AI 输出不构成专业建议（法律、医疗、财务或其他方面）。如有需要，请咨询合格的专业人士。

资料来源：[gateway/frontend/src/app/terms/page.tsx:50-100]()

## 系统健康与自愈

### 安全状态监控

DingDawg 管理后台提供了全面的安全状态监控功能：

```mermaid
graph TD
    A[系统监控] --> B[组件状态]
    A --> C[安全层状态]
    A --> D[自愈机制]
    A --> E[错误追踪]
    
    B --> B1[前端服务]
    B --> B2[后端服务]
    B --> B3[数据库]
    
    C --> C1[认证层]
    C --> C2[授权层]
    C --> C3[加密层]
    
    D --> D1[熔断器]
    D --> D2[自动重试]
    D --> D3[故障转移]
```

系统管理员可以通过管理界面的 Security 面板查看各安全组件的实时状态：

```tsx
{components?.security && (
  <Section title="Security">
    <div className="bg-[#0d1926] border border-[#1a2a3d] rounded-xl divide-y divide-[#1a2a3d]">
      {Object.entries(components.security).map(([key, value]) => (
        <div key={key} className="flex items-center justify-between px-4 py-2.5">
          <span className="text-sm text-gray-300 capitalize">
            {key.replace(/_/g, " ")}
          </span>
          <StatusDot color={statusColor(value)} label={value.toUpperCase()} />
        </div>
      ))}
    </div>
  </Section>
)}
```

资料来源：[gateway/frontend/src/app/admin/system/page.tsx:40-60]()

### 自愈机制

系统具备自动故障检测和恢复能力：

| 机制类型 | 触发条件 | 恢复动作 | 监控指标 |
|----------|----------|----------|----------|
| 熔断器 | 连续失败超过阈值 | 暂停服务调用，启用备用方案 | 错误率 |
| 自动重试 | 网络超时或临时故障 | 指数退避重试 | 响应时间 |
| 健康检查 | 定时检测 | 自动重启不健康组件 | 服务可用性 |
| Webhook 重试 | 目标服务不可达 | 延迟重发至多 3 次 | 送达率 |

资料来源：[gateway/frontend/src/app/admin/system/page.tsx:60-90]()

## 集成安全

### 第三方服务认证

DingDawg 支持与多种第三方服务集成，每种集成都采用相应的安全认证机制：

| 服务类型 | 认证方式 | 安全要求 | 配置位置 |
|----------|----------|----------|----------|
| Google Calendar | OAuth 2.0 | 用户授权 | 集成页面 |
| Stripe | API Key | 服务器端存储 | 配置文件 |
| SendGrid | API Key | 环境变量 | 集成配置 |
| Twilio | Account SID + Token | 加密存储 | 集成配置 |
| Vapi | API Key | 服务器端存储 | 集成配置 |
| Webhook | HMAC 签名 | 每次请求验证 | 端点配置 |

资料来源：[gateway/frontend/src/app/integrations/page.tsx:1-50]()

### Webhook 安全

系统支持 Webhook 的安全配置，包括：

- **签名验证**：使用 HMAC-SHA256 算法验证请求来源
- **自动重试**：失败时自动重试，最多重试 3 次
- **成功速率监控**：实时显示 Webhook 投递成功率

资料来源：[gateway/frontend/src/app/admin/integrations/page.tsx:1-60]()

## 账单与支付安全

### 支付信息处理

DingDawg 的支付信息处理遵循严格的 PCI DSS 合规要求：

```mermaid
graph LR
    A[用户发起支付] --> B{Stripe 处理}
    B --> C[支付卡验证]
    C --> D{验证结果}
    D -->|成功| E[生成订阅]
    D -->|失败| F[返回错误]
    E --> G[更新账户状态]
```

关键安全要点：

- **平台不存储**：系统不存储任何支付卡详细信息
- **第三方处理**：所有支付操作由 Stripe 安全处理
- **令牌化**：使用支付令牌而非真实卡号进行关联

资料来源：[gateway/frontend/src/app/billing/page.tsx:1-40]()

### 使用量限制

系统实施使用量监控以保护用户和平台安全：

```tsx
// 使用量紧迫度计算
const usagePct = usage && usage.actions_included > 0
  ? Math.min(100, Math.round((usage.total_actions / usage.actions_included) * 100))
  : 0;
const showUrgencyBanner = usagePct >= 80 && currentPlanId !== "enterprise";
```

当使用量达到 80% 时，系统会向用户显示紧迫度提示，Enterprise 计划用户不受此限制。

资料来源：[gateway/frontend/src/app/billing/page.tsx:40-80]()

## API 访问安全

### API 密钥管理

API 访问控制包括以下安全措施：

- **速率限制**：自动请求必须尊重速率限制，不得干扰平台稳定性
- **来源验证**：通过 CORS 配置限制 API 访问来源
- **端点认证**：每个 API 端点都需要通过认证中间件验证

### CORS 配置

系统支持灵活的跨域资源共享配置：

```python
def get_allowed_origins(self) -> list[str]:
    """Return ``allowed_origins`` as a list of stripped origin strings."""
    return [o.strip() for o in self.allowed_origins.split(",") if o.strip()]
```

配置示例：

```
ISG_AGENT_ALLOWED_ORIGINS=http://localhost:3002, https://app.example.com
```

资料来源：[gateway/isg_agent/config.py:50-80]()

## 合规与法律框架

### @Handle 政策

DingDawg 实施了严格的 @Handle 永久性政策来维护系统安全：

| 政策要点 | 说明 |
|----------|------|
| 唯一性 | 每个 @Handle 在全平台唯一，不可重复 |
| 永久性 | 一旦声明，不可更改、转让或出售 |
| 所有权 | 用户不得出售、租用或以其他方式商业利用其 Handle |
| 争议解决 | 所有权争议通过官方渠道解决 |

资料来源：[gateway/frontend/src/app/terms/page.tsx:100-150]()

### 用户责任

用户在使用平台时需承担以下安全责任：

1. 确保账户信息安全且及时更新
2. 不与他人共享账户凭证
3. 发现可疑活动时立即通知 support@dingdawg.com
4. 验证 AI 生成内容后再依赖使用
5. 年龄不低于 13 岁方可创建账户

资料来源：[gateway/frontend/src/app/terms/page.tsx:150-180]()

## 安全最佳实践

### 开发者建议

1. **环境变量管理**：生产环境务必设置强 secret_key
2. **日志级别**：生产环境建议使用 WARNING 或 ERROR 级别
3. **CORS 配置**：仅在必要时允许跨域访问
4. **API 调用**：遵守速率限制，实施指数退避重试

### 运维建议

1. **定期监控**：关注管理后台的安全状态面板
2. **错误追踪**：定期检查客户端错误日志
3. **集成测试**：使用自检功能验证各组件连接状态
4. **备份策略**：确保数据库和配置的定期备份

## 常见安全问题排查

| 问题现象 | 可能原因 | 解决方案 |
|----------|----------|----------|
| 认证失败 | Token 过期 | 重新登录获取新 Token |
| CORS 错误 | 来源不在白名单 | 检查 allowed_origins 配置 |
| Webhook 投递失败 | 签名验证失败 | 检查 Webhook 密钥配置 |
| 使用量异常 | 未授权使用 | 检查 API 密钥是否泄露 |
| 支付失败 | Stripe 配置问题 | 验证 Stripe API 密钥有效性 |

## 相关文档

如需了解更多技术细节，请参阅以下相关文档：

- [快速入门指南](./quick-start.md) - 了解平台基本使用方法
- [API 参考文档](./api-reference.md) - 完整的 API 接口说明
- [配置参考](./configuration.md) - 详细的环境变量配置说明
- [部署指南](./deployment.md) - 生产环境部署最佳实践

---

<a id='page-constitution'></a>

## 代理宪法配置指南

### 相关页面

相关主题：[七大创新特性](#page-innovations), [安全模型](#page-security), [后端API系统](#page-backend-api)

```markdown
<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx)
- [gateway/frontend/src/app/onboarding/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/onboarding/page.tsx)
- [gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)
- [gateway/isg_agent/api/routes/console_governance.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/api/routes/console_governance.py)
- [gateway/isg_agent/schemas/skills.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/schemas/skills.py)
- [gateway/frontend/src/app/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/integrations/page.tsx)
- [gateway/frontend/src/components/dashboard/DashboardHeader.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/dashboard/DashboardHeader.tsx)

</details>

# 代理宪法配置指南

## 概述

代理宪法（Agent Constitution）是 DingDawg Agent 1 平台中用于定义 AI 代理行为准则、运营边界和安全策略的核心配置机制。通过宪法配置，开发者可以为代理设置系统提示词定制、业务时间限制、技能激活规则以及安全防护层级，确保代理在既定范围内运行。

本文档基于源码分析，详细介绍代理宪法配置的各个组成部分、配置方式及其在系统中的作用。

## 核心配置架构

DingDawg Agent 1 的宪法配置采用分层架构，涵盖以下核心领域：

```mermaid
graph TD
    A[代理宪法配置] --> B[业务运营配置]
    A --> C[技能与能力配置]
    A --> D[安全与治理配置]
    A --> E[集成与第三方配置]
    
    B --> B1[营业时间限制]
    B --> B2[行业领域选择]
    B --> B3[定价层级]
    
    C --> C1[模板选择]
    C --> C2[技能激活]
    C --> C3[系统提示词]
    
    D --> D1[自愈机制]
    D --> D2[安全层级]
    D --> D3[熔断器配置]
    
    E --> E1[第三方集成]
    E --> E2[Webhook配置]
```

资料来源：[gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx)

## 业务运营配置

### 营业时间限制

营业时间限制是代理宪法的重要组成部分，用于控制代理何时响应用户请求。当启用营业时间限制时，代理仅在设定的时间范围内处理对话。

```typescript
interface BusinessHours {
  mon: TimeRange;
  tue: TimeRange;
  wed: TimeRange;
  thu: TimeRange;
  fri: TimeRange;
  sat: TimeRange;
  sun: TimeRange;
}

interface TimeRange {
  open: string;  // 格式: "HH:MM"
  close: string; // 格式: "HH:MM"
}
```

资料来源：[gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx:28-40](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx)

#### 配置组件参数说明

| 参数 | 类型 | 描述 | 示例值 |
|------|------|------|--------|
| `wizard.hoursEnabled` | `boolean` | 是否启用营业时间强制 | `true` / `false` |
| `wizard.hours[day].open` | `string` | 每周指定日期的开门时间 | `"09:00"` |
| `wizard.hours[day].close` | `string` | 每周指定日期的关门时间 | `"18:00"` |
| `day` | `enum` | 星期标识符 | `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun` |

营业时间配置界面提供了直观的可视化组件：

```tsx
{(["mon", "tue", "wed", "thu", "fri", "sat", "sun"] as const).map((day) => {
  const range = wizard.hours[day];
  return (
    <input
      type="time"
      value={range.open}
      onChange={(e) => setWizard(...)}
    />
  );
})}
```

资料来源：[gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx:45-60](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx)

### 行业领域选择

代理宪法要求配置代理所属的行业领域（sector），用于优化代理的行为模式和响应策略。领域选择是注册过程中的关键步骤之一。

```typescript
interface StepActivationProps {
  agentName: string;
  handle: string;
  sector: Sector | null;
  tier: TierId | null;
  tiers: Tier[];
}
```

资料来源：[gateway/frontend/src/app/onboarding/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/onboarding/page.tsx)

## 技能与能力配置

### 模板系统

代理宪法支持通过模板（Template）快速初始化代理能力。模板定义了代理的预设行为模式、技能组合和对话风格。

```typescript
interface Template {
  id: string;
  name: string;
  icon: string;
  popular?: boolean;
  description?: string;
}
```

资料来源：[gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx)

#### 模板选择界面

```tsx
{templates.map((tpl) => {
  const isSelected = wizard.templateId === tpl.id;
  return (
    <button
      key={tpl.id}
      onClick={() => set("templateId", tpl.id)}
      aria-pressed={isSelected}
      style={{
        background: isSelected
          ? "rgba(246,180,0,0.12)"
          : "rgba(255,255,255,0.04)",
        border: isSelected
          ? "1px solid rgba(246,180,0,0.45)"
          : "1px solid rgba(255,255,255,0.07)",
      }}
    >
      <span>{tpl.icon}</span>
      <span>{tpl.name}</span>
      {tpl.popular && <span>Popular</span>}
    </button>
  );
})}
```

资料来源：[gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx)

### 技能激活状态

代理宪法配置中包含技能（Skills）的激活状态管理。技能是代理执行特定任务的能力单元。

```typescript
interface DashboardStats {
  conversations: number;
  activeTasks: number;
  activeSkills: number;  // 当前激活的技能数量
  integrations: IntegrationStatus[];
}
```

资料来源：[gateway/frontend/src/components/dashboard/DashboardHeader.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/dashboard/DashboardHeader.tsx)

## 安全与治理配置

### 系统健康监控

代理宪法包含自检（Self-Test）机制，用于验证系统各组件的健康状态。

```typescript
interface SelfTestResult {
  database: ComponentStatus;
  tables: ComponentStatus;
  llm_providers: ComponentStatus;
  stripe: ComponentStatus;
  routes: ComponentStatus;
  security: SecurityLayers;
}
```

资料来源：[gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)

#### 自检功能说明

| 检查项 | 描述 | 预期状态 |
|--------|------|----------|
| Database | 数据库连接状态 | `healthy` / `unhealthy` |
| Tables | 数据表完整性 | `healthy` / `unhealthy` |
| LLM Providers | 语言模型提供商连接 | `healthy` / `unhealthy` |
| Stripe | 支付服务集成状态 | `healthy` / `unhealthy` |
| Routes | API 路由可用性 | `healthy` / `unhealthy` |
| Security | 安全层级状态 | `healthy` / `unhealthy` |

自检界面提供了运行按钮：

```tsx
<button
  onClick={() => void handleSelfTest()}
  disabled={selfTestRunning}
  className="bg-[var(--gold-400)]/20 text-[var(--gold-400)]"
>
  {selfTestRunning ? "Running..." : "Run Test"}
</button>
```

资料来源：[gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)

### 安全层级

代理宪法的安全配置包含多个防护层：

```typescript
interface SecurityLayers {
  prompt_armor: Status;
  extraction_defense: Status;
  auth_layer_1: Status;
  auth_layer_2: Status;
  auth_layer_3: Status;
  auth_layer_4: Status;
}
```

资料来源：[gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)

安全层级展示组件：

```tsx
{Object.entries(components.security).map(([key, value]) => (
  <div key={key} className="flex items-center justify-between">
    <span className="capitalize">{key.replace(/_/g, " ")}</span>
    <StatusDot color={statusColor(value)} label={value.toUpperCase()} />
  </div>
))}
```

### 自愈机制

代理宪法包含自愈（Self-Healing）功能，用于自动恢复系统故障。

```typescript
interface SelfHealing {
  circuit_breakers: CircuitBreaker[];
  auto_recovered: RecoveryEvent[];
}
```

资料来源：[gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)

自愈机制的工作流程：

```mermaid
graph TD
    A[检测到异常] --> B{是否在熔断器覆盖范围}
    B -->|是| C[触发熔断器]
    B -->|否| D[记录错误日志]
    C --> E{自动恢复可行}
    E -->|可行| F[执行自动恢复]
    E -->|不可行| G[人工介入]
    F --> H[记录恢复事件]
    H --> I[更新自愈日志]
```

## 集成配置

### 第三方服务集成

代理宪法支持与多个第三方服务的集成配置：

| 服务类别 | 示例服务 | 配置方式 |
|----------|----------|----------|
| 通信 | Google, Twilio, SendGrid | API Key 配置 |
| 语音 | VAPI | Webhook 回调 |
| 日历 | Google Calendar | OAuth 授权 |
| 支付 | Stripe | Webhook 集成 |

资料来源：[gateway/frontend/src/app/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/integrations/page.tsx)

### Webhook 配置

Webhook 是代理宪法中用于接收外部事件通知的关键机制。

```typescript
interface IntegrationHealth {
  connected_agents: number;
  last_test_result: "pass" | "fail";
  last_test_response_ms: number | null;
  last_tested_at: string;
  webhook_success_rate: number | null;
}
```

资料来源：[gateway/frontend/src/app/admin/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/integrations/page.tsx)

#### Webhook 状态显示

```tsx
<div className="flex items-center justify-between pt-1">
  <span className="text-xs text-gray-600">
    {health?.last_tested_at
      ? `Tested ${formatTime(health.last_tested_at)}`
      : "Not yet tested"}
  </span>
</div>
```

Webhook 成功率显示：

```tsx
{health?.webhook_success_rate !== null && health?.webhook_success_rate !== undefined && (
  <RateBar rate={health.webhook_success_rate} />
)}
```

### 集成配置模态框

集成配置通过模态框组件实现：

```tsx
<IntegrationConfigModal
  integration={openModal}
  status={status}
  webhooks={webhooks}
  onClose={() => setOpenModal(null)}
  onConnectGoogle={handleConnectGoogle}
  onConfigureSendGrid={handleConfigureSendGrid}
  onConfigureTwilio={handleConfigureTwilio}
  onConfigureVapi={handleConfigureVapi}
  onDisconnect={handleDisconnect}
  onTestIntegration={handleTest}
  onAddWebhook={handleAddWebhook}
  onDeleteWebhook={handleDeleteWebhook}
/>
```

资料来源：[gateway/frontend/src/app/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/integrations/page.tsx)

## 配置工作流

### 代理创建流程

```mermaid
graph LR
    A[选择模板] --> B[配置基础信息]
    B --> C[设置业务时间]
    C --> D[选择行业领域]
    D --> E[配置第三方集成]
    E --> F[设置安全层级]
    F --> G[激活代理]
```

### 完整配置流程

| 步骤 | 阶段 | 关键配置项 |
|------|------|------------|
| 1 | 模板选择 | 选择预设模板或空白代理 |
| 2 | 基础信息 | 代理名称、@handle |
| 3 | 营业时间 | 配置每周营业时间 |
| 4 | 行业领域 | 选择所属行业 |
| 5 | 定价层级 | 选择服务套餐 |
| 6 | 集成配置 | 配置第三方服务 |
| 7 | 安全设置 | 验证安全层级 |
| 8 | 激活部署 | 完成代理激活 |

## 配置管理界面

### 仪表板概览

代理宪法配置可通过管理仪表板进行监控：

```typescript
interface DashboardHeaderProps {
  stats: {
    conversations: number;
    activeTasks: number;
    activeSkills: number;
    integrations: IntegrationStatus[];
  };
}
```

资料来源：[gateway/frontend/src/components/dashboard/DashboardHeader.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/dashboard/DashboardHeader.tsx)

### 集成状态指示

集成状态通过颜色编码显示：

| 状态 | 颜色 | 含义 |
|------|------|------|
| 已连接 | 绿色 | 服务正常运行 |
| 未连接 | 灰色 | 服务未配置 |
| 错误 | 红色 | 服务异常 |

```tsx
{stats.integrations.slice(0, 5).map((integration) => (
  <span
    key={integration.name}
    className={cn(
      "h-2 w-2 rounded-full",
      integrationColor(integration.connected)
    )}
    title={`${integration.name}: ${integration.connected ? "Connected" : "Disconnected"}`}
  />
))}
```

## 常见配置问题

### 营业时间配置问题

**问题**：代理在营业时间外仍然响应。

**排查步骤**：
1. 确认 `hoursEnabled` 标志已启用
2. 检查各日期的时间范围是否正确设置
3. 验证服务器时区与配置时区是否一致

### 集成连接失败

**问题**：第三方服务集成状态显示失败。

**排查步骤**：
1. 检查 API Key 是否有效且未过期
2. 验证 Webhook URL 是否可访问
3. 运行自检功能查看详细错误信息

### 安全层级异常

**问题**：安全层级显示异常状态。

**排查步骤**：
1. 检查提示词防护配置
2. 验证身份验证层级配置
3. 查看自愈日志中的自动恢复记录

## 相关文档

- [系统管理指南](./admin-system-guide.md)
- [集成配置参考](./integrations-reference.md)
- [安全配置白皮书](./security-whitepaper.md)
- [API 路由文档](../api/routes/console_governance.md)
```

---

*最后更新：基于源码版本生成*

---

<a id='page-backend-api'></a>

## 后端API系统

### 相关页面

相关主题：[AI模型集成](#page-ai-integration), [安全模型](#page-security)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [gateway/isg_agent/api/routes/integrations/__init__.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/api/routes/integrations/__init__.py)
- [gateway/isg_agent/api/routes/integrations/_ddmain.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/api/routes/integrations/_ddmain.py)
- [gateway/isg_agent/api/routes/public.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/api/routes/public.py)
- [gateway/isg_agent/schemas/agents.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/schemas/agents.py)
- [gateway/isg_agent/config.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/config.py)
- [gateway/frontend/src/app/explore/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/explore/page.tsx)
- [gateway/frontend/src/app/billing/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/billing/page.tsx)
</details>

# 后端API系统

## 概述

DingDawg 后端API系统是整个平台的核心服务层，采用 FastAPI 框架构建，负责处理所有业务逻辑、数据持久化、外部服务集成以及与前端应用的通信。该系统托管在 `gateway/isg_agent/` 目录下，提供 RESTful API 接口供前端和外部客户端调用。

后端系统的主要职责包括：

- **用户认证与授权**：通过 `/api/v1/auth` 路由处理用户登录、注册、会话管理
- **AI Agent 管理**：提供 Agent 的创建、更新、查询和删除操作
- **模板系统**：支持基于模板快速创建 Agent
- **集成服务**：对接 VAPI、Stripe、Google Calendar、Email、SMS 等第三方服务
- **公开数据访问**：提供公开的 Agent 发现和浏览接口

资料来源：[gateway/isg_agent/config.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/config.py)

---

## 系统架构

### 整体架构图

```mermaid
graph TB
    subgraph 前端层["前端层 (React/Next.js)"]
        F1[Web App]
        F2[管理后台]
        F3[公开页面]
    end

    subgraph 网关层["API 网关"]
        GW[FastAPI Gateway]
    end

    subgraph 路由模块["路由模块"]
        R1[/api/v1/auth]
        R2[/api/v1/agents]
        R3[/api/v1/templates]
        R4[/api/v1/public]
        R5[/api/v1/integrations]
        R6[/api/v1/tasks]
    end

    subgraph 服务层["业务服务"]
        S1[认证服务]
        S2[Agent服务]
        S3[模板服务]
        S4[任务服务]
        S5[集成服务]
    end

    subgraph 数据层["数据存储"]
        DB[(PostgreSQL)]
        CACHE[(Redis Cache)]
    end

    subgraph 外部服务["第三方服务"]
        E1[VAPI语音]
        E2[Stripe支付]
        E3[Google Calendar]
        E4[Email/SMS]
    end

    F1 & F2 & F3 --> GW
    GW --> R1 & R2 & R3 & R4 & R5 & R6
    R1 --> S1
    R2 --> S2
    R3 --> S3
    R5 --> S5
    R6 --> S4
    S1 & S2 & S3 & S4 & S5 --> DB
    S5 --> E1 & E2 & E3 & E4
```

### 技术栈

| 层级 | 技术选型 | 说明 |
|------|---------|------|
| Web框架 | FastAPI | 高性能异步API框架 |
| 数据库 | PostgreSQL | 主数据存储 |
| 缓存 | Redis | 会话缓存和性能优化 |
| ORM | SQLAlchemy | 数据库抽象层 |
| 验证 | Pydantic | 请求/响应数据校验 |
| 认证 | JWT + Passkey | 双因素认证支持 |
| 支付 | Stripe | 订阅和支付处理 |

资料来源：[gateway/isg_agent/config.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/config.py)

---

## 路由组织结构

### 路由文件布局

```
gateway/isg_agent/api/routes/
├── __init__.py
├── agents.py          # Agent CRUD 操作
├── auth.py            # 认证与授权
├── templates.py       # 模板管理
├── tasks.py           # 异步任务
├── public.py          # 公开接口
├── billing.py         # 计费相关
└── integrations/
    ├── __init__.py    # 集成路由导出
    ├── _ddmain.py     # DDMain桥接路由
    ├── email.py       # 邮件集成
    ├── sms.py         # 短信集成
    ├── vapi.py        # 语音集成
    ├── google_calendar.py  # 日历同步
    ├── status.py      # 状态查询
    └── management.py  # 集成管理
```

### 集成模块的包结构

集成模块采用了分包设计，将原来单一的 `integrations.py` 扁平文件拆分为多个子模块：

> 这使得 `integrations.py` 包替换了旧的扁平文件。DDMain 桥接路由（先前 `integrations.py` 的唯一内容）通过 `__init__.py` 重新导出，以便 `app.py` 可以继续无变化地导入。

资料来源：[gateway/isg_agent/api/routes/integrations/__init__.py:1-22](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/api/routes/integrations/__init__.py)

```python
# gateway/isg_agent/api/routes/integrations/__init__.py
from isg_agent.api.routes.integrations._ddmain import router

__all__ = ["router"]
```

这种设计确保了向后兼容性的同时，实现了模块的清晰分离。

---

## 核心数据模型

### Agent 数据结构

Agent 是 DingDawg 平台的核心实体，以下是其完整的数据模型：

```python
# gateway/isg_agent/schemas/agents.py

class AgentResponse(BaseModel):
    """单个 Agent 的响应模型"""
    id: str                    # Agent的唯一UUID
    user_id: str               # 所有者用户ID
    handle: str                # 唯一@handle标识符
    name: str                   # 显示名称
    agent_type: str            # "personal" 或 "business"
    industry_type: Optional[str] = None    # 行业类型
    template_id: Optional[str] = None     # 创建时使用的模板UUID
    config_json: Optional[str] = None     # Agent配置JSON
    branding_json: Optional[str] = None    # 品牌/主题设置JSON
    status: str                 # 生命周期状态
    subscription_tier: str     # 计费层级
    created_at: str             # ISO 8601 UTC创建时间
    updated_at: str             # ISO 8601 UTC更新时间
```

资料来源：[gateway/isg_agent/schemas/agents.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/schemas/agents.py)

### Agent 状态与层级

| 状态字段 | 可选值 | 说明 |
|---------|-------|------|
| `status` | `active` / `suspended` / `archived` | Agent生命周期状态 |
| `subscription_tier` | `free` / `starter` / `pro` / `enterprise` | 计费等级 |
| `agent_type` | `personal` / `business` | Agent类型 |

---

## 公开API接口

### 公开 Agent 浏览

系统提供公开接口允许未认证用户浏览 Agent 列表：

```typescript
// gateway/frontend/src/app/explore/page.tsx
const data = await get<ListAgentsResponse>("/api/v1/public/agents?limit=100");
```

公开接口采用 `/api/v1/public/` 前缀，与需要认证的内部接口分离。

### Agent 卡片页面

公开 API 还提供 Agent 卡片（Card）的 HTML 渲染支持，用于社交分享和 SEO 优化：

```python
# gateway/isg_agent/api/routes/public.py
# 返回包含完整 SEO 元数据的 HTML 页面
<meta property="og:title" content="{name} &mdash; DingDawg Agent">
<meta property="og:description" content="{description or greeting}">
<meta property="og:type" content="website">
<meta name="twitter:card" content="summary">
```

资料来源：[gateway/isg_agent/api/routes/public.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/api/routes/public.py)

---

## 集成服务系统

### 集成架构

DingDawg 采用模块化的集成架构，通过 `DDMain` 桥接器统一管理各种第三方服务的集成：

```mermaid
graph LR
    subgraph 核心["核心系统"]
        CORE[Agent Core]
        BRIDGE[DDMain Bridge]
    end

    subgraph 集成模块["Notify 集成"]
        EMAIL[Email]
        SMS[SMS]
        VAPI[VAPI Voice]
        CAL[Google Calendar]
    end

    CORE --> BRIDGE
    BRIDGE --> EMAIL
    BRIDGE --> SMS
    BRIDGE --> VAPI
    BRIDGE --> CAL
```

### VAPI 语音集成

VAPI 集成为 Agent 提供语音交互能力：

```typescript
// gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx
interface VapiConfig {
    apiKey: string;
    voice_model?: "alloy" | "echo" | "fable" | "onyx" | "nova" | "shimmer";
}

const VOICE_MODELS = [
    { value: "alloy", label: "Alloy" },
    { value: "echo", label: "Echo" },
    { value: "fable", label: "Fable" },
    { value: "onyx", label: "Onyx" },
    { value: "nova", label: "Nova" },
    { value: "shimmer", label: "Shimmer" }
];
```

资料来源：[gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx)

---

## 配置系统

### 环境变量配置

后端使用 Pydantic Settings 进行配置管理，支持环境变量前缀和嵌套配置：

```python
# gateway/isg_agent/config.py
model_config = {
    "env_prefix": "ISG_AGENT_",           # 环境变量前缀
    "env_nested_delimiter": "__",        # 嵌套分隔符
    "populate_by_name": True,             # 允许按名称填充
    "extra": "ignore",                    # 忽略额外字段
    "env_file": ".env",                   # 环境文件
    "env_file_encoding": "utf-8",         # 文件编码
}
```

### 日志级别验证

配置系统包含日志级别的自动规范化：

```python
@field_validator("log_level")
@classmethod
def _normalise_log_level(cls, v: str) -> str:
    """将日志级别规范化为大写格式"""
    normalised = v.upper().strip()
    valid_levels = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
    if normalised not in valid_levels:
        raise ValueError(
            f"Invalid log_level {v!r}; must be one of {sorted(valid_levels)}"
        )
    return normalised
```

### Secret Key 安全策略

系统为 `secret_key` 实现了安全策略：

> 生成一个安全的随机密钥（如果未提供）；在生产环境中拒绝弱密钥。

资料来源：[gateway/isg_agent/config.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/config.py)

---

## 计费与用量

### 用量跟踪

系统跟踪每个 Agent 的动作使用量：

```typescript
// gateway/frontend/src/app/billing/page.tsx
// 用量紧迫度：>=80% 警告，>=100% 危险
const usagePct = usage && usage.actions_included > 0
    ? Math.min(100, Math.round((total_actions / actions_included) * 100))
    : 0;
const showUrgencyBanner = usagePct >= 80 && currentPlanId !== "enterprise";
```

### 计划层级

| 层级 | 动作配额 | 特性 |
|------|---------|------|
| free | 有限 | 基础功能 |
| starter | 增加 | 标准功能 |
| pro | 更高 | 高级功能 |
| enterprise | 无限 | 全功能+优先支持 |

资料来源：[gateway/frontend/src/app/billing/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/billing/page.tsx)

---

## 安全机制

### 认证流程

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Auth
    participant DB

    Client->>API: 登录请求
    API->>Auth: 验证凭证
    Auth->>DB: 查询用户
    DB-->>Auth: 用户数据
    Auth-->>API: JWT Token
    API-->>Client: 认证成功

    Client->>API: API请求 + JWT
    API->>API: 验证Token
    API-->>Client: 受保护的资源
```

### CORS 配置

系统通过 `allowed_origins` 配置支持跨域请求：

```python
# 支持逗号分隔的多个源
allowed_origins = "http://localhost:3002, https://app.example.com"

# 解析为列表
@property
def allowed_origins_list(self) -> list[str]:
    return [o.strip() for o in self.allowed_origins.split(",") if o.strip()]
```

资料来源：[gateway/isg_agent/config.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/config.py)

---

## 公开发现系统

### Agent 分类

公开 API 支持按行业分类浏览 Agent：

```typescript
// gateway/frontend/src/app/explore/page.tsx
type Category = "all" | "healthcare" | "legal" | "real_estate" | "automotive" | "home_services" | "retail";

function industryToCategory(industry: string): Category {
    // 行业到分类的映射逻辑
}
```

### 发现页面流程

```mermaid
graph TD
    A[访问 /explore] --> B{已登录?}
    B -->|是| C[显示已认证界面]
    B -->|否| D[显示公开界面]
    C --> E[获取 Agent 列表]
    D --> E
    E --> F[按分类筛选]
    F --> G[搜索过滤]
    G --> H[渲染 Agent 卡片网格]
```

---

## See Also

- [前端架构](../frontend/前端架构.md)
- [集成服务配置](../integrations/集成服务配置.md)
- [认证与授权](../auth/认证与授权.md)
- [数据库模式](../database/数据库模式.md)

---

<a id='page-ai-integration'></a>

## AI模型集成

### 相关页面

相关主题：[后端API系统](#page-backend-api), [系统架构](#page-architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [gateway/isg_agent/api/routes/integrations/__init__.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/api/routes/integrations/__init__.py)
- [gateway/isg_agent/config.py](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/isg_agent/config.py)
- [gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)
- [gateway/frontend/src/app/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/integrations/page.tsx)
- [gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx)
- [gateway/frontend/src/app/billing/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/billing/page.tsx)
</details>

# AI模型集成

## 概述

DingDawg Agent 1 平台采用模块化的AI模型集成架构，允许企业根据业务需求灵活选择和配置不同的AI服务提供商。系统支持多种主流AI模型服务，包括OpenAI、Anthropic、Google AI等，并通过智能路由机制实现请求分发、故障转移和成本优化。

AI模型集成是平台的核心能力之一，直接决定了AI Agent的对话质量、响应速度和运营成本。通过统一的模型抽象层和配置管理界面，用户可以无需深入了解底层API即可完成模型的接入和切换。资料来源：[gateway/isg_agent/api/routes/integrations/__init__.py:1-20]()

## 系统架构

### 整体架构设计

AI模型集成采用分层架构设计，从底层到顶层依次为：

1. **模型提供者层（Provider Layer）**：封装各AI服务提供商的SDK和API调用
2. **模型注册中心（Registry）**：管理所有已配置模型的元数据和状态
3. **智能路由层（Router）**：根据策略选择最优模型处理请求
4. **业务接口层（API Routes）**：向上层应用提供统一的模型调用接口

```mermaid
graph TD
    A[业务请求] --> B[API Routes]
    B --> C[智能路由层 Router]
    C --> D[模型注册中心 Registry]
    D --> E[模型提供者层 Providers]
    
    E --> F[OpenAI Provider]
    E --> G[Anthropic Provider]
    E --> H[Google Provider]
    E --> I[Mercury Provider]
    E --> J[Ollama Provider]
    
    F --> K[OpenAI API]
    G --> L[Anthropic API]
    H --> M[Google AI API]
    
    C -->|故障转移| F
    C -->|成本优化| G
    C -->|智能选择| H
```

### 目录结构

模型集成相关代码位于 `gateway/isg_agent/models/` 目录下：

```
gateway/isg_agent/models/
├── provider.py              # 基础Provider抽象类
├── openai_provider.py      # OpenAI模型实现
├── anthropic_provider.py   # Anthropic Claude模型实现
├── google_provider.py      # Google Gemini模型实现
├── mercury_provider.py     # Mercury模型实现
├── ollama_provider.py      # Ollama本地模型实现
├── intelligent_router.py   # 智能路由逻辑
├── registry.py             # 模型注册与管理
└── router.py               # 请求路由分发
```

## 模型提供者

### Provider基类

所有AI模型提供者都继承自统一的Provider基类，定义了标准接口：

| 方法/属性 | 说明 | 返回类型 |
|---------|------|---------|
| `chat_completion()` | 发送对话请求 | `ChatCompletion` |
| `get_usage_stats()` | 获取使用统计 | `UsageStats` |
| `health_check()` | 健康状态检查 | `bool` |
| `configured` | 是否已正确配置 | `bool` |

### OpenAI Provider

OpenAI Provider封装了OpenAI API的调用逻辑，支持GPT-4、GPT-3.5-Turbo等模型。该提供者通过API密钥进行认证，并处理请求速率限制和错误重试。

配置参数：

| 参数 | 环境变量 | 说明 | 必填 |
|------|---------|------|-----|
| API Key | `OPENAI_API_KEY` | OpenAI API密钥 | 是 |
| Organization | `OPENAI_ORG_ID` | 组织ID | 否 |
| Base URL | `OPENAI_BASE_URL` | API基础URL | 否 |

### Anthropic Provider

Anthropic Provider提供对Claude系列模型的访问。系统支持Claude 3 Opus、Claude 3 Sonnet和Claude 3 Haiku等模型。该提供者同样通过API密钥认证，并支持自定义系统提示词和参数调优。

### Google Provider

Google Provider集成Google AI的Gemini系列模型，支持Gemini Pro和Gemini Ultra。该提供者特别适用于需要强大推理能力的复杂任务。

### Mercury Provider

Mercury是一个轻量级模型提供者，专为成本敏感型应用设计。通过Mercury Provider，用户可以以更低的成本访问经过优化的AI能力。

### Ollama Provider

Ollama Provider支持本地部署的Ollama服务器，允许企业完全在本地运行AI模型。这对于数据隐私要求极高的场景（如金融、医疗）尤为重要，无需将敏感数据发送至第三方API。

## 智能路由机制

### 路由策略

智能路由层根据多个维度选择最优模型：

```mermaid
graph LR
    A[请求] --> B{路由决策}
    B --> C[成本优先]
    B --> D[质量优先]
    B --> E[延迟优先]
    B --> F[可用性优先]
    
    C --> G[选择低价模型]
    D --> H[选择最强模型]
    E --> I[选择最快模型]
    F --> J[选择健康模型]
```

### 熔断器机制

系统实现了熔断器（Circuit Breaker）模式，防止故障模型影响整体服务质量：

- **关闭状态**：正常转发请求
- **打开状态**：快速失败，立即返回备选结果
- **半开状态**：探测恢复情况

### 健康监控

每个模型提供者都具备独立的心跳检测机制，系统持续监控：

- 过去1小时错误率
- 平均响应时间
- API配额使用情况
- 最后成功响应时间

资料来源：[gateway/frontend/src/app/admin/system/page.tsx:1-50]()

## 配置管理

### 环境变量配置

AI模型配置通过环境变量进行管理，所有配置项均以 `ISG_AGENT_` 为前缀：

```python
# 资料来源：gateway/isg_agent/config.py:1-30指定格式
ISG_AGENT_LOG_LEVEL=INFO
ISG_AGENT_SECRET_KEY=your-secret-key-here
```

### 日志级别配置

系统支持标准日志级别配置：

| 级别 | 说明 |
|-----|------|
| `DEBUG` | 详细调试信息 |
| `INFO` | 一般信息 |
| `WARNING` | 警告信息 |
| `ERROR` | 错误信息 |
| `CRITICAL` | 严重错误 |

```python
# 验证器实现
@field_validator("log_level")
@classmethod
def _normalise_log_level(cls, v: str) -> str:
    """Normalise log level to uppercase."""
    normalised = v.upper().strip()
    valid_levels = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
    if normalised not in valid_levels:
        raise ValueError(
            f"Invalid log_level {v!r}; must be one of {sorted(valid_levels)}"
        )
    return normalised
```

## 前端管理界面

### 系统状态面板

管理员可以通过系统面板查看所有AI模型的实时状态：

```typescript
// 资料来源：gateway/frontend/src/app/admin/system/page.tsx
interface ComponentStatus {
  status: "online" | "offline" | "degraded";
  configured: boolean;
  error_rate_1h?: number;
  last_webhook?: string;
}
```

### LLM提供商状态

系统显示各模型提供商的详细状态信息：

| 字段 | 说明 |
|-----|------|
| `configured` | 是否已完成配置 |
| `status` | 当前运行状态 |
| `error_rate_1h` | 过去1小时错误率 |
| `reason` | 未配置或故障原因 |

```tsx
// 错误率展示示例
{info.error_rate_1h !== null && info.error_rate_1h !== undefined && (
  <MetricRow
    label="Error rate (1h)"
    value={`${(info.error_rate_1h * 100).toFixed(2)}%`}
  />
)}
```

### 集成配置模态框

通过集成配置模态框，管理员可以：

- 输入和验证API密钥
- 选择语音合成模型
- 配置Webhook回调
- 测试连接状态

```tsx
// 资料来源：gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx
const VOICE_MODELS = [
  { value: "browser_tts", label: "Browser TTS" },
  { value: "openai", label: "OpenAI TTS" },
  { value: "elevenlabs", label: "ElevenLabs" }
];
```

## 计费与用量

### Action计费模式

平台采用按Action计费模式，用户只需为实际使用的AI调用付费：

| 套餐 | 价格 | Action配额 | 适用场景 |
|-----|------|-----------|---------|
| Free | $0 | 有限 | 试用/体验 |
| Starter | $X | 中等 | 小型企业 |
| Pro | $XX | 充足 | 成长型企业 |
| Enterprise | $XXX | 无限制 | 大型企业 |

### 用量监控

系统实时跟踪Action使用量：

```typescript
// 资料来源：gateway/frontend/src/app/billing/page.tsx
interface UsageStats {
  total_actions: number;
  actions_included: number;
  plan: "free" | "starter" | "pro" | "enterprise";
}

// 用量百分比计算
const usagePct = usage && usage.actions_included > 0
  ? Math.min(100, Math.round((usage.total_actions / usage.actions_included) * 100))
  : 0;
```

### 用量警告

系统会在用量达到特定阈值时发出提醒：

| 阈值 | 提示级别 | 动作 |
|-----|---------|-----|
| ≥80% | 警告 | 显示黄色横幅 |
| ≥100% | 紧急 | 显示红色横幅，提示升级 |

## 安全考虑

### 密钥管理

所有API密钥通过环境变量配置，敏感信息绝不硬编码：

```python
# 资料来源：gateway/isg_agent/config.py
@field_validator("secret_key")
@classmethod
def _ensure_secret_key(cls, v: str) -> str:
    """Generate a secure random key if none is provided; reject weak keys in production."""
    # 安全密钥生成逻辑
```

### 故障关闭策略

系统采用故障关闭（Fail-Closed）策略：

- 未配置的模型提供者直接返回错误
- API调用失败时不会静默降级
- 所有边界条件都有明确的错误处理

### 输入验证

所有模型请求都经过严格验证：

- 参数类型检查
- 输入长度限制
- 特殊字符过滤
- Prompt注入防护

## 数据隐私

### 数据保留策略

根据隐私政策，平台对AI交互数据有以下处理：

| 数据类型 | 保留期限 | 用途 |
|---------|---------|-----|
| 对话日志 | 按用户账户关联 | 历史记录和服务改进 |
| 使用分析 | 匿名化处理 | 性能监控 |
| 支付信息 | 加密存储 | 账单处理 |

### 企业数据保护

对于高敏感场景，推荐使用Ollama Provider实现完全本地化部署：

```mermaid
graph TD
    A[敏感数据] --> B{部署模式}
    B -->|云端| C[第三方API]
    B -->|本地| D[Ollama Server]
    D --> E[数据不出本地]
```

## 最佳实践

### 模型选择指南

| 场景 | 推荐模型 | 理由 |
|-----|---------|-----|
| 快速响应 | GPT-3.5-Turbo | 延迟低、成本低 |
| 高质量对话 | Claude 3 Sonnet | 推理能力强 |
| 复杂推理 | GPT-4/Claude 3 Opus | 顶级推理能力 |
| 成本优化 | Mercury/Ollama | 性价比高 |
| 数据敏感 | Ollama | 完全本地化 |

### 成本优化策略

1. **模型分级**：日常查询使用轻量模型，复杂任务使用重型模型
2. **缓存结果**：重复问题直接返回缓存结果
3. **批处理**：批量请求合并处理减少API调用
4. **智能路由**：根据问题类型自动选择最优模型

## 故障排除

### 常见问题

| 问题 | 可能原因 | 解决方案 |
|-----|---------|---------|
| 模型无响应 | API密钥错误 | 检查环境变量配置 |
| 错误率上升 | 配额耗尽 | 升级套餐或等待重置 |
| 响应缓慢 | 网络延迟/服务器负载 | 检查系统状态面板 |
| 连接失败 | 模型未配置 | 通过管理界面配置 |

### 健康检查端点

管理员可通过API检查模型健康状态：

```
GET /api/v1/admin/system/health
```

返回各模型提供商的详细状态信息。

## 相关文档

- [系统架构概览](./system-architecture.md)
- [集成服务配置](./integrations.md)
- [安全加固指南](./security-hardening.md)
- [API参考文档](./api-reference.md)

---

*本文档最后更新于系统版本 v1.0，基于 DingDawg Agent 1 仓库源码生成。*

---

<a id='page-frontend'></a>

## 前端组件与界面

### 相关页面

相关主题：[系统架构](#page-architecture), [数据流与状态管理](#page-data-flow)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [gateway/frontend/src/app/explore/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/explore/page.tsx)
- [gateway/frontend/src/app/admin/system/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/system/page.tsx)
- [gateway/frontend/src/app/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/page.tsx)
- [gateway/frontend/src/app/privacy/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/privacy/page.tsx)
- [gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx)
- [gateway/frontend/src/components/admin/AdminErrorBoundary.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/admin/AdminErrorBoundary.tsx)
- [gateway/frontend/src/app/admin/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/integrations/page.tsx)
- [gateway/frontend/src/app/operations/marketing/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/operations/marketing/page.tsx)
- [gateway/frontend/src/components/dashboard/DashboardHeader.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/dashboard/DashboardHeader.tsx)
- [gateway/frontend/src/app/integrations/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/integrations/page.tsx)
- [gateway/frontend/src/app/admin/agents/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/admin/agents/page.tsx)
- [gateway/frontend/src/app/onboarding/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/onboarding/page.tsx)
- [gateway/frontend/src/app/legal/page.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/app/legal/page.tsx)
- [gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx](https://github.com/dingdawg/dingdawg-agent-1/blob/main/gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx)
- [dashboard/index.html](https://github.com/dingdawg/dingdawg-agent-1/blob/main/dashboard/index.html)

</details>

# 前端组件与界面

本文档详细介绍 DingDawg 平台的前端组件架构与用户界面设计。该前端基于 Next.js 框架构建，采用 TypeScript 开发，提供了完整的管理后台、用户仪表板、集成配置、引导流程等功能模块。

## 技术栈概述

DingDawg 前端采用现代化的技术栈构建，确保应用具有良好的可维护性、性能和用户体验。

### 核心框架

| 技术 | 版本/用途 | 说明 |
|------|----------|------|
| Next.js | 14+ | React 服务端渲染框架 |
| TypeScript | 严格模式 | 类型安全的 JavaScript 超集 |
| Tailwind CSS | 自定义配置 | 原子化 CSS 框架，使用 CSS 变量定义主题 |

### 样式系统

前端使用 CSS 自定义属性（CSS Variables）实现主题化管理，核心变量定义包括：

```css
--foreground       /* 主文本颜色 */
--color-muted      /* 次要文本颜色 */
--stroke           /* 边框和分隔线颜色 */
--gold-400/500     /* 金色强调色 */
```

资料来源：[gateway/frontend/src/app/page.tsx:1-50]()

## 页面结构

### 页面层级概览

```mermaid
graph TD
    A[根路由 /] --> B[首页 /page]
    A --> C[探索页 /explore]
    A --> D[仪表板 /dashboard]
    A --> E[管理后台 /admin]
    A --> F[集成页 /integrations]
    A --> G[隐私政策 /privacy]
    A --> H[法律页面 /legal]
    A --> I[引导流程 /onboarding]
    A --> J[计费页面 /billing]
    
    D --> D1[CEO 仪表板 /dashboard/ceo]
    E --> E1[系统管理 /admin/system]
    E --> E2[代理管理 /admin/agents]
    E --> E3[集成管理 /admin/integrations]
    F --> F1[配置弹窗 IntegrationConfigModal]
    
    style A fill:#f9d71c,color:#000
    style D fill:#1a2a3d,color:#fff
    style E fill:#1a2a3d,color:#fff
```

### 首页 (HomePage)

首页是 DingDawg 平台的入口页面，包含品牌展示和功能介绍。

资料来源：[gateway/frontend/src/app/page.tsx:1-100]()

#### 主要功能

- **SEO 优化**：嵌入 JSON-LD 结构化数据，用于搜索引擎优化
- **身份验证重定向**：未认证用户显示品牌信息，已认证用户自动跳转至仪表板
- **特性对比展示**：展示 DingDawg 与其他解决方案的对比

```tsx
export default function HomePage() {
  return (
    <>
      <AuthRedirect to="/dashboard" />
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify([...])
        }}
      />
      {/* 功能展示组件 */}
    </>
  );
}
```

### 探索页面 (ExplorePage)

探索页面用于浏览和搜索公开的 AI 代理，支持按行业分类筛选。

资料来源：[gateway/frontend/src/app/explore/page.tsx:1-100]()

#### 核心功能

| 功能 | 描述 |
|------|------|
| 代理列表展示 | 展示所有公开代理的名称、描述、行业分类 |
| 搜索过滤 | 支持关键字搜索代理 |
| 分类筛选 | 按行业类别筛选代理 |
| 代理卡片 | 点击跳转至对应代理的详细信息页 |

#### 代理数据结构

```typescript
interface PublicAgent {
  handle: string;           // 代理唯一标识
  name: string;              // 代理名称
  description?: string;     // 代理描述
  greeting?: string;         // 问候语
  industry?: string;         // 所属行业
  category?: Category;      // 分类（从行业映射）
}
```

## 管理后台

管理后台提供系统级配置和监控功能，仅对授权管理员开放。

### 系统管理页面

系统管理页面展示平台各组件的健康状态和安全配置。

资料来源：[gateway/frontend/src/app/admin/system/page.tsx:1-80]()

#### 监控指标

| 组件类型 | 监控内容 |
|----------|----------|
| 服务组件 | Webhook 连接状态、上次调用时间 |
| 安全层 | 各项安全配置的启用状态 |
| 自愈机制 | 熔断器状态、自我修复功能 |

#### 自测试功能

系统提供集成自测试功能，可验证以下组件：

- 数据库连接状态
- 数据表完整性
- LLM 提供商配置
- Stripe 支付集成
- 路由配置
- 安全层状态

```tsx
<button
  onClick={() => void handleSelfTest()}
  disabled={selfTestRunning}
  className="bg-[var(--gold-400)]/20 text-[var(--gold-400)]"
>
  {selfTestRunning ? "Running..." : "Run Test"}
</button>
```

### 代理管理页面

代理管理页面提供平台所有 AI 代理的列表管理功能。

资料来源：[gateway/frontend/src/app/admin/agents/page.tsx:1-100]()

#### 功能特性

| 功能 | 说明 |
|------|------|
| 搜索过滤 | 按名称或句柄搜索代理 |
| 分页展示 | 服务端分页，支持大数量数据 |
| 分页导航 | 上一页/下一页导航，显示当前页码 |

```tsx
{totalPages > 1 && (
  <div className="flex items-center justify-between">
    <span>Page {page} of {totalPages}</span>
    <div className="flex gap-2">
      <button onClick={() => setPage(Math.max(1, page - 1))}>Prev</button>
      <button onClick={() => setPage(Math.min(totalPages, page + 1))}>Next</button>
    </div>
  </div>
)}
```

### 集成管理页面

集成管理页面用于配置和管理第三方服务集成。

资料来源：[gateway/frontend/src/app/admin/integrations/page.tsx:1-100]()
资料来源：[gateway/frontend/src/app/integrations/page.tsx:1-100]()

#### 集成状态展示

| 字段 | 描述 |
|------|------|
| `connected_agents` | 已连接的代理数量 |
| `last_test_result` | 最近测试结果（pass/fail） |
| `last_test_response_ms` | 最近响应时间（毫秒） |
| `webhook_success_rate` | Webhook 成功率 |

## 引导流程

引导流程（Onboarding）帮助新用户完成初始配置，包括选择模板、设置营业时间等步骤。

资料来源：[gateway/frontend/src/app/onboarding/page.tsx:1-150]()
资料来源：[gateway/frontend/src/components/onboarding/OnboardingChatStream.tsx:1-80]()

### 引导步骤流程

```mermaid
graph LR
    A[选择模板] --> B[配置营业时间]
    B --> C[设置代理名称]
    C --> D[设置 @Handle]
    D --> E[完成配置]
    
    style A fill:#f9d71c,color:#000
    style E fill:#22c55e,color:#fff
```

### 营业时间配置

引导流程支持按星期配置营业时间：

| 星期 | 配置字段 |
|------|----------|
| 周一至周五 | `open` / `close` 时间 |
| 周六 | 周末工作时间 |
| 周日 | 周末工作时间 |

```tsx
<div className="grid grid-cols-7 gap-1 text-center">
  {(["mon", "tue", "wed", "thu", "fri", "sat", "sun"] as const).map((day) => (
    <div key={day} className="flex flex-col gap-0.5">
      <input
        type="time"
        value={wizard.hours[day].open}
        onChange={(e) => setWizard(...)}
      />
    </div>
  ))}
</div>
```

### 模板选择

用户可从预设模板中选择代理类型，模板包含以下属性：

```typescript
interface Template {
  id: string;
  name: string;
  icon: string;
  popular?: boolean;
}
```

## 核心组件库

### 错误边界组件

`AdminErrorBoundary` 组件捕获渲染错误，防止整个应用崩溃。

资料来源：[gateway/frontend/src/components/admin/AdminErrorBoundary.tsx:1-80]()

#### 组件状态

| 状态 | 描述 |
|------|------|
| `error` | 错误消息文本 |
| `stack` | 错误堆栈跟踪 |
| `hasError` | 是否捕获到错误 |

#### 错误展示格式

```tsx
<div style={{ background: "rgba(239,68,68,0.08)", borderRadius: 12 }}>
  <p style={{ color: "#f87171", fontWeight: 600 }}>
    {this.state.error || "Unknown render error"}
  </p>
</div>

<details>
  <summary>Stack trace</summary>
  <pre>{this.state.stack}</pre>
</details>
```

### 仪表板头部组件

`DashboardHeader` 组件展示关键统计数据和集成状态。

资料来源：[gateway/frontend/src/components/dashboard/DashboardHeader.tsx:1-100]()

#### 统计数据展示

| 指标 | 用途 |
|------|------|
| `conversations` | 对话总数 |
| `activeTasks` | 活跃任务数 |
| `activeSkills` | 活跃技能数 |
| `integrations` | 集成连接状态 |

#### 集成指示器

头部右侧显示最多 5 个集成状态点：

```tsx
{stats.integrations.slice(0, 5).map((integration) => (
  <span
    key={integration.name}
    className={cn("h-2 w-2 rounded-full", integrationColor(integration.connected))}
    title={`${integration.name}: ${integration.connected ? "Connected" : "Disconnected"}`}
  />
))}
```

### 集成配置弹窗

`IntegrationConfigModal` 组件提供第三方集成的配置界面。

资料来源：[gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx:1-80]()

#### 支持的集成类型

| 集成 | 配置项 |
|------|--------|
| Vapi | API Key、语音模型选择 |
| Google | OAuth 连接 |
| SendGrid | SMTP 配置 |
| Twilio | 电话/SMS 配置 |

#### 语音模型选项

```typescript
const VOICE_MODELS = [
  { value: "browser_tts", label: "Browser TTS" },
  { value: "openai_tts", label: "OpenAI TTS" },
  { value: "elevenlabs", label: "ElevenLabs" },
];
```

## 隐私与法律页面

### 隐私政策页面

详细说明平台收集和使用用户数据的政策。

资料来源：[gateway/frontend/src/app/privacy/page.tsx:1-100]()

#### 数据类型

| 类别 | 说明 |
|------|------|
| 账户数据 | 邮箱、密码哈希、用户名 |
| 代理数据 | Handle、名称、行业、配置 |
| 对话日志 | 与 AI 代理的消息记录 |
| 使用分析 | 页面访问、功能使用情况 |
| 支付信息 | 支付卡详情（由 Stripe 处理） |

### 法律信息页面

提供平台的法律条款和联系方式。

资料来源：[gateway/frontend/src/app/legal/page.tsx:1-50]()

## 运营页面

### 营销活动页面

用于创建和管理营销活动，支持多渠道发送。

资料来源：[gateway/frontend/src/app/operations/marketing/page.tsx:1-100]()

#### 活动状态

| 状态 | 描述 |
|------|------|
| `draft` | 草稿状态 |
| `scheduled` | 已排期 |
| `sending` | 发送中 |
| `sent` | 已发送 |

#### 活动数据结构

```typescript
interface Campaign {
  id: string;
  name: string;
  channel: "email" | "sms" | "voice";
  status: "draft" | "scheduled" | "sending" | "sent";
  sent_count?: number;
}
```

## 独立仪表板

除主应用外，项目还包含一个独立的监控仪表板。

资料来源：[dashboard/index.html:1-20]()

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="ISG Agent 1 — Monitoring and Management Dashboard" />
    <title>ISG Agent 1 Dashboard</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
```

该仪表板作为独立单页应用（SPA）运行，使用 React 18 的新特性构建。

## 主题与样式规范

### 颜色系统

| 变量名 | 用途 | 示例值 |
|--------|------|--------|
| `--foreground` | 主文本 | `#ffffff` |
| `--color-muted` | 次要文本 | `rgba(148,163,184,0.6)` |
| `--stroke` | 边框线 | `#1a2a3d` |
| `--gold-400/500` | 强调色 | `#F6B400` |
| `--bg-primary` | 主背景 | `#0d0d0d` |

### 组件样式规范

- 使用 `glass-panel` 类实现毛玻璃效果
- 使用 `line-clamp-*` 类限制文本行数
- 错误提示使用红色系：`rgba(239,68,68,*)`
- 成功提示使用绿色系：`rgba(34,197,94,*)`

## 状态管理

### 认证状态

前端使用 `useAuthStore` Hook 管理用户认证状态：

```typescript
const { isAuthenticated } = useAuthStore();

// 已认证用户访问首页自动重定向
if (isAuthenticated) {
  return <AppShell><ExploreContent /></AppShell>;
}
```

### API 状态管理

使用 React Hooks 管理数据获取状态：

```typescript
const [agents, setAgents] = useState<PublicAgent[]>([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
```

## 常见问题与最佳实践

### 错误处理

1. **渲染错误**：使用 `AdminErrorBoundary` 组件捕获
2. **API 错误**：在 catch 块中提取错误消息
3. **网络错误**：显示友好提示并提供重试选项

### 性能优化

1. 使用 `useCallback` 缓存回调函数
2. 使用 `useMemo` 缓存计算结果
3. 图片使用 `next/image` 组件优化加载

### 可访问性

1. 使用 `aria-pressed` 标识可切换状态
2. 使用 `aria-label` 为图标按钮添加说明
3. 使用 `aria-hidden` 隐藏装饰性图标

## 相关页面

- [后端 API 文档](https://github.com/dingdawg/dingdawg-agent-1/wiki)
- [数据库架构](https://github.com/dingdawg/dingdawg-agent-1/wiki)
- [身份认证系统](https://github.com/dingdawg/dingdawg-agent-1/wiki)
- [第三方集成指南](https://github.com/dingdawg/dingdawg-agent-1/wiki)

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：dingdawg/dingdawg-agent-1

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `dingdawg-agent-1` 与安装入口 `dingdawg-support-agent` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npx dingdawg-support-agent`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | mcp_registry:io.github.dingdawg/dingdawg-support-agent:2.0.6 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.dingdawg%2Fdingdawg-support-agent/versions/2.0.6 | repo=dingdawg-agent-1; install=dingdawg-support-agent

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | mcp_registry:io.github.dingdawg/dingdawg-support-agent:2.0.6 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.dingdawg%2Fdingdawg-support-agent/versions/2.0.6 | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.dingdawg/dingdawg-support-agent:2.0.6 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.dingdawg%2Fdingdawg-support-agent/versions/2.0.6 | last_activity_observed missing

## 4. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | mcp_registry:io.github.dingdawg/dingdawg-support-agent:2.0.6 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.dingdawg%2Fdingdawg-support-agent/versions/2.0.6 | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | mcp_registry:io.github.dingdawg/dingdawg-support-agent:2.0.6 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.dingdawg%2Fdingdawg-support-agent/versions/2.0.6 | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.dingdawg/dingdawg-support-agent:2.0.6 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.dingdawg%2Fdingdawg-support-agent/versions/2.0.6 | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.dingdawg/dingdawg-support-agent:2.0.6 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.dingdawg%2Fdingdawg-support-agent/versions/2.0.6 | release_recency=unknown

<!-- canonical_name: dingdawg/dingdawg-agent-1; human_manual_source: deepwiki_human_wiki -->
