keepwork-sdk 1.0.0

package/dist-npm/types/src/store/PersonalPageStore.base.d.ts

@@ -0,0 +1,267 @@
+/**
+ * PersonalPageStore.base.ts — 基础层（构造/事件/缓存/WorkSpace/SearchPath/MountedFolder/路径工具）
+ *
+ * 包含：
+ * - 构造函数与字段声明
+ * - 事件总线（on / off / emit）
+ * - reset / clearMemoryCache
+ * - withConfig / withWorkspace（Proxy 作用域）
+ * - _normalizeMountedFolder
+ * - SearchPath（addSearchPath / removeSearchPath / _readFromSearchPath / _doReadFromSearchPath）
+ * - getAbsUrl / _getMountedPagePath / _getMountedTreeParams
+ * - _isAbsolutePath / _readAbsoluteFile / _readMountedFile / _listMountedDir / _fetchMountedTree
+ * - sanitizePageName / getEffectivePageName / _stripSpuriousWorkspaceSegment
+ * - _toInternalPageKey / _toCurrentWorkspaceRelative
+ * - setUsername / getUsername
+ * - checkInitSyncTimers / destroy
+ * - ensureUserProfile
+ */
+import type { MountedFolder, SearchPath, PageSyncOptions, IPersonalPageSDK } from './PersonalPageStore.types';
+/**
+ * PersonalPageStore 基础层。
+ * 不直接实例化 — 由 PersonalPageStore.ts 主类继承并扩展。
+ */
+export declare class PersonalPageStoreBase {
+    static debug: boolean;
+    static _log(..._args: unknown[]): void;
+    sdk: IPersonalPageSDK;
+    /** L1 内存缓存：pageKey → 页面数据对象 */
+    personalPageData: Record<string, Record<string, unknown>>;
+    /** 待写入（已修改未保存）的数据 */
+    personalPageDataUpdated: Record<string, Record<string, unknown>>;
+    /** 已标记删除的 key 列表 */
+    personalPageDataDeleted: Record<string, string[]>;
+    /** 各页面的状态标志（版本检查等） */
+    pageStatus: Record<string, Record<string, unknown>>;
+    /** 待磁盘写入的页面集合 */
+    pendingDiskPages: Set<string>;
+    /** 待远端同步的页面集合 */
+    pendingSync: Set<string>;
+    /** 各页面的同步选项 */
+    pageSyncOptions: Record<string, PageSyncOptions>;
+    isSyncing: boolean;
+    _batchSavePromise: Promise<number> | null;
+    _batchSyncPromise: Promise<number> | null;
+    pageMutationVersion: Record<string, number>;
+    userProfileLoaded: boolean;
+    overrideUsername: string | null;
+    workspace: string | null;
+    mountedFolder: MountedFolder | null;
+    _searchPaths: SearchPath[];
+    /** 远端同步间隔（ms），默认 5 秒 */
+    remoteSyncInterval: number;
+    remoteStorePath: string;
+    /** 事件监听器映射 */
+    _eventListeners: Record<string, Array<(...args: unknown[]) => void>>;
+    /** 定时同步 timer */
+    gitSyncTimer: ReturnType<typeof setInterval> | null;
+    /** 防抖磁盘写入 timer */
+    _diskSaveTimeout: ReturnType<typeof setTimeout> | null;
+    _searchPathNotFound?: Set<string>;
+    _searchPathInflight?: Map<string, Promise<string | null>>;
+    _remoteTreeCache: string[] | null;
+    _remoteTreeCacheTime: number;
+    constructor(sdk: IPersonalPageSDK);
+    /**
+     * 注册事件监听器。
+     * 已知事件：
+     * - `'versionConflict'`：本地与远端版本冲突时触发，携带冲突详情
+     *
+     * @param event   - 事件名
+     * @param handler - 回调函数
+     */
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    /**
+     * 取消注册事件监听器。
+     * @param event   - 事件名
+     * @param handler - 要取消的回调
+     */
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    /**
+     * 触发事件，依次调用所有已注册监听器。
+     * @param event - 事件名
+     * @param args  - 传递给监听器的参数
+     */
+    emit(event: string, ...args: unknown[]): void;
+    /**
+     * 重置所有内存状态（数据/定时器/缓存），但不清除 IndexedDB 和远端数据。
+     * 认证变更（setToken）后由 keepworkSDK 调用。
+     */
+    reset(): void;
+    /**
+     * 清除内存缓存（认证变更后由 keepworkSDK 调用）。
+     * 等同于 reset()，不清除持久化层。
+     */
+    clearMemoryCache(): void;
+    /**
+     * 从工具/会话 config 对象创建作用域 store 实例。
+     * 自动解析 workspace 和 mountFolder，回退到当前值或 'workspace_default'。
+     *
+     * @param config - 包含可选 workspace / mountFolder 字段的配置对象
+     * @returns 作用域 store 代理
+     */
+    withConfig(config?: Record<string, unknown>): this;
+    /**
+     * 创建覆盖了 workspace 和/或 mountedFolder 的轻量代理实例。
+     * 代理的所有方法调用使用指定的作用域，不会修改共享 store —
+     * 对并发异步操作安全。
+     * 共享可变状态（Promise/定时器/缓存/同步标志/数据 map）会写穿到父 store，
+     * 保持所有代理状态一致。
+     *
+     * @param workspace     - 工作空间名称覆盖（null 表示无工作空间）
+     * @param mountedFolder - 挂载文件夹覆盖
+     */
+    withWorkspace(workspace: string | null, mountedFolder?: MountedFolder | null): this;
+    /**
+     * 将 mountedFolder 输入（路径字符串或对象）规范化为标准对象格式。
+     * 路径字符串格式：`"username/remoteStorePath.../workspace"`（至少 2 段）
+     * 返回 null 表示无效输入，undefined 表示未传入。
+     *
+     * @param mountedFolder - 路径字符串、MountedFolder 对象或 null
+     */
+    _normalizeMountedFolder(mountedFolder: unknown): MountedFolder | null | undefined;
+    /**
+     * 注册 URL 搜索路径，作为 readFile 的 URL 回退。
+     * 当本地和 mountedFolder 均找不到文件时，按前缀匹配 baseUrl 拼接路径并 fetch。
+     *
+     * @param prefix    - 路径前缀（含 workspace，如 "myws/skills"）
+     * @param baseUrl   - 基础 URL（末尾应含 /）
+     * @param options   - isReadonly（默认 true）：只读路径在 readFile 中优先级最高
+     */
+    addSearchPath(prefix: string, baseUrl: string, options?: {
+        isReadonly?: boolean;
+    }): void;
+    /**
+     * 移除已注册的搜索路径。
+     * @param prefix - 要移除的路径前缀
+     */
+    removeSearchPath(prefix: string): void;
+    /**
+     * 从已注册搜索路径中读取文件（URL 回退）。
+     * 命中内存缓存时直接返回；否则发起 fetch 并将结果缓存到内存。
+     * 使用 inflight Map 合并并发重复请求。
+     *
+     * @param pageName     - 相对于 workspace 的页面名（不含 workspace 前缀）
+     * @param readonlyOnly - true=仅搜索只读路径；false=仅搜索非只读路径；undefined=全部
+     */
+    _readFromSearchPath(pageName: string, readonlyOnly?: boolean): Promise<string | null>;
+    /** @private 实际 fetch 逻辑（_readFromSearchPath 去重后调用一次）。 */
+    private _doReadFromSearchPath;
+    /**
+     * 获取文件的绝对 URL。
+     * 优先匹配注册的搜索路径；回退到 Keepwork raw API URL。
+     *
+     * @param filename - 文件名（相对于 workspace，不含 .md）
+     */
+    getAbsUrl(filename: string): string;
+    /**
+     * 构建 mountedFolder 中文件的远端路径。
+     * 格式：`username/remoteStorePath/workspace/pageName`
+     */
+    _getMountedPagePath(pageName: string): string;
+    /**
+     * 获取 mountedFolder 的远端树参数。
+     * @returns `{ sitePath, remotePrefix, folderBase }`
+     */
+    _getMountedTreeParams(): {
+        sitePath: string;
+        remotePrefix: string;
+        folderBase: string;
+    };
+    /**
+     * 检查路径是否为绝对路径（以 `//` 开头）。
+     * 绝对路径格式：`//username/sitename/relative_path`
+     */
+    _isAbsolutePath(pageName: string): boolean;
+    /**
+     * 通过绝对路径（//username/sitename/...）读取文件内容。
+     * 结果缓存到内存中，后续调用直接返回缓存。
+     *
+     * @param absolutePath - `//` 开头的路径
+     * @param bUseCache    - 是否使用 API 缓存（默认 true）
+     */
+    _readAbsoluteFile(absolutePath: string, bUseCache?: boolean): Promise<string | null>;
+    /**
+     * 从 mountedFolder（只读）读取文件内容。
+     * @param pageName  - 相对于 workspace 的页面名
+     * @param bUseCache - 是否使用 API 缓存（默认 true）
+     */
+    _readMountedFile(pageName: string, bUseCache?: boolean): Promise<string | null>;
+    /**
+     * 列出 mountedFolder（只读）中的目录内容。
+     * @returns 子项名称集合（目录以 `/` 结尾）
+     */
+    _listMountedDir(dirPath: string, isRoot: boolean, _normalizedDir: string, recursive?: boolean): Promise<Set<string>>;
+    /**
+     * 获取 mountedFolder 的完整远端文件树（非递归，内部调用 sdk.getSiteTree）。
+     * @returns 页面名数组（相对于 mounted workspace，不含 .md）
+     */
+    _fetchMountedTree(): Promise<string[]>;
+    /**
+     * 规范化页面名：移除前导 `./` / `/`、workspace 前缀和 `.md` 扩展名。
+     * 绝对路径（`//...`）不做任何处理。
+     *
+     * @param pageName - 原始页面名
+     */
+    sanitizePageName(pageName: string): string;
+    /**
+     * 获取含 workspace 前缀的有效页面名（用于 IndexedDB / 远端路径）。
+     *
+     * @param pageName - 相对页面名
+     */
+    getEffectivePageName(pageName: string): string;
+    /**
+     * 去除 LLM 工具调用有时注入的多余 "workspace/" 路径段。
+     * 如 "silvermind/workspace/memory/x" → "silvermind/memory/x"
+     * @private
+     */
+    _stripSpuriousWorkspaceSegment(name: string): string;
+    /**
+     * 将页面名转换为规范的内部存储 key。
+     * 非绝对路径始终以 `workspace/pageName` 形式存储。
+     */
+    _toInternalPageKey(pageName: string): string;
+    /**
+     * 将内部 key 转换为当前 workspace 的相对名称。
+     * 若 key 属于其他 workspace，返回 null。
+     */
+    _toCurrentWorkspaceRelative(pageKey: string): string | null;
+    /**
+     * 设置 override 用户名（用于访问其他用户的页面数据）。
+     * 用户名变更时自动重置所有缓存。
+     * 传入 null 或 '' 表示使用当前登录用户。
+     *
+     * @param username - 要覆盖的用户名，或 null/'' 恢复当前用户
+     */
+    setUsername(username: string | null): void;
+    /**
+     * 获取当前使用的用户名（override 或当前登录用户）。
+     * @returns 用户名字符串，未登录时返回 null
+     */
+    getUsername(): string | null;
+    /**
+     * 初始化远端同步定时器（若尚未初始化）。
+     * 由 savePageData 在有数据变更时自动调用。
+     */
+    checkInitSyncTimers(): void;
+    /**
+     * 销毁 store，清除所有定时器（页面卸载时调用）。
+     */
+    destroy(): void;
+    /**
+     * 确保用户档案已加载（若已有 token）。
+     * 无 token 时允许匿名模式正常运行，不阻塞操作。
+     */
+    ensureUserProfile(): Promise<void>;
+    /** @internal 由 data 层实现 */
+    getValueByPath(_obj: Record<string, unknown> | null | undefined, _path: string): unknown;
+    /** @internal 由 data 层实现 */
+    setValueByPath(_obj: Record<string, unknown>, _path: string, _value: unknown): boolean;
+    /** @internal 由 data 层实现 */
+    isValidValue(_value: unknown): boolean;
+    /** @internal 由 sync 层实现 */
+    getRemotePagePath(_pageName: string): string;
+    /** @internal 由 sync 层实现 */
+    getLocalPagePath(_pageName: string): string;
+}
+//# sourceMappingURL=PersonalPageStore.base.d.ts.map

