dsh-advisor-plugin 0.2.1

package/src/client/patrol-chat.ts

@@ -0,0 +1,109 @@
+/**
+ * patrol-chat —— 巡逻裁决的会话聊天视图贡献（client 半）。
+ *
+ * 机制（0.1.1 实测反编译确认）：
+ *   - 会话事件流 → conversationEvents 注册的 Definition（事件→业务上下文
+ *     状态机）→ buildViewNode 物化聊天节点（kind 为判别键）→ ChatNodeSeat
+ *     按节点 kind 派发 keyed `conversation.chat.node` 槽 → 我们注册的
+ *     key 'advisor-patrol' 卡片渲染。
+ *   - Definition 匹配不独占：所有命中者各自物化。我们的 match 只认
+ *     plugin/point 双判别字段，stock 的 messageDefinition 等不会碰
+ *     log-only 的 hook/invoked，fallback 也只认 surface 事件——因此
+ *     该事件在全 UI 里只有这一张卡片，无重复渲染。
+ *   - 未装载本插件客户端（如 CLI 会话）时事件零渲染，静默无害。
+ *
+ * 类型策略：conversationEvents 服务在 0.1.1 声明于 dsh-client-runtime
+ * （本包未链接、版本间漂移），此处按结构收窄——同 controller.ts 对
+ * settingsScope 的做法，版本无关。
+ */
+
+import { isPatrolVerdictEvent, type PatrolEventData } from '../patrol-event.js'
+
+/** 会话事件的最小结构（client 侧收窄读取） */
+export interface PatrolEventLike {
+  readonly type?: unknown
+  readonly seq: number
+  readonly time: number
+  readonly data?: unknown
+  readonly location?: unknown
+}
+
+/** Definition match 返回的身份 */
+interface PatrolMatchResult {
+  readonly id: string
+  readonly role: 'start'
+}
+
+/** 引擎喂给 start/buildViewNode 的上下文（最小结构） */
+interface PatrolNodeContext {
+  readonly key: string
+  readonly id: string
+  readonly start?: { readonly location?: unknown } | undefined
+  readonly matches?: readonly { readonly location?: unknown }[] | undefined
+  readonly state?: PatrolNodeState | undefined
+}
+
+/** 节点数据 = 事件载荷 + 日志定位（卡片渲染的全部输入） */
+export interface PatrolNodeState extends PatrolEventData {
+  readonly seq: number
+  readonly time: number
+}
+
+/** 聊天节点的最终形态（ChatConversationViewNode 的结构子集） */
+export interface PatrolChatViewNode {
+  readonly key: string
+  readonly kind: 'advisor-patrol'
+  readonly id: string
+  readonly target: 'chat'
+  readonly anchorSeq: number
+  readonly location: unknown
+  readonly visibility: 'visible'
+  readonly data: PatrolNodeState
+}
+
+/** 事件定位兜底：start 匹配的位置 → 首个匹配的位置 → 未解析 */
+function patrolLocation(context: PatrolNodeContext): unknown {
+  return context.start?.location ?? context.matches?.[0]?.location ?? { kind: 'unresolved' }
+}
+
+/** 巡逻裁决的聊天 Definition（纯工厂，可单测） */
+export function patrolChatDefinition(): {
+  kind: 'advisor-patrol'
+  target: 'chat'
+  match(event: PatrolEventLike): PatrolMatchResult | null
+  start(_context: unknown, match: { event: PatrolEventLike }): PatrolNodeState
+  update(context: { state: PatrolNodeState }): PatrolNodeState
+  buildViewNode(context: PatrolNodeContext): PatrolChatViewNode | null
+} {
+  return {
+    kind: 'advisor-patrol',
+    target: 'chat',
+    match: (event) => {
+      if (!isPatrolVerdictEvent(event)) return null
+      return { id: `advisor-patrol-${event.seq}`, role: 'start' }
+    },
+    start: (_context, match) => {
+      const data = match.event.data as PatrolEventData
+      return { ...data, seq: match.event.seq, time: match.event.time }
+    },
+    update: (context) => context.state,
+    buildViewNode: (context) => {
+      if (context.state === undefined) return null
+      return {
+        key: context.key,
+        kind: 'advisor-patrol',
+        id: context.id,
+        target: 'chat',
+        anchorSeq: context.state.seq,
+        location: patrolLocation(context),
+        visibility: 'visible',
+        data: context.state,
+      }
+    },
+  }
+}
+
+/** conversationEvents 服务的结构化最小面（版本无关收窄） */
+export interface ConversationEventsService {
+  register(definition: ReturnType<typeof patrolChatDefinition>): () => void
+}

