@fantasticit/sumi 0.0.0-stage → 0.5.1

package/node_modules/@sumi/plugin-sdk/dist/protocol.d.ts

@@ -0,0 +1,200 @@
+/** 插件协议：内核与插件之间唯一的契约。 */
+export type Status = 'pass' | 'fail' | 'blocked' | 'skipped' | 'pending';
+/** 步骤状态比插件状态多一个只能由内核设置的 not-applicable。 */
+export type StepState = Status | 'not-applicable';
+export type PluginKind = 'check' | 'planner';
+export type Severity = 'error' | 'warning' | 'info';
+export type Effect = 'none' | 'writes-worktree' | 'writes-control' | 'network' | 'publish';
+export type ReceiptOutcome = 'passed' | 'failed' | 'skipped' | 'not-executed';
+export declare const STATUSES: readonly Status[];
+export declare const EFFECTS: readonly Effect[];
+export declare const RECEIPT_OUTCOMES: readonly ReceiptOutcome[];
+/** 约定退出码：pass 为 0，fail 为 1，其余为 2。 */
+export declare function exitCodeFor(status: Status): number;
+export interface MetricDeclaration {
+    name: string;
+    direction: 'lower-is-better' | 'higher-is-better';
+    /** 测量噪声的容差（绝对值）：只有超出容差的变化才算变差或变好。缺省为 0。 */
+    tolerance?: number;
+}
+/** 按方向与容差比较指标：worse / better 都只在超出容差时成立。 */
+export declare function compareMetric(decl: MetricDeclaration, value: number, base: number): {
+    worse: boolean;
+    better: boolean;
+};
+export interface CommandDeclaration {
+    name: string;
+    argv: string[];
+    description: string;
+}
+export interface PluginDeclaration {
+    id: string;
+    version: string;
+    kind: PluginKind;
+    /** argv 数组；以 ./ 或 ../ 开头的参数相对声明文件所在目录解析。派生插件与只提供命令的插件不声明。 */
+    command: string[];
+    /** 派生插件：沿用该插件的执行命令、kind 与超时，以 with 作为默认步骤配置（例如以一个运行任意命令的插件包装项目已有脚本）。 */
+    base?: string;
+    /** 默认步骤配置，流程步骤的 with 逐键覆盖。 */
+    with?: Record<string, unknown>;
+    /** 超时，单位秒。 */
+    timeout: number;
+    triggers?: string[];
+    minTier?: string;
+    fix?: string[];
+    metrics?: MetricDeclaration[];
+    commands?: CommandDeclaration[];
+    /** 依赖的插件包名称。 */
+    requires?: string[];
+    /** 运行前提：项目 node_modules/.bin 下的可执行文件与相对仓库根的文件；只供接入流程裁剪默认流程。 */
+    needs?: {
+        bin?: string[];
+        files?: string[];
+    };
+    /** 插件需要接入的 hook：值为本插件注册的命令名，由适配生成器统一接线。 */
+    hooks?: {
+        /** git hook 名称 → 命令名，例如 pre-push: verify。 */
+        git?: Record<string, string>;
+        /** AI 工具调用工具前、编辑文件后与准备结束回合时运行的命令。工具原始负载经标准输入传入。 */
+        agent?: {
+            beforeTool?: string;
+            afterEdit?: string;
+            stop?: string;
+        };
+    };
+    /** 接入已有仓库后运行的 sumi 命令参数，例如 [snapshot, save]。 */
+    afterInit?: string[];
+    /** 本插件提供的动态指令：主题名 → 插件包内的指令文件（Markdown）。 */
+    instructions?: Record<string, string>;
+    /** 一句话说明，供 sumi context 与诊断展示。 */
+    description?: string;
+    /** 约束查询命令（本插件注册的命令名）：标准输入为 { repoRoot, paths }，标准输出为 ContextResult。 */
+    context?: string;
+}
+/** 约束查询命令输出的条目：ref 与规则引用的写法相同（如 <类型>:<目标>、<类型>:<集合>#<条目>）。 */
+export interface ContextItem {
+    ref: string;
+    text: string;
+    source?: string;
+    /** 不限路径（没有触发条件或范围）的条目。 */
+    global?: boolean;
+    /** 同样指向本条目的其他引用写法（例如条目所属集合的引用），规则引用其中任一即视为关联。 */
+    aliases?: string[];
+}
+export interface ContextResult {
+    items: ContextItem[];
+}
+export declare const HOOK_BLOCK_START = "# >>> sumi\uFF1A\u7531 sumi update \u751F\u6210\uFF0C\u8BF7\u52FF\u624B\u6539 >>>";
+export declare const HOOK_BLOCK_END = "# <<< sumi <<<";
+export declare const PROJECT_SUMI = "node ./control/bin/sumi.cjs";
+export declare const PROJECT_SUMI_ARGV: readonly ["node", "./control/bin/sumi.cjs"];
+/** hook 中只调用仓库提交的 launcher，不再读取 PATH 上的全局 sumi。 */
+export declare function hookBlock(command: string[], _legacyInstall?: string): string;
+/** 由 sumi 独占的 git hook 文件（原生 git hook）。 */
+export declare function gitHookScript(command: string[], legacyInstall?: string): string;
+export interface Obligation {
+    id: string;
+    type: string;
+    target: Record<string, unknown>;
+    required: boolean;
+}
+export interface Receipt {
+    id: string;
+    outcome: ReceiptOutcome;
+    detail?: string;
+}
+export interface Finding {
+    id: string;
+    rule: string;
+    severity: Severity;
+    message: string;
+    file?: string;
+    line?: number;
+    subject?: string;
+}
+export interface Metric {
+    name: string;
+    /** 检查范围内的绝对值。 */
+    value: number;
+    /** 相对基准新增的量，改动范围运行时用于棘轮比较。 */
+    added?: number;
+}
+interface NextBase {
+    why: string;
+    /** 插件自定义的子类型标签，例如 dispatch-agent。 */
+    kind?: string;
+}
+export interface RunAction extends NextBase {
+    type: 'run';
+    argv: string[];
+    effects: Effect[];
+}
+export interface EditAction extends NextBase {
+    type: 'edit';
+    file: string;
+    line?: number;
+    intent: string;
+}
+export interface AskHumanAction extends NextBase {
+    type: 'ask-human';
+    question: string;
+    argv?: string[];
+}
+export interface StopAction extends NextBase {
+    type: 'stop';
+    reason: string;
+}
+export type NextAction = RunAction | EditAction | AskHumanAction | StopAction;
+export interface PlannedStep {
+    id: string;
+    use: string;
+    with?: Record<string, unknown>;
+    required?: boolean;
+    /** 插入位置：在某步骤实例之前或之后；都未给出时追加到流程末尾。 */
+    before?: string;
+    after?: string;
+}
+export interface Injection {
+    step: string;
+    files?: string[];
+    obligations?: Obligation[];
+    required?: boolean;
+}
+export interface Plan {
+    steps?: PlannedStep[];
+    inject?: Injection[];
+    labels?: Record<string, string>;
+}
+export interface PluginResult {
+    status: Status;
+    summary: string;
+    findings: Finding[];
+    /** 实际检查范围。 */
+    checked: 'all' | string[];
+    evidence: string[];
+    metrics?: Metric[];
+    obligations?: Receipt[];
+    next?: NextAction[];
+    /** 报告段落（Markdown）：内核原样记入运行记录，供 PR 报告等命令展示，不解释其内容。 */
+    report?: string;
+    /** 仅 planner 使用。 */
+    plan?: Plan;
+}
+export interface PluginContext {
+    repoRoot: string;
+    /** 基准提交 OID；null 表示空树。 */
+    base: string | null;
+    mode: 'worktree' | 'commit';
+    tier: string;
+    tiers: string[];
+    stepId: string;
+    config: Record<string, unknown>;
+    files: string[];
+    all: boolean;
+    obligations: Obligation[];
+    evidenceDir: string;
+    runDir: string;
+    runId: string;
+    labels: Record<string, string>;
+}
+export {};

