dsh-flakefinder 0.1.0

package/README.en.md

@@ -0,0 +1,50 @@
+# dsh-flakefinder
+
+> Teach agents the difference between broken code and a flaky test.
+
+A DeepSeek Harness plugin for test stability: run tests repeatedly, classify flaky cases, keep history, maintain a quarantine manifest, and gate writes with approvals. Zero runtime dependencies.
+
+![license](https://img.shields.io/npm/l/dsh-flakefinder) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-flakefinder?style=social)
+
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
+## Tools
+
+| Tool | Purpose | Write |
+| :-- | :-- | :-- |
+| `flaky_detect` | Repeat tests N times and classify stable-pass / stable-fail / flaky | history only |
+| `flaky_history` | Query detection history, filter by target | no |
+| `flaky_report` | Combine quarantine manifest and history into a report | no |
+| `flaky_quarantine` | Write flaky cases to `.flakefinder.json` | yes (approval) |
+| `flaky_clear` | Remove recovered cases from the manifest | yes (approval) |
+
+Frameworks: vitest / jest / node:test, auto-detected in that order.
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-flakefinder
+```
+
+## Example
+
+```text
+User: src/checkout.test.ts keeps failing recently, is it real?
+Agent:
+  flaky_detect(target="src/checkout.test.ts", runs=5)
+  -> verdict: flaky (3/5 passed; failures cluster on fake timers)
+  -> flaky_quarantine(tests=["src/checkout.test.ts > timer restore"], reason="timer race")
+```
+
+## Config
+
+See `cordis.patch.yml`; defaults: `defaultRuns=5`, `maxRuns=20`, `timeoutMs=120000`, `writeApproval=true`.
+
+## Development
+
+```bash
+pnpm test
+pnpm typecheck
+```
+
+MIT

package/README.md

@@ -0,0 +1,101 @@
+# dsh-flakefinder
+
+> 让 agent 分清「代码坏了」还是「测试在抽风」。
+
+DeepSeek Harness 测试稳定性插件：重复运行测试并识别 flaky 用例，历史留档、隔离清单、写操作审批门。零运行时依赖。
+
+![license](https://img.shields.io/npm/l/dsh-flakefinder) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-flakefinder?style=social)
+
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
+## 工具
+
+| 工具 | 作用 | 写操作 |
+| :-- | :-- | :-- |
+| `flaky_detect` | 重复运行测试 N 次，判定 stable-pass / stable-fail / flaky | 否（写历史） |
+| `flaky_history` | 查询检测历史，按目标过滤 | 否 |
+| `flaky_report` | 汇总隔离清单 + 历史，输出稳定性报告 | 否 |
+| `flaky_quarantine` | 把 flaky 用例写入 `.flakefinder.json` 隔离清单 | 是（审批门） |
+| `flaky_clear` | 从隔离清单移除已恢复的用例 | 是（审批门） |
+
+支持框架：
+
+- vitest：读取 `node_modules/vitest/vitest.mjs`，使用 JSON reporter
+- jest：读取 `node_modules/jest/bin/jest.js`，使用 `--json --outputFile`
+- node:test：`node --test --test-reporter=tap`，解析 TAP
+- `framework: auto` 按 vitest → jest → node:test 自动探测
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-flakefinder
+```
+
+或手动安装后在 profile 的 `cordis.patch.yml` 插入：
+
+```yaml
+- id: flakefinder
+  name: 'dsh-flakefinder'
+  config:
+    defaultRuns: 5
+    writeApproval: true
+```
+
+## 使用示例
+
+```text
+用户：src/checkout.test.ts 最近老失败，帮我判断一下
+Agent：
+  flaky_detect(target="src/checkout.test.ts", runs=5)
+  → 判定：flaky；3/5 通过，失败集中在 useFakeTimers 用例
+  → flaky_quarantine(tests=["src/checkout.test.ts > 定时器恢复"], reason="定时器竞态")
+```
+
+## 配置
+
+| 字段 | 默认 | 说明 |
+| :-- | :-- | :-- |
+| `defaultRuns` | `5` | `flaky_detect` 默认重复次数（3-20） |
+| `maxRuns` | `20` | 单次允许的最大重复次数（3-50） |
+| `timeoutMs` | `120000` | 单轮测试运行超时 |
+| `graceMs` | `10000` | 超时后宽限 |
+| `writeApproval` | `true` | 隔离清单写操作是否走审批门 |
+| `dataDir` | `DSH_HOME/.dsh-flakefinder` | 历史存储目录 |
+| `quarantineFile` | `<cwd>/.flakefinder.json` | 隔离清单路径 |
+
+## 隔离清单格式
+
+```json
+{
+  "version": 1,
+  "quarantined": [
+    {
+      "file": "src/checkout.test.ts",
+      "name": "使用假定时器后恢复真实定时器",
+      "reason": "定时器竞态，见 issue #12",
+      "since": "2026-08-16T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+隔离清单只记录，不修改测试源码；agent 跑测试前应先查阅 `flaky_report`。
+
+## 工程
+
+- Node >= 22.13，TypeScript，零运行时依赖
+- 测试进程走 DSH 官方 subprocess 服务，argv 数组、无 shell
+- 全量单测 30+：解析、判定、存储、审批门、注册与 manifest
+- `pnpm test`：构建 + `node --test`
+
+## 发布门禁
+
+1. `pnpm test` 全绿
+2. `pnpm typecheck`
+3. 危险模式扫描（eval / child_process / 密钥零容忍）
+4. 真实 profile 冒烟：全新临时 profile 安装插件 → 真 boot → stderr 零报错
+5. manifest 自检（bundle patch / exports / files 白名单）
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,19 @@
+# dsh-flakefinder 组合包补丁：把测试稳定性插件行插入 profile。
+# 用户 profile 的 cordis.patch.yml 可按 id 覆盖本行整个 config。
+#
+# 示例：
+#   - id: flakefinder
+#     name: 'dsh-flakefinder'
+#     config:
+#       defaultRuns: 5          # flaky_detect 默认重复次数（3-20）
+#       timeoutMs: 120000       # 单次测试运行超时（毫秒）
+#       writeApproval: true     # quarantine/clear 是否走审批门（默认 true）
+#       dataDir: ''             # 历史存储目录（默认 DSH_HOME/.dsh-flakefinder）
+#       quarantineFile: ''      # 隔离清单（默认项目根 .flakefinder.json）
+#
+- insert:
+    - id: flakefinder
+      name: 'dsh-flakefinder'
+      config:
+        defaultRuns: 5
+        writeApproval: true

package/lib/args.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 测试框架探测与 argv 构建：直接调用本地 node_modules 里的 CLI 入口，
+ * 全程 argv 数组、无 shell，避免 npx 下载与命令注入。
+ *
+ * @module dsh-flakefinder/args
+ */
+export type Framework = 'auto' | 'vitest' | 'jest' | 'node';
+export type ReportKind = 'json' | 'tap';
+export interface TestPlan {
+    framework: Exclude<Framework, 'auto'>;
+    reportKind: ReportKind;
+    reportPath: string;
+    argv: string[];
+    label: string;
+}
+/** 解析 framework 参数；非法值抛中文错误。 */
+export declare function readFramework(raw: unknown): Framework;
+/** 在 cwd 里探测本地框架 CLI 入口；显式指定时缺失会给出中文指引。 */
+export declare function detectFramework(cwd: string, requested: Framework): Exclude<Framework, 'auto'>;
+/** 构建一次测试运行的执行计划。runIndex 仅用于给临时报告文件命名。 */
+export declare function buildPlan(cwd: string, target: string, requested: Framework, runIndex: number): TestPlan;

package/lib/args.js

@@ -0,0 +1,81 @@
+/**
+ * 测试框架探测与 argv 构建：直接调用本地 node_modules 里的 CLI 入口，
+ * 全程 argv 数组、无 shell，避免 npx 下载与命令注入。
+ *
+ * @module dsh-flakefinder/args
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { assertTarget } from './config.js';
+/** 解析 framework 参数；非法值抛中文错误。 */
+export function readFramework(raw) {
+    if (raw === undefined || raw === null)
+        return 'auto';
+    if (raw === 'auto' || raw === 'vitest' || raw === 'jest' || raw === 'node')
+        return raw;
+    throw new Error('framework 只支持 auto / vitest / jest / node，收到：' + String(raw));
+}
+function localEntry(cwd, ...parts) {
+    const full = path.join(cwd, ...parts);
+    return fs.existsSync(full) ? full : null;
+}
+/** 在 cwd 里探测本地框架 CLI 入口；显式指定时缺失会给出中文指引。 */
+export function detectFramework(cwd, requested) {
+    const vitest = localEntry(cwd, 'node_modules', 'vitest', 'vitest.mjs');
+    const jest = localEntry(cwd, 'node_modules', 'jest', 'bin', 'jest.js');
+    if (requested !== 'auto') {
+        if (requested === 'vitest' && vitest === null) {
+            throw new Error('framework=vitest，但在 ' + cwd + ' 下找不到 node_modules/vitest/vitest.mjs。请先安装 vitest（例如 pnpm add -D vitest）。');
+        }
+        if (requested === 'jest' && jest === null) {
+            throw new Error('framework=jest，但在 ' + cwd + ' 下找不到 node_modules/jest/bin/jest.js。请先安装 jest。');
+        }
+        return requested;
+    }
+    if (vitest !== null)
+        return 'vitest';
+    if (jest !== null)
+        return 'jest';
+    return 'node';
+}
+/** 构建一次测试运行的执行计划。runIndex 仅用于给临时报告文件命名。 */
+export function buildPlan(cwd, target, requested, runIndex) {
+    const safeTarget = assertTarget(target);
+    const framework = detectFramework(cwd, requested);
+    const token = crypto.randomBytes(6).toString('hex');
+    if (framework === 'vitest') {
+        const entry = localEntry(cwd, 'node_modules', 'vitest', 'vitest.mjs');
+        if (entry === null)
+            throw new Error('未找到本地 vitest 入口：node_modules/vitest/vitest.mjs');
+        const reportPath = path.join(os.tmpdir(), 'dsh-flakefinder-vitest-' + process.pid + '-' + String(runIndex) + '-' + token + '.json');
+        return {
+            framework,
+            reportKind: 'json',
+            reportPath,
+            argv: [process.execPath, entry, 'run', safeTarget, '--reporter=json', '--outputFile', reportPath],
+            label: 'vitest run ' + safeTarget,
+        };
+    }
+    if (framework === 'jest') {
+        const entry = localEntry(cwd, 'node_modules', 'jest', 'bin', 'jest.js');
+        if (entry === null)
+            throw new Error('未找到本地 jest 入口：node_modules/jest/bin/jest.js');
+        const reportPath = path.join(os.tmpdir(), 'dsh-flakefinder-jest-' + process.pid + '-' + String(runIndex) + '-' + token + '.json');
+        return {
+            framework,
+            reportKind: 'json',
+            reportPath,
+            argv: [process.execPath, entry, '--runInBand', '--json', '--outputFile', reportPath, safeTarget],
+            label: 'jest run ' + safeTarget,
+        };
+    }
+    return {
+        framework: 'node',
+        reportKind: 'tap',
+        reportPath: '',
+        argv: [process.execPath, '--test', '--test-reporter=tap', safeTarget],
+        label: 'node --test ' + safeTarget,
+    };
+}

package/lib/classify.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 多轮结果聚合与 flaky 判定：纯函数，便于单测边界。
+ *
+ * @module dsh-flakefinder/classify
+ */
+import type { NormalizedRun } from './parse.js';
+export type RunVerdict = 'stable-pass' | 'stable-fail' | 'flaky' | 'empty' | 'skipped';
+export type TestVerdict = 'stable-pass' | 'stable-fail' | 'flaky' | 'skipped';
+export interface RunRecord {
+    runIndex: number;
+    success: boolean;
+    passed: number;
+    failed: number;
+    skipped: number;
+    durationMs: number;
+}
+export interface TestRecord {
+    id: string;
+    file: string;
+    name: string;
+    passes: number;
+    failures: number;
+    skips: number;
+    failureRate: number;
+    verdict: TestVerdict;
+}
+export interface DetectionResult {
+    runs: RunRecord[];
+    verdict: RunVerdict;
+    stablePassCount: number;
+    stableFailCount: number;
+    flakyCount: number;
+    skippedCount: number;
+    tests: TestRecord[];
+    durationMs: number;
+}
+export declare function aggregate(runs: Array<{
+    index: number;
+    report: NormalizedRun | null;
+    durationMs: number;
+    error?: string;
+}>): DetectionResult;
+/** 结果里需要写入历史的 flaky 用例。 */
+export declare function flakyTests(result: DetectionResult): Array<{
+    file: string;
+    name: string;
+    failureRate: number;
+}>;

package/lib/classify.js

@@ -0,0 +1,103 @@
+/**
+ * 多轮结果聚合与 flaky 判定：纯函数，便于单测边界。
+ *
+ * @module dsh-flakefinder/classify
+ */
+export function aggregate(runs) {
+    const records = runs.map(run => ({
+        runIndex: run.index,
+        success: run.report?.success === true,
+        passed: run.report?.passed ?? 0,
+        failed: run.report?.failed ?? 0,
+        skipped: run.report?.skipped ?? 0,
+        durationMs: run.durationMs,
+    }));
+    const active = runs.filter(run => run.report !== null);
+    if (active.length === 0) {
+        const detail = runs.find(run => run.error !== undefined);
+        throw new Error('没有一次运行产出可解析的测试报告。' + (detail?.error !== undefined ? ' 首个错误：' + detail.error : ''));
+    }
+    const byId = new Map();
+    for (const run of active) {
+        const tests = run.report?.tests ?? [];
+        for (const test of tests) {
+            let entry = byId.get(test.id);
+            if (entry === undefined) {
+                entry = { file: test.file, name: test.name, passes: 0, failures: 0, skips: 0 };
+                byId.set(test.id, entry);
+            }
+            if (test.status === 'passed')
+                entry.passes += 1;
+            else if (test.status === 'failed')
+                entry.failures += 1;
+            else
+                entry.skips += 1;
+        }
+    }
+    const tests = [];
+    let stablePassCount = 0;
+    let stableFailCount = 0;
+    let flakyCount = 0;
+    let skippedCount = 0;
+    for (const [id, entry] of byId) {
+        const seen = entry.passes + entry.failures;
+        let verdict;
+        if (seen === 0) {
+            verdict = 'skipped';
+            skippedCount += 1;
+        }
+        else if (entry.failures === 0) {
+            verdict = 'stable-pass';
+            stablePassCount += 1;
+        }
+        else if (entry.passes === 0) {
+            verdict = 'stable-fail';
+            stableFailCount += 1;
+        }
+        else {
+            verdict = 'flaky';
+            flakyCount += 1;
+        }
+        tests.push({
+            id,
+            file: entry.file,
+            name: entry.name,
+            passes: entry.passes,
+            failures: entry.failures,
+            skips: entry.skips,
+            failureRate: seen === 0 ? 0 : Math.round((entry.failures / seen) * 1000) / 10,
+            verdict,
+        });
+    }
+    let verdict;
+    const passRuns = records.filter(run => run.success).length;
+    if (tests.every(test => test.verdict === 'skipped')) {
+        verdict = 'skipped';
+    }
+    else if (passRuns === records.length) {
+        verdict = 'stable-pass';
+    }
+    else if (passRuns === 0) {
+        verdict = 'stable-fail';
+    }
+    else {
+        verdict = 'flaky';
+    }
+    tests.sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        runs: records,
+        verdict,
+        stablePassCount,
+        stableFailCount,
+        flakyCount,
+        skippedCount,
+        tests,
+        durationMs: records.reduce((sum, item) => sum + item.durationMs, 0),
+    };
+}
+/** 结果里需要写入历史的 flaky 用例。 */
+export function flakyTests(result) {
+    return result.tests
+        .filter(test => test.verdict === 'flaky')
+        .map(test => ({ file: test.file, name: test.name, failureRate: test.failureRate }));
+}

package/lib/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * dsh-flakefinder 配置解析：重复次数、超时、审批策略与存储路径。
+ *
+ * @module dsh-flakefinder/config
+ */
+/** 插件行配置（cordis.patch.yml 里的 config 段，可缺省）。 */
+export interface FlakeConfig {
+    /** flaky_detect 默认重复次数（3-20）。 */
+    defaultRuns?: number;
+    /** 单次运行允许的最大重复次数（3-50，默认 20）。 */
+    maxRuns?: number;
+    /** 单次测试运行的超时（毫秒，默认 120000）。 */
+    timeoutMs?: number;
+    /** 超时后给测试进程的宽限时间（毫秒，默认 10000）。 */
+    graceMs?: number;
+    /** quarantine/clear 两个写工具是否走宿主审批门（默认 true）。 */
+    writeApproval?: boolean;
+    /** 历史存储目录（默认 DSH_HOME/.dsh-flakefinder）。 */
+    dataDir?: string;
+    /** 项目隔离清单路径（默认 cwd/.flakefinder.json）。 */
+    quarantineFile?: string;
+}
+/** 解析后的配置。 */
+export interface ResolvedFlakeConfig {
+    defaultRuns: number;
+    maxRuns: number;
+    timeoutMs: number;
+    graceMs: number;
+    writeApproval: boolean;
+    dataDir: string;
+    quarantineFile: string;
+}
+/** 解析并校验配置，非法值抛出中文错误。 */
+export declare function resolveConfig(config: FlakeConfig | undefined | null, cwd?: string): ResolvedFlakeConfig;
+/** 解析并钳制 flaky_detect 的 runs 参数。 */
+export declare function resolveRuns(raw: unknown, cfg: ResolvedFlakeConfig): number;
+/** 校验测试目标：非空且不能以 - 开头，避免被测试框架解析成选项。 */
+export declare function assertTarget(value: string): string;
+/** 从参数里取字符串；不识别类型时返回 undefined。 */
+export declare function optionalString(args: Record<string, unknown>, key: string): string | undefined;
+/** 从参数里取必填字符串；缺失时抛中文错误。 */
+export declare function requiredString(args: Record<string, unknown>, key: string, label: string): string;
+/** 从参数里取整数；缺失用默认值，非法抛中文错误。 */
+export declare function optionalInteger(args: Record<string, unknown>, key: string, label: string, lo: number, hi: number, fallback: number): number;

package/lib/config.js

@@ -0,0 +1,102 @@
+/**
+ * dsh-flakefinder 配置解析：重复次数、超时、审批策略与存储路径。
+ *
+ * @module dsh-flakefinder/config
+ */
+import { homedir } from 'node:os';
+import path from 'node:path';
+const MIN_RUNS = 3;
+const MAX_RUNS = 50;
+/** DSH_HOME 缺省时退回用户目录下的 .dsh。 */
+function defaultDataDir() {
+    const home = process.env.DSH_HOME?.trim();
+    return path.join(home !== undefined && home !== '' ? home : path.join(homedir(), '.dsh'), '.dsh-flakefinder');
+}
+/** 解析并校验配置，非法值抛出中文错误。 */
+export function resolveConfig(config, cwd = process.cwd()) {
+    const cfg = config ?? {};
+    let defaultRuns = 5;
+    if (cfg.defaultRuns !== undefined) {
+        defaultRuns = readRuns('defaultRuns', cfg.defaultRuns, 3, 20);
+    }
+    let maxRuns = 20;
+    if (cfg.maxRuns !== undefined) {
+        maxRuns = readRuns('maxRuns', cfg.maxRuns, MIN_RUNS, MAX_RUNS);
+    }
+    if (defaultRuns > maxRuns)
+        defaultRuns = maxRuns;
+    let timeoutMs = 120000;
+    if (cfg.timeoutMs !== undefined) {
+        if (typeof cfg.timeoutMs !== 'number' || !Number.isFinite(cfg.timeoutMs) || cfg.timeoutMs <= 0) {
+            throw new Error('timeoutMs 必须是大于 0 的数字（毫秒）。');
+        }
+        timeoutMs = Math.min(10 * 60 * 1000, Math.max(10000, Math.round(cfg.timeoutMs)));
+    }
+    let graceMs = 10000;
+    if (cfg.graceMs !== undefined) {
+        if (typeof cfg.graceMs !== 'number' || !Number.isFinite(cfg.graceMs) || cfg.graceMs <= 0) {
+            throw new Error('graceMs 必须是大于 0 的数字（毫秒）。');
+        }
+        graceMs = Math.min(120000, Math.max(1000, Math.round(cfg.graceMs)));
+    }
+    const writeApproval = cfg.writeApproval !== false;
+    const dataDir = typeof cfg.dataDir === 'string' && cfg.dataDir.trim() !== ''
+        ? path.resolve(cwd, cfg.dataDir.trim())
+        : defaultDataDir();
+    const quarantineFile = typeof cfg.quarantineFile === 'string' && cfg.quarantineFile.trim() !== ''
+        ? path.resolve(cwd, cfg.quarantineFile.trim())
+        : path.join(cwd, '.flakefinder.json');
+    return { defaultRuns, maxRuns, timeoutMs, graceMs, writeApproval, dataDir, quarantineFile };
+}
+function readRuns(label, value, lo, hi) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        throw new Error(label + ' 必须是数字。');
+    const rounded = Math.round(value);
+    if (rounded < lo || rounded > hi)
+        throw new Error(label + ' 必须在 ' + String(lo) + '-' + String(hi) + ' 之间。');
+    return rounded;
+}
+/** 解析并钳制 flaky_detect 的 runs 参数。 */
+export function resolveRuns(raw, cfg) {
+    if (raw === undefined || raw === null)
+        return cfg.defaultRuns;
+    if (typeof raw !== 'number' || !Number.isFinite(raw))
+        throw new Error('runs 必须是数字（3-' + String(cfg.maxRuns) + '）。');
+    const runs = Math.round(raw);
+    if (runs < 3 || runs > cfg.maxRuns)
+        throw new Error('runs 必须在 3-' + String(cfg.maxRuns) + ' 之间。');
+    return runs;
+}
+/** 校验测试目标：非空且不能以 - 开头，避免被测试框架解析成选项。 */
+export function assertTarget(value) {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        throw new Error('target（测试文件/目录/glob）为必填，请提供非空字符串。');
+    if (trimmed.startsWith('-'))
+        throw new Error('target 不能以 - 开头：' + value);
+    return trimmed;
+}
+/** 从参数里取字符串；不识别类型时返回 undefined。 */
+export function optionalString(args, key) {
+    const value = args[key];
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+/** 从参数里取必填字符串；缺失时抛中文错误。 */
+export function requiredString(args, key, label) {
+    const value = optionalString(args, key);
+    if (value === undefined)
+        throw new Error(label + '（参数 ' + key + '）为必填，请提供非空字符串。');
+    return value;
+}
+/** 从参数里取整数；缺失用默认值，非法抛中文错误。 */
+export function optionalInteger(args, key, label, lo, hi, fallback) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        throw new Error(label + '（参数 ' + key + '）必须是数字。');
+    const rounded = Math.round(value);
+    if (rounded < lo || rounded > hi)
+        throw new Error(label + '（参数 ' + key + '）必须在 ' + String(lo) + '-' + String(hi) + ' 之间。');
+    return rounded;
+}

package/lib/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * dsh-flakefinder —— 测试稳定性工具插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：注册五个面向模型的工具（flaky_detect / flaky_history /
+ * flaky_quarantine / flaky_clear / flaky_report）。测试进程走 DSH 官方 subprocess 服务
+ * （argv 数组、无 shell），隔离清单写操作默认走宿主审批门。零运行时依赖。
+ *
+ * @module dsh-flakefinder
+ */
+import { type FlakeConfig } from './config.js';
+import { type SubprocessSpawnLike } from './runner.js';
+import { type FlakeToolDefinition } from './tools.js';
+/** cordis 服务注入：apply 里要用 ctx.subprocess 与 ctx.tools。 */
+export declare const inject: string[];
+/** 插件所需的最小 ctx 面。 */
+export interface FlakePluginContext {
+    subprocess: {
+        spawn: SubprocessSpawnLike;
+    };
+    tools: {
+        register(definition: FlakeToolDefinition, options?: {
+            prepend?: boolean;
+        }): () => void;
+    };
+    get?(name: 'approval'): unknown;
+    on?(event: string, listener: () => void): () => void;
+}
+/**
+ * 插件入口：解析配置、封装执行器与存储、注册五个工具。
+ */
+export declare function apply(ctx: FlakePluginContext, config?: FlakeConfig | null): void;
+export * from './args.js';
+export * from './classify.js';
+export * from './config.js';
+export * from './parse.js';
+export * from './runner.js';
+export * from './store.js';
+export * from './tools.js';

package/lib/index.js

@@ -0,0 +1,56 @@
+/**
+ * dsh-flakefinder —— 测试稳定性工具插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：注册五个面向模型的工具（flaky_detect / flaky_history /
+ * flaky_quarantine / flaky_clear / flaky_report）。测试进程走 DSH 官方 subprocess 服务
+ * （argv 数组、无 shell），隔离清单写操作默认走宿主审批门。零运行时依赖。
+ *
+ * @module dsh-flakefinder
+ */
+import { resolveConfig } from './config.js';
+import { createSubprocessRunner } from './runner.js';
+import { createStore } from './store.js';
+import { buildFlakeTools } from './tools.js';
+/** cordis 服务注入：apply 里要用 ctx.subprocess 与 ctx.tools。 */
+export const inject = ['subprocess', 'tools'];
+/**
+ * 插件入口：解析配置、封装执行器与存储、注册五个工具。
+ */
+export function apply(ctx, config) {
+    let cfg;
+    try {
+        cfg = resolveConfig(config);
+    }
+    catch (error) {
+        console.warn('[dsh-flakefinder] ' + (error instanceof Error ? error.message : String(error)));
+        cfg = resolveConfig(null);
+    }
+    const runner = createSubprocessRunner(ctx.subprocess.spawn, cfg.graceMs, cfg.timeoutMs);
+    const store = createStore(cfg.dataDir, cfg.quarantineFile);
+    const tools = buildFlakeTools(cfg, runner, store);
+    const disposers = [];
+    for (const definition of tools) {
+        const wrapped = { ...definition };
+        if (wrapped.gate !== undefined) {
+            const original = wrapped.gate.bind(wrapped);
+            wrapped.gate = async (exec, next) => {
+                const record = (typeof exec === 'object' && exec !== null ? exec : {});
+                return original({ ...record, approval: ctx.get?.('approval') }, next);
+            };
+        }
+        disposers.push(ctx.tools.register(wrapped, { prepend: true }));
+    }
+    if (typeof ctx.on === 'function') {
+        ctx.on('dispose', () => {
+            for (const dispose of disposers)
+                dispose();
+        });
+    }
+}
+export * from './args.js';
+export * from './classify.js';
+export * from './config.js';
+export * from './parse.js';
+export * from './runner.js';
+export * from './store.js';
+export * from './tools.js';