@spaceflow/core 0.1.1

package/src/extension-system/extension.interface.ts

@@ -0,0 +1,221 @@
+import { Type, DynamicModule } from "@nestjs/common";
+
+/** .spaceflow 目录名 */
+export const SPACEFLOW_DIR = ".spaceflow";
+
+/** package.json 文件名 */
+export const PACKAGE_JSON = "package.json";
+
+/**
+ * Extension 元数据
+ */
+export interface SpaceflowExtensionMetadata {
+  /** Extension 名称 */
+  name: string;
+  /** 提供的命令列表 */
+  commands: string[];
+  /** 对应 spaceflow.json 中的配置 key（可选） */
+  configKey?: string;
+  /** 依赖的其他 Extension 配置 key 列表，读取其他 Extension 配置前必须在此声明 */
+  configDependencies?: string[];
+  /** 配置 schema 工厂函数，返回 zod schema，用于验证配置和生成 JSON Schema */
+  configSchema?: () => unknown;
+  /** Extension 版本 */
+  version?: string;
+  /** Extension 描述 */
+  description?: string;
+}
+
+/**
+ * Extension 模块类型，支持静态模块或动态模块
+ */
+export type ExtensionModuleType = Type<any> | DynamicModule;
+
+/**
+ * Extension 接口
+ */
+export interface SpaceflowExtension {
+  /** 获取 Extension 元数据 */
+  getMetadata(): SpaceflowExtensionMetadata;
+  /**
+   * 获取 NestJS Module
+   * 可以返回静态 Module 类或 DynamicModule
+   * 如果需要动态配置，推荐返回 DynamicModule
+   */
+  getModule(): ExtensionModuleType;
+}
+
+/**
+ * Extension 类静态接口
+ */
+export interface SpaceflowExtensionConstructor {
+  new (): SpaceflowExtension;
+}
+
+/**
+ * Extension 入口导出格式
+ */
+export type SpaceflowExtensionExport =
+  | SpaceflowExtensionConstructor
+  | {
+      default: SpaceflowExtensionConstructor;
+    };
+
+/**
+ * 已加载的 Extension 信息
+ */
+export interface LoadedExtension {
+  /** Extension 名称 */
+  name: string;
+  /** Extension 来源（npm 包名） */
+  source: string;
+  /** NestJS 模块（静态或动态） */
+  module: ExtensionModuleType;
+  /** 包的完整导出（用于 MCP 服务发现） */
+  exports?: Record<string, unknown>;
+  /** 提供的命令列表 */
+  commands: string[];
+  /** 配置 key */
+  configKey?: string;
+  /** 依赖的其他 Extension 配置 key 列表 */
+  configDependencies?: string[];
+  /** 配置 schema 工厂函数 */
+  configSchema?: () => unknown;
+  /** Extension 版本 */
+  version?: string;
+  /** Extension 描述 */
+  description?: string;
+}
+
+/**
+ * .spaceflow/package.json 中的 dependencies
+ */
+export type ExtensionDependencies = Record<string, string>;
+
+/**
+ * Spaceflow 导出类型
+ * - flow: 子命令（默认），需要构建，注册为 CLI 子命令
+ * - command: 编辑器命令，复制到 .claude/commands/ 等目录
+ * - skill: 技能包，复制到 .claude/skills/ 等目录
+ * - mcp: MCP Server，注册到编辑器的 mcp.json 配置
+ */
+export type SpaceflowExportType = "flow" | "command" | "skill" | "mcp";
+
+/**
+ * MCP Server 配置
+ */
+export interface McpServerConfig {
+  /** 启动命令，如 "node", "python" */
+  command: string;
+  /** 启动参数，如 ["dist/index.js"] */
+  args?: string[];
+  /** 需要的环境变量名列表，安装时会提示用户配置 */
+  env?: string[];
+}
+
+/**
+ * 单个导出项配置
+ */
+export interface SpaceflowExportConfig {
+  /** 导出类型，默认为 flow */
+  type?: SpaceflowExportType;
+  /** 入口路径，相对于包根目录 */
+  entry: string;
+  /** 描述（可选） */
+  description?: string;
+  /** MCP Server 配置（仅 type 为 mcp 时有效） */
+  mcp?: McpServerConfig;
+}
+
+/**
+ * package.json 中的 spaceflow 配置
+ *
+ * 完整格式：
+ * ```json
+ * "spaceflow": {
+ *   "exports": {
+ *     "review": { "type": "flow", "entry": "." },
+ *     "review-rules": { "type": "skill", "entry": "./skills" },
+ *     "my-mcp": { "type": "mcp", "entry": ".", "mcp": { "command": "node", "args": ["dist/index.js"] } }
+ *   }
+ * }
+ * ```
+ *
+ * 简化格式（单导出）：
+ * ```json
+ * "spaceflow": {
+ *   "type": "mcp",
+ *   "entry": ".",
+ *   "mcp": { "command": "node", "args": ["dist/index.js"] }
+ * }
+ * ```
+ */
+export interface SpaceflowPackageConfig {
+  /** 多导出配置 */
+  exports?: Record<string, SpaceflowExportConfig>;
+  /** 简化格式：导出类型 */
+  type?: SpaceflowExportType;
+  /** 简化格式：入口路径 */
+  entry?: string;
+  /** 简化格式：描述 */
+  description?: string;
+  /** 简化格式：MCP 配置 */
+  mcp?: McpServerConfig;
+}
+
+/**
+ * 解析后的导出项
+ */
+export interface ResolvedSpaceflowExport {
+  /** 导出名称 */
+  name: string;
+  /** 导出类型 */
+  type: SpaceflowExportType;
+  /** 入口路径（绝对路径） */
+  entry: string;
+  /** 描述 */
+  description?: string;
+  /** MCP 配置（仅 type 为 mcp 时有效） */
+  mcp?: McpServerConfig;
+}
+
+/**
+ * 解析 spaceflow 配置，返回所有导出项
+ */
+export function resolveSpaceflowConfig(
+  config: SpaceflowPackageConfig | undefined,
+  packageName: string,
+  packagePath: string,
+): ResolvedSpaceflowExport[] {
+  const { join } = require("path");
+
+  if (!config) {
+    return [];
+  }
+
+  // 完整格式：有 exports 字段
+  if (config.exports) {
+    return Object.entries(config.exports).map(([name, exportConfig]) => ({
+      name,
+      type: exportConfig.type || "flow",
+      entry: join(packagePath, exportConfig.entry),
+      description: exportConfig.description,
+      mcp: exportConfig.mcp,
+    }));
+  }
+
+  // 简化格式：直接有 type/entry 字段
+  if (config.entry) {
+    return [
+      {
+        name: packageName,
+        type: config.type || "flow",
+        entry: join(packagePath, config.entry),
+        description: config.description,
+        mcp: config.mcp,
+      },
+    ];
+  }
+
+  return [];
+}

