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

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

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

# `mentor` 操作

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

<!-- 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，而[部分操作](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)说明了角色、类型以及 MCP 的 `all` 列表。未知的输入字段会照常处理，并列在 `ignored_args` 中。

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

<a id="mentorbrief"></a>

## `mentor.brief`

某个 agent 的使用画像以及存储提示。

`POST /v1/mentor.brief` · MCP `loom_mentor_brief` · 角色 `viewer` · 读取

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `agent` | `str` | `''` | 写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许时的任意 agent。 |
| `window_seconds` | `int` | `604800` | 读取账本时向前回溯的时长，单位为秒；范围为 1 小时到 90 天。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `org` | `str` | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 该操作读取或写入的命名空间。 |
| `agent` | `str` | 写入或读取的 agent；`'-'` 或 `'*'` 表示在操作允许时的任意 agent。 |
| `window_seconds` | `int` | 计算画像所用的时间窗口，单位为秒；从缓存返回的画像沿用其计算时的窗口。 |
| `computed_at` | `datetime` | 画像的计算时间（UTC）；从缓存返回时早于本次调用。 |
| `sessions` | `int` | 该 agent 在窗口内由客户端命名的不同会话数（不计 `-` 和 `*`）。 |
| `usage` | `dict[str, int]` | 该 agent 在窗口内对各操作的调用次数。 |
| `planes` | `list[MentorPlane]` | mentor 已知的所有平面，包含该 agent 对每个平面的调用次数以及该平面是否可用。 |
| `hints` | `list[MentorHint]` | 针对该 agent 触发的规则，每条附带触发它的计数；没有则为空。 |
| `adoption` | `list[MentorAdoption]` | 按提示代码统计其被展示的会话数和被采纳的会话数，展示最多的排在最前；没有提示到达该 agent 或读取失败时为空。 |
| `usage_evidence` | `list[UsageRung]` | 该 agent 在窗口内对 Loom 的使用情况，每级一项，从最弱的说明开始：从发起过一次调用到完成一次评分运行。 |
| `ledger_from` | `datetime \| None` | 该 agent 在窗口内最早的账本行，不论类型；没有账本行或读取失败时为 None。 |
| `ledger_retention_days` | `int \| None` | 已配置的保留策略对该命名空间的调用账本行的保留天数；0 表示保留到被删除，读取失败时为 None。 |
| `agents` | `list[str]` | 该命名空间在窗口内的写入者，最活跃的排在最前；调用方没有自己的 agent 名称时（如控制台），简报默认取第一个，`agent_defaulted` 会标明这一点。 |
| `agent_defaulted` | `bool` | 调用方没有指定真实的 agent，简报选取了 `agents` 中写入最多的 agent 时为 True。 |
| `skipped` | `list[str]` | 简报无法读取的事项，格式为 "step: reason"。 |
| `healthy` | `bool` | 没有警告级或严重级的提示。 |

<a id="mentorguide"></a>

## `mentor.guide`

此服务器附带的 agent 指南；对所有调用方都相同。

`POST /v1/mentor.guide` · MCP `loom_mentor_guide` · 角色 `viewer` · 读取 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | `''` | 租户（身份元组的第一个元素）。 |
| `part` | `Literal['skill', 'reference', 'all']` | `'skill'` | 返回哪一部分：`skill`（循环与规则，默认值）、`reference`（各个平面）或 `all`。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `version` | `str` | 指南的版本（skills/loom/SKILL.md 的 `metadata.version`）。 |
| `part` | `Literal['skill', 'reference', 'all']` | 按请求返回的部分。 |
| `text` | `str` | Markdown 格式的指南，不含 skill 的 frontmatter。 |

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