@spaceflow/core 0.1.1

package/src/shared/storage/storage.service.ts

@@ -0,0 +1,293 @@
+import { Inject, Injectable, OnModuleDestroy } from "@nestjs/common";
+import { type StorageAdapter } from "./adapters/storage-adapter.interface";
+import { STORAGE_ADAPTER, STORAGE_MODULE_OPTIONS, type StorageModuleOptions } from "./types";
+
+/**
+ * Storage 服务
+ * 提供统一的键值存储接口，支持过期时间和层级 key
+ *
+ * Key 使用 : 作为层级分隔符，例如：
+ * - user:123:profile
+ * - cache:api:users
+ */
+@Injectable()
+export class StorageService implements OnModuleDestroy {
+  protected cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    @Inject(STORAGE_ADAPTER)
+    protected readonly adapter: StorageAdapter,
+    @Inject(STORAGE_MODULE_OPTIONS)
+    protected readonly options: StorageModuleOptions,
+  ) {
+    // 启动定期清理过期项的定时器
+    this.startCleanupTimer();
+  }
+
+  onModuleDestroy() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+
+  /**
+   * 启动定期清理过期项的定时器
+   */
+  protected startCleanupTimer(): void {
+    // 每分钟清理一次过期项
+    this.cleanupTimer = setInterval(() => {
+      this.cleanup().catch(console.error);
+    }, 60 * 1000);
+  }
+
+  /**
+   * 清理所有过期项
+   */
+  async cleanup(): Promise<number> {
+    const now = Date.now();
+    const allKeys = await this.adapter.keys();
+    let cleaned = 0;
+
+    for (const key of allKeys) {
+      const item = await this.adapter.get(key);
+      if (item && item.expireAt && item.expireAt <= now) {
+        await this.adapter.delete(key);
+        cleaned++;
+      }
+    }
+
+    return cleaned;
+  }
+
+  /**
+   * 获取值
+   * @param key 键名，支持 : 分隔的层级结构
+   * @returns 值，如果不存在或已过期返回 undefined
+   */
+  async get<T = any>(key: string): Promise<T | undefined> {
+    const item = await this.adapter.get<T>(key);
+
+    if (!item) {
+      return undefined;
+    }
+
+    // 检查是否过期
+    if (item.expireAt && item.expireAt <= Date.now()) {
+      await this.adapter.delete(key);
+      return undefined;
+    }
+
+    return item.value;
+  }
+
+  /**
+   * 设置值
+   * @param key 键名，支持 : 分隔的层级结构
+   * @param value 值
+   * @param ttl 过期时间（毫秒），0 或 undefined 表示使用默认值
+   */
+  async set<T = any>(key: string, value: T, ttl?: number): Promise<void> {
+    const effectiveTtl = ttl ?? this.options.defaultTtl ?? 0;
+
+    // 检查是否需要淘汰
+    if (this.options.maxKeys && this.options.maxKeys > 0) {
+      const exists = await this.adapter.has(key);
+      if (!exists) {
+        await this.evictIfNeeded();
+      }
+    }
+
+    await this.adapter.set(key, {
+      value,
+      expireAt: effectiveTtl > 0 ? Date.now() + effectiveTtl : undefined,
+    });
+  }
+
+  /**
+   * 如果超过最大 key 数量，淘汰最早过期的 key
+   */
+  protected async evictIfNeeded(): Promise<void> {
+    const maxKeys = this.options.maxKeys;
+    if (!maxKeys || maxKeys <= 0) return;
+
+    const currentSize = await this.adapter.size();
+    if (currentSize < maxKeys) return;
+
+    // 先清理过期的 key
+    await this.cleanup();
+
+    // 再次检查
+    const sizeAfterCleanup = await this.adapter.size();
+    if (sizeAfterCleanup < maxKeys) return;
+
+    // 仍然超过限制，淘汰最早过期的 key
+    const allKeys = await this.adapter.keys();
+    const keyWithExpire: { key: string; expireAt: number }[] = [];
+
+    for (const key of allKeys) {
+      const item = await this.adapter.get(key);
+      if (item) {
+        keyWithExpire.push({
+          key,
+          expireAt: item.expireAt ?? Infinity, // 永不过期的放最后
+        });
+      }
+    }
+
+    // 按过期时间排序，最早过期的在前面
+    keyWithExpire.sort((a, b) => a.expireAt - b.expireAt);
+
+    // 淘汰超出的 key
+    const toEvict = sizeAfterCleanup - maxKeys + 1; // +1 为新 key 腾出空间
+    for (let i = 0; i < toEvict && i < keyWithExpire.length; i++) {
+      await this.adapter.delete(keyWithExpire[i].key);
+    }
+  }
+
+  /**
+   * 删除值
+   * @param key 键名
+   * @returns 是否删除成功
+   */
+  async del(key: string): Promise<boolean> {
+    return this.adapter.delete(key);
+  }
+
+  /**
+   * 检查键是否存在（且未过期）
+   * @param key 键名
+   */
+  async has(key: string): Promise<boolean> {
+    const item = await this.adapter.get(key);
+
+    if (!item) {
+      return false;
+    }
+
+    // 检查是否过期
+    if (item.expireAt && item.expireAt <= Date.now()) {
+      await this.adapter.delete(key);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * 获取匹配的键名列表
+   * @param pattern 匹配模式，支持 * 通配符
+   *
+   * 示例：
+   * - keys('user:*') 获取所有以 user: 开头的键
+   * - keys('*:profile') 获取所有以 :profile 结尾的键
+   * - keys('user:*:settings') 获取匹配模式的键
+   */
+  async keys(pattern?: string): Promise<string[]> {
+    const allKeys = await this.adapter.keys(pattern);
+    const now = Date.now();
+    const validKeys: string[] = [];
+
+    // 过滤掉已过期的键
+    for (const key of allKeys) {
+      const item = await this.adapter.get(key);
+      if (item && (!item.expireAt || item.expireAt > now)) {
+        validKeys.push(key);
+      }
+    }
+
+    return validKeys;
+  }
+
+  /**
+   * 获取指定前缀下的所有键
+   * @param prefix 前缀，例如 'user:123'
+   */
+  async keysWithPrefix(prefix: string): Promise<string[]> {
+    return this.keys(`${prefix}:*`);
+  }
+
+  /**
+   * 删除指定前缀下的所有键
+   * @param prefix 前缀
+   * @returns 删除的键数量
+   */
+  async delByPrefix(prefix: string): Promise<number> {
+    const keysToDelete = await this.keysWithPrefix(prefix);
+    let deleted = 0;
+
+    for (const key of keysToDelete) {
+      if (await this.adapter.delete(key)) {
+        deleted++;
+      }
+    }
+
+    return deleted;
+  }
+
+  /**
+   * 设置过期时间
+   * @param key 键名
+   * @param ttl 过期时间（毫秒）
+   * @returns 是否设置成功
+   */
+  async expire(key: string, ttl: number): Promise<boolean> {
+    const item = await this.adapter.get(key);
+
+    if (!item) {
+      return false;
+    }
+
+    // 检查是否已过期
+    if (item.expireAt && item.expireAt <= Date.now()) {
+      await this.adapter.delete(key);
+      return false;
+    }
+
+    await this.adapter.set(key, {
+      ...item,
+      expireAt: ttl > 0 ? Date.now() + ttl : undefined,
+    });
+
+    return true;
+  }
+
+  /**
+   * 获取剩余过期时间
+   * @param key 键名
+   * @returns 剩余时间（毫秒），-1 表示永不过期，undefined 表示键不存在
+   */
+  async ttl(key: string): Promise<number | undefined> {
+    const item = await this.adapter.get(key);
+
+    if (!item) {
+      return undefined;
+    }
+
+    // 检查是否已过期
+    if (item.expireAt && item.expireAt <= Date.now()) {
+      await this.adapter.delete(key);
+      return undefined;
+    }
+
+    if (!item.expireAt) {
+      return -1; // 永不过期
+    }
+
+    return item.expireAt - Date.now();
+  }
+
+  /**
+   * 清空所有存储
+   */
+  async clear(): Promise<void> {
+    await this.adapter.clear();
+  }
+
+  /**
+   * 获取当前存储的 key 数量
+   */
+  async size(): Promise<number> {
+    return this.adapter.size();
+  }
+}

package/src/shared/storage/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Storage 模块配置选项
+ */
+export interface StorageModuleOptions {
+  /**
+   * 适配器类型
+   */
+  adapter: "memory" | "file";
+
+  /**
+   * 文件适配器的存储路径（仅 file 适配器需要）
+   */
+  filePath?: string;
+
+  /**
+   * 默认过期时间（毫秒），0 表示永不过期
+   */
+  defaultTtl?: number;
+
+  /**
+   * 最大 key 数量，超过时会淘汰最早过期的 key
+   * 0 或 undefined 表示不限制
+   */
+  maxKeys?: number;
+}
+
+/**
+ * 异步模块配置选项
+ */
+export interface StorageModuleAsyncOptions {
+  useFactory: (...args: any[]) => Promise<StorageModuleOptions> | StorageModuleOptions;
+  inject?: any[];
+}
+
+/**
+ * 存储项元数据
+ */
+export interface StorageItem<T = any> {
+  value: T;
+  expireAt?: number; // 过期时间戳，undefined 表示永不过期
+}
+
+/**
+ * 模块配置注入 Token
+ */
+export const STORAGE_MODULE_OPTIONS = Symbol("STORAGE_MODULE_OPTIONS");
+
+/**
+ * 适配器注入 Token
+ */
+export const STORAGE_ADAPTER = Symbol("STORAGE_ADAPTER");

package/src/shared/verbose/index.ts

@@ -0,0 +1,73 @@
+/**
+ * 日志级别（字符串模式）
+ * - "silent": 静默模式，不输出任何日志
+ * - "info": 显示过程日志（如 "开始审查"、"完成审查"）
+ * - "verbose": 显示详细日志
+ * - "debug": 显示调试日志（包括大模型的输入提示词和输出过程）
+ */
+export type LogLevel = "silent" | "info" | "verbose" | "debug";
+
+/**
+ * Verbose 日志级别（数字模式，向后兼容）
+ * - 0 / false: 静默模式，只返回结果
+ * - 1 / true: 显示过程日志
+ * - 2: 显示详细日志
+ * - 3: 显示调试日志
+ */
+export type VerboseLevel = 0 | 1 | 2 | 3 | false | true;
+
+/** 日志级别优先级映射 */
+export const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+  silent: 0,
+  info: 1,
+  verbose: 2,
+  debug: 3,
+} as const;
+
+/** VerboseLevel 数字到 LogLevel 字符串的映射 */
+const VERBOSE_TO_LOG_LEVEL: Record<number, LogLevel> = {
+  0: "silent",
+  1: "info",
+  2: "verbose",
+  3: "debug",
+} as const;
+
+/**
+ * 将任意级别值统一转为 LogLevel 字符串
+ * @param level 日志级别（字符串、数字、布尔值）
+ * @returns LogLevel 字符串
+ */
+export const toLogLevel = (level: LogLevel | VerboseLevel | undefined): LogLevel => {
+  if (level === undefined) return "info";
+  if (typeof level === "string") return level;
+  if (level === true) return "info";
+  if (level === false) return "silent";
+  return VERBOSE_TO_LOG_LEVEL[level] ?? "info";
+};
+
+/**
+ * 将 verbose 值规范化为数字
+ * @param verbose verbose 值（支持字符串、数字、布尔值）
+ * @returns 规范化后的数字 (0, 1, 2, 3)
+ */
+export function normalizeVerbose(
+  verbose: LogLevel | VerboseLevel | boolean | undefined,
+): 0 | 1 | 2 | 3 {
+  if (verbose === undefined || verbose === false || verbose === 0 || verbose === "silent") return 0;
+  if (verbose === true || verbose === 1 || verbose === "info") return 1;
+  if (verbose === 2 || verbose === "verbose") return 2;
+  return 3;
+}
+
+/**
+ * 判断是否应该打印指定级别的日志
+ * @param verbose 当前 verbose 级别（支持字符串或数字）
+ * @param requiredLevel 需要的最低级别 (1, 2, 3)
+ * @returns 是否应该打印
+ */
+export function shouldLog(
+  verbose: LogLevel | VerboseLevel | undefined,
+  requiredLevel: 1 | 2 | 3,
+): boolean {
+  return normalizeVerbose(verbose) >= requiredLevel;
+}

