@xgjktech/xg-openclaw-shared 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { Plan, Task, Step, TaskStatus, StepStatus } from "./plan-types.js";
+export { assertPlanInvariants, PlanInvariantError } from "./plan-types.js";
+export type { PlanStore, PlanSummary } from "./plan-store.js";
+export { SqlitePlanStore, openPlanStoreReadonly, resolvePlanDbPath, PlanStoreError } from "./plan-store.js";
+export type { PlanEventPayload, PlanEventSummary } from "./plan-events.js";
+export { planEventStream, isPlanEventPayload } from "./plan-events.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE3E,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE5G,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// 桶文件：xg-shared 的唯一公开面。两插件（本插件 + IM 插件）均只从此入口 import。
+export { assertPlanInvariants, PlanInvariantError } from "./plan-types.js";
+export { SqlitePlanStore, openPlanStoreReadonly, resolvePlanDbPath, PlanStoreError } from "./plan-store.js";
+export { planEventStream, isPlanEventPayload } from "./plan-events.js";

package/dist/plan-events.d.ts

@@ -0,0 +1,40 @@
+import type { TaskStatus } from "./plan-types.js";
+/**
+ * stream 名 = `<pluginId>.plan`。第三方插件发的 stream 必须等于自己的 pluginId 或以
+ * `pluginId.` 前缀（OpenClaw 硬约束），禁止发裸 `plan`（host 保留流）。
+ */
+export declare function planEventStream(pluginId: string): string;
+export interface PlanEventSummary {
+    total: number;
+    completed: number;
+    blocked: number;
+    inProgress: number;
+}
+/**
+ * plan_execute 推进后发出的事件 payload（缝隙 A 定义，两插件共用）。
+ * 路由定位字段（deliveryContext/agentAccountId/messageChannel/sessionKey）均可选：
+ * 能从工具工厂 ctx 取到就带，取不到就省略——事件是尽力而为，不因缺字段而阻断。
+ */
+export interface PlanEventPayload {
+    kind: "plan_update";
+    planId: string;
+    goal: string;
+    action: string;
+    taskIndex: number;
+    stepIndex?: number;
+    taskTitle: string;
+    taskStatus: TaskStatus;
+    blockedNote?: string;
+    summary: PlanEventSummary;
+    runId: string;
+    sessionKey?: string;
+    deliveryContext?: unknown;
+    agentAccountId?: string;
+    messageChannel?: string;
+}
+/**
+ * 运行时类型守卫：IM 侧订阅 handle 内用它校验 event.data 是否为合法 PlanEventPayload，
+ * 防止跨插件事件流误解析（订阅按 stream 过滤但 data 结构未经编译期保证）。
+ */
+export declare function isPlanEventPayload(value: unknown): value is PlanEventPayload;
+//# sourceMappingURL=plan-events.d.ts.map

package/dist/plan-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-events.d.ts","sourceRoot":"","sources":["../src/plan-events.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AA0BD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CA8B5E"}

package/dist/plan-events.js

