chore: remove legacy startup paths

2026-04-03 13:45:57 +08:00
parent 2027635efe
commit dc0b250adc
36 changed files with 598 additions and 1923 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,29 @@
+# Docs Index
+
+这个目录只保留当前仍有维护价值的文档。
+阅读顺序建议从“权威事实”开始，再看“兼容清理”和“规划说明”。
+
+## 权威事实
+
+- [`current-architecture.md`](./current-architecture.md) — 当前项目架构、运行路径和真相源定义
+- [`project-layout.md`](./project-layout.md) — 当前仓库目录职责与阅读方式
+- [`terminology.md`](./terminology.md) — runtime、run、workspace 等核心术语
+- [`runtime-api-changes.md`](./runtime-api-changes.md) — 当前 `runtime_service` API 约定与行为补充
+- [`current-architecture.excalidraw`](./current-architecture.excalidraw) — 架构图源文件
+
+## 兼容与遗留清理
+
+- [`legacy-inventory.md`](./legacy-inventory.md) — 兼容层、遗留代码和历史边界清单
+- [`compat-removal-plan.md`](./compat-removal-plan.md) — 兼容移除计划与收敛方向
+
+## 规划说明
+
+- [`development-roadmap.md`](./development-roadmap.md) — 后续演进方向和阶段性路线
+
+## 使用原则
+
+- 讨论“现在系统怎么工作”，优先看 `current-architecture.md`
+- 讨论“顶层目录应该怎么理解”，优先看 `project-layout.md`
+- 讨论“某个旧入口为什么还在”，优先看 `legacy-inventory.md`
+- 讨论“准备删哪些兼容路径”，优先看 `compat-removal-plan.md`
+- 不要把历史计划或阶段性修复记录当成当前事实源
--- a/docs/compat-removal-plan.md
+++ b/docs/compat-removal-plan.md
@@ -67,11 +67,11 @@ backward-compatible behavior while migration settles.

 ## Remaining Migration Risks

-### Split service deployment is not yet the checked-in production default
+### Checked-in deployment artifacts still lag the development topology

 - The repo documents split-service local development clearly.
- The checked-in production example still centers on `backend.main` and nginx
-  WebSocket proxying.
+- The checked-in deployment docs still center on historical nginx
+  WebSocket proxying rather than the active dev topology.
 - This is a topology mismatch to keep in mind when changing deploy docs or prod
  automation.

@@ -93,13 +93,13 @@ backward-compatible behavior while migration settles.
 Migration can be considered effectively complete when all of the following are
 true:

-1. Production deployment docs and scripts explicitly run the same split-service
-   topology used in development, or intentionally document a different stable
-   production topology.
+1. Deployment docs and scripts explicitly run the same split-service
+   topology used in development, or are removed from the repo.
 2. Critical read paths no longer require ambiguous fallback behavior to local
   module implementations.
 3. OpenClaw integration is documented as a stable contract with clear guidance
-   on when to use the WebSocket gateway versus the REST surface.
+   on when to use the WebSocket gateway versus the small set of CLI-backed
+   gateway read helpers.
 4. The frontend-service routing model is stable enough that direct-service and
   gateway-mediated paths are deliberate design choices rather than migration
   leftovers.
@@ -137,9 +137,6 @@ Recommended next action:
 These still have an operational reason to exist and should be documented rather
 than treated as accidental leftovers.

- `backend.main`
-  - compatibility gateway/runtime process
-  - still relevant for websocket transport and current deploy topology
 - `runs/<run_id>/team_dashboard/*.json`
  - export/consumer compatibility layer
 - gateway-mediated websocket/event flow
@@ -147,8 +144,8 @@ than treated as accidental leftovers.

 Recommended next action:

- keep these, but document them as intentional compatibility surfaces with
-  explicit ownership.
+- keep only surfaces with an active operational consumer, and avoid routing new
+  development through them.

 ### 3. Defer Until Topology Decisions Are Final

@@ -157,8 +154,8 @@ churn without simplifying the current runtime.

 - `workspaces/` design-time registry versus `runs/<run_id>/` runtime state
 - env-dependent service fallback behavior