package/node_modules/@sumi/plugin-sdk/dist/protocol.js

@@ -0,0 +1,36 @@
+/** 插件协议：内核与插件之间唯一的契约。 */
+export const STATUSES = ['pass', 'fail', 'blocked', 'skipped', 'pending'];
+export const EFFECTS = ['none', 'writes-worktree', 'writes-control', 'network', 'publish'];
+export const RECEIPT_OUTCOMES = ['passed', 'failed', 'skipped', 'not-executed'];
+/** 约定退出码：pass 为 0，fail 为 1，其余为 2。 */
+export function exitCodeFor(status) {
+    if (status === 'pass')
+        return 0;
+    if (status === 'fail')
+        return 1;
+    return 2;
+}
+/** 按方向与容差比较指标：worse / better 都只在超出容差时成立。 */
+export function compareMetric(decl, value, base) {
+    const tol = decl.tolerance ?? 0;
+    const delta = decl.direction === 'lower-is-better' ? base - value : value - base;
+    return { worse: delta < -tol, better: delta > tol };
+}
+export const HOOK_BLOCK_START = '# >>> sumi：由 sumi update 生成，请勿手改 >>>';
+export const HOOK_BLOCK_END = '# <<< sumi <<<';
+export const PROJECT_SUMI = 'node ./control/bin/sumi.cjs';
+export const PROJECT_SUMI_ARGV = ['node', './control/bin/sumi.cjs'];
+/** hook 中只调用仓库提交的 launcher，不再读取 PATH 上的全局 sumi。 */
+export function hookBlock(command, _legacyInstall) {
+    return [
+        HOOK_BLOCK_START,
+        `test -f ./control/bin/sumi.cjs || { echo "缺少项目 Sumi launcher：请用 Sumi 0.4.0 临时 CLI 重新执行 vendor" >&2; exit 1; }`,
+        `${PROJECT_SUMI} ${command.join(' ')} "$@" || exit $?`,
+        HOOK_BLOCK_END,
+    ].join('\n');
+}
+/** 由 sumi 独占的 git hook 文件（原生 git hook）。 */
+export function gitHookScript(command, legacyInstall) {
+    return `#!/bin/sh\n${hookBlock(command, legacyInstall)}\n`;
+}
+//# sourceMappingURL=protocol.js.map

