@y9931666/dsh-plugin-roundtable 1.0.0-rc.2

package/lib/types/kb-digest.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 知识库摘要缓存（C2）：让主持人不必为同一个文件重复读两遍。
+ *
+ * 分工刻意划清——本模块**不调用任何 LLM**，只做三件事：
+ *   1. 失效判定：`path + size + mtimeMs` 任一变化即失效（宿主
+ *      `listKbDirectory()` 本来就在 stat 每个条目，比对不额外产生 IO）；
+ *   2. 合并与淘汰：同 path 覆盖；超条数 / 超长度按最旧淘汰；
+ *   3. 把缓存条目与磁盘现状比对，供 `roundtable_status` 直接展示
+ *      "哪条还能用、哪条得重读"。
+ *
+ * digest 正文由主持人读过文件后写下（`roundtable_kb_digest` 工具）。
+ * 缓存**不参与预算计数**：它不消耗模型 token。
+ *
+ * @module dsh-plugin-roundtable/kb-digest
+ */
+import type { KbDigestEntry } from './types.ts';
+/** 缓存条目数上限；超出按 `ts` 最旧淘汰。 */
+export declare const KB_DIGEST_MAX_ENTRIES = 50;
+/** 单条摘要字符上限；超出截断（缓存是"要点"，不是全文副本）。 */
+export declare const KB_DIGEST_MAX_CHARS = 2000;
+/** 一条缓存条目，外加它相对磁盘现状是否仍然有效。 */
+export interface KbDigestStatusEntry extends KbDigestEntry {
+    /** true = 失效键未变，摘要可直接使用；false = 文件变了/读不到，必须重读。 */
+    valid: boolean;
+}
+/**
+ * 失效判定（纯函数）：失效键完全一致才算命中。
+ *
+ * `current === undefined`（文件已不存在 / 读不到）一律视为失效——宁可让
+ * 主持人多读一次，也不要拿一份可能过期的摘要去回答专家。
+ */
+export declare function digestIsFresh(entry: Pick<KbDigestEntry, 'size' | 'mtimeMs'>, current: {
+    size: number;
+    mtimeMs: number;
+} | undefined): boolean;
+/**
+ * 合并一条摘要（纯函数）：同 `path` 覆盖，其余按 `ts` 从新到旧保留，
+ * 超出 `maxEntries` 的部分淘汰最旧。返回新数组，不改动入参。
+ */
+export declare function mergeKbDigestEntry(entries: readonly KbDigestEntry[], next: KbDigestEntry, maxEntries?: number): KbDigestEntry[];
+/**
+ * 用磁盘现状标注每条缓存的 `valid`。
+ *
+ * 每条一次 `stat`：条目上限是 {@link KB_DIGEST_MAX_ENTRIES}（50），
+ * 而且只在 `roundtable_status` 里调用，成本可忽略。
+ */
+export declare function evaluateKbDigests(entries: readonly KbDigestEntry[]): Promise<KbDigestStatusEntry[]>;

