尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
扩展 Loom
Loom 为每一类事物各设一个注册表:操作、worker、设置、提供方、语言通道、提取步骤和 tracker 源。要扩展 Loom,只需向对应的注册表添加一行;HTTP、MCP、SDK 以及生成的参考文档都会随之更新。
请先确认仅靠数据是否就能满足需求。tracker 源、记录 schema、procedure 或历史策略都是通过配置完成的,无需编程。
flowchart LR
subgraph Data["Configure, no code"]
T["tracker source<br/>tracker.source.add"]
R["record schema<br/>memory_schema.register"]
P["history policy<br/>policy.set"]
end
subgraph Code["Add a registry row"]
O["operation<br/>server/<domain>/api"]
W["worker<br/>server/workers/registry.py"]
L["language lane<br/>server/code/domain/extract/lang_*.py"]
S["pipeline step<br/>register_step"]
V["provider<br/>server/embedding, server/llm"]
M["table / column<br/>schemas/migrations"]
end
subgraph Clients["Outside the server"]
I["plugins, hooks, skills<br/>integrations/"]
end
选择扩展点
| 你想要…… | 扩展点 | 位置 | 指南 |
|---|---|---|---|
| 向调用方开放新的能力 | 操作(operation) | server/<domain>/api/ops_<group>.py, server/<domain>/app/<group>.py |
添加操作 |
| 按计划在后台执行工作 | worker | server/<domain>/workers/<name>.py,以及 server/workers/registry.py 中的一行 |
添加 worker |
| 存储新的数据 | 表或列 | schemas/migrations/<NNN>_*.sql, server/<domain>/store/ |
添加表 |
| 为新的编程语言建立索引 | 代码索引语言通道 | server/code/domain/extract/lang_<lang>.py, lang_detect.py, server/code/app/index/ingest.py |
添加语言支持 |
| 为部分调用方改变提取时保留的内容 | 流水线步骤 | server/memory/app/pipeline.py 中的 register_step |
提取流水线 |
| 读取新的问题跟踪器或 CI 历史 | 跟踪器来源(仅数据) | tracker.source.add + tracker.source.set_mapping |
跟踪器记录约定 |
| 保存带有标识和类型化字段的事实 | 记录模式(仅数据) | memory_schema.register, memory.record.write |
写入记忆 |
| 根据 agent 的历史限制其可执行的操作 | 历史策略(仅数据) | policy.set |
令牌与授权 |
| 使用其他嵌入或 LLM 提供方 | 提供方客户端 | server/embedding/, server/llm/ |
见下文 |
| 添加设置项 | 设置字段 | server/settings/catalog.py 中对应领域的部分 |
见下文 |
| 从其他客户端采集会话,或提供 agent 指引 | 集成、钩子或技能 | integrations/, skills/ |
见下文 |
所有扩展的共同点
- 代码就是注册表。 传输层遍历
ALL_OPERATIONS,supervisor 遍历_WORKERS,设置参考文档由server/settings/生成。每个注册表都有快照测试或普查测试,在你重新生成之前测试会一直失败。 - 生成的文件。
make lint会以--check方式运行每个生成器:SDK 的 op 表(scripts/codegen/sdk_py_gen.py、sdk_ts_gen.py)、reach 清单(op_reach_census.py)、参考页面(docs_reference.py、settings_reference.py)以及 Codex 插件副本(agent_plugin_sync.py)。参见代码生成。 - 成熟度。 新增的 op 需声明
maturity="experimental",除非它替换的是一个稳定的 op(参见添加操作)。 - 度量。 对排序、提取或提供方默认值的任何改动,都要在改动前后运行相应的基准测试(参见性能调优)。
- 基础结构不是扩展点。 引擎(ClickHouse)、身份元组、逐行内容哈希审计以及五个信念修订操作,只有在 PR 和架构文档中给出设计依据后才能更改(参见系统概览)。
添加 provider
Embedder 和 LLM 都是由设置选定的客户端。
Embedder 放在 server/embedding/ 中,与 openai.py、gemini.py、local.py 和 fake.py 并列。它共用 server/embedding/_provider.py 中的 HTTP 基础代码:
- 仅在可重试的状态码上重试,总共尝试三次(含首次请求,即最多重试两次);
- 输入过长时抛出
EmbedderInputTooLarge,而不是由 provider 静默截断; - 向量为空、维度不符或含非有限值时抛出
MalformedEmbedding。
在 server/embedding/embedder.py 中接入:根据 LOOM_EMBEDDING_MODEL 推断 provider(_inferred_provider)、LOOM_EMBEDDING_PROVIDER 的取值,以及 KEY_ENVS 中的密钥变量。缺少密钥时会回退到 fake embedder,并记录一条错误日志。
LLM 放在 server/llm/ 中,与 openai.py、anthropic.py 和 fake.py 并列,并实现 LLMClient(server/llm/client.py)。在 _build_llm_client 中,以及在 DEFAULT_MODEL_BY_PROVIDER、KEY_ENV_BY_PROVIDER 和 resolve_llm_provider(server/core/llm_provider.py)中接入。
警告: provider 会影响质量。相似度阈值是按
text-embedding-3-small校准的。在将新 provider 设为默认之前,请先针对它运行make bench-quick。新增 embedder 后,需要对每个已有命名空间执行loom reembed。
添加设置
新字段放在 server/settings/catalog.py 中对应领域的分区里(MemorySearch、Code、Tracker 等),所有设置都在这一个文件中声明。字段上方的注释说明它控制什么以及各个取值的含义;该注释会成为生成的配置参考中对应的一行。环境变量名为 LOOM_<FIELD>。
读取时使用 settings.<field>,不要使用 getattr(settings, "<field>", default)。tests/unit/test_settings_attribute_access.py 会在出现后一种写法时失败:复制的默认值会逐渐与原值不一致,还会让删除该字段的人找不到读取它的位置。使用 python scripts/codegen/settings_reference.py 和 python scripts/codegen/settings_schema.py 重新生成。
要下线一个标志,请删除该设置、它对应的分支,以及携带它的所有请求级字段。仍然发送该字段的客户端依然会得到响应,该字段会列在 ignored_args 中。
添加集成
| 集成 | 位置 | 说明 |
|---|---|---|
| 编码 agent 插件的 hook 或 skill | integrations/claude-code-plugin/ (hooks/, lib/, skills/) |
这是权威来源;python scripts/codegen/agent_plugin_sync.py 会把脚本、skill 和列表图标 (assets/) 复制到 integrations/codex-plugin/。新增 hook 需要手动接入 Codex 的 hooks.json。当插件清单中的版本号变化时,已安装的客户端会获取更新。 |
| 其他客户端的会话捕获 hook | integrations/<client>/ (cursor/, generic/) |
调用 loom ingest-transcript 或 conversation.append,并使用 memory.set_from_messages 进行提取。 |
| 可移植的 agent skill | skills/<name>/SKILL.md |
可按名称安装到任何支持 Agent-Skills 的客户端;仅提供指引,不含 hook。 |
| 框架适配器 | sdk/python/loom/integrations/, sdk/typescript/src/integrations/ |
用框架的存储或记忆接口封装 SDK(Python 中有 LangGraph 的 LoomStore 和 Strands 的 LoomMemoryStore,TypeScript 中有 Strands 适配器)。 |
| 可观测性后端 | server/observability/ |
span 已带有 loom.request_id 并通过 OTLP 导出;优先使用 OTLP collector,而不是新增 exporter。 |
集成介绍了已提供的集成。Agent 集成说明了任何新客户端应当写入和读取的内容。