尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 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 的门禁,参见测试。
新贡献者的阅读顺序
- README 和 系统概览:产品的对外功能和系统的整体结构。
server/operations/registry.py:所有传输层都会遍历的 wire-op 注册表。server/main.py,即 lifespan:迁移、worker 和传输层是如何接入的。- 与你要修改的内容对应的
server/<domain>/api/ops*.py中的 op 组,然后是server/<domain>/app/中的处理程序,以及它所调用的server/<domain>/store/中的仓库。 schemas/schema.sql:它读写的表。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 作为唯一引擎、身份元组、逐行内容哈希审计、五种信念修订操作)需要在拉取请求中说明设计理由,并更新对应的架构页面(重大变更)。