TradingAgents-CN v1.0.1 提示词模板与多智能体偏好系统设计全解:数据库、27 个 API 与版本管理实战方案

原创2026-09-09 21:19:481,709 阅读
文章标签:金融科技多智能体AI Agent人工智能大模型后端前端数据分析

TradingAgents-CN v1.0.1 提示词模板与多智能体偏好系统设计全解:数据库、27 个 API 与版本管理实战方案

本篇技术指南围绕 TradingAgents-CN 开源仓库中 v1.0.1 版本的最终设计说明(docs/design/v1.0.1/FINAL_DESIGN_NOTES.md)展开,系统解析"提示词模板系统 + 用户分析偏好系统"从数据库建模、用户管理到 API 与前端 UI 的完整设计方案。读者读完本指南后,将掌握该设计如何在既有用户体系上以最小改动扩展出多 Agent 个性化分析能力,理解 5 个新增 MongoDB 集合、27 个 RESTful 端点、模板版本回滚机制的设计动机,并可直接按集成步骤与实现路线图在仓库中落地推进。


一、设计背景:基于现有系统,而非推倒重来

v1.0.1 设计的第一条原则是"基于现有系统的设计"。初版设计没有考虑项目已有的用户系统,v1.0.1 对此进行了纠正:通过创建 INTEGRATION_WITH_EXISTING_SYSTEM.md 文档,明确了与既有用户体系的集成方式。

其关键约束与设计要点如下:

  • 复用现有的 users 集合:不新建用户表,而是在既有用户体系之上做扩展;
  • 扩展现有的 UserPreferences 字段:在嵌入式偏好文档中追加分析偏好相关字段;
  • 最小化对现有代码的改动:保持现有认证、用户 CRUD 逻辑不动;
  • 完全向后兼容:存量用户无需任何数据迁移即可继续使用,新功能作为可选能力存在。

这套思路可以从仓库现有代码中得到印证:app/models/user.py 中 User 模型(_id、username、email、hashed_password、is_active、is_verified、is_admin、时间戳、preferences 嵌入式文档、配额与统计字段、favorite_stocks 列表)与设计文档描述的"现有用户模型"完全一致;app/services/user_service.py 中的 create_user、authenticate_user、update_user、list_users 等即设计文档所指的"现有用户系统"服务层。也就是说,v1.0.1 的全部新能力都是在这套已上线的用户体系上"叠加"出来的。

二、数据库设计优化:从 SQL 到 MongoDB 文档模型

设计团队对数据层做了三项重要决策:

  • 从 SQL 设计改为 MongoDB 文档设计:与项目现有技术栈(MongoDB 数据库 tradingagents)保持一致;
  • 使用 ObjectId 而不是 UUID:原生复用 MongoDB 主键类型,仓库中 app/models/user.py 通过 PyObjectId = Annotated[ObjectId, BeforeValidator(validate_object_id), PlainSerializer(serialize_object_id, return_type=str)] 实现了 ObjectId 的校验与序列化,设计中的新集合同样沿用该约定;
  • 支持嵌入式文档 + 完整的索引设计:偏好、模板内容等结构化数据以嵌套文档存储,并为高频查询字段建立索引。

新增 5 个集合

集合 职责
analysis_preferences 分析偏好(激进/中性/保守)
prompt_templates 提示词模板(系统模板 + 用户模板)
user_template_configs 用户-模板-偏好绑定配置
template_history 模板修改历史与版本
template_comparison 版本对比记录

1. analysis_preferences(分析偏好)

{
    _id: ObjectId,
    user_id: ObjectId,        // 关联到 users._id
    preference_type: String,  // 'aggressive', 'neutral', 'conservative'
    description: String,
    risk_level: Number,               // 0.0-1.0
    confidence_threshold: Number,     // 0.0-1.0
    position_size_multiplier: Number, // 0.5-2.0
    decision_speed: String,           // 'fast', 'normal', 'slow'
    is_default: Boolean,
    created_at: DateTime,
    updated_at: DateTime
}

索引设计:

db.analysis_preferences.createIndex({ user_id: 1 });
db.analysis_preferences.createIndex({ user_id: 1, preference_type: 1 }, { unique: true });
db.analysis_preferences.createIndex({ user_id: 1, is_default: 1 });

其中 (user_id, preference_type) 的唯一复合索引保证"同一用户同类型偏好只有一条",从数据层面杜绝重复。

2. prompt_templates(模板存储)