package/lib/types/members.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Expert-node subagent lifecycle: spawn one continuable child per node,
+ * deliver messages into its next FIFO turn, interrupt it, and observe its
+ * live activity. Mirrors the AgentTeams member pattern against the
+ * 0.1.2-rc.1 subagent seam.
+ *
+ * Node personas are the《全局协作总纲》plus node-specific rules; the charter
+ * is injected so every node carries the four-section protocol.
+ * @module dsh-plugin-roundtable/members
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ToolRestriction } from '@deepseek-ai/dsh-tools';
+import type { Meeting, MeetingNode, SkillDelivery } from './types.ts';
+import { CAPTAIN_KEY } from './types.ts';
+import { nodePersona, nodeWelcome } from './prompt.ts';
+import type { ExpertLimits, NodeSkillContext } from './prompt.ts';
+/**
+ * 本插件自己声明的 `MessageSourceMap` 条目。
+ *
+ * 0.1.5-rc.3 的宿主有一个 catch-all 的 `plugin` kind
+ * （`{ kind: 'plugin', plugin: string }`），本插件曾用它标注注入给主持人的
+ * steering 内容。**0.2.0-rc.2 移除了它**：`@deepseek-ai/dsh-llm` 的
+ * `MessageSourceMap` 只保留 `user` / `model` / `tool` / `system-prompt`，
+ * 其余一律由**生产者在自己的模块里声明**——宿主的 `tool-registry`、
+ * `ptc-mode`、`agent-message`、`subagent-settled` 都是这么做的。原文注释写得很
+ * 直白："there is no shared catch-all `plugin` kind"。
+ *
+ * 所以这里按同一模式补上本插件的 kind，而不是退化成匿名的 `user` 消息：
+ * 转录消费者据此把"插件注入的提示"与"用户自己说的话"分开显示。
+ * 运行时无影响——`kind` 是归属标签，未知值一律 fall through。
+ */
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** 圆桌会议插件注入的 steering / 系统侧提示。 */
+        roundtable: {
+            kind: 'roundtable';
+            /** 生产者标识，便于在转录里追溯来源。 */
+            plugin: string;
+        };
+    }
+}
+/** Runtime knobs for node spawning, resolved from plugin config. */
+export interface MemberRuntimeConfig {
+    /** Registered `ctx.subagents` provider name (must support continuable + persona). */
+    provider: string;
+    /** Node delegation depth cap (1 by default: experts may not spawn teams of their own). */
+    maxDepth?: number;
+}
+/** The node's tool restriction: deny captain-only tools, and — in direct
+ *  skill-delivery mode — narrow the surface to the explicit expert allowlist
+ *  so the host's `skill` loader is reachable from a node. */
+export declare function nodeToolRestriction(skillDelivery?: SkillDelivery): ToolRestriction;
+export { nodePersona, nodeWelcome };
+export type { ExpertLimits, NodeSkillContext };
+/**
+ * Spawn one node as a durable continuable subagent of the captain and fill
+ * `node.id` with its child session id. On failure nothing is persisted.
+ */
+export declare function spawnNode(ctx: Context, config: MemberRuntimeConfig, meeting: Meeting, node: MeetingNode, captain: Agent, stateDir: string, signal: AbortSignal, limits?: ExpertLimits, skill?: NodeSkillContext): Promise<void>;
+/**
+ * Deliver one message to a node as its next FIFO turn. Best effort: a failure
+ * is logged and reported as `false` so the caller can decide.
+ */
+export declare function deliverToNode(ctx: Context, captain: Agent, childId: string, text: string, signal: AbortSignal): Promise<boolean>;
+/** Request cancellation of one live node's current turn (fire and return). */
+export declare function interruptNode(ctx: Context, captain: Agent, childId: string): void;
+/**
+ * Interrupt one node **without** needing a live captain Agent.
+ *
+ * `ctx.subagents.interrupt` needs an ancestor Agent as its authority, so it is
+ * useless on paths that only hold session ids (the RPC surface, or a captain
+ * whose Agent is offline). The host's remote face is explicitly documented as
+ * "what keeps a live child interruptible while its parent Agent is offline".
+ *
+ * @returns true when the host accepted the request.
+ */
+export declare function interruptNodeByParent(ctx: Context, childId: string, parentSessionId: string): boolean;
+/** Steer a live message into the captain at its nearest model boundary (best effort). */
+export declare function steerCaptain(captain: Agent, text: string): boolean;
+/** Resolve the real driver activity for durable node ids. */
+export declare function nodeActivity(ctx: Context, nodes: readonly MeetingNode[]): Map<string, 'running' | 'idle' | 'ready'>;
+export { CAPTAIN_KEY };

