@y9931666/dsh-plugin-crossfire 0.1.1 → 0.1.3

package/lib/types/rpc.d.ts

@@ -1,176 +0,0 @@
-/**
- * Crossfire 的浏览器面：一个 `dispatch`（RPC）+ 一个快照收集器（GET）。
- *
- * ## 两条传输，同一份 dispatch
- *
- * 1. 插件自有的 web POST 路由 `/plugins/dsh-plugin-crossfire/rpc`（首选：任何带 web
- *    服务的 profile 都可达）；
- * 2. 宿主通用 connection 通道（兜底，经 `ctx.get` 懒取）。
- *
- * ## O1：卡片按钮**直推** host 状态机
- *
- * 这是 crossfire 与圆桌会议最重要的编排差异。圆桌的 UI 只能写"用户行为队列"，
- * 等主持人下一轮执行；针锋的按钮直接调用这里的 `crossfire/review.advance`，
- * 因此用户点"开审"不必等一整个模型回合。
- *
- * 代价是：**RPC 路径没有 `exec.agent`**。凡是需要父 Agent 的动作（拉起子代理）
- * 就得先按会话 id 把 Agent 找回来（`ctx.agents.get`）；找不到（会话已冷）时如实
- * 失败并让用户改用对话触发，而不是假装成功。
- *
- * ## 一条不可越界的规则
- *
- * `crossfire/defect.setStatus` **只允许人从界面调用**。它没有对应的 agent 工具，
- * 也永远不该有：表态权是这个插件存在的理由本身。
- *
- * @module dsh-plugin-crossfire/rpc
- */
-import type { Context } from '@deepseek-ai/cordis';
-import { type PreferenceStore } from './preferences.ts';
-import { exportFile } from './review.ts';
-import type { ToolsConfig } from './tools.ts';
-import { type CrossfireRecord, type Intensity } from './types.ts';
-/** 插件自有 RPC 路由（浏览器半体优先走这条）。 */
-export declare const RPC_ROUTE = "/plugins/dsh-plugin-crossfire/rpc";
-/** 插件自有快照路由（卡片每秒轮询它）。 */
-export declare const STATE_ROUTE = "/plugins/dsh-plugin-crossfire/state";
-/** 运行时依赖：偏好存储 + 工具/引擎共用的配置（单一来源）。 */
-export interface CrossfireRuntime {
-    prefs: PreferenceStore;
-    tools: ToolsConfig;
-}
-/** RPC 失败包封。 */
-export interface RpcFailure {
-    ok: false;
-    error: {
-        code: string;
-        message: string;
-    };
-}
-/** RPC 结果包封（成功 / 失败二选一）。 */
-export type RpcResult = {
-    ok: true;
-    value: unknown;
-} | RpcFailure;
-/** dispatch 的类型：端点名 + 载荷 → 结果包封。 */
-export type RpcDispatch = (endpoint: string, payload: unknown) => Promise<RpcResult>;
-/** 卡片所需的评审快照（刻意不含 workspace 绝对路径之外的任何隐私内容）。 */
-export interface ReviewSnapshot {
-    reviewId: string;
-    status: CrossfireRecord['status'];
-    subjectTitle: string;
-    subjectContent: string;
-    subjectSource: string;
-    stanceText: string;
-    stanceOrigin: string;
-    dimensions: string[];
-    intensity: Intensity;
-    intensityLabel: string;
-    reviewPass: number;
-    maxReviewPass: number;
-    experts: {
-        key: string;
-        dimension: string;
-        status: string;
-        defectCount: number;
-        reportCount?: number;
-        /** 实际模型路由；未指定（继承主持人）时两个字段都不出现。 */
-        provider?: string;
-        model?: string;
-        /** 用户补充的角色定位（专家列表里可编辑）。 */
-        role?: string;
-        note?: string;
-    }[];
-    defects: {
-        id: string;
-        expertKey: string;
-        dimension: string;
-        dimensionFallback?: boolean;
-        content: string;
-        quote?: string;
-        evidence?: {
-            kind: 'repro' | 'argument';
-            text: string;
-        };
-        strikesStance?: boolean;
-        status: 'pending' | 'endorsed' | 'rejected';
-        rejectReason?: string;
-        /** 复审核对结论；`verdict` 缺席 = 尚未判断（**不是**"未修复"）。 */
-        recheck?: {
-            pass: number;
-            verdict?: string;
-            note?: string;
-        };
-    }[];
-    counts: {
-        total: number;
-        pending: number;
-        endorsed: number;
-        rejected: number;
-        strikes: number;
-    };
-    budget: {
-        maxRounds: number;
-        maxTokens: number;
-        usedRounds: number;
-        usedTokens: number;
-    };
-    startedAt: number;
-    updatedAt: number;
-    /** 这份评审所在的状态根（客户端回传后可免去再次遍历工作区）。 */
-    stateRoot: string;
-}
-/** 把记录收敛成卡片快照。 */
-export declare function snapshotOf(record: CrossfireRecord, stateRoot: string): ReviewSnapshot;
-/** 身份判定的结果。 */
-export type ActorVerdict = {
-    ok: true;
-    bound: boolean;
-} | {
-    ok: false;
-    code: 'no-actor' | 'foreign-owner';
-    message: string;
-};
-/**
- * 判定"谁在操作这一场评审"。
- *
- * ## 为什么必须是严格的（这里出过一个真实的安全缺陷）
- *
- * 会话 id 在这个插件里**同时是凭据和权限**：`load()` 用它做归属校验，
- * `review.advance` 的 attack 分支又用它换回 live Agent 去拉起专家。原先的写法把
- * 空会话当成"跳过校验"，于是当客户端没把 session 送进来时：
- *
- * - 归属校验整条短路（任何会话都能操作任何记录）；
- * - 而 attack 又会退回用**记录里的 owner** 换 Agent，照样把专家拉起来。
- *
- * 结果是一条能真正干活的越权通道，而且它的成功响应与合法调用完全同形 —— 验收时
- * 根本分不出来。红队在验收流程里抓到了这一点。
- *
- * 所以现在的规则是：**必须声称一个会话**。规则本身是纯函数，因此可以被测试直接
- * 钉住（`test/rpc-identity.test.mjs`），而不是只靠人工点一次按钮。
- *
- * @param ownerSessionId - 记录里的 owner（早期数据可能没有）。
- * @param actorSession - 调用方声称的会话 id（缺失时为 `''`）。
- */
-export declare function judgeActor(ownerSessionId: string | undefined, actorSession: string): ActorVerdict;
-/** 收集全部评审快照（卡片轮询的数据源）。 */
-export declare function collectSnapshots(ctx: Context, stateDir: string, session: string): Promise<{
-    reviews: ReviewSnapshot[];
-    note?: string;
-}>;
-/** 注册 RPC 端点，返回可复用的 `dispatch`。 */
-export declare function registerRpc(ctx: Context, runtime: CrossfireRuntime): RpcDispatch;
-/**
- * 从界面直接开一场评审。
- *
- * 与 `crossfire_open` 工具同源，区别只是工作区来自会话 id 而不是 `exec.agent`。
- */
-export declare function openReviewFromRpc(ctx: Context, runtime: CrossfireRuntime, input: {
-    session: string;
-    title: string;
-    content: string;
-    dimensions?: unknown;
-    intensity?: unknown;
-    stance?: string;
-}): Promise<RpcResult>;
-/** 导出路径（批 4 的下载按钮用）。 */
-export { exportFile };

