TradingAgents-CN v1.0.1 提示词模板与多智能体偏好系统设计全解:数据库、27 个 API 与版本管理实战方案
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):
- 用户管理面板:用户信息展示与编辑;
- 偏好管理面板:偏好列表、编辑表单、选择器与预览;
- 模板配置面板:按 Agent 查看/绑定用户模板;
- 模板编辑器:支持五段式内容编辑、草稿/启用切换、长度提示;
- 历史记录面板:分页展示版本历史、恢复确认;
- 版本对比面板:双版本差异可视化与统计。
七、设计原则与规模对比
五项设计原则
- 最小化改动:复用现有系统、扩展而不是重写、向后兼容;
- 用户隔离:每个用户独立配置、数据完全隔离、权限管理;
- 灵活性:支持多种偏好、自定义模板、版本管理;
- 可扩展性:模块化设计、易于添加新 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 下的关键文档,可对照深入阅读:
- README.md:快速开始入口;
- INTEGRATION_WITH_EXISTING_SYSTEM.md:与现有用户系统集成设计;
- DATABASE_AND_USER_MANAGEMENT.md:数据库、用户管理、模板生命周期与数据流设计;
- ENHANCED_API_DESIGN.md:27 个 API 端点的完整请求/响应定义;
- ENHANCED_IMPLEMENTATION_ROADMAP.md:9 阶段实现计划与里程碑;
- PROMPT_TEMPLATE_SYSTEM_SUMMARY.md:提示词模板系统总体方案总结;
- EXTENDED_AGENTS_SUPPORT.md:13 个 Agent 模板规划;
- FRONTEND_UI_DESIGN.md:6 个前端 UI 组件设计。
同时可结合仓库源码 app/models/user.py(现有 User / UserPreferences 模型)与 app/services/user_service.py(现有用户服务层)对照理解"基于现有系统扩展"的设计落点。该设计当前版本为 v1.0.1,状态为"设计完成",下一步为按路线图启动 Phase 1 实现。