dsh-advisor-plugin 0.2.1

package/src/patrol.ts

@@ -0,0 +1,229 @@
+/**
+ * patrol —— 巡逻模式：把 advisor 从"被动求助"升级为"主动监控"。
+ *
+ * 工作方式：
+ *   1. agent/request 每步触发（复用现有 waterfall），按间隔步数 + 最小时间
+ *      间隔决定是否发起一次巡逻（不阻塞当前请求，异步执行）；
+ *   2. 巡逻 = 把会话快照 + 巡逻问题发给审查模型，要求回
+ *      ON-TRACK / CORRECTION: ... / STOP: ... 三选一裁决；
+ *   3. 裁决为纠偏/停止时，把干预文本经 `agent.inject()` 以 user 上下文排进
+ *      下一步请求——落在对话尾部（新近性最高，实测系统提示段在几百条工具
+ *      结果的会话里权重不足，执行模型"读到但不动"）；同时把裁决写入会话
+ *      日志（patrol-event.ts，log-only），消息流出 🧭 巡逻卡片（ON-TRACK
+ *      出低调灰卡，unclear 不出）；
+ *   4. 侧调用（巡逻自身 + 显式 advisor() 工具）通过 llm-call 的
+ *      深度计数排除，避免把自己的请求当成执行请求。
+ *
+ * 成本提示：每次巡逻 = 整段会话计费一次审查模型（与显式 advisor()
+ * 相同）。patrolEnabled / patrolEverySteps 可在设置页调整或关闭。
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Message } from '@deepseek-ai/dsh-llm'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { PATROL_NUDGE, PATROL_SYSTEM_PROMPT, buildInterventionText } from './advisor-prompt.js'
+import type { Config, Selection } from './config.js'
+import { isExecutorBlocked } from './config.js'
+import { callReviewer, stripExecutorEcho } from './llm-call.js'
+import { appendPatrolVerdict } from './patrol-event.js'
+import { createAdviceDeduper, isContentFreeAdvice, normalizeAdvice } from './emission-guard.js'
+
+/** 两次巡逻之间的最小墙钟间隔（防止快速工具链把审查模型打爆） */
+export const MIN_PATROL_INTERVAL_MS = 90_000
+
+/** 巡逻裁决（解析失败归为 unclear——不确定时宁可不打扰执行模型） */
+export type PatrolVerdictKind = 'on-track' | 'correction' | 'stop' | 'unclear'
+
+export interface PatrolVerdict {
+  kind: PatrolVerdictKind
+  detail: string
+}
+
+/** 是否该发起一次巡逻（纯函数，可单测） */
+export function shouldPatrol(input: {
+  armed: boolean
+  blocked: boolean
+  step: number
+  everySteps: number
+  now: number
+  lastPatrolMs: number
+  minIntervalMs: number
+  inFlight: boolean
+  patrolEnabled: boolean
+}): boolean {
+  if (!input.patrolEnabled || !input.armed || input.blocked || input.inFlight) return false
+  if (input.everySteps < 1) return false
+  if (input.step % input.everySteps !== 0) return false
+  return input.now - input.lastPatrolMs >= input.minIntervalMs
+}
+
+/** 解析审查模型的巡逻裁决（纯函数）：只认首行前缀，其余整段作为细节 */
+export function parsePatrolVerdict(text: string): PatrolVerdict {
+  const trimmed = text.trim()
+  if (trimmed === '') return { kind: 'unclear', detail: '' }
+  const firstLineEnd = trimmed.indexOf('\n')
+  const firstLine = (firstLineEnd === -1 ? trimmed : trimmed.slice(0, firstLineEnd)).trim()
+  const rest = firstLineEnd === -1 ? '' : trimmed.slice(firstLineEnd + 1).trim()
+  const upper = firstLine.toUpperCase()
+  if (upper.startsWith('ON-TRACK')) return { kind: 'on-track', detail: rest }
+  if (upper.startsWith('CORRECTION:') || upper.startsWith('CORRECTION')) {
+    const inline = firstLine.slice(firstLine.indexOf(':') + 1).trim()
+    return { kind: 'correction', detail: [inline, rest].filter(s => s !== '').join('\n') }
+  }
+  if (upper.startsWith('STOP:') || upper.startsWith('STOP')) {
+    const inline = firstLine.slice(firstLine.indexOf(':') + 1).trim()
+    return { kind: 'stop', detail: [inline, rest].filter(s => s !== '').join('\n') }
+  }
+  return { kind: 'unclear', detail: trimmed }
+}
+
+function createUserText(text: string): Message {
+  return createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
+}
+
+export interface PatrolDeps {
+  getConfig: () => Config
+  getSelection: () => Selection | undefined
+  buildMessages: (agent: Agent) => Message[]
+}
+
+export function registerPatrol(ctx: Context, deps: PatrolDeps): () => void {
+  const stepCounts = new Map<Agent, number>()
+  /** 每 agent 的建议去重器（防噪闸之一：会话内精确去重） */
+  const dedupers = new Map<Agent, (normalized: string) => boolean>()
+  /** 每 agent 的纠偏冷却终点（步数）：一次注入后 N 个请求内 concern 降级 */
+  const immuneUntilStep = new Map<Agent, number>()
+  let lastPatrolMs = 0
+  let inFlight = false
+
+  const runPatrol = async (agent: Agent) => {
+    const selection = deps.getSelection()
+    if (selection === undefined) return
+    inFlight = true
+    const startedAt = Date.now()
+    try {
+      // 快照末尾挂巡逻问题（与显式咨询共用消息组装，含工具清单前缀与尾部规则）
+      const messages = [...deps.buildMessages(agent), createUserText(PATROL_NUDGE)]
+      // 调查授权：审查模型可先在工作区内只读核实再裁决（cwd 缺省时不启用）
+      const investigate = deps.getConfig().investigate !== false ? agent.session.header.cwd : undefined
+      const outcome = await callReviewer(ctx, selection, PATROL_SYSTEM_PROMPT, messages, undefined, investigate, agent.session.id)
+      if (!outcome.ok) {
+        console.log(`[dsh-advisor][patrol] 巡逻调用失败（已跳过本轮）：${outcome.errorMessage}`)
+        return
+      }
+      const verdict = parsePatrolVerdict(stripExecutorEcho(outcome.text, messages))
+      const elapsed = Math.round(Date.now() - startedAt)
+      if (verdict.kind === 'on-track') {
+        console.log(`[dsh-advisor][patrol] ON-TRACK（${elapsed}ms）——执行方向正常`)
+        // 低调灰卡：on-track 也写事件（用户拍板的完整视野）；写失败不影响巡逻
+        appendPatrolVerdict(agent.session, {
+          verdict: 'on-track',
+          detail: verdict.detail,
+          step: stepCounts.get(agent) ?? 0,
+          reviewer: `${selection.provider}/${selection.model}`,
+          patrolMs: elapsed,
+          usage: outcome.usage,
+        })
+        return
+      }
+      if (verdict.kind === 'unclear') {
+        // 解析失败不出卡片（不是"检查通过"也不是"需要干预"，只留日志）
+        console.log(`[dsh-advisor][patrol] 裁决不可解析（${elapsed}ms），不打扰执行模型。原文前 200 字：${outcome.text.slice(0, 200)}`)
+        return
+      }
+      console.log(`[dsh-advisor][patrol] ${verdict.kind === 'stop' ? 'STOP' : 'CORRECTION'}（${elapsed}ms）：${verdict.detail.slice(0, 200)}`)
+      // 防噪闸 ①：内容空短语——只给结论不给理由的建议没有信息量，按不打扰处理
+      const normalized = normalizeAdvice(verdict.detail)
+      if (isContentFreeAdvice(normalized)) {
+        console.log(`[dsh-advisor][patrol] 裁决内容空（归一化后无实质信息），不打扰执行模型：${normalized.slice(0, 60)}`)
+        return
+      }
+      const deduper = dedupers.get(agent) ?? createAdviceDeduper()
+      dedupers.set(agent, deduper)
+      // 冷却降级：一次注入后 N 个请求内，correction 只出卡片不注入（stop 豁免）
+      const step = stepCounts.get(agent) ?? 0
+      const downgraded = verdict.kind === 'correction' && step < (immuneUntilStep.get(agent) ?? -1)
+      // 人类可观测性通道：裁决写入会话日志，消息流将出现 🧭 卡片（log-only）
+      appendPatrolVerdict(agent.session, {
+        verdict: verdict.kind,
+        detail: verdict.detail,
+        step,
+        reviewer: `${selection.provider}/${selection.model}`,
+        patrolMs: elapsed,
+        usage: outcome.usage,
+        ...(downgraded ? { downgraded: true } : {}),
+      })
+      console.log('[dsh-advisor][patrol] 裁决已写入会话事件')
+      // 防噪闸 ②：会话内精确去重——与已注入过的建议重复则丢弃（只记日志）
+      if (!downgraded && !deduper(normalized)) {
+        console.log('[dsh-advisor][patrol] 与此前已注入的纠偏重复，丢弃本次注入')
+        return
+      }
+      if (downgraded) {
+        console.log(`[dsh-advisor][patrol] 纠偏冷却期内（第 ${step} 步 < ${immuneUntilStep.get(agent)}），本次只出卡片不注入`)
+        return
+      }
+      // 模型面投递：agent.inject() 把干预排成下一步请求的尾部 user 上下文。
+      // 实测教训：系统提示动态段在几百条工具结果的会话里新近性不足，执行
+      // 模型"读到但不动"；尾部上下文是文件变更通知/skill 内容同款官方通道，
+      // 位置就是模型注意力最集中的对话末尾，且 UI 会渲染成上下文行。
+      try {
+        const immuneTurns = deps.getConfig().patrolImmuneTurns ?? 3
+        if (verdict.kind === 'correction' && immuneTurns > 0) {
+          immuneUntilStep.set(agent, step + immuneTurns)
+        }
+        agent.inject(createUserMessage({
+          content: [{ type: 'text', text: buildInterventionText(verdict.kind, verdict.detail) }],
+          source: {
+            kind: 'plugin',
+            plugin: 'dsh-advisor',
+            form: 'notice',
+            summary: `${verdict.kind === 'stop' ? '巡逻叫停' : '巡逻纠偏'}：${verdict.detail.slice(0, 60)}`,
+          },
+        }))
+        console.log(`[dsh-advisor][patrol] 已将${verdict.kind === 'stop' ? '停止' : '纠偏'}干预排入下一步请求（尾部上下文）`)
+      } catch (error) {
+        // 注入失败不影响巡逻本身
+        console.warn('[dsh-advisor][patrol] 干预注入失败：', error)
+      }
+    } finally {
+      inFlight = false
+    }
+  }
+
+  const disposeRequest = ctx.on('agent/request', async (payload, next) => {
+    const config = await next()
+    try {
+      const agent = payload.agent
+      const step = (stepCounts.get(agent) ?? 0) + 1
+      stepCounts.set(agent, step)
+      const pluginConfig = deps.getConfig()
+      const blocked = isExecutorBlocked(pluginConfig, config.provider, config.model, config.reasoningEffort)
+      if (!shouldPatrol({
+        armed: deps.getSelection() !== undefined,
+        blocked,
+        step,
+        everySteps: pluginConfig.patrolEverySteps ?? 6,
+        now: Date.now(),
+        lastPatrolMs,
+        minIntervalMs: MIN_PATROL_INTERVAL_MS,
+        inFlight,
+        patrolEnabled: pluginConfig.patrolEnabled !== false,
+      })) return config
+      lastPatrolMs = Date.now()
+      void runPatrol(agent)
+    } catch (error) {
+      // 巡逻绝不破坏用户的 turn
+      console.error('[dsh-advisor][patrol] 调度失败：', error)
+    }
+    return config
+  })
+
+  return () => {
+    disposeRequest()
+    stepCounts.clear()
+    dedupers.clear()
+    immuneUntilStep.clear()
+  }
+}