package/test/app.e2e-spec.ts

@@ -0,0 +1,22 @@
+import { Test, TestingModule } from "@nestjs/testing";
+import { INestApplication } from "@nestjs/common";
+import * as request from "supertest";
+import { App } from "supertest/types";
+import { AppModule } from "./../src/app.module";
+
+describe("AppController (e2e)", () => {
+  let app: INestApplication<App>;
+
+  beforeEach(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    await app.init();
+  });
+
+  it("/ (GET)", () => {
+    return request(app.getHttpServer()).get("/").expect(200).expect("Hello World!");
+  });
+});

package/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "removeComments": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "target": "ES2023",
+    "sourceMap": true,
+    "outDir": "./dist",
+    "baseUrl": "./",
+    "incremental": true,
+    "skipLibCheck": true,
+    "strictNullChecks": true,
+    "forceConsistentCasingInFileNames": true,
+    "noImplicitAny": false,
+    "strictBindCallApply": false,
+    "noFallthroughCasesInSwitch": false,
+    "resolveJsonModule": true,
+    "types": ["vitest/globals"]
+  }
+}

package/tsconfig.skill.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "declaration": false,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,58 @@
+import swc from "unplugin-swc";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  plugins: [swc.vite()],
+  test: {
+    root: "src",
+    globals: true,
+    environment: "node",
+    include: ["**/*.spec.ts"],
+    alias: {
+      "^src/(.*)$": "$1",
+    },
+    coverage: {
+      provider: "v8",
+      include: ["shared/**/*.ts"],
+      exclude: [
+        "**/*.spec.ts",
+        "**/*.module.ts",
+        "**/index.ts",
+        "**/__mocks__/**",
+        "**/*.interface.ts",
+        "**/*.types.ts",
+        "**/types.ts",
+        "**/types/**",
+        "**/interfaces/**",
+        "**/feishu-sdk/**",
+        "**/storage/**",
+        "**/rspack-config/**",
+        "**/output/**",
+        "**/parallel/**",
+        "**/mcp/**",
+        "**/editor-config/**",
+        "**/package-manager/**",
+        "**/source-utils/**",
+        "**/spaceflow-dir/**",
+        "**/verbose/**",
+        "**/claude-setup/**",
+        "**/git-sdk/git-sdk.service.ts",
+        "**/i18n/locale-detect.ts",
+        "**/tui.renderer.ts",
+        "**/llm-jsonput/**",
+        "**/stream-logger.ts",
+        "**/open-code.adapter.ts",
+        "**/claude-code.adapter.ts",
+        "**/gitlab.adapter.ts",
+        "**/gitea.adapter.ts",
+        "**/github.adapter.ts",
+      ],
+      thresholds: {
+        lines: 80,
+        functions: 80,
+        branches: 80,
+        statements: 80,
+      },
+    },
+  },
+});