- checked-in deployment docs centered on `backend.main`
- dual OpenClaw shapes: gateway integration and REST facade
+- checked-in deployment docs that have not yet been rewritten around split services
+- dual OpenClaw access patterns: gateway integration and CLI-backed read helpers

 Recommended next action:

--- a/docs/current-architecture.excalidraw
+++ b/docs/current-architecture.excalidraw
@@ -386,13 +386,13 @@
      "updated": 1,
      "link": null,
      "locked": false,
-      "text": "Gateway :8765\\nbackend.main\\nWebSocket + runtime orchestration",
+      "text": "Gateway :8765\\nGateway process\\nWebSocket + runtime orchestration",
      "fontSize": 18,
      "fontFamily": 5,
      "textAlign": "center",
      "verticalAlign": "middle",
      "containerId": null,
-      "originalText": "Gateway :8765\nbackend.main\nWebSocket + runtime orchestration",
+      "originalText": "Gateway :8765\nGateway process\nWebSocket + runtime orchestration",
      "lineHeight": 1.2
    },
    {
@@ -696,13 +696,13 @@
      "updated": 1,
      "link": null,
      "locked": false,
-      "text": "OpenClaw WS :18789\\noptional REST :8004",
+      "text": "OpenClaw WS :18789\\nCLI-backed reads via gateway",
      "fontSize": 20,
      "fontFamily": 5,
      "textAlign": "center",
      "verticalAlign": "middle",
      "containerId": null,
-      "originalText": "OpenClaw WS :18789\noptional REST :8004",
+      "originalText": "OpenClaw WS :18789\nCLI-backed reads via gateway",
      "lineHeight": 1.2
    },
    {
--- a/docs/current-architecture.md
+++ b/docs/current-architecture.md
@@ -1,8 +1,8 @@
 # Current Architecture

 This file describes the current code-supported architecture only. Historical
-paths and partial migrations are intentionally excluded unless called out as
-legacy compatibility.
+paths and partial migrations are intentionally excluded unless brief historical
+context is needed to explain the current shape.

 Reference material:

@@ -11,40 +11,21 @@ Reference material:
 - legacy inventory: [legacy-inventory.md](./legacy-inventory.md)
 - terminology guide: [terminology.md](./terminology.md)

-## Runtime Modes
+## Runtime Mode

-The system supports two distinct runtime modes:
+The supported runtime model is the split-service development architecture.

-### Standalone Mode (Legacy Compatibility)
-
-Direct Gateway startup via `backend.main` as a monolithic entrypoint.
-
-```bash
-python -m backend.main --mode live --port 8765
-```
-
-**Characteristics:**
- Single process runs Gateway, Pipeline, Market Service, and Scheduler
- No service discovery or process management
- Suitable for single-node deployments and quick testing
- All components share the same memory space
-
-**Use cases:**
- Quick local testing without service orchestration
- Single-node production deployments
- Backward compatibility with legacy startup scripts
-
-### Microservice Mode (Default for Development)
-
-Split-service architecture with dedicated runtime_service managing the Gateway lifecycle.
+Split-service architecture with a dedicated runtime API surface and a separate
+Gateway process.

 ```bash
 ./start-dev.sh  # Starts all services including runtime_service and Gateway
 ```

 **Characteristics:**
- `runtime_service` (:8003) acts as Gateway Process Manager
- Gateway runs as a subprocess managed by runtime_service
+- `runtime_service` (:8003) provides runtime lifecycle APIs
+- the checked-in `start-dev.sh` starts split services and lets `runtime_service` spawn Gateway
+- manual split-service flows can also let `runtime_service` spawn Gateway
 - Clear separation between Control Plane (runtime_service) and Data Plane (Gateway)
 - Service discovery via environment variables
 - Independent scaling and deployment of each service
@@ -54,20 +35,7 @@ Split-service architecture with dedicated runtime_service managing the Gateway l
 - Multi-node deployments
 - Production environments requiring service isolation

-## Mode Comparison
-
-| Aspect | Standalone Mode | Microservice Mode |
-|--------|-----------------|-------------------|
-| **Entry point** | `python -m backend.main` | `./start-dev.sh` or individual services |
-| **Process model** | Single monolithic process | Multiple specialized processes |
-| **Gateway management** | Self-contained | Managed by runtime_service |
-| **Service discovery** | None (in-process) | Environment variable based |
-| **Hot reload** | Full restart required | Per-service reload |
-| **Scaling** | Vertical only | Horizontal possible |
-| **Complexity** | Lower | Higher |
-| **Use case** | Testing, simple deployments | Development, production |
-
-## Default Runtime Shape (Microservice Mode)
+## Default Runtime Shape

 The active runtime path is:

@@ -83,7 +51,6 @@ Current service surfaces:
  - read-only explain/news APIs
 - `backend.apps.runtime_service` on `:8003`
  - runtime lifecycle and gateway process management
-  - optional OpenClaw REST facade
 - gateway WebSocket on `:8765`
  - live feed/event transport and pipeline coordination

@@ -163,11 +130,11 @@ use `docker` mode with appropriate resource limits.

 ### Current State

-The system is in a transitional state:
+The system is in an active development state:

 1. **Microservice infrastructure is operational** - runtime_service can start/stop Gateway as subprocess
 2. **Pipeline logic remains in Gateway** - full Pipeline execution still happens within Gateway process
-3. **Standalone mode is preserved** - direct `backend.main` startup for compatibility
+3. **Direct gateway startup has been removed** - the repository now exposes a single supported startup model

 ### Future Direction

@@ -184,9 +151,9 @@ Phase 3: Pipeline decomposition (planned)
 - Gateway becomes a thin event router
 - runtime_service evolves into full orchestrator

-Phase 4: Standalone mode deprecation (future)
- Remove direct `backend.main` entry point
- All deployments use microservice mode
+Phase 4: Deployment convergence (future)
+- Remove or rewrite historical deployment artifacts
+- Keep all documented startup paths aligned with `runtime_service`

 ## Legacy Compatibility

@@ -194,8 +161,8 @@ These items still exist, but they are not the recommended source of truth for
 new development:

 - root-level runtime data directories such as `live/`, `production/`, `backtest/`
- direct `backend.main` startup as the primary development path
+- historical documentation gaps that have not yet been fully rewritten

-The current runtime still creates legacy `AnalystAgent` / `RiskAgent` /
-`PMAgent` instances directly. EvoAgent remains an in-progress migration target,
-not the default execution path.
+Legacy fallback agent paths still exist in compatibility-oriented creation
+flows, but the default `TradingPipeline` runtime now prefers `EvoAgent` for the
+supported roles unless rollout settings explicitly reduce that set.
--- a/docs/development-roadmap.md
+++ b/docs/development-roadmap.md
@@ -63,14 +63,14 @@ Goal: preserve only intentional compatibility layers.

 Planned work:

- identify startup scripts and deploy artifacts that still center on
-  `backend.main` as a monolithic entrypoint
+- identify any remaining deployment docs that still lag the split-service topology
 - classify compatibility surfaces into:
  - stable and intentional
  - temporary and shrinking
  - removable once replacements are fully active
 - reduce env-dependent fallback ambiguity for read-only service routing where practical
- document the difference between OpenClaw WebSocket integration and the optional REST facade
+- document the difference between OpenClaw WebSocket integration and the small
+  set of CLI-backed gateway read helpers

 Definition of done:

--- a/docs/legacy-inventory.md
+++ b/docs/legacy-inventory.md
@@ -21,7 +21,7 @@ These are the current defaults to build against:
  - `backend.apps.trading_service` on `:8001`
  - `backend.apps.news_service` on `:8002`
 - gateway process
-  - `backend.main`
+  - `backend.gateway_server` in the default managed-runtime path
  - `backend.services.gateway` on `:8765`

 ## Compatibility Surface Classification
@@ -35,7 +35,6 @@ compatibility surfaces with explicit ownership.

 | Surface | Location | Owner | Reason |
 |---------|----------|-------|--------|
-| Gateway-first production | `scripts/run_prod.sh`, `deploy/systemd/`, `deploy/nginx/` | ops-team | Current production example runs gateway directly and proxies `/ws` |
 | Dashboard export layer | `runs/<run_id>/team_dashboard/*.json` | frontend-team | Downstream dashboard consumers read these exports |
 | Design-time workspace registry | `workspaces/`, `backend.api.workspaces` | control-plane-team | Control-plane editing and registry-style management |
 | Gateway WebSocket transport | `backend.services.gateway` on `:8765` | runtime-team | Live event streaming contract for frontend |
@@ -50,8 +49,8 @@ in use.

 | Surface | Location | Replacement | ETA |
 |---------|----------|-------------|-----|
-| Legacy analyst agents | `backend.agents.analyst.*` | `EvoAgent` | After EvoAgent smoke tests pass |
-| Mixed workspace_id semantics | `/api/workspaces/{id}/agents/...` | ✅ `/api/runs/{run_id}/agents/...` routes added | Completed |
+| Legacy agent fallback paths | compatibility constructors in `backend.core.pipeline_runner` | `EvoAgent` | After fallback-free runtime cutover |
+| Mixed workspace_id semantics | removed from runtime agent routes | ✅ `/api/runs/{run_id}/agents/...` is the only runtime agent route | Completed |
 | Root-level runtime directories | `live/`, `backtest/`, `production/` | `runs/<run_id>/` | ✅ Removed, backed up to runs/_legacy/ |

 **Status**: Do not add new code using these surfaces. Migrate existing usage
@@ -67,43 +66,13 @@ topology and service-routing policy are frozen.
 |---------|---------------|-----------------|
 | OpenClaw integration | Gateway WebSocket (port 18789) | Stable — REST facade removed |
 | Env-dependent service fallbacks | `TRADING_SERVICE_URL`, `NEWS_SERVICE_URL` fallbacks to local modules | Remove fallbacks and require explicit URLs? |
-| Split-service production deploy | Docs show gateway-first, dev uses split-service | Align production with dev topology? |
+| Split-service deployment docs | Deployment docs are still partial compared with the dev topology | Rewrite deploy docs around split services? |

 **Status**: Document current behavior. Do not actively remove until topology
 decisions are finalized.

 ## Detailed Surface Documentation

-### Gateway-First Production Example
-
-**Files**:
- `scripts/run_prod.sh` - Production launch script
- `deploy/systemd/evotraders.service` - systemd unit
- `deploy/nginx/bigtime.cillinn.com.conf` - HTTPS + WebSocket proxy
- `deploy/nginx/bigtime.cillinn.com.http.conf` - HTTP variant
-
-**Behavior**:
-```bash
-# scripts/run_prod.sh launches:
-python3 -m backend.main \
-  --mode live \
-  --config-name production \
-  --host 127.0.0.1 \
-  --port 8765
-```
-
-**nginx proxies**:
- `/ws` -> `127.0.0.1:8765` (WebSocket upgrade)
- `/` -> static files in `/var/www/bigtime/current`
-
-**Why this exists**:
- Simpler production deployment (single process + nginx)
- WebSocket is the practical live event contract for frontend
- Split-service topology adds operational complexity not needed for all deployments
-
-**Ownership**: ops-team
-**Status**: Stable and intentional
-
 ### Dashboard Export Layer

 **Files**: `runs/<run_id>/team_dashboard/*.json`
@@ -154,19 +123,14 @@ These remain in the tree, but they should not define the architecture for new wo
 - treat these as historical or compatibility-oriented data/layout artifacts
 - do not use them as the default runtime contract for new features

-### Mixed `workspace_id` semantics on agent routes
+### Historical mixed `workspace_id` semantics on agent routes

- `/api/workspaces/{workspace_id}/agents/...`
+This compatibility shape has been removed from runtime agent routes.

-**Read**:
+**Current rule**:

- design-time CRUD routes use `workspace_id` as a registry workspace id
- profile, skills, and editable file routes use `workspace_id` as a run id
-
-**Mitigation already in repo**:
-
- `agent_service /api/status` exposes scope metadata
- runtime-read responses expose `scope_type` and `scope_note`
+- design-time CRUD routes use `/api/workspaces/{workspace_id}/agents/...`
+- runtime agent assets use `/api/runs/{run_id}/agents/...`

 ### Partial EvoAgent rollout

@@ -175,8 +139,10 @@ These remain in the tree, but they should not define the architecture for new wo

 **Read**:

- EvoAgent is still a controlled rollout path
- legacy analyst/risk/PM implementations remain the default runtime path for now
+- EvoAgent is the default selection path for supported roles in the current
+  pipeline
+- legacy implementations remain as compatibility fallbacks in selected startup
+  and runner paths

 ## Recommended Usage

@@ -185,13 +151,14 @@ When in doubt:
 1. trust `docs/current-architecture.md`
 2. trust `runs/<run_id>/` over root-level runtime directories
 3. treat `workspaces/` as control-plane registry, not runtime truth
-4. treat deploy artifacts as the current checked-in example, not the full system contract
+4. treat deploy artifacts as partial references, not the full system contract
 5. check this file's **Compatibility Surface Classification** before assuming something is legacy
+6. prefer `runtime_service`-managed startup for all new work

 ## Change Log

 | Date | Change |
 |------|--------|
 | 2026-03-31 | Added Compatibility Surface Classification (3 buckets) |
-| 2026-03-31 | Documented OpenClaw dual integration (REST vs WebSocket) |
+| 2026-03-31 | Clarified OpenClaw integration documentation |
 | 2026-03-31 | Added ownership and status to all surfaces |
--- a/docs/project-layout.md
+++ b/docs/project-layout.md
@@ -0,0 +1,80 @@
+# Project Layout
+
+这个文件只描述当前仓库目录的职责划分，不记录历史迁移过程。
+
+如果你想知道“系统现在怎么工作”，优先看 `current-architecture.md`。
+如果你想知道“这个目录现在应该怎么理解”，看本文。
+
+## 顶层目录
+
+### 主线代码
+
+- `backend/`
+  - 后端运行时、服务、API、Pipeline、Agent、工具与测试
+- `frontend/`
+  - React/Vite 前端
+- `shared/`
+  - 前后端共享 schema 与 client 封装
+
+### 当前有效的数据与状态目录
+
+- `runs/`
+  - 运行态真相源
+  - 每个 `run_id` 下保存 BOOTSTRAP、agent 资产、state、logs、dashboard 导出
+- `workspaces/`
+  - 设计时注册表
+  - 用于 control-plane CRUD，不是默认运行时执行目录
+- `data/`
+  - 项目使用的数据资产与本地数据文件
+
+### 文档与部署
+
+- `docs/`
+  - 当前仍维护的架构、兼容边界、路线图、目录说明
+- `services/`
+  - 服务边界说明
+- `deploy/`
+  - 部署示例、systemd、nginx 配置
+- `scripts/`
+  - 启动、检查、烟测与辅助脚本
+
+### 项目入口与元数据
+
+- `README.md`
+  - 英文主说明
+- `README_zh.md`
+  - 中文主说明
+- `pyproject.toml`
+  - Python 项目元数据与依赖
+- `start-dev.sh`
+  - 本地默认开发入口
+- `start.sh`
+  - 偏生产风格的本地启动入口
+
+## 本地环境目录
+
+这些目录通常只对当前机器有效，不应作为架构事实源：
+
+- `.venv/`
+  - 本地 Python 虚拟环境
+- `.pydeps/`
+  - 本地依赖落地目录
+- `.omc/`
+  - 本地工具状态
+- `.codex/`
+  - 本地代理/工具状态
+
+## 阅读原则
+
+- 看运行时行为，优先从 `backend/`、`frontend/`、`runs/` 开始
+- 看控制面编辑与设计态资产，优先看 `workspaces/`
+- 看服务边界，优先看 `services/README.md`
+- 看目录时，不要把本地环境目录当成项目结构的一部分
+- 新增目录前，先判断它属于“主线代码 / 运行态数据 / 文档部署 / 本地环境”中的哪一类
+
+## 当前约束
+
+- 不再新增参考仓、副本仓、样例快照目录到顶层
+- 不再把测试输出、PID、构建产物、缓存目录提交到仓库
+- 运行态相关的新文件优先放到 `runs/<run_id>/`
+- 设计态注册相关的新文件优先放到 `workspaces/`