尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
服务端布局
server/ 按领域组织。每个产品平面(plane)对应一个包,包内包含其 wire 声明、处理器、纯逻辑、ClickHouse 访问和后台循环,并由一项测试固定导入的允许方向。本页可作为放置新模块时的参考,也可用于解读契约测试报出的导入错误。
包
| 包 | 职责 | 可导入 |
|---|---|---|
server/main.py |
应用装配:lifespan、路由、workers、传输层。与 server/boot.py、server/health.py、server/wiring.py、server/worker_main.py 和 server/__init__.py 一起,是仅有的根模块 |
任意 |
server/boot.py |
lifespan 的启动和关闭步骤:串行化的启动迁移、leader 的 tracker 命名空间行、吊销快照和密钥环、supervisor 租约循环、写入排空 | 任意 |
server/health.py |
GET /v1/health:多层级健康检查应答(ClickHouse、providers、启动快照、校准、速率限制器,按需包含 workers 和可观测性) |
任意 |
server/wiring.py |
wire():为每个平台接缝提供其领域部分(认证网关的命名空间目录、状态指标的事实数据);由 main.py、CLI 和测试套件运行 |
任意 |
server/worker_main.py |
workers 子进程的组合根(python -m server.worker_main):supervisor 及其 workers 所用的部分,不含对外服务的 lifespan |
任意 |
server/core/ |
横切基础设施:ClickHouse 客户端(ch)、errors、预算、日期时间、哈希、命名、游标、幂等、速率限制、向量存储策略、schema/(迁移和 DDL 工具) |
core、settings |
server/settings/ |
所有设置都在 catalog.py 中声明,每个领域一个分区,组合成 Settings |
core、settings |
server/operations/ |
注册表核心:Operation 和 Role(base.py)、扁平化注册表(registry.py:ALL_OPERATIONS、OPERATIONS_BY_NAME)、toolsets.py、读取投影、覆盖范围普查 |
core、平台包、每个领域的 api |
server/transport/ |
HTTP 和 MCP:准入、请求绑定、列表、primer | core、平台包;领域的 api、app 和 domain(绝不导入其 store 或 workers);不可导入 cli |
server/cli/ |
loom 命令,一个外层适配器 |
任意 |
server/workers/ |
worker 注册表(registry.py)、supervisor、pass 上下文、状态及其存储、首轮调度、成本事件。worker 循环位于各自的领域中 |
core、平台包;领域的 workers(注册表中的模块字符串) |
server/observability/ |
账本、事件、审计行、指标、追踪导出 | core、平台包 |
server/auth/ |
令牌的签发与验证、角色和命名空间网关、每请求身份 | core、平台包 |
server/embedding/、llm/ |
可插拔的 embedder 和 LLM providers | core、平台包 |
server/clients/、storage/ |
出站 HTTP(共享连接池、GitHub);保留期子句 | core、平台包 |
server/memory/ |
记忆平面:memory.*、搜索、ask、提取、事实、流程、画像、工作记忆、上下文包、冲突、黑名单、loom_search |
参见层次 |
server/code/ |
代码平面:code.*、索引(app/index/、domain/index/、store/index/)、其解析器(domain/extract/)、摄取和编译器层级的 workers |
参见层次 |
server/tracker/ |
Tracker 命名空间:tracker.*、重复检查、实时来源读取器及其客户端、loom 自身的 tracker 表 |
参见层次 |
server/knowledge/ |
知识文档和分块、对话、仓库文档 | 参见层次 |
server/erasure/ |
擦除 saga、其普查、联合后端、恢复 worker | 参见层次 |
server/tasks/ |
任务收件箱、运行账本、其唤醒和 webhook 循环 | 参见层次 |
server/identity/ |
命名空间、授权、历史策略、读取范围、受限访问、控制台页面和调用方 API(/v1/me/*) |
参见层次 |
server/insights/ |
运维界面:ops.*、cost.*、agents.*、audit.list、ui.vitals、mentor.brief、/v1/admin/* 路由 |
参见层次 |
server/assistant/ |
助手:其 LibreChat 服务用户和 agent 定义,在启动时设置 | 参见层次 |
平台包指 core 以及上表中其他非领域包:settings、operations、transport、cli、workers、observability、auth、embedding、llm、clients 和 storage。除 core 和 settings 外,每个平台包都可以导入任何其他平台包,除表中所列情形外,没有平台包会导入领域包。
层级
一个领域包最多包含五个子包。模块放在其主要职责所在的子包中;较小的领域子包更少。
| 层级 | 内容 | 可导入 |
|---|---|---|
api/ |
对外接口:Pydantic 输入和输出模型(models*.py),以及该领域各 op 组的 Operation 声明(ops*.py) |
core、operations、settings;任意领域的 domain 和 api;Operation 所绑定的处理函数所在的本领域 app |
app/ |
处理函数与编排:一个 op 或一次 worker 执行过程按顺序做什么,包括 I/O | 本领域的 api、app、domain、store;其他领域的 app、domain 和接口模型(api/models*.py);core 以及除 transport 和 cli 之外的所有平台包 |
domain/ |
纯逻辑、类型化的值和策略:不涉及 ClickHouse,不涉及网络 | core(不含其 I/O 模块:ch、schema、idempotency、ratelimit_shared、namespace_write_marks)、settings、任意领域的 domain |
store/ |
ClickHouse 仓库和行构建器:该领域对其表执行的每一条语句 | core、settings、observability、storage、本领域的 store、任意领域的 domain |
workers/ |
后台循环,每个注册表行对应一个模块 | 与 app 相同,只是用 workers 取代 api;其他领域的 app、domain 和接口模型 |
有一个 domain/ 模块会启动进程:server/code/domain/extract/bounded_parse.py。domain/ 中的每个 tree-sitter 解析器都会调用它,它先在受资源限制的本地子进程中解析每个源文件。
有两条依赖边被刻意排除。store/ 从不调用 app/:仓库接收值并返回行,因此可以用假的 store 来测试 app。另外,任何领域都不读取其他领域的 store/:它调用该领域的 app/ 或读取其 domain/ 类型,这样一张表的所有者就是其语句的唯一写入方。要调用其他领域的处理函数,app/ 和 workers/ 可以导入该领域的接口模型(api/models*.py),但绝不能导入它的 api/ops*.py。app/ 导入接口模型,而不导入 ops 模块,这样 Operation 声明就可以绑定处理函数而不产生导入循环。
导入约定
tests/unit/test_package_contracts.py 使用 ast 解析 server/ 下的每个模块,并按两端所属的包和层级对每条导入进行分类,包括顶层导入、嵌套在 if/try 下的导入、函数内部的导入,以及 TYPE_CHECKING 下的导入。上述规则不允许的导入会使测试失败,并给出导入方和被导入的模块。
目前违反该约定的导入列在 tests/unit/package_contract_allowlist.txt 中,按模块路径以 importer -> imported 的形式记录。这份列表只会缩减:如果某个已允许的导入对不再出现,测试同样会失败,因此修复一条导入就意味着删除对应的那一行。
旁边还有第二项检查:只有 server/transport/、server/cli/ 和 server/main.py 可以导入 server.transport(tests/unit/test_transport_layering.py)。任何领域模块都不得导入 server.cli。
添加模块
- 选择该模块所服务的表、op 组或平面所属的领域。服务于所有平面的模块(如 ClickHouse 辅助函数、哈希规则)放在
core/;服务于两个领域的模块,放在它所读取的行所属的领域,另一个领域调用它。 - 按模块的职责选择层级,而不是按调用方选择:涉及 I/O 或 await 某个对象的
async def放在app/或store/;仅依赖参数的函数放在domain/。 - 在包内按模块所存放的内容命名,不要重复路径:用
server/erasure/app/saga.py,而不是server/erasure/app/erasure_saga.py。 - 包的
__init__.py只保留一行 docstring,说明该包负责什么。只有当它是该包的公开接口时,才重新导出名称(server/memory/store/、server/code/store/index/)。 - 后台循环是
<domain>/workers/中的一个模块,外加server/workers/registry.py中的一行,写明其完整模块路径。 - mock 或 monkeypatch 的目标、注册表中的行以及覆盖率下限,都通过路径来指定模块;请使用模块的真实路径,不要通过重新导出来指定。
- 通过
server.core.paths查找服务器自带的文件(迁移、schema.sql、前端构建产物),不要通过数__file__的父目录层数来查找(tests/unit/test_repo_paths.py)。
Extractor 模块
extractor_stamp.STAGE_MODULES 中列出的文件是代码索引的版本戳。该版本戳对每个文件的名称和代码 token 做哈希,其中 import 按其绑定的名称计入,而不是按所来自的包计入。版本戳一旦变化,每个代码命名空间的索引都会重新生成。这些文件与 extractor_stamp.py 一起位于 server/code/domain/extract/ 中,由后者从自身所在目录读取它们,这些文件保持原有的文件名。各语言通道模块位于它们旁边。把其中一个文件在不同包之间移动,不会改变版本戳;重命名、重新格式化(ruff format 会排除它们)或修改其代码,则会改变版本戳。