strepsiades
128 lines
3.7 KiB
Markdown
128 lines
3.7 KiB
Markdown
# 快速上手
|
||
|
||
这份文档只服务第一次接手 `ecm_sync_system` 的开发者。目标不是完整讲架构，而是让你先跑起来、知道从哪里入手，再去看更细的说明。
|
||
|
||
## 1. 先做什么
|
||
|
||
第一次进入仓库时，建议按下面顺序执行：
|
||
|
||
1. 准备 Python 3.9+。
|
||
2. 在仓库根目录创建并激活虚拟环境。
|
||
3. 执行 `pip install -e .` 安装当前项目。
|
||
4. 跑状态机配置校验，确认基础工具链正常。
|
||
5. 跑一条轻量测试，确认测试与渲染工具链可用。
|
||
6. 再去看架构文档和状态机文档。
|
||
|
||
推荐命令：
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -e .
|
||
python run.py --help
|
||
python tools/validate_config.py --config sync_state_machine/config/node_state_machine.yaml
|
||
pytest tests/integration/test_toolchain_config_and_graph.py -q
|
||
```
|
||
|
||
## 2. 仓库里最重要的目录
|
||
|
||
- `sync_state_machine/`
|
||
- 真正的引擎实现目录。大多数“核心代码入口”都在这里。
|
||
- `run_profiles/`
|
||
- 运行配置与模板。
|
||
- `tests/`
|
||
- 单元测试与集成测试。
|
||
- `tools/`
|
||
- 状态机校验、图渲染、远程环境等工具。
|
||
- `scripts/`
|
||
- 自动化测试编排和数据集相关脚本。
|
||
- `docs/`
|
||
- 面向开发者的设计、运行和排障文档。
|
||
|
||
## 3. 先读哪几篇文档
|
||
|
||
按任务来看：
|
||
|
||
- 想知道系统整体怎么分层：`docs/architecture.md`
|
||
- 想知道状态机怎么工作：`docs/node_state_definition.md` 和 `docs/state_machine.md`
|
||
- 想知道一次同步是怎么跑的：`docs/sync_flow.md`
|
||
- 想调运行配置：`docs/runtime_config_guide.md`
|
||
- 想接新 datasource 或 handler：`sync_state_machine/datasource/README.md` 和 `docs/library_integration_guide.md`
|
||
- 想看测试体系：`docs/testing_guide.md` 和 `tests/README.md`
|
||
- 想做排障：`docs/operations.md`
|
||
|
||
## 4. 新人最容易踩的坑
|
||
|
||
### 4.1 先用仓库入口，不要默认 shell 里已经有命令
|
||
|
||
如果你还没执行过 `pip install -e .`，那么 `ecm-sync-run` 不一定可用。
|
||
|
||
首次调试建议优先用：
|
||
|
||
```bash
|
||
python run.py --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml
|
||
```
|
||
|
||
安装完成后，再切换到：
|
||
|
||
```bash
|
||
ecm-sync-run --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml
|
||
```
|
||
|
||
### 4.2 核心实现路径以 `sync_state_machine/` 为准
|
||
|
||
阅读历史文档时，如果看到类似下面的写法：
|
||
|
||
- `pipeline/full_sync_pipeline.py`
|
||
- `sync_system/strategy.py`
|
||
- `datasource/datasource.py`
|
||
- `engine/events.py`
|
||
|
||
请优先理解为它们在当前仓库中的真实位置分别是：
|
||
|
||
- `sync_state_machine/pipeline/full_sync_pipeline.py`
|
||
- `sync_state_machine/sync_system/strategy.py`
|
||
- `sync_state_machine/datasource/datasource.py`
|
||
- `sync_state_machine/engine/events.py`
|
||
|
||
## 5. 如果你要开始改代码
|
||
|
||
### 5.1 改 domain 行为
|
||
|
||
优先查看：
|
||
|
||
- `sync_state_machine/domain/<node_type>/`
|
||
- `sync_state_machine/sync_system/strategy_ops/`
|
||
- `tests/unit/` 中对应测试
|
||
|
||
### 5.2 改状态机语义
|
||
|
||
优先查看：
|
||
|
||
- `sync_state_machine/config/node_state_machine.yaml`
|
||
- `sync_state_machine/engine/events.py`
|
||
- `sync_state_machine/engine/state_apply.py`
|
||
|
||
改完建议至少执行：
|
||
|
||
```bash
|
||
python tools/validate_config.py --config sync_state_machine/config/node_state_machine.yaml
|
||
pytest tests/integration/test_toolchain_config_and_graph.py -q
|
||
```
|
||
|
||
### 5.3 改运行配置或 datasource
|
||
|
||
优先查看：
|
||
|
||
- `docs/runtime_config_guide.md`
|
||
- `run_profiles/README.md`
|
||
- `sync_state_machine/datasource/README.md`
|
||
|
||
## 6. 出错先看哪里
|
||
|
||
推荐排查顺序：
|
||
|
||
1. 先看运行日志中的 `Resolved Full Config`。
|
||
2. 再看节点 `sync_log / status / error`。
|
||
3. 再对照 `docs/operations.md` 和 `docs/state_machine.md`。
|
||
4. 如果是配置问题，先让校验报错，不要绕过 schema 或状态机校验。 |