package/src/client/store.ts

@@ -0,0 +1,29 @@
+/**
+ * store —— 极简快照存储（结构兼容渲染器的 HostObservable：
+ * { getSnapshot, subscribe }），避免对官方 client-store 的值导入，
+ * 让外部 client 插件保持零运行时外部依赖。
+ */
+
+export interface SnapshotStore<T> {
+  getSnapshot(): T
+  subscribe(fn: () => void): () => void
+  set(value: T): void
+}
+
+export function createSnapshotStore<T>(initial: T): SnapshotStore<T> {
+  let current = initial
+  const listeners = new Set<() => void>()
+  return {
+    getSnapshot: () => current,
+    subscribe: (fn) => {
+      listeners.add(fn)
+      return () => {
+        listeners.delete(fn)
+      }
+    },
+    set: (value) => {
+      current = value
+      for (const fn of listeners) fn()
+    },
+  }
+}

package/src/command.ts

@@ -0,0 +1,61 @@
+/**
+ * command —— `/advisor` 人类命令：报告当前审查模型选择、逐 provider 列出
+ * 可配置模型（来自 llm 服务的模型目录）、以及黑名单状态。不产生模型消息。
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-commands'
+import { selectionLabel, type Config, type Selection } from './config.js'
+
+export function registerAdvisorCommand(
+  ctx: Context,
+  getConfig: () => Config,
+  getSelection: () => Selection | undefined,
+  getSettingsInfo: () => string,
+): (() => void) | undefined {
+  const commands = ctx.get('commands')
+  if (commands === undefined) return undefined
+  return commands.register({
+    name: 'advisor',
+    description: '查看 advisor（审查模型）配置与各 provider 可用模型',
+    handler: async () => {
+      const selection = getSelection()
+      const current = selection === undefined
+        ? '未配置审查模型——advisor 工具对模型不可见。'
+        : `Advisor：${selectionLabel(selection)}`
+
+      const providers = ctx.llm.listProviders()
+      let routesBlock: string
+      if (providers.length === 0) {
+        routesBlock = '没有已注册的 provider 路由（需要挂载 llm 适配器，如 llm-pi-ai）。'
+      } else {
+        const perProvider = await Promise.all(providers.map(async p => {
+          try {
+            const models = await ctx.llm.listModels(p.id)
+            const list = models.length === 0 ? '（无模型）' : models.map(m => m.id).join(', ')
+            return `- ${p.id}（${p.name}）: ${list}`
+          } catch {
+            return `- ${p.id}（${p.name}）: 模型列表获取失败`
+          }
+        }))
+        routesBlock = ['已注册 provider 路由与模型：', ...perProvider].join('\n')
+      }
+
+      const config = getConfig()
+      const blocklist = (config.disabledForModels ?? []).length === 0
+        ? '执行模型黑名单：（空）'
+        : `执行模型黑名单：${config.disabledForModels?.join(', ')}`
+
+      return {
+        kind: 'success',
+        text: [
+          current,
+          routesBlock,
+          blocklist,
+          getSettingsInfo(),
+          '在 设置 → 插件 → Advisor 卡片中选择审查模型，或直接编辑 ~/.dsh/settings.yaml 的 advisor: 段。',
+        ].join('\n'),
+      }
+    },
+  })
+}

package/src/config.ts

@@ -0,0 +1,113 @@
+/**
+ * config —— schemastery 配置 schema、审查模型选择解析、执行模型黑名单语法。
+ *
+ * 配置三层合成（rc.6 settings 服务）：schema 默认值 → 插件组合层 base →
+ * 用户层（~/.dsh/settings.yaml 的 advisor: 段，设置页卡片写入的就是这一层）。
+ *
+ * `provider` + `model` 两者齐备 advisor 才武装（对应 rpiv 的 "off costs
+ * nothing"：没有审查模型时工具与提示词段都不注册）。
+ *
+ * disabledForModels 条目语法（字符串数组，与设置页文案一致）：
+ *   "model"                 —— 任意 provider 跑该模型都禁用
+ *   "provider/model"        —— 精确路由禁用
+ *   "provider/model@effort" —— 档位达到 effort 及以上才禁用
+ */
+
+import z from '@deepseek-ai/schemastery'
+
+export interface Config {
+  provider?: string
+  model?: string
+  effort?: string
+  disabledForModels?: string[]
+  guidelines?: string[]
+  patrolEnabled?: boolean
+  patrolEverySteps?: number
+  patrolImmuneTurns?: number
+  investigate?: boolean
+}
+
+export const Config: z<Config> = z.object({
+  provider: z.string().default('').description('审查模型所在的 provider 路由名（ctx.llm 适配器路由，如 example-provider）'),
+  model: z.string().default('').description('该路由下的审查模型 id（如 deepseek-v4-pro）'),
+  effort: z.string().default('').description('审查模型推理档位；留空走模型默认'),
+  disabledForModels: z.array(z.string()).default([]).description('执行模型黑名单："model" / "provider/model" / "provider/model@minEffort"'),
+  guidelines: z.array(z.string()).default([]).description('覆盖默认的升级守则（系统提示段文本，每条一行）'),
+  patrolEnabled: z.boolean().default(true).description('巡逻模式：执行中每 N 步自动把会话快照发给审查模型检查是否跑偏，跑偏时注入纠偏'),
+  patrolEverySteps: z.number().default(6).min(2).max(500).description('巡逻间隔（模型请求步数）；每次巡逻整段会话计费一次审查模型。当保底用可以配大（如 100）'),
+  patrolImmuneTurns: z.number().default(3).min(0).max(20).description('纠偏冷却：一次纠偏注入后的 N 个请求内，新的 CORRECTION 降级为只出卡片不注入（STOP 不受冷却限制）'),
+  investigate: z.boolean().default(true).description('审查者调查工具：允许审查模型在裁决前用只读工具（工作区内搜索/读文件）亲自核实，建议更有据'),
+})
+
+/** 已武装的审查路由；undefined = advisor 关闭 */
+export interface Selection {
+  readonly provider: string
+  readonly model: string
+  readonly effort?: string
+}
+
+export function resolveSelection(config: Config): Selection | undefined {
+  const { provider, model } = config
+  if (provider === undefined || provider === '' || model === undefined || model === '') return undefined
+  return config.effort === undefined || config.effort === ''
+    ? { provider, model }
+    : { provider, model, effort: config.effort }
+}
+
+export function selectionLabel(selection: Selection): string {
+  return selection.effort === undefined
+    ? `${selection.provider}/${selection.model}`
+    : `${selection.provider}/${selection.model} (${selection.effort})`
+}
+
+// "@minEffort" 阈值比较用的档位序；未知档位排名 NaN 而不是猜
+const EFFORT_LADDER = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const
+
+function effortRank(effort: string): number {
+  const index = EFFORT_LADDER.indexOf(effort as (typeof EFFORT_LADDER)[number])
+  return index === -1 ? Number.NaN : index
+}
+
+interface BlockRule {
+  provider?: string
+  model: string
+  minEffort?: string
+}
+
+function parseRule(entry: string): BlockRule | undefined {
+  const parts = entry.split('@')
+  const route = parts[0] ?? ''
+  const minEffort = parts[1]
+  const trimmed = route.trim()
+  if (trimmed === '') return undefined
+  const slash = trimmed.indexOf('/')
+  if (slash === -1) return { model: trimmed, ...(minEffort === undefined ? {} : { minEffort }) }
+  return {
+    provider: trimmed.slice(0, slash),
+    model: trimmed.slice(slash + 1),
+    ...(minEffort === undefined ? {} : { minEffort }),
+  }
+}
+
+/** 执行路由在当前档位下是否命中黑名单（fail-soft：未知档位/未知阈值不禁用） */
+export function isExecutorBlocked(
+  config: Config,
+  provider: string | undefined,
+  model: string | undefined,
+  reasoningEffort: string | undefined,
+): boolean {
+  if (provider === undefined || model === undefined) return false
+  for (const entry of config.disabledForModels ?? []) {
+    const rule = parseRule(entry)
+    if (rule === undefined) continue
+    if (rule.provider !== undefined && rule.provider !== provider) continue
+    if (rule.model !== model) continue
+    if (rule.minEffort !== undefined) {
+      const current = effortRank(reasoningEffort ?? '')
+      const floor = effortRank(rule.minEffort)
+      if (Number.isNaN(current) || Number.isNaN(floor) || current < floor) continue
+    }
+    return true
+  }
+  return false
+}