package/node_modules/@sumi/plugin-sdk/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,yBAAyB;AAUzB,MAAM,CAAC,MAAM,QAAQ,GAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAC7F,MAAM,CAAC,MAAM,OAAO,GAAsB,CAAC,MAAM,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAC9G,MAAM,CAAC,MAAM,gBAAgB,GAA8B,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;AAE3G,qCAAqC;AACrC,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,CAAC,CAAC;IAChC,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,CAAC;AACX,CAAC;AASD,4CAA4C;AAC5C,MAAM,UAAU,aAAa,CAAC,IAAuB,EAAE,KAAa,EAAE,IAAY;IAChF,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,KAAK,iBAAiB,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC;IACjF,OAAO,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,GAAG,GAAG,EAAE,CAAC;AACtD,CAAC;AA6DD,MAAM,CAAC,MAAM,gBAAgB,GAAG,sCAAsC,CAAC;AACvE,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAC/C,MAAM,CAAC,MAAM,YAAY,GAAG,6BAA6B,CAAC;AAC1D,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAU,CAAC;AAE7E,mDAAmD;AACnD,MAAM,UAAU,SAAS,CAAC,OAAiB,EAAE,cAAuB;IAClE,OAAO;QACL,gBAAgB;QAChB,+GAA+G;QAC/G,GAAG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,kBAAkB;QACtD,cAAc;KACf,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,aAAa,CAAC,OAAiB,EAAE,aAAsB;IACrE,OAAO,cAAc,SAAS,CAAC,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC;AAC7D,CAAC"}

