> Source: https://clickhouse.github.io/loom/zh-CN/reference/operations/procedure/ (Markdown: https://clickhouse.github.io/loom/zh-CN/reference/operations/procedure.md)

<!-- i18n: source=docs/reference/operations/procedure.md blob=7ffae765f4965c91d0da72b0ded6b8bb9483dfb3 model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://clickhouse.github.io/loom/reference/operations/procedure/)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://clickhouse.github.io/loom/reference/operations/procedure/), which is authoritative.

<a id="procedure-operations"></a>

# `procedure` 操作

每个 `procedure.*` 操作接受和返回的确切字段。

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

每个操作都是通过 HTTP 的 `POST /v1/<op>` 以及 MCP 工具 `loom_<op>`。当传输方式支持时，身份字段（`org`、`namespace`、`agent`、`user_id`、`session_id`）会从令牌和 MCP 会话中填充；对于单用户服务器上不带令牌的 HTTP 调用，除 `code.*` 和 `tracker.*`（它们保留各自平面的 org）之外的所有操作都使用该安装的 org，而在[部分操作](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)上，其命名空间和 agent 也会如此填充；参见[身份与命名空间](https://clickhouse.github.io/loom/zh-CN/concepts/identities-and-namespaces/)。[操作索引](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)说明了 role、kind 以及 MCP 的 `all` 列表。未知的输入字段仍会被处理，并在 `ignored_args` 中列出。

<!-- prettier-ignore-start -->

<a id="procedureadd"></a>

## `procedure.add`

注册一条程序性记忆，即“如何做 X”的方法，包含结构化的 (name, situation, steps) 字段。

`POST /v1/procedure.add` · MCP `loom_procedure_add` · 角色 `writer` · 写入

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（标识元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `'-'` | 执行写入或读取的 agent；在操作允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `name` | `str` | 必填 | 程序名称；记忆键为 `procedure_<slug of name>`，因此同名会覆盖重写。 |
| `situation` | `str` | 必填 | 该程序适用的时机（前置条件）；这段文本决定 `procedure.match` 的匹配结果。 |
| `steps` | `list[str]` | 必填 | 至少两步：只有一步是经验教训，而不是程序（挖掘器也遵循同一条界线）。 |
| `tags` | `list[str]` | *(计算得出)* | 存储在该程序上的调用方标签；该行还会获得标签 `procedure`。 |
| `metadata` | `dict[str, Any]` | *(计算得出)* | 可选的结构化元数据（以键值形式表示的前置条件、预期输出等）。 |
| `graph` | `dict[str, Any] \| None` | `None` | 可选的可执行图（节点 = 步骤 / 记忆 / 整合 / 决策，边 = dep / dataflow / branch）。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `memory_key` | `str` | 程序行的键（`procedure_<slug>`）。 |
| `memory_id` | `str` | 所写入记忆版本的 id。 |
| `version` | `int` | 所写入行的版本号。 |

<a id="procedureevolve"></a>

## `procedure.evolve`

将一个流程（procedure）累积的运行轨迹整合为改进后的图：按成功的遍历次数对已验证的路径排序，将没有任何一次运行用过的步骤标记为死胡同，并标记那些位于…

`POST /v1/procedure.evolve` · MCP `loom_procedure_evolve` · 角色 `writer` · 写入 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（标识元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `'-'` | 写入或读取的 agent；在操作允许时，`'-'` 或 `'*'` 表示任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的最终用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `memory_key` | `str` | 必填 | 要演化的流程的键（`procedure_<slug>`）。 |
| `min_runs` | `int` | `3` | 剪枝依据证据行动之前，需要合并的最少运行次数。 |
| `gate_mode` | `Literal['sprt', 'margin']` | `'sprt'` | 待定修订版本的接受门限。 |
| `gate_min_runs` | `int` | `3` | 在给出任何结论之前，被测试的修订版本所需的运行次数。 |
| `gate_margin` | `float` | `0.05` | margin 模式：触发回退的成功率下降幅度。 |
| `gate_min_drop` | `float` | `0.15` | sprt 模式：值得回退的下降幅度、错误率，以及超过该运行次数后由点估计做决定。 |
| `gate_alpha` | `float` | `0.05` | sprt 模式：误回退的错误率；越低，回退前所需的证据越多。 |
| `gate_beta` | `float` | `0.2` | sprt 模式：漏判下降的错误率；越低，接受前所需的证据越多。 |
| `gate_max_runs` | `int` | `50` | sprt 模式：修订版本上的运行次数达到该值后，由点估计做决定。 |
| `strike_limit` | `int \| None` | `None` | 使流程被隔离的连续失败运行次数；None = LOOM_PROCEDURE_STRIKE_LIMIT（3），0 = 从不隔离。 |
| `gate_cost_tolerance` | `float` | `0.25` | 对已接受修订版本的成本平局裁决：当其成功运行的成本比前一修订版本高出该比例以上时回退（以时长、步骤数、token 中第一个双方都有报告的指标为准）；双方都需要 `gate_cost_min_samples` 次有成本记录的成功运行… |
| `gate_cost_min_samples` | `int \| None` | `None` | 成本检查时每一方所需的有成本记录的成功运行次数；`None` = `gate_min_runs`。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `memory_key` | `str` | 已演化的流程的键。 |
| `version` | `int` | 本次调用写入的流程行的版本。 |
| `revision` | `int` | 本次调用之后该流程的拓扑修订号（回退会开启一个新的修订）。 |
| `changed` | `bool` | 本次调用改变了图的标记或隔离状态时为 True。 |
| `template` | `bool` | 该流程现在是可复用的模板（稳定、多数成功、未被隔离）时为 True。 |
| `folded_runs` | `int` | 本次调用合并进图中的账本行数。 |
| `gate` | `Literal['none', 'undecided', 'accept', 'revert']` | 待定修订版本的接受门限：none（没有待定项）、undecided（运行次数尚不足）、accept、revert。 |
| `gate_mode` | `str` | 所使用的门限模式（`sprt` 或 `margin`）；没有待定修订版本时为 ""。 |
| `gate_llr` | `float` | sprt：累积的对数似然比（正值倾向于“该修订版本使情况变差”）；越过边界时给出结论。 |
| `gate_before` | `dict[str, int]` | {total, ok}，前一修订版本 |
| `gate_after` | `dict[str, int]` | {total, ok}，被测试的修订版本 |
| `gate_cost_before` | `dict[str, float]` | 每一方成功运行的成本中位数，以及已通过成功率门限的修订版本仍被回退的原因（"cost"）。 |
| `gate_cost_after` | `dict[str, float]` | 被测试修订版本上成功运行的成本中位数。 |
| `gate_reason` | `str` | 回退时为 `success` 或 `cost`；否则为 ""。 |
| `dead_end_steps` | `list[str]` | 没有任何已合并运行遍历过的步骤文本（从线性的 `steps` 中降级）。 |
| `fail_prone_steps` | `list[str]` | 结果对比：不成比例地出现在失败运行中的步骤/转换（失败占比 >= 流程的基础失败率 + 余量，且运行次数足够）。 |
| `fail_prone_transitions` | `list[str]` | 不成比例地出现在失败运行中的转换，以 `src -> dst` 节点 id 表示。 |
| `run_stats` | `dict[str, int]` | 本次调用之后该流程已合并的 `{total, ok}`。 |
| `strikes` | `int` | 轨迹日志末尾的连续失败运行次数，以及该流程是否已被淘汰。 |
| `quarantined` | `bool` | 流程被淘汰时为 True（参见 `strike_limit`）。 |
| `retention` | `dict[str, float]` | 轨迹日志上的成功留存：首次运行成功的相邻运行对、其中第二次也成功的数量，以及比率。 |

<a id="procedurefork"></a>

## `procedure.fork`

将调用方有读取权限的命名空间中的 procedure 复制到请求所在的命名空间，并重置其证据。

`POST /v1/procedure.fork` · MCP `loom_procedure_fork` · 角色 `writer` · 写入 · 已审计 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 目标（请求所在的命名空间；该操作强制要求 WRITER 角色） |
| `agent` | `str` | `'-'` | 写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许时匹配任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `from_namespace` | `str` | 必填 | 复制的来源命名空间；调用方需要对其有读取权限。 |
| `from_org` | `str` | `''` | 默认为 `org` |
| `memory_key` | `str` | 必填 | `from_namespace` 中要复制的 procedure 的键。 |
| `new_name` | `str` | `''` | 复制时重命名（记忆键由名称派生）。 |
| `reason` | `str` | `''` | 采用该 procedure 的原因；保存在 `forked_from` 中。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `memory_key` | `str` | 目标命名空间中新 procedure 的键。 |
| `version` | `int` | 所写入行的版本。 |
| `name` | `str` | 新 procedure 的名称（`new_name` 或来源的名称）。 |
| `steps` | `list[str]` | 复制的步骤。 |
| `forked_from` | `dict[str, Any]` | 血缘信息：来源 org、命名空间、键、修订版本、摘要、模板标记、运行统计、fork 的执行者、原因和时间。 |

<a id="procedurelist"></a>

## `procedure.list`

列出命名空间中已注册的 procedure（可按 memory_key 前缀或标签过滤）。

`POST /v1/procedure.list` · MCP `loom_procedure_list` · 角色 `viewer` · 读操作 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `'*'` | 写入或读取的 agent；在操作允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `prefix` | `str` | `''` | 仅返回键以 `procedure_` 加此值开头的 procedure；"" 表示列出全部。 |
| `tags` | `list[str]` | *（计算得出）* | 仅返回至少带有其中一个标签的 procedure；为空表示不按标签过滤。 |
| `limit` | `int` | `50` | 最多读取这么多条 procedure 行（服务器上限为 500）。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `procedures` | `list[_ProcedureSummary]` | 该命名空间的 procedure（名称、适用情形、标签、键、创建时间）。 |

<a id="procedurelocate"></a>

## `procedure.locate`

我在这个流程中处于哪一步，接下来是什么？

`POST /v1/procedure.locate` · MCP `loom_procedure_locate` · 角色 `viewer` · 读取 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `'*'` | 写入或读取的 agent；在操作允许时，`'-'` 或 `'*'` 表示任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示没有。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示没有。 |
| `memory_key` | `str` | 必填 | agent 正在遵循的流程的键（`procedure_<slug>`）。 |
| `at` | `str` | `''` | agent 所处的位置：节点 id，或其最近一次调用的工具名。 |
| `recent_path` | `list[str]` | *（自动计算）* | agent 在本次运行中最近经过的节点 id 或工具名，最早的在前；用于计算 `revisits` 和 `looping`。 |
| `hops` | `int` | `2` | 向前展示多远。2 足够用于下一步决策；更多会消耗更多 token。 |
| `include_notes` | `bool` | `True` | 为前方的转换附上账本中最近的失败备注。 |
| `max_notes` | `int` | `5` | 失败备注的最大数量；0 表示不附加。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `memory_key` | `str` | 所读取流程的键。 |
| `name` | `str` | 流程的名称。 |
| `status` | `Literal['template', 'exercised', 'authored', 'candidate', 'quarantined']` | `template`、`exercised`、`authored`、`candidate` 或 `quarantined`。 |
| `matched` | `bool` | 当 `at`（或 `recent_path` 的最后一项）对应图中的某个节点时为 True。 |
| `active` | `dict[str, Any] \| None` | agent 所在的节点；未匹配时为 `None`。 |
| `hops` | `list[list[dict[str, Any]]]` | hops[0] = 前方一步，hops[1] = 前方两步，……（不含死胡同）。 |
| `entry_nodes` | `list[str]` | 未匹配时：没有入边的节点 id，即流程的起点。 |
| `dominant_next` | `list[str]` | 从当前节点出发，沿已验证路径的下一批节点 id。 |
| `revisits` | `dict[str, int]` | 轨迹窗口：本次运行中每个节点的访问次数、当前节点是否被重复访问，以及从该节点出发尚未选择的出口。 |
| `looping` | `bool` | 当前节点已在 `recent_path` 的更早位置出现时为 True。 |
| `exits` | `list[str]` | 处于循环时：从当前节点可到达、且本次运行中尚未访问的节点 id；否则为空。 |
| `failure_notes` | `list[dict[str, Any]]` | agent 在失败运行中留下的备注，这些运行终止于前方的某个转换。 |
| `rendered` | `str` | 以上内容的确定性文本，可直接放入提示词。 |
| `run_stats` | `dict[str, int]` | 该流程汇总后的 `{total, ok}`。 |
| `for_agent` | `dict[str, int]` | 调用方 agent 的 `{total, ok}`；对于 `*`、`-` 或没有运行记录时为空。 |

<a id="procedurematch"></a>

## `procedure.match`

查找 `situation` 字段在语义上与调用方所描述情境最接近的 procedure。

`POST /v1/procedure.match` · MCP `loom_procedure_match` · 角色 `viewer` · 读取

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该 op 读取或写入的命名空间。 |
| `agent` | `str` | `'*'` | 默认扇出：范围内任意 agent 的 procedure |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `situation` | `str` | 必填 | agent 所处的状态；会与每个 procedure 已存储的 situation 进行比较。 |
| `top_k` | `int` | `5` | 最多搜索这么多个候选项（1–50）；过滤后返回的结果可能更少。 |
| `tags` | `list[str]` | *（计算得出）* | 仅返回带有至少一个这些标签的 procedure；为空表示不按标签过滤。 |
| `namespace_scope` | `Literal['this', 'all_mine']` | `'all_mine'` | `all_mine` 还会搜索调用方自己的命名空间（最多到扇出上限）；`this` 仅搜索 `namespace`。 |
| `templates_only` | `bool` | `False` | 为 true 时，仅返回已升级为可复用模板的 procedure（经过验证、被充分执行的工作流拓扑）。 |
| `include_candidates` | `bool` | `True` | 候选项是尚未被执行过、且不是人工编写的 procedure。 |
| `include_quarantined` | `bool` | `False` | 被隔离的 procedure（其最近 `strike_limit` 次运行全部失败）除非明确要求，否则会被丢弃；如返回则排在最后并带有标注。 |
| `recent_tools` | `list[str]` | *（计算得出）* | agent 在当前任务中最近调用过的工具。 |
| `tool_boost` | `float` | `0.2` | `tool_overlap` 在融合 `score` 中的权重；0 表示忽略 `recent_tools`。 |
| `utility_weight` | `float \| None` | `None` | 融合分数中由账本得出的效用项的权重：score = similarity + tool_boost*overlap + weight * ((ok+1)/(total+2) - 0.5)。 |
| `goal` | `str \| None` | `None` | agent 正在追求的目标，区别于它所处的状态。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `matches` | `list[_ProcedureMatch]` | 匹配的 procedure，按状态层级排序（候选项和被隔离的排在最后），再按 `score` 排序。 |
| `matched` | `int` | 账本上的命中率：匹配了多少个、排名第一的 procedure 及其分数（out_matched / out_procedure_key / out_score）。 |
| `procedure_key` | `str` | 排名第一的匹配项的记忆键；没有匹配时为 ""。 |
| `score` | `float` | 排名第一的匹配项的融合分数；没有匹配时为 0。 |

<a id="procedurerecord_run"></a>

## `procedure.record_run`

报告一次 procedure 的执行情况，让 loom 了解哪条路径真正有效。

`POST /v1/procedure.record_run` · MCP `loom_procedure_record_run` · 角色 `writer` · 写操作 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `'-'` | 写入或读取的 agent；在操作允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的最终用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `memory_key` | `str` | 必填 | 所执行的 procedure 的键（`procedure_<slug>`）。 |
| `path` | `list[str]` | *（自动计算）* | agent 在本次执行中实际访问的有序节点 id。 |
| `ok` | `bool` | `True` | 本次执行是否成功。 |
| `note` | `str` | `''` | 关于本次执行的自由文本备注（例如失败原因）；`procedure.locate` 会显示失败执行的备注。 |
| `ts` | `str` | `''` | 不会被存储：账本会为每次执行打上服务器的时间。 |
| `steps_taken` | `int \| None` | `None` | 本次执行的开销。 |
| `duration_ms` | `int` | `0` | 本次执行耗时，单位为毫秒；0 表示未知。 |
| `tokens` | `int` | `0` | 本次执行消耗的 token；0 表示未知。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `memory_key` | `str` | 本次执行所记录到的 procedure 的键。 |
| `version` | `int` | 始终为 0：执行记录写入账本，procedure 行不会被重写。 |
| `run_stats` | `dict[str, int]` | `{total, ok, unfolded}`，包含本次执行；`unfolded` 表示 `procedure.evolve` 尚未合并的账本执行记录数。 |

<a id="procedurerevise"></a>

## `procedure.revise`

为流程提出修改后的拓扑：由你来担任优化者。

`POST /v1/procedure.revise` · MCP `loom_procedure_revise` · 角色 `writer` · 写入 · 已审计 · 未列入 MCP `all` 工具集

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该 op 读取或写入的命名空间。 |
| `agent` | `str` | `'-'` | 执行写入或读取的 agent；在该 op 允许的情况下，`'-'` 或 `'*'` 表示任意 agent。 |
| `user_id` | `str` | `'-'` | 该行所属的终端用户；`'-'` 表示无。 |
| `session_id` | `str` | `'-'` | 该行所属的会话或对话；`'-'` 表示无。 |
| `memory_key` | `str` | 必填 | 要修改的流程的键（`procedure_<slug>`）。 |
| `graph` | `dict[str, Any]` | 必填 | 提出的拓扑（完整的图；未改动的节点保留其 id，以便沿用其统计数据）。 |
| `reason` | `str` | `''` | 原因：失败的运行暴露了什么问题，以及此次修改改变了什么。 |
| `force` | `bool` | `False` | 即使门控已拒绝该拓扑，仍然提出。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `memory_key` | `str` | 被修改的流程的键。 |
| `version` | `int` | 本次调用写入的流程行的版本。 |
| `revision` | `int` | 新的修订号；从现在起记录的运行都计入该修订。 |
| `prior_revision` | `int` | 被取代的修订（门控回退时会恢复）。 |
| `digest` | `str` | 所提出拓扑的哈希；门控用它来识别已被拒绝的拓扑。 |
| `steps` | `list[str]` | 由新图推导出的线性步骤列表。 |

<!-- prettier-ignore-end -->
