跳转至

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

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

添加操作

操作只在注册表中声明一次。HTTP 路由(POST /v1/<op>)、OpenAPI schema、MCP 工具(loom_<op with dots as underscores>)、目录(/v1/operations、ops.capabilities)、SDK 的操作表以及操作参考都由它派生。你需要编写模型、处理函数、声明和测试,然后重新生成其余内容。

flowchart LR
    M["Input / Output models<br/>server/&lt;domain&gt;/api/models_&lt;group&gt;.py"] --> D["Operation(...) in OPERATIONS<br/>server/&lt;domain&gt;/api/ops_&lt;group&gt;.py"]
    H["handler<br/>server/&lt;domain&gt;/app/&lt;group&gt;.py"] --> D
    D --> R["ALL_OPERATIONS"]
    R --> HTTP["HTTP /v1/&lt;op&gt;"]
    R --> MCP["MCP tool + toolsets"]
    R --> G["generated: sdk ops.py, ops.ts,<br/>reach manifest, reference/operations.md"]

示例是 calibration.get,它是最小的操作之一:server/memory/api/models_calibration.py、server/memory/api/ops_calibration.py 和 server/memory/app/calibration.py。

1. 定义输入和输出模型

把它们放在该分组的 models 模块中,即 server/<domain>/api/models_<group>.py。models 模块只包含 Pydantic 传输模型:它不导入任何 handler。

from pydantic import BaseModel, Field


class CalibrationGetInput(BaseModel):
    org: str
    namespace: str


class CalibrationGetOutput(BaseModel):
    source: str  # "namespace" / "cluster" / "scalar"
    embedder_model: str = ""
    noise_floor: float
    ...
    similar_pairs_n: int = Field(default=0)

模型的规则:

  • 身份。 按命名空间寻址的 op 接受 org 和 namespace。写入行的 op 还接受身份元组的其余部分:agent、user_id、session_id、run_id(后三者默认为 '-')。通过 MCP 调用时,服务器会用连接的默认值填充省略的身份字段,然后对请求体中指明的 (org, namespace) 进行授权。
  • 由服务器写入的列绝不取自请求体。 写入路径会设置 actor(server.memory.app.provenance.writer_actor)和 source_class(server.memory.domain.provenance.source_class_for)。请求只能声明降级为 derived、external 或 imported。
  • 对 MCP 隐藏与 agent 无关的字段。 用 json_schema_extra=MCP_HIDDEN(server/operations/base.py)标记排序参数或流水线开关。MCP schema 会省略该字段,但 op 仍然接受它。
  • 读取类输入不要使用模型级别的“A 或 B 二选一”校验器。 传输层会在授权之前校验请求体,因此一个会抛出异常的 @model_validator 会向命名空间门禁将会拒绝的主体暴露该 op 的信息。请把规则放在 handler 中,并抛出 server.core.errors.ValidationError。tests/unit/test_op_inputs_after_gate.py 会检查每个已注册的 op。
  • 要废弃某个字段,直接删除它。 仍然发送该字段的客户端依然会得到响应,并且该字段会列在 ignored_args 中(未知字段和已移除字段)。

2. 编写 handler

每个分组对应一个 handler 模块,位于 server/<domain>/app/ 下。handler 是 async 函数,接收输入模型并返回输出模型。它在模块顶部导入 wire 模型;模型从不导入 handler,因此导入关系是无环的:

from server.memory.api.models_calibration import CalibrationGetInput, CalibrationGetOutput


