附录 A：源码阅读地图
这份地图按问题而不是目录索引文件。建议先读每组“入口”，遇到具体分支再向下追。
运行主链
| 问题 | 入口文件 | 向下追踪 |
|---|---|---|
| HTTP run 如何创建 | app/gateway/routers/thread_runs.py | runtime/runs/manager.py |
| Agent 如何后台执行 | runtime/runs/worker.py::run_agent | stream bridge、journal、checkpoint state |
| Agent 如何组装 | agents/lead_agent/agent.py::make_lead_agent | models、tools、middlewares、prompt |
| 图从哪里注册 | backend/langgraph.json | deerflow.agents:make_lead_agent |
| SSE 如何 join/replay | routers/thread_runs.py | runtime/stream_bridge.py |
Agent 内核
| 主题 | 先读 | 再读 |
|---|---|---|
| 通用 SDK 工厂 | agents/factory.py | agents/features.py |
| 产品中间件顺序 | agents/lead_agent/agent.py::build_middlewares | agents/middlewares/* |
| 状态 reducers | agents/thread_state.py | delta checkpoint tests |
| 系统提示词 | agents/lead_agent/prompt.py | Dynamic/Durable Context middleware |
| 模型适配 | models/factory.py | 各 provider/patch 文件 |
工具与沙箱
| 主题 | 先读 | 再读 |
|---|---|---|
| 工具汇总 | tools/tools.py | config/tool_config.py |
| 文件工具 | sandbox/tools.py | read-before-write、output budget |
| 沙箱接口 | sandbox/sandbox.py | provider 与 local 实现 |
| 路径映射 | sandbox/local/local_sandbox.py | runtime paths、uploads |
| 产物交付 | tools/builtins/present_file_tool.py | artifacts router、前端 provider |
上下文与扩展
| 主题 | 先读 | 再读 |
|---|---|---|
| 子代理 | tools/builtins/task_tool.py | subagents/executor.py、registry |
| 自动摘要 | middlewares/summarization_middleware.py | runtime/context_compaction.py |
| 长期记忆 | agents/memory/manager.py | memory middleware、backend adapters |
| Skills | skills/loader.py / storage | activation、policy、durable context |
| MCP | mcp/tools.py | client、cache、session_pool、oauth |
| 延迟工具 | tools/builtins/tool_search.py | routing/filter middleware |
产品运行时
| 主题 | 先读 | 再读 |
|---|---|---|
| App 装配 | app/gateway/app.py | dependencies、各 router |
| 数据库 | persistence/bootstrap.py | engine、SQL repositories、migrations |
| Checkpoint | runtime/checkpointer/provider.py | async provider、mode、state |
| Auth | app/gateway/auth_middleware.py | auth service、CSRF、user context |
| RBAC | authz/provider.py | principal、rbac、adapter、tool_filter |
| 渠道 | app/channels/* | channel connections router |
前端
| 问题 | 入口 | 关键纯逻辑 |
|---|---|---|
| 聊天运行 | components/workspace/chats/use-thread-chat.ts | core/threads/hooks.ts |
| SDK 封装/gap | core/api/api-client.ts | core/api/stream-mode.ts |
| 消息分组 | core/messages/utils.ts | run-duration、human-input |
| 子任务卡片 | core/tasks/context.tsx | lifecycle、steps、subtask-update |
| Artifact | components/workspace/artifacts/context.tsx | core/artifacts/* |
| 页面路由 | app/workspace/chats/[thread_id]/page.tsx | chat-box、message-list |
一条实用的 rg 路径
阅读某个状态字段时，按这四步搜：
bash
rg '字段名' backend/packages/harness/deerflow/agents/thread_state.py
rg '字段名' backend/packages/harness/deerflow
rg '字段名' backend/app
rg '字段名' frontend/src1
2
3
4
2
3
4
这会依次找到定义/reducer、生产者、API 投影和 UI 消费者，比从全仓库结果中盲跳更容易建立因果链。
基线说明
本文分析的是包版本 2.1.0、2026-08-01 的本地源码快照。上游 main 的文件位置和行为可能变化；若链接与描述不一致，以本地基线和对应版本 tag 为准。