@@ -0,0 +1,74 @@
+// 缝隙B 事件契约：stream 名生成 + payload 类型 + 运行时类型守卫。
+// 本文件不 import openclaw；emitAgentEvent 的实际调用在插件侧（xg-harness-tools/notify.ts）完成。
+/**
+ * stream 名 = `<pluginId>.plan`。第三方插件发的 stream 必须等于自己的 pluginId 或以
+ * `pluginId.` 前缀（OpenClaw 硬约束），禁止发裸 `plan`（host 保留流）。
+ */
+export function planEventStream(pluginId) {
+    if (pluginId.trim() === "") {
+        throw new Error("pluginId 不能为空");
+    }
+    return `${pluginId}.plan`;
+}
+function isPlanEventSummary(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const summary = value;
+    return (typeof summary["total"] === "number" &&
+        typeof summary["completed"] === "number" &&
+        typeof summary["blocked"] === "number" &&
+        typeof summary["inProgress"] === "number");
+}
+const TASK_STATUSES = [
+    "pending",
+    "in_progress",
+    "completed",
+    "blocked",
+];
+function isTaskStatusValue(value) {
+    return typeof value === "string" && TASK_STATUSES.includes(value);
+}
+/**
+ * 运行时类型守卫：IM 侧订阅 handle 内用它校验 event.data 是否为合法 PlanEventPayload，
+ * 防止跨插件事件流误解析（订阅按 stream 过滤但 data 结构未经编译期保证）。
+ */
+export function isPlanEventPayload(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const payload = value;
+    if (payload["kind"] !== "plan_update")
+        return false;
+    if (typeof payload["planId"] !== "string" || payload["planId"] === "")
+        return false;
+    if (typeof payload["goal"] !== "string")
+        return false;
+    if (typeof payload["action"] !== "string")
+        return false;
+    if (typeof payload["taskIndex"] !== "number")
+        return false;
+    if (payload["stepIndex"] !== undefined && typeof payload["stepIndex"] !== "number")
+        return false;
+    if (typeof payload["taskTitle"] !== "string")
+        return false;
+    if (!isTaskStatusValue(payload["taskStatus"]))
+        return false;
+    if (payload["blockedNote"] !== undefined && typeof payload["blockedNote"] !== "string") {
+        return false;
+    }
+    if (!isPlanEventSummary(payload["summary"]))
+        return false;
+    if (typeof payload["runId"] !== "string" || payload["runId"] === "")
+        return false;
+    if (payload["sessionKey"] !== undefined && typeof payload["sessionKey"] !== "string") {
+        return false;
+    }
+    if (payload["agentAccountId"] !== undefined && typeof payload["agentAccountId"] !== "string") {
+        return false;
+    }
+    if (payload["messageChannel"] !== undefined && typeof payload["messageChannel"] !== "string") {
+        return false;
+    }
+    return true;
+}

package/dist/plan-store.d.ts

@@ -0,0 +1,48 @@
+import type { Plan } from "./plan-types.js";
+export interface PlanSummary {
+    planId: string;
+    goal: string;
+    updatedAt: string;
+    taskCounts: {
+        total: number;
+        completed: number;
+        blocked: number;
+        inProgress: number;
+    };
+}
+export interface PlanStore {
+    get(planId: string): Plan | undefined;
+    set(plan: Plan): void;
+    delete(planId: string): void;
+    list(): PlanSummary[];
+}
+export declare class PlanStoreError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * SqlitePlanStore：本插件的唯一写者。读写走事务，异常一律转 PlanStoreError，
+ * 绝不让底层 SQLite 异常冒泡崩 gateway（企业工具与 gateway 同进程约束）。
+ */
+export declare class SqlitePlanStore implements PlanStore {
+    private readonly db;
+    constructor(dbPath: string);
+    /** 关闭底层数据库连接，释放文件句柄。测试与短生命周期场景使用；插件运行时通常常驻不调用。 */
+    close(): void;
+    get(planId: string): Plan | undefined;
+    set(plan: Plan): void;
+    delete(planId: string): void;
+    list(): PlanSummary[];
+}
+/**
+ * IM 侧只读入口：以 readOnly 模式打开同一 DB，杜绝误写。
+ * 只暴露 get/list（缝隙 C 读路径），不暴露 set/delete。
+ */
+export declare function openPlanStoreReadonly(dbPath: string): Pick<PlanStore, "get" | "list">;
+/**
+ * 路径约定：<stateDir>/xgjktech/plans.sqlite（两插件共享 xgjktech 命名空间）。
+ * 负责 mkdir -p 该子目录，调用方无需自行建目录。
+ */
+export declare function resolvePlanDbPath(stateDir: string): string;
+//# sourceMappingURL=plan-store.d.ts.map