async def handle_calibration_get(input: CalibrationGetInput) -> CalibrationGetOutput:
    from server.memory.app.embedder_calibration import get_calibration, get_namespace_calibration

    ns_cal = await get_namespace_calibration(input.org, input.namespace)
    ...
  • 纯逻辑放在该领域的 domain/ 中,SQL 放在其 store/ 中。handler 负责组合它们。
  • 拒绝请求时,抛出 server.core.errors.LoomServerError 的子类(或带有 {"code", "message"} detail 的 HTTPException)。传输层会将其转换为错误信封,在 MCP 上则转换为 isError 结果。新增的错误码会出现在生成的错误参考中。
  • 宽泛的 except 要说明原因:except Exception as e: # noqa: BLE001 — <what must not fail>。
  • 传输层会用 log_comment 标记 ClickHouse 查询;handler 不需要做任何事。
  • 读取配置时使用 settings.<field>,不要使用 getattr(settings, ...)。
  • 如果该 op 写入 loom.memory 或 loom.shared,请使用 server/memory/store/rows.py 中的构建器来构造行(添加表)。

通过组织范围 id 寻址的 op

只接收 (org, memory_id) 的 op,例如 memory.get_by_id 或 memory.update_by_id,不会从传输层获得命名空间。请将其声明为 row_scoped=True,在读取之前先解析调用方可访问的命名空间,并隐藏属于其他命名空间的行:

import server.memory.store as memory_repo
from server.memory.app.id_namespace import namespace_for_id

namespace = await namespace_for_id(input.org, input.memory_id, strong=False)
if namespace is None:
    return MemoryGetByIdOutput(found=False)
row = await memory_repo.get_by_id(input.memory_id, org=input.org, namespace=namespace, ...)
if row is None:
    return MemoryGetByIdOutput(found=False)

应答方式与行不存在时相同,绝不返回 403:403 会确认该 id 存在于另一个租户中。写入时,向 namespace_for_id 传入 Role.WRITER 和 strong=True,以便读取最新的持有者。必须先读取行的 op,例如 memory.redact,在获取之后用 authz.row_in_scope 进行检查(行级范围的操作)。

3. 声明操作

from server.operations.base import Operation, Role

calibration_get = Operation(
    name="calibration.get",
    maturity="experimental",
    input_model=CalibrationGetInput,
    output_model=CalibrationGetOutput,
    handler=handle_calibration_get,
    idempotent=True,
    required_role=Role.VIEWER,
    audit=False,
)

OPERATIONS: list[Operation] = [calibration_get]

操作的延迟预算是 server/settings/catalog.py 中 OP_BUDGETS_P99_MS 的一个条目,所有 op 的预算都在这里设置,即 "calibration.get": 60,(该 op 设计目标的 p99,单位为 ms;调用成功但超出该值时会触发 budget.violated 事件)。handler 在运行时记录的请求形态(server.observability.budget_shape)在 OP_SHAPE_BUDGETS_P99_MS 中有各自的预算,目录中列出了这些预算。没有条目的 op 会导致 tests/unit/test_op_budgets.py 失败。部署时可以用 LOOM_LATENCY_BUDGET_OVERRIDES 调整单个 op,用 LOOM_LATENCY_BUDGET_MULTIPLIER 统一调整所有 op。

声明位于该分组的 ops 模块 server/<domain>/api/ops_<group>.py 中,该模块会导入模型和 handler。把它追加到模块的 OPERATIONS 列表中。新的分组模块需要在 server/operations/registry.py 中导入,并追加到 _OPERATION_MODULES。