package/lib/types/split.d.ts

@@ -1,156 +0,0 @@
-/**
- * 观点拆分：把红队专家的一条发言拆成 1~3 条独立缺陷，用户即可对单条缺陷
- * 「认定/驳回」。
- *
- * 三道防线（沿用圆桌里被真实数据验证过的设计，**不要改**）：
- *  ① JSON schema 严格约束输出（tools 参数 + temperature 0）
- *  ② 任何解析失败 → 返回 null，由调用方整条兜底（seq=0）
- *  ③ quote 必须是发言原文的子串（规范化后 indexOf），否则丢弃该 quote
- *
- * crossfire 相对圆桌的三处改动：
- *  - **维度归一化**：拆分结果里的 dimension 不再直接采信，一律过
- *    `resolveDimension`，保证落库的 dimension 一定 ∈ `allowed`；
- *  - **打穿标记**：每条缺陷可带 `strikesStance`（是否打穿了用户立场里的某条理由）；
- *  - 工具名与 system 提示词按 crossfire 改写。
- *
- * @module dsh-plugin-crossfire/split
- */
-/** 一条拆分结果（= 一条待裁决的缺陷）。 */
-export interface SplitLine {
-    content: string;
-    quote?: string;
-    /** 归一化后的维度，只要 `allowed` 非空就一定 ∈ allowed。 */
-    dimension: string;
-    /** true = 模型给的原始维度越界/缺失，落库时被归一化过。 */
-    dimensionFallback?: boolean;
-    /** 是否打穿了用户在「立场」里给出的某条理由。 */
-    strikesStance?: boolean;
-    /** 证据分级（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 并发上限（默认 4；`1` = 串行）。
-     *
-     * 它是"收集"这一步的墙钟时间决定项：一条发言一次往返，此前是串行 `await`，一场
-     * 21 条发言的评审就是 21 次串行往返（红队评审抓出的性能缺陷）。上限刻意不高 ——
-     * 这些请求打同一个 provider，拉满只会撞速率限制反而更慢。
-     *
-     * 放在这里而不是插件 Config：两个调用点（工具与 RPC 直推）读的都是同一个
-     * `reviewSplit`，因此两边的并发行为天然一致，不会分叉。
-     */
-    llmConcurrency?: 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>;
-}
-/** 拆分工具的 JSON schema（防线①）。导出以便测试断言 schema 形状。 */
-export declare const SPLIT_TOOL: {
-    readonly name: "split_crossfire_defect";
-    readonly description: "把一条红队专家发言拆成 1~3 条独立缺陷（每条缺陷只含一个问题）。";
-    readonly parameters: {
-        readonly type: "object";
-        readonly additionalProperties: false;
-        readonly properties: {
-            readonly defects: {
-                readonly type: "array";
-                readonly minItems: 1;
-                readonly maxItems: 3;
-                readonly items: {
-                    readonly type: "object";
-                    readonly additionalProperties: false;
-                    readonly properties: {
-                        readonly content: {
-                            readonly type: "string";
-                            readonly description: "单条缺陷的完整表述。";
-                        };
-                        readonly quote: {
-                            readonly type: "string";
-                            readonly description: "发言原文中与该缺陷对应的子串（可选，必须逐字来自发言原文）。";
-                        };
-                        readonly dimension: {
-                            readonly type: "string";
-                            readonly description: "缺陷所属维度。必须逐字取自给定清单 allowed 中的一项，不得自创。";
-                        };
-                        readonly strikes_stance: {
-                            readonly type: "boolean";
-                            readonly description: "该缺陷是否打穿了用户在「立场」里给出的某条理由。";
-                        };
-                        readonly evidence: {
-                            readonly type: "object";
-                            readonly description: "证据分级（C1）：代码/bug 类缺陷填 repro（附可复现步骤 1. 2. 3.）；设计类缺陷填 argument（附论证链，不编造伪复现步骤）。无法给出证据时省略该字段。";
-                            readonly additionalProperties: false;
-                            readonly properties: {
-                                readonly kind: {
-                                    readonly type: "string";
-                                    readonly enum: readonly ["repro", "argument"];
-                                    readonly description: "repro=可复现步骤（代码/bug 类）；argument=论证链（设计类）。";
-                                };
-                                readonly text: {
-                                    readonly type: "string";
-                                    readonly description: "证据正文：复现步骤（编号 1. 2. 3.）或论证链，≤600 字符。";
-                                };
-                            };
-                            readonly required: readonly ["kind", "text"];
-                        };
-                    };
-                    readonly required: readonly ["content", "dimension"];
-                };
-            };
-        };
-        readonly required: readonly ["defects"];
-    };
-};
-/**
- * 判定这段文字里专家自己写的「针对立场」结论是不是**打穿**。
- *
- * ## 为什么不能只写 `includes('打穿')`（这是真实存在的坑）
- *
- * `未打穿` 的后两个字就是 `打穿`，纯子串匹配会把"没打穿"读成"打穿了"，方向整个反过来。
- * 所以这里匹配有界的标记（`针对立场…：打穿|未打穿`）并**显式取反**：只有 `未` 缺席时
- * 才算打穿；标记压根不存在（含 `undefined`）也一律算没打穿。
- *
- * 之所以要有这个本地判定：专家的信封格式是**固定**的，报告正文里本来就写着结论。
- * 模型拆分失败退到本地启发式（{@link splitByMarkers}）时不该把这个信号丢掉 ——
- * 那正是"打穿立场"标签永远显示不出来的原因之一。
- */
-export declare function stanceMarkerStrikes(text: string | undefined): boolean;
-export declare function splitByMarkers(content: string, allowed: readonly string[]): SplitLine[] | null;
-/**
- * 拆分一条发言为若干独立缺陷；任何失败返回 null（调用方整条兜底）。
- * quote 与发言原文做规范化子串校验（防线③），不匹配即丢弃。
- * dimension 一律过 `resolveDimension`（落库值必须 ∈ allowed）。
- */
-export declare function splitUtterance(llm: SplitLlmLike, config: ReviewSplitConfig, expertKey: string, content: string, allowed: readonly string[], stance: string): Promise<SplitLine[] | null>;