package/src/emission-guard.ts

@@ -0,0 +1,76 @@
+/**
+ * emission-guard —— 审查建议的防噪闸（对照 oh-my-pi AdvisorEmissionGuard，
+ * 其源于生产事故：某会话 advisor 发了 309 次 advise、其中 114 次是
+ * "Stop."——防噪规则必须是代码而不是提示词）。
+ *
+ * 我们对应的问题：巡逻重复发同类 CORRECTION（实测"已咨询过不要重复"
+ * 连续纠偏）、无理由的"停止"式裁决。三道闸：
+ *   1. 归一化：大小写/NFKC/非字母数字折叠——"Stop."/"*STOP*"/"  停止！"
+ *      归一到同一个键；
+ *   2. 内容空短语黑名单：归一化后整体匹配（中英双语）——只说结论不给
+ *      理由的建议没有信息量，按 unclear 处理不打扰；
+ *   3. 会话内精确去重：已注入过的建议再次出现直接丢弃（FIFO 容量上限，
+ *      对齐 OMP 的 4096）。
+ */
+
+/** 会话内建议去重的历史容量（对齐 oh-my-pi） */
+export const ADVICE_DEDUPE_CAPACITY = 4_096
+
+/**
+ * 归一化建议文本（纯函数，可单测）：小写 + NFKC + 非字母数字连续段折叠为
+ * 单空格 + 修剪。\p{L} 覆盖 CJK 表意字符，中文建议同样可归一。
+ */
+export function normalizeAdvice(text: string): string {
+  return text
+    .toLowerCase()
+    .normalize('NFKC')
+    .replace(/[^\p{L}\p{N}]+/gu, ' ')
+    .trim()
+}
+
+/** 归一化后整体匹配的"内容空"短语——只给结论不给理由（黑名单保守收录） */
+const CONTENT_FREE_PHRASES: ReadonlySet<string> = new Set([
+  // 英文（对齐 OMP 观测到的噪声）
+  'stop', 'stop here', 'stop now', 'halt', 'abort',
+  'done', 'task done', 'task complete', 'complete', 'finished', 'ok', 'okay', 'ok done',
+  'no issue', 'no issues', 'no issue continue', 'no concerns', 'no concern',
+  'nothing to add', 'nothing to flag', 'nothing to report', 'no notes',
+  'no further input', 'no further input needed', 'no further input required',
+  'lgtm', 'looks good', 'looks good to me', 'continue', 'keep going',
+  // 中文（patrol 裁决实测可能出现的形式；键必须是归一化后的形态——
+  // 标点已折叠为空格，如"没有问题，继续。"→"没有问题 继续"）
+  '停止', '停止吧', '立即停止', '停下来', '停下', '中止', '终止',
+  '已完成', '已完成任务', '任务完成', '任务已完成', '完成', '结束了',
+  '好的', '没有问题', '无问题', '没有问题 继续', '无需修改', '不需要修改',
+  '继续', '继续保持', '保持现状', '一切正常', '一切正常 继续', '方向正确',
+  '没有建议', '无建议', '没有要补充的', '无补充', '没有意见',
+])
+
+/**
+ * 归一化后的建议是否"内容空"（纯函数）：整体命中黑名单、或归一化后为空。
+ * 部分匹配不算——"停止：await 缺失会丢缓冲写"这类带理由的建议不受影响。
+ */
+export function isContentFreeAdvice(normalized: string): boolean {
+  if (normalized === '') return true
+  return CONTENT_FREE_PHRASES.has(normalized)
+}
+
+/**
+ * 会话内建议去重器（每 agent 一份）。返回一个判定函数：输入归一化后的
+ * 建议键，首次出现返回 true（接受并记录），重复出现返回 false（丢弃）。
+ * FIFO 容量上限防止长会话无界增长。
+ */
+export function createAdviceDeduper(capacity: number = ADVICE_DEDUPE_CAPACITY): (normalized: string) => boolean {
+  const seen = new Set<string>()
+  const order: string[] = []
+  return (normalized: string): boolean => {
+    if (seen.has(normalized)) return false
+    seen.add(normalized)
+    order.push(normalized)
+    if (order.length > capacity) {
+      const oldest = order.shift()
+      if (oldest !== undefined) seen.delete(oldest)
+    }
+    return true
+  }
+}