package/dist/plan-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-store.d.ts","sourceRoot":"","sources":["../src/plan-store.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACvF;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACtC,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,IAAI,IAAI,WAAW,EAAE,CAAC;CACvB;AAED,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAyGD;;;GAGG;AACH,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;gBAEtB,MAAM,EAAE,MAAM;IAI1B,kDAAkD;IAClD,KAAK,IAAI,IAAI;IAIb,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIrC,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IA8BrB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ5B,IAAI,IAAI,WAAW,EAAE;CAGtB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC,CAWrF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI1D"}

package/dist/plan-store.js

@@ -0,0 +1,185 @@
+// PlanStore：Plan 的持久化访问器。node:sqlite 同步 API，单表 JSON blob + 冗余列。
+// 本文件不 import openclaw；stateDir 字符串由调用方（插件）解析后传入。
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+export class PlanStoreError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "PlanStoreError";
+    }
+}
+const SCHEMA_VERSION = 1;
+const BUSY_TIMEOUT_MS = 5000;
+const CREATE_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS plans (
+  plan_id     TEXT PRIMARY KEY,
+  goal        TEXT NOT NULL,
+  created_at  TEXT NOT NULL,
+  updated_at  TEXT NOT NULL,
+  doc         TEXT NOT NULL
+) STRICT;
+`;
+const CREATE_INDEX_SQL = `
+CREATE INDEX IF NOT EXISTS idx_plans_updated_at ON plans(updated_at);
+`;
+function parsePlanDoc(row) {
+    try {
+        return JSON.parse(row.doc);
+    }
+    catch (cause) {
+        throw new PlanStoreError(`plan ${row.plan_id} 的 doc 列不是合法 JSON`, { cause });
+    }
+}
+function summarizeTaskCounts(plan) {
+    const counts = { total: 0, completed: 0, blocked: 0, inProgress: 0 };
+    for (const task of plan.tasks) {
+        counts.total += 1;
+        if (task.status === "completed")
+            counts.completed += 1;
+        if (task.status === "blocked")
+            counts.blocked += 1;
+        if (task.status === "in_progress")
+            counts.inProgress += 1;
+    }
+    return counts;
+}
+function ensureSchema(db) {
+    db.exec(CREATE_TABLE_SQL);
+    db.exec(CREATE_INDEX_SQL);
+    db.exec(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+}
+function openDatabase(dbPath, options) {
+    try {
+        const db = new DatabaseSync(dbPath, { readOnly: options.readOnly });
+        db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS};`);
+        if (!options.readOnly) {
+            db.exec("PRAGMA journal_mode = WAL;");
+            ensureSchema(db);
+        }
+        return db;
+    }
+    catch (cause) {
+        throw new PlanStoreError(`打开 PlanStore 数据库失败: ${dbPath}`, { cause });
+    }
+}
+function readPlanRow(db, planId) {
+    return db
+        .prepare("SELECT plan_id, goal, created_at, updated_at, doc FROM plans WHERE plan_id = ?")
+        .get(planId);
+}
+function readAllPlanRows(db) {
+    return db
+        .prepare("SELECT plan_id, goal, created_at, updated_at, doc FROM plans ORDER BY updated_at DESC")
+        .all();
+}
+function getPlan(db, planId, errorPrefix) {
+    try {
+        const row = readPlanRow(db, planId);
+        return row === undefined ? undefined : parsePlanDoc(row);
+    }
+    catch (cause) {
+        if (cause instanceof PlanStoreError)
+            throw cause;
+        throw new PlanStoreError(`${errorPrefix} plan ${planId} 失败`, { cause });
+    }
+}
+function listPlans(db, errorPrefix) {
+    try {
+        return readAllPlanRows(db).map((row) => {
+            const plan = parsePlanDoc(row);
+            return {
+                planId: row.plan_id,
+                goal: row.goal,
+                updatedAt: row.updated_at,
+                taskCounts: summarizeTaskCounts(plan),
+            };
+        });
+    }
+    catch (cause) {
+        if (cause instanceof PlanStoreError)
+            throw cause;
+        throw new PlanStoreError(`${errorPrefix} plan 列表失败`, { cause });
+    }
+}
+/**
+ * SqlitePlanStore：本插件的唯一写者。读写走事务，异常一律转 PlanStoreError，
+ * 绝不让底层 SQLite 异常冒泡崩 gateway（企业工具与 gateway 同进程约束）。
+ */
+export class SqlitePlanStore {
+    db;
+    constructor(dbPath) {
+        this.db = openDatabase(dbPath, { readOnly: false });
+    }
+    /** 关闭底层数据库连接，释放文件句柄。测试与短生命周期场景使用；插件运行时通常常驻不调用。 */
+    close() {
+        this.db.close();
+    }
+    get(planId) {
+        return getPlan(this.db, planId, "读取");
+    }
+    set(plan) {
+        try {
+            this.db.exec("BEGIN IMMEDIATE");
+            try {
+                this.db
+                    .prepare(`INSERT INTO plans (plan_id, goal, created_at, updated_at, doc)
+             VALUES (@planId, @goal, @createdAt, @updatedAt, @doc)
+             ON CONFLICT(plan_id) DO UPDATE SET
+               goal = excluded.goal,
+               updated_at = excluded.updated_at,
+               doc = excluded.doc`)
+                    .run({
+                    planId: plan.planId,
+                    goal: plan.goal,
+                    createdAt: plan.createdAt,
+                    updatedAt: plan.updatedAt,
+                    doc: JSON.stringify(plan),
+                });
+                this.db.exec("COMMIT");
+            }
+            catch (cause) {
+                this.db.exec("ROLLBACK");
+                throw cause;
+            }
+        }
+        catch (cause) {
+            throw new PlanStoreError(`写入 plan ${plan.planId} 失败`, { cause });
+        }
+    }
+    delete(planId) {
+        try {
+            this.db.prepare("DELETE FROM plans WHERE plan_id = ?").run(planId);
+        }
+        catch (cause) {
+            throw new PlanStoreError(`删除 plan ${planId} 失败`, { cause });
+        }
+    }
+    list() {
+        return listPlans(this.db, "列出");
+    }
+}
+/**
+ * IM 侧只读入口：以 readOnly 模式打开同一 DB，杜绝误写。
+ * 只暴露 get/list（缝隙 C 读路径），不暴露 set/delete。
+ */
+export function openPlanStoreReadonly(dbPath) {
+    const db = openDatabase(dbPath, { readOnly: true });
+    return {
+        get(planId) {
+            return getPlan(db, planId, "只读读取");
+        },
+        list() {
+            return listPlans(db, "只读列出");
+        },
+    };
+}
+/**
+ * 路径约定：<stateDir>/xgjktech/plans.sqlite（两插件共享 xgjktech 命名空间）。
+ * 负责 mkdir -p 该子目录，调用方无需自行建目录。
+ */
+export function resolvePlanDbPath(stateDir) {
+    const dir = join(stateDir, "xgjktech");
+    mkdirSync(dir, { recursive: true });
+    return join(dir, "plans.sqlite");
+}

