minimal-agent 0.18.12 → 0.18.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.18.12",
+  "version": "0.18.14",
   "description": "Bun-first 的本地 Agent 内核，支持工具、插件、工作流、上下文压缩、长期记忆与 OpenAI 兼容接口；Tauri 桌面宿主和 Node.js npm 发布可复用同一内核",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",
@@ -215,7 +215,6 @@
     "proper-lockfile": "^4.1.2",
     "react": "^18.3.1",
     "sharp": "^0.34.5",
-    "ssh2": "^1.17.0",
     "turndown": "^7.2.4",
     "undici": "^6.28.1",
     "vscode-jsonrpc": "^8.2.1",
@@ -228,7 +227,6 @@
     "@types/node": "^20.14.0",
     "@types/proper-lockfile": "^4.1.4",
     "@types/react": "^18.3.0",
-    "@types/ssh2": "^1.15.6",
     "bun-types": "^1.3.13",
     "typescript": "^5.5.0"
   },

package/plugins/workflow-runner/src/runtime/context.js

@@ -503,7 +503,7 @@ export function createWorkflowContext(deps) {
                 maxTurns: opts.maxTurns,
                 allowedTools: allowed,
                 toolBoundaryLabel: '当前工作流节点',
-                advisorCheckpoints: opts.toolMode !== 'read-only',
+                advisorReminders: opts.toolMode !== 'read-only',
                 availableTools: ctx.tools,
                 ...(opts.allowedTools === undefined ? {} : { requiredTools: allowed }),
                 ...executionServices(requestSignal, opts.toolMode),

package/plugins/workflow-runner/src/runtime/context.ts

@@ -749,7 +749,7 @@ export function createWorkflowContext(deps: ApiDeps): WorkflowContext {
         maxTurns: opts.maxTurns,
         allowedTools: allowed,
         toolBoundaryLabel: '当前工作流节点',
-        advisorCheckpoints: opts.toolMode !== 'read-only',
+        advisorReminders: opts.toolMode !== 'read-only',
         availableTools: ctx.tools,
         ...(opts.allowedTools === undefined ? {} : { requiredTools: allowed }),
         ...executionServices(requestSignal, opts.toolMode),

package/plugins/workflow-runner/test/embeddedExecution.test.ts

@@ -36,7 +36,6 @@ const tools: Tool[] = [
   'Write',
   'Skill',
   'Advisor',
-  'AdvisorDecision',
   'PresentResult',
   'AskUserQuestion',
 ].map((name) => ({
@@ -165,8 +164,7 @@ test('embedded tools exclude outer delivery/advisor/ask, preserve explicitly req
     expect(names).toContain('Read');
     for (const name of [
       'Advisor',
-      'AdvisorDecision',
-      'PresentResult',
+          'PresentResult',
       'AskUserQuestion',
     ])
       expect(names).not.toContain(name);
@@ -177,8 +175,7 @@ test('embedded tools exclude outer delivery/advisor/ask, preserve explicitly req
       allowedTools: [
         'Read',
         'Advisor',
-        'AdvisorDecision',
-        'PresentResult',
+              'PresentResult',
         'AskUserQuestion',
       ],
       isolated: true,

package/plugins/workflow-runner/test/execLifetime.test.ts

@@ -6,8 +6,21 @@ import { executeWorkflowFile } from '../src/runtime/exec.js';
 
 const dirs: string[] = [];
 afterEach(async () => {
-  for (const dir of dirs.splice(0))
-    await rm(dir, { recursive: true, force: true });
+  // Windows keeps a just-terminated process's cwd busy for ~200ms after the
+  // async taskkill (EBUSY). Retry instead of failing a test that passed; a
+  // genuinely leaked process would still hold the directory after 5s and fail.
+  // Explicit loop: Bun's rm does not honor maxRetries.
+  for (const dir of dirs.splice(0)) {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await rm(dir, { recursive: true, force: true });
+        break;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EBUSY' || attempt >= 50) throw error;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+    }
+  }
 });
 async function script(source: string) {
   const cwd = await mkdtemp(join(tmpdir(), 'wf-process-'));

package/skills/ssh-remote-dev/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ssh-remote-dev
+description: Develop, inspect, test, and transfer files in a user-authorized remote working directory over SSH. Use when work must happen on a configured SSH host rather than only in the local workspace; prefer SSH config aliases and key-based authentication. Do not use for non-SSH services or as permission to access hosts the user has not placed in scope.
+---
+
+# SSH Remote Development
+
+Operate remote repositories through the system `ssh` and `scp` clients. Treat the remote host and filesystem as external state: this skill supplies a workflow, not standing authorization for unrelated hosts or destructive actions.
+
+## Establish the target
+
+- Resolve the SSH destination from the user's named `~/.ssh/config` alias when possible. Never expose private-key contents, passwords, passphrases, tokens, or full SSH configuration in output.
+- Establish one explicit remote working directory for the task. If the alias or directory is genuinely missing, ask for only that missing value.
+- Prefer non-interactive key or SSH-agent authentication. Use `-o BatchMode=yes` and a short `-o ConnectTimeout=10` for probes so a command cannot hang on a password prompt.
+- When the authorized host only supports a password, start `ssh` or `sftp` with a TTY and send the password only to the live prompt. Never place it in the command line, an environment variable, an askpass helper, a generated script, a project file, or the skill. Keep one bounded interactive session when practical instead of repeatedly handling the password, and close it when the task ends.
+- Start with a read-only probe that prints the canonical directory, platform/shell information when relevant, and repository status. Verify that the canonical path is the intended target before any write.
+- Each SSH invocation is stateless. Include the directory and required environment setup in every command, for example `cd -- '<remote-root>' && <command>`. Do not assume a previous `cd`, exported variable, virtual environment, or shell session persists.
+- Default to a POSIX shell only when the probe confirms one. Adapt commands for a Windows/PowerShell remote instead of forcing Bash syntax.
+
+## Work in the remote repository
+
+- Inspect before changing: read the relevant files, repository instructions, current branch, `git status --short`, and focused diffs. Preserve pre-existing edits and untracked files as user work.
+- Disable Git paging per invocation for captured output, for example `git -c core.pager=cat status --short` or `git -c core.pager=cat diff --stat`. An interactive pager can consume later commands as keystrokes; if one opens unexpectedly, quit it before sending anything else.
+- Keep remote commands narrowly scoped and outputs bounded. Prefer targeted searches and `head`, `tail`, or equivalent over dumping large files or logs.
+- Run the smallest useful verification after changes, then report the exact remote path, files changed, and test result.
+- Never run `git reset --hard`, checkout-based discard, force push, recursive deletion, or broad cleanup unless the user explicitly requests that exact destructive outcome. Validate canonical targets immediately before an authorized destructive operation.
+- For a recoverable removal, prefer moving the item under `<remote-root>/.codex-trash/<timestamp>/` and tell the user where it went. Do not claim this is recoverable if it crosses filesystems or the move failed.
+
+## Edit files safely
+
+For a trivial, deterministic change, a carefully quoted remote command is acceptable. For non-trivial source edits, use this conflict-aware workflow:
+
+1. Record the remote file's identity and hash (`sha256sum` or platform equivalent), and whether it exists.
+2. Download it to a task-specific staging directory inside the local writable workspace.
+3. Edit the staged file with `apply_patch` and run any useful local checks.
+4. Recheck the remote hash immediately before upload. If it changed, stop and reconcile instead of overwriting concurrent work.
+5. Upload to a uniquely named temporary file in the same remote directory. Preserve the original mode when relevant, then atomically rename the temporary file over the destination.
+6. Clean up only the temporary artifact created by this workflow. Re-read or hash the installed file and inspect `git diff` remotely.
+
+For a new file, first verify the destination still does not exist. For multiple related files, use one task-specific staging tree and repeat the conflict check for every existing destination. Avoid brittle `sed`/regex rewrites for semantic code changes.
+
+## Transfer files
+
+- Use `scp -- <local-path> <alias>:<remote-path>` for uploads and the inverse for downloads. Quote local and remote paths independently; do not construct commands from untrusted remote output.
+- Keep local downloads within the current workspace or another user-approved writable directory.
+- Upload writes are external mutations. Use the temporary-upload-and-rename pattern for files that replace existing content.
+- Do not add `StrictHostKeyChecking=no`. If host-key verification fails or a stored key changes, stop and ask the user to verify the fingerprint through a trusted channel.
+- For a large read-only code review, a selective local mirror is acceptable: copy only first-party source, tests, manifests, and sanitized configuration examples into a clearly named task cache. Exclude dependency trees, build outputs, caches, logs, data, model weights, nested third-party repositories, and live secret files. Treat the mirror as non-authoritative, do not run Git operations from it, and re-read remote files before any later edit.
+
+## Long-running work
+
+- Do not hold one SSH call open indefinitely. For a user-requested service or long test on a POSIX host, use `nohup`/`setsid` with a task-specific log and PID file, return promptly, and verify it in a fresh SSH call.
+- A timeout or disconnected channel does not prove whether a remote command stopped. Check the PID, log, process marker, or expected artifact before retrying so duplicate jobs are not started.
+- Stop only the recorded PID after verifying its command line belongs to this task. Do not use broad `pkill` patterns when an exact PID is available.
+
+## Permissions and failures
+
+- Request host/network execution approval when the runtime requires it. A skill cannot bypass the sandbox or approval system.
+- Do not install packages, change SSH server configuration, alter firewall rules, modify system services, or write outside the agreed remote working directory unless the user separately authorizes it.
+- On authentication failure, report the alias and failure class without echoing credentials. On network failure, distinguish DNS, timeout, refusal, host-key, and authentication errors before retrying.
+- Limit automatic retries to one for transient connection failures. Do not retry commands with uncertain side effects until their remote result has been checked.

package/skills/ssh-remote-dev/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SSH Remote Development"
+  short_description: "Safely develop in a remote workspace over SSH"
+  default_prompt: "Use $ssh-remote-dev to inspect and develop in my configured remote SSH workspace."

package/src/advisor/README.md

@@ -1,24 +1,62 @@
-# 自动顾问与文字交付契约
-
-TUI 和 Desktop 复用 `runQuery` 的检查点与工具事件，不在前端自行发起第二模型请求。
-仅已配置、启用且为自动模式的 Advisor 才进入有效工具集；仅手动模式保持手动调用。
-
-实质交付不限定为文件。调研结论、计算、方案比较、推荐也需要第二意见。
-提示词要求主模型主动识别；运行时补充确定性的文本信号（分析请求对应的
-非简短回答、含数字的成本/风险/推荐等），并保留变更、验证、正式成果与调查证据触发器。
-这些信号是可测试的启发式，不是完整语义分类器；短小含蓄的结论仍可能漏判，
-没有任何长度单独触发规则。不要将“自信”或“没有文件”当作豁免条件。
-
-执行前、连续失败、文字与文件交付共享待复核检查点。若模型仍试图继续解决或交付，
-宿主补一次对应 reason 的 Advisor 调用；用户明确不满、证据冲突、无法判断的表达
-也可建立检查点。只读诊断和人类澄清仍可进行。
-通过同一工具权限、取消、历史和 UI 事件通道执行，并将最新待交付草稿交给顾问。
-主模型读取意见后重新生成操作或回复，不执行咨询前预生成的后续操作。
-已完成同阶段咨询不重复调用；交付复核后成果又发生写入，重新开启交付复核；
-新增证据后的新冲突可以再问，普通读取本身不重开交付检查。
-明确仅修正拼写/文案的小修改不机械进行执行前或变更交付检查。
-顾问失败、被权限拒绝或达到执行上限时允许有界降级，并明确提示未复核；不无限重试，
-不将未调用、调用失败或顾问意见冒充验证证据。忽略提醒不再算尝试，
-实际失败/拒绝作为咨询结果留痕，未执行的检查点跨中断保留。
-
-回归入口：`bun test test/deliveryReview.test.ts test/loop.advisorGate.test.ts`。
+# 顾问：模型决定，宿主只提醒
+
+顾问的用法向 Claude Code 自带的 advisor 看齐：**谁来问、什么时候问由主模型自己判断**
+（规则写在 `prompts/policyRegistry.ts::capability.advisor` 和 `tools/advisor/advisor.ts::description`），
+顾问看到的是**整段对话**（上下文细则见 `CONTEXT.md`）。宿主不拦截、不扣答案、不替模型调用——
+这三样是旧 `AdvisorCoordinator`（867 行）的主要复杂度来源，而且都以降低回答实时性、制造误伤为代价：
+开着顾问时每个回答被藏起来整块出现，写文件被暂缓，合成的 Advisor 调用以模型名义写进历史。已全部移除，
+连同 `AdvisorDecision`（采纳留痕）和 `shareSensitive` 开关。
+
+## 宿主做的唯一一件事：AdvisorNudge
+
+`advisorNudge.ts` 只在一次 `runQuery` 内记账（改动、验证、调查证据、成功的咨询次数、卡住信号），
+产出两样东西：
+
+1. **提醒**——写进下一次请求的动态上下文（`loop.ts::buildRequestTransientContext`）：
+   - 实质请求（分析/调研/比较/计算/设计/推荐/成本或风险判断，或已调查够多）且还没咨询、还没动手：
+     "要动手修改，或要给出分析结论之前，先咨询一次"；
+   - 已有实质成果、自上次咨询后又有新进展：给出最终结论或交付之前先咨询；
+   - 同一问题连续失败/没有进展：继续重试之前先咨询（只读诊断和换路径不受影响）；
+   - 请求里有明显不满/证据冲突/无法判断的表达：先核查再咨询。
+   文字不带计数——它只在状态翻转时变化，不会每个请求都改写缓存前缀。顾问不可用、
+   `advisorReminders:false`（只读内嵌节点）、简短即时问答、纯文案/routine 维护请求：都不提醒。
+2. **一条非阻塞 warning**——最终回答发布时，实质成果仍没经顾问复核则提示一次
+   （"没有经过顾问复核；不能把它视为已复核"）。回答本身已经实时显示，warning 在它之后。
+   澄清提问和一两句话不算成果（草稿只能豁免自己，不能触发）。
+
+"请求是否实质"仍是写之前就能知道的启发式（`deliveryReview.ts::requestNeedsTextReview`）：
+"继续/展开第二点"沿用上一条请求的判定，"计算机/对比度"这类只是含了分析词的不算。
+这是可测试的启发式，不是语义分类器；不要把"自信"或"没有文件"当成豁免条件。
+
+## 弱模型兜底：贴近动作的提示 + 可选的补问（`advisor.enforcement`）
+
+动态上下文里的提醒离模型的下一步很远，弱基座模型多轮之后基本读不到。两处补强，都不拦截、不扣答案、不伪造调用：
+
+1. **首次改动提示**（始终开启）：实质请求里第一次动手改东西、却还没咨询过——提示作为一行文字贴在
+   **那条工具结果**末尾（`takeActionHint`，整个运行内一次）。工具照常执行；工具结果是模型下一次请求里最近的内容。
+2. **补问回合**（配置 `advisor.enforcement: 'followup'`，默认 `'remind'`）：实质回答发布后仍未复核，
+   loop 追加一条系统提示用户消息（`pushAdvisorFollowUpMarker`）再发一次请求，让**模型自己**调用 Advisor——
+   回答不撤回，Advisor 调用是模型发出的。每个 `runQuery` 最多一次；模型不理会就由 warning 收尾。
+   代价是多一次全上下文请求，只给不会主动咨询的基座开。`RunQueryOptions.advisorFollowUp` 可显式覆盖配置。
+
+## 唯一的"暂缓"：同一批里排在 Advisor 之后的调用
+
+模型一次响应里同时发出 `Advisor` 和后续调用时，排在 Advisor **之后**的调用不执行（回给模型的是
+`disposition: 'deferred'` 的说明），让它先读完意见再重新规划——与自己用顾问的方式一致："读完意见再操作"。
+排在 Advisor 之前的调用（比如同批的 Read）照常执行，并且已经在顾问收到的历史里
+（`test/advisorBackground.test.ts` 锁这条）。这只是一次批内的顺序规则，不是检查点：顾问不会因此
+推迟任何独立的工具调用，也不会扣下回答。
+
+## 谁来停住重复失败
+
+`StallGuard`：同一调用连续两次返回相同失败，第三次在执行前被拒绝——**与顾问是否可用无关**。
+顾问只提醒之后，没有别的东西能停住循环。成功的咨询会让守卫清零（`noteConsultation`），
+否则顾问建议"修好环境再试"时同一条命令仍被拒。
+
+## 降级
+
+每次咨询只尝试一次；不可用、失败、空答、超时都以 `ok:false` 回到主模型，由它自行继续，
+不自动重试、不转成人工审批、不宣称获得验证。不设咨询配额。
+
+回归入口：`bun test test/advisorNudge.test.ts test/loop.advisorNudge.test.ts test/deliveryReview.test.ts
+test/advisorContextFidelity.test.ts test/advisor.test.ts`。

package/src/advisor/advisorNudge.js

@@ -0,0 +1,199 @@
+import { isCosmeticRequest, isReviewProcessQuestion, isRoutineMaintenancePath, isRoutineMaintenanceRequest, needsTextDeliveryReview, requestNeedsTextReview, reviewSignal, } from './deliveryReview.js';
+/**
+ * ============================================================
+ *  src/advisor/advisorNudge.ts —— 顾问的"提醒"，不是"闸门"
+ * ------------------------------------------------------------
+ *  谁来问顾问由模型自己决定（时机规则在提示词与 Advisor 工具说明里），宿主只做一件事：
+ *  把"你还没问"这个事实，用动态上下文里的一行话告诉模型。
+ *
+ *  它**不**拦截工具、**不**扣下回答、**不**替模型伪造 Advisor 调用——这三样是旧
+ *  AdvisorCoordinator 的主要复杂度来源，而且都以降低回答的实时性、增加误伤为代价
+ *  （开着顾问时每个回答被藏起来整块出现；写文件被暂缓；合成的 Advisor 调用以模型名义
+ *  写进历史）。提醒是否被采纳由模型判断；没被采纳时，唯一的后果是最终回答附一条
+ *  非阻塞的 warning，如实说明"这份实质成果没经顾问复核"。
+ *
+ *  只在**一次 runQuery** 内记账，不跨回合恢复（上一回合问没问过，与这一回合无关）。
+ *
+ *  提醒文字刻意不带计数：它进入当轮请求的易变上下文，文字稳定则只在状态翻转时
+ *  改变一两次，不会每个请求都改写前缀。
+ * ============================================================
+ */
+const INVESTIGATION_TOOLS = new Set([
+    'Read', 'Glob', 'Grep', 'LSP', 'WebSearch', 'WebFetch', 'WebBrowser',
+    'TerminalCapture', 'RecallMemory', 'SearchConversations',
+]);
+const MUTATING_ACTIVITY = new Set(['created', 'modified', 'generated', 'deleted']);
+/** 调查证据攒到这个数，就算做了足以需要复核的实事（与旧触发阈值一致）。 */
+const EVIDENCE_THRESHOLD = 3;
+export class AdvisorNudge {
+    #request;
+    #previousRequest;
+    #available;
+    #consultations = 0;
+    /** 进度计数：每次改动、验证、调查证据 +1。咨询时记下当时的值。 */
+    #progress = 0;
+    #consultedAtProgress = -1;
+    #mutations = 0;
+    #nonRoutineMutation = false;
+    #verifications = 0;
+    #evidence = 0;
+    #delivered = false;
+    #signal;
+    #stalled = new Set();
+    #warned = false;
+    #followedUp = false;
+    #actionHintDue = false;
+    #actionHinted = false;
+    constructor(input) {
+        this.#request = input.currentRequest;
+        this.#previousRequest = input.previousRequest;
+        this.#available = input.advisorAvailable;
+        this.#signal = reviewSignal(input.currentRequest);
+    }
+    setAvailable(available) {
+        this.#available = available;
+    }
+    /** 本次运行内成功咨询的次数。 */
+    get consultations() {
+        return this.#consultations;
+    }
+    observeToolResult(call, result, semantics) {
+        if (!result.ok && result.disposition === 'deferred')
+            return;
+        const name = call.function.name;
+        if (name === 'Advisor') {
+            if (result.ok) {
+                this.#consultations++;
+                this.#consultedAtProgress = this.#progress;
+                this.#stalled.clear();
+                this.#signal = undefined;
+            }
+            return;
+        }
+        if (name === 'OptimizeConversation')
+            return;
+        const mutationsBefore = this.#mutations;
+        const metadata = result.metadata;
+        if (metadata?.kind === 'process_execution' && metadata.commandKind !== 'other'
+            && ['completed', 'failed'].includes(metadata.status)) {
+            this.#verifications++;
+            this.#progress++;
+        }
+        if (!result.ok)
+            return;
+        if (metadata?.kind === 'file_activity') {
+            const changes = metadata.files.filter((file) => MUTATING_ACTIVITY.has(file.activity));
+            this.#mutations += changes.length;
+            this.#progress += changes.length;
+            this.#nonRoutineMutation ||= changes.some((file) => file.activity === 'deleted' || !isRoutineMaintenancePath(file.relativePath));
+        }
+        else if (semantics?.mutatesWorkspace) {
+            this.#mutations++;
+            this.#progress++;
+            this.#nonRoutineMutation = true;
+        }
+        if (metadata?.kind === 'result_manifest') {
+            this.#delivered = true;
+            this.#progress++;
+        }
+        if (INVESTIGATION_TOOLS.has(name)) {
+            this.#evidence++;
+            this.#progress++;
+        }
+        // 第一次动手改东西、却还没问过顾问：提示贴在这条工具结果上（见 takeActionHint）。
+        if (this.#mutations > mutationsBefore && this.#available && this.#consultations === 0
+            && !this.#actionHinted && this.#substantive()) {
+            this.#actionHintDue = true;
+        }
+    }
+    /**
+     * 贴在"第一次改动"那条工具结果末尾的一行提示（整个运行内最多一次）。
+     * 动态上下文里的提醒离模型的下一步很远，弱模型多轮之后基本读不到；工具结果是它下一次
+     * 请求里最近的内容。工具照常执行，这只是文字，不推迟、不拦截。
+     */
+    takeActionHint() {
+        if (!this.#actionHintDue)
+            return '';
+        this.#actionHintDue = false;
+        this.#actionHinted = true;
+        return '[Advisor 提醒] 你已开始动手改动，但本回合还没有咨询顾问。继续下一步之前先调用 Advisor 复核方案；简短的即时问答不需要。';
+    }
+    /** 连续同类失败或没有进展：继续重试之前先问（提醒，不阻止只读诊断或换路径）。 */
+    notifyStalled(signature) {
+        this.#stalled.add(signature);
+    }
+    /** 本回合做过足以需要复核的实事（改动、验证、正式成果、足量调查证据）。 */
+    #hasWork() {
+        return (this.#mutations > 0 && !isCosmeticRequest(this.#request))
+            || this.#verifications > 0
+            || this.#delivered
+            || this.#evidence >= EVIDENCE_THRESHOLD;
+    }
+    /** 这个请求是否需要第二意见：做了实事，或请求本身就是分析/比较/推荐/成本风险判断。 */
+    #substantive() {
+        if (isReviewProcessQuestion(this.#request) && this.#mutations === 0 && !this.#delivered)
+            return false;
+        if (isRoutineMaintenanceRequest(this.#request) && !this.#nonRoutineMutation && !this.#delivered)
+            return false;
+        return this.#hasWork() || requestNeedsTextReview(this.#request, this.#previousRequest);
+    }
+    /** 最近一次咨询之后，是否又有了新的进展（或根本没问过）。 */
+    #unreviewed() {
+        return this.#consultedAtProgress < 0 || this.#progress > this.#consultedAtProgress;
+    }
+    /** 要交付的实质成果是否缺一次复核；最终回答发布时据此决定是否附 warning。 */
+    needsDeliveryReview() {
+        return this.#available && this.#substantive() && this.#unreviewed();
+    }
+    /** 下一次请求的动态提醒。顾问不可用时为空。 */
+    reminder() {
+        if (!this.#available)
+            return '';
+        const lines = [];
+        if (this.#stalled.size > 0) {
+            lines.push('Advisor 提醒：检测到同一问题连续失败或执行没有进展。继续重试之前先咨询 Advisor（只读诊断和换路径不受影响）。');
+        }
+        if (this.#signal && this.#consultations === 0) {
+            lines.push(this.#signal === 'user_dissatisfaction'
+                ? 'Advisor 提醒：用户对结果明显不满。先核查已有材料，再咨询 Advisor 对照用户的验收项。'
+                : this.#signal === 'evidence_conflict'
+                    ? 'Advisor 提醒：材料之间存在冲突。核查后仍无法判断哪边对，请咨询 Advisor。'
+                    : 'Advisor 提醒：你可能还不确定该怎么处理。动手之前可以先咨询 Advisor。');
+        }
+        const substantive = this.#substantive();
+        if (substantive && this.#consultations === 0 && this.#mutations === 0 && !this.#delivered) {
+            lines.push('Advisor 提醒：本回合还没有咨询顾问。要动手修改，或要给出分析结论之前，先咨询一次 Advisor；简短的即时问答不需要。');
+        }
+        else if (substantive && this.#unreviewed()) {
+            lines.push('Advisor 提醒：本回合已有实质成果（改动、验证或调查结论），自上次咨询后又有新进展。给出最终结论或交付之前，先咨询一次 Advisor。');
+        }
+        return lines.join('\n');
+    }
+    #answerNeedsReview(answer) {
+        if (!this.needsDeliveryReview())
+            return false;
+        // 没做过实事、只是一段回答时，澄清提问和一两句话不算成果（草稿只能豁免自己）。
+        // 补问之后的那句简短回应不会自己够格；要不要警告看的是被补问的那版实质回答。
+        return this.#followedUp || this.#hasWork() || needsTextDeliveryReview(this.#request, answer, this.#previousRequest);
+    }
+    /**
+     * 这版回答发布后是否该补问一次顾问（`advisor.enforcement: 'followup'`，给不会主动咨询的弱模型）。
+     * 判据与 warning 相同，整个运行内只给一次；回答本身已显示，不撤回。
+     */
+    followUpDue(answer) {
+        return !this.#followedUp && this.#answerNeedsReview(answer);
+    }
+    markFollowedUp() {
+        this.#followedUp = true;
+    }
+    /**
+     * 最终回答发布时调用：实质成果没经顾问复核，则返回一条（本次运行内只给一次）
+     * 非阻塞的 warning；已复核、顾问不可用、或不是实质成果则不打扰。
+     */
+    unreviewedWarning(answer) {
+        if (this.#warned || !this.#answerNeedsReview(answer))
+            return undefined;
+        this.#warned = true;
+        return '本回答包含实质结论或成果，但没有经过顾问复核；不能把它视为已复核。';
+    }
+}