> Source: https://clickhouse.github.io/loom/zh-CN/development/repository-guide/ (Markdown: https://clickhouse.github.io/loom/zh-CN/development/repository-guide.md)

<!-- i18n: source=docs/development/repository-guide.md blob=680d8d038e278f6e630e4556f475452ba591d298 model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://clickhouse.github.io/loom/development/repository-guide/)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/development/repository-guide/), which is authoritative.

<a id="repository-guide"></a>

# 仓库指南

本文介绍每个顶层目录存放的内容、各项功能在 `server/` 中的位置、阅读代码的推荐顺序，以及拉取请求必须遵守的约定。

<a id="top-level-layout"></a>

## 顶层布局

| 路径                                                                                                                                                         | 内容                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server/`                                                                                                                                                    | FastAPI 服务器：领域包（记忆、代码、tracker 等）、操作注册表、worker、传输层、CLI、设置                                                                                                                                                                                                                                                                                                  |
| `extractor/`                                                                                                                                                 | 参考 extractor 服务（`loom_extractor/`）：格式检测和文档解析器，在服务器之外运行；其镜像（`Dockerfile`，以 `ghcr.io/clickhouse/loom-extractor` 发布）和锁文件（`uv.lock`）；参见[文档提取](https://github.com/ClickHouse/loom/blob/main/docs/architecture/document-extraction.md)                                                                                                |
| `sdk/python/`                                                                                                                                                | Python SDK，以 `clickhouse-loom` 发布（`sdk/python/loom/`）                                                                                                                                                                                                                                                                                                                              |
| `sdk/typescript/`                                                                                                                                            | TypeScript SDK，以 `@clickhouse/loom` 发布（`sdk/typescript/src/`）                                                                                                                                                                                                                                                                                                                      |
| `frontend/`                                                                                                                                                  | 在 `/` 提供的 React 控制台（Vite + Tailwind）；`src/`、`e2e/` 中的 Playwright 测试用例、`scripts/bundle_budget.mjs`                                                                                                                                                                                                                                                                     |
| `schemas/`                                                                                                                                                   | `migrations/`（带编号的 SQL）、`schema.sql`（生成的当前结构）、`otel/`（ClickStack OTel 表）、`ops/`（手动运行的 SQL）；参见 [`schemas/README.md`](https://github.com/ClickHouse/loom/blob/main/schemas/README.md)                                                                                                                                                                                                        |
| `dev/`                                                                                                                                                       | compose 栈、运维脚本（`loom_ingest.py`、`loom_init.py`、`onboard_tenant.py`、备份与恢复、`verify_audit_chain.py`）、`ci_start_clickhouse.sh`、`redeploy_preflight.sh`                                                                                                                                                                                                                     |
| `deploy/`                                                                                                                                                    | ClickHouse 服务器配置（`clickhouse-config/`）、Lemmagen3 模型（`lemmagen3/`）、蓝绿代理（`proxy/`）、Helm chart（`helm/`）、仓库任务沙箱 AppArmor 配置文件（`apparmor/`）、独立部署的环境模板（`standalone/`）、定时命名空间复制 CronJob（`okf-sync/`）、控制台（`dashboards/`、`hyperdx_dashboards.md`、`clickstack_sources.sh`） |
| `bench/`                                                                                                                                                     | 基准测试工具与门禁、其固定数据（`fixtures/`）、数据集、评分标准、验收与 skill 评测；参见[基准测试](https://clickhouse.github.io/loom/zh-CN/benchmarks/overview/)                                                                                                                                                                                                                                                             |
| `integrations/`                                                                                                                                              | 客户端集成：Claude Code 和 Codex 插件、Cline hooks、grep shim、Cursor 和通用转录 hooks、OKF CI 门禁                                                                                                                                                                                                                                                                                      |
| `skills/`                                                                                                                                                    | 独立的 Agent Skills：`loom-code`，以及 `loom`（服务器镜像附带并由 `mentor.guide` 提供的 agent 指南）                                                                                                                                                                                                                                                                                      |
| `scripts/`                                                                                                                                                   | `codegen/`（生成器）、`gates/`（CI 棘轮与守卫）、`ops/`（运维工具）、`scip_harness/`（编译器层级的生产者）、`docs_site/`（文档站点的 hook、主题覆盖、固定版本的构建器和 IndexNow 提交）、`i18n/`（翻译生成器及其新鲜度检查）                                                                                                                                                              |
| `tests/`                                                                                                                                                     | `unit/`、`integration/`、`analyzer/`、`code_lanes/`、`fixtures/`（见下文）                                                                                                                                                                                                                                                                                                               |
| `examples/`                                                                                                                                                  | 可运行的集成示例（`claude_agent_loop.py`、`ledger_run.py`、`log_conversation.py`、`onboarding_walkthrough.py`），以及教师复制到自己仓库中的课程起始模板（`course-starter/`，[教学](https://github.com/ClickHouse/loom/blob/main/docs/guides/teaching.md#hand-out-the-labs-as-an-assignment)）                                                                                            |
| `i18n/`                                                                                                                                                      | README、快速开始和用例页面的机器翻译，`LANGUAGES` 中每种语言一个文件夹；由 `scripts/i18n/translate.py` 生成（`.github/workflows/i18n.yml`），从不手动编辑                                                                                                                                                                                                                                 |
| `docs/`                                                                                                                                                      | 本文档；`mkdocs.yml` 和 `scripts/docs_site/` 将其构建为文档站点（`.github/workflows/docs-site.yml`）                                                                                                                                                                                                                                                                                     |
| `.github/`                                                                                                                                                   | CI、发布和扫描工作流（`workflows/`）、issue 和 pull request 模板，以及 `social-preview.png`，即在 Settings → General → Social preview 中上传的图片（GitHub 只读取上传的副本）                                                                                                                                                                                                              |
| `.devcontainer/`                                                                                                                                             | GitHub Codespaces 试用环境：一个使用安装程序安装最新版本并连接 Claude Code 的 dev container；不是开发环境（[快速开始](https://clickhouse.github.io/loom/zh-CN/getting-started/quickstart/#try-it-in-github-codespaces)）                                                                                                                                                                                                      |
| `Dockerfile`, `Makefile`, `redeploy.sh`, `pyproject.toml`, `uv.lock`                                                                                         | 服务器的镜像、任务运行器、蓝绿部署脚本、服务器包及其锁文件                                                                                                                                                                                                                                                                                                                               |
| `server.json`, `context7.json`, `CITATION.cff`, `gemini-extension.json`, `.claude-plugin/`, `.cursor-plugin/`, `plugin.json`, `mcp.json`, `.agents/plugins/` | MCP Registry 条目、文档索引配置、GitHub 显示为 "Cite this repository" 的引用文件、Gemini CLI 扩展清单、带有 `loom-code` skill 清单的 Claude Code 市场、Cursor 市场和插件、GitHub Copilot CLI 安装的 Agent Plugins 包、Codex 市场                                                                                                                                                          |
| `llms-install.md`                                                                                                                                            | 编码 agent 安装 Loom 并将其添加为 MCP 服务器所遵循的步骤                                                                                                                                                                                                                                                                                                                                 |
| `AGENTS.md`, `CLAUDE.md`                                                                                                                                     | 每个编码 agent 都会读取的指令；`CLAUDE.md` 导入 `AGENTS.md`                                                                                                                                                                                                                                                                                                                              |
| `.claude/`, `.agents/skills/`                                                                                                                                | agent 的 skills、按路径限定的规则、只读的审查者子 agent 及其 hook，以及项目权限设置；`.agents/skills/` 为 Codex 链接每个 skill                                                                                                                                                                                                                                                            |

<a id="inside-server"></a>

## server/ 内部

`server/` 按领域组织。请求从某个传输层进入，由操作注册表分派给某个领域 `app/` 中的处理器，处理器运行 `domain/` 中的纯逻辑，并通过 `store/` 中的仓库进行读写，领域的 SQL 都保存在这些仓库里。[服务器布局](https://clickhouse.github.io/loom/zh-CN/architecture/server-layout/)给出了完整的结构图，以及由契约测试强制执行的导入规则；请求路径见[系统概览](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md)。

| 包 / 模块                                                                                               | 作用                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `memory/`, `code/`, `tracker/`, `knowledge/`, `erasure/`, `tasks/`, `identity/`, `insights/`            | 领域包；每个包最多包含五层：`api/`（线上传输模型 `models*.py` 和 `Operation` 列表 `ops*.py`）、`app/`（处理器与编排）、`domain/`（纯逻辑）、`store/`（ClickHouse 仓库与行构建器；`memory/store/rows.py` 存放版本行构建器）、`workers/`（后台循环） |
| `operations/`                                                                                           | 注册表核心：`Operation` 和 `Role`（`base.py`）；`registry.py` 导入每个领域的操作组并构建 `ALL_OPERATIONS` 和 `OPERATIONS_BY_NAME`；`toolsets.py`、读取投影、覆盖范围普查                                                                                                                                                      |
| `transport/`                                                                                            | HTTP（`http.py`）和 MCP（`mcp.py`，以及 `mcp_schemas`、`mcp_config`、`mcp_tools`、`mcp_identity`）、参数反馈、请求体限制                                                                                                                                                                                                    |
| `workers/`                                                                                              | worker 注册表（`registry.py`、`_WORKERS`）以及运行它的监督器（`supervisor.py`）；每个循环位于其所属领域的 `workers/` 中                                                                                                                                                                                                     |
| `settings/`                                                                                             | 所有设置都在 `catalog.py` 中，每个领域一个分节，组合成 `Settings`                                                                                                                                                                                                                                                           |
| `auth/`                                                                                                 | JWT 的签发与验证、角色与授权、登录、OIDC、自助注册、吊销                                                                                                                                                                                                                                                                    |
| `embedding/`, `llm/`                                                                                    | 可插拔的提供方接口（OpenAI、Anthropic、Gemini、本地、fake）、缓存与回退                                                                                                                                                                                                                                                      |
| `observability/`                                                                                        | 账本发射器、审计日志、成本核算与预算、OTel 指标与 span、`/v1/health` 报告的 `problems` 列表                                                                                                                                                                                                                                  |
| `clients/`                                                                                              | 外部服务的 HTTP 客户端（共享的提供方连接池、GitHub）                                                                                                                                                                                                                                                                         |
| `storage/`                                                                                              | 按表的 TTL 组合                                                                                                                                                                                                                                                                                                              |
| `cli/`                                                                                                  | `loom` 命令树（由 `app.py` 组装）                                                                                                                                                                                                                                                                                            |
| `main.py`, `boot.py`, `health.py`, `wiring.py`                                                          | FastAPI 应用及其生命周期（worker、传输层）、启动与关闭步骤（启动迁移、吊销快照）、`/v1/health` 以及 `wire()`                                                                                                                                                                                                                |
| `core/ch.py`                                                                                            | ClickHouse 客户端、连接池和查询归因（`set_query_tag`）                                                                                                                                                                                                                                                                       |
| `core/errors.py`                                                                                        | 类型化错误（`LoomServerError` 的子类）及其 HTTP 状态                                                                                                                                                                                                                                                                         |
| `core/ratelimit.py`, `core/ratelimit_shared.py`, `core/idempotency.py`, `memory/app/blacklist_guard.py` | 请求路径上的防护                                                                                                                                                                                                                                                                                                             |
| `core/schema/`                                                                                          | 迁移运行器（`migrate.py`）及其跨容器锁（`migrate_lease.py`），以及运行器和重建工具共用的 schema 重写（`table_rebuild.py`、`vector_codec_ddl.py`）                                                                                                                                                                            |

<a id="inside-tests"></a>

## tests/ 目录内部

| 路径                 | 内容                                                                                                                                                           |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tests/unit/`        | 不需要 ClickHouse 的快速测试；`snapshots/`（CLI 命令树与帮助、worker 注册表、SDK 公共 API）、`fixtures/`，以及共享的辅助代码                                   |
| `tests/integration/` | 针对运行中的服务器和 ClickHouse 的测试（由 `tests/conftest.py` 和 `tests/integration/conftest.py` 负责接入），包括跨主体泄漏探测                               |
| `tests/analyzer/`    | 语句语料库：每个 SQL 构建器的各种形态，在已完成迁移的空表上通过 `EXPLAIN QUERY TREE` 运行；参见其 [README](https://github.com/ClickHouse/loom/blob/main/tests/analyzer/README.md) |
| `tests/code_lanes/`  | SQL 与 shell 通道语料库：代码索引从 `tests/fixtures/code_lanes/` 中得到的结果，与已提交的预期结果进行比较                                                       |
| `tests/fixtures/`    | 各测试套件共享的输入                                                                                                                                           |

各测试套件如何运行、跳过以及如何作为 CI 的门禁，参见[测试](https://clickhouse.github.io/loom/zh-CN/development/testing/)。

<a id="reading-order-for-a-new-contributor"></a>

## 新贡献者的阅读顺序

1. [README](https://github.com/ClickHouse/loom/blob/main/i18n/zh-CN/README.md) 和 [系统概览](https://github.com/ClickHouse/loom/blob/main/docs/architecture/system-overview.md)：产品的对外功能和系统的整体结构。
2. [`server/operations/registry.py`](https://github.com/ClickHouse/loom/blob/main/server/operations/registry.py)：所有传输层都会遍历的 wire-op 注册表。
3. `server/main.py`，即 lifespan：迁移、worker 和传输层是如何接入的。
4. 与你要修改的内容对应的 `server/<domain>/api/ops*.py` 中的 op 组，然后是 `server/<domain>/app/` 中的处理程序，以及它所调用的 `server/<domain>/store/` 中的仓库。
5. [`schemas/schema.sql`](https://github.com/ClickHouse/loom/blob/main/schemas/schema.sql)：它读写的表。
6. [`AGENTS.md`](https://github.com/ClickHouse/loom/blob/main/AGENTS.md) 和 `.claude/rules/`：各项约定及其原因。

<a id="conventions-that-are-not-obvious"></a>

## 不太明显的约定

[CONTRIBUTING.md](https://github.com/ClickHouse/loom/blob/main/CONTRIBUTING.md#conventions-that-arent-obvious) 列出了这些约定，[`AGENTS.md`](https://github.com/ClickHouse/loom/blob/main/AGENTS.md) 以及 `.claude/rules/` 下的规则则给出了原因。以下测试和检查关卡会强制执行这些约定：

| 检查关卡                                                                         | 保证的内容                                               |
| -------------------------------------------------------------------------------- | -------------------------------------------------------- |
| 生成的 SDK 表、覆盖范围普查（[代码生成](https://clickhouse.github.io/loom/zh-CN/development/code-generation/)）                    | op 是注册表中的行                                        |
| `tests/integration/test_cross_principal_leakage.py`                              | 使用组织级 id 的 op 会将外部主体的行隐藏为 `found=False` |
| `test_memory_versions_schema.py`                                                 | `loom.memory` 的列会镜像到 `loom.memory_versions`        |
| `test_migrations_additive.py`、账本校验和（[迁移](https://github.com/ClickHouse/loom/blob/main/docs/development/migrations.md)） | 迁移只做增量，且从不被修改                               |
| `test_every_table_is_classified.py`                                              | 每张表都已为数据擦除分类                                 |
| `test_settings_attribute_access.py`、`test_settings_reference.py`                | 设置以 `settings.<field>` 的方式读取，参考文档保持最新   |
| `test_worker_registry_snapshot.py`、`test_worker_registry_parity.py`             | worker 是注册表中的行                                    |
| ruff `BLE001`                                                                    | 宽泛的 except 必须说明原因                               |
| `scripts/gates/function_length_gate.py`                                          | 任何函数都不得超出其基线长度                             |
| `tests/unit/test_public_copy.py`                                                 | 仓库文本与具体产品无关                                   |

基础性的设计（以 ClickHouse 作为唯一引擎、身份元组、逐行内容哈希审计、五种信念修订操作）需要在拉取请求中说明设计理由，并更新对应的架构页面（[重大变更](https://github.com/ClickHouse/loom/blob/main/CONTRIBUTING.md#material-changes)）。

<a id="related"></a>

## 相关内容

- [本地开发](https://github.com/ClickHouse/loom/blob/main/docs/development/local-development.md)、[测试](https://clickhouse.github.io/loom/zh-CN/development/testing/)、[代码生成](https://clickhouse.github.io/loom/zh-CN/development/code-generation/)
- [添加操作](https://clickhouse.github.io/loom/zh-CN/development/adding-an-operation/)、[添加 worker](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-worker.md)、[添加表](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-a-table.md)、[添加语言支持](https://github.com/ClickHouse/loom/blob/main/docs/development/adding-language-support.md)、[扩展 Loom](https://clickhouse.github.io/loom/zh-CN/development/extending-loom/)
