@qlingzzy/qling 1.0.0

package/dist/repl.d.ts

@@ -0,0 +1,41 @@
+import { AgentLoop } from "./agent-loop.js";
+export type ReplInputResult = "continue" | "exit";
+export declare class Repl {
+    private agent;
+    private rl;
+    private readonly startupResumeTarget?;
+    private readonly startupContinue;
+    private scheduler;
+    private goalController;
+    private controllersSessionId;
+    private immediatePrompt;
+    private runningScheduledTask;
+    constructor(agent?: AgentLoop, options?: {
+        resumeSession?: string;
+        continueSession?: boolean;
+    });
+    start(): Promise<void>;
+    private loop;
+    handleInputLine(input: string): Promise<ReplInputResult>;
+    private processPrompt;
+    private resolveGoalContinuationPrompt;
+    private cleanupLocalControlStateForReset;
+    private createSlashContext;
+    private listSavedSessionSummariesForSlash;
+    private writeLegacySessionList;
+    private formatLegacyDetailedSessionList;
+    private resolveLegacyLoadTarget;
+    private parseLegacyLoadIndex;
+    private listLegacyLoadCandidates;
+    private formatSessionTime;
+    private ensureLocalSessionControllers;
+    private resetLocalSessionControllers;
+    private switchSession;
+    private finalizeRestoredSession;
+    private withLocalRestoreStatus;
+    private formatLegacyRestoreMessage;
+    private formatStartupRestoreMessage;
+    private formatLocalRestoreStatusSuffix;
+    private restoreStartupSessionIfNeeded;
+}
+//# sourceMappingURL=repl.d.ts.map

package/dist/repl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../src/repl.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAQ5C,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,MAAM,CAAC;AAMlD,qBAAa,IAAI;IACf,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,EAAE,CAAqB;IAC/B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,oBAAoB,CAAuB;IACnD,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,oBAAoB,CAAS;gBAGnC,KAAK,CAAC,EAAE,SAAS,EACjB,OAAO,GAAE;QACP,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;KACtB;IAWF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAqBd,IAAI;IAeZ,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;YA+EhD,aAAa;YA8Bb,6BAA6B;YAqC7B,gCAAgC;IAoB9C,OAAO,CAAC,kBAAkB;YAkBZ,iCAAiC;YAwBjC,sBAAsB;IAepC,OAAO,CAAC,+BAA+B;YAezB,uBAAuB;IAWrC,OAAO,CAAC,oBAAoB;YASd,wBAAwB;IAatC,OAAO,CAAC,iBAAiB;YAKX,6BAA6B;YAwC7B,4BAA4B;YAS5B,aAAa;YAWb,uBAAuB;YAMvB,sBAAsB;IAcpC,OAAO,CAAC,0BAA0B;IAIlC,OAAO,CAAC,2BAA2B;IAInC,OAAO,CAAC,8BAA8B;YAYxB,6BAA6B;CAS5C"}

package/dist/repl.js