{
    _id: ObjectId,
    agent_type: String,      // 'analysts', 'researchers', 'debators', 'managers', 'trader'
    agent_name: String,      // 具体 Agent 名称,如 fundamentals_analyst
    template_name: String,
    preference_type: String, // 'aggressive'/'neutral'/'conservative',null 表示通用
    content: {
        system_prompt: String,
        tool_guidance: String,
        analysis_requirements: String,
        output_format: String,
        constraints: String
    },
    is_system: Boolean,            // true=系统模板,false=用户自定义
    created_by: ObjectId,          // 系统模板为 null
    base_template_id: ObjectId,    // 用户模板克隆自哪个系统模板
    base_version: Number,          // 克隆时的系统模板版本号(用于后续对比提醒)
    status: String,                // 'draft' | 'active'
    created_at: DateTime,
    updated_at: DateTime,
    version: Number                // 当前版本号
}

索引:

db.prompt_templates.createIndex({ agent_type: 1, agent_name: 1 });
db.prompt_templates.createIndex({ is_system: 1 });
db.prompt_templates.createIndex({ created_by: 1 });
db.prompt_templates.createIndex({ preference_type: 1 });

3. user_template_configs(用户模板配置)

{
    _id: ObjectId,
    user_id: ObjectId,     // 关联 users._id
    agent_type: String,
    agent_name: String,
    template_id: ObjectId,   // 关联 prompt_templates._id
    preference_id: ObjectId, // 关联 analysis_preferences._id
    is_active: Boolean,
    created_at: DateTime,
    updated_at: DateTime
}

索引((user_id, agent_type, agent_name) 唯一,保证每个用户每个 Agent 只有一份生效配置):

db.user_template_configs.createIndex({ user_id: 1 });
db.user_template_configs.createIndex({ user_id: 1, agent_type: 1, agent_name: 1 }, { unique: true });
db.user_template_configs.createIndex({ template_id: 1 });

4. template_history(模板修改历史)

{
    _id: ObjectId,
    template_id: ObjectId,     // 关联 prompt_templates._id
    user_id: ObjectId,         // 系统模板为 null
    version: Number,
    content: { /* 与 prompt_templates.content 相同的五段结构 */ },
    change_description: String,
    change_type: String,       // 'create', 'update', 'delete', 'restore'
    created_at: DateTime
}

索引:

db.template_history.createIndex({ template_id: 1, version: 1 });
db.template_history.createIndex({ template_id: 1, created_at: -1 });

5. template_comparison(模板对比记录)

{
    _id: ObjectId,
    user_id: ObjectId,
    template_id_1: ObjectId,
    template_id_2: ObjectId,
    version_1: Number,
    version_2: Number,
    differences: [
        {
            field: String,      // 如 system_prompt
            old_value: String,
            new_value: String,
            change_type: String // 'added', 'removed', 'modified'
        }
    ],
    created_at: DateTime
}

数据模型关系

users (1) ──→ (N) analysis_preferences
users (1) ──→ (N) user_template_configs
users (1) ──→ (N) prompt_templates (created_by)
users (1) ──→ (N) template_history (user_id)
users (1) ──→ (N) template_comparison (user_id)

prompt_templates (1) ──→ (N) template_history
prompt_templates (1) ──→ (N) user_template_configs
prompt_templates (1) ──→ (N) template_comparison

analysis_preferences (1) ──→ (N) user_template_configs
template_history (1) ──→ (N) template_comparison

三、用户管理策略:扩展现有 UserPreferences

设计文档明确给出了方案 1(扩展现有 preferences 字段)作为推荐方案:在 UserPreferences 中仅追加两个字段,即可把分析偏好系统接入现有用户模型,无需修改 User 主模型、无需大规模数据库迁移:

# 在现有 preferences 中添加
class UserPreferences(BaseModel):
    # 现有字段...
    analysis_preference_type: str = "neutral"          # 默认中性
    analysis_preference_id: Optional[str] = None        # 关联到 analysis_preferences._id

该方案的优点在设计中被明确列出:无需修改现有 User 模型、最小化数据库迁移、保持向后兼容。备选方案 2(创建独立集合)灵活性更高,但需要额外维护关联关系。

从仓库现状看,app/models/user.py 中 UserPreferences 已具备 default_market(默认 "A股")、default_depth(默认 "3")、default_analysts(默认 ["市场分析师", "基本面分析师"])、auto_refresh、refresh_interval、ui_theme、sidebar_width、language、通知类开关等字段,与设计文档中"现有偏好设置"清单一致;analysis_preference_type / analysis_preference_id 属于 v1.0.1 设计新增字段,是本文档描述的设计内容,尚未落入现有模型。

分析偏好系统:3 种预设偏好 + 可配置参数

