跳转至

尚无译文的页面会以英语打开,并标注为英语。

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

使用你的编码 agent 安装 Loom

本页面向编码 agent(Claude Code 或 Codex),当它被要求在自己所运行的机器上安装 Loom 并证明安装可用时,可按本页操作。本页说明要运行什么、不要做什么、每项检查必须看到什么,以及需要给出的报告。每一步都可以直接照着运行;需要由人完成的步骤会有明确标记。

每个发布版本都会以纯文本形式附带本页,并填入对应的版本号和提交:

https://github.com/ClickHouse/loom/releases/latest/download/agent-setup.txt
https://github.com/ClickHouse/loom/releases/download/v<version>/agent-setup.txt

固定版本

此副本未指明任何发行版本,因此其中的命令无法直接运行。请按照你被要求安装的发行版本中的 agent-setup.txt 操作,其中下面所有的 <version> 和 <commit> 均已填好;如果没有指明发行版本,请按照最新版本的操作:https://github.com/ClickHouse/loom/releases/latest/download/agent-setup.txt。

规则

  • 不要使用 sudo,也不要安装或更改系统软件包。带 compose 插件的 Docker 必须已能在你的用户下运行,并且 curl、tar、python3、Node.js 18 或更高版本(插件的 hook 在其上运行)以及你自己的 CLI(claude 或 codex)必须在 PATH 中;如果缺少其中任何一项,请停止并报告。
  • 不要设置任何提供商密钥,也不要索要。没有密钥时,该技术栈也能启动,下面的每项检查都能通过。
  • 在第 1 步之前,如果你的环境中设置了任何 LOOM_* 变量(安装程序、插件和 SDK 都会读取它们:端口、绑定地址、另一台服务器),如果 ~/.loom 已存在,或者你的 CLI 已经认识某个 loom:插件(claude plugin list、codex plugin list)、插件市场(claude plugin marketplace list、codex plugin marketplace list)或 MCP 服务器(claude mcp list、codex mcp list),请停止并报告。是否更改其中任何一项,由使用者决定。如果以上都没有,该技术栈只在 localhost:7777 上响应,插件会连接到它。
  • 不要为了让检查通过而削弱检查:不要编辑检查脚本、跳过某个步骤、更改检查的预期内容,也不要为未运行的步骤报告 PASS。一行 FAIL 就是一份正确的报告。

1. 安装发布版本

mkdir -p ~/loom-agent-setup
curl -fsSL "https://github.com/ClickHouse/loom/releases/download/v<version>/install.sh" \
  -o ~/loom-agent-setup/loom-install.sh && sh ~/loom-agent-setup/loom-install.sh \
  && rm ~/loom-agent-setup/loom-install.sh

安装程序会校验安装包的 SHA-256,将其安装到 ~/.loom 下,启动整个服务栈,并等待服务器的 /v1/health 就绪。如果命令失败,报告中只需给出其 install 一行,不要继续往下进行。快速入门中完整说明了安装程序所做的事情。

2. 安装插件

插件来自同一版本的源码,因此与服务器版本一致:

curl -fsSL "https://github.com/ClickHouse/loom/archive/refs/tags/v<version>.tar.gz" \
  | tar -xz -C ~/loom-agent-setup

请保留 ~/loom-agent-setup:它是 marketplace 的源。然后,对于 Claude Code:

claude plugin marketplace add ~/loom-agent-setup/loom-<version>
claude plugin install loom@loom

对于 Codex:

codex plugin marketplace add ~/loom-agent-setup/loom-<version>
codex plugin add loom@loom

已安装的技术栈是单用户的,因此插件连接到 http://localhost:7777,无需令牌。用户现在需要启动一个新的 agent 会话(Codex:运行交互式 codex,并在其中批准插件的 hooks),再次把这段文字交给它,并说"从第 3 步继续"。第 3 步和第 4 步在该会话中运行。

3. 运行检查

