# 源码阅读路线

代码依据：2026-09-30 当前工作区。每条路线以具体业务场景为入口，提供代码文件、关键函数、调用关系、数据状态和测试阅读位置。

## 路线入口

1. [一次咨询的全过程](01-conversation.md)：消费者页面、消息接口、数据库事件、SSE 续传、人工接管与回复。适合作为共同入门路线。
2. [Agent 如何完成任务](02-agent-runtime.md)：运行创建、发布配置、worker 调度、LangGraph、工具调用、补充信息与业务等待恢复。
3. [一笔换货申请如何完成](03-after-sales.md)：业务资格、方案版本、客户确认、主管审批、数量预占与 OMS 履约。
4. [资料与记忆如何参与回答](04-knowledge-memory.md)：资料发布、混合检索、引用复验、客户授权与沟通习惯记忆。
5. [多个商家如何共用平台](05-identity-permissions.md)：租户与店铺、登录会话、资源归属、操作权限、后台复验与平台独立身份。
6. [模型资源与费用](06-capacity-billing.md)：并发预留、租户调度、token 与金额预占、实际用量结算、账单与双人审批。
7. [外部渠道与可靠消息](07-channels-messaging.md)：签名验证、身份关联、Inbox、Outbox、RabbitMQ、消费收据和渠道投递。
8. [运行管理与效果验证](08-operations-evaluation.md)：应用启动、发布检查、心跳、监控、故障恢复入口、Agent 评测与检索评测。

## 跟踪方法

打开一条路线后，从图中的入口函数开始，在源码中寻找图上标注的下一次调用。每到一个节点，记录当前输入、身份、读取的数据、写入的数据和返回结果。遇到数据库任务、HTTP 或消息队列时，沿箭头上的说明进入对应接收端或工作进程。

后端图中以 `modules/`、`core/`、`operations/`、`oms/` 开始的路径相对 `src/zhifu/`；`frontend/`、`scripts/`、`tests/` 与 `compose` 文件从仓库根目录开始。各路线提供节点编号和源码导航，点击带行号的链接可以定位对应定义。

图中的连续箭头表示当前进程内的函数调用、返回后继续执行或带条件的分支；具体含义写在箭头上。间断箭头标注 HTTP、数据库持久记录、消息队列、框架回调或后续独立请求。函数名称和所有状态名称保持源码标识。

函数嵌套定义会注明所属外层函数，例如 `build_graph.model` 表示 `build_graph` 内部的 `model`。同一文件出现多个 `execute_one` 或 `emit` 时，以文件路径和所属类确认定义。`内部` 节点说明当前函数中的关键处理位置。

阅读每幅图后，用源码回答文末的三个检查问题，并查看相应测试用例中的输入、调用和断言。测试文件承担行为说明的作用；实际运行时遵循项目的环境要求、数据范围和模型调用限制。

## 交叉阅读位置

- 路线 1 到达 Agent worker 后，进入路线 2；遇到售后卡片、客户确认和审批时，进入路线 3。
- 路线 2 中的 `search_knowledge`、记忆读取、`BudgetCallback` 分别连接路线 4 与路线 6。
- 路线 3 的 `BusinessEvent`、消费收据和 OMS 请求连接路线 7；业务权限检查连接路线 5。
- 路线 8 根据运行记录、费用记录、检索资料版本和业务断言核对前面各条路线的结果。

已有的[会话消息流程文档](../architecture/conversation-message-flow.md) 提供完整对话时序，可以与路线 1、路线 2 配合阅读。

## 核对范围

本组文档按当前源码核对文件、函数、分支、持久记录与进程边界。文档检查覆盖 Mermaid 语法、本地链接及带行号的源码位置。本文档编写过程没有执行业务验收、外部履约或生成模型请求；测试文件链接供学员阅读。