agent-remnote 0.0.1 → 0.1.0

package/dist/apps/cli/src/commands/db/recent.js

@@ -0,0 +1,178 @@
+import { Command } from '@effect/cli';
+import * as Options from '@effect/cli/Options';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import { AppConfig } from '../../services/AppConfig.js';
+import { RemDb } from '../../services/RemDb.js';
+import { writeFailure, writeSuccess } from '../_shared.js';
+function optionToUndefined(opt) {
+    return Option.isSome(opt) ? opt.value : undefined;
+}
+function pad2(n) {
+    return String(n).padStart(2, '0');
+}
+function msToLocalStr(ms) {
+    const d = new Date(ms);
+    return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())} ${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+}
+function cleanTitle(input) {
+    if (typeof input !== 'string')
+        return '';
+    return input.split(/\s+/).join(' ').trim();
+}
+function asInt(value) {
+    const n = typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : 0;
+    return Number.isFinite(n) ? n : 0;
+}
+function clampInt(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.max(min, Math.min(max, value));
+}
+function scalar(db, sql, params) {
+    const row = db.prepare(sql).get(...params);
+    return asInt(row?.c ?? row?.count ?? row?.['count(*)']);
+}
+const days = Options.integer('days').pipe(Options.optional, Options.map(optionToUndefined));
+const maxParents = Options.integer('max-parents').pipe(Options.optional, Options.map(optionToUndefined));
+const perParent = Options.integer('per-parent').pipe(Options.optional, Options.map(optionToUndefined));
+export const dbRecentCommand = Command.make('recent', {
+    days,
+    maxParents,
+    perParent,
+    noParentGroup: Options.boolean('no-parent-group'),
+}, ({ days, maxParents, perParent, noParentGroup }) => Effect.gen(function* () {
+    const d = clampInt(days ?? 15, 1, 3650);
+    const maxP = clampInt(maxParents ?? 20, 1, 500);
+    const perP = clampInt(perParent ?? 10, 1, 500);
+    const cutoffMs = Date.now() - d * 86400 * 1000;
+    const cfg = yield* AppConfig;
+    const remDb = yield* RemDb;
+    const result = yield* remDb.withDb(cfg.remnoteDb, (db) => {
+        const counts = {
+            quanta_created: scalar(db, "select count(*) as c from quanta where json_extract(doc,'$.createdAt') >= ?", [
+                cutoffMs,
+            ]),
+            quanta_touched: scalar(db, "select count(*) as c from quanta where json_extract(doc,'$.m') >= ?", [
+                cutoffMs,
+            ]),
+            rem_created: scalar(db, `
+              select count(*) as c
+              from quanta q
+              join remsSearchInfos r on r.id=q._id
+              where json_extract(q.doc,'$.createdAt') >= ?
+            `, [cutoffMs]),
+            rem_created_and_edited: scalar(db, `
+              select count(*) as c
+              from quanta q
+              join remsSearchInfos r on r.id=q._id
+              where json_extract(q.doc,'$.createdAt') >= ?
+                and json_extract(q.doc,'$.m') > json_extract(q.doc,'$.createdAt')
+            `, [cutoffMs]),
+            rem_modified_old: scalar(db, `
+              select count(*) as c
+              from quanta q
+              join remsSearchInfos r on r.id=q._id
+              where json_extract(q.doc,'$.m') >= ?
+                and json_extract(q.doc,'$.createdAt') < ?
+            `, [cutoffMs, cutoffMs]),
+        };
+        const rows = db
+            .prepare(`
+              select
+                q._id as id,
+                cast(json_extract(q.doc,'$.createdAt') as integer) as createdAt,
+                cast(json_extract(q.doc,'$.m') as integer) as updatedAt,
+                json_extract(r.doc,'$.r') as preview,
+                json_extract(q.doc,'$.parent') as parentId,
+                json_extract(pr.doc,'$.r') as parentPreview
+              from quanta q
+              join remsSearchInfos r on r.id=q._id
+              left join remsSearchInfos pr on pr.id = json_extract(q.doc,'$.parent')
+              where cast(json_extract(q.doc,'$.createdAt') as integer) >= ?
+              order by createdAt desc
+            `)
+            .all(cutoffMs);
+        const items = rows.map((row) => {
+            const createdAt = asInt(row.createdAt);
+            const updatedAt = asInt(row.updatedAt);
+            const preview = cleanTitle(row.preview) || '<no preview>';
+            const parentId = typeof row.parentId === 'string' ? row.parentId : row.parentId ? String(row.parentId) : '';
+            const parentPreview = cleanTitle(row.parentPreview) || '<unknown parent>';
+            return {
+                id: String(row.id),
+                created_at: createdAt,
+                updated_at: updatedAt,
+                preview,
+                parent_id: parentId,
+                parent_preview: parentPreview,
+                edited_after_create: createdAt > 0 && updatedAt > createdAt,
+            };
+        });
+        return { counts, items };
+    });
+    const dbPath = result.info.dbPath;
+    const cutoffText = msToLocalStr(cutoffMs);
+    const header = [
+        `# RemNote 近 ${d} 天新增/修改概览`,
+        ``,
+        `- db: \`${dbPath}\``,
+        `- cutoff: \`${cutoffText}\``,
+        `- rem(索引): 新增 \`${result.result.counts.rem_created}\`；新建后编辑 \`${result.result.counts.rem_created_and_edited}\`；仅修改旧内容 \`${result.result.counts.rem_modified_old}\``,
+        `- quanta(全量): createdAt>=cutoff \`${result.result.counts.quanta_created}\`；m>=cutoff \`${result.result.counts.quanta_touched}\``,
+        ``,
+    ].join('\n');
+    const ids = [];
+    const mdLines = [header.trimEnd()];
+    if (result.result.items.length > 0) {
+        if (noParentGroup) {
+            mdLines.push('## 新增 Rem（按时间倒序）', '');
+            const take = Math.min(result.result.items.length, maxP * perP);
+            for (const row of result.result.items.slice(0, take)) {
+                ids.push(row.id);
+                const marker = row.edited_after_create ? '（后续有编辑）' : '';
+                mdLines.push(`- \`${msToLocalStr(row.created_at)}\` ${row.preview} \`${row.id}\`${marker}`);
+            }
+        }
+        else {
+            const groups = new Map();
+            for (const row of result.result.items) {
+                const key = row.parent_id;
+                const existing = groups.get(key);
+                if (existing) {
+                    existing.items.push(row);
+                }
+                else {
+                    groups.set(key, { parent_id: key, parent_title: row.parent_preview, items: [row] });
+                }
+            }
+            const ordered = Array.from(groups.values())
+                .sort((a, b) => {
+                const aMax = Math.max(...a.items.map((r) => r.created_at));
+                const bMax = Math.max(...b.items.map((r) => r.created_at));
+                return bMax - aMax;
+            })
+                .slice(0, maxP);
+            mdLines.push(`## 新增 Rem（按 parent 分组，最多 ${maxP} 组 × 每组 ${perP} 条）`, '');
+            for (const group of ordered) {
+                const items = [...group.items].sort((a, b) => b.created_at - a.created_at);
+                mdLines.push(`### ${group.parent_title} (${group.items.length})`, '');
+                for (const row of items.slice(0, perP)) {
+                    ids.push(row.id);
+                    const marker = row.edited_after_create ? '（后续有编辑）' : '';
+                    mdLines.push(`- \`${msToLocalStr(row.created_at)}\` ${row.preview} \`${row.id}\`${marker}`);
+                }
+                mdLines.push('');
+            }
+        }
+    }
+    const data = {
+        db_path: dbPath,
+        resolution: result.info.source,
+        days: d,
+        cutoff_ms: cutoffMs,
+        counts: result.result.counts,
+        items: result.result.items,
+    };
+    yield* writeSuccess({ data, ids, md: mdLines.join('\n').trimEnd() + '\n' });
+}).pipe(Effect.catchAll(writeFailure)));

