TradingAgents-CN 提示词模板系统 v1.0.1 设计全解析:多智能体分析偏好、模板版本管理与 27 个 RESTful API

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

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/ 目录下,分为四组:

分组 文档数 代表文档
核心功能设计 6 份 ENHANCEMENT_SUMMARY.md、INTEGRATION_WITH_EXISTING_SYSTEM.md、ENHANCED_API_DESIGN.md、FRONTEND_UI_DESIGN.md
系统设计 7 份 EXTENDED_AGENTS_SUPPORT.md、AGENT_TEMPLATE_SPECIFICATIONS.md、prompt_template_system_design.md
实现指南 6 份 prompt_template_implementation_guide.md、prompt_template_technical_spec.md、QUICK_REFERENCE.md
总结文档 2 份 FINAL_SUMMARY.md、README.md

设计规模汇总如下:

指标 数量
设计文档 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 分析师集成方式

每个分析师在初始化时执行四步:

  1. 接收 template_name 参数;
  2. 通过 PromptTemplateManager 加载模板;
  3. 将模板内容注入提示词;
  4. 运行时使用自定义提示词执行分析。

快速参考中的集成代码形态如下:

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 自增,不设并发冲突检测,依靠历史记录支持对比与回滚。

生效优先级(运行时解析模板的顺序):

  1. 查找 user_template_configs 中匹配 (user_id, agent_type, agent_name, preference_id) 且 is_active = true 的配置 → 命中则使用其指向的用户模板;
  2. 若用户无配置 → 按 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(- 旧值 / + 新值、逐字段差异) 恢复到旧版本、关闭

三条关键交互流程:

  1. 用户选择偏好:进入偏好管理 → 查看三种偏好 → 选择默认 → 系统保存 → 后续 Agent 使用该偏好的模板;
  2. 用户编辑模板:进入模板编辑器 → 修改内容 → 保存 → 系统创建新版本 → 记录修改历史 → 返回成功提示;
  3. 用户对比版本:进入历史记录 → 选择两个版本 → 对比 → 展示差异 → 可选恢复。

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 最佳实践

  1. 默认模板优先:大多数场景使用 default 模板,降低调优成本;
  2. A/B 测试:通过模板对比功能对比不同模板,找到最优方案;
  3. 版本控制:保留模板历史,便于回滚与审计;
  4. 文档注释:在模板中清楚说明用途,维护团队可读性;
  5. 标签分类:使用 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 逐项推进实现。

登录后查看全文
TradingAgents-CN