@allbluecn/shared 0.2.0

package/src/interfaces/ai.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+export interface CLIAgentInfo {
+  id: string
+  name: string
+  binary: string
+  version: string
+  available: boolean
+}
+
+export interface AiAdapter {
+  detect(): Promise<CLIAgentInfo[]>
+  execute(
+    commandId: string,
+    ctx: { entityType: string; entityIds: string[]; userInput?: string }
+  ): Promise<{ content: string }>
+  stream(
+    commandId: string,
+    ctx: { entityType: string; entityIds: string[]; userInput?: string }
+  ): AsyncGenerator<string>
+  getActiveAgent(): string
+  switchAgent(agentId: string): void
+}

package/src/interfaces/avatar.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+export type AvatarPart = "face" | "eyes" | "eyebrows" | "mouth" | "nose" | "glasses" | "hair" | "accessories" | "details" | "beard"
+
+export type AvatarConfig = Record<AvatarPart, number>
+
+export type ShapeType = "circle" | "rounded" | "square"

package/src/interfaces/module.ts

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+export interface EntityDef {
+  type: string
+  table: string
+  searchFields: string[]
+  displayFields: string[]
+}
+
+export interface AICommandContext {
+  entityType: string
+  entityIds: string[]
+  userInput?: string
+  module: AllBlueModule
+}
+
+export interface AICommandResult {
+  content: string
+  actions?: { type: string; payload: unknown }[]
+}
+
+export type AICommandHandler = (ctx: AICommandContext) => Promise<AICommandResult>
+
+export interface AICommandDef {
+  id: string
+  label: string
+  icon: string
+  entityTypes: string[]
+  handler: AICommandHandler
+}
+
+export type ReferenceDisplayFn = (
+  type: string,
+  data: Record<string, unknown>
+) => { title: string; status?: string; priority?: string; url?: string }
+
+export interface AllBlueModule {
+  id: string
+  name: string
+  icon: string
+  workspaceRoute: string
+  entities: EntityDef[]
+  aiCommands: AICommandDef[]
+  referenceDisplay: ReferenceDisplayFn
+}

package/src/interfaces/references.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+export interface RefDisplay {
+  title: string
+  status?: string
+  priority?: string
+  url?: string
+}
+
+export interface Reference {
+  id: string
+  sourceModule: string
+  sourceEntityId: string
+  targetModule: string
+  targetEntityId: string
+}
+
+export interface ResolvedRef extends Reference {
+  display: RefDisplay
+}
+
+export interface SearchResult {
+  id: string
+  module: string
+  type: string
+  title: string
+  status?: string
+  url?: string
+}

package/src/interfaces/transport.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+export interface EntityUpdateEvent {
+  type: string
+  id: string
+  fields: Record<string, unknown>
+}
+
+export interface RealtimeTransport {
+  subscribe(entityIds: string[], onUpdate: (event: EntityUpdateEvent) => void): () => void
+}

package/src/lib/annotation-template.ts

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { DOMParser } from "@tiptap/pm/model";
+import type { Editor } from "@tiptap/react";
+
+/**
+ * 将 HTML 字符串转为 ProseMirror content 节点数组（用于 insertContent 的 content 字段）。
+ * 客户端调用（onAnnotate 事件触发），document 可用。
+ */
+export function htmlToPmContent(editor: Editor, html: string): any[] {
+  if (typeof document === "undefined" || !html) return [{ type: "paragraph" }];
+  const wrapper = document.createElement("div");
+  wrapper.innerHTML = html;
+  const parser = DOMParser.fromSchema(editor.schema);
+  const parsed = parser.parse(wrapper);
+  const json = parsed.toJSON();
+  return (json as any).content ?? [{ type: "paragraph" }];
+}

