跳转至

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

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

procedure 操作

每个 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] 由新图推导出的线性步骤列表。