package/dist-npm/types/src/store/PersonalPageStore.base.d.ts.map

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

package/dist-npm/types/src/store/PersonalPageStore.d.ts

@@ -0,0 +1,13 @@
+import { PersonalPageStoreSync } from './PersonalPageStore.sync';
+import { StorageUtil } from './LocalStorageUtil';
+import type { IPersonalPageSDK } from './PersonalPageStore.types';
+declare class PersonalPageStore extends PersonalPageStoreSync {
+    static debug: boolean;
+    static _log(...args: unknown[]): void;
+    constructor(sdk: IPersonalPageSDK);
+}
+export default PersonalPageStore;
+export { StorageUtil };
+export type { IPersonalPageSDK } from './PersonalPageStore.types';
+export type { MountedFolder, SearchPath, PageMetadata, VersionConflictEvent } from './PersonalPageStore.types';
+//# sourceMappingURL=PersonalPageStore.d.ts.map

package/dist-npm/types/src/store/PersonalPageStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersonalPageStore.d.ts","sourceRoot":"","sources":["../../../../src/store/PersonalPageStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,cAAM,iBAAkB,SAAQ,qBAAqB;IACnD,OAAgB,KAAK,UAAS;WACd,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;gBAGlC,GAAG,EAAE,gBAAgB;CAClC;AAID,eAAe,iBAAiB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,CAAC;AACvB,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist-npm/types/src/store/PersonalPageStore.data.d.ts

