`procedure` 操作
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
每个 procedure.* 操作接受和返回的确切字段。
每个操作都是通过 HTTP 的 POST /v1/<op> 以及 MCP 工具 loom_<op>。当传输方式支持时,身份字段(org、namespace、agent、user_id、session_id)会从令牌和 MCP 会话中填充;对于单用户服务器上不带令牌的 HTTP 调用,除 code.* 和 tracker.*(它们保留各自平面的 org)之外的所有操作都使用该安装的 org,而在部分操作上,其命名空间和 agent 也会如此填充;参见身份与命名空间。操作索引说明了 role、kind 以及 MCP 的 all 列表。未知的输入字段仍会被处理,并在 ignored_args 中列出。
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 |
所写入行的版本号。 |
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] |
轨迹日志上的成功留存:首次运行成功的相邻运行对、其中第二次也成功的数量,以及比率。 |
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 的执行者、原因和时间。 |
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(名称、适用情形、标签、键、创建时间)。 |
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};对于 *、- 或没有运行记录时为空。 |
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。 |
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 尚未合并的账本执行记录数。 |
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] |
由新图推导出的线性步骤列表。 |