docs: refresh runtime guidance

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       # 状态同步

docs/CRITICAL_FIXES.md

@@ -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*

docs/OPTIMIZATION_PLAN.md

@@ -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/<run_id>/` 下的运行时 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/<run_id>/` 是唯一的运行时数据来源
-2. ✅ `workspaces/` 仅用于设计时注册表
-3. ✅ 所有服务边界清晰，无循环依赖
-4. ✅ 文档和代码一致
-
----
-
-## 风险和对策
-
-| 风险 | 可能性 | 影响 | 对策 |
-|------|--------|------|------|
-| EvoAgent 与 Legacy 行为不一致 | 中 | 高 | 并行运行对比测试 |
-| 长期记忆集成复杂 | 中 | 中 | 分阶段实现，先支持基础功能 |
-| 性能下降 | 低 | 高 | 基准测试，性能剖析 |
-| 迁移期间系统不稳定 | 中 | 高 | 保持 Legacy 作为回退 |
-
----
-
-*计划创建日期: 2026-04-01*
-*负责: Claude Code*

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"`
 
 **验证失败响应**:
 

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
+- design-time CRUD uses `/api/workspaces/{workspace_id}/...`
-- runtime-read routes may use the same slot for `run_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