package/node_modules/@sumi/plugin-sdk/dist/rules.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 规则语句中的执行者引用：[<类型>:<目标>]，例如 [plugin:core/lint]。SDK 只定义写法，
+ * 哪些类型算执行者、目标如何校验，由使用它的插件决定。
+ */
+export interface RuleRef {
+    kind: string;
+    target: string;
+}
+/** 每次返回新的全局正则，避免共享 lastIndex。 */
+export declare function ruleRefPattern(): RegExp;
+/** 一行文本中的全部执行者引用。 */
+export declare function ruleRefs(text: string): RuleRef[];
+/** 读取约束查询命令的输入：标准输入上的 { repoRoot, paths }。 */
+export declare function readContextInput(): Promise<{
+    repoRoot: string;
+    paths: string[];
+}>;

package/node_modules/@sumi/plugin-sdk/dist/rules.js

@@ -0,0 +1,16 @@
+/** 每次返回新的全局正则，避免共享 lastIndex。 */
+export function ruleRefPattern() {
+    return /\[([a-z][a-z-]*):([^\]\s]+)\]/g;
+}
+/** 一行文本中的全部执行者引用。 */
+export function ruleRefs(text) {
+    return [...text.matchAll(ruleRefPattern())].map((m) => ({ kind: m[1], target: m[2] }));
+}
+/** 读取约束查询命令的输入：标准输入上的 { repoRoot, paths }。 */
+export async function readContextInput() {
+    let text = '';
+    for await (const chunk of process.stdin)
+        text += chunk;
+    return JSON.parse(text);
+}
+//# sourceMappingURL=rules.js.map

package/node_modules/@sumi/plugin-sdk/dist/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AASA,iCAAiC;AACjC,MAAM,UAAU,cAAc;IAC5B,OAAO,gCAAgC,CAAC;AAC1C,CAAC;AAED,qBAAqB;AACrB,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,8CAA8C;AAC9C,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK;QAAE,IAAI,IAAI,KAAK,CAAC;IACvD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAA0C,CAAC;AACnE,CAAC"}

package/node_modules/@sumi/plugin-sdk/dist/sdk.d.ts

@@ -0,0 +1,12 @@
+import { type PluginContext, type PluginResult } from './protocol.js';
+/** 结果中保留的 findings 上限。 */
+export declare const MAX_FINDINGS = 500;
+/** 结果的便捷构造：只需给出 status 与 summary，其余字段取空值。 */
+export declare function result(partial: Partial<PluginResult> & Pick<PluginResult, 'status' | 'summary'>): PluginResult;
+/** 把内容写入本步骤的证据目录，返回相对仓库根的路径。 */
+export declare function writeEvidence(ctx: PluginContext, name: string, content: string): string;
+/**
+ * 插件入口：读取 stdin 上下文，调用处理函数，按约定写出结果并设置退出码。
+ * 处理函数抛出的异常转为 blocked 结果。
+ */
+export declare function definePlugin(handler: (ctx: PluginContext) => Promise<PluginResult> | PluginResult): Promise<void>;

package/node_modules/@sumi/plugin-sdk/dist/sdk.js

@@ -0,0 +1,51 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { exitCodeFor } from './protocol.js';
+/** 结果中保留的 findings 上限。 */
+export const MAX_FINDINGS = 500;
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** 结果的便捷构造：只需给出 status 与 summary，其余字段取空值。 */
+export function result(partial) {
+    return { findings: [], checked: [], evidence: [], ...partial };
+}
+/** 把内容写入本步骤的证据目录，返回相对仓库根的路径。 */
+export function writeEvidence(ctx, name, content) {
+    mkdirSync(ctx.evidenceDir, { recursive: true });
+    const path = join(ctx.evidenceDir, name);
+    writeFileSync(path, content);
+    return path;
+}
+/**
+ * 插件入口：读取 stdin 上下文，调用处理函数，按约定写出结果并设置退出码。
+ * 处理函数抛出的异常转为 blocked 结果。
+ */
+export async function definePlugin(handler) {
+    let output;
+    let ctx;
+    try {
+        ctx = JSON.parse(await readStdin());
+        output = await handler(ctx);
+    }
+    catch (error) {
+        output = result({ status: 'blocked', summary: `插件异常：${error.message}` });
+    }
+    // findings 过多时只在结果中保留前 MAX_FINDINGS 条，完整列表写入证据，避免结果超过内核的输出上限。
+    if (ctx && output.findings.length > MAX_FINDINGS) {
+        const all = output.findings;
+        const path = writeEvidence(ctx, 'findings.json', JSON.stringify(all, null, 2));
+        output = {
+            ...output,
+            findings: all.slice(0, MAX_FINDINGS),
+            evidence: [...output.evidence, path],
+            summary: `${output.summary}（共 ${all.length} 条，结果中保留前 ${MAX_FINDINGS} 条）`,
+        };
+    }
+    process.stdout.write(JSON.stringify(output));
+    process.exitCode = exitCodeFor(output.status);
+}
+//# sourceMappingURL=sdk.js.map

