@xcompiler/cli 0.2.2 → 0.2.3

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.3";
 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，
@@ -462,7 +471,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 +533,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 +611,8 @@ interface HookContextMap {
     'compile.finish': {
         plan: Plan;
         planPath: string;
+        phasePlanPath?: string;
+        currentPlanPath?: string;
     };
     'run.before': {
         plan: Plan;
@@ -845,7 +858,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 +886,65 @@ 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。
+ *  - 评分会随成功/失败动态调整：失败 -0.5 直到 0.1；成功 +0.1 直到 cap=1。
+ *  - 只有用户在配置中显式设置 score=0 才表示禁用；运行时自动评分不会写出 0。
+ *  - preflight 检测到 ollama 服务器上**模型不存在**会在当前运行跳过该 provider，并把评分降到 0.1。
  *  - 持久化到 config 同目录的 sidecar 文件 `llm_scores.yaml`，避免改写用户的 config.yaml
  *    （会丢注释）。配置里 `llm.scores` 段作为 sidecar 缺失时的初值。
  */
 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 userDisabled;
+    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);
+    constructor(configPath: string, initial?: Record<string, number>, audit?: AuditLogger | undefined, opts?: ScoreStoreOptions);
     /** 异步加载 sidecar 文件；失败/不存在不抛错，使用 ctor 提供的初值。 */
     load(): Promise<void>;
     get(name: string): number;
-    /** 主动设置评分（如 preflight 把不存在的模型置 0）。 */
+    /** 主动设置评分；value=0 仅用于显式禁用，其它值会归一到动态范围。 */
     set(name: string, value: number, reason?: string): void;
     decay(name: string, reason: string): void;
     boost(name: string, reason: string): void;
+    /** True only for providers explicitly disabled by user config (`llm.scores.<provider>: 0`). */
+    isUserDisabled(name: string): boolean;
     /** 全量快照（用于测试与 audit 输出）。 */
     snapshot(): Record<string, number>;
     /** 等待待写入完成（CLI 退出前调用，确保评分已落盘）。 */
     flush(): Promise<void>;
     private scheduleSave;
     private persist;
+    private defaultFor;
+    private minFor;
+    private maxFor;
+    private isClusterProvider;
+    private clampConfigured;
+    private clampDynamic;
 }
 
 /** 插件注册、扩展能力合并与生命周期 Hook 调度中心。 */
@@ -1130,7 +1167,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 {