package/src/lib/comment-utils.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+export function maskEmail(email?: string | null): string {
+  if (!email) return "未知用户";
+  const [local, domain] = email.split("@");
+  if (!domain) return email;
+  const prefix = local.length > 3 ? local.slice(0, 3) : local;
+  return `${prefix}***@${domain}`;
+}
+
+export function formatTime(date: Date | string): string {
+  const d = new Date(date);
+  const now = new Date();
+  const diff = now.getTime() - d.getTime();
+  const minutes = Math.floor(diff / 60000);
+  if (minutes < 1) return "刚刚";
+  if (minutes < 60) return `${minutes}分钟前`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}小时前`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}天前`;
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")} ${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+
+export function formatEditedTime(date: Date | string): string {
+  const time = formatTime(date);
+  return `修改于${time}`;
+}
+
+export function getUserInitial(username: string): string {
+  return (username || "?").charAt(0).toUpperCase();
+}

package/src/lib/datetime.ts

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { formatInTimeZone, toZonedTime, fromZonedTime } from 'date-fns-tz'
+import { startOfDay, subDays } from 'date-fns'
+
+const FALLBACK_TIMEZONE = 'Asia/Shanghai'
+
+/**
+ * 解析生效时区：项目时区 > 用户时区 > 浏览器时区 > Asia/Shanghai
+ */
+export function resolveTimezone(
+  projectTz?: string | null,
+  userTz?: string | null,
+): string {
+  const browserTz =
+    typeof Intl !== 'undefined'
+      ? Intl.DateTimeFormat().resolvedOptions().timeZone
+      : FALLBACK_TIMEZONE
+  return projectTz || userTz || browserTz || FALLBACK_TIMEZONE
+}
+
+/**
+ * 时区感知的时间格式化。
+ * @param date UTC Date 对象（来自 DB）
+ * @param timezone IANA 时区，如 "Asia/Shanghai"
+ * @param fmt date-fns 格式，默认 "yyyy-MM-dd HH:mm"
+ */
+export function formatDate(
+  date: Date,
+  timezone: string,
+  fmt = 'yyyy-MM-dd HH:mm',
+): string {
+  try {
+    return formatInTimeZone(date, timezone, fmt)
+  } catch {
+    return formatInTimeZone(date, FALLBACK_TIMEZONE, fmt)
+  }
+}
+
+/**
+ * 相对时间（今天/昨天/具体日期），基于时区计算「今天的 0 点」。
+ * @param now 当前时间（测试注入；生产用默认 new Date()）
+ */
+export function formatRelative(
+  date: Date,
+  timezone: string,
+  now: Date = new Date(),
+): string {
+  try {
+    const todayStart = startOfDayInTimeZone(now, timezone)
+    const yesterdayStart = new Date(todayStart)
+    yesterdayStart.setDate(yesterdayStart.getDate() - 1)
+
+    const dateStart = startOfDayInTimeZone(date, timezone)
+
+    if (dateStart.getTime() === todayStart.getTime()) return '今天'
+    if (dateStart.getTime() === yesterdayStart.getTime()) return '昨天'
+    return formatInTimeZone(date, timezone, 'yyyy-MM-dd')
+  } catch {
+    return formatInTimeZone(date, FALLBACK_TIMEZONE, 'yyyy-MM-dd')
+  }
+}
+
+/**
+ * 获取指定时区下某天的 0 点（UTC Date 对象）。
+ */
+function startOfDayInTimeZone(date: Date, timezone: string): Date {
+  const zoned = toZonedTime(date, timezone)
+  const dayStart = startOfDay(zoned)
+  return fromZonedTime(dayStart, timezone)
+}
+
+/**
+ * 对话历史日期分组标签（今天/昨天/本周/具体日期）。
+ * @param date UTC Date 对象
+ * @param timezone IANA 时区
+ */
+export function formatChatDate(date: Date, timezone: string): string {
+  try {
+    const now = new Date()
+    const todayStart = startOfDayInTimeZone(now, timezone)
+    const yesterdayStart = subDays(todayStart, 1)
+    const weekStart = subDays(todayStart, 7)
+
+    const dateStart = startOfDayInTimeZone(date, timezone)
+
+    if (dateStart.getTime() === todayStart.getTime()) return '今天'
+    if (dateStart.getTime() === yesterdayStart.getTime()) return '昨天'
+    if (dateStart.getTime() >= weekStart.getTime()) return '本周'
+
+    const currentYear = Number(formatInTimeZone(now, timezone, 'yyyy'))
+    const dateYear = Number(formatInTimeZone(date, timezone, 'yyyy'))
+    if (dateYear === currentYear) {
+      return formatInTimeZone(date, timezone, 'M月d日')
+    }
+    return formatInTimeZone(date, timezone, 'yyyy年M月d日')
+  } catch {
+    return formatInTimeZone(date, FALLBACK_TIMEZONE, 'yyyy-MM-dd')
+  }
+}

