681 lines
29 KiB
Plaintext
681 lines
29 KiB
Plaintext
# AI PaaS 商业平台 - Qoder 开发规格文档
|
||
|
||
|
||
## 一、文档用途说明
|
||
|
||
本文档是为 **Qoder 1.0**（阿里云智能体自主开发工作台）准备的完整项目开发规格说明。Qoder 已从 AI IDE 升级为智能体自主开发工作台，支持 **Quest 模式**（自主编程）、**Agent 模式**（智能体协作）和 **Repo Wiki**（项目知识库）。你只需将本文档作为项目上下文投喂给 Qoder，即可启动 AI 自主开发流程。
|
||
|
||
**使用方式**：
|
||
1. 在 Qoder 中创建新项目，导入本文档作为项目规格
|
||
2. 开启 **Quest 模式**，将各模块作为独立 Quest 派发给 Agent 团队
|
||
3. Agent 团队将“自动驾驶”，自主完成执行、验证和交付全流程任务
|
||
|
||
|
||
## 二、项目概述
|
||
|
||
### 2.1 项目名称
|
||
**AI PaaS 商业平台** —— 面向个人用户的 AI 能力服务平台
|
||
|
||
### 2.2 核心业务能力
|
||
| 能力模块 | 说明 |
|
||
|---------|------|
|
||
| **Agent（智能体）** | 用户创建、部署、管理自己的 AI Agent |
|
||
| **MCP（模型上下文协议）** | 支持 MCP 协议的 AI 服务接入 |
|
||
| **Skills（技能市场）** | 用户发布、购买、使用 AI 技能 |
|
||
| **IM Bot（即时通讯机器人）** | 支持微信、QQ、钉钉等平台的 AI 机器人 |
|
||
| **CLI（命令行工具）** | 开发者友好的命令行接口 |
|
||
| **ACP（Agent通信协议）** | Agent 间通信协议 |
|
||
| **AI 产品交易平台** | AI 产品的交易市场 |
|
||
|
||
### 2.3 开发策略：核心自研 + 开源集成
|
||
|
||
| 策略 | 适用模块 | 说明 |
|
||
|------|---------|------|
|
||
| **核心自研** | 能力注册中心、LLM Provider Router、计费引擎、Skills市场、交易平台 | 平台核心竞争力，必须自研 |
|
||
| **开源集成** | 认证授权、API网关、Agent编排、向量数据库 | 利用成熟开源项目，避免重复造轮子 |
|
||
|
||
|
||
## 三、总体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 接入层 (Access Layer) │
|
||
│ Web Dashboard │ REST API │ WebSocket │ CLI │ IM Bot │ SDK │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ API Gateway (Apache APISIX) │
|
||
│ 认证鉴权(JWT/API Key) │ 限流熔断 │ 路由转发 │ 协议转换 │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 标准化中间件层 (Core Middleware) — 核心自研 │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ 能力注册中心 │ │ LLM Provider │ │ 用量追踪与 │ │ 计费引擎 │ │
|
||
│ │ (Capability │ │ Router │ │ 计费系统 │ │ (订阅/Token) │ │
|
||
│ │ Registry) │ │ │ │ │ │ │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ AI 能力层 (AI Capability Layer) │
|
||
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
|
||
│ │ Agent │ │ MCP │ │ Skills │ │ IM │ │ 知识库 │ │ 交易 │ │
|
||
│ │ 编排 │ │ Server │ │ 市场 │ │ Bot │ │ (RAG) │ │ 平台 │ │
|
||
│ │(LangFlow)│(自研) │ │(自研) │ │(自研) │ │(集成) │ │(自研) │ │
|
||
│ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 基础设施层 (Infrastructure) │
|
||
│ 容器编排(K8s) │ PostgreSQL │ Redis │ Kafka │ Milvus/Qdrant │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
|
||
## 四、技术选型总览
|
||
|
||
| 层级 | 组件 | 技术选型 | 选型理由 |
|
||
|------|------|---------|---------|
|
||
| **API网关** | 统一入口 | **Apache APISIX 3.15+** | 云原生、高性能、支持AI代理插件 |
|
||
| **认证授权** | 身份管理 | **Keycloak 26.6+** | 功能全面，支持OAuth 2.0/OIDC，零宕机更新 |
|
||
| **Agent编排** | 可视化工作流 | **LangFlow 1.10+** | 低代码AI工作流构建，支持MCP互操作 |
|
||
| **向量数据库** | RAG检索 | **Milvus 2.6+ / Qdrant 1.18+** | Milvus适合大规模生产；Qdrant性价比高 |
|
||
| **主数据库** | 业务数据 | **PostgreSQL** | 成熟稳定，支持多租户行级隔离 |
|
||
| **缓存** | 性能加速 | **Redis** | 高性能内存数据库 |
|
||
| **消息队列** | 异步处理 | **Apache Kafka** | 高吞吐，适合用量追踪等场景 |
|
||
| **容器编排** | 部署管理 | **Kubernetes** | 业界标准 |
|
||
| **可观测性** | 监控告警 | **Prometheus + Grafana + OpenTelemetry** | 开源标准组合 |
|
||
| **支付集成** | 支付网关 | **统一支付SDK** | 一套API集成支付宝、微信、Stripe |
|
||
|
||
|
||
## 五、模块详细规格
|
||
|
||
### 5.1 平台底座（Platform Foundation）
|
||
|
||
#### 5.1.1 用户认证与授权（集成 Keycloak）
|
||
|
||
**任务目标**：集成 Keycloak 实现统一的用户认证与授权。
|
||
|
||
**技术要求**：
|
||
- 部署 Keycloak 26.6+
|
||
- 配置 OAuth 2.0 / OIDC 协议支持
|
||
- 实现 JWT 令牌签发与验证（RS256）
|
||
- 支持社交登录（GitHub、Google 等）
|
||
- 实现 RBAC 权限模型
|
||
- 支持 API Key 认证（为 CLI/SDK 提供）
|
||
|
||
**Qoder 开发指令**：
|
||
> “在项目中集成 Keycloak 26.6+，配置 OAuth 2.0 授权服务器。实现 Spring Security / 自定义过滤器验证 JWT 令牌。设计 RBAC 角色体系（admin、user、developer）。实现 API Key 的生成、存储和验证逻辑。”
|
||
|
||
#### 5.1.2 多租户架构（核心自研）
|
||
|
||
**任务目标**：实现基于 tenant_id 的行级隔离多租户架构。
|
||
|
||
**技术要求**：
|
||
- 所有数据表包含 `tenant_id` 字段
|
||
- 数据库查询自动添加 `tenant_id = current_tenant_id()` 过滤条件
|
||
- 租户创建时自动初始化默认配置
|
||
- 支持租户禁用/启用/注销
|
||
|
||
**数据模型**：
|
||
```sql
|
||
-- 租户表
|
||
CREATE TABLE tenants (
|
||
id UUID PRIMARY KEY,
|
||
name VARCHAR(255) NOT NULL,
|
||
plan_type VARCHAR(50) DEFAULT 'free', -- free | pro | enterprise
|
||
status VARCHAR(20) DEFAULT 'active',
|
||
created_at TIMESTAMP DEFAULT NOW(),
|
||
updated_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
-- 所有业务表均包含 tenant_id 外键
|
||
```
|
||
|
||
**Qoder 开发指令**：
|
||
> “实现多租户架构，采用行级隔离方案。所有业务表包含 tenant_id 字段。实现 TenantContext 线程上下文传递 tenant_id。数据库层实现自动租户过滤。提供租户管理 API（创建、查询、禁用、注销）。”
|
||
|
||
#### 5.1.3 用户 Dashboard（自研）
|
||
|
||
**任务目标**：为每个用户提供独立的工作台。
|
||
|
||
**功能模块**：
|
||
| 模块 | 功能 |
|
||
|------|------|
|
||
| 使用统计 | API调用次数、Token消耗、各能力使用分布 |
|
||
| 账单管理 | 月度账单、消费明细、发票下载 |
|
||
| 配置管理 | API Key管理、Webhook配置、通知设置 |
|
||
| 能力管理 | 已订阅能力列表、使用配额、到期时间 |
|
||
|
||
**Qoder 开发指令**：
|
||
> “开发用户 Dashboard 后端 API 和前端页面。后端使用 [语言] 实现统计聚合查询、账单查询、配置管理接口。前端使用 React/Vue 3 + Ant Design 实现仪表盘页面。”
|
||
|
||
#### 5.1.4 管理后台（自研）
|
||
|
||
**任务目标**：为平台运营人员提供管理后台。
|
||
|
||
**功能模块**：
|
||
| 模块 | 功能 |
|
||
|------|------|
|
||
| 用户管理 | 租户创建/禁用/注销、权限分配 |
|
||
| 系统监控 | 服务健康检查、QPS监控、错误告警 |
|
||
| 内容审核 | Skills发布审核、Agent合规检查 |
|
||
| 计费管理 | 套餐配置、定价调整、订单管理 |
|
||
|
||
**Qoder 开发指令**：
|
||
> “开发管理后台，包含用户管理、系统监控、内容审核、计费管理四个核心模块。与 Keycloak 管理 API 集成实现用户权限管理。”
|
||
|
||
|
||
### 5.2 标准化中间件（核心自研 — 平台核心竞争力）
|
||
|
||
#### 5.2.1 能力注册中心（Capability Registry）
|
||
|
||
**任务目标**：实现 AI 能力的标准化注册、发现和版本管理。
|
||
|
||
**Capability 元数据模型**：
|
||
```json
|
||
{
|
||
"capability_id": "skill_001",
|
||
"name": "智能摘要",
|
||
"type": "skill", // agent | mcp | skill | imbot | knowledge
|
||
"version": "v1.2.0",
|
||
"description": "基于大模型的文本摘要生成",
|
||
"tags": ["nlp", "summary", "llm"],
|
||
"endpoint": "/api/v1/capabilities/skill_001/invoke",
|
||
"protocol": "rest", // rest | websocket | grpc
|
||
"dependencies": ["llm-provider/deepseek-v3"],
|
||
"pricing": {
|
||
"model": "token_based",
|
||
"price_per_1k_tokens": 0.001
|
||
},
|
||
"owner": "user_123",
|
||
"status": "active" // active | deprecated | beta
|
||
}
|
||
```
|
||
|
||
**功能清单**：
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 动态注册 | 支持能力的热注册，无需重启服务 |
|
||
| 动态注销 | 支持能力的热注销 |
|
||
| 版本管理 | 语义化版本控制（SemVer），多版本共存 |
|
||
| 依赖管理 | 声明能力间的依赖关系 |
|
||
| 服务发现 | 按类型、标签、名称检索能力 |
|
||
| 状态管理 | active / deprecated / beta 状态流转 |
|
||
|
||
**API 设计**：
|
||
```
|
||
POST /api/v1/capabilities # 注册能力
|
||
DELETE /api/v1/capabilities/{id} # 注销能力
|
||
GET /api/v1/capabilities # 列表查询（支持过滤）
|
||
GET /api/v1/capabilities/{id} # 获取能力详情
|
||
PUT /api/v1/capabilities/{id} # 更新能力
|
||
POST /api/v1/capabilities/{id}/versions # 发布新版本
|
||
```
|
||
|
||
**数据库设计**：
|
||
```sql
|
||
CREATE TABLE capabilities (
|
||
id UUID PRIMARY KEY,
|
||
tenant_id UUID NOT NULL REFERENCES tenants(id),
|
||
name VARCHAR(255) NOT NULL,
|
||
type VARCHAR(50) NOT NULL,
|
||
version VARCHAR(50) NOT NULL,
|
||
description TEXT,
|
||
tags TEXT[],
|
||
endpoint VARCHAR(500),
|
||
protocol VARCHAR(20) DEFAULT 'rest',
|
||
dependencies JSONB,
|
||
pricing JSONB,
|
||
owner_id UUID,
|
||
status VARCHAR(20) DEFAULT 'active',
|
||
created_at TIMESTAMP DEFAULT NOW(),
|
||
updated_at TIMESTAMP DEFAULT NOW(),
|
||
UNIQUE(tenant_id, name, version)
|
||
);
|
||
|
||
CREATE INDEX idx_capabilities_type ON capabilities(type);
|
||
CREATE INDEX idx_capabilities_status ON capabilities(status);
|
||
```
|
||
|
||
**Qoder 开发指令**：
|
||
> “实现能力注册中心服务。定义 Capability 元数据模型。实现 CRUD API。实现基于 etcd 或 PostgreSQL 的注册表存储。实现能力发现和查询接口。这是平台的核心竞争力，请确保代码质量、测试覆盖和文档完善。”
|
||
|
||
#### 5.2.2 API Gateway（集成 Apache APISIX）
|
||
|
||
**任务目标**：部署和配置 Apache APISIX 作为统一 API 网关。
|
||
|
||
**APISIX 版本**：3.15.0+
|
||
|
||
**核心配置需求**：
|
||
| 功能 | APISIX 插件 | 说明 |
|
||
|------|-------------|------|
|
||
| JWT认证 | `jwt-auth` | 验证 JWT 令牌 |
|
||
| API Key认证 | `key-auth` | 验证 API Key |
|
||
| 限流 | `limit-req` / `limit-count` | 按租户/能力限流 |
|
||
| 熔断 | `api-breaker` | 后端服务熔断保护 |
|
||
| 路由转发 | `proxy-rewrite` | 动态路由到不同后端 |
|
||
| 可观测性 | `prometheus` | 指标采集 |
|
||
| AI代理 | `ai-proxy` | 支持多LLM提供商路由 |
|
||
|
||
**APISIX 配置示例**：
|
||
```yaml
|
||
# 路由配置示例
|
||
routes:
|
||
- id: capability-api
|
||
uri: /api/v1/capabilities/*
|
||
plugins:
|
||
jwt-auth: {}
|
||
limit-count:
|
||
count: 1000
|
||
time_window: 60
|
||
key: "consumer_name"
|
||
upstream:
|
||
type: roundrobin
|
||
nodes:
|
||
"capability-service:8080": 1
|
||
```
|
||
|
||
**Qoder 开发指令**：
|
||
> “部署 Apache APISIX 3.15+，配置以下插件：jwt-auth、key-auth、limit-req、api-breaker、proxy-rewrite、prometheus。编写 APISIX 配置文件（config.yaml）和路由配置。实现与能力注册中心联动的动态路由更新机制。”
|
||
|
||
#### 5.2.3 LLM Provider Router（核心自研）
|
||
|
||
**任务目标**：统一对接多个 LLM 提供商，提供 OpenAI 兼容格式的 API。
|
||
|
||
**支持的模型平台**：
|
||
- DeepSeek
|
||
- 千问（Qwen）
|
||
- 豆包（Doubao）
|
||
- 百度文心
|
||
- 元宝
|
||
- 智谱（Zhipu）
|
||
- 本地 Ollama
|
||
|
||
**统一 API 格式**：
|
||
```
|
||
POST /v1/chat/completions
|
||
```
|
||
|
||
**核心功能**：
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 统一接入 | 各厂商API适配为OpenAI兼容格式 |
|
||
| 智能路由 | 根据延迟、成本、上下文自动选择模型 |
|
||
| 故障转移 | 主模型不可用时自动切换备用模型 |
|
||
| 负载均衡 | 多API Key轮询 |
|
||
| 自动重试 | 可配置重试次数和策略 |
|
||
| 缓存机制 | 简单缓存 + 语义缓存 |
|
||
| 熔断保护 | 提供商健康检查，自动隔离 |
|
||
|
||
**Provider 适配器接口**：
|
||
```python
|
||
# Python 示例
|
||
class LLMProvider:
|
||
def __init__(self, config: ProviderConfig):
|
||
self.config = config
|
||
|
||
async def chat_completions(self, request: ChatRequest) -> ChatResponse:
|
||
"""统一聊天补全接口"""
|
||
pass
|
||
|
||
async def health_check(self) -> bool:
|
||
"""健康检查"""
|
||
pass
|
||
```
|
||
|
||
**路由策略配置**：
|
||
```json
|
||
{
|
||
"route_policy": {
|
||
"default": "deepseek-v3",
|
||
"fallback": ["qwen-max", "zhipu-glm-4"],
|
||
"cost_optimization": {
|
||
"enabled": true,
|
||
"max_cost_per_1k_tokens": 0.002
|
||
},
|
||
"latency_optimization": {
|
||
"enabled": false,
|
||
"max_latency_ms": 5000
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Qoder 开发指令**：
|
||
> “实现 LLM Provider Router 服务。设计 Provider 抽象接口，为 DeepSeek、Qwen、Doubao、百度文心、智谱、Ollama 各实现一个适配器。实现智能路由引擎（支持成本优先、延迟优先、故障转移策略）。实现缓存层（Redis）。实现健康检查和熔断机制。提供统一 OpenAI 兼容 API。”
|
||
|
||
#### 5.2.4 用量追踪与计费系统（核心自研）
|
||
|
||
**任务目标**：实时记录 API 调用和 Token 消耗，与计费引擎联动。
|
||
|
||
**追踪维度**：
|
||
| 维度 | 说明 |
|
||
|------|------|
|
||
| 按能力 | 每个 Capability 的调用次数和消耗 |
|
||
| 按模型 | 每个 LLM 模型的 Token 消耗（区分输入/输出） |
|
||
| 按时间 | 实时/日/周/月统计 |
|
||
| 按租户 | 每个用户的汇总消耗 |
|
||
|
||
**数据模型**：
|
||
```sql
|
||
CREATE TABLE usage_records (
|
||
id UUID PRIMARY KEY,
|
||
tenant_id UUID NOT NULL REFERENCES tenants(id),
|
||
capability_id UUID REFERENCES capabilities(id),
|
||
model_name VARCHAR(100),
|
||
input_tokens INTEGER,
|
||
output_tokens INTEGER,
|
||
total_tokens INTEGER,
|
||
request_id VARCHAR(100),
|
||
status VARCHAR(20),
|
||
cost DECIMAL(10, 6),
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_usage_tenant_time ON usage_records(tenant_id, created_at);
|
||
CREATE INDEX idx_usage_capability ON usage_records(capability_id);
|
||
```
|
||
|
||
**计费模式**：
|
||
| 模式 | 说明 |
|
||
|------|------|
|
||
| 订阅制 | 月度/年度订阅，包含不同等级套餐 |
|
||
| Token计费 | 基于 API 调用次数/Token 消耗量计费 |
|
||
| 混合模式 | 基础订阅 + 超出部分按量计费 |
|
||
|
||
**套餐设计**：
|
||
| 套餐 | 价格 | 月Token配额 | 并发限制 |
|
||
|------|------|------------|---------|
|
||
| 免费版 | ¥0 | 10万 | 1 |
|
||
| 专业版 | ¥99/月 | 500万 | 5 |
|
||
| 企业版 | ¥499/月 | 3000万 | 20 |
|
||
|
||
**Qoder 开发指令**：
|
||
> “实现用量追踪和计费系统。设计 usage_records 表，实现异步记录用量（通过 Kafka 削峰填谷）。实现用量聚合查询（按时间、能力、模型维度）。实现计费引擎：订阅计费、Token计费、混合计费三种模式。集成支付网关（支付宝、微信支付、Stripe）。实现账单生成和发票管理。”
|
||
|
||
|
||
### 5.3 AI 能力层
|
||
|
||
#### 5.3.1 Agent 编排（集成 LangFlow）
|
||
|
||
**任务目标**：集成 LangFlow 1.10+ 提供可视化 Agent 编排能力。
|
||
|
||
**LangFlow 能力**：
|
||
- 可视化拖放式工作流构建
|
||
- 多智能体协同和对话管理
|
||
- 内置 API 服务器
|
||
- 支持 MCP 互操作
|
||
- 长期记忆支持（Memory bases）
|
||
|
||
**集成方式**：
|
||
- LangFlow 作为独立服务部署
|
||
- 每个 Agent 作为 Capability 注册到能力注册中心
|
||
- 通过 API Gateway 统一暴露 Agent 调用接口
|
||
|
||
**Qoder 开发指令**：
|
||
> “部署 LangFlow 1.10+ 作为 Agent 编排服务。实现 LangFlow 与平台认证系统的集成（SSO）。实现 Agent 发布流程：将 LangFlow 构建的 Agent 注册为 Capability。实现 Agent 调用日志记录和用量追踪。”
|
||
|
||
#### 5.3.2 MCP Server（自研）
|
||
|
||
**任务目标**：提供 MCP（Model Context Protocol）协议服务的托管与管理能力。
|
||
|
||
**功能清单**：
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 服务注册 | MCP Server 注册为 Capability |
|
||
| 服务发现 | 通过能力注册中心发现 MCP 服务 |
|
||
| 协议代理 | 平台作为 MCP 客户端代理 |
|
||
| 版本管理 | 支持 MCP 协议版本管理 |
|
||
|
||
**Qoder 开发指令**：
|
||
> “实现 MCP Server 托管服务。支持 MCP Server 注册为 Capability。实现 MCP 协议代理（转发请求到注册的 MCP Server）。实现 MCP 服务发现接口。”
|
||
|
||
#### 5.3.3 Skills 市场（核心自研）
|
||
|
||
**任务目标**：实现 AI 技能的发布、审核、交易、版本管理。
|
||
|
||
**Skill 规范**：
|
||
| 要素 | 说明 |
|
||
|------|------|
|
||
| 功能原子性 | 聚焦单一任务 |
|
||
| 接口标准化 | 统一输入/输出格式（JSON Schema） |
|
||
| 环境隔离性 | 容器化部署 |
|
||
|
||
**Skills 市场功能**：
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 技能发布 | 开发者上传 Skill，填写元数据 |
|
||
| 技能审核 | 平台审核内容合规性和质量 |
|
||
| 技能购买 | 用户浏览、购买 Skill |
|
||
| 版本管理 | 支持语义化版本，热更新 |
|
||
| 使用统计 | Skill 调用次数、收益统计 |
|
||
|
||
**商业化模型**：
|
||
- 订阅制：基础免费 + 高级付费
|
||
- 按调用量计费
|
||
- 平台抽成：15%-30%
|
||
|
||
**Qoder 开发指令**：
|
||
> “实现 Skills 市场完整功能。包括 Skill 发布流程（上传、元数据填写）、审核流程（自动化测试+人工审查）、购买流程（支付、授权）、版本管理（SemVer）、调用统计和收益分成。Skill 作为 Capability 注册到能力注册中心。”
|
||
|
||
#### 5.3.4 IM Bot（自研）
|
||
|
||
**任务目标**：支持多平台即时通讯机器人。
|
||
|
||
**支持的平台**：
|
||
- 微信（企业微信/个人微信）
|
||
- QQ
|
||
- 钉钉
|
||
- 飞书
|
||
|
||
**架构**：
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ IM Bot 统一接入层 │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │ 微信适配 │ │ QQ适配 │ │ 钉钉适配 │ │ 飞书适配 │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ 消息路由 & 能力调用 │
|
||
│ (Agent / Skill / Knowledge Base) │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Qoder 开发指令**：
|
||
> “实现 IM Bot 统一接入服务。设计适配器模式，为微信、QQ、钉钉、飞书各实现一个适配器。实现消息路由引擎（根据消息内容路由到对应 Agent/Skill）。实现会话管理（多轮对话上下文）。实现 Webhook 回调配置。”
|
||
|
||
#### 5.3.5 知识库（RAG）（集成向量数据库）
|
||
|
||
**任务目标**：提供文档上传、向量化检索、RAG 问答能力。
|
||
|
||
**技术选型**：
|
||
| 组件 | 推荐 | 说明 |
|
||
|------|------|------|
|
||
| 向量数据库 | Milvus 2.6+或 Qdrant 1.18+ | Milvus适合大规模，Qdrant性价比高 |
|
||
| 嵌入模型 | text-embedding-ada-002 / BGE | 文本向量化 |
|
||
| 文档处理 | Unstructured / LlamaIndex | PDF/Word/HTML解析 |
|
||
| RAG框架 | LangChain / LlamaIndex | 检索增强生成 |
|
||
|
||
**功能清单**：
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 文档上传 | 支持 PDF、Word、HTML、TXT 等格式 |
|
||
| 文档解析 | 自动提取文本内容 |
|
||
| 向量化 | 文本分块并生成向量 |
|
||
| 语义检索 | 基于向量相似度检索 |
|
||
| RAG问答 | 检索 + LLM 生成回答 |
|
||
|
||
**Qoder 开发指令**：
|
||
> “实现知识库 RAG 服务。部署 Milvus/Qdrant 向量数据库。实现文档上传、解析（使用 Unstructured）、分块、向量化（使用嵌入模型）、存储流程。实现语义检索 API。实现 RAG 问答 API（检索 + LLM 生成）。知识库作为 Capability 注册。”
|
||
|
||
#### 5.3.6 AI 产品交易平台（核心自研）
|
||
|
||
**任务目标**：为个人用户提供 AI 产品的交易市场。
|
||
|
||
**交易品类**：
|
||
- AI Agent（完整 Agent 应用）
|
||
- Skills（可复用的 AI 技能模块）
|
||
- Prompt 模板
|
||
- 微调模型
|
||
- 数据集
|
||
|
||
**核心流程**：
|
||
1. **发布**：开发者上传产品，填写元数据、定价
|
||
2. **审核**：平台审核内容合规性和质量
|
||
3. **交易**：用户浏览、购买、支付
|
||
4. **交付**：自动化数字交付（API Key发放、代码下载）
|
||
5. **结算**：平台抽成后结算给开发者
|
||
|
||
**数据模型**：
|
||
```sql
|
||
CREATE TABLE products (
|
||
id UUID PRIMARY KEY,
|
||
tenant_id UUID NOT NULL,
|
||
name VARCHAR(255) NOT NULL,
|
||
type VARCHAR(50) NOT NULL, -- agent | skill | prompt | model | dataset
|
||
description TEXT,
|
||
price DECIMAL(10, 2),
|
||
pricing_model VARCHAR(50), -- one_time | subscription | pay_per_use
|
||
status VARCHAR(20) DEFAULT 'pending', -- pending | approved | rejected | active
|
||
owner_id UUID,
|
||
created_at TIMESTAMP DEFAULT NOW(),
|
||
updated_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
CREATE TABLE orders (
|
||
id UUID PRIMARY KEY,
|
||
product_id UUID REFERENCES products(id),
|
||
buyer_id UUID NOT NULL,
|
||
amount DECIMAL(10, 2),
|
||
status VARCHAR(20), -- pending | paid | delivered | refunded
|
||
payment_id VARCHAR(100),
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
```
|
||
|
||
**Qoder 开发指令**：
|
||
> “实现 AI 产品交易平台。包括商品管理（发布、审核、下架）、订单系统（下单、支付、状态流转）、数字交付（自动发放 API Key/下载链接）、结算系统（平台抽成、开发者结算）、评价体系。集成支付网关。”
|
||
|
||
|
||
## 六、基础设施
|
||
|
||
### 6.1 容器编排（Kubernetes）
|
||
|
||
**部署架构**：
|
||
- 每个微服务独立 Deployment
|
||
- Service 暴露服务
|
||
- Ingress 管理外部访问
|
||
- ConfigMap/Secret 管理配置
|
||
- HPA 自动扩缩容
|
||
|
||
**Qoder 开发指令**：
|
||
> “为每个服务编写 Dockerfile 和 Kubernetes 部署清单（Deployment、Service、Ingress、ConfigMap、Secret）。配置 HPA 自动扩缩容。”
|
||
|
||
### 6.2 可观测性（Prometheus + Grafana + OpenTelemetry）
|
||
|
||
**Qoder 开发指令**：
|
||
> “集成 OpenTelemetry 实现分布式追踪。配置 Prometheus 采集指标。配置 Grafana 仪表盘（服务健康、QPS、延迟、错误率）。配置告警规则。”
|
||
|
||
|
||
## 七、开发阶段与里程碑
|
||
|
||
### 阶段一：平台底座（Week 1-3）
|
||
|
||
| 任务 | 负责人（Qoder Agent） | 产出 |
|
||
|------|----------------------|------|
|
||
| 部署 Keycloak 26.6+ | Agent-Auth | 认证服务就绪 |
|
||
| 实现多租户数据模型 | Agent-DB | 数据库迁移脚本 |
|
||
| 实现用户认证与授权集成 | Agent-Auth | JWT验证过滤器、API Key管理 |
|
||
| 开发用户 Dashboard | Agent-Dashboard | 后端API + 前端页面 |
|
||
| 开发管理后台 | Agent-Admin | 后端API + 前端页面 |
|
||
|
||
### 阶段二：标准化中间件（Week 4-8）
|
||
|
||
| 任务 | 负责人（Qoder Agent） | 产出 |
|
||
|------|----------------------|------|
|
||
| 实现能力注册中心 | Agent-Registry | Capability CRUD API |
|
||
| 部署配置 APISIX | Agent-Gateway | APISIX配置文件 + 路由规则 |
|
||
| 实现 LLM Provider Router | Agent-Router | 多模型适配器 + 路由引擎 |
|
||
| 实现用量追踪系统 | Agent-Usage | 用量记录 + 聚合查询 |
|
||
| 实现计费引擎 | Agent-Billing | 订阅/Token/混合计费 |
|
||
|
||
### 阶段三：AI 能力层（Week 9-16）
|
||
|
||
| 任务 | 负责人（Qoder Agent） | 产出 |
|
||
|------|----------------------|------|
|
||
| 部署集成 LangFlow | Agent-Agent | Agent编排服务 |
|
||
| 实现 MCP Server 托管 | Agent-MCP | MCP协议代理 |
|
||
| 实现 Skills 市场 | Agent-Skills | 发布/审核/购买/版本管理 |
|
||
| 实现 IM Bot | Agent-IM | 多平台机器人适配器 |
|
||
| 实现知识库 RAG | Agent-RAG | 文档上传/向量检索/问答 |
|
||
| 实现交易平台 | Agent-Trade | 商品/订单/支付/结算 |
|
||
|
||
### 阶段四：集成测试与部署（Week 17-20）
|
||
|
||
| 任务 | 负责人（Qoder Agent） | 产出 |
|
||
|------|----------------------|------|
|
||
| 端到端集成测试 | Agent-Test | 测试报告 |
|
||
| 编写部署清单 | Agent-Ops | K8s YAML文件 |
|
||
| 配置可观测性 | Agent-Obs | Prometheus + Grafana |
|
||
| 性能压测 | Agent-Test | 压测报告 |
|
||
|
||
|
||
## 八、Qoder 使用指南
|
||
|
||
### 8.1 项目初始化
|
||
|
||
1. 在 Qoder 中创建新项目
|
||
2. 将本文档上传为 **Repo Wiki**（项目知识库）
|
||
3. 配置 Qoder Rules：
|
||
- 代码规范（使用 [语言] 的编码规范）
|
||
- 测试覆盖率要求（≥80%）
|
||
- API 文档要求（OpenAPI 3.0）
|
||
|
||
### 8.2 Quest 模式使用
|
||
|
||
将每个模块作为独立 **Quest** 派发：
|
||
|
||
```
|
||
Quest 示例：
|
||
"实现能力注册中心服务。要求：
|
||
1. 使用 [语言] 开发
|
||
2. 数据存储使用 PostgreSQL
|
||
3. 提供 RESTful API
|
||
4. 参考本文档 5.2.1 节的数据模型和 API 设计
|
||
5. 编写单元测试，覆盖率 ≥80%
|
||
6. 编写 OpenAPI 文档"
|
||
```
|
||
|
||
### 8.3 Agent 模式使用
|
||
|
||
开启多 Agent 协作模式，并行开发多个模块：
|
||
|
||
```
|
||
Agent 团队配置：
|
||
- Agent-Auth: 负责认证授权模块
|
||
- Agent-Registry: 负责能力注册中心
|
||
- Agent-Router: 负责 LLM Provider Router
|
||
- Agent-Billing: 负责计费系统
|
||
- Agent-Frontend: 负责前端页面
|
||
```
|
||
|
||
### 8.4 代码审查
|
||
|
||
利用 Qoder 的 CodeReview 功能进行代码审查：
|
||
- 每次 Quest 完成后触发自动 CodeReview
|
||
- 人工复核关键模块（能力注册中心、计费引擎）
|
||
|
||
|
||
## 九、成功标准
|
||
|
||
| 维度 | 标准 |
|
||
|------|------|
|
||
| **功能完整性** | 所有 7 个核心能力模块均可运行 |
|
||
| **API 可用性** | 核心 API 成功率 ≥99.9% |
|
||
| **多租户隔离** | 租户数据严格隔离，无数据泄露 |
|
||
| **计费准确性** | 用量记录和计费误差 <0.1% |
|
||
| **LLM 路由** | 支持 ≥5 个 LLM 提供商，故障转移 <3秒 |
|
||
| **代码质量** | 测试覆盖率 ≥80%，无严重安全漏洞 | |