TradingAgents-CN 提示词模板系统 v1.0.1 设计全解析:多智能体分析偏好、模板版本管理与 27 个 RESTful API
TradingAgents-CN 提示词模板系统 v1.0.1 设计全解析:多智能体分析偏好、模板版本管理与 27 个 RESTful API
导读
本文以 docs/design/v1.0.1/DESIGN_COMPLETION_SUMMARY.md 为骨架,完整解析 TradingAgents-CN 中「提示词模板系统 v1.0.1 增强版」的整套设计:包括 5 个新增 MongoDB 集合、13 个 Agent 的 31 个预设模板、激进/中性/保守三类分析偏好、模板版本管理与回滚,以及 27 个 RESTful API 端点和 6 个前端组件。读者读完后可以掌握这套多智能体提示词管理系统的数据模型、API 契约、集成策略与实现路线,并能在当前仓库的 tradingagents/agents/analysts 等真实代码结构中找到对应的 Agent 集成落点。
一、设计完成状态与整体规模
提示词模板系统 v1.0.1(增强版)于 2025-01-15 完成设计,共产出 21 份设计文档、约 50,000 字,状态为「🟢 设计完成、待实现」。设计文档分布在 docs/design/v1.0.1/ 目录下,分为四组:
设计规模汇总如下:
| 指标 | 数量 |
|---|---|
| 设计文档 | 21 份 |
| 新增集合 | 5 个 |
| API 端点 | 27 个 |
| UI 组件 | 6 个 |
| Agent 支持 | 13 个 |
| 预设模板 | 31 个 |
| 实现阶段 | 9 个(Phase 1-9) |
| 实现任务 | 215 个 |
| 预计工期 | 11 周 |
说明:本套文档属于「设计完成、待实现」阶段的设计规范,文中所有集合、API、组件均为设计契约;实现时应以 prompt_template_implementation_guide.md 与 IMPLEMENTATION_CHECKLIST.md 为落地依据。
二、核心功能设计概览
系统围绕「为每个分析师智能体提供可配置的提示词模板」这一目标展开,共包含七大核心功能模块。
2.1 数据库存储
- 5 个新增 MongoDB 集合:
analysis_preferences、prompt_templates、user_template_configs、template_history、template_comparison; - 与现有
users集合集成,复用用户体系; - 完整的索引设计(
user_id、agent_type、preference_type、template_id等复合索引); - 通过嵌入式文档、事务与乐观锁保证数据一致性。
2.2 用户管理
- 基于现有
User模型扩展,不重建用户体系; - 支持多用户独立配置、用户隔离与权限控制;
- 新增偏好关联(用户可拥有多个偏好并设置默认偏好)。
2.3 分析偏好
- 3 种偏好类型:激进(Aggressive)、中性(Neutral)、保守(Conservative);
- 4 个可配置参数:
risk_level(风险等级 0.0-1.0)、confidence_threshold(信心阈值 0.0-1.0)、position_size_multiplier(仓位倍数 0.5-2.0)、decision_speed(决策速度 fast/normal/slow); - 用户可创建多个偏好,支持设置默认偏好。
2.4 模板管理
- 系统模板 31 个预设,覆盖 13 个 Agent;
- 用户自定义模板(基于系统模板克隆副本,用户间互不共享);
- 模板版本管理与模板对比功能。
2.5 历史记录
- 自动版本控制(每次保存 version 自增);
- 修改历史追踪(
change_type:create/update/delete/restore); - 版本对比(逐字段差异高亮)与回滚功能。
2.6 Web API
- 27 个 RESTful 端点,覆盖用户、偏好、模板、配置、历史、统计六类资源;
- 完整 CRUD 操作、Bearer Token 认证授权、统一错误响应格式。
2.7 前端 UI
- 6 个主要组件:用户管理面板、偏好管理面板、模板配置面板、模板编辑器、历史记录面板、版本对比面板;
- 模块化组件 + 响应式设计(桌面三栏 / 平板两栏 / 手机单栏)。
三、系统架构与模板文件格式
3.1 目录结构
设计文档 prompt_template_system_design.md 给出了模板定义与代码的目录规划:
prompts/
├── templates/ # 模板定义
│ ├── fundamentals/ # 基本面分析师模板
│ │ ├── default.yaml # 默认模板
│ │ ├── conservative.yaml # 保守模板
│ │ └── aggressive.yaml # 激进模板
│ ├── market/ # 市场分析师模板
│ ├── news/ # 新闻分析师模板
│ └── social/ # 社媒分析师模板
├── schema/ # 模板 schema 定义
│ └── prompt_template_schema.json
└── README.md
tradingagents/
├── config/
│ └── prompt_manager.py # 提示词管理器
└── agents/
└── analysts/
└── prompt_templates.py # 提示词模板工具函数
从当前仓库源码看,tradingagents/agents/ 下确实按分析师类型组织代码:tradingagents/agents/analysts 包含 fundamentals_analyst.py、market_analyst.py、news_analyst.py、social_media_analyst.py 等,tradingagents/agents/researchers、tradingagents/agents/trader、tradingagents/agents/managers 分别对应研究员、交易员与经理角色——与设计中的 agent_type 取值(analysts/researchers/debators/managers/trader)一一对应,可以推断模板系统将以这些现有 Agent 类为集成目标。
3.2 模板 YAML 格式
每个模板以 YAML 文件定义,包含元信息与五段提示词内容:
# prompts/templates/fundamentals/default.yaml
version: "1.0"
analyst_type: "fundamentals"
name: "基本面分析 - 默认模版"
description: "标准的基本面分析提示词"
created_at: "2024-01-01"
tags: ["default", "fundamentals"]
# 系统提示词 - 定义分析师角色和职责
system_prompt: |
你是一位专业的股票基本面分析师。
[详细的系统提示词内容]
# 工具调用指导 - 指导如何使用工具
tool_guidance: |
1. 立即调用 get_stock_fundamentals_unified 工具
2. 等待工具返回真实数据
[详细的工具使用指导]
# 分析要求 - 具体的分析维度
analysis_requirements: |
- 基于真实数据进行深度基本面分析
- 计算并提供合理价位区间
[详细的分析要求]
# 输出格式 - 期望的输出结构
output_format: |
# 公司基本信息
## 财务数据分析
## 估值指标分析
[详细的输出格式]
# 约束条件 - 禁止和强制要求
constraints:
forbidden:
- "不允许假设数据"
- "不允许编造信息"
required:
- "必须调用工具"
- "必须使用中文"
设计还明确了模板中的动态变量,渲染时注入:
{ticker}- 股票代码{company_name}- 公司名称{market_name}- 市场名称{currency_name}- 货币名称{currency_symbol}- 货币符号{current_date}- 当前日期{start_date}- 开始日期{tool_names}- 可用工具列表
3.3 核心模块:PromptTemplateManager
class PromptTemplateManager:
"""提示词模版管理器"""
def __init__(self, template_dir: str):
"""初始化管理器"""
def load_template(self, analyst_type: str, template_name: str) -> Dict:
"""加载指定的模版"""
def list_templates(self, analyst_type: str) -> List[Dict]:
"""列出某个分析师的所有模版"""
def save_custom_template(self, analyst_type: str, template: Dict) -> str:
"""保存自定义模版"""
def get_template_versions(self, analyst_type: str, template_name: str) -> List[Dict]:
"""获取模版版本历史"""
def validate_template(self, template: Dict) -> bool:
"""验证模版格式"""
对应地,QUICK_REFERENCE.md 给出了管理器在 tradingagents.config.prompt_manager 下的调用示例(load_template / list_templates / render_template / get_template_versions / save_custom_template),这是实现阶段「模版加载 → 变量渲染 → 注入 Agent」调用链的核心入口。
3.4 分析师集成方式
每个分析师在初始化时执行四步:
- 接收
template_name参数; - 通过
PromptTemplateManager加载模板; - 将模板内容注入提示词;
- 运行时使用自定义提示词执行分析。
快速参考中的集成代码形态如下:
from tradingagents.config.prompt_manager import PromptTemplateManager
manager = PromptTemplateManager()
template = manager.load_template("fundamentals", "default")
analyst = create_fundamentals_analyst(
llm=llm,
toolkit=toolkit,
template_name="conservative"
)
# 渲染模板变量
rendered = manager.render_template(
template,
ticker="000001",
company_name="平安银行"
)
3.5 13 个 Agent 的模板矩阵
设计为 13 个 Agent 提供 31 个预设模板,其中 4 类分析师各提供 3 套模板:
| Agent 类型 | 模板 1 | 模板 2 | 模板 3 |
|---|---|---|---|
| 基本面分析师 (fundamentals) | default 标准基本面分析 | conservative 保守估值分析 | aggressive 激进成长分析 |
| 市场分析师 (market) | default 标准技术分析 | short_term 短期交易分析 | long_term 长期趋势分析 |
| 新闻分析师 (news) | default 标准新闻分析 | real_time 实时新闻快速分析 | deep 深度新闻影响分析 |
| 社媒分析师 (social) | default 标准情绪分析 | sentiment_focus 情绪导向分析 | trend_focus 趋势导向分析 |
prompt_templates 集合设计中的 agent_type 取值范围为 'analysts', 'researchers', 'debators', 'managers', 'trader',agent_name 具体到 Agent 名称(如 fundamentals_analyst),每个「Agent + 偏好」组合保证至少一份系统默认模板可用。
四、与现有系统的集成设计
4.1 现有系统基线
设计文档 INTEGRATION_WITH_EXISTING_SYSTEM.md 明确了集成基线:
- 现有用户系统位于 app/models/user.py 与 app/services/user_service.py;
- 数据库为 MongoDB(库名 tradingagents),集合
users; - 认证采用密码哈希,现有
UserService.authenticate_user()直接复用,无需修改; - 现有
User模型已包含preferences: UserPreferences嵌入式文档,以及daily_quota、concurrent_limit、total_analyses、favorite_stocks等字段。
现有 UserPreferences 字段包括 default_market、default_depth、default_analysts、auto_refresh、refresh_interval、ui_theme、language、notifications_enabled 等。
4.2 两种集成方案
方案 1:扩展现有 preferences 字段(推荐)
无需修改现有表结构、改动最小,代价是 preferences 字段会变大:
class UserPreferences(BaseModel):
# 现有字段...
default_market: str = "A股"
default_depth: str = "3"
default_analysts: List[str] = []
auto_refresh: bool = True
refresh_interval: int = 30
ui_theme: str = "light"
language: str = "zh-CN"
notifications_enabled: bool = True
# 新增字段 - 分析偏好
analysis_preference_type: str = "neutral" # 'aggressive', 'neutral', 'conservative'
analysis_preference_id: Optional[str] = None # 关联到 analysis_preferences._id
方案 2:创建独立集合(灵活性更高)
完全独立、易于扩展,代价是需要维护关联关系:
db.createCollection('analysis_preferences');
db.createCollection('prompt_templates');
db.createCollection('user_template_configs');
db.createCollection('template_history');
db.createCollection('template_comparison');
4.3 集成点清单
| 集成点 | 处理方式 |
|---|---|
| 用户认证 | 复用现有 UserService.authenticate_user(),无需修改 |
| 用户信息 | 使用现有 User 模型,扩展 UserPreferences 添加分析偏好字段 |
| 用户偏好 | 新增 AnalysisPreferenceService |
| 模板管理 | 新增 PromptTemplateService |
| 用户配置 | 新增 UserTemplateConfigService |
| 历史记录 | 新增 TemplateHistoryService |
4.4 迁移步骤
# Step 1: 在 MongoDB 中创建新集合
db.createCollection('analysis_preferences');
db.createCollection('prompt_templates');
db.createCollection('user_template_configs');
db.createCollection('template_history');
db.createCollection('template_comparison');
# 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
从当前仓库看,scripts/import_config_and_create_user.py 已展示了「配置导入 + 用户创建」的脚本模式,模板系统的迁移脚本可沿用同样的结构与执行方式。
五、数据库集合设计与数据模型
设计文档 DATABASE_AND_USER_MANAGEMENT.md 给出了 5 个新增集合的完整字段与索引设计。
5.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 });
5.2 prompt_templates(模板存储)
{
_id: ObjectId,
agent_type: String, // 'analysts', 'researchers', 'debators', 'managers', 'trader'
agent_name: String, // 具体 Agent 名称
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, // 关联 users._id,系统模板为 null
base_template_id: ObjectId, // 用户模板的来源系统模板 ID
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 });
5.3 user_template_configs(用户模板配置)
{
_id: ObjectId,
user_id: ObjectId,
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 唯一索引保证同一组合只有一条生效配置):
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 });
5.4 template_history(修改历史)
{
_id: ObjectId,
template_id: ObjectId,
user_id: ObjectId, // 系统模板为 null
version: Number,
content: { /* 与模板 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.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,
old_value: String,
new_value: String,
change_type: String // 'added', 'removed', 'modified'
}
],
created_at: DateTime
}
5.6 数据模型关系图
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
关键关系:一个用户可有多个偏好;一个用户可为多个 Agent 配置模板;每个模板有完整修改历史;用户配置通过 preference_id 关联特定偏好。
5.7 模板语义、生命周期与生效优先级
设计对模板语义做了明确区分,这是「用户定制」与「系统兜底」并存的关键:
- 系统模板(
is_system = true,created_by = null):由系统/管理员维护,普通用户只读,作为示例与默认兜底; - 用户模板(
is_system = false,created_by = user_id):用户在界面「基于示例模板新建」时克隆一份系统模板作为自己的独立副本,用户间不共享同一条记录; - 草稿 vs 启用:
status: 'draft' | 'active',草稿用于暂存未启用内容(可多份),「保存并启用」时才更新user_template_configs; - 更新策略:同一用户多次编辑采用直接覆盖(最后一次保存为当前版本),每次保存向
template_history追加记录、version自增,不设并发冲突检测,依靠历史记录支持对比与回滚。
生效优先级(运行时解析模板的顺序):
- 查找
user_template_configs中匹配(user_id, agent_type, agent_name, preference_id)且is_active = true的配置 → 命中则使用其指向的用户模板; - 若用户无配置 → 按
agent_type + agent_name + preference_type回退到系统默认模板。
5.8 配额与内容长度限制(软约束)
- 每个用户在同一
(agent_type, agent_name, preference_id)组合下:active模板 1 个(由唯一索引保证),draft模板建议 3~5 个(后台可配置); - 单个模板
content.*字段总长度建议控制在 32KB~64KB 以内,避免超长 Prompt 拖慢模型响应或超出上下文窗口;实现上在 API 层做长度校验,在前端编辑器实时显示长度/占比提示。
六、27 个 RESTful API 端点设计
设计文档 ENHANCED_API_DESIGN.md 定义了完整的 API 契约,按资源划分为六组,合计 27 个端点。
6.1 用户管理 API(4 个)
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/users |
创建用户 |
| GET | /api/v1/users/{user_id} |
获取用户信息 |
| PUT | /api/v1/users/{user_id} |
更新用户信息 |
| DELETE | /api/v1/users/{user_id} |
删除用户 |
创建用户示例:
POST /api/v1/users
Content-Type: application/json
{
"username": "john_doe",
"email": "john@example.com"
}
Response 201:
{
"user_id": "uuid",
"username": "john_doe",
"email": "john@example.com",
"created_at": "2025-01-15T10:00:00Z"
}
6.2 分析偏好 API(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
Content-Type: application/json
{
"preference_type": "conservative",
"description": "保守型投资偏好",
"risk_level": 0.3,
"confidence_threshold": 0.8,
"position_size_multiplier": 0.5,
"decision_speed": "slow",
"is_default": true
}
Response 201: 包含 preference_id 及全部参数字段的偏好详情
6.3 模板配置 API(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} |
删除配置 |
设置模板配置时,请求体携带 agent_type、agent_name、template_id、preference_id 四个关联字段,例如 agent_type: "analysts"、agent_name: "fundamentals_analyst"。
6.4 模板管理 API(4 个)
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/templates |
创建自定义模板 |
| PUT | /api/v1/templates/{template_id} |
更新模板(版本自增) |
| GET | /api/v1/users/{user_id}/custom-templates |
获取用户自定义模板(支持 agent_type / preference_type 过滤与分页) |
| POST | /api/v1/templates/{template_id}/clone |
克隆模板 |
创建自定义模板时,content 为五段结构(system_prompt / tool_guidance / analysis_requirements / output_format / constraints),status 支持 'draft' 与 'active';每次更新必须携带 change_description,响应中的 version 会自增。
6.5 模板历史 API(5 个)
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/templates/{template_id}/history |
获取历史列表(分页、按创建时间倒序) |
| GET | /api/v1/templates/{template_id}/history/{version} |
获取特定版本内容 |
| POST | /api/v1/templates/{template_id}/restore/{version} |
恢复到特定版本 |
| POST | /api/v1/templates/{template_id}/compare |
对比两个版本 |
| GET | /api/v1/users/{user_id}/template-comparisons |
获取用户对比历史 |
版本对比请求与响应示例:
POST /api/v1/templates/{template_id}/compare
Content-Type: application/json
{
"version_1": 2,
"version_2": 3
}
Response 200:
{
"comparison_id": "uuid",
"template_id": "uuid",
"version_1": 2,
"version_2": 3,
"differences": [
{
"field": "system_prompt",
"old_value": "...",
"new_value": "...",
"change_type": "modified"
}
],
"created_at": "2025-01-15T10:00:00Z"
}
版本恢复示例:
POST /api/v1/templates/{template_id}/restore/{version}
Content-Type: application/json
{
"reason": "Restore to previous working version"
}
Response 200:
{
"message": "Template restored successfully",
"new_version": 4,
"restored_from_version": 2
}
6.6 统计 API(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 |
使用该偏好的 Agent 数、关联模板数、最后使用时间 |
6.7 认证、授权与错误处理
- 认证头:
Authorization: Bearer {token}; - 权限规则:用户只能访问自己的数据,管理员可访问所有数据,系统模板只读;
- 错误码:400(参数错误)、401(未认证)、403(无权限)、404(资源不存在)、409(冲突,如重复偏好类型)、500(服务器错误);
- 统一错误响应格式:
{
"error": {
"code": "INVALID_REQUEST",
"message": "Invalid request parameters",
"details": {}
}
}
七、前端 UI 设计(6 个组件)
设计文档 FRONTEND_UI_DESIGN.md 规划了 6 个核心组件与三条主要交互流程。
7.1 组件清单与核心交互
| 组件 | 核心功能 | 关键操作 |
|---|---|---|
| 用户管理面板 | 查看/编辑用户信息、删除账户、用户统计 | 编辑、删除、管理偏好 |
| 分析偏好管理面板 | 三种偏好卡片展示(含风险等级进度条、信心阈值、仓位倍数、决策速度) | 选择、编辑、删除、新建、设为默认 |
| 模板配置面板 | 按 Agent 分组展示当前模板与偏好 | 更改模板、编辑、预览 |
| 模板编辑器 | 五段内容的多行文本编辑(系统提示词/工具指导/分析要求/输出格式/约束) | 保存、取消、预览、历史 |
| 历史记录面板 | 版本列表(版本号/修改说明/修改者/时间) | 查看、恢复、对比 |
| 版本对比面板 | 双版本并排 diff(- 旧值 / + 新值、逐字段差异) |
恢复到旧版本、关闭 |
三条关键交互流程:
- 用户选择偏好:进入偏好管理 → 查看三种偏好 → 选择默认 → 系统保存 → 后续 Agent 使用该偏好的模板;
- 用户编辑模板:进入模板编辑器 → 修改内容 → 保存 → 系统创建新版本 → 记录修改历史 → 返回成功提示;
- 用户对比版本:进入历史记录 → 选择两个版本 → 对比 → 展示差异 → 可选恢复。
7.2 响应式与设计规范
- 桌面版(1200px+):三栏布局;平板版(768px-1199px):两栏 + 折叠菜单;手机版(<768px):单栏 + 抽屉菜单;
- 颜色方案:主色
#2196F3(蓝)、成功#4CAF50(绿)、警告#FF9800(橙)、错误#F44336(红)、中立#9E9E9E(灰); - 字体层级:标题 18px 粗体 / 正文 14px / 小字 12px;间距 8/16/24px 三级。
八、数据流与使用流程
8.1 用户选择模板流程
1. 用户登录
↓
2. 获取用户偏好
↓
3. 加载用户配置的模板
↓
4. 如果没有配置,加载默认模板
↓
5. 根据偏好类型加载对应模板
↓
6. 返回模板给 Agent
8.2 用户修改模板流程
1. 用户编辑模板
↓
2. 验证模板内容
↓
3. 保存新版本到数据库
↓
4. 记录修改历史
↓
5. 更新用户配置
↓
6. 返回成功响应
8.3 模板对比流程
1. 用户选择两个版本
↓
2. 从数据库获取两个版本内容
↓
3. 执行差异对比
↓
4. 保存对比记录
↓
5. 返回对比结果
8.4 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
)
九、关键设计决策与性能考量
9.1 关键设计决策
- 与现有系统集成:复用现有
users集合、扩展UserPreferences字段、最小化改动、保证向后兼容(现有用户无需修改,新功能可选); - 数据模型:MongoDB 文档模型 + 灵活嵌入式文档 + 完整关系设计 + 性能优化索引;
- API 设计:RESTful 风格、标准 HTTP 方法、统一响应格式、完整错误处理;
- 前端设计:模块化组件、响应式布局、用户友好、完整交互流程。
9.2 权限模型
class Permission:
# 模板权限
- view_template: 查看模板
- edit_template: 编辑模板
- delete_template: 删除模板
- create_template: 创建模板
- share_template: 分享模板
# 历史权限
- view_history: 查看历史
- restore_version: 恢复版本
- compare_versions: 对比版本
# 偏好权限
- manage_preferences: 管理偏好
- set_default_preference: 设置默认偏好
规则:用户只能编辑自己的模板;系统模板只读;管理员可管理所有模板;用户只能查看自己的历史。
9.3 性能优化
- 缓存策略:用户偏好、模板、历史记录均可用 Redis 缓存;
- 索引优化:
user_id、agent_type、preference_type、template_id四类核心索引; - 查询优化:连接查询减少访问次数、分页处理大数据量、异步操作处理耗时任务;
- 数据一致性:事务保证写入一致、乐观锁防止并发冲突。
十、实现路线图与下一步
10.1 九阶段实现路线
设计文档 ENHANCED_IMPLEMENTATION_ROADMAP.md 将 215 个任务分为 9 个 Phase、预计 11 周:
| 阶段 | 内容 | 工期 |
|---|---|---|
| Phase 1-2 | 基础设施(集合、索引、DAO 层) | 3 周 |
| Phase 3-5 | 模板创建与 Agent 集成 | 3 周 |
| Phase 6-7 | 历史记录与 Web API | 2 周 |
| Phase 8-9 | 前端 UI 与性能优化 | 3 周 |
相比原 9 周 155 个任务的计划,增强版增加 2 周、60 个任务(新增数据库、偏好、历史、API、前端能力)。四阶段实现优先级为:Phase 1 创建模板存储结构与管理器 → Phase 2 集成到分析师代码 → Phase 3 创建 Web API → Phase 4 前端集成与文档。
10.2 后续版本规划
- v1.2 计划支持模板继承与高级功能;
- 实现阶段的后续步骤包括:创建数据库迁移脚本、实现 DAL/BLL、实现 API、前端集成、单元与集成测试(详见 IMPLEMENTATION_CHECKLIST.md)。
10.3 立即可做的行动
- 审查 21 份设计文档(推荐顺序见 README.md);
- 获取利益相关者反馈、确认实现优先级;
- 准备开发环境、分配开发资源、制定详细计划。
十一、快速参考与最佳实践
11.1 常用 API 快速命令
# 列出基本面分析师的所有模板
curl http://localhost:8000/api/prompts/templates/fundamentals
# 获取默认模板
curl http://localhost:8000/api/prompts/templates/fundamentals/default
# 预览模板(渲染变量)
curl -X POST http://localhost:8000/api/prompts/templates/fundamentals/default/preview \
-H "Content-Type: application/json" \
-d '{"variables": {"ticker": "000001", "company_name": "平安银行"}}'
11.2 常见任务代码形态
# 任务1: 使用保守模板分析
analyst = create_fundamentals_analyst(llm, toolkit, template_name="conservative")
result = analyst(state)
# 任务2: 对比两个模板(A/B 测试)
analyst_a = create_market_analyst(llm, toolkit, "short_term")
analyst_b = create_market_analyst(llm, toolkit, "long_term")
# 任务3: 创建自定义模板
custom = {
"version": "1.0",
"analyst_type": "fundamentals",
"name": "我的模版",
"system_prompt": "...",
"tool_guidance": "...",
"analysis_requirements": "...",
"output_format": "...",
"constraints": {...}
}
manager.save_custom_template("fundamentals", custom)
# 任务4: 获取模板版本历史
versions = manager.get_template_versions("fundamentals", "default")
11.3 最佳实践
- 默认模板优先:大多数场景使用 default 模板,降低调优成本;
- A/B 测试:通过模板对比功能对比不同模板,找到最优方案;
- 版本控制:保留模板历史,便于回滚与审计;
- 文档注释:在模板中清楚说明用途,维护团队可读性;
- 标签分类:使用 tags 分类管理模板,便于查找。
11.4 常见问题速答
- 如何修改现有模板? 编辑对应 YAML 文件,或通过更新 API(携带
change_description)完成; - 如何回滚到旧版本? 调用
manager.rollback_template(analyst_type, name, version)或历史恢复 API; - 自定义模板保存在哪里? 持久化到 MongoDB
prompt_templates集合; - 模板变量如何注入? 使用
manager.render_template(template, **variables)渲染后再交给 Agent; - 支持多语言吗? 可以创建不同语言的模板,通过标签区分。
总结
提示词模板系统 v1.0.1 是一套面向多智能体 LLM 交易框架的完整提示词治理方案:它用 5 个 MongoDB 集合把「分析偏好 → 模板 → 用户配置 → 历史版本 → 对比记录」串成闭环,用 27 个 RESTful API 暴露全部 CRUD 与统计能力,用 6 个前端组件提供可视化编辑与版本对比体验,并通过「系统模板兜底 + 用户模板优先」的生效优先级保证了向后兼容与多用户隔离。21 份设计文档(约 5 万字)为落地实现提供了从数据模型到前端交互的完整契约,建议结合 QUICK_REFERENCE.md 快速上手、以 IMPLEMENTATION_CHECKLIST.md 逐项推进实现。