package/lib/types/node-events.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 专家子代理的生命周期接入（第 1 批）。
+ *
+ * 背景（来自真实会议数据）：专家的产出**只在它主动调用 `roundtable_speak`
+ * 的那一刻**才落盘。v0-2-36 那场评审里，一位红队专家完成了大量取证，却在
+ * speak 之前进程中断 —— 观点全丢，`review.json` 永久停在 `reviewing`、
+ * `viewpoints` 为空。同时 9 条被拉起的路由里 4 条 0 产出，而插件只留下一个
+ * `removed` 墓碑，没有任何失败原因，只能靠主持人用自然语言反复催办。
+ *
+ * 宿主其实早就把两件事递到手上：
+ * - `subagent/end` 带 `lastAssistantMessage`，且官方说明 **可续聊子代理的
+ *   每一个 activation epoch 都会发这个事件** —— 于是产出能在 `speak` 之外被
+ *   自动捕获，中途中断也不会全丢；
+ * - 同一事件带 `stopReason`（`error` / `max-tokens` / `aborted` …），基础设施
+ *   级失败时 `lastAssistantMessage` 为空；而 `agent/request-error` 进一步带
+ *   `provider` 与 `failure: LlmFailure`（含 HTTP `status`），于是"为什么拉不
+ *   起来"（额度、鉴权、模型名写错）可以被写成 `node.lastError`。
+ *
+ * 索引是**进程内**的：childId → (stateRoot, meetingId)。冷启动后的旧节点无法
+ * 归属，这是刻意的 —— 宁可漏捕获，也不要把别的会话的文本写进会议记录。
+ *
+ * @module dsh-plugin-roundtable/node-events
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { MeetingNode } from './types.ts';
+/** Where one node's meeting lives on disk. */
+export interface NodeLocation {
+    stateRoot: string;
+    meetingId: string;
+}
+/** Remember which meeting a freshly spawned node belongs to. */
+export declare function registerNodeChild(childId: string, location: NodeLocation): void;
+/** Drop one node's index entry (node removed, or failed spawn rolled back). */
+export declare function forgetNodeChild(childId: string): void;
+/** Look up a node's meeting by its child session id. */
+export declare function locateNodeChild(childId: string): NodeLocation | undefined;
+/** Test-only: clear the process-local index. */
+export declare function __resetNodeIndexForTests(): void;
+/** Flatten the text blocks of one assistant output (empty when there is none). */
+export declare function blocksToText(blocks: readonly ContentBlock[] | undefined): string;
+/** What one settled child run means for its node. */
+export interface NodeEndOutcome {
+    /** Captured output; empty string means the child produced nothing usable. */
+    text: string;
+    /** Readable reason, written to `node.lastError` when `text` is empty. */
+    note: string;
+}
+/**
+ * Decide what a settled child run contributes to its meeting.
+ *
+ * A run that ends `completed` but carries no text is *not* a hard failure (the
+ * expert may have only acknowledged), so it gets its own wording — the point is
+ * to never leave the captain guessing between "still working" and "died".
+ */
+export declare function describeNodeEnd(info: {
+    readonly stopReason?: string;
+    readonly lastAssistantMessage?: readonly ContentBlock[];
+}): NodeEndOutcome;
+/** One-line readable description of a provider request failure. */
+export declare function describeRequestFailure(provider: string, failure: {
+    message?: string;
+    code?: string;
+    status?: number;
+} | undefined): string;
+/**
+ * Subscribe the two host events that make expert output and expert failure
+ * visible.
+ *
+ * Deliberately non-invasive: `subagent/end` is a plain emit, and the
+ * `agent/request-error` waterfall listener always delegates through `next()` so
+ * the host's own retry/recovery policy is untouched — this plugin only observes.
+ */
+export declare function attachNodeEvents(ctx: Context): void;
+/** Node liveness, refined by asking the host's own subagent tree. */
+export type NodeLiveness = 'running' | 'idle' | 'ready' | 'missing';
+/**
+ * Reconcile node liveness against the host's real subagent tree.
+ *
+ * `ctx.agents.get(id)` only knows **live** drivers, so a node whose process is
+ * gone looks exactly like one that is merely between turns — both report
+ * `ready`, and the captain cannot tell "待唤醒" from "已经没了". Asking the
+ * durable catalog separates them: an id the host still lists is a cold-but-real
+ * child, an id it no longer knows is `missing` — which is precisely the old
+ * "把消息投进死节点、静默丢一整轮" failure seen in the meeting records.
+ *
+ * Runs one listing per meeting (not per node) and degrades to the previous
+ * semantics when the catalog is unavailable.
+ */
+export declare function reconcileNodeLiveness(ctx: Context, captainSessionId: string, nodes: readonly MeetingNode[]): Promise<Map<string, NodeLiveness>>;