package/src/prompt-section.ts

@@ -0,0 +1,21 @@
+/**
+ * prompt-section —— 注入系统提示的升级守则段。
+ * 只在已选审查模型时注册——未武装的 advisor 零提示词成本。
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import { DEFAULT_GUIDELINES } from './advisor-prompt.js'
+import type { Config } from './config.js'
+
+export function registerAdvisorSection(ctx: Context, config: Config): () => void {
+  const guidelines = config.guidelines === undefined || config.guidelines.length === 0
+    ? DEFAULT_GUIDELINES
+    : config.guidelines
+  const text = ['## Advisor escalation', '', ...guidelines.map(g => `- ${g}`)].join('\n')
+  return ctx.systemPrompt.section({
+    name: 'advisor-guidelines',
+    order: 550,
+    text,
+  })
+}

package/src/settings.ts

@@ -0,0 +1,74 @@
+/**
+ * settings —— 把 'advisor' 命名空间接入 settings 服务（用户层 =
+ * ~/.dsh/settings.yaml 的 advisor: 段；设置页卡片写的也是这一层）。
+ *
+ * 双路径兼容（rc.6 与更新版本宿主）：
+ *   - installSection（较新宿主）：带 setSource/onChange 钩子的注册面
+ *   - settings.register（rc.6）：scope.get() 初读 + scope.watch() 活编辑
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-settings'
+import { Config as ConfigSchema, resolveSelection, type Config, type Selection } from './config.js'
+
+export interface SettingsWiring {
+  /** 设置服务状态描述（进 /advisor 命令输出与日志） */
+  info: string
+}
+
+export function wireSettings(
+  ctx: Context,
+  state: { config: Config, selection: Selection | undefined },
+  onConfigChange: () => void,
+): SettingsWiring {
+  const settings = ctx.get('settings') as
+    | {
+      installSection?: (ctx: Context, ns: string, schema: unknown, entry: unknown, hooks: unknown) => void
+      register?: (ns: string, schema: unknown, options?: { base?: unknown }) => {
+        get: () => Config
+        watch: (cb: (next: Config) => void) => () => void
+      }
+    }
+    | undefined
+
+  if (settings === undefined) {
+    return { info: 'settings 服务不可用——advisor 配置固定为插件组合层' }
+  }
+
+  if (typeof settings.installSection === 'function') {
+    // 较新宿主：setSource 把"当前值来源"交给设置服务接管
+    let source: () => Config = () => state.config
+    settings.installSection(ctx, 'advisor', ConfigSchema, state.config, {
+      setSource: (next: () => Config) => {
+        source = next
+      },
+      onChange: () => {
+        state.config = source()
+        state.selection = resolveSelection(state.config)
+        onConfigChange()
+      },
+    })
+    return { info: 'settings.installSection 已接入（advisor 命名空间可在设置页编辑）' }
+  }
+
+  if (typeof settings.register === 'function') {
+    // rc.6 宿主：scope.get() 读合成值（schema 默认 → base → 用户层），watch 活编辑
+    try {
+      const scope = settings.register('advisor', ConfigSchema, { base: state.config })
+      const resolved = scope.get()
+      state.selection = resolveSelection(resolved)
+      state.config = resolved
+      onConfigChange()
+      scope.watch(next => {
+        state.config = next
+        state.selection = resolveSelection(next)
+        onConfigChange()
+      })
+      return { info: `settings.register 已接入（advisor 命名空间，用户层在 ~/.dsh/settings.yaml）` }
+    } catch (error) {
+      return { info: `settings.register 失败：${error instanceof Error ? error.message : String(error)}` }
+    }
+  }
+
+  return { info: 'settings 服务形态未知——advisor 配置固定为插件组合层' }
+}

