@spaceflow/core 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaceflow/core",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Spaceflow 核心能力库",
   "license": "MIT",
   "author": "Lydanne",
@@ -69,6 +69,10 @@
     "./parallel": {
       "types": "./src/shared/parallel/index.ts",
       "import": "./dist/index.js"
+    },
+    "./cli-runtime": {
+      "types": "./src/cli-runtime/index.ts",
+      "import": "./dist/index.js"
     }
   },
   "dependencies": {
@@ -92,7 +96,10 @@
     "release-it-gitea": "^1.8.0",
     "rxjs": "^7.8.1",
     "zod": "^4.3.6",
-    "zod-to-json-schema": "^3.25.1"
+    "zod-to-json-schema": "^3.25.1",
+    "commander": "^12.1.0",
+    "i18next": "^25.8.4",
+    "@spaceflow/shared": "0.2.0"
   },
   "devDependencies": {
     "@swc/core": "1.15.3",
@@ -108,7 +115,6 @@
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.20.0",
     "@vitest/coverage-v8": "^4.0.18",
-    "i18next": "^25.8.4",
     "unplugin-swc": "^1.5.9",
     "vitest": "^4.0.18"
   },

package/src/cli-runtime/di/config.ts

@@ -0,0 +1,157 @@
+import { type IConfigReader, loadSpaceflowConfig } from "@spaceflow/core";
+import type { ZodSchema } from "zod";
+
+/**
+ * 环境变量映射配置
+ * key: 配置路径（如 "gitProvider.token"）
+ * value: 环境变量名或环境变量名数组（按优先级）
+ */
+const ENV_MAPPINGS: Record<string, string | string[]> = {
+  // Git Provider
+  "gitProvider.token": ["GIT_PROVIDER_TOKEN", "GITHUB_TOKEN", "GITLAB_TOKEN", "GITEA_TOKEN"],
+  "gitProvider.serverUrl": ["GIT_PROVIDER_SERVER_URL", "GITHUB_API_URL"],
+  // OpenAI
+  "llm.openai.apiKey": "OPENAI_API_KEY",
+  "llm.openai.baseUrl": "OPENAI_BASE_URL",
+  "llm.openai.model": "OPENAI_MODEL",
+  // Gemini
+  "llm.gemini.apiKey": "GEMINI_API_KEY",
+  "llm.gemini.model": "GEMINI_MODEL",
+  // Claude
+  "llm.claudeCode.authToken": "ANTHROPIC_API_KEY",
+};
+
+/**
+ * 从环境变量获取值
+ */
+function getEnvValue(envNames: string | string[]): string | undefined {
+  const names = Array.isArray(envNames) ? envNames : [envNames];
+  for (const name of names) {
+    const value = process.env[name];
+    if (value) return value;
+  }
+  return undefined;
+}
+
+/**
+ * 设置嵌套对象的值
+ */
+function setNestedValue(obj: Record<string, any>, path: string, value: any): void {
+  const parts = path.split(".");
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (!(part in current)) {
+      current[part] = {};
+    }
+    current = current[part];
+  }
+  current[parts[parts.length - 1]] = value;
+}
+
+/**
+ * 获取嵌套对象的值
+ */
+function getNestedValue(obj: Record<string, any>, path: string): any {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return current;
+}
+
+/**
+ * 统一配置服务
+ * 负责从配置文件和环境变量读取配置
+ */
+export class UnifiedConfigReader implements IConfigReader {
+  private mergedConfig: Record<string, unknown>;
+  private schemas = new Map<string, ZodSchema>();
+
+  constructor(cwd?: string) {
+    const config = loadSpaceflowConfig(cwd) as Record<string, unknown>;
+    this.mergedConfig = this.mergeEnvConfig(config);
+  }
+
+  /**
+   * 合并环境变量到配置
+   */
+  private mergeEnvConfig(config: Record<string, unknown>): Record<string, unknown> {
+    const merged = JSON.parse(JSON.stringify(config));
+    for (const [path, envNames] of Object.entries(ENV_MAPPINGS)) {
+      const envValue = getEnvValue(envNames);
+      if (envValue && !getNestedValue(merged, path)) {
+        setNestedValue(merged, path, envValue);
+      }
+    }
+    // 特殊处理：如果有 OPENAI_API_KEY 但没有 llm.openai，创建默认配置
+    if (process.env.OPENAI_API_KEY && !merged.llm) {
+      merged.llm = {
+        openai: {
+          apiKey: process.env.OPENAI_API_KEY,
+          baseUrl: process.env.OPENAI_BASE_URL || "https://api.openai.com/v1",
+          model: process.env.OPENAI_MODEL,
+        },
+      };
+    }
+    return merged;
+  }
+
+  /**
+   * 获取配置值
+   */
+  get<T>(key: string): T | undefined {
+    const parts = key.split(".");
+    let current: unknown = this.mergedConfig;
+    for (const part of parts) {
+      if (current === null || current === undefined) {
+        return undefined;
+      }
+      current = (current as Record<string, unknown>)[part];
+    }
+    return current as T | undefined;
+  }
+
+  /**
+   * 获取插件配置（带 schema 验证）
+   */
+  getPluginConfig<T>(key: string): T | undefined {
+    const rawConfig = this.mergedConfig[key] ?? {};
+    const schema = this.schemas.get(key);
+    if (!schema) {
+      return rawConfig as T;
+    }
+    try {
+      return schema.parse(rawConfig) as T;
+    } catch (error) {
+      console.warn(`⚠️ 配置 "${key}" 验证失败:`, error);
+      return rawConfig as T;
+    }
+  }
+
+  /**
+   * 注册配置 schema
+   */
+  registerSchema(key: string, schema: ZodSchema): void {
+    this.schemas.set(key, schema);
+  }
+
+  /**
+   * 重新加载配置
+   */
+  reload(cwd?: string): void {
+    const config = loadSpaceflowConfig(cwd) as Record<string, unknown>;
+    this.mergedConfig = this.mergeEnvConfig(config);
+  }
+
+  /**
+   * 获取原始配置对象
+   */
+  getRawConfig(): Record<string, unknown> {
+    return this.mergedConfig;
+  }
+}

