advisor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Advisor

You are the main model. Advisor mode adds a second, stronger model that you consult at a few key points. The advisor gets your briefing (and the full transcript when available), thinks hard, and returns a verdict with guidance. It does not edit files. You still do the work and make the final call.

State lives in

.cursor/advisor/state.json

at the project root. When that file exists with

"enabled": true

, advisor mode is on for this project.

你是主模型。Advisor 模式会添加一个更强的第二模型，你可以在几个关键节点咨询它。advisor 会收到你的简报（以及可用时的完整对话记录），深入思考后返回带有指导意见的结论。它不会编辑文件。你仍然负责执行工作并做出最终决策。

状态存储在项目根目录的

.cursor/advisor/state.json

文件中。当该文件存在且

"enabled": true

时，此项目的 advisor 模式处于开启状态。

Commands

命令

The text after

/advisor

selects the action.

Input	Action
`/advisor`	Enable for this conversation with the default advisor: the latest Grok at its highest reasoning effort. If a state file already exists, from this or another conversation, re-bind it here, keeping its `model` and `nudge` settings.
`/advisor <model>`	Same, with the given model. Any model available to subagents works: `/advisor cursor-grok-4.6-xhigh-fast` , `/advisor composer-2.5` .
`/advisor off`	Disable: delete `.cursor/advisor/` .
`/advisor status`	Report model, consult count, and whether the end-of-turn nudge is on. Changes nothing.
`/advisor ask <question>`	Consult now about the current work, regardless of checkpoint.
`/advisor nudge on` / `off`	Toggle the end-of-turn reminder posted by the plugin's stop hook (default on).

If the message also contains a task (

/advisor, then refactor the cache layer

), enable first, then do the task under advisor mode.

/advisor

后面的文本用于选择操作。

输入	操作
`/advisor`	使用默认 advisor 开启本次对话的 advisor 模式：默认模型为推理强度最高的最新版 Grok。如果当前或其他对话已存在状态文件，在此处重新绑定，保留其 `model` 和 `nudge` 设置。
`/advisor <model>`	功能同上，但使用指定模型。任何 subagent 可用的模型都支持：例如 `/advisor cursor-grok-4.6-xhigh-fast` 、 `/advisor composer-2.5` 。
`/advisor off`	关闭 advisor 模式：删除 `.cursor/advisor/` 目录。
`/advisor status`	报告当前使用的模型、咨询次数，以及回合结束 nudge 是否开启。不做任何修改。
`/advisor ask <question>`	立即就当前工作进行咨询，不受检查点限制。
`/advisor nudge on` / `off`	切换插件 stop hook 发布的回合结束提醒（默认开启）。

如果消息中还包含任务（例如

/advisor, then refactor the cache layer

），先开启 advisor 模式，再在该模式下执行任务。

Choosing the model

选择模型

The default is the latest Grok model at its highest reasoning effort, currently

cursor-grok-4.6-xhigh

. If a newer Grok or a higher effort tier appears in the subagent model list available to you, prefer it and say so.

For

/advisor <model>

, resolve the request against the subagent model slugs available to you:

An exact slug: use it as is.
A family or version name (
```
grok fast
```
,
```
composer
```
): that family's latest model at its highest reasoning tier.
No match: say so, name two or three close options, and keep the current model.

If the Task tool rejects a slug, read the valid slugs from its error message, pick the closest one (same family, highest reasoning tier), save it to

state.json

, and tell the user in one line. Do not block the consult on the slug.

默认使用推理强度最高的最新版 Grok 模型，当前为

cursor-grok-4.6-xhigh

。如果你可用的 subagent 模型列表中出现了更新的 Grok 版本或更高的推理强度等级，优先使用并告知用户。

对于

/advisor <model>

命令，根据你可用的 subagent 模型 slug 解析请求：