@@ -0,0 +1,198 @@
+/**
+ * PersonalPageStore.data.ts — 数据层（工具方法 + CRUD 核心）
+ *
+ * 包含：
+ * - getValueByPath / setValueByPath / deleteValueByPath（dot notation 路径操作）
+ * - isValidValue / isValueEqual（值校验/比较）
+ * - deepClone / mergeData（数据复制/合并）
+ * - getLocalPagePath / getRemotePagePath / isUseLocal
+ * - getMetadata / setMetadata / _getTimestamp / generateVersion
+ * - savePageDataTimeSeries（时序数据追加）
+ * - loadPageDataAsNumber
+ * - savePageData / deletePageData（核心 CRUD）
+ * - checkMergeRemoteData（版本合并，含冲突解决）
+ * - isRemotePageVersionChecked / setRemotePageVersionChecked
+ * - _markPageMutation / _getPageMutationVersion
+ * - loadPageDataFromRemote / loadPageData（读取入口）
+ */
+import type { PageMetadata, TimeSeriesKeyValue } from './PersonalPageStore.types';
+import { PersonalPageStoreBase } from './PersonalPageStore.base';
+export declare class PersonalPageStoreData extends PersonalPageStoreBase {
+    /**
+     * 通过 dot notation 路径读取对象中的值。
+     * 路径不存在时返回 null。
+     *
+     * @param obj  - 源对象
+     * @param path - 如 `"user.profile.name"`；空路径返回整个对象
+     */
+    getValueByPath(obj: Record<string, unknown> | null | undefined, path: string): unknown;
+    /**
+     * 通过 dot notation 路径在对象中写入值。
+     * 路径中间节点不存在时自动创建空对象。
+     *
+     * @param obj   - 目标对象
+     * @param path  - dot notation 路径；空路径时将 value 对象合并到 obj
+     * @param value - 要写入的值
+     * @returns 是否写入成功
+     */
+    setValueByPath(obj: Record<string, unknown>, path: string, value: unknown): boolean;
+    /**
+     * 通过 dot notation 路径删除对象中的值。
+     * @returns 是否成功删除
+     */
+    deleteValueByPath(obj: Record<string, unknown>, path: string): boolean;
+    /**
+     * 检查值是否有效（非 null / 非空字符串 / 非空对象）。
+     * @param value - 要检查的值
+     */
+    isValidValue(value: unknown): boolean;
+    /**
+     * 深度相等性比较（支持数组和嵌套对象）。
+     * @param v1 - 第一个值
+     * @param v2 - 第二个值
+     */
+    isValueEqual(v1: unknown, v2: unknown): boolean;
+    /**
+     * 深度克隆值（防止外部修改内部数据）。
+     * 支持：null / 原始类型 / Date / Array / 普通对象；
+     * 正确处理循环引用（WeakMap 追踪）。
+     *
+     * @param value - 要克隆的值
+     * @param seen  - 循环引用追踪（内部参数，请勿手动传入）
+     */
+    deepClone<T>(value: T, seen?: WeakMap<object, unknown>): T;
+    /**
+     * 深度合并 source 到 target（数组替换，对象递归合并）。
+     * @param target - 目标对象（会被原地修改）
+     * @param source - 源对象
+     */
+    mergeData(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * 计算页面在 IndexedDB / localStorage 中的存储 key。
+     * 格式：`personal_page_{username}_{effectiveName}`
+     */
+    getLocalPagePath(pageName: string): string;
+    /**
+     * 计算页面在 Keepwork 远端的完整路径。
+     * 格式：`username/remoteStorePath/effectiveName`
+     * @throws 未登录且无 override 用户名时抛出错误
+     */
+    getRemotePagePath(pageName: string): string;
+    /**
+     * 检查是否处于本地模式（无 token 且无 override 用户名，仅使用本地存储）。
+     */
+    isUseLocal(): boolean;
+    /**
+     * 读取页面数据对象的版本元数据（向后兼容 `metadata` 和 `_metadata` 字段）。
+     */
+    getMetadata(data: Record<string, unknown> | null | undefined): PageMetadata;
+    /**
+     * 写入页面数据对象的版本元数据（使用新字段名 `_metadata`）。
+     */
+    setMetadata(data: Record<string, unknown>, metadata: PageMetadata): void;
+    /**
+     * 生成当前时间戳字符串（格式：`YYYY-MM-DD-HH:MM:SS`）。
+     * 用于版本元数据的 created_at / updated_at 字段。
+     */
+    _getTimestamp(): string;
+    /**
+     * 生成自增版本元数据。
+     * 若远端版本比本地新，基于远端版本自增；否则基于本地版本自增。
+     *
+     * @param localData  - 当前本地数据对象
+     * @param remoteData - 最新远端数据对象（可选）
+     */
+    generateVersion(localData?: Record<string, unknown>, remoteData?: Record<string, unknown>): PageMetadata;
+    /**
+     * 保存时序数据（数组形式，新数据插入头部，超过 maxKeyCount 时截断）。
+     *
+     * 支持 unique 类型（相同值时更新而非追加）、addictive（累加）、mean（均值）。
+     *
+     * @param pageName    - 页面名
+     * @param keyValues   - 数据键值数组，每项含 `key / value / type`
+     * @param maxKeyCount - 每个 key 最多保留的元素数（默认 10）
+     * @param bFlush      - 是否立即写盘
+     * @param bUseCache   - 是否使用缓存
+     */
+    savePageDataTimeSeries(pageName: string, keyValues: TimeSeriesKeyValue[], maxKeyCount?: number, bFlush?: boolean, bUseCache?: boolean): Promise<void>;
+    /**
+     * 读取数值型页面数据（数组时返回第一个元素）。
+     *
+     * @param pageName    - 页面名
+     * @param key         - 数据键
+     * @param forceRemote - 是否强制从远端加载
+     */
+    loadPageDataAsNumber(pageName: string, key: string, forceRemote?: boolean): Promise<number | null>;
+    /**
+     * 保存页面数据（核心写入入口）。
+     *
+     * 写入流程：
+     * 1. 检查并加载本地磁盘 + 远端数据（版本合并）
+     * 2. 比较新旧值，相同则跳过
+     * 3. 将变更写入 `personalPageDataUpdated`
+     * 4. 标记 pending 并触发防抖磁盘写入
+     *
+     * @param pageName  - 页面名
+     * @param key       - dot notation 数据键（`_metadata` 保留，不可直接写）
+     * @param value     - 要保存的值；null 表示删除该键
+     * @param bFlush    - 是否立即写盘并触发同步
+     * @param bUseCache - 是否使用远端缓存
+     */
+    savePageData(pageName: string, key: string, value: unknown, bFlush?: boolean, bUseCache?: boolean): Promise<void>;
+    /**
+     * 删除页面数据的指定键。
+     *
+     * @param pageName - 页面名
+     * @param key      - dot notation 数据键（不能为 'metadata' / '_metadata'）
+     * @param bFlush   - 是否立即触发同步
+     * @returns 是否成功删除
+     */
+    deletePageData(pageName: string, key: string, bFlush?: boolean): Promise<boolean>;
+    /**
+     * 检查并合并远端数据（版本比较 + 冲突解决）。
+     *
+     * 合并策略：
+     * - 远端版本更新 → 使用远端数据
+     * - 本地版本更新 + bUseCache → 可能是缓存陈旧，触发冲突解决逻辑并发出 versionConflict 事件
+     * - 版本相同且本地为空 → 使用远端数据
+     *
+     * @param pageName    - 页面名
+     * @param bForceMerge - 强制重新检查（忽略已检查标志）
+     * @param bUseCache   - 是否使用远端缓存
+     */
+    checkMergeRemoteData(pageName: string, bForceMerge?: boolean, bUseCache?: boolean): Promise<void>;
+    isRemotePageVersionChecked(pageName: string): boolean;
+    setRemotePageVersionChecked(pageName: string, bChecked: boolean): void;
+    _markPageMutation(pageName: string): number;
+    _getPageMutationVersion(pageName: string): number;
+    /**
+     * 直接从远端加载页面数据（绕过版本检查）。
+     * 结果同步到本地缓存并写盘，下次读取直接命中缓存。
+     *
+     * @param pageName  - 页面名
+     * @param key       - dot notation 数据键
+     * @param bUseCache - 是否使用 API 缓存
+     */
+    loadPageDataFromRemote(pageName: string, key: string, bUseCache?: boolean): Promise<unknown>;
+    /**
+     * 加载页面数据（含版本合并，主读取入口）。
+     *
+     * 读取顺序：
+     * 1. `forceRemote=true` → 直接调用 loadPageDataFromRemote
+     * 2. 检查本地磁盘（checkLoadPageFromDisk）
+     * 3. 检查远端版本（checkMergeRemoteData）
+     * 4. 读取 personalPageDataUpdated（最高优先级）
+     * 5. 读取 personalPageData（原始/合并后数据）
+     *
+     * @param pageName    - 页面名
+     * @param key         - dot notation 数据键（空字符串返回整个页面对象）
+     * @param forceRemote - 强制从远端加载（默认 false）
+     * @param bUseCache   - 是否使用远端缓存
+     */
+    loadPageData(pageName: string, key: string, forceRemote?: boolean, bUseCache?: boolean): Promise<unknown>;
+    /**
+     * 确保页面数据已从磁盘加载并与远端合并（懒加载门卫）。
+     */
+    checkLoadData(pageName: string, bUseCache?: boolean): Promise<void>;
+}
+//# sourceMappingURL=PersonalPageStore.data.d.ts.map

package/dist-npm/types/src/store/PersonalPageStore.data.d.ts.map

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

package/dist-npm/types/src/store/PersonalPageStore.sync.d.ts

@@ -0,0 +1,171 @@
+/**
+ * PersonalPageStore.sync.ts — 同步层（磁盘读写 + 远端同步 + 文件操作 API）
+ *
+ * 包含：
+ * - clearLocalDisk / clearRemotePage / clearPageData
+ * - listPages
+ * - _getRemoteTreeParams / _fetchRemoteTree
+ * - checkLoadData / checkLoadPageFromDisk
+ * - saveToDisk / syncToGit / batchSaveToDisk / batchSyncToGit / batchSyncToRemote
+ * - debouncedDiskSave
+ * - 文件操作 API：readFile / replaceStringInFile / grepSearch / createFile / listDir
+ * - 辅助：_isFileOpScoped / _globToRegex
+ */
+import type { ListDirOptions } from './PersonalPageStore.types';
+import { PersonalPageStoreData } from './PersonalPageStore.data';
+export declare class PersonalPageStoreSync extends PersonalPageStoreData {
+    /**
+     * 清除指定页面的本地磁盘（IndexedDB）数据和内存缓存。
+     * 同时清理 `.md` 扩展名变体，兼容旧版存储格式。
+     *
+     * @param pageName - 页面名
+     * @returns 是否成功清除至少一条记录
+     */
+    clearLocalDisk(pageName: string): Promise<boolean>;
+    /**
+     * 删除远端页面文件（调用 sdk.deleteMarkdownByFullPath）。
+     * 本地模式下跳过远端操作，直接返回 true。
+     *
+     * @param pageName - 页面名
+     */
+    clearRemotePage(pageName: string): Promise<boolean>;
+    /**
+     * 同时清除本地磁盘和远端页面。
+     * @param pageName - 页面名
+     */
+    clearPageData(pageName: string): Promise<void>;
+    /**
+     * 列出所有已知页面名（内存 + IndexedDB + 远端 API）。
+     * 委托给 `listDir('.', true)` 并去除 `.md` 扩展名。
+     */
+    listPages(): Promise<string[]>;
+    /**
+     * 获取当前 workspace 在远端的站点路径和目录参数。
+     * @returns `{ sitePath, remotePrefix, folderBase }`
+     */
+    _getRemoteTreeParams(): {
+        sitePath: string;
+        remotePrefix: string;
+        folderBase: string;
+    };
+    /**
+     * 获取当前 workspace 的完整远端文件树（30 秒内存缓存）。
+     * @returns 页面名数组（相对于 workspace，不含 .md）
+     */
+    _fetchRemoteTree(): Promise<string[]>;
+    /**
+     * 从 IndexedDB 加载页面数据（懒加载，已加载则跳过）。
+     * 同步迁移 localStorage 旧版数据到 IndexedDB。
+     *
+     * @param pageName    - 页面名
+     * @param forceRefresh - 强制重新从磁盘读取
+     */
+    checkLoadPageFromDisk(pageName: string, forceRefresh?: boolean): Promise<void>;
+    /**
+     * 将内存中的最新数据序列化并写入 IndexedDB（同步调用，立即返回）。
+     *
+     * 流程：
+     * 1. 合并 personalPageDataUpdated 到 personalPageData
+     * 2. 处理 personalPageDataDeleted 中的删除 key
+     * 3. 更新版本元数据
+     * 4. 序列化为 YAML 并调用 StorageUtil.setItem
+     *
+     * @param pageName  - 页面名
+     * @param forceSave - 即使无更新也强制保存（用于版本冲突解决）
+     */
+    saveToDisk(pageName: string, forceSave?: boolean): Promise<boolean>;
+    /**
+     * 将页面数据同步到远端 Git（editMarkdownByFullPath）。
+     *
+     * 同步前先合并最新远端版本（防止覆盖他人更改）。
+     * 同步成功后清除 pending 状态。
+     *
+     * @param pageName  - 页面名
+     * @param bUseCache - 是否使用 API 缓存
+     */
+    syncToGit(pageName: string, bUseCache?: boolean): Promise<boolean>;
+    /**
+     * 防抖磁盘写入（500ms 后执行 batchSaveToDisk）。
+     * 写入完成后若还有待保存页面则继续递归调度。
+     */
+    debouncedDiskSave(): void;
+    /**
+     * 批量写入所有 pendingDiskPages 到 IndexedDB。
+     * 调用方若已在进行中，直接复用同一 Promise（合并并发）。
+     *
+     * @returns 成功保存的页面数
+     */
+    batchSaveToDisk(): Promise<number>;
+    /**
+     * 批量同步所有 pendingSync 到远端（每批并发执行，循环直到队列清空）。
+     * 调用方若已在进行中，直接复用同一 Promise。
+     *
+     * @param forceSync - 强制同步（当前未使用，预留参数）
+     * @returns 成功同步的页面数
+     */
+    batchSyncToGit(forceSync?: boolean): Promise<number>;
+    /**
+     * batchSyncToGit 的别名（兼容旧调用约定）。
+     */
+    batchSyncToRemote(forceSync?: boolean): Promise<number>;
+    /**
+     * 校验文件操作是否在 workspace 作用域内（未设置 workspace 时拒绝执行）。
+     * @private
+     */
+    _isFileOpScoped(callerName: string): boolean;
+    /**
+     * 将 glob 模式转换为 RegExp（支持 * / ** / ?）。
+     * @private
+     */
+    _globToRegex(glob: string): RegExp;
+    /**
+     * 按行范围读取文件内容。
+     * 文件内容存储在页面数据的 `"content"` 键下。
+     * 读取顺序：只读搜索路径 → 本地存储 → mountedFolder → 非只读搜索路径。
+     *
+     * @param pageName  - 页面名（相当于文件路径）
+     * @param startLine - 起始行（1-based，默认 1）
+     * @param endLine   - 终止行（1-based，包含，默认最后一行）
+     * @returns 指定行范围的内容字符串
+     */
+    readFile(pageName: string, startLine?: number, endLine?: number): Promise<string>;
+    /**
+     * 精确替换文件中的一处字符串（仅替换首次出现，若多处匹配则报错）。
+     * mountedFolder 中的文件走 copy-on-write：读取后写入本地。
+     *
+     * @param pageName  - 页面名
+     * @param oldString - 要精确匹配的原始字符串
+     * @param newString - 替换后的字符串
+     * @returns 操作结果描述字符串
+     */
+    replaceStringInFile(pageName: string, oldString: string, newString: string): Promise<string>;
+    /**
+     * 在已加载页面的内容中全文搜索（text / regex）。
+     * 当 `includePattern` 为精确文件名时，还会从磁盘/远端加载该文件。
+     *
+     * @param query          - 搜索字符串或正则模式
+     * @param isRegexp       - 是否将 query 视为正则表达式
+     * @param includePattern - Glob 模式，用于过滤搜索范围
+     * @param maxResults     - 最大返回结果数（默认 100）
+     * @returns 格式化的搜索结果字符串
+     */
+    grepSearch(query: string, isRegexp?: boolean, includePattern?: string, maxResults?: number): Promise<string>;
+    /**
+     * 创建或覆盖文件（将内容存储到页面的 `"content"` 键）。
+     *
+     * @param pageName - 页面名（文件路径）
+     * @param content  - 文件内容（undefined/null 写入空字符串）
+     */
+    createFile(pageName: string, content?: string): Promise<string>;
+    /**
+     * 列出目录内容（本地 + 远端 + mountedFolder 三源合并）。
+     * 目录以 `/` 结尾，文件不加后缀（但内部用 `.md` 标识）。
+     *
+     * @param dirPath   - 目录路径；`"."` / `""` / `"/"` 表示 workspace 根
+     * @param recursive - 是否递归列出（默认 false）
+     * @param options   - showInvisibleFiles / remoteOnly / skipLocalOnlyFile
+     * @returns 换行分隔的子项名称字符串
+     */
+    listDir(dirPath: string, recursive?: boolean, options?: ListDirOptions | null): Promise<string>;
+}
+//# sourceMappingURL=PersonalPageStore.sync.d.ts.map