package/src/cli-runtime/di/container.ts

@@ -0,0 +1,120 @@
+import type {
+  SpaceflowContext,
+  IConfigReader,
+  IOutputService,
+  IStorageService,
+} from "@spaceflow/core";
+
+/**
+ * 服务工厂函数类型
+ */
+export type ServiceFactory<T = unknown> = (container: ServiceContainer) => T;
+
+/**
+ * 服务注册信息
+ */
+interface ServiceRegistration<T = unknown> {
+  factory: ServiceFactory<T>;
+  instance?: T;
+  initialized: boolean;
+}
+
+/**
+ * 服务容器
+ * 提供懒加载的依赖注入功能
+ */
+export class ServiceContainer implements SpaceflowContext {
+  private registrations = new Map<string, ServiceRegistration>();
+  private _config!: IConfigReader;
+  private _output!: IOutputService;
+  private _storage!: IStorageService;
+
+  /**
+   * 设置核心服务（config, output, storage）
+   */
+  setCoreServices(config: IConfigReader, output: IOutputService, storage: IStorageService): void {
+    this._config = config;
+    this._output = output;
+    this._storage = storage;
+  }
+
+  /**
+   * 注册服务工厂（懒加载）
+   */
+  registerFactory<T>(key: string, factory: ServiceFactory<T>): void {
+    this.registrations.set(key, {
+      factory: factory as ServiceFactory,
+      initialized: false,
+    });
+  }
+
+  /**
+   * 注册服务实例（立即可用）
+   */
+  registerService(key: string, service: unknown): void {
+    this.registrations.set(key, {
+      factory: () => service,
+      instance: service,
+      initialized: true,
+    });
+  }
+
+  /**
+   * 获取服务（懒加载）
+   */
+  getService<T = unknown>(key: string): T {
+    const registration = this.registrations.get(key);
+    if (!registration) {
+      throw new Error(`服务 "${key}" 未注册`);
+    }
+    if (!registration.initialized) {
+      registration.instance = registration.factory(this);
+      registration.initialized = true;
+    }
+    return registration.instance as T;
+  }
+
+  /**
+   * 检查服务是否已注册
+   */
+  hasService(key: string): boolean {
+    return this.registrations.has(key);
+  }
+
+  /**
+   * 尝试获取服务（不抛错）
+   */
+  tryGetService<T = unknown>(key: string): T | undefined {
+    if (!this.hasService(key)) {
+      return undefined;
+    }
+    try {
+      return this.getService<T>(key);
+    } catch {
+      return undefined;
+    }
+  }
+
+  get config(): IConfigReader {
+    return this._config;
+  }
+
+  get output(): IOutputService {
+    return this._output;
+  }
+
+  get storage(): IStorageService {
+    return this._storage;
+  }
+
+  /**
+   * 销毁容器
+   */
+  async destroy(): Promise<void> {
+    // 销毁 storage 服务（清理定时器）
+    if (this._storage && typeof (this._storage as any).destroy === "function") {
+      (this._storage as any).destroy();
+    }
+    this.registrations.clear();
+  }
+}