package/node_modules/@sumi/plugin-sdk/dist/sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.js","sourceRoot":"","sources":["../src/sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAyC,MAAM,eAAe,CAAC;AAEnF,0BAA0B;AAC1B,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAEhC,KAAK,UAAU,SAAS;IACtB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK;QAAE,MAAM,CAAC,IAAI,CAAC,KAAe,CAAC,CAAC;IACtE,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,MAAM,CAAC,OAAyE;IAC9F,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC;AACjE,CAAC;AAED,gCAAgC;AAChC,MAAM,UAAU,aAAa,CAAC,GAAkB,EAAE,IAAY,EAAE,OAAe;IAC7E,SAAS,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IACzC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7B,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAqE;IACtG,IAAI,MAAoB,CAAC;IACzB,IAAI,GAA8B,CAAC;IACnC,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,SAAS,EAAE,CAAkB,CAAC;QACrD,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,MAAM,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,QAAS,KAAe,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,8DAA8D;IAC9D,IAAI,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC;QAC5B,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC/E,MAAM,GAAG;YACP,GAAG,MAAM;YACT,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC;YACpC,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC;YACpC,OAAO,EAAE,GAAG,MAAM,CAAC,OAAO,MAAM,GAAG,CAAC,MAAM,aAAa,YAAY,KAAK;SACzE,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7C,OAAO,CAAC,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAChD,CAAC"}

package/node_modules/@sumi/plugin-sdk/dist/tool-batches.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Windows 的 .cmd shim 会经过命令解释器；给引号、转义和 shim 前缀保留余量。
+ * 所有平台共用该预算，使长列表行为可重复测试。
+ */
+export declare const FILE_TOOL_COMMAND_BUDGET = 6000;
+export declare function estimateCommandSize(command: string, args: string[]): number;
+/**
+ * 保持原顺序把文件参数拆成可安全启动的批次。
+ * 固定参数或单个文件无法放入空批时直接拒绝，避免工具收到截断列表。
+ */
+export declare function splitFileArguments(command: string, fixedArgs: string[], files: string[], budget?: number): string[][];

package/node_modules/@sumi/plugin-sdk/dist/tool-batches.js

@@ -0,0 +1,41 @@
+/**
+ * Windows 的 .cmd shim 会经过命令解释器；给引号、转义和 shim 前缀保留余量。
+ * 所有平台共用该预算，使长列表行为可重复测试。
+ */
+export const FILE_TOOL_COMMAND_BUDGET = 6_000;
+const SHELL_OVERHEAD = 128;
+/** 按 UTF-8 字节数的两倍保守估算参数经 shell 引号与转义后的占用。 */
+function estimateArgumentSize(value) {
+    return Buffer.byteLength(value, 'utf8') * 2 + 8;
+}
+export function estimateCommandSize(command, args) {
+    return [command, ...args].reduce((size, value) => size + estimateArgumentSize(value), SHELL_OVERHEAD);
+}
+/**
+ * 保持原顺序把文件参数拆成可安全启动的批次。
+ * 固定参数或单个文件无法放入空批时直接拒绝，避免工具收到截断列表。
+ */
+export function splitFileArguments(command, fixedArgs, files, budget = FILE_TOOL_COMMAND_BUDGET) {
+    if (!Number.isSafeInteger(budget) || budget <= 0)
+        throw new Error(`无效的命令参数安全预算：${budget}`);
+    const fixedSize = estimateCommandSize(command, fixedArgs);
+    if (fixedSize > budget)
+        throw new Error(`工具固定参数超过安全预算：${command}`);
+    if (files.length === 0)
+        return [[]];
+    const batches = [];
+    let batch = [];
+    for (const file of files) {
+        if (estimateCommandSize(command, [...fixedArgs, file]) > budget) {
+            throw new Error(`单个文件参数超过安全预算：${file}`);
+        }
+        if (batch.length > 0 && estimateCommandSize(command, [...fixedArgs, ...batch, file]) > budget) {
+            batches.push(batch);
+            batch = [];
+        }
+        batch.push(file);
+    }
+    batches.push(batch);
+    return batches;
+}
+//# sourceMappingURL=tool-batches.js.map