package/dist/plan-types.d.ts

@@ -0,0 +1,35 @@
+export type TaskStatus = "pending" | "in_progress" | "completed" | "blocked";
+export type StepStatus = "pending" | "in_progress" | "completed";
+export interface Step {
+    text: string;
+    status: StepStatus;
+}
+export interface Task {
+    title: string;
+    status: TaskStatus;
+    note?: string;
+    steps?: Step[];
+}
+export interface Plan {
+    planId: string;
+    goal: string;
+    createdAt: string;
+    updatedAt: string;
+    tasks: Task[];
+}
+export declare class PlanInvariantError extends Error {
+    constructor(message: string);
+}
+/**
+ * 校验 Plan 是否满足全部领域不变量，违反则抛出 PlanInvariantError。
+ * plan_write / plan_execute 写库前必须调用；供两插件共享同一份判定，避免理解漂移。
+ *
+ * 覆盖的不变量（见 02-PlanStore设计 §2）：
+ * 1. 全计划最多一个 in_progress task。
+ * 2. 每个 task 内最多一个 in_progress step。
+ * 3. status==="blocked" 的 task 必须有非空 note。
+ * 4. planId / goal 非空；tasks 至少一项。
+ * 5. task.status / step.status 取值必须在枚举内。
+ */
+export declare function assertPlanInvariants(plan: Plan): void;
+//# sourceMappingURL=plan-types.d.ts.map