package/lib/types/plan.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 会议设置确认卡片（R1）：草案数据结构 + 卡片 Markdown 渲染 + 答案解析。
+ *
+ * 原生 `ctx.userQuestions` 没有表单能力（只有选项列表 + 一个自由文本
+ * `custom`），所以"可改全部"是通过 `custom` 自由文本 + 回流重建实现的，
+ * 而不是富表单。本模块只负责把一份草案渲染成**可读**的 Markdown，并把
+ * 用户的回答解析成三态：approved / revise / unavailable。
+ *
+ * @module dsh-plugin-roundtable/plan
+ */
+import type { SkillDelivery } from './types.ts';
+/** skill 的两种传递方式（D5）。单一来源：types.ts。 */
+export type { SkillDelivery };
+/** 卡片上"按此创建"选项的固定标签；`intent.approve` 必须与它逐字一致。 */
+export declare const PLAN_APPROVE_LABEL = "\u6309\u6B64\u521B\u5EFA";
+/** 卡片上的次选项：用户想改点什么。 */
+export declare const PLAN_REVISE_LABEL = "\u6211\u8981\u4FEE\u6539";
+/**
+ * 一张设置卡片所描述的会议草案（尚未创建）。
+ *
+ * 字段与 `roundtable_create` 的入参一一对应，外加 `skills` / `skillDelivery`，
+ * 这样用户确认后主持人可以**原样**按草案创建会议，不再自行拍参数。
+ */
+export interface MeetingDraft {
+    /** 会议名称（同时作为会议 id 的稳定来源）。 */
+    name: string;
+    /** 会议背景与核心目标（总纲第一节）。 */
+    goal: string;
+    /** 协作模式。 */
+    mode: 'orchestrated' | 'egalitarian' | 'redteam';
+    /** 轮数上限，超限闭麦。 */
+    maxRounds: number;
+    /** Token 预算上限，超限闭麦。 */
+    maxTokens: number;
+    /** 知识库目录（可空）：主持人按需读取其中文件转交专家。 */
+    kbPath: string;
+    /** 本次会议选中的 skill 名称清单（可为空）。 */
+    skills: string[];
+    /** skill 传递方式：relay=主持人中转；direct=专家自行调用。 */
+    skillDelivery: SkillDelivery;
+}
+/** 卡片选项的两态解析结果。 */
+export type PlanConfirmation = {
+    kind: 'approved';
+} | {
+    kind: 'revise';
+    note: string;
+}
+/** 服务缺失或用户没给任何选择：主持人应把它当作"再确认一次"。 */
+ | {
+    kind: 'unavailable';
+    note: string;
+};
+/** 清单里的一条 skill：只要名字与描述这两个字段。 */
+export interface SkillListEntry {
+    readonly name: string;
+    readonly description?: string;
+}
+/**
+ * 把一份草案渲染成卡片正文（Markdown）。
+ *
+ * 这里是"让用户看懂将要创建什么"的唯一位置：每一项参数都显示当前值，
+ * 专家逐个列出 key / 角色 / 路由，并把**当前可选**的 skill 清单也列出来
+ * （用户要在「我要修改」的自由文本里增删 skill，就得先看得到名字）。
+ * 禁止在其中塞伪交互说明。
+ */
+export declare function formatMeetingDraft(draft: MeetingDraft, experts: readonly {
+    key: string;
+    role?: string;
+    provider?: string;
+    model?: string;
+}[], options?: {
+    revised?: boolean;
+    availableSkills?: readonly SkillListEntry[];
+}): string;
+/**
+ * 解析用户的卡片回答。
+ *
+ * 协议与 `intent.kind: 'plan-review'` 的语义一致：`selected` 含
+ * `PLAN_APPROVE_LABEL` 即视为批准，其余选项（或只有 custom 文本）视为
+ * 要求修改。不识别 intent 的 UI 会退回普通选项列表，答复编码完全相同。
+ */
+export declare function resolvePlanConfirmation(answer: {
+    selected: string[];
+    custom?: string;
+} | undefined, approveLabel?: string): PlanConfirmation;

