概述

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

技术架构

整体架构图

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

目录结构

核心功能模块

1. 用户引导流程 (Onboarding)

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

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

#### @handle 唯一标识

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

2. 代理市场 (Explore)

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

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

3. 管理仪表板 (Dashboard)

#### CEO 仪表板

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

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

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

#### 系统管理面板

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

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

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

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

4. 集成管理 (Integrations)

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

"即将推出"区域显示待开发的集成功能，用户可通过配置模态框进行连接、断开、测试和 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 的公开元数据格式，用于在外部平台展示代理信息。

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

安全与合规

数据隐私

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

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

服务条款

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

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

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

错误处理

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

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

安装步骤

# 克隆仓库
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 文件：

常见问题

代理响应延迟

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

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

排查步骤：

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

@Handle 不可用

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

集成连接失败

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

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

See Also

• 架构文档
• API 参考文档
• 部署指南
• 贡献指南

前提条件

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

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

整体流程概览

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

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 是否可用：

// Handle 验证状态类型
type HandleStatus = 
  | '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

第三步：配置业务时间

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

// 业务时间配置结构
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 提供多种套餐等级以满足不同规模企业的需求：

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

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

第五步：Agent 激活与部署

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

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 都有一个对应的公开展示页面，包含以下核心元素：

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

管理后台概览

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

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 的能力边界：

支持的集成类型

集成健康检查

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

// 集成健康检查结果结构
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;
}

资料来源：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 进行程序化交互
• 高级配置：探索安全设置、自我修复机制等高级功能
• 模板开发：学习如何创建自定义的行业模板

相关链接

• 入职引导流程
• Agent 管理后台
• 集成配置指南
• API 参考文档
• 隐私政策

1. 架构概述

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

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

2. 技术栈概览

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

资料来源：gateway/frontend/src/app/layout.tsx、gateway/isg_agent/config.py

3. 前端架构

3.1 应用结构

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

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、gateway/frontend/src/app/explore/page.tsx

3.2 核心页面模块

资料来源：gateway/frontend/src/app/integrations/page.tsx、gateway/frontend/src/app/admin/system/page.tsx

3.3 认证与状态管理

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

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

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

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

return <ExploreContent />;

资料来源：gateway/frontend/src/app/explore/page.tsx

4. 后端架构

4.1 应用入口

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

# 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

4.2 配置管理系统

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

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

@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

4.3 API 路由结构

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

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]

集成路由模块结构：

