dsh-advisor-plugin 0.2.1

package/lib/gating.js

@@ -0,0 +1,48 @@
+/**
+ * gating —— 按 agent 动态可见性。每次解析模型请求时把执行路由对照
+ * 黑名单：命中的 agent 在自己的作用域上挂 restrict({deny:['advisor']})
+ * （工具 schema 从该 agent 的提示里消失），未命中的解除限制。
+ */
+import { ADVISOR_TOOL_NAME } from './advisor-prompt.js';
+import { isExecutorBlocked } from './config.js';
+export function registerGating(ctx, getConfig, hasReviewer) {
+    const restrictions = new Map();
+    const lift = (agent) => {
+        const dispose = restrictions.get(agent);
+        if (dispose !== undefined) {
+            dispose();
+            restrictions.delete(agent);
+        }
+    };
+    const reconcile = (agent, provider, model, reasoningEffort) => {
+        // 未武装时工具根本没注册——无事可藏，且 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/lib/history.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 Message } from '@deepseek-ai/dsh-llm';
+export declare function createHistoryBuilder(ctx: Context): (agent: Agent) => Message[];

package/lib/history.js

@@ -0,0 +1,95 @@
+/**
+ * history —— 组装发给审查模型的消息列表。
+ *
+ * 结构（对齐 rpiv-advisor）：
+ *   [工具清单合成消息] + [session.deriveMessages() 的模型可见面]
+ *
+ * 两个工程要点：
+ *   1. deriveMessages() 是 compaction 感知的——压缩摘要按模型实际看到的
+ *      面貌转发，而不是重放压缩前的原始历史；
+ *   2. 工具清单做"按名排序 + 键排序稳定序列化"——多次 advisor 调用间
+ *      字节级一致，命中 DeepSeek 上下文缓存（缓存是整段转发模式的省钱杠杆）。
+ *
+ * 尾部两条规则原样移植 rpiv：剥掉 in-flight 的 advisor() 调用（孤儿
+ * toolCall 会被 provider 拒绝）；保证 user 结尾（部分 provider 拒绝
+ * assistant 结尾）。
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { ADVISOR_TOOL_NAME, MSG_USER_TAIL_NUDGE } from './advisor-prompt.js';
+// 递归键排序序列化：键序与 V8 插入序无关，同一清单字节级一致
+function stableStringify(value) {
+    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;
+    const entries = [];
+    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(',')}}`;
+}
+function createUserText(text) {
+    return createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } });
+}
+function getInventoryMessage(ctx, cache, scope) {
+    // 传 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) {
+    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 }];
+}
+// 保证 user 结尾：剥除后尾部可能是 assistant（executor 在调用前输出了思考）
+function ensureUserTail(messages) {
+    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) {
+    // 每个 agent 一份清单缓存（WeakMap 不阻碍临时 agent 回收）：工具可见面
+    // 是 per-agent 的，作用域不同清单也不同，不能共用同一份缓存
+    const caches = new WeakMap();
+    return function buildAdvisorMessages(agent) {
+        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/lib/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 { Config as ConfigSchema, type Config } from './config.js';
+export declare const name = "dsh-advisor";
+export declare const inject: string[];
+export { ConfigSchema as Config };
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,96 @@
+/**
+ * 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 { Config as ConfigSchema, resolveSelection } 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, config) {
+    const state = {
+        config,
+        selection: resolveSelection(config),
+        settingsInfo: 'settings 服务未接入',
+    };
+    const buildMessages = createHistoryBuilder(ctx);
+    let registration;
+    // 武装/解除的总闸：工具与提示段同生同灭
+    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();
+    });
+}

package/lib/llm-call.d.ts

@@ -0,0 +1,69 @@
+/**
+ * llm-call —— 审查模型侧调用，走 ctx.llm.stream（复用 DSH 已注册的
+ * provider 路由与凭据——审查模型就是"DSH 已经配置好的模型"之一）。
+ *
+ * 聚合 text-delta、捕获 usage、把 finish 分块路由成类型化结果；
+ * 正常停止但无正文时恰好重试一次（aborted / error 短路不重试）。
+ *
+ * 调查工具（对照 oh-my-pi：advisor 默认授予 read/grep/glob，建议前先
+ * 亲自查证）：传入 investigateRoot 时走 agentic 循环——审查模型可用
+ * 两个只读工具（工作区内正则搜索 / 读文件）核实事实后再出最终裁决。
+ * 工具在本地用 node:fs 实现（只读、锁定在会话工作区子树内、结果截断），
+ * 不经过宿主工具运行时（无审批/沙箱副作用，代价是只有这两个只读原语）。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Message, ToolCallBlock, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { Selection } from './config.js';
+export type AdvisorOutcome = {
+    ok: true;
+    text: string;
+    usage: TokenUsage | undefined;
+    finishKind: string;
+} | {
+    ok: false;
+    errorMessage: string;
+};
+export declare function isReviewerCallActive(): boolean;
+/**
+ * 剥离审查模型对执行模型"最后一句话"的回显。实测部分审查模型（经由
+ * 代理网关）会在正式建议前先复读执行模型调用 advisor 前的可见文本
+ * （如"好的，马上调用 advisor 咨询！"）——对执行模型毫无信息量。
+ * 仅当 guidance 的首个非空行与转发消息里最后一条 assistant 文本完全
+ * 一致时剥掉该行，误伤面最小。
+ */
+export declare function stripExecutorEcho(guidance: string, messages: readonly Message[]): string;
+/**
+ * 审查侧调用入口。
+ * @param investigateRoot 提供时启用调查循环：审查模型可用只读工具在工作区
+ * 内核实后再出最终裁决（对照 oh-my-pi 的 advisor 调查授权）
+ */
+export declare function callReviewer(ctx: Context, selection: Selection, systemPrompt: string, messages: Message[], signal: AbortSignal | undefined, investigateRoot?: string, sessionId?: SessionId): Promise<AdvisorOutcome>;
+/** 是否"模型不支持该推理档位"类错误（纯函数，可单测） */
+export declare function isUnsupportedEffortError(errorMessage: string | undefined): boolean;
+/** 是否"上下文窗口溢出"类错误（纯函数，可单测） */
+export declare function isContextOverflowError(errorMessage: string | undefined): boolean;
+/**
+ * 溢出时的截断转发（纯函数，可单测）：保留首条（工具清单合成消息）+
+ * 尾部约 1/4 的近期消息，并在衔接处插入一条截断说明。巡逻/咨询的裁决
+ * 主要依赖近期行为，截断后仍足以判断方向。
+ *
+ * 配对安全：消息边界截断可能把 tool_use 切在丢弃区、把配对的
+ * tool_result 留在保留区头部——孤儿 tool_result 会被 Claude/OpenAI 类
+ * provider 整包拒绝（实测 `unexpected tool_use_id ... must have a
+ * corresponding tool_use block`）。从保留区头部起剥掉含 tool-result 块
+ * 的 user 消息，直到首条不再引用被切断的调用。
+ */
+export declare function truncateForReviewer(messages: readonly Message[]): Message[];
+/** 简易 glob → RegExp（* 不跨目录、** 跨目录、双星号加斜杠匹配零个或多个目录、? 单字符） */
+export declare function globToRegExp(glob: string): RegExp;
+/**
+ * 把目标路径解析进工作区子树（纯函数，可单测）：越界（../ 或绝对路径指向
+ * 区外）返回 undefined——审查者的读取面被硬限制在会话工作区内。
+ */
+export declare function resolveWithinRoot(root: string, target: string): string | undefined;
+/** 调查工具执行器（只读、限工作区、结果截断） */
+export declare function createInvestigateExecutor(root: string): (call: ToolCallBlock) => Promise<{
+    content: string;
+    isError: boolean;
+}>;