字段 必填 含义
name 是 点分格式 <group>.<verb>。HTTP 路径为 /v1/<name>;MCP 工具为 loom_<name with . → _>。
input_model, output_model 是 Pydantic 模型。
handler 是 异步可调用对象:输入模型 → 输出模型。
idempotent 是 遇到瞬时故障时可以安全重试。SDK 和客户端依赖这一点。
required_role 是 Role.VIEWER、WRITER、ADMIN、ORG_ADMIN 或 PLATFORM_ADMIN。
audit 否 True:成功时向 loom.audit_log 写入一行。凡是会修改记忆、授权、策略或配置的操作都应设置。
writes 否 该 op 会修改已存储的状态,但 viewer 可以调用它且重试是安全的(例如一条反馈记录、一个已读标记)。writer 角色或 audit=True 本身已经表明会写入。
maturity 否 stable(默认)或 experimental。参见第 5 步。
skip_namespace_authz 否 对作用于命名空间本身的 op(join、leave、register),或目标只能由 handler 解析的 op(按 id 的 memory.verify、按范围的 erasure.request、按调用者角色的 erasure.list),跳过传输层的命名空间检查;由 handler 执行自己的规则。角色检查仍会执行。
deployment_scoped 否 该 op 读取的是部署本身的信息(其构建、其注册表),而不是任何命名空间的数据;带范围限定的令牌以其各命名空间中的最高角色通过。
row_scoped 否 通过组织范围的 id 寻址;handler 对该行所属的范围进行授权(读取前用 namespace_for_id,或读取后用 row_in_scope),并将不属于调用者的行视为不存在。

当且仅当 op 满足 idempotent、required_role == Role.VIEWER、非 audit 且非 writes 时(Operation.read_only),它才是只读的(MCP readOnlyHint,readonly 工具集)。自动批准只读工具的客户端会信任这些标志。

4. 决定 MCP 可见性

server/operations/toolsets.py 决定 op 在哪里列出:

  • 精选名单(_MCP_CORE_OPS、_MCP_CODING_OPS、_MCP_ATOMIC_OPS、_MCP_TASK_OPS、_MCP_TRACKER_OPS、_MCP_CODE_CORE_OPS)会把 op 列在对应的 ?toolset= 下。每个列出的属性在每一轮都会消耗 token,因此只添加该类 agent 会调用的内容。tests/unit/test_mcp_listing_budget.py 把列表限制在 token 上限之内。
  • 未列出(大多数 op):可在任意列表中通过 loom_op 按名称调用(在 readonly 下只能调用读操作,见 MCP 工具集)。?toolset=all 会列出 stable op,而 experimental op 只有在 core 或 atomic 名单列出它时才会列出(见 server/operations/toolsets.py 中的 listed_under_all)。
  • _MCP_HIDDEN_OPS:无法通过 MCP 访问。tests/unit/test_hidden_op_says_why.py 要求返回的拒绝信息中指明应改为调用什么。

已列出的 op 需要在 server/transport/mcp_descriptions.py(TOOL_DESCRIPTIONS)中提供描述。请面向模型来写:何时调用该工具、它返回什么、不应该用它做什么。关于已变更事实的描述,应插入同一模块中的 revision_policy(),而不是自行表述。引用其他 op 时使用其带点号的 op 名称;每个列表会把已列出的 op 改写为对应的工具名,并标出未列出的 op(MCP 参考)。切勿把 op 写成调用形式(op(args)),也不要写在更长的代码片段内,或手写“(via loom_op)”。作为字段示例值给出的 op 名称要放在单引号中('memory.ask'),列表会保持其原样。

5. 检查覆盖范围与成熟度