package/lib/types/state.d.ts

@@ -1,84 +0,0 @@
-/**
- * Crossfire durable state：`<workspace>/<stateDir>/crossfire/<reviewId>/` 下的
- * 原子文件持久化 + 进程内串行锁。
- *
- * 目录布局（与圆桌会议的**关键差异**：多一层 `crossfire/` 命名空间，因为本
- * 插件不依附任何一场会议，可以完全不开会直接审）：
- *
- *   <stateRoot>/crossfire/<reviewId>/review.json       — 评审记录（主文档）
- *   <stateRoot>/crossfire/<reviewId>/transcript.jsonl   — 红队发言（append-only）
- *   <stateRoot>/crossfire/<reviewId>/user-actions.jsonl — 用户行为队列
- *   <stateRoot>/crossfire/<reviewId>/export.md          — 导出物
- *
- * 三条铁律（沿用圆桌已验证的契约）：
- * 1. **读失败绝不抛给调用方**：坏 JSON / 缺文件一律返回 undefined 或空集，
- *    由调用方决定降级方式。状态损坏不能让整张卡片从界面上消失。
- * 2. **写必须原子**：优先宿主 `@deepseek-ai/dsh-atomic-write`（带 Windows
- *    瞬时 EACCES/EBUSY 重试），否则本地同目录 tmp + rename 兜底。
- * 3. **坏行必须被计数**：`user-actions.jsonl` 的半行 JSON 若被静默跳过，
- *    那条用户操作就永久丢失且无人知道（圆桌 A2 的真实教训）。
- *
- * @module dsh-plugin-crossfire/state
- */
-/** 本插件在状态根下的固定命名空间目录名。 */
-export declare const CROSSFIRE_NAMESPACE = "crossfire";
-/** Stable directory id from a display name (keeps CJK, lowercases latin). */
-export declare function sanitizeKey(value: string): string;
-/**
- * Serialize async operations sharing one key inside this process.
- *
- * 注意（已知限制，写在任务书里）：这是**进程内**锁，跨进程不互斥。多窗口同时
- * 操作同一场评审时，后写者覆盖前者，只靠原子写保证文件不会写坏。v0.1.0 接受。
- */
-export declare function withCrossfireLock<T>(key: string, operation: () => Promise<T>): Promise<T>;
-/** 锁 key：同一场评审的操作互相串行。 */
-export declare function reviewLockKey(stateRoot: string, reviewId: string): string;
-/** Absolute state root under a workspace. */
-export declare function stateRootOf(workspace: string, stateDir: string): string;
-/** `<stateRoot>/crossfire` —— 本插件的命名空间目录。 */
-export declare function crossfireRootOf(stateRoot: string): string;
-/** Absolute directory of one review. */
-export declare function reviewDirOf(stateRoot: string, reviewId: string): string;
-/** 生成一个可读、可排序、无碰撞的评审 id：`x-<yyyyMMdd-HHmmss>-<4位>`。 */
-export declare function newReviewId(now?: number, random?: string): string;
-/** Atomically publish a UTF-8 text file. */
-export declare function writeTextAtomic(file: string, text: string): Promise<void>;
-/**
- * 原子写一份**带 UTF-8 BOM** 的文本，供人用记事本直接打开。
- *
- * 为什么单独一个函数：Windows 记事本对"无 BOM 的 UTF-8"时常误判成 ANSI，中文变乱码。
- * 而 `.md` 扩展名在不少机器上被别的程序抢走，双击进不了记事本。所以导出时额外写一份
- * `.txt`（带 BOM）—— 用户反馈"导出来的产物我无法用记事本查看"就是这个原因。
- *
- * BOM 只加在这份人读副本上：`.md` 保持无 BOM，交给 Markdown 渲染器更干净。
- */
-export declare function writeTextAtomicWithBom(file: string, text: string): Promise<void>;
-/** Atomically publish a JSON file (same-directory tmp + rename). */
-export declare function writeJsonAtomic(file: string, value: unknown): Promise<void>;
-/** 确保目录存在（幂等）。 */
-export declare function ensureDir(dir: string): Promise<void>;
-/**
- * 读一个 JSON 文件；**不存在或损坏都返回 undefined**（铁律 1）。
- *
- * 调用方拿到 undefined 时应当降级，而不是把异常抛给用户界面。
- */
-export declare function readJsonFile<T>(file: string): Promise<T | undefined>;
-/** 追加一条 JSONL 记录（自动建目录）。 */
-export declare function appendJsonLine(file: string, value: unknown): Promise<void>;
-/** 读取 JSONL 的结果：合法条目 + **被丢弃的坏行数**（铁律 3）。 */
-export interface JsonLinesReport<T> {
-    items: T[];
-    /** 无法解析的行数。非 0 时调用方必须如实告知用户，不许静默吞掉。 */
-    malformed: number;
-}
-/**
- * 读 JSONL；坏行被跳过但**计数**。
- *
- * 容忍被截断的尾行（进程在写一半时崩溃留下的半行 JSON），但它同样计入
- * `malformed` —— 因为那条记录确实丢了。
- */
-export declare function readJsonLines<T>(file: string): Promise<JsonLinesReport<T>>;
-/** 列出状态根下的全部评审 id（按名字排序，名字本身按时间可排）。 */
-export declare function listReviewIds(stateRoot: string): Promise<string[]>;
-/** 删除一场评审的全部落盘记录（幂等；目录不存在不算错误）。 */
-export declare function removeReviewDir(stateRoot: string, reviewId: string): Promise<void>;

