From 771de8c49c4a342bcc22f4e2bdcc0a1444167d84 Mon Sep 17 00:00:00 2001 From: cillin Date: Fri, 3 Apr 2026 13:48:49 +0800 Subject: [PATCH] docs: refresh runtime guidance --- CLAUDE.md | 6 +- docs/CRITICAL_FIXES.md | 239 ---------------------------------- docs/OPTIMIZATION_PLAN.md | 249 ------------------------------------ docs/runtime-api-changes.md | 30 ++++- docs/terminology.md | 11 +- 5 files changed, 34 insertions(+), 501 deletions(-) delete mode 100644 docs/CRITICAL_FIXES.md delete mode 100644 docs/OPTIMIZATION_PLAN.md diff --git a/CLAUDE.md b/CLAUDE.md index 1e8f2dd..15cd912 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -115,7 +115,8 @@ npm run test # Vitest 单元测试 | 文件 | 职责 | |------|------| -| `pipeline.py` | TradingPipeline - 核心编排器（分析→沟通→决策→执行→评估） | +| `pipeline.py` | TradingPipeline - 核心编排器（分析→沟通→决策→执行→评估），支持断点 Checkpoint | +| `apo.py` | PolicyOptimizer - (APO) 自动策略优化器，根据 P&L 自动修改 Agent POLICY.md | | `pipeline_runner.py` | REST API 触发的独立执行，5 阶段启动 | | `scheduler.py` | BacktestScheduler、Scheduler - 回测/实盘调度 | | `state_sync.py` | StateSync - 状态同步和广播 | @@ -168,7 +169,8 @@ backend/ │ └── models.py # ProcessRun、ProcessRunState │ ├── core/ # Pipeline 执行 -│ ├── pipeline.py # TradingPipeline（核心编排器） +│ ├── pipeline.py # TradingPipeline（核心编排器，支持恢复） +│ ├── apo.py # PolicyOptimizer（自动调优） │ ├── pipeline_runner.py # 独立 Pipeline 执行 │ ├── scheduler.py # 调度器 │ └── state_sync.py # 状态同步 diff --git a/docs/CRITICAL_FIXES.md b/docs/CRITICAL_FIXES.md deleted file mode 100644 index f27b002..0000000 --- a/docs/CRITICAL_FIXES.md +++ /dev/null @@ -1,239 +0,0 @@ -# 关键代码修复方案 - -## 1. EvoAgent 长期记忆支持 ✅ - -**状态**: EvoAgent 已支持 `long_term_memory` 参数，但需要移除 Legacy 回退逻辑 - -**需要修改的文件**: -- `backend/main.py` 第 158-176 行 - 移除记忆启用时的 Legacy 回退 -- `backend/core/pipeline.py` - 同样更新 -- `backend/core/pipeline_runner.py` - 同样更新 - -**修复代码** (main.py): -```python -def _create_analyst_agent(...): - # ... 工具包创建代码 ... - - use_evo_agent = analyst_type in _resolve_evo_agent_ids() - - if use_evo_agent: - workspace_dir = skills_manager.get_agent_asset_dir(config_name, analyst_type) - agent_config = load_agent_workspace_config(workspace_dir / "agent.yaml") - agent = EvoAgent( - agent_id=analyst_type, - config_name=config_name, - workspace_dir=workspace_dir, - model=model, - formatter=formatter, - skills_manager=skills_manager, - prompt_files=agent_config.prompt_files, - long_term_memory=long_term_memory, # 已支持 - long_term_memory_mode="static_control", - ) - agent.toolkit = toolkit - setattr(agent, "workspace_id", config_name) - return agent - - # Legacy fallback (deprecated) - return AnalystAgent(...) -``` - -## 2. Workspace ID 语义清理 - -**问题**: `workspace_id` 同时用于 design-time 和 runtime 两个不同概念 - -**修复方案**: - -```python -# backend/api/workspaces.py -# 明确区分两种资源 - -# Design-time workspaces (CRUD) -@router.get("/design-workspaces/{workspace_id}/...") -async def get_design_workspace(workspace_id: str): ... - -# Runtime runs (只读) -@router.get("/runs/{run_id}/agents/{agent_id}/...") -async def get_runtime_agent(run_id: str, agent_id: str): ... -``` - -## 3. ToolGuard 与 Gateway 审批同步 ✅ 已完成 - -**状态**: 审批同步已完善，添加了批量审批支持 - -**API 端点**: -- `POST /api/guard/check` - 检查工具调用是否需要审批 -- `POST /api/guard/approve` - 批准单个工具调用 -- `POST /api/guard/approve/batch` - ✅ 批量批准多个工具调用（新增） -- `POST /api/guard/deny` - 拒绝工具调用 -- `GET /api/guard/pending` - 获取待审批列表 - -**批量审批示例**: -```python -# 批量批准 -await approve_tool_calls( - BatchApprovalRequest( - approval_ids=["approval_001", "approval_002", "approval_003"], - one_time=True, - ) -) -``` - -**超时处理**: 默认 300 秒超时，可在 `ToolGuardMixin._init_tool_guard()` 中配置 - -## 4. Smoke Test 依赖修复 - -**需要的依赖**: -```bash -pip install pandas numpy matplotlib seaborn -pip install finnhub-python yfinance -pip install loguru rich -pip install websockets -pip install httpx requests -pip install PyYAML -pip install pandas-market-calendars exchange-calendars -``` - -## 5. 统一 Agent 工厂 ✅ 已完成 - -**文件** `backend/agents/unified_factory.py`: - -统一工厂已创建，支持： -- 所有 6 种 Agent 角色的创建 -- 自动 EvoAgent vs Legacy Agent 选择 -- Workspace 驱动配置 -- 长期记忆支持 - -```python -from backend.agents.unified_factory import UnifiedAgentFactory, get_agent_factory - -# 使用示例 -factory = UnifiedAgentFactory( - config_name="smoke_fullstack", - skills_manager=skills_manager, -) - -# 创建分析师 -analyst = factory.create_analyst( - analyst_type="fundamentals_analyst", - model=model, - formatter=formatter, - long_term_memory=memory, -) -``` - -## 6. EvoAgent 默认启用 - -**修改** `backend/config/constants.py`: - -```python -# 默认所有角色使用 EvoAgent -DEFAULT_EVO_AGENT_ROLES = { - "fundamentals_analyst", - "technical_analyst", - "sentiment_analyst", - "valuation_analyst", - "risk_manager", - "portfolio_manager", -} - -# EVO_AGENT_IDS 现在用于选择性地禁用 EvoAgent -# 如果设置，只启用指定的角色 -# 如果未设置，启用所有角色 -``` - -**修改** `backend/main.py`: -```python -def _resolve_evo_agent_ids() -> set[str]: - """Return agent ids selected to use EvoAgent. - - By default, all supported roles use EvoAgent. - EVO_AGENT_IDS can be used to limit to specific roles. - """ - from backend.config.constants import DEFAULT_EVO_AGENT_ROLES - - raw = os.getenv("EVO_AGENT_IDS", "") - if raw.strip(): - # Filter to only valid roles - requested = {x.strip() for x in raw.split(",") if x.strip()} - return requested & DEFAULT_EVO_AGENT_ROLES - - # Default: all roles use EvoAgent - return DEFAULT_EVO_AGENT_ROLES -``` - -## 7. 遗留代码清理 - -**可以删除的文件**: -- `backend/agents/compat.py` ✅ 已删除 -- `frontend/src/hooks/useWebsocketSessionSync.js` ✅ 已删除 - -**标记为废弃的文件** ✅ 已完成: -- `backend/agents/analyst.py` - 已添加 DeprecationWarning -- `backend/agents/risk_manager.py` - 已添加 DeprecationWarning -- `backend/agents/portfolio_manager.py` - 已添加 DeprecationWarning - -## 8. 测试修复 - -**更新** `backend/tests/test_evo_agent_selection.py`: - -移除这些测试 ✅ 已完成: -- `test_main_create_analyst_agent_falls_back_to_legacy_when_memory_enabled` -- `test_main_create_risk_manager_falls_back_to_legacy_when_memory_enabled` -- `test_main_create_portfolio_manager_falls_back_to_legacy_when_memory_enabled` - -添加新测试 ✅ 已完成: -- `test_evo_agent_supports_long_term_memory` -- `test_all_roles_use_evo_agent_by_default` - -新增集成测试文件 ✅ 已完成: -- `backend/tests/test_evo_agent_integration.py` - 13 个集成测试覆盖 Factory、ToolGuard、Workspace 集成 - -## 9. 快速修复清单 - -运行以下命令应用关键修复: - -```bash -# 1. 修复 EvoAgent 记忆支持 (修改 main.py, pipeline.py, pipeline_runner.py) -# 移除 long_term_memory 检查导致的 Legacy 回退 - -# 2. 修复默认 EvoAgent 启用 -sed -i 's/def _resolve_evo_agent_ids():/def _resolve_evo_agent_ids() -> set[str]:/' backend/main.py - -# 3. 确保所有测试通过 -pytest backend/tests/test_evo_agent_selection.py -v - -# 4. 运行 smoke test -python3 scripts/smoke_evo_runtime.py --test-all-roles -``` - -## 10. 实施进度 - -### ✅ 已完成 - -| 任务 | 状态 | 文件 | -|------|------|------| -| EvoAgent 长期记忆支持 | ✅ 已完成 | `evo_agent.py`, `main.py` | -| 默认启用所有角色 EvoAgent | ✅ 已完成 | `main.py`, `pipeline.py` | -| 统一 Agent 工厂 | ✅ 已完成 | `unified_factory.py` | -| ToolGuard Gateway 同步 | ✅ 已完成 | `tool_guard.py`, `guard.py` | -| ToolGuard 批量审批 | ✅ 已完成 | `guard.py` | -| 废弃标记 Legacy Agent | ✅ 已完成 | `analyst.py`, `risk_manager.py`, `portfolio_manager.py` | -| 集成测试 | ✅ 已完成 | `test_evo_agent_integration.py` | -| 类型注解 | ✅ 已完成 | `unified_factory.py` | -| Team 基础设施 | ✅ 已完成 | `messenger.py`, `task_delegator.py` | -| Skills 沙盒执行 | ✅ 已完成 | `sandboxed_executor.py` | - -### 🚧 待完成 - -| 优先级 | 任务 | 说明 | -|--------|------|------| -| P0 | Smoke Test 依赖修复 | 需要安装 pandas, finnhub, pandas-market-calendars 等 | -| P1 | Workspace ID 语义清理 | ✅ 已添加 `run_id`，保留 `workspace_id` 用于向后兼容 | -| P2 | 文档完善 | ✅ 已完成 | - -*最后更新: 2026-04-02* - ---- - -*文档生成时间: 2026-04-01* diff --git a/docs/OPTIMIZATION_PLAN.md b/docs/OPTIMIZATION_PLAN.md deleted file mode 100644 index 5aae612..0000000 --- a/docs/OPTIMIZATION_PLAN.md +++ /dev/null @@ -1,249 +0,0 @@ -# 大时代项目优化和功能补齐计划 - -## 当前状态评估 - -### 已完成的工作 -1. ✅ EvoAgent 核心实现 (`backend/agents/base/evo_agent.py`) -2. ✅ ToolGuardMixin 工具守卫 (`backend/agents/base/tool_guard.py`) -3. ✅ Hooks 系统 (`backend/agents/base/hooks.py`) -4. ✅ Smoke test 脚本 (`scripts/smoke_evo_runtime.py`) -5. ✅ 选择性 EvoAgent 测试 (`backend/tests/test_evo_agent_selection.py`) -6. ✅ 删除 `backend/agents/compat.py` 兼容性层 -7. ✅ 删除 `useWebsocketSessionSync.js` 旧钩子 - -### 遗留问题清单 - -#### 🔴 P0: 阻塞 EvoAgent 全面推出 - -| # | 问题 | 位置 | 影响 | 解决方案 | -|---|------|------|------|----------| -| P0-1 | EvoAgent 不支持长期记忆 | `evo_agent.py:165-166` | 启用 memory 时回退到 Legacy Agent | 集成 ReMe 记忆系统 | -| P0-2 | Pipeline 运行时分析师创建路径不一致 | `pipeline.py` | 运行时动态创建可能跳过 EvoAgent 路径 | 统一 `_create_runtime_analyst` 逻辑 | -| P0-3 | Workspace 加载路径混乱 | `workspace.py`, `workspace_manager.py` | `workspace_id` vs `run_id` 语义混合 | 明确区分 design-time 和 runtime 路径 | -| P0-4 | Smoke test 失败排查 | `scripts/smoke_evo_runtime.py` | 无法验证 EvoAgent 是否正确启动 | 修复测试并确保通过 | - -#### 🟡 P1: 功能完善 - -| # | 问题 | 位置 | 影响 | 解决方案 | -|---|------|------|------|----------| -| P1-1 | Team 基础设施未完成 | `evo_agent.py:41-48` | Agent 间通信和任务委托不可用 | 完成 messenger 和 task_delegator | -| P1-2 | ToolGuard 与 Gateway 审批流程集成 | `tool_guard.py`, `api/guard.py` | 审批状态同步可能不一致 | 统一审批存储和事件通知 | -| P1-3 | Skills 沙盒执行 | `tools/sandboxed_executor.py` | 生产环境需要 Docker 隔离 | 完善沙盒执行器 | -| P1-4 | 错误处理和重试机制 | 多处 | 部分错误未正确处理 | 添加统一的错误处理 | - -#### 🟢 P2: 代码质量和可维护性 - -| # | 问题 | 位置 | 影响 | 解决方案 | -|---|------|------|------|----------| -| P2-1 | 重复的 Agent 创建逻辑 | `main.py`, `pipeline.py`, `pipeline_runner.py` | 维护困难，容易遗漏 | 提取统一的 Agent 工厂 | -| P2-2 | 类型注解不完整 | 多处 | IDE 提示不足 | 完善类型注解 | -| P2-3 | 缺少 EvoAgent 集成测试 | `backend/tests/` | 无法确保功能完整 | 添加集成测试 | -| P2-4 | 文档和注释 | 多处 | 新贡献者理解困难 | 完善文档 | - ---- - -## 详细实施方案 - -### Phase 1: P0 阻塞问题修复 - -#### P0-1: EvoAgent 长期记忆支持 - -**问题描述**: -```python -# main.py 中当前逻辑 -if long_term_memory and agent_id not in EVO_AGENT_IDS: - # 使用 Legacy Agent -else: - # 使用 EvoAgent -``` - -**目标**: EvoAgent 支持 ReMe 长期记忆系统 - -**实施步骤**: -1. 在 `EvoAgent.__init__` 中正确接收 `long_term_memory` 参数 -2. 集成 ReMe 记忆系统的读写 -3. 在 Hooks 中添加记忆相关的生命周期管理 -4. 修改 `main.py`, `pipeline.py` 中移除 EvoAgent 的记忆回退逻辑 - -**文件修改**: -- `backend/agents/base/evo_agent.py` -- `backend/main.py` -- `backend/core/pipeline.py` - -#### P0-2: Pipeline 运行时分析师创建统一 - -**问题描述**: -`TradingPipeline._create_runtime_analyst` 方法需要确保: -1. 检查 `EVO_AGENT_IDS` 环境变量 -2. 正确传递所有必要参数给 EvoAgent -3. 处理 workspace 资产准备 - -**实施步骤**: -1. 统一 `pipeline.py` 和 `main.py` 中的 Agent 创建逻辑 -2. 确保 EvoAgent 路径和 Legacy 路径参数一致 -3. 添加运行时动态 Agent 创建的测试 - -**文件修改**: -- `backend/core/pipeline.py` -- `backend/main.py` - -#### P0-3: Workspace 路径清理 - -**问题描述**: -- `workspace_id` 有时指 `workspaces/` 目录下的设计时 workspace -- 有时指 `runs//` 下的运行时 workspace - -**解决方案**: -1. 明确命名：`design_workspace_id` vs `run_id` -2. 在 API 路由中区分两种资源 -3. 内部统一使用 `run_id` 作为运行时标识 - -**文件修改**: -- `backend/api/workspaces.py` -- `backend/api/agents.py` -- `backend/agents/workspace_manager.py` - -#### P0-4: Smoke Test 修复 - -**当前测试**: -```bash -python3 scripts/smoke_evo_runtime.py --agent-id fundamentals_analyst -``` - -**验证点**: -1. Gateway 正常启动 -2. EvoAgent 日志出现 -3. `runtime_state.json` 正确写入 -4. 审批流程正常工作 - -**实施步骤**: -1. 运行测试并识别失败点 -2. 修复 EvoAgent 初始化问题 -3. 确保所有 6 个角色都能通过测试 - ---- - -### Phase 2: P1 功能完善 - -#### P1-1: Team 基础设施 - -**当前状态**: -```python -try: - from backend.agents.team.messenger import AgentMessenger - from backend.agents.team.task_delegator import TaskDelegator - TEAM_INFRA_AVAILABLE = True -except ImportError: - TEAM_INFRA_AVAILABLE = False -``` - -**目标**: 完成 Agent 间通信和任务委托 - -**实施步骤**: -1. 完成 `AgentMessenger` 实现 -2. 完成 `TaskDelegator` 实现 -3. 添加 Agent 团队协调的测试 - -#### P1-2: ToolGuard 与 Gateway 集成 - -**当前状态**: -- `ToolGuardStore` 是内存存储 -- Gateway 通过 `get_global_runtime_manager()` 访问 - -**改进**: -1. 确保审批状态在 Gateway 和 Agent 间同步 -2. 添加审批超时处理 -3. 支持批量审批 - -#### P1-3: Skills 沙盒执行 - -**当前状态**: -```python -SKILL_SANDBOX_MODE=none # 开发模式，直接执行 -``` - -**目标**: 生产环境使用 Docker 隔离 - -**实施步骤**: -1. 完成 `DockerSandboxBackend` -2. 添加资源限制（CPU、内存、网络） -3. 添加执行超时控制 - ---- - -### Phase 3: P2 代码质量 - -#### P2-1: 统一 Agent 工厂 - -**目标**: 提取 `AgentFactory` 统一处理所有 Agent 创建 - -**设计**: -```python -class AgentFactory: - def create_analyst(self, analyst_type: str, **kwargs) -> BaseAgent - def create_risk_manager(self, **kwargs) -> BaseAgent - def create_portfolio_manager(self, **kwargs) -> BaseAgent -``` - -#### P2-2: 类型注解 - -**目标**: 所有公共 API 完整的类型注解 - -#### P2-3: 集成测试 - -**目标**: EvoAgent 完整的端到端测试 - ---- - -## 实施顺序 - -### Week 1: P0 阻塞问题 -1. [ ] P0-4: 运行 Smoke Test，识别失败点 -2. [ ] P0-1: EvoAgent 长期记忆支持 -3. [ ] P0-2: Pipeline 运行时统一 -4. [ ] P0-3: Workspace 路径清理 -5. [ ] 验证所有 Smoke Test 通过 - -### Week 2: P1 功能完善 -1. [ ] P1-1: Team 基础设施 -2. [ ] P1-2: ToolGuard 集成优化 -3. [ ] P1-3: Skills 沙盒执行 - -### Week 3: P2 代码质量 -1. [ ] P2-1: 统一 Agent 工厂 -2. [ ] P2-2: 类型注解 -3. [ ] P2-3: 集成测试 -4. [ ] P2-4: 文档完善 - ---- - -## 成功标准 - -### EvoAgent 全面推出标准 -1. ✅ 所有 6 个角色通过 smoke test -2. ✅ 长期记忆功能正常工作 -3. ✅ 无需 `EVO_AGENT_IDS` 环境变量即可使用 EvoAgent -4. ✅ Legacy Agent 代码标记为 deprecated -5. ✅ 集成测试覆盖主要使用场景 - -### 架构清理标准 -1. ✅ `runs//` 是唯一的运行时数据来源 -2. ✅ `workspaces/` 仅用于设计时注册表 -3. ✅ 所有服务边界清晰，无循环依赖 -4. ✅ 文档和代码一致 - ---- - -## 风险和对策 - -| 风险 | 可能性 | 影响 | 对策 | -|------|--------|------|------| -| EvoAgent 与 Legacy 行为不一致 | 中 | 高 | 并行运行对比测试 | -| 长期记忆集成复杂 | 中 | 中 | 分阶段实现，先支持基础功能 | -| 性能下降 | 低 | 高 | 基准测试，性能剖析 | -| 迁移期间系统不稳定 | 中 | 高 | 保持 Legacy 作为回退 | - ---- - -*计划创建日期: 2026-04-01* -*负责: Claude Code* diff --git a/docs/runtime-api-changes.md b/docs/runtime-api-changes.md index 85e0bba..06c92e7 100644 --- a/docs/runtime-api-changes.md +++ b/docs/runtime-api-changes.md @@ -1,8 +1,26 @@ -# Runtime Service API 变更文档 +# Runtime Service API 说明 ## 概述 -本文档描述了 `runtime_service` API 的改进，包括新增端点、增强的响应字段和改进的错误处理。 +本文档描述当前 `runtime_service` API 的关键端点、增强响应字段和启动/健康检查相关行为。 +它应被视为 runtime API 的补充说明，而不是迁移过程中的一次性变更记录。 + +## 适用范围 + +- 运行时控制面：`backend.apps.runtime_service` +- 运行时 API 前缀：`/api/runtime/*` +- 当前推荐配套阅读： + - `README.md` + - `README_zh.md` + - `docs/current-architecture.md` + +## 关于 `schedule_mode` 的当前约定 + +当前对外约定统一使用 `daily` / `interval`。 + +- `interval` 是当前公开的盘中轮询名称 +- `intraday` 仅作为向后兼容输入别名保留 +- runtime API 的响应和写回配置应优先输出 `interval` ## 新增端点 @@ -26,7 +44,8 @@ - `mode`: 运行模式，`"live"`（实盘）或 `"backtest"`（回测），运行时停止时为 `"stopped"` - `is_backtest`: 是否为回测模式 - `run_id`: 当前运行的任务 ID -- `schedule_mode`: 调度模式，`"daily"` 或 `"intraday"` +- `schedule_mode`: 调度模式字段。当前公开值为 `daily` 或 `interval`； + 历史输入别名 `intraday` 会在服务端归一化为 `interval`。 - `is_running`: Gateway 是否正在运行 --- @@ -113,7 +132,7 @@ --- -## 改进的端点 +## 关键端点说明 ### GET /api/runtime/gateway/status @@ -256,7 +275,8 @@ Gateway 启动前会自动验证以下配置： - `start_date` 必须早于 `end_date` 6. **调度模式** - - `schedule_mode` 必须是 `"daily"` 或 `"intraday"` + - 当前公开校验值为 `"daily"` / `"interval"` + - 历史输入 `"intraday"` 会被兼容性归一化为 `"interval"` **验证失败响应**: diff --git a/docs/terminology.md b/docs/terminology.md index f36d129..34bebf9 100644 --- a/docs/terminology.md +++ b/docs/terminology.md @@ -51,19 +51,18 @@ Examples: ## Compatibility Rule -Some API paths and fields still use legacy names: +Some fields still use legacy names: -- `/api/workspaces/{workspace_id}/agents/...` - `workspace_id` on approval records -When reading those surfaces: +Current API path rule: -- design-time CRUD routes use `workspace_id` literally -- runtime-read routes may use the same slot for `run_id` +- design-time CRUD uses `/api/workspaces/{workspace_id}/...` +- runtime agent assets use `/api/runs/{run_id}/agents/...` For new code: -- prefer `runId` for runtime variables +- prefer `runId` for runtime variables and runtime API paths - prefer `workspaceId` only for design-time registry flows ## UI Wording