decision 操作
decision 操作
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
每个 decision.* 操作接受和返回的确切字段。
每个操作都是 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 中列出。
decision.chain
追踪一项决策的因果链:向上游(是什么导致或影响了它)和/或向下游(它进而导致了什么),在已编写的图上最多追踪 4 跳。
POST /v1/decision.chain · MCP loom_decision_chain · 角色 viewer · 读取 · 不在 MCP all 工具集中列出
| 输入字段 | 类型 | 默认值 | 含义 |
|---|---|---|---|
org |
str |
必填 | 租户(身份元组的第一个元素)。 |
namespace |
str |
必填 | 该操作读取或写入的命名空间。 |
memory_key |
str |
必填 | 遍历的起始键,通常是某项决策的键。 |
direction |
Literal['upstream', 'downstream', 'both'] |
'both' |
upstream 沿着导致当前节点的方向追踪,downstream 沿着当前节点导致的结果追踪,both 两个方向都遍历。 |
max_hops |
int |
3 |
向外遍历的边数,范围 1-4。 |
| 输出字段 | 类型 | 含义 |
|---|---|---|
seed |
str |
起始键,原样返回。 |
seed_decision |
DecisionRow | None |
起始键对应的决策记录;当起始键不是有效决策时为 null。 |
nodes |
list[ChainNodeRow] |
通过 caused、influenced 或 derived_from 边到达的每个键,每个键只出现一次,按跳数由近到远排列。 |
decision.outcome
在现实给出结果之后,为一项决策闭环:记录实际发生了什么,以及决策是否奏效(success)。
POST /v1/decision.outcome · MCP loom_decision_outcome · 角色 writer · 写入 · 已审计 · 不在 MCP all 工具集中列出
| 输入字段 | 类型 | 默认值 | 含义 |
|---|---|---|---|
org |
str |
必填 | 租户(身份元组的第一个元素)。 |
namespace |
str |
必填 | 该操作读取或写入的命名空间。 |
memory_key |
str |
必填 | 要更新的有效决策;如果没有该决策,或者该记录的写入者在此 key 下没有有效的决策行,则返回 404。 |
realized_outcome |
str |
必填 | 实际发生的结果,存储在决策记录中。 |
success |
bool | None |
None |
None 表示保留记录原有的结论;True/False 会设置结论,并为做出该决策的运行所用的记忆记功(或标记)。 |
agent |
str |
'*' |
写入或读取的 agent;在操作允许的情况下,'-' 或 '*' 表示任意 agent。 |
| 输出字段 | 类型 | 含义 |
|---|---|---|
memory_key |
str |
决策的 key,原样返回。 |
updated |
bool |
始终为 true:决策不存在时返回 404。 |
memories_credited |
int |
通过运行账本记功的记忆数(run.complete memories_used)。 |
decision.precedents
在做决定之前,先查询类似情境下曾经做过哪些决定:对过往决定进行语义搜索(可限定类别),每条结果都附带其推理过程、被否决的备选方案,以及(如果已知)…
POST /v1/decision.precedents · MCP loom_decision_precedents · 角色 viewer · 读取 · 不在 MCP all 工具集中列出
| 输入字段 | 类型 | 默认值 | 含义 |
|---|---|---|---|
org |
str |
必填 | 租户(身份元组的第一个元素)。 |
namespace |
str |
必填 | 该操作读取或写入的命名空间。 |
agent |
str |
'*' |
写入或读取的 agent;'-' 或 '*' 表示在该操作允许的情况下匹配任意 agent。 |
query |
str |
必填 | 当前的情境,按做决定的 agent 所看到的方式描述。 |
category |
str |
'' |
仅返回此类别的决定(不区分大小写);“” 表示搜索所有类别。 |
top_k |
int |
5 |
最多返回这么多条先例,范围 1-25。 |
with_outcome_only |
bool |
False |
仅返回已知实际结果的决定(已调用 decision.outcome)。 |
| 输出字段 | 类型 | 含义 |
|---|---|---|
precedents |
list[DecisionRow] |
仍然有效的过往决定,决定陈述最相似的排在最前。 |
embedding_model |
str |
底层记忆搜索所使用的嵌入模型。 |
decision.record
将一项决策(DECISION)记录为一等对象:每当你在日后会产生影响的选项之间做出选择时(供应商、设计、修复、回滚),都应调用它。
POST /v1/decision.record · MCP loom_decision_record · 角色 writer · 幂等 · 已审计 · 未列入 MCP all 工具集
| 输入字段 | 类型 | 默认值 | 含义 |
|---|---|---|---|
org |
str |
必填 | 租户(身份元组的第一个元素)。 |
namespace |
str |
必填 | 该操作读取或写入的命名空间。 |
agent |
str |
必填 | 写入或读取的 agent;'-' 或 '*' 表示在操作允许的情况下匹配任意 agent。 |
user_id |
str |
'-' |
该行所属的终端用户;'-' 表示无。 |
session_id |
str |
'-' |
该行所属的会话或对话;'-' 表示无。 |
run_id |
str |
'-' |
做出该决策时所处的运行(run.begin)。 |
category |
str |
必填 | category 加 scenario 共同标识一项决策:对同一场景重新决策会取代先前的记录(历史中仍保留它)。 |
scenario |
str |
必填 | 需要做出决策的情形;decision.precedents 会将查询与决策的陈述进行匹配,而陈述以该场景开头。 |
reasoning |
str |
必填 | 选择该结果的原因。 |
outcome |
str |
必填 | 决策的内容。 |
alternatives |
list[str] |
(计算得出) | 曾被考虑但未被选中的方案:每个“为什么不选 X”的问题都需要这个字段,而大多数决策日志都没有它。 |
confidence |
float |
0.0 |
决策者的置信度,0-1;0 表示不记录置信度(此时记忆行和边的置信度为 1.0)。 |
stage |
Literal['decided', 'proposed'] |
'decided' |
“decided”(默认),或 “proposed”,表示已提出但尚未选定或实施的选项(提案、计划、待办事项);与 memory.set 的 proposed(处于试用中的事实)无关。 |
decision_maker |
str |
'' |
决策者,可以是人或 agent;“” 表示记录为调用方 agent。 |
caused_by |
list[str] |
(计算得出) | 导致或影响了该决策的 memory_keys(决策、事实、流程);每一项都会成为一条以本次调用为证据的人工创建的边(memory.link)。 |
influenced_by |
list[str] |
(计算得出) | 塑造了该决策但并未导致它的键;每一项都会成为一条 influenced 边。 |
tags |
list[str] |
(计算得出) | 记忆行上除 decision 和 decision:category:<category> 之外的额外标签;此处的 decision:proposed 标签会被丢弃(请用 stage 设置)。 |
valid_at |
datetime | None |
None |
决策在现实世界中生效的时间;None 表示当前时间。 |
files |
list[str] | None |
None |
该决策所约束的仓库文件(仓库相对路径或纯文件名);memory.for_file 会在编辑这些文件之前提供该决策。 |
source_class |
Literal['derived', 'external', 'imported'] | None |
None |
声明该决策派生自其他内容(derived)或来自外部(external、imported)。 |
source_resource_id |
str |
'' |
该决策所取自的文件路径、文档 id 或 URL,会在其命中结果中被引用。 |
| 输出字段 | 类型 | 含义 |
|---|---|---|
memory_key |
str |
决策的键,由 category 加 scenario 派生;将其传给 decision.outcome 和 decision.chain。 |
record_id |
str |
所写入的 decision 记录版本的 id。 |
superseded_prior |
bool |
当同一 category 加 scenario 已存在一项有效决策且现已被本次决策取代时为 True。 |
edges_written |
int |
写入的 caused / influenced 边的数量;失败的链接会被跳过。 |
next |
str |
指明后续操作的纯文本提示。 |