package/src/lib/desktop-detect.ts

@@ -0,0 +1,27 @@
+/**
+ * Detect if code is running inside Tauri desktop environment.
+ * Uses `window.__TAURI_INTERNALS__` (Tauri 2) with fallback to `window.__TAURI__` (Tauri 1 compat).
+ */
+export function isDesktop(): boolean {
+  if (typeof window === 'undefined') return false
+  return Boolean(
+    (window as unknown as { __TAURI_INTERNALS__?: unknown }).__TAURI_INTERNALS__ ||
+      (window as unknown as { __TAURI__?: unknown }).__TAURI__,
+  )
+}
+
+/**
+ * Dynamically import Tauri core API. Returns null if not in desktop env.
+ * Use this to avoid bundling @tauri-apps/api in web production.
+ */
+export async function getTauriInvoke(): Promise<
+  ((cmd: string, args?: Record<string, unknown>) => Promise<unknown>) | null
+> {
+  if (!isDesktop()) return null
+  try {
+    const core = await import('@tauri-apps/api/core')
+    return core.invoke
+  } catch {
+    return null
+  }
+}

package/src/lib/outline-utils.ts

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { CanvasElement } from "../types/prototype";
+import { OutlineNode } from "../types/outline";
+
+export function buildOutline(elements: CanvasElement[]): OutlineNode[] {
+  const containers = elements.filter(e => isContainer(e));
+  const atoms = elements.filter(e => !isContainer(e));
+  const roots: OutlineNode[] = [];
+  const usedAtoms = new Set<string>();
+
+  for (const c of containers) {
+    const rect = { x: c.x, y: c.y, w: c.width, h: c.height };
+    const children = atoms
+      .filter(a => !usedAtoms.has(a.id) && isInside(a, rect))
+      .map(a => { usedAtoms.add(a.id); return toAtomNode(a); });
+    roots.push({ id: `container-${c.id}`, label: (c.overrides ?? c.props)?.name || c.type, type: "container", elementId: c.id, children });
+  }
+
+  for (const a of atoms) {
+    if (!usedAtoms.has(a.id)) {
+      roots.push(toAtomNode(a));
+    }
+  }
+
+  return roots;
+}
+
+function isContainer(el: CanvasElement): boolean {
+  return (el.width >= 160 && el.height >= 100) || (el.overrides ?? el.props)?.isContainer === true;
+}
+
+function isInside(atom: CanvasElement, rect: { x: number; y: number; w: number; h: number }): boolean {
+  return atom.x >= rect.x && atom.y >= rect.y &&
+         atom.x + atom.width <= rect.x + rect.w &&
+         atom.y + atom.height <= rect.y + rect.h;
+}
+
+function toAtomNode(el: CanvasElement): OutlineNode {
+  const p = el.overrides ?? el.props;
+  return { id: `atom-${el.id}`, label: p?.text || p?.label || el.type, type: "atom", elementId: el.id, children: [] };
+}