package/lib/types/preferences.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 运行时偏好的持久化与净化（宿主设置模型重构后的自持久化实现）。
+ *
+ * ## 为什么不再是宿主的 settings 命名空间
+ *
+ * 0.1.5-rc.3 时代，宿主 `settings` 服务提供
+ * `settings.register(ns, schema, { base })`，返回一个 `SettingsScope`，自带
+ * `get()` / `update()` / `watch()` —— 插件因此可以把「运行时可改、改完立即
+ * 生效」的偏好寄存在宿主的 `settings.yaml` 里。
+ *
+ * 0.2.0-rc.2 把该服务重构为 `SettingsForms`：它把 **profile 配置投影成表单**
+ * （`configure` / `describe` / `update` / `replace` / `mutate`），插件不再有
+ * 「注册自己的命名空间」这个动作，`SettingsScope` 类型也随之消失。新模型里
+ * 插件的可配置面是它自己的 Cordis `Config`，而写 Config 会触发 Loader 重载
+ * 该 entry —— 对「改一个偏好就重启整场会议」来说太重了。
+ *
+ * 因此本插件改为自持久化：偏好落在 DSH home 下的
+ * `roundtable/preferences.json`，读写都在插件内部完成，不再依赖宿主设置服务，
+ * 也就不会因为该服务的下一次重构而再次失效。
+ *
+ * ## 三条铁律（与 state.ts 同源）
+ *
+ * 1. **读失败绝不抛给调用方**：偏好文件损坏或被手改成非法 JSON，一律退回默认
+ *    值并留一条日志。偏好是观察性配置，它不能让整场会议从界面上消失。
+ * 2. **写入必须原子**：复用 {@link writeTextAtomic}（宿主 `writeFileAtomic`
+ *    优先、本地 tmp+rename 兜底），避免半截 JSON 落盘。
+ * 3. **非法字段一律净化**：schemastery 不校验数组条目的 required 字段，
+ *    条目级校验只能手写 —— 与既有净化契约一致。
+ *
+ * @module dsh-plugin-roundtable/preferences
+ */
+import type { RolePreset, RoleSquad } from './types.ts';
+/**
+ * 解析 DeepSeek Harness home。
+ *
+ * 与宿主 `@deepseek-ai/dsh-home-paths` 的 `resolveDshHome` 优先级对齐：
+ * `configured` > `$DSH_HOME` > `~/.dsh`。只有第一级做不到 —— 它是宿主进程内部
+ * 传入的显式覆盖，插件拿不到 —— 但环境变量与默认值这两级完全一致，因此在
+ * 任何正常启动的宿主里都会落到同一个目录。
+ *
+ * 刻意**不**静态 import `@deepseek-ai/dsh-home-paths`：那会把它变成加载门禁，
+ * 而本模块只是要一个路径（见 harness-compat 的铁律 #1）。
+ */
+export declare function dshHomeDir(): string;
+/** 偏好文件的绝对路径（DSH home 下的 `roundtable/preferences.json`）。 */
+export declare function preferencesFilePath(): string;
+/** Wire shape of the runtime preferences. */
+export interface RoundTablePreferences {
+    readonly defaultMode: 'orchestrated' | 'egalitarian' | 'redteam';
+    readonly maxRounds: number;
+    readonly maxTokens: number;
+    /** 互通开关：true = 显示所有圆桌会议；false = 仅显示当前对话开启的会议。 */
+    readonly showAllMeetings: boolean;
+    /** 专家每轮输出 token 上限（模型请求 max_tokens），0 = 不限制。 */
+    readonly expertMaxTokens: number;
+    /** 专家每轮最多提几条意见，0 = 不限制。 */
+    readonly expertMaxOpinions: number;
+    /** E1/E4 反馈：会议结束后是否询问轻量反馈；false = 永久关闭（设置页可改）。 */
+    readonly feedbackEnabled: boolean;
+    /** R2.2/D5：skill 传递方式（relay=主持人中转；direct=专家自行调用）。 */
+    readonly skillDelivery: 'relay' | 'direct';
+    /** 右栏面板可见性（R3）：被列出的面板在拓扑页隐藏；空 = 全部显示。 */
+    readonly hiddenPanels: string[];
+    /** A1：画布图例是否已被用户关闭（默认 false = 显示）。 */
+    readonly legendHidden: boolean;
+    /** B3：用户自建角色预设（全局偏好；不预置任何内置角色）。 */
+    readonly rolePresets: RolePreset[];
+    /** B3+：用户自建阵容预设（一次套用多位专家；同样不预置）。 */
+    readonly squads: RoleSquad[];
+}
+/** 没有任何持久化数据时的偏好。`defaultMode` 由调用方按插件 Config 覆盖。 */
+export declare function defaultPreferences(defaultMode: RoundTablePreferences['defaultMode']): RoundTablePreferences;
+/** 右栏可隐藏的面板 id（客户端与服务端共用的稳定标识）。 */
+export declare const ROUNDTABLE_PANELS: readonly string[];
+/** 把任意输入收敛成合法的隐藏面板清单（未知 id 丢弃，去重）。 */
+export declare function sanitizeHiddenPanels(value: unknown): string[];
+/** 预设条目的硬上限（客户端与服务端共用；服务端截断，客户端提前拦截）。 */
+export declare const ROLE_PRESET_MAX = 50;
+/**
+ * 把任意输入收敛成合法的角色预设清单（B3）。
+ *
+ * schemastery 的 `z.object` 在 resolve 阶段**不校验缺失的 required 字段**
+ * （`s({ rolePresets: [{ id: 'a' }] })` 直接通过），所以条目级校验不能依赖
+ * schema，必须在这里手写 —— 与 {@link sanitizeHiddenPanels} 同一套路：
+ *   - `name` 与 `role` 非空是硬要求，二者缺一即丢弃该条；
+ *   - `id` 为空或与前面的条目重复时**重新分配**（保数据，不静默丢条目）；
+ *   - `provider`/`model` 必须成对出现，否则整体视为"继承主持人"；
+ *   - 单字段超长截断，总条数超 {@link ROLE_PRESET_MAX} 截断。
+ */
+export declare function sanitizeRolePresets(value: unknown): RolePreset[];
+/** 阵容预设的硬上限（客户端与服务端共用；服务端截断，客户端提前拦截）。 */
+export declare const SQUAD_MAX = 20;
+export declare const SQUAD_MEMBER_MAX = 8;
+/**
+ * 把任意输入收敛成合法的阵容预设清单（B3+）。
+ *
+ * 与 {@link sanitizeRolePresets} 同一套路（schemastery 不校验 required，
+ * 条目级校验只能手写），差别只有两条：
+ *   - 成员的**去重键是 key**（同一阵容里不能有两位同名专家）；
+ *   - **没有任何成员的阵容被丢弃** —— 否则设置页会出现一条点了没反应的条目。
+ *
+ * 兼容性（这一条就是"结构变更必须自带迁移"的落地方式）：`squads` 是
+ * **可选新增字段**，旧偏好对象里没有它时读到的是 `[]`，读侧归一化、
+ * 只有用户真的保存时才写回，因此不需要版本号迁移，也不可能损坏已有数据。
+ */
+export declare function sanitizeSquads(value: unknown): RoleSquad[];
+/**
+ * 把 `layer` 叠在 `base` 之上并逐字段净化。
+ *
+ * 语义与宿主 `SettingsScope.update(patch)` + `get()` 的组合一致：**只覆盖
+ * `layer` 中出现的字段**，其余沿用 `base`。因此同一个函数同时服务于两条路径：
+ *   - 读盘：`normalizePreferences(fileContent, defaults)` —— 旧文件缺新字段时补默认；
+ *   - 写入：`normalizePreferences(patch, current)` —— 设置页的部分更新。
+ */
+export declare function normalizePreferences(layer: unknown, base: RoundTablePreferences): RoundTablePreferences;
+/** 偏好读取面：`get()` 永远返回一个完整、合法的对象。 */
+export interface PreferenceStore {
+    /** 当前生效的偏好（同步读，永远完整）。 */
+    get(): RoundTablePreferences;
+    /** 叠加一次部分更新，落盘后返回新值；写失败只记日志，不抛给调用方。 */
+    update(patch: unknown): Promise<RoundTablePreferences>;
+    /** 订阅变更（返回退订函数）；回调抛错不影响其它订阅者。 */
+    watch(listener: (value: RoundTablePreferences) => void): () => void;
+    /** 等待首次读盘完成（测试与诊断用）。 */
+    ready(): Promise<void>;
+}
+/** 建一个偏好存储所需的最小依赖。 */
+export interface PreferenceStoreOptions {
+    /** 基准偏好（通常来自插件 Config 的 `defaultMode` 与内置默认值）。 */
+    base: RoundTablePreferences;
+    /** 覆盖偏好文件路径（测试用）。 */
+    file?: string;
+    /** 诊断日志；缺省静默 —— 偏好问题不该刷屏。 */
+    log?: (message: string, error?: unknown) => void;
+}
+/**
+ * 创建偏好存储。
+ *
+ * 读盘是**惰性且异步**的（构造后立刻开始），因此 `get()` 在首次读盘完成前
+ * 返回基准值而不是阻塞宿主启动 —— 这与宿主设置服务的可用性无关，也是它比
+ * `ctx.inject(['settings'])` 更稳的地方：没有可选能力可缺。
+ */
+export declare function createPreferenceStore(options: PreferenceStoreOptions): PreferenceStore;

