flavor-code 1.3.12 → 1.3.15

package/dist/explain/service.d.ts

@@ -0,0 +1,114 @@
+import type { ModelRegistry } from "../models/registry.js";
+import type { QuestionBridge } from "../tools/ask-user-question.js";
+export interface ExplainNode {
+    id: string;
+    kind: string;
+    name: string;
+    qualifiedName: string;
+    filePath: string;
+    language: string;
+    startLine: number;
+    endLine: number;
+    signature?: string;
+}
+export interface ExplainGraph {
+    status(): Promise<{
+        available: boolean;
+    }>;
+    search(query: string, limit?: number): Promise<readonly ExplainNode[]>;
+    relations(id: string, hops?: number): Promise<{
+        origin?: ExplainNode;
+        callers: readonly ExplainNode[];
+        callees: readonly ExplainNode[];
+    }>;
+}
+export type ExplainTarget = {
+    kind: "resolved";
+    node: ExplainNode;
+} | {
+    kind: "ambiguous";
+    candidates: readonly ExplainNode[];
+} | {
+    kind: "not-found";
+    query: string;
+};
+/** A query that looks like a node id ('path/…#name') is tried as an exact
+ *  graph lookup first; anything else goes through ranked name search. */
+export declare function resolveExplainTarget(graph: ExplainGraph, query: string): Promise<ExplainTarget>;
+/** Label shared by the picker options and the answer matching below. The
+ *  graph node id is unique, so it doubles as an unambiguous picker label. */
+export declare function explainCandidateLabel(candidate: ExplainNode): string;
+export type ExplainSelection = {
+    kind: "picked";
+    node: ExplainNode;
+} | {
+    kind: "typed";
+    query: string;
+} | {
+    kind: "cancelled";
+};
+/** Interactive disambiguation: top-3 candidates (label = `name (filePath)`,
+ *  description = kind + file:line) plus Cancel. The terminal question cards
+ *  always append a free-text choice, so the user can type a more exact symbol
+ *  instead; that raw text comes back as `typed` for the caller to re-resolve. */
+export declare function selectExplainCandidate(candidates: readonly ExplainNode[], questions: QuestionBridge, signal: AbortSignal): Promise<ExplainSelection>;
+export interface ExplainPromptInput {
+    anchor: ExplainNode;
+    anchorSource: string;
+    callers: readonly {
+        name: string;
+        filePath: string;
+        startLine: number;
+    }[];
+    callees: readonly {
+        name: string;
+        filePath: string;
+        startLine: number;
+    }[];
+    history: readonly {
+        date: string;
+        author: string;
+        subject: string;
+    }[];
+    focus?: string;
+    language: string;
+}
+/** Assemble the evidence bundle (source slice + relations + commit subjects)
+ *  into a single prompt. The model must only see real code and real history,
+ *  so the "why" section stays grounded and can say 不确定 instead of guessing. */
+export declare function buildExplainPrompt(input: ExplainPromptInput): string;
+export interface ExplainModelOptions {
+    registry: ModelRegistry;
+    /** Cheap model id provider; evaluated lazily so /model switches apply. */
+    modelId(): string;
+}
+/** One streaming completion from the cheap (subagent) model, mirroring
+ *  src/git/insights.ts. Throws on stream errors or empty output; runExplain
+ *  turns the throw into user-facing text. When `onText` is provided every
+ *  streamed text delta is forwarded as it arrives, so callers can surface
+ *  incremental (SSE-style) output instead of one buffered blob. */
+export declare function explainWithModel(options: ExplainModelOptions, prompt: string, signal: AbortSignal, onText?: (chunk: string) => void): Promise<string>;
+export interface ExplainDeps {
+    graph: ExplainGraph;
+    /** Read a workspace-relative file (production enforces workspace containment). */
+    readFile(path: string): Promise<string>;
+    history?(path: string, limit: number): Promise<readonly {
+        date: string;
+        author: string;
+        subject: string;
+    }[]>;
+    questions?: QuestionBridge;
+    registry: ModelRegistry;
+    modelId(): string;
+    language: string;
+    notify?(message: string): void;
+    /** Forwarded per streamed text delta. When present, runExplain emits the
+     *  whole answer incrementally through it and returns an empty string on
+     *  success (the caller must not re-print the answer as one notice). */
+    onText?(chunk: string): void;
+}
+/** Orchestrate one /explain turn: resolve the symbol (asking the user to pick
+ *  on ambiguity), gather grounded evidence and stream a cheap-model answer.
+ *  Every failure path returns user-facing text instead of throwing, matching
+ *  the /review semantics in src/ui/session.ts. */
+export declare function runExplain(deps: ExplainDeps, query: string | undefined, focus: string | undefined, signal: AbortSignal): Promise<string>;