完全匹配的 slug：直接使用。
系列或版本名（
```
grok fast
```
、
```
composer
```
）：使用该系列最高推理等级的最新模型。
无匹配：告知用户，列出两到三个相近选项，并保持当前模型不变。

如果 Task 工具拒绝了某个 slug，从错误信息中读取有效的 slug 列表，选择最接近的一个（同一系列、最高推理等级），保存到

state.json

，并用一行话告知用户。不要因为 slug 问题阻塞咨询流程。

Enabling

启用方式

Resolve the model as described above.
Write
```
.cursor/advisor/state.json
```
with the file-writing tool (not a shell redirect), creating the directory if needed. If a state file already exists, carry over its
```
model
```
(unless this command names one) and
```
nudge
```
, and reset every other field to the values below. You cannot see which conversation an existing file belongs to, so always rewrite it: that re-binds the mode to this conversation, the hooks re-fill
```
conversation_id
```
and
```
transcript_path
```
, and the next consult starts a fresh advisor instead of resuming another chat's. Also delete
```
.cursor/advisor/pending
```
and
```
.cursor/advisor/last-response.txt
```
if they exist, so a marker left by another conversation cannot trigger the end-of-turn nudge here. Keep
```
log.md
```
.
json
```
{
  "enabled": true,
  "model": "cursor-grok-4.6-xhigh",
  "nudge": true,
  "advisor_agent_id": null,
  "conversation_id": null,
  "transcript_path": null,
  "consults": 0,
  "last_consult_at": null,
  "enabled_at": "<current UTC time, ISO 8601>"
}
```
The plugin's hooks fill in
```
conversation_id
```
,
```
transcript_path
```
,
```
consults
```
, and
```
last_consult_at
```
. Leave them alone.

Confirm in one line:

Advisor on: <slug>. I'll consult it before major decisions, when I'm stuck, and before I call the task done.

Then continue with any task in the same message.

Never stage or commit

.cursor/advisor/

按照上述方法解析模型。
使用文件写入工具（而非 shell 重定向）写入
```
.cursor/advisor/state.json
```
，必要时创建目录。如果已存在状态文件，保留其
```
model
```
（除非本次命令指定了模型）和
```
nudge
```
设置，将其他所有字段重置为以下值。你无法判断现有文件属于哪个对话，因此始终重写该文件：这样可以将模式重新绑定到当前对话，hook 会重新填充
```
conversation_id
```
和
```
transcript_path
```
，下一次咨询会启动一个全新的 advisor，而不是恢复另一个对话的会话。同时删除
```
.cursor/advisor/pending
```
和
```
.cursor/advisor/last-response.txt
```
（如果存在），避免其他对话留下的标记触发本次对话的回合结束 nudge。保留
```
log.md
```
文件。
json
```
{
  "enabled": true,
  "model": "cursor-grok-4.6-xhigh",
  "nudge": true,
  "advisor_agent_id": null,
  "conversation_id": null,
  "transcript_path": null,
  "consults": 0,
  "last_consult_at": null,
  "enabled_at": "<current UTC time, ISO 8601>"
}
```
插件的 hook 会自动填充
```
conversation_id
```
、
```
transcript_path
```
、
```
consults
```
和
```
last_consult_at
```
字段。不要修改这些字段。

用一行话确认：

Advisor 已开启：<slug>。我会在重大决策前、遇到问题卡壳时、以及宣布任务完成前咨询它。

然后继续执行同一条消息中的其他任务。

永远不要暂存或提交

.cursor/advisor/

目录。

Checkpoints

检查点

Consult at these points and nowhere else. Each consult is a strong-model call; the value comes from using it selectively.

