---
title: "`decision` 操作"
---

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

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

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

<!-- 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 也会按此处理；参见[身份与命名空间](/docs/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="decisionchain"></a>

## `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` 边到达的每个键，每个键只出现一次，按跳数由近到远排列。 |

<a id="decisionoutcome"></a>

## `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）。 |

<a id="decisionprecedents"></a>

## `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` | 底层记忆搜索所使用的嵌入模型。 |

<a id="decisionrecord"></a>

## `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` | 指明后续操作的纯文本提示。 |

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