- 已经知道仓库大致结构，但想快速找到“这类任务从哪里下手”的开发者
- 想减少在多份文档之间来回跳转的读者
- 不逐条重复 API 契约内容，那部分见 api-docs.md
- 不讲完整架构背景，那部分见 service-architecture.md
- backend/main.py
- crawler/crawling/pipeline.py
- persistence_api/graph_service.py
- search/main.py
- shared/config.py
先看：
通常改动顺序：
- 在
backend/main.py增加或调整公共/api/*路由。 - 如果需要下游能力，再去改
crawler、search或persistence-api的/internal/*。 - 同步更新前端 API 封装与调用页面。
- 同步更新 api-docs.md。
先看：
常见落点：
- 抓取行为： crawler/crawling/fetching/httpx_fetcher.py
- 友链页发现： crawler/crawling/discovery.py
- 链接抽取： crawler/crawling/extraction.py
- 过滤规则： crawler/filters.py
- URL 归一化： crawler/crawling/normalization.py
- 导出逻辑： crawler/export_service.py
先看：
- persistence_api/graph_service.py
- persistence_api/graph_projection.py
- backend/main.py
- frontend/src/pages/GraphPage.tsx
- frontend/src/lib/api.ts
判断原则：
- 图数据的事实来源和视图组装在
persistence-api backend负责把这些能力暴露成公共/api/graph*- 前端只负责参数组织、交互和渲染
如果你要讨论未来能力规划，再看：
先看：
链路顺序：
backend 在 health 检查、crawl run、runtime batch、database reset 后触发 search 读/重建索引 -> search 读取 search-index.json，缓存为空时回退到 persistence-api /internal/search-snapshot
先看：
重点记住：
- 运行器状态保存在
crawler进程内存里 backend只负责把 runtime 能力暴露成公共接口- 重置数据库前，
backend会先检查 runtime 是否忙碌
先看：
相关状态位置：
- SQLite：
data/heyblog.sqlite - 导出目录：
data/exports/或volumes/exports/ - 搜索缓存：
data/search-cache/或volumes/search-cache/ - PostgreSQL 卷：
volumes/postgres/
先看：
如果页面需要新数据：
- 先确认公共 API 是否已经存在。
- 没有的话，回到“我要新增或调整公共 API”这条流程。
先看：
优先核对：
- 服务基地址是否指到了正确端口
- 本地
uvicorn启动时是否把 Docker 默认主机名改成了127.0.0.1 HEYBLOG_DB_DSN是否意外覆盖了 SQLite 模式