package/src/tool.ts

@@ -0,0 +1,114 @@
+/**
+ * tool —— 零参数 `advisor` 工具（defineTool）。
+ *
+ * execute() 解析当前选择 → 组装审查消息 → 侧调用 → 返回规范值；
+ * 每条失败路径同样返回值（渲染成可读文本），执行模型读到错误说明后
+ * 继续本轮——advisor 挂掉绝不炸掉执行模型的 turn。
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ContentBlock, TextBlock } from '@deepseek-ai/dsh-llm'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { ADVISOR_SYSTEM_PROMPT, ADVISOR_TOOL_DESCRIPTION, ADVISOR_TOOL_NAME, MSG_NO_AGENT_SCOPE, MSG_NO_MODEL } from './advisor-prompt.js'
+import { selectionLabel, type Selection } from './config.js'
+import { callReviewer, stripExecutorEcho } from './llm-call.js'
+
+/** 工具结果信封：成功带指导文本，失败带可读错误（渲染层只取文本） */
+export interface AdvisorValue {
+  ok: boolean
+  advisorModel: string
+  guidance?: string
+  effort?: string
+  finishKind?: string
+  errorMessage?: string
+  inputTokens?: number
+  outputTokens?: number
+}
+
+function renderText(value: AdvisorValue): string {
+  if (!value.ok) return value.errorMessage ?? 'Advisor call failed.'
+  return value.guidance ?? ''
+}
+
+/** 从工具结果内容块提取纯文本（presentResult 只拿得到渲染后的内容块） */
+function textOfContent(content: ContentBlock[]): string {
+  return content
+    .filter((block): block is TextBlock => block.type === 'text')
+    .map(block => block.text)
+    .join('\n')
+    .trim()
+}
+
+export function createAdvisorTool(
+  ctx: Context,
+  getSelection: () => Selection | undefined,
+  buildMessages: (agent: Agent) => import('@deepseek-ai/dsh-llm').Message[],
+  getConfig: () => import('./config.js').Config,
+) {
+  return defineTool({
+    name: ADVISOR_TOOL_NAME,
+    description: ADVISOR_TOOL_DESCRIPTION,
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          advisorModel: { type: 'string' },
+          guidance: { type: 'string' },
+          effort: { type: 'string' },
+          finishKind: { type: 'string' },
+          errorMessage: { type: 'string' },
+          inputTokens: { type: 'number' },
+          outputTokens: { type: 'number' },
+        },
+      },
+      render: (_args, value): ContentBlock[] => [{ type: 'text', text: renderText(value as unknown as AdvisorValue) }],
+    },
+    // 专属卡片：调用中/结果两态都有 🧭 标识，结果卡片正文就是审查建议，
+    // 用户在消息列表展开即见"真的调了 advisor、建议是什么"
+    presentCall: () => ({ card: 'generic', title: '🧭 Advisor 咨询中…' }),
+    presentResult: (_args, result) => {
+      const text = textOfContent(result.content)
+      return {
+        card: 'generic',
+        title: result.isError ? '🧭 Advisor 调用失败' : '🧭 Advisor 建议',
+        ...(text === '' ? {} : { content: [{ type: 'text' as const, text }] }),
+      }
+    },
+    async execute(_args, exec) {
+      const selection = getSelection()
+      if (selection === undefined) {
+        return { ok: false, advisorModel: '(not configured)', errorMessage: MSG_NO_MODEL } satisfies AdvisorValue
+      }
+      if (exec.agent === undefined) {
+        return { ok: false, advisorModel: selectionLabel(selection), errorMessage: MSG_NO_AGENT_SCOPE } satisfies AdvisorValue
+      }
+      const messages = buildMessages(exec.agent)
+      // 调查授权与巡逻一致：审查模型可先只读核实再给建议
+      const investigate = getConfig().investigate !== false ? exec.agent.session.header.cwd : undefined
+      const outcome = await callReviewer(ctx, selection, ADVISOR_SYSTEM_PROMPT, messages, exec.signal, investigate, exec.agent.session.id)
+      if (!outcome.ok) {
+        return {
+          ok: false,
+          advisorModel: selectionLabel(selection),
+          ...(selection.effort === undefined ? {} : { effort: selection.effort }),
+          errorMessage: outcome.errorMessage,
+        } satisfies AdvisorValue
+      }
+      return {
+        ok: true,
+        advisorModel: selectionLabel(selection),
+        // 剥掉审查模型对执行模型"最后一句话"的回显（网关实测行为）
+        guidance: stripExecutorEcho(outcome.text, messages),
+        ...(selection.effort === undefined ? {} : { effort: selection.effort }),
+        finishKind: outcome.finishKind,
+        ...(outcome.usage === undefined
+          ? {}
+          : { inputTokens: outcome.usage.inputTokens, outputTokens: outcome.usage.outputTokens }),
+      } satisfies AdvisorValue
+    },
+  })
+}