@xcompiler/cli 0.2.2 → 0.2.4

package/dist/runtime/runtime.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-declare const XCOMPILER_VERSION = "0.2.2";
+declare const XCOMPILER_VERSION = "0.2.4";
 declare const XCOMPILER_PLUGIN_API_VERSION = 1;
 
 /** Supported target languages for generated projects. */
@@ -72,6 +72,7 @@ declare const PlanSchema: z.ZodPipe<z.ZodObject<{
         refactor: "refactor";
         self: "self";
     }>>;
+    phaseId: z.ZodDefault<z.ZodString>;
     projectType: z.ZodDefault<z.ZodEnum<{
         application: "application";
         library: "library";
@@ -165,6 +166,7 @@ declare const PlanSchema: z.ZodPipe<z.ZodObject<{
     version: "1";
     language: "python" | "typescript";
     intent: "greenfield" | "feature" | "refactor" | "self";
+    phaseId: string;
     projectType: "application" | "library" | "mixed";
     requirementDigest: string;
     globalPrompt: string;
@@ -221,6 +223,7 @@ declare const PlanSchema: z.ZodPipe<z.ZodObject<{
     version: "1";
     language: "python" | "typescript";
     intent: "greenfield" | "feature" | "refactor" | "self";
+    phaseId: string;
     projectType: "application" | "library" | "mixed";
     requirementDigest: string;
     globalPrompt: string;
@@ -305,6 +308,12 @@ interface ChatOptions {
      * 空输出、model token loop 等“表面成功但语义不可用”场景。
      */
     validate?: (text: string) => void;
+    /**
+     * Whether a provider response should increase its dynamic score.
+     * Step/workflow executors should disable this and score quality through
+     * their own validation instead of treating "returned text" as task success.
+     */
+    scoreSuccess?: boolean;
     /**
      * 调用者可传入回调，与 LLM 输出一同拿到实际产出该响应的 provider 名。
      * 主要用于追溯：在 FallbackClient 中服务于响应的是链中某一个后选 provider，
@@ -368,11 +377,12 @@ declare class AuditLogger {
     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 思考过程完整记录"。
+     * 记录一轮 Executor 执行摘要：简短 intent、issue 处理方案、计划调用的 actions、是否完成。
+     * 写入 jsonl + markdown 折叠块，交付时可追溯每轮决策和动作。
      */
     executorTurn(stepId: string, role: string, round: number, payload: {
         thoughts?: string;
+        issueResolutionPlan?: string;
         actions?: unknown[];
         done?: boolean;
         raw?: string;
@@ -436,11 +446,23 @@ interface ExecResult {
     stderr: string;
     timedOut: boolean;
     durationMs: number;
+    timeoutReason?: string;
+}
+interface ExecProgressWatch {
+    /** Host-side paths whose recursive size indicates install progress. */
+    paths: string[];
+    /** Kill the child only after this much time without size growth. */
+    idleTimeoutMs: number;
+    /** Poll interval for recursive size checks. */
+    checkIntervalMs?: number;
+    /** Human-readable label used in timeout diagnostics. */
+    label?: string;
 }
 interface ExecExtra {
     cwd?: string;
     env?: Record<string, string>;
     timeoutMs?: number;
+    progressWatch?: ExecProgressWatch;
 }
 /** 沙盒统一接口。任意 phase / tool 都通过此接口与运行时交互。 */
 interface Sandbox {
@@ -462,7 +484,7 @@ interface Sandbox {
     /**
      * 运行工程入口程序。
      *  - Python：`python <args>`（自动选用 venv 内解释器）。
-     *  - TypeScript：`npx tsx <args>`。
+     *  - TypeScript：默认 `npx tsx <entry>`；当 args 以 `npm`/`npx`/`node`/`tsx`/`tsc` 开头时执行对应项目命令。
      */
     runProgram(args: string[], extra?: ExecExtra): Promise<ExecResult>;
     /**
@@ -524,6 +546,8 @@ interface ToolContext {
     language?: Language;
     /** 当前 Step 的 write_file / append_file 单次 content 字节预算。 */
     writeChunkBytes?: number;
+    /** run_tests 未提供有效过滤参数时使用的当前阶段默认测试范围。 */
+    defaultTestArgs?: string[];
     /** Optional protocol/UI permission hook for sensitive tool operations. */
     requestPermission?: ToolPermissionRequester;
     /** Optional protocol/UI event hook for tool calls and file changes. */
@@ -600,6 +624,8 @@ interface HookContextMap {
     'compile.finish': {
         plan: Plan;
         planPath: string;
+        phasePlanPath?: string;
+        currentPlanPath?: string;
     };
     'run.before': {
         plan: Plan;
@@ -845,7 +871,7 @@ interface CompileOptions {
      * 已澄清的 topic.md 直接输入：跳过 intake / clarify / Addenda / Gate 1，把该文件
      * 内容当作冻结后的项目选题书，直接进入 decompose。常用于：
      *   - 用户上次已澄清并保留了 topic.md，重新跑 decompose 不想再问一遍
-     *   - 离线编辑了 topic.md 想直接拿来出 plan.json
+     *   - 离线编辑了 topic.md 想直接拿来出 phasePlan.json 与当前阶段计划
      * 与 --input 互斥；同时给则 --topic 优先并打印警告。
      */
     topicFile?: string;
@@ -873,41 +899,73 @@ declare function runCompile(opts: CompileOptions): Promise<{
     planPath?: string;
 }>;
 
+interface ScoreStoreOptions {
+    /** Providers tagged as aggregated/route pools such as OpenRouter free mode. */
+    clusterProviderNames?: string[];
+    /** Dynamic score floor for cluster providers. Defaults to 0.2. */
+    clusterScoreMin?: number;
+    /** Dynamic score cap and default score for cluster providers. Defaults to 0.5. */
+    clusterScoreMax?: number;
+}
 /**
  * 每个 LLM provider 的运行时评分（默认 1.0）。
  *
  * 设计动机：
  *  - 配置允许给一个角色挂多个 provider；运行时按评分降序选择当前"最可信"的。
- *  - 评分会随成功/失败动态调整：失败 -0.5 直到 0（=禁用）；成功 +0.1 直到 cap=10。
- *  - preflight 检测到 ollama 服务器上**模型不存在**会直接把评分置 0。
- *  - 持久化到 config 同目录的 sidecar 文件 `llm_scores.yaml`，避免改写用户的 config.yaml
- *    （会丢注释）。配置里 `llm.scores` 段作为 sidecar 缺失时的初值。
+ *  - 评分会随成功/失败动态调整：失败 -0.5 直到 0.1；成功 +0.1 直到 cap=1。
+ *  - `llm_scores.yaml` 是 XCompiler 维护的动态快照；它不是用户策略文件。
+ *  - 用户手动覆盖写在 `llm_scores_user.yaml`；其中 score=0 表示禁用，并且优先生效。
+ *  - preflight 检测到 ollama 服务器上**模型不存在**会在当前运行跳过该 provider，并把评分降到 0.1。
+ *  - 动态评分持久化到 config 同目录的 sidecar 文件 `llm_scores.yaml`，避免改写用户的 config.yaml
+ *    （会丢注释）。配置里 `llm.scores` 段仅作为兼容初值；旧配置中显式 0 仍视为用户禁用。
  */
 declare class ScoreStore {
     private readonly audit?;
     static readonly DEFAULT = 1;
-    static readonly MIN = 0;
-    static readonly MAX = 10;
+    static readonly DISABLED = 0;
+    static readonly MIN = 0.1;
+    static readonly MAX = 1;
+    static readonly CLUSTER_MIN = 0.2;
+    static readonly CLUSTER_MAX = 0.5;
     static readonly DECAY = 0.5;
     static readonly BOOST = 0.1;
-    private readonly scores;
+    private readonly dynamicScores;
+    private readonly userScores;
+    private readonly clusterProviders;
+    private readonly clusterMin;
+    private readonly clusterMax;
     private dirty;
     private writeQueue;
     private readonly sidecarPath;
-    constructor(configPath: string, initial?: Record<string, number>, audit?: AuditLogger | undefined);
-    /** 异步加载 sidecar 文件；失败/不存在不抛错，使用 ctor 提供的初值。 */
+    private readonly userScoresPath;
+    constructor(configPath: string, initial?: Record<string, number>, audit?: AuditLogger | undefined, opts?: ScoreStoreOptions);
+    /** 异步加载动态 sidecar 与用户覆盖文件；失败/不存在不抛错，使用 ctor 提供的初值。 */
     load(): Promise<void>;
+    private loadDynamicScores;
+    private loadUserScores;
     get(name: string): number;
-    /** 主动设置评分（如 preflight 把不存在的模型置 0）。 */
+    /** 主动设置动态评分；用户覆盖只从配置或 llm_scores_user.yaml 读取。 */
     set(name: string, value: number, reason?: string): void;
     decay(name: string, reason: string): void;
     boost(name: string, reason: string): void;
-    /** 全量快照（用于测试与 audit 输出）。 */
+    /** True only for providers explicitly disabled by user config or llm_scores_user.yaml. */
+    isUserDisabled(name: string): boolean;
+    /** 动态评分快照（用于持久化、测试与 audit 输出；不包含用户覆盖）。 */
     snapshot(): Record<string, number>;
+    /** 用户覆盖快照（用于测试/诊断；运行时不会改写用户文件）。 */
+    userSnapshot(): Record<string, number>;
     /** 等待待写入完成（CLI 退出前调用，确保评分已落盘）。 */
     flush(): Promise<void>;
     private scheduleSave;
     private persist;
+    private defaultFor;
+    private minFor;
+    private maxFor;
+    private isClusterProvider;
+    private dynamicScore;
+    private clampDynamic;
+    private clampPersistedDynamic;
+    private clampUserScore;
 }
 
 /** 插件注册、扩展能力合并与生命周期 Hook 调度中心。 */
@@ -975,6 +1033,8 @@ interface ExecuteOptions {
     force?: boolean;
     /** Optional XXX.xc project file to keep in sync with execution progress. */
     projectFilePath?: string;
+    /** Optional debug wiki root directory. Defaults to XCompiler's own .xcompiler/debug-wiki. */
+    debugWikiPath?: string;
     /** Project-file history command label; defaults to run. */
     projectCommand?: string;
     /** Whether to append a history row when execution starts; defaults to true. */
@@ -1017,6 +1077,7 @@ declare function runBuildCommand(opts: RuntimeBuildCommandOptions): Promise<Runt
 type RuntimeEvolveCommandOptions = Omit<CompileOptions, 'workspace' | 'outputFile' | 'projectCommand'> & WorkspaceOptions & {
     planOut?: string;
     cwd?: string;
+    debugWikiPath?: string;
 };
 interface RuntimeEvolveCommandResult {
     workspace: string;
@@ -1038,6 +1099,7 @@ declare function runLoadCommand(opts: RuntimeLoadCommandOptions): Promise<Execut
 type RuntimeAppendCommandOptions = Omit<CompileOptions, 'workspace' | 'baselinePlanFile' | 'outputFile' | 'projectFilePath' | 'projectCommand'> & {
     projectFile: string;
     planOut?: string;
+    debugWikiPath?: string;
 };
 interface RuntimeAppendCommandResult {
     workspace: string;
@@ -1130,7 +1192,7 @@ declare function runDoctorCommand(opts?: RuntimeDoctorOptions): Promise<RuntimeD
 
 interface LsOptions {
     workspace: string;
-    /** Maximum depth for recursively finding plan.json files. Defaults to 4. */
+    /** Maximum depth for recursively finding phasePlan.json / legacy plan.json files. Defaults to 4. */
     maxDepth?: number;
 }
 interface PlanSummary {