package/src/gating.ts

@@ -0,0 +1,54 @@
+/**
+ * gating —— 按 agent 动态可见性。每次解析模型请求时把执行路由对照
+ * 黑名单：命中的 agent 在自己的作用域上挂 restrict({deny:['advisor']})
+ * （工具 schema 从该 agent 的提示里消失），未命中的解除限制。
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-tools'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { ADVISOR_TOOL_NAME } from './advisor-prompt.js'
+import { isExecutorBlocked, type Config } from './config.js'
+
+export function registerGating(ctx: Context, getConfig: () => Config, hasReviewer: () => boolean) {
+  const restrictions = new Map<Agent, () => void>()
+
+  const lift = (agent: Agent) => {
+    const dispose = restrictions.get(agent)
+    if (dispose !== undefined) {
+      dispose()
+      restrictions.delete(agent)
+    }
+  }
+
+  const reconcile = (agent: Agent, provider: string | undefined, model: string | undefined, reasoningEffort: string | undefined) => {
+    // 未武装时工具根本没注册——无事可藏，且 restrict() 会拒绝未知名
+    if (!hasReviewer()) {
+      lift(agent)
+      return
+    }
+    const blocked = isExecutorBlocked(getConfig(), provider, model, reasoningEffort)
+    if (blocked && !restrictions.has(agent)) {
+      restrictions.set(agent, agent.ctx.tools.restrict({ deny: [ADVISOR_TOOL_NAME] }))
+    } else if (!blocked) {
+      lift(agent)
+    }
+  }
+
+  const disposeListener = ctx.on('agent/request', async (payload, next) => {
+    const config = await next()
+    try {
+      reconcile(payload.agent, config.provider, config.model, config.reasoningEffort)
+    } catch (error) {
+      // 可见性门控绝不破坏用户的 turn
+      console.error('[dsh-advisor] gating 失败：', error)
+    }
+    return config
+  })
+
+  return () => {
+    disposeListener()
+    for (const dispose of restrictions.values()) dispose()
+    restrictions.clear()
+  }
+}

package/src/history.ts

@@ -0,0 +1,102 @@
+/**
+ * history —— 组装发给审查模型的消息列表。
+ *
+ * 结构（对齐 rpiv-advisor）：
+ *   [工具清单合成消息] + [session.deriveMessages() 的模型可见面]
+ *
+ * 两个工程要点：
+ *   1. deriveMessages() 是 compaction 感知的——压缩摘要按模型实际看到的
+ *      面貌转发，而不是重放压缩前的原始历史；
+ *   2. 工具清单做"按名排序 + 键排序稳定序列化"——多次 advisor 调用间
+ *      字节级一致，命中 DeepSeek 上下文缓存（缓存是整段转发模式的省钱杠杆）。
+ *
+ * 尾部两条规则原样移植 rpiv：剥掉 in-flight 的 advisor() 调用（孤儿
+ * toolCall 会被 provider 拒绝）；保证 user 结尾（部分 provider 拒绝
+ * assistant 结尾）。
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-tools'
+import { createUserMessage, type Message, type UserMessage } from '@deepseek-ai/dsh-llm'
+import { ADVISOR_TOOL_NAME, MSG_USER_TAIL_NUDGE } from './advisor-prompt.js'
+
+// 递归键排序序列化：键序与 V8 插入序无关，同一清单字节级一致
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) {
+    return `[${value.map(v => (v === undefined ? 'null' : stableStringify(v))).join(',')}]`
+  }
+  const obj = value as Record<string, unknown>
+  const entries: string[] = []
+  for (const k of Object.keys(obj).sort()) {
+    const v = obj[k]
+    if (v === undefined) continue
+    entries.push(`${JSON.stringify(k)}:${stableStringify(v)}`)
+  }
+  return `{${entries.join(',')}}`
+}
+
+interface InventoryCache {
+  signature?: string
+  message?: UserMessage
+}
+
+function createUserText(text: string): UserMessage {
+  return createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
+}
+
+function getInventoryMessage(ctx: Context, cache: InventoryCache, scope: Agent): UserMessage | undefined {
+  // 传 agent 作用域：审查者看到的必须是执行模型实际可见的工具面
+  // （黑名单 restrict、agent-scoped 工具都体现在这个 scope 里）
+  const schemas = ctx.tools.schemas(scope)
+  if (schemas.length === 0) return undefined
+  const sorted = [...schemas].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+  const signature = sorted.map(t => t.name).join('|')
+  if (cache.signature === signature && cache.message !== undefined) return cache.message
+  const block = sorted
+    .map(t => `### ${t.name}\n${t.description}\n\nParameters: ${stableStringify(t.parameters)}`)
+    .join('\n\n---\n\n')
+  const message = createUserText(`## Available Executor Tools\n\n${block}`)
+  cache.signature = signature
+  cache.message = message
+  return message
+}
+
+// 剥掉尾部 assistant 消息里 in-flight 的 advisor() toolCall——正是触发本次
+// 咨询的那个调用，还没有配对结果，转发它只会让 provider 拒绝载荷
+function stripInflightAdvisorCall(messages: Message[]): Message[] {
+  if (messages.length === 0) return messages
+  const last = messages[messages.length - 1]
+  if (last === undefined || last.role !== 'assistant') return messages
+  const filtered = last.content.filter(
+    block => !(block.type === 'tool-call' && block.name === ADVISOR_TOOL_NAME),
+  )
+  if (filtered.length === last.content.length) return messages
+  if (filtered.length === 0) return messages.slice(0, -1)
+  return [...messages.slice(0, -1), { ...last, content: filtered } satisfies Message]
+}
+
+// 保证 user 结尾：剥除后尾部可能是 assistant（executor 在调用前输出了思考）
+function ensureUserTail(messages: Message[]): Message[] {
+  if (messages.length === 0) return messages
+  const last = messages[messages.length - 1]
+  if (last === undefined || last.role !== 'assistant') return messages
+  return [...messages, createUserText(MSG_USER_TAIL_NUDGE)]
+}
+
+export function createHistoryBuilder(ctx: Context) {
+  // 每个 agent 一份清单缓存（WeakMap 不阻碍临时 agent 回收）：工具可见面
+  // 是 per-agent 的，作用域不同清单也不同，不能共用同一份缓存
+  const caches = new WeakMap<Agent, InventoryCache>()
+  return function buildAdvisorMessages(agent: Agent): Message[] {
+    const branch = ensureUserTail(stripInflightAdvisorCall(agent.session.deriveMessages()))
+    let cache = caches.get(agent)
+    if (cache === undefined) {
+      cache = {}
+      caches.set(agent, cache)
+    }
+    const inventory = getInventoryMessage(ctx, cache, agent)
+    return inventory === undefined ? branch : [inventory, ...branch]
+  }
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+/**
+ * dsh-advisor —— advisor 策略模式的 DSH 实现（host 半入口）。
+ *
+ * 机制（rpiv-advisor 移植）：
+ *   1. 执行模型拿到零参数 `advisor` 工具；调用即把整段会话分支
+ *      （compaction 感知）+ 工具清单转发给配置的更强审查模型；
+ *   2. 审查模型按 plan / correction / stop signal 三选一契约回文，
+ *      作为工具结果交还执行模型——不进人类可见对话流；
+ *   3. 组合关系：选了审查模型 ⇔ 工具 + 升级守则提示段注册在案
+ *      （未武装的 advisor 零提示词成本）；
+ *   4. agent/request 监听每次解析的执行路由，命中 disabledForModels
+ *      黑名单时对那个 agent 作用域挂 restrict 隐藏工具；
+ *   5. settings 服务就绪后配置接入 'advisor' 命名空间（用户层在
+ *      ~/.dsh/settings.yaml 的 advisor: 段；设置页卡片实时读写）。
+ *
+ * 服务时序：tools/llm/systemPrompt 是硬依赖（inject 导出）；settings 与
+ * commands 是软依赖——用 ctx.inject 等待就绪，apply 时刻 ctx.get
+ * 拿到 undefined 只说明服务尚未激活，不代表不存在。
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-tools'
+import { Config as ConfigSchema, resolveSelection, type Config, type Selection } from './config.js'
+import { registerAdvisorCommand } from './command.js'
+import { registerGating } from './gating.js'
+import { createHistoryBuilder } from './history.js'
+import { registerPatrol } from './patrol.js'
+import { registerAdvisorSection } from './prompt-section.js'
+import { createAdvisorTool } from './tool.js'
+import { wireSettings } from './settings.js'
+
+export const name = 'dsh-advisor'
+export const inject = ['tools', 'llm', 'systemPrompt']
+export { ConfigSchema as Config }
+
+export function apply(ctx: Context, config: Config) {
+  const state: { config: Config, selection: Selection | undefined, settingsInfo: string } = {
+    config,
+    selection: resolveSelection(config),
+    settingsInfo: 'settings 服务未接入',
+  }
+
+  const buildMessages = createHistoryBuilder(ctx)
+  let registration: (() => void) | undefined
+
+  // 武装/解除的总闸：工具与提示段同生同灭
+  const reconcileRegistration = () => {
+    registration?.()
+    registration = undefined
+    if (state.selection === undefined) return
+    const disposeTool = ctx.tools.register(createAdvisorTool(ctx, () => state.selection, buildMessages, () => state.config))
+    const disposeSection = registerAdvisorSection(ctx, state.config)
+    registration = () => {
+      disposeTool()
+      disposeSection()
+    }
+  }
+
+  const disposeGating = registerGating(ctx, () => state.config, () => state.selection !== undefined)
+
+  // 巡逻模式：按间隔自动检查执行是否跑偏并注入纠偏（未武装/被禁用时内部 no-op）
+  const disposePatrol = registerPatrol(ctx, {
+    getConfig: () => state.config,
+    getSelection: () => state.selection,
+    buildMessages,
+  })
+  if (state.config.patrolEnabled !== false) {
+    console.log(`[dsh-advisor] 巡逻模式开启：每 ${state.config.patrolEverySteps ?? 6} 步自动检查（间隔下限 90s）`)
+  }
+
+  // /advisor 命令：commands 服务就绪后注册（fiber 卸载自动清理）
+  ctx.inject(['commands'], (commandsCtx) => {
+    const dispose = registerAdvisorCommand(commandsCtx, () => state.config, () => state.selection, () => state.settingsInfo)
+    if (dispose !== undefined) commandsCtx.effect(() => dispose, 'dsh-advisor: /advisor command')
+  })
+
+  // 设置接入：settings 服务就绪后把 'advisor' 命名空间接进来并活编辑。
+  // 注意传插件根 ctx：rc.6 cordis 的 Service 方法绑定调用者 fiber，注册
+  // effect 挂在 inject 的临时 fiber 上会在 fiber 回收时静默注销命名空间。
+  ctx.inject(['settings'], () => {
+    const wiring = wireSettings(ctx, state, reconcileRegistration)
+    state.settingsInfo = wiring.info
+    reconcileRegistration()
+    console.log(`[dsh-advisor] ${wiring.info}`)
+    // 设置解析后的最终武装状态（apply 时刻的那条"未武装"只是组合层初值）
+    if (state.selection === undefined) {
+      console.log('[dsh-advisor] 设置解析完成：仍未武装（advisor: 段缺 provider/model）——工具不注册')
+    } else {
+      console.log(`[dsh-advisor] 设置解析完成：已武装 ${state.selection.provider}/${state.selection.model}${state.selection.effort === undefined ? '' : ` (${state.selection.effort})`}——advisor 工具已注册`)
+    }
+  })
+
+  reconcileRegistration()
+
+  if (state.selection === undefined) {
+    console.log('[dsh-advisor] 未武装：未配置审查模型（provider+model），advisor 工具不注册')
+  } else {
+    console.log(`[dsh-advisor] 已武装：${state.selection.provider}/${state.selection.model}${state.selection.effort === undefined ? '' : ` (${state.selection.effort})`}`)
+  }
+
+  ctx.effect(() => () => {
+    registration?.()
+    disposeGating()
+    disposePatrol()
+  })
+}