package/src/cli-runtime/di/index.ts

@@ -0,0 +1,3 @@
+export { ServiceContainer, type ServiceFactory } from "./container";
+export { initializeContainer } from "./services";
+export { UnifiedConfigReader } from "./config";

package/src/cli-runtime/di/services.ts

@@ -0,0 +1,53 @@
+import {
+  OutputService,
+  StorageService,
+  GitSdkService,
+  GitProviderService,
+  LlmProxyService,
+  FileAdapter,
+} from "@spaceflow/core";
+import { join } from "path";
+import type { ServiceContainer } from "./container";
+import { UnifiedConfigReader } from "./config";
+
+/**
+ * 初始化服务容器
+ */
+export function initializeContainer(container: ServiceContainer, cwd?: string): void {
+  const workDir = cwd || process.cwd();
+  // 初始化核心服务（.env 已在 CLI 壳子阶段加载）
+  const config = new UnifiedConfigReader(workDir);
+  const output = new OutputService();
+  const storageDir = join(workDir, ".spaceflow", "cache");
+  const storage = new StorageService(new FileAdapter(storageDir));
+  container.setCoreServices(config, output, storage);
+  // 注册服务工厂
+  registerServiceFactories(container);
+}
+
+/**
+ * 注册所有服务工厂
+ */
+function registerServiceFactories(container: ServiceContainer): void {
+  // Config - 返回已初始化的 config
+  container.registerFactory("config", (c) => c.config);
+  // GitSdk - 无依赖
+  container.registerFactory("gitSdk", () => new GitSdkService());
+  // GitProvider - 依赖配置（环境变量已在 UnifiedConfigReader 中合并）
+  container.registerFactory("gitProvider", (c) => {
+    const config = c.config.get<any>("gitProvider");
+    if (!config?.provider) {
+      throw new Error("缺少 gitProvider 配置");
+    }
+    const baseUrl = config.serverUrl || config.baseUrl;
+    return new GitProviderService({ ...config, baseUrl });
+  });
+  // LlmProxy - 依赖配置（环境变量已在 UnifiedConfigReader 中合并）
+  container.registerFactory("llmProxy", (c) => {
+    const config = c.config.get<any>("llm");
+    if (!config || (!config.openai && !config.gemini && !config.claudeCode && !config.openCode)) {
+      throw new Error("缺少 llm 配置，请在 spaceflow.json 中配置或设置 OPENAI_API_KEY 环境变量");
+    }
+    return new LlmProxyService(config);
+  });
+}

package/src/cli-runtime/extension-loader.ts