package/lib/types/prompt.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 提示词资产（第 4 步：各 AI 之间的提示词与限定）。
+ *
+ * 本模块**只生成纯文本**，零运行时依赖（仅 type-only import）。这样
+ * `test/prompt-budget.test.mjs` 可以直接 import 它做体积护栏 —— 提示词
+ * 会随时间自然膨胀，护栏是唯一能阻止它涨回去的手段。
+ *
+ * 三条设计原则（压缩而不丢信息）：
+ *   1. **常驻的极简**：usage 段只讲"什么时候用哪件工具"，操作规程留在各
+ *      工具自己的 description 里（两处都常驻，所以同一规则绝不写两遍）；
+ *   2. **按需的详尽**：细节在真正用到它的那一刻才进上下文；
+ *   3. **跨边界的结构化**：转发用引用（`R{n}[{speaker}]`）而不是复述全文。
+ *
+ * @module dsh-plugin-roundtable/prompt
+ */
+import type { Meeting, MeetingNode, SkillDelivery } from './types.ts';
+/** 任务信封（主持人 → 专家）：固定四段，可机械转发，不粘贴全文。 */
+export declare const TASK_ENVELOPE = "[TASK R{\u8F6E} \u2192 {key}] \u76EE\u6807\uFF5C\u8F93\u5165\uFF08\u5F15\u7528 R{n}[{\u53D1\u8A00\u4EBA}] \u6216\u6587\u4EF6\u8DEF\u5F84\uFF09\uFF5C\u7EA6\u675F\uFF5C\u671F\u671B\u4EA7\u51FA";
+/** 报告信封（专家 → 网关/主持人）：`[核心产出]` 就是网关抓取的段落。 */
+export declare const REPORT_ENVELOPE = "[REPORT R{\u8F6E} {key}] \u7ED3\u8BBA\uFF08\u22643 \u6761\uFF09\uFF5C\u8BC1\u636E\uFF5C\u5F85\u51B3\u7B56";
+/**
+ * 主持人（DeepSeek 本体）的常驻 usage 段。
+ *
+ * **它每一次请求都要付费**，包括完全不开会的日常对话。因此这里只保留
+ * "何时触发、按什么顺序、红线在哪"，把流程细节交给各工具的 description。
+ * 也**不再逐个列出工具名**：工具 schema 本来就在请求里，列一遍是纯冗余。
+ */
+export declare function usageSectionText(): string;
+/** Per-expert answer limits resolved from settings at spawn time. */
+export interface ExpertLimits {
+    /** Per-request output token cap (model max_tokens); 0 = unlimited. */
+    maxTokens?: number;
+    /** Max opinions per round (prompt-level constraint); 0 = unlimited. */
+    maxOpinions?: number;
+}
+/** 节点 persona 需要的 skill 上下文（R2：会议选中的 skill 与传递方式）。 */
+export interface NodeSkillContext {
+    /** 选择随 persona 注入的 skill 名称（缺省取 meeting.skills）。 */
+    names?: readonly string[];
+    /** 缺省取 meeting.skillDelivery。 */
+    delivery?: SkillDelivery;
+    /** host 是否真的注册了 `skill` 工具（未注册时不得让专家去调它）。 */
+    skillToolAvailable?: boolean;
+}
+/** The node's system prompt (persona): the charter plus node working rules.
+ *
+ *  与 charter 严格分工：**总纲写共同红线（格式、编造、拍板），这里只写
+ *  "你这个节点具体怎么做"**。同一约束绝不在这两处各写一遍 —— persona 会
+ *  跟着专家的每一次请求付费。 */
+export declare function nodePersona(meeting: Meeting, node: MeetingNode, stateDir: string, limits?: ExpertLimits, skill?: NodeSkillContext): string;
+/** The initial user message delivered when the node is created. */
+export declare function nodeWelcome(meeting: Meeting, node: MeetingNode): string;

