@qlingzzy/qling 1.0.0

package/dist/metrics/collector.d.ts

@@ -0,0 +1,17 @@
+import type { MetricEvent, MetricsQuery } from "./types.js";
+export declare class MetricsCollector {
+    private metricsDir;
+    private buffer;
+    private sessionId;
+    private flushIntervalMs;
+    constructor(metricsDir: string, sessionId: string, flushIntervalMs?: number);
+    init(): Promise<void>;
+    record(event: Omit<MetricEvent, "ts" | "session_id">): void;
+    flush(): Promise<void>;
+    query(query: MetricsQuery): Promise<MetricEvent[]>;
+    startAutoFlush(): ReturnType<typeof setInterval>;
+    stopAutoFlush(timer: ReturnType<typeof setInterval>): void;
+    purgeOldEntries(retentionDays: number): Promise<number>;
+    private matchesQuery;
+}
+//# sourceMappingURL=collector.d.ts.map

package/dist/metrics/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../src/metrics/collector.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAS;gBAEpB,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAE,MAAe;IAM7E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,YAAY,CAAC,GAAG,IAAI;IAYrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBtB,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA6BxD,cAAc,IAAI,UAAU,CAAC,OAAO,WAAW,CAAC;IAMhD,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,GAAG,IAAI;IAIpD,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuC7D,OAAO,CAAC,YAAY;CAOrB"}

package/dist/metrics/collector.js

@@ -0,0 +1,137 @@
+// ============================================================
+// 轻灵 - Metrics Collector（JSONL 指标收集器）
+// ============================================================
+import * as fs from "fs/promises";
+import * as fsSync from "fs";
+import * as path from "path";
+export class MetricsCollector {
+    metricsDir;
+    buffer = [];
+    sessionId;
+    flushIntervalMs;
+    constructor(metricsDir, sessionId, flushIntervalMs = 10_000) {
+        this.metricsDir = metricsDir;
+        this.sessionId = sessionId;
+        this.flushIntervalMs = flushIntervalMs;
+    }
+    async init() {
+        await fs.mkdir(this.metricsDir, { recursive: true });
+    }
+    record(event) {
+        this.buffer.push({
+            ...event,
+            ts: Date.now(),
+            session_id: this.sessionId,
+        });
+        if (this.buffer.length >= 100) {
+            // auto-flush when buffer is large
+            this.flush().catch(() => { });
+        }
+    }
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        const events = [...this.buffer];
+        this.buffer = [];
+        const date = new Date().toISOString().slice(0, 10);
+        const filePath = path.join(this.metricsDir, `metrics-${date}.jsonl`);
+        const lines = events.map((e) => JSON.stringify(e)).join("\n") + "\n";
+        try {
+            await fs.appendFile(filePath, lines, "utf-8");
+        }
+        catch (err) {
+            // put events back in buffer
+            this.buffer.unshift(...events);
+            console.error("[Metrics] flush failed: " + err.message);
+        }
+    }
+    async query(query) {
+        if (!fsSync.existsSync(this.metricsDir))
+            return [];
+        const files = await fs.readdir(this.metricsDir);
+        const jsonlFiles = files.filter((f) => f.startsWith("metrics-") && f.endsWith(".jsonl")).sort().reverse();
+        const results = [];
+        for (const file of jsonlFiles) {
+            if (query.limit && results.length >= query.limit)
+                break;
+            const filePath = path.join(this.metricsDir, file);
+            const raw = await fs.readFile(filePath, "utf-8");
+            for (const line of raw.split("\n")) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const event = JSON.parse(trimmed);
+                    if (this.matchesQuery(event, query)) {
+                        results.push(event);
+                    }
+                }
+                catch {
+                    // skip
+                }
+            }
+        }
+        if (query.limit)
+            return results.slice(0, query.limit);
+        return results;
+    }
+    startAutoFlush() {
+        return setInterval(() => {
+            this.flush().catch(() => { });
+        }, this.flushIntervalMs);
+    }
+    stopAutoFlush(timer) {
+        clearInterval(timer);
+    }
+    async purgeOldEntries(retentionDays) {
+        if (retentionDays <= 0)
+            return 0;
+        if (!fsSync.existsSync(this.metricsDir))
+            return 0;
+        const cutoff = Date.now() - retentionDays * 86_400_000;
+        const files = await fs.readdir(this.metricsDir);
+        const jsonlFiles = files.filter((f) => f.startsWith("metrics-") && f.endsWith(".jsonl"));
+        let purged = 0;
+        for (const file of jsonlFiles) {
+            const filePath = path.join(this.metricsDir, file);
+            const raw = await fs.readFile(filePath, "utf-8");
+            const lines = raw.split("\n");
+            const kept = [];
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const event = JSON.parse(trimmed);
+                    if (event.ts >= cutoff) {
+                        kept.push(trimmed);
+                    }
+                    else {
+                        purged++;
+                    }
+                }
+                catch {
+                    kept.push(trimmed);
+                }
+            }
+            if (kept.length === 0) {
+                await fs.unlink(filePath);
+            }
+            else {
+                await fs.writeFile(filePath, kept.join("\n") + "\n", "utf-8");
+            }
+        }
+        return purged;
+    }
+    matchesQuery(event, query) {
+        if (query.type && event.type !== query.type)
+            return false;
+        if (query.session_id && event.session_id !== query.session_id)
+            return false;
+        if (query.from && event.ts < query.from)
+            return false;
+        if (query.to && event.ts > query.to)
+            return false;
+        return true;
+    }
+}