package/node_modules/@sumi/plugin-sdk/dist/tool-batches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-batches.js","sourceRoot":"","sources":["../src/tool-batches.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,CAAC;AAE9C,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B,6CAA6C;AAC7C,SAAS,oBAAoB,CAAC,KAAa;IACzC,OAAO,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAE,IAAc;IACjE,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,GAAG,oBAAoB,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC,CAAC;AACxG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,SAAmB,EAAE,KAAe,EAAE,MAAM,GAAG,wBAAwB;IACzH,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,eAAe,MAAM,EAAE,CAAC,CAAC;IAC3F,MAAM,SAAS,GAAG,mBAAmB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC1D,IAAI,SAAS,GAAG,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,OAAO,EAAE,CAAC,CAAC;IACnE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IAEpC,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,IAAI,KAAK,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,mBAAmB,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,EAAE,IAAI,CAAC,CAAC,GAAG,MAAM,EAAE,CAAC;YAChE,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,mBAAmB,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,EAAE,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,MAAM,EAAE,CAAC;YAC9F,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,GAAG,EAAE,CAAC;QACb,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpB,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/node_modules/@sumi/plugin-sdk/dist/validate.d.ts

@@ -0,0 +1,8 @@
+import { type PluginDeclaration, type PluginResult } from './protocol.js';
+/** 校验函数只返回错误列表，空数组表示合法。 */
+type Errors = string[];
+export declare function validateDeclaration(value: unknown): Errors;
+export declare function validateResult(value: unknown, kind?: 'check' | 'planner'): Errors;
+export declare function assertDeclaration(value: unknown): PluginDeclaration;
+export declare function assertResult(value: unknown): PluginResult;
+export {};

package/node_modules/@sumi/plugin-sdk/dist/validate.js