"""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

5. 数据模型

5.1 Agent 实体

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

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

5.2 订阅层级

平台支持四级订阅体系：

资料来源：gateway/frontend/src/app/onboarding/page.tsx

6. 集成系统

6.1 集成模块架构

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

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 集成提供语音代理能力，支持多种语音模型：

配置参数包括：

• Vapi API Key：VAPI 平台密钥
• Voice Model：语音模型选择
• Status：连接状态
• last_webhook：最后接收的 Webhook 时间戳

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

资料来源：gateway/frontend/src/components/integrations/IntegrationConfigModal.tsx

6.3 Webhook 管理

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

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

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

资料来源：gateway/frontend/src/app/integrations/page.tsx

7. 监控与自愈系统

7.1 系统状态监控

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

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

7.2 自愈机制

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

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

自愈功能包括：

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

资料来源：gateway/frontend/src/app/admin/system/page.tsx

8. 引导流程架构

8.1 用户引导步骤

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

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

8.2 引导状态管理

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

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

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、gateway/frontend/src/app/onboarding/page.tsx

8.3 @Handle 策略

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

资料来源：gateway/frontend/src/app/terms/page.tsx

9. 监控仪表盘

9.1 CEO 仪表盘

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

<!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

9.2 产品与支付管理

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

资料来源：gateway/frontend/src/app/dashboard/ceo/page.tsx

10. 安全机制

10.1 认证与授权

系统采用多层认证机制：

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

# 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

10.3 隐私与数据保护

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

资料来源：gateway/frontend/src/app/privacy/page.tsx

11. 公共 API

11.1 公开代理卡片

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

<!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

11.2 API 端点

12. 常见故障与排查

12.1 集成连接失败

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

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

12.2 引导流程中断

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

12.3 自测试失败

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

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

资料来源：gateway/frontend/src/app/admin/system/page.tsx

13. See Also

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

数据流与状态管理

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

七大创新特性

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

概述

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

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

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

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

安全架构总览

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

配置验证机制

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

资料来源：gateway/isg_agent/config.py:100-150

@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 平台实施了分层认证机制，确保只有经过验证的用户才能访问相应功能：

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

数据安全保护

用户数据分类

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

资料来源：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 管理后台提供了全面的安全状态监控功能：

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 面板查看各安全组件的实时状态：

{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

自愈机制

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

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

集成安全

第三方服务认证

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

资料来源：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 合规要求：

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

使用量限制

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

// 使用量紧迫度计算
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 配置

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

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 永久性政策来维护系统安全：

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

用户责任

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

1. 确保账户信息安全且及时更新
2. 不与他人共享账户凭证
3. 发现可疑活动时立即通知 [email protected]
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. 备份策略：确保数据库和配置的定期备份

常见安全问题排查

相关文档

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

• 快速入门指南 - 了解平台基本使用方法
• API 参考文档 - 完整的 API 接口说明
• 配置参考 - 详细的环境变量配置说明
• 部署指南 - 生产环境部署最佳实践

概述

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

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

核心配置架构

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

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

业务运营配置

营业时间限制

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

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

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

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

{(["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

行业领域选择

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

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

资料来源：gateway/frontend/src/app/onboarding/page.tsx

技能与能力配置

模板系统

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

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

资料来源：gateway/frontend/src/components/onboarding/OnboardingChatStream.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

技能激活状态

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

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

资料来源：gateway/frontend/src/components/dashboard/DashboardHeader.tsx

安全与治理配置

系统健康监控

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

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

资料来源：gateway/frontend/src/app/admin/system/page.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

安全层级

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

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

安全层级展示组件：

{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）功能，用于自动恢复系统故障。

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

资料来源：gateway/frontend/src/app/admin/system/page.tsx

自愈机制的工作流程：

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

集成配置

第三方服务集成

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

资料来源：gateway/frontend/src/app/integrations/page.tsx

Webhook 配置

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

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

#### Webhook 状态显示

<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 成功率显示：

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

集成配置模态框

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

<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

配置工作流

代理创建流程

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

完整配置流程

配置管理界面

仪表板概览

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

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

资料来源：gateway/frontend/src/components/dashboard/DashboardHeader.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. 查看自愈日志中的自动恢复记录

相关文档

• 系统管理指南
• 集成配置参考
• 安全配置白皮书
• 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

概述

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）：向上层应用提供统一的模型调用接口

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基类，定义了标准接口：

OpenAI Provider

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

配置参数：

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。

智能路由机制

路由策略

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

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_ 为前缀：

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

日志级别配置

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

# 验证器实现
@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模型的实时状态：

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

LLM提供商状态

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

// 错误率展示示例
{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回调
• 测试连接状态

// 资料来源：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使用量：

// 资料来源：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;

用量警告

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

安全考虑

密钥管理

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

# 资料来源：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实现完全本地化部署：

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

最佳实践

模型选择指南

成本优化策略

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

故障排除

常见问题

健康检查端点

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

GET /api/v1/admin/system/health

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

相关文档

• 系统架构概览
• 集成服务配置
• 安全加固指南
• API参考文档

技术栈概述

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

核心框架

样式系统

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

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

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

页面结构

页面层级概览

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 与其他解决方案的对比

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

#### 核心功能

#### 代理数据结构

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

管理后台

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

系统管理页面

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

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

#### 监控指标

#### 自测试功能

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

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

<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

#### 功能特性

{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

#### 集成状态展示

引导流程

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

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

引导步骤流程

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

营业时间配置

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

<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>

模板选择

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

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

核心组件库

错误边界组件

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

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

#### 组件状态

#### 错误展示格式

<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>

仪表板头部组件

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

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

#### 统计数据展示

#### 集成指示器

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

{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

#### 支持的集成类型

#### 语音模型选项

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

#### 数据类型

法律信息页面

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

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

运营页面

营销活动页面

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

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

#### 活动状态

#### 活动数据结构

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

独立仪表板

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

资料来源：dashboard/index.html:1-20

<!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 的新特性构建。

主题与样式规范

颜色系统

组件样式规范

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

状态管理

认证状态

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

const { isAuthenticated } = useAuthStore();

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

API 状态管理

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

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 文档
• 数据库架构
• 身份认证系统
• 第三方集成指南

Pitfall Log / 踩坑日志

项目：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