@mebular/fleet 0.0.0-stage → 0.1.0

package/dist/protocol/envelope.js

@@ -0,0 +1,169 @@
+// Mebular Fleet —— 任务 envelope 与显式状态机（M0 骨架；M1 扩展为完整模型）。
+//
+// **任务 = 记忆**：任务是一类带 `namespace`（如 `tasks`）的图上记忆，生命周期由**显式状态事件**
+// 驱动；`expiresAt` 只是本机任务板的**软约定**，不参与跨端一致性判定（见 `SEALING.md` 红线：
+// 墙钟不进一致性判定）。本文件**只消费 `@mebular/core` 的公共 API**，不在 core 引入任务语义。
+/** 协议版本（envelope 线格式版本；改动 = 破坏性，需全端同版本）。 */
+export const FLEET_PROTOCOL_VERSION = 1;
+/**
+ * 任务状态（**单调秩**，用于并发/乱序下的确定性收敛）：
+ * - `queued` → `claimed` → `running` → `done` | `failed`
+ * - `done` / `failed` 为**终态**（同秩，平局由 `TERMINAL_PRECEDENCE` 兜底）。
+ */
+export const TASK_STATUSES = ['queued', 'claimed', 'running', 'done', 'failed'];
+/** 状态秩：`done`/`failed` 同秩（终态），其余严格递增。 */
+export const STATUS_RANK = {
+    queued: 0,
+    claimed: 1,
+    running: 2,
+    done: 3,
+    failed: 3,
+};
+/** 终态平局裁决：数值大者胜（确定性）。 */
+export const TERMINAL_PRECEDENCE = {
+    queued: 0,
+    claimed: 0,
+    running: 0,
+    failed: 2,
+    done: 1,
+};
+/** root 级派发策略：`children-ok`（默认，可派生）| `root-only`（执行者只能干、不得再派）。 */
+export const DISPATCH_POLICIES = ['children-ok', 'root-only'];
+/** root 预算默认值（W1 上界，可由 root 收紧）。 */
+export const DEFAULT_ROOT_BUDGET = { maxDepth: 8, maxChildren: 16, maxTasks: 256 };
+/** 预算合法性（非负整数；越界由树不变式判定，这里只做形状）。 */
+export function isTaskBudget(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const b = value;
+    return (Number.isInteger(b.maxDepth) && b.maxDepth >= 0 &&
+        Number.isInteger(b.maxChildren) && b.maxChildren >= 0 &&
+        Number.isInteger(b.maxTasks) && b.maxTasks >= 0);
+}
+/** 派发策略守卫。 */
+export function isTaskDispatch(value) {
+    return typeof value === 'string' && DISPATCH_POLICIES.includes(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/** 端标识守卫（`{device,agent}` 均为非空字符串）。 */
+export function isFleetEndpoint(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const e = value;
+    return isNonEmptyString(e.device) && isNonEmptyString(e.agent);
+}
+/** 状态判定。 */
+export function isTaskStatus(value) {
+    return typeof value === 'string' && TASK_STATUSES.includes(value);
+}
+/** 终态判定。 */
+export function isTerminal(status) {
+    return status === 'done' || status === 'failed';
+}
+/**
+ * 确定性状态裁决：返回 `a` / `b` 中更靠后的那个（收敛用，与到达顺序无关）。
+ * 先比 `STATUS_RANK`；同秩（终态）比 `TERMINAL_PRECEDENCE`；再平局取字典序大的状态名。
+ */
+export function resolveStatus(a, b) {
+    if (STATUS_RANK[a] !== STATUS_RANK[b])
+        return STATUS_RANK[a] > STATUS_RANK[b] ? a : b;
+    if (TERMINAL_PRECEDENCE[a] !== TERMINAL_PRECEDENCE[b]) {
+        return TERMINAL_PRECEDENCE[a] > TERMINAL_PRECEDENCE[b] ? a : b;
+    }
+    return a >= b ? a : b;
+}
+/**
+ * 合法迁移表（显式，避免跳级；与 `protocol/state-machine.json` 一致）。
+ * 非法迁移必须被拒绝（M1 负例）。
+ */
+export const TASK_TRANSITIONS = {
+    queued: ['claimed', 'failed'],
+    claimed: ['running', 'failed'],
+    running: ['done', 'failed'],
+    done: [],
+    failed: [],
+};
+/** 状态是否可迁移（`from === to` 视为幂等自迁移）。 */
+export function canTransition(from, to) {
+    if (from === to)
+        return true;
+    return TASK_TRANSITIONS[from].includes(to);
+}
+/** 校验一个未知输入是否为合法 `TaskEnvelope`（不做数值语义裁决）。 */
+export function validateEnvelope(input) {
+    const errors = [];
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return { ok: false, errors: ['envelope 必须是对象'] };
+    }
+    const e = input;
+    if (e.v !== FLEET_PROTOCOL_VERSION)
+        errors.push(`v 必须为 ${FLEET_PROTOCOL_VERSION}`);
+    if (!isNonEmptyString(e.taskId))
+        errors.push('taskId 必须为非空字符串');
+    if (!isFleetEndpoint(e.from))
+        errors.push('from 必须为 {device,agent} 非空字符串');
+    if (!isFleetEndpoint(e.to))
+        errors.push('to 必须为 {device,agent} 非空字符串');
+    if (!isNonEmptyString(e.intent))
+        errors.push('intent 必须为非空字符串');
+    if (e.payloadRef !== undefined && !isNonEmptyString(e.payloadRef)) {
+        errors.push('payloadRef 若存在须为非空字符串');
+    }
+    if (!isTaskStatus(e.status))
+        errors.push(`status 必须为 ${TASK_STATUSES.join('|')}`);
+    if (typeof e.attempts !== 'number' || !Number.isInteger(e.attempts) || e.attempts < 0) {
+        errors.push('attempts 必须为非负整数');
+    }
+    if (e.expiresAt !== undefined && (typeof e.expiresAt !== 'number' || !Number.isFinite(e.expiresAt))) {
+        errors.push('expiresAt 若存在须为有限数字（软约定，不参与跨端状态）');
+    }
+    if (typeof e.trace !== 'object' || e.trace === null) {
+        errors.push('trace 必须为对象');
+    }
+    else {
+        const trace = e.trace;
+        if (trace.causedBy !== undefined && !isNonEmptyString(trace.causedBy)) {
+            errors.push('trace.causedBy 若存在须为非空字符串');
+        }
+        if (!Array.isArray(trace.chain) || !trace.chain.every(isNonEmptyString)) {
+            errors.push('trace.chain 必须为字符串数组');
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}
+/** 递归键序规范化（键按字典序，`undefined` 丢弃）→ 同一对象恒得同一字节串。 */
+function canonicalize(input) {
+    if (Array.isArray(input))
+        return input.map(canonicalize);
+    if (typeof input === 'object' && input !== null) {
+        const src = input;
+        const out = {};
+        for (const key of Object.keys(src).sort()) {
+            if (src[key] !== undefined)
+                out[key] = canonicalize(src[key]);
+        }
+        return out;
+    }
+    return input;
+}
+/** 序列化为**确定序** JSON（同一 envelope → 同一字节串）。 */
+export function serializeEnvelope(envelope) {
+    return JSON.stringify(canonicalize(envelope));
+}
+/** 解析并校验；非法输入抛错（错误信息含全部违规项）。 */
+export function parseEnvelope(json) {
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch (error) {
+        throw new Error(`envelope JSON 解析失败：${error.message}`);
+    }
+    const result = validateEnvelope(raw);
+    if (!result.ok)
+        throw new Error(`envelope 非法：${result.errors.join('; ')}`);
+    return raw;
+}
+//# sourceMappingURL=envelope.js.map

package/dist/protocol/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/protocol/envelope.ts"],"names":[],"mappings":"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"}

package/dist/protocol/events.d.ts

@@ -0,0 +1,51 @@
+import { type FleetEndpoint, type FleetTrace, type TaskBudget, type TaskDispatch, type TaskStatus } from './envelope.js';
+/** 事件类型。 */
+export declare const TASK_EVENT_TYPES: readonly ["created", "claimed", "running", "done", "failed"];
+export type TaskEventType = (typeof TASK_EVENT_TYPES)[number];
+/** 事件类型 → 目标权威状态（一一对应）。 */
+export declare const EVENT_TO_STATUS: Readonly<Record<TaskEventType, TaskStatus>>;
+/** 任务事件（线格式）。 */
+export interface TaskEvent {
+    /** 协议版本 */
+    v: number;
+    /** 事件唯一 ID（内容寻址或全局唯一；**幂等键**：重复投递按此去重） */
+    eventId: string;
+    /** 所属任务 */
+    taskId: string;
+    /** 事件类型 */
+    type: TaskEventType;
+    /** 发出该事件的端 */
+    actor: FleetEndpoint;
+    /** 本机墙钟（**advisory**：不参与收敛） */
+    at: number;
+    /** 迁移后的权威状态（必须与 `type` 一致） */
+    toStatus: TaskStatus;
+    /** 因果链 */
+    trace: FleetTrace;
+    /** `created` 事件必填：目标端 */
+    to?: FleetEndpoint;
+    /** `created` 事件必填：意图 */
+    intent?: string;
+    /** `created` 事件可选：**软约定**到期（不参与权威判定） */
+    expiresAt?: number;
+    /** 结果/负载引用（`done` 常带） */
+    payloadRef?: string;
+    /** 失败原因（`failed` 常带） */
+    reason?: string;
+    /** **W1**：`created` 可声明子树预算（随树单调递减；缺省 root 用默认/子任务按父推导） */
+    budget?: TaskBudget;
+    /** **W1**：`created`（root）可声明派发策略；缺省 `children-ok` */
+    dispatch?: TaskDispatch;
+}
+/** 事件类型守卫。 */
+export declare function isTaskEventType(value: unknown): value is TaskEventType;
+/** 校验结果。 */
+export interface TaskEventValidation {
+    ok: boolean;
+    errors: string[];
+}
+/** 校验未知输入是否为合法 `TaskEvent`（不做迁移合法性判定）。 */
+export declare function validateTaskEvent(input: unknown): TaskEventValidation;
+/** 便于测试/构造的校验快捷键。 */
+export declare function isTaskEvent(input: unknown): input is TaskEvent;
+//# sourceMappingURL=events.d.ts.map

package/dist/protocol/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/protocol/events.ts"],"names":[],"mappings":"AAMA,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AAEvB,YAAY;AACZ,eAAO,MAAM,gBAAgB,8DAA+D,CAAC;AAC7F,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,2BAA2B;AAC3B,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,UAAU,CAAC,CAMvE,CAAC;AAEF,iBAAiB;AACjB,MAAM,WAAW,SAAS;IACxB,WAAW;IACX,CAAC,EAAE,MAAM,CAAC;IACV,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IACf,WAAW;IACX,IAAI,EAAE,aAAa,CAAC;IACpB,cAAc;IACd,KAAK,EAAE,aAAa,CAAC;IACrB,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,QAAQ,EAAE,UAAU,CAAC;IACrB,UAAU;IACV,KAAK,EAAE,UAAU,CAAC;IAClB,yBAAyB;IACzB,EAAE,CAAC,EAAE,aAAa,CAAC;IACnB,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,cAAc;AACd,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED,YAAY;AACZ,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAMD,0CAA0C;AAC1C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA+CrE;AAED,qBAAqB;AACrB,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D"}

package/dist/protocol/events.js

@@ -0,0 +1,87 @@
+// Fleet 任务事件（M1）：**显式状态事件**驱动权威生命周期。
+//
+// 事件是任务（一类记忆）上的状态迁移记录。`at` 是**本机墙钟**，仅用于展示与本地排队，
+// **不参与**权威状态判定（见 `SEALING.md`：墙钟不进一致性判定）。收敛只由
+// `(状态秩, 终态平局裁决, eventId)` 决定（见 `model.ts`）。
+import { FLEET_PROTOCOL_VERSION, isTaskStatus, isFleetEndpoint, isTaskBudget, isTaskDispatch, } from './envelope.js';
+/** 事件类型。 */
+export const TASK_EVENT_TYPES = ['created', 'claimed', 'running', 'done', 'failed'];
+/** 事件类型 → 目标权威状态（一一对应）。 */
+export const EVENT_TO_STATUS = {
+    created: 'queued',
+    claimed: 'claimed',
+    running: 'running',
+    done: 'done',
+    failed: 'failed',
+};
+/** 事件类型守卫。 */
+export function isTaskEventType(value) {
+    return typeof value === 'string' && TASK_EVENT_TYPES.includes(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/** 校验未知输入是否为合法 `TaskEvent`（不做迁移合法性判定）。 */
+export function validateTaskEvent(input) {
+    const errors = [];
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return { ok: false, errors: ['event 必须是对象'] };
+    }
+    const e = input;
+    if (e.v !== FLEET_PROTOCOL_VERSION)
+        errors.push(`v 必须为 ${FLEET_PROTOCOL_VERSION}`);
+    if (!isNonEmptyString(e.eventId))
+        errors.push('eventId 必须为非空字符串');
+    if (!isNonEmptyString(e.taskId))
+        errors.push('taskId 必须为非空字符串');
+    if (!isTaskEventType(e.type))
+        errors.push(`type 必须为 ${TASK_EVENT_TYPES.join('|')}`);
+    if (!isFleetEndpoint(e.actor))
+        errors.push('actor 必须为 {device,agent} 非空字符串');
+    if (typeof e.at !== 'number' || !Number.isFinite(e.at))
+        errors.push('at 必须为有限数字');
+    if (!isTaskStatus(e.toStatus))
+        errors.push('toStatus 必须为合法任务状态');
+    else if (isTaskEventType(e.type) && EVENT_TO_STATUS[e.type] !== e.toStatus) {
+        errors.push(`toStatus 必须与 type 一致（${e.type} → ${EVENT_TO_STATUS[e.type]}）`);
+    }
+    if (typeof e.trace !== 'object' || e.trace === null) {
+        errors.push('trace 必须为对象');
+    }
+    else {
+        const trace = e.trace;
+        if (trace.causedBy !== undefined && !isNonEmptyString(trace.causedBy)) {
+            errors.push('trace.causedBy 若存在须为非空字符串');
+        }
+        if (!Array.isArray(trace.chain) || !trace.chain.every(isNonEmptyString)) {
+            errors.push('trace.chain 必须为字符串数组');
+        }
+    }
+    if (e.payloadRef !== undefined && !isNonEmptyString(e.payloadRef)) {
+        errors.push('payloadRef 若存在须为非空字符串');
+    }
+    if (e.reason !== undefined && !isNonEmptyString(e.reason)) {
+        errors.push('reason 若存在须为非空字符串');
+    }
+    if (e.type === 'created') {
+        if (!isFleetEndpoint(e.to))
+            errors.push('created 事件的 to 必须为 {device,agent}');
+        if (!isNonEmptyString(e.intent))
+            errors.push('created 事件的 intent 必须为非空字符串');
+    }
+    if (e.expiresAt !== undefined && (typeof e.expiresAt !== 'number' || !Number.isFinite(e.expiresAt))) {
+        errors.push('expiresAt 若存在须为有限数字（advisory）');
+    }
+    if (e.budget !== undefined && !isTaskBudget(e.budget)) {
+        errors.push('budget 若存在须为 {maxDepth,maxChildren,maxTasks} 非负整数');
+    }
+    if (e.dispatch !== undefined && !isTaskDispatch(e.dispatch)) {
+        errors.push('dispatch 若存在须为 children-ok|root-only');
+    }
+    return { ok: errors.length === 0, errors };
+}
+/** 便于测试/构造的校验快捷键。 */
+export function isTaskEvent(input) {
+    return validateTaskEvent(input).ok;
+}
+//# sourceMappingURL=events.js.map

package/dist/protocol/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/protocol/events.ts"],"names":[],"mappings":"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"}

package/dist/qr.d.ts

@@ -0,0 +1,15 @@
+export interface QrRenderResult {
+    /** 渲染产物（terminal/svg） */
+    value: string;
+    /** 渲染形态 */
+    kind: 'terminal' | 'svg';
+}
+export interface QrOptions {
+    /** 非致命渲染告警；调用方回退文本令牌/分组文本 */
+    onWarn?: (message: string) => void;
+}
+/** 终端二维码（ANSI 黑字白底；内容=令牌文本） */
+export declare function renderTerminalQr(text: string, options?: QrOptions): Promise<QrRenderResult | null>;
+/** SVG（控制台服务端渲染；前端以 data-uri <img> 展示，避免注入） */
+export declare function renderSvgQr(text: string, options?: QrOptions): Promise<QrRenderResult | null>;
+//# sourceMappingURL=qr.d.ts.map

package/dist/qr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr.d.ts","sourceRoot":"","sources":["../src/qr.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,IAAI,EAAE,UAAU,GAAG,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AA+BD,+BAA+B;AAC/B,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,SAAc,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAO5G;AAED,+CAA+C;AAC/C,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,SAAc,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAQvG"}

package/dist/qr.js

@@ -0,0 +1,52 @@
+// C7 · 配对二维码渲染（应用层能力；`qrcode-generator` 为普通运行时依赖）
+//
+// 语义：QR 内容 = **内联令牌文本本身**（不引自定义 scheme）；因此任何扫码器/文本通道等价。
+// 降级：编码失败 → 返回 null + 告警（**只给文本，不报错**）——绝不阻断邀请/加入。
+import qrcode from 'qrcode-generator';
+function makeQr(text) {
+    const qr = qrcode(0, 'M');
+    qr.addData(text);
+    qr.make();
+    return qr;
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+// qrcode-generator 的 ASCII 画法是「亮模块 = 块字符」，只适合深色终端。
+// 反相后固定 ANSI 黑字白底，使任何主题下都保持标准极性。
+const TERMINAL_INVERT = { ' ': '█', '▀': '▄', '▄': '▀', '█': ' ' };
+function invertTerminalArt(art) {
+    const lines = art.split('\n');
+    return lines
+        .map((line, index) => {
+        // QR module count 恒为奇数（17 + 4n），四模块静区使最后一行半行全是静区：
+        // 保持白色，避免反相成黑条。
+        const rendered = index === lines.length - 1
+            ? ' '.repeat(line.length)
+            : line.replace(/[█▀▄ ]/g, (ch) => TERMINAL_INVERT[ch] ?? ch);
+        return `\x1b[30;47m${rendered}\x1b[0m`;
+    })
+        .join('\n');
+}
+/** 终端二维码（ANSI 黑字白底；内容=令牌文本） */
+export async function renderTerminalQr(text, options = {}) {
+    try {
+        return { value: invertTerminalArt(makeQr(text).createASCII(1, 4)), kind: 'terminal' };
+    }
+    catch (error) {
+        options.onWarn?.(`二维码：终端渲染失败（${errorText(error)}）`);
+        return null;
+    }
+}
+/** SVG（控制台服务端渲染；前端以 data-uri <img> 展示，避免注入） */
+export async function renderSvgQr(text, options = {}) {
+    try {
+        const value = makeQr(text).createSvgTag({ cellSize: 4, margin: 1 });
+        return { value, kind: 'svg' };
+    }
+    catch (error) {
+        options.onWarn?.(`二维码：SVG 渲染失败（${errorText(error)}）`);
+        return null;
+    }
+}
+//# sourceMappingURL=qr.js.map

package/dist/qr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr.js","sourceRoot":"","sources":["../src/qr.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,wDAAwD;AACxD,mDAAmD;AAEnD,OAAO,MAAM,MAAM,kBAAkB,CAAC;AActC,SAAS,MAAM,CAAC,IAAY;IAC1B,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC1B,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,EAAE,CAAC,IAAI,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED,mDAAmD;AACnD,iCAAiC;AACjC,MAAM,eAAe,GAA2B,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAE3F,SAAS,iBAAiB,CAAC,GAAW;IACpC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,KAAK;SACT,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QACnB,kDAAkD;QAClD,gBAAgB;QAChB,MAAM,QAAQ,GAAG,KAAK,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC;YACzC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;YACzB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/D,OAAO,cAAc,QAAQ,SAAS,CAAC;IACzC,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,+BAA+B;AAC/B,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,UAAqB,EAAE;IAC1E,IAAI,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IACxF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,EAAE,CAAC,cAAc,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,+CAA+C;AAC/C,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,UAAqB,EAAE;IACrE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;QACpE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,EAAE,CAAC,gBAAgB,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/quickstart.d.ts

@@ -0,0 +1,167 @@
+import { type FleetAgentConfig, type FleetConfig } from './config.js';
+/** 加入码内信任材料的记录形状（Stage 2 将由令牌取代）。 */
+export interface JoinTrustMaterial {
+    publicKey: string;
+    privateKeyPkcs8: string;
+}
+export interface JoinCode {
+    v: 1;
+    kind: 'mebular-fleet-join';
+    /** 生成方的构建 SHA（join 侧版本核对；不一致即拒绝） */
+    sha: string;
+    /** A 的 deviceId */
+    device: string;
+    namespace: string;
+    /** A 的可达 multiaddr（含 /p2p/<id>），跨网回退用 */
+    multiaddrs: string[];
+    fingerprint: string;
+    issuedAt: number;
+    trust: JoinTrustMaterial;
+    note?: string;
+}
+export interface AgentProbe {
+    agents: FleetAgentConfig[];
+    sources: string[];
+}
+export interface ServiceInstallOutcome {
+    installed: boolean;
+    note?: string;
+}
+export type ServiceInstaller = (dir: string) => Promise<ServiceInstallOutcome>;
+/** 默认设备名：主机名清洗（小写、非法字符→`-`、去首尾 `-`）。 */
+export declare function sanitizeDeviceName(name: string): string;
+export declare function defaultDeviceName(host?: string): string;
+/**
+ * 默认设备目录：`FLEET_DIR` → `MEBULAR_HOME` → `~/.mebular`（W2 一机一节点统一 home）。
+ * 旧 `~/.fleet` 仅作 **embedded 测试模式**（`--dir` 显式指定）。
+ */
+export declare function defaultFleetDir(env?: NodeJS.ProcessEnv): string;
+/** PATH 中是否存在可执行文件（Windows 尝试 PATHEXT 扩展）。 */
+export declare function commandExists(command: string, env?: NodeJS.ProcessEnv, platform?: string): boolean;
+/** agent 自动探测：PATH 有 hermes → hermes；存在 `MEBULAR_FLEET_OPENCHAMBER_*` → openchamber；否则 echo。 */
+export declare function detectAgents(env?: NodeJS.ProcessEnv, platform?: string): AgentProbe;
+/** 端口占用检查：占用 → 抛清晰错误 + 建议（`tcp/0` 表示随机端口，跳过）。 */
+export declare function assertListenAvailable(listen: string): Promise<void>;
+/** 解析加入码：接受内联 base64 或其文本内容（兼容直接粘贴 JSON）。 */
+export declare function decodeJoinCode(text: string): JoinCode;
+/** 加入码 → 内联 base64。 */
+export declare function encodeJoinCode(code: JoinCode): string;
+/** 脱敏描述（**不含信任材料**，可用于日志/报告）。 */
+export declare function describeJoinCode(code: JoinCode): Record<string, unknown>;
+/** 写加入码文件（0600）。 */
+export declare function writeJoinCodeFile(path: string, inline: string): Promise<void>;
+/**
+ * 构建 SHA 的**环境覆盖**（CLI 传入真实 `version.json` 值）。
+ * 本模块刻意不读 `import.meta`（ts-jest 以 CJS 加载 src，会编译失败）；
+ * 缺省 `unknown` → 版本核对自动跳过。
+ */
+export declare function envBuildSha(env?: NodeJS.ProcessEnv): string;
+export interface QuickstartInput {
+    dir: string;
+    device: string;
+    namespace?: string;
+    listen?: string;
+    codeFile?: string;
+    joinPort?: number;
+    joinHost?: string;
+    agents?: FleetAgentConfig[];
+    /** W2：同时配置**统一守护**（写 <dir>/config.json + fleet daemon 客户端 + 装 mebular-serve） */
+    daemon?: boolean;
+    /** 守护 MCP/app 端口（默认 7331） */
+    daemonPort?: number;
+    /** 守护服务安装回调（mebular-serve） */
+    installDaemon?: ServiceInstaller;
+    /** 服务安装回调；缺省 = 不安装（CLI 传真实安装器） */
+    installService?: ServiceInstaller;
+    /** 跳过端口占用检查（测试用） */
+    skipPortCheck?: boolean;
+    /** 覆盖构建 SHA（测试用） */
+    buildSha?: string;
+    /** 覆盖探测环境（测试用） */
+    env?: NodeJS.ProcessEnv;
+    platform?: string;
+}
+export interface QuickstartResult {
+    device: string;
+    dir: string;
+    namespace: string;
+    fingerprint: string;
+    code: string;
+    codeFile?: string;
+    multiaddrs: string[];
+    agents: FleetAgentConfig[];
+    agentSources: string[];
+    serviceInstalled: boolean;
+    serviceNote?: string;
+    joinNext: string[];
+    warnings: string[];
+    /** T2：令牌加入（主密钥不复制）——推荐路径 */
+    inviteToken: string;
+    joinEndpoint: string;
+    joinPort: number;
+    /** W2：统一守护（`--daemon`）时的端点/服务安装结果 */
+    daemon?: {
+        endpoint: string;
+        installed: boolean;
+        note?: string;
+    };
+}
+/** W2：确保守护 bearer 令牌存在（写入 <dir>/auth/tokens.json，0600）；返回内联 token。 */
+export declare function ensureDaemonToken(dir: string): Promise<{
+    token: string;
+    tokensFile: string;
+}>;
+/**
+ * W2 B2：把统一守护配置写进同一 home（`<dir>/config.json`），并让 fleet 走 daemon 客户端：
+ * fleet.config.json 增 `store:'daemon'` + `daemon:{endpoint,token}`。**不动** embedded 配置字段。
+ */
+export declare function configureDaemonHome(dir: string, config: FleetConfig, namespace: string, joinPort: number, daemonPort: number, delegated: {
+    userMasterPublicKeyFile: string;
+} | null, peers?: Array<{
+    device: string;
+    addr?: string;
+}>): Promise<{
+    token: string;
+    endpoint: string;
+}>;
+/** W2：Agent 侧 MCP 配置片段（守护 MCP stdio）。 */
+export declare function agentMcpConfig(): Record<string, unknown>;
+/** 选一个可对外通告的 LAN IPv4（无则回环）。 */
+export declare function pickLanHost(): string;
+/** A 一条命令：onboard + 本机订阅(self) + 加入码 + 服务 + doctor。 */
+export declare function quickstart(input: QuickstartInput): Promise<QuickstartResult>;
+export interface JoinInput {
+    dir: string;
+    code: string;
+    device: string;
+    namespace?: string;
+    listen?: string;
+    agents?: FleetAgentConfig[];
+    installService?: ServiceInstaller;
+    skipPortCheck?: boolean;
+    buildSha?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: string;
+}
+export interface JoinResult {
+    device: string;
+    dir: string;
+    peer: string;
+    namespace: string;
+    fingerprint: string;
+    alreadyJoined: boolean;
+    serviceInstalled: boolean;
+    serviceNote?: string;
+    multiaddrs: string[];
+    agents: FleetAgentConfig[];
+    agentSources: string[];
+    next: string[];
+}
+/** B 一条命令：版本核对 → 导入信任材料/地址 → onboard → 声明成员(active) → 服务 → doctor。 */
+export declare function joinFleet(input: JoinInput): Promise<JoinResult>;
+/** 读加入码文件（或内联）。 */
+export declare function readJoinCode(input: {
+    code?: string;
+    codeFile?: string;
+}): Promise<string>;
+//# sourceMappingURL=quickstart.d.ts.map

package/dist/quickstart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickstart.d.ts","sourceRoot":"","sources":["../src/quickstart.ts"],"names":[],"mappings":"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"}