{
    preference_type: 'aggressive' | 'neutral' | 'conservative',
    risk_level: 0.0-1.0,
    confidence_threshold: 0.0-1.0,
    position_size_multiplier: 0.5-2.0,
    decision_speed: 'fast' | 'normal' | 'slow'
}

系统特性:

  • 用户可创建多个偏好(激进、中性、保守可并存);
  • 支持设置默认偏好(is_default);
  • 与模板配置关联(user_template_configs 通过 preference_id 绑定偏好)。

三种偏好在各 Agent 上的语义差异:

偏好 分析师 研究员 辩手 交易员
激进 (Aggressive) 更激进的评分标准 更看好的观点 更激进的风险评估 更大的仓位建议
中性 (Neutral) 中立的评分标准 平衡的观点 中立的风险评估 适中的仓位建议
保守 (Conservative) 保守的评分标准 更看空的观点 保守的风险评估 较小的仓位建议

模板语义、生命周期与生效优先级

设计文档对模板运行期语义做了细致规定,这是整个系统可用的关键:

  • 系统模板(is_system = true, created_by = null):由系统/管理员创建维护,普通用户只能查看不能直接修改,作为"示例模板"与默认兜底模板;
  • 用户模板(is_system = false, created_by = user_id):用户在界面上"基于示例模板新建"时克隆一份系统模板归自己所有,每个用户拥有独立副本,只能编辑自己创建的模板;
  • 生效优先级:先查 user_template_configs 中是否存在匹配 (user_id, agent_type, agent_name, preference_id) 且 is_active = true 的配置,命中则使用其指向的用户模板;未配置则按 agent_type + agent_name + preference_type 回退到系统默认模板,保证"每个 Agent + 偏好组合至少有一份系统默认模板可用";
  • 草稿 vs 启用:status: 'draft' | 'active',草稿用于暂存未启用内容(可多份,不参与 user_template_configs 绑定),"保存并启用"才置为 active 并更新配置记录;
  • 更新策略:同一用户多次编辑同一模板采用直接覆盖(最后一次保存为当前版本),每次保存都在 template_history 新增一条记录且 version 自增,不引入并发冲突检测,依赖历史记录支持对比与回滚。

四、模板版本管理:修改可追踪、可回滚、可对比

版本管理是 v1.0.1 的核心增强之一,对应 template_history 与 template_comparison 两个集合:

  • 自动版本控制:每次修改创建新版本(version 自增);
  • 修改历史追踪:template_history 保存完整历史,change_type 区分 create / update / delete / restore,change_description 记录改动说明;
  • 版本对比:template_comparison 按字段级(system_prompt、tool_guidance、analysis_requirements、output_format、constraints)记录 old_value / new_value / change_type;
  • 回滚功能:恢复到历史版本时会产生一个新的高版本号(而非覆盖旧版本),保证审计链完整。

三条核心数据流(来自 DATABASE_AND_USER_MANAGEMENT.md):

用户选择模板流程:
1. 用户登录 → 2. 获取用户偏好 → 3. 加载用户配置的模板
→ 4. 无配置则加载默认模板 → 5. 按偏好类型加载对应模板 → 6. 返回模板给 Agent

用户修改模板流程:
1. 用户编辑模板 → 2. 验证模板内容 → 3. 保存新版本到数据库
→ 4. 记录修改历史 → 5. 更新用户配置 → 6. 返回成功响应

模板对比流程:
1. 用户选择两个版本 → 2. 从数据库获取两个版本内容
→ 3. 执行差异对比 → 4. 保存对比记录 → 5. 返回对比结果

配额与限制(软约束)

  • 每个用户在同一 (agent_type, agent_name, preference_id) 组合下:active 模板 1 个(由 user_template_configs 唯一索引保证),draft 模板建议 3~5 个(后台可调);
  • 超出上限时 API 层返回友好错误码(如 400 + 明确提示),管理后台可提供"一键清理过期草稿";
  • 单个模板 content.* 各字段总长度建议控制在 32KB~64KB 以内:避免超长 Prompt 拖慢模型响应或超出上下文窗口,同时降低存储与网络压力;实现上在 API 层做长度校验、前端编辑器实时显示长度/占比提示。

五、API 设计:27 个 RESTful 端点

v1.0.1 设计了完整的 API 面,共 27 个端点,按功能分为 6 类(完整接口定义见 ENHANCED_API_DESIGN.md)。

用户管理(4 个)

POST   /api/v1/users
GET    /api/v1/users/{user_id}
PUT    /api/v1/users/{user_id}
DELETE /api/v1/users/{user_id}

