跳到内容
ClickHouse Loom
Esc
↑↓导航↵打开⌘J预览
本页内容

仓库指南

本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.

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

顶层布局

路径 内容
server/ FastAPI 服务器:领域包(记忆、代码、tracker 等)、操作注册表、worker、传输层、CLI、设置
extractor/ 参考 extractor 服务(loom_extractor/):格式检测和文档解析器,在服务器之外运行;其镜像(Dockerfile,以 ghcr.io/clickhouse/loom-extractor 发布)和锁文件(uv.lock);参见文档提取
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
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 评测;参见基准测试
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/,教学)
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;不是开发环境(快速开始)
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

server/ 内部

server/ 按领域组织。请求从某个传输层进入,由操作注册表分派给某个领域 app/ 中的处理器,处理器运行 domain/ 中的纯逻辑,并通过 store/ 中的仓库进行读写,领域的 SQL 都保存在这些仓库里。服务器布局给出了完整的结构图,以及由契约测试强制执行的导入规则;请求路径见系统概览。

包 / 模块 作用
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)

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
tests/code_lanes/ SQL 与 shell 通道语料库:代码索引从 tests/fixtures/code_lanes/ 中得到的结果,与已提交的预期结果进行比较
tests/fixtures/ 各测试套件共享的输入

各测试套件如何运行、跳过以及如何作为 CI 的门禁,参见测试。

新贡献者的阅读顺序

  1. README 和 系统概览:产品的对外功能和系统的整体结构。
  2. 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:它读写的表。
  6. AGENTS.md 和 .claude/rules/:各项约定及其原因。

不太明显的约定

CONTRIBUTING.md 列出了这些约定,AGENTS.md 以及 .claude/rules/ 下的规则则给出了原因。以下测试和检查关卡会强制执行这些约定:

检查关卡 保证的内容
生成的 SDK 表、覆盖范围普查(代码生成) 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、账本校验和(迁移) 迁移只做增量,且从不被修改
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 作为唯一引擎、身份元组、逐行内容哈希审计、五种信念修订操作)需要在拉取请求中说明设计理由,并更新对应的架构页面(重大变更)。

相关内容

这个页面有帮助吗?