@@ -0,0 +1,396 @@
+// ============================================================
+// 轻灵 - 交互模式 REPL
+// 多轮对话，不用每次都重开
+// ============================================================
+import * as readline from "readline";
+import { AgentLoop } from "./agent-loop.js";
+import { handleSlashCommand } from "./commands/index.js";
+import { SessionGoalController } from "./session/goal-controller.js";
+import { SessionGoalManager } from "./session/session-goal-manager.js";
+import { SessionScheduler } from "./session/session-scheduler.js";
+export class Repl {
+    agent;
+    rl;
+    startupResumeTarget;
+    startupContinue;
+    scheduler = null;
+    goalController = null;
+    controllersSessionId = null;
+    immediatePrompt = null;
+    runningScheduledTask = false;
+    constructor(agent, options = {}) {
+        this.agent = agent ?? new AgentLoop();
+        this.startupResumeTarget = options.resumeSession;
+        this.startupContinue = options.continueSession ?? false;
+        this.rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+    }
+    async start() {
+        console.log(`
+╔══════════════════════════════════════════╗
+║         🌬️ 轻灵 REPL 模式               ║
+║   输入任务，回车执行。输入 q 退出。       ║
+║   输入 !reset 重置对话。                 ║
+║   输入 !save [name] 保存会话。           ║
+║   输入 !load [name] 恢复会话。           ║
+║   输入 !sessions 查看已保存会话。         ║
+╚══════════════════════════════════════════╝
+`);
+        const restored = await this.restoreStartupSessionIfNeeded();
+        const restoredWithLocalStatus = restored
+            ? await this.finalizeRestoredSession(restored)
+            : null;
+        if (restoredWithLocalStatus) {
+            console.log(`${this.formatStartupRestoreMessage(restoredWithLocalStatus)}\n`);
+        }
+        this.loop();
+    }
+    async loop() {
+        const prompt = () => new Promise((resolve) => {
+            this.rl.question("🎋 > ", (answer) => resolve(answer));
+        });
+        while (true) {
+            const input = await prompt();
+            const result = await this.handleInputLine(input);
+            if (result === "exit") {
+                return;
+            }
+        }
+    }
+    async handleInputLine(input) {
+        const trimmedInput = input.trim();
+        if (trimmedInput === "q" || trimmedInput === "quit" || trimmedInput === "exit") {
+            console.log("👋 再见！");
+            try {
+                await this.agent.shutdown();
+            }
+            catch {
+                // ignore shutdown cleanup failures in REPL exit path
+            }
+            await this.resetLocalSessionControllers();
+            this.rl.close();
+            process.stdin.pause();
+            return "exit";
+        }
+        if (trimmedInput === "!reset" || trimmedInput === "reset") {
+            this.agent.reset();
+            const canceledTasks = await this.cleanupLocalControlStateForReset();
+            await this.agent.checkpointSession();
+            console.log(`✅ 对话已重置。${canceledTasks > 0 ? `已同步取消 ${canceledTasks} 个 loop 任务。` : ""}\n`);
+            return "continue";
+        }
+        if (trimmedInput === "!save" || trimmedInput.startsWith("!save ")) {
+            const name = trimmedInput.replace(/^!save\s*/, "") || undefined;
+            const file = await this.agent.saveSession(name);
+            console.log(`💾 会话已保存: ${file}\n`);
+            return "continue";
+        }
+        if (trimmedInput === "!load" || trimmedInput.startsWith("!load ")) {
+            const name = trimmedInput.replace(/^!load\s*/, "");
+            if (!name) {
+                await this.writeLegacySessionList();
+            }
+            else {
+                const restoreTarget = await this.resolveLegacyLoadTarget(name);
+                const restored = await this.agent.restoreSession(restoreTarget);
+                const restoredWithLocalStatus = restored
+                    ? await this.finalizeRestoredSession(restored)
+                    : null;
+                console.log(restoredWithLocalStatus
+                    ? `${this.formatLegacyRestoreMessage(restoredWithLocalStatus)}\n`
+                    : `❌ 找不到会话: ${name}\n`);
+            }
+            return "continue";
+        }
+        if (trimmedInput === "!sessions" || trimmedInput === "!ls") {
+            await this.writeLegacySessionList();
+            return "continue";
+        }
+        if (!trimmedInput) {
+            return "continue";
+        }
+        if (trimmedInput.startsWith("/")) {
+            await this.ensureLocalSessionControllers();
+            this.immediatePrompt = null;
+            const handledSlashCommand = await handleSlashCommand(trimmedInput, this.createSlashContext());
+            if (handledSlashCommand) {
+                if (this.immediatePrompt) {
+                    const nextPrompt = this.immediatePrompt;
+                    this.immediatePrompt = null;
+                    await this.processPrompt(nextPrompt);
+                }
+                else {
+                    await this.scheduler?.runDueTasksOnce();
+                }
+                return "continue";
+            }
+        }
+        await this.processPrompt(input);
+        return "continue";
+    }
+    async processPrompt(input) {
+        let currentPrompt = input;
+        this.scheduler?.setBusy(true);
+        try {
+            while (currentPrompt) {
+                console.log("\n🎋 轻灵正在思考...\n");
+                try {
+                    this.agent.addUserMessage(currentPrompt);
+                    const response = await this.agent.run();
+                    await this.agent.checkpointSession();
+                    console.log(`\n${response}\n`);
+                }
+                catch (err) {
+                    console.error(`\n❌ 出错: ${err instanceof Error ? err.message : String(err)}\n`);
+                    console.log("💡 输入 !reset 重置对话，或继续输入新任务。\n");
+                    currentPrompt = null;
+                    break;
+                }
+                currentPrompt = await this.resolveGoalContinuationPrompt();
+            }
+        }
+        finally {
+            this.scheduler?.setBusy(false);
+            if (!this.runningScheduledTask) {
+                await this.scheduler?.runDueTasksOnce();
+            }
+        }
+    }
+    async resolveGoalContinuationPrompt() {
+        if (!this.goalController) {
+            return null;
+        }
+        if (typeof this.agent.getMessagesSnapshot !== "function" ||
+            typeof this.agent.getSessionStats !== "function") {
+            return null;
+        }
+        try {
+            const stats = this.agent.getSessionStats();
+            const goalResult = await this.goalController.afterTurn({
+                transcript: SessionGoalController.messagesToTranscript(this.agent.getMessagesSnapshot()),
+                stats: {
+                    turnCount: stats.turnCount ?? 0,
+                    tokens: stats.tokens ?? 0,
+                },
+            });
+            if (goalResult.status === "continue" && goalResult.continuePrompt) {
+                console.log(`⚠️ goal 未达成: ${goalResult.reason ?? "条件未满足"}\n`);
+                return goalResult.continuePrompt;
+            }
+            if (goalResult.status === "achieved") {
+                console.log(`✅ goal 已达成: ${goalResult.reason ?? "条件满足"}\n`);
+            }
+            else if (goalResult.status === "cleared") {
+                console.log(`⚠️ goal 已停止: ${goalResult.reason ?? "已清除"}\n`);
+            }
+        }
+        catch (err) {
+            console.error(`⚠️ goal 评估失败: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        return null;
+    }
+    async cleanupLocalControlStateForReset() {
+        let canceledTasks = 0;
+        if (this.scheduler && typeof this.scheduler.cancelAllTasks === "function") {
+            canceledTasks = await this.scheduler.cancelAllTasks();
+        }
+        if (this.goalController &&
+            typeof this.goalController.getGoalStatus === "function" &&
+            typeof this.goalController.clearGoal === "function") {
+            const goalStatus = await this.goalController.getGoalStatus();
+            if (goalStatus?.status === "active") {
+                await this.goalController.clearGoal("conversation_reset");
+            }
+        }
+        return canceledTasks;
+    }
+    createSlashContext() {
+        return {
+            agentLoop: this.agent,
+            scheduler: this.scheduler ?? undefined,
+            goalController: this.goalController ?? undefined,
+            workspaceDir: typeof this.agent.getWorkspaceDir === "function"
+                ? this.agent.getWorkspaceDir()
+                : undefined,
+            listSavedSessions: async () => this.listSavedSessionSummariesForSlash(),
+            switchSession: async (target) => this.switchSession(target),
+            setImmediatePrompt: (prompt) => {
+                this.immediatePrompt = prompt;
+            },
+            writeLine: (line = "") => console.log(line),
+            writeError: (line = "") => console.error(line),
+        };
+    }
+    async listSavedSessionSummariesForSlash() {
+        if (typeof this.agent.listSessionsDetailed === "function") {
+            return (await this.agent.listSessionsDetailed());
+        }
+        if (typeof this.agent.listSessions !== "function") {
+            return [];
+        }
+        const names = await this.agent.listSessions();
+        const placeholderTime = new Date(0).toISOString();
+        return names.map((name) => ({
+            name,
+            sessionId: name,
+            workspaceDir: null,
+            createdAt: placeholderTime,
+            updatedAt: placeholderTime,
+            turnCount: 0,
+            messageCount: 0,
+            sessionTokens: 0,
+            compactionCount: 0,
+        }));
+    }
+    async writeLegacySessionList() {
+        if (typeof this.agent.listSessionsDetailed === "function") {
+            const sessions = await this.agent.listSessionsDetailed();
+            console.log(this.formatLegacyDetailedSessionList(sessions));
+            return;
+        }
+        const sessions = await this.agent.listSessions();
+        if (sessions.length === 0) {
+            console.log("📭 没有已保存的会话。\n");
+        }
+        else {
+            console.log("📂 已保存的会话:\n" + sessions.map((s, i) => `  ${i + 1}. ${s}`).join("\n") + "\n");
+        }
+    }
+    formatLegacyDetailedSessionList(sessions) {
+        if (sessions.length === 0) {
+            return "📭 没有已保存的会话。\n";
+        }
+        const lines = ["📂 已保存的会话:"];
+        sessions.forEach((session, index) => {
+            lines.push(`  ${index + 1}. ${session.name} | ${session.sessionId}`);
+            lines.push(`     更新: ${this.formatSessionTime(session.updatedAt)} | turns=${session.turnCount} | messages=${session.messageCount}`);
+        });
+        return `${lines.join("\n")}\n`;
+    }
+    async resolveLegacyLoadTarget(rawTarget) {
+        const target = rawTarget.trim();
+        const selectionIndex = this.parseLegacyLoadIndex(target);
+        if (selectionIndex === null) {
+            return target;
+        }
+        const candidates = await this.listLegacyLoadCandidates();
+        return candidates[selectionIndex - 1] ?? target;
+    }
+    parseLegacyLoadIndex(target) {
+        if (!/^[1-9]\d*$/.test(target)) {
+            return null;
+        }
+        const selectionIndex = Number(target);
+        return Number.isSafeInteger(selectionIndex) ? selectionIndex : null;
+    }
+    async listLegacyLoadCandidates() {
+        if (typeof this.agent.listSessionsDetailed === "function") {
+            const sessions = await this.agent.listSessionsDetailed();
+            return sessions.map((session) => session.name);
+        }
+        if (typeof this.agent.listSessions !== "function") {
+            return [];
+        }
+        return (await this.agent.listSessions());
+    }
+    formatSessionTime(value) {
+        const ts = Date.parse(value);
+        return Number.isNaN(ts) ? value : new Date(ts).toLocaleString();
+    }
+    async ensureLocalSessionControllers() {
+        if (typeof this.agent.getRuntimeRootDir !== "function" ||
+            typeof this.agent.getSessionId !== "function") {
+            return;
+        }
+        const sessionId = this.agent.getSessionId();
+        if (this.scheduler && this.goalController && this.controllersSessionId === sessionId) {
+            return;
+        }
+        await this.resetLocalSessionControllers();
+        const stateDir = this.agent.getRuntimeRootDir();
+        this.scheduler = new SessionScheduler({
+            stateDir,
+            sessionId,
+            runner: "session",
+            onDue: async (task) => {
+                this.runningScheduledTask = true;
+                try {
+                    await this.processPrompt(task.prompt);
+                }
+                finally {
+                    this.runningScheduledTask = false;
+                }
+            },
+        });
+        await this.scheduler.init();
+        this.scheduler.start();
+        const goalManager = new SessionGoalManager({ stateDir, sessionId });
+        this.goalController = new SessionGoalController({
+            manager: goalManager,
+            runner: "session",
+        });
+        await this.goalController.init();
+        this.controllersSessionId = sessionId;
+    }
+    async resetLocalSessionControllers() {
+        if (this.scheduler) {
+            await this.scheduler.stop();
+        }
+        this.scheduler = null;
+        this.goalController = null;
+        this.controllersSessionId = null;
+    }
+    async switchSession(target) {
+        const restored = target
+            ? await this.agent.restoreSession(target)
+            : await this.agent.restoreLatestSession();
+        if (!restored) {
+            return null;
+        }
+        return this.finalizeRestoredSession(restored);
+    }
+    async finalizeRestoredSession(restored) {
+        await this.agent.checkpointSession();
+        await this.ensureLocalSessionControllers();
+        return this.withLocalRestoreStatus(restored);
+    }
+    async withLocalRestoreStatus(restored) {
+        if (!this.scheduler && !this.goalController) {
+            return restored;
+        }
+        const tasks = this.scheduler ? await this.scheduler.listTasks() : [];
+        const goal = this.goalController ? await this.goalController.getGoalStatus() : null;
+        return {
+            ...restored,
+            activeTaskCount: tasks.filter((task) => task.status !== "canceled" && task.status !== "completed").length,
+            activeGoalStatus: goal?.status ?? null,
+        };
+    }
+    formatLegacyRestoreMessage(restored) {
+        return `📂 会话已恢复: ${restored.name} (${restored.sessionId})${this.formatLocalRestoreStatusSuffix(restored)}`;
+    }
+    formatStartupRestoreMessage(restored) {
+        return `♻️ 已恢复会话: ${restored.name} (${restored.sessionId})${this.formatLocalRestoreStatusSuffix(restored)}`;
+    }
+    formatLocalRestoreStatusSuffix(restored) {
+        const localStatus = [];
+        if (typeof restored.activeTaskCount === "number") {
+            localStatus.push(`Loop Tasks: ${restored.activeTaskCount}`);
+        }
+        if (restored.activeGoalStatus) {
+            localStatus.push(`Goal: ${restored.activeGoalStatus}`);
+        }
+        return localStatus.length > 0 ? ` - ${localStatus.join(", ")}` : "";
+    }
+    async restoreStartupSessionIfNeeded() {
+        if (this.startupResumeTarget) {
+            return this.agent.restoreSession(this.startupResumeTarget);
+        }
+        if (this.startupContinue) {
+            return this.agent.restoreLatestSession();
+        }
+        return null;
+    }
+}

package/dist/runtime-paths.d.ts

@@ -0,0 +1,32 @@
+export interface RuntimeRoots {
+    workspaceDir: string | null;
+    fileCacheDir: string;
+    fileStateDir: string;
+}
+export type DefaultRootKind = "workspace" | "file_cache" | "file_state";
+/** write/patch 沙箱：默认仅工作区 */
+export type WriteSandboxMode = "workspace" | "roots" | "off";
+export declare function getRuntimeRootsFromEnv(env?: NodeJS.ProcessEnv): RuntimeRoots;
+export declare function resolveWriteSandboxMode(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): WriteSandboxMode;
+/** 有效工作区：显式 workspace，否则 cwd */
+export declare function resolveEffectiveWorkspace(roots: RuntimeRoots): string;
+/**
+ * 写工具路径是否允许。
+ * - workspace: 仅工作区（默认）
+ * - roots: workspace + state + cache
+ * - off: 不检查
+ */
+export declare function isPathAllowedForWrite(absPath: string, roots: RuntimeRoots, mode?: WriteSandboxMode): boolean;
+export interface SensitiveWriteCheck {
+    blocked: boolean;
+    code: string;
+    reason: string;
+}
+/**
+ * 敏感写目标检测（.env / 密钥文件）。
+ * QLING_ALLOW_SENSITIVE_WRITE=1 时放行。
+ */
+export declare function checkSensitiveWriteTarget(absPath: string, env?: NodeJS.ProcessEnv | Record<string, string | undefined>): SensitiveWriteCheck | null;
+export declare function resolveToolPath(inputPath: string, roots: RuntimeRoots, defaultRoot?: DefaultRootKind): string;
+export declare function isWithinAllowedRoots(absPath: string, roots: RuntimeRoots): boolean;
+//# sourceMappingURL=runtime-paths.d.ts.map

package/dist/runtime-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-paths.d.ts","sourceRoot":"","sources":["../src/runtime-paths.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,YAAY,GAAG,YAAY,CAAC;AAExE,4BAA4B;AAC5B,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,OAAO,GAAG,KAAK,CAAC;AAuB7D,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAUzF;AAED,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxE,gBAAgB,CAKlB;AAED,gCAAgC;AAChC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,YAAY,EACnB,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAOT;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxE,mBAAmB,GAAG,IAAI,CAiC5B;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,EACnB,WAAW,GAAE,eAA6B,GACzC,MAAM,CAwBR;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAMlF"}

package/dist/runtime-paths.js

@@ -0,0 +1,134 @@
+import * as os from "os";
+import * as path from "path";
+const HOME = os.homedir();
+const DEFAULT_STATE_DIR = path.join(HOME, ".qling");
+const DEFAULT_CACHE_DIR = path.join(DEFAULT_STATE_DIR, "cache");
+/** 默认拒绝写入的敏感文件名模式（小写比较） */
+const SENSITIVE_BASENAME_EXACT = new Set([
+    ".env",
+    ".env.local",
+    ".env.development",
+    ".env.production",
+    ".env.test",
+    "id_rsa",
+    "id_ed25519",
+    "credentials.json",
+    "service-account.json",
+    ".npmrc",
+    ".pypirc",
+]);
+const SENSITIVE_BASENAME_SUFFIXES = [".pem", ".key", ".p12", ".pfx"];
+export function getRuntimeRootsFromEnv(env = process.env) {
+    const state = path.resolve(env.QLING_FILE_STATE_DIR ?? DEFAULT_STATE_DIR);
+    const cache = path.resolve(env.QLING_FILE_CACHE_DIR ?? path.join(state, "cache"));
+    const ws = env.QLING_WORKSPACE_DIR?.trim();
+    return {
+        workspaceDir: ws ? path.resolve(ws) : null,
+        fileCacheDir: cache,
+        fileStateDir: state,
+    };
+}
+export function resolveWriteSandboxMode(env = process.env) {
+    const raw = String(env.QLING_WRITE_SANDBOX ?? "workspace").trim().toLowerCase();
+    if (raw === "off" || raw === "false" || raw === "0" || raw === "none")
+        return "off";
+    if (raw === "roots" || raw === "all" || raw === "legacy")
+        return "roots";
+    return "workspace";
+}
+/** 有效工作区：显式 workspace，否则 cwd */
+export function resolveEffectiveWorkspace(roots) {
+    return path.resolve(roots.workspaceDir ?? process.cwd());
+}
+/**
+ * 写工具路径是否允许。
+ * - workspace: 仅工作区（默认）
+ * - roots: workspace + state + cache
+ * - off: 不检查
+ */
+export function isPathAllowedForWrite(absPath, roots, mode) {
+    const m = mode ?? resolveWriteSandboxMode();
+    if (m === "off")
+        return true;
+    const target = path.resolve(absPath);
+    if (m === "roots")
+        return isWithinAllowedRoots(target, roots);
+    const ws = resolveEffectiveWorkspace(roots);
+    return isSubPath(target, ws);
+}
+/**
+ * 敏感写目标检测（.env / 密钥文件）。
+ * QLING_ALLOW_SENSITIVE_WRITE=1 时放行。
+ */
+export function checkSensitiveWriteTarget(absPath, env = process.env) {
+    const allow = String(env.QLING_ALLOW_SENSITIVE_WRITE ?? "").trim().toLowerCase();
+    if (allow === "1" || allow === "true" || allow === "yes" || allow === "on") {
+        return null;
+    }
+    const base = path.basename(absPath);
+    const baseLower = base.toLowerCase();
+    const norm = path.resolve(absPath).replace(/\\/g, "/").toLowerCase();
+    if (SENSITIVE_BASENAME_EXACT.has(baseLower) || baseLower.startsWith(".env.")) {
+        return {
+            blocked: true,
+            code: "WRITE_SENSITIVE_PATH",
+            reason: `refusing to write sensitive file '${base}'. Set QLING_ALLOW_SENSITIVE_WRITE=1 to override.`,
+        };
+    }
+    if (SENSITIVE_BASENAME_SUFFIXES.some((s) => baseLower.endsWith(s))) {
+        return {
+            blocked: true,
+            code: "WRITE_SENSITIVE_PATH",
+            reason: `refusing to write key-like file '${base}'. Set QLING_ALLOW_SENSITIVE_WRITE=1 to override.`,
+        };
+    }
+    // 路径中显式 .git/credentials 等
+    if (norm.includes("/.git/credentials") || norm.endsWith("/.git-credentials")) {
+        return {
+            blocked: true,
+            code: "WRITE_SENSITIVE_PATH",
+            reason: "refusing to write git credentials store.",
+        };
+    }
+    return null;
+}
+export function resolveToolPath(inputPath, roots, defaultRoot = "workspace") {
+    const raw = inputPath.trim();
+    if (!raw)
+        return raw;
+    const normalized = raw.replace(/\\/g, "/");
+    if (normalized.startsWith("workspace_dir/")) {
+        const rel = normalized.slice("workspace_dir/".length);
+        const base = roots.workspaceDir ?? roots.fileCacheDir;
+        return path.resolve(base, rel);
+    }
+    if (normalized.startsWith("file_cache_dir/")) {
+        return path.resolve(roots.fileCacheDir, normalized.slice("file_cache_dir/".length));
+    }
+    if (normalized.startsWith("file_state_dir/")) {
+        return path.resolve(roots.fileStateDir, normalized.slice("file_state_dir/".length));
+    }
+    if (path.isAbsolute(raw)) {
+        return path.resolve(raw);
+    }
+    const fallback = pickDefaultRoot(defaultRoot, roots);
+    return path.resolve(fallback, raw);
+}
+export function isWithinAllowedRoots(absPath, roots) {
+    const candidates = [roots.fileCacheDir, roots.fileStateDir];
+    if (roots.workspaceDir)
+        candidates.push(roots.workspaceDir);
+    const target = path.resolve(absPath);
+    return candidates.some((root) => isSubPath(target, path.resolve(root)));
+}
+function pickDefaultRoot(kind, roots) {
+    if (kind === "file_cache")
+        return roots.fileCacheDir;
+    if (kind === "file_state")
+        return roots.fileStateDir;
+    return roots.workspaceDir ?? roots.fileCacheDir;
+}
+function isSubPath(target, base) {
+    const rel = path.relative(base, target);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}

package/dist/sdk.d.ts

@@ -0,0 +1,12 @@
+export { AgentLoop, type LlmSessionPatch } from "./agent-loop.js";
+export { loadQlingConfig, applyConfigToProcessEnv, buildDefaultConfig, guardConfigFromEnv, type QlingConfig, type CliGlobalOptions, type LoadedConfig, } from "./config.js";
+export { getProviderPreset, listProviderPresets, resolveModelCandidates, type ProviderPreset, } from "./providers/presets.js";
+export { getMcpPreset, listMcpPresets, type McpPreset, } from "./mcp/presets.js";
+export { addMcpPresetToStore, loadMcpStore, saveMcpStore, defaultMcpStorePath, type McpStoreFile, } from "./mcp/store.js";
+export { getRuntimeRootsFromEnv, isPathAllowedForWrite, checkSensitiveWriteTarget, resolveWriteSandboxMode, type RuntimeRoots, type WriteSandboxMode, } from "./runtime-paths.js";
+export { runEvalSuite, formatEvalReport, type RunEvalOptions, } from "./eval/runner.js";
+export { buildEvalSmokeTasks } from "./eval/tasks.js";
+export { ALL_TOOLS, buildToolRegistry, dispatch } from "./tools/index.js";
+export { getPackageVersion, formatCliVersion, formatDaemonVersion, } from "./package-version.js";
+export type { AgentConfig, Message, ToolDefinition, ToolResult } from "./types.js";
+//# sourceMappingURL=sdk.d.ts.map

package/dist/sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../src/sdk.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,KAAK,cAAc,GACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,YAAY,EACZ,cAAc,EACd,KAAK,SAAS,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,KAAK,YAAY,GAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,EACzB,uBAAuB,EACvB,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/sdk.js

@@ -0,0 +1,18 @@
+// ============================================================
+// 轻灵 Qling — SDK 导出面（Phase 2.0 雏形）
+//
+// 用法:
+//   import { AgentLoop, loadQlingConfig, listProviderPresets } from "@qlingzzy/qling";
+//
+// 说明: 此为可嵌入入口；CLI 入口仍是 dist/index.js (bin: qling)
+// ============================================================
+export { AgentLoop } from "./agent-loop.js";
+export { loadQlingConfig, applyConfigToProcessEnv, buildDefaultConfig, guardConfigFromEnv, } from "./config.js";
+export { getProviderPreset, listProviderPresets, resolveModelCandidates, } from "./providers/presets.js";
+export { getMcpPreset, listMcpPresets, } from "./mcp/presets.js";
+export { addMcpPresetToStore, loadMcpStore, saveMcpStore, defaultMcpStorePath, } from "./mcp/store.js";
+export { getRuntimeRootsFromEnv, isPathAllowedForWrite, checkSensitiveWriteTarget, resolveWriteSandboxMode, } from "./runtime-paths.js";
+export { runEvalSuite, formatEvalReport, } from "./eval/runner.js";
+export { buildEvalSmokeTasks } from "./eval/tasks.js";
+export { ALL_TOOLS, buildToolRegistry, dispatch } from "./tools/index.js";
+export { getPackageVersion, formatCliVersion, formatDaemonVersion, } from "./package-version.js";

package/dist/session/daemon-session-api.d.ts

@@ -0,0 +1,22 @@
+import type { SessionTask } from "./session-scheduler.js";
+import type { SessionGoalState } from "./session-goal-manager.js";
+export declare class DaemonSessionApi {
+    private readonly client;
+    constructor(baseUrl?: string);
+    createLoopTask(sessionId: string, payload: {
+        prompt: string;
+        intervalMs: number;
+        mode: "fixed" | "default";
+        runner: "daemon";
+    }): Promise<SessionTask>;
+    setGoal(sessionId: string, condition: string, stats?: {
+        turnCount: number;
+        tokens: number;
+    }): Promise<SessionGoalState>;
+    clearGoal(sessionId: string): Promise<SessionGoalState>;
+    getGoal(sessionId: string): Promise<SessionGoalState | null>;
+    listLoopTasks(sessionId: string): Promise<SessionTask[]>;
+    cancelLoopTask(sessionId: string, taskId: string): Promise<SessionTask>;
+    clearLoopTasks(sessionId: string): Promise<number>;
+}
+//# sourceMappingURL=daemon-session-api.d.ts.map