package/src/lib/pacer.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { RateLimiter } from "@tanstack/pacer"
+import { useDebouncedCallback, useThrottledCallback } from "@tanstack/react-pacer"
+
+export const EDITOR_AUTO_SAVE_MS = 2000
+export const EDITOR_CHANGE_DEBOUNCE_MS = 500
+export const SEARCH_DEBOUNCE_MS = 300
+export const SCROLL_THROTTLE_MS = 150
+export const AI_RATE_LIMIT = {
+  chat: { max: 10, windowMs: 60_000 },
+  execute: { max: 5, windowMs: 60_000 },
+  generatePrototype: { max: 5, windowMs: 60_000 },
+  testProvider: { max: 10, windowMs: 60_000 },
+  detect: { max: 10, windowMs: 60_000 },
+  webSearch: { max: 20, windowMs: 60_000 },
+} as const
+
+export interface RateLimitConfig {
+  max: number
+  windowMs: number
+}
+
+export { useDebouncedCallback }
+export { useThrottledCallback }
+
+interface ServerFnRateLimitResult {
+  allowed: boolean
+  retryAfterMs: number
+}
+
+const limiterCache = new Map<
+  string,
+  { limiter: RateLimiter<(...args: unknown[]) => boolean>; lastAccess: number }
+>()
+
+const CACHE_TTL_MS = 5 * 60 * 1000
+
+function purgeStaleEntries() {
+  const now = Date.now()
+  for (const [key, entry] of limiterCache) {
+    if (now - entry.lastAccess > CACHE_TTL_MS) {
+      entry.limiter.reset()
+      limiterCache.delete(key)
+    }
+  }
+}
+
+setInterval(purgeStaleEntries, 60_000)
+
+export function getRateLimiter(
+  key: string,
+  config: RateLimitConfig
+): RateLimiter<(...args: unknown[]) => boolean> {
+  const existing = limiterCache.get(key)
+  if (existing) {
+    existing.lastAccess = Date.now()
+    return existing.limiter
+  }
+
+  const limiter = new RateLimiter(() => true, {
+    limit: config.max,
+    window: config.windowMs,
+    windowType: "sliding",
+  })
+
+  limiterCache.set(key, { limiter, lastAccess: Date.now() })
+  return limiter
+}
+
+export function checkRateLimit(
+  key: string,
+  config: RateLimitConfig
+): ServerFnRateLimitResult {
+  const limiter = getRateLimiter(key, config)
+  const allowed = limiter.maybeExecute()
+  return {
+    allowed,
+    retryAfterMs: allowed ? 0 : limiter.getMsUntilNextWindow(),
+  }
+}

package/src/lib/prd/stack-layout.ts

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import type { CanvasElement } from "../../types/prototype"
+
+export interface StackLayoutOptions {
+  startX: number
+  startY: number
+  gap: number
+}
+
+/**
+ * 计算新组件在画板上的纵向堆叠位置。
+ * 起始 y = 现有元素的最大 (y + height) + gap，若无现有元素则用 startY。
+ * items 的 height 用于决定每个新组件的纵向偏移，确保大小不一的组件不会重叠。
+ */
+export function computeStackPositions(
+  existing: Pick<CanvasElement, "x" | "y" | "height">[],
+  items: Array<Pick<CanvasElement, "height">>,
+  options: StackLayoutOptions,
+): Array<{ x: number; y: number }> {
+  if (items.length === 0) return []
+
+  const { startX, startY, gap } = options
+
+  const maxBottom = existing.reduce(
+    (max, el) => Math.max(max, el.y + el.height),
+    0,
+  )
+  const baseY = existing.length > 0 ? maxBottom + gap : startY
+
+  const positions: Array<{ x: number; y: number }> = []
+  let cursorY = baseY
+  for (const item of items) {
+    positions.push({ x: startX, y: cursorY })
+    cursorY += item.height + gap
+  }
+  return positions
+}