package/dist/apps/cli/src/commands/doctor.js

@@ -0,0 +1,124 @@
+import { Command } from '@effect/cli';
+import * as Effect from 'effect/Effect';
+import { constants as FS_CONSTANTS, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { AppConfig } from '../services/AppConfig.js';
+import { DaemonFiles } from '../services/DaemonFiles.js';
+import { Queue } from '../services/Queue.js';
+import { RemDb } from '../services/RemDb.js';
+import { WsClient } from '../services/WsClient.js';
+import { writeFailure, writeSuccess } from './_shared.js';
+import { WS_HEALTH_TIMEOUT_MS } from './ws/_shared.js';
+async function canWritePath(filePath) {
+    try {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.access(path.dirname(filePath), FS_CONSTANTS.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const doctorCommand = Command.make('doctor', {}, () => Effect.gen(function* () {
+    const cfg = yield* AppConfig;
+    const queue = yield* Queue;
+    const remDb = yield* RemDb;
+    const ws = yield* WsClient;
+    const daemonFiles = yield* DaemonFiles;
+    const queueStats = yield* queue.stats({ dbPath: cfg.queueDb }).pipe(Effect.either);
+    const remnote = yield* remDb
+        .withDb(cfg.remnoteDb, (db) => {
+        db.prepare('SELECT 1 FROM quanta LIMIT 1').get();
+        const hasSearchInfos = !!db
+            .prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name='remsSearchInfos' LIMIT 1`)
+            .get();
+        const hasContents = !!db
+            .prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name='remsContents' LIMIT 1`)
+            .get();
+        return { has_search_index: hasSearchInfos && hasContents };
+    })
+        .pipe(Effect.either);
+    const wsHealth = yield* ws.health({ url: cfg.wsUrl, timeoutMs: WS_HEALTH_TIMEOUT_MS }).pipe(Effect.either);
+    const wsClients = yield* ws.queryClients({ url: cfg.wsUrl, timeoutMs: WS_HEALTH_TIMEOUT_MS }).pipe(Effect.either);
+    const pidFilePath = daemonFiles.defaultPidFile();
+    const logFilePath = daemonFiles.defaultLogFile();
+    const pidWritable = yield* Effect.tryPromise({
+        try: async () => await canWritePath(pidFilePath),
+        catch: () => false,
+    });
+    const logWritable = yield* Effect.tryPromise({
+        try: async () => await canWritePath(logFilePath),
+        catch: () => false,
+    });
+    const data = {
+        queue: {
+            ok: queueStats._tag === 'Right',
+            db_path: cfg.queueDb,
+            stats: queueStats._tag === 'Right' ? queueStats.right : undefined,
+            error: queueStats._tag === 'Left' ? queueStats.left.message : undefined,
+        },
+        remnote_db: {
+            ok: remnote._tag === 'Right',
+            db_path: remnote._tag === 'Right' ? remnote.right.info.dbPath : cfg.remnoteDb,
+            resolution: remnote._tag === 'Right' ? remnote.right.info.source : undefined,
+            has_search_index: remnote._tag === 'Right' ? remnote.right.result.has_search_index : undefined,
+            error: remnote._tag === 'Left' ? remnote.left.message : undefined,
+        },
+        ws: {
+            ok: wsHealth._tag === 'Right',
+            url: cfg.wsUrl,
+            rtt_ms: wsHealth._tag === 'Right' ? wsHealth.right.rtt_ms : undefined,
+            error: wsHealth._tag === 'Left' ? wsHealth.left.message : undefined,
+            clients: wsClients._tag === 'Right' ? wsClients.right.clients : [],
+        },
+        daemon_files: {
+            pid_file: pidFilePath,
+            log_file: logFilePath,
+            pid_writable: pidWritable,
+            log_writable: logWritable,
+        },
+    };
+    const overallOk = data.queue.ok &&
+        data.remnote_db.ok &&
+        data.ws.ok &&
+        data.daemon_files.pid_writable &&
+        data.daemon_files.log_writable;
+    const hints = [];
+    if (!data.ws.ok)
+        hints.push('可尝试：remnote ws ensure / remnote ws status');
+    if (data.ws.ok && data.ws.clients.length === 0)
+        hints.push('WS 可达但暂无插件连接：请确认插件已启用并连接控制通道');
+    if (!data.queue.ok)
+        hints.push('队列 DB 不可用：检查 --queue-db 或 REMNOTE_QUEUE_DB 路径权限');
+    if (!data.remnote_db.ok)
+        hints.push('RemNote DB 不可用：检查 --remnote-db 或运行 remnote db backups 选择备份路径');
+    if (!data.remnote_db.has_search_index && data.remnote_db.ok) {
+        hints.push('RemNote DB 缺少搜索索引表：read search/query 可能不可用，请在 RemNote 客户端完成索引生成或使用较新备份');
+    }
+    if (!data.daemon_files.pid_writable || !data.daemon_files.log_writable) {
+        hints.push('daemon 文件不可写：检查 HOME 目录权限或自定义 ws start --pid-file/--log-file 路径');
+    }
+    const md = [
+        `# doctor`,
+        `- overall_ok: ${overallOk}`,
+        `- queue_ok: ${data.queue.ok}`,
+        `- queue_db: ${data.queue.db_path}`,
+        `- remnote_db_ok: ${data.remnote_db.ok}`,
+        `- remnote_db: ${data.remnote_db.db_path ?? ''}`,
+        `- remnote_db_resolution: ${data.remnote_db.resolution ?? ''}`,
+        `- remnote_search_index_ok: ${data.remnote_db.has_search_index ?? ''}`,
+        `- ws_ok: ${data.ws.ok}`,
+        `- ws_url: ${data.ws.url}`,
+        `- ws_rtt_ms: ${data.ws.rtt_ms ?? ''}`,
+        `- ws_clients: ${data.ws.clients.length}`,
+        `- pid_file_writable: ${data.daemon_files.pid_writable}`,
+        `- pid_file: ${data.daemon_files.pid_file}`,
+        `- log_file_writable: ${data.daemon_files.log_writable}`,
+        `- log_file: ${data.daemon_files.log_file}`,
+        hints.length > 0 ? `\n## Hint` : '',
+        ...hints.map((h) => `- ${h}`),
+    ]
+        .filter(Boolean)
+        .join('\n');
+    yield* writeSuccess({ data: { overall_ok: overallOk, ...data, hints }, md });
+}).pipe(Effect.catchAll(writeFailure)));

package/dist/apps/cli/src/commands/index.js

@@ -0,0 +1,73 @@
+import { Command } from '@effect/cli';
+import * as Options from '@effect/cli/Options';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import { applyCommand } from './apply.js';
+import { configCommand } from './config/index.js';
+import { doctorCommand } from './doctor.js';
+import { dailyCommand } from './daily/index.js';
+import { dbCommand } from './db/index.js';
+import { opsCommand } from './ops/index.js';
+import { queueCommand } from './queue/index.js';
+import { readCommand } from './read/index.js';
+import { todosCommand } from './todos/index.js';
+import { topicCommand } from './topic/index.js';
+import { writeCommand } from './write/index.js';
+import { wsCommand } from './ws/index.js';
+import { wechatCommand } from './wechat/index.js';
+import { AppConfig } from '../services/AppConfig.js';
+import { ConfigLive, resolveConfig } from '../services/Config.js';
+import { DaemonFilesLive } from '../services/DaemonFiles.js';
+import { OutputLive } from '../services/Output.js';
+import { PayloadLive } from '../services/Payload.js';
+import { ProcessLive } from '../services/Process.js';
+import { QueueLive } from '../services/Queue.js';
+import { RefResolverLive } from '../services/RefResolver.js';
+import { RemDbLive } from '../services/RemDb.js';
+import { WsClientLive } from '../services/WsClient.js';
+function optionToUndefined(opt) {
+    return Option.isSome(opt) ? opt.value : undefined;
+}
+const remnoteDb = Options.text('remnote-db').pipe(Options.optional, Options.map(optionToUndefined));
+const queueDb = Options.text('queue-db').pipe(Options.optional, Options.map(optionToUndefined));
+const wsUrl = Options.text('ws-url').pipe(Options.optional, Options.map(optionToUndefined));
+const consumerId = Options.text('consumer-id').pipe(Options.optional, Options.map(optionToUndefined));
+const repo = Options.text('repo').pipe(Options.optional, Options.map(optionToUndefined));
+const servicesLive = Layer.mergeAll(OutputLive, ConfigLive, PayloadLive, DaemonFilesLive, ProcessLive, WsClientLive, QueueLive, RefResolverLive, RemDbLive);
+export const rootCommand = Command.make('remnote', {
+    json: Options.boolean('json'),
+    md: Options.boolean('md'),
+    ids: Options.boolean('ids'),
+    quiet: Options.boolean('quiet'),
+    debug: Options.boolean('debug'),
+    remnoteDb,
+    queueDb,
+    wsUrl,
+    consumerId,
+    repo,
+}).pipe(Command.withSubcommands([
+    wsCommand,
+    queueCommand,
+    applyCommand,
+    readCommand,
+    dailyCommand,
+    wechatCommand,
+    topicCommand,
+    todosCommand,
+    dbCommand,
+    configCommand,
+    doctorCommand,
+    opsCommand,
+    writeCommand,
+]), Command.provideEffect(AppConfig, (args) => resolveConfig({
+    json: args.json,
+    md: args.md,
+    ids: args.ids,
+    quiet: args.quiet,
+    debug: args.debug,
+    remnoteDb: args.remnoteDb,
+    queueDb: args.queueDb,
+    wsUrl: args.wsUrl,
+    consumerId: args.consumerId,
+    repo: args.repo,
+})), Command.provide(servicesLive));

package/dist/apps/cli/src/commands/ops/index.js

@@ -0,0 +1,4 @@
+import { Command } from '@effect/cli';
+import { opsListCommand } from './list.js';
+import { opsSchemaCommand } from './schema.js';
+export const opsCommand = Command.make('ops', {}).pipe(Command.withSubcommands([opsListCommand, opsSchemaCommand]));

package/dist/apps/cli/src/commands/ops/list.js

@@ -0,0 +1,12 @@
+import { Command } from '@effect/cli';
+import * as Effect from 'effect/Effect';
+import { TYPES } from '../../adapters/mcp.js';
+import { writeFailure, writeSuccess } from '../_shared.js';
+export const opsListCommand = Command.make('list', {}, () => Effect.gen(function* () {
+    const types = Object.keys(TYPES).sort();
+    yield* writeSuccess({
+        data: { types },
+        ids: types,
+        md: types.map((t) => `- ${t}`).join('\n'),
+    });
+}).pipe(Effect.catchAll(writeFailure)));

package/dist/apps/cli/src/commands/ops/schema.js

@@ -0,0 +1,77 @@
+import { Command } from '@effect/cli';
+import * as Options from '@effect/cli/Options';
+import * as Effect from 'effect/Effect';
+import { TYPES } from '../../adapters/mcp.js';
+import { CliError } from '../../services/Errors.js';
+import { writeFailure, writeSuccess } from '../_shared.js';
+function typeHint(field) {
+    const f = field.toLowerCase();
+    if (f.includes('markdown'))
+        return 'string(markdown)';
+    if (f.endsWith('id') || f.endsWith('ids') || f.includes('parentid'))
+        return 'string(remId)';
+    if (f.includes('tags') || f.endsWith('ids'))
+        return 'string[]';
+    if (f.startsWith('is') || f.startsWith('include') || f.startsWith('exclude') || f.includes('create'))
+        return 'boolean';
+    if (f.includes('count') || f.includes('size') || f.includes('position') || f.includes('max') || f.includes('ms'))
+        return 'number';
+    return 'unknown';
+}
+function exampleValue(field) {
+    const f = field.toLowerCase();
+    if (f.includes('markdown'))
+        return '# Markdown...';
+    if (f.endsWith('ids') || f === 'tags')
+        return [];
+    if (f.endsWith('id') || f.includes('parentid'))
+        return '<remId>';
+    if (f.startsWith('is') || f.startsWith('include') || f.startsWith('exclude') || f.includes('create'))
+        return true;
+    if (f.includes('count') || f.includes('size') || f.includes('position') || f.includes('max') || f.includes('ms'))
+        return 0;
+    if (f.includes('url'))
+        return 'https://example.com';
+    return '<value>';
+}
+export const opsSchemaCommand = Command.make('schema', { type: Options.text('type') }, ({ type }) => Effect.gen(function* () {
+    const spec = TYPES[type];
+    if (!spec) {
+        return yield* Effect.fail(new CliError({
+            code: 'INVALID_ARGS',
+            message: `未知 op 类型：${type}`,
+            exitCode: 2,
+            hint: ['remnote ops list'],
+        }));
+    }
+    const required = Array.isArray(spec.required) ? spec.required : [];
+    const optional = Array.isArray(spec.optional) ? spec.optional : [];
+    const examplePayload = {};
+    for (const f of required)
+        examplePayload[f] = exampleValue(f);
+    const fields = [
+        ...required.map((name) => ({ name, required: true, type: typeHint(name) })),
+        ...optional.map((name) => ({ name, required: false, type: typeHint(name) })),
+    ];
+    const data = {
+        type,
+        description: spec.description ?? '',
+        fields,
+        example: { type, payload: examplePayload },
+    };
+    const md = [
+        `# ${type}`,
+        spec.description ? `- description: ${spec.description}` : '',
+        required.length > 0 ? `\n## required` : '',
+        ...required.map((f) => `- ${f} (${typeHint(f)})`),
+        optional.length > 0 ? `\n## optional` : '',
+        ...optional.map((f) => `- ${f} (${typeHint(f)})`),
+        `\n## example`,
+        '```json',
+        JSON.stringify(data.example, null, 2),
+        '```',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    yield* writeSuccess({ data, md });
+}).pipe(Effect.catchAll(writeFailure)));

package/dist/apps/cli/src/commands/queue/enqueue.js

@@ -0,0 +1,73 @@
+import { Command } from '@effect/cli';
+import * as Options from '@effect/cli/Options';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import { CliError, isCliError } from '../../services/Errors.js';
+import { Payload } from '../../services/Payload.js';
+import { writeFailure, writeSuccess } from '../_shared.js';
+import { enqueueOps, normalizeOps, parseEnqueuePayload } from '../_enqueue.js';
+function optionToUndefined(opt) {
+    return Option.isSome(opt) ? opt.value : undefined;
+}
+function readOptionalText(name) {
+    return Options.text(name).pipe(Options.optional, Options.map(optionToUndefined));
+}
+const payloadSpec = Options.text('payload');
+const metaSpec = readOptionalText('meta');
+const clientId = readOptionalText('client-id');
+const idempotencyKey = readOptionalText('idempotency-key');
+const priority = Options.integer('priority').pipe(Options.optional, Options.map(optionToUndefined));
+export const queueEnqueueCommand = Command.make('enqueue', {
+    payload: payloadSpec,
+    notify: Options.boolean('notify'),
+    ensureWs: Options.boolean('ensure-ws'),
+    priority,
+    clientId,
+    idempotencyKey,
+    meta: metaSpec,
+}, ({ payload, notify, ensureWs, priority, clientId, idempotencyKey, meta }) => Effect.gen(function* () {
+    const payloadSvc = yield* Payload;
+    const raw = yield* payloadSvc.readJson(payload);
+    const parsed = yield* Effect.try({
+        try: () => parseEnqueuePayload(raw),
+        catch: (e) => isCliError(e)
+            ? e
+            : new CliError({
+                code: 'INVALID_PAYLOAD',
+                message: 'payload 形状不合法：必须是 ops 数组，或 { ops: [...] }',
+                exitCode: 2,
+            }),
+    });
+    const rawOps = parsed.ops;
+    if (rawOps.length === 0) {
+        return yield* Effect.fail(new CliError({ code: 'INVALID_PAYLOAD', message: 'ops 不能为空', exitCode: 2 }));
+    }
+    if (rawOps.length > 500) {
+        return yield* Effect.fail(new CliError({
+            code: 'PAYLOAD_TOO_LARGE',
+            message: `ops 数量过多（${rawOps.length}），请拆分后重试`,
+            exitCode: 2,
+            details: { ops: rawOps.length, max_ops: 500 },
+        }));
+    }
+    const ops = yield* normalizeOps(rawOps);
+    const metaFromFlag = meta ? yield* payloadSvc.readJson(meta) : undefined;
+    const metaValue = metaFromFlag ?? parsed.meta;
+    const resolvedPriority = priority ?? parsed.priority;
+    const resolvedClientId = clientId ?? parsed.clientId;
+    const resolvedIdempotencyKey = idempotencyKey ?? parsed.idempotencyKey;
+    const data = yield* enqueueOps({
+        ops,
+        priority: resolvedPriority,
+        clientId: resolvedClientId,
+        idempotencyKey: resolvedIdempotencyKey,
+        meta: metaValue,
+        notify,
+        ensureWs,
+    });
+    yield* writeSuccess({
+        data,
+        ids: [data.txn_id, ...data.op_ids],
+        md: `- txn_id: ${data.txn_id}\n- op_ids: ${data.op_ids.length}\n- notified: ${data.notified}\n- sent: ${data.sent ?? ''}\n`,
+    });
+}).pipe(Effect.catchAll(writeFailure)));

package/dist/apps/cli/src/commands/queue/index.js

@@ -0,0 +1,5 @@
+import { Command } from '@effect/cli';
+import { queueEnqueueCommand } from './enqueue.js';
+import { queueInspectCommand } from './inspect.js';
+import { queueStatsCommand } from './stats.js';
+export const queueCommand = Command.make('queue', {}).pipe(Command.withSubcommands([queueStatsCommand, queueInspectCommand, queueEnqueueCommand]));

package/dist/apps/cli/src/commands/queue/inspect.js

@@ -0,0 +1,26 @@
+import { Command } from '@effect/cli';
+import * as Options from '@effect/cli/Options';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import { AppConfig } from '../../services/AppConfig.js';
+import { CliError } from '../../services/Errors.js';
+import { Queue } from '../../services/Queue.js';
+import { writeFailure, writeSuccess } from '../_shared.js';
+function optionToUndefined(opt) {
+    return Option.isSome(opt) ? opt.value : undefined;
+}
+const txn = Options.text('txn').pipe(Options.optional, Options.map(optionToUndefined));
+const op = Options.text('op').pipe(Options.optional, Options.map(optionToUndefined));
+export const queueInspectCommand = Command.make('inspect', { txn, op }, ({ txn, op }) => Effect.gen(function* () {
+    const cfg = yield* AppConfig;
+    const queue = yield* Queue;
+    if (txn && op) {
+        return yield* Effect.fail(new CliError({
+            code: 'INVALID_ARGS',
+            message: '--txn 与 --op 只能二选一',
+            exitCode: 2,
+        }));
+    }
+    const result = yield* queue.inspect({ dbPath: cfg.queueDb, txnId: txn, opId: op });
+    yield* writeSuccess({ data: result, md: `- txn_id: ${String(result?.txn?.txn_id ?? '')}\n- ops: ${result?.ops?.length ?? 0}\n` });
+}).pipe(Effect.catchAll(writeFailure)));

package/dist/apps/cli/src/commands/queue/stats.js

@@ -0,0 +1,14 @@
+import { Command } from '@effect/cli';
+import * as Effect from 'effect/Effect';
+import { AppConfig } from '../../services/AppConfig.js';
+import { Queue } from '../../services/Queue.js';
+import { writeFailure, writeSuccess } from '../_shared.js';
+export const queueStatsCommand = Command.make('stats', {}, () => Effect.gen(function* () {
+    const cfg = yield* AppConfig;
+    const queue = yield* Queue;
+    const result = yield* queue.stats({ dbPath: cfg.queueDb });
+    yield* writeSuccess({
+        data: result,
+        md: `- pending: ${result.pending ?? ''}\n- in_progress: ${result.in_progress ?? ''}\n- dead: ${result.dead ?? ''}\n`,
+    });
+}).pipe(Effect.catchAll(writeFailure)));

package/dist/apps/cli/src/commands/read/by-reference.js

@@ -0,0 +1,35 @@
+import { Command } from '@effect/cli';
+import * as Options from '@effect/cli/Options';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import { executeFindRemsByReference } from '../../adapters/mcp.js';
+import { AppConfig } from '../../services/AppConfig.js';
+import { CliError } from '../../services/Errors.js';
+import { writeFailure, writeSuccess } from '../_shared.js';
+import { cliErrorFromUnknown } from '../_tool.js';
+function optionToUndefined(opt) {
+    return Option.isSome(opt) ? opt.value : undefined;
+}
+const reference = Options.text('reference').pipe(Options.repeated);
+const timeRange = Options.text('time').pipe(Options.optional, Options.map(optionToUndefined));
+const maxDepth = Options.integer('max-depth').pipe(Options.optional, Options.map(optionToUndefined));
+const limit = Options.integer('limit').pipe(Options.optional, Options.map(optionToUndefined));
+const offset = Options.integer('offset').pipe(Options.optional, Options.map(optionToUndefined));
+export const readByReferenceCommand = Command.make('by-reference', { reference, timeRange, maxDepth, limit, offset }, ({ reference, timeRange, maxDepth, limit, offset }) => Effect.gen(function* () {
+    if (!reference || reference.length === 0) {
+        return yield* Effect.fail(new CliError({ code: 'INVALID_ARGS', message: '--reference 至少提供 1 个 Rem ID', exitCode: 2 }));
+    }
+    const cfg = yield* AppConfig;
+    const result = yield* Effect.tryPromise({
+        try: async () => await executeFindRemsByReference({
+            targetIds: reference,
+            dbPath: cfg.remnoteDb,
+            timeRange: timeRange,
+            maxDepth: maxDepth,
+            limit: limit,
+            offset: offset,
+        }),
+        catch: (e) => cliErrorFromUnknown(e, { code: 'DB_UNAVAILABLE' }),
+    });
+    yield* writeSuccess({ data: result, md: result.markdown ?? '' });
+}).pipe(Effect.catchAll(writeFailure)));

package/dist/apps/cli/src/commands/read/connections.js

@@ -0,0 +1,15 @@
+import { Command } from '@effect/cli';
+import * as Options from '@effect/cli/Options';
+import * as Effect from 'effect/Effect';
+import { executeGetRemConnections } from '../../adapters/mcp.js';
+import { AppConfig } from '../../services/AppConfig.js';
+import { writeFailure, writeSuccess } from '../_shared.js';
+import { cliErrorFromUnknown, unwrapStructuredContent } from '../_tool.js';
+export const readConnectionsCommand = Command.make('connections', { id: Options.text('id') }, ({ id }) => Effect.gen(function* () {
+    const cfg = yield* AppConfig;
+    const payload = yield* Effect.tryPromise({
+        try: async () => unwrapStructuredContent(await executeGetRemConnections({ id, dbPath: cfg.remnoteDb })),
+        catch: (e) => cliErrorFromUnknown(e, { code: 'DB_UNAVAILABLE' }),
+    });
+    yield* writeSuccess({ data: payload, md: payload.markdown ?? '' });
+}).pipe(Effect.catchAll(writeFailure)));