@@ -0,0 +1,221 @@
+import { EFFECTS, RECEIPT_OUTCOMES, STATUSES } from './protocol.js';
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
+const nonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+export function validateDeclaration(value) {
+    const errors = [];
+    if (!isObject(value))
+        return ['声明必须是对象'];
+    for (const key of ['id', 'version']) {
+        if (!nonEmptyString(value[key]))
+            errors.push(`缺少字段 ${key}`);
+    }
+    // 三种形态：可执行插件（command）、派生插件（base，沿用其命令）、只提供命令与 hook 的插件。
+    const derived = value.base !== undefined;
+    const commandOnly = !derived && value.command === undefined && (value.commands !== undefined || value.hooks !== undefined);
+    if (derived) {
+        if (!nonEmptyString(value.base))
+            errors.push('base 必须是插件 id');
+        if (value.command !== undefined)
+            errors.push('派生插件不能声明 command');
+        if (value.kind !== undefined && value.kind !== 'check' && value.kind !== 'planner')
+            errors.push('kind 必须为 check 或 planner');
+        if (value.timeout !== undefined && (typeof value.timeout !== 'number' || value.timeout <= 0))
+            errors.push('timeout 必须是正数');
+    }
+    else if (!commandOnly) {
+        if (value.kind !== 'check' && value.kind !== 'planner')
+            errors.push('kind 必须为 check 或 planner');
+        if (!isStringArray(value.command) || value.command.length === 0)
+            errors.push('缺少字段 command');
+        if (typeof value.timeout !== 'number' || value.timeout <= 0)
+            errors.push('缺少字段 timeout');
+    }
+    if (value.with !== undefined && !isObject(value.with))
+        errors.push('with 必须是对象');
+    if (value.description !== undefined && !nonEmptyString(value.description))
+        errors.push('description 必须是字符串');
+    if (value.context !== undefined && !nonEmptyString(value.context))
+        errors.push('context 必须是命令名');
+    if (value.triggers !== undefined && !isStringArray(value.triggers))
+        errors.push('triggers 必须是字符串数组');
+    if (value.minTier !== undefined && !nonEmptyString(value.minTier))
+        errors.push('minTier 必须是字符串');
+    if (value.fix !== undefined && (!isStringArray(value.fix) || value.fix.length === 0)) {
+        errors.push('fix 必须是非空字符串数组');
+    }
+    if (value.requires !== undefined && !isStringArray(value.requires))
+        errors.push('requires 必须是字符串数组');
+    if (value.needs !== undefined) {
+        if (!isObject(value.needs))
+            errors.push('needs 必须是对象');
+        else
+            for (const key of ['bin', 'files']) {
+                if (value.needs[key] !== undefined && !isStringArray(value.needs[key]))
+                    errors.push(`needs.${key} 必须是字符串数组`);
+            }
+    }
+    if (value.metrics !== undefined) {
+        if (!Array.isArray(value.metrics))
+            errors.push('metrics 必须是数组');
+        else
+            value.metrics.forEach((m, i) => {
+                if (!isObject(m) || !nonEmptyString(m.name))
+                    errors.push(`metrics[${i}] 缺少 name`);
+                else if (m.direction !== 'lower-is-better' && m.direction !== 'higher-is-better') {
+                    errors.push(`metrics[${i}] direction 非法`);
+                }
+                else if (m.tolerance !== undefined && (typeof m.tolerance !== 'number' || m.tolerance < 0)) {
+                    errors.push(`metrics[${i}] tolerance 必须是非负数`);
+                }
+            });
+    }
+    if (value.hooks !== undefined) {
+        const hooks = value.hooks;
+        const git = hooks?.git;
+        const agent = hooks?.agent;
+        if (!isObject(hooks))
+            errors.push('hooks 必须是对象');
+        else if (git !== undefined && (!isObject(git) || !Object.values(git).every(nonEmptyString)))
+            errors.push('hooks.git 必须是 hook 名称到命令名的映射');
+        else if (agent !== undefined && !isObject(agent))
+            errors.push('hooks.agent 必须是对象');
+        else {
+            for (const key of ['beforeTool', 'afterEdit', 'stop']) {
+                if (agent?.[key] !== undefined && !nonEmptyString(agent[key]))
+                    errors.push(`hooks.agent.${key} 必须是命令名`);
+            }
+        }
+    }
+    // hook 与约束查询只能调用本插件注册的命令。
+    {
+        const hooks = (isObject(value.hooks) ? value.hooks : {});
+        const git = isObject(hooks.git) ? hooks.git : {};
+        const agent = (isObject(hooks.agent) ? hooks.agent : {});
+        const registered = new Set(Array.isArray(value.commands) ? value.commands.map((c) => c?.name) : []);
+        const referenced = [...Object.values(git), agent.beforeTool, agent.afterEdit, agent.stop, value.context].filter(nonEmptyString);
+        for (const name of referenced) {
+            if (!registered.has(name))
+                errors.push(`hook 或约束查询引用的命令 ${name} 未在 commands 中注册`);
+        }
+    }
+    if (value.instructions !== undefined && (!isObject(value.instructions) || !Object.values(value.instructions).every(nonEmptyString))) {
+        errors.push('instructions 必须是主题名到指令文件的映射');
+    }
+    if (value.afterInit !== undefined && (!isStringArray(value.afterInit) || value.afterInit.length === 0))
+        errors.push('afterInit 必须是非空字符串数组');
+    if (value.commands !== undefined) {
+        if (!Array.isArray(value.commands))
+            errors.push('commands 必须是数组');
+        else
+            value.commands.forEach((c, i) => {
+                if (!isObject(c) || !nonEmptyString(c.name) || !isStringArray(c.argv) || c.argv.length === 0) {
+                    errors.push(`commands[${i}] 需要 name 与 argv`);
+                }
+            });
+    }
+    return errors;
+}
+function validateNext(next, errors) {
+    if (!Array.isArray(next)) {
+        errors.push('next 必须是数组');
+        return;
+    }
+    next.forEach((a, i) => {
+        const at = `next[${i}]`;
+        if (!isObject(a) || !nonEmptyString(a.why)) {
+            errors.push(`${at} 缺少 why`);
+            return;
+        }
+        switch (a.type) {
+            case 'run':
+                if (!isStringArray(a.argv) || a.argv.length === 0)
+                    errors.push(`${at} 缺少 argv`);
+                if (!isStringArray(a.effects) || a.effects.length === 0 || !a.effects.every((e) => EFFECTS.includes(e))) {
+                    errors.push(`${at} effects 非法`);
+                }
+                break;
+            case 'edit':
+                if (!nonEmptyString(a.file) || !nonEmptyString(a.intent))
+                    errors.push(`${at} 需要 file 与 intent`);
+                break;
+            case 'ask-human':
+                if (!nonEmptyString(a.question))
+                    errors.push(`${at} 缺少 question`);
+                if (a.argv !== undefined && !isStringArray(a.argv))
+                    errors.push(`${at} argv 非法`);
+                break;
+            case 'stop':
+                if (!nonEmptyString(a.reason))
+                    errors.push(`${at} 缺少 reason`);
+                break;
+            default:
+                errors.push(`${at} type 非法`);
+        }
+    });
+}
+export function validateResult(value, kind = 'check') {
+    const errors = [];
+    if (!isObject(value))
+        return ['结果必须是对象'];
+    if (!STATUSES.includes(value.status))
+        errors.push('status 非法');
+    if (typeof value.summary !== 'string')
+        errors.push('缺少 summary');
+    if (!Array.isArray(value.findings))
+        errors.push('findings 必须是数组');
+    else
+        value.findings.forEach((f, i) => {
+            if (!isObject(f) || !nonEmptyString(f.id) || !nonEmptyString(f.rule) || typeof f.message !== 'string') {
+                errors.push(`findings[${i}] 需要 id、rule、message`);
+                return;
+            }
+            if (f.severity !== 'error' && f.severity !== 'warning' && f.severity !== 'info') {
+                errors.push(`findings[${i}] severity 非法`);
+            }
+        });
+    if (value.checked !== 'all' && !isStringArray(value.checked))
+        errors.push('checked 必须为 all 或文件列表');
+    if (!isStringArray(value.evidence))
+        errors.push('evidence 必须是字符串数组');
+    if (value.metrics !== undefined) {
+        if (!Array.isArray(value.metrics))
+            errors.push('metrics 必须是数组');
+        else
+            value.metrics.forEach((m, i) => {
+                if (!isObject(m) || !nonEmptyString(m.name) || typeof m.value !== 'number') {
+                    errors.push(`metrics[${i}] 需要 name 与数值 value`);
+                }
+            });
+    }
+    if (value.obligations !== undefined) {
+        if (!Array.isArray(value.obligations))
+            errors.push('obligations 必须是数组');
+        else
+            value.obligations.forEach((r, i) => {
+                if (!isObject(r) || !nonEmptyString(r.id) || !RECEIPT_OUTCOMES.includes(r.outcome)) {
+                    errors.push(`obligations[${i}] 回执非法`);
+                }
+            });
+    }
+    if (value.next !== undefined)
+        validateNext(value.next, errors);
+    if (value.report !== undefined && typeof value.report !== 'string')
+        errors.push('report 必须是字符串');
+    if (value.plan !== undefined && kind !== 'planner')
+        errors.push('只有 planner 可以返回 plan');
+    return errors;
+}
+export function assertDeclaration(value) {
+    const errors = validateDeclaration(value);
+    if (errors.length)
+        throw new Error(errors.join('；'));
+    return value;
+}
+export function assertResult(value) {
+    const errors = validateResult(value);
+    if (errors.length)
+        throw new Error(errors.join('；'));
+    return value;
+}
+//# sourceMappingURL=validate.js.map