一个 op 的 覆盖范围(reach)是推导出来的(Operation.reach,server/operations/reach.py):它由该 op 是否属于 MCP 名单,加上对 SDK、examples/、dev/ 和 scripts/、插件 hook 以及控制台中 "/v1/<op>" 调用位置的一次已提交扫描共同决定。{"http_only"} 表示只有原始的 /v1/* POST 请求能访问它。

每个 op 要么出现在所有接口上,要么在代码中说明原因。HTTP 提供注册表中的每个 op,两个 SDK 也都由注册表生成。MCP 会覆盖该 op,除非 _MCP_HIDDEN_OPS 将其保留给用户和运维人员使用。当用户需要时,控制台会调用它:用于管理、审阅、检查、配置,或在确认后删除;这类新 op 在发布时要附带对应的控制入口。只有 agent 或客户端程序会调用的 op,或者控制台通过另一个 op 提供的 op,会在 NOT_IN_DASHBOARD(server/operations/dashboard.py)中列出并注明原因。普查工具的 --check(tests/unit/test_op_reach_census.py)会对既没有控制台调用位置、在 server/operations/dashboard.py 中也没有条目的 op 报错。

  • 对 MCP 隐藏且没有其他覆盖路径的 op(server/operations/reach.py 列出了这些类型),需要声明 maturity="experimental"。
  • stable op 要么列在 MCP all 工具集中,要么在对 MCP 隐藏时具有其他覆盖路径,并且应当有生产环境的调用方;python scripts/codegen/op_reach_census.py --call-counts --days 30 可以显示它是否有这样的调用方。除非新 op 取代某个 stable op,否则请将其声明为 experimental。
  • 刷新清单:python scripts/codegen/op_reach_census.py --write-manifest(写入 server/operations/reach_manifest.py)。

6. 编写测试

测试 对你的 op 的要求
tests/unit/ 下的单元测试 覆盖处理函数的拒绝路径和正常路径。
tests/integration/test_cross_principal_leakage.py 每个读取类 op 都以另一个租户的身份调用(另一个命名空间上的写入者和查看者,以及另一个组织),并带有 canary nonce;响应中不得包含任何 nonce,且每次调用都以 200(空结果)、403 或 404 结束,绝不能返回 500。请求内容由你的输入模型合成,因此新的读取类 op 在注册当天就会被探测。
tests/integration/test_restricted_namespace_leakage.py 对受限命名空间做同样的检查。
tests/unit/test_op_inputs_after_gate.py 你的输入模型在构造时不会出现模型级校验错误。
tests/unit/test_op_reach_census.py reach 与 maturity 一致,且 manifest 是最新的。
tests/unit/test_mcp_listing_budget.py 列出的 op 不会使列表超出预算,且其描述不会指向客户端无法调用的工具。

如果泄漏测试套件无法为你的 op 合成请求体,它会报告这一点;请添加提示(hint),不要跳过。会修改调用者自己命名空间的 op 应放入该套件的 _SKIP_OPS,写入者门禁由其他测试覆盖。集成测试需要一个运行中的服务器(LOOM_BASE_URL),没有时会跳过。请使用该套件的辅助函数签发令牌,不要使用自助注册,CI 未启用自助注册。

7. 重新生成并运行检查

python scripts/codegen/sdk_py_gen.py                       # sdk/python/loom/ops.py
python scripts/codegen/sdk_py_client_gen.py                # sdk/python/loom/client.py
python scripts/codegen/sdk_ts_gen.py                       # sdk/typescript/src/generated/ops.ts
python scripts/codegen/op_reach_census.py --write-manifest # server/operations/reach_manifest.py
python scripts/codegen/docs_reference.py                   # generated regions of docs/reference/*.md
make format
make lint          # ruff, gates, every generator with --check, the reach census --check, Biome's dashboard accessibility rules
make typecheck
make test-unit     # reach census, MCP listing budget

如果生成的文件已过期,CI 会失败。生成的 SDK 文件会让所有客户端同时获得该 op:Python 和 TypeScript 中的 agent.call("calibration.get", {...}) 会依据新的 TypedDict 和 interface 进行类型检查。SDK 客户端上的手写方法(sdk/python/loom/<group>.py)是可选的;对常用的操作可以添加一个。它算作一条 reach 路径。

python scripts/codegen/wire_changelog.py <rev_a> <rev_b> 会打印两个版本之间对客户端有影响的变更。发布说明就是据此生成的。

提交 PR 之前

  • 模型、handler、声明、OPERATIONS 条目(新增分组时还需要 _OPERATION_MODULES)。
  • 已审慎选定 required_role、idempotent、audit、writes、maturity。
  • row_scoped 操作对不属于调用方的行,返回与行不存在时相同的结果。
  • 工具集的归属,以及(如果列出)对应的描述。
  • 上述测试均已通过;生成的文件已重新生成。
  • 负责该操作的功能页面已链接到操作参考中对应的锚点。

相关内容