package/dist/plan-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-types.d.ts","sourceRoot":"","sources":["../src/plan-types.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;AAC7E,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;AAUjE,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,IAAI;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAwDrD"}

package/dist/plan-types.js

@@ -0,0 +1,72 @@
+// Plan/Task/Step 数据模型与不变量校验。纯类型 + 纯函数，无副作用、无 openclaw 依赖。
+const TASK_STATUSES = [
+    "pending",
+    "in_progress",
+    "completed",
+    "blocked",
+];
+const STEP_STATUSES = ["pending", "in_progress", "completed"];
+export class PlanInvariantError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PlanInvariantError";
+    }
+}
+function isTaskStatus(value) {
+    return TASK_STATUSES.includes(value);
+}
+function isStepStatus(value) {
+    return STEP_STATUSES.includes(value);
+}
+/**
+ * 校验 Plan 是否满足全部领域不变量，违反则抛出 PlanInvariantError。
+ * plan_write / plan_execute 写库前必须调用；供两插件共享同一份判定，避免理解漂移。
+ *
+ * 覆盖的不变量（见 02-PlanStore设计 §2）：
+ * 1. 全计划最多一个 in_progress task。
+ * 2. 每个 task 内最多一个 in_progress step。
+ * 3. status==="blocked" 的 task 必须有非空 note。
+ * 4. planId / goal 非空；tasks 至少一项。
+ * 5. task.status / step.status 取值必须在枚举内。
+ */
+export function assertPlanInvariants(plan) {
+    if (plan.planId.trim() === "") {
+        throw new PlanInvariantError("planId 不能为空");
+    }
+    if (plan.goal.trim() === "") {
+        throw new PlanInvariantError("goal 不能为空");
+    }
+    if (plan.tasks.length === 0) {
+        throw new PlanInvariantError("tasks 至少一项");
+    }
+    let inProgressTaskCount = 0;
+    plan.tasks.forEach((task, taskIndex) => {
+        if (!isTaskStatus(task.status)) {
+            throw new PlanInvariantError(`tasks[${taskIndex}].status 取值非法: ${task.status}`);
+        }
+        if (task.status === "in_progress") {
+            inProgressTaskCount += 1;
+        }
+        if (task.status === "blocked" && (task.note === undefined || task.note.trim() === "")) {
+            throw new PlanInvariantError(`tasks[${taskIndex}] 状态为 blocked 时必须带非空 note`);
+        }
+        if (task.steps === undefined) {
+            return;
+        }
+        let inProgressStepCount = 0;
+        task.steps.forEach((step, stepIndex) => {
+            if (!isStepStatus(step.status)) {
+                throw new PlanInvariantError(`tasks[${taskIndex}].steps[${stepIndex}].status 取值非法: ${step.status}`);
+            }
+            if (step.status === "in_progress") {
+                inProgressStepCount += 1;
+            }
+        });
+        if (inProgressStepCount > 1) {
+            throw new PlanInvariantError(`tasks[${taskIndex}] 内 in_progress 的 step 超过一个`);
+        }
+    });
+    if (inProgressTaskCount > 1) {
+        throw new PlanInvariantError("全计划 in_progress 的 task 超过一个");
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@xgjktech/xg-openclaw-shared",
+  "version": "0.1.0",
+  "description": "xgjktech OpenClaw 插件共享层：Plan 数据模型/不变量、SQLite PlanStore、计划事件契约",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest": "npm run build",
+    "test": "node --test dist/*.test.js",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.0",
+    "typescript": "^5.6.0"
+  }
+}