package/dist/sdk/index.js

@@ -4,7 +4,7 @@ import {
   FlavorRpcServer,
   TraceRecordSchema,
   TraceRecorder
-} from "../chunk-EZNIDHFZ.js";
+} from "../chunk-TQXNF337.js";
 import {
   AgentMessageQueue,
   DockerExecutionEnvironment,
@@ -13,7 +13,7 @@ import {
   WorkspaceCheckpointStore,
   buildDockerInvocation,
   createProductionRuntime
-} from "../chunk-QC5OYQTB.js";
+} from "../chunk-WB4IJXFT.js";
 import "../chunk-JFKRX2KG.js";
 import "../chunk-RQTYHUMK.js";
 import "../chunk-S32JRDZK.js";

package/dist/ui/commands.d.ts

@@ -1,4 +1,4 @@
-export declare const MVP_COMMANDS: readonly ["model", "init", "config", "login", "logout", "permissions", "skills", "plugins", "hooks", "tasks", "finish", "compact", "clear", "help", "exit", "audit", "usage", "loop", "goal", "evolve", "mcp", "commit", "review", "ide", "memory", "remember", "forget", "forget-cold", "checkpoint", "tree", "rewind", "unrevert", "fork", "pals", "chat", "co-work", "tool"];
+export declare const MVP_COMMANDS: readonly ["model", "init", "config", "login", "logout", "permissions", "skills", "plugins", "hooks", "tasks", "finish", "compact", "clear", "help", "exit", "audit", "usage", "loop", "goal", "evolve", "mcp", "commit", "review", "explain", "ide", "memory", "remember", "forget", "forget-cold", "checkpoint", "tree", "rewind", "unrevert", "fork", "pals", "chat", "co-work", "tool"];
 export declare const COMMAND_DESCRIPTIONS: Record<(typeof MVP_COMMANDS)[number], string>;
 export type PermissionCommandMode = PermissionMode;
 export type ModelRole = "main" | "subagent";
@@ -73,6 +73,10 @@ export type SlashCommand = {
 } | {
     name: "review";
     focus?: string;
+} | {
+    name: "explain";
+    query?: string;
+    focus?: string;
 } | {
     name: "remember";
     type: MemoryType;
@@ -91,7 +95,7 @@ export type SlashCommand = {
     target: string;
     goal: string;
 } | CoWorkSlashCommand | {
-    name: Exclude<(typeof MVP_COMMANDS)[number], "model" | "permissions" | "audit" | "loop" | "goal" | "evolve" | "commit" | "review" | "mcp" | "remember" | "forget" | "checkpoint" | "rewind" | "fork" | "pals" | "chat" | "co-work" | "tool">;
+    name: Exclude<(typeof MVP_COMMANDS)[number], "model" | "permissions" | "audit" | "loop" | "goal" | "evolve" | "commit" | "review" | "explain" | "mcp" | "remember" | "forget" | "checkpoint" | "rewind" | "fork" | "pals" | "chat" | "co-work" | "tool">;
 } | {
     name: "audit";
     toolFilter?: string | undefined;

package/dist/ui/session.d.ts

@@ -133,6 +133,7 @@ export interface SessionServices {
     evolve(args: readonly string[]): string | Promise<string>;
     gitCommit?(hint: string | undefined, signal: AbortSignal): Promise<string>;
     gitReview?(focus: string | undefined, signal: AbortSignal): Promise<string>;
+    explain?(query: string | undefined, focus: string | undefined, signal: AbortSignal, onText?: (chunk: string) => void): Promise<string>;
     usage(): string | Promise<string>;
     cancelActiveTask(): void | Promise<void>;
     clearContext(): void | Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flavor-code",
-  "version": "1.3.12",
+  "version": "1.3.15",
   "author": "YachuanWzh",
   "type": "module",
   "publishConfig": {