将此脚本保存为 loom-setup-check.py,然后运行 python3 loom-setup-check.py。它只使用 Python 标准库,并通过 HTTP 与 Loom 通信。它写入命名空间 agent-setup-check,用本次运行自己的标签标记所写入的内容,只搜索本次运行写入的行,并在结束时删除它们。

loom-setup-check.py
import json
import os
import pathlib
import random
import sys
import urllib.error
import urllib.parse
import urllib.request

PIN_VERSION = "<version>"
PIN_COMMIT = "<commit>"
# Loom's own tests point the check elsewhere; an agent sets neither.
BASE = os.environ.get("SETUP_CHECK_URL", "http://localhost:7777")
WHO = {"org": os.environ.get("SETUP_CHECK_ORG", "dev"), "namespace": "agent-setup-check"}
AGENT = "agent-setup"
SESSION = "setup-1"
RUN = f"{random.randrange(100_000):05d}"
TAGS = [f"setup-check:{RUN}"]
FACT = f"The setup check orchard has {RUN} pear trees."
KEY = f"setup/check/orchard-{RUN}"
DOC = f"setup-check://irrigation-{RUN}"
NOTE = f"Irrigation valve {RUN} opens at five in the morning, every second day."
LOOPBACK = ("localhost", "127.0.0.1", "::1")
checks = []


def call(op, **body):
    req = urllib.request.Request(
        f"{BASE}/v1/{op}",
        data=json.dumps({**WHO, **body}).encode(),
        headers={"Content-Type": "application/json"},
    )
    try:
        with urllib.request.urlopen(req, timeout=60) as resp:
            return json.load(resp)
    except urllib.error.HTTPError as e:
        raise RuntimeError(f"{op} answered {e.code}: {e.read()[:200].decode(errors='replace')}")


def check(name, probe):
    try:
        grade, detail = probe()
    except Exception as e:  # any failure is this check's FAIL line
        grade, detail = "FAIL", f"{type(e).__name__}: {e}"
    checks.append((name, grade, detail))
    return grade == "PASS"


def hit_problem(hits, field, wanted, text_field):
    """Why the first hit is not the row this run wrote, or None when it is."""
    if not hits["results"]:
        return "no hits"
    top = hits["results"][0]
    if top[field] != wanted:
        return f"the first hit is {top[field]}, not {wanted}"
    if RUN not in top[text_field]:
        return f"{wanted} came back without its text"
    return None


def bind_host():
    """LOOM_BIND_HOST from the installed stack's .env, or "" when it sets none."""
    env = pathlib.Path.home() / ".loom" / ".env"
    lines = env.read_text().splitlines() if env.exists() else []
    values = [line.split("=", 1)[1].strip() for line in lines if line.startswith("LOOM_BIND_HOST=")]
    return values[-1] if values else ""


def server():
    if PIN_VERSION.startswith("<"):
        return "FAIL", "this copy names no release: use the release's agent-setup.txt"
    if urllib.parse.urlsplit(BASE).hostname not in LOOPBACK:
        return "FAIL", f"{BASE} is not a loopback address"
    host = bind_host()
    if host not in ("", *LOOPBACK):
        return "FAIL", f"~/.loom/.env publishes Loom on {host}"
    with urllib.request.urlopen(f"{BASE}/v1/health", timeout=30) as resp:
        health = json.load(resp)
    version, commit = health.get("version"), health.get("build_commit")
    # A release candidate's server reports the final version it leads to.
    final = PIN_VERSION.split("-")[0]
    if (version, commit) != (final, PIN_COMMIT):
        return "FAIL", f"serves {version} at {commit}; the pins name {final} at {PIN_COMMIT}"
    return "PASS", f"{BASE} serves {version} at {commit[:12]}"