@@ -0,0 +1,74 @@
+import type { ExtensionDefinition, CommandDefinition } from "@spaceflow/core";
+import type { SpaceflowContext } from "@spaceflow/core";
+
+/**
+ * 扩展加载器
+ * 加载新格式的扩展（使用 defineExtension）
+ */
+export class ExtensionLoader {
+  private extensions = new Map<string, ExtensionDefinition>();
+  private commands = new Map<string, CommandDefinition>();
+
+  constructor(private readonly ctx: SpaceflowContext) {}
+
+  /**
+   * 注册扩展
+   */
+  registerExtension(extension: ExtensionDefinition): void {
+    this.extensions.set(extension.name, extension);
+
+    // 注册配置 schema
+    if (extension.configSchema && extension.configKey) {
+      this.ctx.config.registerSchema(extension.configKey, extension.configSchema());
+    }
+
+    // 注册命令
+    for (const cmd of extension.commands) {
+      this.commands.set(cmd.name, cmd);
+    }
+
+    // 注册服务
+    if (extension.services) {
+      for (const svc of extension.services) {
+        const instance = svc.factory(this.ctx);
+        this.ctx.registerService(svc.key, instance);
+      }
+    }
+
+    // 调用初始化钩子
+    if (extension.onInit) {
+      extension.onInit(this.ctx);
+    }
+  }
+
+  /**
+   * 获取所有命令
+   */
+  getCommands(): CommandDefinition[] {
+    return Array.from(this.commands.values());
+  }
+
+  /**
+   * 获取所有扩展
+   */
+  getExtensions(): ExtensionDefinition[] {
+    return Array.from(this.extensions.values());
+  }
+
+  /**
+   * 获取所有 MCP 服务
+   * 返回扩展中定义的 mcp 字段
+   */
+  getMcpServers(): Array<{ extensionName: string; mcp: NonNullable<ExtensionDefinition["mcp"]> }> {
+    const mcpServers: Array<{
+      extensionName: string;
+      mcp: NonNullable<ExtensionDefinition["mcp"]>;
+    }> = [];
+    for (const ext of this.extensions.values()) {
+      if (ext.mcp) {
+        mcpServers.push({ extensionName: ext.name, mcp: ext.mcp });
+      }
+    }
+    return mcpServers;
+  }
+}

package/src/{shared → cli-runtime}/i18n/index.ts