偏好管理(6 个)

POST   /api/v1/users/{user_id}/preferences
GET    /api/v1/users/{user_id}/preferences
GET    /api/v1/users/{user_id}/preferences/{preference_id}
PUT    /api/v1/users/{user_id}/preferences/{preference_id}
DELETE /api/v1/users/{user_id}/preferences/{preference_id}
POST   /api/v1/users/{user_id}/preferences/{preference_id}/set-default

创建偏好的请求示例:

POST /api/v1/users/{user_id}/preferences
{
    "preference_type": "conservative",
    "description": "保守型投资偏好",
    "risk_level": 0.3,
    "confidence_threshold": 0.8,
    "position_size_multiplier": 0.5,
    "decision_speed": "slow",
    "is_default": true
}

模板管理(6 个)

POST   /api/v1/templates
GET    /api/v1/templates/{template_id}
PUT    /api/v1/templates/{template_id}
DELETE /api/v1/templates/{template_id}
GET    /api/v1/users/{user_id}/custom-templates
POST   /api/v1/templates/{template_id}/clone

创建自定义模板时提交 agent_type、agent_name、template_name、preference_type、五段式 content 与 status('draft' | 'active');clone 端点用于"基于示例模板新建",返回新模板的 template_id、version: 1。

历史管理(4 个)

GET  /api/v1/templates/{template_id}/history          (page, page_size, sort_by 分页)
GET  /api/v1/templates/{template_id}/history/{version}
POST /api/v1/templates/{template_id}/restore/{version}
POST /api/v1/templates/{template_id}/compare

恢复版本请求示例:

POST /api/v1/templates/{template_id}/restore/{version}
{
    "reason": "Restore to previous working version"
}
// 响应: { "message": "Template restored successfully", "new_version": 4, "restored_from_version": 2 }

版本对比请求与响应:

POST /api/v1/templates/{template_id}/compare
{
    "version_1": 2,
    "version_2": 3
}
// 响应差异数组: [{ "field": "system_prompt", "old_value": "...", "new_value": "...", "change_type": "modified" }]

配置管理(4 个)

GET    /api/v1/users/{user_id}/template-configs
POST   /api/v1/users/{user_id}/template-configs
PUT    /api/v1/users/{user_id}/template-configs/{config_id}
DELETE /api/v1/users/{user_id}/template-configs/{config_id}

统计(3 个)

GET /api/v1/users/{user_id}/statistics
GET /api/v1/templates/{template_id}/statistics
GET /api/v1/users/{user_id}/preferences/{preference_id}/statistics

统计端点分别聚合偏好数、自定义模板数、模板版本数、对比次数、使用该模板的用户数、最常使用的版本等指标。

认证、授权与错误处理

  • 认证头统一使用 Authorization: Bearer {token};
  • 权限规则:用户只能访问自己的数据、管理员可访问所有数据、系统模板只读;
  • 错误码约定:400 参数错误、401 未认证、403 无权限、404 资源不存在、409 冲突(如重复的偏好类型)、500 服务器错误;
  • 统一错误响应格式:{ "error": { "code": "INVALID_REQUEST", "message": "...", "details": {...} } }。

六、前端设计:6 个主要 UI 组件

设计文档规划了 6 个前端组件(详见 FRONTEND_UI_DESIGN.md):

  1. 用户管理面板:用户信息展示与编辑;
  2. 偏好管理面板:偏好列表、编辑表单、选择器与预览;
  3. 模板配置面板:按 Agent 查看/绑定用户模板;
  4. 模板编辑器:支持五段式内容编辑、草稿/启用切换、长度提示;
  5. 历史记录面板:分页展示版本历史、恢复确认;
  6. 版本对比面板:双版本差异可视化与统计。

七、设计原则与规模对比

五项设计原则

  • 最小化改动:复用现有系统、扩展而不是重写、向后兼容;
  • 用户隔离:每个用户独立配置、数据完全隔离、权限管理;
  • 灵活性:支持多种偏好、自定义模板、版本管理;
  • 可扩展性:模块化设计、易于添加新 Agent 与新功能(13 个 Agent 全覆盖);
  • 性能优化:完整的索引设计、Redis 缓存策略(用户偏好/模板/历史记录缓存)、查询优化(分页、异步操作)。

v1.0 → v1.0.1 设计规模对比

指标 v1.0 v1.0.1 增长
设计文档 9 份 21 份 +133%
Agent 支持 4 个 13 个 +225%
预设模板 12 个 31 个 +158%
新增集合 6 个 5 个 -17%
API 端点 未设计 27 个 新增
UI 组件 未设计 6 个 新增
实现阶段 8 个 9 个 +12%
实现任务 155 个 215 个 +39%
预计工期 9 周 11 周 +22%

