@xcompiler/cli 0.2.2

package/dist/plugins/index.d.ts

@@ -0,0 +1,809 @@
+import { z } from 'zod';
+
+/**
+ * AuditLogger 把开发流水线中的所有交互/执行动作记录到两份产物：
+ *
+ *  - `docs/process_log.md` —— 人类可读的过程记录，用于交付时汇总。
+ *  - `.xcompiler/audit.jsonl`   —— 机器可读的逐行 JSON，便于后续分析与回放。
+ *
+ * 设计原则：
+ *  - 追加写入，永不删除。
+ *  - 失败时不影响主流程（写盘异常仅打印 warning）。
+ *  - 每条事件都带 ts / kind / payload。
+ */
+type AuditKind = 'session.start' | 'session.end' | 'user.input' | 'user.decision' | 'llm.request' | 'llm.response' | 'llm.error' | 'llm.score' | 'fs.write' | 'plan.persist' | 'topic.persist' | 'phase.start' | 'phase.end' | 'tool.call' | 'tool.result' | 'sandbox.exec' | 'executor.turn' | 'planner.thought' | 'conftest.autogen' | 'issue.record' | 'issue.route' | 'issue.resolve' | 'note';
+interface AuditLoggerOptions {
+    /** workspace 根目录（绝对路径） */
+    root: string;
+    /** 命令名，例如 `xcompiler_build` / `xcompiler_run` */
+    command: string;
+    /** markdown 文件相对路径，默认 docs/process_log.md */
+    mdRelPath?: string;
+    /** jsonl 文件相对路径，默认 .xcompiler/audit.jsonl */
+    jsonlRelPath?: string;
+    /** full=完整内容；redacted=保留内容但遮蔽凭据（默认）；metadata=仅保留长度与摘要。 */
+    contentMode?: AuditContentMode;
+}
+type AuditContentMode = 'full' | 'redacted' | 'metadata';
+declare class AuditLogger {
+    private readonly mdAbs;
+    private readonly jsonlAbs;
+    private readonly command;
+    private readonly contentMode;
+    private startTs;
+    /** 串行化 markdown 追加，防止并发 appendFile 交错。 */
+    private mdQueue;
+    constructor(opts: AuditLoggerOptions);
+    start(meta?: Record<string, unknown>): Promise<void>;
+    end(summary?: Record<string, unknown>): Promise<void>;
+    /** 通用事件，jsonl + 简短 markdown 一行。 */
+    event(kind: AuditKind, message: string, data?: Record<string, unknown>): Promise<void>;
+    /** 用户输入 / 决策。会把内容以引用块写入 markdown。 */
+    userInput(label: string, content: string): Promise<void>;
+    userDecision(label: string, value: string): Promise<void>;
+    /** LLM 请求/响应：完整 prompt 与回包写入 markdown 折叠块。 */
+    llmRequest(role: string, model: string, messages: unknown, options?: unknown): Promise<void>;
+    llmResponse(role: string, model: string, content: string, meta?: Record<string, unknown>): Promise<void>;
+    llmError(role: string, model: string, err: unknown): Promise<void>;
+    /**
+     * 记录一轮 Executor 思考：thoughts 文本、计划调用的 actions、是否完成。
+     * 写入 jsonl + markdown 折叠块，交付时可作为"AI 思考过程完整记录"。
+     */
+    executorTurn(stepId: string, role: string, round: number, payload: {
+        thoughts?: string;
+        actions?: unknown[];
+        done?: boolean;
+        raw?: string;
+        provider?: string;
+    }): Promise<void>;
+    /** 记录 Planner 的思考阶段，比如 clarify / decompose 原始输出。 */
+    plannerThought(stage: string, content: string, meta?: Record<string, unknown> & {
+        provider?: string;
+    }): Promise<void>;
+    private ensureFiles;
+    private appendMd;
+    private appendJsonl;
+}
+
+type ChatRole = 'system' | 'user' | 'assistant';
+interface ChatMessage {
+    role: ChatRole;
+    content: string;
+}
+interface ChatOptions {
+    temperature?: number;
+    maxTokens?: number;
+    /** Force JSON-only response if provider supports it. */
+    responseFormat?: 'text' | 'json';
+    /**
+     * 流式 token 回调。设置后 provider 会以增量方式推送 token；
+     * provider 仍会聚合并返回完整文本作为最终结果。
+     */
+    onToken?: (chunk: string) => void;
+    /**
+     * 流式模式下的“可提前结束”判定。用于兼容一些 provider：
+     * 输出内容本身已经完整，但既不及时发送 [DONE]，也不主动断开连接。
+     * 返回 true 后 provider 应尽快结束本次流读取并返回当前 aggregate。
+     */
+    streamStopWhen?: (text: string) => boolean;
+    /**
+     * 可选验证钩子：provider 返回后调用。抛异常会被 FallbackClient
+     * 视为该 provider 失败，并切换到下一个。适用于：JSON 退化、
+     * 空输出、model token loop 等“表面成功但语义不可用”场景。
+     */
+    validate?: (text: string) => void;
+    /**
+     * 调用者可传入回调，与 LLM 输出一同拿到实际产出该响应的 provider 名。
+     * 主要用于追溯：在 FallbackClient 中服务于响应的是链中某一个后选 provider，
+     * 调用者（如 Executor）需要在审计 / Markdown 记录中为响应打上正确的“via 哪个模型”标签。
+     */
+    onProvider?: (name: string) => void;
+    /**
+     * 每次开始尝试候选 provider 时触发。用于 CLI 在等待首个 token 前显示
+     * 当前 provider 与模型；fallback 切换时会再次触发。
+     */
+    onProviderStart?: (name: string, model: string) => void;
+}
+interface LLMClient {
+    readonly name: string;
+    chat(messages: ChatMessage[], options?: ChatOptions): Promise<string>;
+}
+
+declare class Workspace {
+    readonly root: string;
+    constructor(root: string);
+    abs(...p: string[]): string;
+    ensure(dir: string): Promise<void>;
+    writeFile(rel: string, content: string): Promise<void>;
+    readFile(rel: string): Promise<string>;
+    exists(rel: string): Promise<boolean>;
+    remove(rel: string): Promise<void>;
+}
+
+interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    durationMs: number;
+}
+interface ExecExtra {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+}
+/** 沙盒统一接口。任意 phase / tool 都通过此接口与运行时交互。 */
+interface Sandbox {
+    /** 实现标识，便于审计与日志区分。 */
+    readonly kind: 'subprocess' | 'docker';
+    /**
+     * 构建/复用环境。
+     *  - Python：`pip install -r requirements.txt` + venv。
+     *  - TypeScript：`npm install`（依据 package.json）。
+     * manifestFile 为依赖清单在 workspace 内的相对路径；不存在则跳过安装。
+     * 返回是否真正重建。
+     */
+    build(manifestFile?: string): Promise<{
+        rebuilt: boolean;
+        reason: string;
+    }>;
+    /** 执行任意命令；cmd 视实现可能是宿主路径或容器内路径。 */
+    exec(cmd: string, argv: string[], extra?: ExecExtra): Promise<ExecResult>;
+    /**
+     * 运行工程入口程序。
+     *  - Python：`python <args>`（自动选用 venv 内解释器）。
+     *  - TypeScript：`npx tsx <args>`。
+     */
+    runProgram(args: string[], extra?: ExecExtra): Promise<ExecResult>;
+    /**
+     * 运行测试套件。
+     *  - Python：`python -m pytest <args>`。
+     *  - TypeScript：`npm test`（Vitest）。
+     */
+    runTests(args?: string[], extra?: ExecExtra): Promise<ExecResult>;
+    /**
+     * 安装额外依赖（不写入依赖清单）。
+     *  - Python：`pip install <packages>`。
+     *  - TypeScript：`npm install <packages>`。
+     */
+    installDeps(packages: string[]): Promise<ExecResult>;
+}
+
+/** Supported target languages for generated projects. */
+declare const LANGUAGES: readonly ["python", "typescript"];
+type Language = (typeof LANGUAGES)[number];
+/** Plan intent: greenfield generation, incremental work, or isolated self-bootstrap. */
+declare const PLAN_INTENTS: readonly ["greenfield", "feature", "refactor", "self"];
+type PlanIntent = (typeof PLAN_INTENTS)[number];
+declare const ROLES: readonly ["Planner", "Architect", "Coder", "Tester", "Debugger"];
+type Role = (typeof ROLES)[number];
+interface StepSubtask {
+    id: string;
+    title: string;
+    description: string;
+    acceptance?: string;
+    outputs?: string[];
+    subTasks?: StepSubtask[];
+}
+declare const StepSchema: z.ZodObject<{
+    id: z.ZodString;
+    iterationId: z.ZodDefault<z.ZodString>;
+    phase: z.ZodEnum<{
+        REQUIREMENT_ANALYSIS: "REQUIREMENT_ANALYSIS";
+        HIGH_LEVEL_DESIGN: "HIGH_LEVEL_DESIGN";
+        DETAILED_DESIGN: "DETAILED_DESIGN";
+        CODE: "CODE";
+        UNIT_TEST: "UNIT_TEST";
+        INTEGRATION_TEST: "INTEGRATION_TEST";
+        MODULE_TEST: "MODULE_TEST";
+        FUNCTIONAL_TEST: "FUNCTIONAL_TEST";
+        DEBUG: "DEBUG";
+    }>;
+    title: z.ZodString;
+    description: z.ZodString;
+    systemPrompt: z.ZodString;
+    role: z.ZodEnum<{
+        Planner: "Planner";
+        Architect: "Architect";
+        Coder: "Coder";
+        Tester: "Tester";
+        Debugger: "Debugger";
+    }>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    inputs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    outputs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    subTasks: z.ZodOptional<z.ZodArray<z.ZodType<StepSubtask, unknown, z.core.$ZodTypeInternals<StepSubtask, unknown>>>>;
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    acceptance: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<{
+        PENDING: "PENDING";
+        RUNNING: "RUNNING";
+        DONE: "DONE";
+        FAILED: "FAILED";
+        SKIPPED: "SKIPPED";
+    }>>;
+    retries: z.ZodDefault<z.ZodNumber>;
+    maxRetries: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type Step = z.infer<typeof StepSchema>;
+declare const PlanSchema: z.ZodPipe<z.ZodObject<{
+    version: z.ZodLiteral<"1">;
+    language: z.ZodDefault<z.ZodEnum<{
+        python: "python";
+        typescript: "typescript";
+    }>>;
+    intent: z.ZodDefault<z.ZodEnum<{
+        greenfield: "greenfield";
+        feature: "feature";
+        refactor: "refactor";
+        self: "self";
+    }>>;
+    projectType: z.ZodDefault<z.ZodEnum<{
+        application: "application";
+        library: "library";
+        mixed: "mixed";
+    }>>;
+    requirementDigest: z.ZodString;
+    complexityAssessment: z.ZodOptional<z.ZodObject<{
+        level: z.ZodEnum<{
+            simple: "simple";
+            moderate: "moderate";
+            complex: "complex";
+        }>;
+        rationale: z.ZodString;
+        splitRecommended: z.ZodDefault<z.ZodBoolean>;
+        userForcedPhaseSplit: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    implementationPhases: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        objective: z.ZodString;
+        status: z.ZodDefault<z.ZodEnum<{
+            current: "current";
+            planned: "planned";
+            deferred: "deferred";
+        }>>;
+        scope: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        deliverables: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        verificationGate: z.ZodOptional<z.ZodObject<{
+            summary: z.ZodString;
+            checks: z.ZodArray<z.ZodString>;
+            failurePolicy: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    architectureModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        responsibility: z.ZodString;
+        sourcePaths: z.ZodArray<z.ZodString>;
+        testPaths: z.ZodArray<z.ZodString>;
+        dependencies: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    globalPrompt: z.ZodDefault<z.ZodString>;
+    baselineSummary: z.ZodDefault<z.ZodString>;
+    dependencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    pythonRequirements: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    userAddenda: z.ZodDefault<z.ZodString>;
+    createdAt: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        iterationId: z.ZodDefault<z.ZodString>;
+        phase: z.ZodEnum<{
+            REQUIREMENT_ANALYSIS: "REQUIREMENT_ANALYSIS";
+            HIGH_LEVEL_DESIGN: "HIGH_LEVEL_DESIGN";
+            DETAILED_DESIGN: "DETAILED_DESIGN";
+            CODE: "CODE";
+            UNIT_TEST: "UNIT_TEST";
+            INTEGRATION_TEST: "INTEGRATION_TEST";
+            MODULE_TEST: "MODULE_TEST";
+            FUNCTIONAL_TEST: "FUNCTIONAL_TEST";
+            DEBUG: "DEBUG";
+        }>;
+        title: z.ZodString;
+        description: z.ZodString;
+        systemPrompt: z.ZodString;
+        role: z.ZodEnum<{
+            Planner: "Planner";
+            Architect: "Architect";
+            Coder: "Coder";
+            Tester: "Tester";
+            Debugger: "Debugger";
+        }>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        inputs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        outputs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        subTasks: z.ZodOptional<z.ZodArray<z.ZodType<StepSubtask, unknown, z.core.$ZodTypeInternals<StepSubtask, unknown>>>>;
+        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        acceptance: z.ZodString;
+        status: z.ZodDefault<z.ZodEnum<{
+            PENDING: "PENDING";
+            RUNNING: "RUNNING";
+            DONE: "DONE";
+            FAILED: "FAILED";
+            SKIPPED: "SKIPPED";
+        }>>;
+        retries: z.ZodDefault<z.ZodNumber>;
+        maxRetries: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodTransform<{
+    dependencies: string[];
+    version: "1";
+    language: "python" | "typescript";
+    intent: "greenfield" | "feature" | "refactor" | "self";
+    projectType: "application" | "library" | "mixed";
+    requirementDigest: string;
+    globalPrompt: string;
+    baselineSummary: string;
+    userAddenda: string;
+    createdAt: string;
+    steps: {
+        id: string;
+        iterationId: string;
+        phase: "REQUIREMENT_ANALYSIS" | "HIGH_LEVEL_DESIGN" | "DETAILED_DESIGN" | "CODE" | "UNIT_TEST" | "INTEGRATION_TEST" | "MODULE_TEST" | "FUNCTIONAL_TEST" | "DEBUG";
+        title: string;
+        description: string;
+        systemPrompt: string;
+        role: "Planner" | "Architect" | "Coder" | "Tester" | "Debugger";
+        tools: string[];
+        inputs: string[];
+        outputs: string[];
+        dependsOn: string[];
+        acceptance: string;
+        status: "PENDING" | "RUNNING" | "DONE" | "FAILED" | "SKIPPED";
+        retries: number;
+        maxRetries: number;
+        subTasks?: StepSubtask[] | undefined;
+    }[];
+    complexityAssessment?: {
+        level: "simple" | "moderate" | "complex";
+        rationale: string;
+        splitRecommended: boolean;
+        userForcedPhaseSplit: boolean;
+    } | undefined;
+    implementationPhases?: {
+        id: string;
+        title: string;
+        objective: string;
+        status: "current" | "planned" | "deferred";
+        scope: string[];
+        deliverables: string[];
+        dependsOn: string[];
+        verificationGate?: {
+            summary: string;
+            checks: string[];
+            failurePolicy: string;
+        } | undefined;
+    }[] | undefined;
+    architectureModules?: {
+        id: string;
+        name: string;
+        responsibility: string;
+        sourcePaths: string[];
+        testPaths: string[];
+        dependencies: string[];
+    }[] | undefined;
+}, {
+    version: "1";
+    language: "python" | "typescript";
+    intent: "greenfield" | "feature" | "refactor" | "self";
+    projectType: "application" | "library" | "mixed";
+    requirementDigest: string;
+    globalPrompt: string;
+    baselineSummary: string;
+    userAddenda: string;
+    createdAt: string;
+    steps: {
+        id: string;
+        iterationId: string;
+        phase: "REQUIREMENT_ANALYSIS" | "HIGH_LEVEL_DESIGN" | "DETAILED_DESIGN" | "CODE" | "UNIT_TEST" | "INTEGRATION_TEST" | "MODULE_TEST" | "FUNCTIONAL_TEST" | "DEBUG";
+        title: string;
+        description: string;
+        systemPrompt: string;
+        role: "Planner" | "Architect" | "Coder" | "Tester" | "Debugger";
+        tools: string[];
+        inputs: string[];
+        outputs: string[];
+        dependsOn: string[];
+        acceptance: string;
+        status: "PENDING" | "RUNNING" | "DONE" | "FAILED" | "SKIPPED";
+        retries: number;
+        maxRetries: number;
+        subTasks?: StepSubtask[] | undefined;
+    }[];
+    complexityAssessment?: {
+        level: "simple" | "moderate" | "complex";
+        rationale: string;
+        splitRecommended: boolean;
+        userForcedPhaseSplit: boolean;
+    } | undefined;
+    implementationPhases?: {
+        id: string;
+        title: string;
+        objective: string;
+        status: "current" | "planned" | "deferred";
+        scope: string[];
+        deliverables: string[];
+        dependsOn: string[];
+        verificationGate?: {
+            summary: string;
+            checks: string[];
+            failurePolicy: string;
+        } | undefined;
+    }[] | undefined;
+    architectureModules?: {
+        id: string;
+        name: string;
+        responsibility: string;
+        sourcePaths: string[];
+        testPaths: string[];
+        dependencies: string[];
+    }[] | undefined;
+    dependencies?: string[] | undefined;
+    pythonRequirements?: string[] | undefined;
+}>>;
+type Plan = z.infer<typeof PlanSchema>;
+
+type ToolPermissionOperation = 'shell_command' | 'file_write' | 'file_delete' | 'install_dependency' | 'config_change' | 'git_operation' | 'network_access' | 'test_command' | 'build_command' | 'external_read' | 'external_write';
+interface ToolPermissionRequest {
+    id?: string;
+    operationType: ToolPermissionOperation;
+    target: string;
+    reason: string;
+    risk: string;
+    scope: string;
+    skippable: boolean;
+    denyBehavior: string;
+    stepId?: string;
+    tool?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ToolPermissionDecision {
+    approved: boolean;
+    reason?: string;
+}
+type ToolPermissionRequester = (request: ToolPermissionRequest) => Promise<ToolPermissionDecision>;
+interface ToolExecutionEvent {
+    status: 'started' | 'completed';
+    stepId: string;
+    tool: string;
+    target?: string;
+    args?: Record<string, unknown>;
+    ok?: boolean;
+    summary?: string;
+    error?: string;
+    changedFiles?: string[];
+    patch?: string;
+}
+type ToolExecutionReporter = (event: ToolExecutionEvent) => void | Promise<void>;
+/** 工具调用的统一上下文。 */
+interface ToolContext {
+    ws: Workspace;
+    sandbox: Sandbox;
+    audit?: AuditLogger;
+    /** 当前 Step 的 outputs 白名单（写操作必须落在白名单内）。 */
+    allowedWrites: string[];
+    /** 当前 Step 的 id（仅用于审计）。 */
+    stepId: string;
+    /** 目标语言（决定依赖清单文件等）。默认 python。 */
+    language?: Language;
+    /** 当前 Step 的 write_file / append_file 单次 content 字节预算。 */
+    writeChunkBytes?: number;
+    /** Optional protocol/UI permission hook for sensitive tool operations. */
+    requestPermission?: ToolPermissionRequester;
+    /** Optional protocol/UI event hook for tool calls and file changes. */
+    onToolEvent?: ToolExecutionReporter;
+}
+/** 单次工具调用的结果统一结构。 */
+interface ToolResult<T = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: string;
+    /** 用于摘要展示。 */
+    summary?: string;
+}
+interface Tool<A = unknown, R = unknown> {
+    readonly name: string;
+    readonly description: string;
+    /** 简要 JSON Schema 描述参数（仅用于 prompt，不强校验）。 */
+    readonly argsSchema: Record<string, unknown>;
+    run(args: A, ctx: ToolContext): Promise<ToolResult<R>>;
+}
+
+declare const CLARIFICATION_CATEGORIES: readonly ["functionality", "data", "acceptance", "boundary", "quality", "extensibility"];
+type ClarificationCategory = (typeof CLARIFICATION_CATEGORIES)[number];
+declare const CLARIFICATION_OPTION_LABELS: readonly ["A", "B", "C", "D", "E"];
+type ClarificationOptionLabel = (typeof CLARIFICATION_OPTION_LABELS)[number];
+interface ClarifyOption {
+    label: ClarificationOptionLabel;
+    answer: string;
+}
+interface ClarifyQuestion {
+    id: string;
+    category: ClarificationCategory;
+    question: string;
+    why: string;
+    options: ClarifyOption[];
+}
+interface PlannerInput {
+    rawRequirement: string;
+    clarifications: Array<{
+        question: string;
+        answer: string;
+        category?: ClarificationCategory;
+        why?: string;
+        options?: ClarifyOption[];
+    }>;
+    /** 用户在澄清问答后补充的自定义需求（可为空）。 */
+    userAddenda?: string;
+    /** 增量开发时，现有工程基线摘要（文档 / 计划 / 源码树）。 */
+    baselineContext?: string;
+    /** 计划意图：greenfield / feature / refactor / self。 */
+    intent?: PlanIntent;
+}
+
+/**
+ * Skill：把一组原子工具组合为面向 LLM 的"高阶能力"。
+ *
+ * 在 M3 阶段 Skill 是一层"语义包装"——执行器仍然按 step.tools 中的工具名调用具体 Tool，
+ * 但 Step 可以声明 `tools: ["skill:patcher"]`，Skill Registry 会展开为底层工具集合，
+ * 并把 Skill 的 `prompt` 注入 system prompt，提示 LLM 该如何组合这些工具。
+ */
+interface Skill {
+    /** 形如 `patcher` / `tester` / `dep_resolver`。 */
+    readonly name: string;
+    /** 注入到 system prompt 的简短指引（中文一句话）。 */
+    readonly prompt: string;
+    /** 该 Skill 暴露给 LLM 的底层工具名集合。 */
+    readonly tools: string[];
+}
+
+interface EngineRunSummary {
+    totalSteps: number;
+    executedSteps: number;
+    failedStepId?: string;
+    failureLog?: string;
+    failureReason?: string;
+}
+interface StepAttemptOutcome {
+    ok: boolean;
+    failureLog: string;
+    reason?: string;
+}
+/**
+ * XCompiler 的公共生命周期 Hook。
+ *
+ * Context 对象会按顺序传给所有 handler；插件可以原位补充或调整字段，但不得替换
+ * workspace / audit 等核心服务。涉及文件写入时仍必须通过 Tool 与 EditGuard。
+ */
+interface HookContextMap {
+    'compile.start': {
+        workspace: string;
+        intent: PlanIntent;
+        topicMode: boolean;
+    };
+    'compile.afterClarify': {
+        rawRequirement: string;
+        questions: ClarifyQuestion[];
+        clarifications: PlannerInput['clarifications'];
+        userAddenda: string;
+    };
+    'compile.beforeDecompose': {
+        input: PlannerInput;
+    };
+    'compile.afterPlan': {
+        plan: Plan;
+    };
+    'compile.finish': {
+        plan: Plan;
+        planPath: string;
+    };
+    'run.before': {
+        plan: Plan;
+    };
+    'run.after': {
+        plan: Plan;
+        result: EngineRunSummary;
+    };
+    'run.error': {
+        plan: Plan;
+        error: unknown;
+    };
+    'step.before': {
+        plan: Plan;
+        step: Step;
+    };
+    'step.after': {
+        plan: Plan;
+        step: Step;
+        ok: boolean;
+    };
+    'step.error': {
+        plan: Plan;
+        step: Step;
+        error: unknown;
+    };
+    'step.attempt.before': {
+        plan: Plan;
+        step: Step;
+        role: Role;
+        debug: boolean;
+        retry: number;
+    };
+    'step.attempt.after': {
+        plan: Plan;
+        step: Step;
+        role: Role;
+        debug: boolean;
+        retry: number;
+        outcome: StepAttemptOutcome;
+    };
+    'tool.before': {
+        stepId: string;
+        tool: string;
+        args: unknown;
+        context: ToolContext;
+    };
+    'tool.after': {
+        stepId: string;
+        tool: string;
+        args: unknown;
+        context: ToolContext;
+        result: ToolResult;
+    };
+    'tool.error': {
+        stepId: string;
+        tool: string;
+        args: unknown;
+        context: ToolContext;
+        error: unknown;
+    };
+    'llm.before': {
+        role: string;
+        model: string;
+        messages: ChatMessage[];
+        options?: ChatOptions;
+    };
+    'llm.after': {
+        role: string;
+        model: string;
+        messages: ChatMessage[];
+        response: string;
+        durationMs: number;
+    };
+    'llm.error': {
+        role: string;
+        model: string;
+        messages: ChatMessage[];
+        error: unknown;
+        durationMs: number;
+    };
+}
+type HookName = keyof HookContextMap;
+type HookHandler<K extends HookName> = (context: HookContextMap[K]) => void | Promise<void>;
+interface HookRegistrationOptions {
+    /** 数值越大越先执行；相同优先级保持插件及注册顺序。 */
+    priority?: number;
+}
+interface PluginApi {
+    /** 当前 XCompiler 核心版本。 */
+    readonly xcompilerVersion: string;
+    /** 当前插件 API 主版本；仅同一主版本兼容。 */
+    readonly pluginApiVersion: number;
+    on<K extends HookName>(hook: K, handler: HookHandler<K>, options?: HookRegistrationOptions): () => void;
+    registerTool(tool: Tool): void;
+    registerSkill(skill: Skill): void;
+}
+/** 可序列化的插件清单；后续 registry / marketplace 不需要加载插件代码即可读取。 */
+interface XCompilerPluginManifest {
+    /** 全局唯一且稳定的插件 ID，例如 `company.policy-checker`。 */
+    id: string;
+    /** 插件自身版本，必须是完整 SemVer。 */
+    version: string;
+    /** 插件编译时面向的 XCompiler Plugin API 主版本。 */
+    apiVersion: number;
+    /** 插件可运行的最低 XCompiler 核心版本；必填完整 SemVer。 */
+    minXCompilerVersion: string;
+    /** 以下字段用于插件目录展示，不参与运行时兼容判定。 */
+    displayName?: string;
+    description?: string;
+    license?: string;
+    homepage?: string;
+    keywords?: string[];
+}
+type PluginCompatibilityCode = 'compatible' | 'invalid-runtime-version' | 'invalid-id' | 'invalid-plugin-version' | 'invalid-min-xcompiler-version' | 'api-version-mismatch' | 'xcompiler-version-too-old';
+interface PluginCompatibilityReport {
+    compatible: boolean;
+    code: PluginCompatibilityCode;
+    pluginId: string;
+    pluginVersion: string;
+    xcompilerVersion: string;
+    pluginApiVersion: number;
+    message?: string;
+}
+interface XCompilerPlugin {
+    manifest: XCompilerPluginManifest;
+    /** 默认 continue：记录错误但不拖垮核心流程。 */
+    failureMode?: 'continue' | 'fail';
+    setup(api: PluginApi): void | Promise<void>;
+}
+/** 插件磁盘来源；manifest 与可执行入口分离，兼容检查先于模块 import。 */
+interface PluginSource {
+    manifestPath: string;
+    entryPath: string;
+    /** 模块导出名，默认 `default`。 */
+    exportName?: string;
+}
+interface PluginLoadOptions {
+    sources: PluginSource[];
+    baseDir?: string;
+    audit?: AuditLogger;
+    xcompilerVersion?: string;
+    pluginApiVersion?: number;
+}
+interface PluginHostOptions {
+    plugins?: XCompilerPlugin[];
+    /** 强制所有插件错误中断主流程，适合 CI / 合规插件。 */
+    strict?: boolean;
+    audit?: AuditLogger;
+    /** 嵌入式宿主可显式传入版本；一般应使用内置默认值。 */
+    xcompilerVersion?: string;
+    pluginApiVersion?: number;
+}
+interface PluginExtensionTarget {
+    tools: {
+        get(name: string): Tool | undefined;
+        register(tool: Tool): void;
+    };
+    skills: {
+        get(name: string): Skill | undefined;
+        register(skill: Skill): void;
+    };
+}
+
+/** 插件注册、扩展能力合并与生命周期 Hook 调度中心。 */
+declare class PluginHost {
+    private readonly plugins;
+    private readonly strict;
+    private readonly xcompilerVersion;
+    private readonly pluginApiVersion;
+    private readonly hooks;
+    private readonly contributedTools;
+    private readonly contributedSkills;
+    private audit?;
+    private initialized;
+    private registrationOrder;
+    constructor(options?: PluginHostOptions);
+    get size(): number;
+    /** 返回只读清单快照，供诊断、插件目录和未来 registry 使用。 */
+    get manifests(): readonly XCompilerPluginManifest[];
+    setAudit(audit: AuditLogger): void;
+    initialize(): Promise<void>;
+    /** 把插件贡献的 Tool / Skill 合并到 Engine 的默认注册表；禁止静默覆盖核心能力。 */
+    applyExtensions(target: PluginExtensionTarget): void;
+    emit<K extends HookName>(hook: K, context: HookContextMap[K]): Promise<void>;
+    /** 在不绕过原 Tool / EditGuard 的前提下增加 before / after / error Hook。 */
+    wrapTool<A, R>(tool: Tool<A, R>): Tool<A, R>;
+    /** 包装完整 LLM 调用；response 可由 after Hook 做结构化后处理。 */
+    wrapLLM(client: LLMClient, role: string): LLMClient;
+    private createApi;
+    private handleFailure;
+}
+
+interface PluginRuntimeVersion {
+    xcompilerVersion?: string;
+    pluginApiVersion?: number;
+}
+/** 在加载插件代码前可独立调用的 manifest 兼容性检查。 */
+declare function checkPluginCompatibility(manifest: XCompilerPluginManifest, runtime?: PluginRuntimeVersion): PluginCompatibilityReport;
+
+/**
+ * 从磁盘加载插件。全部 manifest 会在任何插件模块 import 之前完成读取、兼容性与
+ * 重复 ID 检查，避免不兼容插件借助模块顶层代码绕过宿主版本门禁。
+ */
+declare function loadPluginSources(options: PluginLoadOptions): Promise<XCompilerPlugin[]>;
+
+declare const XCOMPILER_VERSION = "0.2.2";
+declare const XCOMPILER_PLUGIN_API_VERSION = 1;
+
+export { type EngineRunSummary, type HookContextMap, type HookHandler, type HookName, type HookRegistrationOptions, type PluginApi, type PluginCompatibilityCode, type PluginCompatibilityReport, type PluginExtensionTarget, PluginHost, type PluginHostOptions, type PluginLoadOptions, type PluginRuntimeVersion, type PluginSource, type Skill, type StepAttemptOutcome, type Tool, type ToolContext, type ToolResult, XCOMPILER_PLUGIN_API_VERSION, XCOMPILER_VERSION, type XCompilerPlugin, type XCompilerPluginManifest, checkPluginCompatibility, loadPluginSources };