package/lib/types/tools.d.ts

@@ -1,59 +0,0 @@
-/**
- * `crossfire_*` 模型面向的工具。
- *
- * ## 编排模型（与圆桌会议的根本差异）
- *
- * 圆桌是"主持人统筹"：模型负责建会、拉人、转述、聚合、推进每一轮。crossfire 不
- * 需要这些 —— 卡片上的按钮经 RPC 直接驱动 host 状态机（O1 决策）。所以这里的工具
- * 面刻意小：**六步、每步一件事、每步可单独重试**，模型只在"推不动了"的时候介入。
- *
- * 状态机（见 review.ts）：
- *   draft --open--> attacking --attack--> judging --collect--> settled --finish-->
- *   settled --recheck--> attacking（复审：只核对旧账，不许开新战线）
- *
- * ## 一条不可越界的规则
- *
- * **没有任何"代表态"的工具。** 缺陷的认定 / 驳回只能由人在卡片上操作，因此这里
- * 找不到 `crossfire_decide` 这类入口，而且不该有人加上它 —— 表态权是这个插件
- * 存在的理由本身。
- *
- * @module dsh-plugin-crossfire/tools
- */
-import type { Context } from '@deepseek-ai/cordis';
-import type { ReviewSplitConfig } from './split.ts';
-import type { Intensity } from './types.ts';
-/** 设置页那一层（每次调用实时读取，因此改设置对新建评审立即生效）。 */
-export interface ReviewDefaults {
-    intensity: Intensity;
-    maxRounds: number;
-    maxTokens: number;
-    expertMaxTokens: number;
-    expertMaxOpinions: number;
-    customDimensions: string[];
-}
-/** 工具运行时配置。 */
-export interface ToolsConfig {
-    stateDir: string;
-    memberProvider: string;
-    maxExperts: number;
-    memberMaxDepth?: number;
-    /**
-     * 专家**继承主持人**时实际生效的模型路由。
-     *
-     * 只为可观测性：开打时把这个生效值写回专家记录，卡片才能把"继承"画成真实品牌
-     * （DeepSeek 的蓝色 DS 块），而不是中性灰 `?`。它不参与任何路由决策。
-     */
-    defaultProvider?: string;
-    defaultModel?: string;
-    /** 观点拆分的 LLM 路由（不可用时自动退到本地兜底）。 */
-    reviewSplit: ReviewSplitConfig;
-    /** 实时读取的默认值。 */
-    getDefaults: () => ReviewDefaults;
-}
-export declare function registerCrossfireTools(ctx: Context, config: ToolsConfig): void;
-/**
- * 归属识别说明：`crossfire_report` 只认**专家索引**（expert-events 的进程内
- * childId → 评审位置）。专家是通过 `startContinuable` 拉起的子代理，唯一可靠的
- * 归属线索就是它的 childId。刻意不去"扫所有评审找 ownerSessionId 匹配" ——
- * 那样会让一个普通会话冒充专家提交发言。
- */