其中 Agent 覆盖从 4 个分析师(基本面、市场、新闻、社媒)扩展至 13 个 Agent(含研究员、辩手、管理者和交易员),预设模板从 12 个增至 31 个,各 Agent 模板规划详见 PROMPT_TEMPLATE_SYSTEM_SUMMARY.md 与 EXTENDED_AGENTS_SUPPORT.md。

八、集成步骤:5 个脚本从零落地

设计文档给出了可直接执行的 5 步集成流程:

# Step 1: 创建新集合
python scripts/create_template_collections.py

# Step 2: 创建索引
python scripts/create_template_indexes.py

# Step 3: 导入系统模板
python scripts/import_system_templates.py

# Step 4: 创建默认偏好
python scripts/create_default_preferences.py

# Step 5: 创建默认配置
python scripts/create_default_configs.py

与 Agent 侧的集成方式(设计文档给出):

# Agent 初始化时
agent = create_agent(
    agent_type='fundamentals_analyst',
    user_id='user_123',
    preference_type='conservative'
)

# Agent 内部自动加载用户配置的模板
template = template_manager.get_user_template(
    user_id=user_id,
    agent_type=agent_type,
    preference_type=preference_type
)

服务层规划新增 4 个 Service:AnalysisPreferenceService(偏好管理)、PromptTemplateService(系统与用户模板)、UserTemplateConfigService(用户配置)、TemplateHistoryService(历史记录);认证继续复用现有 UserService.authenticate_user()。

九、实现路线图:9 个阶段、11 周、215 个任务

完整路线图见 ENHANCED_IMPLEMENTATION_ROADMAP.md:

阶段 名称 周数 任务数 优先级
Phase 1 基础设施 + 数据库 2 25 🔴 高
Phase 2 用户和偏好管理 1 20 🔴 高
Phase 3 分析师模版 1 25 🔴 高
Phase 4 研究员和辩手模版 1 20 🟡 中
Phase 5 管理者和交易员模版 1 15 🟡 中
Phase 6 历史记录和版本管理 1 20 🟡 中
Phase 7 Web API(完整) 1 35 🔴 高
Phase 8 前端 UI 和集成 2 40 🟡 中
Phase 9 文档和优化 1 15 🟢 低
总计 9 个阶段 11 周 215 -

模板内容的来源路径规划为 prompts/templates/ 目录(如 fundamentals/default.yaml、conservative.yaml、aggressive.yaml),配合 prompts/schema/prompt_template_schema.json 做格式校验,由 PromptTemplateManager 负责加载、缓存、验证、渲染与管理版本;每个分析师的模板规划(4 个分析师示例)为:基本面分析师 default / conservative / aggressive,市场分析师 default / short_term / long_term,新闻分析师 default / real_time / deep,社媒分析师 default / sentiment_focus / trend_focus。

十、关键决策与风险缓解

关键决策问答

为什么选择 MongoDB? 现有系统已使用 MongoDB,文档模型灵活、易于扩展,无需引入第二套存储。

为什么是 3 种偏好? 覆盖大多数用户需求,同时易于理解、使用与实现。

为什么支持版本管理? 用户可以追踪修改、支持回滚、支持对比,是模板系统可信可维护的基础。

为什么是 27 个 API 端点? 覆盖完整 CRUD 操作,支持统计和对比能力,同时保持端点数量可控、易于扩展。

风险与缓解措施

  • 数据迁移风险:需要谨慎处理现有数据 → 缓解:充分的测试、灰度发布;
  • 性能风险:查询与索引需优化 → 缓解:索引设计、Redis 缓存、分页与异步查询;
  • 兼容性风险:需确保向后兼容 → 缓解:复用现有 User 模型、新功能可选、旧数据零迁移。

实现优先级建议:高优先级为数据库设计、用户管理、偏好管理;中优先级为模板管理、API 实现;低优先级为前端 UI、历史记录。

十一、相关文档导航

以下为 v1.0.1 设计文档集中地 docs/design/v1.0.1 下的关键文档,可对照深入阅读:

同时可结合仓库源码 app/models/user.py(现有 User / UserPreferences 模型)与 app/services/user_service.py(现有用户服务层)对照理解"基于现有系统扩展"的设计落点。该设计当前版本为 v1.0.1,状态为"设计完成",下一步为按路线图启动 Phase 1 实现。

登录后查看全文
TradingAgents-CN