更新文档

README.md

@@ -2,6 +2,42 @@
 
 可作为命令行工具运行，也可作为 `pip install -e .` 的本地可编辑安装库接入其他项目。
 
+## 0. 10 分钟上手
+
+如果你是第一次进入这个仓库，先不要从所有文档开始读，先确认环境和最小工具链可用。
+
+推荐顺序：
+1. 准备 Python 3.9+ 环境（当前仓库已在 `pyproject.toml` 中声明 `requires-python >= 3.9`）。
+2. 在仓库根目录创建并激活虚拟环境。
+3. 以可编辑模式安装本项目。
+4. 先跑配置校验，再跑一个轻量集成测试，确认本地环境可用。
+5. 只在确认入口可运行后，再去看架构与状态机文档。
+
+最小命令链：
+
+```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
+```
+
+如果你只是想直接运行仓库内现成配置，优先用仓库入口：
+
+```bash
+python run.py --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml
+```
+
+如果你已经完成 `pip install -e .`，也可以使用安装后的命令行入口：
+
+```bash
+ecm-sync-run --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml
+```
+
+面向第一次接触仓库的更完整说明见：`docs/getting_started.md`
+
 ## 1. 项目简介
 
 本项目用于实现异构系统之间的数据推送：将项目侧管理平台的十余种业务数据，稳定推送到集团侧管理平台。
@@ -18,6 +54,7 @@
 项目采用：`schema` 严格约束 + 状态机 + 节点模型 + 分层架构 + 注册式 `domain` + 数据源与同步系统解耦。
 
 架构详见：
+- `docs/getting_started.md`
 - `docs/architecture.md`
 - `docs/node_state_definition.md`
 - `docs/state_machine.md`
@@ -58,20 +95,24 @@
 
 ## 5. 使用方法
 
+先区分两种常见使用方式：
+- 仓库内开发与调试：优先使用 `python run.py ...`，因为它不依赖 shell 中已经存在 `ecm-sync-run`。
+- 作为库或已安装命令使用：先执行 `pip install -e .`，再使用 `ecm-sync-run ...`。
+
 运行配置遵循一个约定：
 - 跟踪在仓库里的 `run_profiles/*.yaml` 与 `run_profiles/preset/*.default.yaml` 只写必要的覆盖项。
 - pipeline 启动时会打印并写入一份 **Resolved Full Config**，把省略的默认值全部补齐，便于排障和审阅。
 - 字段含义与全量示例见：`docs/runtime_config_guide.md`
 
 ### JSONL 同步
-- 已安装命令行入口：`ecm-sync-run --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml`
 - 仓库内直接运行：`python run.py --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml`
+- 已安装命令行入口：`ecm-sync-run --config_path=run_profiles/preset/jsonl_to_jsonl.default.yaml`
 - 多项目 JSONL 示例：`python run.py --config_path=run_profiles/preset/jsonl_to_jsonl.multi_project.default.yaml`
 - 自定义配置：从 `run_profiles/preset/` 复制一份到 `run_profiles/*.local.yaml`，只改有差异的字段即可。
 
 ### API 同步
-- 已安装命令行入口：`ecm-sync-run --config_path=run_profiles/preset/jsonl_to_api.default.yaml`
 - 仓库内直接运行：`python run.py --config_path=run_profiles/preset/jsonl_to_api.default.yaml`
+- 已安装命令行入口：`ecm-sync-run --config_path=run_profiles/preset/jsonl_to_api.default.yaml`
 - 如果是单项目联调，优先参考仓库内现成示例：`run_profiles/jsonl_to_api.yaml`
 
 ### 库模式使用
@@ -99,6 +140,16 @@
 
 ## 文档导航
 
+如果你是按任务查文档，建议按下面的顺序进入：
+- 第一次接手仓库：`docs/getting_started.md`
+- 想理解整体分层：`docs/architecture.md`
+- 想理解状态与迁移：`docs/node_state_definition.md` + `docs/state_machine.md`
+- 想调运行配置：`docs/runtime_config_guide.md` + `run_profiles/README.md`
+- 想接新数据源或改 handler：`sync_state_machine/datasource/README.md` + `docs/library_integration_guide.md`
+- 想排障：`docs/operations.md`
+- 想补测试或跑联调：`docs/testing_guide.md` + `tests/README.md`
+
+- 新人上手：`docs/getting_started.md`
 - 总体架构：`docs/architecture.md`
 - 状态定义：`docs/node_state_definition.md`
 - 状态机规则：`docs/state_machine.md`