Before a major decision. Choosing between architectures or approaches; changes that are hard to reverse or have a wide blast radius (schema or data migrations, deleting or rewriting a module, public API or config format changes, dependency swaps, auth, payments, or other security-sensitive code); or a request that is ambiguous in a way that would change the work materially. Consult once you have a concrete plan and the options in hand, not before you understand the problem. One consult covers the plan; do not re-consult per file.
When stuck. The same error or failing test after two genuine fix attempts; behavior you cannot explain from the code; or when you are about to reach for a workaround: a retry loop, a
```
sleep
```
, a broad
```
try/except
```
, skipping a test, or disabling a check to get past something.
Before declaring done. Any task that changed logic or touched more than a couple of files: consult once before writing the final summary, and include what you verified and how. Skip for trivial edits (typos, comments, a one-line config change) and say so in one line.
On request.
```
/advisor ask ...
```
, or the user asks what the advisor thinks.

Do not consult for routine steps, for things you can verify yourself (run the test, read the code), or more than once per checkpoint. If you would consult more than about four times in one task, the task should probably be split, or you should ask the user.

仅在以下节点进行咨询，其他时候不要咨询。每次咨询都会调用一次强模型；其价值在于有选择地使用。

重大决策前。 在架构或方案之间做选择；难以回滚或影响范围广的变更（schema 或数据迁移、删除或重写模块、公共 API 或配置格式变更、依赖替换、auth、支付或其他安全敏感代码）；或者需求模糊，可能大幅改变工作内容。等你有了具体方案和可选选项后再咨询，不要在还没理解问题的时候就咨询。一次咨询覆盖整个方案；不要每个文件都重新咨询。
遇到卡壳时。 经过两次真正的修复尝试后，仍然出现相同的错误或测试失败；代码的行为无法解释；或者你打算采用临时方案：重试循环、
```
sleep
```
、宽泛的
```
try/except
```
、跳过测试，或者禁用某个检查来绕过问题。
宣布完成前。 任何修改了逻辑或涉及多个文件的任务：在编写最终总结前咨询一次，并说明你验证了什么、如何验证的。对于琐碎的编辑（拼写错误、注释、单行配置变更）可以跳过咨询，并用一行话说明。
用户要求时。 执行
```
/advisor ask ...
```
命令，或者用户询问 advisor 的意见时。

不要为常规步骤咨询，不要为你自己可以验证的事情（运行测试、阅读代码）咨询，也不要在同一个检查点多次咨询。如果一个任务中你需要咨询超过四次，那么这个任务可能应该拆分，或者你应该询问用户。

How to consult

如何咨询

Read
```
.cursor/advisor/state.json
```
and decide which situation you are in:
- Mode on here: the file exists with
```
enabled: true
```
  and you ran the Enabling steps in this conversation. Checkpoint consults and
```
/advisor ask
```
  both follow the steps below in full, including
```
resume
```
  and state writes.
- Not on here: the file is missing,
```
enabled
```
  is false, or you did not write it. A file you did not write belongs to another chat; only
```
/advisor
```
  re-binds it, so leave it alone and never
```
resume
```
  an
```
advisor_agent_id
```
  you did not save yourself. Do not consult at checkpoints. If the user explicitly asks for a consult in this message (
```
/advisor ask ...
```
  , or a request for a second opinion), run it as a one-off: a fresh spawn on the file's
```
model
```
  if there is one, otherwise the default; no
```
resume
```
  , no state writes, and no