def memory():
    call("memory.set", agent=AGENT, memory_key=KEY, value=FACT, tags=TAGS, session_id=SESSION)
    # A new session reads with no session_id: it sees what the last one wrote.
    hits = call(
        "memory.search", query="how many pear trees does the setup check orchard have", tags=TAGS
    )
    problem = hit_problem(hits, "memory_key", KEY, "content_excerpt")
    if problem:
        return "FAIL", problem
    similarity = float(hits["results"][0]["similarity"])
    return "PASS", f"a new session finds {KEY} (similarity {similarity:.2f})"


def knowledge():
    call("knowledge.add", agent=AGENT, source_uri=DOC, title="Irrigation", content=NOTE, tags=TAGS)
    hits = call("knowledge.search", query="when does the irrigation valve open", tags=TAGS)
    problem = hit_problem(hits, "source_uri", DOC, "content")
    if problem:
        return "FAIL", problem
    similarity = float(hits["results"][0]["similarity"])
    return "PASS", f"knowledge.search finds {DOC} (similarity {similarity:.2f})"


def cleanup():
    gone = call("memory.delete", agent=AGENT, memory_key=KEY, session_id=SESSION)["found"]
    dropped = call("knowledge.delete", source_uri=DOC)["deleted"]
    if not (gone and dropped):
        return "FAIL", f"memory deleted: {gone}, document deleted: {dropped}"
    return "PASS", "deleted the memory and the document it wrote"


# Nothing is written to a server the pins or the loopback rule refuse.
if check("server", server):
    check("memory", memory)
    check("knowledge", knowledge)
    check("cleanup", cleanup)
width = max(len(name) for name, _, _ in checks)
for name, grade, detail in checks:
    print(f"  [{grade}]  {name:<{width}}  {detail}")
failed = [name for name, grade, _ in checks if grade == "FAIL"]
if failed:
    print(f"\n{len(failed)} check(s) failed: {', '.join(failed)}")
    sys.exit(1)
print(f"\nAll {len(checks)} checks passed.")

每项检查必须看到的结果:

检查 通过条件
server URL 和 ~/.loom/.env 中的 LOOM_BIND_HOST 均为本地回环地址,并且 /v1/health 返回固定的版本(候选版本则为其最终版本)和提交。
memory 在一个会话中写入的事实,是不指定会话的搜索(如下一个会话所做的搜索)的第一条命中,带有其自身的文本和数值相似度。
knowledge 用 knowledge.add 添加的文档是 knowledge.search 的第一条命中,带有其自身的文本和数值相似度。
cleanup 脚本写入的记忆和文档均已删除。

当 server 检查失败时,脚本不会写入任何内容,也不会运行其他检查。

4. 检查 agent 的连接

使用查询 agent setup check 调用一次 loom_search 工具,并运行 claude plugin list(或 codex plugin list)。当该工具应答且没有报错,并且列表中显示 loom@loom 已启用时,输出的行是 [PASS] agent loom_search answered,否则是 [FAIL] agent <the tool's error, or the plugin's status>。

报告

先给出脚本输出的各行,再给出 agent 行,然后给出一条汇总,汇总中也要把 agent 行计算在内,格式与 loom doctor 相同:

  [PASS]  server     http://localhost:7777 serves 1.2.3 at 0123456789ab
  [PASS]  memory     a new session finds setup/check/orchard-04211 (similarity 0.91)
  [PASS]  knowledge  knowledge.search finds setup-check://irrigation-04211 (similarity 0.77)
  [PASS]  cleanup    deleted the memory and the document it wrote
  [PASS]  agent      loom_search answered

All 5 checks passed.

出现失败时,汇总写作 <n> check(s) failed: <names>,需要修复的是第一条 FAIL 行。中止运行的步骤只输出一行及其汇总:

  • 在第 1 步之前就中止的规则:[FAIL] setup <what was missing or found>;
  • 安装失败:[FAIL] install <the command's last line>;
  • 第 2 步失败:[FAIL] plugin <the failed command's last line>;

每种情况后面都跟一行 1 check(s) failed: <its name>。