@xcompiler/cli 0.2.3 → 0.2.4

package/dist/runtime/runtime.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-declare const XCOMPILER_VERSION = "0.2.3";
+declare const XCOMPILER_VERSION = "0.2.4";
 declare const XCOMPILER_PLUGIN_API_VERSION = 1;
 
 /** Supported target languages for generated projects. */
@@ -377,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;
@@ -445,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 {
@@ -900,10 +913,11 @@ interface ScoreStoreOptions {
  * 设计动机：
  *  - 配置允许给一个角色挂多个 provider；运行时按评分降序选择当前"最可信"的。
  *  - 评分会随成功/失败动态调整：失败 -0.5 直到 0.1；成功 +0.1 直到 cap=1。
- *  - 只有用户在配置中显式设置 score=0 才表示禁用；运行时自动评分不会写出 0。
+ *  - `llm_scores.yaml` 是 XCompiler 维护的动态快照；它不是用户策略文件。
+ *  - 用户手动覆盖写在 `llm_scores_user.yaml`；其中 score=0 表示禁用，并且优先生效。
  *  - preflight 检测到 ollama 服务器上**模型不存在**会在当前运行跳过该 provider，并把评分降到 0.1。
- *  - 持久化到 config 同目录的 sidecar 文件 `llm_scores.yaml`，避免改写用户的 config.yaml
- *    （会丢注释）。配置里 `llm.scores` 段作为 sidecar 缺失时的初值。
+ *  - 动态评分持久化到 config 同目录的 sidecar 文件 `llm_scores.yaml`，避免改写用户的 config.yaml
+ *    （会丢注释）。配置里 `llm.scores` 段仅作为兼容初值；旧配置中显式 0 仍视为用户禁用。
  */
 declare class ScoreStore {
     private readonly audit?;
@@ -915,26 +929,31 @@ declare class ScoreStore {
     static readonly CLUSTER_MAX = 0.5;
     static readonly DECAY = 0.5;
     static readonly BOOST = 0.1;
-    private readonly scores;
-    private readonly userDisabled;
+    private readonly dynamicScores;
+    private readonly userScores;
     private readonly clusterProviders;
     private readonly clusterMin;
     private readonly clusterMax;
     private dirty;
     private writeQueue;
     private readonly sidecarPath;
+    private readonly userScoresPath;
     constructor(configPath: string, initial?: Record<string, number>, audit?: AuditLogger | undefined, opts?: ScoreStoreOptions);
-    /** 异步加载 sidecar 文件；失败/不存在不抛错，使用 ctor 提供的初值。 */
+    /** 异步加载动态 sidecar 与用户覆盖文件；失败/不存在不抛错，使用 ctor 提供的初值。 */
     load(): Promise<void>;
+    private loadDynamicScores;
+    private loadUserScores;
     get(name: string): number;
-    /** 主动设置评分；value=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;
-    /** True only for providers explicitly disabled by user config (`llm.scores.<provider>: 0`). */
+    /** True only for providers explicitly disabled by user config or llm_scores_user.yaml. */
     isUserDisabled(name: string): boolean;
-    /** 全量快照（用于测试与 audit 输出）。 */
+    /** 动态评分快照（用于持久化、测试与 audit 输出；不包含用户覆盖）。 */
     snapshot(): Record<string, number>;
+    /** 用户覆盖快照（用于测试/诊断；运行时不会改写用户文件）。 */
+    userSnapshot(): Record<string, number>;
     /** 等待待写入完成（CLI 退出前调用，确保评分已落盘）。 */
     flush(): Promise<void>;
     private scheduleSave;
@@ -943,8 +962,10 @@ declare class ScoreStore {
     private minFor;
     private maxFor;
     private isClusterProvider;
-    private clampConfigured;
+    private dynamicScore;
     private clampDynamic;
+    private clampPersistedDynamic;
+    private clampUserScore;
 }
 
 /** 插件注册、扩展能力合并与生命周期 Hook 调度中心。 */
@@ -1012,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. */
@@ -1054,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;
@@ -1075,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;