```
transcript_path
```
  (another chat's transcript is not yours to share; write "not available"). Mention that
```
/advisor
```
  turns the mode on for this conversation.
Build the briefing from
```
references/briefing-template.md
```
. Give the advisor everything it needs to disagree with you:
- The user's request verbatim, plus constraints or corrections they added later.
- What has happened so far, in order: what you investigated, decided, changed, tried, and ruled out.
- Relevant tool results verbatim: error messages, stack traces, test output, diffs. Trim unrelated noise and mark trims with
```
[...]
```
  , but never paraphrase evidence.
- Current state:
```
git status --short
```
  ,
```
git diff --stat
```
  , files you touched, anything half-done.
- Your specific questions, the options you see, and your current leaning with reasons.
- The
```
transcript_path
```
  from
```
state.json
```
  when set and the mode is on in this conversation, so the advisor can read the full conversation itself.
- No secrets. Redact tokens, keys, and
```
.env
```
  values.
Spawn the advisor in the foreground and wait for it:
- ```
subagent_type: "advisor-subagent"
```
- ```
model: <state.model>
```
- ```
description: "Advisor: <checkpoint>"
```
  , for example
```
Advisor: pre-completion review
```
- ```
run_in_background: false
```
- When
```
state.advisor_agent_id
```
  is set, pass it as
```
resume
```
  and omit
```
model
```
  ; the advisor keeps its model and the context of earlier consults, so the briefing can be a delta: what changed since last time plus the new questions. If the resume fails, spawn fresh.
- Save the returned agent id to
```
advisor_agent_id
```
  in
```
state.json
```
  . Clear it when the model changes.
Act on the verdict:
- ```
proceed
```
  : go.
- ```
proceed with changes
```
  : make the recommended changes unless they conflict with the user's instructions or facts you have verified. Say which you skipped and why.
- ```
stop
```
  : do not continue with the plan. Rethink, or bring the disagreement to the user if it is a product or scope question.
- If the advisor asks for something it needs, provide it via
```
resume
```
  , once. Do not ping-pong.
- You are accountable for the result. The advisor is a strong second opinion, not an authority. If it is wrong about the codebase, show it the evidence once, or overrule it and tell the user why.
Report each consult to the user in one or two lines:
```
Advisor (<model>): <verdict>. <One-line summary>. <What you did about it.>
```
Keep the advisor's full response out of the chat unless the user asks; the hooks also append it to
```
.cursor/advisor/log.md
```
.

读取
```
.cursor/advisor/state.json
```
，判断你处于哪种情况：
- 模式已在当前对话开启：文件存在且
```
enabled: true
```
  ，并且你在本次对话中执行了启用步骤。检查点咨询和
```
/advisor ask
```
  都完全遵循以下步骤，包括
```
resume
```
  和状态写入。
- 未在当前对话开启：文件不存在、
```
enabled
```
  为 false，或者文件不是你写入的。不是你写入的文件属于其他对话；只有
```
/advisor
```
  命令可以重新绑定它，因此不要改动它，也永远不要
```
resume
```
  一个你自己没有保存过的
```
advisor_agent_id
```
  。不要在检查点进行咨询。如果用户在本条消息中明确要求咨询（
```
/advisor ask ...
```
  ，或要求第二意见），将其作为一次性咨询执行：如果文件中有
```
model
```
  则使用该模型启动新的 advisor，否则使用默认模型；不执行
```
resume
```
  、不写入状态、也不传递
```
transcript_path
```
  （其他对话的记录不属于你，无权共享；填写“not available”）。同时告知用户可以使用
```
/advisor
```
  为本次对话开启该模式。
根据
```
references/briefing-template.md
```
构建简报。向 advisor 提供所有必要信息，以便它能提出不同意见：
- 用户的原始请求，以及他们后来添加的约束或修正。
- 到目前为止的进展，按顺序排列：你调查了什么、做了什么决定、修改了什么、尝试了什么、排除了什么。
- 相关工具的原始输出：错误信息、stack trace、测试输出、diff。删除无关内容并用
```
[...]
```
  标记，但绝对不要改写证据内容。
- 当前状态：
```
git status --short
```
  、
```
git diff --stat
```
  、你修改过的文件、所有未完成的工作。
- 你的具体问题、你看到的可选方案，以及你当前的倾向和理由。
- 如果
```
state.json
```
  中设置了
```
transcript_path
```
  且当前对话已开启模式，提供该路径，以便 advisor 可以自行读取完整对话。
- 不要包含机密信息。隐去 token、密钥和
```
.env
```
  文件中的值。
在前台启动 advisor 并等待其返回：
- ```
subagent_type: "advisor-subagent"
```
- ```
model: <state.model>
```
- ```
description: "Advisor: <checkpoint>"
```
  ，例如
```
Advisor: pre-completion review
```
- ```
run_in_background: false
```
- 当设置了
```
state.advisor_agent_id
```
  时，将其作为
```
resume
```
  参数传递，并省略
```
model
```
  ；advisor 会保留其模型和之前咨询的上下文，因此简报可以只包含增量内容：上次咨询后的变更加上新的问题。如果恢复失败，则重新启动新的 advisor。
- 将返回的 agent id 保存到
```
state.json
```
  的
```
advisor_agent_id
```
  字段中。模型变更时清空该字段。
根据结论采取行动：
- ```
proceed
```
  ：继续执行。
- ```
proceed with changes
```
  ：执行建议的变更，除非这些变更与用户的指令或你已验证的事实冲突。说明你跳过了哪些变更以及原因。
- ```
stop
```
  ：不要继续执行原计划。重新思考，如果是产品或范围问题，将分歧告知用户。
- 如果 advisor 要求提供某些必要信息，通过
```
resume
```
  提供一次。不要来回反复。
- 你对结果负责。advisor 只是提供强有力的第二意见，不是权威。如果它对代码库的判断有误，向它展示一次证据，或者否决它的意见并告知用户原因。
用一到两句话向用户报告每次咨询的结果：
```
Advisor (<model>)：<verdict>。<一行总结>。<你采取的行动。>
```
除非用户要求，否则不要在聊天中展示 advisor 的完整回复；hook 也会将完整回复追加到
```
.cursor/advisor/log.md
```
文件中。

End-of-turn nudge

回合结束 nudge

When files changed since the last consult and a turn ends without one, the plugin's

stop

hook posts a follow-up that starts with

[Advisor]

. Treat it as the "before declaring done" checkpoint: run the pre-completion consult, or answer in one line that the change was trivial, or that you are waiting on the user, and stop. It fires at most once per batch of edits.

/advisor nudge off

disables it.

如果自上次咨询以来文件发生了变更，且一个回合结束时没有进行咨询，插件的

stop

hook 会发布一条以

[Advisor]

开头的后续消息。将其视为“宣布完成前”检查点：执行完成前咨询，或者用一行话说明变更很琐碎，或者你正在等待用户回复，然后停止。每批编辑最多触发一次。可以通过

/advisor nudge off

禁用该功能。

Disabling

禁用方式

/advisor off

: delete

.cursor/advisor/

and confirm in one line. Do not consult again in this conversation unless the user re-enables the mode or explicitly asks for a one-off consult.

/advisor off

：删除

.cursor/advisor/

目录，并用一行话确认。本次对话中不要再进行咨询，除非用户重新开启模式或明确要求一次性咨询。

Guardrails

防护规则

Never enable advisor mode unasked. "Get a second opinion on this" is a one-off consult, not a mode change.
The advisor is read-only. Never ask it to edit files or do the task.
Never loop on the advisor: at most one follow-up per checkpoint.
If the
```
advisor-subagent
```
subagent is unavailable (no Task tool, or a hook denies it), tell the user once and continue without it.
To keep this skill in context for a whole session rather than one message, the user can invoke
```
/advisor
```
as a Custom Mode (Option+Enter / Alt+Enter). The state file works either way.

未经用户要求，永远不要开启 advisor 模式。“对此征求第二意见”属于一次性咨询，不是模式变更。
advisor 是只读的。永远不要要求它编辑文件或执行任务。
永远不要循环咨询 advisor：每个检查点最多进行一次后续咨询。
如果
```
advisor-subagent
```
subagent 不可用（没有 Task 工具，或 hook 拒绝访问），告知用户一次，然后继续工作（不使用 advisor）。
如果用户希望在整个会话中（而非单条消息）保持该 skill 处于上下文，可以将
```
/advisor
```
作为自定义模式调用（Option+Enter / Alt+Enter）。状态文件在两种方式下都有效。