@@ -1,3 +1,4 @@
+// ---- 基础 i18n 设施（globalThis 桥接） ----
 export {
   t,
   setGlobalT,
@@ -7,8 +8,13 @@ export {
   type TranslateFn,
   type AddLocaleResourcesFn,
 } from "./i18n";
+
+// ---- 语言检测 ----
 export { detectLocale } from "./locale-detect";
 
-// 导出 core 基础翻译资源，供 CLI 注册
+// ---- CLI i18n 初始化（i18next） ----
+export { initCliI18n, addI18nextResources } from "./init";
+
+// ---- core 基础翻译资源 ----
 export { default as coreZhCN } from "../../locales/zh-cn/translation.json";
 export { default as coreEn } from "../../locales/en/translation.json";

package/src/cli-runtime/i18n/init.ts

@@ -0,0 +1,117 @@
+import * as i18nextModule from "i18next";
+import type { i18n } from "i18next";
+import { setGlobalT, setGlobalAddLocaleResources } from "./i18n";
+import { detectLocale } from "./locale-detect";
+
+// core 基础翻译资源
+import coreZhCN from "../../locales/zh-cn/translation.json";
+import coreEn from "../../locales/en/translation.json";
+
+// 兼容 CJS/ESM 混合环境
+const i18next: i18n =
+  (i18nextModule as unknown as { default: i18n }).default || (i18nextModule as unknown as i18n);
+
+// ---- CLI 命令翻译 ----
+import buildZhCN from "../../locales/zh-cn/build.json";
+import buildEn from "../../locales/en/build.json";
+import clearZhCN from "../../locales/zh-cn/clear.json";
+import clearEn from "../../locales/en/clear.json";
+import commitZhCN from "../../locales/zh-cn/commit.json";
+import commitEn from "../../locales/en/commit.json";
+import createZhCN from "../../locales/zh-cn/create.json";
+import createEn from "../../locales/en/create.json";
+import devZhCN from "../../locales/zh-cn/dev.json";
+import devEn from "../../locales/en/dev.json";
+import installZhCN from "../../locales/zh-cn/install.json";
+import installEn from "../../locales/en/install.json";
+import listZhCN from "../../locales/zh-cn/list.json";
+import listEn from "../../locales/en/list.json";
+import mcpZhCN from "../../locales/zh-cn/mcp.json";
+import mcpEn from "../../locales/en/mcp.json";
+import runxZhCN from "../../locales/zh-cn/runx.json";
+import runxEn from "../../locales/en/runx.json";
+import schemaZhCN from "../../locales/zh-cn/schema.json";
+import schemaEn from "../../locales/en/schema.json";
+import setupZhCN from "../../locales/zh-cn/setup.json";
+import setupEn from "../../locales/en/setup.json";
+import uninstallZhCN from "../../locales/zh-cn/uninstall.json";
+import uninstallEn from "../../locales/en/uninstall.json";
+import updateZhCN from "../../locales/zh-cn/update.json";
+import updateEn from "../../locales/en/update.json";
+
+type LocaleResource = Record<string, Record<string, string>>;
+
+/** 所有内部命令 i18n 资源映射（命名空间 → 语言 → 翻译） */
+const allLocales: Record<string, LocaleResource> = {
+  build: { "zh-CN": buildZhCN, en: buildEn },
+  clear: { "zh-CN": clearZhCN, en: clearEn },
+  commit: { "zh-CN": commitZhCN, en: commitEn },
+  create: { "zh-CN": createZhCN, en: createEn },
+  dev: { "zh-CN": devZhCN, en: devEn },
+  install: { "zh-CN": installZhCN, en: installEn },
+  list: { "zh-CN": listZhCN, en: listEn },
+  mcp: { "zh-CN": mcpZhCN, en: mcpEn },
+  runx: { "zh-CN": runxZhCN, en: runxEn },
+  schema: { "zh-CN": schemaZhCN, en: schemaEn },
+  setup: { "zh-CN": setupZhCN, en: setupEn },
+  uninstall: { "zh-CN": uninstallZhCN, en: uninstallEn },
+  update: { "zh-CN": updateZhCN, en: updateEn },
+};
+
+/** 默认命名空间 */
+const DEFAULT_NS = "translation";
+
+/**
+ * 初始化 CLI 的 i18n 系统
+ * 1. 初始化 i18next（core 基础翻译 + CLI 命令翻译）
+ * 2. 通过 setGlobalT 挂载翻译函数到 globalThis
+ */
+export function initCliI18n(lang?: string): void {
+  const lng = lang || detectLocale();
+
+  void i18next.init({
+    lng,
+    fallbackLng: "zh-CN",
+    defaultNS: DEFAULT_NS,
+    ns: [DEFAULT_NS, ...Object.keys(allLocales)],
+    resources: {
+      "zh-CN": { [DEFAULT_NS]: coreZhCN },
+      en: { [DEFAULT_NS]: coreEn },
+    },
+    interpolation: { escapeValue: false },
+    returnNull: false,
+    returnEmptyString: false,
+    initImmediate: false,
+    showSupportNotice: false,
+  });
+
+  // 注册 CLI 命令翻译到各自命名空间
+  for (const [ns, resources] of Object.entries(allLocales)) {
+    for (const [lngKey, translations] of Object.entries(resources)) {
+      i18next.addResourceBundle(lngKey, ns, translations, true, true);
+    }
+  }
+
+  // 挂载到 globalThis，让 core 和扩展的 t() / addLocaleResources() 调用都能生效
+  setGlobalT((key, options) => i18next.t(key, options) as string);
+  setGlobalAddLocaleResources(addI18nextResources);
+}
+
+/**
+ * 为外部 Extension 注册语言资源（i18next 实现）
+ * @param ns 命名空间（通常为 Extension name）
+ * @param resources 语言资源，key 为语言代码，值为翻译对象
+ */
+export function addI18nextResources(
+  ns: string,
+  resources: Record<string, Record<string, unknown>>,
+): void {
+  for (const [lng, translations] of Object.entries(resources)) {
+    i18next.addResourceBundle(lng, ns, translations, true, true);
+  }
+  if (!i18next.options.ns) {
+    i18next.options.ns = [DEFAULT_NS, ns];
+  } else if (Array.isArray(i18next.options.ns) && !i18next.options.ns.includes(ns)) {
+    i18next.options.ns.push(ns);
+  }
+}