paperkite 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# 纸鸢
+
+纸鸢是一个以 TypeScript 编写的 Telegram 自动化运行时。触发器、动作、定时任务与常驻服务统一写在一份 YAML 配置里，插件只通过能力名接入运行时。
+
+## 快速开始
+
+```bash
+pnpm install
+cp data/settings.example.yml data/settings.yml
+cp data/flows.example.yml data/flows.yml
+pnpm build
+pnpm start init
+pnpm start run
+```
+
+首次运行前先用 `paperkite session login <会话名>` 登录，在终端按提示输入电话号、验证码即可。凭据、会话、日志和数据库都已加入忽略规则，不应提交到仓库。
+
+## 框架
+
+运行时把自动化分成四类，统一写在 `data/flows.yml`：
+
+| 类别 | 说明 |
+| --- | --- |
+| `triggers` | 事件驱动，收到消息、会话状态变化时执行动作 |
+| `commands` | 手动命令，通过控制台或 CLI 触发 |
+| `schedules` | 定时任务 |
+| `services` | 常驻服务（Web 终端等） |
+
+动作统一为 `capability + session + config`：
+
+```yaml
+run:
+  capability: messages.send
+  session: primary
+  config:
+    peer: "@someone"
+    text: "hello"
+```
+
+运行时只加载配置实际用到的能力。会话由运行时统一持有，插件只以会话名访问。动作文本支持 `{{event.text}}`、`{{event.senderId}}` 等路径模板，也兼容 `{text}`、`{chat}` 等简写。动作可以挂 `hook` 指向一个 TypeScript 模块，在执行前转换或跳过本次 config。
+
+重载会停止现有流、重读 flows.yml 并按新配置重启，进程与会话池不退出；settings.yml 仍需重启生效。CLI、Web 控制台等前端都通过同一份运行时控制契约取数、下发操作、订阅事件。
+
+## 插件
+
+插件是独立的 workspace 项目，有自己的 `package.json` 与 `paperkite.plugin` 声明。配置与用法见各插件包内的 README。
+
+| 插件 | 能力 | 文档 |
+| --- | --- | --- |
+| `@paperkite/plugin-messages` | `messages.send` | [README](packages/messages/README.md) |
+| `@paperkite/plugin-notify-bark` | `notify.bark` | [README](packages/notify-bark/README.md) |
+| `@paperkite/plugin-messages-watch` | `messages.watch`、`messages.poll` | [README](packages/messages-watch/README.md) |
+| `@paperkite/plugin-account-health` | `account.health` | [README](packages/account-health/README.md) |
+| `@paperkite/plugin-archive` | `archive.sync`、`archive.console` | [README](packages/archive/README.md) |
+| `@paperkite/plugin-process-run` | `process.run` | [README](packages/process-run/README.md) |
+| `@paperkite/plugin-favorites-cleanup` | `favorites.cleanup` | [README](packages/favorites-cleanup/README.md) |
+| `@paperkite/plugin-runtime-console` | `runtime.console` | [README](packages/runtime-console/README.md) |
+
+`@paperkite/sdk` 是共享库，不属于插件，没有 `paperkite.plugin` 声明。
+
+### 插件安装
+
+内置插件（`paperkite.bundles`）随核心安装目录解析，默认可用；`plugin add` 可安装第三方插件，或安装同名包覆盖内置插件。
+
+插件管理用 profile 目录中的 `package.json` 保存依赖和启用清单：
+
+```bash
+paperkite plugin --profile default add <npm-package>
+paperkite plugin --profile default remove <npm-package>
+paperkite plugin --profile default update <npm-package>
+```
+
+`add`、`remove`、`update` 后面的参数由 pnpm 处理。只有带 `paperkite.plugin` 声明的依赖才会成为可加载插件。
+
+## 开发
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm build
+```

package/data/flows.example.yml

@@ -0,0 +1,65 @@
+commands:
+  - id: send-test
+    title: 发送测试消息
+    run:
+      capability: messages.send
+      session: primary
+      config:
+        peer: "@example"
+        text: "纸鸢测试消息"
+
+triggers:
+  - id: account-health
+    capability: account.health
+    config:
+      notifyOnRecovery: true
+    actions:
+      - capability: notify.bark
+        config:
+          key: replace-with-your-bark-key
+          title: 会话异常
+          body: "{{event.session}} {{event.state}}"
+
+  - id: important-message
+    capability: messages.watch
+    session: primary
+    config:
+      chats: ["@example"]
+      keywords: ["提醒"]
+    actions:
+      - capability: notify.bark
+        config:
+          key: replace-with-your-bark-key
+          title: 新消息
+          body: "{{event.text}}"
+
+  - id: important-message-secondary
+    capability: messages.watch
+    session: secondary
+    config:
+      chats: ["@example"]
+      keywords: ["提醒"]
+    actions:
+      - capability: notify.bark
+        config:
+          key: replace-with-your-bark-key
+          title: 新消息
+          body: "{{event.text}}"
+
+schedules:
+  - id: archive-hourly
+    intervalSeconds: 3600
+    session: primary
+    run:
+      capability: archive.sync
+      config:
+        url: sqlite:data/archive.sqlite
+        chats: ["@example"]
+        maxMessages: 500
+
+services:
+  - id: runtime-console
+    capability: runtime.console
+    config:
+      host: 127.0.0.1
+      port: 3378

package/data/settings.example.yml

@@ -0,0 +1,13 @@
+telegram:
+  apiId: 123456
+  apiHash: replace-with-your-api-hash
+  sessionsDir: accounts
+  sessionGuard:
+    windowMs: 60000
+    threshold: 5
+    backoffMinMs: 30000
+    backoffMaxMs: 1800000
+
+logging:
+  level: info
+  directory: logs

package/dist/data/hooks/weekend-slot.d.ts

@@ -0,0 +1,12 @@
+interface HookInput {
+    readonly config: unknown;
+    readonly emission?: {
+        readonly event?: unknown;
+    };
+}
+interface HookResult {
+    readonly config?: unknown;
+    readonly skip?: boolean;
+}
+export default function weekendSlot({ config, emission }: HookInput): HookResult | undefined;
+export {};

package/dist/data/hooks/weekend-slot.js

@@ -0,0 +1,107 @@
+const DAY_KEYS = ["周一", "周二", "周三", "周四", "周五", "周六", "周日"];
+const DAY_ALIASES = {
+    周一: "周一",
+    星期一: "周一",
+    礼拜一: "周一",
+    周二: "周二",
+    星期二: "周二",
+    礼拜二: "周二",
+    周三: "周三",
+    星期三: "周三",
+    礼拜三: "周三",
+    周四: "周四",
+    星期四: "周四",
+    礼拜四: "周四",
+    周五: "周五",
+    星期五: "周五",
+    礼拜五: "周五",
+    周六: "周六",
+    星期六: "周六",
+    礼拜六: "周六",
+    周日: "周日",
+    星期日: "周日",
+    星期天: "周日",
+    周天: "周日",
+    礼拜日: "周日",
+    礼拜天: "周日"
+};
+const timePattern = /\d{1,2}(?:[.:]\d{1,2})?/g;
+export default function weekendSlot({ config, emission }) {
+    if (!isRecord(config))
+        return undefined;
+    const event = isRecord(emission?.event) ? emission.event : undefined;
+    const source = typeof event?.text === "string" ? event.text : "";
+    if (!source)
+        return undefined;
+    const day = findSlot(source, enabledDays(config.days));
+    if (!day)
+        return { skip: true };
+    const text = config.text;
+    if (Array.isArray(text)) {
+        return { config: { text: text.map((value) => inject(String(value), day)) } };
+    }
+    if (typeof text === "string")
+        return { config: { text: inject(text, day) } };
+    return undefined;
+}
+function enabledDays(days) {
+    if (!Array.isArray(days))
+        return new Set(DAY_KEYS);
+    const enabled = new Set();
+    for (const value of days) {
+        const day = toDay(value);
+        if (day)
+            enabled.add(day);
+    }
+    return enabled.size > 0 ? enabled : new Set(DAY_KEYS);
+}
+function toDay(value) {
+    if (typeof value === "string")
+        return DAY_ALIASES[value];
+    if (typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 7) {
+        return DAY_KEYS[value - 1];
+    }
+    return undefined;
+}
+function findSlot(source, enabled) {
+    for (const line of source.split(/\r?\n/)) {
+        const day = lineDay(line, enabled);
+        if (!day)
+            continue;
+        const start = firstSlotStart(line);
+        if (start?.startsWith("3"))
+            return day;
+    }
+    return undefined;
+}
+function lineDay(line, enabled) {
+    let found;
+    for (const [name, day] of Object.entries(DAY_ALIASES)) {
+        const position = line.indexOf(name);
+        if (position < 0 || !enabled.has(day))
+            continue;
+        if (found && position >= found.position)
+            continue;
+        found = { position, day };
+    }
+    return found?.day;
+}
+function firstSlotStart(line) {
+    timePattern.lastIndex = 0;
+    let match;
+    while ((match = timePattern.exec(line))) {
+        const token = match[0] ?? "";
+        const suffix = line[match.index + token.length];
+        if (suffix === "号" || suffix === "日" || suffix === "月")
+            continue;
+        return token;
+    }
+    return undefined;
+}
+function inject(value, day) {
+    return value.replace("帮我约", `帮我约${day}`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=weekend-slot.js.map

package/dist/data/hooks/weekend-slot.js.map

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

package/dist/packages/account-health/src/index.d.ts

@@ -0,0 +1,8 @@
+import { Trigger } from "@paperkite/sdk";
+interface HealthConfig {
+    readonly notifyOnRecovery?: boolean;
+}
+export declare class SessionHealthTrigger extends Trigger<HealthConfig> {
+    run(): Promise<void>;
+}
+export {};

package/dist/packages/account-health/src/index.js

@@ -0,0 +1,37 @@
+import { Trigger } from "@paperkite/sdk";
+export class SessionHealthTrigger extends Trigger {
+    async run() {
+        if (!this.control)
+            throw new Error("session health watcher needs the runtime control contract");
+        const notifyRecovery = this.config.notifyOnRecovery === true;
+        const notify = (name, state, reason) => {
+            return this.emit({ session: name, state, reason });
+        };
+        for (const info of this.control.snapshot.sessions) {
+            if (info.state !== "connected" && info.state !== "starting") {
+                await notify(info.name, info.state, info.reason);
+            }
+        }
+        const unsubscribe = this.control.subscribe((event) => {
+            if (event.type !== "session.state" || event.state === "starting")
+                return;
+            if (event.state === "connected" && !notifyRecovery)
+                return;
+            void notify(event.name, event.state, event.reason).catch((error) => {
+                this.context.logger.error("session health watcher notification failed", error);
+            });
+        });
+        try {
+            await waitForAbort(this.signal);
+        }
+        finally {
+            unsubscribe();
+        }
+    }
+}
+async function waitForAbort(signal) {
+    if (signal.aborted)
+        return;
+    await new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+}
+//# sourceMappingURL=index.js.map

package/dist/packages/account-health/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/account-health/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAqB,MAAM,gBAAgB,CAAC;AAM5D,MAAM,OAAO,oBAAqB,SAAQ,OAAqB;IAC7D,KAAK,CAAC,GAAG;QACP,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAChG,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,gBAAgB,KAAK,IAAI,CAAC;QAC7D,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,KAAmB,EAAE,MAA0B,EAAiB,EAAE;YAC9F,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QACrD,CAAC,CAAC;QAEF,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;YAClD,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,IAAI,IAAI,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;gBAC5D,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;QACD,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;YACnD,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,IAAI,KAAK,CAAC,KAAK,KAAK,UAAU;gBAAE,OAAO;YACzE,IAAI,KAAK,CAAC,KAAK,KAAK,WAAW,IAAI,CAAC,cAAc;gBAAE,OAAO;YAC3D,KAAK,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBAC1E,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4CAA4C,EAAE,KAAK,CAAC,CAAC;YACjF,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,IAAI,CAAC;YACH,MAAM,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;gBAAS,CAAC;YACT,WAAW,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;CACF;AAED,KAAK,UAAU,YAAY,CAAC,MAAmB;IAC7C,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO;IAC3B,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AAC1G,CAAC"}

package/dist/packages/archive/src/archiver.d.ts

@@ -0,0 +1,98 @@
+import type { RuntimeLogger } from "@paperkite/sdk";
+import type { ArchiveStore, MessageEntity } from "./storage/index.js";
+export interface TelegramMessage {
+    readonly id: number;
+    readonly date: number;
+    readonly text?: string;
+    readonly rawText?: string;
+    readonly message?: string;
+    readonly entities?: readonly unknown[];
+    readonly media?: unknown;
+    readonly sender?: unknown;
+    readonly senderId?: unknown;
+    readonly replyToMessageId?: number;
+    readonly replyTo?: {
+        readonly replyToMessageId?: number;
+        readonly replyToTopId?: number;
+    };
+    readonly forward?: {
+        readonly fromId?: unknown;
+        readonly fromName?: string;
+    };
+    readonly fwdFrom?: {
+        readonly fromId?: unknown;
+        readonly fromName?: string;
+    };
+    readonly groupedId?: unknown;
+}
+export interface DialogEntry {
+    readonly title?: string;
+    readonly entity?: unknown;
+}
+/** GramJS downloadMedia 的缩略图参数：sizeType 字符串（"s"/"m"…）或 PhotoSize/VideoSize 实例。 */
+export type ThumbParam = number | string | unknown;
+export interface ArchiveClient {
+    getEntity(identifier: string | number): Promise<unknown>;
+    iterDialogs(): AsyncIterable<DialogEntry>;
+    iterMessages(entity: unknown, options: {
+        limit: number;
+        maxId: number;
+    }): AsyncIterable<TelegramMessage>;
+    getMessages(entity: unknown, options: {
+        ids: readonly number[];
+    }): Promise<readonly (TelegramMessage | undefined)[]>;
+    downloadMedia(message: TelegramMessage, options?: {
+        outputFile?: string;
+        thumb?: ThumbParam;
+    }): Promise<Buffer | string | undefined>;
+    /** 按字节区间逐块产出媒体；未提供时控制台以 gramjs 原生迭代回退。 */
+    iterMediaChunks?(media: unknown, options: {
+        offset: number;
+        limit: number;
+    }): AsyncIterable<Buffer> | undefined;
+}
+export interface ChatInfo {
+    readonly chatId: string;
+    readonly title?: string;
+    readonly username?: string;
+    readonly type: "channel" | "group" | "user";
+    readonly description?: string;
+    readonly membersCount?: number;
+}
+export interface ArchiveRunOptions {
+    readonly daysBack?: number;
+    readonly maxMessages?: number;
+    readonly resume?: boolean;
+    readonly downloadMedia?: boolean;
+}
+export interface ArchiveResult {
+    readonly messages: number;
+    readonly media: number;
+    readonly skipped: number;
+}
+export interface ArchiverDependencies {
+    readonly store: ArchiveStore;
+    readonly mediaDir: string;
+    readonly downloadMedia: boolean;
+    readonly batchSize: number;
+    readonly shouldStop: () => boolean;
+    readonly submit: <T>(operation: (client: ArchiveClient) => T | Promise<T>) => Promise<T>;
+    readonly chatIdOf: (entity: unknown) => string;
+    readonly logger: RuntimeLogger;
+}
+export declare class MessageArchiver {
+    private readonly deps;
+    constructor(deps: ArchiverDependencies);
+    findChat(identifier: string | number): Promise<ChatInfo | undefined>;
+    saveChatMessages(chatIdentifier: string | number, options?: ArchiveRunOptions): Promise<ArchiveResult>;
+    private resolveEntity;
+    private planSyncWindow;
+    private runSyncWindow;
+    private sweep;
+    private fetchPageOnHost;
+    private commitPage;
+    private downloadNewMedia;
+    private downloadMediaOnHost;
+}
+/** 消息实体归一化：与 Telegram 原生对齐（offset/length 为 UTF-16 码元），链接实体保留目标 URL。 */
+export declare function normalizeEntities(entities: readonly unknown[] | undefined): readonly MessageEntity[];