package/lib/types/proxy-thinking.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Proxy Thinking (代理思考): when a black-box worker model (no visible
+ * reasoning) must execute a task, the director model (DeepSeek) first writes
+ * its own reasoning as `[DeepSeek 代理思考]`, then translates the goal into
+ * exact worker parameters. The UI prefixes stages with
+ * `[DeepSeek 代理思考]` / `[<worker> 渲染中]`.
+ * @module dsh-plugin-roundtable/proxy-thinking
+ */
+/** The director-side prompt template (spec §6.2). */
+export declare const PROXY_THINKING_TEMPLATE = "\u3010\u4EE3\u7406\u601D\u8003\uFF08Proxy Thinking\uFF09\u2014\u2014 \u5BFC\u6F14\u6A21\u578B\u4FA7\u3011\n\n\u4F60\u5F53\u524D\u626E\u6F14\"\u5BFC\u6F14\u6A21\u578B\"\uFF0C\u8D1F\u8D23\u628A\u4E00\u4E2A\u6A21\u7CCA\u76EE\u6807\u4EA4\u7ED9\u4E00\u4E2A\"\u65E0\u601D\u8003\u8FC7\u7A0B\u7684\u5E72\u6D3B\u6A21\u578B\" <worker_model> \u6267\u884C\u3002\n<worker_model> \u4E0D\u4F1A\u5C55\u793A\u601D\u8003\u8FC7\u7A0B\u3001\u4E0D\u4F1A\u81EA\u6211\u7EA0\u9519\u3001\u4E0D\u4F1A\u8FFD\u95EE\u6F84\u6E05\u3002\n\u56E0\u6B64\u4F60\u7684\u804C\u8D23\u662F\u66FF\u5B83\u5B8C\u6210\u601D\u8003\uFF0C\u5E76\u628A\u4EFB\u52A1\u7FFB\u8BD1\u6210\u5B83\u80FD\u76F4\u63A5\u6267\u884C\u7684\u6307\u4EE4\u3002\n\n\u8BF7\u4E25\u683C\u6309\u4EE5\u4E0B\u987A\u5E8F\u8F93\u51FA\uFF0C\u4E0D\u8981\u9057\u6F0F\u4EFB\u4F55\u4E00\u8282\uFF1A\n\n\u4E00\u3001[DeepSeek \u4EE3\u7406\u601D\u8003]\n\u7528\u81EA\u7136\u8BED\u8A00\u5199\u51FA\u4F60\u7684\u5B8C\u6574\u63A8\u7406\u8FC7\u7A0B\uFF0C\u81F3\u5C11\u8986\u76D6\uFF1A\n- \u4F60\u5982\u4F55\u7406\u89E3\u8FD9\u4E2A\u76EE\u6807\uFF08\u62C6\u89E3\u6210\u54EA\u4E9B\u5B50\u610F\u56FE\uFF09\n- \u4F60\u9009\u62E9\u4EC0\u4E48\u7B56\u7565\uFF0C\u4E3A\u4EC0\u4E48\n- \u5173\u952E\u53C2\u6570\u4E3A\u4EC0\u4E48\u8FD9\u6837\u5B9A\uFF08\u7ED9\u51FA\u53D6\u820D\u7406\u7531\uFF09\n- \u9884\u671F\u7ED3\u679C\u662F\u4EC0\u4E48\n- \u53EF\u80FD\u7684\u5931\u8D25\u70B9\u4E0E\u515C\u5E95\u65B9\u6848\n\uFF08\u8FD9\u4E00\u8282\u662F\"\u4EE3\u7406\u601D\u8003\"\uFF0C\u76F4\u63A5\u5C55\u793A\u7ED9\u7528\u6237\uFF0C\u8865\u9F50 <worker_model> \u7F3A\u5931\u7684\u900F\u660E\u6027\u3002\uFF09\n\n\u4E8C\u3001[\u53C2\u6570\u7FFB\u8BD1 \u2192 <worker_model>]\n\u628A\u76EE\u6807\u7FFB\u8BD1\u6210 <worker_model> \u80FD\u76F4\u63A5\u6267\u884C\u7684\u7CBE\u786E\u6307\u4EE4/\u53C2\u6570\uFF1A\n- \u5B57\u6BB5\u5FC5\u987B\u7B26\u5408 <worker_model> \u7684\u8F93\u5165\u89C4\u8303\uFF08schema\uFF09\n- \u7981\u6B62\u542B\u7CCA\u63CF\u8FF0\uFF1A\u4E0D\u7528\"\u597D\u770B\u4E00\u70B9/\u9AD8\u7EA7\u4E00\u70B9\"\uFF0C\u5FC5\u987B\u7ED9\u51FA\u5177\u4F53\u98CE\u683C\u3001\u6784\u56FE\u3001\u65F6\u957F\u3001\u5C3A\u5BF8\u3001\u8BED\u6C14\u7B49\n- \u8F93\u51FA\u4E3A\u7ED3\u6784\u5316 JSON \u6216\u7CBE\u786E\u6307\u4EE4\u6587\u672C\uFF08\u4EE5 <worker_model> \u5B9E\u9645\u63A5\u53D7\u7684\u683C\u5F0F\u4E3A\u51C6\uFF09\n\n\u4E09\u3001[\u9884\u671F\u4E0E\u515C\u5E95]\n- \u9884\u671F\u7ED3\u679C\uFF1A\u6267\u884C\u6210\u529F\u65F6\u5E94\u5F97\u5230\u4EC0\u4E48\n- \u5931\u8D25\u515C\u5E95\uFF1A\u82E5\u7ED3\u679C\u4E0D\u7B26\u5408\u9884\u671F\uFF0C\u4F60\u63A5\u4E0B\u6765\u5982\u4F55\u4FEE\u6B63\u6216\u964D\u7EA7";
+/** Compose the director-side prompt for one worker task. */
+export declare function proxyThinkingPrompt(workerModel: string, task: string): string;

