ai-exchange/docs/archive/AI_ICT_research_council脚手架与数据表草案_v1.md

AI_ICT research_council 脚手架与数据表草案 v1

1. 文档目标

本草案用于明确：

1. research_council 目录结构应如何搭建
2. 每个模块的职责边界是什么
3. 数据表与 migration 初稿应如何命名
4. 如何避免和现有 AI_ICT 主链冲突

---

2. 目录脚手架建议

src/services/research_council/
├── __init__.py
├── council_context_builder.py
├── council_orchestrator.py
├── council_schema.py
├── council_output_formatter.py
├── council_mapper_service.py
├── council_memory_service.py
├── council_checkpoint_service.py
├── tradingagents_adapter.py
├── debate_service.py
└── agents/
    ├── structure_analyst.py
    ├── risk_analyst.py
    ├── news_event_analyst.py
    ├── visual_analyst.py
    ├── bull_researcher.py
    ├── bear_researcher.py
    └── research_manager.py

---

3. 模块职责

3.1 council_context_builder.py

职责：

• 读取 AI_ICT 已有结构化事实
• 生成 council 输入上下文

必须只读消费：

• market_state
• trading_plan
• candidate
• signal
• risk_result
• trust_policy
• visual_review
• operator_notes
• journal / weekly review

禁止：

• 自己重算 market truth
• 自己生成平行 readiness / trust

3.2 tradingagents_adapter.py

职责：

• 适配 TradingAgents 的编排、结构化输出、checkpoint/memory 思路
• 屏蔽掉不适用的股票数据入口

禁止：

• 直接暴露 yfinance / alpha_vantage 作为主事实源

3.3 debate_service.py

职责：

• 统一整理支持 / 反对理由
• 生成分歧点与 follow-up checks

3.4 council_mapper_service.py

职责：

• 将 council 结果映射到：
  • decision_packet
  • review_packet
  • workbench
  • visual_watch 建议项

3.5 council_memory_service.py

职责：

• 读写 lesson store
• 读取相似历史经验
• 回填历史复盘数据

3.6 council_checkpoint_service.py

职责：

• 管理 council 运行中断恢复
• 提供 replay / resume 支撑

---

4. 数据表草案

4.1 research_council_runs

建议 migration：

• 036_create_research_council_runs.sql

建议字段：

• id
• instrument_id
• trading_plan_id
• candidate_id
• signal_id
• decision_packet_id
• status
• committee_confidence
• summary_text
• payload_json
• created_ts
• updated_ts

用途：

• 记录一次 council 运行的总结果

4.2 research_council_messages

建议 migration：

• 037_create_research_council_messages.sql

建议字段：

• id
• run_id
• agent_role
• message_type
• payload_json
• created_ts

用途：

• 记录各角色输出

4.3 research_council_links

建议 migration：

• 038_create_research_council_links.sql

建议字段：

• id
• run_id
• trading_plan_id
• candidate_id
• signal_id
• decision_packet_id
• execution_ticket_id
• created_ts

用途：

• 连接 council run 与主链对象

4.4 research_council_lessons

建议 migration：

• 039_create_research_council_lessons.sql

建议字段：

• id
• instrument_id
• session_code
• setup_type
• lesson_type
• importance_score
• summary_text
• source_type
• source_ref
• payload_json
• created_ts

用途：

• 持久化结构化经验

4.5 research_council_checkpoints

建议 migration：

• 040_create_research_council_checkpoints.sql

建议字段：

• id
• run_id
• step_name
• checkpoint_payload
• status
• updated_ts

用途：

• 管理中断恢复

---

5. repository 草案

建议新增：

• src/repositories/research_council_run_repository.py
• src/repositories/research_council_message_repository.py
• src/repositories/research_council_link_repository.py
• src/repositories/research_council_lesson_repository.py
• src/repositories/research_council_checkpoint_repository.py

---

6. 脚本草案

建议新增：

• scripts/run_research_council.py
• scripts/run_research_council_replay.py
• scripts/run_research_council_backfill_lessons.py
• scripts/run_research_council_eval.py

---

7. 测试草案

建议新增：

• tests/unit/test_research_council_imports.py
• tests/unit/test_research_council_context_builder.py
• tests/unit/test_research_council_schema.py
• tests/unit/test_research_council_analysts.py
• tests/unit/test_research_council_orchestrator.py
• tests/unit/test_research_council_runtime_integration.py
• tests/unit/test_research_council_decision_packet_fields.py

---

8. 边界守卫

以下规则必须在脚手架阶段就固定：

1. council 不重写主事实层
2. council 不重写 risk_result
3. council 不重写 execution_allowed
4. council 不替代 DecisionPacketService 主裁决
5. council 不引入第二套 readiness / trust

---

9. 推荐落地顺序

1. 先落目录与 schema
2. 再落 context builder
3. 再落最小 analysts / orchestrator
4. 再落 runs / messages / links 三张表
5. 再落 lessons / checkpoints
6. 最后接入 runtime / packet / workbench