package/src/extension-system/index.ts

@@ -0,0 +1 @@
+export * from "./extension.interface";

package/src/index.ts

@@ -0,0 +1,80 @@
+// ============ 插件系统 ============
+export * from "./extension-system";
+
+// ============ 基础能力模块 ============
+// Git Provider - 多平台 Git 托管 API 操作（GitHub、Gitea、GitLab）
+export * from "./shared/git-provider";
+
+// Git SDK - Git 命令操作
+export * from "./shared/git-sdk";
+
+// LLM Proxy - 多 LLM 适配器
+export * from "./shared/llm-proxy";
+
+// Feishu SDK - 飞书 API 操作
+export * from "./shared/feishu-sdk";
+
+// Storage - 存储服务
+export * from "./shared/storage";
+
+// Claude Setup - Claude Agent 配置
+export * from "./shared/claude-setup";
+
+// Parallel - 并行执行工具
+export * from "./shared/parallel";
+
+// Output - 输出服务
+export * from "./shared/output";
+
+// Verbose - 日志级别
+export * from "./shared/verbose";
+
+// Editor Config - 编辑器配置
+export * from "./shared/editor-config";
+
+// LLM JsonPut - JSON 结构化输出
+export * from "./shared/llm-jsonput";
+
+// Source Utils - 源类型判断工具
+export * from "./shared/source-utils";
+
+// Package Manager - 包管理器检测
+export * from "./shared/package-manager";
+
+// Spaceflow Dir - .spaceflow 目录管理
+export * from "./shared/spaceflow-dir";
+
+// Rspack Config - Rspack 配置工具
+export * from "./shared/rspack-config";
+
+// MCP - Model Context Protocol 支持
+export * from "./shared/mcp";
+
+// I18n - 国际化
+export * from "./shared/i18n";
+
+// Logger - 全局日志工具
+export * from "./shared/logger";
+
+// ============ 配置相关 ============
+export * from "./config";
+
+// ============ NestJS 重导出 ============
+export { Command, CommandRunner, Option, SubCommand } from "nest-commander";
+export { Module, Injectable, Inject, Global } from "@nestjs/common";
+export { ConfigModule, ConfigService } from "@nestjs/config";
+
+// ============ Zod 重导出 ============
+export { z } from "zod";
+
+// ============ Swagger DTO 重导出 ============
+export { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+export {
+  IsString,
+  IsNumber,
+  IsBoolean,
+  IsOptional,
+  IsArray,
+  IsEnum,
+  IsNotEmpty,
+} from "class-validator";

package/src/locales/en/translation.json

@@ -0,0 +1,11 @@
+{
+  "common.executionFailed": "Execution failed: {{error}}",
+  "common.stackTrace": "\nStack trace:\n{{stack}}",
+  "common.options.dryRun": "Only print actions without executing",
+  "common.options.verbose": "Show verbose logs (-v: basic, -vv: detailed)",
+  "common.options.verboseDebug": "Show verbose logs (-v: basic, -vv: detailed, -vvv: debug)",
+  "common.options.ci": "Run in CI environment",
+  "config.parseWarning": "Warning: unable to parse config file {{path}}",
+  "config.validationFailed": "Spaceflow config validation failed:\n{{errors}}",
+  "extensionLoader.loadFailed": "⚠️ Failed to load Extension {{name}}: {{error}}"
+}

package/src/locales/zh-cn/translation.json

@@ -0,0 +1,11 @@
+{
+  "common.executionFailed": "执行失败: {{error}}",
+  "common.stackTrace": "\n堆栈信息:\n{{stack}}",
+  "common.options.dryRun": "仅打印将要执行的操作，不实际执行",
+  "common.options.verbose": "显示详细日志 (-v: 基本日志, -vv: 详细日志)",
+  "common.options.verboseDebug": "显示详细日志 (-v: 基本日志, -vv: 详细日志, -vvv: 调试日志)",
+  "common.options.ci": "是否在 CI 环境中运行",
+  "config.parseWarning": "警告: 无法解析配置文件 {{path}}",
+  "config.validationFailed": "Spaceflow 配置验证失败:\n{{errors}}",
+  "extensionLoader.loadFailed": "⚠️ 加载 Extension {{name}} 失败: {{error}}"
+}

package/src/shared/claude-setup/claude-setup.module.ts

@@ -0,0 +1,8 @@
+import { Module } from "@nestjs/common";
+import { ClaudeSetupService } from "./claude-setup.service";
+
+@Module({
+  providers: [ClaudeSetupService],
+  exports: [ClaudeSetupService],
+})
+export class ClaudeSetupModule {}

package/src/shared/claude-setup/claude-setup.service.ts

@@ -0,0 +1,131 @@
+import { Injectable } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { readFile, writeFile, mkdir, copyFile, unlink } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
+import { LlmConfig } from "../../config";
+
+import { shouldLog, type VerboseLevel } from "../verbose";
+
+@Injectable()
+export class ClaudeSetupService {
+  constructor(protected readonly configService: ConfigService) {}
+
+  private getPaths() {
+    const claudeDir = join(homedir(), ".claude");
+    return {
+      claudeDir,
+      settingsPath: join(claudeDir, "settings.json"),
+      settingsBackupPath: join(claudeDir, "settings.json.bak"),
+      claudeJsonPath: join(homedir(), ".claude.json"),
+      claudeJsonBackupPath: join(homedir(), ".claude.json.bak"),
+    };
+  }
+
+  async backup(): Promise<void> {
+    const paths = this.getPaths();
+    try {
+      await copyFile(paths.settingsPath, paths.settingsBackupPath);
+    } catch (e) {
+      // 忽略文件不存在的情况
+    }
+    try {
+      await copyFile(paths.claudeJsonPath, paths.claudeJsonBackupPath);
+    } catch (e) {
+      // 忽略文件不存在的情况
+    }
+  }
+
+  async restore(): Promise<void> {
+    const paths = this.getPaths();
+    try {
+      await copyFile(paths.settingsBackupPath, paths.settingsPath);
+      await unlink(paths.settingsBackupPath);
+    } catch (e) {
+      // 忽略备份文件不存在的情况
+    }
+    try {
+      await copyFile(paths.claudeJsonBackupPath, paths.claudeJsonPath);
+      await unlink(paths.claudeJsonBackupPath);
+    } catch (e) {
+      // 忽略备份文件不存在的情况
+    }
+  }
+
+  /**
+   * 使用临时配置执行操作
+   * 自动备份现有配置，执行完成后恢复
+   */
+  async withTemporaryConfig<T>(fn: () => Promise<T>, verbose?: VerboseLevel): Promise<T> {
+    await this.backup();
+    try {
+      await this.configure(verbose);
+      return await fn();
+    } finally {
+      await this.restore();
+    }
+  }
+
+  async configure(verbose?: VerboseLevel): Promise<void> {
+    const { claudeDir, settingsPath, claudeJsonPath } = this.getPaths();
+
+    const llmConf = this.configService.get<LlmConfig>("llm");
+    const claudeCode = llmConf?.claudeCode;
+
+    if (!claudeCode) {
+      if (shouldLog(verbose, 1)) {
+        console.log("未配置 claude 设置，跳过");
+      }
+      return;
+    }
+
+    try {
+      await mkdir(claudeDir, { recursive: true });
+    } catch {
+      // ignore if exists
+    }
+
+    let existingSettings = {};
+    try {
+      const content = await readFile(settingsPath, "utf-8");
+      existingSettings = JSON.parse(content);
+    } catch {
+      // file doesn't exist or invalid JSON
+    }
+
+    const existing = existingSettings as Record<string, Record<string, unknown>>;
+    const env: Record<string, string> = { ...(existing.env as Record<string, string>) };
+    if (claudeCode.baseUrl) env.ANTHROPIC_BASE_URL = claudeCode.baseUrl;
+    if (claudeCode.authToken) {
+      env.ANTHROPIC_AUTH_TOKEN = claudeCode.authToken;
+    } else {
+      throw new Error("未配置 claudeCode.authToken 设置");
+    }
+    if (claudeCode.model) env.ANTHROPIC_MODEL = claudeCode.model;
+
+    const mergedSettings = {
+      ...existingSettings,
+      env,
+    };
+
+    await writeFile(settingsPath, JSON.stringify(mergedSettings, null, 2), "utf-8");
+    if (shouldLog(verbose, 1)) {
+      console.log(`✅ 已写入 ${settingsPath}`);
+    }
+
+    if (claudeCode.hasCompletedOnboarding !== undefined) {
+      let claudeJson: Record<string, unknown> = {};
+      try {
+        const content = await readFile(claudeJsonPath, "utf-8");
+        claudeJson = JSON.parse(content);
+      } catch {
+        // file doesn't exist or invalid JSON
+      }
+      claudeJson.hasCompletedOnboarding = claudeCode.hasCompletedOnboarding;
+      await writeFile(claudeJsonPath, JSON.stringify(claudeJson, null, 2), "utf-8");
+      if (shouldLog(verbose, 1)) {
+        console.log(`✅ 已写入 ${claudeJsonPath}`);
+      }
+    }
+  }
+}

package/src/shared/claude-setup/index.ts

@@ -0,0 +1,2 @@
+export * from "./claude-setup.service";
+export * from "./claude-setup.module";

package/src/shared/editor-config/index.ts

@@ -0,0 +1,23 @@
+/**
+ * 编辑器配置目录映射
+ * key: 编辑器名称（用于配置文件）
+ * value: 编辑器配置目录名（以 . 开头）
+ */
+export const EDITOR_DIR_MAPPING: Record<string, string> = {
+  claudeCode: ".claude",
+  windsurf: ".windsurf",
+  cursor: ".cursor",
+  opencode: ".opencode",
+};
+
+/**
+ * 默认支持的编辑器
+ */
+export const DEFAULT_EDITOR = "claudeCode";
+
+/**
+ * 根据编辑器名称获取配置目录名
+ */
+export function getEditorDirName(editor: string): string {
+  return EDITOR_DIR_MAPPING[editor] || `.${editor}`;
+}

package/src/shared/feishu-sdk/feishu-sdk.module.ts

@@ -0,0 +1,77 @@
+import { DynamicModule, Module } from "@nestjs/common";
+import { ConfigModule, ConfigService } from "@nestjs/config";
+import { EventEmitterModule } from "@nestjs/event-emitter";
+import { FeishuSdkService } from "./feishu-sdk.service";
+import { FeishuCardService } from "./fieshu-card.service";
+import { FeishuModuleOptions, FeishuModuleAsyncOptions, FEISHU_MODULE_OPTIONS } from "./types";
+import { feishuConfig, FeishuConfig } from "../../config";
+
+@Module({})
+export class FeishuSdkModule {
+  /**
+   * 同步注册模块
+   */
+  static forRoot(options: FeishuModuleOptions): DynamicModule {
+    return {
+      module: FeishuSdkModule,
+      imports: [EventEmitterModule.forRoot()],
+      providers: [
+        {
+          provide: FEISHU_MODULE_OPTIONS,
+          useValue: options,
+        },
+        FeishuSdkService,
+        FeishuCardService,
+      ],
+      exports: [FeishuSdkService, FeishuCardService],
+    };
+  }
+
+  /**
+   * 异步注册模块 - 支持从环境变量等动态获取配置
+   */
+  static forRootAsync(options: FeishuModuleAsyncOptions): DynamicModule {
+    return {
+      module: FeishuSdkModule,
+      imports: [EventEmitterModule.forRoot()],
+      providers: [
+        {
+          provide: FEISHU_MODULE_OPTIONS,
+          useFactory: options.useFactory,
+          inject: options.inject || [],
+        },
+        FeishuSdkService,
+        FeishuCardService,
+      ],
+      exports: [FeishuSdkService, FeishuCardService],
+    };
+  }
+
+  /**
+   * 使用 ConfigService 注册模块
+   */
+  static forFeature(): DynamicModule {
+    return {
+      module: FeishuSdkModule,
+      imports: [ConfigModule.forFeature(feishuConfig), EventEmitterModule.forRoot()],
+      providers: [
+        {
+          provide: FEISHU_MODULE_OPTIONS,
+          useFactory: (configService: ConfigService): FeishuModuleOptions => {
+            const config = configService.get<FeishuConfig>("feishu");
+            return {
+              appId: config?.appId || "",
+              appSecret: config?.appSecret || "",
+              appType: config?.appType,
+              domain: config?.domain,
+            };
+          },
+          inject: [ConfigService],
+        },
+        FeishuSdkService,
+        FeishuCardService,
+      ],
+      exports: [FeishuSdkService, FeishuCardService],
+    };
+  }
+}