package/dist/metrics/types.d.ts

@@ -0,0 +1,14 @@
+export interface MetricEvent {
+    ts: number;
+    type: "turn_complete" | "tool_call" | "tool_error" | "memory_write" | "compaction" | "session_start" | "session_end";
+    session_id: string;
+    data: Record<string, unknown>;
+}
+export interface MetricsQuery {
+    type?: string;
+    session_id?: string;
+    from?: number;
+    to?: number;
+    limit?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/metrics/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/metrics/types.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,eAAe,GAAG,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,YAAY,GAAG,eAAe,GAAG,aAAa,CAAC;IACrH,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/metrics/types.js

@@ -0,0 +1,4 @@
+// ============================================================
+// 轻灵 - Metrics 类型
+// ============================================================
+export {};

package/dist/mission/manager.d.ts

@@ -0,0 +1,28 @@
+import { Mission, MissionStatus, MissionEvent } from "./types.js";
+export declare class MissionManager {
+    private stateDir;
+    private missions;
+    constructor(stateDir: string);
+    init(): Promise<void>;
+    createMission(name: string, description: string, sessionId: string, options?: {
+        sourceMissionId?: string;
+    }): Promise<Mission>;
+    updateStatus(id: string, status: MissionStatus, error?: Mission["error"], meta?: Record<string, unknown>): Promise<Mission>;
+    getMission(id: string): Mission | undefined;
+    getMissionOrThrow(id: string): Mission;
+    listMissions(): Mission[];
+    getMissionLogs(id: string): Promise<MissionEvent[]>;
+    appendLog(id: string, message: string, meta?: Record<string, unknown>): Promise<void>;
+    pauseMission(id: string, reason?: string): Promise<Mission>;
+    resumeMission(id: string, reason?: string): Promise<Mission>;
+    cancelMission(id: string, reason?: string): Promise<Mission>;
+    retryMission(id: string): Promise<Mission>;
+    private saveMission;
+    private loadMissions;
+    private getMissionPath;
+    private getEventPath;
+    private appendEvent;
+    private applyControlTransition;
+    private createMissionError;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/mission/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/mission/manager.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAKlE,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAmC;gBAEvC,QAAQ,EAAE,MAAM;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAOrB,aAAa,CACjB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAO,GACzC,OAAO,CAAC,OAAO,CAAC;IAmCb,YAAY,CAChB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,aAAa,EACrB,KAAK,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,EACxB,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,OAAO,CAAC;IA2BnB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI3C,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAQtC,YAAY,IAAI,OAAO,EAAE;IAKnB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAanD,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAezF,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI3D,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI5D,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkB5D,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YAyBlC,WAAW;YAKX,YAAY;IAe1B,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,YAAY;YAIN,WAAW;YAKX,sBAAsB;IAiCpC,OAAO,CAAC,kBAAkB;CAM3B"}

package/dist/mission/manager.js

@@ -0,0 +1,208 @@
+// ============================================================
+// 轻灵 - Mission Manager (v0.5)
+// 负责 Mission 的持久化、状态流转与队列管理
+// ============================================================
+import * as fs from "fs/promises";
+import * as path from "path";
+import { existsSync } from "fs";
+const TERMINAL_STATUSES = new Set(["succeeded", "failed", "canceled"]);
+const PAUSABLE_STATUSES = new Set(["queued", "running", "blocked"]);
+export class MissionManager {
+    stateDir;
+    missions = new Map();
+    constructor(stateDir) {
+        this.stateDir = path.join(stateDir, "missions");
+    }
+    async init() {
+        if (!existsSync(this.stateDir)) {
+            await fs.mkdir(this.stateDir, { recursive: true });
+        }
+        await this.loadMissions();
+    }
+    async createMission(name, description, sessionId, options = {}) {
+        const mission = {
+            id: `msn_${Date.now()}_${Math.random().toString(36).slice(2, 7)}`,
+            name,
+            description,
+            status: "queued",
+            sessionId,
+            sourceMissionId: options.sourceMissionId,
+            lastContext: [],
+            metrics: {
+                startTime: Date.now(),
+                totalTurns: 0,
+                totalTokens: 0,
+                totalToolCalls: 0,
+            },
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+        };
+        this.missions.set(mission.id, mission);
+        await this.saveMission(mission);
+        await this.appendEvent({
+            missionId: mission.id,
+            type: "state_changed",
+            timestamp: Date.now(),
+            data: {
+                from: null,
+                to: "queued",
+                reason: "mission_created",
+                sourceMissionId: options.sourceMissionId ?? null,
+            },
+        });
+        return mission;
+    }
+    async updateStatus(id, status, error, meta = {}) {
+        const mission = this.getMissionOrThrow(id);
+        const previousStatus = mission.status;
+        mission.status = status;
+        if (error)
+            mission.error = error;
+        else if (status !== "failed")
+            delete mission.error;
+        mission.updatedAt = Date.now();
+        if (TERMINAL_STATUSES.has(status))
+            mission.metrics.endTime = Date.now();
+        else
+            delete mission.metrics.endTime;
+        await this.saveMission(mission);
+        await this.appendEvent({
+            missionId: mission.id,
+            type: "state_changed",
+            timestamp: Date.now(),
+            data: {
+                from: previousStatus,
+                to: status,
+                error: error ? { ...error } : null,
+                ...meta,
+            },
+        });
+        return mission;
+    }
+    getMission(id) {
+        return this.missions.get(id);
+    }
+    getMissionOrThrow(id) {
+        const mission = this.missions.get(id);
+        if (!mission) {
+            throw this.createMissionError("MISSION_NOT_FOUND", `mission not found: ${id}`, 404);
+        }
+        return mission;
+    }
+    listMissions() {
+        return Array.from(this.missions.values())
+            .sort((a, b) => b.createdAt - a.createdAt);
+    }
+    async getMissionLogs(id) {
+        this.getMissionOrThrow(id);
+        const filePath = this.getEventPath(id);
+        if (!existsSync(filePath))
+            return [];
+        const raw = await fs.readFile(filePath, "utf-8");
+        return raw
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    async appendLog(id, message, meta = {}) {
+        const mission = this.getMissionOrThrow(id);
+        mission.updatedAt = Date.now();
+        await this.saveMission(mission);
+        await this.appendEvent({
+            missionId: id,
+            type: "log",
+            timestamp: Date.now(),
+            data: {
+                message,
+                ...meta,
+            },
+        });
+    }
+    async pauseMission(id, reason) {
+        return this.applyControlTransition(id, "pause", "paused", PAUSABLE_STATUSES, reason);
+    }
+    async resumeMission(id, reason) {
+        return this.applyControlTransition(id, "resume", "queued", new Set(["paused"]), reason);
+    }
+    async cancelMission(id, reason) {
+        const mission = this.getMissionOrThrow(id);
+        if (TERMINAL_STATUSES.has(mission.status)) {
+            throw this.createMissionError("MISSION_INVALID_TRANSITION", `mission ${id} is already terminal (${mission.status})`, 409);
+        }
+        return this.applyControlTransition(id, "cancel", "canceled", new Set(["queued", "running", "blocked", "paused"]), reason);
+    }
+    async retryMission(id) {
+        const mission = this.getMissionOrThrow(id);
+        if (!TERMINAL_STATUSES.has(mission.status)) {
+            throw this.createMissionError("MISSION_INVALID_TRANSITION", `mission ${id} must be terminal before retry`, 409);
+        }
+        await this.appendEvent({
+            missionId: id,
+            type: "control",
+            timestamp: Date.now(),
+            data: {
+                action: "retry",
+                from: mission.status,
+            },
+        });
+        return this.createMission(mission.name, mission.description, mission.sessionId, {
+            sourceMissionId: mission.id,
+        });
+    }
+    async saveMission(mission) {
+        const filePath = this.getMissionPath(mission.id);
+        await fs.writeFile(filePath, JSON.stringify(mission, null, 2), "utf-8");
+    }
+    async loadMissions() {
+        const files = await fs.readdir(this.stateDir);
+        for (const file of files) {
+            if (file.endsWith(".json")) {
+                try {
+                    const raw = await fs.readFile(path.join(this.stateDir, file), "utf-8");
+                    const mission = JSON.parse(raw);
+                    this.missions.set(mission.id, mission);
+                }
+                catch (err) {
+                    console.error(`[MissionManager] Failed to load mission ${file}: ${err.message}`);
+                }
+            }
+        }
+    }
+    getMissionPath(id) {
+        return path.join(this.stateDir, `${id}.json`);
+    }
+    getEventPath(id) {
+        return path.join(this.stateDir, `${id}.events.jsonl`);
+    }
+    async appendEvent(event) {
+        const filePath = this.getEventPath(event.missionId);
+        await fs.appendFile(filePath, JSON.stringify(event) + "\n", "utf-8");
+    }
+    async applyControlTransition(id, action, nextStatus, allowedFrom, reason) {
+        const mission = this.getMissionOrThrow(id);
+        if (!allowedFrom.has(mission.status)) {
+            throw this.createMissionError("MISSION_INVALID_TRANSITION", `mission ${id} cannot ${action} from ${mission.status}; allowed from ${Array.from(allowedFrom).join(", ")}`, 409);
+        }
+        await this.appendEvent({
+            missionId: id,
+            type: "control",
+            timestamp: Date.now(),
+            data: {
+                action,
+                from: mission.status,
+                reason: reason ?? null,
+            },
+        });
+        return this.updateStatus(id, nextStatus, undefined, {
+            action,
+            reason: reason ?? null,
+        });
+    }
+    createMissionError(code, message, statusCode) {
+        const error = new Error(message);
+        error.code = code;
+        error.statusCode = statusCode;
+        return error;
+    }
+}

package/dist/mission/types.d.ts

@@ -0,0 +1,37 @@
+import { Message } from "../types.js";
+export type MissionStatus = "queued" | "running" | "blocked" | "paused" | "succeeded" | "failed" | "canceled";
+export interface Mission {
+    id: string;
+    name: string;
+    description: string;
+    status: MissionStatus;
+    /** 关联的会话与工作流信息 */
+    sessionId: string;
+    workflowRunId?: string;
+    sourceMissionId?: string;
+    /** 执行上下文快照 */
+    lastContext: Message[];
+    /** 统计数据 */
+    metrics: {
+        startTime: number;
+        endTime?: number;
+        totalTurns: number;
+        totalTokens: number;
+        totalToolCalls: number;
+    };
+    /** 错误信息 */
+    error?: {
+        message: string;
+        code: string;
+        stack?: string;
+    };
+    createdAt: number;
+    updatedAt: number;
+}
+export interface MissionEvent {
+    missionId: string;
+    type: "state_changed" | "control" | "log";
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mission/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mission/types.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAwB,MAAM,aAAa,CAAC;AAG5D,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,SAAS,GACT,SAAS,GACT,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,UAAU,CAAC;AAEf,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;IAEtB,kBAAkB;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,cAAc;IACd,WAAW,EAAE,OAAO,EAAE,CAAC;IAEvB,WAAW;IACX,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IAEF,WAAW;IACX,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IAEF,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,eAAe,GAAG,SAAS,GAAG,KAAK,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B"}

package/dist/mission/types.js

@@ -0,0 +1,5 @@
+// ============================================================
+// 轻灵 - Mission Types (v0.5)
+// 使命级任务模型：支持异步脱离、队列管理与全局状态追踪
+// ============================================================
+export {};

package/dist/onboarding/tutorial.d.ts

@@ -0,0 +1,33 @@
+export interface OnboardingStep {
+    id: string;
+    title: string;
+    detail: string;
+    example?: string;
+}
+export interface OnboardingCardOptions {
+    /** 产品显示名 */
+    productName?: string;
+    /** 是否强调 API key 配置 */
+    needSetup?: boolean;
+}
+/**
+ * 首次启动 3 步任务（纯数据，可单测）。
+ */
+export declare function buildOnboardingSteps(options?: OnboardingCardOptions): OnboardingStep[];
+/**
+ * 格式化首次启动卡片（不调用模型、不上传）。
+ */
+export declare function formatOnboardingCard(options?: OnboardingCardOptions): string[];
+export declare function resolveOnboardedPath(stateDir: string): string;
+export declare function hasCompletedOnboarding(stateDir: string): Promise<boolean>;
+export declare function markOnboardingComplete(stateDir: string): Promise<void>;
+export declare function checkOnboarding(options?: {
+    stateDir?: string | null;
+    needSetup?: boolean;
+    /** 强制展示（测试用） */
+    force?: boolean;
+    write?: (line: string) => void;
+}): Promise<{
+    shown: boolean;
+}>;
+//# sourceMappingURL=tutorial.d.ts.map

package/dist/onboarding/tutorial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutorial.d.ts","sourceRoot":"","sources":["../../src/onboarding/tutorial.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,EAAE,CAgC1F;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,MAAM,EAAE,CAuBlF;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/E;AAED,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5E;AAED,wBAAsB,eAAe,CACnC,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3B,GACL,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAoB7B"}

package/dist/onboarding/tutorial.js

@@ -0,0 +1,96 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+import { stdin as input } from "process";
+/**
+ * 首次启动 3 步任务（纯数据，可单测）。
+ */
+export function buildOnboardingSteps(options = {}) {
+    const steps = [
+        {
+            id: "task",
+            title: "发一条真实任务",
+            detail: "直接输入自然语言任务，让 Agent 使用本机工具完成。",
+            example: "分析这个仓库的结构",
+        },
+        {
+            id: "slash",
+            title: "打开本地控制面",
+            detail: "输入 / 打开命令面板；Tab 补全；方向键选择。",
+            example: "/help  或  /statusline",
+        },
+        {
+            id: "doctor",
+            title: "检查环境与隐私边界",
+            detail: "确认配置、状态目录与数据留存路径。",
+            example: "/doctor   然后   /privacy",
+        },
+    ];
+    if (options.needSetup) {
+        steps.unshift({
+            id: "setup",
+            title: "先完成 LLM 配置",
+            detail: "运行 setup 选择 Provider/Model；API key 写入系统环境变量，勿写入 .env。",
+            example: "qling setup",
+        });
+    }
+    return steps;
+}
+/**
+ * 格式化首次启动卡片（不调用模型、不上传）。
+ */
+export function formatOnboardingCard(options = {}) {
+    const product = options.productName?.trim() || "轻灵 Qling";
+    const steps = buildOnboardingSteps(options);
+    const lines = [
+        "",
+        `${product} · 本地工作台`,
+        "-----------------------------------------",
+        "首次使用 · 按下面步骤开始（本地引导，不调用模型）:",
+    ];
+    steps.forEach((step, index) => {
+        lines.push(`${index + 1}. ${step.title}`);
+        lines.push(`   ${step.detail}`);
+        if (step.example) {
+            lines.push(`   例: ${step.example}`);
+        }
+    });
+    lines.push("-----------------------------------------");
+    lines.push("提示: 完成后可用 /expand、/plan、/model list 继续探索。");
+    lines.push("安装与分发: 见 docs/install.md 与 README.en.md");
+    lines.push("");
+    return lines;
+}
+export function resolveOnboardedPath(stateDir) {
+    return path.join(path.resolve(stateDir), ".onboarded");
+}
+export async function hasCompletedOnboarding(stateDir) {
+    try {
+        await fs.access(resolveOnboardedPath(stateDir));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function markOnboardingComplete(stateDir) {
+    await fs.mkdir(path.resolve(stateDir), { recursive: true });
+    await fs.writeFile(resolveOnboardedPath(stateDir), new Date().toISOString() + "\n", "utf-8");
+}
+export async function checkOnboarding(options = {}) {
+    if (!options.force && !input.isTTY) {
+        return { shown: false };
+    }
+    const stateDir = options.stateDir ? path.resolve(options.stateDir) : path.join(os.homedir(), ".qling");
+    if (!options.force && (await hasCompletedOnboarding(stateDir))) {
+        return { shown: false };
+    }
+    const write = options.write ?? ((line) => console.log(line));
+    for (const line of formatOnboardingCard({ needSetup: options.needSetup })) {
+        write(line);
+    }
+    if (!options.force) {
+        await markOnboardingComplete(stateDir);
+    }
+    return { shown: true };
+}

package/dist/output-style.d.ts

@@ -0,0 +1,14 @@
+export type KeyValueRow = readonly [label: string, value: unknown];
+export interface LocalPanelSection {
+    heading: string;
+    rows: readonly KeyValueRow[];
+}
+export interface LocalPanelOptions {
+    icon?: string;
+    title: string;
+    sections: readonly LocalPanelSection[];
+    boundary: string;
+}
+export declare function formatKeyValueRows(rows: readonly KeyValueRow[]): string[];
+export declare function formatLocalPanel(options: LocalPanelOptions): string[];
+//# sourceMappingURL=output-style.d.ts.map

package/dist/output-style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-style.d.ts","sourceRoot":"","sources":["../src/output-style.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAEnE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,QAAQ,EAAE,MAAM,CAAC;CAClB;AASD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,EAAE,CAIzE;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,EAAE,CAkBrE"}

package/dist/output-style.js

@@ -0,0 +1,29 @@
+const PANEL_RULE = "─────────────────────────────────────────";
+function formatValue(value) {
+    if (value === null || value === undefined || value === "")
+        return "-";
+    return String(value);
+}
+export function formatKeyValueRows(rows) {
+    const labels = rows.map(([label]) => label);
+    const width = labels.reduce((max, label) => Math.max(max, label.length), 0);
+    return rows.map(([label, value]) => `${label.padEnd(width, " ")} : ${formatValue(value)}`);
+}
+export function formatLocalPanel(options) {
+    const icon = options.icon?.trim() || "◇";
+    const lines = [
+        "",
+        `${icon} 轻灵 · ${options.title}`,
+        PANEL_RULE,
+    ];
+    options.sections.forEach((section, index) => {
+        if (index > 0)
+            lines.push("");
+        lines.push(`▸ ${section.heading}`);
+        lines.push(...formatKeyValueRows(section.rows).map((line) => `  ${line}`));
+    });
+    lines.push(PANEL_RULE);
+    lines.push(`边界 : ${options.boundary}`);
+    lines.push("");
+    return lines;
+}

package/dist/package-version.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 返回当前包版本（如 1.0.0）。失败时回退 0.0.0。
+ * 从 dist/* 向上两级定位 package.json（与 src/dist 布局一致）。
+ */
+export declare function getPackageVersion(): string;
+/** CLI / health 展示用，如 qling/1.0.0 */
+export declare function formatCliVersion(binName?: string): string;
+/** daemon health 用，如 1.0.0-daemon */
+export declare function formatDaemonVersion(): string;
+/** 测试可重置缓存 */
+export declare function resetPackageVersionCache(): void;
+//# sourceMappingURL=package-version.d.ts.map