package/lib/types/review-split.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 观点拆分（V0.2.2 批次 1）：collect_review 时把红队专家的一条发言用 LLM
+ * 拆成 1~3 条独立观点，用户即可对单条观点「支持/驳回」。
+ *
+ * 三道防线（V0.2.2 方案定稿）：
+ *  ① JSON schema 严格约束输出（tools 参数 + temperature 0）
+ *  ② 任何解析失败 → 返回 null，调用方整条兜底（seq=0）
+ *  ③ quote 必须是发言原文的子串（规范化后 indexOf），否则丢弃该 quote
+ * @module dsh-plugin-roundtable/review-split
+ */
+/** 一条拆分结果。 */
+export interface SplitLine {
+    content: string;
+    quote?: string;
+    dimension: string;
+    /** 证据分级（C1）：代码/bug 类 = repro（可复现步骤）；设计类 = argument（论证链）。 */
+    evidence?: {
+        kind: 'repro' | 'argument';
+        text: string;
+    };
+}
+/** 拆分调用的模型路由配置（默认 deepseek-official/deepseek-v4-flash，实测可用）。 */
+export interface ReviewSplitConfig {
+    provider: string;
+    model: string;
+    /** 每条发言最多拆几条观点（默认 3）。 */
+    maxOpinions: number;
+}
+/** 最小化 LLM 服务形状（与 ctx.llm.stream 结构兼容）。 */
+export interface SplitLlmLike {
+    stream(options: {
+        provider: string;
+        model: string;
+        messages: {
+            id: string;
+            role: 'user';
+            content: {
+                type: 'text';
+                text: string;
+            }[];
+            source: {
+                kind: 'user';
+            };
+        }[];
+        system?: string;
+        tools?: {
+            name: string;
+            description: string;
+            parameters: Record<string, unknown>;
+        }[];
+        temperature?: number;
+        maxTokens?: number;
+        signal?: AbortSignal;
+    }): AsyncIterable<unknown>;
+}
+export declare function splitByMarkers(content: string): SplitLine[] | null;
+/**
+ * 拆分一条发言为若干独立观点；任何失败返回 null（调用方整条兜底）。
+ * quote 与发言原文做规范化子串校验（防线③），不匹配即丢弃。
+ */
+export declare function splitUtterance(llm: SplitLlmLike, config: ReviewSplitConfig, nodeKey: string, content: string): Promise<SplitLine[] | null>;